Table of contents

• 3.1 Summary of Changes for SMIL 2.1
• 3.2 Introduction
• 3.3 Animation Model
  • 3.3.1 The simple animation function f(t)
  • 3.3.2 Summary of symbols used in the semantic descriptions
  • 3.3.3 The animation sandwich model
  • 3.3.4 Animation elements as "continuous media"
  • 3.3.5 The animation effect function F(t,u)
    • Repeating animations
      • Examples
      • Controlling behavior of repeating animation - Cumulative animation
    • Freezing animations
  • 3.3.6 Additive animation
    • Additive and Cumulative animation
  • 3.3.7 Restarting animations
  • 3.3.8 Animation function value details
    • Interpolation and indefinite simple durations
• 3.4 Overview of the SMIL 2.1 BasicAnimation Module
• 3.5 SMIL 2.1 BasicAnimation Module Common Attributes
  • 3.5.1 Specifying the animation target
    • The target attribute
    • The target element
  • 3.5.2 Specifying the simple animation function f(t)
    • Interpolation modes illustrated
    • Examples of calcMode
  • 3.5.3 Specifying the animation effect function F(t,u)
  • 3.5.4 Simple animation functions specified by from, to and by
    • To animation
• 3.6 SMIL 2.1 BasicAnimation Elements
  • 3.6.1 The animate element
  • 3.6.2 The set element
  • 3.6.3 The animateMotion element
  • 3.6.4 The animateColor element
• 3.7 SMIL 2.1 BasicAnimation Module Details
  • 3.7.1 BasicAnimation integration requirements
    • Required definitions and constraints on animation targets
      • Specifying the target element
      • Target attribute issues
    • Integrating animateMotion functionality
  • 3.7.2 Document type definition (DTD) for the BasicAnimation module
• 3.8 Overview of the SMIL 2.1 SplineAnimation Module
  • 3.8.1 SMIL 2.1 SplineAnimation Module Attributes
    • Spline animation function calculation mode
      • Examples of advanced uses of calcMode
      • Interpolation with keySplines
  • 3.8.2 SMIL 2.1 SplineAnimation Module Elements
  • 3.8.3 The spline animate element
  • 3.8.4 The spline animateMotion element
  • 3.8.5 The spline animateColor element
• 3.9 SMIL 2.1 SplineAnimation Module Details
  • 3.9.1 SplineAnimation integration requirements
  • 3.9.2 Document type definition (DTD) for the SplineAnimation module
• 3.10 Common Animation Integration Requirements
  • 3.10.1 Integration requirements
    • Extending Animation
    • Constraints on manipulating animation elements
    • Handling syntax errors
    • Error handling semantics

3.3Animation Model

This section describes the semantics underlying the SMIL 2.1 animationmodules. The specific elements are not described here, but rather the commonconcepts and syntax that comprise the model for animation.  Document issuesare described, as well as the means to target an element for animation. Theanimation model is then defined by building up from the simplest to the mostcomplex concepts: first the simple duration and simple animation functionf(t), and then the overall effectF(t,u). 

3.3.1The simple animationfunction f(t)

Animation is defined as a time-based function of atarget element(or more specifically of someattribute of the target element, thetarget attribute). The animation defines a mapping of time to valuesfor the target attribute. This mapping takes into account all aspects oftiming, as well as animation-specific semantics.  The overall mapping isbased on asimple animation functionf(t) which describes the animation over thesimple duration of the element. Every animation defines a simple animationfunction which produces a value for the target attribute for any time withinthe simple duration.

Normative

Atarget 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 CSSproperty that applies to the element.  By default, the target element of ananimation will be the parent of the animation element (an animation elementis typically a child of the target element). However, the target may be anyelement in the document, identified either by an XML ID reference or via anXLink[XLINK] locator reference.

As a simple example, the following defines an animation of an SVGrectangle shape.  The rectangle will change from being tall and thin tobeing 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 of100 pixels over the course of 10 seconds. Over the same ten seconds, theheight of the rectangle changes from 100 pixels to 10 pixels.

When an animation is running, it should not actually change the attributevalues in the DOM[DOM2].  The animation runtime should maintain apresentation value for each animated attribute, separate from theDOM or CSS Object Model (OM). If an implementation does not support an objectmodel, it should maintain the original value as defined by the document aswell as the presentation value. The presentation value is reflected in thedisplayed form of the document. Animations thus manipulate the presentationvalue, and should not affect thebase value exposed by DOM or CSSOM. This is detailed inTheanimation sandwich model.

Normative

Thebase value of a target attributea at timet is the value ofa to which animation is applied at timet.

Thepresentation value of a target attributea at timet is the value ofa resulting from the application of animation at timet.

The presentation value reflects theeffect of animation on thebase value. The effect is the change to the base value of the targetattribute at any given time. When an animation completes, the effect of theanimation is no longer applied, and the presentation value reverts to thebase value by default. The animation effect can also be extended tofreeze the last value for the length of time determined by thesemantics of thefill attribute.

An animation element defines asimple animation function which isevaluated as needed over time by the implementation. The resulting values areapplied to the presentation value for the target attribute. Animationfunctions are continuous in time and can be sampled at whatever frame rate isappropriate for the rendering system. The syntactic representation of thesimple animation function is independent of this model, and may be describedin a variety of ways. The animation elements in this specification supportsyntax for a set of discrete or interpolated values, a path syntax for motionbased upon SVG paths, keyframe based timing, evenly paced interpolation, andvariants on these features.

In the example immediately above, the simple animation function for thewidth attribute, specified by'from="10px" to="100px" ...dur="10s"' is

f(t) = (10 + 90*t/10) px, wheret is given in seconds.

Simple animation functions may be defined which have additionalparameters, or that are purely or partially algorithmic. For example, a "to"animation interpolates from the current value to the "to" value:

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

The animation function is a function of the current position, as well asof time:

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

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

Normative

Thesimple animation function defined by an animation element is a function of time,f(t), defined for timest,0<=t<=d, whered is the simple duration of the element.

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

Animations can be defined to either override or add to the base value ofan attribute. In this context, the base value may be the DOM value, or theresult of other animations that also target the same attribute. This moregeneral concept of a base value is termed theunderlying value.Animations that add to the underlying value are described asadditive animations. Animations that override the underlying valueare referred to asnon-additive animations. Theanimation effectfunction of an element is the function which includes the affect of theunderlying value and accounts for repeating and freezing of the element.Because the animation effect can be affected by repeating and freezing, it isdefined over the active duration of the element rather than its simpleduration.

Animations can be combined in ways which produce intermediate valuesoutside of the domain of the target attribute, but where the presentationvalue produced is valid. Thetype of a target attribute is thislarger set. This is detailed inThe animation sandwichmodel.

Normative

Thetype of a target attributea is the base type of which the domain ofa is a subset.

Theanimation effect function,F(t,u), of an animation element with active durationAD is a function mapping timest:0<=t<AD and valuesu of the type of the target attributea into values of the type ofa.

Theunderlying valueu of a target attributea of an animation elementat timet is the value ofa to which the animation effect is applied at timet.

The animation effect functionF(t,u) isusually defined as a function of the simple animation functionf(t).f(t) mustbe defined in such a manner thatF(t,u)produces values of the correct type.

