Copyright ©2000 W3C® (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.
This is a working draft 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.
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 is a Working Draft of the World Wide Web Consortium. Review comments on this specification should be sent to www-smil@w3.org. The archive of public comments is available at http://lists.w3.org/Archives/Public/www-smil/.
The SMIL Animation specification has been produced as part of the W3C Synchronized Multimedia Activity. The document has been written by the SYMM Working Group (members only) working with the SVG Working Group (members only). The goals of the SYMM group are discussed in the SYMM Working Group charter (members only).
This specification is a revision of the "Last Call Working Draft" SMIL Animation of 28-January-2000, incorporating editorial suggestions received in review comments. Before the Working Group will consider moving this document to Candidate Recommendation stage, additional changes are still required to align this draft with the developments in SMIL Boston. Specifically, requested revisions to the "Last Call Working Draft" included incorporation of some of the advanced timing features of SMIL Boston which were still being developed at the time of publication of this draft.
It is inappropriate to use W3C Working Drafts 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.
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. Controlling the active duration
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. Animation function value
details
3.9. 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. Required definitions and
constraints on animation targets
5.3. Constraints on
manipulating animation elements
5.4. Required
definitions and constraints on element timing
5.5. Error handling semantics
5.6. SMIL Animation
namespace
6. Document Object Model support
6.1. Event model
6.2. Supported interfaces
6.3. IDL definition
6.4. Java language binding
6.5. ECMAScript language binding
7. Appendix: Differences from SMIL 1.0 timing model
8. References
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 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 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.
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.
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.
f(t)F(t) defines
the mapping for the entire animation, f(t)
has a simplified model that just handles the simple duration.F(t)F(t) combines the animation function
f(t) with all the other aspects of
animation and timing controls.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).
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 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 target element. The prefix is prepended to the value for
attributeName.
For more information on XML namespaces, see [XML-NS].
attributeName has an
XMLNS prefix, the implementation must use the associated namespace
as defined in the scope of 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>"href =
uri-referenceWhen 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'actuate = 'onLoad'show = 'embed'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.
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.
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 below (in Timing Attribute Values). A syntax summary is provided
here as an aid to the reader.
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.
In the syntax specifications that follow, allowed white space is indicated as "S", defined as follows (based upon the [XML] definition for white space):
S ::= spacechar+ spacechar ::= (#x20 | #x9 | #xD | #xA)
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, nor is leading or trailing white space.
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:
02:30:03 50:00:10.25 = 50 hours, 10 seconds and 250
milliseconds
02:33 00:10.5 = 10.5 seconds = 10 seconds and 500
milliseconds 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 millisecondsFractional values are just (base 10) floating point specifications of seconds. Thus:
00.5s = 500 milliseconds
00:00.005 = 5 milliseconds
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
the 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:
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 (i.e. before and after the entire syncbase value) is not allowed.
Examples:
begin="x.end+45s" : Begin 45 seconds after "x" ends
begin="x.begin" : Begin when "x" begins
begin="x.begin + 1m" : Begin 1 minute after "x" begins
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 the id value of 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 of type ID (per the
XML definition) in the host language, for the event-base element. This element
must be another element contained in the host document.
If the id value term is missing, the event-base element is defined to be 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 event names 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 (i.e. before and after the entire eventbase value) is not allowed.
Note that it is not an error to specify an event that cannot be raised on the Event-base element (such as click for audio or other non-visual elements). Similarly, if the host language allows dynamically created events (as supported by DOM-Level2-Events [DOM2Events]), it is not possible to specify all Event-symbol names, and 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.load" : Begin when "load" is raised on "x"
begin="x.focus+3s" : Begin 3 seconds after a "focus" event is
raised 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 after the user clicks on the
element.
<rect ...>
<set begin="click" dur="5s" to="red" attributeName="fill" />
</rect>
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.
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 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 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 attribute. This may only be used with
attributes that support addition.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.
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>
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"calcMode attribute is ignored and discrete interpolation is
used.
calcMode.paced" is specified, any
keyTimes or keySplines will be
ignored.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>"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:
keyTime associated with each value defines when the value is
set; values are interpolated between the
keyTimes.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>"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:
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.
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.
There are 6 segments of equal duration: 1 segment per value. |
 |
Figure 1b: Default linear animation.
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.
There are 5 segments of varying duration: n-1 segments for n values, computed to yield a constant rate of change in the value. |
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" calcMode="discrete"
values="green; yellow; red" keyTimes="0; 5; 10" />
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" |
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:
| keySplines values | Initial value | After 1s | After 2s | After 3s | Final value |
| 0 0 1 1 | 10.0 | 12.5 | 15.0 | 17.5 | 20.0 |
| .5 0 .5 1 | 10.0 | 11.0 | 15.0 | 19.0 | 20.0 |
| 0 .75 .25 1 | 10.0 | 18.0 | 19.3 | 19.8 | 20.0 |
| 1 0 .25 .25 | 10.0 | 10.1 | 10.6 | 16.9 | 20.0 |
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; 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>
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 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. 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.
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.
f(t).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.
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" />
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="c( 3 5 7 5 10 0)" 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.
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:
"sum", each repeat iteration after the first builds upon
the last value of the previous iteration."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.
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
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.
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.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.
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:
Additionally, the following rules must be followed in computing values:
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.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:
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.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.repeatCount can specify).The following symbols are used in the table:
Bd| Simple duration d |
repeatCount |
repeatDur |
end |
Active Duration |
| defined | d | |||
| defined | defined | repeatCount*d |
||
| defined | defined | repeatDur |
||
| defined | defined | MIN( d, end-B ) |
||
| defined | defined | defined | MIN( repeatCount*d, repeatDur
) |
|
| defined | defined | defined | MIN( repeatCount*d,
( end-B )) |
|
| defined | defined | defined | MIN( repeatDur,
( end-B )) |
|
| defined | defined | defined | defined | MIN( repeatCount*d,
repeatDur, ( end-B )) |
| indefinite | * | indefinite | ||
| indefinite | * | defined | repeatDur |
|
| indefinite | * | defined | end-B |
|
| indefinite | * | defined | defined | MIN( repeatDur,
( end-B )) |
| * | indefinite | indefinite | ||
| * | indefinite | indefinite | ||
| * | indefinite | indefinite | indefinite | |
| * | indefinite | defined | end-B |
|
| * | indefinite | defined | end-B |
|
| * | indefinite | indefinite | defined | end-B |
repeatCount and repeatDur, and
end.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"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" .../>
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.
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"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.
The attribute values to and by, used to describe the animation function, can override the
additive attribute in certain cases:
by is used without
from, (by animation) the animation
is defined to be additive (i.e. the equivalent of
additive="sum").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.
dtvcurvtof(t) = vcur +
((vto - vcur) *
(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".
| Time | F(t) for A1 |
F(t) for A2 |
| 0 | 0 | 0 |
| 1 | -1 | 0.1 |
| 2 | -2 | 0.4 |
| 3 | -3 | 0.9 |
| 4 | -4 | 1.6 |
| 5 | -5 | 2.5 |
| 6 | -6 | 3.6 |
| 7 | -7 | 4.9 |
| 8 | -8 | 6.4 |
| 9 | -9 | 8.1 |
| 10 | -10 | 10 |
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.
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"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:
begin specified as an event-value can be
restarted when the named event fires multiple times.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).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.
The restart setting for an animation is evaluated when the syncbase element
restarts, when the eventbase event happens, or when the DOM method call (e.g.
beginElement()) happens. For example:
<img ...>
<animate id="foo" begin="click" ..." />
<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, and "bar" would be rescheduled to start at 8 seconds. If the user clicks again at 9 seconds, "foo" would restart but "bar" will not, as it is set to allow restart only when it is not active.
If an element is currently active when a restart is scheduled, the element should end immediately (at the time of the restart evaluation). It should not continue playing until the rescheduled begin actually happens. For example:
<img ...> <animate id="foo" begin="click" ..."/> <animate id="bar" begin="foo.begin+2s" dur="10s" /> </img>
If the user clicks the image once at 3 seconds, "foo" begins to play and 2 seconds later "bar" will play as well. If the user clicks again at 6 seconds, "foo" restarts immediately, "bar" is stopped, and "bar" will restart at 8 seconds.
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 Unifying event-based and scheduled timing.
SMIL Animation specifies that restart="never" precludes
restart for the remainder of the document duration. In the more general SMIL
Boston [SMIL-Boston] 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.
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.
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 values for general XML DOM properties, the implementation must at least restore the original value when animations no longer have an effect.
@@ Should we make further recommendations on the fallback DOM implementations?
The rest of this discussion assumes the recommended approach using a separate presentation value.
The model accounting for the OM and concurrently active or frozen animations for a given attribute is described as a "sandwich", a loose analogy to the layers of meat and cheeses in a "submarine sandwich" (a long sandwich made with many pieces of meats and cheese layered along the length of the bread). In the analogy, time is associated with the length of the sandwich, and each animation has its duration represented by the length of bread that the layer covers. On the bottom of the sandwich is the base value taken from the OM. Each active (or frozen) animation is a layer above this. The layers (i.e. the animations) are placed on the sandwich both in time along the length of the bread, as well as in order according to priority, with higher priority animations placed above (i.e. on top of) lower priority animations. At any given point in time, you can take a slice of the sandwich and see how the animation layers stack up.
Note that animations manipulate the presentation value coming out of the OM in which the attribute is defined, and pass the resulting value on to the next layer of document processing. This does not replace or override any of the normal document OM processing cascade.
Specifically, animating an attribute defined in XML will modify the presentation value before it is passed through the style sheet cascade, using the XML DOM value as its base. Animating an attribute defined in a style sheet language will modify the presentation value passed through the remainder of the cascade.
In CSS2 and the DOM 2 CSS-OM, the terms "specified", "computed" and
"actual" are used to describe the results of evaluating the syntax, the
cascade and the presentation rendering. When animation is applied to CSS
properties of a particular element, the base value to be animated is read
using the (readonly) getComputedStyle() method on that element.
The values produced by the animation are written into an override stylesheet
for that element, which may be obtained using the
getOverrideStyle() method. These new values then affect the
cascade and are reflected in a new computed value (and thus, modified
presentation). This means that the effect of animation overrides all style
sheet rules, except for user rules with the !important property.
This enables !important user style settings to have priority over
animations, an important requirement for accessibility. Note that the
animation may have side effects upon the document layout. See also the [CSS2] specification (the terms are defined in section
6.1), and the [DOM2CSS] specification (section
5.2.1).
Within an OM, 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 activation order is resolved as follows:
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. In contrast, 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.
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 recommended that implementations clamp the results to the legal range as late as possible, before applying them to the presentation value. Ideally, the effect of all the animations active or frozen at a given point should be combined, before any clamping is performed. Although individual animation functions may yield out of range values, the combination of additive animations may still be legal. Clamping only the final result and not the effect of the individual animation functions provides support for these cases. Intermediate results may be clamped when necessary although this is not optimal. The host language must define the clamping semantics for each attribute that can be animated. As an example, this is defined for The animateColor element.
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 OM 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 OM 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 combined
with any other animations for each attribute that is affected. Thus, e.g. an
animateMotion animation may be in more than one animation
sandwich (depending upon the layout model of the host language). For animation
elements that implicitly target attributes, the host language designer must
specify which attributes are implicitly targeted, and the runtime must
accordingly combine animations for the respective attributes.
Note that any queries (via DOM interfaces) on the target attribute will reflect the OM value, and will not reflect the effect of animations. Note also that the OM value may still be changed via the OM 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 OM values, the document display must reflect changes to the OM values. Host languages can support script languages that can manipulate attribute values directly in the OM. If an animation is active or frozen while a change to the OM 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).
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 6 shows the legal transitions between the states 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.
Note that there is no transition allowed from the frozen state to the finished state. This is a result of the fact that SMIL Animation does not support time containers. Once an element is frozen, it remains frozen until the documents ends, or until a restart transition makes it active again.
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).
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:
Additionally, an animation element may be started by a DOM
beginElement() or beginElementAt() method call, or
as the result of being the target of an activated hyperlink.
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, repeatDur, and repeatCount
attributes as detailed in the sections above describing those attributes, and
in Computing the active duration.
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.
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.
If an animation has the fill attribute set to
remove (