SMIL Animation

Abstract

This is a Proposed Recommendation of a specification of animation functionality for XML documents.  It describes an animation framework as well as a set of base XML animation elements suitable for integration with XML documents. It is based upon the SMIL 1.0 timing model, with some extensions, and is a true subset of SMIL 2.0.

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.

This document enters a Proposed Recommendation review period. W3C Advisory Committee Members are invited to send formal review comments until 16 August 2001 to w3t-smil-anim@w3.org, visible only to the W3C Team.
The public is invited to send comments on this document to the public mailing list www-smil@w3.org - (public archives).

After the review, the Director will announce the document's disposition: it may become a W3C Recommendation (possibly with minor changes). This announcement should not be expected sooner than 14 days after the end of the review.

The SMIL Animation specification has been produced as part of the W3C Synchronized Multimedia Activity and was written by the SYMM Working Group (members only) of the W3C Interaction Domain, working with the SVG Working Group (members only) of the W3C Document Formats Domain. The goals of the SYMM Working Group are discussed in the SYMM Working Group charter [members only], (revised July 2000 from original charter version).

This specification is a revision of the "Post Last Call Working Draft" SMIL Animation of 31-July-2000, incorporating changes that were required to fully align this draft with the developments in SMIL 2.0. These changes make SMIL Animation a true subset of SMIL 2.0. In consequence, SMIL Animation has met the exit criteria for Candidate Recommendation since SMIL 2.0 has already done so.

The SYMM Working Group [members only] considers that all features in the SMIL 2.0 specification have been implemented at least twice in an interoperable way. The SYMM Working Group Charter [members only] defines this as the implementations having been developed independently by different organizations and each test in the SMIL 2.0 test suite has at least two passing implementations. The Implementation results are publicly released and are intended solely to be used as proof of SMIL 2.0 implementability. It is only a snap shot of the actual implementation behaviors at one moment of time, as these implementations may not be immediately available to the public. The interoperability data is not intended to be used for assessing or grading the performance of any individual implementation.

There are patent disclosures and license commitments associated with the SMIL 2.0 specification (and thus with the SMIL Animation specification also), these may be found on the SYMM Patent Statement page in conformance with W3C policy.

It is inappropriate to use W3C Proposed Recommendations as reference material or to cite them as other than "work in progress". This is work in progress and does not imply endorsement by, or the consensus of W3C. A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR.

Quick Table of Contents

Full Table of Contents

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 [SMIL1.0], with some changes and extensions to support additional timing features. 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 Required definitions and 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 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 and properties 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 animation-specific semantics. 

Animations specify a begin, and a simple duration that 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 function should repeat. The simple duration combined with any repeating behavior 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 either by an ID reference or via an XLink [XLink] locator reference.

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.

When an animation is running, it should not actually change the attribute values in the DOM [DOM-Level-2].  The animation runtime should 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 should 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 should not affect the base value exposed by DOM or CSS OM. This is detailed in The animation sandwich model.

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. Animation functions are continuous in time and can be sampled at whatever frame rate is appropriate for the rendering system. 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.

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 simple 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.

3. Animation model

This section describes the attribute 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 time model depends upon several definitions for the host document: A 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 defined 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 interpretation.

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 list of CSS properties supported by the host language is matched first (if CSS is supported in the host language); if no CSS match is made (or CSS does not apply) the default namespace for the target element will be matched.

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 animation 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 animation 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 (values are case-sensitive):

"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.

"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. Note that if the value for attributeName has an XMLNS prefix, the implementation must use the associated namespace as defined in the scope of the animation element.

"auto"

The implementation should match the attributeName to an attribute for the target element. The implementation must first search through the the list of CSS properties for a matching property name, and if none is found, search the default XML namespace for the 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 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. if 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 locator, referring 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, the host language designer chooses to include both attributes in the host language, then when both are specified for a given animation element the XLink href attribute takes precedence over the targetElement attribute.

The advantage of using the targetElement attribute is the 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. The following two examples illustrate the two approaches.

This example uses the simpler targetElement syntax:

<animate targetElement="foo" attributeName="bar" .../>

