Movatterモバイル変換

19 Animation

Contents

• 19.1 Introduction
• 19.2 Animation elements
  • 19.2.1 Overview
  • 19.2.2 Relationship to SMIL Animation
  • 19.2.3 Animation elements example
  • 19.2.4 Attributes to identify the target element for an animation
  • 19.2.5 Attributes to identify the target attribute or property for an animation
  • 19.2.6 Attributes to control the timing of the animation
  • 19.2.7 Attributes that define animation values over time
  • 19.2.8 Attributes that control whether animations are additive
  • 19.2.9 Inheritance
  • 19.2.10 The'animate' element
  • 19.2.11 The'set' element
  • 19.2.12 The'animateMotion' element
  • 19.2.13 The'animateColor' element
  • 19.2.14 The'animateTransform' element
  • 19.2.15 Elements, attributes and properties that can be animated
• 19.3 Animation using the SVG DOM
• 19.4 Animation Module
• 19.5 DOM interfaces

19.1 Introduction

Because the Web is a dynamic medium, SVG supports the ability to change vector graphics over time. SVG content can be animated in the following ways:

• Using SVG'sanimation elements. SVG document fragments can describe time-based modifications to the document's elements. Using the various animation elements, you can define motion paths, fade-in or fade-out effects, and objects that grow, shrink, spin or change color.
• Using theSVG DOM. The SVG DOM conforms to key aspects of the "Document Object Model (DOM) Level 1" [DOM1] and "Document Object Model (DOM) Level 2" [DOM2] specifications. Every attribute and style sheet setting is accessible to scripting, and SVG offers a set of additional DOM interfaces to support efficient animation via scripting. As a result, virtually any kind of animation can be achieved. The timer facilities in scripting languages such as ECMAScript can be used to start up and control the animations. (Seeexample below.)
• SVG has been designed to allow future versions of SMIL [SMIL1] to use animated or static SVG content as media components.
• In the future, it is expected that future versions of SMIL will be modularized and that components of it could be used in conjunction with SVG and other XML grammars to achieve animation effects.

19.2 Animation elements

19.2.1 Overview

SVG's animation elements were developed in collaboration with the W3C Synchronized Multimedia (SYMM) Working Group, developers of the Synchronized Multimedia Integration Language (SMIL) 1.0 Specification [SMIL1].

The SYMM Working Group, in collaboration with the SVG Working Group, has authored the SMIL Animation specification [SMILANIM], which represents a general-purpose XML animation feature set. SVG incorporates the animation features defined in the SMIL Animation specification and provides some SVG-specific extensions.

For an introduction to the approach and features available in any language that supports SMIL Animation, see SMIL Animation overview and SMIL Animation animation model. For the list of animation features which go beyond SMIL Animation, seeSVG extensions to SMIL Animation.

19.2.2 Relationship to SMIL Animation

SVG is a host language in terms of SMIL Animation and therefore introduces additional constraints and features as permitted by that specification. Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for SVG's animation elements and attributes is the SMIL Animation [SMILANIM] specification.

SVG supports the following four animation elements which are defined in the SMIL Animation specification:

Additionally, SVG includes the following compatible extensions to SMIL Animation:

For compatibility with other aspects of the language, SVG usesURI references via anxlink:href attribute to identify the elements which are to be targets of the animations.

SMIL Animation requires that the host language define the meaning fordocument begin and thedocument end. Since an'svg' is sometimes the root of the XML document tree and other times can be a component of a parent XML grammar, thedocument begin for a given SVG document fragment is defined to be the exact time at which the'svg' element'sSVGLoad event is triggered. Thedocument end of an SVG document fragment is the point at which the document fragment has been released and is no longer being processed by the user agent. However, nested'svg' elements within an SVG document do not constitute document fragments in this sense, and do not define a separate document begin; all times within the nested SVG fragment are relative to the document time defined for the root'svg' element.

For SVG, the termpresentation time indicates the position in the timeline relative to thedocument begin of a given document fragment.

SVG defines more constrained error processing than is defined in the SMIL Animation [SMILANIM] specification. SMIL Animation defines error processing behavior where the document continues to run in certain error situations, whereas all animations within an SVG document fragment will stop in the event of any error within the document (seeError processing).

19.2.3 Animation elements example

Example anim01 below demonstrates each of SVG's five animation elements.

<?xml version="1.0" standalone="no"?><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"   "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg width="8cm" height="3cm"  viewBox="0 0 800 300"     xmlns="http://www.w3.org/2000/svg" version="1.1">  <desc>Example anim01 - demonstrate animation elements</desc>  <rect x="1" y="1" width="798" height="298"         fill="none" stroke="blue" stroke-width="2" />  <!-- The following illustrates the use of the 'animate' element        to animate a rectangles x, y, and width attributes so that        the rectangle grows to ultimately fill the viewport. -->  <rect x="300" y="100" width="300" height="100"        fill="rgb(255,255,0)"  >    <animate attributeName="x" attributeType="XML"             begin="0s" dur="9s" fill="freeze" from="300" to="0" />    <animate attributeName="y" attributeType="XML"             begin="0s" dur="9s" fill="freeze" from="100" to="0" />    <animate attributeName="width" attributeType="XML"             begin="0s" dur="9s" fill="freeze" from="300" to="800" />    <animate attributeName="height" attributeType="XML"             begin="0s" dur="9s" fill="freeze" from="100" to="300" />  </rect>  <!-- Set up a new user coordinate system so that        the text string's origin is at (0,0), allowing        rotation and scale relative to the new origin -->  <g transform="translate(100,100)" >    <!-- The following illustrates the use of the 'set', 'animateMotion',         'animateColor' and 'animateTransform' elements. The 'text' element          below starts off hidden (i.e., invisible). At 3 seconds, it:           * becomes visible           * continuously moves diagonally across the viewport           * changes color from blue to dark red           * rotates from -30 to zero degrees           * scales by a factor of three. -->    <text x="0" y="0"          font-family="Verdana" font-size="35.27" visibility="hidden"  >       It's alive!      <set attributeName="visibility" attributeType="CSS" to="visible"           begin="3s" dur="6s" fill="freeze" />      <animateMotion path="M 0 0 L 100 100"            begin="3s" dur="6s" fill="freeze" />      <animateColor attributeName="fill" attributeType="CSS"           from="rgb(0,0,255)" to="rgb(128,0,0)"           begin="3s" dur="6s" fill="freeze" />      <animateTransform attributeName="transform" attributeType="XML"           type="rotate" from="-30" to="0"           begin="3s" dur="6s" fill="freeze" />      <animateTransform attributeName="transform" attributeType="XML"           type="scale" from="1" to="3" additive="sum"           begin="3s" dur="6s" fill="freeze" />    </text>  </g></svg>

