13 Animation

13.1 The animation element

The animation elements specifies an SVG document or an SVG document fragment which provided synchronized animated vector graphics. Like video, the animation element is a graphical object with size determined by its x, y, width and height attributes.

  <define name='animation'>
    <element name='animation'>
      <ref name='attlist.animation'/>
      <ref name='SVG.animation.content'/>
    </element>
  </define>

  <define name='SVG.animation.content'>
    <zeroOrMore>
      <ref name='SVG.Description.class'/>
    </zeroOrMore>
    <zeroOrMore>
      <choice>
        <ref name='SVG.Animation.class'/>
        <ref name='SVG.Handler.class'/>
      </choice>
    </zeroOrMore>
  </define>

  <define name='attlist.animation' combine='interleave'>
    <ref name='SVG.Core.attrib'/>
    <ref name='SVG.Conditional.attrib'/>
    <ref name='SVG.Opacity.attrib'/>
    <ref name='SVG.Graphics.attrib'/>
    <ref name='SVG.Focusable.attrib'/>
    <ref name='SVG.Clip.attrib'/>
    <ref name='SVG.Mask.attrib'/>
    <ref name='SVG.Filter.attrib'/>
    <ref name='SVG.Compositing.attrib'/>
    <ref name='SVG.GraphicalEvents.attrib'/>
    <ref name='SVG.Tooltip.attrib'/>
    <ref name='SVG.Cursor.attrib'/>
    <ref name='SVG.XLinkEmbed.attrib'/>
    <ref name='SVG.External.attrib'/>
    <ref name='SVG.AnimationTiming.attrib'/>
    <ref name='SVG.Media.attrib'/>
    <ref name='SVG.Filter.attrib'/>
    <ref name='SVG.Compositing.attrib'/>
    <ref name='SVG.GraphicalEvents.attrib'/>
    <ref name='SVG.Tooltip.attrib'/>
    <ref name='SVG.Cursor.attrib'/>
    <ref name='SVG.XLinkEmbed.attrib'/>
    <ref name='SVG.External.attrib'/>
    <ref name='SVG.AnimationTiming.attrib'/>
    <ref name='SVG.Media.attrib'/>
    <ref name='SVG.BackgroundFill.attrib'/>
    <ref name='SVG.AnimationTimingNoMinMax.attrib'/>
    <ref name='SVG.AnimationSync.attrib'/>
    <optional>
      <attribute name='x' svg:animatable='true' svg:inheritable='false'>
        <ref name='Coordinate.datatype'/>
      </attribute>
    </optional>
    <optional>
      <attribute name='y' svg:animatable='true' svg:inheritable='false'>
        <ref name='Coordinate.datatype'/>
      </attribute>
    </optional>
    <attribute name='width' svg:animatable='true' svg:inheritable='false'>
      <ref name='Length.datatype'/>
    </attribute>
    <attribute name='height' svg:animatable='true' svg:inheritable='false'>
      <ref name='Length.datatype'/>
    </attribute>
    <optional>
      <attribute name='preserveAspectRatio' a:defaultValue='xMidYMid meet' 
         svg:animatable='yes' svg:inheritable='false'>
        <ref name='PreserveAspectRatioSpec.datatype'/>
      </attribute>
    </optional>
    <ref name='SVG.transform.attrib'/>
  </define>

The usual SMIL animation features are used to start and stop the animation at the appropriate times. The xlink:href attribute refers to the vector graphics content that is to be animated.

In the case where the animation element references an external SVG document the same set of rules as used when referencing external SVG images apply.

In the case where the animation element references an SVG document fragment, the conceptual processing model is that the entire document containing the fragment is processed as a complete SVG document instance (coordinate systems transformations and stylesheets are applied; scripts are executed; etc.). The document is conceptually rendered to an invisible (offscreen) canvas except for the referenced fragment which is rendered directly to the screen canvas. When the animation element references a document fragment the preserveAspectRatio attribute has no meaning. The rules for applying x, y, width and height are the same set of rules that apply for the use element.

The following example illustrates the use of the animation element.

<svg xmlns="http://www.w3.org/2000/svg" 
     xmlns:xlink="http://www.w3.org/1999/xlink"
     version="1.2">

  <defs>
    <rect id="movieClip" x="-50" y="-50" width="100" height="100" 
          fill="purple" stroke="black">

      <animate attributeName="fill" values="purple;yellow;purple" 
               keyTimes="0;.5;1" begin="0" dur="2" fill="freeze"/>

   </rect>
  </defs>


  <animation begin="1" dur="3" repeatCount="1.5" fill="freeze" 
             x="100 y="100" width="100" height="100" 
             xlink:href="#movieClip"/>

  <animation begin="2" 
             x="100" y="300" width="100" height="100"
             xlink:href="#movieClip"/>

</svg>

The DOM interface for the animation element is shown below:

