18 Animation
Contents
18.1 Introduction
The Web is
a dynamic medium and that SVG needs to support the ability
to change vector graphics over time. SVG documents can be animated in the following ways:
- Using SVG's Animation Elements.
An SVG document can describe time-based modifications
to the document's elements. Using the various animation elements,
you can do motion paths, fade-in/fade-out effects and objects that
grow, shrink, spin or change color.
- Using the SVG DOM. The SVG DOM conforms
to key aspects of
Document
Object Model (DOM) Level 1 Specification and
Document
Object Model (DOM) Level 2 Specification.
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.
(See example below.)
- SVG documents can be components within
SMIL (Synchronized Multimedia Integration Language)
documents.
- 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 such as XHTML to achieve animation effects.
18.2 Animation elements
18.2.1 Introduction
The animation elements in SVG were developed in collaboration
with the W3C Synchronized Multimedia (SYMM) Working Group,
developers of the Synchronized Multimedia Integration
Language (SMIL) 1.0 Specification
[SMIL1], with an attempt
at compatibility with SYMM work-in-progress efforts towards formulating
SMIL 2.0 and general animation facilities for XML grammars
such as XHTML [XHTML10].
18.2.2 The <animate> element
The <animate> element is used to animate
a single XML attribute or property over time. For example, to
make a rectangle repeatedly fade away over 5 seconds, you can
specify (??? better examples will come later):
<rect id="MyRect" ...>
<animate href="#foo"
attributeType="css" attribute="opacity"
from="1" to="0" dur="5s" repeatCount="indefinite" />
Attribute definitions:
-
xlink:href = "uri-reference"
- A URI reference to the element
which is the target of this animation and which therefore
will have one of its attributes modified over time.
The target element must be part of the current SVG document.
-
attribute = "<attributeName>"
- The name of the attribute or property which is to be animated.
-
attributeType = "xml | css"
- Indicate the type of the attribute or property.
A value of attributeType="xml" indicates the
attribute represents the name of an XML attribute
on the element referenced by xlink:href.
A value of attributeType="css" indicates the
attribute represents the name of an CSS property
on the element referenced by xlink:href.
-
begin = "value"
- Specifies the time for the explicit begin of the animation relative to
the completion of document loading. The attribute can contain the following two types of values:
-
<delay-value>
-
A <delay-value> is a clock-value measuring presentation time. Presentation
time advances at the speed of the presentation. It behaves like the timecode
shown on a counter of a tape-deck. It can be stopped, decreased or increased
either by user actions, or by the player itself.
-
<event-value>
-
The element begins when a certain event occurs. Its value
is an element-event. (??? Need definition of "element-event".
The element generating the event must be "in scope". (??? Need definition of "in scope".)
-
none (the default)
-
The animation should not start automatically; instead, the animation
should only start in response to an explicit event.
For more information, see the SMIL 1.0 specification [SMIL1].
-
end = "value"
- Specifies the time for the explicit end of the animation relative to
the completion of document loading. The attribute can contain the same types of
attribute values as the begin attribute.
-
dur = "<clock-value>"
- Specifies the explicit duration of the animation.
-
repeatCount = "<number> | indefinite"
- Specifies either the <number> of times to loop through the animation
or indefinite, which indicates that the animation should be repeated indefinitely.
Legal <number> values are integer or fractional iterations, greater than 0.
A repeat count of less than 1 will cut short the specified simple duration.
At most one of repeatCount or repeatDur should be specified (if both are specified, the repeat
duration is defined as the minimum of the specified repeatDur, and the simple duration
multiplied by the repeatCount (count).
The default value is one.
-
repeatDur = "<clock-value>"
- This causes the element to play repeatedly (loop) for the specified duration. Each repeat
iteration lasts for the simple duration. This attribute has no affect if the duration is 0.
A repeat duration less than the simple duration specified in dur will cut short the duration. A
repeat duration equal to the simple duration is a no-op.
Legal values are clock values greater than 0.
In addition, "indefinite" may be specified to indicate that the element should repeat indefinitely
(subject to the time container semantics).
At most one of repeatCount or repeatDur should be specified (if both are specified, the repeat
duration is defined as the minimum of the specified repeatDur, and the simple duration
multiplied by the repeatCount (count).
-
beginEvent = "<clock-value>"
- Defines the timebase to be the referenced event. Events can be timing events (e.g.
element.onBegin) as well as any other event supported by the DOM (e.g. element.onclick,
document.onscroll). This supports interactive timing within a document, and reduces the need to
add script to "wire" elements together.
The current element will begin when the referenced event is raised (plus any offset value). If the
referenced event is never raised, the current element may never be active/displayed. If a negative
begin (delay) value is used with this attribute, the element will become active when the event is
raised, but will define the local timeline sync according to the offset.
Legal values are:
- event-base-value :
- ("id(" id-ref ")")? ( event-ref ) ( signed-clock-val )?
Any defined event name, referenced by the associated element ID.
E.g. beginEvent="id(button1)(onclick)(3s)".
Note that if the id-ref is omitted, the current element is assumed.
An alternative syntax would follow ECMAScript conventions:
[id-ref "." ]? event-ref [ "+"|"-" signed-clock-val ]?
E.g. beginEvent="button1.onclick+3s"
- "none"
- The string "none".
-
endEvent = "<clock-value>"
- Defines the end of the active duration to be relative to the referenced event. Events can be
timing events (e.g. element.onBegin) as well as any other event supported by the DOM (e.g.
element.onClick, document.onscroll). See also the notes on beginEvent.
The active duration of the current element will end when the referenced event is raised (plus any
offset). If the referenced event is never raised, the current element may remain active.
If a negative delay value is used with this attribute, it will be ignored.
This attribute may be combined with a determinate specification for the element end.
If a finite active duration is defined for the element (with the end or dur attributes and/or
repeatCount/repeatDur), the element will end at the earlier of the specified duration or the endEvent
time. This allows authors to specify a maximum duration in addition to and interactive end.
If the named event is "none", this element will simply wait to be turned off (e.g. by script). This is
not required, and is more easily accomplished by specifying no end or duration for an
element; it will default to an indefinite duration, and can be ended via the DOM interfaces.
Legal values are:
- event-base-value :
- ("id(" id-ref ")")? ( event-ref ) ( signed-clock-val )?
Any defined event name, referenced by the associated element ID.
E.g. beginEvent="id(button1)(onclick)(3s)".
Note that if the id-ref is omitted, the current element is assumed.
An alternative syntax would follow ECMAScript conventions:
[id-ref "." ]? event-ref [ "+"|"-" signed-clock-val ]?
E.g. endEvent="button1.onclick+3s"
- "none"
- The string "none".
-
additive = "true | false"
- Controls whether or not the animation is additive. Possible values are "true" and "false". Default is
"false", unless another attribute is used which specifies otherwise. This attribute is ignored if the
target attribute does not support addition.
-
accumulate = "true | false"
- Controls whether or not the animation is cumulative. Possible values are "true" and "false". Default
is "false". This attribute is ignored if the target attribute does not support addition.
-
fill = "remove | freeze"
- Controls whether the final result of the animation should remain past the
end of the duration of the animation. remove indicates that
the element should revert to its original values at the end of the animation.
freeze indicates that
the element should retain the final attribute/property value that is in place at the end of the animation.
Default is "remove".
-
values = "<list>"
- A semicolon-separated list of one or more values, compatible with the target attribute.
-
from = "<value>"
- Specifies the starting value of the animation.
If from is specified, its value must match
the to or by type.
If the from value is not specified,
The value must be compatible with the target attribute.
-
to = "<value>"
- Specifies the ending value of the animation. The argument value must match the attribute type.
Specifies a non-additive animation with 2 elements in the values array, the value of the from
attribute and the value of the to attribute. The from attribute defaults to the base value of the
attribute for the animation when to is used.
by = "<value>"
- Specifies a relative offset value for the animation. he argument value must match the attribute type.
Specifies an additive animation with two elements in the values array, from and by. The from
attribute defaults to zero when by is used.
-
calcMode = "discrete | linear | spline"
- Specifies the interpolation mode for the animation. This can take any of the following values:
- "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.
Treated as "discrete" if the attribute does not support linear interpolation. This is the default
calcMode.
- "spline"
- As for linear, interpolating from one value in the values list to the next by the the amount of
time elapsed defined by a cubic Bezier spline defined by the interpSpline attribute.
-
vtimes = "<list>"
- A semicolon-separated list of explicit time values
defining when each of the values in the values attribute
should become the current value. vtimes are specified
as decimal fractions between 0 and 1, representing the relative offset
into the duration of the
<animate> element.
If the vtimes attribute is not present,
the values in the values attribute are assumed
to be equally spaced through the animation duration, with the first value
being applied at the very beginning of the animation,
and the last value being applied at the very end of the animation.
There should be exactly as many values in the
vtimes list as in the
values list.
If more vtimes are provided than
values, then the extra
vtimes are ignored.s in the
values list.
If more values are provided than
vtimes, then the extra
values are ignored.
-
interpSpline = "<list>"
- A semicolon-separated list of 4-tuples of numbers that specify
a non-linear interpolation between each corresponding pair of
values. Each 4-tuple x1 y1 x2 y2
defines the control points for a cubic bezier segment
within the unit square (0,0) to (1,1).
The interpolations are done as follows:
Suppose you are at time t, where t[i] < t < t[i+1], where
t[i] is the timevalue coresponding to values[i].
Then, calculate a weighting factor w = y(t), where
y(t) is the cubic bezier formula for y as a function of t,
where the cubic bezier is defined by anchor points
(0,0) and (1,1) and control points (x1,y1) and (x2,y2).
Finally, the value to use at time t is calculated by:
value = (1-w) * values[i] + w * values[i+1].
- Attributes defined elsewhere:
-
id,
system-required.
xmlns:xlink,
xlink:type,
xlink:role,
xlink:title,
xlink:show,
xlink:actuate.
18.2.3 The <animateMotion> element
The <animateMotion> element cause a
<symbol> or
<svg> element.
to move along a motion path. (??? Examples coming later.)
Attribute definitions:
-
xlink:href = "uri-reference"
- A URI reference to the element
which is the target of this animation and which therefore
will have its position modified over time.
The target element must be part of the current SVG document.
The target element must be a
<symbol> or
<svg> element.
The <symbol> will be scaled to fit into
a viewport whose width and height are one unit in user space.
To scale the symbol to the appropriate size, use the
<animateTransform>
element and have it reference this.<animateMotion> element.
-
motionPath = "<path-data>"
- The motion path, expressed in the same format and interpreted the
same way as the d= attribute
on the <path> element.
The target element moves along the given path.
-
rotate = "<angle> | auto"
- auto is default, which says to rotate object to
track the tangent of the motion path.
An actual angle value can also be given, which is
relative to X-axis of current coordinate system.
-
values = "<list>"
- A semicolon-separated list of one or more values which represents
the relative percentage
of distance along the motion path.
(Note: the default yields constant velocity from the start
of the path to the end of the path.)
For example: values="0% 30% 90%" or values="0 .3 .9",
which says (assuming the default value for vtimes) that you start
at the beginning of the path, end up at 30% along the path
at time .5, and end up at .9 along the path at time 1.
from="" to="" by="" are also available.
Values less than zero or
greater than one are adjusted to stay between zero and one.
-
from = "<value>"
- Specifies the starting value of the animation as a relative percentage
distance along the motion path.
-
to = "<value>"
- Specifies the ending value of the animation as a relative percentage
distance along the motion path.
-
by = "<value>"
- Specifies a relative offset value for the animation as a relative percentage
distance along the motion path.
- Attributes defined elsewhere:
-
id,
system-required.
xmlns:xlink,
xlink:type,
xlink:role,
xlink:title,
xlink:show,
xlink:actuate.
begin,
end,
dur,
repeatCount,
repeatDur,
beginEvent,
endEvent,
fill,
calcMode,
vtimes,
interpSpline.
18.2.4 The <animateTransform> element
The <animateTransform> element adds
a supplemental transformation onto a target element so that
it can be translated, scaled, rotated or skewed. (??? Examples coming later.)
Attribute definitions:
-
xlink:href = "uri-reference"
- A URI reference to the element
which is the target of this animation and which therefore
will have its current transformation matrix modified over time.
The target element must be part of the current SVG document.
-
values = "<list>"
- A semicolon-separated list of one or more values which represents
one of the following simple forms of the
transform
attribute:
- translate(x,y)
- scale(x[,y])
- rotate(angle)
- skewX(angle)
- skewY(angle)
All of the values must use the same form; thus, you can specify
values="rotate(30);rotate(90);rotate(180)"
but you cannot specify
values="rotate(30);scale(2);translate(3,5)".
To mix different types of transformations, use multiple
<animateTransform> operating
on the same target element with
additive="true".
-
from = "<value>"
- Specifies the starting value of the animation. The value must use the
same form as to and/or by.
-
to = "<value>"
- Specifies the ending value of the animation. The value must use the
same form as from and/or by.
-
by = "<value>"
- Specifies a relative offset value for the animation. The value must use the
same form as from and/or to.
- Attributes defined elsewhere:
-
id,
system-required.
xmlns:xlink,
xlink:type,
xlink:role,
xlink:title,
xlink:show,
xlink:actuate.
begin,
end,
dur,
repeatCount,
repeatDur,
beginEvent,
endEvent,
fill,
calcMode,
vtimes,
interpSpline.
18.2.5 The <animateColor> element
The <animateColor> element specifies
a color transformation over time. (??? Examples coming later.)
Attribute definitions:
-
xlink:href = "uri-reference"
- A URI reference to the element
which is the target of this animation and which therefore
will have its color modified over time.
The target element must be part of the current SVG document.
-
values = "<list>"
- A semicolon-separated list of color values using any color formulation
that is valid for SVG's various color properties.
Out of range and negative values are permitted, such as, "rgb(-50, 0, 0)".
-
from = "<value>"
- Specifies the starting color value of the animation. Allowable forms
are the same as for the values attribute.
-
to = "<value>"
- Specifies the ending color value of the animation. Allowable forms
are the same as for the values attribute.
-
by = "<value>"
- Specifies a relative offset color value for the animation. Allowable forms
are the same as for the values attribute.
- Attributes defined elsewhere:
-
id,
system-required.
xmlns:xlink,
xlink:type,
xlink:role,
xlink:title,
xlink:show,
xlink:actuate.
begin,
end,
dur,
repeatCount,
repeatDur,
beginEvent,
endEvent,
fill,
calcMode,
vtimes,
interpSpline.
18.2.6 The <animateFlipbook> element
The <animateFlipbook> element produces
a flipbook-like animation effect. The list of
child <animateFlipbookValue> elements
provides indicates the series of elements to make visible one after another
as the animation executes. (??? Examples coming later.)
- Attributes defined elsewhere:
-
id,
system-required.
begin,
end,
dur,
repeatCount,
repeatDur,
beginEvent,
endEvent,
fill,
calcMode,
vtimes.
Attribute definitions:
-
xlink:href = "uri-reference"
- A URI reference to the element
which should be made visible at the appropriate time in this animation.
The target elements must be part of the current SVG document.
- Attributes defined elsewhere:
-
id,
xmlns:xlink,
xlink:type,
xlink:role,
xlink:title,
xlink:show,
xlink:actuate.
18.3 Animation example using the SVG DOM
The following example shows a simple animation:
<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG August 1999//EN"
"http://www.w3.org/Graphics/SVG/SVG-19990812.dtd">
<svg width="4in" height="3in"
viewBox="0 0 400 300"
onload="StartAnimation()" >
<defs>
<script><![CDATA[
var timer_increment = 50.
var max_time = 10000
var text_element
StartAnimation() {
text_element = document.getElementById("TextElement");
ShowAndGrowElement(0);
}
ShowAndGrowElement(timevalue) {
timevalue = timevalue + timer_increment
if (timevalue > max_time)
timevalue = timevalue - floor(timevalue/max_time) * max_time
// 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.getStyle().setProperty("opacity", "opacity:" + opacityfactor, "")
// Call ShowAndGrowElement again <timer_increment> milliseconds later.
setTimeout("ShowAndGrowElement(" + timer_increment + ")")
}
]]></script>
</defs>
<g transform="translate(50,300)" style="fill:red; font-size:10">
<text id="TextElement">SVG</text>
</g>
</svg>
Download this example
The above SVG file contains a single graphics element, a text string
that says "SVG". The animation loops continuously. The text string starts
out small and transparent and grows to be large and opaque. Here is
an explanation of how this example works:
- The <svg> element's
width and height
attributes indicate that the document should take up
a rectangle of size 4inches by 3inches.
The viewBox attribute indicates that the initial
coordinate system should have (0,0) at its top left and (400,300) at
its bottom right. (Thus, 1 inch equals 100 user units.)
The onload="StartAnimation()" attribute indicates that when
the document has been fully loaded and processed, then invoke
ECMAScript function StartAnimation().
- The <script> element defines the ECMAScript which makes
the animation happen. The
StartAnimation() function is only called once
to give a value to global variable text_element and to
make the initial call to ShowAndGrowElement().
ShowAndGrowElement() is called every 50 milliseconds and
resets the transform and style attributes
on the text element to new values each time it is called.
At the end of ShowAndGrowElement, 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.