Example anim01

At zero seconds		At three seconds
At six seconds		At nine seconds

View this example as SVG (SVG-enabled browsers only)

The sections below describe the various animation attributes and elements.

19.2.4 Attributes to identify the target element for an animation

The following attributes are common to all animation elements and identify the target element for the animation.

<!ENTITY %SVG.Animation.attrib    "%SVG.XLink.attrib;     %SVG.Animation.extra.attrib;">

19.2.5 Attributes to identify the target attribute or property for an animation

The following attributes identify the target attribute or property for the giventarget element whose value changes over time.

<!ENTITY %SVG.AnimationAttribute.attrib    "attributeName  CDATA  #REQUIRED     attributeType  CDATA  #IMPLIED     %SVG.AnimationAttribute.extra.attrib;">

19.2.6 Attributes to control the timing of the animation

The following attributes are common to all animation elements and control the timing of the animation, including what causes the animation to start and end, whether the animation runs repeatedly, and whether to retain the end state the animation once the animation ends.

<!ENTITY %SVG.AnimationTiming.attrib    "begin CDATA #IMPLIED     dur CDATA #IMPLIED     end CDATA #IMPLIED     min CDATA #IMPLIED     max CDATA #IMPLIED     restart ( always | never | whenNotActive ) 'always'     repeatCount CDATA #IMPLIED     repeatDur CDATA #IMPLIED     fill ( remove | freeze ) 'remove'     %SVG.AnimationTiming.extra.attrib;">

In the syntax specifications that follow, optional white space is indicated as "S", defined as follows:

S ::= (#x20 | #x9 | #xD | #xA)*

Clock values

Clock values have the same syntax as in SMIL Animation [SMILANIM], which is repeated here:

Clock-val         ::= Full-clock-val | Partial-clock-val                       | Timecount-valFull-clock-val    ::= Hours ":" Minutes ":" Seconds ("." Fraction)?Partial-clock-val ::= Minutes ":" Seconds ("." Fraction)?Timecount-val     ::= Timecount ("." Fraction)? (Metric)?Metric            ::= "h" | "min" | "s" | "ms"Hours             ::= DIGIT+; any positive numberMinutes           ::= 2DIGIT; range from 00 to 59Seconds           ::= 2DIGIT; range from 00 to 59Fraction      ::= DIGIT+Timecount         ::= DIGIT+2DIGIT        ::= DIGIT DIGITDIGIT         ::= [0-9]

For Timecount values, the default metric suffix is "s" (for seconds). No embedded white space is allowed in clock values, although leading and trailing white space characters will be ignored.

Clock values describepresentation time.

The following are examples of legal clock values:

• Full clock values: 
  02:30:03    = 2 hours, 30 minutes and 3 seconds
    50:00:10.25 = 50 hours, 10 seconds and 250 milliseconds
• Partial clock value: 
  02:33   = 2 minutes and 33 seconds
    00:10.5 = 10.5 seconds = 10 seconds and 500 milliseconds
• Timecount values:
    3.2h    = 3.2 hours = 3 hours and 12 minutes
    45min   = 45 minutes
    30s     = 30 seconds
    5ms     = 5 milliseconds
    12.467  = 12 seconds and 467 milliseconds

Fractional values are just (base 10) floating point definitions of seconds. Thus:

00.5s = 500 milliseconds
00:00.005 = 5 milliseconds

19.2.7 Attributes that define animation values over time

The following attributes are common to elements'animate','animateMotion','animateColor' and'animateTransform'. These attributes define the values that are assigned to the target attribute or property over time. The attributes below provide control over the relative timing of keyframes and the interpolation method between discrete values.

<!ENTITY %SVG.AnimationValue.attrib    "calcMode ( discrete | linear | paced | spline ) 'linear'     values CDATA #IMPLIED     keyTimes CDATA #IMPLIED     keySplines CDATA #IMPLIED     from CDATA #IMPLIED     to CDATA #IMPLIED     by CDATA #IMPLIED     %SVG.AnimationValue.extra.attrib;">

Attribute definitions:

calcMode= "discrete | linear | paced | spline"

Specifies the interpolation mode for the animation. This can take any of the following values. The default mode is "linear", however if the attribute does not support linear interpolation (e.g. for strings), thecalcMode attribute is ignored and discrete interpolation is used.

discrete

This specifies that the animation function will jump from one value to the next without any interpolation.

linear

Simple linear interpolation between values is used to calculate the animation function. Except for'animateMotion', this is the defaultcalcMode.

paced

Defines interpolation to produce an even pace of change across the animation. This is only supported for values that define a linear numeric range, and for which some notion of "distance" between points can be calculated (e.g. position, width, height, etc.). If "paced" is specified, anykeyTimes orkeySplines will be ignored. For'animateMotion', this is the defaultcalcMode.

spline

Interpolates from one value in thevalues list to the next according to a time function defined by a cubic Bézier spline. The points of the spline are defined in thekeyTimes attribute, and the control points for each interval are defined in thekeySplines attribute.

Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this attribute is the SMIL Animation [ SMILANIM] specification. In particular, see SMIL Animation: 'calcMode' attribute.

values= "<list>"

A semicolon-separated list of one or more values. Vector-valued attributes are supported using the vector syntax of theattributeType domain. Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this attribute is the SMIL Animation [ SMILANIM] specification. In particular, see SMIL Animation: 'values' attribute.

keyTimes= "<list>"

A semicolon-separated list of time values used to control the pacing of the animation. Each time in the list corresponds to a value in thevalues attribute list, and defines when the value is used in the animation function. Each time value in thekeyTimes list is specified as a floating point value between 0 and 1 (inclusive), representing a proportional offset into the simple duration of the animation element.  

If a list ofkeyTimes is specified, there must be exactly as many values in thekeyTimes list as in thevalues list. 

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

ThekeyTimes list semantics depends upon the interpolation mode:

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

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

If there are any errors in thekeyTimes specification (bad values, too many or too few values), the document fragment is in error (seeerror processing).

If the simple duration is indefinite, anykeyTimes specification will be ignored.

Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this attribute is the SMIL Animation [ SMILANIM] specification. In particular, see SMIL Animation: 'keyTimes' attribute.

keySplines= "<list>"

A set of Bézier control points associated with thekeyTimes list, defining a cubic Bézier function that controls interval pacing. The attribute value is a semicolon separated list of control point descriptions. Each control point description is a set of four values:x1 y1 x2 y2, describing the Bézier control points for one time segment. ThekeyTimes values that define the associated segment are the Bézier "anchor points", and thekeySplines values are the control points. Thus, there must be one fewer sets of control points than there arekeyTimes. 

The values must all be in the range 0 to 1.

This attribute is ignored unless thecalcMode is set to "spline".

If there are any errors in thekeySplines specification (bad values, too many or too few values), the document fragment is in error (seeerror processing).

Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this attribute is the SMIL Animation [ SMILANIM] specification. In particular, see SMIL Animation: 'keySplines' attribute.

from= "<value>"

Specifies the starting value of the animation.
Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this attribute is the SMIL Animation [ SMILANIM] specification. In particular, see SMIL Animation: 'from' attribute.

to= "<value>"

Specifies the ending value of the animation.
Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this attribute is the SMIL Animation [ SMILANIM] specification. In particular, see SMIL Animation: 'to' attribute.

by= "<value>"

Specifies a relative offset value for the animation.
Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this attribute is the SMIL Animation [ SMILANIM] specification. In particular, see SMIL Animation: 'by' attribute.

The SMIL Animation [ SMILANIM] specification defines the detailed processing rules associated with the above attributes. Except for any SVG-specific rules explicitly mentioned in this specification, the SMIL Animation [ SMILANIM] specification is the normative definition of the processing rules for the above attributes.

The animation values specified in the animation element must be legal values for the specified attribute. Leading and trailing white space, and white space before and after semicolon separators, will be ignored.

All values specified must be legal values for the specified attribute (as defined in the associated namespace). If any values are not legal, the document fragment is in error (seeerror processing).

If a list of values is used, the animation will apply the values in order over the course of the animation. If a list ofvalues is specified, anyfrom,to andby attribute values are ignored.

The processing rules for the variants offrom/by/to animations are described in Animation function values.

The following figure illustrates the interpretation of thekeySplines attribute. Each diagram illustrates the effect ofkeySplines settings for a single interval (i.e. between the associated pairs of values in thekeyTimes andvalues lists.). The horizontal axis can be thought of as the input value for theunit progress of interpolation within the interval - i.e. the pace with which interpolation proceeds along the given interval. The vertical axis is the resulting value for theunit progress, yielded by thekeySplines function. Another way of describing this is that the horizontal axis is the inputunit time for the interval, and the vertical axis is the outputunit time. See also the section Timing and real-world clock times.

Examples ofkeySplines

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

To illustrate the calculations, consider the simple example:

<animate dur="4s" values="10; 20" keyTimes="0; 1"     calcMode="spline"keySplines={as in table} />

Using the keySplines values for each of the four cases above, the approximate interpolated values as the animation proceeds are:

keySplines values	Initial value	After 1s	After 2s	After 3s	Final value
0 0 1 1	10.0	12.5	15.0	17.5	20.0
.5 0 .5 1	10.0	11.0	15.0	19.0	20.0
0 .75 .25 1	10.0	18.0	19.3	19.8	20.0
1 0 .25 .25	10.0	10.1	10.6	16.9	20.0

For a formal definition of Bézier spline calculation, see [FOLEY-VANDAM].

19.2.8 Attributes that control whether animations are additive

It is frequently useful to define animation as an offset or delta to an attribute's value, rather than as absolute values. A simple "grow" animation can increase the width of an object by 10 pixels:

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

It is frequently useful for repeated animations to build upon the previous results, accumulating with each interation. The following example causes the rectangle to continue to grow with each repeat of the animation:

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

At the end of the first repetition, the rectangle has a width of 30 pixels. At the end of the second repetition, the rectangle has a width of 40 pixels. At the end of the fifth repetition, the rectangle has a width of 70 pixels.

For more information about additive animations, see SMIL Animation: Additive animation. For more information on cumulative animations, see SMIL Animation: Controlling behavior of repeating animation - Cumulative animation.

The following attributes are common to elements'animate','animateMotion','animateColor' and'animateTransform'.

<!ENTITY %SVG.AnimationAddtion.attrib    "additive ( replace | sum ) 'replace'     accumulate ( none | sum ) 'none'     %SVG.AnimationAddtion.extra.attrib;">

19.2.9 Inheritance

SVG allows both attributes and properties to be animated. If a given attribute or property is inheritable by descendants, then animations on a parent element such as a'g' element has the effect of propagating the attribute or property animation values to descendant elements as the animation proceeds; thus, descendant elements can inherit animated attributes and properties from their ancestors.

19.2.10 The'animate' element

The'animate' element is used to animate a single attribute or property over time. For example, to make a rectangle repeatedly fade away over 5 seconds, you can specify:

<rect>  <animate attributeType="CSS" attributeName="opacity"          from="1" to="0" dur="5s" repeatCount="indefinite" /></rect>

Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this element is the SMIL Animation [SMILANIM] specification. In particular, see SMIL Animation: 'animate' element.

<!ENTITY % SVG.animate.extra.content "" ><!ENTITY % SVG.animate.element "INCLUDE" ><![%SVG.animate.element;[<!ENTITY % SVG.animate.content    "( %SVG.Description.class; %SVG.animate.extra.content; )\*"><!ELEMENT %SVG.animate.qname; %SVG.animate.content; ><!-- end of SVG.animate.element -->]]><!ENTITY % SVG.animate.attlist "INCLUDE" ><![%SVG.animate.attlist;[<!ATTLIST %SVG.animate.qname;    %SVG.Core.attrib;    %SVG.Conditional.attrib;    %SVG.AnimationEvents.attrib;    %SVG.External.attrib;    %SVG.Animation.attrib;    %SVG.AnimationAttribute.attrib;    %SVG.AnimationTiming.attrib;    %SVG.AnimationValue.attrib;    %SVG.AnimationAddtion.attrib;>

For a list of attributes and properties that can be animated using the'animate' element, seeElements, attributes and properties that can be animated.

19.2.11 The'set' element

The'set' element provides a simple means of just setting the value of an attribute for a specified duration. It supports all attribute types, including those that cannot reasonably be interpolated, such as string and boolean values. The'set' element is non-additive. The additive and accumulate attributes are not allowed, and will be ignored if specified.

Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this element is the SMIL Animation [SMILANIM] specification. In particular, see SMIL Animation: 'set' element.

<!ENTITY % SVG.set.extra.content "" ><!ENTITY % SVG.set.element "INCLUDE" ><![%SVG.set.element;[<!ENTITY % SVG.set.content    "( %SVG.Description.class; %SVG.set.extra.content; )*"><!ELEMENT %SVG.set.qname; %SVG.set.content; ><!-- end of SVG.set.element -->]]><!ENTITY % SVG.set.attlist "INCLUDE" ><![%SVG.set.attlist;[<!ATTLIST %SVG.set.qname;    %SVG.Core.attrib;    %SVG.Conditional.attrib;    %SVG.AnimationEvents.attrib;    %SVG.External.attrib;    %SVG.Animation.attrib;    %SVG.AnimationAttribute.attrib;    %SVG.AnimationTiming.attrib;    to CDATA #IMPLIED>

For a list of attributes and properties that can be animated using the'set' element, seeElements, attributes and properties that can be animated.

19.2.12 The'animateMotion' element

The'animateMotion' element causes a referenced element to move along a motion path.

Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this element is the SMIL Animation [SMILANIM] specification. In particular, see SMIL Animation: 'animateMotion' element.

<!ENTITY % SVG.animateMotion.extra.content "" ><!ENTITY % SVG.animateMotion.element "INCLUDE" ><![%SVG.animateMotion.element;[<!ENTITY % SVG.animateMotion.content    "(( %SVG.Description.class; )*, %SVG.mpath.qname;?        %SVG.animateMotion.extra.content; )"><!ELEMENT %SVG.animateMotion.qname; %SVG.animateMot\ion.content; ><!-- end of SVG.animateMotion.element -->]]><!ENTITY % SVG.animateMotion.attlist "INCLUDE" ><![%SVG.animateMotion.attlist;[<!ATTLIST %SVG.animateMotion.qname;    %SVG.Core.attrib;    %SVG.Conditional.attrib;    %SVG.AnimationEvents.attrib;    %SVG.External.attrib;    %SVG.Animation.attrib;    %SVG.AnimationTiming.attrib;    %SVG.AnimationAddtion.attrib;    calcMode ( discrete | linear | paced | spline ) 'paced'    values CDATA #IMPLIED    keyTimes CDATA #IMPLIED    keySplines CDATA #IMPLIED    from CDATA #IMPLIED    to CDATA #IMPLIED    by CDATA #IMPLIED    path CDATA #IMPLIED    keyPoints CDATA #IMPLIED    rotate CDATA #IMPLIED    origin CDATA #IMPLIED>

<!ENTITY % SVG.mpath.extra.content "" ><!ENTITY % SVG.mpath.element "INCLUDE" ><![%SVG.mpath.element;[<!ENTITY % SVG.mpath.content    "( %SVG.Description.class; %SVG.mpath.extra.content; )*"><!ELEMENT %SVG.mpath.qname; %SVG.mpath.content; ><!-- end of SVG.mpath.element -->]]><!ENTITY % SVG.mpath.attlist "INCLUDE" ><![%SVG.mpath.attlist;[<!ATTLIST %SVG.mpath.qname;    %SVG.Core.attrib;    %SVG.XLinkRequired.attrib;    %SVG.External.attrib;>

For'animateMotion', the specified values forfrom,by,to andvalues consists of x, y coordinate pairs, with a single comma and/or white space separating the x coordinate from the y coordinate. For example,from="33,15" specifies an x coordinate value of33 and a y coordinate value of15.

If provided, thevalues attribute must consists of a list of x, y coordinate pairs. Coordinate values are separated by at least one white space character or a comma. Additional white space around the separator is allowed. For example,values="10,20;30,20;30,40" orvalues="10mm,20mm;30mm,20mm;30mm,40mm". Each coordinate represents alength. Attributesfrom,by,to andvalues specify a shape on the current canvas which represents the motion path.

Two options are available which allow definition of a motion path using any of SVG'spath data commands:

• thepath attribute defines a motion path directly on'animateMotion' element using any of SVG'spath data commands.
• the'mpath' sub-element provides the ability to reference an external'path' element as the definition of the motion path.

Note that SVG'spath data commands can only contain values in user space, whereasfrom,by,to andvalues can specify coordinates in user space or using unit identifiers. SeeUnits.

The various (x,y) points of the shape provide a supplemental transformation matrix onto the CTM for the referenced object which causes a translation along the x- and y-axes of the current user coordinate system by the (x,y) values of the shape computed over time. Thus, the referenced object is translated over time by the offset of the motion path relative to the origin of the current user coordinate system. The supplemental transformation is applied on top of any transformations due to the target element'stransform attribute or any animations on that attribute due to'animateTransform' elements on the target element.

Theadditive andaccumulate attributes apply to'animateMotion' elements. Multiple'animateMotion' elements all simultaneously referencing the same target element can be additive with respect to each other; however, the transformations which result from the'animateMotion' elements are always supplemental to any transformations due to the target element'stransform attribute or any'animateTransform' elements.

The default calculation mode (calcMode) foranimateMotion is "paced". This will produce constant velocity motion along the specified path. Note that while animateMotion elements can be additive, it is important to observe that the addition of two or more "paced" (constant velocity) animations might not result in a combined motion animation with constant velocity.

When apath is combined with "discrete", "linear" or "spline"calcMode settings, and if attributekeyPoints is not provided, the number of values is defined to be the number of points defined by the path, unless there are "move to" commands within the path. A "move to" command within thepath (i.e. other than at the beginning of thepath description) A "move to" command does not count as an additional point when dividing up the duration, or when associatingkeyTimes,keySplines andkeyPoints values. When apath is combined with a "paced"calcMode setting, all "move to" commands are considered to have 0 length (i.e. they always happen instantaneously), and is not considered in computing the pacing.

For more flexibility in controlling the velocity along the motion path, thekeyPoints attribute provides the ability to specify the progress along the motion path for each of thekeyTimes specified values. If specified,keyPoints causeskeyTimes to apply to the values inkeyPoints rather than the points specified in thevalues attribute array or the points on thepath attribute.

The override rules for'animateMotion are as follows. Regarding the definition of the motion path, the'mpath' element overrides the thepath attribute, which overridesvalues, which overridesfrom/by/to. Regarding determining the points which correspond to thekeyTimes attributes, thekeyPoints attribute overridespath, which overridesvalues, which overridesfrom/by/to.

At any timet within a motion path animation of durationdur, the computed coordinate (x,y) along the motion path is determined by finding the point (x,y) which ist/dur distance along the motion path using the user agent'sdistance along the path algorithm.

The following example demonstrates the supplemental transformation matrices that are computed during a motion path animation.

Example animMotion01 shows a triangle moving along a motion path.

<?xml version="1.0" standalone="no"?><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"   "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg width="5cm" height="3cm"  viewBox="0 0 500 300"     xmlns="http://www.w3.org/2000/svg" version="1.1"     xmlns:xlink="http://www.w3.org/1999/xlink" >  <desc>Example animMotion01 - demonstrate motion animation computations</desc>  <rect x="1" y="1" width="498" height="298"        fill="none" stroke="blue" stroke-width="2" />  <!-- Draw the outline of the motion path in blue, along          with three small circles at the start, middle and end. -->  <path d="M100,250 C 100,50 400,50 400,250"        fill="none" stroke="blue" stroke-width="7.06"  />  <circle cx="100" cy="250" r="17.64" fill="blue"  />  <circle cx="250" cy="100" r="17.64" fill="blue"  />  <circle cx="400" cy="250" r="17.64" fill="blue"  />  <!-- Here is a triangle which will be moved about the motion path.       It is defined with an upright orientation with the base of       the triangle centered horizontally just above the origin. -->  <path d="M-25,-12.5 L25,-12.5 L 0,-87.5 z"        fill="yellow" stroke="red" stroke-width="7.06"  >    <!-- Define the motion path animation -->    <animateMotion dur="6s" repeatCount="indefinite" rotate="auto" >       <mpath xlink:href="#path1"/>    </animateMotion>  </path></svg>

Example animMotion01

At zero seconds

At three seconds

At six seconds

View this example as SVG (SVG-enabled browsers only)

The following table shows the supplemental transformation matrices that are applied to achieve the effect of the motion path animation.

For a list of elements that can be animated using the'animateMotion' element, seeElements, attributes and properties that can be animated.

19.2.13 The'animateColor' element

The'animateColor' element specifies a color transformation over time.

Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this element is the SMIL Animation [SMILANIM] specification. In particular, see SMIL Animation: 'animateColor' element.

<!ENTITY % SVG.animateColor.extra.content "" ><!ENTITY % SVG.animateColor.element "INCLUDE" ><![%SVG.animateColor.element;[<!ENTITY % SVG.animateColor.content    "( %SVG.Description.class; %SVG.animateColor.extra.conte\nt; )*"><!ELEMENT %SVG.animateColor.qname; %SVG.animateColor\.content; ><!-- end of SVG.animateColor.element -->]]><!ENTITY % SVG.animateColor.attlist "INCLUDE" ><![%SVG.animateColor.attlist;[<!ATTLIST %SVG.animateColor.qname;    %SVG.Core.attrib;    %SVG.Conditional.attrib;    %SVG.AnimationEvents.attrib;    %SVG.External.attrib;    %SVG.Animation.attrib;    %SVG.AnimationAttribute.attrib;    %SVG.AnimationTiming.attrib;    %SVG.AnimationValue.attrib;    %SVG.AnimationAddtion.attrib;>

Thefrom,by andto attributes take color values, where each color value is expressed using the following syntax (the same syntax as used in SVG's properties that can take color values):

<color> [icc-color(<name>[,<icccolorvalue>]*)]

Thevalues attribute for the'animateColor' element consists of a semicolon-separated list of color values, with each color value expressed in the above syntax.

Out of range color values can be provided, but user agent processing will be implementation dependent. User agents should clamp color values to allow color range values as late as possible, but note that system differences might preclude consistent behavior across different systems.

The'color-interpolation' property applies to color interpolations that result from'animateColor' animations.

For a list of attributes and properties that can be animated using the'animateColor' element, seeElements, attributes and properties that can be animated.

19.2.14 The'animateTransform' element

The'animateTransform' element animates a transformation attribute on a target element, thereby allowing animations to control translation, scaling, rotation and/or skewing.

<!ENTITY % SVG.animateTransform.extra.content "" ><!ENTITY % SVG.animateTransform.element "INCLUDE" ><![%SVG.animateTransform.element;[<!ENTITY % SVG.animateTransform.content    "( %SVG.Description.class; %SVG.animateTransform.extra.c\ontent; )*"><!ELEMENT %SVG.animateTransform.qname; %SVG.anim\ateTransform.content; ><!-- end of SVG.animateTransform.element -->]]><!ENTITY % SVG.animateTransform.attlist "INCLUDE" ><![%SVG.animateTransform.attlist;[<!ATTLIST %SVG.animateTransform.qname;    %SVG.Core.attrib;    %SVG.Conditional.attrib;    %SVG.AnimationEvents.attrib;    %SVG.External.attrib;    %SVG.Animation.attrib;    %SVG.AnimationAttribute.attrib;    %SVG.AnimationTiming.attrib;    %SVG.AnimationValue.attrib;   %SVG.AnimationAddtion.attrib;    type ( translate | scale | rotate | skewX | skewY ) 'translate'>

Thefrom,by andto attributes take a value expressed using the same syntax that is available for the given transformation type:

• For atype="translate", each individual value is expressed as<tx> [,<ty>].
• For atype="scale", each individual value is expressed as<sx> [,<sy>].
• For atype="rotate", each individual value is expressed as<rotate-angle> [<cx> <cy>].
• For atype="skewX" andtype="skewY", each individual value is expressed as<skew-angle>.

Thevalues attribute for the'animateTransform' element consists of a semicolon-separated list of values, where each individual value is expressed as described above forfrom,by andto.

IfcalcMode has the valuepaced, then a total "distance" for each component of the transformation is calculated (e.g., for a translate operation, a total distance is calculated for bothtx andty) consisting of the sum of the absolute values of the differences between each pair of values, and the animation runs to produce a constant distance movement for each individual component.

When an animation is active, the effect of non-additive'animateTransform' (i.e.,additive="replace") is to replace the given attribute's value with the transformation defined by the'animateTransform'. The effect of additive (i.e.,additive="sum") is to post-multiply the transformation matrix corresponding to the transformation defined by this'animateTransform'. To illustrate:

<rect transform="skewX(30)"...>  <animateTransform attributeName="transform" attributeType="XML"                    type="rotate" from="0" to="90" dur="5s"                    additive="replace" fill="freeze"/>  <animateTransform attributeName="transform" attributeType="XML"                    type="scale" from="1" to="2" dur="5s"                    additive="replace" fill="freeze"/></rect>

In the code snippet above, because the both animations haveadditive="replace", the first animation overrides the transformation on the rectangle itself and the second animation overrides the transformation from the first animation; therefore, at time 5 seconds, the visual result of the above two animations would be equivalent to the following static rectangle:

<rect transform="scale(2)" ... />

whereas in the following example:

<rect transform="skewX(30)"...>  <animateTransform attributeName="transform" attributeType="XML"                    type="rotate" from="0" to="90" dur="5s"                     additive="sum" fill="freeze"/>  <animateTransform attributeName="transform" attributeType="XML"                    type="scale" from="1" to="2" dur="5s"                    additive="sum" fill="freeze"/></rect>

In this code snippet, because the both animations haveadditive="sum", the first animation post-multiplies its transformation to any transformations on the rectangle itself and the second animation post-multiplies its transformation to any transformation from the first animation; therefore, at time 5 seconds, the visual result of the above two animations would be equivalent to the following static rectangle:

<rect transform="skewX(30) rotate(90) scale(2)" ... />

For a list of attributes and properties that can be animated using the'animateTransform' element, seeElements, attributes and properties that can be animated.

19.2.15 Elements, attributes and properties that can be animated

The following lists all of the elements which can be animated by an'animateMotion' element:

• 'g'
• 'defs'
• 'use'
• 'image'
• 'switch'
• 'path'
• 'rect'
• 'circle'
• 'ellipse'
• 'line'
• 'polyline'
• 'polygon'
• 'text'
• 'clipPath'
• 'mask'
• 'a'
• 'foreignObject'

Each attribute or property within this specification indicates whether or not it can be animated by SVG's animation elements. Animatable attributes and properties are designated as follows:

    Animatable: yes.

whereas attributes and properties that cannot be animated are designated:

    Animatable: no.

SVG has a defined set ofbasic data types for its various supported attributes and properties. For those attributes and properties that can be animated, the following table indicates which animation elements can be used to animate each of the basic data types. If a given attribute or property can take values of keywords (which are not additive) or numeric values (which are additive), then additive animations are possible if the subsequent animation uses a numeric value even if the base animation uses a keyword value; however, if the subsequent animation uses a keyword value, additive animation is not possible.

Any deviation from the above table or other special note about the animation capabilities of a particular attribute or property is included in the section of the specification where the given attribute or property is defined.

19.3 Animation using the SVG DOM

Example dom01 shows a simple animation using the DOM.

<?xml version="1.0" standalone="no"?><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"   "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg width="4cm" height="2cm" viewBox="0 0 400 200"     xmlns="http://www.w3.org/2000/svg"     onload="StartAnimation(evt)" version="1.1">  <script type="text/ecmascript"><![CDATA[    var timevalue = 0;    var timer_increment = 50;    var max_time = 5000;    var text_element;    function StartAnimation(evt) {      text_element = evt.target.ownerDocument.getElementById("TextElement");      ShowAndGrowElement();    }    function ShowAndGrowElement() {      timevalue = timevalue + timer_increment;      if (timevalue > max_time)        return;      // Scale the text string gradually until it is 20 times larger      scalefactor = (timevalue * 20.) / max_time;      text_element.setAttribute("transform", "scale(" + scalefactor + ")");      // Make the string more opaque      opacityfactor = timevalue / max_time;      text_element.setAttribute("opacity", opacityfactor);      // Call ShowAndGrowElement again <timer_increment> milliseconds later.      setTimeout("ShowAndGrowElement()", timer_increment)    }    window.ShowAndGrowElement = ShowAndGrowElement  ]]></script>  <rect x="1" y="1" width="398" height="198"        fill="none" stroke="blue" stroke-width="2"/>  <g transform="translate(50,150)" fill="red" font-size="7">    <text>SVG</text>  </g></svg>

Example dom01

At zero seconds

At 2.5 seconds

At five seconds

View this example as SVG (SVG-enabled browsers only)

The above SVG file contains a single graphics element, a text string that says "SVG". The animation loops for 5 seconds. The text string starts out small and transparent and grows to be large and opaque. Here is an explanation of how this example works:

• Theonload="StartAnimation(evt)" attribute indicates that, once the document has been fully loaded and processed, invoke ECMAScript functionStartAnimation.
• The 'script' element defines the ECMAScript which makes the animation happen. TheStartAnimation() function is only called once to give a value to global variabletext_element and to make the initial call toShowAndGrowElement().ShowAndGrowElement() is called every 50 milliseconds and resets thetransform andstyle attributes on the text element to new values each time it is called. At the end ofShowAndGrowElement, the function tells the ECMAScript engine to call itself again after 50 more milliseconds.
• The 'g' element shifts the coordinate system so that the origin is shifted toward the lower-left of the viewing area. It also defines the fill color and font-size to use when drawing the text string.
• The 'text' element contains the text string and is the element whose attributes get changed during the animation.

If scripts are modifying the same attributes or properties that are being animated by SVG'sanimation elements, the scripts modify the base value for the animation. If a base value is modified while an animation element is animating the corresponding attribute or property, the animations are required to adjust dynamically to the new base value.

If a script is modifying a property on the override style sheet at the same time that ananimation element is animating that property, the result is implementation-dependent; thus, it is recommended that this be avoided.

19.4 Animation Module

19.5 DOM interfaces

The following two interfaces are fromSMIL Animation. They are included here for easy reference:

InterfaceElementTimeControl

TheElementTimeControl interface, part of theorg.w3c.dom.smil module and defined in SMIL Animation: Supported interfaces, defines common methods for elements which define animation behaviors compatible with SMIL Animation.

CallingbeginElement() causes the animation to begin in the same way that an animation with event-based begin timing begins. The effective begin time is the current presentation time at the time of the DOM method call. Note thatbeginElement() is subject to therestart attribute in the same manner that event-based begin timing is. If an animation is specified to disallow restarting at a given point,beginElement() methods calls must fail. Refer also to the section Restarting animation.

CallingbeginElementAt(seconds) has the same behavior asbeginElement(), except that the effective begin time is offset from the current presentation time by an amount specified as a parameter. Passing a negative value for the offset causes the element to begin as forbeginElement(), but has the effect that the element begins at the specified offset into its active duration. ThebeginElementAt() method must also respect therestart attribute. The restart semantics for abeginElementAt() method call are evaluated at the time of the method call, and not at the effective begin time specified by the offset parameter.

CallingendElement() causes an animation to end the active duration, just asend does. Depending upon the value of thefill attribute, the animation effect may no longer be applied, or it may be frozen at the current effect. Refer also to the section Freezing animations. If an animation is not currently active (i.e. if it has not yet begun or if it is frozen), theendElement() method will fail.

CallingendElementAt() causes an animation to end the active duration, just asendElement() does, but allows the caller to specify a positive offset, to cause the element to end at a point in the future. Other than delaying when the end actually happens, the semantics are identical to those forendElement(). IfendElementAt() is called more than once while an element is active, the end time specified by the last method call will determine the end behavior.

IDL Definition

interface ElementTimeControl {   boolean beginElement (  )                  raises( DOMException );  boolean beginElementAt ( in float offset )                  raises( DOMException );  boolean endElement (  )                  raises( DOMException );  boolean endElementAt ( in float offset )                  raises( DOMException );};

Methods

beginElement

Causes this element to begin the local timeline (subject to restart constraints).

No Parameters

Return value

boolean

true if the method call was successful and the element was begun.false if the method call failed. Possible reasons for failure include: The element is already active and cannot be restarted when it is active. Therestart attribute is set to"whenNotActive". The element is active or has been active and cannot be restarted. Therestart attribute is set to"never".

Exceptions

DOMException

SYNTAX_ERR: The element was not defined with the appropriate syntax to allowbeginElement calls.

beginElementAt

Causes this element to begin the local timeline (subject to restart constraints), at the passed offset from the current time when the method is called. If the offset is >= 0, the semantics are equivalent to an event-base begin with the specified offset. If the offset is < 0, the semantics are equivalent to beginElement(), but the element active duration is evaluated as though the element had begun at the passed (negative) offset from the current time when the method is called.

Parameters

infloatoffset

The offset in seconds at which to begin the element.

Return value

boolean

true if the method call was successful and the element was begun.false if the method call failed. Possible reasons for failure include: The element is already active and cannot be restarted when it is active. Therestart attribute is set to"whenNotActive". The element is active or has been active and cannot be restarted. Therestart attribute is set to"never".

Exceptions

DOMException

SYNTAX_ERR: The element was not defined with the appropriate syntax to allowbeginElementAt calls.

endElement

Causes this element to end the local timeline.

No Parameters

Return value

boolean

true if the method call was successful and the element was ended.false if method call failed. Possible reasons for failure include: The element is not active.

Exceptions

DOMException

SYNTAX_ERR: The element was not defined with the appropriate syntax to allowendElement calls.

endElementAt

Causes this element to end the local timeline at the specified offset from the current time when the method is called.

Parameters

infloatoffset

The offset in seconds at which to end the element. Must be >= 0.

Return value

boolean

true if the method call was successful and the element was ended.false if the method call failed. Possible reasons for failure include: The element is not active.

Exceptions

DOMException

SYNTAX_ERR: The element was not defined with the appropriate syntax to allowendElementAt calls.

The corresponding Java binding:

package org.w3c.dom.svg;import org.w3c.dom.DOMException;public interface ElementTimeControl {  boolean beginElement (  )                  throws DOMException;  boolean beginElementAt ( float offset )                  throws DOMException;  boolean endElement (  )                  throws DOMException;  boolean endElementAt ( float offset )                  throws DOMException;}

InterfaceTimeEvent

TheTimeEvent interface, defined in SMIL Animation: Supported interfaces defined in SMIL Animation: Supported interfaces, provides specific contextual information associated with Time events.

The different types of events that can occur are:

beginEvent

This event is raised when the element local timeline begins to play. It will be raised each time the element begins the active duration (i.e. when it restarts, but not when it repeats). It may be raised both in the course of normal (i.e. scheduled or interactive) timeline play, as well as in the case that the element was begun with thebeginElement() orbeginElementAt() methods. Note that if an element is restarted while it is currently playing, the element will raise an end event and another begin event, as the element restarts.

• Bubbles: No
• Cancelable: No
• Context Info: None

endEvent

This event is raised at the active end of the element. Note that this event is not raised at the simple end of each repeat. This event may be raised both in the course of normal (i.e. scheduled or interactive) timeline play, as well as in the case that the element was ended with theendElement() orendElementAt() methods. Note that if an element is restarted while it is currently playing, the element will raise an end event and another begin event, as the element restarts.

• Bubbles: No
• Cancelable: No
• Context Info: None

repeatEvent

This event is raised when an element local timeline repeats. It will be raised each time the element repeats, after the first iteration.
The event provides a numerical indication of which repeat iteration is beginning. The value is a 0-based integer, but the repeat event is not raised for the first iteration and so the observed values of the detail attribute will be >= 1.

• Bubbles: No
• Cancelable: No
• Context Info: detail (current iteration)

IDL Definition

interface TimeEvent : events::Event {   readonly attribute views::AbstractView view;  readonly attribute long                detail;  void initTimeEvent ( in DOMString typeArg, in views::AbstractView viewArg, in long detailArg );};

Attributes

readonlyviews::AbstractViewview

Theview attribute identifies theAbstractView [DOM2-VIEWS] from which the event was generated.

readonlylongdetail

Specifies some detail information about the Event, depending on the type of the event. For this event type, indicates the repeat number for the animation.

Methods

initTimeEvent

The initTimeEvent method is used to initialize the value of aTimeEvent created through theDocumentEvent interface. This method may only be called before theTimeEvent has been dispatched via thedispatchEvent method, though it may be called multiple times during that phase if necessary. If called multiple times, the final invocation takes precedence.

Parameters

inDOMStringtypeArg		Specifies the event type.
inviews::AbstractViewviewArg		Specifies the Event'sAbstractView.
inlongdetailArg		Specifies theEvent's detail.

No Return Value

No Exceptions

The corresponding Java binding:

package org.w3c.dom.svg;import org.w3c.dom.events.Event;import org.w3c.dom.views.AbstractView;public interface TimeEvent extends                Event {  public AbstractView getView( );  public int          getDetail( );  void initTimeEvent ( String typeArg, AbstractView viewArg, int detailArg );}

The following interfaces are defined below:SVGAnimationElement,SVGAnimateElement,SVGSetElement,SVGAnimateMotionElement,SVGMPathElement,SVGAnimateColorElement,SVGAnimateTransformElement.

InterfaceSVGAnimationElement

TheSVGAnimationElement interface is the base interface for all of the animation element interfaces:SVGAnimateElement,SVGSetElement,SVGAnimateColorElement,SVGAnimateMotionElement andSVGAnimateTransformElement.

Unlike other SVG DOM interfaces, the SVG DOM does not specify convenience DOM properties corresponding to the various language attributes on SVG's animation elements. Specification of these convenience properties in a way that will be compatible with future versions of SMIL Animation is expected in a future version of SVG. The current method for accessing and modifying the attributes on the animation elements is to use the standardgetAttribute,setAttribute,getAttributeNS andsetAttributeNS defined in DOM2.

IDL Definition

interface SVGAnimationElement :                 SVGElement,                SVGTests,                SVGExternalResourcesRequired,                smil::ElementTimeControl,                events::EventTarget {   readonly attribute SVGElement targetElement;  float getStartTime (  );  float getCurrentTime (  );  float getSimpleDuration (  )                  raises( DOMException );};

Attributes

readonlySVGElementtargetElement

The element which is being animated.

Methods

getStartTime

Returns the start time in seconds for this animation.

No Parameters

Return value

float

The start time in seconds for this animation relative to the start time of the time container.

No Exceptions

getCurrentTime

Returns the current time in seconds relative to time zero for the given time container.

No Parameters

Return value

float

The current time in seconds relative to time zero for the given time container.

No Exceptions

getSimpleDuration

Returns the number of seconds for the simple duration for this animation. If the simple duration is undefined (e.g., the end time is indefinite), then an exception is raised.

No Parameters

Return value

float

The number of seconds for the simple duration for this animation.

Exceptions

DOMException

NOT_SUPPORTED_ERR: The simple duration is not determined on the given element.

InterfaceSVGAnimateElement

TheSVGAnimateElement interface corresponds to the'animate' element.

Object-oriented access to the attributes of the'animate' element via the SVG DOM is not available.

IDL Definition

interface SVGAnimateElement : SVGAnimationElement {};

InterfaceSVGSetElement

TheSVGSetElement interface corresponds to the'set' element.

Object-oriented access to the attributes of the'set' element via the SVG DOM is not available.

IDL Definition

interface SVGSetElement : SVGAnimationElement {};

InterfaceSVGAnimateMotionElement

TheSVGAnimateMotionElement interface corresponds to the'animateMotion' element.

Object-oriented access to the attributes of the'animateMotion' element via the SVG DOM is not available.

IDL Definition

interface SVGAnimateMotionElement : SVGAnimationElement {};

InterfaceSVGMPathElement

TheSVGMPathElement interface corresponds to the'mpath' element.

IDL Definition

interface SVGMPathElement :                 SVGElement,                SVGURIReference,                SVGExternalResourcesRequired {};

InterfaceSVGAnimateColorElement

TheSVGAnimateColorElement interface corresponds to the'animateColor' element.

Object-oriented access to the attributes of the'animateColor' element via the SVG DOM is not available.

IDL Definition

interface SVGAnimateColorElement : SVGAnimationElement {};

InterfaceSVGAnimateTransformElement

TheSVGAnimateTransformElement interface corresponds to the'animateTransform' element.

Object-oriented access to the attributes of the'animateTransform' element via the SVG DOM is not available.

IDL Definition

interface SVGAnimateTransformElement : SVGAnimationElement {};