Table of Contents

1. Introduction

2. Overview and Terminology
    2.1. Basics of Animation
    2.2. Animation function values
    2.3. Symbols used in the semantic descriptions

3. Animation Model
    3.1. Specifying the animation target
    3.2. Specifying the animation function f(t)
        3.2.1. Animation function timing
        3.2.2. Animation function values
        3.2.3. Animation function calculation modes
    3.3. Specifying the animation effect F(t)
       3.3.1. Repeating Animation
       3.3.2. Specifying endActive
       3.3.3. Computing the Active Duration
       3.3.4. Freezing Animations
       3.3.5. Additive Animation
       3.3.6. Restarting Animations
    3.4. Handling Syntax Errors
    3.5. The Animation Sandwich Model
    3.6. State Transition Model
    3.7. Timing Model Details
       3.7.1. Timing and real-world clock times
       3.7.2. Interval Timing
       3.7.3. Unifying Event-based and Scheduled Timing
       3.7.4. Hyperlinks and Timing
       3.7.5. Propagating Changes to Times
    3.8. Common Syntax DTD Definitions

4. Animation elements
    4.1. The animate element
    4.2. The set element
    4.3. The animateMotion element
    4.4. The animateColor element

5. Integrating SMIL Animation into a host language
    5.1. Required host language definitions
    5.2. Constraints on Animation targets
    5.3. Constraints on Animation Attribute manipulation
    5.4. Constraints on Element Timing
    5.5. Error handling semantics
    5.6. SMIL Animation namespace

6. DOM Support
    6.1. Event Model
    6.2. Supported Methods
    6.3. IDL Definition
    6.4. Java Language Binding
    6.5. ECMA Script Language Binding

7. Appendix: Differences and Extensions to SMIL 1.0

8. References

1. Introduction

This document describes a framework for incorporating animation onto a time line and a mechanism for composing the effects of multiple animations.  A set of basic animation elements are also described that can be applied to any XML-based language. A language with which this module is integrated is referred to as a host language. A document containing animation elements is referred to as a host document.

Animation is inherently time-based. SMIL Animation is defined in terms of the SMIL timing model.  The animation capabilities are described by new elements with associated attributes and semantics, as well as the SMIL timing attributes. Animation is modeled as a function that changes the presented value of a specific attribute over time.

The timing model is based upon SMIL 1.0, with some changes and extensions to support interactive (event-based) timing. SMIL Animation uses a simplified "flat" timing model, with no time containers (like <par> or <seq>). This version of SMIL Animation may not be used with documents that otherwise contain timing. See also Constraints on Element Timing.

While this document defines a base set of animation capabilities, it is assumed that host languages may build upon the support to define additional and/or more specialized animation elements.  In order to ensure a consistent model for document authors and runtime implementers, we introduce a framework for integrating animation with the SMIL timing model. Animation only manipulates attributes of the target elements, and so does not require any specific knowledge of the target element semantics.

The examples in this document that include syntax for a host language use SMIL, SVG, XHTML and CSS. These are provided as an indication of possible integrations with various host languages.

2. Overview and Terminology

2.1. Basics of Animation

Animation is defined as a time-based manipulation of a target element (or more specifically of some attribute of the target element, the target attribute). The animation defines a mapping of time to values for the target attribute. This mapping accounts for all aspects of timing, as well as various specific controls on the animation. 

Animations specify a begin and simple duration which can be repeated. Each animation defines an animation function, that produces a value for the target attribute, for any time within the simple duration. The author can specify how long or how many times an animation should repeat - this defines the active duration.

The target attribute is the name of a feature of a target element as defined in a host language document. This may be (e.g.) an XML attribute contained in the element or a CSS property that applies to the element.  By default, the target element of an animation will be the parent of the animation element (an animation element is typically a child of the target element). However, the target may be any element in the document, identified by the associated element id or via an XLink [XLink] reference.

When an animation is running, it does not actually change the attribute values in the DOM [DOM-Level-1].  The animation runtime must maintain a presentation value for each animated attribute, separate from the DOM or CSS Object Model (OM). If an implementation does not support an object model, it must maintain the original value as defined by the document as well as the presentation value. The presentation value is reflected in the display form of the document. Animations thus manipulate the presentation value, and do not affect the base value exposed by DOM or CSS OM. 

The animation function is evaluated as needed over time by the implementation, and the resulting values are applied to the presentation value for the target attribute.  The syntactic representation of the animation function is independent of this model, and may be described in a variety of ways. The animation elements in this specification support syntax for a set of discrete or interpolated values, a path syntax for motion based upon SVG paths, keyframe based timing, evenly paced interpolation, and variants on these features. Animation functions could be defined that were purely or partially algorithmic (e.g. a random value function or a motion animation that tracks the mouse position) . In all cases, the animation exposes this as a function of time.

The presentation value reflects the effect of the animation upon the base value. The effect is the change to the value of the target attribute at any given time. When an animation completes, the effect of the animation is no longer applied, and the presentation value reverts to the base value by default. The animation effect can also be extended to freeze the last value for the remainder of the document duration.

Animations can be defined to either override or add to the base value of an attribute. In this context, the base value may be the DOM value, or the result of other animations that also target the same attribute. This more general concept of a base value is termed the underlying value. Animations that add to the underlying value are described as additive animations. Animations that override the underlying value are referred to as non-additive animations.

As a simple example, the following defines an animation of an SVG rectangle shape.  The rectangle will change from being tall and thin to being short and wide.

<rect ...>
   <animate attributeName="width"  from="10px"  to="100px" 
            begin="0s" dur="10s" />
   <animate attributeName="height" from="100px" to="10px"
            begin="0s" dur="10s" />
</rect>

The rectangle begins with a width of 10 pixels and increases to a width of 100 pixels over the course of 10 seconds. Over the same ten seconds, the height of the rectangle changes from 100 pixels to 10 pixels.

2.2. Animation function values

Many animations specify the animation function f(t) as a sequence of values to be applied over time. For some types of attributes (e.g. numbers), it is also possible to describe an interpolation function between values.

As a simple form of describing the values, animation elements can specify a from value and a to value. If the attribute takes values that support interpolation (e.g. a number), the animation function can interpolate values in the range defined by  from and to, over the course of the simple duration. A variant on this uses a by value in place of the to value, to indicate an additive change to the attribute.

More complex forms specify a list of values, or even a path description for motion. Authors can also control the timing of the values, to describe "keyframe" animations, and even more complex functions.

2.3. Symbols used in the semantic descriptions

f(t)

The simplified animation function that maps times within the simple duration to values for the target attribute (0 <= t <= simple duration). Note that while F(t) defines the mapping for the entire animation, f(t) has a simplified model that just handles the simple duration.

F(t)

The effect of an animation for any point in the animation. This maps any non-negative time to a value for the target attribute. A time value of 0 corresponds to the time at which the animation begins. Note that F(t) combines the animation function f(t) with all the other aspects of animation and timing controls.

B

The begin of an animation.

d

The simple duration of an animation.

AD

The active duration of an animation. This is the period during which time is actively advancing for the animation. This includes any effect of repeating the simple duration, but does not include the time during which the animation may be frozen.

AE

The active end. This is the end of the active duration of an animation.

3. Animation Model

This section describes the syntax and semantics for describing animations. The specific elements are not described here, but rather the common concepts and syntax that comprise the model for animation.  Document issues are described, as well as the means to target an element for animation. The animation model is then defined by building up from the simplest to the most complex concepts: first the simple duration and animation function f(t), and then the overall behavior F(t).  Finally, the model for combining animations is presented, and additional details of animation timing are described.

The host document is presented over a certain time interval. The start of the interval in which the document is presented is referred to as the document begin. The end of the interval in which the document is presented is referred to as the document end. The difference between the end and the begin is referred to as the document duration. The formal definitions of presentation and document begin and end are left to the host language designer (see also Required host language definitions).

3.1. Specifying the animation target

The animation target is described as a specific attribute of a particular element. The means of specifying the target attribute and the target element are detailed in this section.

The Target Attribute

The target attribute to be animated is specified with attributeName. The value of this attribute is a string that specifies the name of the target attribute, as defined in the host language.

The attributes of an element that can be animated are often defined by different languages, and/or in different namespaces. For example, in many XML applications, the position of an element (which is a typical target attribute) is defined as a CSS property rather than as XML attributes. In some cases, the same attribute name is associated with attributes or properties in more than one language, or namespace.  To allow the author to disambiguate the name mapping, an additional attribute attributeType is provided that specifies the intended namespace. 

The attributeType attribute is optional. By default, the animation runtime will resolve the names according to the following rule: If there is a name conflict and attributeType is not specified, the CSS namespace is matched first (if CSS is supported in the host language), followed by the default namespace for the target element. If a target attribute is defined in an XML Namespace other than the default namespace for the target element, the author must specify the namespace of the target attribute using the associated namespace prefix as defined in the scope of the target element. The prefix is prepended to the value for attributeName.

For more information on XML namespaces, see [XML-NS].

attributeName = <attributeName>

Specifies the name of the target attribute. An XMLNS prefix may be used to indicate the XML namespace for the attribute. The prefix will be interpreted in the scope of the target element.

 

attributeType = "CSS | XML | auto"

Specifies the namespace in which the target attribute and its associated values are defined. The attribute value is one of the following:

"XML"

This specifies that the value of "attributeName" is the name of an XML attribute defined in the default XML namespace for the target element. If the value for attributeName has an XMLNS prefix, the implementation must use the associated namespace as defined in the scope of the target element.

"CSS"

This specifies that the value of "attributeName" is the name of a CSS property, as defined for the host document. This argument value is only meaningful in host language environments that support CSS.

"auto"

The implementation should match the attributeName to an attribute for the target element. 
This is the default.

The Target Element

An animation element can define the target element of the animation either explicitly or implicitly. An explicit definition uses an attribute to specify the target element. The syntax for this is described below.

If no explicit target is specified, the implicit definition of the target element is the parent element of the animation element in the document tree. It is expected that the common case will be that an animation element is declared as a child of the element to be animated. In this case, no explicit target need be specified.

If an explicit target element reference cannot be resolved (e.g. no such element can be found), the animation has no effect. In addition, if the target element (either implicit or explicit) does not support the specified target attribute, the animation has no effect. See also Handling Syntax Errors.

The following two attributes can be used to identify the target element explicitly:

targetElement = "<IDREF>"

This attribute specifies the target element to be animated. The attribute value must be the value of an XML identifier attribute of an element within the host document. For a formal definition of "IDREF", refer to XML 1.0 [XML]. 

href = uri-reference

This attribute specifies an XLink reference to the target element to be animated.

When integrating animation elements into the host language, the language designer should avoid including both of these attributes. If however, both attributes must be included in the host language, and they both occur in an animation element, the XLink "href" attribute takes precedence over the "targetElement" attribute.

The advantage of using a "targetElement" attribute is a simpler syntax of the attribute value compared to the "href" attribute. The advantage of using the XLink "href" attribute is that it is extensible to a full linking mechanism in future versions of SMIL Animation, and the animation element can be processed by generic XLink processors. The XLink form is also provided for host languages that are designed to use XLink for all such references.

When using an XLink "href" attribute, the following additional XLink attributes need to be defined in the host language. These may be defined in a DTD, or the host language may require these in the document syntax to support generic XLink processors. For more information, refer to the "XML Linking Language (XLink)" [XLink].

The following XLink attributes are required by the XLink specification. The values are fixed, and so may be specified as such in a DTD. All other XLink attributes are optional, and do not affect SMIL Animation semantics.

type = 'simple'

Identifies the type of XLink being used. To link to the target element, a simple link is used, and thus the attribute value is fixed to "simple". 

actuate = 'auto'

Indicates that the link to the target element is followed automatically (i.e., without user action).

show = 'embed'

Indicates that the reference does not include additional content in the file. 

3.2. Specifying the animation function f(t)

Each animation function defines the value of the attribute at a particular moment in time. The range for which the animation function is defined is the simple duration. The animation function does not produce defined results for times outside the range of 0 to the simple duration.

3.2.1. Specifying function timing

The basic timing for an element is described using the begin, end and dur attributes. Authors can specify the begin time of an animation in a variety of ways, ranging from simple clock times to the time that an event like a mouse-click happens. The length of the simple duration can be specified either as a duration or by specifying an end time. The attribute syntax is described below.

begin

Defines when the element should begin (i.e. become active).
The attribute value can be one of the following types of values:

clock-value

Specifies the presentation time at which the animation begins. The begin is thus defined relative to the document begin.

syncbase-value : ( id-ref "." ) ( "begin" | "end" ) ( "+"clock-value )?

Describes a syncbase and an offset from that syncbase. The element begin is defined relative to the begin B or active end AE of another animation.

event-value : ( id-ref "." )? ( event-ref  ) ( "+"clock-value )?

Describes an event and an optional offset that determine the element begin. The animation begin is defined relative to the time that the event is raised. Events may be any event defined for the host language in accordance with [DOM2Events]. These may include user-interface events, event-triggers transmitted via a network, etc. Details of vvent-based timing are described in the section below on Unifying Event-based and Scheduled Timing.

