Abstract
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.
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 is the
"Last Call Working Draft" of the specification for SMIL Animation. The
Last Call review period ends at 2359Z on 27 February 2000. Please send review
comments before the review period ends to
www-smil@w3.org.
If the review indicates that there is consensus in the community, the Working
Group plans to ask the W3C Director to advance this document to Candidate
Recommendation.
This Working Draft 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 is a W3C Working Draft for review by W3C Members and other interested
parties. It is a draft document and may be updated, replaced or obsoleted
by other documents at any time. It is inappropriate to use W3C Working Drafts
as reference material or to cite them as other than "work in progress". This
document is work in progress and does not imply endorsement by the
W3C membership.
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, 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 and/or
more specialized animation elements. In order to ensure a consistent
model for document authors and runtime implementers, we introduce a framework
for integrating animation with the SMIL timing model. Animation only manipulates
attributes 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.
When an animation is running, it does not actually change the attribute values
in the DOM [DOM-Level-2]. The animation
runtime must maintain a presentation value for each animated attribute,
separate from the DOM or CSS Object Model (OM). If an implementation does
not support an object model, it must maintain the original value as defined
by the document as well as the presentation value. The presentation value
is reflected in the display form of the document. Animations thus manipulate
the presentation value, and do not affect the base value exposed
by DOM or CSS OM.
The animation function is evaluated as needed over time by the implementation,
and the resulting values are applied to the presentation value for the target
attribute. 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.
As a simple example, the following defines an animation of an SVG rectangle
shape. The rectangle will change from being tall and thin to being
short and wide.
<rect ...>
<animate attributeName="width" from="10px" to="100px"
begin="0s" dur="10s" />
<animate attributeName="height" from="100px" to="10px"
begin="0s" dur="10s" />
</rect>
The rectangle begins with a width of 10 pixels and increases to a width of
100 pixels over the course of 10 seconds. Over the same ten seconds, the
height of the rectangle changes from 100 pixels to 10 pixels.
2.2. Animation function values
Many animations specify the animation function
f(t) as a sequence of values to be applied
over time. For some types of attributes (e.g. numbers), it is also possible
to describe an interpolation function between values.
As a simple form of describing the values, animation elements can specify
a from value and a to value. If the attribute takes values
that support interpolation (e.g. a number), the animation function can
interpolate values in the range defined by from and
to, over the course of the simple duration. A variant on this uses
a by value in place of the to value, to indicate an additive
change to the attribute.
More complex forms specify a list of values, or even a path description for
motion. Authors can also control the timing of the values, to describe "keyframe"
animations, and even more complex functions.
2.3. Symbols used in the semantic descriptions
-
f(t)
-
The 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.
-
B
-
The begin of an animation.
-
d
-
The simple duration of an animation.
-
AD
-
The active duration of an animation. This is the period during which time
is actively advancing for the animation. This includes any effect of repeating
the simple duration, but does not include the time during which the animation
may be frozen.
-
AE
-
The active end. This is the end of the active duration of an animation.
3. Animation model
This section describes the 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 namespace.
The attributeType attribute is optional. By default, the animation
runtime will resolve the names according to the following rule: If there
is a name conflict and attributeType is not specified, the CSS
namespace is matched first (if CSS is supported in the host language), followed
by the default namespace for the target element.
If a target attribute is defined in an XML Namespace other than the default
namespace for the target element, the author must specify the namespace of
the target attribute using the associated namespace prefix as defined in
the scope of the target element. The prefix is prepended to the value for
attributeName.
For more information on XML namespaces, see
[XML-NS].
-
attributeName =
<attributeName>
-
Specifies the name of the target attribute. An XMLNS prefix may be used to
indicate the XML namespace for the attribute. The prefix will be interpreted
in the scope of the target element.
-
-
attributeType
= "CSS | XML | auto"
-
Specifies the namespace in which the target attribute and its associated
values are defined. The attribute value is one of the following (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. If the
value for
attributeName has an XMLNS prefix, the implementation
must use the associated namespace as defined in the scope of the target element.
-
"auto"
-
The implementation should match the attributeName to an attribute for the
target element. The implementation must first search through the CSS
namespace for a matching property name, and if none is found, search the
XML namespace.
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. 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, both
attributes must be included in the host language, and they both occur in
an animation element, the XLink "href" attribute takes precedence over the
"targetElement" attribute.
The advantage of using a "targetElement" attribute is 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" attribute="bar" .../>
This example uses the more flexible XLink locater syntax, with the equivalent
target.
<animate href="#foo" attribute="bar" .../>
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 is fixed to "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 below (in Timing Attribute Values); a syntax summary is provided
here as an aid to the reader.
-
begin
-
Defines when the element should begin (i.e. become active).
The attribute value can be one of the following types of values:
-
clock-value
-
Specifies the presentation time at which the animation begins. The begin
is thus defined relative to the document begin.
-
syncbase-value : ( id-ref "." ) (
"begin" | "end" ) ( "+"clock-value )?
-
Describes a syncbase and an offset from that syncbase. The element begin
is defined relative to the begin
B or active
end AE of another animation.
-
event-value : ( id-ref "." )? ( event-ref
) ( "+"clock-value )?
-
Describes an event and an optional offset that determine the element begin.
The animation begin is defined relative to the time that the event is raised.
Events may be any event defined for the host language in accordance with
[DOM2Events]. These may include user-interface
events, event-triggers transmitted via a network, etc. Details of event-based
timing are described in the section below on Unifying
event-based and scheduled timing.
-
"indefinite"
-
The begin of the animation will be determined by a "beginElement()" method
call or a hyperlink targeted to the animation element.
The SMIL Animation DOM methods are described in the
Supported methods section.
Hyperlink-based timing is described in the
Hyperlinks and timing section.
-
dur
-
Specifies the simple duration.
The attribute value can be one of the following types of values:
-
clock-value
-
Specifies the length of the simple duration in presentation time.
Value must be greater than 0.
-
"indefinite"
-
Specifies the simple duration
d as indefinite.
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. 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.
Timing attribute values
In the syntax specifications that follow, allowed white space is indicated
as "S", defined as follows (taken from the [XML]
definition for "S"):
S ::= (#x20 | #x9 | #xD | #xA)+
Clock values
Clock values have the following syntax:
Clock-val ::= Full-clock-val | Partial-clock-val
| Timecount-val
Full-clock-val ::= Hours ":" Minutes ":" Seconds ("." Fraction)?
Partial-clock-val ::= Minutes ":" Seconds ("." Fraction)?
Timecount-val ::= Timecount ("." Fraction)? (Metric)?
Metric ::= "h" | "min" | "s" | "ms"
Hours ::= DIGIT+; any positive number
Minutes ::= 2DIGIT; range from 00 to 59
Seconds ::= 2DIGIT; range from 00 to 59
Fraction ::= DIGIT+
Timecount ::= DIGIT+
2DIGIT ::= DIGIT DIGIT
DIGIT ::= [0-9]
For Timecount values, the default metric suffix is "s" (for seconds). No
embedded white space is allowed in clock values, 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:
-
Full clock values:
02:30:03
50:00:10.25 = 50 hours, 10 seconds and 250 milliseconds
-
Partial clock value:
02:33
00:10.5 = 10.5 seconds = 10 seconds and 500 milliseconds
-
Timecount values:
3.2h = 3.2 hours = 3 hours and 12
minutes
45min = 45 minutes
30s = 30 seconds
5ms = 5 milliseconds
12.467 = 12 seconds and 467 milliseconds
Fractional values are just (base 10) floating point definitions of seconds.
Thus:
00.5s = 500 milliseconds
00:00.005 = 5 milliseconds
Syncbase values
A syncbase value has the following syntax:
Syncbase-value ::= ( Syncbase-element "." Time-symbol
)
( S "+" S Clock-value
)?
Syncbase-element ::= Id-value
Time-symbol ::= "begin" | "end"
A syncbase value starts with a Syncbase-element term defining the value of
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. For a formal definition of
"ID", refer to XML 1.0
[XML].
The syncbase element is qualified with one of the following time symbols:
-
begin
-
Denotes the begin time of the syncbase element.
-
end
-
Denotes the Active End
AE of the syncbase element.
The time symbol can be followed by a clock value. The clock value specifies
a presentation time offset from the time (i.e. the begin or end) specified
by the syncbase and time symbol. If the clock value is omitted, it defaults
to "0".
No embedded white space is allowed between a syncbase element and a time-symbol.
White space will be ignored before and after a "+" for a clock value. Leading
and trailing white space (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
Event values
An event value has the following syntax:
Event-value ::= (
Eventbase-element "." )? Event-symbol
( S "+" S Clock-value
)?
Eventbase-element ::= Id-value
An Event value starts with 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 considered 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]), and it is not possible to specify
all Event-symbol names, 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"
attributeType="CSS" />
...
</rect>
3.2.2. Animation function values
The animation is described either as a list of values, or in a
simplified form that describes the from, to and by
values.
-
from =
"<value>"
-
Specifies the starting value of the animation.
-
to =
"<value>"
-
Specifies the ending value of the animation.
-
by =
"<value>"
-
Specifies a relative offset value for the animation.
-
values =
"<list>"
-
A semicolon-separated list of one or more values. Vector-valued attributes
are supported using the vector syntax of the
attributeType domain.
The animation values specified in the animation element must be legal values
for the specified attribute. See also
Animation function value
details.
Leading and trailing white space, and white space before and after semi-colon
separators, will be ignored.
If any values are not legal, the animation will have no effect (see also
Handling Syntax Errors).
If a list of values is used, the animation will apply the values in order
over the course of the animation (pacing and interpolation between these
values is described in the next section).
If a list of values is specified, any from, to
and by attribute values are ignored.
The simpler from/to/by syntax provides for several variants. Note
that from is optional, but that one of by or
to must be used (unless of course a list of values
is provided). It is not legal to specify both by and
to attributes - if both are specified, only the to
attribute will be used (the by will be ignored). The combinations
of attributes yield the following classes of animation:
-
from-to animation
-
Specifying a
from value and a to value defines
a simple animation, equivalent to a values list with 2 values.
The animation function is defined to start with the from value,
and to finish with the to value.
-
from-by animation
-
Specifying a
from value and a by value defines
a simple animation in which the animation function is defined to start with
the from value, and to change this over the course of the simple
duration d by a delta specified with
the by attribute. This may only be used with attributes that
support addition (e.g. most numeric attributes).
-
by animation
-
Specifying only a by value defines a simple animation in which the animation
function is defined to offset the underlying value for the attribute, using
a delta that varies over the course of the simple duration
d, starting from a delta of 0 and ending with
the delta specified with the by attribute. This may only be
used with attributes that support addition.
-
to animation
-
This describes an animation in which the animation function is defined to
start with the underlying value for the attribute, and finish with the value
specified with the
to attribute. Using this form, an author
can describe an animation that will start with whatever value the attribute
has originally, and will end up at the desired to value.
The last two forms "by animation" and "to animation" have
additional semantic constraints when combined with other animations. The
details of this are described below in the section
How from, to and by attributes affect additive
behavior.
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 basic method of applying
values to the attribute. The keyTimes attribute provides additional
control over the timing of the animation function, associating a time with
each value in the values list. Finally, the
keySplines attribute provides a means of controlling the pacing
of interpolation between the values in the values list.
-
calcMode =
"discrete | linear | paced | spline"
-
Specifies the interpolation mode for the animation. This can take any of
the following values. The default mode is "linear", however if the
attribute does not support linear interpolation (e.g. for strings), the
calcMode attribute is ignored and discrete interpolation is
always used.
-
discrete
-
This specifies that the animation function will jump from one value to the
next without any interpolation.
-
linear
-
Simple linear interpolation between values is used to calculate the animation
function.
This is the default calcMode.
-
paced
-
Defines interpolation to produce an even pace of change across the animation.
This is only supported for values that define a linear numeric range, and
for which some notion of "distance" between points can be calculated (e.g.
position, width, height, etc.). If "
paced" is specified, any
keyTimes or keySplines will be ignored.
-
spline
-
Interpolates from one value in the
values list to the next according
to a time function defined by a cubic Bezier spline. The points of the spline
are defined in the keyTimes attribute, and the control points
for each interval are defined in the keySplines attribute.
-
keyTimes =
"<list>"
-
A semicolon-separated list of time values used to control the pacing of the
animation. Each time in the list corresponds to a value in the
values attribute list, and defines when the value should be
used in the animation function. Each time value in the keyTimes
list is specified as a floating point value between 0 and 1 (inclusive),
representing a proportional offset into the simple duration of the
animation element.
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 keyTime
associated with each value defines when the value is set; the animation function
uses each value until the next keyTime defined.
If there are any errors in the keyTimes specification (bad values,
too many or too few values), the animation will have no effect.
If the simple duration is indefinite, any keyTimes specification
will be ignored.
-
keySplines
= "<list>"
-
A set of Bezier control points associated with the
keyTimes
list, defining a cubic Bezier function that controls interval pacing. The
attribute value is a semi-colon separated list of control point descriptions.
Each control point description is a set of four 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 the keyTimes attribute is
not specified, the values in the
values attribute are assumed
to be equally spaced through the animation duration, according to the
calcMode:
-
For discrete animation, the duration is divided into equal time periods,
one per value. The animation function takes on the values in order, one value
for each time period.
-
For linear and spline animation, the duration is divided into
n-1 even periods, and the animation function is a linear
interpolation between the values at the associated times. Note that a linear
animation will be a nicely closed loop if the first value is repeated as
the last.
Note that for the shorthand forms to animation and from-to
animation, there are only 1 and 2 values respectively. Thus a discrete
to animation will simply set the "to" value for the simple duration.
A discrete from-to animation will set the "from" value for the first
half of the simple duration and the "to" value for the second half of the
simple duration.
Note that if the calcMode is set to "paced", the
keyTimes attribute is ignored, and the values in the
values attribute are spaced to produce a constant rate of change
as the target attribute value is interpolated.
If the argument values for keyTimes or
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 semi-colon separators will be ignored.
Examples
This 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>
This example illustrates the use of keyTimes:
<animate attributeName="x" dur="10s" values="0; 50; 100"
keyTimes="0; .8; 1" calcMode="linear"/>
The keyTimes values causes the "x" attribute to have a value
of "0" at the start of the animation, "50" after 8 seconds (at 80% into the
simple duration) and "100" at the end of the animation. The value will change
more slowly in the first half of the animation, and more quickly in the second
half.
Extending this example to use keySplines:
<animate attributeName="x" dur="10s" values="0; 50; 100"
keyTimes="0; .8; 1" calcMode="spline"
keySplines=".5 0 .5 1; 0 0 1 1" />
The keyTimes still causes the "x" attribute to have a value
of "0" at the start of the animation, "50" after 8 seconds and "100" at the
end of the animation. However, the keySplines values define
a curve for pacing the interpolation between values. In the example above,
the spline causes an ease-in and ease-out effect between time 0 and 8 seconds
(i.e. between keyTimes 0 and .8, and values "0"
and "50"), but a strict linear interpolation between 8 seconds and the end
(i.e. between keyTimes .8 and 1, and values
"50" and "100"). See Figure 1 below for an illustration of the curves that
these keySplines values define.
For some attributes, the pace of change may not be easily discernable
by viewers. However for animations like motion, the ability to make the
speed of the motion change gradually, and not in abrupt steps, can
be important. The keySplines attribute provides this control.
The following figure illustrates the interpretation of the
keySplines attribute. Each diagram illustrates the effect of
keySplines settings for a single interval (i.e. between the
associated pairs of values in the keyTimes and
values lists.). The horizontal axis can be thought of as the
input value for the unit progress of interpolation within the interval
- i.e. the pace with which interpolation proceeds along the given interval.
The vertical axis is the resulting value for the unit progress,
yielded by the keySplines function. Another way of describing
this is that the horizontal axis is the input unit time for the
interval, and the vertical axis is the output unit time. See also
the section Timing and real-world
clock times.
|
keySplines="0 0 1 1"
(the default) |
|
keySplines=".5 0 .5 1"
|
|
keySplines="0 .75 .25 1" |
|
keySplines="1 0 .25 .25" |
Figure 1: Illustration of 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:
| 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:
Computer Graphics : Principles and Practice, Second Edition by James
D. Foley, Andries van Dam, Steven K. Feiner, John F. Hughes, Richard L. Phillips,
Addison-Wesley, pp. 488-491.
3.3. Specifying the animation effect
F(t)
As described above, the animation function
f(t) defines the animation for the simple duration.
However SMIL Animation allows the author to repeat this, and to specify whether
the animation should simply end when the active duration completes, or whether
it should be frozen at the last value. In addition, the author
can specify how each animation should be combined with other animations and
the original DOM value.
This section describes the syntax and associated semantics for the additional
functionality. A detailed model for combining animations is described, along
with a state model for animations, and additional details of the timing model.
The period of time during which the animation is actively playing, including
any repeat behavior, is described as the active duration
AD. The active duration may be computed from
the simple duration and the repeat specification, 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 d 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
d. Values must be greater than 0.
-
"indefinite"
-
The animation is defined to repeat indefinitely (i.e. until the document
ends).
-
repeatDur
-
Specifies the total duration for repeat. It can have the following attribute
values:
-
clock-value
-
Specifies the duration in presentation time to repeat the animation function
f(t).
-
-
"indefinite"
-
The animation is defined to repeat indefinitely (i.e. until the document
ends).
At most one of repeatCount or repeatDur should
be specified. If both are specified (and the simple duration is not indefinite),
the active duration is defined as the minimum of the specified repeatDur,
and the simple duration multiplied by repeatCount. For the purposes
of this comparison, a defined value is considered to be "less than" a value
of "indefinite". If the simple duration is indefinite, and both
repeatCount 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 AD will be 5 seconds.
<animate attributeName="top" from="0" to="10" dur="2.5s"
repeatCount="2"
/>
In the following example, the animation function will be repeated two full
times and then the first half is repeated once more; the active duration
AD will be 7.5 seconds.
<animate attributeName="top" from="0" to="10" dur="3s"
repeatCount="2.5"
/>
In the following example, the animation function will repeat for a total
of 7 seconds. It will play fully two times, followed by a fractional part
of 2 seconds. This is equivalent to a repeatCount of 2.8. The last (partial)
iteration will apply values in the range "0" to "8".
<animate attributeName="top" from="0" to="10" dur="2.5s"
repeatDur="7s" />
Note that if the simple duration is not defined (e.g. it is indefinite),
repeat behavior is not defined (but repeatDur still defines
the active duration). In the following example the simple duration is indefinite,
and so the repeatCount is effectively ignored. Nevertheless,
this is not considered an error. The active duration
AD is also indefinite. The effect of the animation
is to set the fill color to red (i.e. to just use the value for
f(0)) for the remainder of the document duration.
<animate attributeName="fill" from="red" to="blue"
repeatCount="2" />
In the following example, the simple duration is indefinite, and so repeat
behavior is not meaningful. However, the repeatDur still determines
the active duration AD. The effect of the animation
is to set the fill color to red for 10 seconds.
<animate attributeName="fill" from="red" to="blue"
repeatDur="10s" />
In the following example, the simple duration is longer than the duration
specified by repeatDur, and so the active duration will effectively
cut short the simple duration. However, animation function still uses the
specified simple duration. The effect of the animation is to interpolate
the value of "top" from 10 to 15, over the course of 5 seconds.
<animate attributeName="top" from="10" to="20"
dur="10s"
repeatDur="5s" />
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, we describe this example as:
<img ...>
<animateMotion path="c( 3 5 8 5 10 0)" dur="10s"
accumulate="sum" repeatCount="10" />
</img>
@@ Pictures would help here
The image moves from the original position along the arc over the course
of 10 seconds. As the animation repeats, it builds upon the previous value
and begins the second arc where the first one ended. In this way, the image
"bounces" across the screen. This could be described as a complete path,
but the path description would get quite large, and would be more cumbersome
to edit.
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.
Any numeric attribute that supports addition can support cumulative animation.
For example, we can grow the "width" of an SVG "rect" element by 100 pixels
in 100 seconds.
<rect width="20px"...>
<animate attributeName="width" by="10px" dur="10s"
accumulate="sum" repeatCount="10" />
</rect>
After 10 seconds, the rectangle is 30 pixels wide. The animation repeats,
and builds upon the previous values growing to 40 pixels after 20 pixels,
and up to 120 pixels wide after all ten repeats.
The behavior of repeating animations is controlled with the
accumulate attribute:
-
accumulate =
"none | sum"
-
Controls whether or not the animation is cumulative.
If "sum", each repeat iteration after the first builds upon
the last value of the previous iteration.
If "none", repeat iterations are not cumulative, and simply
repeat the animation function f(t). This is
the default.
This attribute is ignored if the target attribute value does not support
addition, or if the animation element does not repeat.
Cumulative animation is not defined for "to animation". This attribute
will be ignored if the animation function is specified with only the
to attribute. See also Specifying
function values.
To produce the cumulative animation behavior, the animation function
f(t) must be modified slightly. Each iteration
after the first must add in the last value of the previous iteration - this
is expressed as a multiple of the last value
specified for the animation function. Note
that cumulative animation is defined in terms of the values specified for
the animation behavior, and not in terms of sampled or rendered animation
values. The latter would vary from machine to machine, and could even vary
between document views on the same machine.
Let fi(t) represent the cumulative
animation function for a given iteration 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 or the last value in a "values"
list). Each iteration after the first (i.e.
fi(t) where i >=
1 ) adds in the computed offset:
fi(t) = (ve * i) + f(t)
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 methods 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 next section, Computing the active
duration.
-
end
-
Defines an end value for the animation that can constrain the active
duration.
The attribute value can be one of the following types of values:
-
clock-value
-
Specifies the presentation time of the end. The end value is thus defined
relative to the document begin.
-
syncbase-value : ( id-ref ) ( ".begin"
| ".end" )? ( "+"clock-value )?
-
Describes a syncbase and an offset from that syncbase. The end value is defined
relative to the begin
B or active end
AE of another animation.
-
event-value : ( id-ref "." )? ( event-ref
) ( "+"clock-value )?
-
Describes an event and an optional offset that determine the end value. The
end value is defined relative to the time that the event is raised. The event
must be raised after the animation begins, and before the active duration
otherwise ends (e.g. as defined by
repeatDur). Events may be
any event defined for the host language in accordance with
[DOM2Events]. These may include user-interface
events, event-triggers transmitted via a network, etc. Details of event-based
timing are described in the section below on Unifying
event-based and scheduled timing.
-
"indefinite"
-
The end value of the animation will be determined by an "endElement()" method
call. The SMIL Animation DOM methods are described in the
Supported methods section.
If end specifies an event-value or syncbase-value that is not
resolved, the end value is considered indefinite (until resolved).
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 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 2 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
AD 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
AD 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
AD divided by the simple duration
d (this may yield partial repeat iterations,
just as repeatCount can specify).
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 |
Figure 2: 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
AE of the animation, the animation no longer
affects the target (unless the animation is restarted - see
Restarting animations).
This is the default value.
This functionality is also useful when a series of motions are defined that
should build upon one another, as in this example:
<img ...>
<animateMotion begin="0" dur="5s" path="[some path]"
additive="sum" fill="freeze" />
<animateMotion begin="5s" dur="5s" path="[some path]"
additive="sum" fill="freeze" />
<animateMotion begin="10s" dur="5s" path="[some path]"
additive="sum" fill="freeze" />
</img>
The image moves along the first path, and then starts the second path from
the end of the first, then follows the third path from the end of the second,
and stays at the final point. The semantics of the additive
attribute are defined in the next section.
Note that if the active duration cuts short the simple duration (including
the case of partial repeats), then the freeze value 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 freeze value 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 freeze value 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
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.
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, the animation is defined to be additive
(i.e. the equivalent of additive="sum").
-
If
to is used without
from, (i.e. a "to animation") and if the attribute
supports addition the animation is defined to be a 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.
vcur is the current base value (at time t)
vto is the defined "to" value
f(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.
For an example of additive "to-animation", consider the following
two additive animations. The first, a "by-animation" applies a delta
to attribute "x" from 0 to -10. The second, a "to-animation" animates
to a final value of 10.
<foo x="0" .../>
<animate id="A1" attributeName="x"
by="-10" dur="10s" fill="freeze" />
<animate id="A2" attributeName="x"
to="10" dur="10s" fill="freeze" />
</foo>
The presentation value for "x" in the example above, over the course of the
10 seconds is presented in Figure 3 below. These values are simply computed
using the formula described above. Note that the value for
F(t) 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 |
Figure 3: Effect of Additive to-animation example
Additive and Cumulative animation
The "accumulate" attribute should not be confused with the
"additive" attribute. The "additive" attribute
defines how an animation is combined with other animations and the base value
of the attribute. The "accumulate" attribute defines only
how the animation function interacts with itself, across repeat iterations.
Typically, authors expect cumulative animations to be additive (as in the
examples described for accumulate
above), but this is not required. The following
example is not additive.
<img ...>
<animate dur="10s" repeatDur="indefinite"
attributeName="top" from="20" by="10"
additive="replace" accumulate="sum" />
</img>
The animation overrides whatever original value was set for "top", and begins
at the value 20. It moves down by 10 pixels to 30, then repeats. It is
cumulative, so the second iteration starts at 30 and moves down by another
10 to 40. Etc.
When a cumulative animation is also defined to be additive, both features
function normally. The accumulated effect for
F(t) is used as the value for the animation,
and is added to the underlying value for the target attribute. Refer also
to The animation sandwich model.
3.3.6. Restarting animations
When an animation is defined to begin at a simple offset (e.g.
begin="5s" ), there is an unequivocal time when the element
begins. However, if an animation is defined to begin relative to an event
(e.g. begin="foo.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.
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 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.
Comparison to SMIL timing
SMIL Animation specifies that restart="never" precludes restart
for the remainder of the document duration. In the more general 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.
3.4. Handling syntax errors
The specific error handling mechanisms for each attribute are described with
the individual syntax descriptions. However, some of these specifications
describe the behavior of an animation with syntax errors as "having no
effect". This means that the animation will continue to behave normally
with respect to timing, but will not manipulate any presentation value, and
so will have no visible impact upon the presentation.
In particular, this means that if other animation elements are defined to
begin or end relative to an animation that "has no effect", the other animation
elements will begin and end as though there were no syntax errors. The
presentation runtime may indicate an error, but 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 must 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 must maintain the
original value as defined by the document as well as the presentation value;
for the purposes of this section, we will consider this original value to
be equivalent to the value in the OM.
The model accounting for the OM and concurrently active or frozen animations
for a given attribute is described as a "sandwich", an analogy to the layers
of meat and cheeses in a "submarine sandwich". On the bottom of the sandwich
is the base value taken from the OM. Each active (or frozen) animation is
a layer above this. The layers (i.e. the animations) are placed on the sandwich
in order according to priority, with higher priority animations
placed above lower priority animations. 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 both the DOM 2 CSS-OM and in CSS2, 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 it's 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).
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:
-
If one animation is a time dependent of another (e.g. it is specified
to begin when another begins), then the time dependent is considered to activate
after the syncbase element, and so has higher priority. Time dependency
is further discussed in Propagating changes to
times. This rule applies independent of the timing described for the
syncbase element - i.e. it does not matter whether the syncbase element begins
on an offset, relative to another syncbase, relative to an event-base, or
via hyperlinking. In all cases, the syncbase is begun before any time dependents
are begun, and so the syncbase has lower priority than the time dependent.
-
If two animations share no time dependency relationship (e.g. neither is
defined relative to the other, even indirectly) the element that appears
first in the document has lower priority. This includes the cases in which
two animation elements are defined relative to the same syncbase or
event-base.
Note that if an animation is restarted (see also Restarting
animations), it will always move to the top of the priority list, as
it becomes the most recently activated animation. That is, when an animation
restarts, its layer is pulled out of the sandwich, and added back on the
very top. Note also that when an element repeats, the priority is not
affected (repeat behavior is not defined as restarting).
Each additive animation adds its effect to the result of all sandwich layers
below. A non-additive animation simply overrides the result of all lower
sandwich layers. The end result at the top of the sandwich is the presentation
value that must be reflected in the document view.
Some attributes that support additive animation have a defined legal range
for values (e.g. an opacity attribute may allow values between 0 and 1).
In some cases, an animation function may yield out of range values. It is
up to the implementation to clamp the results at the top of the animation
stack to the legal range before applying them to the presentation value.
However, the effect of all the animations in the stack should be combined,
before any clamping is performed. Although individual animation functions
may yield out of range values, the combination of additive animations in
the animation stack may still be legal. Clamping only the final result and
not the effect of the individual animation functions provides support for
these cases. 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 placed
in the respective animation stack for each attribute that is affected. Thus,
e.g. an animateMotion animation may be in more than one animation
stack (depending upon the layout model of the host language). For animation
elements that implicitly target attributes, the host language designer must
specify what attributes are implicitly targeted, and the runtime must maintain
the animation stacks accordingly.
Note that any queries (via DOM interfaces) on the target attribute will reflect
the 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).
-
If only additive animations are active or frozen (i.e. no non-additive animations
are active or frozen for the given attribute) when the OM value is changed,
the presentation value must reflect the changed OM value as well as the effect
of the additive animations. When the animations complete and the effect of
each is no longer applied, the presentation value will be equal to the changed
OM value.
-
If any non-additive animation is running when the OM value is changed, the
presentation value will not reflect the changed OM value, but will only reflect
the effect of the highest priority non-additive animation, and any still
higher priority additive animations. When all non-additive animations complete
and the effect of each is no longer applied, the presentation value will
reflect the changed OM value and the effect of any additive animations that
are active or frozen.
3.6. State transition model
At any moment in time, an animation is in exactly one of the following
states: idle, active, finished or frozen. The
state transitions are caused by events called start,
restart, freeze and stop. Figure 4 shows the legal
transitions between the states of an animation:
Figure 4: State diagram of an animation
The following sections explain the semantics of the states and transitions
of an animation, and explain how to define the transitions using attributes
of the animation element.
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.
Initial State: Idle
When the document that contains an animation element is first presented,
the animation is created in the idle state. This is the common starting
state for all animation elements.
In the idle state an animation is inactive and does not affect the
presentation of the document in any way. The animation simply waits for the
time or event specified in its begin attribute. Note that the
animation may transition immediately to the active state if the value of
the begin attribute is zero (the default).
Start Transition: Idle to Active
An animation in the idle state transitions to the active
state when the condition specified in the begin attribute becomes
true. As described in the section on the begin attribute, this
condition may depend upon one of several factors:
-
reaching a particular time in the presentation.
-
another animation element reaching a particular point in its active duration.
-
the occurrence of an event, such as a mouse click.
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.
Active State:
In the active state, an animation performs the transformation of its specified
presentation values. The active state includes the entire active duration
of the animation. The active duration of an animation element is specified
by the interaction between the dur, end,
repeatDur, and repeatCount attributes as detailed
in the sections above describing those attributes, and in
Computing the active duration.
Freeze Transition: Active to Frozen
If an animation has the fill attribute set to
freeze, upon reaching the end of its active duration, the animation
will transition to the frozen state.
Frozen State:
In the frozen state the animation will continue to apply its final
transformation of the specified presentation values for the remainder of
the document presentation time, unless restarted.
Stop Transition: Active to Finished
If an animation has the fill attribute set to
remove (the default), upon reaching the end of its active duration,
the animation will transition to the finished state.
Finished State:
In the finished state the animation will no longer affect the
presentation of the document, unless restarted.
Restart Transition: Frozen to Active
The ability of an animation element to make this transition depends upon
the value of the restart attribute. If the restart
attribute value is always or whenNotActive the
animation element will transition to the active state in response to a DOM
beginElement() or beginElementAt() method
call, or an additional begin event. The restart transition effectively resets
the state of the animation element; the element's simple and active duration
must be recomputed as if it were being started for the first time.
Restart Transition: Active to Active
An animation element may receive a DOM beginElement() or
beginElementAt() method call or may receive an additional begin
event while in the active state. In this case, if the value of the
restart attribute is always the animation element
will re-transition to the active state and restart as described
above. Any other value for the restart attribute will prevent
this transition from occurring.
Restart Transition: Finished to Active
An animation element restart can result from a DOM call or an additional
begin event, subject to the restrictions imposed by the restart
attribute. When in the finished state, an animation element may re-transition
to the active state if the value of the restart attribute is
always or whenNotActive. Any other value for the
restart attribute will prevent this transition from occurring.
3.7. Timing model details
3.7.1. Timing and real-world clock
times
Throughout this specification, animation is described as a function of "time".
In particular, the animation function is described as producing a value for
any "time" in the range of the simple duration. However, the simple duration
can be repeated, and the animation can begin and restart in many ways.
As such, there is no direct relationship between the "time" that an animation
function uses, and the real world concept of time as reflected on a clock.
When a keySplines attribute is used to adjust the pacing between
values in an animation, the semantics can be thought of as changing the pace
of time in the given interval. An equivalent model is that
keySplines simply changes the pace at which interpolation
progresses through the given interval. The two interpretations are
equivalent mathematically, and the significant point is that the notion of
"time" as defined for the animation function f(t)
should not be construed as real world clock time. For the
purposes of animation, "time" can behave quite differently from real world
clock time.
3.7.2. Interval timing
SMIL Animation assumes the most common model for interval timing.
This describes intervals of time (i.e. durations) in which the begin time
of the interval is included in the interval, but the end time is excluded
from the interval. This is also referred to as end-point exclusive
timing. This model makes arithmetic for intervals work correctly, and provides
sensible models for sequences of intervals.
Background rationale
In the real world, this is equivalent to the way that seconds add up to minutes,
and minutes add up to hours. Although a minute is described as 60 seconds,
a digital clock never shows more than 59 seconds. Adding one more second
to "00:59" does not yield "00:60" but rather "01:00", or 1 minute and 0 seconds.
The theoretical end time of 60 seconds that describes a minute interval is
excluded from the actual interval.
In the world of media and timelines, the same applies: Let A be a video,
a clip of audio, or an animation. Assume "A" begins at 10 and runs until
15 (in any units - it does not matter). If "B" is defined to follow "A",
then it begins at 15 (and not at 15 plus some minimum interval). When a runtime
actually renders out frames (or samples for audio), and must render the time
"15", it should not show both a frame of "A" and a frame of "B", but rather
should only show the new element "B". This is the same for audio, or for
any interval on a timeline. If the model does not use endpoint-exclusive
timing, it will draw overlapping frames, or have overlapping samples of audio,
of sequenced animations, etc.
Note that transitions from "A" to "B" also adhere to the interval timing
model. They do require that "A" not actually end at 15, and that
both elements actually overlap. Nevertheless, the "A" duration is simply
extended by the transition duration (e.g. 1 second). This new duration for
"A" is also endpoint exclusive - at the end of this new duration,
the transition will be complete, and only "B" should be rendered - "A" is
no longer needed.
Implications for animation
For animation, several results of this are important: the definition of repeat,
and the value sampled during the "frozen" state.
When repeating an animation, the arithmetic follows the end-point exclusive
model. Consider the example:
<animation dur="4s" repeatCount="4" .../>
At time 0, the simple duration is sampled at 0, and the first value is
applied. This is the inclusive begin of the interval. The
simple duration is sampled normally up to 4 seconds. However, the appropriate
way to map time on the active duration to time on the simple duration is
to use the remainder of division by the simple duration:
simpleTime = REMAINDER( activeTime, d
)
or
F(t) = f( REMAINDER( t, d )
) where t is within the active duration
Note: REMAINDER( t, d ) is defined as t -
d*floor(t/d)
Using this, a time of 4 (or 8 or 12) maps to the time of
0 on the simple duration. The endpoint of the simple duration
is excluded from (i.e. not actually sampled on) the simple duration.
This implies that the last value of an animation function
f(t) may never actually be applied (e.g. for
a linear interpolation). In the case of an animation that does not
repeat and does not specify fill="freeze",
this may in fact be the case. However, in the following example, the appropriate
value for the frozen state is clearly the "to" value:
<animation from="0" to="5" dur="4s" fill=freeze
.../>
This does not break the interval timing model, but does require an additional
qualification for the animation function
F(t) while in the frozen state:
-
If the active duration is an even multiple of the simple duration, the value
to apply in the frozen state is the last value defined for the animation
function
f(t).
The definition of accumulate also aligns to this
model. The arithmetic is effectively inverted and values accumulate by adding
in a multiple of the last value defined for the animation function
f(t).
3.7.3. Unifying interactive and scheduled timing
SMIL Animation describes extensions to SMIL 1.0 to support interactive timing
of animation elements. These extensions allow the author to specify that
an animation should begin or end in response to an event (such as a user-input
event like "click"), or to a hyperlink activation, or to a DOM method call.
The syntax to describe this uses event-value
specifications and the special argument value "indefinite" for the
begin and end attribute values. Event values describe
user interface and other events. DOM method calls to begin or end an animation
require that the associated attribute use the special value "indefinite".
A hyperlink can also be targeted at an animation element that specifies
begin="indefinite". The animation will begin when the hyperlink
is activated (usually by the user clicking on the anchor). It is not possible
to directly control the active end of an animation using hyperlinks.
Background
The current model represents an evolution from earlier multimedia runtimes.
These were typically either pure, static schedulers or pure event-based
systems. Scheduler models present a linear timeline that integrates
both discrete and continuous media. Scheduler models tend to
be good for storytelling, but have limited support for user-interaction.
Event-based systems, on the other hand, model multimedia as a graph of event
bindings. Event-based systems provide flexible support for
user-interaction, but generally have poor scheduling facilities; they are
best applied to highly interactive and experiential multimedia.
The SMIL 1.0 model is primarily a scheduling model, but with some flexibility
to support continuous media with unknown duration. User interaction is supported
in the form of timed hyperlinking semantics, but there was no support for
activating individual elements via interaction.
Modeling interactive, event-based content in SMIL
<