This example uses the more flexible XLink locator syntax, with the equivalent target.

<foo xmlns:xlink="http://www.w3.org/1999/xlink">
   ...
   <animate xlink:href="#foo" attributeName="bar" .../>
   ...
</foo>

When using an XLink href attribute on an animation element, 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 must be "simple". 

actuate = 'onLoad'

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. 

Additional details on the target element specification as relates to the host document and language are described in Required definitions and constraints on animation targets.

3.2. Specifying the animation function f(t)

Every animation function defines the value of the attribute at a particular moment in time. The time 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. Animation function timing

The basic timing for an element is described using the begin 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 is specified using the dur attribute. The attribute syntax is described below. The normative syntax rules for each attribute value variant are described in Timing attribute value grammars. A syntax summary is provided here as an aid to the reader.

This section is normative

Begin value semantics

This section is normative

• If no begin is specified, the default timing is equivalent to an offset value of "0".
• If there is a syntax error in any individual value in the list of begin or end values (i.e., the value does not conform to the defined syntax for any of the time values), the host language must specify how the user agent deals with this.
• A time value may conform to the defined syntax but still be invalid (e.g. if an unknown element is referenced by ID in a syncbase value). If there is such an evaluation error in an individual value in the list of begin or end values, the individual value will be will be treated as though "indefinite" were specified, and the rest of the list will not be processed normally. If no legal value is specified for a begin or end attribute, the element assumes an "indefinite" begin or end time (respectively).

This section is informative

The begin value can specify a list of times. This can be used to specify multiple "ways" or "rules" to begin an element, e.g. if any one of several events is raised. A list of times can also define multiple begin times, allowing the element to play more than once (this behavior can be controlled, e.g. to only allow the earliest begin to actually be used - see also Restarting animations). 

In general, the earliest time in the list determines the begin time of the element. There are additional constraints upon the evaluation of the begin time list, detailed in Evaluation of begin and end time lists.

Note that while it is legal to include "indefinite" in a list of values for begin, "indefinite" is only really useful as a single value. Combining it with other values does not impact begin timing, as DOM begin methods can be called with or without specifying "indefinite" for begin.

Handling negative offsets for begin

This section is informative

The use of negative offsets to define begin times merely defines the synchronization relationship of the element. It does not in any way override the time container constraints upon the element, and it cannot override the constraints of presentation time. 

This section is normative

• The computed offset relative to the document begin time may be negative.
• A begin time may be specified with a negative offset relative to an event or to a syncbase that is not initially resolved.  When the syncbase or eventbase time is resolved, the computed time may be in the past.

The computed begin time defines the scheduled synchronization relationship of the element, even if it is not possible to begin the element at the computed time. The time model uses the computed begin time, and not the observed time of the element begin. 

This section is normative

• When a begin time is resolved to be in the past (i.e., before the current presentation time), the element begins immediately, but acts as though it had begun at the specified time (playing from an offset into the media).

The element will actually begin at the time computed according to the following algorithm:

Let o be the offset value of a given begin value,
d be the associated simple duration, 
AD be the associated active duration.
Let rAt be the time when the begin time becomes resolved.
Let rTo be the resolved sync-base or event-base time without the offset
Let rD be rTo - rAt.  If rD < 0 then rD is set to 0.
 
If AD is indefinite, it compares greater than any value of o or ABS(o).
REM( x, y ) is defined as x - (y * floor( x/y )). 
If y is indefinite, REM( x, y ) is just x.

Let mb = REM( ABS(o), d ) - rD

If ABS(o) >= AD then the element does not begin.
Else if mb >= 0 then the media begins at mb.
Else the media begins at mb + d.

If the element repeats, the iteration value of the repeat event has the calculated value based upon the above computed begin time, and not the observed number of repeats.

This section is informative

Thus for example:

<animate begin="foo.click-8s" dur="3s" repeatCount="10" .../>