"indefinite"

The begin of the animation will be determined by a "beginElement()" method call or a hyperlink targeted to the animation element.
The SMIL Animation DOM methods are described in the Supported Methods section.
Hyperlink-based timing is described in the Hyperlinks and Timing section.

dur

Specifies the simple duration.
The attribute value can be one of the following types of values:

clock-value

Specifies the length of the simple duration in presentation time.

"indefinite"

Specifies the simple duration d as indefinite.

end

Specifies the simple duration as the difference between an end time and the begin time of the animation B. 
The attribute value can be one of the following types of values:

clock-value

Specifies the presentation time at which the simple duration ends. The end of the simple duration is thus defined relative to the document begin. 

syncbase-value : ( id-ref "." ) ( "begin" | "end" ) ( "+"clock-value )?

Describes a syncbase and an offset from that syncbase. The animation end is defined relative to the begin B or active end AE of another animation.

If no begin is specified, the default value is "0" - the animation begins when the document begins. If there is any error in the argument value syntax for begin, the default value for begin will be used.

If the animation does not have a dur or end attribute, the simple duration is indefinite.

If there is any error in the argument value syntax for dur or end, the respective attribute will be ignored (as though it were not specified). If the end specifies a time that is before the begin time of the animation, the end specification is ignored.

The simple duration defined by end, regardless of the attribute value variant, is computed as the time defined by end, minus the begin time. If the end time is indefinite, the computed simple duration is also indefinite.

If the animation element has both a dur and an end attribute, the simple duration is defined to be the minimum duration specified by these attributes. For the purposes of this comparison, a defined value is considered to be "less than" an "indefinite" value.

Note that when the end attribute refers to the begin or end of another animation, it may not be possible to calculate when the end will happen. For example, if the syncbase element is defined to begin on some event, the begin and end times will not be known until the event happens. When such a time becomes known (i.e. when it can be calculated as a presentation time), the time is said to be resolved (see also the discussion of Unifying scheduled and interactive timing). The simple duration is indefinite if the end specifies a syncbase-value that is not a resolved time. 

Note that the simple duration may be indefinite when an animation begins, but can then be resolved at some point after the animation begins. For example:

<rect>
   <animate id="foo" endActive="onclick" .../>
   <animate id="bar" end="foo.end" .../>
</rect>

The simple duration of "bar" is defined by the active end of "foo". When the user clicks on the rectangle parent, "foo" ends and the simple duration of "bar" becomes defined as well.

Timing Attribute Values

In the syntax specifications that follow, allowed white space is indicated as "S", defined as follows (taken from the [XML] definition for "S"):