3.3.2Summary of symbols used in thesemantic descriptions

a

The target attribute of an animation element.

d

The simple duration of the element.

AD

The active duration of the element.

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 attributea, generally at a specific timet.

f(t)

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

Note that whileF(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 functionf(t) with all the other aspects of animation and timing controls.

3.3.3The animation sandwichmodel

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

The remainder of this discussion uses the generic term OM for both the XMLDOM[DOM2] as well as the CSS-OM. If an implementation does not support anobject model, it should ideally maintain the original value as defined by thedocument 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 theOM.

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

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

The model accounting for the OM and concurrently active or frozenanimations for a given attribute is described as a "sandwich", a looseanalogy to the layers of meat and cheeses in a "submarine sandwich" (a longsandwich made with many pieces of meats and cheese layered along the lengthof the bread). In the analogy, time is associated with the length of thesandwich, and each animation has its duration represented by the length ofbread that the layer covers. On the bottom of the sandwich is the base valuetaken 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 timealong the length of the bread, as well as in order according topriority, with higher priority animations placed above (i.e. on topof) lower priority animations. At any given point in time, you can take aslice of the sandwich and see how the animation layers stack up.

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

Specifically, animating an attribute defined in XML will modify thepresentation value before it is passed through the style sheet cascade, usingthe XML DOM value as its base. Animating an attribute defined in a stylesheet language will modify the presentation value passed through theremainder 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, thecascade and the presentation rendering. When animation is applied to CSSproperties of a particular element, the base value to be animated is readusing the (readonly)getComputedStyle() method on that element.The values produced by the animation are written into an override stylesheetfor that element, which may be obtained using thegetOverrideStyle() method. These new values then affect thecascade and are reflected in a new computed value (and thus, modifiedpresentation). This means that the effect of animation overrides all stylesheet rules, except for user rules with the!important property.This enables!important user style settings to have priorityover animations, an important requirement for accessibility. Note that theanimation may have side effects upon the document layout. See alsosection6.1, "Specified, computed, and actual values," of[CSS2] andsection5.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 begunanimation has highest priority. When two animations start at the same momentin time, the activation order is resolved as follows:

• If one animation is atime dependent of another (e.g. it is specified to begin when another begins), then the time dependent is considered to activateafter the syncbase element, and so has higher priority. Time dependency is further discussed inPropagating 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 alsoRestarting animations), it will always moveto the top of the priority list, as it becomes the most recently activatedanimation. That is, when an animation restarts, its layer is pulled out ofthe sandwich, and added back on the very top.  In contrast, when an elementrepeats the priority is not affected (repeat behavior is not defined asrestarting).

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

Some attributes that support additive animation have a defined legal rangefor values (e.g. an opacity attribute may allow values between 0 and 1). Insome cases, an animation function may yield out of range values. It isrecommended that implementations clamp the results to the legal range as lateas possible, before applying them to the presentation value. Ideally, theeffect of all the animations active or frozen at a given point should becombined, before any clamping is performed. Although individual animationfunctions may yield out of range values, the combination of additiveanimations may still be legal. Clamping only the final result and not theeffect of the individual animation functions provides support for thesecases. Intermediate results may be clamped when necessary although this isnot optimal. The host language must define the clamping semantics for eachattribute that can be animated. As an example, this is defined foranimateColor element.

Initially, before any animations for a given attribute are active, thepresentation value will be identical to the original value specified in thedocument (the OM value).

When all animations for a given attribute have completed and theassociated animation effects are no longer applied, the presentation valuewill again be equal to the OM value. Note that if any animation is definedwithfill="freeze", theeffect of the animation will be applied as long as the animation elementremains in the frozen state, and so the presentation value will continue toreflect the animation effect. Refer also to the section "Freezing animations".

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

Note that any queries (via DOM interfaces) on the target attribute willreflect the OM value, and will not reflect the effect of animations. Notealso that the OM value may still be changed via the OM interfaces (e.g. usingscript). While it may be useful or desired to provide access to the finalpresentation value after all animation effects have been applied, such aninterface is not provided as part of SMIL Animation. A future version mayaddress this.