interface SVGAnimationElement:
  SVGMediaElement, 
  SVGURIReference,
  SVGLangSpace,
  SVGStylable,
  SVGTransformable {

readonly attribute SVGAnimatedLength x;
readonly attribute SVGAnimatedLength y;
readonly attribute SVGAnimatedLength width;
readonly attribute SVGAnimatedLength height;
readonly attribute SVGAnimatedPreserveAspectRatio preserveAspectRatio;

};

13.1.1 Transition effects

There exist a number of usage scenarios for transition effects between views of SVG. For example, an image slideshow or multipage SVG documents.

SMIL 2.0 defines syntax for allowing the transition between multimedia elements to include a transition, such as a fadein/fadeout. There is a comprehensive set of transition effects defined by SMPTE and listed in an appendix of SMIL 2.0 Transition Effects

SVG 1.2 adds the transition effects from SMIL 2.0, in particular the transition element and the transIn and transOut attributes.

13.1.1.1 The transition element

The transition element defines a single transition class. A transition element can be the child of any class, although normally they are defined within a defs section.

  <define name='transition'>
    <element name='transition'>
      <ref name='attlist.transition'/>
      <ref name='SVG.transition.content'/>
    </element>
  </define>

  <define name='attlist.transition' combine='interleave'>
    <ref name='SVG.Core.attrib'/>
    <optional>
      <attribute name='dur'/>
    </optional>
    <optional>
      <attribute name='startProgress'>
        <data type='float'/>
      </attribute>
    </optional>
    <optional>
      <attribute name='endProgress'>
        <data type='float'/>
      </attribute>
    </optional>
    <optional>
      <attribute name='direction' a:defaultValue='forward'>
        <choice>
          <value>forward</value>
          <value>reverse</value>
        </choice>
      </attribute>
    </optional>
    <optional>
      <attribute name='fadeColor' a:defaultValue='black'/>
    </optional>

    <!-- refer to the full schema for the transition type
         attributes. -->
    <ref name='attlist.transition-types'/>
  </define>

  <define name='SVG.transition.content'>
    <zeroOrMore>
      <ref name='SVG.Description.class'/>
    </zeroOrMore>
  </define>

  <define name='SVG.Transition.attrib' combine='interleave'>
    <ref name='transIn.attrib'/>
    <ref name='transOut.attrib'/>
  </define>

  <define name='transIn.attrib'>
    <optional>
      <attribute name='transIn'/>
    </optional>
  </define>

  <define name='transOut.attrib'>
    <optional>
      <attribute name='transOut'/>
    </optional>
  </define>

Attributes:

type

The type of transition. This attribute is required and must be one of the transition families listed in the SMIL 2.0 Transitions Taxonomy.

subtype

The subtype of the transition. If specified then the attribute must be a recognized subtype of the transition type. If not specified, then the subtype is the default for the particular transition type.

dur

The duration of the transition. If specified it must be a clock-value. The default value is "1s".

startProgress

This is the amount of progress through the transition at which to begin execution. Legal values are real numbers in the range 0.0-1.0. For instance, we may want to begin a crossfade with the destination image being already 30% faded in. For this case, startProgress would be 0.3. The default value is 0.0.

endProgress

This is the amount of progress through the transition at which to end execution. Legal values are real numbers in the range 0.0-1.0 and the value of this attribute must be greater than or equal to the value of the startProgress attribute. If endProgress is equal to startProgress, then the transition remains at a fixed progress for the duration of the transition. The default value is 1.0.

direction

This specifies the direction the transition will run. The legal values are "forward" and "reverse". The default value is "forward". Note that this does not impact the media being transitioned to, but only affects the geometry of the transition. For instance, if you specified a type of "barWipe" and a subtype of "leftToRight", then the media would be wiped in by a vertical bar moving left to right. However, if you specified direction="reverse", then it would be wiped in by the same vertical bar moving right to left. Another example is the type of "starWipe" and subtype of "fourPoint". For this transition, running the transition forward reveals the destination media on the inside of a four-point star which starts small and gets larger as the transition progresses. Running this transition in reverse would reveal the destination media in the area outside of a large four-point star. The star begins large and gets smaller as the transition progresses. Note that not all transitions will have meaningful reverse interpretations. For instance, a crossfade is not a geometric transition, and therefore has no interpretation of reverse direction. Transitions which do not have a reverse interpretation should ignore the direction attribute and assume the default value of "forward".

fadeColor

If the value of the "type" attribute is "fade" and the value of the "subtype" attribute is "fadeToColor" or "fadeFromColor", then this attribute specifies the starting or ending color of the fade. If the value of the "type" attribute is not "fade", or the value of the "subtype" attribute is not "fadeToColor" or "fadeFromColor", then this attribute is ignored. The allowed values are any color value or a reference to a solidColor object. The default value is "black".

None of the attributes on the transition element are animatable.

SVG 1.2 does not allow extensions to the transition types specified by SMIL 2.0.