The animation begins when the user clicks on the element "foo". Its calculated begin time is actually 8 seconds earlier, and so it begins to play at 2 seconds into the 3 second simple duration, on the third repeat iteration. One second later, the fourth iteration of the element will begin, and the associated repeat event will have the iteration value set to 3 (since it is zero based). The element will end 22 seconds after the click. The beginEvent event is raised when the element begins, but has a time stamp value that corresponds to the defined begin time, 8 seconds earlier. Any time dependents are activated relative to the computed begin time, and not the observed begin time. 

Note: If script authors wish to distinguish between the computed repeat iterations and observed repeat iterations, they can count actual repeat events in the associated event handler.

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 attribute, the simple duration is indefinite. Note that interpolation will not work if the simple duration is indefinite (although this may still be useful for <set> elements). See also Interpolation and indefinite simple durations.

If there is any error in the argument value syntax for dur, the attribute will be ignored (as though it were not specified), and so the simple duration will be indefinite.

If the begin is specified to be "indefinite" or specifies an event-base, the time of the begin is not actually known until the element is activated (e.g., with a hyperlink, DOM method call or the referenced event). The time is referred to as unresolved when it is not known. At the point at which the element begin is activated, the time becomes resolved. This is described in detail in Unifying event-based and scheduled timing.

Examples

The following examples all specify a begin at midnight on January 1st 2000, UTC

begin="wallclock(2000-01-01Z)"
begin="wallclock( 2000-01-01T00:00Z )"
begin="wallclock( 2000-01-01T00:00:00Z )"
begin="wallclock( 2000-01-01T00:00:00.0Z )"
begin="wallclock( 2000-01-01T00:00:00.0Z )"
begin="wallclock( 2000-01-01T00:00:00.0-00:00 )"

The following example specifies a begin at 3:30 in the afternoon on July 28th 1990, in the Pacific US time zone:

begin="wallclock( 1990-07-28T15:30-08:00 )"

The following example specifies a begin at 8 in the morning wherever the document is presented:

begin="wallclock( 08:00 )"

3.2.2. Animation function values

In addition to the target attribute and the timing, an animation must specify how to change the value over time. An animation can be described either as a list of values, or in a simplified form using 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.

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 from/to/by syntax provides for several variants. To use one of these variants, one of by or to must be specified; a from value is optional. 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 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, 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 any current value for the attribute, 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.

The animation values specified in the animation element must be legal values for the specified attribute. See also Animation function value details. 

Leading and trailing white space, and white space before and after semicolon separators, will be ignored.

If any values (i.e., the argument-values for from, to, by or values attributes) are not legal, the animation will have no effect (see also Handling Syntax Errors). Similarly, if none of the from, to, by or values attributes are specified, the animation will have no effect.

Interpolation and indefinite simple durations

If the simple duration of an animation is indefinite (e.g., if no dur value is specified), 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.

Examples

The following example using the values syntax animates the width of an SVG shape over the course of 10 seconds, interpolating 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. Animation 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 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 (or the points in a path description for animateMotion - see The animateMotion element). 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), the calcMode attribute is ignored and discrete interpolation is 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.

If a list of keyTimes is specified, there must be exactly as many values in the keyTimes list as in the values list.

Each successive time value must be greater than or equal to the preceding time value.

The keyTimes list semantics depends upon the interpolation mode:

• For linear and spline animation, the first time value in the list must be 0, and the last time value in the list must be 1. The keyTime associated with each value defines when the value is set; values are interpolated between the keyTimes.
• For discrete animation, the first time value in the list must be 0. The time associated with each value defines when the value is set; the animation function uses that value until the next time defined in keyTimes.

If the interpolation mode is "paced", the keyTimes attribute is ignored.

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 semicolon separated list of control point descriptions. Each control point description is a set of four floating point 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 calcMode is set to "discrete", "linear" or "spline", but 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 smoothly closed loop if the first value is repeated as the last.

This semantic applies as well when the keySplines attribute is specified, but keyTimes is not. The times associated to the keySplines values are determined as described above.

The syntax for the control point sets in keySplines lists is:

control-pt-set ::= ( fpval comma-wsp fpval comma-wsp fpval comma-wsp fpval )
fpval          ::= Floating point number
comma-wsp      ::= S (spacechar|",") S

