You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
5561 lines
290 KiB
5561 lines
290 KiB
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
|
|
"http://www.w3.org/TR/REC-html40/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<style type="text/css">
|
|
H4, H5, H6 {text-align: left; font-family: sans-serif; font-weight: normal; color: #0050B2; }
|
|
p, blockquote, h4 { font-family: sans-serif; }
|
|
dt, dd, dl, ul, li { font-family: sans-serif; }
|
|
pre, code { font-family: monospace }
|
|
|
|
/* Table of contents styles */
|
|
div.toc {background-color: #ccccff; border: none; margin-right: 5%; }
|
|
|
|
</style>
|
|
<title>SMIL Animation</title>
|
|
<link rel="stylesheet" type="text/css"
|
|
href="http://www.w3.org/StyleSheets/TR/W3C-REC.css">
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<div class="head">
|
|
<p><a href="http://www.w3.org/"><img src="http://www.w3.org/Icons/w3c_home" alt="W3C" height="48" width="72"></a></p>
|
|
|
|
<h1 class="notoc" id="h001">SMIL Animation</h1>
|
|
|
|
<h2 class="notoc" id="h002">W3C Recommendation 04-September-2001</h2>
|
|
<dl>
|
|
<dt>This version:</dt>
|
|
<dd><a href="http://www.w3.org/TR/2001/REC-smil-animation-20010904/">http://www.w3.org/TR/2001/REC-smil-animation-20010904/</a></dd>
|
|
<dt>Latest version:</dt>
|
|
<dd><a href="http://www.w3.org/TR/smil-animation">http://www.w3.org/TR/smil-animation</a></dd>
|
|
<dt>Previous version:</dt>
|
|
<dd><a href="http://www.w3.org/TR/2001/PR-smil-animation-20010719/">http://www.w3.org/TR/2001/PR-smil-animation-20010719</a></dd>
|
|
<dt>Editor(s)</dt>
|
|
<dd>Patrick Schmitz (<a
|
|
href="mailto:pschmitz@microsoft.com">pschmitz@microsoft.com</a>),
|
|
Microsoft</dd>
|
|
<dd>Aaron Cohen (<a
|
|
href="mailto:aaron.m.cohen@intel.com">aaron.m.cohen@intel.com</a>),
|
|
Intel</dd>
|
|
</dl>
|
|
|
|
<p class="copyright"><a
|
|
href="http://www.w3.org/Consortium/Legal/ipr-notice-20000612#Copyright">Copyright</a>
|
|
©2001 <a href="http://www.w3.org/"><abbr
|
|
title="World Wide Web Consortium">W3C</abbr></a><sup>®</sup> (<a
|
|
href="http://www.lcs.mit.edu/"><abbr
|
|
title="Massachusetts Institute of Technology">MIT</abbr></a>, <a
|
|
href="http://www.inria.fr/"><abbr lang="fr"
|
|
title="Institut National de Recherche en Informatique et Automatique">INRIA</abbr></a>,
|
|
<a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a
|
|
href="http://www.w3.org/Consortium/Legal/ipr-notice-20000612#Legal_Disclaimer">liability</a>,
|
|
<a
|
|
href="http://www.w3.org/Consortium/Legal/ipr-notice-20000612#W3C_Trademarks">trademark</a>,
|
|
<a
|
|
href="http://www.w3.org/Consortium/Legal/copyright-documents-19990405">document
|
|
use</a> and <a
|
|
href="http://www.w3.org/Consortium/Legal/copyright-software-19980720">software
|
|
licensing</a> rules apply.</p>
|
|
|
|
<p></p>
|
|
<hr title="Separator from Header">
|
|
</div>
|
|
|
|
<h2 id="h003">Abstract</h2>
|
|
|
|
<p>This is a W3C Recommendation of a specification of animation functionality for
|
|
XML documents. It describes an animation framework as well as a set of base
|
|
XML animation elements suitable for integration with XML documents. It is
|
|
based upon the SMIL 1.0 timing model, with some extensions, and is a true
|
|
subset of SMIL 2.0. This provides an intermediate stepping stone in terms of
|
|
implementation complexity, for applications that wish to have SMIL-compatible
|
|
animation but do not need or want time containers.</p>
|
|
|
|
<h2 id="h004">Status of this document</h2>
|
|
|
|
<p><em>This section describes the status of this document at the time of its
|
|
publication. Other documents may supersede this document. The latest status of
|
|
this document series is maintained at the W3C.</em></p>
|
|
|
|
<p>This document has been reviewed by W3C Members and other interested parties and has been endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited as a normative reference from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web. </p>
|
|
|
|
<p>The SMIL Animation specification has been produced as part of the <a
|
|
href="http://www.w3.org/AudioVideo/">W3C Synchronized Multimedia Activity</a> and was
|
|
written by the <a
|
|
href="http://www.w3.org/AudioVideo/Group/">SYMM Working Group</a> (<em><a
|
|
href="http://cgi.w3.org/MemberAccess/AccessRequest">members only</a></em>) of the W3C Interaction Domain, working with the
|
|
<a href="http://www.w3.org/Graphics/SVG/Group/">SVG Working Group</a> (<em><a
|
|
href="http://cgi.w3.org/MemberAccess/AccessRequest">members only</a></em>) of the W3C Document Formats Domain. The goals of the SYMM Working Group are
|
|
discussed in the <a
|
|
href="http://www.w3.org/AudioVideo/Group/symm-wg-charter">SYMM Working Group
|
|
charter</a> (<em><a
|
|
href="http://cgi.w3.org/MemberAccess/AccessRequest">members only</a></em>), (revised July 2000 from original charter
|
|
version).</p>
|
|
|
|
<p>The <a href="http://www.w3.org/AudioVideo/Group/">SYMM Working Group</a>
|
|
(<em><a
|
|
href="http://cgi.w3.org/MemberAccess/AccessRequest">members only</a></em>) considers that all features in the SMIL 2.0
|
|
specification have been implemented at least twice in an interoperable way.
|
|
The <a href="http://www.w3.org/AudioVideo/Group/symm-wg-charter#Criteria">SYMM
|
|
Working Group Charter</a> (<em><a
|
|
href="http://cgi.w3.org/MemberAccess/AccessRequest">members only</a></em>) defines this as the implementations having been developed
|
|
independently by different organizations and each test in the <a
|
|
href="http://smil.nist.gov/Testcase2.html">SMIL 2.0 test suite</a> has at
|
|
least two passing implementations. The <a
|
|
href="/2001/05/23/SMIL-implementation-result.html">Implementation results</a>
|
|
are publicly released and are intended solely to be used as proof of SMIL 2.0
|
|
implementability. It is only a snap shot of the actual implementation
|
|
behaviors at one moment of time, as these implementations may not be
|
|
immediately available to the public. The interoperability data is not intended
|
|
to be used for assessing or grading the performance of any individual
|
|
implementation.</p>
|
|
|
|
<p>There are patent disclosures and license commitments associated with the
|
|
SMIL 2.0 specification (and thus with the SMIL Animation specification also),
|
|
these may be found on the <a
|
|
href="/2001/05/23/SMIL-IPR-statements.html">SYMM Patent Statement page</a> in
|
|
conformance with <a href="http://www.w3.org/Consortium/Process/#ipr">W3C
|
|
policy</a>.</p>
|
|
|
|
<p>Please report errors in this document to www-smil@w3.org. The list of known errors in this specification is available at <a href="http://www.w3.org/2001/09/REC-smil-animation-20010904-errata">http://www.w3.org/2001/09/REC-smil-animation-20010904-errata</a>.
|
|
</p>
|
|
|
|
|
|
<p>A list of current W3C
|
|
Recommendations and other technical documents can be found at <a
|
|
href="http://www.w3.org/TR"> http://www.w3.org/TR</a>.</p>
|
|
<hr>
|
|
|
|
<h2 id="h005">Quick Table of Contents</h2>
|
|
|
|
<div class="toc">
|
|
1. <a href="#Introduction">Introduction<br>
|
|
</a>2. <a href="#AnimationFramework">Overview and terminology</a><br>
|
|
3. <a href="#AnimationModel">Animation model</a><br>
|
|
4. <a href="#AnimationElements">Animation elements</a><br>
|
|
5. <a href="#IntegratingSMILAnim">Integrating SMIL Animation into a host
|
|
language</a><br>
|
|
6. <a href="#DOMSupport">Document Object Model support</a><br>
|
|
7. <a href="#Appendix-DifferencesFromSMIL1">Appendix: Differences from SMIL
|
|
1.0 timing model</a><br>
|
|
8. <a href="#References">References</a></div>
|
|
|
|
<p></p>
|
|
<hr>
|
|
|
|
<h2 id="h006">Full Table of Contents</h2>
|
|
|
|
<div class="toc">
|
|
1. <a href="#Introduction">Introduction<br>
|
|
</a>
|
|
|
|
<p>2. <a href="#AnimationFramework">Overview and terminology</a><br>
|
|
2.1. <a href="#BasicAnim">Basics of animation</a><br>
|
|
2.2. <a href="#AnimationValues">Animation function values</a><br>
|
|
2.3. <a href="#AnimationSymbols">Symbols used in the semantic
|
|
descriptions<br>
|
|
</a></p>
|
|
|
|
<p>3. <a href="#AnimationModel">Animation model</a><br>
|
|
3.1. <a href="#SpecifyingAnimationTarget">Specifying the animation
|
|
target</a><br>
|
|
3.2. <a href="#SpecifyingAnimationFunction">Specifying the animation
|
|
function f(t)</a><br>
|
|
3.2.1. <a href="#AnimFuncTiming">Animation function timing</a><br>
|
|
3.2.2. <a href="#AnimFuncValues">Animation function values</a><br>
|
|
3.2.3. <a href="#AnimFuncCalcMode">Animation function calculation
|
|
modes</a><br>
|
|
3.3. <a href="#SpecifyingAnimationEffect">Specifying the animation effect
|
|
F(t)</a><br>
|
|
3.3.1. <a href="#RepeatingAnim">Repeating animation</a><br>
|
|
3.3.2. <a href="#EndActive">Controlling the active duration</a><br>
|
|
3.3.3. <a href="#MinMax">The min and max attributes</a><br>
|
|
3.3.4. <a href="#ComputingActiveDur">Computing the active
|
|
duration</a><br>
|
|
3.3.5. <a href="#Fill">Freezing animations</a><br>
|
|
3.3.6. <a href="#AdditiveAnim">Additive animation</a><br>
|
|
3.3.7. <a href="#Restart">Restarting animations</a><br>
|
|
3.4. <a href="#AnimationSyntaxErrors">Handling syntax errors</a><br>
|
|
3.5. <a href="#AnimationSandwichModel">The animation sandwich
|
|
model</a><br>
|
|
3.6. <a href="#TimingModelDetails">Timing model details</a><br>
|
|
3.6.1. <a href="#TimingAndRealWorldClockTime">Timing and real-world clock times</a><br>
|
|
3.6.2. <a href="#IntervalTiming">Interval timing</a><br>
|
|
3.6.3. <a href="#Unifying">Unifying event-based and scheduled timing</a><br>
|
|
3.6.4. <a href="#Timing-EventSensitivity">Event sensitivity</a><br>
|
|
3.6.5. <a href="#HyperlinkSemantics">Hyperlinks and timing</a><br>
|
|
3.6.6. <a href="#PropagatingTimes">Propagating changes to times</a><br>
|
|
3.6.7. <a href="#TimingAttrValGrammars">Timing attribute value grammars</a><br>
|
|
3.6.8. <a href="#Timing-EvaluationOfBeginEndTimeLists">Evaluation of begin and
|
|
end time lists</a><br>
|
|
3.7. <a href="#AnimationFunctionValueDetails">Animation function value
|
|
details</a><br>
|
|
3.8. <a href="#BasicSyntaxDTDDefs">Common syntax DTD definitions</a><br>
|
|
</p>
|
|
|
|
<p>4. <a href="#AnimationElements">Animation elements</a><br>
|
|
4.1. <a href="#animateElement">The animate element</a><br>
|
|
4.2. <a href="#setElement">The set element</a><br>
|
|
4.3. <a href="#animateMotionElement">The animateMotion element</a><br>
|
|
4.4. <a href="#animateColorElement">The animateColor element</a><br>
|
|
</p>
|
|
|
|
<p>5. <a href="#IntegratingSMILAnim">Integrating SMIL Animation into a host
|
|
language</a><br>
|
|
5.1. <a href="#Integrating-RequiredDefs">Required host language
|
|
definitions</a><br>
|
|
5.2. <a href="#Integrating-ConstraintsOnTargets">Required definitions and
|
|
constraints on animation targets</a><br>
|
|
5.3. <a href="#Integrating-ConstraintsOnAttributes"> Constraints on
|
|
manipulating animation elements</a><br>
|
|
5.4. <a href="#Integrating-ConstraintsOnElementTiming">Required
|
|
definitions and constraints on element timing</a><br>
|
|
5.5. <a href="#Integrating-ErrorHandling">Error handling semantics</a><br>
|
|
5.6. <a href="#Integrating-SMILAnimNamespace">SMIL Animation
|
|
namespace</a><br>
|
|
</p>
|
|
|
|
<p>6. <a href="#DOMSupport">Document Object Model support</a><br>
|
|
6.1. <a href="#EventModel">Events and event model</a><br>
|
|
6.2. <a href="#DOM-SupportedMethods">Supported interfaces</a><br>
|
|
6.3. <a href="#DOM-IDL">IDL definition</a><br>
|
|
6.4. <a href="#DOM-Java">Java language binding</a><br>
|
|
6.5. <a href="#DOM-ECMA">ECMAScript language binding</a></p>
|
|
|
|
<p>7. <a href="#Appendix-DifferencesFromSMIL1">Appendix: Differences from SMIL
|
|
1.0 timing model</a></p>
|
|
|
|
<p>8. <a href="#References">References</a></p>
|
|
</div>
|
|
|
|
<p></p>
|
|
<hr>
|
|
<!-- End of TOC -->
|
|
|
|
<h2><a name="Introduction"></a> 1. Introduction</h2>
|
|
|
|
<p>This document describes a framework for incorporating animation onto a time
|
|
line and a mechanism for composing the effects of multiple animations. A set
|
|
of basic animation elements are also described that can be applied to any [<a
|
|
href="#ref-XML10">XML</a>]-based language. A language with which this module
|
|
is integrated is referred to as a <em>host language</em>. A document
|
|
containing animation elements is referred to as a <em>host document</em>.</p>
|
|
|
|
<p>Animation is inherently time-based. SMIL Animation is defined in terms of
|
|
the SMIL timing model. The animation capabilities are described by new
|
|
elements with associated attributes and semantics, as well as the SMIL timing
|
|
attributes. Animation is modeled as a function that changes the <em> presented
|
|
value</em> of a specific attribute over time.</p>
|
|
|
|
<p>The timing model is based upon SMIL 1.0 [<a href="#ref-SMIL">SMIL1.0</a>],
|
|
with some changes and extensions to support additional timing features.
|
|
SMIL Animation uses a simplified "flat" timing model, with no time containers
|
|
(like <code><par></code> or <code><seq></code>). This version of
|
|
SMIL Animation may not be used with documents that otherwise contain timing.
|
|
See also <a href="#Integrating-ConstraintsOnElementTiming">Required
|
|
definitions and constraints on element timing</a>.</p>
|
|
|
|
<p>While this document defines a base set of animation capabilities, it is
|
|
assumed that host languages may build upon the support to define additional or
|
|
more specialized animation elements. In order to ensure a consistent model
|
|
for document authors and runtime implementers, we introduce a framework for
|
|
integrating animation with the SMIL timing model. Animation only manipulates
|
|
attributes and properties of the target elements, and so does not require any
|
|
specific knowledge of the target element semantics.</p>
|
|
|
|
<p>The examples in this document that include syntax for a host language use
|
|
SMIL, SVG, XHTML and CSS. These are provided as an indication of possible
|
|
integrations with various host languages.</p>
|
|
|
|
<h2><a name="AnimationFramework"></a> 2. Overview and terminology</h2>
|
|
|
|
<h3><a name="BasicAnim"></a> 2.1. Basics of animation</h3>
|
|
|
|
<p>Animation is defined as a time-based manipulation of a <em>target
|
|
element</em> (or more specifically of some <em>attribute</em> of the target
|
|
element, the <em>target attribute</em>). The animation defines a mapping of
|
|
time to values for the target attribute. This mapping accounts for all aspects
|
|
of timing, as well as animation-specific semantics. </p>
|
|
|
|
<p>Animations specify a begin, and a <em>simple duration</em> that can be
|
|
repeated. Each animation defines an <em>animation function</em> that produces
|
|
a value for the target attribute, for any time within the simple duration. The
|
|
author can specify how long or how many times an animation function should
|
|
repeat. The simple duration combined with any repeating behavior defines the
|
|
<em>active duration</em>.</p>
|
|
|
|
<p>The target attribute is the name of a feature of a target element as
|
|
defined in a host language document. This may be (e.g.) an XML attribute
|
|
contained in the element or a CSS property that applies to the element. By
|
|
default, the target element of an animation will be the parent of the
|
|
animation element (an animation element is typically a child of the target
|
|
element). However, the target may be any element in the document, identified
|
|
either by an ID reference or via an XLink [<a href="#ref-XLink">XLink</a>]
|
|
locator reference.</p>
|
|
|
|
<p>As a simple example, the following defines an animation of an SVG rectangle
|
|
shape. The rectangle will change from being tall and thin to being short and
|
|
wide.</p>
|
|
<pre><rect ...>
|
|
<animate attributeName="width" from="10px" to="100px"
|
|
begin="0s" dur="10s" />
|
|
<animate attributeName="height" from="100px" to="10px"
|
|
begin="0s" dur="10s" />
|
|
</rect></pre>
|
|
|
|
<p>The rectangle begins with a width of 10 pixels and increases to a width of
|
|
100 pixels over the course of 10 seconds. Over the same ten seconds, the
|
|
height of the rectangle changes from 100 pixels to 10 pixels.</p>
|
|
|
|
<p>When an animation is running, it should not actually change the attribute
|
|
values in the DOM [<a href="#ref-DOM-Level-2">DOM-Level-2</a>]. The animation
|
|
runtime should maintain a <em>presentation value</em> for each animated
|
|
attribute, separate from the DOM or CSS Object Model (OM). If an
|
|
implementation does not support an object model, it should maintain the
|
|
original value as defined by the document as well as the presentation value.
|
|
The presentation value is reflected in the display form of the document.
|
|
Animations thus manipulate the presentation value, and should not affect the
|
|
<em>base value</em> exposed by DOM or CSS OM. This is detailed in <a
|
|
href="#AnimationSandwichModel">The animation sandwich model</a>.</p>
|
|
|
|
<p>The animation function is evaluated as needed over time by the
|
|
implementation, and the resulting values are applied to the presentation value
|
|
for the target attribute. Animation functions are continuous in time and can
|
|
be sampled at whatever frame rate is appropriate for the rendering system. The
|
|
syntactic representation of the animation function is independent of this
|
|
model, and may be described in a variety of ways. The animation elements in
|
|
this specification support syntax for a set of discrete or interpolated
|
|
values, a path syntax for motion based upon SVG paths, keyframe based timing,
|
|
evenly paced interpolation, and variants on these features. Animation
|
|
functions could be defined that were purely or partially algorithmic (e.g., a
|
|
random value function or a motion animation that tracks the mouse position).
|
|
In all cases, the animation exposes this as a function of time.</p>
|
|
|
|
<p>The presentation value reflects the <em>effect</em> of the animation upon
|
|
the base value. The effect is the change to the value of the target attribute
|
|
at any given time. When an animation completes, the effect of the animation is
|
|
no longer applied, and the presentation value reverts to the base value by
|
|
default. The animation effect can also be extended to <em>freeze</em> the last
|
|
value for the remainder of the document duration.</p>
|
|
|
|
<p>Animations can be defined to either override or add to the base value of an
|
|
attribute. In this context, the base value may be the DOM value, or the result
|
|
of other animations that also target the same attribute. This more general
|
|
concept of a base value is termed the <i>underlying value. </i>Animations that
|
|
add to the underlying value are described as <em>additive</em> animations.
|
|
Animations that override the underlying value are referred to as
|
|
<em>non-additive</em> animations.</p>
|
|
|
|
<h3><a name="AnimationValues"></a> 2.2. Animation function values</h3>
|
|
|
|
<p>Many animations specify the animation function
|
|
<code><strong>f(t)</strong></code> as a sequence of values to be applied over
|
|
time. For some types of attributes (e.g. numbers), it is also possible to
|
|
describe an interpolation function between values.</p>
|
|
|
|
<p>As a simple form of describing the values, animation elements can specify a
|
|
<em>from</em> value and a <em>to</em> value. If the attribute takes values
|
|
that support interpolation (e.g. a number), the animation function can
|
|
interpolate values in the range defined by <em>from</em> and <em>to</em>,
|
|
over the course of the simple duration. A variant on this uses a <em>by</em>
|
|
value in place of the <em>to</em> value, to indicate an additive change to the
|
|
attribute.</p>
|
|
|
|
<p>More complex forms specify a list of values, or even a path description for
|
|
motion. Authors can also control the timing of the values, to describe
|
|
"keyframe" animations, and even more complex functions.</p>
|
|
|
|
<h3><a name="AnimationSymbols"></a> 2.3. Symbols used in the semantic
|
|
descriptions</h3>
|
|
<dl>
|
|
<dt><code><strong>f(t)</strong></code></dt>
|
|
<dd>The simple animation function that maps times within the simple
|
|
duration to values for the target attribute (0 <= t <= simple
|
|
duration). Note that while <code><strong>F(t)</strong></code> defines
|
|
the mapping for the entire animation, <code><strong>f(t)</strong></code>
|
|
has a simplified model that just handles the simple duration.</dd>
|
|
<dt><code><strong>F(t)</strong></code></dt>
|
|
<dd>The effect of an animation for any point in the animation. This maps
|
|
any non-negative time to a value for the target attribute. A time value
|
|
of 0 corresponds to the time at which the animation begins. Note that
|
|
<code><strong>F(t)</strong></code> combines the animation function
|
|
<code><strong>f(t)</strong></code> with all the other aspects of
|
|
animation and timing controls.</dd>
|
|
</dl>
|
|
|
|
<h2><a name="AnimationModel"></a> 3. Animation model</h2>
|
|
|
|
<p>This section describes the attribute syntax and semantics for describing
|
|
animations. The specific elements are not described here, but rather the
|
|
common concepts and syntax that comprise the model for animation. Document
|
|
issues are described, as well as the means to target an element for animation.
|
|
The animation model is then defined by building up from the simplest to the
|
|
most complex concepts: first the simple duration and animation function
|
|
<code><strong>f(t)</strong></code>, and then the overall behavior
|
|
<code><strong>F(t)</strong></code>. Finally, the model for combining
|
|
animations is presented, and additional details of animation timing are
|
|
described.</p>
|
|
|
|
<p>The time model depends upon several definitions for the host document: A
|
|
host document is presented over a certain time interval. The start of the
|
|
interval in which the document is presented is referred to as the <em>document
|
|
begin</em>. The end of the interval in which the document is presented is
|
|
referred to as the <em>document end</em>. The difference between the end and
|
|
the begin is referred to as the <em>document duration</em>. The formal
|
|
definitions of presentation and document begin and end are left to the host
|
|
language designer (see also <a href="#Integrating-RequiredDefs">Required host
|
|
language definitions</a>).</p>
|
|
|
|
<h3><a name="SpecifyingAnimationTarget"></a> 3.1. Specifying the animation
|
|
target</h3>
|
|
|
|
<p>The animation target is defined as a specific attribute of a particular
|
|
element. The means of specifying the target attribute and the target element
|
|
are detailed in this section.</p>
|
|
|
|
<h4><a name="SpecifyingTargetAttribute"></a>The target attribute</h4>
|
|
|
|
<p>The target attribute to be animated is specified with
|
|
<code>attributeName</code>. The value of this attribute is a string that
|
|
specifies the name of the target attribute, as defined in the host
|
|
language.</p>
|
|
|
|
<p>The attributes of an element that can be animated are often defined by
|
|
different languages, and/or in different namespaces. For example, in many XML
|
|
applications, the position of an element (which is a typical target attribute)
|
|
is defined as a CSS property rather than as XML attributes. In some cases, the
|
|
same attribute name is associated with attributes or properties in more than
|
|
one language, or namespace. To allow the author to disambiguate the name
|
|
mapping, an additional attribute <code>attributeType</code> is provided that
|
|
specifies the intended interpretation.</p>
|
|
|
|
<p>The <code>attributeType</code> attribute is optional. By default, the
|
|
animation runtime will resolve the names according to the following rule: If
|
|
there is a name conflict and <code>attributeType</code> is not specified, the
|
|
list of CSS properties supported by the host language is matched first (if CSS
|
|
is supported in the host language); if no CSS match is made (or CSS does not
|
|
apply) the default namespace for the target element will be matched.</p>
|
|
|
|
<p>If a target attribute is defined in an XML Namespace other than the default
|
|
namespace for the target element, the author must specify the namespace of the
|
|
target attribute using the associated namespace prefix as defined in the scope
|
|
of the animation element. The prefix is prepended to the value for
|
|
<code>attributeName</code>.</p>
|
|
|
|
<p>For more information on XML namespaces, see [<a
|
|
href="#ref-XML-NS">XML-NS</a>].</p>
|
|
<dl>
|
|
<dt><a name="AttributeAttribute"></a>attributeName<span class="argvalue"> =
|
|
<strong><attributeName></strong></span></dt>
|
|
<dd>Specifies the name of the target attribute. An XMLNS prefix may be
|
|
used to indicate the XML namespace for the attribute. The prefix will be
|
|
interpreted in the scope of the animation element.</dd>
|
|
<dt> </dt>
|
|
<dt><a name="AttributeTypeAttribute"></a>attributeType<span
|
|
class="argvalue"> = "<strong>CSS | XML | auto</strong>"</span></dt>
|
|
<dd>Specifies the namespace in which the target attribute and its
|
|
associated values are defined. The attribute value is one of the
|
|
following (values are case-sensitive):
|
|
<dl>
|
|
<dt>"CSS"</dt>
|
|
<dd>This specifies that the value of "attributeName" is the name of
|
|
a CSS property, as defined for the host document. This argument
|
|
value is only meaningful in host language environments that
|
|
support CSS.</dd>
|
|
<dt>"XML"</dt>
|
|
<dd>This specifies that the value of "attributeName" is the name of
|
|
an XML attribute defined in the default XML namespace for the
|
|
target element. Note that if the value for <code>attributeName</code> has an
|
|
XMLNS prefix, the implementation must use the associated namespace
|
|
as defined in the scope of the animation element.</dd>
|
|
<dt>"auto"</dt>
|
|
<dd>The implementation should match the attributeName to an
|
|
attribute for the target element. The implementation must first
|
|
search through the the list of CSS properties for a matching
|
|
property name, and if none is found, search the default XML
|
|
namespace for the element.<br>
|
|
This is the default.</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h4><a name="SpecifyingTargetElement"></a> The target element</h4>
|
|
|
|
<p>An animation element can define the target element of the animation either
|
|
explicitly or implicitly. An explicit definition uses an attribute to specify
|
|
the target element. The syntax for this is described below.</p>
|
|
|
|
<p>If no explicit target is specified, the implicit target element is the
|
|
parent element of the animation element in the document tree. It is expected
|
|
that the common case will be that an animation element is declared as a child
|
|
of the element to be animated. In this case, no explicit target need be
|
|
specified.</p>
|
|
|
|
<p>If an explicit target element reference cannot be resolved (e.g. if no such
|
|
element can be found), the animation has no effect. In addition, if the target
|
|
element (either implicit or explicit) does not support the specified target
|
|
attribute, the animation has no effect. See also <a
|
|
href="#AnimationSyntaxErrors">Handling syntax errors</a>.</p>
|
|
|
|
<p>The following two attributes can be used to identify the target element
|
|
explicitly:</p>
|
|
<dl>
|
|
<dt><a name="TargetAttribute"></a><code>targetElement</code><span
|
|
class="argvalue"> = "<strong><IDREF></strong>"</span></dt>
|
|
<dd>This attribute specifies the target element to be animated. The
|
|
attribute value must be the value of an XML identifier attribute of an
|
|
element within the host document. For a formal definition of "IDREF",
|
|
refer to XML 1.0 [<a href="#ref-XML10">XML</a>]. </dd>
|
|
<dt><a name="HrefAttribute"></a><code>href</code><span class="argvalue"> =
|
|
<em>uri-reference</em></span></dt>
|
|
<dd>This attribute specifies an XLink locator, referring to the target
|
|
element to be animated.</dd>
|
|
</dl>
|
|
|
|
<p>When integrating animation elements into the host language, the language
|
|
designer should avoid including both of these attributes. If however, the host
|
|
language designer chooses to include both attributes in the host language,
|
|
then when both are specified for a given animation element the XLink
|
|
<code>href</code> attribute takes precedence over the
|
|
<code>targetElement</code> attribute.</p>
|
|
|
|
<p>The advantage of using the <code>targetElement</code> attribute is the
|
|
simpler syntax of the attribute value compared to the <code>href</code>
|
|
attribute. The advantage of using the XLink <code>href</code> attribute is
|
|
that it is extensible to a full linking mechanism in future versions of SMIL
|
|
Animation, and the animation element can be processed by generic XLink
|
|
processors. The XLink form is also provided for host languages that are
|
|
designed to use XLink for all such references. The following two examples
|
|
illustrate the two approaches.</p>
|
|
|
|
<p>This example uses the simpler <code>targetElement</code> syntax:</p>
|
|
<pre><animate targetElement="foo" attributeName="bar" .../></pre>
|
|
|
|
<p>This example uses the more flexible XLink locator syntax, with the
|
|
equivalent target.</p>
|
|
<pre><foo xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
...
|
|
<animate xlink:href="#foo" attributeName="bar" .../>
|
|
...
|
|
</foo></pre>
|
|
|
|
<p>When using an XLink <code>href</code> attribute on an animation element,
|
|
the following additional XLink attributes need to be defined in the host
|
|
language. These may be defined in a DTD, or the host language may require
|
|
these in the document syntax to support generic XLink processors. For more
|
|
information, refer to the "XML Linking Language (XLink)" [<a
|
|
href="#ref-XLink">XLink</a>].</p>
|
|
|
|
<p>The following XLink attributes are required by the XLink specification. The
|
|
values are fixed, and so may be specified as such in a DTD. All other XLink
|
|
attributes are optional, and do not affect SMIL Animation semantics.</p>
|
|
<dl>
|
|
<dt><a name="XLinkTypeAttribute"></a><code>type</code> <span
|
|
class="argvalue">= 'simple'</span></dt>
|
|
<dd>Identifies the type of XLink being used. To link to the target
|
|
element, a simple link is used, and thus the attribute value must be
|
|
"simple". </dd>
|
|
<dt><a name="XLinkActuateAttribute"></a><code>actuate</code> <span
|
|
class="argvalue">= 'onLoad'</span></dt>
|
|
<dd>Indicates that the link to the target element is followed
|
|
automatically (i.e., without user action).</dd>
|
|
<dt><a name="XLinkShowAttribute"></a><code>show</code> <span
|
|
class="argvalue">= 'embed'</span></dt>
|
|
<dd>Indicates that the reference does not include additional content in
|
|
the file. </dd>
|
|
</dl>
|
|
|
|
<p>Additional details on the target element specification as relates to the
|
|
host document and language are described in <a
|
|
href="#Integrating-ConstraintsOnTargets">Required definitions and constraints
|
|
on animation targets</a>.</p>
|
|
|
|
<h3><a name="SpecifyingAnimationFunction"></a> 3.2. Specifying the animation
|
|
function f(t)</h3>
|
|
|
|
<p>Every animation function defines the value of the attribute at a particular
|
|
moment in time. The time range for which the animation function is defined is
|
|
the simple duration. The animation function does not produce defined results
|
|
for times outside the range of 0 to the simple duration.</p>
|
|
|
|
<h4><a name="AnimFuncTiming"></a> 3.2.1. Animation function timing</h4>
|
|
|
|
<p>The basic timing for an element is described using the <code>begin</code>
|
|
and <code>dur</code> attributes. Authors can specify the begin time of an
|
|
animation in a variety of ways, ranging from simple clock times to the time
|
|
that an event like a mouse-click happens. The length of the simple duration is
|
|
specified using the <code>dur</code> attribute. The attribute syntax is
|
|
described below. The normative syntax rules for each attribute value variant
|
|
are described in <a href="#TimingAttrValGrammars"> Timing attribute value
|
|
grammars</a>. A syntax summary is provided
|
|
here as an aid to the reader.</p>
|
|
|
|
<p><em>This section is normative</em></p>
|
|
<div class="adef-list">
|
|
<dl>
|
|
<dt><a name="BeginAttribute"><span class="adef">begin</span></a>
|
|
<dd>Defines when the element becomes active. <br>
|
|
The attribute value is a semi-colon separated list of values.
|
|
<dl>
|
|
<dt><a href="#Timing-BeginValueListSyntax">begin-value-list</a> :
|
|
begin-value (";" begin-value-list )?</dt>
|
|
<dd>A semi-colon separated list of begin values. The interpretation of a
|
|
list of begin times is detailed in the section <a href="#Timing-EvaluationOfBeginEndTimeLists">Evaluation
|
|
of begin and end time lists</a>.<br>
|
|
<dt>begin-value : ( offset-value | syncbase-value |
|
|
event-value | repeat-value | accessKey-value | media-marker-value |
|
|
wallclock-sync-value | "indefinite" )
|
|
<dd>Describes the element begin.
|
|
<dt><a href="#Timing-OffsetValueSyntax">offset-value</a> : ( "+" |
|
|
"-" )? <a href="#Timing-ClockValueSyntax">Clock-value</a>
|
|
<dd>Specifies the presentation time at which the animation begins.
|
|
The begin is defined relative to the document begin.</dd>
|
|
<dt><a href="#Timing-SyncbaseValueSyntax">syncbase-value</a> : ( Id-value
|
|
"." ( "begin" | "end" ) ) ( (
|
|
"+" | "-" ) Clock-value )?</dt>
|
|
<dd>Describes a syncbase and an offset from that syncbase. The element
|
|
begin is defined relative to the begin or active end of another
|
|
element.</dd>
|
|
<dt><a href="#Timing-EventValueSyntax">event-value</a> : ( Id-value
|
|
"." )? ( event-ref ) ( ( "+" | "-"
|
|
) Clock-value )?</dt>
|
|
<dd>Describes an event and an optional offset that determine the
|
|
element begin. The animation begin is defined relative to the time
|
|
that the event is raised. Events may be any event defined for the
|
|
host language in accordance with [<a href="#ref-DOM2Events">DOM2Events</a>].
|
|
These may include
|
|
user-interface events, event-triggers transmitted via a network,
|
|
etc. Details of event-based timing are described in the section
|
|
below on <a href="#Unifying">Unifying event-based and scheduled
|
|
timing</a>.</dd>
|
|
<dt><a href="#Timing-RepeatValueSyntax">repeat-value</a> : ( Id-value
|
|
"." )? "repeat(" integer ")" ( (
|
|
"+" | "-" ) Clock-value )?</dt>
|
|
<dd>Describes a qualified repeat event. The element begin is defined
|
|
relative to the time that the repeat event is raised with the
|
|
specified iteration value.
|
|
<dt><a href="#Timing-AccessKeyValueSyntax">accessKey-value</a> : "accessKey("
|
|
character ")"</dt>
|
|
<dd>Describes an accessKey that determines the element begin. The
|
|
element begin is defined relative to the time that the accessKey
|
|
character is input by the user.
|
|
<dt><a href="#Timing-WallclockSyncValueSyntax">wallclock-sync-value</a>
|
|
: "wallclock(" wallclock-value ")"</dt>
|
|
<dd>Describes the element begin as a real-world clock time. The
|
|
wallclock time syntax is based upon syntax defined in [<a href="#ref-iso8601">ISO8601</a>].
|
|
<dt>"indefinite"</dt>
|
|
<dd>The begin of the animation will be determined by a
|
|
"beginElement()" method call or a hyperlink targeted to the
|
|
animation element.<br>
|
|
The SMIL Animation DOM methods are described in the <a
|
|
href="#DOM-SupportedMethods">Supported methods</a> section.<br>
|
|
Hyperlink-based timing is described in the <a
|
|
href="#HyperlinkSemantics">Hyperlinks and timing</a> section.</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<h5><a name="Timing-BeginValueSemantics"></a>Begin value semantics</h5>
|
|
<p><em>This section is normative</em></p>
|
|
<ul>
|
|
<li>If no <span class="ainst-begin ainst">begin</span> is specified, the
|
|
default timing is equivalent to an offset value of "0".
|
|
<li>If there is a syntax error in any individual value in the list of begin or
|
|
end values (i.e., the value does not conform to the defined syntax for any of
|
|
the time values), the host language must specify how the user agent deals
|
|
with this.</li>
|
|
<li>A time value may conform to the defined syntax but still be invalid (e.g.
|
|
if an unknown element is referenced by ID in a syncbase value). If there is
|
|
such an evaluation error in an individual value in the list of begin or end
|
|
values, the individual value will be will be treated as though
|
|
"indefinite" were specified, and the rest of the list will not be
|
|
processed normally. If no legal value is specified for a begin or end
|
|
attribute, the element assumes an "indefinite" begin or end time
|
|
(respectively).</li>
|
|
</ul>
|
|
<p class="descdef"><em>This section is informative</em></p>
|
|
<p>The <span class="ainst-begin ainst">begin</span> value can specify a list of
|
|
times. This can be used to specify multiple "ways" or
|
|
"rules" to begin an element, e.g. if any one of several events is
|
|
raised. A list of times can also define multiple begin times, allowing the
|
|
element to play more than once (this behavior can be controlled, e.g. to only
|
|
allow the earliest begin to actually be used - see also <a href="#Restart">Restarting
|
|
animations</a>). </p>
|
|
<p>In general, the earliest time in the list determines the begin time of the
|
|
element. There are additional constraints upon the evaluation of the begin time
|
|
list, detailed in <a href="#Timing-EvaluationOfBeginEndTimeLists">Evaluation of
|
|
begin and end time lists</a>.</p>
|
|
<p>Note that while it is legal to include "indefinite" in a list of
|
|
values for <span class="ainst-begin ainst">begin</span>, "indefinite"
|
|
is only really useful as a single value. Combining it with other values does not
|
|
impact begin timing, as DOM begin methods can be called with or without specifying
|
|
"indefinite" for <span class="ainst-begin ainst">begin</span>.</p>
|
|
<h5><a name="Timing-NegativeBegins"></a>Handling negative offsets for begin</h5>
|
|
<p class="descdef"><em>This section is informative</em></p>
|
|
<p>The use of negative offsets to define begin times merely defines the
|
|
synchronization relationship of the element. It does not in any way override the
|
|
time container constraints upon the element, and it cannot override the
|
|
constraints of presentation time. </p>
|
|
<p><em>This section is normative</em></p>
|
|
<ul>
|
|
<li>The computed offset relative to the document begin time may
|
|
be negative.
|
|
<li>A begin time may be specified with a negative offset relative to an event
|
|
or to a syncbase that is not initially resolved. When the syncbase or
|
|
eventbase time is resolved, the computed time may be in the past.</li>
|
|
</ul>
|
|
<p><span class="normative">The computed begin time defines the <em>scheduled
|
|
synchronization relationship</em> of the element, even if it is not possible to
|
|
begin the element at the computed time. The time model uses the computed begin
|
|
time, and not the observed time of the element begin. </span></p>
|
|
<p><em>This section is normative</em></p>
|
|
<ul>
|
|
<li><span class="normative">When a begin time is resolved to be in the past
|
|
(i.e., before the current presentation time), the element begins
|
|
immediately, but acts as though it had begun at the specified time (playing
|
|
from an offset into the media).</span></li>
|
|
</ul>
|
|
<p><span class="normative">The element will actually begin at the time computed
|
|
according to the following algorithm:</span></p>
|
|
<pre><span class="normative">Let <strong>o</strong> be the offset value of a given begin value,</span>
|
|
<span class="normative"><strong>d</strong> be the associated simple duration, </span>
|
|
<span class="normative"><strong>AD</strong> be the associated active duration.</span>
|
|
<span class="normative">Let <strong>rAt</strong> be the time when the begin time becomes resolved.</span>
|
|
<span class="normative">Let <strong>rTo</strong> be the resolved sync-base or event-base time without the offset</span>
|
|
<span class="normative">Let <strong>rD</strong> be <strong>rTo - rAt</strong>. If <strong>rD < 0</strong> then <strong>rD</strong> is set to <strong>0</strong>.</span>
|
|
<span class="normative"> </span>
|
|
<span class="normative">If <strong>AD</strong> is indefinite, it compares greater than any value of <strong>o</strong> or <strong>ABS(o)</strong>.</span>
|
|
<span class="normative"><strong>REM( x, y )</strong> is defined as <strong>x - (y * floor( x/y ))</strong>. </span>
|
|
<span class="normative">If y is indefinite, <strong>REM( x, y )</strong> is just <strong>x.</strong></span>
|
|
|
|
Let <strong>mb = REM( ABS(o), d ) - rD</strong></pre>
|
|
<pre><span class="normative">If <strong>ABS(o) >= AD </strong>then the element does not begin.</span>
|
|
<span class="normative">Else if <strong>mb >= 0</strong> then the media begins at <strong>mb</strong>.</span>
|
|
<span class="normative">Else the media begins at <strong>mb + d</strong>.</span></pre>
|
|
<p><span class="normative">If the element repeats, the iteration value of the <code>repeat</code>
|
|
event has the calculated value based upon the above computed begin time, and not
|
|
the observed number of repeats.</span></p>
|
|
<p class="descdef"><span class="informative"><em>This section is informative</em></span></p>
|
|
<p><span class="informative">Thus for example:</span></p>
|
|
<pre><span class="informative"><animate begin="foo.click-8s" dur="3s" repeatCount="10" .../></span></pre>
|
|
<p><span class="informative">The animation begins when the user clicks on the
|
|
element "foo". Its calculated begin time is actually 8 seconds
|
|
earlier, and so it begins to play at 2 seconds into the 3 second simple
|
|
duration, on the third repeat iteration. One second later, the fourth iteration
|
|
of the element will begin, and the associated <code>repeat</code> event will
|
|
have the iteration value set to 3 (since it is zero based). The element will end
|
|
22 seconds after the click. The <code>beginEvent</code> event is raised when
|
|
the element begins, but has a time stamp value that corresponds to the defined
|
|
begin time, 8 seconds earlier. Any time dependents are activated relative to the
|
|
computed begin time, and not the observed begin time. </span></p>
|
|
<p><span class="informative">Note: If script authors wish to distinguish between
|
|
the computed repeat iterations and observed repeat iterations, they can count
|
|
actual <code>repeat</code> events in the associated event handler.</span></p>
|
|
<div class="adef-list">
|
|
<dl>
|
|
<dt><a name="DurAttribute"><span class="adef">dur</span></a></dt>
|
|
<dd>Specifies the simple duration.<br>
|
|
The attribute value can be one of the following types of values:
|
|
<dl>
|
|
<dt> <a href="#Timing-ClockValueSyntax">Clock-value</a>
|
|
</dt>
|
|
<dd>Specifies the length of the simple duration in presentation
|
|
time.<br>
|
|
Value must be greater than 0.</dd>
|
|
<dt>"indefinite"</dt>
|
|
<dd>Specifies the simple duration as indefinite.</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
|
|
<p>If no <code>begin</code> is specified, the default value is "0" - the
|
|
animation begins when the document begins. If there is any error in the
|
|
argument value syntax for <code>begin</code>, the default value for
|
|
<code>begin</code> will be used.</p>
|
|
|
|
<p>If the animation does not have a <code>dur</code> attribute, the simple
|
|
duration is indefinite. Note that interpolation will not work if the simple
|
|
duration is indefinite (although this may still be useful for <code><a
|
|
href="#setElement"><set></a></code> elements). See also <a
|
|
href="#InterpolationAndIndefSimpleDur">Interpolation and indefinite simple
|
|
durations</a>.</p>
|
|
|
|
<p>If there is any error in the argument value syntax for <code>dur</code>,
|
|
the attribute will be ignored (as though it were not specified), and so the
|
|
simple duration will be indefinite.</p>
|
|
|
|
<p>If the begin is specified to be "indefinite" or specifies an event-base,
|
|
the time of the begin is not actually known until the element is activated
|
|
(e.g., with a hyperlink, DOM method call or the referenced event). The time is
|
|
referred to as <em>unresolved</em> when it is not known. At the point at which
|
|
the element begin is activated, the time becomes <em>resolved</em>. This is
|
|
described in detail in <a href="#Unifying">Unifying event-based and scheduled
|
|
timing</a>.</p>
|
|
|
|
<h6><a name="Timing-WallclockExamples"></a>Examples</h6>
|
|
<p><span class="informative">The following examples all specify a begin at
|
|
midnight on January 1st 2000, UTC</span></p>
|
|
<pre><span class="informative">begin="wallclock(2000-01-01Z)"</span>
|
|
<span class="informative">begin="wallclock( 2000-01-01T00:00Z )"</span>
|
|
<span class="informative">begin="wallclock( 2000-01-01T00:00:00Z )"</span>
|
|
<span class="informative">begin="wallclock( 2000-01-01T00:00:00.0Z )"</span>
|
|
<span class="informative">begin="wallclock( 2000-01-01T00:00:00.0Z )"</span>
|
|
<span class="informative">begin="wallclock( 2000-01-01T00:00:00.0-00:00 )"</span></pre>
|
|
<p><span class="informative">The following example specifies a begin at 3:30 in
|
|
the afternoon on July 28th 1990, in the Pacific US time zone:</span></p>
|
|
<pre><span class="informative">begin="wallclock( 1990-07-28T15:30-08:00 )"</span></pre>
|
|
<p><span class="informative">The following example specifies a begin at 8 in the
|
|
morning wherever the document is presented:</span></p>
|
|
<pre><span class="informative">begin="wallclock( 08:00 )"</span></pre>
|
|
|
|
<h4><a name="AnimFuncValues"></a> 3.2.2. Animation function values</h4>
|
|
|
|
<p>In addition to the target attribute and the timing, an animation must
|
|
specify how to change the value over time. An animation can be described
|
|
either as a list of <em>values</em>, or in a simplified form using
|
|
<em>from</em>, <em>to</em> and <em>by</em> values.</p>
|
|
<dl>
|
|
<dt><a name="FromAttribute"></a>from <span class="argvalue">=
|
|
"<strong><value></strong>"</span></dt>
|
|
<dd>Specifies the starting value of the animation.</dd>
|
|
<dt><a name="ToAttribute"></a>to <span class="argvalue">=
|
|
"<strong><value></strong>"</span></dt>
|
|
<dd>Specifies the ending value of the animation.</dd>
|
|
<dt><a name="ByAttribute"></a>by <span class="argvalue">=
|
|
"<strong><value></strong>"</span></dt>
|
|
<dd>Specifies a relative offset value for the animation.</dd>
|
|
<dt><a name="ValuesAttribute"></a>values <span class="argvalue">=
|
|
"<strong><list></strong>"</span></dt>
|
|
<dd>A semicolon-separated list of one or more values. Vector-valued
|
|
attributes are supported using the vector syntax of the
|
|
<code>attributeType</code> domain.</dd>
|
|
</dl>
|
|
|
|
<p>If a list of values is used, the animation will apply the values in order
|
|
over the course of the animation (pacing and interpolation between these
|
|
values is described in the <a href="#AnimFuncCalcMode">next section</a>). If a
|
|
list of <em>values </em>is specified, any <em>from</em>, <em>to</em> and
|
|
<em>by</em> attribute values are ignored.</p>
|
|
|
|
<p>The simpler <em>from/to/by</em> syntax provides for several variants. To
|
|
use one of these variants, one of <code>by</code> or <code>to</code> must be
|
|
specified; a <code>from</code> value is optional. It is not legal to specify
|
|
both <code>by</code> and <code>to</code> attributes - if both are specified,
|
|
only the <code>to</code> attribute will be used (the <code>by</code> will be
|
|
ignored). The combinations of attributes yield the following classes of
|
|
animation:</p>
|
|
<dl>
|
|
<dt><em>from-to</em> animation</dt>
|
|
<dd>Specifying a <code>from</code> value and a <code>to</code> value
|
|
defines a simple animation, equivalent to a <code>values</code> list
|
|
with 2 values. The animation function is defined to start with the
|
|
<code>from</code> value, and to finish with the <code>to</code>
|
|
value.</dd>
|
|
<dt><em>from-by</em> animation</dt>
|
|
<dd>Specifying a <code>from</code> value and a <code>by</code> value
|
|
defines a simple animation in which the animation function is defined to
|
|
start with the <code>from</code> value, and to change this over the
|
|
course of the simple duration by a <em>delta</em> specified with the
|
|
<code>by</code> attribute. This may only be used with attributes that
|
|
support addition (e.g. most numeric attributes).</dd>
|
|
<dt><em>by</em> animation</dt>
|
|
<dd>Specifying only a by value defines a simple animation in which the
|
|
animation function is defined to offset the underlying value for the
|
|
attribute, using a delta that varies over the course of the simple
|
|
duration, starting from a delta of 0 and ending with the delta specified
|
|
with the <code>by</code> attribute. This may only be used with
|
|
attributes that support addition.</dd>
|
|
<dt><em>to</em> animation</dt>
|
|
<dd>This describes an animation in which the animation function is defined
|
|
to start with the underlying value for the attribute, and finish with
|
|
the value specified with the <code>to</code> attribute. Using this form,
|
|
an author can describe an animation that will start with any current
|
|
value for the attribute, and will end up at the desired <code>to</code>
|
|
value.</dd>
|
|
</dl>
|
|
|
|
<p>The last two forms "<em>by animation</em>" and "<em>to animation</em>" have
|
|
additional semantic constraints when combined with other animations. The
|
|
details of this are described below in the section <a
|
|
href="#FromToByAndAdditive">How from, to and by attributes affect additive
|
|
behavior</a>.</p>
|
|
|
|
<p>The animation values specified in the animation element must be legal
|
|
values for the specified attribute. See also <a
|
|
href="#AnimationFunctionValueDetails">Animation function value
|
|
details</a>. </p>
|
|
|
|
<p>Leading and trailing white space, and white space before and after
|
|
semicolon separators, will be ignored.</p>
|
|
|
|
<p>If any values (i.e., the argument-values for <code>from</code>,
|
|
<code>to</code>, <code>by</code> or <code>values</code> attributes) are not
|
|
legal, the animation will have no effect (see also <a
|
|
href="#AnimationSyntaxErrors">Handling Syntax Errors</a>). Similarly, if none
|
|
of the <code>from</code>, <code>to</code>, <code>by</code> or
|
|
<code>values</code> attributes are specified, the animation will have no
|
|
effect.</p>
|
|
|
|
<h5><a name="InterpolationAndIndefSimpleDur"></a>Interpolation and indefinite
|
|
simple durations</h5>
|
|
|
|
<p>If the simple duration of an animation is indefinite (e.g., if no
|
|
<code>dur</code> value is specified), interpolation is not generally
|
|
meaningful. While it is possible to define an animation function that is not
|
|
based upon a defined simple duration (e.g., some random number algorithm), most
|
|
animations define the function in terms of the simple duration. If an
|
|
animation function is defined in terms of the simple duration and the simple
|
|
duration is indefinite, the first value of the animation function (i.e.,
|
|
<code><strong>f(0)</strong></code>) should be used (effectively as a constant)
|
|
for the animation function.</p>
|
|
|
|
<p><strong>Examples</strong></p>
|
|
|
|
<p>The following example using the <code>values</code> syntax animates the
|
|
width of an SVG shape over the course of 10 seconds, interpolating from a
|
|
width of 40 to a width of 100 and back to 40.</p>
|
|
<pre><rect ...>
|
|
<animate attributeName="width" values="40;100;40" dur="10s"/>
|
|
</rect></pre>
|
|
|
|
<p>The following "<em>from-to animation</em>" example animates the width of an
|
|
SVG shape over the course of 10 seconds from a width of 50 to a width of
|
|
100.</p>
|
|
<pre><rect ...>
|
|
<animate attributeName="width" from="50" to="100" dur="10s"/>
|
|
</rect></pre>
|
|
|
|
<p>The following "<em>from-by animation</em>" example animates the width of an
|
|
SVG shape over the course of 10 seconds from a width of 50 to a width of
|
|
75.</p>
|
|
<pre><rect ...>
|
|
<animate attributeName="width" from="50" by="25" dur="10s"/>
|
|
</rect></pre>
|
|
|
|
<p>The following "<em>by animation</em>" example animates the width of an SVG
|
|
shape over the course of 10 seconds from the original width of 40 to a width
|
|
of 70.</p>
|
|
<pre><rect width="40"...>
|
|
<animate attributeName="width" by="30" dur="10s"/>
|
|
</rect></pre>
|
|
|
|
<p>The following "<em>to animation</em>" example animates the width of an SVG
|
|
shape over the course of 10 seconds from the original width of 40 to a width
|
|
of 100.</p>
|
|
<pre><rect width="40"...>
|
|
<animate attributeName="width" to="100" dur="10s"/>
|
|
</rect></pre>
|
|
|
|
<h4><a name="AnimFuncCalcMode"></a> 3.2.3. Animation function calculation
|
|
modes</h4>
|
|
|
|
<p>By default, a simple linear interpolation is performed over the values,
|
|
evenly spaced over the duration of the animation. Additional attributes can
|
|
be used for finer control over the interpolation and timing of the values. The
|
|
<code>calcMode</code> attribute defines the method of applying values to the
|
|
attribute. The <code>keyTimes</code> attribute provides additional control
|
|
over the timing of the animation function, associating a time with each value
|
|
in the <code>values</code> list (or the points in a <code>path</code>
|
|
description for <code>animateMotion</code> - see <a
|
|
href="#animateMotionElement">The animateMotion element</a>). Finally, the
|
|
<code>keySplines</code> attribute provides a means of controlling the pacing
|
|
of interpolation <em>between</em> the values in the <code>values</code>
|
|
list.</p>
|
|
<dl>
|
|
<dt><code><a name="CalcModeAttribute"></a>calcMode</code> <span
|
|
class="argvalue">= "<strong>discrete | linear | paced |
|
|
spline</strong>"</span></dt>
|
|
<dd>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), the
|
|
<code>calcMode</code> attribute is ignored and discrete interpolation is
|
|
used.
|
|
<dl>
|
|
<dt>discrete</dt>
|
|
<dd>This specifies that the animation function will jump from one
|
|
value to the next without any interpolation.</dd>
|
|
<dt>linear</dt>
|
|
<dd>Simple linear interpolation between values is used to calculate
|
|
the animation function. <br>
|
|
This is the default <code>calcMode</code>.</dd>
|
|
<dt>paced</dt>
|
|
<dd>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 "<code>paced</code>" is specified, any
|
|
<code>keyTimes</code> or <code>keySplines</code> will be
|
|
ignored.</dd>
|
|
<dt><a name="ix_SplineSyntax"></a>spline</dt>
|
|
<dd>Interpolates from one value in the <code>values</code> list to
|
|
the next according to a time function defined by a cubic Bezier
|
|
spline. The points of the spline are defined in the
|
|
<code>keyTimes</code> attribute, and the control points for each
|
|
interval are defined in the <code>keySplines</code>
|
|
attribute.</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><code><a name="KeyTimesAttribute"></a>keyTimes</code> <span
|
|
class="argvalue">= "<strong><list></strong>"</span></dt>
|
|
<dd>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 the
|
|
<code>values</code> attribute list, and defines when the value should be
|
|
used in the animation function. Each time value in the
|
|
<code>keyTimes</code> list is specified as a floating point value
|
|
between 0 and 1 (inclusive), representing a proportional offset into the
|
|
simple duration of the <span class="element-name">animation</span>
|
|
element.
|
|
<p>If a list of <code>keyTimes</code> is specified, there must be
|
|
exactly as many values in the <code>keyTimes</code> list as in the
|
|
<code>values</code> list.</p>
|
|
<p>Each successive time value must be greater than or equal to the
|
|
preceding time value.</p>
|
|
<p>The <code>keyTimes</code> list semantics depends upon the
|
|
interpolation mode:</p>
|
|
<ul>
|
|
<li>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. The <code>
|
|
keyTime</code> associated with each value defines when the value is
|
|
set; values are interpolated between the <code>
|
|
keyTimes</code>.</li>
|
|
<li>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 in <code>keyTimes</code>.</li>
|
|
</ul>
|
|
<p>If the interpolation mode is "paced", the <code>keyTimes</code>
|
|
attribute is ignored.</p>
|
|
<p>If there are any errors in the <code>keyTimes</code> specification
|
|
(bad values, too many or too few values), the animation will have no
|
|
effect.</p>
|
|
<p>If the simple duration is indefinite, any <code>keyTimes</code>
|
|
specification will be ignored.<br>
|
|
</p>
|
|
</dd>
|
|
<dt><code><a name="KeySplinesAttribute"></a>keySplines</code> <span
|
|
class="argvalue">= "<strong><list></strong>"</span></dt>
|
|
<dd>A set of Bezier control points associated with the
|
|
<code>keyTimes</code> list, defining a cubic Bezier 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 floating point values: <code>x1 y1 x2 y2</code>, describing
|
|
the Bezier control points for one time segment. The
|
|
<code>keyTimes</code> values that define the associated segment are the
|
|
Bezier "anchor points", and the <code>keySplines</code> values are the
|
|
control points. Thus, there must be one fewer sets of control points
|
|
than there are <code>keyTimes</code>.
|
|
<p>The values must all be in the range 0 to 1.</p>
|
|
<p>This attribute is ignored unless the <code>calcMode</code> is set to
|
|
"spline".</p>
|
|
<p>If there are any errors in the <code>keySplines</code> specification
|
|
(bad values, too many or too few values), the animation will have no
|
|
effect.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>If <code>calcMode</code> is set to "discrete", "linear" or "spline", but
|
|
the <span class="attr-name"><code>keyTimes</code></span> attribute is not
|
|
specified, the values in the <span
|
|
class="attr-name"><code>values</code></span> attribute are assumed to be
|
|
equally spaced through the animation duration, according to the
|
|
<code>calcMode</code>:</p>
|
|
<ul>
|
|
<li>For <em> discrete</em> animation, the duration is divided into equal
|
|
time periods, one per value. The animation function takes on the values in
|
|
order, one value for each time period. </li>
|
|
<li>For <em> linear</em> and <em> spline</em> animation, the duration is
|
|
divided into <code>n-1</code> even periods, and the animation function is
|
|
a linear interpolation between the values at the associated times. Note
|
|
that a <em> linear</em> animation will be a smoothly closed loop if the
|
|
first value is repeated as the last.</li>
|
|
</ul>
|
|
|
|
<p>This semantic applies as well when the <code>keySplines</code> attribute is
|
|
specified, but <span class="attr-name"><code>keyTimes</code></span> is not.
|
|
The times associated to the <code>keySplines</code> values are determined as
|
|
described above.</p>
|
|
|
|
<p>The syntax for the control point sets in <code>keySplines</code> lists
|
|
is:</p>
|
|
<pre>control-pt-set ::= ( fpval comma-wsp fpval comma-wsp fpval comma-wsp fpval )
|
|
fpval ::= <em>Floating point number</em>
|
|
<a name="comma-wspBNF"></a>comma-wsp ::= <a href="#Timing-WhiteSpaceBNF">S</a> (<a href="#Timing-WhiteSpaceBNF">spacechar</a>|",") <a href="#Timing-WhiteSpaceBNF">S</a></pre>
|
|
|
|
<p>Control point values are separated by at least one white space character or
|
|
a comma. Additional white space around the separator is allowed. The allowed
|
|
syntax for floating point numbers must be defined in the host language.</p>
|
|
|
|
<p>For the shorthand forms <em>from-to animation</em> and <em>from-by
|
|
animation</em>, there are only 2 values. A discrete <em>from-to
|
|
animation</em> will set the "from" value for the first half of the simple
|
|
duration and the "to" value for the second half of the simple duration.
|
|
Similarly, a discrete <em>from-by animation</em> will set the "from" value for
|
|
the first half of the simple duration and for the second half of the simple
|
|
duration will set the computed result of applying the "by" value. For the
|
|
shorthand form <em>to animation</em>, there is only 1 value; a discrete <em>to
|
|
animation</em> will simply set the "to" value for the simple duration.</p>
|
|
|
|
<p>If the argument values for <code>keyTimes</code> or
|
|
<code>keySplines</code> are not legal (including too few or too many values
|
|
for either attribute), the animation will have no effect (see also <a
|
|
href="#AnimationSyntaxErrors">Handling syntax errors</a>).</p>
|
|
|
|
<p>In the <code>calcMode</code>, <code>keyTimes</code> and
|
|
<code>keySplines</code> attribute values, leading and trailing white space and
|
|
white space before and after semicolon separators will be ignored.</p>
|
|
|
|
<h5>Interpolation modes illustrated</h5>
|
|
|
|
<p>The three illustrations 1a, 1b and 1c below show how the same basic
|
|
animation will change a value over time, given different interpolation modes.
|
|
All examples use the default timing (no <code>keyTimes</code> or
|
|
<code>keySplines</code> specified). All examples are based upon the following
|
|
example, but with different values for <code>calcMode</code>:</p>
|
|
<pre><animate dur="30s" values="0; 1; 2; 4; 8; 15" calcMode="[as specified]" /></pre>
|
|
|
|
<p> </p>
|
|
|
|
<table border="1" width="100%" cellpadding="10">
|
|
<tbody>
|
|
<tr>
|
|
<td><img border="0" src="DiscreteGraph.png" width="323" height="191"
|
|
alt="Diagram of linear interpolation"></td>
|
|
<td><h5>Figure 1a: Default discrete animation.</h5>
|
|
|
|
<p><code>calcMode="discrete"</code></p>
|
|
|
|
<p>There are 6 segments of equal duration: 1 segment per value.</p>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><img border="0" src="LinearGraph.png" width="323" height="191"
|
|
alt="Diagram of linear interpolation"></td>
|
|
<td><h5>Figure 1b: Default linear animation.</h5>
|
|
|
|
<p><code>calcMode="linear"</code></p>
|
|
|
|
<p>There are 5 segments of equal duration: n-1 segments for n values.
|
|
Spline interpolation is a refinement of linear, and is further
|
|
illustrated in Figure 2, below.</p>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><img border="0" src="PacedGraph.png" width="323" height="191"
|
|
alt="Diagram of linear interpolation"></td>
|
|
<td><h5>Figure 1c: Default paced animation.</h5>
|
|
|
|
<p><code>calcMode="paced"</code></p>
|
|
|
|
<p>There are 5 segments of varying duration: n-1 segments for n
|
|
values, computed to yield a constant rate of change in the value.</p>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h5>Examples</h5>
|
|
|
|
<p>The following example describes a simple discrete animation:</p>
|
|
<pre><animate attributeName="foo" dur="8s"
|
|
values="bar; fun; far; boo" /></pre>
|
|
|
|
<p>The value of the attribute "foo" will be set to each of the four strings
|
|
for 2 seconds each. Because the string values cannot be interpolated, only
|
|
<em>discrete</em> animation is possible; any <code>calcMode</code> attribute
|
|
would be ignored.</p>
|
|
|
|
<p>Discrete animation can also be used with <code>keyTimes</code>, as in the
|
|
following example:</p>
|
|
<pre><animateColor attributeName="color" dur="10s" calcMode="discrete"
|
|
values="green; yellow; red" keyTimes="0.0; 0.5;" /></pre>
|
|
|
|
<p>This example also shows how <code>keyTimes</code> values can interact with
|
|
an indefinite duration. The value of the "color" attribute will be set to
|
|
green for 5 seconds, and then to yellow for 5 seconds, and then will remain
|
|
red for the remainder of the document, since the (unspecified) duration
|
|
defaults to "indefinite".</p>
|
|
|
|
<p>The following example describes a simple linear animation:</p>
|
|
<pre><animate attributeName="x" dur="10s" values="0; 10; 100"
|
|
<strong>calcMode="linear"</strong>/></pre>
|
|
|
|
<p>The value of "x" will change from 0 to 10 in the first 5 seconds, and then
|
|
from 10 to 100 in the second 5 seconds. Note that the values in the
|
|
<code>values</code> attribute are spaced evenly in time with no
|
|
<code>keyTimes</code> specified; in this case the result is a much larger
|
|
actual change in the value during the second half of the animation. Contrast
|
|
this with the same example changed to use "paced" interpolation:</p>
|
|
<pre><animate attributeName="x" dur="10s" values="0; 10; 100"
|
|
<strong>calcMode="paced"</strong>/></pre>
|
|
|
|
<p>To produce an even pace of change to the attribute "x", the second segment
|
|
defined by the values list gets most of the simple duration: The value of "x"
|
|
will change from 0 to 10 in the first second, and then from 10 to 100 in the
|
|
next 9 seconds. While this example could be easily authored as a
|
|
<em>from-to</em> animation without paced interpolation, many examples (such as
|
|
motion paths) are much harder to author without the "paced" value for
|
|
<code>calcMode</code>. </p>
|
|
|
|
<p>The following example illustrates the use of <code>keyTimes</code>:</p>
|
|
<pre><animate attributeName="x" dur="10s" values="0; 50; 100"
|
|
<strong>keyTimes="0; .8; 1"</strong> <strong>calcMode="linear"</strong>/></pre>
|
|
|
|
<p>The <code>keyTimes</code> values cause the "x" attribute to have a value of
|
|
"0" at the start of the animation, "50" after 8 seconds (at 80% into the
|
|
simple duration) and "100" at the end of the animation. The value will change
|
|
more slowly in the first half of the animation, and more quickly in the second
|
|
half.</p>
|
|
|
|
<p>Extending this example to use <code>keySplines</code>:</p>
|
|
<pre><animate attributeName="x" dur="10s" values="0; 50; 100"
|
|
keyTimes="0; .8; 1" <strong>calcMode="spline" </strong>
|
|
<strong> keySplines</strong>=".5 0 .5 1; 0 0 1 1" /></pre>
|
|
|
|
<p>The <code>keyTimes</code> still cause the "x" attribute to have a value of
|
|
"0" at the start of the animation, "50" after 8 seconds and "100" at the end
|
|
of the animation. However, the <code>keySplines</code> values define a curve
|
|
for pacing the interpolation between values. In the example above, the spline
|
|
causes an ease-in and ease-out effect between time 0 and 8 seconds (i.e.,
|
|
between <code>keyTimes</code> 0 and .8, and <code>values</code> "0" and "50"),
|
|
but a strict linear interpolation between 8 seconds and the end (i.e., between
|
|
<code>keyTimes</code> .8 and 1, and <code>values</code> "50" and "100"). See
|
|
Figure 2 below for an illustration of the curves that these
|
|
<code>keySplines</code> values define.</p>
|
|
|
|
<p>For some attributes, the <em>pace</em> of change may not be easily
|
|
discernable by viewers. However for animations like motion, the ability to
|
|
make the <em>speed</em> of the motion change gradually, and not in abrupt
|
|
steps, can be important. The <code>keySplines</code> attribute provides this
|
|
control.</p>
|
|
|
|
<p>The following figure illustrates the interpretation of the
|
|
<code>keySplines</code> attribute. Each diagram illustrates the effect of
|
|
<code>keySplines</code> settings for a single interval (i.e., between the
|
|
associated pairs of values in the <code>keyTimes</code> and
|
|
<code>values</code> lists.). The horizontal axis can be thought of as the
|
|
input value for the <em>unit progress</em> 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 the <em>unit
|
|
progress</em>, yielded by the <code>keySplines</code> function. Another way of
|
|
describing this is that the horizontal axis is the input <em>unit time</em>
|
|
for the interval, and the vertical axis is the output <em>unit time</em>. See
|
|
also the section <a href="#TimingAndRealWorldClockTime">Timing and real-world
|
|
clock times</a>.</p>
|
|
|
|
<table>
|
|
<tbody>
|
|
<tr>
|
|
<td width="10"></td>
|
|
<td width="172"><img
|
|
alt="Example keySplines01 - keySplines of 0 0 1 1 (the default)"
|
|
width="172" height="174" src="interpSpline01.png"> <span
|
|
style="FONT-STYLE: italic; TEXT-ALIGN: center">keySplines="0 0 1 1"
|
|
(the default)</span></td>
|
|
<td width="20"></td>
|
|
<td width="172"><img
|
|
alt="Example keySplines02 - keySplines of .5 0 .5 1"
|
|
src="interpSpline02.png" width="172" height="174"> <span
|
|
style="FONT-STYLE: italic; TEXT-ALIGN: center">keySplines=".5 0 .5 1"<br>
|
|
</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td width="10"></td>
|
|
<td width="172"><img
|
|
alt="Example keySplines03 - keySplines of 0 .75 .25 1"
|
|
src="interpSpline03.png" width="172" height="174"> <span
|
|
style="FONT-STYLE: italic; TEXT-ALIGN: center">keySplines="0 .75 .25 1"</span></td>
|
|
<td width="20"></td>
|
|
<td width="172"><img
|
|
alt="Example keySplines04 - keySplines of 1 0 .25 .25"
|
|
src="interpSpline04.png" width="172" height="174"> <span
|
|
style="FONT-STYLE: italic; TEXT-ALIGN: center">keySplines="1 0 .25 .25"</span></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h5>Figure 2: Illustration of keySplines effect</h5>
|
|
|
|
<p>To illustrate the calculations, consider the simple example:</p>
|
|
<pre><animate dur="4s" values="10; 20" keyTimes="0; 1"
|
|
calcMode="spline" <strong>keySplines</strong>=<em>{as in table}</em> /></pre>
|
|
|
|
<p>Using the keySplines values for each of the four cases above, the
|
|
approximate interpolated values as the animation proceeds are:</p>
|
|
|
|
<table border="1" cellpadding="4">
|
|
<tbody>
|
|
<tr>
|
|
<td>keySplines values </td>
|
|
<td>Initial value</td>
|
|
<td>After 1s</td>
|
|
<td>After 2s</td>
|
|
<td>After 3s</td>
|
|
<td>Final value</td>
|
|
</tr>
|
|
<tr>
|
|
<td>0 0 1 1</td>
|
|
<td>10.0</td>
|
|
<td>12.5</td>
|
|
<td>15.0</td>
|
|
<td>17.5</td>
|
|
<td>20.0</td>
|
|
</tr>
|
|
<tr>
|
|
<td>.5 0 .5 1</td>
|
|
<td>10.0</td>
|
|
<td>11.0</td>
|
|
<td>15.0</td>
|
|
<td>19.0</td>
|
|
<td>20.0</td>
|
|
</tr>
|
|
<tr>
|
|
<td>0 .75 .25 1</td>
|
|
<td>10.0</td>
|
|
<td>18.0</td>
|
|
<td>19.3</td>
|
|
<td>19.8</td>
|
|
<td>20.0</td>
|
|
</tr>
|
|
<tr>
|
|
<td>1 0 .25 .25</td>
|
|
<td>10.0</td>
|
|
<td>10.1</td>
|
|
<td>10.6</td>
|
|
<td>16.9</td>
|
|
<td>20.0</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<p>For a formal definition of Bezier spline calculation, see [<a
|
|
href="#ref-COMP-GRAPHICS">COMP-GRAPHICS</a>].</p>
|
|
|
|
<p>The <code>keyTimes</code> and <code>keySplines</code> attributes can also
|
|
be used with the <em>from/to/by</em> shorthand forms for specifying values, as
|
|
in the following example:</p>
|
|
<pre><animate attributeName="foo" from="10" to="20"
|
|
dur="10s" keyTimes="0.0; 0.7"
|
|
calcMode="spline" <strong>keySplines</strong>="<em>.5 0 .5 1"</em> /></pre>
|
|
|
|
<p>The value will change from 10 to 20, using an "<em>ease-in/ease-out</em>"
|
|
curve specified by the keySplines values. The <code>keyTimes</code> values
|
|
cause the value of 20 to be reached at 7 seconds, and to hold there for the
|
|
remainder of the 10 second simple duration.</p>
|
|
|
|
<p>The following example describes a somewhat unusual usage: "from-to
|
|
animation" with discrete animation. The "stroke-linecap" attribute of SVG
|
|
elements takes a string, and so implies a calcMode of discrete. The animation
|
|
will set the stroke-linecap property to "round" for 5 seconds (half the simple
|
|
duration) and then set the stroke-linecap to "square" for 5 seconds.</p>
|
|
<pre><rect stroke-linecap="butt"...>
|
|
<animate attributeName="stroke-linecap"
|
|
from="round" to="square" dur="10s"/>
|
|
</rect></pre>
|
|
|
|
<h3><a name="SpecifyingAnimationEffect"></a> 3.3. Specifying the animation
|
|
effect F(t)</h3>
|
|
|
|
<p>As described above, the animation function
|
|
<code><strong>f(t)</strong></code> defines the animation for the simple
|
|
duration. However SMIL Animation allows the author to repeat the simple
|
|
duration. SMIL Animation also allows authors to specify whether the animation
|
|
should simply end when the active duration completes, or whether it should be
|
|
<em>frozen</em> at the last value. In addition, the author can specify how
|
|
each animation should be combined with other animations and the original DOM
|
|
value.</p>
|
|
|
|
<p>This section describes the syntax and associated semantics for the
|
|
additional functionality. A detailed model for combining animations is
|
|
described, along with additional details of the timing model.</p>
|
|
|
|
<p>The period of time during which the animation is actively playing,
|
|
including any repeat behavior, is described as the active duration. The active
|
|
duration may be computed from the simple duration and the repeat
|
|
specification, and it may be constrained with the
|
|
<code><strong>end</strong></code> attribute. The complete rules for computing
|
|
the active duration are presented in the section <a
|
|
href="#ComputingActiveDur">Computing the active duration</a>.</p>
|
|
|
|
<h4><a name="RepeatingAnim"></a> 3.3.1. Repeating animations</h4>
|
|
|
|
<p>Repeating an animation causes the animation function
|
|
<code><strong>f(t)</strong></code> to be "played" several times in sequence.
|
|
The author can specify either <em>how many times </em>to repeat, using
|
|
<code>repeatCount</code>, or <em>how long </em>to repeat, using
|
|
<code>repeatDur</code>. Each repeat <em>iteration</em> is one instance of
|
|
"playing" the animation function <code><strong>f(t)</strong></code>.</p>
|
|
|
|
<p>If the simple duration is indefinite, the animation cannot repeat. See also
|
|
the section <a href="#ComputingActiveDur">Computing the active
|
|
duration</a>.</p>
|
|
<dl>
|
|
<dt><a name="RepeatCountAttribute"></a>repeatCount</dt>
|
|
<dd>Specifies the number of iterations of the animation function. It can
|
|
have the following attribute values:
|
|
<dl>
|
|
<dt>numeric value</dt>
|
|
<dd>This is a (base 10) "floating point" numeric value that
|
|
specifies the number of iterations. It can include partial
|
|
iterations expressed as fraction values. A fractional value
|
|
describes a portion of the simple duration. Values must be greater
|
|
than 0. <code><br>
|
|
</code></dd>
|
|
<dt>"indefinite"</dt>
|
|
<dd>The animation is defined to repeat indefinitely (i.e., until the
|
|
document ends).</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><a name="RepeatDurAttribute"></a>repeatDur</dt>
|
|
<dd>Specifies the total duration for repeat. It can have the following
|
|
attribute values:
|
|
<dl>
|
|
<dt><a href="#Timing-ClockValueSyntax">Clock-value</a>
|
|
</dt>
|
|
<dd>Specifies the duration in presentation time to repeat the
|
|
animation function <code><strong>f(t)</strong></code>.</dd>
|
|
<dd> </dd>
|
|
<dt>"indefinite"</dt>
|
|
<dd>The animation is defined to repeat indefinitely (i.e., until the
|
|
document ends).</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>At most one of <code>repeatCount</code> or <code>repeatDur</code> should be
|
|
specified. If both are specified (and the simple duration is not indefinite),
|
|
the active duration is defined as the minimum of the specified repeatDur and
|
|
the simple duration multiplied by repeatCount. For the purposes of this
|
|
comparison, a defined value is considered to be "less than" a value of
|
|
"indefinite". If the simple duration is indefinite, and both
|
|
<code>repeatCount</code> and <code>repeatDur</code> are specified, the
|
|
<code>repeatCount</code> will be ignored, and the <code>repeatDur</code> will
|
|
be used (refer to the examples below describing <code>repeatDur</code> and an
|
|
indefinite simple duration). These rules are included in the section <a
|
|
href="#ComputingActiveDur">Computing the active duration</a>.</p>
|
|
|
|
<h5>Examples</h5>
|
|
|
|
<p>In the following example, the 2.5 second animation function will be
|
|
repeated twice; the active duration will be 5 seconds.</p>
|
|
|
|
<p><tt><animate attributeName="top" from="0" to="10" dur="2.5s"<strong><br>
|
|
repeatCount="2"</strong> /></tt></p>
|
|
|
|
<p>In the following example, the animation function will be repeated two full
|
|
times and then the first half is repeated once more; the active duration will
|
|
be 7.5 seconds.</p>
|
|
|
|
<p><tt><animate attributeName="top" from="0" to="10" dur="3s"<strong><br>
|
|
repeatCount="2.5"</strong> /></tt></p>
|
|
|
|
<p>In the following example, the animation function will repeat for a total of
|
|
7 seconds. It will play fully two times, followed by a fractional part of 2
|
|
seconds. This is equivalent to a repeatCount of 2.8. The last (partial)
|
|
iteration will apply values in the range "0" to "8". </p>
|
|
|
|
<p><tt><animate attributeName="top" from="0" to="10" dur="2.5s"<br>
|
|
<strong>repeatDur="7s"</strong> /></tt></p>
|
|
|
|
<p>Note that if the simple duration is not defined (e.g. it is indefinite),
|
|
repeat behavior is not defined (but <code>repeatDur</code> still defines the
|
|
active duration). In the following example the simple duration is indefinite,
|
|
and so the <code>repeatCount</code> is effectively ignored. Nevertheless, this
|
|
is not considered an error: the active duration is also indefinite. The effect
|
|
of the animation is to to just use the value for <strong>
|
|
<code>f(0)</code></strong>, setting the fill color to red for the remainder of
|
|
the document duration.</p>
|
|
|
|
<p><tt><animate attributeName="fill" from="red" to="blue"
|
|
<strong>repeatCount="2"</strong> /></tt></p>
|
|
|
|
<p>In the following example, the simple duration is indefinite, but the
|
|
<code>repeatDur</code> still determines the active duration. The effect of the
|
|
animation is to set the fill color to red for 10 seconds.</p>
|
|
|
|
<p><tt><animate attributeName="fill" from="red" to="blue"
|
|
<strong>repeatDur="10s"</strong> /></tt></p>
|
|
|
|
<p>In the following example, the simple duration is longer than the duration
|
|
specified by <code>repeatDur</code>, and so the active duration will
|
|
effectively cut short the simple duration. However, the animation function
|
|
still interpolates using the specified simple duration. The effect of the
|
|
animation is to interpolate the value of "top" from 10 to 17, over the course
|
|
of 7 seconds.</p>
|
|
|
|
<p><tt><animate attributeName="top" from="10" to="20" <strong><br>
|
|
dur="10s" repeatDur="7s"</strong> /></tt></p>
|
|
|
|
<!-- start min and restart -->
|
|
<H5>
|
|
<A name="MinAndRestart"></A>The
|
|
<code>min</code> attribute and restart:
|
|
</H5>
|
|
<P>
|
|
The <code>min</code>
|
|
attribute does not prevent an
|
|
element from restarting before the minimum active duration is reached.
|
|
<!-- end min and restart -->
|
|
|
|
<h5><a name="Accumulate"></a>Controlling behavior of repeating animation -
|
|
Cumulative animation</h5>
|
|
|
|
<p>The author may also select whether a repeating animation should repeat the
|
|
original behavior for each iteration, or whether it should build upon the
|
|
previous results, accumulating with each iteration. For example, a motion path
|
|
that describes an arc can repeat by moving along the same arc over and over
|
|
again, or it can begin each repeat iteration where the last left off, making
|
|
the animated element bounce across the window. This is called
|
|
<em>cumulative</em> animation.</p>
|
|
|
|
<p>Using the path notation for a simple arc (detailed in <a
|
|
href="#animateMotionElement">The animateMotion element</a>), we describe this
|
|
example as:</p>
|
|
<pre><img ...>
|
|
<animateMotion path="m 0 0 c 30 50 70 50 100 0 z" dur="5s"
|
|
<strong>accumulate="sum" </strong>repeatCount="4" />
|
|
</img></pre>
|
|
|
|
<p>The image moves from the original position along the arc over the course of
|
|
5 seconds. As the animation repeats, it builds upon the previous value and
|
|
begins the second arc where the first one ended, as illustrated in Figure 3,
|
|
below. In this way, the image "bounces" across the screen. The same animation
|
|
could be described as a complete path of 4 arcs, but in the general case the
|
|
path description can get quite large and cumbersome to edit.</p>
|
|
|
|
<p class="ednote"><img border="0" src="AccumGraph.png" width="471" height="88"
|
|
alt="Diagram showing accumlating animation"></p>
|
|
|
|
<h5>Figure 3: Illustration of repeating animation with
|
|
<code>accumulate="sum"</code>. Each repeat iteration builds upon the
|
|
previous.</h5>
|
|
|
|
<p>Note that cumulative animation only controls how a single animation
|
|
accumulates the results of the animation function as it repeats. It
|
|
specifically does not control how one animation interacts with other
|
|
animations to produce a presentation value. This latter behavior is described
|
|
in the section <a href="#AdditiveAnim">Additive animation</a>.</p>
|
|
|
|
<p>The cumulative behavior of repeating animations is controlled with the
|
|
<code>accumulate</code> attribute:</p>
|
|
<dl>
|
|
<dt><a name="AccumulateAttribute"></a>accumulate <span class="argvalue">=
|
|
"<strong>none | sum</strong>"</span></dt>
|
|
<dd>Controls whether or not the animation is cumulative. <br>
|
|
If <code>"sum"</code>, each repeat iteration after the first builds upon
|
|
the last value of the previous iteration.<br>
|
|
If <code>"none"</code>, repeat iterations are not cumulative, and simply
|
|
repeat the animation function <code><strong>f(t)</strong></code>. This
|
|
is the default.
|
|
<p>This attribute is ignored if the target attribute value does not
|
|
support addition, or if the animation element does not repeat.</p>
|
|
<p>Cumulative animation is not defined for "<em>to animation</em>". This
|
|
attribute will be ignored if the animation function is specified with
|
|
only the <code>to</code> attribute. See also <a
|
|
href="#AnimFuncValues">Specifying function values</a>.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>Any numeric attribute that supports addition can support cumulative
|
|
animation. For example, we can define a "pulsing" animation that will grow the
|
|
"width" of an SVG <code><rect></code> element by 100 pixels in 50
|
|
seconds.</p>
|
|
<pre><rect width="20px"...>
|
|
<animate attributeName="width" dur="5s"
|
|
values="0; 15; 10" additive="sum"
|
|
<strong>accumulate="sum" </strong>repeatCount="10" />
|
|
</rect></pre>
|
|
|
|
<p>Each simple duration causes the rectangle width to bulge by 15 pixels and
|
|
end up 10 pixels larger. The shape is 20 pixels wide at the beginning, and
|
|
after 5 seconds is 30 pixels wide. The animation repeats, and builds upon the
|
|
previous values. The shape will bulge to 45 pixels and then end up 40 pixels
|
|
wide after 10 seconds, and will eventually end up 120 (20 + 100) pixels wide
|
|
after all 10 repeats.</p>
|
|
|
|
<p><em>From-to</em> and <em>from-by</em> animations also support cumulative
|
|
animation, as in the following example:</p>
|
|
<pre><rect width="20px"...>
|
|
<animate attributeName="width" dur="5s" from="10px" to="20px"
|
|
<strong>accumulate="sum" </strong>repeatCount="10" />
|
|
</rect></pre>
|
|
|
|
<p>The rectangle will grow from 10 to 20 pixels in the first 5 seconds, and
|
|
then from 20 to 30 in the next 5 seconds, and so on up to 110 pixels after 10
|
|
repeats. Note that since the default value for <code>additive</code> is
|
|
"replace", the original value is ignored. The following example makes the
|
|
animation explicitly additive:</p>
|
|
<pre><rect width="20px"...>
|
|
<animate attributeName="width" dur="5s" from="10px" to="20px"
|
|
<strong>accumulate="sum" additive="sum" </strong>repeatCount="10" />
|
|
</rect></pre>
|
|
|
|
<p>The results are the same as before, except that all the values are shifted
|
|
up by the original value of 20. The rectangle is 30 pixels wide after 5
|
|
seconds, and 130 pixels wide after 10 repeats.</p>
|
|
|
|
<h6>Computing cumulative animation values</h6>
|
|
|
|
<p>To produce the cumulative animation behavior, the animation function
|
|
<code><strong>f(t)</strong></code> must be modified slightly. Each iteration
|
|
after the first must add in the last value of the previous iteration - this is
|
|
expressed as a multiple of the last value <a
|
|
href="#AnimFuncValues">specified</a> for the animation function. Note that
|
|
cumulative animation is defined in terms of the values specified for the
|
|
animation behavior, and not in terms of sampled or rendered animation values.
|
|
The latter would vary from machine to machine, and could even vary between
|
|
document views on the same machine.</p>
|
|
|
|
<p>Let <code><strong>f<sub>i</sub>(t)</strong></code> represent the cumulative
|
|
animation function for a given iteration <code>i</code>.</p>
|
|
|
|
<p>The first iteration <code><strong>f<sub>0</sub>(t)</strong></code> is
|
|
unaffected by <code>accumulate</code>, and so is the same as the original
|
|
animation function definition.</p>
|
|
|
|
<p><code><strong>f<sub>0</sub>(t) = f(t)</strong></code></p>
|
|
|
|
<p>Let <code><strong>ve</strong></code> be the last value specified for the
|
|
animation function (e.g., the "to" value, the last value in a "values" list, or
|
|
the end of a "path"). Each iteration after the first adds in the computed
|
|
offset:</p>
|
|
|
|
<p><code><strong>f<sub>i</sub>(t) = (ve * i) + f(t) </strong>; i >=
|
|
1</code></p>
|
|
|
|
<h4><a name="EndActive"></a> 3.3.2. Controlling the active duration</h4>
|
|
|
|
<p>SMIL Animation provides an additional control over the active duration. The
|
|
<code>end</code> attribute allows the author to constrain the active duration
|
|
of the animation by specifying an end value, using a simple offset, a time
|
|
base, an event-base or DOM method calls. The <code>end</code> attribute can
|
|
<em>constrain</em> but not <em>extend</em> the active duration that is
|
|
otherwise defined by <code>dur</code> and any repeat behavior. The rules for
|
|
combining the attributes to compute the active duration are presented in the
|
|
section, <a href="#ComputingActiveDur">Computing the active duration</a>.</p>
|
|
<dl>
|
|
<dt><a name="EndActiveAttribute"></a>end</dt>
|
|
<dd>Defines an end value for the animation that can constrain the active
|
|
duration.<br>
|
|
The attribute value is a semi-colon separated list of values.
|
|
<dl>
|
|
<dt><a href="#Timing-EndValueListSyntax">end-value-list</a> : end-value (";"
|
|
end-value-list )?</dt>
|
|
<dd>A semi-colon separated list of end values. The interpretation of a
|
|
list of end times is detailed in the section <a href="#Timing-EvaluationOfBeginEndTimeLists">Evaluation
|
|
of begin and end time lists</a>.<br>
|
|
<dt>end-value : ( offset-value | syncbase-value |
|
|
event-value | repeat-value | accessKey-value | media-marker-value |
|
|
wallclock-sync-value | "indefinite" )
|
|
<dd>Describes the end value.
|
|
<dt><a href="#Timing-OffsetValueSyntax">offset-value</a> : ( "+" |
|
|
"-" )? <a href="#Timing-ClockValueSyntax">Clock-value</a>
|
|
<dd>Specifies the presentation time of the end. The end value is
|
|
thus defined relative to the document begin.</dd>
|
|
<dt><a href="#Timing-SyncbaseValueSyntax">syncbase-value</a> : ( Id-value
|
|
"." ( "begin" | "end" ) ) ( (
|
|
"+" | "-" ) Clock-value )?</dt>
|
|
<dd>Describes a syncbase and an offset from that syncbase. The end
|
|
value is defined relative to the begin or active end of another
|
|
element.</dd>
|
|
<dt><a href="#Timing-EventValueSyntax">event-value</a> : ( Id-value
|
|
"." )? ( event-ref ) ( ( "+" | "-"
|
|
) Clock-value )?</dt>
|
|
<dd>Describes an event and an optional offset that determine the
|
|
element begin. The animation end value is defined relative to the time
|
|
that the event is raised. Events may be any event defined for the
|
|
host language in accordance with [<a
|
|
href="#ref-DOM2Events">DOM2Events</a>]. These may include
|
|
user-interface events, event-triggers transmitted via a network,
|
|
etc. Details of event-based timing are described in the section
|
|
below on <a href="#Unifying">Unifying event-based and scheduled
|
|
timing</a>.</dd>
|
|
<dt><a href="#Timing-RepeatValueSyntax">repeat-value</a> : ( Id-value
|
|
"." )? "repeat(" integer ")" ( (
|
|
"+" | "-" ) Clock-value )?</dt>
|
|
<dd>Describes a qualified repeat event. The end value is defined
|
|
relative to the time that the repeat event is raised with the
|
|
specified iteration value.
|
|
<dt><a href="#Timing-AccessKeyValueSyntax">accessKey-value</a> : "accessKey("
|
|
character ")"</dt>
|
|
<dd>Describes an accessKey that determines the end value. The end value is defined relative to the time that the accessKey
|
|
character is input by the user.
|
|
<dt><a href="#Timing-WallclockSyncValueSyntax">wallclock-sync-value</a>
|
|
: "wallclock(" wallclock-value ")"</dt>
|
|
<dd>Describes the end value as a real-world clock time. The
|
|
wallclock time syntax is based upon syntax defined in [<a href="#ref-iso8601">ISO8601</a>].
|
|
<dt>"indefinite"</dt>
|
|
<dd>The end value of the animation will be determined by a "endElement()"
|
|
(or equivalent) method call.<br>
|
|
The SMIL Animation DOM methods are described in the <a
|
|
href="#DOM-SupportedMethods">Supported methods</a> section.<br>
|
|
Hyperlink-based timing is described in the <a
|
|
href="#HyperlinkSemantics">Hyperlinks and timing</a> section.</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p class="informative">The end value can specify a list of times. This can be
|
|
used to specify multiple "ways" or "rules" to end an element, e.g. if any one
|
|
of several events is raised. A list of times can also define multiple end
|
|
times that can correspond to multiple begin times, allowing the element to
|
|
play more than once (this behavior can be controlled - see also <a href="#Restart">Restarting
|
|
animations</a>). </p>
|
|
|
|
<h5>Examples:</h5>
|
|
|
|
<p>In the following example, the active duration will end at the earlier of 10
|
|
seconds or the end of the "foo" element. This is particularly useful if
|
|
"foo"
|
|
is defined to begin or end relative to an event.</p>
|
|
<pre><animate dur="2s" repeatDur="10s" <strong>end="foo.end</strong>" ... /></pre>
|
|
|
|
<p>In the following example, the animation begins when the user clicks on the
|
|
target element. The active duration will end 30 seconds after the document
|
|
begins. Note that if the user has not clicked on the target element before 30
|
|
seconds elapse, the animation will never begin.</p>
|
|
<pre><animate begin="click" dur="2s" repeatDur="indefinite"
|
|
<strong>end="30s</strong>" ... /></pre>
|
|
|
|
<p>Using <code>end</code> with an event value enables authors to end an
|
|
animation based on either an interactive event or a maximum active duration.
|
|
This is sometimes known as <em>lazy interaction</em>.</p>
|
|
|
|
<p>In this example, a presentation describes some factory processes. It uses
|
|
animation to move an image around (e.g. against a background), demonstrating
|
|
how an object moves from one part of a factory to another. Each step is a
|
|
motion path, and set to repeat 3 times to make the point clear. Each animation
|
|
can also be ended by clicking on some element "next" that allows the user to
|
|
advance the presentation to the next step.</p>
|
|
<pre><img id="objectToMove" ... >
|
|
<animateMotion id="step1" begin="0" dur="5s"
|
|
repeatCount="3" <strong>end="next.click"</strong> path.../>
|
|
<animateMotion id="step2" begin="step1.end" dur="5s"
|
|
repeatCount="3" <strong>end</strong><strong>="next.click"</strong> path.../>
|
|
<animateMotion id="step3" begin="step2.end" dur="5s"
|
|
repeatCount="3" <strong>end</strong><strong>="next.click"</strong> path.../>
|
|
<animateMotion id="step4" begin="step3.end" dur="5s"
|
|
repeatCount="3" <strong>end</strong><strong>="next.click"</strong> path.../>
|
|
<animateMotion id="step5" begin="step4.end" dur="5s"
|
|
repeatCount="3" <strong>end</strong><strong>="next.click"</strong> path.../>
|
|
</img></pre>
|
|
|
|
<p>In this case, the active end of each animation is defined to be the earlier
|
|
of 15 seconds after it begins, or a click on "next". This lets the viewer sit
|
|
back and watch, or advance the presentation at a faster pace.</p>
|
|
|
|
<!-- start of min max -->
|
|
<H4>
|
|
<A name="MinMax"></A> 3.3.3. The <SPAN class="attr">min and max</SPAN> attributes:
|
|
more control over the active duration
|
|
</H4>
|
|
<P>
|
|
<SPAN class="informative"><EM>This section is informative</EM></SPAN>
|
|
<P>
|
|
The min/max attributes provide the author with a way to control the lower
|
|
and upper bound of the element active duration.
|
|
<P>
|
|
<EM>This section is normative</EM>
|
|
<DIV class="adef-list">
|
|
<DL>
|
|
<DT>
|
|
<A name="adef-min"><SPAN class="adef">min</SPAN></A>
|
|
<DD>
|
|
<SPAN class="normative">Specifies the minimum value of the active duration.<BR>
|
|
The attribute value can be either of the following:</SPAN>
|
|
<DL>
|
|
<DT>
|
|
<SPAN class="normative"><A href="#Timing-ClockValueSyntax">Clock-value</A></SPAN>
|
|
<DD>
|
|
<SPAN class="normative">Specifies the length of the minimum value of the
|
|
active duration, measured in element active time.<BR>
|
|
Value must be greater than or equal to 0.</SPAN>
|
|
<DT>
|
|
<SPAN class="normative">"media"</SPAN>
|
|
<DD>
|
|
<SPAN class="normative">Specifies the minimum value of the active duration
|
|
as the intrinsic media duration. This is only valid for elements that define
|
|
media.</SPAN>
|
|
</DL>
|
|
</DL>
|
|
</DIV>
|
|
<P class="normative">
|
|
If there is any error in the argument value syntax for
|
|
<code>min</code>, the attribute will be ignored (as
|
|
though it were not specified).
|
|
<P class="normative">
|
|
The default value for <code>min</code> is "0". This
|
|
does not constrain the active duration at all.
|
|
<DIV class="adef-list">
|
|
<DL>
|
|
<DT>
|
|
<A name="adef-max"><SPAN class="adef">max</SPAN></A>
|
|
<DD>
|
|
<SPAN class="normative">Specifies the maximum value of the active duration.<BR>
|
|
The attribute value can be either of the following:</SPAN>
|
|
<DL>
|
|
<DT>
|
|
<SPAN class="normative"><A href="#Timing-ClockValueSyntax">Clock-value</A></SPAN>
|
|
<DD>
|
|
<SPAN class="normative">Specifies the length of the maximum value of the
|
|
active duration, measured in element active time.<BR>
|
|
Value must be greater than 0.</SPAN>
|
|
<DT>
|
|
<SPAN class="normative">"media"</SPAN>
|
|
<DD>
|
|
<SPAN class="normative">Specifies the maximum value of the active duration
|
|
as the intrinsic media duration. This is only valid for elements that define
|
|
media.</SPAN>
|
|
<DT>
|
|
<SPAN class="normative">"indefinite"</SPAN>
|
|
<DD>
|
|
<SPAN class="normative">The maximum value of the duration is indefinite,
|
|
and so is not constrained.</SPAN>
|
|
</DL>
|
|
</DL>
|
|
</DIV>
|
|
<P class="normative">
|
|
If there is any error in the argument value syntax for
|
|
<code>max</code>, the attribute will be ignored (as
|
|
though it were not specified).
|
|
<P class="normative">
|
|
The default value for <code>max</code> is "indefinite".
|
|
This does not constrain the active duration at all.
|
|
<P class="normative">
|
|
If the "<CODE>media</CODE>" argument value is specified for either
|
|
<code>min</code> or
|
|
<code>max</code> on an element that does not define
|
|
media, the respective attribute
|
|
will be ignored (as though it were not specified).
|
|
<P class="normative">
|
|
If both <code>min</code> and
|
|
<code>max</code> attributes are specified then the
|
|
<code>max</code> value must be greater than or equal
|
|
to the <code>min</code> value. If this requirement
|
|
is not fulfilled then both attributes are ignored.
|
|
<P class="normative">
|
|
The rule to apply to compute the active duration of an element with
|
|
<code>min</code> or
|
|
<code>max</code> specified is the following: Each
|
|
time the active duration of an element is computed (i.e. for each interval
|
|
of the element if it begins more than once), this computation is made without
|
|
taking into account the <code>min</code> and
|
|
<code>max</code> attributes (by applying the algorithm
|
|
described in <A href="#ComputingActiveDur">Computing the active
|
|
duration</A>). The result of this step is checked against the
|
|
<code>min</code> and
|
|
<code>max</code> bounds. If the result is within
|
|
the bounds, this first computed value is correct. Otherwise two situations
|
|
may occur:
|
|
<UL>
|
|
<LI>
|
|
<P class="normative">
|
|
if the first computed duration is greater than the max value, the active
|
|
duration of the element is defined to be equal to the
|
|
<code>max</code> value (see the first example below).
|
|
<LI>
|
|
<P class="normative">
|
|
if the first computed duration is less than the
|
|
<code>min</code> value, the active duration of the
|
|
element becomes equal to the <code>min</code> value
|
|
and the behavior of the element is as follows :
|
|
<UL>
|
|
<LI>
|
|
<P class="normative">
|
|
if the repeating duration (or the simple duration if the element doesn't
|
|
repeat) of the element is greater than
|
|
<code>min</code> then the element is played normally
|
|
for the (<code>min</code> constrained) active duration.
|
|
(see the second and third examples below).
|
|
<LI>
|
|
<P class="normative">
|
|
otherwise the element is played normally for its repeating duration (or simple
|
|
duration if the element does not repeat) and then is frozen or not shown
|
|
depending on the value of the <code>fill</code>
|
|
attribute (see the fourth and fifth examples below).
|
|
</UL>
|
|
</UL>
|
|
<P>
|
|
<H5>
|
|
<A name="minAndNegativeBegins"></A>The
|
|
<code>min</code> attribute and negative begin times
|
|
</H5>
|
|
<P>
|
|
If an element is defined to begin before its parent (e.g. with a simple negative
|
|
offset value), the <code>min</code> duration is measured
|
|
from the calculated begin time not the observed begin (see example 1 below).
|
|
This means that the <code>min</code> value may have
|
|
no observed effect.
|
|
<P>
|
|
See also the section <A href="#MinAndRestart">The min attribute and
|
|
restart</A>.
|
|
<!-- end of min max -->
|
|
|
|
<h4><a name="ComputingActiveDur"></a> 3.3.4. Computing the active
|
|
duration</h4>
|
|
|
|
<p>The table in Figure 4 shows the semantics of all possible combinations of
|
|
simple duration, <code>repeatCount</code> and <code>repeatDur</code>, and
|
|
<code>end</code>. The following conventions are used in the table:</p>
|
|
<ul>
|
|
<li>If a cell is empty, it indicates that the associated attribute is
|
|
omitted in the syntax. <br>
|
|
</li>
|
|
<li>Where the table entry is "defined", this corresponds to an explicit
|
|
specified value other than "indefinite". Note that if the simple duration
|
|
is not specified, it is defined to be indefinite. <br>
|
|
</li>
|
|
<li>Where the entry is a star ("*"), the value does not matter and can be
|
|
any of the possibilities. </li>
|
|
</ul>
|
|
|
|
<p>Additionally, the following rules must be followed in computing values:</p>
|
|
<ul>
|
|
<li>Where the active duration is specified as the minimum of several values
|
|
(MIN), it may not always be possible to calculate this when the document
|
|
begins. If the <code>end</code> is event-based or DOM-based, then an event
|
|
or method call that activates <code>end</code> <em>before</em> the
|
|
duration specified by <code>dur</code> and/or <code>repeatCount</code> or
|
|
<code>repeatDur</code> will cut short the active duration at the
|
|
<code>end</code> activation time.<br>
|
|
</li>
|
|
<li>If the value of <code>end</code> cannot be resolved (e.g. when it is
|
|
event-based), the value is considered to be "indefinite" for the purposes
|
|
of evaluating the active duration. If and when the end value becomes
|
|
resolved, the active duration is reevaluated.</li>
|
|
</ul>
|
|
|
|
<p>Some of the rules and results that are implicit in the table, and that
|
|
should be noted in particular are:</p>
|
|
<ul>
|
|
<li>If <code>end</code> is specified but neither of <code>repeatCount</code>
|
|
or <code>repeatDur</code> are specified, then the active duration is
|
|
defined as the minimum of the simple duration and the duration defined by
|
|
<code>end</code>.<br>
|
|
</li>
|
|
<li>If both <code>end</code> and either (or both) of
|
|
<code>repeatCount</code> or <code>repeatDur</code> are specified, the
|
|
active duration is defined by the minimum duration defined by the
|
|
respective attributes.<br>
|
|
</li>
|
|
<li>It is possible to have an indefinite simple duration and a defined,
|
|
finite active duration. The active duration can <em>constrain</em> (cut
|
|
short) the simple duration, but the active duration does not define the
|
|
simple duration, or change its value (i.e., the simple duration is still
|
|
indefinite as used in the simple animation function).<br>
|
|
</li>
|
|
<li>For any active duration and simple duration that are both not
|
|
indefinite, the number of repeat iterations is defined by the active
|
|
duration divided by the simple duration (this may yield partial repeat
|
|
iterations, just as <code>repeatCount</code> can specify).</li>
|
|
</ul>
|
|
|
|
<p>The following symbols are used in the table:</p>
|
|
<dl>
|
|
<dt><code><strong>B</strong></code></dt>
|
|
<dd>The begin of an animation.</dd>
|
|
<dt><code><strong>d</strong></code></dt>
|
|
<dd>The simple duration of an animation.</dd>
|
|
</dl>
|
|
|
|
<table border="1" cellpadding="3">
|
|
<tbody>
|
|
<tr>
|
|
<td align="center">Simple <br>
|
|
duration <strong>d</strong></td>
|
|
<td align="center"><code>repeatCount</code></td>
|
|
<td align="center"><code>repeatDur</code></td>
|
|
<td align="center"><code>end</code></td>
|
|
<td>Active Duration</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">defined</td>
|
|
<td align="center"> </td>
|
|
<td align="center"> </td>
|
|
<td align="center"> </td>
|
|
<td><strong>d</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">defined</td>
|
|
<td align="center">defined</td>
|
|
<td align="center"> </td>
|
|
<td align="center"> </td>
|
|
<td><code>repeatCount</code>*<strong>d</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">defined</td>
|
|
<td align="center"> </td>
|
|
<td align="center">defined</td>
|
|
<td align="center"> </td>
|
|
<td><code>repeatDur</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">defined</td>
|
|
<td align="center"> </td>
|
|
<td align="center"> </td>
|
|
<td align="center">defined</td>
|
|
<td>MIN( <strong>d</strong>, <code>end</code>-<strong>B </strong>)</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">defined</td>
|
|
<td align="center">defined</td>
|
|
<td align="center">defined</td>
|
|
<td align="center"> </td>
|
|
<td>MIN( <code>repeatCount</code>*<strong>d</strong>, <code>repeatDur
|
|
</code>)</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">defined</td>
|
|
<td align="center">defined</td>
|
|
<td align="center"> </td>
|
|
<td align="center">defined</td>
|
|
<td>MIN( <code>repeatCount</code>*<strong>d</strong>,
|
|
( <code>end</code>-<strong>B</strong> ))</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">defined</td>
|
|
<td align="center"> </td>
|
|
<td align="center">defined</td>
|
|
<td align="center">defined</td>
|
|
<td>MIN( <code>repeatDur</code>,
|
|
( <code>end</code>-<strong>B</strong> ))</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">defined</td>
|
|
<td align="center">defined</td>
|
|
<td align="center">defined</td>
|
|
<td align="center">defined</td>
|
|
<td>MIN( <code>repeatCount</code>*<strong>d</strong>,
|
|
<code>repeatDur</code>, ( <code>end</code>-<strong>B</strong> ))</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">indefinite</td>
|
|
<td align="center">*</td>
|
|
<td align="center"> </td>
|
|
<td align="center"> </td>
|
|
<td>indefinite</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">indefinite</td>
|
|
<td align="center">*</td>
|
|
<td align="center">defined</td>
|
|
<td align="center"> </td>
|
|
<td><code>repeatDur</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">indefinite</td>
|
|
<td align="center">*</td>
|
|
<td align="center"> </td>
|
|
<td align="center">defined</td>
|
|
<td><code>end</code>-<strong>B</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">indefinite</td>
|
|
<td align="center">*</td>
|
|
<td align="center">defined</td>
|
|
<td align="center">defined</td>
|
|
<td>MIN( <code>repeatDur</code>,
|
|
( <code>end</code>-<strong>B</strong> ))</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">*</td>
|
|
<td align="center">indefinite</td>
|
|
<td align="center"> </td>
|
|
<td align="center"> </td>
|
|
<td>indefinite</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">*</td>
|
|
<td align="center"> </td>
|
|
<td align="center">indefinite</td>
|
|
<td align="center"> </td>
|
|
<td>indefinite</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">*</td>
|
|
<td align="center">indefinite</td>
|
|
<td align="center">indefinite</td>
|
|
<td align="center"> </td>
|
|
<td>indefinite</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">*</td>
|
|
<td align="center">indefinite</td>
|
|
<td align="center"> </td>
|
|
<td align="center">defined</td>
|
|
<td><code>end</code>-<strong>B</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">*</td>
|
|
<td align="center"> </td>
|
|
<td align="center">indefinite</td>
|
|
<td align="center">defined</td>
|
|
<td><code>end</code>-<strong>B</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">*</td>
|
|
<td align="center">indefinite</td>
|
|
<td align="center">indefinite</td>
|
|
<td align="center">defined</td>
|
|
<td><code>end</code>-<strong>B</strong></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h5>Figure 4: Computing the active duration for different combinations of
|
|
simple duration, <code>repeatCount</code> and <code>repeatDur</code>, and
|
|
<code>end</code>.</h5>
|
|
|
|
<h4><a name="Fill"></a> 3.3.5. Freezing animations</h4>
|
|
|
|
<p>By default when an animation element ends, its effect is no longer applied
|
|
to the presentation value for the target attribute. For example, if an
|
|
animation moves an image and the animation element ends, the image will "jump
|
|
back" to its original position.</p>
|
|
<pre><img top="3" ...>
|
|
<animate begin="5s" dur="10s" attributeName="top" by="100"/>
|
|
</img></pre>
|
|
|
|
<p>The image will appear stationary at the top value of "3" for 5 seconds,
|
|
then move 100 pixels down in 10 seconds. 15 seconds after the document begin,
|
|
the animation ends, the effect is no longer applied, and the image jumps back
|
|
from 103 to 3 where it started (i.e., to the underlying value of the
|
|
<code>top</code> attribute).</p>
|
|
|
|
<p>The <code>fill</code> attribute can be used to maintain the value of the
|
|
animation after the active duration of the animation element ends:</p>
|
|
<pre><img top="3" ...>
|
|
<animate begin= "5s" dur="10s" attributeName="top" by="100"
|
|
<strong>fill="freeze"</strong> />
|
|
</img></pre>
|
|
|
|
<p>The animation ends 15 seconds after the document begin, but the image
|
|
remains at the top value of 103. The attribute <em>freezes</em> the last value
|
|
of the animation for the remainder of the document duration.</p>
|
|
|
|
<p>The freeze behavior of an animation is controlled using the "fill
|
|
"attribute:</p>
|
|
<dl>
|
|
<dt><a name="FillAttribute"></a><code>fill</code> <span class="argvalue">=
|
|
"<strong>freeze | remove</strong>"</span></dt>
|
|
<dd>This attribute can have the following values:
|
|
<dl>
|
|
<dt>freeze</dt>
|
|
<dd>The animation effect F(t) is defined to freeze the effect value
|
|
at the last value of the active duration. The animation effect is
|
|
"frozen" for the remainder of the document duration (or until the
|
|
animation is restarted - see <a href="#Restart">Restarting
|
|
animations</a>). </dd>
|
|
<dt>remove</dt>
|
|
<dd>The animation effect is removed (no longer applied) when the
|
|
active duration of the animation is over. After the active end of
|
|
the animation, the animation no longer affects the target (unless
|
|
the animation is restarted - see <a href="#Restart">Restarting
|
|
animations</a>).<br>
|
|
This is the default value.</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>If the active duration cuts short the simple duration (including the case
|
|
of partial repeats), the effect value of a <em> frozen</em> animation is
|
|
defined by the shortened simple duration. In the following example, the
|
|
animation function repeats two full times and then again for one-half of the
|
|
simple duration. In this case, the value while <em> frozen</em> will be
|
|
15: </p>
|
|
<pre><animate from="10" to="20" dur="4s"
|
|
<strong>repeatCount="2.5" fill="freeze"</strong> .../> </pre>
|
|
|
|
<p>In the following example, the <code>dur</code> attribute is missing, and so
|
|
the simple duration is indefinite. The active duration is constrained by
|
|
<code>end</code> to be 10 seconds. Since interpolation is not defined, the
|
|
value while <em> frozen</em> will be 10:</p>
|
|
<pre><animate from="10" to="20" end="10s" fill="freeze" .../> </pre>
|
|
|
|
<h5>Comparison to SMIL timing</h5>
|
|
|
|
<p>SMIL Animation specifies that <code>fill="freeze"</code> remains in effect
|
|
for the remainder of the document, or until the element is restarted. In the
|
|
more general SMIL timing model that allows time containers, the duration of
|
|
the freeze effect is controlled by the time container, and never extends past
|
|
the end of the time container simple duration. While this may appear to
|
|
conflict, the SMIL Animation definition of <code>fill="freeze"</code> is
|
|
consistent with the SMIL timing model. It is simply the case that in SMIL
|
|
Animation, the document is the only "time container", and so the effect is as
|
|
described above.</p>
|
|
|
|
<h4><a name="AdditiveAnim"></a> 3.3.6. Additive animation</h4>
|
|
|
|
<p>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:</p>
|
|
<pre><rect width="20px" ...>
|
|
<animate attributeName="width" from="0px" to="10px" dur="10s"
|
|
<strong>additive="sum"</strong>/>
|
|
</rect></pre>
|
|
|
|
<p>The width begins at 20 pixels, and increases to 30 pixels over the course
|
|
of 10 seconds. If the animation were declared to be non-additive, the same
|
|
from and to values would make the width go from 0 to 10 pixels over 10
|
|
seconds.</p>
|
|
|
|
<p>In addition, many complex animations are best expressed as combinations of
|
|
simpler animations. A "vibrating" path, for example, can be described as a
|
|
repeating up and down motion added to any other motion:</p>
|
|
<pre><img ...>
|
|
<animateMotion from="0,0" to="100,0" dur="10s" />
|
|
<animateMotion values="0,0; 0,5; 0,0" dur="1s"
|
|
repeatDur="10s" <strong>additive="sum"</strong>/>
|
|
</img></pre>
|
|
|
|
<p>When there are multiple animations defined for a given attribute that
|
|
overlap at any moment, the two either add together or one overrides the other.
|
|
Animations overlap when they are both either active or frozen at the same
|
|
moment. The ordering of animations (e.g. which animation overrides which) is
|
|
determined by a priority associated with each animation. The animations are
|
|
prioritized according to when each begins. The animation first begun has
|
|
lowest priority and the most recently begun animation has highest
|
|
priority.</p>
|
|
|
|
<p>Higher priority animations that are not additive will override all earlier
|
|
(lower priority) animations, and simply set the attribute value. Animations
|
|
that are additive apply (i.e. add to) to the result of the earlier-activated
|
|
animations. For details on how animations are combined, see <a
|
|
href="#AnimationSandwichModel">The animation sandwich model</a>.</p>
|
|
|
|
<p>The additive behavior of an animation is controlled by the
|
|
<code>additive</code> attribute:</p>
|
|
<dl>
|
|
<dt><a name="AdditiveAttribute"></a><code>additive</code> <span
|
|
class="argvalue">= "<strong>replace | sum</strong>"</span></dt>
|
|
<dd>Controls whether or not the animation is additive.
|
|
<dl>
|
|
<dt>sum</dt>
|
|
<dd>Specifies that the animation will add to the underlying value of
|
|
the attribute and other lower priority animations.</dd>
|
|
<dt>replace</dt>
|
|
<dd>Specifies that the animation will override the underlying value
|
|
of the attribute and other lower priority animations. This is the
|
|
default, however the behavior is also affected by the animation
|
|
value attributes <strong><code>by</code></strong> and
|
|
<strong><code>to</code></strong>, as described <a
|
|
href="#FromToByAndAdditive">below</a>.</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>Additive animation is defined for numeric attributes and other data types
|
|
for which some addition function is defined. This includes numeric attributes
|
|
for concepts such as position, widths and heights, sizes, etc. This also
|
|
includes color (refer to <a href="#animateColorElement">The animateColor
|
|
element</a>), and may include other data types as specified by the host
|
|
language.</p>
|
|
|
|
<p>It is often useful to combine additive animations and <code>fill</code>
|
|
behavior, for example when a series of motions are defined that should build
|
|
upon one another:</p>
|
|
<pre><img ...>
|
|
<animateMotion begin="0" dur="5s" path="<em>[some path]</em>"
|
|
additive="sum" fill="freeze" />
|
|
<animateMotion begin="5s" dur="5s" path="<em>[some path]</em>"
|
|
additive="sum" fill="freeze" />
|
|
<animateMotion begin="10s" dur="5s" path="<em>[some path]</em>"
|
|
additive="sum" fill="freeze" />
|
|
</img></pre>
|
|
|
|
<p>The image moves along the first path, and then starts the second path from
|
|
the end of the first, then follows the third path from the end of the second,
|
|
and stays at the final point.</p>
|
|
|
|
<p>While many animations of numerical attributes will be additive, this is not
|
|
always the case. As an example of an animation that is defined to be
|
|
non-additive, consider a hypothetical extension animation "mouseFollow" that
|
|
causes an object to track the mouse. </p>
|
|
<pre><img ...>
|
|
<animateMotion dur=10s repeatDur="indefinite"
|
|
path="[some nice path]" />
|
|
<mouseFollow begin="mouseover" dur="5s"
|
|
<strong>additive="replace"</strong> fill="remove" />
|
|
</img></pre>
|
|
|
|
<p>The mouse-tracking animation runs for 5 seconds every time the user mouses
|
|
over the image. It cannot be additive, or it will just offset the motion path
|
|
in some odd way. The <code>mouseFollow</code> needs to override the
|
|
<code>animateMotion</code> while it is active. When the
|
|
<code>mouseFollow</code> completes, its effect is no longer applied and the
|
|
<code>animateMotion</code> again controls the presentation value for
|
|
position.</p>
|
|
|
|
<p>In addition, some numeric attributes (e.g., a telephone number attribute)
|
|
may not sensibly support addition - it is left to the host language to specify
|
|
which attributes support additive animation. Attribute types such as strings
|
|
and Booleans for which addition is not defined, cannot support additive
|
|
animation.</p>
|
|
|
|
<h5><a name="FromToByAndAdditive"></a>How from, to and by attributes affect
|
|
additive behavior.</h5>
|
|
|
|
<p>The attribute values <code>to</code> and <code>by</code>, used to <a
|
|
href="#AnimFuncValues">describe the animation function</a>, can override the
|
|
<code>additive</code> attribute in certain cases:</p>
|
|
<ul>
|
|
<li>If <strong><code>by</code></strong> is used <em> without</em>
|
|
<code><strong>from</strong></code>, (<em>by animation</em>) the animation
|
|
is defined to be additive (i.e., the equivalent of
|
|
<code>additive="sum"</code>).</li>
|
|
<li>If <code><strong>to</strong></code> is used <em> without</em>
|
|
<code><strong>from</strong></code>, (<em>to animation</em>) and if the
|
|
attribute supports addition, the animation is defined to be a kind of mix
|
|
of additive and non-additive. The underlying value is used as a starting
|
|
point as with additive animation, however the ending value specified by
|
|
the <code><strong>to</strong></code> attribute overrides the underlying
|
|
value as though the animation was non-additive.</li>
|
|
</ul>
|
|
|
|
<p>For the hybrid case of a <em>to-animation</em>, the animation function
|
|
<code><strong>f(t)</strong></code> is defined in terms of the underlying
|
|
value, the specified <code>to</code> value, and the current value of
|
|
<code><strong>t</strong></code> (i.e. time) relative to the simple duration
|
|
<code><strong>d</strong></code>.</p>
|
|
<dl>
|
|
<dt><code>d</code></dt>
|
|
<dd>is the simple duration</dd>
|
|
<dt><code>t</code></dt>
|
|
<dd>is a time within the simple duration (0 <= t <= d)</dd>
|
|
<dt><code>v</code><sub>cur</sub></dt>
|
|
<dd>is the current base value (at time t)</dd>
|
|
<dt><code>v</code><sub>to</sub></dt>
|
|
<dd>is the defined "to" value</dd>
|
|
</dl>
|
|
|
|
<p><code>f(t) = </code><code>v</code><sub>cur</sub><code> +
|
|
((</code><code>v</code><sub>to</sub><code> - v</code><sub>cur</sub><code>) *
|
|
(t/d))</code></p>
|
|
|
|
<p>Note that if no other (lower priority) animations are active or frozen,
|
|
this defines simple interpolation. However if another animation is
|
|
manipulating the base value, the <em>to-animation</em> will add to the effect
|
|
of the lower priority, but will dominate it as it nears the end of the simple
|
|
duration, eventually overriding it completely. The value for
|
|
<code><strong>F(t)</strong></code> when a <em>to-animation</em> is frozen (at
|
|
the end of the simple duration) is just the <code>to</code> value. If a
|
|
<em>to-animation</em> is frozen anywhere within the simple duration (e.g.,
|
|
using a repeatCount of "2.5"), the value for
|
|
<code><strong>F(t)</strong></code> when the animation is frozen is the value
|
|
computed for the end of the active duration. Even if other, lower priority
|
|
animations are active while a <em>to-animation</em> is frozen, the value for
|
|
<code><strong>F(t)</strong></code> does not change.</p>
|
|
|
|
<p>Multiple <em>to-animations</em> will also combine according to these
|
|
semantics. The higher-priority animation will "win", and the end result will
|
|
be to set the attribute to the final value of the higher-priority
|
|
<em>to-animation</em>.</p>
|
|
|
|
<p>Multiple <em>by-animations</em> combine according to the general rules for
|
|
additive animation and the <a href="#AnimationSandwichModel"> animation
|
|
sandwich model</a>.</p>
|
|
|
|
<p>The use of <code>from</code> values does not imply either additive no
|
|
non-additive animation, and both are possible. The <code>from</code> value for
|
|
an additive animation is simply added to the underlying value, just as for the
|
|
initial value is in animations specified with a <code>values</code> list.
|
|
Additive behavior for <em>from-to</em> and <em>from-by</em> animations is
|
|
controlled by the <code>additive</code> attribute, as in the general case.</p>
|
|
|
|
<p>For an example of additive <em>to-animation</em>, consider the following
|
|
two additive animations. The first, a <em>by-animation</em> applies a delta to
|
|
attribute "x" from 0 to -10. The second, a <em>to-animation</em> animates to a
|
|
final value of 10.</p>
|
|
<pre> <foo x="0" .../>
|
|
<animate id="A1" attributeName="x"
|
|
<strong>by="-10"</strong> dur="10s" fill="freeze" />
|
|
<animate id="A2" attributeName="x" <strong></strong>
|
|
<strong> to="10"</strong> dur="10s" fill="freeze" />
|
|
</foo></pre>
|
|
|
|
<p>The presentation value for "x" in the example above, over the course of the
|
|
10 seconds is presented in Figure 5 below. These values are simply computed
|
|
using the formula described above. Note that the value for
|
|
<code><strong>F(t)</strong></code> for A2 is the presentation value for
|
|
"x".</p>
|
|
|
|
<p> </p>
|
|
|
|
<table border="1" cellpadding="4">
|
|
<tbody>
|
|
<tr>
|
|
<td height="30">Time</td>
|
|
<td height="30"><code><strong>F(t)</strong></code> for A1</td>
|
|
<td height="30"><code><strong>F(t)</strong></code> for A2</td>
|
|
</tr>
|
|
<tr>
|
|
<td height="30" align="center"> 0</td>
|
|
<td height="30" align="center">0</td>
|
|
<td height="30" align="center">0</td>
|
|
</tr>
|
|
<tr>
|
|
<td height="30" align="center"> 1</td>
|
|
<td height="30" align="center">-1</td>
|
|
<td height="30" align="center">0.1</td>
|
|
</tr>
|
|
<tr>
|
|
<td height="30" align="center"> 2</td>
|
|
<td height="30" align="center">-2</td>
|
|
<td height="30" align="center">0.4</td>
|
|
</tr>
|
|
<tr>
|
|
<td height="30" align="center"> 3</td>
|
|
<td height="30" align="center">-3</td>
|
|
<td height="30" align="center">0.9</td>
|
|
</tr>
|
|
<tr>
|
|
<td height="30" align="center"> 4</td>
|
|
<td height="30" align="center">-4</td>
|
|
<td height="30" align="center">1.6</td>
|
|
</tr>
|
|
<tr>
|
|
<td height="30" align="center"> 5</td>
|
|
<td height="30" align="center">-5</td>
|
|
<td height="30" align="center">2.5</td>
|
|
</tr>
|
|
<tr>
|
|
<td height="30" align="center"> 6</td>
|
|
<td height="30" align="center">-6</td>
|
|
<td height="30" align="center">3.6</td>
|
|
</tr>
|
|
<tr>
|
|
<td height="30" align="center"> 7</td>
|
|
<td height="30" align="center">-7</td>
|
|
<td height="30" align="center">4.9</td>
|
|
</tr>
|
|
<tr>
|
|
<td height="31" align="center"> 8</td>
|
|
<td height="31" align="center">-8</td>
|
|
<td height="31" align="center">6.4</td>
|
|
</tr>
|
|
<tr>
|
|
<td height="31" align="center"> 9</td>
|
|
<td height="31" align="center">-9</td>
|
|
<td height="31" align="center">8.1</td>
|
|
</tr>
|
|
<tr>
|
|
<td height="31" align="center">10</td>
|
|
<td height="31" align="center">-10</td>
|
|
<td height="31" align="center">10</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h5>Figure 5: Effect of Additive to-animation example</h5>
|
|
|
|
<h5>Additive and Cumulative animation</h5>
|
|
|
|
<p>The <code>accumulate</code> attribute should not be confused with the
|
|
<code>additive</code> attribute. The <code>additive</code> attribute defines
|
|
how an animation is combined with other animations and the base value of the
|
|
attribute. The <code>accumulate</code> attribute defines only how the
|
|
animation function interacts with itself, across repeat iterations.</p>
|
|
|
|
<p>Typically, authors expect cumulative animations to be additive (as in the
|
|
examples described for <code>accumulate</code> <a
|
|
href="#Accumulate">above</a>), but this is not required. The following example
|
|
is cumulative but not additive.</p>
|
|
<pre><img ...>
|
|
<animate dur="10s" repeatDur="indefinite"
|
|
attributeName="top" from="20" by="10"
|
|
<strong>additive="replace" accumulate="sum" </strong>/>
|
|
</img></pre>
|
|
|
|
<p>The animation overrides whatever original value was set for "top", and
|
|
begins at the value 20. It moves down by 10 pixels to 30, then repeats. It is
|
|
cumulative, so the second iteration starts at 30 and moves down by another 10
|
|
to 40. Etc.</p>
|
|
|
|
<p>When a cumulative animation is also defined to be additive, the two
|
|
features function normally. The accumulated effect for
|
|
<code><strong>F(t)</strong></code> is used as the value for the animation, and
|
|
is added to the underlying value for the target attribute. Refer also to <a
|
|
href="#AnimationSandwichModel">The animation sandwich model</a>.</p>
|
|
|
|
<h4><a name="Restart"></a> 3.3.7. Restarting animation</h4>
|
|
|
|
<p>When an animation is defined to begin at a simple offset (e.g.
|
|
<code>begin="5s"</code> ), there is an unequivocal time when the element
|
|
begins. However, if an animation is defined to begin relative to an event
|
|
(e.g. <code>begin="foo.click"</code> ), the event can happen at any time, and
|
|
moreover can happen <em>more than once</em> (e.g., if the user clicks on "foo"
|
|
several times). In some cases, it is desirable to <em>restart</em> an
|
|
animation if a second begin event is received. In other cases, an author may
|
|
want to preclude this behavior. The <code>restart</code> attribute controls
|
|
the circumstances under which an animation is restarted:</p>
|
|
<dl>
|
|
<dt><a name="RestartAttribute"></a><code>restart</code> <span
|
|
class="argvalue">= "<strong>always | whenNotActive |
|
|
never</strong>"</span></dt>
|
|
<dd><dl>
|
|
<dt>always</dt>
|
|
<dd>The animation can be restarted at any time. <br>
|
|
This is the default value.</dd>
|
|
<dt>whenNotActive</dt>
|
|
<dd>The animation can only be restarted when it is not active (i.e.,
|
|
it <em>can</em> be restarted after the active end). Attempts to
|
|
restart the animation during its active duration are ignored.</dd>
|
|
<dt>never</dt>
|
|
<dd>The animation cannot be restarted for the remainder of the
|
|
document duration.</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>Note that there are several ways that an animation may be restarted. The
|
|
behavior (i.e. to restart or not) in all cases is controlled by the
|
|
<code>restart</code> attribute. The different restart cases are:</p>
|
|
<ul>
|
|
<li>An animation with <code>begin</code> specified as an event-value can be
|
|
restarted when the named event fires multiple times.</li>
|
|
<li>An animation with <code>begin</code> specified as a syncbase value,
|
|
where the syncbase element can restart. When an animation restarts, other
|
|
animations defined to begin relative to the begin or active end of the
|
|
restarting animation may also restart (subject to the value of
|
|
<code>restart</code> on these elements).</li>
|
|
<li>An animation with <code>begin</code> specified as "indefinite" can be
|
|
restarted when the DOM methods <code>beginElement()</code> or
|
|
<code>beginElementAt()</code> are called repeatedly.</li>
|
|
</ul>
|
|
|
|
<p>When an animation restarts, the defining semantic is that it behaves as
|
|
though this were the first time the animation had begun, independent of any
|
|
earlier behavior. The animation effect <code><strong>F(t)</strong></code> is
|
|
defined independent of the restart behavior. Any effect of an animation
|
|
playing earlier is no longer applied, and only the current animation effect
|
|
<code><strong>F(t)</strong></code> is applied.</p>
|
|
|
|
<p>If an additive animation is restarted while it is active or frozen, the
|
|
previous effect of the animation (i.e. before the restart) is no longer
|
|
applied to the attribute. Note in particular that cumulative animation is
|
|
defined only within the active duration of an animation. When an animation
|
|
restarts, all accumulated context is discarded, and the animation effect
|
|
<code><strong>F(t)</strong></code> begins accumulating again from the first
|
|
iteration of the restarted active duration.</p>
|
|
|
|
<p>When an active element restarts, the element first ends the active duration,
|
|
propagates this to time dependents and raises an endEvent in the normal manner
|
|
(see also <a href="#Timing-EvaluationOfBeginEndTimeLists">Evaluation of begin
|
|
and end time lists</a>).</p>
|
|
|
|
<p><span class="normative">For details on when and how the </span><code>restart</code>
|
|
<span class="normative">attribute is evaluated, see </span><a href="#Timing-EvaluationOfBeginEndTimeLists">Evaluation
|
|
of begin and end time lists</a>. </p>
|
|
|
|
<p>Note that using restart can also allow the author to define a single UI
|
|
event to both begin and end an element, as follows:</p>
|
|
<pre><img ...>
|
|
<animate id="foo" begin="click" dur="2s"
|
|
repeatDur="indefinite" end="click"
|
|
<strong>restart="whenNotActive"</strong> ...<strong> </strong>/>
|
|
</img></pre>
|
|
|
|
<p>If "foo" were defined with the default restart behavior "always", a second
|
|
click on the image would simply restart the animation. However, since the
|
|
second click cannot restart the animation when restart is set to "whenNotActive", the click will just end the active duration and stop the
|
|
animation. This is sometimes described as "toggle" activation. See also <a href="#Timing-EventSensitivity">Event sensitivity</a>
|
|
and <a
|
|
href="#Unifying">Unifying event-based and scheduled timing</a>.</p>
|
|
|
|
<h5><a name="ResettingElementState"></a>Resetting element state</h5>
|
|
|
|
<p><em>This section is normative</em></p>
|
|
|
|
<p><span class="normative">When an element restarts, certain state is
|
|
"reset": </span></p>
|
|
<ul>
|
|
<li><span class="normative">Any instance times associated with</span>
|
|
past
|
|
event-values, repeat-values, accessKey-values or added via DOM method
|
|
calls are <span class="normative"> removed from the dependent begin and
|
|
end instance times lists. In effect, all events and DOM methods calls in the
|
|
past are
|
|
cleared. This does not apply to an instance time that defines the begin of
|
|
the current interval.</span></li>
|
|
</ul>
|
|
|
|
<h5>Comparison to SMIL timing</h5>
|
|
|
|
<p>SMIL Animation specifies that <code>restart="never"</code> precludes
|
|
restart for the remainder of the document duration. In the more general SMIL
|
|
2.0 [<a href="#ref-SMIL20">SMIL20</a>] timing model that allows
|
|
time containers, the duration of the <code>restart="never"</code> semantic is
|
|
defined by the time container, and only extends to the end of the time
|
|
container simple duration. While this may appear to conflict, the SMIL
|
|
Animation definition of <code>restart="never"</code> is consistent with the
|
|
SMIL timing model. It is simply the case that in SMIL Animation, the document
|
|
is the only "time container", and so the effect is as described above.</p>
|
|
|
|
<h3><a name="AnimationSyntaxErrors"></a> 3.4. Handling syntax errors</h3>
|
|
|
|
<p>The specific error handling mechanisms for each attribute are described
|
|
with the individual syntax descriptions. Some of these specifications
|
|
describe the behavior of an animation with syntax errors as "having no
|
|
effect". This means that the animation will continue to behave normally with
|
|
respect to timing, but will not manipulate any presentation value, and so will
|
|
have no visible impact upon the presentation. </p>
|
|
|
|
<p>In particular, this means that if other animation elements are defined to
|
|
begin or end relative to an animation that "has no effect", the other
|
|
animation elements will begin and end as though there were no syntax errors.
|
|
The presentation runtime may indicate an error, but need not halt presentation
|
|
or animation of the document. </p>
|
|
|
|
<p>Some host languages and/or runtimes may choose to impose stricter error
|
|
handling (see also <a href="#Integrating-ErrorHandling">Error handling
|
|
semantics</a> for a discussion of host language issues with error handling).
|
|
Authoring environments may also choose to be more intrusive when errors are
|
|
detected.</p>
|
|
|
|
<h3><a name="AnimationSandwichModel"></a> 3.5. The animation sandwich
|
|
model</h3>
|
|
|
|
<p>When an animation is running, it does not actually change the attribute
|
|
values in the DOM. The animation runtime should ideally maintain a <em>
|
|
presentation value</em> for any target attribute, separate from the DOM, CSS,
|
|
or other object model (OM) in which the target attribute is defined. The
|
|
presentation value is reflected in the display form of the document. The
|
|
effect of animations is to manipulate this presentation value, and not to
|
|
affect the underlying DOM or CSS OM values.</p>
|
|
|
|
<p>The remainder of this discussion uses the generic term OM for both the XML
|
|
DOM [<a href="#ref-DOM-Level-2">DOM-Level-2</a>] as well as the CSS-OM. If an
|
|
implementation does not support an object model, it should ideally maintain
|
|
the original value as defined by the document as well as the presentation
|
|
value; for the purposes of this section, we will consider this original value
|
|
to be equivalent to the value in the OM.</p>
|
|
|
|
<p>In some implementations of DOM, it may be difficult or impractical to main
|
|
a presentation value as described. CSS values should always be supported as
|
|
described, as the CSS-OM provides a mechanism to do so. In implementations
|
|
that do not support separate presentation values for general XML DOM
|
|
properties, the implementation must at least restore the original value when
|
|
animations no longer have an effect. </p>
|
|
|
|
<p>The rest of this discussion assumes the recommended approach using a
|
|
separate presentation value.</p>
|
|
|
|
<p>The model accounting for the OM and concurrently active or frozen
|
|
animations for a given attribute is described as a "sandwich", a loose analogy
|
|
to the layers of meat and cheeses in a "submarine sandwich" (a long sandwich
|
|
made with many pieces of meats and cheese layered along the length of the
|
|
bread). In the analogy, time is associated with the length of the sandwich,
|
|
and each animation has its duration represented by the length of bread that
|
|
the layer covers. On the bottom of the sandwich is the base value taken from
|
|
the OM. Each active (or frozen) animation is a layer above this. The layers
|
|
(i.e. the animations) are placed on the sandwich both in time along the length
|
|
of the bread, as well as in order according to <em>priority</em>, with higher
|
|
priority animations placed above (i.e. on top of) lower priority animations.
|
|
At any given point in time, you can take a slice of the sandwich and see how
|
|
the animation layers stack up.</p>
|
|
|
|
<p>Note that animations manipulate the presentation value coming out of the OM
|
|
in which the attribute is defined, and pass the resulting value on to the next
|
|
layer of document processing. This does not replace or override any of the
|
|
normal document OM processing cascade. </p>
|
|
|
|
<p>Specifically, animating an attribute defined in XML will modify the
|
|
presentation value before it is passed through the style sheet cascade, using
|
|
the XML DOM value as its base. Animating an attribute defined in a style sheet
|
|
language will modify the presentation value passed through the remainder of
|
|
the cascade. </p>
|
|
|
|
<p>In CSS2 and the DOM 2 CSS-OM, the terms "specified", "computed" and
|
|
"actual" are used to describe the results of evaluating the syntax, the
|
|
cascade and the presentation rendering. When animation is applied to CSS
|
|
properties of a particular element, the base value to be animated is read
|
|
using the (readonly) <code>getComputedStyle()</code> method on that element.
|
|
The values produced by the animation are written into an override stylesheet
|
|
for that element, which may be obtained using the
|
|
<code>getOverrideStyle()</code> method. These new values then affect the
|
|
cascade and are reflected in a new computed value (and thus, modified
|
|
presentation). This means that the effect of animation overrides all style
|
|
sheet rules, except for user rules with the <code>!important</code> property.
|
|
This enables <code>!important</code> user style settings to have priority over
|
|
animations, an important requirement for accessibility. Note that the
|
|
animation may have side effects upon the document layout. See also the [<a
|
|
href="#ref-CSS2">CSS2</a>] specification (the terms are defined in section
|
|
6.1), and the [<a href="#ref-DOM-CSS">DOM2CSS</a>] specification (section
|
|
5.2.1).</p>
|
|
|
|
<p>Within an OM, animations are prioritized according to when each begins. The
|
|
animation first begun has lowest priority and the most recently begun
|
|
animation has highest priority. When two animations start at the same moment
|
|
in time, the activation order is resolved as follows:</p>
|
|
<ul>
|
|
<li>If one animation is a <em>time dependent</em> of another (e.g., it is
|
|
specified to begin when another begins), then the time dependent is
|
|
considered to activate <em>after</em> the syncbase element, and so has
|
|
higher priority. Time dependency is further discussed in <a
|
|
href="#PropagatingTimes">Propagating changes to times</a>. This rule
|
|
applies independent of the timing described for the syncbase element -
|
|
i.e., it does not matter whether the syncbase element begins on an offset,
|
|
relative to another syncbase, relative to an event-base, or via
|
|
hyperlinking. In all cases, the syncbase is begun before any time
|
|
dependents are begun, and so the syncbase has lower priority than the time
|
|
dependent.</li>
|
|
<li>If two animations share no time dependency relationship (e.g., neither is
|
|
defined relative to the other, even indirectly) the element that appears
|
|
first in the document has lower priority. This includes the cases in which
|
|
two animation elements are defined relative to the same syncbase or
|
|
event-base. </li>
|
|
</ul>
|
|
|
|
<p>Note that if an animation is restarted (see also <a
|
|
href="#Restart">Restarting animations</a>), it will always move to the top of
|
|
the priority list, as it becomes the most recently activated animation. That
|
|
is, when an animation restarts, its layer is pulled out of the sandwich, and
|
|
added back on the very top. In contrast, when an element repeats the priority
|
|
is not affected (repeat behavior is not defined as restarting).</p>
|
|
|
|
<p>Each additive animation adds its effect to the result of all sandwich
|
|
layers below. A non-additive animation simply overrides the result of all
|
|
lower sandwich layers. The end result at the top of the sandwich is the
|
|
presentation value that must be reflected in the document view.</p>
|
|
|
|
<p>Some attributes that support additive animation have a defined legal range
|
|
for values (e.g., an opacity attribute may allow values between 0 and 1). In
|
|
some cases, an animation function may yield out of range values. It is
|
|
recommended that implementations clamp the results to the legal range as late
|
|
as possible, before applying them to the presentation value. Ideally, the
|
|
effect of all the animations active or frozen at a given point should be
|
|
combined, before any clamping is performed. Although individual animation
|
|
functions may yield out of range values, the combination of additive
|
|
animations may still be legal. Clamping only the final result and not the
|
|
effect of the individual animation functions provides support for these cases.
|
|
Intermediate results may be clamped when necessary although this is not
|
|
optimal. The host language must define the clamping semantics for each
|
|
attribute that can be animated. As an example, this is defined for <a
|
|
href="#animateColorElement">The animateColor element</a>. </p>
|
|
|
|
<p>Initially, before any animations for a given attribute are active, the
|
|
presentation value will be identical to the original value specified in the
|
|
document (the OM value).</p>
|
|
|
|
<p>When all animations for a given attribute have completed and the associated
|
|
animation effects are no longer applied, the presentation value will again be
|
|
equal to the OM value. Note that if any animation is defined with
|
|
<code>fill="freeze"</code>, the effect of the animation will be applied as
|
|
long as the document is displayed, and so the presentation value will reflect
|
|
the animation effect until the document end. Refer also to the section "<a
|
|
href="#Fill">Freezing animations</a>".</p>
|
|
|
|
<p>Some animations (e.g. <code>animateMotion</code>) will <em>implicitly
|
|
</em>target an attribute, or possibly several attributes (e.g. the "posX" and
|
|
"posY" attributes of some layout model). These animations must be combined
|
|
with any other animations for each attribute that is affected. Thus for example, an
|
|
<code>animateMotion</code> animation may be in more than one animation
|
|
sandwich (depending upon the layout model of the host language). For animation
|
|
elements that implicitly target attributes, the host language designer must
|
|
specify which attributes are implicitly targeted, and the runtime must
|
|
accordingly combine animations for the respective attributes. </p>
|
|
|
|
<p>Note that any queries (via DOM interfaces) on the target attribute will
|
|
reflect the OM value, and will not reflect the effect of animations. Note also
|
|
that the OM value may still be changed via the OM interfaces (e.g. using
|
|
script). While it may be useful or desired to provide access to the final
|
|
presentation value after all animation effects have been applied, such an
|
|
interface is not provided as part of SMIL Animation. A future version may
|
|
address this.</p>
|
|
|
|
<p>Although animation does not manipulate the OM values, the document display
|
|
must reflect changes to the OM values. Host languages can support script
|
|
languages that can manipulate attribute values directly in the OM. If an
|
|
animation is active or frozen while a change to the OM value is made, the
|
|
behavior is dependent upon whether the animation is defined to be additive or
|
|
not, as follows: (see also the section <a href="#AdditiveAnim">Additive
|
|
animation</a>). </p>
|
|
<ul>
|
|
<li>If only additive animations are active or frozen (i.e., no non-additive
|
|
animations are active or frozen for the given attribute) when the OM value
|
|
is changed, the presentation value must reflect the changed OM value as
|
|
well as the effect of the additive animations. When the animations
|
|
complete and the effect of each is no longer applied, the presentation
|
|
value will be equal to the changed OM value.<br>
|
|
</li>
|
|
<li>If any non-additive animation is running when the OM value is changed,
|
|
the presentation value will not reflect the changed OM value, but will
|
|
only reflect the effect of the highest priority non-additive animation,
|
|
and any still higher priority additive animations. When all non-additive
|
|
animations complete and the effect of each is no longer applied, the
|
|
presentation value will reflect the changed OM value and the effect of any
|
|
additive animations that are active or frozen.</li>
|
|
</ul>
|
|
|
|
<h3><a name="TimingModelDetails"></a> 3.6. Timing model details</h3>
|
|
|
|
<h4><a name="TimingAndRealWorldClockTime"></a> 3.6.1. Timing and real-world
|
|
clock times</h4>
|
|
|
|
<p>Throughout this specification, animation is described as a function of
|
|
"time". In particular, the animation function is described as producing a
|
|
value for any "time" in the range of the simple duration. However, the simple
|
|
duration can be repeated, and the animation can begin and restart in many
|
|
ways. As such, there is no direct relationship between the "time" that an
|
|
animation function uses, and the real world concept of time as reflected on a
|
|
clock.</p>
|
|
|
|
<p>When a <code>keySplines</code> attribute is used to adjust the pacing
|
|
between values in an animation, the semantics can be thought of as changing
|
|
the pace of time in the given interval. An equivalent model is that
|
|
<code>keySplines</code> simply changes the pace at which interpolation
|
|
<em>progresses </em>through the given interval. The two interpretations are
|
|
equivalent mathematically, and the significant point is that the notion of
|
|
"time" as defined for the animation function <code><strong>f(t)
|
|
</strong></code>should not be construed as real world clock time. For the
|
|
purposes of animation, "time" can behave quite differently from real world
|
|
clock time.</p>
|
|
|
|
<h4><a name="IntervalTiming"></a> 3.6.2. Interval timing</h4>
|
|
|
|
<p>SMIL Animation assumes the most common model for <em>interval timing</em>.
|
|
This describes intervals of time (i.e. durations) in which the begin time of
|
|
the interval is included in the interval, but the end time is excluded from
|
|
the interval. This is also referred to as <em>end-point exclusive</em> timing.
|
|
This model makes arithmetic for intervals work correctly, and provides
|
|
sensible models for sequences of intervals.</p>
|
|
|
|
<h5>Background rationale</h5>
|
|
|
|
<p>In the real world, this is equivalent to the way that seconds add up to
|
|
minutes, and minutes add up to hours. Although a minute is described as 60
|
|
seconds, a digital clock never shows more than 59 seconds. Adding one more
|
|
second to "00:59" does not yield "00:60" but rather "01:00", or 1 minute and 0
|
|
seconds. The theoretical end time of 60 seconds that describes a minute
|
|
interval is excluded from the actual interval.</p>
|
|
|
|
<p>In the world of media and timelines, the same applies: Let A be a video, a
|
|
clip of audio, or an animation. Assume "A" begins at 10 and runs until 15 (in
|
|
any units - it does not matter). If "B" is defined to follow "A", then it
|
|
begins at 15 (and not at 15 plus some minimum interval). When an animation
|
|
runtime engine actually renders out frames (or samples for audio), and must
|
|
render the time "15", it should not show both a frame of "A" and a frame of
|
|
"B", but rather should only show the new element "B". This is the same for
|
|
audio, or for any interval on a timeline. If the model does not use
|
|
endpoint-exclusive timing, it will draw overlapping frames, or have
|
|
overlapping samples of audio, of sequenced animations, etc.</p>
|
|
|
|
<p>Note that transitions from "A" to "B" also adhere to the interval timing
|
|
model. They <em>do</em> require that "A" not actually end at 15, and that both
|
|
elements actually overlap. Nevertheless, the "A" duration is simply extended
|
|
by the transition duration (e.g. 1 second). This new duration for "A" is
|
|
<em>also</em> endpoint exclusive - at the end of this new duration, the
|
|
transition will be complete, and only "B" should be rendered - "A" is no
|
|
longer needed.</p>
|
|
|
|
<h5>Implications for animation</h5>
|
|
|
|
<p>For animation, several results of this are important: the definition of
|
|
repeat, and the value sampled during the "frozen" state.</p>
|
|
|
|
<p>When repeating an animation, the arithmetic follows the end-point exclusive
|
|
model. Consider the example:</p>
|
|
|
|
<p><code> <animation dur="4s" repeatCount="4" .../></code></p>
|
|
|
|
<p>At time 0, the simple duration is sampled at 0, and the first value is
|
|
applied. This is the <em>inclusive</em> begin of the interval. The simple
|
|
duration is sampled normally up to 4 seconds. However, the appropriate way to
|
|
map time on the active duration to time on the simple duration is to use the
|
|
remainder of division by the simple duration:</p>
|
|
|
|
<p><code> simpleTime = REMAINDER( activeTime, <strong>d
|
|
) </strong></code></p>
|
|
|
|
<p>or</p>
|
|
|
|
<p><code> <strong>F(t)</strong> = <strong>f( REMAINDER( t, d ) )</strong>
|
|
</code>where t is within the active duration</p>
|
|
|
|
<p>Note:<code> REMAINDER( t, d )</code> is defined as <code>t -
|
|
d*floor(t/d)</code></p>
|
|
|
|
<p>Using this, a time of <strong>4</strong> (or 8 or 12) maps to the time of
|
|
<strong>0</strong> on the simple duration. The endpoint of the simple duration
|
|
is <em>excluded</em> from (i.e. not actually sampled on) the simple
|
|
duration.</p>
|
|
|
|
<p>This implies that the last value of an animation function
|
|
<code><strong>f(t)</strong></code> may never actually be applied (e.g. for a
|
|
linear interpolation). This may be true in the case of an animation that does
|
|
not repeat and does not specify <code><strong>fill="freeze"</strong></code>.
|
|
However, in the following example, the appropriate value for the frozen state
|
|
is clearly the "to" value:</p>
|
|
|
|
<p><code> <animation from="0" to="5" dur="4s" fill=freeze
|
|
.../></code></p>
|
|
|
|
<p>This does not break the interval timing model, but does require an
|
|
additional qualification for the animation function
|
|
<code><strong>F(t)</strong></code> while in the frozen state:</p>
|
|
<ul>
|
|
<li>If the active duration is an even multiple of the simple duration, the
|
|
value to apply in the frozen state is the last value defined for the
|
|
animation function <code><strong>f(t)</strong></code>.</li>
|
|
</ul>
|
|
|
|
<p>The <a href="#Accumulate">definition of accumulate</a> also aligns to this
|
|
model. The arithmetic is effectively inverted and values accumulate by adding
|
|
in a <em>multiple </em>of the last value defined for the animation function
|
|
<code><strong>f(t)</strong></code>.</p>
|
|
|
|
<h4><a name="Unifying"></a> 3.6.3. Unifying interactive and scheduled
|
|
timing</h4>
|
|
|
|
<p>SMIL Animation describes extensions to SMIL 1.0 to support interactive
|
|
timing of animation elements. These extensions allow the author to specify
|
|
that an animation should begin or end in response to an event (such as a
|
|
user-input event like "click"), or to a hyperlink activation, or to a DOM
|
|
method call.</p>
|
|
|
|
<p>The syntax to describe this uses <a
|
|
href="#Timing-EventValueSyntax">event-value</a> specifications and the special
|
|
argument value "indefinite" for the <code>begin</code> and <code>end</code>
|
|
attribute values. Event values describe user interface and other events. DOM
|
|
method calls to begin or end an animation require that the associated
|
|
attribute use the special value "indefinite". A hyperlink can also be targeted
|
|
at an animation element that specifies <code>begin="indefinite"</code>. The
|
|
animation will begin when the hyperlink is activated (usually by the user
|
|
clicking on the anchor). It is not possible to directly control the active end
|
|
of an animation using hyperlinks.</p>
|
|
|
|
<h5>Background</h5>
|
|
|
|
<p>The current model represents an evolution from earlier multimedia runtimes.
|
|
These were typically either pure, static schedulers or pure event-based
|
|
systems. Scheduler models present a linear timeline that integrates both
|
|
discrete and continuous media. Scheduler models tend to be good for
|
|
storytelling, but have limited support for user-interaction. Event-based
|
|
systems, on the other hand, model multimedia as a graph of event bindings.
|
|
Event-based systems provide flexible support for user-interaction, but
|
|
generally have poor scheduling facilities; they are best applied to highly
|
|
interactive and experiential multimedia.</p>
|
|
|
|
<p>The SMIL 1.0 model is primarily a scheduling model, but with some
|
|
flexibility to support continuous media with unknown duration. User
|
|
interaction is supported in the form of timed hyperlinking semantics, but
|
|
there was no support for activating individual elements via interaction.</p>
|
|
|
|
<h5>Modeling interactive, event-based content in SMIL</h5>
|
|
|
|
<p>To integrate interactive content into SMIL timing, the SMIL 1.0 scheduler
|
|
model is extended to support several new concepts: <em>indeterminate
|
|
timing,</em> and <em>activation</em> of the element.</p>
|
|
|
|
<p>With <em>indeterminate timing</em>, an element has an undefined begin or
|
|
end time. The element still exists within the constraints of the document,
|
|
but the begin or end time is determined by some external <em>activation</em>.
|
|
Activation may be event-based (such as by a user-input event), hyperlink based
|
|
(with a hyperlink targeted at the element), or DOM based (e.g., by a call to
|
|
the <code>beginElement()</code> method). From a scheduling perspective, the
|
|
time is described as <em>unresolved</em> before the activation. Once the
|
|
element begin or end has been activated, the time is <em>resolved</em>.</p>
|
|
|
|
<p>The event-activation support provides a means of associating an event with
|
|
the begin or active end time for an element. When the event is raised (e.g.,
|
|
when the user clicks on something), the associated time is resolved to a
|
|
<em>determinate</em> time. For event-based begin times, the element becomes
|
|
active (begins to play) at the time that the event is raised (plus any
|
|
specified offset). The element plays from the beginning of the animation
|
|
function. For event-based active end times, the element becomes inactive
|
|
(stops playing) when the associated event is raised.</p>
|
|
|
|
<p>Note that an event based <code>end</code> will not be activated until the
|
|
element has already begun. Any specified <code>end</code> event is ignored
|
|
before the element begins. See also <a href="#Timing-EventSensitivity">Event sensitivity</a>.</p>
|
|
|
|
<p>Note that when an element restarts, any event-based end time that was
|
|
resolved in the previous instance of play, will be reset to the unresolved
|
|
state.</p>
|
|
|
|
<p>Related to event-activation is <em>link-activation</em>. Hyperlinking has
|
|
defined semantics in SMIL 1.0 to <em> seek</em> a document to a point in time.
|
|
When combined with indeterminate timing, hyperlinking yields a variant on
|
|
interactive content. A hyperlink can be targeted at an element that does not
|
|
have a scheduled begin time. When the link is traversed, the element begins.
|
|
The details of when hyperlinks activate an element, and when they seek the
|
|
document timeline are presented in the next section. </p>
|
|
|
|
<p>Note that hyperlink activation only applies to an element begin time, and
|
|
not to the element end. Event and DOM based activation can apply to both begin
|
|
and end times.</p>
|
|
|
|
<p>Note that elements can define the <code>begin</code> or <code>end</code>
|
|
relative to another element, using a <a
|
|
href="#Timing-SyncbaseValueSyntax">syncbase-value</a> (the begin or end of another
|
|
element). If the syncbase element is in turn defined with, for example,
|
|
event-based times, the syncbase value is not resolved, and so the
|
|
<code>begin</code> or <code>end</code> of the current element is also
|
|
unresolved. For a <code>begin</code> or <code>end</code> time to be resolved,
|
|
any referenced syncbase value must also be resolved.</p>
|
|
|
|
<h4><a name="Timing-EventSensitivity"></a> 3.6.4. Event sensitivity</h4>
|
|
<p><em><span class="informative">This section is informative</span></em></p>
|
|
<p class="informative">The timing model supports synchronization based upon
|
|
unpredictable events such as DOM events or user interface generated events. The
|
|
model for handling events is that the notification of the event is delivered to
|
|
the timing element, and the timing element uses a set of rules to resolve any
|
|
synchronization dependent upon the event.</p>
|
|
<p><em>This section is normative</em></p>
|
|
<p><span class="normative">The semantics of element sensitivity to events are
|
|
described by the following set of rules:</span></p>
|
|
<ol>
|
|
<li><span class="normative">If an element is not active, then events are only
|
|
handled for begin specifications. Thus if an event is raised and <span class="ainst-begin ainst">begin</span>
|
|
specifies the event, the element begins. While the element is not active,
|
|
any <span class="ainst-end ainst">end</span> specification of the event is
|
|
ignored.</span>
|
|
<li><span class="normative">If an element is (already) active when an event is
|
|
raised, and <span class="ainst-begin ainst">begin</span> specifies the
|
|
event, then the behavior depends upon the value of restart:</span>
|
|
<ol>
|
|
<li type="a"><span class="normative">If <span class="ainst-restart
|
|
ainst">restart</span>=<span class="avalue">"always"</span>,
|
|
then a new begin time is resolved for the element based on the event
|
|
time. Any specification of the event in <span class="ainst-end ainst">end</span>
|
|
is ignored for this event instance.</span>
|
|
<li><span class="normative">If <span class="ainst-restart
|
|
ainst">restart</span>=<span class="avalue">"never"</span> or <span class="ainst-restart ainst">restart</span>=<span class="avalue">"whenNotActive"</span>,
|
|
then any <span class="ainst-begin ainst">begin</span> specification of
|
|
the event is ignored for this instance of the event. If <span class="ainst-end
|
|
ainst">end</span> specifies the event, an end value is resolved based
|
|
upon the event time, and the active duration is re-evaluated (according
|
|
to the rules in <a href="#ComputingActiveDur">Computing the
|
|
active duration</a>).</span></li>
|
|
</ol>
|
|
</li>
|
|
</ol>
|
|
<p class="normative">It is important to notice that in no case is a single event
|
|
occurrence used to resolve both a begin and end time on the same element.</p>
|
|
<h5>User event sensitivity and timing</h5>
|
|
<p><span class="normative">The timing model and the user event model are largely
|
|
orthogonal. While the timing model does reference user events, it does not
|
|
define how these events are generated, and in particular does not define
|
|
semantics of keyboard focus, mouse containment, "clickability", and
|
|
related issues. Because timing can affect the presentation of elements, it may
|
|
impact the rules for user event processing, however it only has an effect to the
|
|
extent that the presentation of the element is affected.</span></p>
|
|
|
|
<h4><a name="HyperlinkSemantics"></a> 3.6.5. Hyperlinks and timing</h4>
|
|
|
|
<p>Hyperlinking semantics must be specifically defined for animation in order
|
|
to ensure predictable behavior. Earlier hyperlinking semantics, such as those
|
|
defined by SMIL 1.0 are insufficient because they do not handle indeterminate
|
|
and interactive timing. Here we extend SMIL 1.0 semantics for use in
|
|
presentations that include animations with indeterminate and interactive
|
|
timing.</p>
|
|
|
|
<p>Hyperlinking behavior is described as <em>seeking</em> the document. To
|
|
<em>seek</em> in this sense means to advance the document timeline to the
|
|
specified time. </p>
|
|
|
|
<p>A hyperlink may be targeted at an animation element by specifying the value
|
|
of the <code>id</code> attribute of an animation element in the fragment part
|
|
of the link locator. Traversing a hyperlink that refers to an animation will
|
|
behave according to the following rules:</p>
|
|
<ol>
|
|
<li><span class="normative">If the target element is active, seek the
|
|
document time back to the (current) begin time of the element. If there
|
|
are multiple begin times, use the begin time that corresponds to the
|
|
current "begin instance".</span></li>
|
|
<li><span class="normative">Else if the target element begin time is
|
|
resolved (i.e., there is any resolved time in the list of begin times, or
|
|
if the begin time was forced by an earlier hyperlink or a
|
|
<code>beginElement()</code> method call), seek the document time (forward
|
|
or back, as needed) to the earliest resolved begin time of the target
|
|
element. <span class="informative">Note that the begin time may be
|
|
resolved as a result of an earlier hyperlink, DOM or event activation.
|
|
</span>Once the begin time is resolved, hyperlink traversal always seeks.</span></li>
|
|
<li>Else (animation begin time is unresolved) just resolve the target
|
|
animation begin time at current document time. Disregard the sync-base or
|
|
event base of the animation, and do not "back-propagate" any timing logic
|
|
to resolve the child, but rather treat it as though it were defined with
|
|
<code> begin="indefinite"</code> and just resolve begin time to the
|
|
current document time.</li>
|
|
</ol>
|
|
|
|
<p>Note that hyperlink activation does not introduce any restart behavior, and
|
|
is not subject to the <code>restart</code> attribute semantics.</p>
|
|
|
|
<p>If a seek of the document presentation time is required, it may be
|
|
necessary to seek either forward or backward, depending upon the resolved
|
|
begin time of the element and the current time at the moment of hyperlink
|
|
traversal. </p>
|
|
|
|
<p>After seeking a document forward, the document should be in the same state
|
|
as if the user had allowed the presentation to run normally from the current
|
|
time until reaching the animation element begin time (but had otherwise not
|
|
interacted with the document). In particular, seeking the presentation time
|
|
forward should also cause any other animation elements that have resolved
|
|
begin times between the current time and the seeked-to time to begin. These
|
|
elements may have ended, or may still be active or frozen at the seeked-to
|
|
time, depending upon their begin times and active durations. Also any
|
|
animation elements currently active at the time of hyperlinking should
|
|
"fast-forward" over the seek interval. These may end or may be still active or
|
|
frozen at the seeked-to time, depending upon their active durations. The net
|
|
effect is that seeking forward to a presentation time puts the document into a
|
|
state identical to that as if the document presentation time advanced
|
|
undisturbed to reach the seek time.</p>
|
|
|
|
<p>If the resolved begin time for an animation element that is the target of a
|
|
hyperlink is before the current presentation time, the presentation must seek
|
|
backwards. Seeking backwards will rewind any animations active during the seek
|
|
interval and will turn off any animations that are resolved to begin at a time
|
|
after the seeked-to time. Note that resolved begin times (e.g. a begin
|
|
associated with an event) are not cleared or lost by seeking to an earlier
|
|
time. Subject to the rules above for hyperlinks that target animation
|
|
elements, hyperlinking to elements with resolved begin times will function
|
|
normally, advancing the presentation time forward to the previously resolved
|
|
time.</p>
|
|
|
|
<p>These hyperlinking semantics assume that a record is kept of the resolved
|
|
begin time for all animation elements, and this record is available to be used
|
|
for determining the correct presentation time to seek to. Once resolved, begin
|
|
times are not cleared. However, they can be overwritten by subsequent
|
|
resolutions driven by multiple occurrences of an event (i.e. by restarting).
|
|
For example: </p>
|
|
<pre><animate id="A" begin="10s" .../>
|
|
<animate id="B" begin="A.begin+5s" .../>
|
|
<animate id="C" begin="click" .../>
|
|
<animate id="D" begin="C.begin+5s" .../>
|
|
...
|
|
<a href="#D">Start the last animation</a></pre>
|
|
|
|
<p>The begin time of elements "A" and "B" can be immediately resolved to be at
|
|
10 and 15 seconds respectively. The begin of elements "C" and "D" are
|
|
unresolved when the document starts. Therefore activating the hyperlink will
|
|
have no effect upon the presentation time or upon elements "C" and "D". Now,
|
|
assume that "C" is clicked at 25 seconds into the presentation. The click on
|
|
"C" in turn resolves "D" to begin at 30 seconds. From this point on,
|
|
traversing the hyperlink will cause the presentation time to be seeked to 30
|
|
seconds.</p>
|
|
|
|
<p>If at 60 seconds into the presentation, the user again clicks on "C", "D"
|
|
will become re-resolved to a presentation time of 65 seconds. Subsequent
|
|
activation of the hyperlink will result in the seeking the presentation to 65
|
|
seconds.</p>
|
|
|
|
<h4><a name="PropagatingTimes"></a> 3.6.6. Propagating changes to times</h4>
|
|
|
|
<p>There are several cases in which times may change as the document is
|
|
presented. In particular, when an animation time is defined relative to an
|
|
event, the time (i.e. the animation begin or active end) is resolved when the
|
|
event occurs. Another case arises with restart behavior - both the begin and
|
|
active end time of an animation can change when it restarts. Since the begin
|
|
and active end times of one animation can be defined relative to the begin or
|
|
active end of other animations, any changes to times must be propagated
|
|
throughout the document.</p>
|
|
|
|
<p>When an animation "foo" has a begin or active end time that specifies a
|
|
syncbase element (e.g. "bar" as below):</p>
|
|
<pre><rect ...>
|
|
<animate id="bar" end="click" .../>
|
|
<animate id="foo" begin="bar.end" .../>
|
|
</rect></pre>
|
|
|
|
<p>we say that "foo" is a <em>time-dependent</em> of "bar" - that is, the
|
|
"foo" begin time depends upon the active end of "bar". </p>
|
|
|
|
<p>An element <em><strong>A</strong></em> is a time dependent of another
|
|
element <em><strong>B</strong></em> if <em><strong>A</strong></em> specifies
|
|
<em><strong>B</strong></em> as a syncbase element. In addition, if element
|
|
<em><strong>A</strong></em> is a time dependent of element
|
|
<em><strong>B</strong></em>, and if element <em><strong>B</strong></em> is a
|
|
time dependent of element <em><strong>C</strong></em> (i.e., element
|
|
<em><strong>B</strong></em> defines element <em><strong>C</strong></em> as a
|
|
syncbase element), then element <em><strong>A</strong></em> is an
|
|
<em>indirect</em> time dependent of element <em><strong>C</strong></em>.</p>
|
|
|
|
<p>When an element begins or ends, the time dependents of the element are
|
|
effectively notified of the action, and the schedule for the time dependents
|
|
may be affected. Note than an element must actually begin before any of the
|
|
time dependents (dependent on the begin) are affected, and that an element
|
|
must actually end before any of the time dependents (dependent on the end) are
|
|
affected. This impacts the definition of the priority ordering of animation
|
|
elements, as discussed in <a href="#AnimationSandwichModel">The animation
|
|
sandwich model</a>.</p>
|
|
|
|
<p>In the example above, any changes to the active end time of "bar" must be
|
|
propagated to the begin of "foo". The effect of the changes depends upon the
|
|
state of "foo" when the change happens, as detailed below.</p>
|
|
|
|
<p>If the <em>begin</em> time of an element is dependent upon another element
|
|
(as for "foo" in the example), the resulting behavior when the syncbase
|
|
element ("bar") propagates changes is determined as follows:</p>
|
|
<ul>
|
|
<li>If the time dependent ("foo") has not yet begun, then the begin time is
|
|
simply updated in the schedule. </li>
|
|
<li>If the time dependent ("foo") is currently active, then the
|
|
<code>restart</code> attribute determines the behavior: if it is "always",
|
|
then the time dependent will restart; otherwise the propagated change is
|
|
ignored.</li>
|
|
<li>If the time dependent ("foo") has already begun (at least once) but is
|
|
not currently active, then the <code>restart</code> attribute determines
|
|
the behavior: if it is "always" or "whenNotActive", then the time
|
|
dependent will restart; otherwise the propagated change is ignored.</li>
|
|
</ul>
|
|
|
|
<p>Note that the semantic is directly analogous to event-base timing and the
|
|
<code>restart</code> attribute.</p>
|
|
|
|
<p>If the <em>end</em> time of an element is dependent upon another element,
|
|
the semantic is much simpler:</p>
|
|
<ul>
|
|
<li>If the time dependent has not yet begun or is currently active, then the
|
|
end time is simply updated in the schedule, and the active duration is
|
|
recalculated (according to the table in <a
|
|
href="#ComputingActiveDur">Computing the active duration</a>).</li>
|
|
<li>If the time dependent has already ended the active duration, <font
|
|
color="#000000">then the change is ignored</font>. Even if the recomputed
|
|
active duration would extend past the current time, the element does not
|
|
"restart" and "re-end".</li>
|
|
</ul>
|
|
|
|
<p>Another way to think of this is that the end time is always recalculated,
|
|
but it will not affect the presentation unless the element is currently
|
|
active, or unless the element begins (or restarts) after the change
|
|
happens.</p>
|
|
|
|
<h4><a name="TimingAttrValGrammars"></a> 3.6.7. Timing attribute value grammars</h4>
|
|
<p><span class="normative"><em><span class="informative">This section is </span>normative</em></span></p>
|
|
<p>The syntax specifications are defined using EBNF notation as defined in [<span class="normative"><a href="#ref-XML10">XML10</a></span>]</p>
|
|
<p><span class="normative">In the syntax specifications that follow, allowed
|
|
white space is indicated as "S", defined as follows (taken from the [<a href="#ref-XML10">XML10</a>] definition for "S"):</span></p>
|
|
<pre><span class="normative"><a name="Timing-WhiteSpaceBNF"></a>S ::= (#x20 | #x9 | #xD | #xA)*</span></pre>
|
|
<h5><span class="normative"><a name="Timing-BeginValueListSyntax"></a>Begin
|
|
values</span></h5>
|
|
<p><span class="normative"><em><span class="informative">This section is </span>normative</em></span></p>
|
|
<p><span class="normative">A begin-value-list is a semi-colon separated list of
|
|
timing specifiers:</span></p>
|
|
<pre><span class="normative">begin-value-list ::= begin-value (<code><a href="#Timing-WhiteSpaceBNF">S</a> </code>";" <code><a href="#Timing-WhiteSpaceBNF">S</a> </code>begin-value-list )?</span>
|
|
<span class="normative">begin-value ::= (offset-value | syncbase-value </span>
|
|
<span class="normative"> | event-value</span>
|
|
<span class="normative"> | repeat-value | accessKey-value</span>
|
|
<span class="normative"> | wallclock-sync-value | "indefinite" )</span></pre>
|
|
<h5><span class="normative"><a name="Timing-EndValueListSyntax"></a>End values</span></h5>
|
|
<p><span class="normative"><em><span class="informative">This section is </span>normative</em></span></p>
|
|
<p><span class="normative">An end-value-list is a semi-colon separated list of
|
|
timing specifiers:</span></p>
|
|
<pre><span class="normative">end-value-list ::= end-value (<code><a href="#Timing-WhiteSpaceBNF">S</a> </code>";" <code><a href="#Timing-WhiteSpaceBNF">S</a> </code>end-value-list )?</span>
|
|
<span class="normative">end-value ::= (offset-value | syncbase-value </span>
|
|
<span class="normative"> | event-value</span>
|
|
<span class="normative"> | repeat-value | accessKey-value</span>
|
|
<span class="normative"> | wallclock-sync-value | "indefinite" )</span></pre>
|
|
<h5><a name="Timing-ParsingTimeSpecifiers"></a>Parsing timing specifiers</h5>
|
|
<p><span class="informative">Several of the timing specification values have a
|
|
similar syntax. In addition, XML ID attributes are allowed to contain the dot '<code>.</code>'
|
|
separator character. </span><span class="normative">The backslash character '\'
|
|
can be used to escape the dot separator within identifier and event-name
|
|
references. To parse an individual item in a value-list, the following approach
|
|
defines the correct interpretation. </span></p>
|
|
<ol>
|
|
<li><span class="normative">Strip any leading, trailing, or intervening white space characters.</span>
|
|
<li><span class="normative">If the value begins with a number or numeric sign
|
|
indicator (i.e. <code>'+'</code> or <code>'-'</code>), the value should be
|
|
parsed as an <a href="#Timing-OffsetValueSyntax">offset value</a>.</span>
|
|
<li><span class="normative">Else if the value begins with the token "wallclock",
|
|
it should be parsed as a <a href="#Timing-WallclockSyncValueSyntax">wallclock-sync-value</a>.</span>
|
|
<li><span class="normative">Else if the value is the token
|
|
"indefinite", it should be parsed as the value
|
|
"indefinite".</span>
|
|
<li><span class="normative">Else: Build a token substring up to but not
|
|
including any sign indicator (i.e. strip off any offset). In the following,
|
|
ignore any '<code>.</code>' separator characters preceded by a backslash '<code>\</code>'
|
|
escape character. In addition, strip any leading backslash '<code>\</code>'
|
|
escape character. </span>
|
|
<ol>
|
|
<li><span class="normative">If the token contains no '<code>.</code>'
|
|
separator character, then the value should be parsed as an <a href="#Timing-EventValueSyntax">event-value</a>
|
|
with an unspecified (i.e. default) eventbase-element.</span>
|
|
<li><span class="normative">Else if the token ends with the string "<code>.begin</code>"
|
|
or "<code>.end</code>", then the value should be parsed as a <a href="#Timing-SyncbaseValueSyntax">syncbase-value</a>.</span>
|
|
<li><span class="normative">Else, the value should be parsed as an <a href="#Timing-EventValueSyntax">event-value</a>
|
|
(with a specified eventbase-element). Before parsing the event value,
|
|
any backslash '<code>\</code>' escape character after the '<code>.</code>'
|
|
separator character should be removed.</span></li>
|
|
</ol>
|
|
</li>
|
|
</ol>
|
|
<p class="informative">This approach allows implementations to treat the tokens <span class="avalue">wallclock</span> and <code><strong>indefinite</strong></code>
|
|
as reserved element IDs, and <span class="avalue">begin</span>, <span class="avalue">end</span>
|
|
and <span class="avalue">marker</span> as reserved event names, while retaining
|
|
an escape mechanism so that elements and events with those names may be
|
|
referenced.</p>
|
|
<h5><a name="Timing-ClockValueSyntax"></a>Clock values</h5>
|
|
<p><span class="normative">Clock values have the following syntax:</span></p>
|
|
<pre><span class="normative">Clock-value ::= ( Full-clock-value | Partial-clock-value
|
|
| Timecount-value )</span>
|
|
<span class="normative">Full-clock-value ::= Hours ":" Minutes ":" Seconds ("." Fraction)?</span>
|
|
<span class="normative">Partial-clock-value ::= Minutes ":" Seconds ("." Fraction)?</span>
|
|
<span class="normative">Timecount-value ::= Timecount ("." Fraction)? (Metric)?</span>
|
|
<span class="normative">Metric ::= "h" | "min" | "s" | "ms"</span>
|
|
<span class="normative">Hours ::= DIGIT+; any positive number</span>
|
|
<span class="normative">Minutes ::= 2DIGIT; range from 00 to 59</span>
|
|
<span class="normative">Seconds ::= 2DIGIT; range from 00 to 59</span>
|
|
<span class="normative">Fraction ::= DIGIT+</span>
|
|
<span class="normative">Timecount ::= DIGIT+</span>
|
|
<span class="normative">2DIGIT ::= DIGIT DIGIT</span>
|
|
<span class="normative">DIGIT ::= [0-9]</span></pre>
|
|
<p><span class="normative">For Timecount values, the default metric suffix is
|
|
"s" (for seconds).</span> <span class="informative">No embedded white
|
|
space is allowed in clock values, although leading and trailing white space
|
|
characters will be ignored.</span></p>
|
|
<p><span class="informative">The following are examples of legal clock values:</span></p>
|
|
<ul>
|
|
<li><span class="informative">Full clock values: <code><br>
|
|
02:30:03 </code>= 2 hours, 30 minutes and 3 seconds<br>
|
|
<code> 50:00:10.25 </code>= 50 hours, 10 seconds and 250 milliseconds</span>
|
|
<li><span class="informative">Partial clock value: <code><br>
|
|
02:33 </code>= 2 minutes and 33 seconds<br>
|
|
<code> 00:10.5 </code>= 10.5 seconds = 10 seconds and 500 milliseconds</span>
|
|
<li><span class="informative">Timecount values:<br>
|
|
<code> 3.2h </code>= 3.2 hours = 3 hours and 12
|
|
minutes<br>
|
|
<code> 45min </code>= 45 minutes<br>
|
|
<code> 30s </code>= 30 seconds<br>
|
|
<code> 5ms </code>= 5 milliseconds<br>
|
|
<code> 12.467 </code>= 12 seconds and 467 milliseconds</span></li>
|
|
</ul>
|
|
<p><span class="normative">Fractional values are just (base 10) floating point
|
|
definitions of seconds. The number of digits allowed is unlimited (although
|
|
actual precision may vary among implementations). </span><br>
|
|
<span class="informative">For example:</span></p>
|
|
<pre><span class="informative">00.5s = 500 milliseconds</span>
|
|
<span class="informative">00:00.005 = 5 milliseconds</span></pre>
|
|
<h5><a name="Timing-OffsetValueSyntax"></a>Offset values</h5>
|
|
<p class="informative">Offset values are used to specify when an element should
|
|
begin or end relative to its syncbase.</p>
|
|
<p><span class="normative"><em><span class="informative">This section is </span>normative</em></span></p>
|
|
<p><span class="normative">An offset value has the following syntax:</span></p>
|
|
<pre><span class="normative">offset-value ::= (( <a href="#Timing-WhiteSpaceBNF">S</a> "+" | "-" <a href="#Timing-WhiteSpaceBNF">S</a> )? ( Clock-value )</span></pre>
|
|
<ul>
|
|
<li><span class="normative">An offset value allows an optional sign on a clock
|
|
value, and is used to indicate a positive or negative offset.</span>
|
|
<li><span class="normative">The offset is measured in document time.</span></li>
|
|
</ul>
|
|
<p><span class="normative">The implicit syncbase for an offset value is the
|
|
document begin.</span></p>
|
|
<h5><a name="Timing-IDRefValueSyntax"></a>ID-Reference values</h5>
|
|
<p><span class="normative"><em><span class="informative">This section is </span>normative</em></span></p>
|
|
<p><span class="normative">ID reference values are references to the value of an
|
|
"id" attribute of another element in the document. </span></p>
|
|
<pre><span class="normative">Id-value ::= IDREF</span></pre>
|
|
<ul>
|
|
<li><span class="normative">The IDREF is a legal XML identifier.</span></li>
|
|
</ul>
|
|
<h5><a name="Timing-SyncbaseValueSyntax"></a>Syncbase values</h5>
|
|
<p><span class="informative">A syncbase value starts with a Syncbase-element
|
|
term defining the value of an "id" attribute of another element
|
|
referred to as the <em>syncbase element</em>.</span></p>
|
|
<p><span class="normative"><em><span class="informative">This section is </span>normative</em></span></p>
|
|
<p><span class="normative">A syncbase value has the following syntax:</span></p>
|
|
<p><span class="normative"><code> Syncbase-value ::= (
|
|
Syncbase-element "." Time-symbol )<br>
|
|
|
|
( <a href="#Timing-WhiteSpaceBNF">S</a> ("+"|"-") <a href="#Timing-WhiteSpaceBNF">S</a>
|
|
Clock-value )? <br>
|
|
Syncbase-element ::= Id-value<br>
|
|
Time-symbol ::= "begin" |
|
|
"end"</code></span></p>
|
|
<ul>
|
|
<li><span class="normative">The syncbase element must be another timed element
|
|
contained in the host document.</span>
|
|
<li><span class="normative">If the syncbase element specification refers to
|
|
an illegal element, the time-value description </span>will be treated as
|
|
though "indefinite" were specified.</li>
|
|
</ul>
|
|
<p><span class="normative">The syncbase element is qualified with one of the
|
|
following <em>time symbols:</em></span></p>
|
|
<dl>
|
|
<dt><span class="normative">begin</span>
|
|
<dd><span class="normative">Specifies the begin time of the syncbase element.</span>
|
|
<dt><span class="normative">end</span>
|
|
<dd><span class="normative">Specifies the Active End of the syncbase element.</span></dd>
|
|
</dl>
|
|
<ul>
|
|
<li><span class="normative">The time symbol can be followed by an offset
|
|
value. The offset value specifies an offset from the time (i.e. the begin or
|
|
active end) specified by the syncbase and time symbol.</span>
|
|
<li><span class="normative">If the clock value is omitted, it defaults to
|
|
"0".</span>
|
|
<li><span class="normative">No embedded white space is allowed between a
|
|
syncbase element and a time-symbol.</span>
|
|
<li><span class="normative">White space will be ignored before and after a
|
|
"+" or "-" for a clock value.</span>
|
|
<li><span class="normative">Leading and trailing white space characters (i.e.
|
|
before and after the entire syncbase value) will be ignored.</span></li>
|
|
</ul>
|
|
<p><span class="informative">Examples:</span></p>
|
|
<p><span class="informative"><code> begin="x.end-5s"
|
|
</code>: Begin 5 seconds before "x" ends<br>
|
|
<code> begin=" x.begin " </code>:
|
|
Begin when "x" begins<br>
|
|
<code> begin="x.begin + 1m" </code>: End 1 minute
|
|
after "x" begins</span></p>
|
|
<h5><a name="Timing-EventValueSyntax"></a>Event values</h5>
|
|
<p class="descdef"><span class="informative"><em>This section is informative</em></span></p>
|
|
<p><span class="informative">An Event value starts with an Eventbase-element
|
|
term that specifies the <em>event-base element</em>. The event-base element is
|
|
the element on which the event is observed. Given DOM event bubbling, the
|
|
event-base element may be either the element that raised the event, or it may be
|
|
an ancestor element on which the bubbled event can be observed. Refer to [<a href="#ref-DOM2Events">DOM2Events</a>] for details.</span></p>
|
|
<p><span class="normative"><em><span class="informative">This section is </span>normative</em></span></p>
|
|
<p><span class="normative">An event value has the following syntax:</span></p>
|
|
<p><span class="normative"><code> Event-value
|
|
::= ( Eventbase-element "." )? Event-symbol <br>
|
|
|
|
( <a href="#Timing-WhiteSpaceBNF">S</a> ("+"|"-") <a href="#Timing-WhiteSpaceBNF">S</a>
|
|
Clock-value )? <br>
|
|
Eventbase-element ::= ID</code></span></p>
|
|
<p><span class="normative">The eventbase-element must be another element
|
|
contained in the host document.</span></p>
|
|
<p><span class="normative">If the Eventbase-element term is missing, the
|
|
event-base element is defined to be the target element of the animation,</span></p>
|
|
<p><span class="normative">The event value must specify an Event-symbol. </span><span class="informative">This
|
|
term specifies the name of the event that is raised on the Event-base element.</span> <span class="normative">The
|
|
host language designer must specify which events can be specified.</span></p>
|
|
<ul>
|
|
<li><span class="normative">Host language specifications must include a
|
|
description of legal event names (with "none" as a valid
|
|
description), and/or allow any name to be used.</span>
|
|
<li>
|
|
<p class="normative"><span class="normative">If an integrating language
|
|
specifies no supported events, the event-base time value is effectively
|
|
unsupported for that language. </span></p>
|
|
<li>
|
|
<p class="normative"><span class="normative">If the host language allows
|
|
dynamically created events (as supported by DOM-Level2-Events [<a href="#ref-DOM2Events">DOM2Events</a>]), all possible Event-symbol names cannot be specified and so
|
|
unrecognized names may not be considered errors.</span></p>
|
|
<li>
|
|
<p class="normative"><span class="normative">Unless explicitly specified by
|
|
a host language, it is not considered an error to specify an event that
|
|
cannot be raised on the Event-base element (such as click for audio or other
|
|
non-visual elements).</span> <span class="informative">Since the event will
|
|
never be raised on the specified element, the event-base value will never be
|
|
resolved.</span></p>
|
|
</li>
|
|
</ul>
|
|
<p class="normative">The last term specifies an optional offset-value that is an
|
|
offset from the time of the event.</p>
|
|
<ul>
|
|
<li><span class="normative">If this term is omitted, the offset is 0.</span>
|
|
<li><span class="normative">No embedded white space is allowed between an
|
|
eventbase element and an event-symbol.</span>
|
|
<li><span class="normative">White space will be ignored before and after a
|
|
"+" or "-" for a clock value.</span>
|
|
<li><span class="normative">Leading and trailing white space characters (i.e.,
|
|
before and after the entire eventbase value) will be ignored.</span></li>
|
|
</ul>
|
|
<p><span class="informative"><em>This section is informative</em></span></p>
|
|
<p class="informative">This module defines several events that may be included
|
|
in the supported set for a host language, including <code>beginEvent</code> and <code>endEvent</code>.
|
|
These should not be confused with the syncbase time values. See the section on <a href="#EventModel"><!-- Level 3 -->
|
|
Events and event model</a>.</p>
|
|
<p class="informative"><span class="informative">The semantics of event-based
|
|
timing are detailed in <a href="#Unifying">Unifying Scheduling
|
|
and Interactive Timing</a>. </span></p>
|
|
<p><span class="informative">Examples:</span></p>
|
|
<p><span class="informative"><code> begin=" x.load "
|
|
</code>: Begin when "load" is observed on "x"<br>
|
|
<code> begin="x.focus+3s" </code>:
|
|
Begin 3 seconds after an "focus" event on "x"<br>
|
|
<code> begin="x.endEvent+1.5s" </code>: Begin 1 and a half
|
|
seconds after an "endEvent" event on "x"<br>
|
|
<code> begin="x.repeat"
|
|
</code>: Begin each time a <code>repeat</code> event is observed on
|
|
"x"</span></p>
|
|
<h5><a name="Timing-RepeatValueSyntax"></a>Repeat values</h5>
|
|
<p class="informative">Repeat values are a variant on event values that support
|
|
a qualified repeat event. The <code>repeat</code> event defined in <a href="#EventModel"><!-- Level 3 -->
|
|
Events and event model</a> allows an additional suffix to qualify the event based upon
|
|
an iteration value.</p>
|
|
<p><span class="normative">A repeat value has the following syntax:</span></p>
|
|
<pre><span class="normative">Repeat-value ::= ( Eventbase-element "." )? "repeat(" iteration ")"
|
|
( <a href="#Timing-WhiteSpaceBNF">S</a> ("+"|"-") <a href="#Timing-WhiteSpaceBNF">S</a> Clock-value )?
|
|
iteration ::= DIGIT+ </span></pre>
|
|
<p class="normative">If this qualified form is used, the eventbase value will
|
|
only be resolved when a repeat is observed that has a iteration value that
|
|
matches the specified iteration. </p>
|
|
<p class="informative">The qualified repeat event syntax allows an author to
|
|
respond only to an individual repeat of an element.</p>
|
|
<p><span class="informative">The following example describes a qualified repeat
|
|
eventbase value:</span></p>
|
|
<pre><span class="informative"><animate id="foo" repeatCount="10" end="endAnim.click" ... /></span>
|
|
<span class="informative"><img id="endAnim" <strong>begin="foo.repeat(2)"</strong> .../></span></pre>
|
|
<p><span class="informative">The "endAnim" image will appear when the
|
|
animate element "foo" repeats the second time. This example allows the user to
|
|
stop the animation after it has played though at least twice.</span></p>
|
|
<h5><a name="Timing-AccessKeyValueSyntax"></a>AccessKey values</h5>
|
|
<p>AccessKey values allow an author to tie a begin or end time to a particular
|
|
keypress, independent of focus issues. It is modeled on the HTML accessKey
|
|
support. Unlike with HTML, user agents should not require that a modifier key
|
|
(such as "ALT") be required to activate an access key.</p>
|
|
<p><span class="normative">An access key value has the following syntax:</span></p>
|
|
<p class="normative"><code> AccessKey-value ::= "accessKey("
|
|
character ")"<br>
|
|
|
|
( <a href="#Timing-WhiteSpaceBNF">S</a> ("+"|"-") <a href="#Timing-WhiteSpaceBNF">S</a>
|
|
Clock-value )? <br>
|
|
<br>
|
|
</code>The character is a single character from [<a href="#ref-ISO10646">ISO10646</a>].</p>
|
|
<p><span class="normative">The time value is defined as the time that the access
|
|
key character is input by the user.</span></p>
|
|
<h5><a name="Timing-WallclockSyncValueSyntax"></a>Wallclock-sync values</h5>
|
|
<p><span class="informative"><em>This section is informative</em></span></p>
|
|
<p><span class="informative">Wallclock-sync values have the following syntax.
|
|
The values allowed are based upon several of the "profiles" described
|
|
in [<a href="#ref-DATETIME">DATETIME</a>], which is based upon [</span><a href="#ref-iso8601">ISO8601</a><span class="informative">].</span></p>
|
|
<p><em>This section is normative</em></p>
|
|
<pre><span class="normative">wallclock-val ::= "wallclock(" <a href="#Timing-WhiteSpaceBNF">S</a> (DateTime | WallTime) <a href="#Timing-WhiteSpaceBNF">S</a> ")"</span>
|
|
<span class="normative">DateTime ::= Date "T" WallTime</span>
|
|
<span class="normative">Date ::= Years "-" Months "-" Days</span>
|
|
<span class="normative">WallTime ::= (HHMM-Time | HHMMSS-Time)(TZD)?</span>
|
|
<span class="normative">HHMM-Time ::= Hours24 ":" Minutes</span>
|
|
<span class="normative">HHMMSS-Time ::= Hours24 ":" Minutes ":" Seconds ("." Fraction)?</span>
|
|
<span class="normative">Years ::= 4DIGIT;</span>
|
|
<span class="normative">Months ::= 2DIGIT; range from 01 to 12</span>
|
|
<span class="normative">Days ::= 2DIGIT; range from 01 to 31</span>
|
|
<span class="normative">Hours24 ::= 2DIGIT; range from 00 to 23</span>
|
|
<span class="normative">4DIGIT ::= DIGIT DIGIT DIGIT DIGIT</span>
|
|
<span class="normative">TZD ::= "Z" | (("+" | "-") Hours24 ":" Minutes )</span></pre>
|
|
<ul>
|
|
<li><span class="normative"><!--Moved from above. 4-13-00 -->
|
|
Exactly the components shown here must be present, with exactly this
|
|
punctuation.</span>
|
|
<li><span class="normative">Note that the "T" appears literally in
|
|
the string, to indicate the beginning of the time element, as specified in [</span><a href="#ref-iso8601">ISO8601</a><span class="normative">].</span></li>
|
|
</ul>
|
|
<p class="descdef"><span class="informative"><em>This section is informative</em></span></p>
|
|
<pre><span class="informative">Complete date plus hours and minutes:</span>
|
|
|
|
<span class="informative"> YYYY-MM-DDThh:mmTZD (e.g. 1997-07-16T19:20+01:00)</span>
|
|
|
|
<span class="informative">Complete date plus hours, minutes and seconds:</span>
|
|
|
|
<span class="informative"> YYYY-MM-DDThh:mm:ssTZD (e.g. 1997-07-16T19:20:30+01:00)</span>
|
|
|
|
<span class="informative">Complete date plus hours, minutes, seconds and a decimal fraction of a second</span>
|
|
|
|
<span class="informative"> YYYY-MM-DDThh:mm:ss.sTZD (e.g. 1997-07-16T19:20:30.45+01:00)</span></pre>
|
|
<p><span class="informative">Note that the Minutes, Seconds, Fraction, 2DIGIT
|
|
and DIGIT syntax is as defined for <a href="#Timing-ClockValueSyntax">Clock-values</a>.
|
|
Note that white space is not allowed within the date and time specification.</span></p>
|
|
<p><em>This section is normative</em></p>
|
|
<p><span class="normative">There are three ways of handling time zone offsets:</span></p>
|
|
<ol>
|
|
<li><span class="normative">Times are expressed in UTC (Coordinated Universal
|
|
Time), with a special UTC designator ("Z").</span>
|
|
<li><span class="normative">Times are expressed in local time, together with a
|
|
time zone offset in hours and minutes. A time zone offset of "+hh:mm"
|
|
indicates that the date/time uses a local time zone which is "hh"
|
|
hours and "mm" minutes ahead of UTC. A time zone offset of "-hh:mm"
|
|
indicates that the date/time uses a local time zone which is "hh"
|
|
hours and "mm" minutes behind UTC.</span>
|
|
<li><span class="normative">Times are expressed in local time, as defined for
|
|
the presentation location. The local time zone of the end-user platform is
|
|
used.</span></li>
|
|
</ol>
|
|
<p><span class="informative">The presentation engine must be able to convert
|
|
wallclock-values to a time within the document.</span></p>
|
|
<ul>
|
|
<li><span class="normative">When the document begins, the current wallclock
|
|
time must be noted - this is the <em>document wallclock begin</em>.</span>
|
|
<li><span class="normative">Wallclock values are then converted to a document
|
|
time by subtracting the document wallclock begin.</span></li>
|
|
</ul>
|
|
<p class="descdef"><span class="informative"><em>This section is informative</em></span></p>
|
|
<p><span class="informative">Note that the resulting begin or end time may be
|
|
before the begin, or after end of the parent time container. This is not an
|
|
error, but the <a href=
|
|
"http://www.w3.org/TR/smil20/smil-timing.html#Timing-TimeContainersConstraints">time container
|
|
constraints</a> still apply. In any case, the semantics of the <span class="ainst-begin ainst">begin</span>
|
|
and <span class="ainst-end
|
|
ainst">end</span> attribute govern the interpretation of the wallclock value.</span></p>
|
|
|
|
<h4><a name="Timing-EvaluationOfBeginEndTimeLists"></a> 3.6.8. Evaluation of begin and
|
|
end time lists</h4>
|
|
|
|
<p><em><span class="informative">This section is </span>informative</em></p>
|
|
|
|
<p>Animation elements can have multiple begin and end
|
|
values. We need to specify the semantics associated with multiple begin and
|
|
end times, and how a dynamic timegraph model works with these multiple
|
|
times.</p>
|
|
|
|
<p>The model is based around the idea of <em>intervals</em> for each element.
|
|
An interval is defined by a begin and an end time. As the timegraph is played,
|
|
more than one interval may be created for an element with multiple begin and
|
|
end times. At any given moment, there is one <em>current interval</em>
|
|
associated with each element. Intervals are created by evaluating a list of
|
|
begin times and a list of end times, each of which is based upon the
|
|
<em>conditions</em> described in the begin and end attributes for the
|
|
element.</p>
|
|
|
|
<p>The list of begin times and the list of end times used to calculate new
|
|
intervals are referred to as lists of "instance times". Each instance time in
|
|
one of the lists is associated with the specification of a begin or end
|
|
condition defined in the attribute syntax. Some conditions - for example
|
|
offset-values - only have a single instance in the list. Other conditions may
|
|
have multiple instances if the condition can happen more than once. For
|
|
example a syncbase-value can have multiple instance times if the <em>
|
|
syncbase</em> element has played several intervals, and an event-value may
|
|
have multiple instance times if the event has happened more than once. </p>
|
|
|
|
<p>The instance times lists for each element are initialized when the
|
|
timegraph is initialized, and exist for the entire life of the timegraph. In
|
|
this version of the time model without time containers,
|
|
instance times remain in the lists
|
|
forever, once they have been added. For example, times associated with
|
|
event-values are only added when the associated event happens, but remain in the
|
|
lists thereafter. Similarly,
|
|
Instance times for syncbase-values are added to the list each time a new
|
|
interval is created for the syncbase element, and remain in the list.</p>
|
|
|
|
<p>When the timegraph is initialized, each element creates a first current
|
|
interval. The begin time will generally be resolved, but the end time may
|
|
often be unresolved. If the element can restart while active, the current
|
|
interval can end (early) at the next begin time. This interval will play, and
|
|
then when it ends, the element will review the lists of begin and end instance
|
|
times. If the element should play again, another interval will be created and
|
|
this new interval becomes the <em>current interval</em>. The history of an
|
|
element can be thought of as a set of intervals. </p>
|
|
|
|
<p>Because the begin and end times may depend on other times that can change,
|
|
the current interval is subject to change, over time. For example, if any of
|
|
the instance times for the <em>end</em> changes while the current interval is
|
|
playing, the current interval end will be recomputed and may change.
|
|
Nevertheless, once a time has <em>happened</em>, it is fixed. That is, once
|
|
the current interval has begun, its begin time can no longer change, and once
|
|
the current interval has ended, its end time can no longer change. For an
|
|
element to restart, it must end the current interval and then create a new
|
|
current interval to effect the restart.</p>
|
|
|
|
<p>When a begin or end condition defines a time dependency to another element
|
|
(e.g. with a syncbase-value), the time dependency is generally thought of as a
|
|
relationship between the two elements. This level of dependency is important
|
|
to the model when an element creates a new current interval. However, for the
|
|
purposes of propagating changes to individual times, time dependencies are
|
|
more specifically a dependency from a given <em>interval of the syncbase
|
|
element</em> to a particular <em>instance time</em> in one of the dependent
|
|
element's instance time lists. Since only the current interval's begin and end
|
|
times can change, only the current interval will generate time-change notices
|
|
and propagate these to the dependent instance times.</p>
|
|
|
|
<p>When this section refers to the begin and end times for an element, the
|
|
times are described as being in document time (relative to the document begin). All sync-arcs, event arcs, wallclock values, etc. must be
|
|
converted to this time space for easy comparison. </p>
|
|
|
|
<p>Cycles in the timegraph must be detected and broken to ensure reasonable
|
|
functioning of the implementation. A model for how to do this in the general
|
|
case is described. A
|
|
mechanism to support certain useful cyclic dependencies falls out of the
|
|
model.</p>
|
|
|
|
<p>The rest of this section details the semantics of the instance times lists,
|
|
the element life cycle, and the mechanisms for handling dependency
|
|
relationships and cycles.</p>
|
|
|
|
<h5><a name="Timing-BeginEnd-InstanceTimesLists"></a>The instance times
|
|
lists</h5>
|
|
|
|
<p>Instance lists are associated with each element, and exist for the duration
|
|
of the document (i.e., there is no <em> life cycle</em> for instance lists).
|
|
Instance lists may change, and some times may be added and removed, but the
|
|
begin and end instance times lists are persistent.</p>
|
|
|
|
<p>Each element can have a begin attribute that defines one or more conditions
|
|
that can begin the element. In addition, the timing model describes a set of
|
|
rules for determining the end of the element, including the effects of an end
|
|
attribute that can have multiple conditions. In order to calculate the times
|
|
that should be used for a given interval of the element, we must convert the
|
|
begin times and the end times into parent simple time, sort each list of times
|
|
(independently), and then find an appropriate pair of times to define an
|
|
interval.</p>
|
|
|
|
<p>The instance times can be resolved or unresolved. In the case of the end
|
|
list, an additional special value "indefinite" is allowed. The lists are
|
|
maintained in sorted order, with "indefinite" sorting after all other resolved
|
|
times, and unresolved times sorting to the end.</p>
|
|
|
|
<p>For begin, the list interpretation is straightforward, since begin times
|
|
are based only upon the conditions in the attribute or upon the default begin
|
|
value if there is no attribute. However, when a begin condition is a syncbase-value, the syncbase element may have multiple
|
|
intervals, and we must account for this in the list of begin times associated
|
|
with the conditions.</p>
|
|
|
|
<p>For end, the case is somewhat more complex, since the end conditions are
|
|
only one part of the calculation of the end of the active duration. The
|
|
instance times list for end are used together with the other SMIL Timing
|
|
semantics to calculate the actual end time for an interval. </p>
|
|
|
|
<p>If an instance time was defined as syncbase-values,
|
|
the instance time will maintain a time dependency relationship to the
|
|
associated interval for the syncbase element. This means that if the
|
|
associated begin or end time of the syncbase current interval changes, then
|
|
the dependent instance time for this element will change as well.</p>
|
|
|
|
<p>When an element creates a new interval, it notifies time dependents and
|
|
provides the begin and end times that were calculated according to the
|
|
semantics described in "Computing the active duration". Each dependent element
|
|
will create a new instance time tied to (i.e., with a dependency relationship
|
|
to) the new syncbase current interval. </p>
|
|
|
|
<h6>Building the instance times lists</h6>
|
|
|
|
<p>The translation of begin or end conditions to instance times depends upon
|
|
the type of condition:</p>
|
|
<ul>
|
|
<li><strong>offset-values</strong> are the simplest. Each offset-value
|
|
condition yields a single instance time.</li>
|
|
<li><strong>wallclock-sync-values</strong> are similar to offset values.
|
|
Each wallclock-sync-value condition yields a single instance time.</li>
|
|
<li><strong>event-values, accessKey-values and repeat-values </strong>are all
|
|
treated similarly. These conditions do not yield an instance time unless
|
|
and until the associated event happens. Each time the event happens, the
|
|
condition yields a single instance time. The event time plus or minus any
|
|
offset is <em>added</em> to the list. If the event happens multiple times, there may be multiple instance times in
|
|
the list associated with the event condition. However, an important
|
|
distinction is that event times are cleared from the list each time the
|
|
element is reset (see also <a href="#ResettingElementState">Resetting element state</a>). Within
|
|
this section, these three value types are referred to collectively as
|
|
<em>event value conditions</em>.</li>
|
|
<li><strong>syncbase-values and media-marker-values </strong>are treated similarly. These conditions do
|
|
not yield an instance time unless and until the associated syncbase
|
|
element creates an interval. Each time the syncbase element creates a new
|
|
interval, the condition yields a single instance time. The time plus or
|
|
minus any offset is <em>added</em> to the list. Within this section, these three value types are referred to
|
|
collectively as <em>syncbase value conditions</em>.</li>
|
|
<li>The special value <strong>"indefinite"</strong> does not yield an
|
|
instance time in the begin list. It will, however yield a single instance
|
|
with the value "indefinite" in an end list.</li>
|
|
</ul>
|
|
|
|
<p>If no attribute is present, the default begin value (an offset-value of 0) must be evaluated.</p>
|
|
|
|
<p>If a DOM method call is made to begin or end the element
|
|
(<code>beginElement()</code>, <code> beginElementAt()</code>, <code>
|
|
endElement()</code> or <code> endElementAt()</code>), each method call creates
|
|
a single instance time (in the appropriate instance times list). These time
|
|
instances are cleared upon reset just as for event times. See <a href="#ResettingElementState">Resetting element state</a>.</p>
|
|
|
|
<p>When a new time instance is added to the begin list, the current interval
|
|
will evaluate restart semantics and may ignore the new time or it may end the
|
|
current interval (this is detailed in <a
|
|
href="#Timing-BeginEnd-Restart">Interaction with restart semantics</a>). In
|
|
contrast, when an instance time in the begin list changes because the syncbase
|
|
(current interval) time moves, this does not invoke restart semantics, but may
|
|
change the current begin time: If the current interval has not yet begun, a
|
|
change to an instance time in the begin list will cause a re-evaluation of the
|
|
begin instance lists, which may cause the interval begin time to change. If
|
|
the interval begin time changes, a <em>time-change</em> notice must be
|
|
propagated to all dependents, and the current interval end must also be
|
|
re-evaluated.</p>
|
|
|
|
<p>When a new instance time is added to the end list, or when an instance time
|
|
in the end list changes, the current interval will re-evaluate its end time.
|
|
If it changes, it must notify dependents.</p>
|
|
|
|
<p>If an element has already played all intervals, there may be no current
|
|
interval. In this case, additions to either list of instance times, as well as
|
|
changes to any instance time in either list cause the element to re-evaluate
|
|
the lists just as it would at the end of each interval (as described in <a
|
|
href="#Timing-BeginEnd-LC-End">End of an interval</a> below). This may or may
|
|
not lead to the creation of a new interval for the element.</p>
|
|
|
|
<p>When times are added to the instance times lists, they may or may not be
|
|
resolved. If they are resolved, they will be converted to document time.
|
|
If an instance time changes from unresolved to resolved, it will be similarly
|
|
converted.</p>
|
|
|
|
<p>There is a difference between an unresolved instance time, and a begin or
|
|
end condition that has no associated instance. If, for example, an event value
|
|
condition is specified in the end attribute, but no such event has happened,
|
|
there will be no associated instance time in the end list. However, if a
|
|
syncbase value condition is specified for end, and if the syncbase element has
|
|
a current interval, there will be an associated instance time in the end list.
|
|
Since the syncbase value condition can be relative to the end of the syncbase
|
|
element, and since the end of the syncbase current interval may not be
|
|
resolved, the associated instance time in the end list can be unresolved. Once
|
|
the syncbase current interval actually ends, the dependent instance time in
|
|
the end list will get a time-change notification for the resolved syncbase
|
|
interval end. The dependent instance time will convert the newly resolved
|
|
syncbase time to a resolved time in document time. If the instance lists
|
|
did not include the unresolved instance times, some additional mechanism would
|
|
have to be defined to add the end instance time when the syncbase element's
|
|
current interval actually ended, and resolved its end time. </p>
|
|
|
|
<p>The list of resolved times includes historical times defined relative to
|
|
sync base elements, and so can grow over time if the sync base has many
|
|
intervals. Implementations may filter the list of times as an optimization, so
|
|
long as it does not affect the semantics defined herein.</p>
|
|
|
|
<h5><a name="Timing-BeginEnd-LifeCycle"></a>Element life-cycle</h5>
|
|
|
|
<p>The life cycle of an element can be thought of as the following basic
|
|
steps:</p>
|
|
<ol>
|
|
<li>Startup - getting the first interval</li>
|
|
<li>Waiting to begin the current interval</li>
|
|
<li>Active time - playing an interval</li>
|
|
<li>End of an interval - compute the next one and notify dependents</li>
|
|
<li>Post active - perform any fill and wait for any next interval</li>
|
|
</ol>
|
|
|
|
<p>Steps 2 to 5 can loop for as many intervals as are defined before the end
|
|
of the parent simple duration. At any time during step 2, the begin time for
|
|
the current interval can change, and at any time during steps 2 or 3, the end
|
|
time for the current interval can change. When either happens, the changes are
|
|
propagated to time dependents.</p>
|
|
|
|
<p>When the document and the associated timegraph are initialized, the
|
|
instance lists are empty. The simple offset values and any "indefinite" value
|
|
in an end attribute can be added to the respective lists as part of
|
|
initialization.</p>
|
|
|
|
<p>When an element has played all allowed instances, it can be thought of as
|
|
stuck in step 5. However any changes to the instance lists during this period
|
|
cause the element to jump back to step 4 and consider the creation of a new
|
|
current interval. </p>
|
|
|
|
<h6><a name="Timing-BeginEnd-LC-Start"></a>Startup - getting the first
|
|
interval</h6>
|
|
|
|
<p>An element life cycle begins with the beginning of the document. The cycle
|
|
begins by computing the first current interval. This requires some special consideration of the lists of times,
|
|
but is relatively straight-forward. It is similar to, but not the same
|
|
as the action that applies when the element ends (this is described in <a
|
|
href="#Timing-BeginEnd-LC-End">End of an interval</a>). The basic idea is to
|
|
find the first interval for the element, and make that the current interval.
|
|
However, the model should handle two edge cases:</p>
|
|
|
|
<ol class="toc">
|
|
<li>The element can begin before the document begins, and so appears to begin
|
|
part way into the local timeline. The model must handle begin times before the
|
|
document begin
|
|
(i.e. before 0).</li>
|
|
<li>The element has one or more intervals defined that begin <em>and
|
|
end</em> before the document begins (before 0). These are filtered out of
|
|
the model.</li>
|
|
</ol>
|
|
|
|
<p>Thus the strict definition of the first acceptable interval for the element
|
|
is the first interval that ends after the document begins. Here is some
|
|
pseudo-code to get the first interval for an element. It assumes an abstract
|
|
type "Time" that supports a compare function. It can be a resolved numeric
|
|
value, the special value INDEFINITE (only used with end), and it can be the
|
|
special value UNRESOLVED. Indefinite compares "greater than" all resolved
|
|
values, and UNRESOLVED is "greater than" both resolved values and INDEFINITE.
|
|
The code uses the instance times lists associated with the begin and end
|
|
attributes, as described in the previous section.</p>
|
|
<pre>// Utility function that returns true if the end attribute specification
|
|
// includes conditions that describe event-values, repeat-values or accessKey-values.
|
|
boolean endHasEventConditions();</pre>
|
|
<pre>// Calculates the first acceptable interval for an element
|
|
// Returns:
|
|
// Interval if there is such an interval
|
|
// FAILURE if there is no such interval
|
|
Interval getFirstInterval()
|
|
{
|
|
Time beginAfter=-INFINITY;
|
|
|
|
while( TRUE ) // loop till return
|
|
{
|
|
Set tempBegin = the first value in the begin list that is >= beginAfter.
|
|
If there is no such value // No interval
|
|
return FAILURE;
|
|
|
|
If there was no end attribute specified
|
|
// this calculates the active end with no end constraint
|
|
tempEnd = calcActiveEnd( tempBegin );
|
|
else
|
|
{
|
|
// We have a begin value - get an end
|
|
Set tempEnd = the first value in the end list that is >= tempBegin.
|
|
// Allow for non-0-duration interval that begins immediately
|
|
// after a 0-duration interval.
|
|
If tempEnd == tempBegin && tempEnd has already been used in
|
|
an interval calculated in this method call
|
|
{
|
|
set tempEnd to the next value in the end list that is > tempEnd
|
|
}
|
|
If there is no such value
|
|
{
|
|
// Events leave the end open-ended. If there are other conditions
|
|
// that have not yet generated instances, they must be unresolved.
|
|
if endHasEventConditions()
|
|
OR if the instance list is empty
|
|
tempEnd = UNRESOLVED;
|
|
// if all ends are before the begin, bad interval
|
|
else
|
|
return FAILURE;
|
|
}
|
|
// this calculates the active dur with an end constraint
|
|
tempEnd = calcActiveEnd( tempBegin, tempEnd );
|
|
}
|
|
|
|
// We have an end - is it after the parent simple begin?
|
|
if( tempEnd > 0 )
|
|
return( Interval( tempBegin, tempEnd ) );
|
|
|
|
// interval is too early
|
|
else if( restart == never )
|
|
// if can't restart, no good interval
|
|
return FAILURE;
|
|
|
|
else
|
|
// Change beginAfter to find next interval, and loop
|
|
beginAfter = tempEnd;
|
|
|
|
} // close while loop
|
|
|
|
} // close getFirstInterval</pre>
|
|
|
|
<p>Note that while we might consider the case of <code>restart=always</code>
|
|
separately from <code>restart=whenNotActive</code>, it would just be busy work
|
|
since we need to find an interval that begins <em>after</em>
|
|
<code>tempEnd</code>.</p>
|
|
|
|
<p>If the model yields no first interval for the element, it will never begin,
|
|
and so there is nothing more to do at this point. However if there is a valid
|
|
interval, the element must notify all time dependents that there is a <em>new
|
|
interval</em> of the element. This is a notice from this element to all
|
|
elements that are direct time dependents. This is distinct from the
|
|
propagation of a changed time.</p>
|
|
|
|
<p>When a dependent element gets a "new interval" notice, this includes a
|
|
reference to the new interval. The new interval will generally have a resolved
|
|
begin time and may have a resolved end time. An associated instance time will
|
|
be added to the begin or end instance time list for the dependent element, and
|
|
this new instance time will maintain a time dependency relationship to the
|
|
syncbase interval.</p>
|
|
|
|
<h6><a name="Timing-BeginEnd-LC-FirstWait"></a>Waiting to begin the
|
|
interval</h6>
|
|
|
|
<p>This period only occurs if the current interval does not begin immediately
|
|
when (or before) it is created. While an interval is waiting to begin, any
|
|
changes to syncbase element current interval times will be propagated to the
|
|
instance lists and may result in a change to the current interval.</p>
|
|
|
|
<p>If the element receives a "new interval" notice while it is waiting to
|
|
begin, it will <em>add </em>the associated time (i.e., the begin or end time of
|
|
the syncbase interval) to the appropriate list of resolved times.</p>
|
|
|
|
<p>When an instance time changes, or when a new instance time is added to one
|
|
of the lists, the element will re-evaluate the begin or end time of the
|
|
current interval (using the same algorithm described in the previous
|
|
section). If this re-evaluation yields a changed interval, time change
|
|
notice(s) will be sent to the associated dependents.</p>
|
|
|
|
<p>It is possible during this stage that the begin and end times could change
|
|
such that the interval would never begin (i.e., the interval end is before the
|
|
interval begin). In this case, the interval must be deleted and all dependent
|
|
instance times must be removed from the respective instance lists of dependent
|
|
elements. These changes to the instance lists will cause re-evaluation of the
|
|
dependent element current intervals, in the same manner as a changed instance
|
|
time does.</p>
|
|
|
|
<h6><a name="Timing-BeginEnd-LC-Active"></a>Active time - playing an
|
|
interval</h6>
|
|
|
|
<p>This period occurs when the current interval is active (i.e., once it has
|
|
begun, and until it has ended). During this period, the end time of the
|
|
interval can change, but the begin time cannot. If any of the instance times
|
|
in the begin list change after the current interval has begun, the change will
|
|
not affect the current interval. This is different from the case of <em>adding
|
|
</em>a new instance time to the begin list, which <em>can </em>cause a
|
|
restart.</p>
|
|
|
|
<p>If the element receives a "new interval" notice while it is active, it will
|
|
<em>add </em>the associated time (i.e., the begin or end time of the syncbase
|
|
interval) to the appropriate list of resolved times. If the new interval adds
|
|
a time to the begin list, restart semantics are considered, and this may end
|
|
the current interval.</p>
|
|
|
|
<p>If restart is set to "always", then the current interval will end early if
|
|
there is an instance time in the begin list that is before (i.e. earlier than)
|
|
the defined end for the current interval. Ending in this manner will also send
|
|
a changed time notice to all time dependents for the current interval end.
|
|
See also <a href="#Timing-BeginEnd-Restart">Interaction with restart
|
|
semantics</a>.</p>
|
|
|
|
<h6><a name="Timing-BeginEnd-LC-End"></a>End of an interval</h6>
|
|
|
|
<p>When an element ends the current interval, the element must reconsider the
|
|
lists of resolved begin and end times. If there is another legal interval
|
|
defined to begin at or after the just completed end time, a new interval will
|
|
be created. When a new interval is created it becomes the <em>current
|
|
interval</em> and a new interval notice is sent to all time dependents.</p>
|
|
|
|
<p>The algorithm used is very similar to that used in step 1, except that we
|
|
are interested in finding an interval that begins after the most recent
|
|
end.</p>
|
|
<pre>// Calculates the next acceptable interval for an element
|
|
// Returns:
|
|
// Interval if there is such an interval
|
|
// FAILURE if there is no such interval
|
|
Interval getNextInterval()
|
|
{
|
|
// Note that at this point, the just ended interval is still the "current interval"
|
|
Time beginAfter=currentInterval.end;
|
|
|
|
Set tempBegin = the first value in the begin list that is >= beginAfter.
|
|
If there is no such value // No interval
|
|
return FAILURE;
|
|
|
|
If there was no end attribute specified
|
|
// this calculates the active end with no end constraint
|
|
tempEnd = calcActiveEnd( tempBegin );
|
|
else
|
|
{
|
|
// We have a begin value - get an end
|
|
Set tempEnd = the first value in the end list that is >= tempBegin.
|
|
// Allow for non-0-duration interval that begins immediately
|
|
// after a 0-duration interval.
|
|
If tempEnd == currentInterval.end
|
|
{
|
|
set tempEnd to the next value in the end list that is > tempEnd
|
|
}
|
|
If there is no such value
|
|
{
|
|
// Events leave the end open-ended. If there are other conditions
|
|
// that have not yet generated instances, they must be unresolved.
|
|
if endHasEventConditions()
|
|
OR if the instance list is empty
|
|
tempEnd = UNRESOLVED;
|
|
// if all ends are before the begin, bad interval
|
|
else
|
|
return FAILURE;
|
|
}
|
|
// this calculates the active dur with an end constraint
|
|
tempEnd = calcActiveEnd( tempBegin, tempEnd );
|
|
}
|
|
|
|
return( Interval( tempBegin, tempEnd ) );
|
|
|
|
} // close getNextInterval</pre>
|
|
|
|
<h6><a name="Timing-BeginEnd-LC-PostActive"></a>Post active</h6>
|
|
|
|
<p>This period can extend from the end of an interval until the beginning of
|
|
the next interval, or until the end of the document duration (whichever
|
|
comes first). During this period, any fill behavior is applied to the element.
|
|
The times for this interval can no longer change. Implementations may as an
|
|
optimization choose to break the time dependency relationships since they can
|
|
no longer produce changes.</p>
|
|
|
|
<h5><a name="Timing-BeginEnd-Restart"></a>Interaction with restart
|
|
semantics</h5>
|
|
|
|
<p>There are two cases in which restart semantics must be considered:</p>
|
|
<ol>
|
|
<li>When the current interval is playing, if <code>restart="always"</code>
|
|
then any instance time (call it <code><strong>T</strong></code>) in the
|
|
begin list that is after (i.e. later than) the current interval begin but
|
|
earlier than the current interval end will cause the current interval to
|
|
end at time <code><strong>T</strong></code>. This is the first step in
|
|
restarting the element: when the current interval ends, that in turn will
|
|
create any following interval.</li>
|
|
<li>When a new instance time is added to the begin list of instance times,
|
|
restart rules can apply. The new instance times may result from a begin
|
|
condition that specifies one of the syncbase value conditions, for which a
|
|
new instance notice is received. It may also result from a begin condition
|
|
that specifies one of the event value conditions, for which the associated
|
|
event happens.<br>
|
|
In either case, the restart setting and the state of the current interval
|
|
controls the resulting behavior. The new instance time is computed (e.g.,
|
|
from the syncbase current interval time or from the event time, and
|
|
including any offset), and added to the begin list. Then:
|
|
<ul>
|
|
<li>If the current interval is waiting to play, the element recalculates
|
|
the begin and end times for the current interval, as described in the
|
|
<a href="#Timing-BeginEnd-LifeCycle">Element life-cycle</a> step 1
|
|
(for the first interval) or step 4 (for all later intervals). If
|
|
either the begin or end time of the current interval changes, these
|
|
changes must be propagated to time dependents accordingly.</li>
|
|
<li>If the current interval is playing (i.e. it is active), then the
|
|
restart setting determines the behavior:
|
|
<ul>
|
|
<li>If <code>restart="never"</code> then nothing more is done. It is
|
|
possible (if the new instance time is associated with a syncbase
|
|
value condition) that the new instance time will be used the next
|
|
time the element life cycle begins.</li>
|
|
<li>If <code>restart="whenNotActive" </code>then nothing more is
|
|
done. If the time falls within the current interval, the element
|
|
cannot restart, and if it falls after, then the normal processing
|
|
at the end of the current interval will handle it. If the time
|
|
falls before the current interval, as can happen if the time
|
|
includes a negative offset, the element does not restart (the new
|
|
instance time is effectively ignored).</li>
|
|
<li>If <code>restart="always"</code> then case 1 above applies, and
|
|
will cause the current interval to end.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ol>
|
|
|
|
<h5><a name="Timing-BeginEnd-Cycles"></a>Cyclic dependencies in the
|
|
timegraph</h5>
|
|
|
|
<p>There are two types of cycles that can be created with SMIL timing,
|
|
<em>closed</em> cycles and <em>open</em> or <em>propagating</em> cycles. A
|
|
<em>closed</em> cycle results when a set of elements has mutually dependent
|
|
time conditions, and no other conditions on the affected elements can affect
|
|
or change this dependency relationship, as in examples 1 and 2 below. An
|
|
<em>open</em> or <em>propagating</em> cycle results when a set of elements
|
|
has mutually dependent time conditions, but at least one of the conditions
|
|
involved has more than one resolved condition. If any one of the elements in
|
|
the cycle can generate more than one interval, the cycle can propagate. In
|
|
some cases such as that illustrated in example 3, this can be very useful.</p>
|
|
|
|
<p>Times defined in a closed cycle are unresolved, unless some external
|
|
mechanism resolves one of the element time values (for example a DOM method
|
|
call or the traversal of a hyperlink that targets one of the elements). If
|
|
this happens, the resolved time will propagate through the cycle, resolving
|
|
all the associated time values.</p>
|
|
|
|
<p>Closed cycles are an error, and may cause the entire document to fail. In
|
|
some implementations, the elements in the cycle may just not begin or end
|
|
correctly. Examples 1 and 2 describe the most forgiving behavior, but
|
|
implementations may simply reject a document with a closed cycle.</p>
|
|
|
|
<h5>Detecting Cycles</h5>
|
|
|
|
<p>Implementations can detect cycles in the timegraph using a <em>visited</em>
|
|
flag on each element as part of the processing that propagates changes to time
|
|
dependents. As a changed time notice is propagated, each dependent element is
|
|
marked as having been <em>visited</em>. If the change to a dependent instance
|
|
time results in a change to the current interval for that element, this change
|
|
will propagate in turn to its dependents. This second <em>chained </em>notice
|
|
happens in the context of the first time-change notice that caused it. The
|
|
effect is like a stack that builds as changes propagate throughout the graph,
|
|
and then unwinds when all changes have propagated. If there is a dependency
|
|
cycle, The propagation path will traverse an element twice during a given
|
|
propagation chain. This is a common technique use in graph traversals.</p>
|
|
|
|
<p>A similar approach can be used when building dependency chains during
|
|
initialization of the timegraph, and when propagating new interval notices -
|
|
variations on the theme will be specific to individual implementations.</p>
|
|
|
|
<p>When a cycle is detected, the change propagation is ignored. The element
|
|
that detected the second visit ignores the second change notice, and so breaks
|
|
the cycle.</p>
|
|
|
|
<h5>Examples</h5>
|
|
|
|
<p>Example 1: In the following example, the 2 animations define begin times that
|
|
are mutually dependent. There is no way to resolve these, and so the animations will never begin.</p>
|
|
<pre><animate id="foo" begin="bar.begin" .../>
|
|
<animate id="bar" begin="foo.begin" .../></pre>
|
|
|
|
<p>Example 2: In the following example, the 3 animations define a less obvious
|
|
cycle of begin and end times that are mutually dependent. There is no way to
|
|
resolve these. The animation "joe" will begin but will never end, and the
|
|
animations "foo" and "bar" will never begin.</p>
|
|
<pre><animate id="foo" begin="joe.end" .../>
|
|
<animate id="bar" begin="foo.begin" dur="3s" .../>
|
|
<animate id="joe" begin="0" end="bar.end" .../></pre>
|
|
|
|
<p>Example 3: In the following example, the 2 animations define begin times that
|
|
are mutually dependent, but the first has multiple begin conditions that allow
|
|
the cycle to propagate forwards. The animation "foo" will first be
|
|
active from
|
|
0 to 3 seconds, with the second animation "bar" active from 2 to 5 seconds. As
|
|
each new current interval of "foo" and "bar" are created, they will add a new
|
|
instance time to the other element's begin list, and so the cycle keeps going
|
|
forward. As this overlapping "ping-pong" behavior is not otherwise easy to
|
|
author, these types of cycles are not precluded. Moreover, the correct
|
|
behavior will fall out of the model described above.</p>
|
|
<pre><animate id="foo" begin="0; bar.begin+2s" dur="3s" .../>
|
|
<animate id="bar" begin="foo.begin+2s" dur="3s" .../></pre>
|
|
|
|
<p>Example 4: In the following example, an open cycle is described that
|
|
propagates backwards. The intended behavior does not fall out of the model,
|
|
and is not supported.</p>
|
|
<pre><par dur="10s" repeatCount="11" >
|
|
<video id="foo" begin="0; bar.begin-1s" dur="10s" .../>
|
|
<video id="bar" begin="foo.begin-1s" dur="10s" .../>
|
|
</par></pre>
|
|
|
|
<p> </p>
|
|
|
|
<h3><a name="AnimationFunctionValueDetails"></a> 3.7. Animation function value
|
|
details</h3>
|
|
|
|
<p>Animation function values must be legal values for the specified attribute.
|
|
Three classes of values are described:</p>
|
|
<ol>
|
|
<li><strong>Unitless scalar values</strong>. These are simple scalar values
|
|
that can be parsed and set without semantic constraints. This class
|
|
includes integers (base 10) and floating point (format specified by the
|
|
host language).</li>
|
|
<li><strong>String values</strong>. These are simple strings.</li>
|
|
<li><strong>Language abstract values</strong>. These are values like
|
|
CSS-length and CSS-angle values that have more complex parsing, but that
|
|
can yield numbers that may be interpolated.</li>
|
|
</ol>
|
|
|
|
<p>The <code>animate</code> element can interpolate unitless scalar values,
|
|
and both <code>animate</code> and <code>set</code> elements can handle String
|
|
values without any semantic knowledge of the target element or attribute. The
|
|
<code>animate</code> and <code>set</code> elements must support unitless
|
|
scalar values and string values. The host language must define which language
|
|
abstract values should be handled by these elements. Note that the
|
|
<code>animateColor</code> element implicitly handles the abstract values for
|
|
color values, and that the <code>animateMotion</code> element implicitly
|
|
handles position and path values. </p>
|
|
|
|
<p>In order to support interpolation on attributes that define numeric values
|
|
with some sort of units or qualifiers (e.g. "10px", "2.3feet", "$2.99"), some
|
|
additional support is required to parse and interpolate these values. One
|
|
possibility is to require that the animation framework have built-in knowledge
|
|
of the unit-qualified value types. However, this violates the principle of
|
|
encapsulation and does not scale beyond CSS to XML languages that define new
|
|
attribute value types of this form.</p>
|
|
|
|
<p>The recommended approach is for the animation implementation for a given
|
|
host environment to support two interfaces that abstract the handling of the
|
|
language abstract values. These interfaces are not formally specified, but are
|
|
simply described as follows:</p>
|
|
<ol>
|
|
<li>The first interface converts a string (the animation function value) to
|
|
a unitless, canonical number (either an integer or a floating point
|
|
value). This allows animation elements to interpolate between values
|
|
without requiring specific knowledge of data types like CSS-length. The
|
|
interface will likely require a reference to the target attribute, to
|
|
determine the legal abstract values. If the passed string cannot be
|
|
converted to a unitless scalar, the animation element will treat the
|
|
animation function values as strings, and the <code>calcMode</code> will
|
|
default to "discrete".</li>
|
|
<li>The second interface converts a unitless canonical number to a legal
|
|
string value for the target attribute. This may, for example, simply
|
|
convert the number to a string and append a suffix for the canonical
|
|
units. The animation element uses the result of this to actually set the
|
|
presentation value.</li>
|
|
</ol>
|
|
|
|
<p>Support for these two interfaces ensures that an animation engine need not
|
|
replicate the parser and any additional semantic logic associated with
|
|
language abstract values. </p>
|
|
|
|
<p>This is not an attempt to specify how an implementation provides this
|
|
support, but rather a requirement for how values are interpreted. Animation
|
|
behaviors should not have to understand and be able to convert among all the
|
|
CSS-length units, for example. In addition, this mechanism allows for
|
|
application of animation to new XML languages, if the implementation for a
|
|
language can provide parsing and conversion support for attribute values.</p>
|
|
|
|
<p>The above recommendations notwithstanding, it is sometimes useful to
|
|
interpolate values in a specific unit-space, and to apply the result using the
|
|
specified units rather than canonical units. This is especially true for
|
|
certain relative units such as those defined by CSS (e.g. em units). If an
|
|
animation specifies all the values in the same units, an implementation may
|
|
use knowledge of the associated syntax to interpolate in the unit space, and
|
|
apply the result within the animation sandwich, in terms of the specified
|
|
units rather than canonical units. As noted above, this solution does not
|
|
scale well to the general case. Nevertheless, in certain applications (such as
|
|
CSS properties), it may be desirable to take this approach.</p>
|
|
|
|
<h3><a name="BasicSyntaxDTDDefs"></a> 3.8. Common syntax DTD
|
|
definitions</h3>
|
|
|
|
<p><strong>Timing attributes</strong></p>
|
|
<pre class="dtd-fragment"><a name="TimingAttrsEntity"></a><!ENTITY % timingAttrs
|
|
<a href="#BeginAttribute">begin</a> CDATA #IMPLIED
|
|
<a href="#DurAttribute">dur</a> CDATA #IMPLIED
|
|
<a href="#EndActiveAttribute">end</a> CDATA #IMPLIED
|
|
<a href="#RestartAttribute">restart</a> (always | never |
|
|
whenNotActive) "always"
|
|
<a href="#RepeatCountAttribute">repeatCount</a> CDATA #IMPLIED
|
|
<a href="#RepeatDurAttribute">repeatDur</a> CDATA #IMPLIED
|
|
<a href="#FillAttribute">fill</a> (remove | freeze) "remove"
|
|
></pre>
|
|
|
|
<p><strong>Animation attributes</strong></p>
|
|
<pre class="dtd-fragment"><a name="AnimAttrsEntity"></a><!ENTITY % animAttrs
|
|
<a href="#AttributeAttribute">attributeName</a> CDATA #REQUIRED
|
|
<a href="#AttributeTypeAttribute">attributeType</a> CDATA #IMPLIED
|
|
<a href="#AdditiveAttribute">additive</a> (replace | sum) "replace"
|
|
<a href="#AccumulateAttribute">accumulate</a> (none | sum) "none"
|
|
></pre>
|
|
<pre class="dtd-fragment"><a name="AnimTargetAttrEntity"></a><!ENTITY % animTargetAttr
|
|
<a href="#TargetAttribute">targetElement</a> IDREF #IMPLIED
|
|
></pre>
|
|
<pre class="dtd-fragment"><a name="AnimLinkAttrsEntity"></a><!ENTITY % animLinkAttrs
|
|
<a href="#XLinkTypeAttribute">type</a> (simple | extended | locator | arc) #FIXED "simple"
|
|
<a href="#XLinkShowAttribute">show</a> (new | embed | replace) #FIXED 'embed'
|
|
<a href="#XLinkActuateAttribute">actuate</a> (user | auto) #FIXED 'auto'
|
|
<a href="#HrefAttribute">href</a> CDATA #IMPLIED
|
|
></pre>
|
|
|
|
<h2><a name="AnimationElements"></a> 4. Animation elements</h2>
|
|
|
|
<h3><a name="animateElement"></a> 4.1. The animate element</h3>
|
|
|
|
<p>The <strong><code><animate></code></strong> element introduces a
|
|
generic attribute animation that requires little or no semantic understanding
|
|
of the attribute being animated. It can animate numeric scalars as well as
|
|
numeric vectors. It can also animate a single non-numeric attribute through a
|
|
discrete set of values. The <strong><code><animate></code></strong>
|
|
element is an empty element - it cannot have child elements.</p>
|
|
|
|
<p>This element supports from/to/by and values descriptions for the animation
|
|
function, as well as all of the calculation modes. It supports all the
|
|
described timing attributes. These are all described in respective sections
|
|
above.</p>
|
|
<pre class="dtd-fragment"><!ELEMENT animate EMPTY>
|
|
<!ATTLIST animate
|
|
%<a href="#TimingAttrsEntity">timingAttrs</a>
|
|
%<a href="#AnimAttrsEntity">animAttrs</a>
|
|
<a href="#CalcModeAttribute">calcMode</a> (discrete | linear | paced | spline ) "linear"
|
|
<a href="#ValuesAttribute">values</a> CDATA #IMPLIED
|
|
<a href="#KeyTimesAttribute">keyTimes</a> CDATA #IMPLIED
|
|
<a href="#KeySplinesAttribute">keySplines</a> CDATA #IMPLIED
|
|
<a href="#FromAttribute">from</a> CDATA #IMPLIED
|
|
<a href="#ToAttribute">to</a> CDATA #IMPLIED
|
|
<a href="#ByAttribute">by</a> CDATA #IMPLIED
|
|
></pre>
|
|
|
|
<p>Numerous examples are provided above.</p>
|
|
|
|
<h3><a name="setElement"></a> 4.2. The set element</h3>
|
|
|
|
<p>The <code><strong><set></strong></code> element provides a simple
|
|
means of just setting the value of an attribute for a specified duration. As
|
|
with all animation elements, this only manipulates the presentation value, and
|
|
when the animation completes, the effect is no longer applied. That is,
|
|
<code><set></code> does not <em>permanently</em> set the value of the
|
|
attribute. </p>
|
|
|
|
<p>The <code><set></code> element supports all attribute types,
|
|
including those that cannot reasonably be interpolated and that more sensibly
|
|
support semantics of simply setting a value (e.g. strings and Boolean values).
|
|
The <code>set</code> element is non-additive. The additive and accumulate
|
|
attributes are not allowed, and will be ignored if specified.</p>
|
|
|
|
<p>The <code><set></code> element supports all the timing attributes to
|
|
specify the simple and active durations. However, the <code>repeatCount</code>
|
|
and <code>repeatDur</code> attributes will just affect the active duration of
|
|
the <code><set></code>, extending the effect of the
|
|
<code><set></code> (since it is not really meaningful to "repeat" a
|
|
static operation). Note that using <code>fill="freeze"</code> with
|
|
<code><set></code> will have the same effect as defining the timing so
|
|
that the active duration is "indefinite".</p>
|
|
|
|
<p>The <code><set></code> element supports a more restricted set of
|
|
attributes than the <code><animate></code> element (in particular, only
|
|
one value is specified, and no interpolation control is supported):</p>
|
|
<pre class="dtd-fragment"><!ELEMENT set EMPTY>
|
|
<!ATTLIST set
|
|
%<a href="#TimingAttrsEntity">timingAttrs</a>
|
|
<a href="#AttributeAttribute">attributeName</a> CDATA #REQUIRED
|
|
<a href="#AttributeTypeAttribute">attributeType</a> CDATA #IMPLIED
|
|
<a href="#SetElementToAttribute">to</a> CDATA #IMPLIED
|
|
></pre>
|
|
<dl>
|
|
<dt><code><a name="SetElementToAttribute"></a>to</code> <span
|
|
class="argvalue">= "<strong><value></strong>"</span></dt>
|
|
<dd>Specifies the value for the attribute during the duration of the
|
|
<code><set></code> element. The argument value must match the
|
|
attribute type. </dd>
|
|
</dl>
|
|
|
|
<p><strong>Examples</strong></p>
|
|
|
|
<p>The following changes the stroke-width of an SVG rectangle from the
|
|
original value to 5 pixels wide. The effect begins at 5 seconds and lasts for
|
|
10 seconds, after which the original value is again used.</p>
|
|
<pre><rect ...>
|
|
<set attributeName="stroke-width" to="5px"
|
|
begin="5s" dur="10s" fill="remove" />
|
|
</rect></pre>
|
|
|
|
<p>The following example sets the <code>class</code> attribute of the text
|
|
element to the string "highlight" when the mouse moves over the element, and
|
|
removes the effect when the mouse moves off the element. </p>
|
|
<pre><text>This will highlight if you mouse over it...
|
|
<set attributeName="class" to="highlight"
|
|
begin="mouseover" end="mouseout" />
|
|
</text></pre>
|
|
|
|
<h3><a name="animateMotionElement"></a> 4.3. The animateMotion element</h3>
|
|
|
|
<p>The <strong><code><animateMotion></code></strong> element will move
|
|
an element along a path. The element abstracts the notion of motion and
|
|
position across a variety of layout mechanisms - the host language defines the
|
|
layout model and must specify the precise semantics of position and motion.
|
|
The path can be described in several ways:</p>
|
|
<ul>
|
|
<li>Specifying x,y pairs for the <code>from/to/by</code> attributes. These
|
|
will define a straight line motion path.</li>
|
|
<li>Specifying x,y pairs for the <code>values</code> attribute. This will
|
|
define a motion path of straight line segments, or points (if
|
|
<code>calcMode</code> is set to discrete). This will override any
|
|
<code>from/to/by</code> attribute values.</li>
|
|
<li>Specifying a path in the path attribute. This will define a motion path
|
|
using a subset of the SVG path syntax, and provides smooth path motion.
|
|
This will override any <code>from/to/by</code> or <code>values</code>
|
|
attribute values.</li>
|
|
</ul>
|
|
|
|
<p>All values must be x, y value pairs. Each x and y value may specify any
|
|
units supported for element positioning by the host language. The host
|
|
language defines the default units. In addition, the host language defines the
|
|
<em>reference point</em> for positioning an element. This is the point within
|
|
the element that is aligned to the position described by the motion animation.
|
|
The reference point defaults in some languages to the upper left corner of the
|
|
element bounding box; in other languages the reference point may be implicit,
|
|
or may be specified for an element.</p>
|
|
|
|
<p>The syntax for the x, y value pairs is:</p>
|
|
<pre>coordinate-pair ::= ( coordinate <a href="#comma-wspBNF">comma-wsp</a> coordinate )
|
|
coordinate ::= <em>Number</em></pre>
|
|
|
|
<p>Coordinate values are separated by at least one white space character or a
|
|
comma. Additional white space around the separator is allowed. The values of
|
|
<code>coordinate</code> must be defined as some sort of number in the host
|
|
language.</p>
|
|
|
|
<p>The <code>attributeName</code> and <code>attributeType</code> attributes
|
|
are not used with <code>animateMotion</code>, as the manipulated position
|
|
attribute(s) are defined by the host language. If the position is exposed as
|
|
an attribute or attributes that can also be animated (e.g., as "top" and
|
|
"left", or "posX" and "posY"), implementations must combine
|
|
<code><animateMotion></code> animations with other animations that
|
|
manipulate individual position attributes. See also <a
|
|
href="#AnimationSandwichModel">The animation sandwich model</a>.</p>
|
|
|
|
<p>The <strong><code><animateMotion></code></strong> element adds an
|
|
additional syntax alternative for specifying the animation, the
|
|
"<code>path</code>" attribute. This allows the description of a path using a
|
|
subset of the SVG path syntax. Note that if a path is specified, it will
|
|
override any specified values for <code>values</code> or
|
|
<code>from/to/by</code> attributes. </p>
|
|
|
|
<p>As noted in <a href="#AnimFuncValues">Animation function values</a>, if any
|
|
values (i.e., the argument-values for <code>from</code>, <code>to</code>,
|
|
<code>by</code> or <code>values</code> attributes, <em>or</em> for the
|
|
<code>path</code> attribute) are not legal, the animation will have no effect
|
|
(see also <a href="#AnimationSyntaxErrors">Handling Syntax Errors</a>). The
|
|
same is true if none of the <code>from</code>, <code>to</code>,
|
|
<code>by</code>, <code>values</code> or <code>path</code> attributes are
|
|
specified.</p>
|
|
|
|
<p>The default calculation mode (<code>calcMode</code>) for
|
|
<code>animateMotion</code> is "paced". This will produce constant velocity
|
|
motion along the specified path. Note that while animateMotion elements can be
|
|
additive, authors should note that the addition of two or more "paced"
|
|
(constant velocity) animations may not result in a combined motion animation
|
|
with constant velocity.</p>
|
|
<pre class="dtd-fragment"><!ELEMENT animateMotion EMPTY>
|
|
<!ATTLIST animateMotion
|
|
%<a href="#TimingAttrsEntity">timingAttrs</a>
|
|
<a href="#AdditiveAttribute">additive</a> (replace | sum) "replace"
|
|
<a href="#AccumulateAttribute">accumulate</a> (none | sum) "none"
|
|
<a href="#MotionCalcModeAttribute">calcMode</a> (discrete | linear | paced | spline) "paced"
|
|
<a href="#ValuesAttribute">values</a> CDATA #IMPLIED
|
|
<a href="#FromAttribute">from</a> CDATA #IMPLIED
|
|
<a href="#ToAttribute">to</a> CDATA #IMPLIED
|
|
<a href="#ByAttribute">by</a> CDATA #IMPLIED
|
|
<a href="#KeyTimesAttribute">keyTimes</a> CDATA #IMPLIED
|
|
<a href="#KeySplinesAttribute">keySplines</a> CDATA #IMPLIED
|
|
<a href="#MotionPathAttribute">path</a> CDATA #IMPLIED
|
|
<a href="#MotionOriginAttribute">origin</a> (default) "default"
|
|
/></pre>
|
|
<dl>
|
|
<dt><a name="MotionPathAttribute"></a><code>path</code> <span
|
|
class="argvalue">= "<strong><path-description></strong>"</span></dt>
|
|
<dd>Specifies the curve that describes the attribute value as a function
|
|
of time. The supported syntax is a subset of the SVG path syntax.
|
|
Support includes commands to describes lines ("MmLlHhVvZz") and Bezier
|
|
curves ("Cc"). For details refer to the path specification in SVG [<a
|
|
href="#ref-SVG">SVG</a>].
|
|
<p>Note that SVG provides two forms of path commands - "absolute" and
|
|
"relative". These terms may appear to be related to the definition of
|
|
additive animation and/or to the "origin" attribute, but they are
|
|
orthogonal. The terms "absolute" and "relative" apply only to the
|
|
definition of the path itself, and not to the operation of the
|
|
animation. The "relative" commands define a path point relative to the
|
|
previously specified point. The terms "absolute" and "relative" are
|
|
unrelated to the definitions of both "additive" animation and any
|
|
specification of "origin".</p>
|
|
<ul>
|
|
<li>For the "absolute" commands ("MLHVZC"), the host language must
|
|
specify the coordinate system of the path values.</li>
|
|
<li>If the "relative" commands ("mlhvzc") are used, they simply define
|
|
the point as an offset from the previous point on the path. This
|
|
does not affect the definition of "additive" or "origin" for the
|
|
animateMotion element.</li>
|
|
</ul>
|
|
<p>A path data segment must begin with either one of the "moveto"
|
|
commands.</p>
|
|
<dl>
|
|
<dt>Move To commands - "M <x> <y>" or "m <dx>
|
|
<dy>"</dt>
|
|
<dd>Start a new sub-path at the given (x,y) coordinate. If a moveto
|
|
is followed by multiple pairs of coordinates, the subsequent pairs
|
|
are treated as implicit lineto commands.</dd>
|
|
<dt>Line To commands - "L <x> <y>" or "l <dx>
|
|
<dy>"</dt>
|
|
<dd>Draw a line from the current point to the given (x,y) coordinate
|
|
which becomes the new current point. A number of coordinate pairs
|
|
may be specified to draw a polyline.</dd>
|
|
<dt>Horizontal Line To commands - "H <x>" or "h <dx>"</dt>
|
|
<dd>Draws a horizontal line from the current point (cpx, cpy) to (x,
|
|
cpy). Multiple x values can be provided.</dd>
|
|
<dt>Vertical Line To commands - "V <y>" or "v <dy>"</dt>
|
|
<dd>Draws a vertical line from the current point (cpx, cpy) to (cpx,
|
|
y). Multiple y values can be provided.</dd>
|
|
<dt>Closepath commands - "Z" or "z"</dt>
|
|
<dd>The "closepath" causes an automatic straight line to be drawn
|
|
from the current point to the initial point of the current
|
|
subpath.</dd>
|
|
<dt>Cubic Bezier Curve To commands - <br>
|
|
"C <x1> <y1> <x2> <y2> <x> <y>"
|
|
or <br>
|
|
"c <dx1> <dy1> <dx2> <dy2> <dx>
|
|
<dy>"</dt>
|
|
<dd>Draws a cubic Bezier curve from the current point to (x,y) using
|
|
(x1,y1) as the control point at the beginning of the curve and
|
|
(x2,y2) as the control point at the end of the curve. Multiple
|
|
sets of coordinates may be specified to draw a polybezier.</dd>
|
|
</dl>
|
|
<p>When a <code>path</code> is combined with "discrete", "linear" or
|
|
"spline" <code>calcMode</code> settings, 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 does not define an
|
|
additional "segment" for the purposes of timing or interpolation. A
|
|
"move to" command does not count as an additional point when dividing up
|
|
the duration, or when associating <code>keyTimes</code> and
|
|
<code>keySplines</code> values. When a <code>path</code> is combined
|
|
with a "paced" <code>calcMode</code> setting, all "move to" commands are
|
|
considered to have 0 length (i.e., they always happen instantaneously),
|
|
and should not be considered in computing the pacing.<br>
|
|
</p>
|
|
</dd>
|
|
<dt><code><a name="MotionCalcModeAttribute"></a>calcMode</code> </dt>
|
|
<dd>Defined as above in <a href="#AnimFuncCalcMode">Animation function
|
|
calculation modes</a>, but note that the default <code>calcMode</code>
|
|
for <code>animateMotion</code> is "paced". This will produce constant
|
|
velocity motion across the path.
|
|
<p>The use of "discrete" for the <code>calcMode</code> together with a
|
|
"<code>path</code>" specification is allowed, but will simply jump the
|
|
target element from point to point. If the <code>keyTimes</code>
|
|
attribute is not specified, the times are derived from the points in the
|
|
<code>path</code> specification (as described in <a
|
|
href="#AnimFuncCalcMode">Animation function calculation modes</a>).</p>
|
|
<p>The use of "linear" for the <code>calcMode</code> with more than 2
|
|
points described in "<code>values</code>", "<code>path</code>" or
|
|
"<code>keyTimes</code>" may result in motion with varying velocity. The
|
|
"linear" <code>calcMode</code> specifies that time is evenly divided
|
|
among the segments defined by the "<code>values</code>" or
|
|
"<code>path</code>" (note: any "<code>keyTimes</code>" list defines the
|
|
same number of segments). The use of "linear" does not specify that time
|
|
is divided evenly according to the <em>distance</em> described by each
|
|
segment. </p>
|
|
<p>For motion with constant velocity, <code>calcMode</code> should be
|
|
set to "paced".</p>
|
|
<p>For complete velocity control, calcMode can be set to "spline" and
|
|
the author can specify a velocity control spline with
|
|
"<code>keyTimes</code>" and "<code>keySplines</code>".</p>
|
|
</dd>
|
|
<dt><a name="MotionOriginAttribute"></a><code>origin </code><span
|
|
class="argvalue">= "<strong>default</strong>"</span></dt>
|
|
<dd>Specifies the origin of motion for the animation. The values and
|
|
semantics of this attribute are dependent upon the layout and
|
|
positioning model of the host language. In some languages, there may be
|
|
only one option (i.e. "default"). However, in CSS positioning for
|
|
example, it is possible to specify a motion path relative to the
|
|
container block, or to the layout position of the element. It is often
|
|
useful to describe motion relative to the position of the element as it
|
|
is laid out (e.g., from off screen left to the layout position, specified
|
|
as from="(-100, 0)" and to="(0, 0)". Authors must be able to describe
|
|
motion both in this manner, as well as relative to the container block.
|
|
The <code>origin</code> attribute supports this distinction.
|
|
Nevertheless, because the host language defines the layout model, the
|
|
host language must also specify the "default" behavior, as well as any
|
|
additional attribute values that are supported.
|
|
<p>Note that the definition of the layout model in the host language
|
|
specifies whether containers have bounds, and the behavior when an
|
|
element is moved outside the bounds of the layout container. In CSS2 [<a
|
|
href="#ref-CSS2">CSS2</a>], for example, this can be controlled with the
|
|
"clip" property.</p>
|
|
<p>Note that for additive animation, the "origin" distinction is not
|
|
meaningful. This attribute only applies when <code>additive</code> is
|
|
set to "replace".</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
<h3><a name="animateColorElement"></a> 4.4. The animateColor element</h3>
|
|
|
|
<p>The <strong><code><animateColor></code></strong> element specifies an
|
|
animation of a color attribute. The host language must specify those
|
|
attributes that describe color values and can support color animation. </p>
|
|
|
|
<p>All values must represent [<a href="#ref-sRGB">sRGB</a>] color values.
|
|
Legal value syntax for attribute values is defined by the host language. </p>
|
|
|
|
<p>Interpolation is defined on a per-color-channel basis.</p>
|
|
<pre class="dtd-fragment"><!ELEMENT animateColor EMPTY>
|
|
<!ATTLIST animateColor
|
|
%animAttrs
|
|
%timingAttrs
|
|
<a href="#CalcModeAttribute">calcMode</a> (discrete | linear
|
|
| paced | spline ) "linear"
|
|
<a href="#ValuesAttribute">values</a> CDATA #IMPLIED
|
|
<a href="#FromAttribute">from</a> CDATA #IMPLIED
|
|
<a href="#ToAttribute">to</a> CDATA #IMPLIED
|
|
<a href="#ByAttribute">by</a> CDATA #IMPLIED
|
|
<a href="#KeyTimesAttribute">keyTimes</a> CDATA #IMPLIED
|
|
<a href="#KeySplinesAttribute">keySplines</a> CDATA #IMPLIED
|
|
></pre>
|
|
|
|
<p>The values in the <code>from/to/by</code> and <code>values</code>
|
|
attributes may specify negative and out of gamut values for colors. The
|
|
function defined by an individual <code>animateColor</code> may yield negative
|
|
or out of gamut values. The implementation must correct the resulting
|
|
presentation value, to be legal for the destination (display) colorspace.
|
|
However, as described in <a href="#AnimationSandwichModel">The animation
|
|
sandwich model</a>, the implementation should only correct the final combined
|
|
result of all animations for a given attribute, and should not correct the
|
|
effect of individual animations.</p>
|
|
|
|
<p>Values are corrected by "clamping" the values to the correct range. Values
|
|
less than the minimum allowed value are clamped to the minimum value (commonly
|
|
0, but not necessarily so for some color profiles). Values greater than the
|
|
defined maximum are clamped to the maximum value (defined by the host
|
|
language) .</p>
|
|
|
|
<p>Note that color values are corrected by clamping them to the gamut of the
|
|
destination (display) colorspace. Some implementations may be unable to
|
|
process values which are outside the source (sRGB) colorspace and must thus
|
|
perform clamping to the source colorspace, then convert to the destination
|
|
colorspace and clamp to its gamut. The point is to distinguish between the
|
|
source and destination gamuts; to clamp as late as possible, and to realize
|
|
that some devices, such as inkjet printers which appear to be RGB devices,
|
|
have non-cubical gamuts.</p>
|
|
|
|
<p>Note to implementers: When <code>animateColor</code> is specified as a "to
|
|
animation", the animation function should assume Euclidean RGB-cube distance
|
|
where deltas must be computed. See also <a href="#AnimFuncValues">Specifying
|
|
function values</a> and <a href="#FromToByAndAdditive">How from, to and by
|
|
attributes affect additive behavior</a>. Similarly, when the
|
|
<code>calcMode</code> attribute for <code>animateColor</code> is set to
|
|
"paced", the animation function should assume Euclidean RGB-cube distance to
|
|
compute the distance and pacing.</p>
|
|
|
|
<h2><a name="IntegratingSMILAnim"></a> 5. Integrating SMIL Animation into a
|
|
host language</h2>
|
|
|
|
<p>This section describes what a language designer must actually do to specify
|
|
the integration of SMIL Animation into a host language. This includes basic
|
|
definitions, constraints upon animation, and allowed events and supported
|
|
events.</p>
|
|
|
|
<h3><a name="Integrating-RequiredDefs"></a> 5.1. Required host language
|
|
definitions</h3>
|
|
|
|
<p>The host language designer must define some basic concepts in the context
|
|
of the particular host language. These provide the basis for timing and
|
|
presentation semantics.</p>
|
|
|
|
<p>The host language designer must define what "presenting a document" means.
|
|
A typical example is that the document is displayed on a screen.</p>
|
|
|
|
<p>The host language designer must define the <em>document begin</em>.
|
|
Possible definitions are that the document begins when the complete document
|
|
has been received by a client over a network, or that the document begins when
|
|
certain document parts have been received.</p>
|
|
|
|
<p>The host language designer must define the <em>document end</em>. This is
|
|
typically when the associated application exits or switches context to another
|
|
document.</p>
|
|
|
|
<p>A host language should provide a means of uniquely identifying each
|
|
animation element within a document. The facility provided should be the same
|
|
as for the other elements in the language. For example, since SMIL 1.0
|
|
identifies each element with an "id" attribute that contains an XML ID value
|
|
for that element, animation elements added to SMIL 1.0 should also have an
|
|
"id" attribute.</p>
|
|
|
|
<h3><a name="Integrating-ConstraintsOnTargets"></a> 5.2. Required definitions
|
|
and constraints on animation targets</h3>
|
|
|
|
<h4 id="h007">Specifying the target element</h4>
|
|
|
|
<p>The host language designer must choose whether to support the
|
|
<code>targetElement</code> attribute, or the XLink attributes for <a
|
|
href="#SpecifyingTargetElement">specifying the target element</a>. Note that
|
|
if the XLink syntax is used, the host language designer must decide how to
|
|
denote the XLink namespace for the associated attributes. The namespace can be
|
|
fixed in a DTD, or the language designer can require colonized attribute names
|
|
(<em>qnames</em>) to denote the XLink namespace for the attributes. The
|
|
required XLink attributes have fixed values, and so may also be specified in a
|
|
DTD, or can be required on the animation elements. Host language designers may
|
|
require that the optional XLink attributes be specified. These decisions are
|
|
left to the host language designer - the syntax details for XLink attributes
|
|
do not affect the semantics of SMIL Animation.</p>
|
|
|
|
<p>In general, target elements may be any element in the document. Host
|
|
language designers must specify any exceptions to this. Host language
|
|
designers are discouraged from allowing animation elements to target elements
|
|
outside of the document in which the animation element is defined. The XLink
|
|
syntax for the target element could allow this, but the SMIL timing and
|
|
animation semantics of this are not defined in this version of SMIL
|
|
Animation.</p>
|
|
|
|
<h4 id="h008">Target attribute issues</h4>
|
|
|
|
<p>The definitions in this module can be used to animate any attribute of any
|
|
element in a host document. However, it is expected that host language
|
|
designers integrating SMIL Animation may choose to constrain which elements
|
|
and attributes can support animation. For example, a host language may choose
|
|
not to support animation of the <code>language</code> attribute of a
|
|
<code>script</code> element. A host language which included a specification
|
|
for DOM functionality might limit animation to the attributes which may
|
|
legally be modified through the DOM.</p>
|
|
|
|
<p>Any attribute of any element not specifically excluded from animation by
|
|
the host language may be animated, as long as the underlying data type (as
|
|
defined by the host language for the attribute) supports discrete values (for
|
|
discrete animation) and/or addition (for interpolated and additive
|
|
animation).</p>
|
|
|
|
<p>All constraints upon animation must be described in the host language
|
|
specification or in an appropriate schema, as the DTD alone cannot reasonably
|
|
express this.</p>
|
|
|
|
<p>The host language must define which language abstract values should be
|
|
handled for animated attributes. For example, a host language that
|
|
incorporates CSS may require that CSS length values be supported. This is
|
|
further detailed in <a href="#AnimationFunctionValueDetails">Animation
|
|
function value details</a>.</p>
|
|
|
|
<p>The host language must specify the interpretation of relative values. For
|
|
example, if a value is specified as a percentage of the size of a container,
|
|
the host language must specify whether this value will be dynamically
|
|
interpreted as the container size is animated.</p>
|
|
|
|
<p>The host language must specify the semantics of clamping values for
|
|
attributes. The language must specify any defined ranges for values, and how
|
|
out of range values will be handled.</p>
|
|
|
|
<p>The host language must specify the formats supported for numeric attribute
|
|
values. This includes integer values and especially floating point values for
|
|
attributes such as <code>keyTimes</code> and <code>keySplines</code>. As a
|
|
reasonable minimum, host language designers are encouraged to support the
|
|
format described in <a href="#ref-CSS2">[CSS2]</a>. The specific reference
|
|
within the CSS specification for these data types is <a
|
|
href="http://www.w3.org/TR/REC-CSS2/syndata.html#q13">4.3.1 Integers and real
|
|
numbers</a>.</p>
|
|
|
|
<h4 id="h009">Integrating animateMotion functionality</h4>
|
|
|
|
<p>The host language specification must define which elements can be the
|
|
target of <code>animateMotion</code>. In addition, the host language
|
|
specification must describe the positioning model for elements, and must
|
|
describe the model for <code>animateMotion</code> in this context (i.e., the
|
|
semantics of the "default" value for the <code>origin</code> attribute must be
|
|
defined). If there are different ways to describe position, additional
|
|
attribute values for the <code>origin</code> attribute should be defined to
|
|
allow authors control over the positioning model.</p>
|
|
|
|
<h4><a name="WeLoveSVG">Language integration example: SVG</a></h4>
|
|
|
|
<p>As an example, SVG [<a href="#ref-SVG">SVG</a>] integrates SMIL Animation.
|
|
It specifies which of the elements, attributes and CSS properties may be
|
|
animated. Some attributes (e.g. "viewbox" and "fill-rule") support only
|
|
discrete animation, and others (e.g. "width", "opacity" and "stroke") support
|
|
interpolated and additive animation. An example of an attribute that does not
|
|
support any animation is the <code>xlink:actuate</code> attribute on the
|
|
<code><use></code> element.</p>
|
|
|
|
<p>SVG details the format of numeric values, describing the legal ranges and
|
|
allowing "scientific" (exponential) notation for floating point values.</p>
|
|
|
|
<h3><a name="Integrating-ConstraintsOnAttributes"></a> 5.3. Constraints on
|
|
manipulating animation elements</h3>
|
|
|
|
<p>Language designers integrating SMIL Animation are encouraged to disallow
|
|
manipulation of attributes of the animation elements, after the document has
|
|
begun. This includes both the attributes specifying targets and values, as
|
|
well as the timing attributes. In particular, the <code>id</code> attribute
|
|
(of type ID) on all animation elements must not be mutable (i.e. should be
|
|
read-only). Requiring animation runtimes to track changes to <code>id</code>
|
|
values introduces considerable complexity, for what is at best a questionable
|
|
feature.</p>
|
|
|
|
<p>It is recommended that language specifications disallow manipulation of
|
|
animation element attributes through DOM interfaces after the document has
|
|
begun. It is also recommended that language specifications disallow the use
|
|
of animation elements to target other animation elements.</p>
|
|
|
|
<p>Note in particular that if the <code>attributeName</code> attribute can be
|
|
changed (either by animation or script), problems may arise if the target
|
|
attribute has a namespace qualified name. Current DOM specifications do not
|
|
include a mechanism to handle this binding.</p>
|
|
|
|
<p>Dynamically changing the attribute values of animation elements introduces
|
|
semantic complications to the model that are not yet sufficiently resolved.
|
|
This constraint may be lifted in a future version of SMIL Animation.</p>
|
|
|
|
<h3><a name="Integrating-ConstraintsOnElementTiming"></a> 5.4. Required
|
|
definitions and constraints on element timing</h3>
|
|
|
|
<p>This specification assumes that animation elements are the only elements in
|
|
the host language that have timing semantics (this restriction may be removed
|
|
in a future version of SMIL Animation). This specification cannot be used for
|
|
host languages that contain elements with timing semantics. For example, the
|
|
following integration of animation with SMIL 1.0 is illegal with this version
|
|
of SMIL animation:</p>
|
|
<pre><par id="illegalExample">
|
|
<img begin="2s" dur="1m" src="foo.png" alt="Sad face for bad example" />
|
|
<anchor id="anc" href="#bar" coords="0%,0%,50%,50%" dur="30s" />
|
|
<set targetElement="anc" attributeName="coords"
|
|
begin="10s" dur="20s" fill="freeze"
|
|
to="50%,50%,100%,100%" />
|
|
</img>
|
|
</par></pre>
|
|
|
|
<p>The set of "animation elements" that may have timing includes both the
|
|
elements defined in this specification, as well as extension animation
|
|
elements defined in host languages. Extension animation elements must conform
|
|
to the animation framework described in this document. In particular,
|
|
extension animation elements may not be defined to contain other animation
|
|
elements in a way that would introduce hierarchic timing as supported by the
|
|
<code>par</code> and <code>seq</code> elements in SMIL 1.0 [<a
|
|
href="#ref-SMIL">SMIL</a>].</p>
|
|
|
|
<h4 id="h010">Supported events for event-base timing</h4>
|
|
|
|
<p>The host language must specify which event names are legal in event base
|
|
values. If the host language defines no allowed event names, event-based
|
|
timing is effectively precluded for the host language. </p>
|
|
|
|
<p>Host languages may specify that dynamically created events (as per the [<a
|
|
href="#ref-DOM2Events">DOM2Events</a>] specification) are legal as event
|
|
names, and not explicitly list the allowed names.</p>
|
|
|
|
<h3><a name="Integrating-ErrorHandling"></a> 5.5. Error handling
|
|
semantics</h3>
|
|
|
|
<p>The host language designer may impose stricter constraints upon the error
|
|
handling semantics. That is, in the case of syntax errors, the host language
|
|
may specify additional or stricter mechanisms to be used to indicate an error.
|
|
An example would be to stop all processing of the document, or to halt all
|
|
animation.</p>
|
|
|
|
<p>Host language designers may not relax the error handling specifications, or
|
|
the error handling response (as described in <a
|
|
href="#AnimationSyntaxErrors">Handling syntax errors</a>). For example, host
|
|
language designers may not define error recovery semantics for missing or
|
|
erroneous values in the <code>values</code> or <code>keyTimes</code> attribute
|
|
values.</p>
|
|
|
|
<h3><a name="Integrating-SMILAnimNamespace"></a> 5.6. SMIL Animation
|
|
namespace</h3>
|
|
|
|
<p>Language designers can choose to integrate SMIL Animation as an independent
|
|
namespace, or can integrate SMIL Animation names into a new namespace defined
|
|
as part of the host language. Language designers that wish to put the SMIL
|
|
Animation functionality in an isolated namespace should use the following
|
|
namespace:</p>
|
|
|
|
<p><a href="http://www.w3.org/2001/smil-animation">http://www.w3.org/2001/smil-animation</p>
|
|
|
|
<h2><a name="DOMSupport"></a> 6. Document Object Model support</h2>
|
|
|
|
<p>Any XML-based language that integrates SMIL Animation will inherit the
|
|
basic interfaces defined in DOM [<a href="#ref-DOM-Level-2">DOM-Level-2</a>]
|
|
(although not all languages may require a DOM implementation). SMIL Animation
|
|
specifies the interaction of animation and DOM. SMIL Animation also defines
|
|
constraints upon the basic DOM interfaces, and specific DOM interfaces to
|
|
support SMIL Animation.</p>
|
|
|
|
<p>Note that the language designer integrating SMIL Animation must specify any
|
|
constraints upon SMIL Animation with respect to the DOM. This includes the
|
|
specification of language attributes that can or cannot be animated, as well
|
|
as the definition of addition for any attributes that support additive
|
|
animation.</p>
|
|
|
|
<h3><a name="EventModel"></a> 6.1. Events and event model</h3>
|
|
|
|
<p><span class="informative"><em>This section is informative</em></span></p>
|
|
|
|
<p><span class="informative">SMIL event-timing assumes that the host language
|
|
supports events, and that the events can be bound in a declarative manner. DOM
|
|
Level 2 Events [<a href="#ref-DOM2Events">DOM2Events</a>] describes functionality to support this.
|
|
</span></p>
|
|
|
|
<p><span class="normative"><em><span class="informative">This section is
|
|
</span>normative</em> </span></p>
|
|
|
|
<p><span class="normative">The specific events supported are defined by the
|
|
host language. If no events are defined by a host language, event-timing is
|
|
effectively omitted. </span></p>
|
|
|
|
<p><span class="normative">This module defines a set of events that may be
|
|
included by a host language. These include:</span></p>
|
|
<dl class="normative">
|
|
<dt><b>beginEvent</b></dt>
|
|
<dd>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 a DOM method.</dd>
|
|
<dt><b>endEvent</b></dt>
|
|
<dd>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 a
|
|
DOM method.</dd>
|
|
<dt><b>repeat</b></dt>
|
|
<dd>This event is raised when the element local timeline repeats. It will
|
|
be raised each time the element repeats, after the first iteration.
|
|
Associated with the repeat event is an integer that indicates 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 will be >= 1.</dd>
|
|
</dl>
|
|
|
|
<p class="informative">If an element is restarted while it is currently
|
|
playing, the element will raise an <code> endEvent</code> and then a
|
|
<code>beginEvent</code>, as the element restarts.</p>
|
|
|
|
<p class="informative">The <code>beginEvent</code> may not be raised at the
|
|
time that is calculated as the begin for an element. For example the element
|
|
can specify a begin time before the beginning of the document (either with a negative offset value, or with a syncbase time that resolves to
|
|
a time before the document begin). In this case, a time dependent of the <span
|
|
class="ainst-begin ainst">begin</span> syncbase time will be defined relative
|
|
to the calculated begin time. The <code>beginEvent</code>
|
|
will be raise when the element actually begins - in the example case when the
|
|
document begins. Similarly, the <code>endEvent </code>is raised
|
|
when the element actually ends, which may differ from the calculated end time
|
|
(e.g., when the end is specified as a negative offset from a user event). See
|
|
also the discussion <a href="#PropagatingTimes">Propagating changes to
|
|
times</a>.</p>
|
|
|
|
<h3>6.2. <a name="DOM-SupportedMethods">Supported interfaces</a></h3>
|
|
|
|
<p>SMIL Animation supports several methods for controlling the behavior of
|
|
animation: <span
|
|
class="informative"><code>beginElement()</code>,
|
|
<code>beginElementAt(),</code> <code>endElement(),</code> and </span><span
|
|
class="normative"><code>endElementAt()</code>.</span><span class="informative"> </span>
|
|
These methods are used to begin and end the <span class="informative">active duration of an element. Authors can (but are not
|
|
required to) declare the timing to respond to the DOM using the following syntax</span>:</p>
|
|
<pre><animate begin="indefinite" end="indefinite" .../></pre>
|
|
|
|
<p>If a DOM method call is made to begin or end the element (using <code>beginElement()</code>,
|
|
<code>beginElementAt()</code>, <code>endElement()</code> or <code>endElementAt()</code>),
|
|
each method call creates a single instance time (in the appropriate instance
|
|
times list). These times are then interpreted as part of the semantics of lists
|
|
of times, as described in <a href="#Timing-EvaluationOfBeginEndTimeLists">Evaluation
|
|
of begin and end time lists</a>.</p>
|
|
<ul>
|
|
<li><span class="normative">The instance time associated with a </span><code>beginElement()</code>
|
|
or <code>endElement()</code> call <span class="normative"> is the current
|
|
presentation time at the time of the DOM method call.</span></li>
|
|
<li><span class="normative">The instance time associated with a </span><code>beginElementAt()</code>
|
|
or <code></code><code>endElementAt()</code> call <span class="normative">is the current
|
|
presentation time at the time of the DOM method call, plus or minus the
|
|
specified offset.</span></li>
|
|
<li><span class="normative">Note that <code>beginElement()</code> is subject
|
|
to the <span class="ainst-restart ainst">restart</span> attribute in the
|
|
same manner that event-based begin timing is.</span><span class="informative"> Refer also to the
|
|
section</span> <a href="#Restart">Restarting animations</a><span class="informative">.
|
|
</span></li>
|
|
</ul>
|
|
|
|
<p>The expectation of the following interface is that an instance of the
|
|
ElementTimeControl interface can be obtained by using binding-specific casting
|
|
methods on an instance of an animate element. A DOM application can use the
|
|
<code>hasFeature</code> method of the <a
|
|
href="http://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-5CED94D7">DOMImplementation</a>
|
|
interface to determine whether the <a
|
|
href="#ElementTimeControl"><code>ElementTimeControl</code></a> interface is
|
|
supported or not. The feature string for this interface is "TimeControl".</p>
|
|
|
|
<div class="div1">
|
|
|
|
<div class="div2">
|
|
<dl>
|
|
<dt><b>Interface <i><a
|
|
name="ElementTimeControl">ElementTimeControl</a></i></b></dt>
|
|
<dd><dl>
|
|
<dt><br>
|
|
<b>IDL Definition</b></dt>
|
|
<dd>
|
|
<div class="idl-code">
|
|
<pre>interface ElementTimeControl {
|
|
boolean beginElement();
|
|
boolean beginElementAt(in float offset));
|
|
boolean endElement();
|
|
boolean endElementAt(in float offset);
|
|
};</pre>
|
|
</div>
|
|
<p><br>
|
|
</p>
|
|
</dd>
|
|
<dt><b>Methods</b></dt>
|
|
<dd><dl>
|
|
<dt><code class="method-name"><a
|
|
name="beginElement">beginElement</a></code></dt>
|
|
<dd>
|
|
<div class="method">
|
|
Creates a begin instance time for the current time.
|
|
|
|
<div class="return">
|
|
<b>Return Value</b>
|
|
|
|
<div class="returntable">
|
|
|
|
<table border="0">
|
|
<tbody>
|
|
<tr>
|
|
<td valign="top"><code>void</code></td>
|
|
<td></td>
|
|
<td>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<!-- return -->
|
|
<div>
|
|
<b>No Parameters</b></div>
|
|
</div>
|
|
</dd>
|
|
<dt><code class="method-name"><a
|
|
name="beginElementAt">beginElementAt</a></code></dt>
|
|
<dd>
|
|
<div class="method">
|
|
Creates a begin instance time for the current time plus or
|
|
minus the passed offset.
|
|
|
|
<div class="parameters">
|
|
<b>Parameters</b>
|
|
|
|
<div class="paramtable">
|
|
|
|
<table border="0">
|
|
<tbody>
|
|
<tr>
|
|
<td valign="top"><code>float</code></td>
|
|
<td></td>
|
|
<td valign="top"><code>offset</code></td>
|
|
<td></td>
|
|
<td>The offset in seconds at which to begin the
|
|
element.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<!-- parameters -->
|
|
|
|
<div class="return">
|
|
<b>Return Value</b>
|
|
|
|
<div class="returntable">
|
|
|
|
<table border="0">
|
|
<tbody>
|
|
<tr>
|
|
<td valign="top"><code>void</code></td>
|
|
<td></td>
|
|
<td>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<!-- return -->
|
|
</div>
|
|
</dd>
|
|
<dt><code class="method-name"><a
|
|
name="endElement">endElement</a></code></dt>
|
|
<dd>
|
|
<div class="method">
|
|
Creates an end instance time for the current time.
|
|
|
|
<div class="return">
|
|
<b>Return Value</b>
|
|
|
|
<div class="returntable">
|
|
|
|
<table border="0">
|
|
<tbody>
|
|
<tr>
|
|
<td valign="top"><code>void</code></td>
|
|
<td></td>
|
|
<td>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<!-- return -->
|
|
|
|
<div class="parameters">
|
|
<b>No Parameters</b>
|
|
</div>
|
|
</div>
|
|
</dd>
|
|
<dt><code class="method-name"><a
|
|
name="endElementAt">endElementAt</a></code></dt>
|
|
<dd>
|
|
<div class="method">
|
|
Creates an end instance time for the current time plus or
|
|
minus the passed offset.
|
|
|
|
<div class="parameters">
|
|
<b>Parameters</b>
|
|
|
|
<div class="paramtable">
|
|
|
|
<table border="0">
|
|
<tbody>
|
|
<tr>
|
|
<td valign="top"><code>float</code></td>
|
|
<td></td>
|
|
<td valign="top"><code>offset</code></td>
|
|
<td></td>
|
|
<td>The offset in seconds at which to end the element.
|
|
Must be >= 0.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<!-- parameters -->
|
|
|
|
<div class="return">
|
|
<b>Return Value</b>
|
|
|
|
<div class="returntable">
|
|
|
|
<table border="0">
|
|
<tbody>
|
|
<tr>
|
|
<td valign="top"><code>void</code></td>
|
|
<td></td>
|
|
<td>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<!-- return -->
|
|
|
|
</div>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><b>Interface <i><a name="Events-TimeEvent">TimeEvent</a></i></b></dt>
|
|
<dd>The <code>TimeEvent</code> interface provides specific contextual
|
|
information associated with Time events.
|
|
<dl>
|
|
<dt><br>
|
|
<b>IDL Definition</b></dt>
|
|
<dd>
|
|
<div class="idl-code">
|
|
<pre>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);
|
|
};</pre>
|
|
</div>
|
|
<p><br>
|
|
</p>
|
|
</dd>
|
|
<dt><b>Attributes</b></dt>
|
|
<dd><dl>
|
|
<dt><code class="attribute-name"><a
|
|
name="Events-TimeEvent-view">view</a></code> of type
|
|
<code>views::AbstractView</code>, readonly</dt>
|
|
<dd>The <code>view</code> attribute identifies the
|
|
<code>AbstractView</code> from which the event was
|
|
generated.
|
|
<p> </p>
|
|
</dd>
|
|
<dt><code class="attribute-name">detail</code> of type
|
|
<code>long</code>, readonly</dt>
|
|
<dd>Specifies some detail information about the
|
|
<code>Event</code>, depending on the type of event.
|
|
<p> </p>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><b>Methods</b></dt>
|
|
<dd><dl>
|
|
<dt><code class="method-name"><a
|
|
name="Events-Event-initTimeEvent">initTimeEvent</a></code></dt>
|
|
<dd>
|
|
<div class="method">
|
|
The <code>initTimeEvent</code> method is used to initialize
|
|
the value of a <code>TimeEvent</code> created through the
|
|
<code>DocumentEvent</code> interface. This method may only
|
|
be called before the <code>TimeEvent</code> has been
|
|
dispatched via the <code>dispatchEvent</code> method, though
|
|
it may be called multiple times during that phase if
|
|
necessary. If called multiple times, the final invocation
|
|
takes precedence.
|
|
|
|
<div class="parameters">
|
|
<b>Parameters</b>
|
|
|
|
<div class="paramtable">
|
|
|
|
<table border="0">
|
|
<tbody>
|
|
<tr>
|
|
<td valign="top"><code>DOMString</code></td>
|
|
<td></td>
|
|
<td valign="top"><code>typeArg</code></td>
|
|
<td></td>
|
|
<td>Specifies the event type.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><code>views::AbstractView</code></td>
|
|
<td></td>
|
|
<td valign="top"><code>viewArg</code></td>
|
|
<td></td>
|
|
<td>Specifies the <code>Event</code>'s
|
|
<code>AbstractView</code>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><code>long</code></td>
|
|
<td></td>
|
|
<td valign="top"><code>detailArg</code></td>
|
|
<td></td>
|
|
<td>Specifies the <code>Event</code>'s detail.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<!-- parameters -->
|
|
|
|
<div>
|
|
<b>No Return Value</b></div>
|
|
|
|
<div>
|
|
<b>No Exceptions</b></div>
|
|
<p> </p>
|
|
</div>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>The different types of events that can occur are:</p>
|
|
<dl>
|
|
<dt><b>begin</b></dt>
|
|
<dd>Raised when the element begins. See also <a href="#EventModel">Events
|
|
and event model</a>.
|
|
<ul>
|
|
<li>Bubbles: No</li>
|
|
<li>Cancelable: No</li>
|
|
<li>Context Info: None</li>
|
|
</ul>
|
|
</dd>
|
|
<dt><b>end</b></dt>
|
|
<dd>Raised when the element ends its active duration. See also <a href="#EventModel">Events
|
|
and event model</a>.
|
|
<ul>
|
|
<li>Bubbles: No</li>
|
|
<li>Cancelable: No</li>
|
|
<li>Context Info: None</li>
|
|
</ul>
|
|
</dd>
|
|
<dt><b>repeat</b></dt>
|
|
<dd>Raised when the element repeats. See also <a href="#EventModel">Events
|
|
and event model</a>.
|
|
<ul>
|
|
<li>Bubbles: No</li>
|
|
<li>Cancelable: No</li>
|
|
<li>Context Info: detail (current iteration)</li>
|
|
</ul>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<!-- div2 -->
|
|
</div>
|
|
<!-- div1 -->
|
|
|
|
<h3><a name="DOM-IDL"></a> 6.3. IDL definition</h3>
|
|
|
|
<h4><a name="smil-idl">smil.idl:</a></h4>
|
|
|
|
<div class="idl-code">
|
|
<pre>// File: smil.idl
|
|
#ifndef _SMIL_IDL_
|
|
#define _SMIL_IDL_
|
|
|
|
#include "dom.idl"
|
|
|
|
#pragma prefix "dom.w3c.org"
|
|
module smil
|
|
{
|
|
typedef dom::DOMString DOMString;
|
|
|
|
interface ElementTimeControl {
|
|
void beginElement();
|
|
void beginElementAt(in float offset);
|
|
void endElement();
|
|
void endElementAt(in float offset);
|
|
};
|
|
|
|
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);
|
|
};
|
|
};
|
|
|
|
#endif // _SMIL_IDL_</pre>
|
|
</div>
|
|
|
|
<h3><a name="DOM-Java"></a> 6.4. Java language binding</h3>
|
|
|
|
<div class="div1">
|
|
|
|
<div class="div2">
|
|
<h3><a name="SMIL-Java-ElementTimeControl">org/w3c/dom/smil/ElementTimeControl.java:</a></h3>
|
|
|
|
<div class="java-code">
|
|
<pre>package org.w3c.dom.smil;
|
|
|
|
import org.w3c.dom.DOMException;
|
|
|
|
public interface ElementTimeControl {
|
|
public void beginElement();
|
|
|
|
public void beginElementAt(float offset);
|
|
|
|
public void endElement();
|
|
|
|
public void endElementAt(float offset);
|
|
|
|
}</pre>
|
|
</div>
|
|
|
|
<h3><a name="SMIL-Java-TimeEvent">org/w3c/dom/smil/TimeEvent.java:</a></h3>
|
|
|
|
<div class="java-code">
|
|
<pre>package org.w3c.dom.smil;
|
|
|
|
import org.w3c.dom.events.Event;
|
|
import org.w3c.dom.views.AbstractView;
|
|
|
|
public interface TimeEvent extends Event {
|
|
public AbstractView getView();
|
|
|
|
public int getDetail();
|
|
|
|
public void initTimeEvent(String typeArg,
|
|
AbstractView viewArg,
|
|
int detailArg);
|
|
|
|
}</pre>
|
|
</div>
|
|
</div>
|
|
<!-- div2 -->
|
|
</div>
|
|
<!-- div1 -->
|
|
|
|
<h3><a name="DOM-ECMA"></a> 6.5. ECMAScript language binding</h3>
|
|
|
|
<div class="ecma-block">
|
|
<dl>
|
|
<dt>Object <b>ElementTimeControl</b></dt>
|
|
<dd><dl>
|
|
<dt>The <b>ElementTimeControl</b> object has the following
|
|
methods:</dt>
|
|
<dd><dl>
|
|
<dt><b>beginElement()</b></dt>
|
|
<dd>This method returns a <b>void</b>.</dd>
|
|
<dt><b>beginElementAt(offset)</b></dt>
|
|
<dd>This method returns a <b>void</b>. The <b>offset</b>
|
|
parameter is of type <b>float</b>.</dd>
|
|
<dt><b>endElement()</b></dt>
|
|
<dd>This method returns a <b>void</b>.</dd>
|
|
<dt><b>endElementAt(offset)</b></dt>
|
|
<dd>This method returns a <b>void</b>. The <b>offset</b>
|
|
parameter is of type <b>float</b>.</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt>Object <b>TimeEvent</b></dt>
|
|
<dd><dl>
|
|
<dt><b>TimeEvent</b> has all the properties and methods of
|
|
<b>Event</b> as well as the properties and methods defined below.</dt>
|
|
<dt>The <b>TimeEvent</b> object has the following properties:</dt>
|
|
<dd><dl>
|
|
<dt><b>view</b></dt>
|
|
<dd>This property is of type <b>AbstractView</b>.</dd>
|
|
<dt><b>detail</b></dt>
|
|
<dd>This property is of type <b>long</b>.</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt>The <b>TimeEvent</b> object has the following methods:</dt>
|
|
<dd><dl>
|
|
<dt><b>initTimeEvent(typeArg, viewArg, detailArg)</b></dt>
|
|
<dd>This method returns a <b>void</b>. The <b>typeArg</b>
|
|
parameter is of type <b>DOMString</b>. The <b>viewArg</b>
|
|
parameter is of type <b>views::AbstractView</b>. The
|
|
<b>detailArg</b> parameter is of type <b>long</b>.</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p><br>
|
|
</p>
|
|
</div>
|
|
|
|
<p> </p>
|
|
|
|
<h2><a name="Appendix-DifferencesFromSMIL1"></a> 7. Appendix: Differences from
|
|
SMIL 1.0 timing model</h2>
|
|
<ul>
|
|
<li>No time containers supported - does not support <code><seq></code>
|
|
and <code><par></code></li>
|
|
<li>Renamed "element-event" concept to "syncbase value", changed
|
|
syntax.</li>
|
|
<li>Added event-based timing support for <code>begin</code> and
|
|
<code>end</code> attributes.</li>
|
|
<li>Added hyperlink activation support to <code>begin</code> attribute.</li>
|
|
<li>Support DOM methods for activation of <code>begin</code> and
|
|
<code>end</code> attributes, and for <code>begin</code>, <code>end</code>
|
|
and <code>repeat</code> events.</li>
|
|
<li>Modified <code>end</code> attribute semantics to align with SMIL 2.0.</li>
|
|
<li>Added <code>repeatCount</code> and <code>repeatDur</code> and omitted
|
|
<code>repeat</code>. This aligns with SMIL 2.0.</li>
|
|
<li>Syncbase-value (offset) can exceed duration of syncbase element</li>
|
|
<li>Tweaked Clock value definition to support >24 hours.</li>
|
|
</ul>
|
|
|
|
<h2><a name="References"></a> 8. References</h2>
|
|
<dl>
|
|
<dt><a name="ref-CSS2"></a><strong>[CSS2]</strong></dt>
|
|
<dd>"Cascading Style Sheets, level 2", B. Bos, H. W. Lie, C. Lilley, I.
|
|
Jacobs, 12 May 1998.<br>
|
|
Available at <a
|
|
href="http://www.w3.org/TR/REC-CSS2">http://www.w3.org/TR/REC-CSS2</a>.</dd>
|
|
<dt><a name="ref-COMP-GRAPHICS"></a><strong>[COMP-GRAPHICS]</strong></dt>
|
|
<dd>"Computer Graphics : Principles and Practice, Second Edition", James
|
|
D. Foley, Andries van Dam, Steven K. Feiner, John F. Hughes, Richard L.
|
|
Phillips, Addison-Wesley, pp. 488-491.</dd>
|
|
<dt><a class="normref" name="ref-DATETIME"></a>[DATETIME]</dt>
|
|
<dd>"Date and Time Formats", M. Wolf, C. Wicksteed. W3C Note 27
|
|
August 1998,<br>
|
|
Available at: <a href="http://www.w3.org/TR/NOTE-datetime">http://www.w3.org/TR/NOTE-datetime</a></dd>
|
|
<dt><a class="normref"
|
|
name="ref-DOM-Level-2"></a><strong>[DOM-Level-2]</strong></dt>
|
|
<dd>"Document Object Model (DOM) Level 2 Core Specification"<br>
|
|
Available at <a
|
|
href="http://www.w3.org/TR/DOM-Level-2-Core/">http://www.w3.org/TR/DOM-Level-2/</a>.</dd>
|
|
<dt><strong><a name="ref-DOM-CSS"></a>[DOM2CSS]</strong></dt>
|
|
<dd>"Document Object Model CSS"<br>
|
|
Available at <a
|
|
href="http://www.w3.org/TR/DOM-Level-2-Style/css.html">http://www.w3.org/TR/DOM-Level-2-Style/css.html</a>.</dd>
|
|
<dt><a class="normref"
|
|
name="ref-DOM2Events"></a><strong>[DOM2Events]</strong></dt>
|
|
<dd>"Document Object Model Events", T. Pixley<br>
|
|
Available at <a
|
|
href="http://www.w3.org/TR/DOM-Level-2-Events/events.html">http://www.w3.org/TR/DOM-Level-2-Events/events.html</a>.</dd>
|
|
<dt><a name="ref-HTML40" class="normref"></a><strong>[HTML]</strong></dt>
|
|
<dd>"HTML 4.01 Specification", D. Raggett, A. Le Hors, I. Jacobs, 24
|
|
December 1999.<br>
|
|
Available at <a
|
|
href="http://www.w3.org/TR/REC-html40">http://www.w3.org/TR/REC-html40</a>.</dd>
|
|
<dt><A class=normref name=ref-iso8601></a><strong>[ISO8601]</strong></dt>
|
|
<dd>"Data elements and interchange formats - Information interchange -
|
|
Representation of dates and times", International Organization for
|
|
Standardization, 1998. </dd>
|
|
<DT><STRONG><A class=normref name=ref-ISO10646></A>[ISO10646]</STRONG> </dt>
|
|
<DD>""Information Technology -- Universal Multiple-Octet Coded Character Set
|
|
(UCS) -- Part 1: Architecture and Basic Multilingual Plane", ISO/IEC
|
|
10646-1:1993. This reference refers to a set of codepoints that may evolve as
|
|
new characters are assigned to them. This reference therefore includes future
|
|
amendments as long as they do not change character assignments up to and
|
|
including the first five amendments to ISO/IEC 10646-1:1993. Also, this
|
|
reference assumes that the character sets defined by ISO 10646 and Unicode
|
|
remain character-by-character equivalent. This reference also includes future
|
|
publications of other parts of 10646 (i.e., other than Part 1) that define
|
|
characters in planes 1-16. " </DD>
|
|
<dt><a name="ref-SMIL"></a><strong>[SMIL1.0]</strong></dt>
|
|
<dd>"Synchronized Multimedia Integration Language (SMIL) 1.0 Specification
|
|
W3C Recommendation 15-June-1998 ". <br>
|
|
Available at: <a
|
|
href="http://www.w3.org/TR/REC-smil">http://www.w3.org/TR/REC-smil</a>.</dd>
|
|
<dt><strong><a name="ref-SMIL20"></a>[SMIL20]</strong></dt>
|
|
<dd>"Synchronized Multimedia Integration Language (SMIL 2.0)
|
|
Specification", <br>
|
|
W3C SYMM (Proposed Recommendation). <br>
|
|
Available at <a href="http://www.w3.org/TR/smil20/">http://www.w3.org/TR/smil20/</a></dd>
|
|
<dt><a name="ref-SYMM-MOD"
|
|
class="normref"></a><strong>[SMIL-MOD]</strong></dt>
|
|
<dd>"Synchronized Multimedia Modules based upon SMIL 1.0", Patrick
|
|
Schmitz, Ted Wugofski, Warner ten Kate. <br>
|
|
Available at <a
|
|
href="http://www.w3.org/TR/NOTE-SYMM-modules">http://www.w3.org/TR/NOTE-SYMM-modules</a>.</dd>
|
|
<dt><a name="ref-sRGB"></a>[sRGB]</dt>
|
|
<dd>IEC 61966-2-1 (1999-10) - "Multimedia systems and equipment - Colour
|
|
measurement and management - Part 2-1: Colour management - Default RGB
|
|
colour space - sRGB", ISBN: 2-8318-4989-6 ICS codes: 33.160.60, 37.080
|
|
TC 100 51 pp. <br>
|
|
Available at: <a
|
|
href="http://www.iec.ch/nr1899.htm">http://www.iec.ch/nr1899.htm</a>.</dd>
|
|
<dt><a name="ref-SVG" class="normref"></a><strong>[SVG]</strong></dt>
|
|
<dd>"Scalable Vector Graphics (SVG) 1.0 Specification", W3C Proposed Recommendation, 19 July 2001.
|
|
<br>
|
|
Available at <a
|
|
href="http://www.w3.org/TR/SVG/">http://www.w3.org/TR/SVG/</a>.</dd>
|
|
<dt><a name="ref-XLink"></a><strong>[XLink]</strong></dt>
|
|
<dd>"XML Linking Language (XLink)", S. DeRose, E. Maler, D. Orchard,
|
|
editors, 27 June 2001.<br>
|
|
Available at <a
|
|
href="http://www.w3.org/TR/xlink/">http://www.w3.org/TR/xlink</a></dd>
|
|
<dt><a name="ref-XML10" class="normref"></a><strong>[XML]</strong></dt>
|
|
<dd>"Extensible Markup Language (XML) 1.0", T. Bray, J. Paoli, C.M.
|
|
Sperberg-McQueen, Eve Maler, editors, 6 October 2000. <br>
|
|
Available at <a
|
|
href="http://www.w3.org/TR/REC-xml">http://www.w3.org/TR/REC-xml</a></dd>
|
|
<dt><a name="ref-XML-NS"></a><strong>[XML-NS]</strong></dt>
|
|
<dd>"Namespaces in XML" T. Bray, D. Hollander, A. Layman, editors, 14
|
|
January 1999.<br>
|
|
Available at <a
|
|
href="http://www.w3.org/TR/REC-xml-names/">http://www.w3.org/TR/REC-xml-names/</a>.</dd>
|
|
</dl>
|
|
|
|
<p></p>
|
|
<hr>
|
|
</body>
|
|
</html>
|