SMIL 3.0 Animation

12.1 Overview and Summary of Changes for SMIL 3.0

This section is informative.

The SMIL 3.0 specification leaves the SMIL 2.1 Animation Modules [SMIL21-animation] mostly unchanged. The only changes are that normative text is added that clarifies the ability of a host language designer to override the event base default element, and that several typos and some examples have been corrected.

12.2 Introduction

This section is informative.

This section defines the SMIL 3.0 Animation Modules, which are composed of a BasicAnimation module and a SplineAnimation module. These modules contain elements and attributes for incorporating animation onto a time line, and a mechanism for composing the effects of multiple animations. Since these elements and attributes are defined in modules, designers of other markup languages may choose whether or not to include this functionality in their languages. Language designers incorporating other SMIL modules do not need to include the animation modules if animation functionality is not needed.

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

While this document defines a base set of animation capabilities, it is assumed that host languages may build upon the support to define additional or more specialized animation elements. Animation only manipulates attributes and properties of the target elements, and so does not require any knowledge of the target element semantics beyond basic type information. Basic type information includes such information as whether a type supports addition, and whether a list of numbers is just that, or whether it represents e.g. a set of coordinates.

Note that the host language determines which attributes may be animated.

This module depends on the SMIL 3.0 BasicInlineTiming module, using elements and attributes from the Timing module for its time line. The BasicInlineTiming module is a prerequisite for any profile using SMIL Animation. The reader is presumed to have read and be familiar with the SMIL 3.0 Timing modules.

This section first presents the underlying principles of animation in SMIL 3.0, then the elements and attributes of the BasicAnimation module and of the SplineAnimation module.

12.3 Module Overview

This section is informative.

SMIL 3.0 Animation functionality is partitioned across the following 2 modules:

BasicAnimation

The BasicAnimation module defines simple animation functions defined by sets of points to be visited in sequence, with the function defined between those using discrete, linear or paced interpolation.

SplineAnimation

The SplineAnimation module extends the discrete, linear and paced calculation modes of the BasicAnimation module, providing additional control over interpolation and timing.

12.4 Animation Model

This section is normative.

This section is informative.

This section describes the semantics underlying the SMIL 3.0 animation modules. 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 simple animation function f(t), and then the overall effect F(t,u).

12.4.1 Summary of symbols used in the semantic descriptions

This section is informative.

In the definitions of the animation functions, a number of symbols are used. These symbols are summarized here.

a

The target attribute of an animation element.

d

The simple duration of the element.

AD

The active duration of the element.

IAD

The intermediate active duration of the element. This value is the duration for which the element is to repeat, only taking the dur, repeatCount and repeatDur attributes into account.

rd

The repeat duration of the element. This is defined as the minimum of the active duration and the intermediate active duration. It is the time during which the animation plays normally. If the intermediate active duration is less than the active duration, the animation is either frozen or not present during the difference.

t

A time. Depending on the context, t may be in user-perceived time, an element’s active duration, or its simple duration.

u

The underlying value of the target attribute a, generally at a specific time t.

f(t)

The simple animation function of&nbsp;times within the simple duration. This is&nbsp;defined for&nbsp;t: 0&lt;=t<d.

Note that while F(t,u) defines the mapping for the entire animation, f(t) has a simplified model that just handles the simple duration.

f(d)

While f(t) is not defined for the value t=d, the expression f(d) is used as a shorthand to refer to the last value defined for the animation function.

F(t,u)

The effect of an animation for any point in the active duration of the animation. This maps times within the active duration (t: 0<=t<AD) and an underlying value to a value for the target attribute. A time value of 0 corresponds to the time at which the animation begins. F(t,u) combines the simple animation function f(t) with all the other aspects of animation and timing controls.

12.4.2 The simple animation function f(t)

Animation is defined as a time-based function 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 takes into account all aspects of timing, as well as animation-specific semantics. The overall mapping is based on a simple animation function f(t) which describes the animation over the simple duration of the element. Every animation defines a simple animation function which produces a value for the target attribute for any time within the simple duration.

A 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 XML ID reference or via an XLink [XLINK] locator reference.

This section is informative.

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&nbsp;width of&nbsp;10&nbsp;pixels and increases to&nbsp;a&nbsp;width of&nbsp;100 pixels over the course of&nbsp;10&nbsp;seconds. Over the same ten seconds, the height of&nbsp;the rectangle changes from 100 pixels to&nbsp;10&nbsp;pixels.