Control point values are separated by at least one white space character or a comma. Additional white space around the separator is allowed. The allowed syntax for floating point numbers must be defined in the host language.

For the shorthand forms from-to animation and from-by animation, there are only 2 values.  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. Similarly, a discrete from-by animation will set the "from" value for the first half of the simple duration and for the second half of the simple duration will set the computed result of applying the "by" value. For the shorthand form to animation, there is only 1 value; a discrete to animation will simply set the "to" value for the simple duration.

If the  argument values for keyTimes or keySplines 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 semicolon separators will be ignored.

Interpolation modes illustrated

The three illustrations 1a, 1b and 1c below show how the same basic animation will change a value over time, given different interpolation modes. All examples use the default timing (no keyTimes or keySplines specified). All examples are based upon the following example, but with different values for calcMode:

<animate dur="30s" values="0; 1; 2; 4; 8; 15" calcMode="[as specified]" />

	Figure 1a: Default discrete animation. calcMode="discrete" There are 6 segments of equal duration: 1 segment per value.
	Figure 1b: Default linear animation. calcMode="linear" There are 5 segments of equal duration: n-1 segments for n values. Spline interpolation is a refinement of linear, and is further illustrated in Figure 2, below.
	Figure 1c: Default paced animation. calcMode="paced" There are 5 segments of varying duration: n-1 segments for n values, computed to yield a constant rate of change in the value.

Examples

The following example describes a simple discrete animation:

<animate attributeName="foo" dur="8s" 
     values="bar; fun; far; boo" />

The value of the attribute "foo" will be set to each of the four strings for 2 seconds each. Because the string values cannot be interpolated, only discrete animation is possible; any calcMode attribute would be ignored.

Discrete animation can also be used with keyTimes, as in the following example:

<animateColor attributeName="color" dur="10s" calcMode="discrete"
     values="green; yellow; red" keyTimes="0.0; 0.5;" />

This example also shows how keyTimes values can interact with an indefinite duration. The value of the "color" attribute will be set to green for 5 seconds, and then to yellow for 5 seconds, and then will remain red for the remainder of the document, since the (unspecified) duration defaults to "indefinite".

The following example describes a simple linear animation:

<animate attributeName="x" dur="10s" values="0; 10; 100" 
     calcMode="linear"/>

The value of "x" will change from 0 to 10 in the first 5 seconds, and then from 10 to 100 in the second 5 seconds. Note that the values in the values attribute are spaced evenly in time with no keyTimes specified; in this case the result is a much larger actual change in the value during the second half of the animation. Contrast this with the same example changed to use "paced" interpolation:

<animate attributeName="x" dur="10s" values="0; 10; 100" 
     calcMode="paced"/>

To produce an even pace of change to the attribute "x", the second segment defined by the values list gets most of the simple duration: The value of "x" will change from 0 to 10 in the first second, and then from 10 to 100 in the next 9 seconds. While this example could be easily authored as a from-to animation without paced interpolation, many examples (such as motion paths) are much harder to author without the "paced" value for calcMode. 

The following example illustrates the use of keyTimes:

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

The keyTimes values cause 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 cause 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 2 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 2: Illustration of keySplines 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 [COMP-GRAPHICS].

The keyTimes and keySplines attributes can also be used with the from/to/by shorthand forms for specifying values, as in the following example:

<animate attributeName="foo" from="10" to="20" 
     dur="10s" keyTimes="0.0; 0.7"
     calcMode="spline" keySplines=".5 0 .5 1" />

The value will change from 10 to 20, using an "ease-in/ease-out" curve specified by the keySplines values. The keyTimes values cause the value of 20 to be reached at 7 seconds, and to hold there for the remainder of the 10 second simple duration.

The following example describes a somewhat unusual usage: "from-to animation" with discrete animation. The "stroke-linecap" attribute of SVG elements takes a string, and so implies a calcMode of discrete. The animation will set the stroke-linecap property to "round" for 5 seconds (half the simple duration) and then set the stroke-linecap to "square" for 5 seconds.

<rect stroke-linecap="butt"...>
   <animate attributeName="stroke-linecap" 
      from="round" to="square" dur="10s"/>