S ::= (#x20 | #x9 | #xD | #xA)+

Clock values

Clock values have the following syntax:

Clock-val         ::= Full-clock-val | Partial-clock-val 
                      | Timecount-val
Full-clock-val    ::= Hours ":" Minutes ":" Seconds ("." Fraction)?
Partial-clock-val ::= Minutes ":" Seconds ("." Fraction)?
Timecount-val     ::= Timecount ("." Fraction)? (Metric)?
Metric            ::= "h" | "min" | "s" | "ms"
Hours             ::= DIGIT+; any positive number
Minutes           ::= 2DIGIT; range from 00 to 59
Seconds           ::= 2DIGIT; range from 00 to 59
Fraction	  ::= DIGIT+
Timecount         ::= DIGIT+
2DIGIT		  ::= DIGIT DIGIT
DIGIT		  ::= [0-9]

For Timecount values, the default metric suffix is "s" (for seconds). No embedded white space is allowed in clock values, although leading and trailing white space characters will be ignored.

In SMIL Animation, clock values describe presentation time. Presentation time behaves like the timecode shown on a counter of a tape-deck that advances at the speed of the presentation. It reflects that the presentation can be stopped, and that its speed can be decreased or increased either by user actions, or by the animation engine itself.

The following are examples of legal clock values:

• Full clock values: 
  02:30:03    = 2 hours, 30 minutes and 3 seconds
    50:00:10.25 = 50 hours, 10 seconds and 250 milliseconds
• Partial clock value: 
  02:33   = 2 minutes and 33 seconds
    00:10.5 = 10.5 seconds = 10 seconds and 500 milliseconds
• Timecount values:
    3.2h    = 3.2 hours = 3 hours and 12 minutes
    45min   = 45 minutes
    30s     = 30 seconds
    5ms     = 5 milliseconds
    12.467  = 12 seconds and 467 milliseconds

Fractional values are just (base 10) floating point definitions of seconds. Thus:

00.5s = 500 milliseconds
00:00.005 = 5 milliseconds

Syncbase values

A syncbase value has the following syntax:

 Syncbase-value   ::= ( Syncbase-element "." Time-symbol )
                      ( S "+" S Clock-value )? 
 Syncbase-element ::= Id-value
 Time-symbol      ::= "begin" | "end"

A syncbase value starts with a Syncbase-element term defining the value of an "id" attribute of an animation element referred to as the syncbase element. This element must be another animation element contained in the host document.

The syncbase element is qualified with one of the following time symbols:

begin

Specifies the begin time of the syncbase element.

end

Specifies the Active End AE of the syncbase element.

The time symbol can be followed by a clock value. The clock value specifies a presentation time offset from the time (i.e. the begin or end) specified by the syncbase and time symbol. If the clock value is omitted, it defaults to "0".

No embedded white space is allowed between a syncbase element and a time-symbol. White space will be ignored before and after a "+" for a clock value. Leading and trailing white space characters (i.e. before and after the entire syncbase value) will be ignored.

Examples:

  begin="x.end+45s"  : Begin 45 seconds after "x" ends
  begin=" x.begin "  : Begin when "x" begins
  end="x.begin + 1m" : End 1 minute after "x" begins

Event values

An event value has the following syntax:

  Event-value       ::= ( Eventbase-element "." )? Event-symbol 
                        ( S "+" S Clock-value )? 
  Eventbase-element ::= Id-value

An Event value starts with an Eventbase-element term that specifies the event-base element. The event-base element is the element on which the event is observed. Given DOM event bubbling, the event-base element may be either the element that raised the event, or it may be an ancestor element on which the bubbled event can be observed. Refer to DOM-Level2-Events [DOM2Events] for details.
The "Id-value" is the value of an attribute declared to be an "id" in the host language, for the event-base element. This element must be another animation element contained in the host document.
If the Eventbase-element term is missing, the event-base element defaults to the target element of the animation. 

The event value must specify an Event-symbol. This term specifies the name of the event that is raised on the Event-base element.  The host language designer must specify which types of events can be used.

The last term specifies an optional clock-value that is a presentation time offset from the event. If this term is omitted, the offset is 0.

No embedded white space is allowed between an eventbase element and an event-symbol. White space will be ignored before and after a "+" for a clock value. Leading and trailing white space characters (i.e. before and after the entire eventbase value) will be ignored.

Note that it is not considered an error to specify an event that cannot be raised on the Event-base element (such as onclick for audio or other non-visual elements).  Similarly, if the host language allows dynamically created events (as supported by DOM-Level2-Events [DOM2Events]), all possible Event-symbol names cannot be specified, and so unrecognized names may not be considered errors. Host language specifications must include a description of legal event names, and/or allow any name to be used.

Examples:

 begin=" x.onload "   : Begin when "onload" is observed on "x"
 begin="x.onfocus+3s" : Begin 3 seconds after an "onfocus" event on "x"

The defaults for the event and target element syntax make it easy to define simple interactive behavior. The following example sets the rect element color to be red for 5 seconds, when the user clicks on the element.

  <rect ...>
    <set begin="onclick" dur="5s" to="red"
         attributeName="fill" attributeType="css" />
    ...
  </rect>

3.2.2. Specifying function values

The animation is described either as a list of values, or in a simplified form that describes the from, to and by values.

from = "<value>"

Specifies the starting value of the animation.

to = "<value>"

Specifies the ending value of the animation.

by = "<value>"

Specifies a relative offset value for the animation.

values = "<list>"

A semicolon-separated list of one or more values. Vector-valued attributes are supported using the vector syntax of the attributeType domain.

The animation values specified in the animation element must be legal values for the specified attribute. Leading and trailing white space, and white space before and after semi-colon separators, will be ignored.

All values specified must be legal values for the specified attribute (as defined in the associated namespace). If any values are not legal, the animation will have no effect (see also Handling Syntax Errors).

If a list of values is used, the animation will apply the values in order over the course of the animation (pacing and interpolation between these values is described in the next section). If a list of values is specified, any from, to and by attribute values are ignored.

The simpler syntax provides for several variants. Note that from is optional, but that one of by or to must be used (unless of course a list of values is provided). It is not legal to specify both by and to attributes - if both are specified, only the to attribute will be used (the by will be ignored). The combinations of attributes yield the following classes of animation:

from-to animation

Specifying a from value and a to value defines a simple animation, equivalent to a values list with 2 values. The animation function is defined to start with the from value, and to finish with the to value.

from-by animation

Specifying a from value and a by value defines a simple animation in which the animation function is defined to start with the from value, and to change this over the course of the simple duration d by a delta specified with the by attribute. This may only be used with attributes that support addition (e.g. most numeric attributes).

by animation

Specifying only a by value defines a simple animation in which the animation function is defined to offset the underlying value for the attribute, using a delta that varies over the course of the simple duration d, starting from a delta of 0 and ending with the delta specified with the by attribute. This may only be used with attributes that support addition.

to animation

This describes an animation in which the animation function is defined to start with the underlying value for the attribute, and finish with the value specified with the to attribute. Using this form, an author can describe an animation that will start with whatever value the attribute has originally, and will end up at the desired to value.

The last two forms "by animation" and "to animation" have additional semantic constraints when combined with other animations. The details of this are described below in the section How from, to and by attributes affect additive behavior.

If the simple duration of an animation is indefinite when an animation begins, interpolation is not generally meaningful. While it is possible to define an animation function that is not based upon a defined simple duration (e.g. some random number algorithm), most animations define the function in terms of the simple duration. If an animation function is defined in terms of the simple duration and the simple duration is indefinite, the first value of the animation function (i.e. f(0)) should be used (effectively as a constant) for the animation function. Note that the simple duration may change from indefinite to some resolved value while the animation is active - see also the section Propagating Changes to Times.

Examples

The following example using the values syntax animates the width of an SVG shape over the course of 10 seconds from a width of 40 to a width of 100 and back to 40.

<rect ...>
   <animate attributeName="width" values="40;100;40" dur="10s"/>
</rect>

The following "from-to animation" example animates the width of an SVG shape over the course of 10 seconds from a width of 50 to a width of 100.

<rect ...>
   <animate attributeName="width" from="50" to="100" dur="10s"/>
</rect>

The following "from-by animation" example animates the width of an SVG shape over the course of 10 seconds from a width of 50 to a width of 75.

<rect ...>
   <animate attributeName="width" from="50" by="25" dur="10s"/>
</rect>

The following "by animation" example animates the width of an SVG shape over the course of 10 seconds from the original width of 40 to a width of 70.

<rect width="40"...>
   <animate attributeName="width" by="30" dur="10s"/>
</rect>

The following "to animation" example animates the width of an SVG shape over the course of 10 seconds from the original width of 40 to a width of 100.

<rect width="40"...>
   <animate attributeName="width" to="100" dur="10s"/>
</rect>

3.2.3. Specifying function calculation modes

By default, a simple linear interpolation is performed over the values, evenly spaced over the duration of the animation.  Additional attributes can be used for finer control over the interpolation and timing of the values. The calcMode attribute defines the basic method of applying values to the attribute. The keyTimes attribute provides additional control over the timing of the animation function, associating a time with each value in the values list. Finally, the keySplines attribute provides a means of controlling the pacing of interpolation between the values in the values list.

calcMode = "discrete | linear | paced | spline"

Specifies the interpolation mode for the animation. This can take any of the following values.  The default mode is "linear", however if the attribute does not support linear interpolation (e.g. for strings), this attribute is ignored and discrete interpolation is always used.

"discrete"

This specifies that the animation function will jump from one value to the next without any interpolation.

"linear"

Simple linear interpolation between values is used to calculate the animation function. This is the default calcMode.

"paced"

Defines interpolation to produce an even pace of change across the animation. This is only supported for values that define a linear numeric range, and for which some notion of "distance" between points can be calculated (e.g. position, width, height, etc.). If "paced" is specified, any keyTimes or keySplines will be ignored.

"spline"

Interpolates from one value in the values list to the next according to a time function defined by a cubic Bezier spline. The points of the spline are defined in the keyTimes attribute, and the control points for each interval are defined in the keySplines attribute.

keyTimes = "<list>"

A semicolon-separated list of time values used to control the pacing of the animation. Each time in the list corresponds to a value in the values attribute list, and defines when the value should be used in the animation function. Each time value in the keyTimes list is specified as a floating point value between 0 and 1 (inclusive), representing a proportional offset into the simple duration of the animation element.  
Each successive time value must be greater than or equal to the preceding time value. 
The first time value in the list must be 0, and the last time value in the list must be 1.
If a list of keyTimes is specified, there must be exactly as many values in the keyTimes list as in the values list. 
If there are any errors in the keyTimes specification (bad values, too many or too few values), the animation will have no effect.
If the simple duration is indefinite, any keyTimes specification will be ignored.

keySplines = "<list>"

A set of Bezier control points associated with the keyTimes list, defining a cubic Bezier function that controls interval pacing. The attribute value is a semi-colon separated list of control point descriptions. Each control point description is a set of four values: x1 y1 x2 y2, describing the Bezier control points for one time segment. The keyTimes values that define the associated segment are the Bezier "anchor points", and the keySplines values are the control points.
Thus, there must be one fewer sets of control points than there are keyTimes. 
The values must all be in the range 0 to 1.
This attribute is ignored unless the calcMode is set to "spline".
If there are any errors in the keySplines specification (bad values, too many or too few values), the animation will have no effect.

If the keyTimes attribute is not specified, the values in the values attribute are assumed to be equally spaced through the animation duration, according to the calcMode:

• For discrete animation, the duration is divided into equal time periods, one per value. The animation function takes on the values in order, one value for each time period. 
• For linear and spline animation, the duration is divided into n-1 even periods, and the animation function is a linear interpolation between the values at the associated times. Note that a linear animation will be a nicely closed loop if the first value is repeated as the last.

Note that for the shorthand forms to animation and from-to animation, there are only 1 and 2 values respectively. Thus a discrete to animation will simply set the "to" value for the simple duration. A discrete from-to animation will set the "from" value for the first half of the simple duration and the "to" value for the second half of the simple duration.

Note that if the calcMode is set to "paced", the keyTimes attribute is ignored, and the values in the values attribute are spaced to produce a constant rate of change as the target attribute value is interpolated.

If the  argument values for keyTimes or interSpline are not legal (including too few or too many values for either attribute), the animation will have no effect (see also Handling Syntax Errors).

In the calcMode, keyTimes and keySplines attribute values, leading and trailing white space and white space before and after semi-colon separators will be ignored.

Examples

This example describes a somewhat unusual usage: "from-to animation" with discrete animation. The "fontStyle" attribute of the SVG font element takes a string, and so implies a calcMode of discrete. The animation will set the fontStyle to "italic" for 5 seconds (half the simple duration) and then set the fontStyle to "bold,italic" for 5 seconds.

<font fontStyle="normal"...>
   <animate attributeName="fontStyle" 
      from="italic" to="bold,italic" dur="10s"/>
</font>

This example illustrates the use of keyTimes:

<animate attributeName="x" dur="10s" values="0; 50; 100" 
     keyTimes="0; .8; 1" calcMode="linear"/>

The keyTimes values causes the "x" attribute to have a value of "0" at the start of the animation, "50" after 8 seconds (at 80% into the simple duration) and "100" at the end of the animation. The value will change more slowly in the first half of the animation, and more quickly in the second half.

Extending this example to use keySplines:

<animate attributeName="x" dur="10s" values="0; 50; 100" 
     keyTimes="0; .8; 1" calcMode="spline" 
     keySplines=".5 0 .5 1; 0 0 1 1" />

The keyTimes still causes the "x" attribute to have a value of "0" at the start of the animation, "50" after 8 seconds and "100" at the end of the animation. However, the keySplines values define a curve for pacing the interpolation between values. In the example above, the spline causes an ease-in and ease-out effect between time 0 and 8 seconds (i.e. between keyTimes 0 and .8, and values "0" and "50"), but a strict linear interpolation between 8 seconds and the end (i.e. between keyTimes .8 and 1, and values  "50" and "100"). See Figure 1 below for an illustration of the curves that these keySplines values define.

For some attributes, the pace of change may not be easily discernable by viewers. However for animations like motion, the ability to make the speed of the motion change gradually, and not in abrupt steps can be important. The keySplines attribute provides this control.

The following figure illustrates the interpretation of the keySplines attribute. Each diagram illustrates the effect of keySplines settings for a single interval (i.e. between the associated pairs of values in the keyTimes and values lists.). The horizontal axis can be thought of as the input value for the unit progress of interpolation within the interval - i.e. the pace with which interpolation proceeds along the given interval. The vertical axis is the resulting value for the unit progress, yielded by the keySplines function. Another way of describing this is that the horizontal axis is the input unit time for the interval, and the vertical axis is the output unit time. See also the section Timing and real-world clock times.

	keySplines="0 0 1 1" (the default)		keySplines=".5 0 .5 1"
	keySplines="0 .75 .25 1"		keySplines="1 0 .25 .25"

Figure 1: Illustration of keySpline effect

To illustrate the calculations, consider the simple example:

<animate dur="4s" values="10; 20" keyTimes="0; 1"
     calcMode="spline" keySplines={as in table} />

Using the keySplines values for each of the four cases above, the approximate interpolated values as the animation proceeds are:

For a formal definition of Bezier spline calculation, see:

Computer Graphics : Principles and Practice, Second Edition by James D. Foley, Andries van Dam, Steven K. Feiner, John F. Hughes, Richard L. Phillips, Addison-Wesley, pp. 488-491.

3.3. Specifying the animation effect F(t)

As described above, the animation function f(t) defines the animation for the simple duration. However SMIL Animation allows the author to repeat this, and to specify whether the animation should simply end when the active duration completes, or whether it should be frozen at the last value.  In addition, the author can specify how each animation should be combined with other animations and the original DOM value.

This section describes the syntax and associated semantics for the additional functionality. A detailed model for combining animations is described, along with a state model for animations, and additional details of the timing model.

The period of time during which the animation is actively playing, including any repeat behavior, is described as the active duration AD. The active duration may be computed from the simple duration and the repeat specification, or it may be specified with the endActive attribute.  The complete rules for computing the active duration are presented in the section Computing the Active Duration.

3.3.1. Repeating Animations

Repeating an animation causes the animation function f(t) to be "played" several times in sequence.  The author can specify either how many times to repeat, using repeatCount, or how long to repeat, using repeatDur. Each repeat iteration is one instance of "playing" the animation function f(t).

If the simple duration d is indefinite, the animation cannot repeat. See also the sections Computing the Active Duration and Propagating Changes to Times.

repeatCount

Specifies the number of iterations of the animation function. It can have the following attribute values:

numeric value

This is a (base 10) "floating point" numeric value that specifies the number of iterations. It can include partial iterations expressed as fraction values. A fractional value describes a portion of the simple duration d. Values must be greater than 0.


"indefinite"

The animation is defined to repeat indefinitely (i.e. until the document ends).

repeatDur

Specifies the total duration for repeat. It can have the following attribute values:

clock-value

Specifies the duration in presentation time to repeat the animation function f(t).

 

"indefinite"

The animation is defined to repeat indefinitely  (i.e. until the document ends).

At most one of repeatCount or repeatDur should be specified. If both are specified (and the simple duration is not indefinite), the active duration is defined as the minimum of the specified repeatDur, and the simple duration multiplied by repeatCount. For the purposes of this comparison, a defined value is considered to be "less than" a value of "indefinite". If the simple duration is indefinite, and both repeatCount or repeatDur are specified, the repeatCount will be ignored, and the repeatDur will be used (refer to the examples below describing repeatDur and an indefinite simple duration). These rules are included in the section Computing the Active Duration.

Examples

@@ Need to add example of repeatCount < 1 and/or repeatDur < simple duration

In the following example, the 2.5 second animation function will be repeated twice; the active duration AD will be 5 seconds.

<animate attributeName="top" from="0" to="10" dur="2.5s"
         repeatCount="2" />

In the following example, the animation function will be repeated two full times and then first half is repeated once more; the active duration AD will be 7.5 seconds.

<animate attributeName="top" from="0" to="10" dur="3s"
         repeatCount="2.5" />

In the following example, the animation function will repeat for a total of 7 seconds. It will play fully two times, followed by a fractional part of 2 seconds. This is equivalent to a repeatCount of 2.8. The last (partial) iteration will apply values in the range "0" to "8". 

<animate attributeName="top" from="0" to="10" dur="2.5s"
         repeatDur="7s" />

Note that if the simple duration is not defined (e.g. it is indefinite), repeat behavior is not defined (but repeatDur still defines the active duration). In the following example the simple duration is indefinite, and so the repeatCount is effectively ignored. Nevertheless, this is not considered an error. The active duration AD is also indefinite. The effect of the animation is to set the fill color to red (i.e. to just use the value for f(0)) for the remainder of the document duration.

<animate attributeName="fill" from="red" to="blue" repeatCount="2" />

In the following example, the simple duration is indefinite, and so repeat behavior is not meaningful. However, the repeatDur still determines the active duration AD. The effect of the animation is to set the fill color to red for 10 seconds.

<animate attributeName="fill" from="red" to="blue" repeatDur="10s" />

In the following example, the simple duration is longer than the duration specified by repeatDur, and so the active duration will effectively cut short the simple duration. However, animation function still uses the specified simple duration. The effect of the animation is to interpolate the value of "top" from 10 to 15, over the course of 5 seconds.

<animate attributeName="top" from="10" to="20" 
         dur="10s" repeatDur="5s" />

Computing Simple Duration for Repeating animations.

If an element is defined to repeat and the simple duration is defined by end, the end is only used for the first repeat iteration. The simple duration d computed for the first repeat iteration is used for all successive iterations, and the end value is effectively ignored. For example:

<rect>
   <animate id="foo" dur="5s" .../>
   <animate id="bar" end="foo.end" repeatCount="5" .../>
</rect>

The simple duration of "bar" is 5 seconds. If each repeat iteration re-evaluated the simple duration, the second and successive iterations would compute a simple duration of 0. The SMIL Animation timing model uses the simple duration as defined in the first iteration, and so the "bar" animation will repeat the simple duration another 4 times, using the 5 second simple duration for all iterations.

The same semantics apply when the simple duration is not resolved when an element begins. The details of this as described in Propagating Changes to Times.

Controlling behavior of repeating animation - Cumulative Animation

The author may also select whether a repeating animation should repeat the original behavior for each iteration, or whether it should build upon the previous results, accumulating with each iteration. For example, a motion path that describes an arc can repeat by drawing the same arc over and over again, or it can begin each repeat iteration where the last left off, making the animated element bounce across the window. This is called cumulative animation.

Using the path notation for a simple arc, we describe this as:

<img ...>
   <animateMotion path="c( 3 5 8 5 10 0)" dur="10s"
      accumulate="sum" repeatCount="10" />
</img>

@@ Pictures would help here

The image moves from the original position along the arc over the course of 10 seconds. As the animation repeats, it builds upon the previous value and begins the second arc where the first one ended. In this way, the image "bounces" across the screen. This could be described as a complete path, but the path description would get quite large, and would be more cumbersome to edit.

Any numeric attribute that supports addition can support cumulative animation. For example, we can grow the "width" of an SVG "rect" element by 100 pixels in 100 seconds.

<rect width="20px"...>
   <animate attributeName="width" by="10px" dur="10s"
      accumulate="sum" repeatCount="10" />
</rect>

After 10 seconds, the rectangle is 30 pixels wide. The animation repeats, and builds upon the previous values growing to 40 pixels after 20 pixels, and up to 120 pixels wide after all ten repeats.

The behavior of repeating animations is controlled with the accumulate attribute:

accumulate = "none | sum"

Controls whether or not the animation is cumulative. 
If "sum", each repeat iteration after the first builds upon the last value of the previous iteration.
If "none", repeat iterations are not cumulative, and simply repeat the animation function f(t). This is the default.
This attribute is ignored if the target attribute value does not support addition, or if the animation element does not repeat.
Cumulative animation is not defined for "to animation". This attribute will be ignored if the animation function is specified with only the to attribute. See also Specifying function values.

To produce the cumulative animation behavior, the animation function f(t) must be modified slightly. Each iteration after the first must add in the last value of the previous iteration - this is expressed as a multiple of the last value specified for the animation function. Note that cumulative animation is defined in terms of the values specified for the animation behavior, and not in terms of sampled or rendered animation values. The latter would vary from machine to machine, and could even vary between document views on the same machine.

Let fi(t) represent the cumulative animation function for a given iteration.

The first iteration f0(t) is unaffected by accumulate, and so is the same as the original animation function definition.

f0(t) = f(t)

Let ve be the last value specified for the animation function (e.g. the "to" value or the last value in a "values" list).  Each iteration after the first (i.e. fi(t) where i >= 1 ) adds in the computed offset:

fi(t) = (ve * (i-1)) + f(t)

3.3.2. Specifying endActive

SMIL Animation provides an additional control over the active duration. The endActive attribute allows the author to specify the active end of the animation using a simple offset, a time base, an event-base or DOM methods calls.

endActive

Defines the active end AE of the animation (i.e. the end of the active duration).
The attribute value can be one of the following types of values:

clock-value

Specifies the presentation time of the active end. The active end is thus defined relative to the document begin.

syncbase-value : ( id-ref ) ( ".begin" | ".end" )? ( "+"clock-value )?

Describes a syncbase and an offset from that syncbase. The active end is defined relative to the begin B or active end AE of another animation.

event-value : ( id-ref "." )? ( event-ref  ) ( "+"clock-value )?

Describes an event and an optional offset that determine the active end. The active end is defined relative to the time that the event is raised. The event must be raised after the animation begins, and before the active duration otherwise ends (e.g. as defined by repeatDur). Events may be any event defined for the host language in accordance with [DOM2Events]. These may include user-interface events, event-triggers transmitted via a network, etc. Details of event-based timing are described in the section below on Unifying Event-based and Scheduled Timing.

"indefinite"

The active end of the animation will be determined by an "endElement()" method call. The SMIL Animation DOM methods are described in the Supported Methods section.

If endActive specifies an event-value or syncbase-value that is not resolved, the active duration is indefinite (until resolved).

@@Need example with set showing indefinite simple dur and endActive with end event. An example of the endActive cutting short a longer simpler dur might also be good.

In the following example, the active duration will end at the earlier of 10 seconds, or the end of the "foo" element. This is particularly useful if "foo" is defined to begin or end relative to an event.

<animate dur="2s" repeatDur="10s" endActive="foo.end" ... />

In the following example, the animation begins when the user clicks on the target element. The active duration will end 30 seconds after the document begins. Note that if the user has not clicked on the target element before 30 seconds elapse, the animation will never begin.

<animate begin="onclick" dur="2s" repeatDur="indefinite"
         endActive="30s" ... />

Using endActive with an event value enables authors to end an animation based on either an interactive event or a maximum active duration. This is sometimes known as lazy interaction.

In this example, a presentation describes factory processes. It uses animation to move an image around (e.g. against a background), demonstrating how an object moves from one part of a factory to another. Each step is a motion path, and set to repeat 3 times to make the point clear. Each animation can also be ended by clicking on some element "next" that indicates to the user that the next step should be shown.

<img id="objectToMove" ... >
  <animateMotion id="step1" begin="0" dur="5s"
     repeatCount="3" endActive="next.onclick" path.../>
  <animateMotion id="step2" begin="step1.end" dur="5s"
     repeatCount="3" endActive="next.onclick" path.../>
  <animateMotion id="step3" begin="step2.end" dur="5s"
     repeatCount="3" endActive="next.onclick" path.../>
  <animateMotion id="step4" begin="step3.end" dur="5s"
     repeatCount="3" endActive="next.onclick" path.../>
  <animateMotion id="step5" begin="step4.end" dur="5s"
     repeatCount="3" endActive="next.onclick" path.../>
</img>

In this case, the active end of each animation is defined to be the earlier of 5 seconds after it begins, or a click on "next". This lets the viewer sit back and watch, or advance the presentation at a faster pace.

3.3.3. Computing the Active Duration

The table in Figure 2 shows the semantics of all possible combinations of simple duration, repeatCount and repeatDur, and endActive.

In the table below, if a cell is empty, it indicates that the associated attribute is omitted in the syntax. Where the table entry is "defined", this should be interpreted as a specified value other than "indefinite".  Note that if the simple duration is not specified, it is defined to be indefinite. Where the entry is a star ("*"), the value does not matter and can be any of the possibilities. Note that where the active duration is specified as the minimum of several values (MIN), it may not always be possible to calculate this when the document begins. If the endActive is event-based or DOM-based, then an event or method call that activates endActive before the duration specified by repeatCount or repeatDur will cut short the active duration at the endActive activation time.

Note that if either the simple duration or the value of endActive cannot be resolved, the respective value is considered to be "indefinite" for the purposes of evaluating the active duration. If and when the respective value becomes resolved, the active duration is reevaluated.

Note that for any active duration and simple duration that are both not indefinite, the number of repeat iterations is defined by the active duration AD divided by the simple duration d (this may yield partial repeat iterations, just as repeatCount specifies).

If both endActive and either (or both) of repeatCount or repeatDur are specified, the active duration AD is defined by the minimum duration defined by the respective attributes.

If endActive is specified but neither of repeatCount or repeatDur are specified, then the active duration AD is defined as the minimum of the simple duration and the duration defined by endActive.

Note also that it is possible to have an indefinite simple duration and a defined, finite active duration. The active duration can cut short the simple duration, but the active duration does not define the simple duration, or change its value.

Figure 2: Computing the active duration for different combinations of simple duration, repeatDur and repeatCount, and endActive.

3.3.4. Freezing Animations

By default when an animation element ends, its effect is no longer applied to the presentation value for the target attribute. For example, if an animation moves an image and the animation element ends, the image will "jump back" to its original position.

<img top="3" ...>
   <animate begin="5s" dur="10s" attributeName="top" by="100"/>
</img>

The image will appear stationary at the top value of "3" for 5 seconds, then move 100 pixels down in 10 seconds. 15 seconds after the document begin, the animation ends, the effect is no longer applied, and the image jumps back from 103 to 3 where it started (i.e. to the underlying value of the top attribute).

The fill attribute can be used to maintain the value of the animation after the active duration of the animation element ends:

<img top="3" ...>
   <animate begin= "5s" dur="10s" attributeName="top" by="100"
          fill="freeze" />
</img>

The animation ends 15 seconds after the document begin, but the image remains at the top value of 103. The attribute "freezes" the last value of the animation for the remainder of the document duration.

The freeze behavior of an animation is controlled using the "fill "attribute:

fill

This attribute can have the following values:

freeze

The animation effect F(t) is defined to freeze the effect value at the last value of the active duration. The animation effect is "frozen" for the remainder of the document duration (or until the animation is restarted - see Restarting Animations). 

remove

The animation effect is removed (no longer applied) when the active duration of the animation is over. After the active end AE of the animation, the animation no longer affects the target (unless the animation is restarted - see Restarting Animations).
This is the default value.

This functionality is also useful when a series of motions are defined that should build upon one another, as in this example:

<img ...>
   <animateMotion begin="0" dur="5s" path="[some path]"
           additive="sum" fill="freeze" />
   <animateMotion begin="5s" dur="5s" path="[some path]"
           additive="sum" fill="freeze" />
   <animateMotion begin="10s" dur="5s" path="[some path]"
           additive="sum" fill="freeze" />
</img>

The image moves along the first path, and then starts the second path from the end of the first, then follows the third path from the end of the second, and stays at the final point. The semantics of the additive attribute are defined in the next section.

Note that freeze uses the value of the animation at the active end AE, and not the value that was sampled just before the freeze is applied. When combined with the semantics for indefinite simple durations, an interesting behavior results. For example:

  <animate from="10" to="20" begin="5s" end="onclick" fill="freeze" .../> 

Because the end is specified as an event, the simple duration is indefinite. As long as the animation is active, it uses f(0), the value "10". When the user clicks on the parent element, the animation ends. This also defines the simple duration (it is the time of the click minus 5) and so the value of F(t) while the animation is frozen is equal to the "to" value of "20".

3.3.5. Additive Animation

It is frequently useful to define animation as an offset or delta to an attribute's value, rather than as absolute values. A simple "grow" animation can increase the width of an object by 10 pixels:

<rect width="20px" ...>
   <animate attributeName="width" from="0" to="10" dur="10s"
      additive="sum"/>
</rect>

The width begins at 20 pixels, and increases to 30 pixels over the course of 10 seconds.  If the animation were declared to be non-additive, the same from and to values would make the width go from 0 to 10 pixels over 10 seconds.

In addition, many complex animations are best expressed as combinations of simpler animations. A "vibrating" path, for example, can be described as a repeating up and down motion added to any other motion:

<img ...>
   <animateMotion from="0,0" to="100,0" dur="10s" />
   <animateMotion values="0,0; 0,5; 0,0" dur="1s"
                  repeatDur="10s" additive="sum"/>
</img>

When there are multiple animations defined for a given attribute that overlap at any moment, the two either add together or one overrides the other. Animations overlap when are both either active or frozen at the same moment. The animations are prioritized according to when each begins. The animation first begun has lowest priority and the most recently begun animation has highest priority.

Higher priority animations that are not additive will override all earlier animations, and simply set the attribute value.  Animations that are additive apply (i.e. add to) to the result of the earlier-activated animations. For details on how animations are combined, see The Animation Sandwich Model.

While many animations of numerical attributes will be additive, this is not always the case. As an example of an animation that is defined to be non-additive, consider a hypothetical extension animation "mouseFollow" that causes an object to track the mouse. 

<img ...>
   <animateMotion dur=10s repeatDur=indefinite
           path="[some nice path]" />
   <mouseFollow begin="onmouseover" dur=5s
           additive="replace" fill="remove" />
</img>

The mouse-tracking animation runs for 5 seconds every time you mouse-over the image. It cannot be additive, or it will just offset the motion path in some odd way. The mouseFollow needs to override the animateMotion while it is active. When the mouseFollow completes, its effect is no longer applied and the animateMotion again controls the presentation value for position.

The additive behavior of an animation is controlled by the additive attribute:

additive = "replace | sum"

Controls whether or not the animation is additive. 
If "sum", the animation will add to the underlying value of the attribute and other lower priority animations.
If "replace", the animation will override the underlying value of the attribute and other lower priority animations. This is the default, however the behavior is also affected by the animation value attributes by and to, as described below. 

Additive animation is defined for numeric attributes and other data types for which some addition function is defined. This includes numeric attributes for concepts such as position, widths and heights, sizes, etc. This also includes color (refer to The animateColor element), and other data types as specified by the host language.

Some numeric attributes (e.g. a telephone number attribute) may not sensibly support addition - it is left to the host language to specify which attributes support additive animation. Attribute types such as strings and Booleans, for which addition is not defined, cannot support additive animation.

How from, to and by attributes affect additive behavior.

The attribute values to and by, used to describe the animation function, can override the additive attribute in certain cases:

• If by is used without from, the animation is defined to be additive (i.e. the equivalent of additive="sum").
• If to is used without from, (i.e. a "to animation") and if the attribute supports addition the animation is defined to be a hybrid of additive and non-additive. The underlying value is used as a starting point as with additive animation, however the ending value specified by the to attribute overrides the underlying value as though the animation was non-additive.

For the hybrid case of a "to-animation", the animation function f(t) is defined in terms of the underlying value, the specified to value, and the current value of t (i.e. time) relative to the simple duration d.

  vc   = current base value (at time t)
  ve   = defined "to" value
  f(t) = vc + ((ve - vc) * (t/d))

Note that if no other (lower priority) animations are active or frozen, this defines simple interpolation. However if another animation is manipulating the base value, the "to-animation" will add to the effect of the lower priority, but will dominate it as it nears the end of the simple duration, eventually overriding it completely. The value for F(t) when a "to-animation" is frozen (at the end of the simple duration) is just the to value. If a "to-animation" is frozen anywhere within the simple duration (e.g. using a repeatCount of "2.5"), the value for F(t) when the animation is frozen is the value computed for the end of the active duration. Even if other, lower priority animations are active while a "to-animation" is frozen, the value for F(t) does not change. 

For an example of additive "to-animation", consider the following two additive animations. The first, a "by-animation" applies a delta to attribute "x" from 0 to -10. The second, a "to-animation" animates to a final value of 10.

 <foo x="0" .../>
    <animate id="A1" attributeName="x" by="-10" dur="10s" fill="freeze" />
    <animate id="A2" attributeName="x" to="10"  dur="10s" fill="freeze" />
 </foo>

The presentation value for "x" in the example above, over the course of the 10 seconds is presented in Figure 3 below. These values are simply computed using the formula described above. Note that the value for F(t) is the presentation value for "x".

Figure 3:  Effect of Additive to-animation example

Additive and Cumulative animation

The "accumulate" attribute should not be confused with the  "additive" attribute. The "additive" attribute defines how an animation is combined with other animations and the base value of the attribute.  The "accumulate" attribute defines only how the animation function interacts with itself, across repeat iterations.

Typically, authors expect cumulative animations to be additive (as in the examples described for accumulate above), but this is not required. The following example is not additive.

<img ...>
   <animate dur="10s" repeatDur="indefinite"
            attributeName="top" from="20" by="10"
            additive="replace" accumulate="sum" />
</img>

The animation overrides whatever original value was set for "top", and begins at the value 20. It moves down by 10 pixels to 30, then repeats. It is cumulative, so the second iteration starts at 30 and moves down by another 10 to 40. Etc.

When a cumulative animation is also defined to be additive, both features function normally. The accumulated effect for F(t) is used as the value for the animation, and is added to the underlying value for the target attribute. Refer also to the Animation Sandwich Model.

3.3.6. Restarting Animations

When an animation is defined to begin at a simple offset (e.g. begin="5s" ), there is an unequivocal time when the element begins. However, if an animation is defined to begin relative to an event (e.g. begin="foo.onclick" ), the event can happen at any time, and moreover can happen more than once (e.g. if the user clicks on "foo" several times). In some cases, it is desirable to restart an animation if a second begin event is received. In other cases, an author may want to preclude this behavior. The restart attribute controls under which circumstances, if any, an animation is restarted:

restart

always

The animation can be restarted at any time. 
This is the default value.

never

The animation cannot be restarted for the remainder of the document duration.

whenNotActive

The animation can only be restarted when it is not active (i.e. after the active end). Attempts to restart the animation during its active duration are ignored.

Note that there are several ways that an animation may be restarted. The behavior (i.e. to restart or not) in all cases is controlled by the restart attribute. The different restart cases are:

• An animation with begin specified as an event-value can be restarted when the named event fires multiple times.
• An animation with begin specified as a syncbase value, where the syncbase element can restart. When an animation restarts, other animations defined to begin relative to the begin or end of the restarting animation will also restart (subject to the value of restart on these elements).
• An animation with begin specified as "indefinite" can be restarted when the DOM "beginElement()" method is called repeatedly.
• An animation with begin specified as "indefinite" can be restarted by repeatedly actuating a hyperlink that has the animation element as its target.

When an animation restarts, the primary semantic is that it behaves as though this were the first time the animation had begun, independent of any earlier behavior. The animation effect F(t) is defined independent of the restart behavior. Any effect of an animation playing earlier is no longer applied, and only the current animation effect F(t) is applied.

If an additive animation is restarted while it is active or frozen, the previous effect of the animation (i.e. before the restart) is no longer applied to the attribute. Note in particular that cumulative animation is defined only within the active duration of an animation. When an animation restarts, all accumulated context is discarded, and the animation effect F(t) begins accumulating again from the first iteration of the restarted active duration.

Also, if a simple duration had been defined with an end value, the computed simple duration is not carried over from the previous animation, but rather is recalculated. If the recalculated simple duration for a restarting element is less than 0 (i.e. because the specified end time occurs before the current begin time), then the specified end is ignored (this is the same as if the author specified a negative value for duration - the attribute is simply ignored).

The restart setting for an animation is evaluated not when the syncbase element restarts or when the eventbase event happens, but rather when the animation element would actually restart (i.e. taking into account any offset from the syncbase or eventbase). For example:

<img ...>
   <animate id="foo" begin="onclick" ..." />
   <animate id="bar" begin="foo.begin+2s" dur="10s" 
       restart="whenNotActive" ..." />
</img>

If the user clicks on the image at 5 seconds, animation "foo" will begin, and animation "bar" will be scheduled to begin at 7 seconds. If the user clicks the image again at 6 seconds, "foo" would restart. The effective restart of "bar" is scheduled for 2 seconds later, at 8 seconds. However, since bar will begin playing at 7 seconds, the restart at 8 seconds will be ignored (the restart attribute is set to only allow restart when "bar" is not active). Animation "bar" plays from 7 seconds until 17 seconds. If the user again clicks the image at 16 seconds, "foo" will restart. Although "bar" is active when the user clicks the image, the restart for "bar" is not scheduled until 2 seconds later at 18 seconds. At this point, "bar" will have ended the first time, and so can legally restart. 

The same rules apply if an element is defined to begin when another ends, as in this example:

<img ...>
   <animate id="foo" begin="onclick" dur="2s" ..." />
   <animate id="bar" begin="foo.end" dur="10s" 
       restart="whenNotActive" ..." />
</img>

If the user clicks on the image once at 5 seconds, "foo" will play from 5 to 7 seconds, and "bar" will play from 7 to 17 seconds. If the user clicks again at 16 seconds, "foo" will restart and play again from 16 to 18 seconds. At 18 seconds, "bar" will have ended, and so will restart and play from 18 to 28 seconds.

Note that using restart can also allow the author to define a single UI event to both begin and end and element, as follows:

<img ...>
   <animate id="foo" begin="onclick" dur="2s"
       repeatDur="indefinite" endActive="onclick"
       restart="whenNotActive" ..." />
</img>

If "foo" were defined with the default restart behavior "always", a second click on the image would simply restart the animation. However, since the second click cannot restart the animation when restart is set to "whenNotActive", the click will just end the active duration and stop the animation. This is sometimes described as "toggle" activation.

3.4. Handling Syntax Errors

The specific error handling mechanisms for each attribute are described with the individual syntax descriptions.  However, some of these specifications describe the behavior of an animation with syntax errors as "having no effect".  This means that the animation will continue to behave normally with respect to timing, but will not manipulate any presentation value, and so will have no visible impact upon the presentation. 

In particular, this means that if other animation elements are defined to begin or end relative to an animation that "has no effect", the other animation elements will begin and end as though there were no syntax errors. The presentation runtime may indicate an error, but should not halt presentation or animation of the document. Authoring environments may choose to be more intrusive when errors are detected.

3.5. The Animation Sandwich Model

When an animation is running, it does not actually change the attribute values in the DOM.  The animation runtime must maintain a presentation value for any target attribute, separate from the DOM or CSS OM. The presentation value is reflected in the display form of the document. The effect of animations is to manipulate this presentation value, and not to affect the underlying DOM or CSS OM values.

The remainder of this discussion uses the generic term DOM for both [DOM-Level-1] as well as the CSS-OM or other defined attributeType languages. If an implementation does not support an object model, it must maintain the original value as defined by the document as well as the presentation value; for the purposes of this section, we will consider this original value to be equivalent to the value in the DOM. The concepts described apply to all attributeType languages and the associated object model interfaces.

The model accounting for the DOM and concurrently active or frozen animations for a given attribute is described as a "sandwich", an analogy to the layers of meat and cheeses in a "submarine sandwich". On the bottom of the sandwich is the base value taken from the DOM. Each active (or frozen) animation is a layer above this. The layers (i.e. the animations) are placed on the sandwich in order according to priority, with higher priority animations placed above lower priority animations.

Animations are prioritized according to when each begins. The animation first begun has lowest priority and the most recently begun animation has highest priority. When two animations start at the same moment in time, the element that appears first in the document has lower priority.

Note that if an animation is restarted (see also Restarting Animations), it will always move to the top of the priority list, as it becomes the most recently activated animation. That is, when an animation restarts, its layer is pulled out of the sandwich, and added back on the very top.  Note also that when an element repeats, the priority is not affected (repeat behavior is not defined as restarting).

Each additive animation adds its effect to the result of all sandwich layers below. A non-additive animation simply overrides the result of all lower sandwich layers. The end result at the top of the sandwich is the presentation value that must be reflected in the document view.

CSS defines the terms "specified", "computed" and "actual" to describe the results of evaluating the syntax, the cascade and the presentation rendering. When animation is applied to CSS attributes (properties), the "DOM" value is defined to mean the "computed value" for the associated property. Animation can add to or override the "computed value" value, and the result must be reflected in the presentation. The animation effect can be thought of as applying after the "computed value" but before the "actual value". This means that the effect of animation overrides all stylesheet rules.  However, the animation effect may have side-effects upon the document layout.  See also the [CSS2] specification (the terms are defined in section 6.1).

Some attributes that support additive animation have a defined legal range for values (e.g. an opacity attribute may allow values between 0 and 1). In some cases, an animation function may yield out of range values. It is up to the implementation to clamp the results at the top of the animation stack to the legal range before applying them to the presentation value. However, the effect of all the animations in the stack should be combined, before any clamping is performed. Although individual animation functions may yield out of range values, the combination of additive animations in the animation stack may still be legal. Clamping only the final result and not the effect of the individual animation functions provides support for these cases.

Initially, before any animations for a given attribute are active, the presentation value will be identical to the original value specified in the document (the DOM value).

When all animations for a given attribute have completed and the associated animation effects are no longer applied, the presentation value will again be equal to the DOM value. Note that if any animation is defined with fill="freeze", the effect of the animation will be applied as long as the document is displayed, and so the presentation value will reflect the animation effect until the document end. Refer also to the section "Freezing Animations".

Some animations (e.g. animateMotion) will implicitly target an attribute, or possibly several attributes (e.g. the "posX" and "posY" attributes of some layout model). These animations must be placed in the respective animation stack for each attribute that is affected. Thus, e.g. an animateMotion animation may be in more than one animation stack (depending upon the layout model of the host language). For animation elements that implicitly target attributes, the host language designer must specify what attributes are implicitly targeted, and the runtime must maintain the animation stacks accordingly. 

Note that any queries (via DOM interfaces) on the target attribute will reflect the DOM value, and will not reflect the effect of animations. Note also that the DOM value may still be changed via the DOM interfaces (e.g. using script). While it may be useful or desired to provide access to the final presentation value after all animation effects have been applied, such an interface is not provided as part of SMIL Animation. A future version may address this.

Although animation does not manipulate the DOM values, the document display must reflect changes to the DOM values. Host languages can support script languages that can manipulate attribute values directly in the DOM. If an animation is active or frozen while a change to the DOM value is made, the behavior is dependent upon whether the animation is defined to be additive or not, as follows: (see also the section Additive Animation). 

• If only additive animations are active or frozen (i.e. no non-additive animations are active or frozen for the given attribute) when the DOM value is changed, the presentation value must reflect the changed DOM value as well as the effect of the additive animations. When the animations complete and the effect of each is no longer applied, the presentation value will be equal to the changed DOM value.
  
• If any non-additive animation is running when the DOM value is changed, the presentation value will not reflect the changed DOM value, but will only reflect the effect of the highest priority non-additive animation, and any still higher priority additive animations. When all non-additive animations complete and the effect of each is no longer applied, the presentation value will reflect the changed DOM value and the effect of any additive animations that are active or frozen.

3.6. State Transition Model

At any moment in time, an animation is in exactly one of the following states: idle, active, finished or frozen. The state transitions are caused by events called start, restart, freeze and stop. Figure 4 shows the legal transitions between the states of an animation:

Figure 4: State diagram of an animation

The following sections explain the semantics of the states and transitions of an animation, and explain how to define the transitions using attributes of the animation element.

Initial State: Idle

When the document that contains an animation element is first presented, the animation is created in the idle state. This is the common starting state for all animation elements. 

In the idle state an animation is inactive and does not affect the presentation of the document in any way. The animation simply waits for the time or event specified in its begin attribute. Note that the animation may transition immediately to the active state if the value of the begin attribute is zero (the default).

Start Transition: Idle to Active

An animation in the idle state transitions to the active state when the condition specified in the begin attribute becomes true. As described in the section on the begin attribute, this condition may depend upon one of several factors:

• reaching a particular time in the presentation.
• another animation element reaching a particular point in its active duration.
• the occurrence of an asynchronous event, such as a mouse click.

Additionally, an animation element may be started by a DOM beginElement()method call, or as the result of being the target of an activated hyperlink.

Active State:

In the active state, an animation performs the transformation of its specified presentation values. The active state includes the entire active duration of the animation. The active duration of an animation element is specified by the interaction between the dur, end, endActive, repeatDur, and repeatCount attributes as detailed in the sections above describing those attributes.

Freeze Transition: Active to Frozen

If an animation has the fill attribute set to freeze, upon reaching the end of its active duration, the animation will transition to the frozen state. 

Frozen State:

In the frozen state the animation will continue to apply its final transformation of the specified presentation values for the remainder of the document presentation time unless restarted.

Stop Transition: Active to Finished

If an animation has the fill attribute set to remove (the default), upon reaching the end of its active duration, the animation will transition to the finished state.

Finished State:

In the finished state the animation will no longer affect the presentation of the document, unless restarted.

Restart Transition: Frozen to Active

The ability of an animation element to make this transition depends upon the value of the restart attribute. If the restart attribute value is always or whenNotActive the animation element will transition to the active state in response to a DOM beginElement()method call or a hyperlink activation. The restart transition effectively resets the state of the animation element; the element's simple and active duration must be recomputed as if it were being started for the first time.

Restart Transition: Active to Active

An animation element may receive a beginElement() DOM call or be the target of a hyperlink activation while in the active state. In this case, if the value of the restart attribute is always the animation element will re-transition to the active state and restart as described above. Any other value for the restart attribute will prevent this transition from occurring. 

Restart Transition: Finished to Active

An animation element restart can result from a DOM call or a hyperlink activation, subject to the restrictions imposed by the restart attribute. When in the finished state, an animation element may re-transition to the active state if the value of the restart attribute is always or whenNotActive. Any other value for the restart attribute will prevent this transition from occurring.

3.7. Timing Model Details

3.7.1. Timing and real-world clock times

Throughout this specification, animation is described as a function of "time". In particular, the animation function is described as producing a value for any "time" in the range of the simple duration. However, the simple duration can be repeated, and the animation can begin and restart in many ways.  As such, there is no direct relationship between the "time" that an animation function uses, and the real world concept of time as reflected on a clock.

When a keySplines attribute is used to adjust the pacing between values in an animation, the semantics can be thought of as changing the pace of time in the given interval. An equivalent model is that keySplines simply changes the pace at which interpolation progresses through the given interval. The two interpretations are equivalent mathematically, and the significant point is that the notion of "time" as defined for the animation function f(t) should not be construed as real world clock time. For the purposes of animation, "time" can behave quite differently from real world clock time.

3.7.2. Interval Timing

SMIL Animation assumes the most common model for interval timing. This describes intervals of time (i.e. durations) in which the begin time of the interval is included in the interval, but the end time is excluded from the interval. This is also referred to as "end-point exclusive" timing. This model makes arithmetic for intervals work correctly, and provides sensible models for sequences of intervals.

Background Rationale

In the real world, this is equivalent to the way that seconds add up to minutes, and minutes add up to hours.  Although a minute is described as 60 seconds, a digital clock never shows more than 59 seconds. Adding one more second to "00:59" does not yield "00:60" but rather "01:00", or 1 minute and 0 seconds. The theoretical end time of 60 seconds that describes a minute interval is excluded from the actual interval.

In the world of media and timelines, the same applies: Let a be a video, a clip of audio, or an animation. Assume "A" begins at 10 and runs until 15 (in any units - it does not matter). If "B" is defined to follow "A", then it begins at 15 (and not at 15 plus some minimum interval). When a runtime actually renders out frames (or samples for audio), and must render the time "15", it should not show both a frame of "A" and a frame of "B", but rather should only show the new element "B". This is the same for audio, or for any interval on a timeline. If the model does not use endpoint-exclusive timing, it will draw overlapping frames, or have overlapping samples of audio, of sequenced animations, etc.

Note that transitions from "A" to "B" also adhere to the interval timing model. They do require that "A" not actually end at 15, and that both elements actually overlap. Nevertheless, the "A" duration is simply extended by the transition duration (e.g. 1 second). This new duration for "A" is also endpoint exclusive - at the end of this new duration, the transition will be complete, and only "B" should be rendered - "A" is no longer needed.

Implications for Animation

For animation, several results of this are important: the definition of repeat, and the value sampled during the "frozen" state.

When repeating an animation, the arithmetic follows the end-point exclusive model. Consider the example:

  <animation dur="4s" repeatCount="4" .../>

At time 0, the simple duration is sampled at 0, and the first value is applied.  This is the inclusive begin of the interval. The simple duration is sampled normally up to 4 seconds. However, the appropriate way to map time on the active duration to time on the simple duration is to use the remainder of division by the simple duration:

  simpleTime = REMAINDER( activeTime, d ) 

or

  F(t) = f( REMAINDER( t, d ) )  where t is within the active duration

Note: REMAINDER( t, d ) is defined as t - d*floor(t/d)

Using this, a time of 4 (or 8 or 12) maps to the time of 0 on the simple duration. The endpoint of the simple duration is excluded from (i.e. not actually sampled on) the simple duration.

This implies that the last value of an animation function f(t) may never actually be applied (e.g. for a linear interpolation).  In the case of an animation that does not repeat and does not specify fill="freeze", this may in fact be the case. However, in the following example, the appropriate value for the frozen state is clearly the "to" value:

  <animation from="0" to="5" dur="4s" fill=freeze .../>

This does not break the interval timing model, but does require an additional qualification for the animation function F(t) while in the frozen state:

• If the active duration is an even multiple of the simple duration, the value to apply in the frozen state is the last value defined for the animation function f(t).

The definition of accumulate also aligns to this model. The arithmetic is effectively inverted and values accumulate by adding in a multiple of the last value defined for the animation function f(t).

3.7.3. Unifying Interactive and Scheduled Timing

SMIL Animation describes extensions to SMIL 1.0 to support interactive timing of animation elements. These extensions allow the author to specify that an animation should begin or end in response to an event (such as a user-input event like "click"), or to a hyperlink activation, or to a DOM method call.

The syntax to describe this uses event-value specifications and the special argument value "indefinite" for the begin and endActive attribute values. Event values describe user interface and other events. DOM method calls to begin or end an animation require that the associated attribute use the special value "indefinite". A hyperlink can also be targeted at an animation element that specifies begin="indefinite". The animation will begin when the hyperlink is activated (usually by the user clicking on the anchor). It is not possible to control the active end of an animation using hyperlinks.

Background

The current model represents an evolution from earlier multimedia runtimes. These were typically either pure, static schedulers or pure event-based systems.  Scheduler models present a linear timeline that integrates both discrete and continuous media.   Scheduler models tend to be good for storytelling, but have limited support for user-interaction. Event-based systems, on the other hand, model multimedia as a graph of event bindings.  Event-based systems provide flexible support for user-interaction, but generally have poor scheduling facilities; they are best applied to highly interactive and experiential multimedia.

The SMIL 1.0 model is primarily a scheduling model, but with some flexibility to support continuous media with unknown duration. User interaction is supported in the form of timed hyperlinking semantics, but there was no support for activating individual elements via interaction.

Modeling interactive, event-based content in SMIL

To integrate interactive content into SMIL timing, the SMIL 1.0 scheduler model is extended to support several new concepts: indeterminate timing, and activation of the element.

With indeterminate timing, an element has an undefined begin or end time.  The element still exists within the constraints of the document, but the begin or end time is determined by some external activation. Activation may be event-based (such as by a user-input event), hyperlink based (with a hyperlink targeted at the element), or DOM based (by a call to the beginElement() method).  From a scheduling perspective, the time can be thought of as unresolved. 

The event-activation support provides a means of associating an event with the begin or end time for an element.  When the event is raised (e.g. when the user clicks on something), the associated time is resolved to a determinate time.  For event-based begin times, the element becomes active (begins to play) at the time that the event is raised. The element plays from the beginning of the media (subject to any explicit clipBegin).  For event-based end times, the element becomes inactive (stops playing) when the associated event is raised.

Note that an event based endActive will not be activated until the element has already begun. Any specified endActive event is ignored before the element begins.

Related to event-activation is link-activation.  Hyperlinking has defined semantics in SMIL 1.0 to seek a document to a point in time. When combined with indeterminate timing, hyperlinking yields a variant on interactive content. A hyperlink can be targeted at an element that does not have a scheduled begin time. When the link is traversed, the element begins. The details of when hyperlinks activate an element, and when they seek the document timeline are presented in the next section.

3.7.4. Hyperlinks and Timing

Hyperlinking semantics must be specifically defined for animation in order to ensure predictable behavior. Earlier hyperlinking semantics, such as those defined by SMIL 1.0 are insufficient because they do not handle indeterminate and interactive timing, nor do they handle author-time restart restrictions. Here we extend SMIL 1.0 semantics for use in presentations using animations having indeterminate timing, interactive timing, and author-time restart restrictions.

A hyperlink may be targeted at an animation element by specifying the value of the id attribute of an animation element in the fragment part of the link locator. Traversing a hyperlink that refers to an animation will affect the presentation in one of three ways, depending upon the value of the animation element's begin attribute and the current resolution status of the element's begin time:

• For animations where the value of the begin attribute is equal to "indefinite", the animation will simply be started when a link targeted at the element is traversed. In this case the semantics of the restart attribute will govern the behavior of the animation element if subsequent hyperlink traversals occur.
• Animations where the value of the begin attribute is not equal to "indefinite", and the begin time has been previously resolved will seek the presentation to that resolved time and continue normally from that point. In this case the semantics of the restart attribute will not apply to the activation of the hyperlink.
• Animations where the value of the begin attribute is not equal to "indefinite", and the begin time is unresolved will not seek the document timeline and will have no effect upon the referenced element. This should not be considered an error, and should not affect other language-defined link behavior.

If a seek of the presentation time is required, it may be necessary to seek either forward or backward, depending upon the resolved begin time of the element and the presentation current time at the moment of hyperlink traversal. After seeking a document forward, the document should be in the same state as if the user had allowed the presentation to run normally from the current time until reaching the animation element begin time (but had otherwise not interacted with the document). In particular, seeking the presentation time forward should also cause any other animation elements that have resolved begin times between the current time and the seeked-to time to begin. These elements may have ended, or may still be active or frozen at the seeked-to time, depending upon their begin times and active durations. Also any animation elements currently active at the time of hyperlinking should "fast-forward" over the seek interval. These may end or may be still active or frozen the seek is complete, depending upon their active durations. The net effect is that seeking forward to a presentation time puts the document into a state identical to that as if the document presentation time advanced undisturbed to reach the seek time.

If the resolved activation time for an animation element that is the target of a hyperlink traversal occurs in the past, the presentation time must seek backwards. Seeking backwards will rewind any animations active during the seek interval and will turn off any animations that are resolved to begin at a time after the seeked-to time. Note that resolved begin times (e.g. a begin associated with an event) are not cleared or lost by seeking to an earlier time. Subject to the rules above for hyperlinks that target animation elements, hyperlinking to elements with resolved begin times will function normally, advancing the presentation time forward to the previously resolved time.

These hyperlinking semantics assume that a record is kept of the resolved begin time for all animation elements, and this record is available to be used for determining the correct presentation time to seek to. Once resolved, begin times are not cleared. However, they can be overwritten by subsequent resolutions driven by multiple occurrences of an event (i.e. by restarting). For example: 

<animate id="A" begin="10s" .../>
<animate id="B" begin="A.begin+5s" .../>
<animate id="C" begin="onClick" .../>
<animate id="D" begin="C.begin+5s" .../>
...
<a href="#D">Click here!</a>

The begin time of elements "A" and "B" can be immediately resolved to be at 10 and 15 seconds respectively. The begin of elements "C" and "D" are unresolved when the document starts. Therefore activating the hyperlink will have no effect upon the presentation time or upon elements "C" and "D". Now, assume that "C" is clicked at 25 seconds into the presentation. The click on "C" in turn resolves "D" to begin at 30 seconds. From this point on, traversing the hyperlink will cause the presentation time to be seeked to 30 seconds.

If at 60 seconds into the presentation, the user again clicks on "C", "D" will become re-resolved to a presentation time of 65 seconds. Subsequent activation of the hyperlink will result in the seeking the presentation to 65 seconds.

3.7.5. Propagating Changes to Times

There are several cases in which times may change as the document is presented. In particular, when an animation time is defined relative to an event, the time (i.e. the animation begin or end) is resolved when the event occurs. Another case arises with restart behavior - both the begin and end time of an animation can change when it restarts. Since the begin and end times of one animation can be defined relative to the begin or end of other animations, any changes to times must be propagated throughout the document.

When an animation "foo" has a begin or end time that specifies a syncbase element (e.g. "bar" as below):

<animate id="foo" begin="bar.end" .../>

we say that "foo" is a time-dependent of "bar" - that is, the "foo" begin time depends upon the end of "bar". Any changes to the end time of "bar" must be propagated to the begin of "foo". The effect of the changes depends upon the state of "foo" when the change happens. The rest of the section describes the specific rules for propagating changes.

Propagating to repeating animations

When a repeating animation begins, the simple duration may be indefinite. However, the simple duration may become resolved after the animation begins. If an element is defined to repeat, and the simple duration is defined by end, the end is only used for the first repeat iteration. Once the simple duration is resolved, the simple duration d is used for all successive iterations, and the end value is effectively ignored. For example:

<rect>
   <animate id="foo" endActive="onclick" .../>
   <animate id="bar" end="foo.end" repeatCount="5"
          from="5" to="10" .../>
</rect>

If the user clicks on the rectangle after 5 seconds, the simple duration of "bar" is resolved to 5 seconds. During the first iteration, the simple duration of "bar" was indefinite, and so the animation function f(t) is defined to use f(0), the from value "5". The "bar" animation will then repeat the simple duration another 4 times, using a simple duration of 5 seconds and interpolating the value from "5" to "10".

Note that it is possible for the syncbase element "foo" to end again, if it is restarted. When "foo" restarts, the a new end time is calculated and all time dependents are notified of the change.  If a time dependent like "bar" is repeating (i.e. it is on the second or later iteration), the changed end time is ignored. This is similar to the following example:

  <animate id="foo" begin="onclick" dur="5s" .../> 
  <animate id="bar" begin="0" end="foo.end" .../> 

Animation "bar" will end when "foo" ends, however "foo" can restart on another click. When "foo" restarts, a new end is calculated, and "bar" is notified. However, as "bar" will not restart, the change is ignored. A variant on this illustrates a case when the time change does propagate through:

  <animate id="foo" begin="onclick" dur="5s" .../> 
  <animate id="bar" begin="0" end="foo.end+10s"  .../> 

Animation "bar" will end 10 seconds after "foo" ends. If "foo" is restarted within 10 seconds of when it first ended, "bar" will still be active, and the changed end time will propagate through.  Using example times, if the user clicks on the parent element 8 seconds after the document begins, "foo" begins at 8 seconds and will end at 13 seconds. Animation "bar" would then end at 23 seconds.  If the users clicks the parent again 3 seconds after "foo" ends, (i.e. at 16 seconds), the end of "foo" now has the value of 21 seconds. This change propagates to "bar", and "pushes out" the end of "bar" until 31 seconds. 

The rule is that once an element has ended, changes that affect its end time are ignored. Similarly, once a repeating element has completed the first simple duration (i.e. the first repeat iteration), changes to the end are ignored.

When an element restarts, the simple duration is recalculated, and may again become indefinite. For example:

  <animate id="foo" begin="onclick" end="onblur" .../> 
  <animate id="bar" begin="onclick" end="foo.end" 
      repeatDur="indefinite" .../> 

Both elements will start when the element is first clicked. Element "foo" will end when "onblur" is raised on the target element. At this point, the simple duration of "bar" will become defined (resolved), and "bar" will begin to repeat with this duration. If the user clicks on the target element again, both animations will restart, and "bar" will once again have an indefinite simple duration. 

(Aaron: also point out the the recalculation of the end time also implies recalculation of the  simple duration and therefore the behavior of animations can change while they are running.)

3.8. Common Syntax DTD Definitions

Timing Attributes

<!ENTITY % timingAttrs
  begin          CDATA  #IMPLIED 
  end            CDATA  #IMPLIED
  dur            CDATA  #IMPLIED
  endActive      CDATA  #IMPLIED
  restart        (always | never | 
                   whenNotActive)  "always"
  repeatCount    CDATA  #IMPLIED 
  repeatDur      CDATA  #IMPLIED
  fill           (remove | freeze) "remove"
>

Animation Attributes

<!ENTITY % animAttrs
  attributeName  CDATA  #REQUIRED
  attributeType  CDATA  #IMPLIED
  additive       (replace | sum) "replace"
  accumulate     (none | sum) "none"
>

<!ENTITY % animTargetAttr
  targetElement  IDREF  #IMPLIED
>

<!ENTITY % animLinkAttrs
  type     (simple|extended|locator|arc) #FIXED "simple"
  show     (new|embed|replace) #FIXED 'embed'
  actuate  (user|auto) #FIXED 'auto'
  href     CDATA  #IMPLIED
>

4. Animation elements

4.1. The animate element

The <animate> element introduces a generic attribute animation that requires little or no semantic understanding of the attribute being animated.  It can animate numeric scalars as well as numeric vectors. It can also animate discrete sets of non-numeric attributes. The <animate> element is an empty element - it cannot have child elements.

This element supports from/to/by and values descriptions for the animation function, as well as all of the calculation modes. It supports all the described timing attributes. These are all described in respective sections above.

<!ELEMENT animate EMPTY>
<!ATTLIST animate
  %timingAttrs
  %animAttrs
  id             ID     #IMPLIED 
  calcMode       (discrete | linear | paced | spline ) "linear"
  values         CDATA  #IMPLIED
  keyTimes       CDATA  #IMPLIED
  keySplines     CDATA  #IMPLIED
  from           CDATA  #IMPLIED
  to             CDATA  #IMPLIED
  by             CDATA  #IMPLIED
>

Examples

The following defines the linear animation of a bitmap. The bitmap appears at the top of the region, moves 100 pixels down over 10 seconds, and disappears.

<img ...>
   <animate attributeName="top" from="0" to="100" dur="10s"/>
</img>

4.2. The set element

The <set> element provides a simple means of just setting the value of an attribute for a specified duration. As with all animation elements, this only manipulates the presentation value, and when the animation completes, the effect is no longer applied. That is, set does not permanently set the value of the attribute. 

The set element supports all attribute types, including those that cannot reasonably by interpolated and that more sensibly support semantics of simply setting a value (e.g. strings and Boolean values). The set element is non-additive. The additive and accumulate attributes are not allowed.

This supports the basic set of timing attributes to specify the simple duration, but the repeatCount and repeatDur attributes are not allowed (repeat is not meaningful for set). Note that using fill="freeze" will have the same effect as setting dur="indefinite" (if endActive is not specified).

The <set> element supports a more restricted set of attributes than the  <animate> element:

<!ELEMENT set EMPTY>
<!ATTLIST set
  id             ID     #IMPLIED 
  begin          CDATA  #IMPLIED 
  end            CDATA  #IMPLIED
  dur            CDATA  #IMPLIED
  endActive      CDATA  #IMPLIED
  restart        (always | never | 
                   whenNotActive)  "always"
  fill           (remove | freeze) "remove"
  attributeName  CDATA  #REQUIRED
  attributeType  CDATA  #IMPLIED
  to             CDATA  #IMPLIED
>

to = "<value>"

Specifies the value for the attribute during the duration of the <set> element. The argument value must match the attribute type. 

@@Examples!!

4.3. The animateMotion element

In order to abstract the notion of motion paths across a variety of layout mechanisms, we introduce the <animateMotion> element. This describes motion in the abstract - the host language defines the layout model and must specify the precise semantics of motion.  

All values must be x, y value pairs. Each x and y value may specify any units supported for element positioning by the host language. The host language defines the default units. In addition, the host language defines the reference point for positioning an element. This is the point within the element that is aligned to the position described by the motion animation. The reference point defaults in some languages to the upper left corner of the element bounding box; in other languages (such as SVG) the reference point may be specified for the element.

The attributeName and attributeType attributes are not used with animateMotion, as the manipulated position attribute(s) are defined by the host language. If the position is exposed as an attribute or attributes that can also be animated (e.g. as "top" and "left", or "posX" and "posY"), implementations must combine <animateMotion> animations into the respective stacks with other animations that manipulate individual position attributes. See also the section The Animation Stack Model.

All values must be x, y value pairs. Each x and y value may specify any units supported for element positioning by the host language. The host language defines the default units. In addition, the host language defines the reference point for positioning an element. This is the point within the element that is aligned to the position described by the motion animation. The reference point defaults in some languages to the upper left corner of the element bounding box; in other languages (such as SVG) the reference point may be specified for the element.

The <animateMotion> element adds an additional syntax alternative for specifying the animation, the "path" attribute. This allows the description of a path using a subset of the SVG path syntax. Note that if a path is specified, it will override any specified values for values or from/to/by attributes. 

The default calculation mode (calcMode) for animationMotion is "paced". This will produce constant velocity motion along the specified path. Note that while animateMotion elements can be additive, authors should note that the addition of two or more "paced" (constant velocity) animations may not result in a combined motion animation with constant velocity.

<!ELEMENT animateMotion EMPTY>
<!ATTLIST animateMotion
  %timingAttrs
  id             ID     #IMPLIED 
  additive       (replace | sum) "replace"
  accumulate     (none | sum) "none"
  calcMode       (discrete | linear | paced | spline) "paced"
  values         CDATA  #IMPLIED
  from           CDATA  #IMPLIED
  to             CDATA  #IMPLIED
  by             CDATA  #IMPLIED
  keyTimes       CDATA  #IMPLIED
  keySplines     CDATA  #IMPLIED
  path           CDATA  #IMPLIED
  origin         (default) "default"
/>

path = "<path-description>"

Specifies the curve that describes the attribute value as a function of time. The supported syntax is a subset of the SVG path syntax. Support includes commands to describes lines ("MmLlHhVvZz") and Bezier curves ("Cc"). For details refer to the path specification in SVG [SVG]. 
Note that SVG provides two forms of path commands - "absolute" and "relative". These terms may appear to be related to the definition of additive animation and the "origin" attribute, however they should not be confused. The terms "absolute" and "relative" apply only to the definition of the path itself, and not to the operation of the animation. The "relative" commands define a path point relative to the previously specified point. The terms "absolute" and "relative" are unrelated to the definitions of both "additive" animation or the specification of the "origin".

• If the "absolute" commands ("MLHVZC") are used with non-additive animation specifying "origin=parent", then the values specify the position in the layout container. 
• If the "absolute" commands are used with additive animation or with "origin=layout", then the values specify the position as a relative offset from the current or original position, respectively. 
• If the "relative" commands ("mlhvzc") are used, they simply define the point as an offset from the previous point on the path. This does not affect the definition of "additive" or "origin" for the animateMotion element.

Move To commands - "M <x> <y>" or "m <dx> <dy>"

Start a new sub-path at the given (x,y) coordinate. If a moveto is followed by multiple pairs of coordinates, the subsequent pairs are treated as implicit lineto commands

Line To commands - "L <x> <y>" or "l <dx> <dy>"

Draw a line from the current point to the given (x,y) coordinate which becomes the new current point. A number of coordinates pairs may be specified to draw a polyline.

Horizontal Line To commands - "H <x>" or "h <dx>"

Draws a horizontal line from the current point (cpx, cpy) to (x, cpy). Multiple x values can be provided (although usually this doesn't make sense).

Vertical Line To commands - "V <y>" or "v <dy>"

Draws a vertical line from the current point (cpx, cpy) to (cpx, y). Multiple y values can be provided (although usually this doesn't make sense).

Closepath commands - "Z" or "z"

The "closepath" causes an automatic straight line to be drawn from the current point to the initial point of the current subpath.

Cubic bezier Curve To commands - 
  "C <x1> <y1> <x2> <y3> <x> <y>" or 
  "c <dx1> <dy1> <dx2> <dy2> <dx> <dy>"

Draws a cubic bezier curve from the current point to (x,y) using (x1,y1) as the control point at the beginning of the curve and (x2,y2) as the control point at the end of the curve. Multiple sets of coordinates may be specified to draw a polybezier.

When a path is combined with "linear" or "spline" calcMode settings, the number of values is defined to be the number of points defined by the path, unless there are "move to" commands within the path.  A "move to" command within the path (i.e. other than at the beginning of the path description) does not count as an additional point for the purpose of keyTimes and spline, and should not define an additional "segment" for the purposes of timing or interpolation. When a path is combined with a "paced" calcMode setting, all "move to" commands are considered to have 0 length (i.e. they always happen instantaneously), and should not be considered in computing the pacing.

calcMode 

Defined as above in Animation Function Calculation Modes, but note that the default calcMode for animateMotion is "paced". This will produce constant velocity motion across the path.
The use of "discrete" for the calcMode together with a "path" specification is allowed, but is generally not useful (it will simply jump the target element from point to point).
The use of "linear" for the calcMode with more than 2 points described in "values", "path" or "keyTimes" may result in motion with varying velocity. The "linear" calcMode specifies that time is evenly divided among the segments defined by the "values" or "path" (note: any "keyTimes" list defines the same number of segments). The use of "linear" does not specify that time is divided evenly according to the distance described by each segment. 
For motion with constant velocity, calcMode should be set to "paced".
For complete velocity control, calcMode can be set to "spline" and the author can specify a velocity control spline with "keyTimes" and "keySplines".

origin = "default"

Specifies the origin of motion for the animation. The values and semantics of this attribute are dependent upon the layout and positioning model of the host language. In some languages, there may be only one option (i.e. "default"). However, in CSS positioning for example, it is possible to specify a motion path relative to the container block, or to the layout position of the element. It is often useful to describe motion relative to the position of the element as it is laid out (e.g. from off screen left to the layout position, specified as from="(-100, 0)" and to="(0, 0)". Authors must be able to describe motion both in this manner, as well as relative to the container block. The origin attribute supports this distinction. Nevertheless, because the host language defines the layout model, the host language must also specify the "default" behavior, as well as any additional attribute values that are supported.
Note that the definition of the layout model in the host language specifies whether containers have bounds, and the behavior when an element is moved outside the bounds of the layout container. In CSS2 [CSS2], for example, this can be controlled with the "clip" property.
Note that for additive animation, the "origin" distinction is not meaningful.  This attribute only applies when additive is set to "replace".

@@Examples!!

4.4. The animateColor element

The <animateColor> element specifies an animation of a color attribute. The host language must specify those attributes that describe color values, and that can support color animation. 

All values must represent sRGB color values. Legal value syntax for attribute values is defined by the host language. 

Interpolation is defined on a per-color-channel basis.

<!ELEMENT animateColor EMPTY>
<!ATTLIST animateColor
  %animAttrs
  %timingAttrs
  id             ID     #IMPLIED 
  calcMode       (discrete | linear | paced | spline ) "linear"
  values         CDATA  #IMPLIED
  from           CDATA  #IMPLIED
  to             CDATA  #IMPLIED
  by             CDATA  #IMPLIED
  keyTimes       CDATA  #IMPLIED
  keySplines     CDATA  #IMPLIED
>

The values in the from/to/by and values attributes may specify negative and out of gamut values for colors.  The function defined by an individual animateColor may yield negative or out of gamut values.  The implementation must correct the resulting presentation value, to be legal for the destination (display) colorspace. However, as described in the Animation Stack Model, the implementation should only correct the final result of all animations for a given attribute, and should not correct the effect of individual animations.

Values are corrected by "clamping" the values to the correct range. Values less than the minimum allowed value are clamped to the minimum value (commonly 0, but not necessarily so for some color profiles). Values greater than the defined maximum are clamped to the maximum value (defined by the attributeType domain) .

Note that color values are corrected by clamping them to the gamut of the destination (display) colorspace. Some implementations may be unable to process values which are outside the source (sRGB) colorspace and must thus perform clamping to the source colorspace, then convert to the destination colorspace and clamp to its gamut. The point is to distinguish between the source and destination gamuts; to clamp as late as possible, and to realize that some devices, such as inkjet printers which appear to be RGB devices, have non-cubical gamuts.

Note to implementers: When animateColor is specified as a "to animation", the animation function should assume Euclidean RGB-cube distance where deltas must be computed. See also Specifying Function Values and How from, to and by attributes affect additive behavior. Similarly, when the calcMode attribute for animateColor is set to "paced", the animation function should assume Euclidean RGB-cube distance to compute the distance and pacing.

5. Integrating SMIL Animation into a host language

@@@We may also want to talk about ways to do an integration  spec - e.g. do not copy all the semantics from this, but refer to this spec.  The SVG spec is a learning example...

This section describes what a language designer must actually do to specify the integration of SMIL Animation into a host language. This includes basic definitions, constraints upon animation, and allowed/supported events.

5.1. Required host language definitions

The host language designer must define some basic concepts in the context of the particular host language.  These provide the basis for timing and presentation semantics.

The host language designer must define what "presenting a document" means. A typical example is that the document is displayed on a screen.

The host language designer must define the document begin. Possible definitions are that the document begins when the complete document has been received by a client over a network, or that the document begins when certain document parts have been received.

The host language designer must define the document end. This is typically when the associated application exits or switches context to another document.

5.2. Constraints on Animation Targets

Specifying the target element

The host language designer must choose whether to support the targetElement attribute, or the XLink attributes for specifying the target element. Note that if the XLink syntax is used, the host language designer must decide how to denote the XLink namespace for the associated attributes. The namespace can be fixed in a DTD, or the language designer can require colonized attribute names to denote the XLink namespace for the attributes. The required XLink attributes have fixed values, and so may also be specified in a DTD, or can be required on the animation elements. Host language designers may require that the optional XLink attributes be specified. These decisions are left to the host language designer - the syntax details for XLink attributes do not affect the semantics of SMIL Animation.

In general, target elements may be any element in the document. Host language designers must specify any exceptions to this. Host language designers are discouraged from allowing animation elements to target elements outside of the document in which the animation element is defined (the XLink syntax for the target element could allow this, but the semantics of this are not yet resolved). 

Target attribute issues

The definitions in this module can be used to animate any attribute of any element in a host document. However, it is expected that host language designers integrating SMIL Animation may choose to constrain which elements and attributes can support animation. For example, a host language may not support animation of the language attribute of a script element. A host language which included a specification for DOM functionality might limit animation to the attributes which may legally be modified through the DOM.

Any attribute of any element not specifically excluded from animation by the host language may be animated, as long as the underlying datatype (as defined by the host language for the attribute) supports discrete values (for discrete animation) and/or addition (for interpolated and additive animation).

Example: SVG

As an example, SVG [SVG] integrates SMIL Animation. It specifies which of the elements, attributes and CSS properties may be animated.  Some attributes (e.g. "viewbox" and "fill-rule") support only discrete animation, and others (e.g. "width", "opacity" and "stroke") support interpolated and additive animation. An example of an attribute that does not support any animation is the "xlink:actuate" attribute on the <use> element (the value of this attribute is fixed to "auto" in the DTD). 

All constraints upon animation must be described in the host language specification, as the DTD cannot reasonably express this.

Integrating animateMotion functionality

The host language specification must define which elements can be the target of animateMotion. In addition, the host language specification must describe the positioning model for elements, and must describe the model for animateMotion in this context (i.e. the semantics of the "default" value for the origin attribute must be defined). If there are different ways to describe position, additional attribute values for the origin attribute should be defined to allow authors control over the positioning model.

5.3. Constraints on Manipulating Animation elements

Language designers integrating SMIL Animation are encouraged to disallow manipulation of attributes of the animation elements, after the document has begun. This includes both the attributes specifying targets and values, as well as the timing attributes. In particular, the id attribute (of type ID) on all animation elements must not be mutable (i.e. should be read-only). Requiring animation runtimes to track changes to id values introduces considerable complexity, for what is at best a questionable feature.

It is recommended that language specifications disallow manipulation of animation element attributes through DOM interfaces after the document has begun.  It is also recommended that language specifications disallow the use of animation elements to target other animation elements. 

Dynamically changing the attribute values of animation elements introduces semantic complications to the model that are not yet sufficiently resolved. This constraint may be lifted in a future version of SMIL Animation.

5.4. Constraints on Element Timing

This specification assumes that animation elements are the only elements in the host language that have timing semantics (this restriction may be removed in a future version of SMIL Animation). This specification cannot be used for host languages that contain elements with timing semantics. For example, the following integration of animation with SMIL 1.0 is illegal with this version of SMIL animation:

<par>
  <img begin="2s" dur="1m" src="foo.gif" />
    <anchor id="anc" href="#bar" coords="0%,0%,50%,50%" dur="30s" />
    <set targetElement="anc" attributeName="coords" 
         begin="10s" dur="20s" fill="freeze"
         to="50%,50%,100%,100%" />
  </img>
</par>

The set of "animation elements" that may have timing includes both the elements defined in this specification, as well as extension animation elements defined in host languages. Extension animation elements must conform to the animation framework described in this document.  In particular, extension animation elements may not be defined to contain other animation elements in a way that would introduce "nested timing" as supported by the par and seq elements in SMIL 1.0 [SMIL].

5.5. Error handling semantics

The host language designer may impose stricter constraints upon the error handling semantics. That is, in the case of syntax errors, the host language may specify additional or stricter mechanisms to be used to indicate an error. An example would be to stop all processing of the document, or to halt all animation.

Host language designers may not relax the error handling specifications, or the error handling response (as described in Handling Syntax Errors). For example, host language designers may not define error recovery semantics for missing or erroneous values in the values or keyTimes attribute values.

5.6. SMIL Animation namespace

Language designers can choose to integrate SMIL Animation as an independent namespace, or can integrate SMIL Animation names into a new namespace defined as part of the host language. Language designers that wish to put the SMIL Animation functionality in an isolated namespace should use the following namespace:

http://www.w3.org/TR/smil-animation10

6. Document Object Model Support

Any XML-based language that integrates SMIL Animation will inherit the basic interfaces defined in DOM [DOM-Level-1] (although not all languages may require a DOM implementation). SMIL Animation specifies the interaction of animation and DOM. SMIL Animation also defines constraints upon the basic DOM interfaces, and specific DOM interfaces to support SMIL Animation.

Note that the language designer integrating SMIL Animation must specify any constraints upon SMIL Animation with respect to the DOM. This includes the specification of language attributes that can or cannot be animated, as well as the definition of addition for any attributes that support additive animation.

6.1. Event Model

The SMIL Animation timing assumes that the host language supports events, and that the events can be bound in a declarative manner.  DOM Level 2 Events [DOM2Events] describes functionality to support this.

The specific events supported are defined by the host language. 

6.2. Supported Methods

SMIL Animation supports two methods for controlling the behavior of animation: beginElement() and endElement(). These methods are used to begin and end an animation that has declared the timing to respond to the DOM, using the following syntax:

<animate begin="indefinite" endActive="indefinite" .../>

Note that only one of begin or endActive need be specified - either or both can be used.  The beginElement() method must do nothing if the animation is not explicitly set with the begin="indefinite" syntax above. The endElement() method must do nothing if the animation is not explicitly set with the endActive="indefinite" syntax above.

Calling beginElement() causes the animation to begin in the same way that an animation with event-based begin timing begins. The effective begin time is the current presentation time at the time of the DOM method call. Note that beginElement() is subject to the restart attribute in the same manner that event-based begin timing is. If an animation is specified to disallow restarting at a given point, beginElement() methods calls must fail. Refer also to the section Restarting Animations.

Calling endElement() causes an animation to end the active duration, just as endActive does. Depending upon the value of the fill attribute, the animation effect may no longer be applied, or it may be frozen at the current effect. Refer also to the section Freezing Animations. If an animation is not currently active (i.e. if it has not yet begun or if it is frozen), the endElement() method will fail.

The expectation of the following interface is that an instance of the TimeControl interface can be obtained by using binding-specific casting methods on an instance of an animate element. A DOM application can use the hasFeature method of the DOMImplementation interface to determine whether the ElementTimeControl interface is supported or not. The feature string for this interface is "TimeControl".

Interface ElementTimeControl

IDL Definition

interface ElementTimeControl {
  boolean            beginElement()
                                        raises(DOMException);
  boolean            endElement()
                                        raises(DOMException);
};

Methods

beginElement

Causes this element to begin the local timeline (subject to sync constraints).

Return Value

boolean

true if the method call was successful and the element was begun. false if the method call failed. Possible reasons for failure include: The element doesn't support the beginElement method. (the begin attribute is not set to "indefinite") The element is already active and can't be restart when it is active. (the restart attribute is set to "whenNotActive") The element is active or has been active and can't be restart. (the restart attribute is set to "never").

Exceptions

DOMException

SYNTAX_ERR: The element was not defined with the appropriate syntax to allow beginElement calls.

No Parameters

endElement

Causes this element to end the local timeline (subject to sync constraints).

Return Value

boolean

true if the method call was successful and the element was endeed. false if method call failed. Possible reasons for failure include: The element doesn't support the endElement method. (the endActive attribute is not set to "indefinite") The element is not active.

Exceptions

DOMException

SYNTAX_ERR: The element was not defined with the appropriate syntax to allow endElement calls.

No Parameters

6.3. IDL Definition

smil.idl:

// File: smil.idl
#ifndef _SMIL_IDL_
#define _SMIL_IDL_

#include "dom.idl"

#pragma prefix "dom.w3c.org"
module smil
{
  interface ElementTimeControl {
    boolean            beginElement()
                                        raises(dom::DOMException);
    boolean            endElement()
                                        raises(dom::DOMException);
  };
};

#endif // _SMIL_IDL_

6.4. Java Language Binding

org/w3c/dom/smil/TimeControlException.java:

package org.w3c.dom.smil;

public abstract class TimeControlException extends RuntimeException {
  public TimeControlException(short code, String message) {
     super(message);
     this.code = code;
  }
  public short   code;
  // TimeControlExceptionCode
  public static final short           SYNTAX_ERR           = 0;
  public static final short           ACTIVE_ERR           = 1;
  public static final short           INACTIVE_ERR         = 2;
  public static final short           NEVER_RESTART_ERR    = 3;

}

org/w3c/dom/smil/ElementTimeControl.java:

package org.w3c.dom.smil;

import org.w3c.dom.DOMException;

public interface ElementTimeControl {
  public boolean            beginElement()
                                         throws DOMException;
  public boolean            endElement()
                                       throws DOMException;
}

6.5. ECMA Script Language Binding

7. Appendix: Differences and Extensions to SMIL 1.0

@@@This needs more work

• does not support "seq" and "par"
• added "repeatCount", "repeatDur" and "endActive" attributes and corresponding rules to timing model
• supports interactive, event based timing
• supports hyperlink activation
• supports DOM methods for activation of elements
• element-event value definition changed to syncbase-value, changed explanations
• syncbase-value allows offset definition
• syncbase-value (offset) can exceed duration of syncbase element

Comparison of terms

@@@This needs more work

• explicit values: these are values that are specified by certain timing attributes in the document, such as "dur", "begin" etc.
• implicit values: these are values that are not specified by timing attributes, but derived from the context in which the element occurs (parent time container), or from the intrinsic duration of a media object (@@ not relevant for animation)
• desired values: these are values that are determined by combining the explicit values if there are any, or equal to the implicit values
• values: these are values that give the actual begin, end and duration of the element after resolving all dependencies between the various timing attributes and time container constraints. (@@ they are "what the reader of the document will perceive").

8. References

[CSS2]

"Cascading Style Sheets, level 2", B. Bos, H. W. Lie, C. Lilley, I. Jacobs, 12 May 1998.
Available at http://www.w3.org/TR/REC-CSS2.

[DOM-Level-1]

"Document Object Model (DOM) Level 1 Specification"
Available at http://www.w3.org/TR/REC-DOM-Level-1/.

[DOM2Events]

"Document Object Model Events", T. Pixley, C. Wilson
Available at http://www.w3.org/TR/WD-DOM-Level-2/events.html.

[HTML]

"HTML 4.0 Specification", D. Raggett, A. Le Hors, I. Jacobs, 24 April 1998.
Available at http://www.w3.org/TR/REC-html40.

[SMIL1.0]

"Synchronized Multimedia Integration Language (SMIL) 1.0 Specification W3C Recommendation 15-June-1998 ".
Available at: http://www.w3.org/TR/REC-smil.

[SMIL-MOD]

"Synchronized Multimedia Modules based upon SMIL 1.0", Patrick Schmitz, Ted Wugofski, Warner ten Kate.
Available at http://www.w3.org/TR/NOTE-SYMM-modules.

[SVG]

"Scalable Vector Graphics (SVG) 1.0 Specification", W3C Working Draft.
Available at http://www.w3.org/TR/SVG/.

[XLink]

"XML Linking Language (XLink)", S. DeRose, D. Orchard, B. Trafford, editors, 9 July 1999.
Available at http://www.w3.org/TR/xlink

[XML]

"Extensible Markup Language (XML) 1.0", T. Bray, J. Paoli, C.M. Sperberg-McQueen, editors, 10 February 1998.
Available at http://www.w3.org/TR/REC-xml

[XML-NS]

"Namespaces in XML" T. Bray, D. Hollander, A. Layman, editors, 14 January 1999.
Available at http://www.w3.org//TR/REC-xml-names/.