When an&nbsp;animation is&nbsp;running, it&nbsp;should not actually change the attribute values in&nbsp;the DOM [DOM2]. The animation runtime should maintain a&nbsp;presentation value for each animated attribute, separate from the DOM or&nbsp;CSS Object Model (OM). If&nbsp;an&nbsp;implementation does not support an&nbsp;object model, it&nbsp;should maintain the original value as&nbsp;defined by&nbsp;the document as&nbsp;well as&nbsp;the presentation value. The presentation value is&nbsp;reflected in&nbsp;the displayed form of&nbsp;the document. Animations thus manipulate the presentation value, and should not affect the base value exposed by&nbsp;DOM or&nbsp;CSS OM. This is&nbsp;detailed in&nbsp;The animation sandwich model.

The base value of&nbsp;a&nbsp;target attribute a&nbsp;at&nbsp;time t&nbsp;is&nbsp;the value of&nbsp;a&nbsp;to&nbsp;which animation is&nbsp;applied at&nbsp;time&nbsp;t.

The presentation value of&nbsp;a&nbsp;target attribute a&nbsp;at&nbsp;time t&nbsp;is&nbsp;the value of&nbsp;a&nbsp;resulting from the application of&nbsp;animation at&nbsp;time&nbsp;t.

The presentation value reflects the effect of&nbsp;animation on&nbsp;the base value. The effect is&nbsp;the change to&nbsp;the base value of&nbsp;the target attribute at&nbsp;any given time. When an&nbsp;animation completes, the effect of&nbsp;the animation is&nbsp;no&nbsp;longer applied, and the presentation value reverts to&nbsp;the base value by&nbsp;default. The animation effect may also be&nbsp;extended to&nbsp;freeze the last value for the length of&nbsp;time determined by&nbsp;the semantics of&nbsp;the fill attribute.

An&nbsp;animation element defines a&nbsp;simple animation function which is&nbsp;evaluated as&nbsp;needed over time by&nbsp;the implementation. The resulting values are applied to&nbsp;the presentation value for the target attribute. Animation functions are continuous in&nbsp;time and may be&nbsp;sampled at&nbsp;whatever frame rate is&nbsp;appropriate for the rendering system. The syntactic representation of&nbsp;the simple animation function is&nbsp;independent of&nbsp;this model, and may be&nbsp;described in&nbsp;a&nbsp;variety of&nbsp;ways. The animation elements in&nbsp;this specification support syntax for a&nbsp;set of&nbsp;discrete or&nbsp;interpolated values, a&nbsp;path syntax for motion based upon SVG paths, keyframe based timing, evenly paced interpolation, and variants on&nbsp;these features.

This section is&nbsp;informative.

In&nbsp;the example immediately above, the simple animation function for the width attribute, specified by &rsquo;from=&quot;10px&quot; to=&quot;100px&quot; ... dur=&quot;10s&laquo;&rsquo; is

f(t) = (10 + 90*t/10) px, where t&nbsp;is&nbsp;given in&nbsp;seconds.

Simple animation functions may be&nbsp;defined which have additional parameters, or&nbsp;that are purely or&nbsp;partially algorithmic. For example, a&nbsp;&laquo;to&raquo; animation interpolates from the current value to&nbsp;the &laquo;to&raquo; value:

<animate attributeName="top" to="10" dur="2.5s" />

The animation function is&nbsp;a&nbsp;function of&nbsp;the current position, as&nbsp;well as&nbsp;of&nbsp;time:

f(t,u) = (u*(2.5s-t)/2.5s) + 10*(t/2.5s)

In&nbsp;all cases, the animation exposes this as&nbsp;a&nbsp;function of&nbsp;time.

The simple animation function defined by&nbsp;an&nbsp;animation element is&nbsp;a&nbsp;function of&nbsp;time, f(t), defined for times&nbsp;t, 0&lt;=t&lt;=d, where d&nbsp;is&nbsp;the simple duration of&nbsp;the element.

The simple animation function may be&nbsp;defined as&nbsp;a&nbsp;function which depends on&nbsp;factors in&nbsp;addition to&nbsp;time. This does not affect the model of&nbsp;animation, beyond the trivial addition of&nbsp;additional parameters to&nbsp;f(t), such as&nbsp;f(t,u) used in&nbsp;the &laquo;to&raquo; animation example immediately above.

Animations may be&nbsp;defined to&nbsp;either override or&nbsp;add to&nbsp;the base value of&nbsp;an&nbsp;attribute. In&nbsp;this context, the base value may be&nbsp;the DOM value, or&nbsp;the result of&nbsp;other animations that also target the same attribute. This more general concept of&nbsp;a&nbsp;base value is&nbsp;termed the underlying value. Animations that add to&nbsp;the underlying value are described as&nbsp;additive animations. Animations that override the underlying value are referred to&nbsp;as&nbsp;non-additive animations. The animation effect function of&nbsp;an&nbsp;element is&nbsp;the function which includes the effect of&nbsp;the underlying value and accounts for repeating and freezing of&nbsp;the element. Because the animation effect may be&nbsp;affected by&nbsp;repeating and freezing, it&nbsp;is&nbsp;defined over the active duration of&nbsp;the element rather than its simple duration.