</rect>

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 the simple duration. SMIL Animation also allows authors 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 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. The active duration may be computed from the simple duration and the repeat specification, and it may be constrained with the end 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 is indefinite, the animation cannot repeat. See also the section Computing the active duration.

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. 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 and 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

In the following example, the 2.5 second animation function will be repeated twice; the active duration 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 the first half is repeated once more; the active duration 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 is also indefinite. The effect of the animation is to to just use the value for f(0), setting the fill color to red 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, but the repeatDur still determines the active duration. 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, the animation function still interpolates using the specified simple duration. The effect of the animation is to interpolate the value of "top" from 10 to 17, over the course of 7 seconds.

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

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 moving along 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 (detailed in The animateMotion element), we describe this example as:

<img ...>
   <animateMotion path="m 0 0 c 30 50 70 50 100 0 z" dur="5s"
      accumulate="sum" repeatCount="4" />
</img>

The image moves from the original position along the arc over the course of 5 seconds. As the animation repeats, it builds upon the previous value and begins the second arc where the first one ended, as illustrated in Figure 3, below. In this way, the image "bounces" across the screen. The same animation could be described as a complete path of 4 arcs, but in the general case the path description can get quite large and cumbersome to edit.

Figure 3: Illustration of repeating animation with accumulate="sum". Each repeat iteration builds upon the previous.

Note that cumulative animation only controls how a single animation accumulates the results of the animation function as it repeats. It specifically does not control how one animation interacts with other animations to produce a presentation value. This latter behavior is described in the section Additive animation.

The cumulative 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.

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

<rect width="20px"...>
   <animate attributeName="width" dur="5s"
      values="0; 15; 10" additive="sum"
      accumulate="sum" repeatCount="10" />
</rect>

Each simple duration causes the rectangle width to bulge by 15 pixels and end up 10 pixels larger. The shape is 20 pixels wide at the beginning, and after 5 seconds is 30 pixels wide. The animation repeats, and builds upon the previous values. The shape will bulge to 45 pixels and then end up 40 pixels wide after 10 seconds, and will eventually end up 120 (20 + 100) pixels wide after all 10 repeats.

From-to and from-by animations also support cumulative animation, as in the following example:

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

The rectangle will grow from 10 to 20 pixels in the first 5 seconds, and then from 20 to 30 in the next 5 seconds, and so on up to 110 pixels after 10 repeats. Note that since the default value for additive is "replace", the original value is ignored. The following example makes the animation explicitly additive:

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

The results are the same as before, except that all the values are shifted up by the original value of 20. The rectangle is 30 pixels wide after 5 seconds, and 130 pixels wide after 10 repeats.

Computing cumulative animation 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 i.

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, the last value in a "values" list, or the end of a "path").  Each iteration after the first adds in the computed offset:

fi(t) = (ve * i) + f(t)     ; i >= 1

3.3.2. Controlling the active duration

SMIL Animation provides an additional control over the active duration. The end attribute allows the author to constrain the active duration of the animation by specifying an end value, using a simple offset, a time base, an event-base or DOM method calls. The end attribute can constrain but not extend the active duration that is otherwise defined by dur and any repeat behavior. The rules for combining the attributes to compute the active duration are presented in the section, Computing the active duration.

end

Defines an end value for the animation that can constrain the active duration.
The attribute value is a semi-colon separated list of values.

end-value-list : end-value (";" end-value-list )?

A semi-colon separated list of end values. The interpretation of a list of end times is detailed in the section Evaluation of begin and end time lists.

end-value : ( offset-value | syncbase-value | event-value | repeat-value | accessKey-value | media-marker-value | wallclock-sync-value | "indefinite" )

Describes the end value.

offset-value : ( "+" | "-" )? Clock-value

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

syncbase-value : ( Id-value "." ( "begin" | "end" ) ) ( ( "+" | "-" ) Clock-value )?

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

event-value : ( Id-value "." )? ( event-ref  ) ( ( "+" | "-" ) Clock-value )?