13.1.1.2 The transition attributes

Once a transition has been defined in a document, then an transition effect is applied by referencing the transition from the transIn and transOut attributes. The transition attributes are added to the elements that can undergo a transition (listed below).

Transitions specified with a transIn attribute will begin at the beginning of the animation's active duration. Transitions specified with a transOut attribute will end at the end of the animation's active duration or end at the end of the element's fill state if a non-default fill value is applied.

Note that in SVG, the transition effects only apply to animations modifying the xlink:href attribute of graphical elements: image, video, use, page and feImage.

The value of the attributes is a semicolon-separated list of transition element identifiers. The transition used is the first supported transition in the list.

Below is an example of a transition:

<svg width="100%" height="100%" version="1.2"
     xmlns="http://www.w3.org/2000/svg"
     xmlns:xlink="http://www.w3.org/1999/xlink">

  <defs>
    <transition id="fadeToRed2s" type="fade" subtype="fadeToColor"
                fadeColor="red" dur="2s"/>
    <transition id="fadeFromRed1s" type="fade" subtype="fadeFromColor"
                fadeColor="red" dur="1s"/>
  </defs>
 
  <image x="0" y="0" width="100" height="100"
         transIn="fadeFromRed1s"
         transOut="fadeToRed2s">

    <animate attributeType="XML"
             attributeName="xlink:href"
             begin="0s"
             dur="60s"
             values="1.jpg;2.jpg;3.jpg;4.jpg"
             fill="freeze"/>

  </image>

</svg>

13.2 Media elements

SVG supports media elements similar to the SMIL Media Elements. Media elementsdefine their own timelines within their time container. All SVG Media elements support the SVG Timing attributes and run time synchronization.

The following elements are media elements:

• video
• audio
• animation

13.3 Time containers

SVG supports a subset of SMIL 2.0's feature set for nested time containers. All time containers support all or some of the SVG Timing Attributes. The following elements in the SVG language define a new time container:

• svg: is a parallel time container. All descendant elements represent time-based elements with a default timeAction of 'display'.
• pageSet: is a sequential time container. Its page children elements represent time-based elements with a default timeAction of 'display'.
• page: is a parallel time container. All descendant elements represent time-based elements with a default timeAction of 'display'.

Time containers and timeAction are defined by the SMIL2.0 spec.

13.4 Attributes for run-time synchronization

SVG supports the following attributes on time containers and media elements from SMIL 2.0 to control run-time synchronization of different time containers:

• syncBehavior: (canSlip | locked | independent | default)
• syncBehaviorDefault: ( canSlip | locked | independent | inherit )
• syncTolerance: ( Clock-value | default )
• syncToleranceDefault: ( Clock-value | inherit )

The normative definition for these attributes is the SMIL 2.0 specification.

13.5 Time Manipulation

SVG 1.2 adds the speed attribute from the SMIL 2.0 Timing Manipulations Module.

The speed attribute controls the local playback speed of an element, to speed up or slow down the effective rate of play relative to the parent time container. The speed attribute is supported on all timed elements. The argument value does not specify an absolute play speed, but rather is relative to the playback speed of the parent time container. The specified value cascades to all time descendants. Thus if a par and one of its children both specify a speed of 50%, the child will play at 25% of normal playback speed.

Values less than 0 are allowed, and cause the element to play backwards. An element can only play backwards if there is sufficient information about the simple and active durations. Specifically:

• The element simple duration must be resolved and may not be indefinite.
• The element active duration must be resolved and not indefinite, OR the element active duration must be constrained by a resolved simple duration for its associated time container. There must be a means of defining active time running backwards.

If the cascaded speed value for the element is negative and if either of the above two conditions is not met, the element will begin and immediately end (i.e. it will behave as though it had a specified active duration of 0).

13.6 Enhanced ElementTimeControl interface

In SVG 1.2, a document may contain multiple time containers, such as multiple pages or video elements. In order to pause a particular container or timed element, the ElementTimeControl interface has been extended.

interface ElementTimeControl {
   void            beginElement();
   void            beginElementAt(in float offset);
   void            endElement();
   void            endElementAt(in float offset);
   void            pauseElement();
   void            unpauseElement();
   readonly boolean elementPaused;
}

The ElementTimeControl interface is added to all media elements and all time containers.

13.7 Triggering animations using key events

SVG 1.2 updates the definition of the accessKey syntax used to control the animation begin or end.

accessKey-value ::= "accessKey(" character ")" ( S? ("+"|"-") S? Clock-value)?

Describes an accessKey that determines the element begin. The element begin is defined relative to the time of the keydown event corresponding to the specified key. From a formal processing model perspective, accessKey is a keydown event listener on the document which behaves as if stopPropagation() and preventDefault() have both been invoked. The "character" value can be any of the keyboard event identifier strings listed in Appendix A.2 of the DOM3 Events specification.