Although animation does not manipulate the OM values, the document displaymust reflect changes to the OM values. Host languages can support scriptlanguages that can manipulate attribute values directly in the OM. If ananimation is active or frozen while a change to the OM value is made, thebehavior is dependent upon whether the animation is defined to be additive ornot, as follows: (see also the sectionAdditive 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.3.4Animation elements as "continuousmedia"

Within the timing model, animation is considered to be "continuous" media.The animation elements defined in SMIL Animation do not have a naturalintrinsic duration, so they are assigned an intrinsic duration ofindefinite.

This has several consequences, which are noted in various sections below.In particular, most animation elements will have an explicit duration setwith thedur attribute, since a finite,known duration is required for interpolation.

3.3.5The animation effect functionF(t,u)

As described above, the simple animation functionf(t) defines the animation for the simpledurationd. However, SMIL Timing allows theauthor to repeat the simple duration. SMIL Timing also allows authors tospecify whether the animation should simply end when the active durationcompletes, or whether it should befrozen at the last value. SMILAnimation specifies what it means for an animation to be frozen.  Inaddition, the author can specify how each animation should be combined withother animations and the original DOM value.

This section describes the semantics for the additional functionality,including a detailed model for combining animations. This is presented as asequence of functions building on the simple animation function:

• Therepeated animation function,fr(t), defines the effect of repeating an animation element.
• Thecumulative animation function,fc(t), defines the effect of accumulating values from one iteration to the next of a repeated animation element.
• Thefrozen animation function,ff(t), includes the effect of freezing an animation element at the end of its active duration.
• The animation effect function,F(t,u), defines how a an animation element depends on the underlying valueu of the target attribute.

Since these functions describe the animation outside of the simpleduration, they are defined for any timet:0<=t<AD . The frozen animation functionff(t),is additionally defined fort=AD, to account for the case when the element is frozen.

Repeating animations

As described in the sectionInterval timingof the BasicInlineTiming module, repeating an element causes the element tobe "played" several times in sequence. The repeated period is 0 to the simpleduration of the element. Animation follows this model, where "playing" theanimation means applying the simple animation functionf(t) repeatedly.

Normative

Therepeated animation function,fr(t), for any simple animation functionf(t) is

fr(t) =f( REMAINDER( t, d ) ),

wheret>=0,d is the simple duration , andREMAINDER( t, d ) is defined as(t - d*floor(t/d)).

This formulation follows the end-point exclusive model described inInterval timing.As an animation repeats, it starts atf(0), issampled and applied up to but not including the end-pointf(d). At the end of the simple duration, i.e.at the beginning of the next iteration, it starts back atf(0).f(d) maynever actually be applied.

Examples

In the following example, the 2.5 second animation function will berepeated twice; the active duration will be 5 seconds. The attribute top willgo from 0 to (almost) 10, return to 0 at 2.5 seconds, and repeat.

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

In the following example, the animation function will be repeated two fulltimes and then the first half is repeated once more; the active duration willbe 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 totalof 7 seconds. It will play fully two times, followed by a fractional part of2 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" />

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

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

Note that if the simple duration is not defined (e.g. it is indefinite),repeat behavior is not defined (butrepeatDur still defines the activeduration). In the following example the simple duration is indefinite, and sotherepeatCount is effectivelyignored. Nevertheless, this is not considered an error: the active durationis also indefinite. The effect of the animation is to to just use the valueforf(0), setting the fill color to red forthe remainder of the animate element's duration.

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

In the following example, the simple duration is indefinite, but therepeatDur still determines the activeduration. The effect of the animation is to set the fill color to red for 10seconds.

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

In the following example, the simple duration is longer than the durationspecified byrepeatDur, and so theactive duration will effectively cut short the simple duration. However, theanimation function still interpolates using the specified simple duration.The effect of the animation is to interpolate the value of "top" from 10 to17, over the course of 7 seconds.

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

Controlling behavior of repeatinganimation - Cumulative animation

The author may also select whether a repeating animation should repeat theoriginal behavior for each iteration, or whether it should build upon theprevious results, accumulating with each iteration. For example, a motionpath that describes an arc can repeat by moving along the same arc over andover again, or it can begin each repeat iteration where the last left off,making the animated element bounce across the window. This is calledcumulative animation.

Normative

Every animation element must be defined as eithercumulative ornon-cumulative. An animation element may be defined as cumulative only if addition is defined for the target attribute. Thecumulative animation function,fc(t), for any simple animation functionf(t) is

fc(t) =fr(t), if the element is non-cumulative.

If the element is cumulative:

Letfi(t) represent the cumulative animation function for a given iterationi.

The first iterationf0(t) is unaffected byaccumulate, and so is the same as the original simple animation function definition. Each subsequent iteration adds to the result of the previous iterations:

f0(t) = f(t)

fi(t) = (f(d) * i) + f(t - (i*d))  for any integer i > 0.

The cumulative animation function is then

fc(t) =fi(t), wherei = floor(t/d).

Note thatfi+1(t)starts atf(d)*i + f(0). To avoid jumps, authors willtypically choose animation functions which start at 0.

For example, the path notation for a simple arc (detailed inThe animateMotion element) canbe used to describe a bouncing motion:

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

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

Figure 1 - Illustration of repeating animation withaccumulate="sum".

Figure 1 - A cumulative repeating animation. Each repeatiteration builds upon the previous.

Note that cumulative animation only controls how a single animationaccumulates the results of the simple animation function as it repeats. Itspecifically does not control how one animation interacts with otheranimations to produce a presentation value. This latter behavior is describedin the sectionAdditive animation.Similarly, if an element restarts, the accumulate from the first run is notapplied to the second. SeeRestartinganimations.

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

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

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

Freezing animations

Animation elements follow the definition offill in the Timing module. This sectionextends that specification to cover animation-specific semantics.

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

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

As shown in Figure 2, the image will appear stationary at the top value of"3" for 5 seconds, then move 100 pixels down in 10 seconds. 15 seconds afterthe document begin, the animation ends, the effect is no longer applied, andthe image jumps back from 103 to 3 where it started (i.e. to the underlyingDOM value of thetop attribute).

Figure 2 - Illustration of animation without freezing.

Figure 2 - Simple animation without freezing. After theanimate element ends, the effect of the animation is removed.

Thefill attribute can be used tomaintain the value of the animation after the active duration of theanimation 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 imageremains at the top value of 103 (Figure 3). The attributefreezesthe last value of the animation for the duration of the freeze effect. Thisduration is controlled by the time container (for details, seeSMIL Timing andSynchronization).

Figure 3 - Illustration of animation withfill="freeze".

Figure 3 - Simple frozen animation. After theanimate element ends, the effect of the animation is retained.

If the active duration cuts short the simple duration (including the caseof partial repeats), the effect value of a frozen animation isdefined by the shortened simple duration. In the following example, thesimple animation function repeats two full times and then again for one-halfof the simple duration. In this case, the value while frozen willbe 53: 

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

Figure 4 - Illustration of animation combining a partialrepeat andfill="freeze".

In the following example, thedurattribute is missing, and so the simple duration is indefinite. The activeduration is constrained byend to be 10seconds. Interpolation is not defined, and the value while frozenwill be thefrom value,10:

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

Stating this formally:

Normative

Thefrozen animation function,ff(t), for an element with active durationAD, is given by

ff(t) = fc(t) for all timest:0<=t<AD (i.e. before it is frozen)

When the element is frozen,t is effectively equal toAD.

The following equations assume thatt is set toAD when the element is frozen.

IfAD is not an even multiple of the simple duration d,ff(t) = fi(t), wherei = floor(t/d).

This is equivalent tofc(t), except thatfc(t) is not formally defined fort=AD. In this case, the equations remain consistent, and so the equivalent offc(t) is used for the frozen valueff(t).

IfAD is an even multiple ofd, i.e.AD = d*i for some positive integeri , and the animation is non-cumulative,
ff(t) = f(d).

IfAD is an even multiple of d, i.e.AD = d*i for some positive integeri, and the animation is cumulative,

ff(t) = f(d) * i.

Note thatf(d) is a shorthand for the "last value defined for the animation function" (e.g., the "to" value or the last value in the "values" list).

3.3.6Additive animation

In addition to repeating and accumulating values of a single animation, ananimation may be expressed as a delta to an attribute's value, rather than asan absolute value. This can be used in a single animation to modify theunderlying DOM value, or complex animations can be produced by combiningseveral simple ones.

For example, a simple "grow" animation can increase the width of an objectby 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 courseof 10 seconds.  If the animation were declared to be non-additive, the samefrom and to values would make the width go from 0 to 10 pixels over 10seconds.

Many complex animations are best expressed as combinations of simpleranimations. A "vibrating" path, for example, can be described as a repeatingup 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>

Theanimation effect function, captures thesemantics of this for a single animation element:

Normative

Every animation element must be defined as eitheradditive ornon-additive. An element may be defined as additive only if addition is defined for type type of the target attribute.

If the animation is additive, F(t,u) = u + ff(t).

If the animation is non-additive, F(t,u) = ff(t).

When there are multiple animations defined for a given attribute thatoverlap at any moment, the two either add together or one overrides theother. Animations overlap when they are both either active or frozen at thesame moment. The ordering of animations (e.g. which animation overrideswhich) is determined by a priority associated with each animation. Theanimations are prioritized according to when each begins. The animation firstbegun has lowest priority and the most recently begun animation has highestpriority.

Higher priority animations that are not additive will override all earlier(lower priority) animations, and simply set the attribute value.  Animationsthat are additive apply (i.e. add to) to the result of the earlier-activatedanimations. For details on how animations are combined, seeThe animation sandwichmodel.

Additive animation is defined for numeric attributes and other data typesfor which an addition function is defined. This includes numeric attributesfor concepts such as position, widths and heights, sizes, etc. This alsoincludes color (refer toTheanimateColor element), and may include other data types as specified bythe host language.

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

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

The image moves along the first path, and then starts the second path fromthe end of the first, then follows the third path from the end of the second,and stays at the final point.

While many animations of numerical attributes will be additive, this isnot always the case. As an example of an animation that is defined to benon-additive, consider a hypothetical extension animation "mouseFollow" thatcauses 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 mousesover the image. It cannot be additive, or it will just offset the motion pathin some odd way. ThemouseFollow needs to override theanimateMotion while it is active.When themouseFollow completes, its effect is no longer appliedand theanimateMotion againcontrols 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 specifywhich attributes support additive animation. Attribute types for whichaddition is not defined, such as strings and Booleans, cannot supportadditive animation.

Additive and Cumulative animation

Theaccumulate attributeshould not be confused with theadditive attribute. Theadditive attribute defines how ananimation is combined with other animations and the base value of theattribute.  Theaccumulateattribute defines only how the simple animation function interacts withitself, across repeat iterations.

Typically, authors expect cumulative animations to be additive (as in theexamples described foraccumulateabove), but this is not required. Thefollowing example is cumulative but not additive.

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

The animation overrides whatever original value was set for "top", andbegins at the value 20. It moves down by 10 pixels to 30, then repeats. It iscumulative, so the second iteration starts at 50 (the value of 30 from theprevious iteration plus thefrom value,20) and moves down by another 10 to 60, and so on.

When a cumulative animation is also defined to be additive, the twofeatures function normally. The accumulated effect forF(t,u) is used as the value for the animation,and is added to the underlying value for the target attribute. Forexample:

<img top="10" ... >  <animate dur="10s" repeatdur="indefinite"           attributename="top" from="20" by="10"additive="sum" accumulate="sum" /></img>

The animation adds to the original value of 10 that was set for "top", andbegins at the value 30. It moves down by 10 pixels to 40, then repeats. It iscumulative, so the second iteration starts at 60 (the value of 40 from theprevious iteration plus 20) and moves down by another 10 to 70, and so on.

Refer also toThe animationsandwich model.

3.3.7Restarting animations

Animation elements follow the definition of restart in theSMIL Timing module. This section isdescriptive.

When an animation restarts, the defining semantic is that it behaves asthough this were the first time the animation had begun, independent of anyearlier behavior. The animation effect functionF(t,u) is defined independent of the restartbehavior. Any effect of an animation playing earlier is no longer applied,and only the current animation effectF(t,u) isapplied.

If an additive animation is restarted while it is active or frozen, theprevious effect of the animation (i.e. before the restart) is no longerapplied to the attribute. Note in particular that cumulative animation isdefined only within the active duration of an animation. When an animationrestarts, all accumulated context is discarded, and the animation effectF(t,u) begins accumulating again from the firstiteration of the restarted active duration.

3.3.8Animation functionvalue details

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

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

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

In all cases, the animation effect function,F(t,u), must yield legal values for the targetattribute. Three classes of values are described:

1. Unitless scalar values. These are simple scalar values that can be parsed and set without semantic constraints. This class includes integers (base 10) and floating point (format specified by the host language).
2. String values. These are simple strings.
3. Language abstract values. These are values like CSS-length and CSS-angle values that have more complex parsing, but that can yield values that may be interpolated.

Theanimate element caninterpolate unitless scalar values, and bothanimate andset elements can handle String values withoutany semantic knowledge of the target element or attribute. Theanimate andset elements must support unitless scalarvalues and string values. The host language must define which additionallanguage abstract values should be handled by these elements. Note that theanimateColor element implicitlyhandles the abstract values for color values, and that theanimateMotion element implicitlyhandles position and path values. 

In order to support interpolation on attributes that define numeric valueswith some sort of units or qualifiers (e.g. "10px", "2.3feet", "$2.99"), someadditional support is required to parse and interpolate these values. Onepossibility is to require that the animation framework have built-inknowledge of the unit-qualified value types. However, this violates theprinciple of encapsulation and does not scale beyond CSS to XML languagesthat define new attribute value types of this form.

The recommended approach is for the animation implementation for a givenhost environment to support two interfaces that abstract the handling of thelanguage abstract values. These interfaces are not formally specified, butare simply described as follows:

1. The first interface converts a string (the animation function value) to a unitless, canonical number (either an integer or a floating point value). This allows animation elements to interpolate between values without requiring specific knowledge of data types like CSS-length. The interface will likely require a reference to the target attribute, to determine the legal abstract values. If the passed string cannot be converted to a unitless scalar, the animation element will treat the animation function values as strings, and thecalcMode will default to "discrete".
2. The second interface converts a unitless canonical number to a legal string value for the target attribute. This may, for example, simply convert the number to a string and append a suffix for the canonical units. The animation element uses the result of this to actually set the presentation value.

Support for these two interfaces ensures that an animation engine need notreplicate the parser and any additional semantic logic associated withlanguage abstract values. 

This is not an attempt to specify how an implementation provides thissupport, but rather a requirement for how values are interpreted. Animationbehaviors should not have to understand and be able to convert among all theCSS-length units, for example. In addition, this mechanism allows forapplication of animation to new XML languages, if the implementation for alanguage can provide parsing and conversion support for attribute values.

The above recommendations notwithstanding, it is sometimes useful tointerpolate values in a specific unit-space, and to apply the result usingthe specified units rather than canonical units. This is especially true forcertain relative units such as those defined by CSS (e.g. em units). If ananimation specifies all the values in the same units, an implementation mayuse knowledge of the associated syntax to interpolate in the unit space, andapply the result within the animation sandwich, in terms of the specifiedunits rather than canonical units. As noted above, this solution does notscale well to the general case. Nevertheless, in certain applications (suchas CSS properties), it may be desirable to take this approach.

Interpolation andindefinite simple durations

If the simple duration of an animation is indefinite (e.g. if nodur value is specified), interpolation is notgenerally meaningful. While it is possible to define an animation functionthat is not based upon a defined simple duration (e.g. some random numberalgorithm), most animations define the function in terms of the simpleduration. If an animation function is defined in terms of the simple durationand the simple duration is indefinite, the first value of the animationfunction (i.e.f(0)) should be used(effectively as a constant) for the animation function.

3.4Overview of the SMIL 2.1BasicAnimation Module

The SMIL 2.1 BasicAnimation module provides

• Syntax for identifying target elements and attributes,
• 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.
• Theanimate element for generic animation.
• Theset element for simply setting the value of the target attribute to a constant value
• TheanimateMotion element for defining motion on a path. And
• TheanimateColor element for defining color changes over time.

The BasicAnimation module defines attributes and elements following themodel presented in theAnimationModel section.

3.5SMIL 2.1 BasicAnimation Module CommonAttributes

The elements of the BasicAnimation module have in common the attributesused to identify the target attribute and, less universally, the attributesby which the animation functions are specified.

3.5.1Specifying the animationtarget

The animation target is defined as a specific attribute of a particularelement. The means of specifying the target attribute and the target elementare detailed in this section.

The targetattribute

The target attribute to be animated is specified withattributeName. The value of thisattribute is a string that specifies the name of the target attribute, asdefined in the host language.

The attributes of an element that can be animated are often defined bydifferent languages, and/or in different namespaces. For example, in many XMLapplications, the position of an element (which is a typical targetattribute) is defined as a CSS property rather than as XML attributes. Insome cases, the same attribute name is associated with attributes orproperties in more than one language, or namespace.  To allow the author todisambiguate the name mapping, an additional attributeattributeType is provided thatspecifies the intended namespace. 

TheattributeType attributeis optional. By default, the animation runtime will resolve the namesaccording to the following rule: If there is a name conflict andattributeType is not specified, thelist of CSS properties supported by the host language is matched first (ifCSS is supported in the host language); if no CSS match is made (or CSS doesnot apply) the per-element-type partition namespace for the target elementwill be matched.

If a target attribute is defined in an XML Namespace other than theper-element-type partition namespace for the target element, the author mustspecify the namespace of the target attribute using the associated namespaceprefix as defined in the scope of the animation element. The prefix isprepended to the value forattributeName.

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

The target element

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

If no explicit target is specified, the implicit target element is theparent element of the animation element in the document tree. It is expectedthat the common case will be that an animation element is declared as a childof the element to be animated. In this case, no explicit target need bespecified.

If an explicit target element reference cannot be resolved (e.g. if nosuch element can be found), the animation has no effect. In addition, if thetarget element (either implicit or explicit) does not support the specifiedtarget attribute, the animation has no effect. See alsoHandling syntax errors.

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

When integrating animation elements into the host language, the languagedesigner should avoid including both of these attributes. If however, thehost language designer chooses to include both attributes in the hostlanguage, then when both are specified for a given animation element theXLinkhref attribute takesprecedence over thetargetElement attribute.

The advantage of using thetargetElement attribute is thesimpler syntax of the attribute value compared to thehref attribute. The advantage ofusing the XLinkhref attributeis that it is extensible to a full linking mechanism in future versions ofSMIL Animation, and the animation element can be processed by generic XLinkprocessors. The XLink form is also provided for host languages that aredesigned to use XLink for all such references. The following two examplesillustrate the two approaches.

This example uses the simplertargetElement syntax:

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

This example uses the more flexible XLink locater syntax, with theequivalent target:

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

When using an XLinkhrefattribute on an animation element, the following additional XLink attributesneed to be defined in the host language. These may be defined in a DTD, orthe host language may require these in the document syntax to support genericXLink processors. For more information, refer to[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 otherXLink attributes are optional, and do not affect SMIL Animation semantics.

Additional details on the target element specification as relates to thehost document and language are described inRequired definitions andconstraints on animation targets.

3.5.2Specifying the simpleanimation function f(t)

Every animation function defines the value of the attribute at aparticular moment in time. The time range for which the animation function isdefined is the simple duration. The animation function does not producedefined results for times outside the range of 0 to the simple duration.

An animation is described either as a list ofvalues, or in asimplified form that describes thefrom,to andbyvalues. The from/to/by form is defined inSimple animation functions defined by from, toand by.

The animation will apply the values in order over the course of theanimation. Fordiscrete andlinear animations, values in thevalues attribute are equally spaced throughthe animation duration. Forpaced animations, thevalues are spaced so that a uniform rate of change is obtained.

The following example using thevalues syntax animates the width of an SVGshape over the course of 10 seconds, interpolating from a width of 40 to awidth of 100 and back to 40.

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

The simple animation function for this example (with time in seconds)is

f(t) = 40 + 60*t/5,       0 <= t < 5, and
f(t) = 100 - 60*(t-5)/5,  5 <= t <=10.

The simple animation function defined by thevalues andcalcMode attributes can be formallyspecified:

Normative

Leti =floor((t*n)/d),d be the simpleduration of the animation element,n be thenumber of entries in thevalues attribute,value[i] be theith entry (counting from 0),di be the duration of the theith time period, andti be the time at which the theith time period begins.

• Fordiscrete animation, with nokeyTimes attribute, the duration is divided inton equal time periods, one per value. With a keyTimes attribute, the time periods are specified by the keyTimes values. The animation function takes on the values in order, one value for each time period:

      f(t) = value[i]

• Forlinear animation with nokeyTimes attribute, the duration is divided inton-1 equal periods, anddi = d/(n-1) for any value ofi. The animation function is a linear interpolation between the values at the associated times:

        f(t) = value[i] + (value[i+1]-value[i]) * (t-ti)/di.

  With a keyTimes attribute, the time periods are specified by the keyTimes values and sodi is the duration of theith period as defined by the keyTimes values:

  di = (keyTimes[i+1] - keyTimes[i]) * d

• Forpaced animations, the duration is divided into periods of lengths such that the rate of change of the attribute remains constant. If the distance between two values isdist(v1,v2), the total distance traversedD(i) up to and includingvalue[i] is

  D(0) = 0, and

  D(i) = dist(value[0],value[1]) + dist(value[1],value[2]) +...+ dist(value[i-1],value[i]), for integersi with0<i<=n.

  The animation function takes on the values in thevalues attribute at times determined by these distances:

   ti = (D(i)/D(n)) * d, for integersi with0<=i<=n.

  di = ti+1 - ti = ((D(i+1) - D(i)) / D(n)) * d = (dist(value[i],value[i+1]) / D(n)) * d

   f(t) = value[i] + (value[i+1]-value[i]) * (t-ti)/ di

  wherei is the largest non-negative integer such that ti<=t.

Note that alinear orpaced animation will be a smoothly closedloop if the first value is repeated as the last. The keyTimes attribute isdescribed in theSplineAnimationsection.

Interpolation modesillustrated

The three figures 5a, 5b and 5c below show how the same basic animationwill change a value over time, given different interpolation modes.  Allexamples are based upon the following example, but with different values forcalcMode:

<animate dur="30s" values="0; 6; 5; 11; 10; 16" calcMode="[as specified]" />

Figure 5 - Discrete, linear and paced animation

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

Examples of calcMode

The following example describes a simple discrete animation:

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

The value of the attribute "foo" will be set to each of the four stringsfor 2 seconds each. Because the string values cannot be interpolated, onlydiscrete animation is possible; anycalcMode attribute would be ignored.

The following example describes a simple linear animation:

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

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

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

To produce an even pace of change to the attribute "x", the second segmentdefined by the values list gets most of the simple duration: The value of "x"will change from 0 to 10 in the first second, and then from 10 to 100 in thenext 9 seconds. While this example could be easily authored as afrom-toanimation without paced interpolation, manyexamples (such as motion paths) are much harder to author without thepaced value forcalcMode. 

3.5.3Specifying the animationeffect function F(t,u)

As described inThe animationeffect function F(t,u), the simple animation function may be

• Repeated or frozen, using the attributesrepeatCount,repeatDur andfill of theBasicInlineTiming module.
• Defined as cumulative or non-cumulative when repeated.
• Defined as additive or non-additive when combined with the underlying value.

The animation effect functionF(t,u) defines the semantics of these attributes, and give examples. Thissection gives only the syntax.

See theBasicInlineTiming modulefor definitions of the attributesrepeatCount,repeatDur andfill.

The additive and cumulative behavior of repeating animations is controlledwith theadditive andaccumulate attributes, respectively:

3.5.4Simple animation functions specified byfrom, to and by

An animation is described either as a list ofvalues, asdescribed earlier, or in a simplified form that usesfrom,to andby values.

The simplerfrom/to/bysyntax provides for several variants. To use one of these variants, one ofby orto must be specified; afrom value is optional. It is not legal tospecify bothby andto attributes; if both are specified, only theto attribute will be used (theby will be ignored). The combinations ofattributes yield the following classes of animation.

from-toanimation

Specifying afrom value and ato value defines a simple animation. The animation function is defined to start with thefrom value, and to finish with theto value.

Normative: Afrom-toanimation with afrom valuevf and ato valuevt is equivalent to the same animation with avalues list with 2 values,vf andvt.

from-byanimation

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

Normative: Afrom-by animation with afrom valuevf and aby valuevb is equivalent to the same animation with avalues list with 2 values,vf and(vf+vb).

byanimation

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

Normative: Aby animation with aby valuevb is equivalent to the same animation with avalues list with 2 values,0 andvb, andadditive="sum". Any other specification of theadditive attribute in aby animation is ignored.

toanimation

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 theto attribute. Using this form, an author can describe an animation that will start with any current value for the attribute, and will end up at the desiredto value.

A normative definition of atoanimation is given below inToanimation

Examples

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

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

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

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

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

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

From-to andfrom-by animations also support cumulativeanimation, as in the following example:

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

The rectangle will grow from 10 to 20 pixels in the first 5 seconds, andthen from 20 to 30 in the next 5 seconds, and so on up to 110 pixels after 10repeats. Note that since the default value foradditive isreplace, the original value is ignored. The followingexample makes the animation explicitly additive:

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

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

To animation

Atoanimation of an attribute which supports additionis a kind of mix of additive and non-additive animation. The underlying valueis used as a starting point as with additive animation, however the endingvalue specified by theto attributeoverrides the underlying value as though the animation was non-additive.

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

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

Since ato animation has only 1 value, a discretetoanimation will simply set thetovalue for the simple duration. In the following example, the rect will beblue for the 10 second duration of the animate element.

<rect color="red"...>   <animate attributeName="color" to="blue" dur="10s" calcMode="discrete"/></rect>

The semantics oftoanimation fit into the generalanimation model, but with a few special cases. The normative definition givenhere parallels the definition for other types of animation presented in theAnimation Model section.

Normative

The simple animation functionf(t,u) for ato animation withto valuevt is a linear interpolation between the underlying value,u, and theto value:

f(t,u) = (u * (d-t)/d) + (vt * t/d), fort:0<=t<=d whered is the simple duration.

If no other (lower priority) animations are active or frozen, this definessimple interpolation. However if another animation is manipulating theunderlying value, theto animation will initially add to the effectof the lower priority animation, and increasingly dominate it as it nears theend of the simple duration, eventually overriding it completely. The valueforf(t,u) at the end of the simple duration isjust theto value.

Repeatingto animations is the same as repeating otheranimations:

Normative

Therepeated animation function,fr(t,u), has the standard definition:

fr(t,u) =f( REMAINDER(t,d), u ).

Becauseto animation is defined in terms of absolute values ofthe target attribute, cumulative animation is not defined:

Normative

Thecumulative animation function,fc(t), for ato animation is

fc(t,u) =fr(t,u).

A frozento animation takes on the value at the time it isfrozen, masking further changes in the underlying value. This matches thedominance of theto value at the end of the simple duration.Even if other, lower priority animations are active while atoanimation is frozen, the value does not change.

Normative

Thefrozen animation function,ff(t), for ato animation is

ff(t,u)= fc(t,u), if the animation is not frozen at timet, and

ff(t,u)= vf, if the animation is frozen at timet, wherevf is the value offf(t,u) at the moment the animation was frozen.

For example, consider

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

The width will animate from 40 to 100 pixels in the first 10 seconds,repeat 40 to 100 in the second 10 seconds, go from 40 to 70 in the final 5seconds, and freeze at 70.

To animation defines its own kind of additive semantics, so theadditive attribute is ignored.

Normative

The animation effect function,F(t,u) for ato animation is

F(t,u)=ff(t,u).

Multipleto animations will also combine according to thesesemantics. As the animation progresses, the higher-priority animation willhave greater and greater effect, and the end result will be to set theattribute to the final value of the higher-priorityto animation.

For an example of additiveto animation, consider the followingtwo additive animations. The first, aby-animation applies a deltato attribute "x" from 0 to -10. The second, ato animation animatesto a final value of 10.

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

The presentation value for "x" in the example above, over the course ofthe 10 seconds is presented in Figure 6 below. These values are simplycomputed using the formula described above. Note that the value forF(t,u) for A2 is the presentation value for"x", since A2 is the higher-priority animation.

Figure 6 - Effect of Additiveto animationexample

Time	F(t,u) for A1	F(t,u) 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

3.6SMIL 2.1 BasicAnimationElements

The SMIL BasicAnimation module defines four elements,animate,set,animateMotion andanimateColor.

3.6.1The animate element

Theanimate elementintroduces a generic attribute animation that requires little or no semanticunderstanding of the attribute being animated. It can animate numeric scalarsas well as numeric vectors. It can also animate a single non-numericattribute through a discrete set of values. Theanimate element is an empty element; itcannot have child elements.

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

Numerous examples are provided above, as are normative definitions of thesemantics of all attributes supported byanimate.

3.6.2The set element

Theset element providesa simple means of just setting the value of an attribute for a specifiedduration. As with all animation elements, this only manipulates thepresentation value, and when the animation completes, the effect is no longerapplied. That is,set does notpermanently set the value of the attribute. 

Theset element supports allattribute types, including those that cannot reasonably be interpolated andthat more sensibly support semantics of simply setting a value (e.g. stringsand Boolean values). Theset element isnon-additive. The additive and accumulate attributes are not allowed, andwill be ignored if specified.

Theset element supports all thetiming attributes to specify the simple and active durations. However, therepeatCount andrepeatDur attributes will just affectthe active duration of theset,extending the effect of theset (sinceit is not really meaningful to "repeat" a static operation). Note that usingfill="freeze" withset will have the same effect as defining thetiming so that the active duration is indefinite.

Theset element supports a morerestricted set of attributes than the animate element. Only one value isspecified, and neither interpolation control nor additive or cumulativeanimation is supported:

Normative

The simple animation function defined by aset element is

f(t) = v

werev is the value of theto attribute.

Theset element is non-cumulative and non-additive.

Examples

The following changes the stroke-width of an SVG rectangle from theoriginal value to 5 pixels wide. The effect begins at 5 seconds and lasts for10 seconds, after which the original value is again used.

<rect ...>   <set attributeName="stroke-width" to="5px"             begin="5s" dur="10s" fill="remove" /></rect>

The following example sets theclass attribute of the textelement to the string "highlight" when the mouse moves over the element, andremoves the effect when the mouse moves off the element. 

<text>This will highlight if you mouse over it...   <set attributeName="class" to="highlight"             begin="mouseover" end="mouseout" /></text>

3.6.3The animateMotionelement

TheanimateMotion element will move an element along apath. The element abstracts the notion of motion and position across avariety of layout mechanisms - the host language defines the layout model andmust specify the precise semantics of position and motion. The path can bedescribed in either of two ways:

• Specifying an x,y pair for each of thefrom/to/by attributes. These will define a straight line motion path.
• Specifying a semicolon separated list of x,y pairs for thevalues attribute. This will define a motion path of straight line segments, or points (ifcalcMode is set to discrete). This will override anyfrom/to/by attribute values.

All values must be x, y value pairs. Each x and y value may specify anyunits supported for element positioning by the host language. The hostlanguage defines the default units. In addition, the host language definesthereference point for positioning an element. This is the pointwithin the element that is aligned to the position described by the motionanimation. The reference point defaults in some languages to the upper leftcorner of the element bounding box; in other languages the reference pointmay be implicit, or may be specified for an element.

The syntax for the x, y value pairs is:

coordinate-pair ::= "("coordinatecomma-wspcoordinate")"coordinate      ::=numnum             ::=Number

Coordinate values are separated by at least one white space character or acomma. Additional white space around the separator is allowed. The values ofcoordinate must be defined as some sort of number in the hostlanguage.

TheattributeName andattributeType attributes are notused withanimateMotion, asthe manipulated position attribute(s) are defined by the host language. Ifthe position is exposed as an attribute or attributes that can also beanimated (e.g. as "top" and "left", or "posX" and "posY"), implementationsmust combineanimateMotionanimations with other animations that manipulate individual positionattributes. See alsoTheanimation sandwich model.

If none of thefrom,to,by andvaluesattributes are specified, theanimation will have no effect.

The default calculation mode (calcMode) foranimateMotion ispaced. This will produce constant velocity motion alongthe specified path. Note that while animateMotion elements can be additive,the addition of two or morepaced (constantvelocity) animations may not result in a combined motion animation withconstant velocity.

3.6.4The animateColorelement

TheanimateColorelement specifies an animation of a color attribute. The host language mustspecify those attributes that describe color values and can support coloranimation.

All values must represent[sRGB] colorvalues. Legal value syntax for attribute values is defined by the hostlanguage.

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

The values in thefrom/to/by andvalues attributes may specifynegative and out of gamut values for colors.  The function defined by anindividualanimateColor mayyield negative or out of gamut values.  The implementation must correct theresulting presentation value, to be legal for the destination (display)colorspace. However, as described inThe animation sandwich model,the implementation should only correct the final combined result of allanimations for a given attribute, and should not correct the effect ofindividual animations.

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

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

Note to implementers: WhenanimateColor is specified as atoanimation, the animation function should assume Euclidean RGB-cubedistance where deltas must be computed. See alsoSpecifying the simpleanimation function f(t) andSimple animation functions specified by from, toand by. Similarly, when thecalcMode attribute foranimateColor is set topaced, the animation function should assume EuclideanRGB-cube distance to compute the distance and pacing.

3.7SMIL 2.1 BasicAnimation ModuleDetails

3.7.1BasicAnimation integrationrequirements

This section describes what a language designer must actually do tospecify the integration of SMIL Animation into a host language. This includesbasic definitions and constraints upon animation.

In addition to the requirements listed in this section, those listed inCommon animation integrationrequirements must be satisfied.

Requireddefinitions and constraints on animation targets

Specifying the target element

The host language designer must choose whether to support thetargetElement attribute or the XLinkattributes forspecifying thetarget element. Note that if the XLink syntax is used, the host languagedesigner must decide how to denote the XLink namespace for the associatedattributes. The namespace can be fixed in a DTD, or the language designer canrequire colonized attribute names (qnames) to denote the XLinknamespace for the attributes. The required XLink attributes have fixedvalues, and so may also be specified in a DTD, or can be required on theanimation elements. Host language designers may require that the optionalXLink attributes be specified. These decisions are left to the host languagedesigner - the syntax details for XLink attributes do not affect thesemantics of SMIL Animation.

In general, target elements may be any element in the document. Hostlanguage designers must specify any exceptions to this. Host languagedesigners are discouraged from allowing animation elements to target elementsoutside of the document in which the animation element is defined. The XLinksyntax for the target element could allow this, but the SMIL timing andanimation semantics of this are not defined in this version of SMILAnimation.

Target attribute issues

The definitions in this module can be used to animate any attribute of anyelement in a host document. However, it is expected that host languagedesigners integrating SMIL Animation may choose to constrain which elementsand attributes can support animation. For example, a host language may choosenot to support animation of thelanguage attribute of ascript element. A host language which included a specificationfor DOM functionality might limit animation to the attributes which maylegally be modified through the DOM.

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

All constraints upon animation must be described in the host languagespecification or in an appropriate schema, as the DTD alone cannot reasonablyexpress this.

The host language must define which language abstract values should behandled for animated attributes. For example, a host language thatincorporates CSS may require that CSS length values be supported. This isfurther detailed inAnimation function valuedetails.

The host language must specify the interpretation of relative values. Forexample, if a value is specified as a percentage of the size of a container,the host language must specify whether this value will be dynamicallyinterpreted as the container size is animated.

The host language must specify the semantics of clamping values forattributes. The language must specify any defined ranges for values, and howout of range values will be handled.

The host language must specify the formats supported for numeric attributevalues. This includes both integer values and floating point values. As areasonable minimum, host language designers are encouraged to support theformat described insection 4.3.1,"Integers and real numbers," of[CSS2].

Integrating animateMotionfunctionality

The host language specification must define which elements can be thetarget ofanimateMotion. Inaddition, the host language specification must describe the positioning modelfor elements, and must describe the model foranimateMotion in this context (i.e.the semantics of thedefault value for theorigin attribute must be defined). If thereare different ways to describe position, additional attribute values for theorigin attribute should be defined toallow authors control over the positioning model.

3.7.2Document type definition (DTD) for theBasicAnimation module

See the fullDTD for the SMILAnimation Modules.

3.8Overview of the SMIL 2.1SplineAnimation Module

This section defines the functionality of the SMIL 2.1 SplineAnimationmodule. This module adds attributes for spline interpolation and for unevenspacing of points in time. These attributes may be used inanimate,animateMotion andanimateColor elements.

3.8.1SMIL 2.1 SplineAnimation ModuleAttributes

Spline animation functioncalculation mode

The SplineAnimation module extends thediscrete,linear andpaced calculation modes of the BasicAnimation module,providing additional control over interpolation and timing:

• ThecalcMode attribute is extended to support splines.
• Apath attribute is added to theanimateMotion element, allowing authors to define a motion path using a subset of the SVG[SVG] path syntax, and providing smooth path motion.
• ThekeyTimes attribute provides additional control over the timing of the animation function, associating a time with each value in thevalues list (or the points in apath description for theanimateMotion element).
• ThekeySplines attribute provides a means of controlling the pacing of interpolationbetween the values in thevalues list.

This semantic (the duration is divided inton-1 even periods)applies as well when thekeySplines attribute is specified, butkeyTimes is not. The timesassociated to thekeySplinesvalues are determined as described above.

The syntax for the control point sets inkeySplines lists is:

control-pt-set ::= (fpvalcomma-wspfpvalcomma-wspfpvalcomma-wspfpval )

Using:

fpval          ::=Floating point numberS              ::=spacechar*comma-wsp      ::=S (spacechar|",")Sspacechar      ::= (#x20 | #x9 | #xD | #xA)

Control point values are separated by at least one white space characteror a comma. Additional white space around the separator is allowed. Theallowed syntax for floating point numbers must be defined in the hostlanguage.

If the  argument values forkeyTimes orkeySplines are not legal (including toofew or too many values for either attribute), the animation will have noeffect (see alsoHandling syntaxerrors).

In thecalcMode,keyTimes andkeySplines attribute values, leadingand trailing white space and white space before and after semicolonseparators will be ignored.

Examples of advanceduses of calcMode

Discrete animation can be used withkeyTimes, as in the following example:

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

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

The following example illustrates the use ofkeyTimes:

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

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

Interpolation withkeySplines

For some attributes, thepace of change may not be easilydiscernable by viewers. However for animations like motion, the ability tomake thespeed of the motion change gradually, and not in abruptsteps, can be important. ThekeySplines attribute provides thiscontrol.

Extending the above example to usekeySplines:

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

ThekeyTimes still cause the "x"attribute to have a value of "0" at the start of the animation, "50" after 8seconds and "100" at the end of the animation. However, thekeySplines values define a curve forpacing the interpolation between values. In the example above, the splinecauses an ease-in and ease-out effect between time 0 and 8 seconds (i.e.betweenkeyTimes 0 and .8, andvalues "0" and "50"), but a strictlinear interpolation between 8 seconds and the end (i.e. betweenkeyTimes .8 and 1, andvalues  "50" and "100"). Figure 7 showsthe curves that thesekeySplinesvalues define.

Figure 7 - Illustration of keySplines effect

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

Each diagram in Figure 7 illustrates the effect ofkeySplines settings for a singleinterval (i.e. between the associated pairs of values in thekeyTimes andvalues lists.). The horizontal axis can bethought of as the input value for theunit progress of interpolationwithin the interval - i.e. the pace with which interpolation proceeds alongthe given interval. The vertical axis is the resulting value for theunitprogress, yielded by thekeySplines function. Another way ofdescribing this is that the horizontal axis is the inputunit timefor the interval, and the vertical axis is the outputunit time. Seealso the sectionTimingand real-world clock times.

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, theapproximate interpolated values as the animation proceeds are:

For a formal definition of Bezier spline calculation, see[COMP-GRAPHICS], pages 488-491.

ThekeyTimes andkeySplines attributes can also be usedwith thefrom/to/by shorthand forms for specifying values, as in thefollowing example:

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

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

The following example describes a somewhat unusual usage, afrom-to animation with discrete animation. Thestroke-linecap attribute of SVG elements takes a string, and soimplies acalcMode ofdiscrete. The animation will set thestroke-linecap attribute toroundfor 5 seconds (half the simple duration) and then set thestroke-linecap tosquare for 5seconds.

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

3.8.2SMIL 2.1 SplineAnimationModule Elements

The SplineAnimation module extends the BasicAnimation elementsanimate,animateMotion andanimateColor, adding the attributeskeyTimes andkeySplines, and the valuespline for thecaclMode attribute.

3.8.3The spline animateelement

The SplineAnimation module extends theanimate element defined by theBasicAnimation module, adding the following attributes and values.

Examples are provided above, as are normative definitions of the semanticsof all attributes supported byanimate.

3.8.4The spline animateMotionelement

The SplineAnimation module extends theanimateMotion element defined by theBasicAnimation module, adding the following attributes and values.

Examples are provided above, as are normative definitions of the semanticsof all attributes supported byanimate.

For complete velocity control, calcMode can be set tospline and the author can specify a velocity controlspline withkeyTimes andkeySplines.

3.8.5The spline animateColorelement

The SplineAnimation module extends theanimateColor element defined by theBasicAnimation module, adding the following attributes and values.

3.9SMIL 2.1 SplineAnimation ModuleDetails

3.9.1SplineAnimation integrationrequirements

To specify the integration of the SMIL 2.1 SplineAnimation module into ahost language, the language designer must integrate SMIL 2.1 BasicAnimationinto the language, satisfying all the requirements listed inBasicAnimation integrationrequirements.

In addition to integrating BasicAnimation, the requirements listed inCommon animation integrationrequirements must be satisfied for the SplineAnimation module.

3.9.2Document type definition (DTD) forthe SplineAnimation module

See the fullDTD for the SMILAnimation Modules.

3.10Common Animation IntegrationRequirements

This section presents host-language-integration issues which are the samefor the BasicAnimation and SplineAnimation modules.

3.10.1Integrationrequirements

The host language profile must integrate the SMIL 2.1BasicInlineTiming module into the hostlanguage, satisfying all requirements of that module. In addition, allmodules of the SMIL 2.1Timing andSynchronization modules and of the SMIL 2.1Time Manipulation modules which areintegrated into the host language must be available on BasicAnimationelements.

In particular, thefill attribute issupported on animation elements only if the host language integrates the SMIL2.1BasicTimeContainers module inaddition to theBasicInlineTimingmodule.

normative section

If the Eventbase-element term is missing, the event-base element isdefined to be the target element of the animation.

The host langauge profile may add additional attributes to Animationelements. Attributes added to any Animation element must be added to allAnimation elements. In particular, this module does not define an XML IDattribute. It is expected that the host language profile will add an XML IDattribute to the Animation elements.

Extending Animation

Language designers integrating SMIL Animation are encouraged to define newanimation elements where such additions will be of convenience to authors.The new elements must be based on SMIL Animation andSMIL Timing and Synchronization, andmust stay within the framework provided by SMIL Timing and Synchronizationand SMIL Animation.

Language designers are also encouraged to define support for additive andcumulative animation for non-numeric data types where addition can sensiblybe defined.

Constraints onmanipulating animation elements

Language designers integrating SMIL Animation are encouraged to disallowmanipulation of attributes of the animation elements after the document hasbegun. This includes both the attributes specifying targets and values, aswell as the timing attributes. In particular, theid attribute(of type ID) on all animation elements must not be mutable (i.e. should beread-only). Requiring animation runtimes to track changes toidvalues introduces considerable complexity, for what is at best a questionablefeature.

It is recommended that language specifications disallow manipulation ofanimation element attributes through DOM interfaces after the document hasbegun.  It is also recommended that language specifications disallow the useof animation elements to target other animation elements.

Note in particular that if theattributeName attribute can bechanged (either by animation or script), problems may arise if the targetattribute has a namespace qualified name. Current DOM specifications do notinclude a mechanism to handle this binding.

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

Handling syntaxerrors

The specific error handling mechanisms for each attribute are describedwith the individual syntax descriptions.  Some of these specificationsdescribe the behavior of an animation with syntax errors as "having noeffect".  This means that the animation will continue to behave normallywith respect to timing, but will not manipulate any presentation value, andso will have no visible impact upon the presentation. 

In particular, this means that if other animation elements are defined tobegin or end relative to an animation that "has no effect", the otheranimation elements will begin and end as though there were no syntax errors.The presentation runtime may indicate an error, but need not haltpresentation or animation of the document. 

Some host languages and/or runtimes may choose to impose stricter errorhandling (see alsoErrorhandling semantics for a discussion of host language issues with errorhandling). Authoring environments may also choose to be more intrusive whenerrors are detected.

Error handlingsemantics

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

Host language designers may not relax the error handling specifications,or the error handling response (as described inHandling syntax errors). Forexample, host language designers may not define error recovery semantics formissing or erroneous values in thevalues orkeyTimes attribute values.