Describes an event and an optional offset that determine the element begin. The animation end value 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 event-based timing are described in the section below on Unifying event-based and scheduled timing.

repeat-value : ( Id-value "." )? "repeat(" integer ")" ( ( "+" | "-" ) Clock-value )?

Describes a qualified repeat event. The end value is defined relative to the time that the repeat event is raised with the specified iteration value.

accessKey-value : "accessKey(" character ")"

Describes an accessKey that determines the end value. The end value is defined relative to the time that the accessKey character is input by the user.

wallclock-sync-value : "wallclock(" wallclock-value ")"

Describes the end value as a real-world clock time. The wallclock time syntax is based upon syntax defined in [ISO8601].

"indefinite"

The end value of the animation will be determined by a "endElement()" (or equivalent) method call.
The SMIL Animation DOM methods are described in the Supported methods section.
Hyperlink-based timing is described in the Hyperlinks and timing section.

The end value can specify a list of times. This can be used to specify multiple "ways" or "rules" to end an element, e.g. if any one of several events is raised. A list of times can also define multiple end times that can correspond to multiple begin times, allowing the element to play more than once (this behavior can be controlled - see also Restarting animations). 

Examples:

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" end="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="click" dur="2s" repeatDur="indefinite"
         end="30s" ... />

Using end 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 some 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 allows the user to advance the presentation to the next step.

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

In this case, the active end of each animation is defined to be the earlier of 15 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 4 shows the semantics of all possible combinations of simple duration, repeatCount and repeatDur, and end. The following conventions are used in the table:

• If a cell is empty, it indicates that the associated attribute is omitted in the syntax. 
  
• Where the table entry is "defined", this corresponds to an explicit 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. 

Additionally, the following rules must be followed in computing values:

• 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 end is event-based or DOM-based, then an event or method call that activates end before the duration specified by dur and/or repeatCount or repeatDur will cut short the active duration at the end activation time.
  
• If the value of end cannot be resolved (e.g. when it is event-based), the value is considered to be "indefinite" for the purposes of evaluating the active duration. If and when the end value becomes resolved, the active duration is reevaluated.

Some of the rules and results that are implicit in the table, and that should be noted in particular are:

• If end is specified but neither of repeatCount or repeatDur are specified, then the active duration is defined as the minimum of the simple duration and the duration defined by end.
  
• If both end and either (or both) of repeatCount or repeatDur are specified, the active duration is defined by the minimum duration defined by the respective attributes.
  
• It is possible to have an indefinite simple duration and a defined, finite active duration. The active duration can constrain (cut short) the simple duration, but the active duration does not define the simple duration, or change its value (i.e., the simple duration is still indefinite as used in the simple animation function).
  
• For any active duration and simple duration that are both not indefinite, the number of repeat iterations is defined by the active duration divided by the simple duration (this may yield partial repeat iterations, just as repeatCount can specify).

The following symbols are used in the table:

B

The begin of an animation.

d

The simple duration of an animation.

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

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 = "freeze | remove"

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 of the animation, the animation no longer affects the target (unless the animation is restarted - see Restarting animations).
This is the default value.

If the active duration cuts short the simple duration (including the case of partial repeats), the effect value of a frozen animation is defined by the shortened simple duration. In the following example, the animation function repeats two full times and then again for one-half of the simple duration. In this case, the value while frozen will be 15: 

<animate from="10" to="20" dur="4s" 
         repeatCount="2.5" fill="freeze" .../> 

In the following example, the dur attribute is missing, and so the simple duration is indefinite. The active duration is constrained by end to be 10 seconds. Since interpolation is not defined, the value while frozen will be 10:

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

Comparison to SMIL timing

SMIL Animation specifies that fill="freeze" remains in effect for the remainder of the document, or until the element is restarted. In the more general SMIL timing model that allows time containers, the duration of the freeze effect is controlled by the time container, and never extends past the end of the time container simple duration. While this may appear to conflict, the SMIL Animation definition of fill="freeze" is consistent with the SMIL timing model. It is simply the case that in SMIL Animation, the document is the only "time container", and so the effect is as described above.

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="0px" to="10px" 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 they are both either active or frozen at the same moment. The ordering of animations (e.g. which animation overrides which) is determined by a priority associated with each animation. 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 (lower priority) 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.

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