Animations may be&nbsp;combined in&nbsp;ways which produce intermediate values outside of&nbsp;the domain of&nbsp;the target attribute, but where the presentation value produced is&nbsp;valid. The type of&nbsp;a&nbsp;target attribute is&nbsp;this larger set. This is&nbsp;detailed in&nbsp;The animation sandwich model.

The type of&nbsp;a&nbsp;target attribute a&nbsp;is&nbsp;the base type of&nbsp;which the domain of&nbsp;a&nbsp;is&nbsp;a&nbsp;subset.

The underlying value u&nbsp;of&nbsp;a&nbsp;target attribute a&nbsp;of&nbsp;an&nbsp;animation element at&nbsp;time t&nbsp;is&nbsp;the value of&nbsp;a&nbsp;to&nbsp;which the animation effect is&nbsp;applied at&nbsp;time&nbsp;t.

The animation effect function, F(t,u), of&nbsp;an&nbsp;animation element with active duration&nbsp;AD is&nbsp;a&nbsp;function mapping times&nbsp;t: 0&lt;=t<AD and values u of the type of the target attribute a into values of the type of a.

The animation effect function F(t,u) is usually defined as a function of the simple animation function f(t). f(t) must be defined in such a manner that F(t,u) produces values of the correct type.

12.4.3 The animation sandwich model

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

The remainder of this discussion uses the generic term OM for both the XML DOM [DOM2] as well as the CSS-OM. If an implementation does not support an object model, it should ideally maintain the original value as defined by the document as well as the presentation value; for the purposes of this section, we will consider this original value to be equivalent to the value in the OM.

In some implementations of DOM, it may be difficult or impractical to maintain a presentation value as described. CSS values should always be supported as described, as the CSS-OM provides a mechanism to do so. In implementations that do not support separate presentation values for general XML DOM properties, the implementation must at least restore the original value when animations no longer have an effect.

The rest of this discussion assumes the recommended approach using a separate presentation value.

The model accounting for the OM and concurrently active or frozen animations for a given attribute is described as a "sandwich", a loose analogy to the layers of meat and cheeses in a "submarine sandwich" (a long sandwich made with many pieces of meats and cheese layered along the length of the bread). In the analogy, time is associated with the length of the sandwich, and each animation has its duration represented by the length of bread that the layer covers. On the bottom of the sandwich is the base value taken from the OM. Each active (or frozen) animation is a layer above this. The layers (i.e. the animations) are placed on the sandwich both in time along the length of the bread, as well as in order according to priority, with higher priority animations placed above (i.e. on top of) lower priority animations. At any given point in time, you can take a slice of the sandwich and see how the animation layers stack up.

Note that animations manipulate the presentation value coming out of the OM in which the attribute is defined, and pass the resulting value on to the next layer of document processing. This does not replace or override any of the normal document OM processing cascade.

Specifically, animating an attribute defined in XML will modify the presentation value before it is passed through the style sheet cascade, using the XML DOM value as its base. Animating an attribute or property defined in a style sheet language will modify the presentation value passed through the remainder of the cascade.

In CSS2 and the DOM 2 CSS-OM, the terms "specified", "computed" and "actual" are used to describe the results of evaluating the syntax, the cascade and the presentation rendering. When animation is applied to CSS properties of a particular element, the base value to be animated is read using the (readonly) getComputedStyle() method on that element. The values produced by the animation are written into an override stylesheet for that element, which may be obtained using the getOverrideStyle() method. Note that it is assumed that before reading the value, the override stylesheet is cleared so that the animation works on the original document value. 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 section 6.1, "Specified, computed, and actual values," of [CSS2] and section 5.2.1, "Override and computed style sheet," of [DOM2CSS].

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, it will always move to the top of the priority list, as it becomes the most recently activated animation. That is, when an animation restarts, its layer is pulled out of the sandwich, and added back on the very top. In contrast, when an element repeats the priority is not affected (repeat behavior is not defined as restarting).

This remark is informative.

For more information about restarting, see Restarting animations.

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

Some attributes that support additive animation have a defined legal range for values (e.g. an opacity attribute may allow values between 0 and 1). In some cases, an animation function may yield out of range values. It is recommended that implementations clamp the results to the legal range as late as possible, before applying them to the presentation value. Ideally, the effect of all the animations active or frozen at a given point should be combined, before any clamping is performed. Although individual animation functions may yield out of range values, the combination of additive animations may still be legal. Clamping only the final result and not the effect of the individual animation functions provides support for these cases. Intermediate results may be clamped when necessary although this is not optimal. The host language must define the clamping semantics for each attribute that may be animated. As an example, this is defined for 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 animation element remains in the frozen state, and so the presentation value will continue to reflect the animation effect. Refer also to the section "Freezing animations".

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