additive = "replace | sum"

Controls whether or not the animation is additive. 

sum

Specifies that the animation will add to the underlying value of the attribute and other lower priority animations.

replace

Specifies that 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 may include other data types as specified by the host language.

It is often useful to combine additive animations and fill behavior, for example when a series of motions are defined that should build upon one another:

<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.

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="mouseover" dur="5s"
           additive="replace" fill="remove" />
</img>

The mouse-tracking animation runs for 5 seconds every time the user mouses 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.

In addition, 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, (by animation) the animation is defined to be additive (i.e., the equivalent of additive="sum").
• If to is used without from, (to animation) and if the attribute supports addition, the animation is defined to be a kind of mix 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.

d

is the simple duration

t

is a time within the simple duration (0 <= t <= d)

v_cur

is the current base value (at time t)

v_to

is the defined "to" value

f(t) = v_cur + ((v_to - v_cur) * (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.

Multiple to-animations will also combine according to these semantics. The higher-priority animation will "win", and the end result will be to set the attribute to the final value of the higher-priority to-animation.

Multiple by-animations combine according to the general rules for additive animation and the animation sandwich model.

The use of from values does not imply either additive no non-additive animation, and both are possible. The from value for an additive animation is simply added to the underlying value, just as for the initial value is in animations specified with a values list. Additive behavior for from-to and from-by animations is controlled by the additive attribute, as in the general case.

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 5 below. These values are simply computed using the formula described above. Note that the value for F(t) for A2 is the presentation value for "x".

Figure 5:  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 cumulative but 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, the two 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 animation

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.click" ), 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 the circumstances under which an animation is restarted:

restart = "always | whenNotActive | never"

always

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

whenNotActive

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

never

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

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 active end of the restarting animation may also restart (subject to the value of restart on these elements).
• An animation with begin specified as "indefinite" can be restarted when the DOM methods beginElement() or beginElementAt() are called repeatedly.

When an animation restarts, the defining 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.

When an active element restarts, the element first ends the active duration, propagates this to time dependents and raises an endEvent in the normal manner (see also Evaluation of begin and end time lists).

For details on when and how the restart attribute is evaluated, see Evaluation of begin and end time lists. 

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

<img ...>
   <animate id="foo" begin="click" dur="2s"
       repeatDur="indefinite" end="click"
       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. See also Event sensitivity and Unifying event-based and scheduled timing.

Resetting element state

This section is normative

When an element restarts, certain state is "reset":

• Any instance times associated with past event-values, repeat-values, accessKey-values or added via DOM method calls are removed from the dependent begin and end instance times lists. In effect, all events and DOM methods calls in the past are cleared. This does not apply to an instance time that defines the begin of the current interval.

Comparison to SMIL timing

SMIL Animation specifies that restart="never" precludes restart for the remainder of the document duration. In the more general SMIL 2.0 [SMIL20] timing model that allows time containers, the duration of the restart="never" semantic is defined by the time container, and only extends to the end of the time container simple duration. While this may appear to conflict, the SMIL Animation definition of restart="never" is consistent with the SMIL timing model. It is simply the case that in SMIL Animation, the document is the only "time container", and so the effect is as described above.

3.4. Handling syntax errors

The specific error handling mechanisms for each attribute are described with the individual syntax descriptions.  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 need not halt presentation or animation of the document. 

Some host languages and/or runtimes may choose to impose stricter error handling (see also Error handling semantics for a discussion of host language issues with error handling). Authoring environments may also 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 should ideally maintain a presentation value for any target attribute, separate from the DOM, CSS, or other object model (OM) in which the target attribute is defined. 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 OM for both the XML DOM [DOM-Level-2] as well as the CSS-OM. If an implementation does not support an object model, it should ideally 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 OM.

In some implementations of DOM, it may be difficult or impractical to main a presentation value as described. CSS values should always be supported as described, as the CSS-OM provides a mechanism to do so. In implementations that do not support separate presentation va