W3C

Synchronized Multimedia Integration Language (SMIL 2.0) Specification

W3C Working Draft 21 September 2000

This version:
http://www.w3.org/TR/2000/WD-smil20-20000921/
(Other formats: single HTML file, zip archive)
Latest version:
http://www.w3.org/TR/smil20
Previous version:
http://www.w3.org/TR/2000/WD-smil-boston-20000622
Editors:
Jeff Ayars (RealNetworks), Dick Bulterman (Oratrix), Aaron Cohen (Intel), Ken Day (Macromedia), Erik Hodge (RealNetworks), Philipp Hoschka (W3C), Eric Hyche (RealNetworks), Muriel Jourdan (INRIA), Kenichi Kubota (Panasonic), Rob Lanphier (RealNetworks), Nabil Layaïda (INRIA), Philippe Le Hégaret (W3C), Thierry Michel (W3C), Debbie Newman (Microsoft), Jacco van Ossenbruggen (CWI), Lloyd Rutledge (CWI), Bridie Saccocio (RealNetworks), Patrick Schmitz (Microsoft), Warner ten Kate (Philips).

Copyright ©2000 W3C® (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.

Abstract

This document specifies the second version of the Synchronized Multimedia Integration Language (SMIL, pronounced "smile"). SMIL 2.0 has the following two design goals:

Status of this document

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.

This is the Last-Call public Working Draft of SMIL 2.0 specification, issued by the SYMM Working Group [members only], for review by the public, by members and working groups of the World Wide Web Consortium.

This document has been produced as part of the W3C Synchronized Multimedia Activity of the W3C User Interface Domain. The goals of the SYMM Working Group are discussed in the SYMM Working Group charter [members only], (revised July 2000 from original charter version).

This Working Draft incorporates all Working Group decisions through 2000-09-15. It has been reviewed by the SYMM Working Group, and the Working Group has agreed to its publication as a Last Call draft. The Last Call period is expected to end 20 October 2000. Following this Last Call for Review, the Working Group intends to submit this specification for publication as a Candidate Recommendation.

This schedule may vary, depending on the comments of the public and of other W3C working groups on this draft. Such comments are instrumental in the WG's deliberations, and we encourage readers to review the draft and to send comments to www-smil@w3.org. An archive of the comments received is available.

Although the Working Group does not anticipate further changes to the functionality described here, this is still a working draft, subject to change. The present version should be implemented only by those interested in providing a check on its design or by those preparing for an implementation of the Candidate Recommendation. The SYMM WG will not allow early implementation to constrain its ability to make changes to this specification prior to final release.

The XHTML+SMIL Profile which appeared in previous working drafts is still in progress and not yet ready for Last Call. It continues to be updated and will be published as a separate Last Call specification when it is ready. Refer to the available public working draft version of that profile.

This working draft may be updated, replaced or rendered obsolete by other W3C documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". This document is work in progress and does not imply endorsement by the W3C membership.

A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR.

Quick Table of Contents

Full Table of Contents

1. About SMIL 2.0

Editors
Aaron Cohen (aaron.m.cohen@intel.com), Intel
Thierry Michel (tmichel@w3.org), W3C

1.1 Introduction

This document specifies the second version of the Synchronized Multimedia Integration Language (SMIL, pronounced "smile"). SMIL 2.0 has the following two design goals:

SMIL 2.0 is defined as a set of markup modules, which define the semantics and an XML syntax for certain areas of SMIL functionality.

1.1.1 Relation to SMIL 1.0

SMIL 2.0 deprecates a small amount of SMIL 1.0 syntax in favor of more DOM friendly syntax. Most notable is the change from hyphenated attribute names to mixed case (camel case) attribute names, e.g., clipBegin is introduced in favor of clip-begin. The SMIL 2.0 modules do not require support for these SMIL 1.0 attributes so that integration applications are not burdened with them. SMIL document players, those applications that support playback of "application/smil" documents (or however we denote SMIL documents vs. integration documents) must support the deprecated SMIL 1.0 attribute names as well as the new SMIL 2.0 names.

1.1.2 Content of this specification

This specification is structured as a set of sections, each defining one or more modules:

This specification also defines two profiles that are built using the above SMIL 2.0 modules:

The XHTML+SMIL Profile which appeared in previous working drafts is still in progress and not yet ready for Last Call. It continues to be updated and will be published as a separate Last Call specification when it is ready. Refer to the available public working draft version of that profile.

1.2 Acknowledgements

This document has been prepared by the Synchronized Multimedia Working Group (SYMM-WG) of the World Wide Web Consortium. The WG includes the following individuals:

Jin Yu, Compaq - Pietro Marchisio, CSELT - Lynda Hardman, CWI - Jacco van Ossenbruggen, CWI - Lloyd Rutledge, CWI - Olivier Avaro, France Telecom - Ted Wugofski, Gateway (Invited Expert) - Masayuki Hiyama, Glocomm - Keisuke Kamimura, Glocomm - Michelle Y. Kim, IBM - Steve Wood, IBM - Nabil Layaïda, INRIA - Muriel Jourdan, INRIA - Aaron Cohen, Intel - Wayne Carr, Intel - Ken Day, Macromedia - Daniel Weber, Panasonic - Patrick Schmitz, Microsoft - Debbie Newman, Microsoft - Pablo Fernicola, Microsoft - Kevin Gallo, Microsoft - Don Cone, Netscape/AOL - Wo Chang, NIST - Didier Chanut, Nokia - Jack Jansen, Oratrix - Sjoerd Mullender, Oratrix - Dick Bulterman, Oratrix - Kenichi Kubota, Panasonic - Warner ten Kate, Philips - Ramon Clout, Philips - Jeff Ayars, RealNetworks - Erik Hodge, RealNetworks - Rob Lanphier, RealNetworks - Bridie Saccocio, RealNetworks - Eric Hyche, RealNetworks - Geoff Freed, WGBH - Philipp Hoschka, W3C - Philippe Le Hégaret, W3C - Thierry Michel, W3C.

2. The SMIL 2.0 Modules

Editors:
Warner ten Kate (warner.ten.kate@philips.com), (Philips Electronics)
Aaron Cohen (aaron.m.cohen@intel.com), (Intel)
Philipp Hoschka (ph@w3.org), (W3C)

2.1 Introduction

This section is informative.

Since the publication of SMIL 1.0 [SMIL10], interest in the integration of SMIL concepts with the HTML, the HyperText Markup Language [HTML4], and other XML languages, has grown. Likewise, the W3C HTML Working Group has specified XHTML, the Extensible HyperText Markup Language [XHTML10], in preparation to subset, extend, and integrate it with other languages. The strategy considered for integrating respective functionality with other XML-based languages is based on the concepts of modularization and profiling [SMIL-MOD], [XMOD].

Modularization is an approach in which markup functionality is specified as a set of modules that contain semantically-related XML elements, attributes, and attribute values. Profiling is the creation of an XML-based language through combining these modules, in order to provide the functionality required by a particular application.

Profiling introduces the ability to tailor an XML-based language to specific needs, e.g. to optimize presentation and interaction for the client's capabilities. Profiling also adds the ability for integrating functionality from other markup languages, releasing the language designer from specifying that functionality. Moreover, it provides for consistency in markup through the use of the same model to incorporate a function. Identical constructs eases authoring, while at the user agent side there is a potential for re-use of code. For example, a scheduler supporting SMIL timing and synchronization functionality could be used for SMIL documents, XHTML+SMIL documents, and SVG documents.

Modularization enables language designers to specify dedicated markup intended for integration with other, existing, language profiles. Examples of specifications intended for such integration are MathML and XForms [MathML], [XFORMS].

Modularization and profiling use the extensibility properties of XML, and related technology like XML-namespaces and XML Schema [XML10], [XML-NS], [XSCHEMA].

This part of the SMIL 2.0 specification describes the framework on which SMIL modularization and profiling is based, and specifies the SMIL 2.0 Modules, their identifiers, and the requirements for conformance within this framework.

2.1.1 Modularization and Profiling

This section is informative.

The modularization approach used in this specification derives from that set forth in XHTML Modularization [XMOD]. The framework on which SMIL Modularization and Profiling is based, is informally described here.

A Module is a collection of semantically-related XML elements, attributes, and attribute values that represents a unit of functionality. Modules are defined in coherent sets. This coherency is expressed in that the elements of these modules are associated with the same namespace.

A Language Profile is a combination of modules. Modules are atomic, i.e. they cannot be subset when included in a language profile. Furthermore, a module specification may include a set of integration requirements, to which language profiles that include the module must comply.

Commonly, there is a main language profile that incorporates nearly all the modules associated with a single namespace. For example, the SMIL 2.0 language profile uses most of the SMIL 2.0 modules. Usually, the same name is used to loosely reference both; "SMIL 2.0" in the example. Also, the name "profile" is used to mean "language profile".

Other language profiles can be specified that are subsets of the larger one, or that incorporate a mixture of modules associated with different namespaces. SMIL 2.0 Basic is an example of the first, XHTML+SMIL of the latter.

A special module in a language profile is the so-called Structure Module, in that it contains the root element of the language profile, e.g. <smil> or <html>. Any language profile that incorporates modules associated with a single namespace will include the Structure module associated with that namespace.

Other modules that require special mention are those that characterize the core of the functionality provided by the namespace. This is expressed by the notions of host language and integration set. Both of them relate to a set of conformance requirements for language profiles, which includes the requirement to incorporate at least the core set of modules. The set may be different for a host language and an integration set. A host language must incorporate the Structure module; an integration set does not. There may be other differences as well.

The main purpose of language profile conformance is to enhance interoperability. Preferably, the mandatory modules for host language conformance are defined in such a way that any document interchanged in a conforming language profile will yield a reasonable presentation when the document renderer, while supporting the associated mandatory module set, would ignore all other (unknown) elements and attributes. Here, "reasonable presentation" is to be understood as something intelligible, which is not necessarily a close reflection of the author's original intentions. To achieve the latter, a negotiation would have to be conducted to agree on the specific language profile to be used for the document interchange.

2.2 SMIL 2.0 Modules

This section is normative.

SMIL functionality is partitioned into eleven functional areas. Within each functional area a further partitioning is applied into modules. All of these modules, and only these modules, are associated with the SMIL namespace.

The functional areas and their corresponding modules are:

  1. Timing
    1. BasicInlineTiming
    2. MinMaxTiming
    3. SyncbaseTiming
    4. EventTiming
    5. WallclockTiming
    6. MultiArcTiming
    7. MediaMarkerTiming
    8. AccessKeyTiming
    9. BasicTimeContainers
    10. ExclTimeContainers
    11. TimeContainerAttributes
    12. PrevTiming
    13. RestartTiming
    14. SyncBehavior
    15. SyncBehaviorDefault
    16. SyncMaster
    17. RestartDefault
    18. FillDefault
  2. Time Manipulations
    1. TimeManipulations
  3. Animation
    1. BasicAnimation
    2. SplineAnimation
  4. Content Control
    1. BasicContentControl
    2. CustomTestAttributes
    3. PrefetchControl
    4. SkipContentControl
  5. Layout
    1. BasicLayout
    2. AudioLayout
    3. MultiWindowLayout
    4. HierarchicalLayout
  6. Linking
    1. LinkingAttributes
    2. BasicLinking
    3. ObjectLinking
  7. Media Objects
    1. BasicMedia
    2. MediaClipping
    3. MediaClipMarkers
    4. MediaParam
    5. BrushMedia
    6. MediaAccessibility
  8. Metainformation
    1. Metainformation
  9. Structure
    1. Structure
  10. Transitions
    1. BasicTransistions
    2. InlineTransitions
    3. TransitionModifiers
    4. CoordinatedTransitions

This section is informative.

Each of these modules introduces a set of semantically-related elements, properties, and attributes. Each functional area has a corresponding section in this specification document. Further details on each of the modules is specified within those sections.

The modules may be independent or complementary. For example, the SyncbaseTiming module requires and builds upon the BasicInlineTiming module, but the PrefetchControl and SkipContentControl modules are independent from each other. In addition, some modules require modules from other functional areas.

Modules specify their integration requirements. When one module requires another module for basic features and as a prerequisite for integration, a language profile must include the second module in order to include the first. The first module is said to be a dependent of the second module. Dependency may be nested, in that a module may be dependent on a module that is dependent itself.

Table 1 presents the SMIL 2.0 modules and the modules they dependent on.

Table 1: The SMIL 2.0 Modules and their Dependencies.
Module Dependencies
AccessKeyTiming BasicInlineTiming
AudioLayout BasicLayout
BasicAnimation BasicInlineTiming
BasicContentControl NONE
BasicInlineTiming NONE
BasicLayout NONE
BasicLinking NONE
BasicMedia NONE
BasicTimeContainers BasicInlineTiming
BasicTransitions BasicInlineTiming, and
BasicMedia
BrushMedia NONE
CoordinatedTransitions BasicTransitions
CustomTestAttributes BasicContentControl
EventTiming NONE
ExclTimeContainers BasicTimeContainers
FillDefault BasicTimeContainers
HierarchicalLayout BasicLayout
InlineTransitions BasicInlineTiming, and
BasicMedia
LinkingAttributes NONE
MediaAccessibility BasicMedia
MediaClipMarkers MediaClipping
MediaClipping BasicMedia
MediaMarkerTiming BasicInlineTiming
MediaParam BasicMedia
MetaInformation NONE
MinMaxTiming BasicInlineTiming
MultiArcTiming EventTiming, and/or
SyncbaseTiming, and/or
MediaMarkerTiming, and/or
AccessKeyTiming, and/or
WallclockTiming
MultiWindowLayout BasicLayout
ObjectLinking BasicLinking
PrefetchControl NONE
PrevTiming BasicTimeContainers
RestartDefault RestartTiming
RestartTiming EventTiming, and/or
MultiArcTiming
SkipContentControl NONE
SplineAnimation BasicAnimation
StreamingMedia BasicMedia
Structure BasicContentControl, and
BasicInlineTiming, and
BasicLayout, and
BasicLinking, and
BasicMedia, and
BasicTimeContainers, and
SkipContentControl, and
SyncBaseTiming
SyncbaseTiming BasicInlineTiming
SyncBehavior BasicInlineTiming
SyncBehaviorDefault SyncBehavior
SyncMaster SyncBehavior
TimeContainerAttributes BasicInlineTiming
TimeManipulations BasicInlineTiming
TransitionModifiers BasicTransitions, and/or
InlineTransitions
WallclockTiming BasicInlineTiming

2.2.1 SMIL DOM

This section is informative.

SMIL is an XML-based language and conforms to the (XML) DOM Core [DOM1], [DOM2]. In future, a SMIL-specific DOM recommendation may specify support for timing and synchronization, media integration, and other synchronized multimedia functionality [SMIL-DOM].

A language profile may include DOM support. The granularity of DOM being supported, corresponds to the modules being selected in that language profile. As with all modules, required support for the DOM is an option of the language profile.

2.3 Identifiers for SMIL 2.0 Modules and Language Profiles

This section is informative.

This section specifies the identifiers for the SMIL 2.0 namespace and the SMIL 2.0 modules. Each SMIL host language conformant language profile is requested to explicitly state the namespace URI that is to be used to identify it. That namespace URI must comply with the "Requirements on Identifiers for SMIL Host Language Conformant Language Profiles", defined below.

2.3.1 The SMIL Mime Type

This section is normative.

Documents authored in language profiles that include the SMIL Structure module can be associated with the "application/smil" mime type. Documents using the "application/smil" mime type are required to be host language conformant.

2.3.2 XML Namespace Identifier for the SMIL 2.0 Modules

This section is normative.

The XML namespace identifier for the complete set of SMIL 2.0 modules, and the elements and attributes that are contained within is:

http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/

@@ Need to replace this and below by final ID.

2.3.3 Identifiers for SMIL 2.0 Modules and Features

This section is normative.

Each module in this specification has a unique identifier associated with it. They are intended to uniquely and consistently identify each of them. They should be used as values in a test for whether an implementation includes a specific module, as well as in other circumstances where a need to refer to a specific SMIL 2.0 module is necessary.

Table 2 summarizes the identifiers for SMIL 2.0 modules.
Table 2: The SMIL 2.0 Module Identifiers.
Module name Identifier
AccessKeyTiming http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/AccessKeyTiming
AudioLayout http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/AudioLayout
BasicAnimation http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/BasicAnimation
BasicContentControl http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/BasicContentControl
BasicInlineTiming http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/BasicInlineTiming
BasicLayout http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/BasicLayout
BasicLinking http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/BasicLinking
BasicMedia http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/BasicMedia
BasicTimeContainers http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/BasicTimeContainers
BasicTransistions http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/BasicTransistions
BrushMedia http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/BrushMedia
CustomTestAttributes http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/CustomTestAttributes
EventTiming http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/EventTiming
ExclTimeContainers http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/ExclTimeContainers
FillDefault http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/FillDefault
HierarchicalLayout http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/HierarchicalLayout
InlineTransitions http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/InlineTransitions
LinkingAttributes http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/LinkingAttributes
MediaClipMarkers http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/MediaClipMarkers
MediaClipping http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/MediaClipping
MediaMarkerTiming http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/MediaMarkerTiming
MediaParam http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/MediaParam
Metainformation http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/Metainformation
MinMaxTiming http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/MinMaxTiming
MultiElementTransitions http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/MultiElementTransitions
MultiArcTiming http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/MultiArcTiming
MultiWindowLayout http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/MultiWindowLayout
ObjectLinking http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/ObjectLinking
PrefetchControl http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/PrefetchControl
PrevTiming http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/PrevTiming
RestartDefault http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/RestartDefault
RestartTiming http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/RestartTiming
SkipContentControl http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/SkipContentControl
SplineAnimation http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/SplineAnimation
StreamingMedia http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/StreamingMedia
Structure http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/Structure
SyncbaseTiming http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/SyncbaseTiming
SyncBehavior http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/SyncBehavior
SyncBehaviorDefault http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/SyncBehaviorDefault
SyncMaster http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/SyncMaster
TimeContainerAttributes http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/TimeContainerAttributes
TimeManipulations http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/TimeManipulations
WallclockTiming http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/WallclockTiming

In addition to the module identifiers above, there may be different features and variances from one language profile to another that may not be expressed as the support or non-support of a particular module. These features may be expressed using the following identifiers:

http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/NestedTimeContainers
Profile allows nesting of the par and seq time containers.
http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/DeprecatedFeatures
Profile supports deprecated SMIL 1.0 features.

Implementations that support the SMIL BasicContentControl module must allow these as identifiers for use with the XML namespace mechanism, and must allow the associated namespace identifier to be used with the systemRequired test attribute. Profiles must identify those attributes for which an implementation must return "true" (this is an integration requirement). Implementations must return "false" for modules or features which are not fully supported.

2.3.4 The Design of the SMIL Identifiers

This section is informative.

In the design of the identifiers for the SMIL namespace, the SMIL modules, and the SMIL language profiles, the following construction has been used:

  1. The URI format is used that complies with the requirements set forth in "Requirements on Identifiers for SMIL Host Language Conformant Language Profiles".
  2. The base of the URI is the SMIL 1.0 namespace identifier [SMIL10]:

    http://www.w3.org/TR/REC-smil/

  3. To that base is appended a string that uniquely identifies the namespace associated with the elements in the modules, and its version. That identifier also identifies the main language profile. This leads to the namespace identifier for the SMIL 2.0 modules and the SMIL 2.0 language profile:

    http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/

  4. To that versioned identifier is appended a string that uniquely identifies the SMIL host language conformant language profile. For example, the namespace identifier for the SMIL 2.0 Basic language profile is:

    http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/Basic

  5. In the same way, a string is appended to the namespace identifier from step 3 to create the module identifiers. The appended string is the module's name.

2.4 SMIL Conformance

This section is informative.

In this section we specify the rules for SMIL host language and SMIL integration set conformance. First, the conformance requirements for host language conformance and integration set conformance are given. The requirements are similar to those set forth for XHTML host language document type conformance and XHTML integration set document type conformance [XMOD]. In a final section the requirements on identifiers for host language conformant language profiles are given.

Currently, there exist three language profiles using SMIL 2.0 Modules. They are the SMIL 2.0 Language Profile, the SMIL 2.0 Basic Language Profile, and the XHTML+SMIL 2.0 Language Profile (still in progress and not yet ready for Last Call). The first two are SMIL host language conformant, the third is SMIL integration set conformant.

This section is normative.

The following two tables list names used to collectively reference certain sets of SMIL 2.0 elements and attributes. These are used in the definitions of the minimum support in the two sections below on SMIL host language conformance and SMIL integration set conformance. The term "minimum support" is used to refer to the minimum set of elements that an element can contain, and the minimum set of attributes that can be used on an element.
Table 3: Names of SMIL 2.0 Element Collections.
Element Set Name Elements
TIMING-ELMS par, seq
MEDIA-ELMS ref, animation, audio, img, video, text, textstream
EMPTY no elements are required as a minimum

 
Table 4: Names of SMIL 2.0 Attribute Collections.
Attribute Set Name Attributes
TIMING-ATTRS begin, end, dur, repeatDur, repeatCount, max, min, fill, endsync
CONTCTRL-ATTRS systemBitrate, systemCaptions, systemLanguage, systemRequired, systemScreenSize, systemScreenDepth, systemOverdubOrSubtitle, systemAudioDesc, systemOperatingSystem, systemCPU, systemComponent
MEDIA-ATTRS abstract, alt, author, copyright, longdesc, src,  type
LINKING-ATTRS href, sourceLevel, destinationLevel, sourcePlaystate, destinationPlaystate, show, accesskey, tabindex, target, external, actuate
COMMON-ATTRS id, class, xml:lang, title

2.4.1 SMIL Host Language Conformance

This section is normative.

A language profile is said to be SMIL 2.0 host language conformant if it includes the following modules:

  1. Structure
  2. BasicInlineTiming
  3. BasicLayout
  4. BasicLinking
  5. BasicMedia
  6. BasicContentControl
  7. SkipContentControl
  8. SyncBaseTiming
  9. BasicTimeContainers
  10. MinMaxTiming

In addition, the following requirements must be satisfied:

  1. The language profile defines what modules it collects.
  2. The language profile includes all elements, attributes, and attribute values specified by the collected modules.
  3. The language profile fullfills the "minimum support" requirements for elements and attributes as listed in Table 5 below.
  4. The language profile complies with the integration requirements set forth by the modules it collects.
  5. The language profile specifies the semantics related to the integration of the modules.
  6. The language profile defines its DTD or XML Schema.
  7. The language profile defines a unique identifier conforming to the requirements set forth in Requirements on Identifiers for SMIL Host Language Conformant Language Profiles.
Table 5: Minimum Support for SMIL Host Language Conformance.
Element Minimum Support
Elements Attributes
smil head, body COMMON-ATTRS, xmlns
head layout COMMON-ATTRS
body TIMING-ELMS, MEDIA-ELMS, switch, a COMMON-ATTRS
layout root-layout, region COMMON-ATTRS, type
root-layout EMPTY COMMON-ATTRS, backgroundColor, height, width, skip-content
region EMPTY COMMON-ATTRS, backgroundColor, bottom. fit, height, left, right, showBackground, top, width, z-index, skip-content
ref, animation, audio, img, video, text, textstream area COMMON-ATTRS, CONTCTRL-ATTRS, TIMING-ATTRS, MEDIA-ATTRS
a MEDIA-ELMS COMMON-ATTRS, LINKING-ATTRS
area EMPTY COMMON-ATTRS, LINKING-ATTRS, TIMING-ATTRS, shape, coords, nohref, alt
par, seq MEDIA-ELMS, switch, a COMMON-ATTRS, CONTCTRL-ATTRS, TIMING-ATTRS
switch TIMING-ELMS, MEDIA-ELMS, a COMMON-ATTRS, CONTCTRL-ATTRS

Support of deprecated elements and attributes is required for SMIL 2.0 host language conformance for all modules the given language supports. For example, if a SMIL 2.0 host language supports the MultiArcTiming module, it must support the deprecated syntax defined in the MultiArcTiming module.

Since the SMIL 2.0 Structure module may only be used in a profile that is SMIL host language conformant, this implies that the SMIL 2.0 Structure module must at least be accompanied with the eight other modules required for host language conformance that were named above. Those modules themselves can still be used in other, non SMIL host language conformant, language profiles.

2.4.2 SMIL Integration Set Conformance

This section is normative.

A language profile is said to be SMIL 2.0 integration set conformant if it includes the following modules:

  1. BasicInlineTiming
  2. BasicMedia
  3. BasicContentControl
  4. SyncBaseTiming
  5. BasicTimeContainers
  6. MinMaxTiming

In addition, the following requirements must be satisfied:

  1. The language profile defines what modules it collects.
  2. The language profile includes all elements, attributes, and attribute values specified by the collected SMIL 2.0 modules.
  3. The language profile fulfills the "minimum support" requirements for elements and attributes as listed in Table 6 below.
  4. The language profile complies with the integration requirements set forth by the SMIL 2.0 modules it collects.
Table 6: Minimum Support for SMIL Integration Set Conformance.
Element Minimum Support
Elements Attributes
ref, animation, audio, img, video, text, textstream   CONTCTRL-ATTRS, TIMING-ATTRS, MEDIA-ATTRS
par, seq TIMING-ELMS, MEDIA-ELMS, switch, a CONTCTRL-ATTRS, TIMING-ATTRS
switch TIMING-ELMS, MEDIA-ELMS CONTCTRL-ATTRS

Support of deprecated elements and attributes is not required for SMIL 2.0 integration set conformance. However, when included, the above requirements also apply to these elements and attributes. Also, when supported, it is required that all the deprecated elements and attributes from all the included modules are supported as a whole.

2.4.3 Requirements on Identifiers for SMIL Host Language Conformant Language Profiles

This section is informative.

A language profile is specified through its DTD or XML Schema. The identifier of these can be used to identify the language profile. SMIL 1.0 has specified the default namespace declaration on its root element, <smil>, as the decisive identifier for distinguishing it from other language profiles [SMIL10]. For that purpose SMIL 1.0 has specified

http://www.w3.org/TR/REC-smil

as the namespace identifier for SMIL 1.0. The conformance requirements presented in this section are designed with that precedent in mind.

This section is normative.

For the purpose of identifying the version and the language profile used, SMIL host language conformant documents must satisfy the following requirements:

  1. The document should declare a default namespace [XML-NS].
  2. The default namespace must be declared on the <smil> root element.
  3. In case the SMIL host language conformant language profile has been issued as a W3C Recommendation, the default namespace identifier must satisfy the following requirements:
    1. The default namespace identifier should also identify the language profile.
    2. The URI is constructed conformant to the requirements set forth by the W3C [W3C-NSURI], with the exception that
    3. The base of the URI is

      http://www.w3.org/TR/REC-smil/

2.4.4 Error Handling in SMIL Host Language Conformant Documents

This section is normative.

Syntax errors in a SMIL Host Language conformant document are handled according to the XML rules for well-formed or valid XML [XML10].

Semantic errors can arise at various levels. One is where the declared attribute values are of unknown value. Another is where the assembled presentation is (possibly) conflicting, as in a case where media objects are competing for display space or where they are synchronized ambiguously. These latter types, although maybe an error according to the author's intentions, are not considered an error and the player will present according to the resolution rules defined in this specification.

Errors in attribute values might remain undetectable to the parser, because the value type is declared as CDATA, or because the value range is open ended, as in the case of events, for example. However, errors in attribute values can be detected within a given language profile, where that language profile specifies the supported value set. Specifications of language profiles that are SMIL Host Language conformant are required to specify the error handling that is required when such an attribute value error occurs.

2.5 Creating a DTD for a Language Profile

This section is informative.

This section describes how language profiles could be defined using the SMIL 2.0 modular DTDs. The reader is assumed to be familiar with the mechanisms defined in "Modularization of XHTML" [XMOD], in particular Appendix D [XMOD-APPD] and Appendix E [XMOD-APPE]. In general, the SMIL 2.0 modular DTDs use the same mechanisms as the XHTML modular DTDs use. Exceptions to this are:

  1. SMIL supports qualified attribute names for SMIL attributes that can appear on non-SMIL elements. This enables these attributes to use prefixes to indicate that they belong to the SMIL 2.0 namespace.
  2. SMIL supports module level INCLUDE/IGNORE instead of XHTML's element/attlist level. This prohibits profiles from importing only part of a module -- they have to support either all the elements and attributes or none.

Below, we give a short description of the files that are used to define the SMIL 2.0 modular DTDs. See the table and the end of the section for a complete list of the filenames involved.

Following the same mechanisms as the XHTML modular DTDs, the SMIL 2.0 specification places the XML element declarations (e.g. <!ELEMENT...>) and attribute list declarations (e.g. <!ATTLIST...>) of all SMIL 2.0 elements in separate files, the SMIL module files. A SMIL module file is provided for each functional area in the SMIL 2.0 specification (that is, there is a SMIL module file for animation, layout, timing, etc).

The SMIL module files are used in the normative definitions of the specification of the SMIL 2.0 Language Profile and the SMIL 2.0 Basic Language Profile. Usage of the same module files for defining other SMIL profiles is recommended, but not required. The requirements that SMIL language profiles must follow are stated in the SMIL 2.0 specification, not in the DTD code.

To make the SMIL module files independent of each other, and independent of the language profiles, the element and attribute declarations make heavy use of XML entities. This provides profiles with the necessary hooks to define the actual content models and attributes of the SMIL elements.

The SMIL 2.0 Language Profile and SMIL 2.0 Basic Language Profile provide examples of how the SMIL module files can be used. Most of the DTD files are reused across the different profiles. Reused are the SMIL module files, the files that define the data types and the common attributes, the "qname" file that takes care of adding namespace prefixes if necessary, and the framework file, which takes care of including files in the appropriate order.

The files that are different for each profile are the driver file and document model file. This would, in general, also apply to new profiles: to define a new language profile, one has to write the extension module(s), the driver file that defines which modules are used, and a document model file that defines the extended document model. The driver file and document model file are described in more detail below.

The driver file.

This is the file that would be referenced by a document's DOCTYPE declaration. Its main job is to define which document model file and which of the SMIL module files the profile is using. It may also define an optional namespace to be used in all namespace prefixes. For example, to prefix all SMIL element names with "foobar", the following can be added to the start of the profile:

<!ENTITY % SMIL.prefixed "INCLUDE" >
<!ENTITY % SMIL.prefix "foobar" >

Elements defined in their modules as, for example, <video> will become parsed as <foobar:video>. This also applies for SMIL attributes that appear on other elements, so, for example, "begin" becomes "foobar:begin". The default is that the qname prefix is empty -- that is, it is effectively turned off by default.

After these definitions, the driver file includes the framework file (which will subsequently include the data type, common attributes, qname and document model file), after which the SMIL module files are included that are used by this profile.

The document model file.

The document model file contains the XML entities that are used by the SMIL module files to define the content models and attribute lists of the elements in that profile.

Content models generally differ from profile to profile, or contain elements from other modules. To avoid these dependencies in the SMIL module files, content models need to be defined in the document model file. The (dummy) default content model as defined in the SMIL module files is "EMPTY" for all SMIL 2.0 elements.

For the same reasons, the SMIL module files only define a default attribute list for their elements. This default list only contains the SMIL 2.0 core attributes and the attributes that are defined in the same SMIL module file. All other attributes need to be added to this default list by defining the appropriate XML entities. For example, the Media Objects Module file only adds the core and media related attributes on the media objects, other attributes, such as the timing attributes, are added to this list by the document model file.
Table 7: Formal public identifiers and system identifiers of all files used in the SMIL 2.0 modular DTDs.
Driver files for the predefined profiles
-//W3C//DTD SMIL 2.0//EN http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/SMIL20.dtd
-//W3C//DTD SMIL 2.0 Basic//EN http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/SMIL20Basic.dtd
Document model files for the predefined profiles
-//W3C//ENTITIES SMIL 2.0 Document Model 1.0//EN http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/smil-model-1.mod
-//W3C//ENTITIES SMIL 2.0 Basic Document Model 1.0//EN http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/smilbasic-model-1.mod
SMIL 2.0 module files
-//W3C//ELEMENTS SMIL 2.0 Document Structure//EN http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/SMIL-struct.mod
-//W3C//ELEMENTS SMIL 2.0 Animation//EN http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/SMIL-anim.mod
-//W3C//ELEMENTS SMIL 2.0 Content Control//EN http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/SMIL-control.mod
-//W3C//ELEMENTS SMIL 2.0 Document Metainformation//EN http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/SMIL-metainformation.mod
-//W3C//ELEMENTS SMIL 2.0 Layout//EN http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/SMIL-layout.mod
-//W3C//ELEMENTS SMIL 2.0 Linking//EN http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/SMIL-link.mod
-//W3C//ELEMENTS SMIL 2.0 Media Objects//EN http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/SMIL-media.mod
-//W3C//ELEMENTS SMIL 2.0 Timing//EN http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/SMIL-timing.mod
-//W3C//ELEMENTS SMIL 2.0 Transition//EN http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/SMIL-transition.mod
Other utilities: data types, common attributes, qname and frame work files
-//W3C//ENTITIES SMIL 2.0 Datatypes 1.0//EN http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/smil-datatypes-1.mod
-//W3C//ENTITIES SMIL 2.0 Common Attributes 1.0//EN http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/smil-attribs-1.mod
-//W3C//ENTITIES SMIL 2.0 Qualified Names 1.0//EN http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/smil-qname-1.mod
-//W3C//ENTITIES SMIL 2.0 Modular Framework 1.0//EN http://www.w3.org/TR/REC-smil/2000/SMIL20/LC/smil-framework-1.mod

3. The SMIL 2.0 Animation Modules

Editors
Patrick Schmitz (pschmitz@microsoft.com), (Microsoft)
Aaron Cohen (aaron.m.cohen@intel.com), (Intel)
Ken Day (kday@macromedia.com), (Macromedia)

3.1 Introduction

This section defines the SMIL 2.0 Animation Modules, which are composed of a BasicAnimation module and a SplineAnimation module. These modules contain elements and attributes for incorporating animation onto a time line, and a mechanism for composing the effects of multiple animations. Since these elements and attributes are defined in modules, designers of other markup languages can choose whether or not to include this functionality in their languages. Language designers incorporating other SMIL modules do not need to include the animation modules if animation functionality is not needed.

The examples in this document that include syntax for a host language use [SMIL10], [SVG], [HTML4] and [CSS2]. These are provided as an indication of possible integrations with various host languages.

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.  Animation only manipulates attributes and properties of the target elements, and so does not require any knowledge of the target element semantics beyond basic type information.

This module depends on the SMIL 2.0 BasicInlineTiming module, using elements and attributes from the Timing module for its time line. The BasicInlineTiming module is a prerequisite for any profile using SMIL Animation. The reader is presumed to have read and be familiar with the SMIL 2.0 Timing modules. 

This section first presents the underlying principals of animation in SMIL 2.0, then the elements and attributes of the BasicAnimation module and of the SplineAnimation module.

3.2 Animation Model

This section describes the semantics underlying the SMIL 2.0 animation modules. 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 simple animation function f(t), and then the overall effect F(t,u). 

3.2.1 The simple animation function f(t)

Animation is defined as a time-based function of a target element (or more specifically of some attribute of the target element, the target attribute). The animation defines a mapping of time to values for the target attribute. This mapping takes into account all aspects of timing, as well as animation-specific semantics.  The overall mapping is based on a simple animation function f(t) which describes the animation over the simple duration of the element. Every animation defines a simple animation function which produces a value for the target attribute for any time within the simple duration.

Normative

A 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 XML ID reference or via an XLink [XLINK] locator reference.

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.

<rect ...>
   <animate attributeName="width"  from="10px"  to="100px" 
            begin="0s" dur="10s" />
   <animate attributeName="height" from="100px" to="10px"
            begin="0s" dur="10s" />
</rect>

The rectangle begins with a width of 10 pixels and increases to a width 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.

When an animation is running, it should not actually change the attribute values in the DOM [DOM2].  The animation runtime should maintain a presentation value 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 displayed form of the document. Animations thus manipulate the presentation value, and should not affect the base value exposed by DOM or CSS OM. This is detailed in The animation sandwich model.

Normative

The base value of a target attribute a at time t is the value of a to which animation is applied at time t.

The presentation value of a target attribute a at time t is the value of a resulting from the application of animation at time t.

The presentation value reflects the effect of animation on the base value. The effect is the change to the base 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 freeze the last value for the length of time determined by the semantics of the fill attribute.

An animation element defines a simple animation function which is evaluated as needed over time by the implementation. 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 simple 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.

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

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

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

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

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

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

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

Normative

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

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

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 underlying value. Animations that add to the underlying value are described as additive animations. Animations that override the underlying value are referred to as non-additive animations. The animation effect function of an element is the function which includes the affect of the underlying value and accounts for repeating and freezing of the element. Because the animation effect can be affected by repeating and freezing, it is defined over the active duration of the element rather than its simple duration.

Animations can be combined in ways which produce intermediate values outside of the domain of the target attribute, but where the presentation value produced is valid. The type of a target attribute is this larger set. This is detailed in The animation sandwich model.

Normative

The type of a target attribute a is the base type of which the domain of a is a subset.

The animation effect function, F(t,u), of an animation element with active duration AD is a function mapping times t: 0<=t<=AD and values u of the type of the target attribute a into values of the type of a.

The underlying value u of a target attribute a of an animation element at time t is the value of a to which the animation effect is applied at time t.

The animation effect function F(t,u) is usually defined as a function of the simple animation function f(t). f(t) must be defined in such a manner that F(t,u) produces values of the correct type.

3.2.2 Summary of symbols used in the semantic descriptions

a
The target attribute of an animation element.
d
The simple duration of the element.
AD
The active duration of the element.
t
A time. Depending on the context, t may be in user-perceived time, an element's active duration, or its simple duration.
u
The underlying value of the target attribute a, generally at a specific time t.
f(t)
The simple animation function of times within the simple duration. Note that while F(t,u) defines the mapping for the entire animation, f(t) has a simplified model that just handles the simple duration.
F(t,u)
The effect of an animation for any point in the active duration of the animation. This maps times within the active duration (t: 0<=t<=AD) and an underlying value to a value for the target attribute. A time value of 0 corresponds to the time at which the animation begins. F(t,u) combines the simple animation function f(t) with all the other aspects of animation and timing controls.

3.2.3 The animation sandwich model

When an animation is running, it does not actually change the attribute values in the DOM.  The animation runtime should ideally maintain a presentation value 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.

The remainder of this discussion uses the generic term OM for both the XML DOM [DOM2] 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.

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. 

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

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 priority, 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.

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. 

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. 

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) getComputedStyle() 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 getOverrideStyle() 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 !important property. This enables !important 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 section 6.1, "Specified, computed, and actual values," of [CSS2] and section 5.2.1, "Override and computed style sheet," of [DOM2CSS].

Within an OM, animations are prioritized according to when each begins. The animation first begun has lowest priority and the most recently begun animation has highest priority. When two animations start at the same moment in time, the activation order is resolved as follows:

Note that if an animation is restarted (see also Restarting animations), 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).

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.

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 animateColor element.

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).

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 fill="freeze", the effect of the animation will be applied as long as the animation element remians in the frozen state, and so the presentation value will continue to reflect the animation effect. Refer also to the section "Freezing animations".

Some animations (e.g. animateMotion) will implicitly 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, e.g. an animateMotion 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.

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.

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 Additive animation). 

3.2.4 Animation elements as "continuous media"

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

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

3.2.5 The animation effect function F(t,u)

As described above, the simple animation function f(t) defines the animation for the simple duration d. However, SMIL Timing allows the author to repeat the simple duration. SMIL Timing also allows authors to specify whether the animation should simply end when the active duration completes, or whether it should be frozen at the last value. SMIL Animation specifies what it means for an animation to be frozen.  In addition, the author can specify how each animation should be combined with other animations and the original DOM value.

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

Since these functions describe the animation outside of the simple duration, they are defined for any non-negative time t.

Repeating animations

As described in the section Interval timing of the BasicInlineTiming module, repeating an element causes the element to be "played" several times in sequence. The repeated period is 0 to the simple duration of the element. Animation follows this model, where "playing" the animation means applying the simple animation function f(t) repeatedly.

Normative

The repeated animation function, fr(t), for any simple animation function f(t) is

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

where t>=0, d is the simple duration , and REMAINDER( t, d ) is defined as (t - d*floor(t/d)).

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

Examples

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

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

In the following example, the animation function will be repeated two full times and then the first half is repeated once more; the active duration will be 7.5 seconds.

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

In the following example, the animation function will repeat for a 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". 

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

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

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

Note that if the simple duration is not defined (e.g. it is indefinite), repeat behavior is not defined (but repeatDur still defines the active duration). In the following example the simple duration is indefinite, and so the repeatCount 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 f(0), setting the fill color to red for the remainder of the animate element's duration.

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

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

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

In the following example, the simple duration is longer than the duration specified by repeatDur, 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.

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

Controlling behavior of repeating animation - Cumulative animation

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 cumulative animation.

Normative

Every animation element must be defined as either cumulative or non-cumulative. An animation element may be defined as cumulative only if addition is defined for the target attribute. The cumulative animation function, fc(t), for any simple animation function f(t) is

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

If the element is cumulative:

Let fi(t) represent the cumulative animation function for a given iteration i.

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

f0(t) = f(t)

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

The cumulative animation function is then

fc(t) = fi(t), where i = floor(t/d).

Note that fi+1(t)starts at f(d)*i + f(0). To avoid jumps, authors will typically choose animation functions which start at 0.

For example, the path notation for a simple arc (detailed in The animateMotion element) can be used to describe a bouncing motion:

<img ...>
   <animateMotion path="c( 3 5 7 5 10 0)" dur="5s"
      accumulate="sum" repeatCount="4" />
</img>

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 1, 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.

Figure 1 - Illustration of repeating animation with accumulate="sum".

Diagram showing accumlating animation

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

Note that cumulative animation only controls how a single animation accumulates the results of the simple 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 Additive animation. Similarily, if an element restarts, the accumulate from the first run is not applied to the second. See Restarting animations.

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 <rect> element by 100 pixels in 50 seconds.

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

Each simple duration causes the rectangle width to bulge by 15 pixels 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.

Freezing animations

Animation elements follow the definition of fill in the Timing module. This section extends that specification to cover animation-specific semantics.

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.

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

As shown in Figure 2, the image will appear stationary at the top value of "3" for 5 seconds, then move 100 pixels down in 10 seconds. 15 seconds 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 DOM value of the top attribute).

Figure 2 - Illustration of animation without freezing.

Diagram showing an animation with default fill.

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

The fill attribute can be used to maintain the value of the animation after the active duration of the animation element ends:

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

The animation ends 15 seconds after the document begin, but the image remains at the top value of 103 (Figure 3). The attribute freezes the last value of the animation for the duration of the freeze effect. This duration is controlled by the time container, and never extends past the end of the time container's simple duration.

Figure 3 - Illustration of animation with fill="freeze".

Diagram showing a frozen animation.

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

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

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

Figure 4 - Illustration of animation combining a partial repeat and fill="freeze".

Diagram showing an animation with a partial repeat and freezing.

In the following example, the dur attribute is missing, and so the simple duration is indefinite. The active duration is constrained by end to be 10 seconds. Interpolation is not defined, and the value while frozen will be the from value, 10:

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

Stating this formally:

Normative

The frozen animation function, ff(t), for an element with active duration AD, 0<=t<=AD is given by

ff(t) = fc(t) for all times t: 0<=t<AD

If AD is not an even multiple of the simple duration d,

ff(AD) = fc(AD).

If AD is an even multiple of d, i.e. AD = d*i for some positive integer i, and the animation is non-cumulative,

ff(AD) = f(d).

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

ff(AD) = fc( d*(i-1) ) + f(d).

3.2.6 Additive animation

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

For example, a simple "grow" animation can increase the width of an object by 10 pixels: 

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

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.

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:

<img ...>
   <animateMotion from="0,0" to="100,0" dur="10s" />
   <animateMotion values="0,0; 0,5; 0,0" dur="1s"
                  repeatDur="10s" additive="sum"/>
</img>

The animation effect function, captures the semantics of this for a single animation element:

Normative

The animation effect function, F(t,u), for an animation element with simple duration x and active duration y is a function mapping t, 0<=t<=AD and u, a value of the type of the target attribute of the animation into that same type.

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

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

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

When there are multiple animations defined for a given attribute 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.

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 The animation sandwich model.

Additive animation is defined for numeric attributes and other data types for which an addition function is defined. This includes numeric attributes for concepts such as position, widths and heights, sizes, etc. This also includes color (refer to The animateColor element), and may include other data types as specified by the host language.

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

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

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

While many animations of numerical attributes will be additive, this 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. 

<img ...>
   <animateMotion dur=10s repeatDur="indefinite"
           path="[some nice path]" />
   <mouseFollow begin="mouseover" dur="5s"
           additive="replace" fill="remove" />
</img>

The mouse-tracking animation runs for 5 seconds every time the user mouses over the image. It cannot be additive, or it will just offset the motion path in some odd way. The mouseFollow needs to override the animateMotion while it is active. When the mouseFollow completes, its effect is no longer applied and the animateMotion again controls the presentation value for position.

In addition, some numeric attributes (e.g. a telephone number attribute) may not sensibly support addition. It is left to the host language to specify which attributes support additive animation. Attribute types for which addition is not defined, such as strings and Booleans, cannot support additive animation.

Additive and Cumulative animation

The accumulate attribute should not be confused with the additive attribute. The additive attribute defines how an animation is combined with other animations and the base value of the attribute.  The accumulate attribute defines only how the simple animation function interacts with itself, across repeat iterations.

Typically, authors expect cumulative animations to be additive (as in the examples described for accumulate above), but this is not required. The following example is cumulative but not additive.

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

The animation overrides whatever original value was set for "top", 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 50 (the value of 30 from the previous iteration plus the from value, 20) and moves down by another 10 to 60, and so on.

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

<img top="10" ... >
  <animate dur="10s" repeatdur="indefinite"

           attributename="top" from="20" by="10"

           additive="sum" accumulate="sum" />
</img>

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

Refer also to The animation sandwich model.

3.2.7 Restarting animations

Animation elements follow the definition of restart in the SMIL Timing module. This section is descriptive.

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 function F(t,u) is defined independent of the restart behavior. Any effect of an animation playing earlier is no longer applied, and only the current animation effect F(t,u) is applied.

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 F(t,u) begins accumulating again from the first iteration of the restarted active duration.

3.2.8 Animation function value details

Many animations specify the simple animation function f(t) 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.

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

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.

In all cases, the animation effect function, F(t,u), must yield legal values for the target attribute. Three classes of values are described:
  1. Unitless scalar values. These are simple scalar values that can be parsed and set without semantic constraints. This class includes integers (base 10) and floating point (format specified by the host language).
  2. String values. These are simple strings.
  3. Language abstract values. These are values like CSS-length and CSS-angle values that have more complex parsing, but that can yield values that may be interpolated.

The animate element can interpolate unitless scalar values, and both animate and set elements can handle String values without any semantic knowledge of the target element or attribute. The animate and set elements must support unitless scalar values and string values. The host language must define which additional language abstract values should be handled by these elements. Note that the animateColor element implicitly handles the abstract values for color values, and that the animateMotion element implicitly handles position and path values. 

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.

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:

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

Support for these two interfaces ensures that an animation engine need not replicate the parser and any additional semantic logic associated with language abstract values. 

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.

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.

Interpolation and indefinite simple durations

If the simple duration of an animation is indefinite (e.g. if no dur 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. f(0)) should be used (effectively as a constant) for the animation function.

3.3 Overview of the SMIL 2.0 BasicAnimation Module

The SMIL 2.0 BasicAnimation module provides

The BasicAnimation module defines attributes and elements following the model presented in the Animation Model section.

3.4 SMIL 2.0 BasicAnimation Module Common Attributes

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

3.4.1 Specifying the animation target

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.

The target attribute

The target attribute to be animated is specified with attributeName. The value of this attribute is a string that specifies the name of the target attribute, as defined in the host language.

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 attributeType is provided that specifies the intended namespace. 

The attributeType attribute is optional. By default, the animation runtime will resolve the names according to the following rule: If there is a name conflict and attributeType 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.

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 target element. The prefix is prepended to the value for attributeName.

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

Target attribute attributes
 
attributeName
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 target element.
 
attributeType
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):
CSS
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.
XML
This specifies that the value of "attributeName" is the name of an XML attribute defined in the default XML namespace for the target element. If the value for attributeName has an XMLNS prefix, the implementation must use the associated namespace as defined in the scope of the target element.
auto
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.
This is the default.

The target element

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.

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.

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 Handling syntax errors.

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

Target element attributes
 
targetElement
This attribute specifies the target element to be animated. The attribute value must be the value of an XML identifier attribute of an element (i.e. an "IDREF") within the host document. For a formal definition of IDREF, refer to XML 1.0 [XML10]. 
href
This attribute specifies the target element to be animated. The attribute value must be an XLink locator, referring to the target element to be animated.

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 href attribute takes precedence over the targetElement attribute.

The advantage of using the targetElement attribute is the simpler syntax of the attribute value compared to the href attribute. The advantage of using the XLink href 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.

This example uses the simpler targetElement syntax:

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

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

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

When using an XLink href 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 [XLINK].

The following XLink attributes are required by the XLink specification. The values are fixed, and so may be specified as such in a DTD. All other XLink attributes are optional, and do not affect SMIL Animation semantics.

XLink attributes for href
 
type
Must be simple. Identifies the type of XLink being used.
actuate
Must be onLoad. Indicates that the link to the target element is followed automatically (i.e., without user action).
show
Must be embed. Indicates that the reference does not include additional content in the file. 

Additional details on the target element specification as relates to the host document and language are described in Required definitions and constraints on animation targets.

3.4.2 Specifying the simple animation function f(t)

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.

An animation is described either as a list of values, or in a simplified form that describes the from, to and by values. The from/to/by form is defined in Simple animation functions defined by from, to and by.

Simple animation function attributes
values

A semicolon-separated list of one or more values, each of which must be a legal value for the specified attribute. Vector-valued attributes are supported using the vector syntax of the attributeType domain. Leading and trailing white space, and white space before and after semi-colon separators, will be ignored.

If any values are not legal, the animation will have no effect (see also Handling Syntax Errors).
calcMode
Specifies the interpolation mode for the animation. If the target attribute does not support linear interpolation (e.g. for strings), or if the values attribute has only one value, the calcMode attribute is ignored and discrete interpolation is used. The calcMode attribute can take any of the following values:
discrete
This specifies that the animation function will jump from one value to the next without any interpolation.
linear
Simple linear interpolation between values is used to calculate the animation function. 
This is the default.
paced

Defines interpolation to produce an even pace of change across the animation. This is only supported for values that define a linear numeric range, and for which some notion of "distance" between points can be calculated (e.g. position, width, height, etc.).

The animation will apply the values in order over the course of the animation. For discrete and linear animations, values in the values attribute are equally spaced through the animation duration. For paced animations, the values are spaced so that a uniform rate of change is obtained.

The following example using the values 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.

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

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

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

The simple animation function defined by the values and calcMode attributes can be formally specified:

Normative

With i = floor((t*n)/d), d the simple duration of the animation element, n the number of entries in the values attribute and value[i] the ith entry (counting from 0):

Note that a linear or paced animation will be a smoothly closed loop if the first value is repeated as the last.

Interpolation modes illustrated

The three figures 5a, 5b and 5c below show how the same basic animation will change a value over time, given different interpolation modes.  All examples are based upon the following example, but with different values for calcMode:

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

Figure 5 - Discrete, linear and paced animation

Diagram of linear interpolation

Figure 5a: Default discrete animation.

calcMode="discrete"

There are 6 segments of equal duration: 1 segment per value.
Diagram of linear interpolation

Figure 5b: Default linear animation.

calcMode="linear"

There are 5 segments of equal duration: n-1 segments for n values.
Diagram of linear interpolation

Figure 5c: Default paced animation.

calcMode="paced"

There are 5 segments of varying duration: n-1 segments for n values, computed to yield a constant rate of change in the value.

Examples of calcMode

The following example describes a simple discrete animation:

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

The value of the attribute "foo" will be set to each of the four strings for 2 seconds each. Because the string values cannot be interpolated, only discrete animation is possible; any calcMode attribute would be ignored.

The following example describes a simple linear animation:

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

The value of "x" will change from 0 to 10 in the first 5 seconds, and then from 10 to 100 in the second 5 seconds. Note that the values in the values attribute are spaced evenly in time; 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:

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

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 from-to animation without paced interpolation, many examples (such as motion paths) are much harder to author without the paced value for calcMode. 

3.4.3 Specifying the animation effect function F(t,u)

As described in The animation effect function F(t,u), the simple animation function may be

The animation effect function F(t,u) defines the semantics of these attributes, and give examples. This section gives only the syntax.

See the BasicInlineTiming module for definitions of the attributes repeatCount, repeatDur and fill.

The additive and cumulative behavior of repeating animations is controlled with the additive and accumulate attributes, respectively:

Animation effect function attributes
accumulate
Controls whether or not the animation is cumulative. May be either of the following two values:
sum
Specifies that the animation is cumulative, i.e. each repeat iteration after the first builds upon the last value of the previous iteration.
none
Specifies that the animation is non-cumulative, i.e. repeat iterations simply repeat the animation function f(t).
This is the default.
This attribute is ignored if the target attribute value does not support addition, or if the animation element does not repeat.
additive
Controls whether or not the animation is additive. 
sum
Specifies that the animation is additive, i.e. will add to the underlying value of the attribute and other lower priority animations.
replace
Specifies that the animation is non-additive, i.e. will override the underlying value of the attribute and other lower priority animations. This is the default.
This attribute is ignored if the target attribute does not support additive animation.

3.4.4 Simple animation functions specified by from, to and by

An animation is described either as a list of values, as described earlier, or in a simplified form that uses from, to and by values.

From/to/by attributes for simple animation functions
from
Specifies the starting value of the animation. Must be a legal value for the specified attribute. Ignored if the values attribute is specified.
to
Specifies the ending value of the animation. Must be a legal value for the specified attribute. Ignored if the values attribute is specified.
by
Specifies a relative offset value for the animation. Must be a legal value of a domain for which addition to the attributeType domain is defined and which yields a value in the attributeType domain. Ignored if the values attribute is specified.

The simpler from/to/by syntax provides for several variants. To use one of these variants, one of by or to must be specified; a from value is optional. It is not legal to specify both by and to attributes; if both are specified, only the to attribute will be used (the by will be ignored). The combinations of attributes yield the following classes of animation.

from-to animation
Specifying a from value and a to value defines a simple animation. The animation function is defined to start with the from value, and to finish with the to value.

Normative: A from-to animation with a from value vf and a to value vt is equivalent to the same animation with a values list with 2 values, vf and vt.
from-by animation
Specifying a from value and a by value defines a simple animation in which the animation function is defined to start with the from value, and to change this over the course of the simple duration by a delta specified with the by attribute. This may only be used with attributes that support addition (e.g. most numeric attributes).

Normative: A from-by animation with a from value vf and a by value vb is equivalent to the same animation with a values list with 2 values, vf and (vf+vb).
by animation
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 by attribute. This may only be used with attributes that support additive animation.

Normative: A by animation with a by value vb is equivalent to the same animation with a values list with 2 values, 0 and vb, and additive="sum". Any other specification of the additive attribute in a by animation is ignored.
to animation
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 to 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 to value.

A normative definition of a to animation is given below in To animation

Examples

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

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

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

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

The following "by animation" 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.

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

From-to and from-by animations also support cumulative animation, as in the following example:

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

The rectangle will grow from 10 to 20 pixels in the first 5 seconds, 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 additive is replace, the original value is ignored. The following example makes the animation explicitly additive:

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

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

To animation

A to animation of an attribute which supports addition is a kind of mix of additive and non-additive animation. The underlying value is used as a starting point as with additive animation, however the ending value specified by the to attribute overrides the underlying value as though the animation was non-additive.

The following "to animation" 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.

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

Since a to animation has only 1 value, a discrete to animation will simply set the to value for the simple duration. In the following example, the rect will be blue for the 10 second duration of the animate element.

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

The semantics of to animation fit into the general animation model, but with a few special cases. The normative definition given here parallels the definition for other types of animation presented in the Animation Model section.

Normative

The simple animation function f(t,u) for a to animation with to value vt is a linear interpolation between the underlying value, u, and the to value:

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

If no other (lower priority) animations are active or frozen, this defines simple interpolation. However if another animation is manipulating the underlying value, the to animation will initially add to the effect of the lower priority animation, and increasingly dominate it as it nears the end of the simple duration, eventually overriding it completely. The value for f(t,u) at the end of the simple duration is just the to value.

Repeating to animations is the same as repeating other animations:

Normative

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

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

Because to animation is defined in terms of absolute values of the target attribute, cumulative animation is not defined:

Normative

The cumulative animation function, fc(t), for a to animation is

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

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

Normative

The frozen animation function, ff(t), for a to animation is

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

ff(t,u) = vf, if the animation is frozen at time t, where vf is the value of ff(t,u) at the moment the animation was frozen.

For example, consider

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

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

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

Normative

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

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

Multiple to animations will also combine according to these semantics. As the animation progresses, the higher-priority animation will have greater and greater effect, and the end result will be to set the attribute to the final value of the higher-priority to animation.

For an example of additive to animation, consider the following two additive animations. The first, a by-animation applies a delta to attribute "x" from 0 to -10. The second, a to animation animates to a final value of 10.

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

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

Figure 6 - Effect of Additive to animation example

Time F(t,u) for A1 F(t,u) for A2
 0 0 0
 1 -1 0.1
 2 -2 0.4
 3 -3 0.9
 4 -4 1.6
 5 -5 2.5
 6 -6 3.6
 7 -7 4.9
 8 -8 6.4
 9 -9 8.1
10 -10 10

3.5 SMIL 2.0 BasicAnimation Elements

The SMIL BasicAnimaion module defines four elements, animate, set, animateMotion and animateColor.

3.5.1 The animate element

The animate 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 animate element is an empty element; it cannot have child elements.

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.

Element attributes
attributeName and
attributeType
The attribute to be animated. See The target attribute. attributeName is required; attributeType is optional.
targetElement,
href,
actuate,
show, and
type
The target element. See The target element. All are optional.
 
from,
to,
by,
values,
calcMode,
accumulate, and
additive
 
Specify the animation function and effect. See Specifying the simple animation function f(t) and Specifying the animation effect F(t,u).

Numerous examples are provided above, as are normative definitions of the semantics of all attributes supported by animate.

3.5.2 The set element

The set 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, set does not permanently set the value of the attribute. 

The set 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 set element is non-additive. The additive and accumulate attributes are not allowed, and will be ignored if specified.

The set element supports all the timing attributes to specify the simple and active durations. However, the repeatCount and repeatDur attributes will just affect the active duration of the set, extending the effect of the set (since it is not really meaningful to "repeat" a static operation). Note that using fill="freeze" with set will have the same effect as defining the timing so that the active duration is indefinite.

The set element supports a more restricted set of attributes than the  animate element. Only one value is specified, and neither interpolation control nor additive or cumulative animation is supported:

Element attributes
attributeName and
attributeType
The attribute to be animated. See The target attribute. attributeName is required; attributeType is optional.
 
targetElement,
href,
actuate,
show, and
type
The target element. See The target element. All are optional.
to
Specifies the value for the target attribute during the active duration of the set element. The argument value must match the target attribute type.

Normative

The simple animation function defined by a set element is

f(t) = v

were v is the value of the to attribute.

The set element is non-cumulative and non-additive.

Examples

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.

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

The following example sets the class 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. 

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

3.5.3 The animateMotion element

The animateMotion 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 either of two ways:

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 reference point 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.

The syntax for the x, y value pairs is:

coordinate-pair ::= ( coordinate comma-wsp coordinate )
coordinate      ::= num
num             ::= Number

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 coordinate must be defined as some sort of number in the host language.

The attributeName and attributeType attributes are not used with animateMotion, 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 animateMotion animations with other animations that manipulate individual position attributes. See also The animation sandwich model.

If none of the from, to, by and values attributes are specified, the animation will have no effect.

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

Element attributes
 
targetElement,
href,
actuate,
show, and
type
The target element. See The target element. All are optional.
from,
to,
by,
values,
accumulate, and
additive
 
Specify the animation function and effect. See Specifying the simple animation function f(t) and Specifying the animation effect F(t,u).
calcMode 
Defined as above in Specifying the simple animation function f(t), but note that the default calcMode for animateMotion is paced. This will produce constant velocity motion.

The use of linear for the calcMode with more than 2 points described in the values attribute may result in motion with varying velocity. The linear calcMode specifies that time is evenly divided among the segments defined by the values. The use of linear does not specify that time is divided evenly according to the distance described by each segment. 

For motion with constant velocity, calcMode should be set to paced.

origin

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, 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 origin 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.

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 [CSS2], for example, this can be controlled with the "clip" property.

Note that for additive animation, the origin distinction is not meaningful.  This attribute only applies when additive is set to replace.

3.5.4 The animateColor element

The animateColor element specifies an animation of a color attribute. The host language must specify those attributes that describe color values and can support color animation.

All values must represent [sRGB] color values. Legal value syntax for attribute values is defined by the host language.

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

Element attributes
attributeName and
attributeType
The attribute to be animated. See The target attribute. attributeName is required; attributeType is optional.
targetElement,
href,
actuate,
show, and
type
The target element. See The target element. All are optional.
 
from,
to,
by,
values,
calcMode,
accumulate, and
additive
 
Specify the animation function and effect. See Specifying the simple animation function f(t), Specifying the animation effect F(t,u).

The values in the from/to/by and values attributes may specify negative and out of gamut values for colors.  The function defined by an individual animateColor 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 The animation sandwich model, 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.

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) .

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.

Note to implementers: When animateColor is specified as a to animation, the animation function should assume Euclidean RGB-cube distance where deltas must be computed. See also Specifying the simple animation function f(t) and Simple animation functions specified by from, to and by. Similarly, when the calcMode attribute for animateColor is set to paced, the animation function should assume Euclidean RGB-cube distance to compute the distance and pacing.

3.6 SMIL 2.0 BasicAnimation Module Details

3.6.1 BasicAnimation integration requirements

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 and constraints upon animation.

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

Required definitions and constraints on animation targets

Specifying the target element

The host language designer must choose whether to support the targetElement attribute or the XLink attributes for specifying the target element. 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 (qnames) 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.

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.

Target attribute issues

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 language attribute of a script 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.

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, additive and cumulative animation).

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.

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 Animation function value details.

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.

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.

The host language must specify the formats supported for numeric attribute values. This includes both integer values and floating point values. As a reasonable minimum, host language designers are encouraged to support the format described in section 4.3.1, "Integers and real numbers," of [CSS2].

Integrating animateMotion functionality

The host language specification must define which elements can be the target of animateMotion. In addition, the host language specification must describe the positioning model for elements, and must describe the model for animateMotion in this context (i.e. the semantics of the default value for the origin attribute must be defined). If there are different ways to describe position, additional attribute values for the origin attribute should be defined to allow authors control over the positioning model.

3.6.2 Document type definition (DTD) for the BasicAnimation module

See the full DTD for the SMIL Animation Modules.

3.7 Overview of the SMIL 2.0 SplineAnimation Module

This section defines the functionality of the SMIL 2.0 SplineAnimation module. This module adds attributes for spline interpolation and for uneven spacing of points in time. These attributes may be used in animate, animateMotion and animateColor elements.

3.7.1 SMIL 2.0 SplineAnimation Module Attributes

Spline animation function calculation mode

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

Calculation mode attributes
calcMode
In addition to the values discrete, linear and paced of the BasicAnimation module, the AdvanceAnimation module supports the value
spline
Interpolates from one value in the values list to the next according to a time function defined by a cubic Bezier spline. The points of the spline are defined in the keyTimes attribute, and the control points for each interval are defined in the keySplines attribute.

The use of discrete for the calcMode together with a path specification is allowed, but will simply jump the target element from point to point. The times are derived from the points in the path specification, as described in the path attribute, immediately below.

keyTimes
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 values attribute list, and defines when the value should be used in the animation function. Each time value in the keyTimes list is specified as a floating point value between 0 and 1 (inclusive), representing a proportional offset into the simple duration of the animation element.

If a list of keyTimes is specified, there must be exactly as many values in the keyTimes list as in the values list.

If no keyTimes attribute is specified, the simple duration is divided into equal segments as described in The simple animation function f(t).

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

The keyTimes list semantics depends upon the interpolation mode:

  • For linear and spline animation, the first time value in the list must be 0, and the last time value in the list must be 1. The keyTime associated with each value defines when the value is set; values are interpolated between the keyTimes.
  • 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 keyTimes.

If the interpolation mode is paced, the keyTimes attribute is ignored.

If there are any errors in the keyTimes specification (bad values, too many or too few values), the animation will have no effect.

If the simple duration is indefinite and the interpolation mode is linear or spline, any keyTimes specification will be ignored.

keySplines
A set of Bezier control points associated with the keyTimes 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: x1 y1 x2 y2, describing the Bezier control points for one time segment. The keyTimes values that define the associated segment are the Bezier "anchor points", and the keySplines values are the control points. Thus, there must be one fewer sets of control points the keySplines attribute than there are keyTimes.

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

This attribute is ignored unless the calcMode is set to spline.


If there are any errors in the keySplines specification (bad values, too many or too few values), the animation will have no effect.

This semantic (the duration is divided into n-1 even periods) applies as well when the keySplines attribute is specified, but keyTimes is not. The times associated to the keySplines values are determined as described above.

The syntax for the control point sets in keySplines lists is:

control-pt-set ::= ( fpval comma-wsp fpval comma-wsp fpval comma-wsp fpval )

Using:

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

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.

If the  argument values for keyTimes or keySplines are not legal (including too few or too many values for either attribute), the animation will have no effect (see also Handling syntax errors).

In the calcMode, keyTimes and keySplines attribute values, leading and trailing white space and white space before and after semicolon separators will be ignored.

Examples of advanced uses of calcMode

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

<animateColor attributeName="color" calcMode="discrete"
     values="green; yellow; red" keyTimes="0; 5; 10" />

This example also shows how keyTimes 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".

The following example illustrates the use of keyTimes:

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

The keyTimes 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.

Interpolation with keySplines

For some attributes, the pace of change may not be easily discernable by viewers. However for animations like motion, the ability to make the speed of the motion change gradually, and not in abrupt steps, can be important. The keySplines attribute provides this control.

Extending the above example to use keySplines:

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

The keyTimes 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 keySplines 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 keyTimes 0 and .8, and values "0" and "50"), but a strict linear interpolation between 8 seconds and the end (i.e. between keyTimes .8 and 1, and values  "50" and "100"). Figure 7 shows the curves that these keySplines values define.

Figure 7 - Illustration of keySplines effect

Example keySplines01 - keySplines of 0 0 1 1 (the default)
keySplines="0 0 1 1"
(the default)
 Example keySplines02 - keySplines of .5 0 .5 1
keySplines=".5 0 .5 1"
 
Example keySplines03 - keySplines of 0 .75 .25 1
keySplines="0 .75 .25 1"
 Example keySplines04 - keySplines of 1 0 .25 .25
keySplines="1 0 .25 .25"

Each diagram in Figure 7 illustrates the effect of keySplines settings for a single interval (i.e. between the associated pairs of values in the keyTimes and values lists.). The horizontal axis can be thought of as the input value for the unit progress of interpolation within the interval - i.e. the pace with which interpolation proceeds along the given interval. The vertical axis is the resulting value for the unit progress, yielded by the keySplines function. Another way of describing this is that the horizontal axis is the input unit time for the interval, and the vertical axis is the output unit time. See also the section Timing and real-world clock times.

To illustrate the calculations, consider the simple example:

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

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

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

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

The keyTimes and keySplines attributes can also be used with the from/to/by shorthand forms for specifying values, as in the following example:

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

The value will change from 10 to 20, using an "ease-in/ease-out" curve specified by the keySplines values. The keyTimes 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.

The following example describes a somewhat unusual usage, a 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 attribute to round for 5 seconds (half the simple duration) and then set the stroke-linecap to square for 5 seconds.

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

3.7.2 SMIL 2.0 SplineAnimation Module Elements

The SplineAnimation module extends the BasicAnimation elements animate, animateMotion and animateColor, adding the attributes keyTimes and keySplines, and the value spline for the caclMode attribute.

3.7.3 The spline animate element

The SplineAnimation module extends the animate element defined by the BasicAnimation module, adding the following attributes and values.

Element attributes
 
all attributes and associated elements of the animate element in BasicAnimation.
See The animate element.
keyTimes,
keySplines, and
calcMode
 
 
Extend the specification animation function and effect. See The animate element and Spline animation function calculation mode.

Examples are provided above, as are normative definitions of the semantics of all attributes supported by animate.

3.7.4 The spline animateMotion element

The SplineAnimation module extends the animateMotion element defined by the BasicAnimation module, adding the following attributes and values.

Element attributes
 
all attributes and associated elements of the animateMotion element in BasicAnimation.
See The animateMotion element.
keyTimes,
keySplines, and
calcMode
 
 
Extend the specification animation function and effect. See The animateMotion element and Spline animation function calculation mode.
path
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 [SVG].
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 from 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.
  • For the "absolute" commands ("MLHVZC"), the host language must specify the coordinate system of the path values.
  • 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.

A path data segment must begin with either one of the "moveto" commands.

Move To commands - "M <x> <y>" or "m <dx> <dy>"
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.
Line To commands - "L <x> <y>" or "l <dx> <dy>"
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.
Horizontal Line To commands - "H <x>" or "h <dx>"
Draws a horizontal line from the current point (cpx, cpy) to (x, cpy). Multiple x values can be provided.
Vertical Line To commands - "V <y>" or "v <dy>"
Draws a vertical line from the current point (cpx, cpy) to (cpx, y). Multiple y values can be provided.
Closepath commands - "Z" or "z"
The "closepath" causes an automatic straight line to be drawn from the current point to the initial point of the current subpath.
Cubic Bezier Curve To commands - 
  "C <x1> <y1> <x2> <y2> <x> <y>" or 
  "c <dx1> <dy1> <dx2> <dy2> <dx> <dy>"
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.

For all calcMode settings, the definition of the simple animation function, f(t), uses the number of values in the values attribute to determine how the simple duration is d is divided into segments. When a path attribute is used, 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. When a path is combined with a paced calcMode setting, all "move to" commands are considered to have 0 duration (i.e. they always happen instantaneously), and should not be considered in computing the pacing.

If the path attrtibute is is specified, any from/to/by or values attribute values will be ignored.

Examples are provided above, as are normative definitions of the semantics of all attributes supported by animate.

For complete velocity control, calcMode can be set to spline and the author can specify a velocity control spline with keyTimes and keySplines.

3.7.5 The spline animateColor element

The SplineAnimation module extends the animateColor element defined by the BasicAnimation module, adding the following attributes and values.

Element attributes
 
all attributes and associated elements of the animateColor element in BasicAnimation.
See The animateColor element.
keyTimes,
keySplines, and
calcMode
 
 
Extend the specification animation function and effect. See The animateColor element and Spline animation function calculation mode.

3.8 SMIL 2.0 SplineAnimation Module Details

3.8.1 SplineAnimation integration requirements

To specify the integration of the SMIL 2.0 SplineAnimation module into a host language, the language designer must integrate SMIL 2.0 BasicAnimation into the language, satisfying all the requirements listed in BasicAnimation integration requirements.

In addition to integrating BasicAnimation, the requirements listed in Common animation integration requirements must be satisfied for the SplineAnimation module.

3.8.2 Document type definition (DTD) for the SplineAnimation module

See the full DTD for the SMIL Animation Modules.

3.9 Common Animation Integration Requirements

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

3.9.1 Integration requirements

The host language profile must integrate the SMIL 2.0 BasicInlineTiming module into the host language, satisfying all requirements of that module. In addition, all modules of the SMIL 2.0 Timing and Synchronization modules and of the SMIL 2.0 Time Manipulation modules which are integrated into the host language must be available on BasicAnimation elements.

In particular, the fill attribute is supported on animation elements only if the host langauge integrates the SMIL 2.0 BasicTimeContainers module in addition to the BasicInlineTiming module.

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

Extending Animation

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

Language designers are also encouraged to define support for additive and cumulative animation for non-numeric data types where addition can sensibly be defined.

Constraints on manipulating animation elements

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 id 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 id values introduces considerable complexity, for what is at best a questionable feature.

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.

Note in particular that if the attributeName 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.

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.

Handling syntax errors

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. 

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. 

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

Error handling semantics

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.

Host language designers may not relax the error handling specifications, or the error handling response (as described in Handling syntax errors). For example, host language designers may not define error recovery semantics for missing or erroneous values in the values or keyTimes attribute values.

3.10 SMIL 2.0 Animation Modules Document Type Definition (DTD) 

<!-- ======================================================================= -->
<!-- SMIL Animation Module  ================================================ -->
<!-- file: SMIL-anim.mod

     This is SMIL 2.0.
     Copyright 2000 W3C (MIT, INRIA, Keio), All Rights Reserved.

        Author:     Patrick Schmitz, Ken Day, Jacco van Ossenbruggen
        Revision:   $Id: smil20.html,v 1.3 2000/09/21 14:27:33 hugo Exp $

     This DTD module is identified by the PUBLIC and SYSTEM identifiers:

     PUBLIC "-//W3C//ELEMENTS SMIL 2.0 Animation//EN"
     SYSTEM "SMIL-anim.mod"

     ======================================================================= -->


<!-- ============================= Dependencies ============================ -->
<!-- The integrating profile is expected to define the following entities,
     Unless the defaults provided are sufficient.
 -->

<!-- SplineAnimation.module entity:  Define as "INCLUDE" if the integrating
     profile includes the SMIL 2.0 SplineAnimation Module, "IGNORE" if not.
     The default is "IGNORE", i.e. by default SplineAnimation is not included
     in the integrating language profile.
 -->
<!ENTITY % SplineAnimation.module "IGNORE">

<!-- Animation depends on SMIL Timing, importing the attributes listed
     in the AnimationTime.attrib entity.  If the integrating profile does 
     include the MinMaxTiming.module, its default value includes the 
     attributes defined in BasicInlineTiming.attrib and inMaxTiming.attrib.
     Otherwise, it is defaulted to BasicInlineTiming.attrib, which is the 
     minimum requirement.
     
     Note that the profile can override these defaults by redefining 
     AnimationTime.attrib.  The profile is also expected to define 
     Fill.attrib.
 -->
<!ENTITY % MinMaxTiming.module "IGNORE">
<![%MinMaxTiming.module;[
  <!ENTITY % AnimationTime.attrib "
	%BasicInlineTiming.attrib;
	%MinMaxTiming.attrib;
  ">
]]>
<!ENTITY % AnimationTime.attrib "%BasicInlineTiming.attrib;">
<!ENTITY % Fill.attrib "">

<!ENTITY % animTimingAttrs "
  %AnimationTime.attrib;             
  %Fill.attrib;            
">

<!-- Language Designer chooses to integrate targetElement or xlink attributes.
     To integrate the targetElement attribute, define the entity
     animation-targetElement as "INCLUDE"; to integrate the XLink attributes,
     define animation-XLinkTarget as "INCLUDE".
     
     One or the other MUST be defined.  It is strongly recommended that only one
     of the two be defined.
-->

<!ENTITY % animation-targetElement "IGNORE">
<![%animation-targetElement;[
  <!ENTITY % animTargetElementAttr
   "targetElement  IDREF  #IMPLIED"
  >
]]>
<!ENTITY % animTargetElementAttr "">

<!ENTITY % animation-XLinkTarget "IGNORE">
<![%animation-XLinkTarget;[
  <!ENTITY % animTargetElementXLink "
    actuate        (onRequest|onLoad)                  'onLoad' 
    href           %URI;                               #IMPLIED
    show           (new | embed | replace)             #FIXED 'embed'
    type           (simple | extended | locator | arc) #FIXED 'simple'
">
]]>
<!ENTITY % animTargetElementXLink "">


<!-- ========================== Attribute Groups =========================== -->

<!-- All animation elements include these attributes -->
<!ENTITY % animAttrsCommon
 "%Core.attrib;
  %I18n.attrib;
  %System.attrib;
  %animTimingAttrs;
  %animTargetElementAttr;
  %animTargetElementXLink;"
>

<!-- All except animateMotion need an identified target attribute -->
<!ENTITY % animAttrsNamedTarget
 "%animAttrsCommon;
  attributeName  CDATA  #REQUIRED
  attributeType  CDATA  #IMPLIED"
>

<!-- All except set support the full animation-function specification,
     additive and cumulative animation.
     SplineAnimation adds the attributes keyTimes, keySplines and path,
	 and the calcMode value "spline", to those of BasicAnimation.
 -->
<![%SplineAnimation.module;[
  <!ENTITY % splineAnimCalcModeValues "| spline">
  <!ENTITY % splineAnimValueAttrs
   "keyTimes CDATA #IMPLIED
    keySplines CDATA #IMPLIED"
  >
  <!ENTITY % splineAnimPathAttr
   "path CDATA #IMPLIED"
  >
]]>
<!ENTITY % splineAnimCalcModeValues "">
<!ENTITY % splineAnimValueAttrs "">
<!ENTITY % splineAnimPathAttr "">

<!ENTITY % animValueAttrs "
  %BasicAnimation.attrib;
  calcMode   (discrete|linear|paced %splineAnimCalcModeValues;) 'linear'
  %splineAnimValueAttrs;
  additive   (replace | sum) 'replace'
  accumulate (none | sum) 'none'"
>


<!-- ========================== Animation Elements ========================= -->

<!ENTITY % animate.attrib  "">
<!ENTITY % animate.content "EMPTY">
<!ENTITY % animate.qname   "animate">
<!ELEMENT %animate.qname; %animate.content;>
<!ATTLIST %animate.qname; %animate.attrib;
  %animAttrsNamedTarget;
  %animValueAttrs;
>

<!ENTITY % set.attrib  "">
<!ENTITY % set.content "EMPTY">
<!ENTITY % set.qname   "set">
<!ELEMENT %set.qname; %set.content;>
<!ATTLIST %set.qname; %set.attrib;
  %animAttrsNamedTarget;
  to  CDATA  #IMPLIED
>

<!ENTITY % animateMotion.attrib  "">
<!ENTITY % animateMotion.content "EMPTY">
<!ENTITY % animateMotion.qname   "animateMotion">
<!ELEMENT %animateMotion.qname; %animateMotion.content;>
<!ATTLIST %animateMotion.qname; %animateMotion.attrib;
  %animAttrsCommon;
  %animValueAttrs;
  %splineAnimPathAttr;
  origin  (default)  "default"
>


<!ENTITY % animateColor.attrib  "">
<!ENTITY % animateColor.content "EMPTY">
<!ENTITY % animateColor.qname   "animateColor">
<!ELEMENT %animateColor.qname; %animateColor.content;>
<!ATTLIST %animateColor.qname; %animateColor.attrib;
  %animAttrsNamedTarget;
  %animValueAttrs;
>

<!-- ========================== End Animation ============================= -->
<!-- end of SMIL-anim.mod -->

4. The SMIL 2.0 Content Control Modules

Editors
Dick Bulterman, (Dick.Bulterman@oratrix.com), Oratrix
Jeffrey Ayars (jeffa@real.com), RealNetworks

4.1 Introduction

This section defines the SMIL 2.0 content control modules. These modules contain elements and attributes which provide for runtime content choices and optimized content delivery. SMIL content control functionality is partitioned across four modules:

Since all of the content control elements and attributes are defined in modules, designers of other markup languages can reuse this functionality on a module by module basis when they need to include media content control in their language.

The functionality in the CustomTestAttributes module builds on the functionality of the BasicContentControl module; profiles implementing the CustomTestAttributes module must also implement the BasicContentControl module. The PrefetchControl and SkipContentControl modules have no prerequisites.

In some of the module descriptions for content control, the concept of "user preference" may be present. User preferences are usually set by the playback engine using a preferences dialog box, but this specification does not place any restrictions on how such preferences are communicated from the user to the SMIL player.

It is implementation dependent when content control attributes are evaluated. Attributes may be evaluated multiple times. Dynamic reevaluation is allowed but not required.

4.2 The SMIL 2.0 BasicContentControl Module

4.2.1 SMIL 2.0 BasicContentControl Module Overview

SMIL 1.0 provides a "test-attribute" mechanism to process an element only when certain conditions are true, for example when the language preference specified by the user matches that of a media object. One or more test attributes may appear on media object references or timing structure elements; if the attribute evaluates to true, the containing element is played, and if the attribute evaluates to false the containing element is ignored. SMIL 1.0 also provides the switch element for expressing that a set of document parts are alternatives, and that the first one fulfilling certain conditions should be chosen. This is useful to express that different language versions of an audio file are available, and that the client may select one of them.

The SMIL 2.0 BasicContent module includes the test attribute functionality from SMIL 1.0 and extends it by supporting new system test attributes. This section will describe the use of the predefined system test attributes, the switch element and test attribute in-line placement. A mechanism for extending test attributes is presented in the CustomTestAttributes module.

Predefined System Test Attributes

This specification defines a list of test attributes that can be added to language elements, as allowed by the language designer. In SMIL 1.0, these elements are synchronization and media elements. Conceptually, these attributes represent Boolean tests. When any of the test attributes specified for an element evaluates to false, the element carrying this attribute is ignored.

SMIL 2.0 supports the full set of SMIL 1.0 system attributes. The SMIL 1.0 compatible system test attributes are:

Note that, with the exception of system-overdub-or-caption, the names of these attributes have been changed to reflect SMIL 2.0's camelCase conventions. The SMIL 1.0 hyphenated names are deprecated in this release.

New to SMIL 2.0 are system test attributes that define additional characteristics of the system environment. These are:

The complete definition of each attribute is given in the attributes definition section.

The switch element

The switch element allows an author to specify a set of alternative elements from which only the first acceptable element is chosen.

An example of the use of the switch is: 

  ...
  <par>
    <video src="anchor.mpg" ... />
    <switch>
      <audio src="dutchHQ.aiff" systemBitrate="56000" ... />
      <audio src="dutchMQ.aiff" systemBitrate="28800" ... />
      <audio src="dutchLQ.aiff" ... />
    </switch>
  </par> 
  ...

In this example, one audio object is selected to accompany the video object. If the system bitrate is 56000 or higher, the object dutchHQ.aiff is selected. If the system bitrate is at least 28800 but less than 56000, the object dutchMQ.aiff is selected. If no other objects are selected, the alternative dutchLQ.aiff is selected, since it has no test attribute (thus is always acceptable) and no other test attributes evaluated to true.

Authors should order the alternatives from the most desirable to the least desirable. Furthermore, authors may wish to place a relatively fail-safe alternative as the last item in the switch so that at least one item within the switch is chosen (unless this is explicitly not desired).

Note that some network protocols, e.g. HTTP and RTSP, support content-negotiation, which may be an alternative to using the switch element in some cases.

It is the responsibility of the SMIL 2.0 player to determine the setting for system test attribute values. Such settings may be determined statically based on configuration settings, or they may be determined (and re-evaluated) dynamically, depending on the player implementation. Players may not select members of a switch at random.

System Test Attribute In-Line Use

To allow more flexibility in element selection, test attributes may also be used outside of the switch element.

In the following example of in-line test attribute use, captions are shown only if the user wants captions on. 

 ...
 <par>
    <audio src="audio.rm"/>
    <video src="video.rm"/>
    <textstream src="stockticker.rt"/>
    <textstream src="closed-caps.rt" systemCaptions="on"/>
 </par>
 ...

The alternatives indicated by the in-line construct could be represented as a set of switch statements, although the resulting switch could become explosive in size. Use of an in-line test mechanism significantly simplifies the specification of adaptive content, especially in those cases where many independent alternatives exist. Note, however, that there is no fail-safe alternative mechanism (such as defining an element without a test attribute inside of a switch) when using test attributes in-line.

Examples of Switch and Test Attribute Use

  1. Choosing between content with different total bitrates

    In a common scenario, implementations may wish to allow for selection via a systemBitrate attribute on elements. The SMIL 2.0 player evaluates each of the elements within the switch one at a time, looking for an acceptable bitrate value. 

     ...
 <par>
    <text .../>
    <switch>
       <par systemBitrate="40000">
       ...
       </par>
       <par systemBitrate="24000">
       ...
       </par> 
       <par systemBitrate="10000">
       ... 
       </par> 
    </switch> 
 </par> 
 ...

    In this example, if the system bitrate has been determined to be less than 10000 (in mobile telephone cases, for example), then none of the par constructs would be included.

  2. Choosing between audio resources with different bitrates

    The elements within the switch may be any combination of elements. For instance, one could specify an alternate audio track: 

     ...
 <switch>
    <audio src="joe-audio-better-quality" systemBitrate="16000" /> 
    <audio src="joe-audio" />
 </switch>
 ...

    If the system bitrate was less than 16000, the standard-quality audio would be presented by default.

  3. Choosing between audio resources in different languages

    In the following example, an audio resource is available both in Dutch and in English. Based on the user's preferred language, the player can choose one of these audio resources. 

     ...
 <switch>
    <audio src="joe-audio-nederlands" systemLanguage="nl"/>
    <audio src="joe-audio-english" systemLanguage="en"/>
 </switch>
 ...

    In this example, if the system language setting was anything other than Dutch or English, no audio would be presented. To make a choice the default, it should appear as the last item in the list and not contain a test attribute. In the following fragment, English is used as the default: 

     ...
 <switch>
    <audio src="joe-audio-nederlands" systemLanguage="nl"/>
    <audio src="joe-audio-english" />
 </switch>
 ...
  4. Choosing between content written for different screens

    In the following example, the presentation contains alternative parts designed for screens with different resolutions and bit-depths. Depending on the particular characteristics of the screen, the player must use the first alternative in which all of the test attributes evaluate to true. 

     ...
 <par>
    <text .../>
    <switch>
       <par systemScreenSize="1280X1024" systemScreenDepth="16">
       ...
       </par>
       <par systemScreenSize="640X480" systemScreenDepth="32">
       ...
       </par> 
       <par systemScreenSize="640X480" systemScreenDepth="16"> 
       ... 
       </par> 
    </switch> 
 </par> 
 ...
  5. Supporting multiple options via in-line use

    This example shows a video that is accompanied by zero or more media objects. If the system language has been set to either Dutch or English, then the appropriate audio object will play. In addition, if the system language has been set to either Dutch or English and systemCaptions has also been set to on, the appropriate text files will also be displayed. 

      ...
  <par>
    <video src="anchor.mpg" ... />
    <audio src="dutch.aiff"   systemLanguage="nl"  ... />
    <audio src="english.aiff" systemLanguage="en" ... />
    <text  src="dutch.html"   systemLanguage="nl" systemCaption="on"... />
    <text  src="english.html" systemLanguage="en" systemCaption="on"... />
  </par> 
  ...

    If system language is set to something other than Dutch or English, no objects will be rendered (except the video). Note that there is no catch-all default mechanism when using test attributes for in-line evaluation.

  6. Choosing the language of overdub and subtitle tracks

    In the following example, a French-language movie is available with English, German, and Dutch overdub and subtitle tracks. The following SMIL segment expresses this, and switches on the alternatives that the user prefers. 

     ...
 <par>
    <switch>
       <audio src="movie-aud-en.rm" systemLanguage="en"
             systemOverdubOrSubtitle="overdub"/>
       <audio src="movie-aud-de.rm" systemLanguage="de"
             systemOverdubOrSubtitle="overdub"/>
       <audio src="movie-aud-nl.rm" systemLanguage="nl"
             systemOverdubOrSubtitle="overdub"/>
       <!-- French for everyone else --> 
       <audio src="movie-aud-fr.rm"/>
    </switch> 
    <video src="movie-vid.rm"/>
    <switch> 
       <textstream src="movie-sub-en.rt" systemLanguage="en" 
             systemOverdubOrSubtitle="subtitle"/>
       <textstream src="movie-sub-de.rt" systemLanguage="de"
             systemOverdubOrSubtitle="subtitle"/> 
       <textstream src="movie-sub-nl.rt" systemLanguage="nl"
             systemOverdubOrSubtitle="subtitle"/> 
       <!-- French captions for those that really want them --> 
       <textstream src="movie-caps-fr.rt" systemCaptions="on"/>
    </switch> 
 </par> 
 ...

4.2.2 Elements and Attributes

SMIL 2.0 BasicContentControl defines the switch element and a set of predefined system test attributes.

The switch element

The switch element allows an author to specify a set of alternative elements. An element is selected as follows: the player evaluates the elements in the order in which they occur in the switch element. The first acceptable element is selected at the exclusion of all other elements within the switch. Implementations must NOT arbitrarily pick an object within a switch when test attributes for all child elements fail.

Element attributes

This element does not have attributes beyond those required of all elements in the profile.

Element content

The content of the element is language implementation dependent.

In the SMIL 2.0 language profile, if the switch is used as a direct or indirect child of a body element, it may contain any media object or timing structure container, or it may contain nested switch elements. All of these elements may appear multiple times inside the switch. If the switch is used as a direct or indirect child of a head element, it may contain one or more layout elements.

Predefined Test Attributes

SMIL 2.0 defines the following system test attributes. When any of the test attributes specified for an element evaluates to false, the element carrying this attribute is ignored. Note that most hyphenated test attribute names from SMIL 1.0 have been deprecated in favor of names using the current SMIL camelCase convention. For these, the deprecated SMIL 1.0 name is shown in parentheses after the preferred name.

systemAudioDesc
values: on | off
This test attribute specifies whether or not closed audio descriptions should be rendered. This is intended to provide authors with the ability to support audio descriptions in the same way that systemCaptions provides text captions. The value of systemAudioDesc is used to control object rendering in conjunction with the user's preference for receiving audio descriptions of a media object if and when these are available. A value of on indicates a preference to have such descriptions rendered when available. A value of off indicates a preference not to render such descriptions.
Authors should place systemAudioDesc = on only on elements that they wish to render when the user has indicated they want audio descriptions. Authors should place systemAudioDesc = off only on elements that they wish to render when the user has indicated they DON'T want audio descriptions.
Evaluates to true if the user preference matches this attribute value. Evaluates to false if they do not match.
systemBitrate (system-bitrate)
value: the approximate bandwidth, in bits-per-second, available to the system.
The measurement of bandwidth is application specific, meaning that applications may use sophisticated measurement of end-to-end connectivity, or a simple static setting controlled by the user. In the latter case, this could for instance be used to make a choice based on the user's connection to the network. Typical values for modem users would be 14400, 28800, 56000 bit/s etc. Evaluates to true if the available system bitrate is equal to or greater than the given value. Evaluates to false if the available system bitrate is less than the given value.
The attribute can assume any integer value greater than 0. If the value exceeds an implementation-defined maximum bandwidth value, the attribute always evaluates to false.
systemCaptions (system-captions)
values: on | off
This attribute allows authors to to specify a redundant text equivalent of the audio portion of the presentation. Examples of intended use are: audiences with hearing disabilities, those learning to read, or anyone who wants or needs this information.
Evaluates to true if the user preference matches this attribute value. Evaluates to false if they do not match.
systemComponent
value: an XML CDATA string containing one or more white-space separated URIs.
Each URI identifies a component of the playback system, e.g. user agent component/feature, number of audio channels, codec, HW mpeg decoder, etc. The URI is implementation dependent. Each implementation is encouraged to publish a list of component URIs which can be used to identify and resolve the presence of implementation-dependent components.
Evaluates to true if the URI can be dereferenced and if the resulting value is true. Evaluates to false otherwise.
systemCPU
value: an XML NMTOKEN [XML10].
This test attribute specifies the CPU on which a user agent may be running. An implementation must allow the user the ability to set the system value to unknown for privacy.
The following list contains the suggested values for this test attribute (additional names may be supported by an implementation): alpha, arm, arm32, hppa1.1, m68k, mips, ppc, rs6000, vax, x86, unknown.

These values come from the _PR_SI_ARCHITECTURE constants defined by the mozilla project.

Evaluates to true if the user preference matches this attribute value. Evaluates to false if they do not match. The value is case-sensitive.
systemLanguage (system-language)
values: a comma-separated list of language names as defined in [RFC1766]
This attribute evaluates to true (1) if one of the languages indicated by user preferences exactly equals one of the languages given in the value of this parameter, or (2) if one of the languages indicated by user preferences exactly matches a prefix of one of the languages given in the value of this parameter such that the first tag character following the prefix is "-". Evaluates to false otherwise. For example, if generic English is specified in the user preferences, it will match both "en" by case (1) and "en-gb" (British English) by case (2), but if British English is specified in the user preferences, it will match only "en-gb" by case (1).

Implementation: When making the choice of linguistic preference available to the user, implementers should take into account the fact that most users are not familiar with the details of language matching as described above, and should provide appropriate guidance. As an example, users may mistakenly assume that on selecting "en-gb", they will be served any kind of English document if British English is not available. The user interface for setting user preferences should guide the user to add "en" to get the best matching behavior.

systemOperatingSystem
value: an XML NMTOKEN [XML10].
This test attribute specifies the operating system on which a user agent may be running. An implementation must allow the user the ability to set the user preference to unknown for privacy.
The following list contains the suggested values for this test attribute (additional names may be supported by an implementation): aix, beos, bsdi, dgux, freebsd, hpux, irix, linux, macos, ncr, nec, netbsd, nextstep, nto, openbsd, openvms, os2, osf, palmos, qnx, sinix, rhapsody, sco, solaris, sonly, sunos, unixware, win16, win32, win9x, winnt, wince, unknown.

These values come from the _PR_SI_SYSNAME constants defined by the mozilla project.

Evaluates to true if the user preference matches this attribute value. Evaluates to false if they do not match. The value is case-sensitive.
systemOverdubOrSubtitle
values: overdub | subtitle
This attribute specifies whether subtitles or overdub is rendered. overdub selects for substitution of one voice track for another, and subtitle means that the user prefers the display of text in a language other than that which is being used in the audio track.
Evaluates to true if the user preference matches this attribute value. Evaluates to false if they do not match.
system-overdub-or-caption
values: caption | overdub
This test attribute has been deprecated in favor of using systemOverdubOrSubtitle and systemCaptions.
This attribute is a setting which determines if users prefer overdubbing or captioning when the option is available.
Evaluates to true if the user preference matches this attribute value. Evaluates to false if they do not match.
systemRequired (system-required)
value: the namespace prefix of a language extension
This attributes provides an extension mechanism for new elements or attributes. Evaluates to true if the extension is supported by the implementation, otherwise, this evaluates to false. [XML-NS]
systemScreenDepth (system-screen-depth)
values: a number greater than 0
This attribute specifies the depth of the screen color palette in bits required for displaying the element. Typical values are 1 | 4 | 8 | 24 | 32.
Evaluates to true if the playback engine is capable of displaying images or video with the given color depth. Evaluates to false if the playback engine is only capable of displaying images or video with a smaller color depth.
systemScreenSize (system-screen-size)
value: a screen size
Attribute values have the following syntax:
screen size ::= screen-height"X"screen-width
Each of these is a pixel value, and must be an integer value greater than 0.
Evaluates to true if the playback engine is capable of displaying a presentation of the given size. Evaluates to false if the playback engine is only capable of displaying smaller presentations.

It is the responsibility of the SMIL 2.0 Player to determine the settings for each predefined test variable. These values may be determined by static configuration settings, or they may be evaluated dynamically during runtime. Such setting and (re)evaluation behavior is implementation dependent.

Authors should realize that if several alternative elements are enclosed in a switch, and none of them evaluate to true, this may lead to situations such as a media object being shown without one or more companion objects. It is thus recommended to include a "catch-all" choice at the end of a switch which is acceptable in all cases.

4.2.3 Integration Requirements for the BasicContentControl Module

The functionality in this module does not build on functionality defined in other SMIL 2.0 modules.

4.2.4 Document Type Definition (DTD) for the BasicContentControl Module

See the full DTD for the SMIL Content Control modules.

4.3 The SMIL 2.0 CustomTestAttributes Module

4.3.1 SMIL 2.0 CustomTestAttributes Module Overview

The use of predefined system test attributes in the SMIL BasicContentControl module provides a selection mechanism based on attributes that are fixed within the module's definition. The CustomTestAttribute module extends this facility with the definition of author-defined custom test attributes. Custom test attributes allow presentation authors to define their own test attributes for use in a specific document. Custom test attributes may be shared among application documents using the uid attribute.

As with system test attributes, custom test attributes can be used within timing structure and media object elements; if they evaluate to true, the containing element is activated and if they evaluate to false, the containing element is ignored.

Since custom test attributes are application/document specific, they need a mechanism to allow attribute definition and attribute setting. Attribute definition is done via the customAttributes and customTest elements. The initial state of any custom test attribute can be set at author-time with the defaultState attribute, which takes a value of either true or false. This module provides an override attribute with a value not-allowed that gives an author the ability to prohibit runtime resetting of any attributes using these mechanisms; if this value is present, its must be enforced by the document player.

The state of the attribute can be changed in one of three ways:

  1. by modifying the value of the default state attribute in the document source before delivery to the player;
  2. by using the unique identifier given in the uid attribute to dereference a runtime value for the customTest; or
  3. by an interface presented to the user (or the user agent) through the document player at runtime.

The exact rules for setting and modifying the values associated with custom test attributes are given below.

An implementation may support either, both, or none of methods 2 and 3. If method 2 is supported, the URI value in uid is simply a unique identifier and does not imply that the runtime value must be fetched over the Web. The value may be stored and retrieved locally, and simply identified by the uid. The precise manner in which this is done is implementation dependent. If method 3 is supported, the custom test attribute facility does not require any specific UI support for direct user manipulation of the custom test attributes.

Example Use

The following example shows one way in which custom test attributes can be applied within a SMIL 2.0 Language profile document: 

<smil>
  <head>
    <layout>
       <!-- define projection regions -->
    </layout>
    <customAttributes>
      <customTest id="west-coast" title="West Coast Edition" 
        defaultState="false" override="allowed"  
        uid="http://defs.example.org/user-settings/west-coast" />
      <customTest id="east-coast" title="East Coast Edition" 
        defaultState="false" override="allowed" 
        uid="http://defs.example.org/user-settings/east-coast" />
      <customTest id="far-north"  title="Northern Edition"
        defaultState="false" override="allowed"
        uid="http://defs.example.org/user-settings/far-north" />
      <customTest id="the-rest"   title="National Edition"
        defaultState="true"  override="not-allowed" />
    </customAttributes>
  </head>
  <body>
    ...
    <par>
      <img src="background.png" region="a"/>
      <video src="story_1v.rm" region="b" />
      <switch>
        <audio src="story_1w.rm" region="c" customTest="west-coast"/>
        <audio src="story_1e.rm" region="c" customTest="east-coast"/>
        <audio src="story_1n.rm" region="c" customTest="far-north"/>
        <audio src="story_1r.rm" region="c" customTest="the-rest"/>
      </switch>
    </par>
    ...
  </body>
</smil>

The customAttributes element in the header contains the definition of the available custom test attributes. Each custom test attribute, defined by the customTest element, contains an identifier and a title (which can be used by a user agent, if available, to label the attribute), as well as an (optional) initial state definition, a UID that contains a unique identifier for the value setting for this attribute and an override flag.

The custom test variables named "west-coast", "east-coast" and "far-north" are defined with a default rendering state of false. They each contain a reference to a URI which is used to define local settings for the respective variables.

The custom test variable "the-rest" is defined with a default rendering setting of true.

Inside the body, a SMIL switch construct is used to select media objects for inclusion in a presentation depending on the values of the various custom test attributes. The first object that contains a value of true will be rendered, and since in this example the last option will always resolve true, it will be rendered if no other objects resolve to true.

While this example shows switch-based use of custom test attributes, the facility could also be applied as test attributes in in-line use.

Rules for Setting Values

The setting of the value associated with a custom test attribute proceeds as follows:

  1. The initial setting is taken from the value of the defaultState attribute, if present. If no default state is explicitly defined, a value of false is used.
  2. Next, if a URI mechanism is supported by the implementation and if the value of the override attribute has been defined and is allowed or uid-only, the URI defined by the uid attribute is checked to see if a persistent value has been defined for the custom test attribute with the associated id. If such a value is present, it is used instead of the default state defined in the document (if any). Otherwise, the existing initial state is maintained.
  3. Next, if a UI-based mechanism (either via the SMIL DOM, a player GUI or some other means) is available, and if the value of the override attribute has been defined and has a value of allowed, the value associated with the custom test attribute is set to the user-specified value. If no user preference has been defined, either the UID-based value or the default value from the document text (in that order) is used.

Note that whenever the author has defined allowed as the value for override, a user setting of the custom test attribute will take precedence over a URI setting. If the attribute value is uid-only, then the URI setting takes precedence. As with predefined system test attributes, this evaluation will occur in an implementation-defined manner. The value may be (re)evaluated dynamically, but this is not required. Note also that not all implementations need support uid or UI setting of attributes.

4.3.2 Elements and Attributes

This section defines the elements and attributes that make up the functionality in the SMIL CustomTestAttributes module. The customAttributes and customTest elements are used to define custom test attribute variables and the customTest attribute is used in-line on media object and timing structure references to control evaluation of the containing elements.

The customAttributes element

The customAttributes element contains definitions of each of the custom test attributes. The contained elements define a collection of author-specified test attributes that can be used in switch statements or as in-line test attributes in the document.

Element attributes

This element does not have attributes beyond those required of all elements in the profile.

Element content

The customAttributes element may contain one or more customTest elements.

The customTest element

The customTest element defines an author-specified name that will be used as the test argument in the switch element or in-line on media object and timing structure elements. The customTest elements are defined within the section delineated by the customAttributes elements that make up part of the document header.

Element attributes
defaultState
values: true | false
The initial state for the named custom test variable is given in the value of this attribute. If unspecified, it defaults to false.
The run-time state for the named custom test variable may be set according to the rules for uid and/or override attribute processing, if present. The values are not case-sensitive.
override
values: allowed | not-allowed | uid-only
This attributes gives the author the ability to block URI or user/user-agent overrides to the initial state by a user directly or via the SMIL DOM or other mechanism. The default value is not-allowed. If a value of allowed is given, either the user/user-agent or URI processing mechanism (in that order) may override the default value of the associated variable. If a value of uid-only is given, only the URI processing mechanism (if available) may override the default value of the associated variable. It is up to the runtime environment to enforce this setting. The values are not case-sensitive.
uid
values: A URI
The URI identifies the associated custom test for persistent use. The user agent should use this as the key to store and retrieve values associated with the custom test attribute, and take care that privacy and security issues are regarded. If the permitted by the override attribute, a resolved reference to a setting via the uid attribute defines the initial setting of the custom test value; this value may be overridden by the user/user-agent if permitted by the override attribute. It is up to the runtime environment to enforce this attribute.

The actual evaluation mechanism associated with the URI is implementation dependent. It can vary from a simple lookup in a local file or registry, to a secure reference via a capabilities database, and may be influenced by other configuration settings provided by the implementation.

Element content

None.

The customTest attribute

In addition to the customAttributes and customTest elements, this module provides a customTest attribute that can be applied by language designers to media objects and timing structure elements requiring selection. In all operational aspects, the custom test attribute is similar to the predefined system test attribute facility of the Basic Content Control module.

customTest
value: an XML identifier
The identifier, defined in a customTest element, defines a variable that is evaluated as a test attribute. If the variable evaluates to true, the associated element is evaluated, otherwise it and its content are skipped. customTest attributes whose value doesn't match the identifier of a customTest element evaluate to false.

4.3.3 Integration Requirements for the CustomTestAttribute Module

The functionality in this module builds on functionality defined in the BasicContentControl module, which is a required prerequisite for inclusion of the CustomTestAttribute module.

The profile implementing the custom test elements and attributes must provide a means of associating a unique XML identifier with a customTest element, so that it can be used by the customTest attribute. And the profile should provide a means of associating descriptive text with a customTest element, which may be used in a GUI or other selection mechanism that may be presented to the user. For the SMIL 2.0 Language Profile, the element's id and title attributes serve this purpose.

4.3.4 Document Type Definition (DTD) for the CustomTestAttribute Module

See the full DTD for the SMIL Content Control modules.

4.4 The SMIL 2.0 PrefetchControl Module

4.4.1 SMIL 2.0 PrefetchControl Module Overview

This module defines an element and attributes that can be used to control the fetching of content from a server in a manner that will improve the rendering performance of the document.

This element will give a suggestion or hint to a user agent that a media resource will be used in the future and the author would like part or all of the resource fetched ahead of time to make the document playback smoother. User-agents can ignore prefetch elements, though doing so may cause an interruption in the document playback when the resource is needed. It gives authoring tools or savvy authors the ability to schedule retrieval of resources when they think that there is available bandwidth or time to do it. A prefetch element is contained within the body of an XML document, and its scheduling is based on its lexical order unless explicit timing is present.

Prefetching data from a URL that changes the content dynamically is potentially dangerous: if the entire resource isn't prefetched, a subsequent request for the remaining data may yield data from a newer resource. A user agent should respect any appropriate caching directives applied to the content, e.g. no-cache 822 headers in HTTP. More specifically, content marked as non-cacheable would have to be refetched each time it was played, where content that is cacheable could be prefetched once, with the results of the prefetch cached for future use.

Examples

  1. Prefetch an image so it can be displayed immediately after a video ends: 
     <smil> 
   <body> 
     <seq>
       <par>
         <prefetch id="endimage"
            src="http://www.example.org/logo.gif"/>
         <text id="interlude"
            src="http://www.example.org/pleasewait.html" fill="freeze"/>
       </par>
       <video id="main-event" src="rtsp://www.example.org/video.mpg"/> 
       <image src="http://www.example.org/logo.gif" dur="5s"/>  
    </seq> 
   </body> 
 </smil>

    The example starts with a prefetch in parallel with the rendering of a text object. The text is discrete media so it ends immediately, the prefetch is defaulted to prefetch the entire image at full available bandwidth and the prefetch element ends when the image is downloaded. That ends the <par> and the video begins playing. When the video ends the image is shown.

  2. Prefetch the images for a button so that rollover occurs quickly for the end user: 
     <html>
 <body>
     <prefetch id="upimage" src="http://www.example.org/up.gif"/>
     <prefetch id="downimage" src="http://www.example.org/down.gif"/>
     ....
     <!-- script will change the graphic on rollover -->
     <img src="http://www.example.org/up.gif"/>
   </body>
 </html>

4.4.2 Elements and Attributes

The prefetch element

The prefetch gives authors a mechanism to influence the scheduling of media object transfers from a server to the player.

Documents must still playback even when the prefetch elements are ignored, although rebuffering or pauses in presentation of the document may occur. If the prefetch for a prefetch element is ignored, any timing on the element is still respected, e.g. if a prefetch element has a dur="5s", elements that depend on the prefetch element's timing behave as if the prefetch took 5 seconds.

The intrinsic duration of a prefetch element is either the duration of the media fetch, if the prefetch operation is supported by the implementation, or zero if prefetch is not supported.

If a prefetch element is repeated, due to restart or repeat on a parent element the prefetch operation should occur again. This insures appropriately "fresh" data is displayed if, for example, the prefetch is for a banner ad to a URL whose content changes with each request.

Element attributes

The prefetch element supports the following attributes:

mediaSize
values: bytes-value | percent-value
Defines how much of the resource to fetch as a function of the file size of the resource. To fetch the entire resource without knowing its size, specify 100%. The default is 100%.
mediaTime
values: clock-value | percent-value
Defines how much of the resource to fetch as a function of the duration of the resource. To fetch the entire resource without knowing its duration, specify 100%. The default is 100%.
For discrete media (non-time based media like text/html or image/png) using this attribute causes the entire resource to be fetched.
bandwidth
values: bitrate-value | percent-value
Defines how much network bandwidth the user agent should use when doing the prefetch. To use all that is available, specify 100%. The default is 100%.

Any attribute with a value of "0%" is ignored and treated as if the attribute wasn't specified.

If both mediaSize and mediaTime are specified, mediaSize is used and mediaTime is ignored.

If the clipBegin or clipEnd in the media object are different from the prefetch, an implementation can use any data that was fetched but the result may not be optimal.

Attribute value syntax
bytes-value
The bytes-value value has the following syntax:

bytes-value ::= Digit+; any positive number

percent-value
The percent-val value has the following syntax:

percent-value ::= Digit+ "%"; any positive number in the range 0 to 100

clock-value
The clock-value value has the following syntax: 
Clock-val         ::= ( Hms-val | Smpte-val )
Smpte-val         ::= ( Smpte-type )? Hours ":" Minutes ":" Seconds 
                      ( ":" Frames ( "." Subframes )? )?
Smpte-type        ::= "smpte" | "smpte-30-drop" | "smpte-25"
Hms-val           ::= ( "npt=" )? (Full-clock-val | Partial-clock-val 
                      | Timecount-val)
Full-clock-val    ::= Hours ":" Minutes ":" Seconds ("." Fraction)?
Partial-clock-val ::= Minutes ":" Seconds ("." Fraction)?
Timecount-val     ::= Timecount ("." Fraction)? (Metric)?
Metric            ::= "h" | "min" | "s" | "ms"
Hours             ::= DIGIT+; any positive number
Minutes           ::= 2DIGIT; range from 00 to 59
Seconds           ::= 2DIGIT; range from 00 to 59
Frames            ::= 2DIGIT; @@ range?
Subframes         ::= 2DIGIT; @@ range?
Fraction          ::= DIGIT+
Timecount         ::= DIGIT+
2DIGIT            ::= DIGIT DIGIT
DIGIT             ::= [0-9]

For Timecount values, the default metric suffix is "s" (for seconds).

bitrate-value
The bitrate-value value specifies a number of bits per second. It has the following syntax:

bitrate-value ::= Digit+; any positive number

4.4.3 Integration Requirements for the PrefetchControl Module

A profile integrating the PrefetchControl module must add the attributes necessary to specify the media to be fetched. In general, these will be the same resource specifying attributes as those on the media elements themselves. In addition, the profile must add any necessary attributes to control the timing of the prefetch element.

4.4.4 Document Type Definition (DTD) for the PrefetchControl Module

See the full DTD for the SMIL Content Control modules.

4.5 The SMIL 2.0 SkipContentControl Module

4.5.1 SMIL 2.0 SkipContentControl Module Overview

This module contains one attribute, skip-content attribute, that can be used to selectively control the evaluation of the element on which this attribute appears. This attribute is introduced for future extensibility of SMIL. The functionality is unchanged from SMIL 1.0.

4.5.2 Elements and Attributes

Element definition

The SkipContentControl module does not contain any element definitions.

The skip-content attribute

skip-content
value: true | false
This attribute controls whether the content of an element is evaluated or should be skipped.
  • If a new element is introduced in a future version of language allowing markup from a previous version of the language as element content, the skip-content attribute controls whether this content is processed by the user agent.
  • If an empty element in a version of a language becomes non-empty in a future SMIL version, the skip-content attribute controls whether this content is ignored by a user agent, or results in a syntax error.
If the value of the skip-content attribute is true, and one of the cases above apply, the content of the element is ignored. If the value is false, the content of the element is processed.
The default value for skip-content is true.

4.5.3 Integration Requirements for the SkipContentControl Module

It is the responsibility of the language profile to specify which elements have skip-content attributes to enable this expansion mechanism.

4.5.4 Document Type Definition (DTD) for the SkipContentControl Module

See the full DTD for the SMIL Content Control modules.

4.6 Content Control Modules DTD 


<!-- ================================================================= -->
<!-- SMIL Content Control Module  ==================================== -->
<!-- file: SMIL-control.mod

     This is SMIL 2.0.
     Copyright 2000 W3C (MIT, INRIA, Keio), All Rights Reserved.

     Author:     Jacco van Ossenbruggen, Aaron Cohen
     Revision:   $Id: smil20.html,v 1.3 2000/09/21 14:27:33 hugo Exp $

     This DTD module is identified by the PUBLIC and SYSTEM identifiers:

     PUBLIC "-//W3C//ELEMENTS SMIL 2.0 Content Control//EN"
     SYSTEM "SMIL-control.mod"

     ================================================================= -->

<!ENTITY %  BasicContentControl.module "INCLUDE">
<![%BasicContentControl.module;[
  <!ENTITY % switch.attrib "">
  <!ENTITY % switch.content "EMPTY">
  <!ENTITY % switch.qname "switch">
  
  <!ELEMENT %switch.qname; %switch.content;>
  <!ATTLIST %switch.qname; %switch.attrib;
        %Core.attrib;
        %I18n.attrib;
  >
]]>

<!-- ========================= CustomTest Elements ========================= -->
<!ENTITY %  CustomTestAttributes.module "IGNORE">
<![%CustomTestAttributes.module;[

  <!ENTITY % customTest.attrib "">
  <!ENTITY % customTest.qname "customTest">
  <!ENTITY % customTest.content "EMPTY">
  <!ELEMENT %customTest.qname; %customTest.content;>
  <!ATTLIST %customTest.qname; %customTest.attrib;
	defaultState		(true|false)	      'false'
	override		(allowed|not-allowed) 'not-allowed'
	uid			%URI;                 #IMPLIED
        %Core.attrib;
        %I18n.attrib;
  >
  <!ENTITY % customAttributes.attrib "">
  <!ENTITY % customAttributes.qname "customAttributes">
  <!ENTITY % customAttributes.content "EMPTY">
  <!ELEMENT %customAttributes.qname; %customAttributes.content;>
  <!ATTLIST %customAttributes.qname; %customAttributes.attrib;
        %Core.attrib;
        %I18n.attrib;
  >

]]> <!-- end of CustomTestAttributes -->

<!-- ========================= PrefetchControl Elements ==================== -->
<!ENTITY % PrefetchControl.module "IGNORE">
<![%PrefetchControl.module;[
  <!ENTITY % prefetch.attrib "">
  <!ENTITY % prefetch.qname "prefetch">
  <!ENTITY % prefetch.content "EMPTY">
  <!ELEMENT %prefetch.qname; %prefetch.content;>
  <!ATTLIST %prefetch.qname; %prefetch.attrib;
	mediaSize		CDATA		#IMPLIED
	mediaTime		CDATA		#IMPLIED
	bandwidth		CDATA		#IMPLIED
        %Core.attrib;
        %I18n.attrib;
  >
]]>

5. The SMIL 2.0 Layout Modules

Editors
Aaron Cohen (aaron.m.cohen@intel.com), Intel
Dick Bulterman (Dick.Bulterman@oratrix.com), Oratrix
Erik Hodge (ehodge@real.com), RealNetworks

5.1 Introduction

This section is informative.

This section defines the SMIL 2.0 Layout Modules, which are composed of a BasicLayout module and three modules with additional functionality that build on top of the BasicLayout module: the AudioLayout, MultiWindowLayout, and HierarchicalLayout modules. The modules contain elements and attributes allowing for positioning of media elements on the visual rendering surface, and control of audio volume. Since these elements and attributes are defined in modules, designers of other markup languages can choose whether or not to include this functionality in their languages. Therefore, language designers incorporating other SMIL modules do not need to include the layout modules if sufficient layout functionality is already present.

5.2  Overview of the SMIL 2.0 BasicLayout Module

This section is informative.

The functionality in this module is essentially identical with the layout functionality in [SMIL10].

Like SMIL 1.0, SMIL 2.0 BasicLayout modules includes a layout model for organizing media elements into regions on the visual rendering surface. The layout element is used in the document head to declare a set of regions on which media elements are rendered. Media elements declare which region they are to be rendered into with the region attribute.

Each region has a set of CSS2 compatible properties such as top, left, height, width, and backgroundColor. These properties can be declared using a syntax defined by the type attribute of the layout element. In this way, media layout can be described using the SMIL 1.0 basic layout syntax or CSS2 syntax.

For example, to describe a region with the id "r" at location 15,20 that is 100 pixels wide by 50 pixels tall using the SMIL basic layout model: 

    <layout>
    <region id="r" top="15px" left="20px" width="100px" height="50px"/>
    </layout>   

To create the same region using CSS2 syntax: 

    <layout type="text/css">
    [region="r"] { top: 15px; left: 20px; width: 100px; height:50px; }
    </layout>

To display a media element in the region declared above, specify the region's id as the region attribute of the media element: 

    <ref region="r" src="http://..." />  

Additionally, implementations may choose to allow using the CSS syntax to set the media layout directly. This can be done by using the selector syntax to set layout properties on the media elements. For example, to display all video and image elements in a rectangle at the same size and position as the examples above: 

    <layout type="text/css">
    video, img { top:15px; left:20px; width:100px; height=50px; }
    </layout>

Note that multiple layout models could be specified within a control structure such as the SMIL switch element, each with a different type. The first layout with a type supported by the implementation will be the one used.

5.3 SMIL 2.0 BasicLayout Module Syntax and Semantics

This section is normative.

5.3.1 Elements and Attributes

This section defines the elements and attributes that make up the functionality in the SMIL BasicLayout module.

The layout element

The layout element determines how the elements in the document's body are positioned on an abstract rendering surface (either visual or acoustic).

The layout element must appear before any of the declared layout is used in the document. If present, the layout element must appear in the head section of the document. If a document contains no layout element, the positioning of the body elements is implementation-dependent.

It is recommended that profiles including the SMIL 2.0 BasicLayout also support the SMIL 2.0 BasicContentControl module. A document can then support multiple alternative layouts by enclosing several layout elements within the SMIL switch element. This could also be used to describe the document's layout using different layout languages. Support for the system test attributes in the SMIL BasicContentControl module also enables greater author flexibility as well as user accessibility.

Default layout values can be assigned to all renderable elements by selecting the empty layout element <layout></layout>. If the document does not include a layout element, then the positioning of media elements is implementation dependent.

 

Element attributes

type
This attribute specifies which layout language is used in the layout element. If the player does not understand this language, it must skip the element and all of its content up until the next </layout> tag. The default value of the type attribute is "text/smil-basic-layout". This identifier value supports SMIL 1.0 and SMIL 2.0 BasicLayout module layout semantics.
Element content

If the type attribute of the layout element has the value "text/smil-basic-layout", it may contain the following elements:

region
root-layout

Languages incorporating the BasicLayout module need to define what additional elements are allowed as children. If the type attribute of the layout element has another value, the element contains character data. 

The region element

The region element controls the position, size and scaling of media object elements.

In the following example fragment, the position of a text element is set to a 5 pixel distance from the top border of the rendering window: 

<smil>
  <head>
    <layout>
        <root-layout width="320" height="480" />    
              <region id="a" top="5" />
    </layout>
  </head>
  <body>
    <text region="a" src="text.html" dur="10s" />
  </body>
</smil>

The position of a region, as specified by its top, bottom, left, and right attributes, is always relative to the parent geometry, which is defined by the parent element. For the SMIL BasicLayout module, all region elements must have as their immediate parent a layout element, and the region position is defined relative to the root window declared in the sibling root-layout element.

When region sizes, as specified by width and height attributes are declared relative with the "%" notation, the size of a region is relative to the size of the parent geometry. Sizes declared as absolute pixel values maintain those absolute values.

Conflicts between the region size and position attributes width, height, bottom, left, right, and top are resolved according to the rules for absolutely positioned, replaced elements in [CSS2]. The default values of region position and size attributes is specified as auto. This attribute value has the same meaning here that it does in [CSS2]. 

 

Element attributes

The region element can have the following visual attributes:

backgroundColor
The use and definition of this attribute are identical to the "background-color" property in the CSS2 specification. This attribute specifies the background color used to fill the area of a region displaying media that is not filled by the media. The display of the background color when the region is not in use by a media element is controlled by the showBackground attribute. Unlike SMIL 1.0, this module requires support for CSS2 system colors.
background-color
Deprecated. Equivalent to backgroundColor, which replaces this attribute. The language profile must define whether or not the background-color attribute is supported. If both the  backgroundColor and background-color attributes are absent, then the background is transparent.
bottom
The use and definition of this attribute are identical to the "bottom" property in the CSS2 specification. Attribute values can be "percentage" values, and a variation of the "length" values defined in CSS2. For "length" values, SMIL 2.0 BasicLayout only supports pixel units as defined in CSS2. It allows the author to leave out the "px" unit qualifier in pixel values (the "px" qualifier is required in CSS2). Conflicts between the region size attributes bottom,  left, right,  top, width, and height are resolved according to the rules for absolutely positioned, replaced elements in [CSS2]. The default value of this attribute is auto.
fit
This attribute specifies the behavior if the intrinsic height and width of a visual media object differ from the values specified by the height and width attributes in the region element. This attribute does not have a one-to-one mapping onto a CSS2 property, but can be simulated in CSS2.
This attribute can have the following values:
fill
Scale the object's height and width independently so that the content just touches all edges of the box.
hidden
Has the following effect:
  • If the intrinsic height (width) of the media object element is smaller than the height (width) defined in the region element, render the object starting from the top (left) edge and fill up the remaining height (width) with the background color.
  • If the intrinsic height (width) of the media object element is greater than the height (width) defined in the region element, render the object starting from the top (left) edge until the height (width) defined in the region element is reached, and clip the parts of the object below (right of) the height (width).
meet
Scale the visual media object while preserving its aspect ratio until its height or width is equal to the value specified by the height or width attributes, while none of the content is clipped. The object's left top corner is positioned at the top-left coordinates of the box, and empty space at the right or bottom is filled up with the background color.
scroll
A scrolling mechanism should be invoked when the element's rendered contents exceed its bounds.
slice
Scale the visual media object while preserving its aspect ratio so that its height or width are equal to the value specified by the height and width attributes while some of the content may get clipped. Depending on the exact situation, either a horizontal or a vertical slice of the visual media object is displayed. Overflow width is clipped from the right of the media object. Overflow height is clipped from the bottom of the media object.

The default value of fit is hidden.

Note that the fit attribute applies to visual media once it has an intrinsic two-dimensional size, such as images and video. It does not apply to visual media that is rendered and adapted to varying circumstances, such as the visual display of HTML, until its two-dimensional spatial dimensions have been determined, such as after an HTML page has been laid out to specific size.

height
The use and definition of this attribute are identical to the "height" property in the CSS2 specification. Attribute values follow the same restrictions and rules as the values of the bottom attribute.
The default value of this attribute is auto.
left
The use and definition of this attribute are identical to the "left" property in the CSS2 specification.
Attribute values follow the same restrictions and rules as the values of the "bottom" attribute.
The default value of this attribute is auto.
regionName
This attribute assigns a name to this region element that can be referred to by the region attribute of media object elements. The regionName attribute is not a unique identifier; multiple region elements can share the same regionName attribute value.
right
The use and definition of this attribute are identical to the "right" property in the CSS2 specification.
Attribute values follow the same restrictions and rules as the values of the "bottom" attribute.
The default value of this attribute is auto.
showBackground
This attribute controls whether the backgroundColor of a region is shown when no media is being rendered to the region:
  • If the value of showBackground is always, then the background color will be shown in the region when no media object is rendering into that region. If the region is part of a hierarchical layout, then any ancestor regions must also either be active or have a showBackground value of always for the background color to be shown.
  • If the value of showBackground is whenActive, then the background color will be not be shown in the region when no media object is rendering into that region. If the region is part of a hierarchical layout, then the background color will also be shown when any descendent regions are active.
The default value of showBackground is always.
top
The use and definition of this attribute are identical to the "top" property in the CSS2 specification.
Attribute values follow the same restrictions and rules as the values of the bottom attribute.
The default value of this attribute is auto.
width
The use and definition of this attribute are identical to the "width" property in the CSS2 specification.
Attribute values follow the same restrictions and rules as the values of the bottom attribute.
The default value of this attribute is auto.
z-index
The use and definition of this attribute are identical to the "z-index" property in the CSS2 specification, with the following exception:
 
If two boxes generated by elements A and B have the same stack level, then:
  • If the display of an element A starts later than the display of an element B, the box of A is stacked on top of the box of B (temporal order).
  • Else, if the display of the elements starts at the same time, and an element A occurs later in the SMIL document text than an element B, the box of A is stacked on top of the box of B (document tree order as defined in CSS2).
A profile integrating the SMIL 2.0 Basic Layout module must provide a means of declaring an XML identifier on region elements.

The root-layout element

The root-layout element determines the value of the layout properties of the root element, which in turn determines the size of the window in which the SMIL presentation is rendered.

If more than one root-layout element is parsed within a single layout element, this is an error, and the document should not be displayed. This does not include root-layout elements skipped by the player (e.g. because the enclosing layout element was skipped due to an unrecognized type or a test attribute evaluated to false).

The semantics of the root-layout element are as in SMIL 1.0: the attributes of the root-layout element determine the size of the top level presentation window, and the declared sibling regions are arranged within this top level window. If either the height or width of the root-layout element is not specified, the value of the attribute is implementation dependent.

Element attributes

The root-layout element can have the following attributes:

backgroundColor
Defined in backgroundColor under the region element. Note that the default background color is transparent, which implies that, by default, the implementation dependent window background will be shown.
background-color
Defined in background-color under the region element.
height
Sets the height of the root element. Only length values are allowed.
width
Sets the width of the root element. Only length values are allowed.

Element content

The root-layout element is an empty element.

This element supports the SMIL 1.0 syntax where the root-layout element is an empty sibling of the top level region elements.

The region attribute

The region attribute is applied to an element in order to specify which rendering region is assigned to the element. The attribute refers to the abstract rendering region (either visual or acoustic) defined within the layout section of the document. The referenced abstract rendering region is determined by applying the following rules, in order:
  1. Find all elements in the layout section with regionName attributes that are assigned the same value as that of the region attribute.
  2. Remove the elements from this collection that are removed from the rendered presentation due to the processing of switch elements and test attributes.
  3. If any elements remain, the media should be rendered in all of the referred to regions. If the application cannot render the media simultaneously in multiple regions, then the media should be rendered using the lexically first remaining element.
  4. If no elements have a regionName attribute that is assigned the same value as that of the region attribute, then select the element in the layout section whose unique identifier is the value of the region attribute.
If this process selects no rendering surface defined in the layout section, the values of the formatting properties of this element are defined by the default layout values, which is described in the section on integration requirements for this module.

The language integrating this module must specify which elements have a region attribute and any inheritance of the attribute.

5.3.2 SMIL BasicLayout Module Details

SMIL 2.0 BasicLayout module is consistent with the visual rendering model defined in CSS2, it reuses the formatting properties defined by the CSS2 specification, and newly introduces the fit attribute [CSS2]. The reader is expected to be familiar with the concepts and terms defined in CSS2.

Integration Requirements

A profile integrating the SMIL 2.0 Basic Layout module must define default values for all layout-related attributes of elements. These should be consistent with the initial values of the corresponding properties in CSS2, if any. In particular the values of the display and position properties should be defined.

A profile integrating the SMIL 2.0 Basic Layout module must define the content models for the layout element if any elements beyond those specified here are to be allowed as children.

A profile integrating the SMIL 2.0 Basic Layout module must provide a means of declaring an XML identifier on region elements. This value is used as the argument value to the region attribute. In addition, the integrating profile must specify which elements have a region attribute and any inheritance of the attribute.

5.3.3 Document Type Definition (DTD) for the BasicLayout Module

See the full DTD for the SMIL Layout modules.

5.4 Overview of the SMIL 2.0 AudioLayout Module

This section is informative.

This section defines the functionality in the SMIL 2.0 AudioLayout module. This level contains an attribute providing audio rendering surface volume control.

5.4.1 Integration Requirements for the AudioLayout Module

This section is normative.

The functionality in this module builds on top of the functionality in the BasicLayout module, which is a required prerequisite for inclusion of the AudioLayout module.

5.4.2 Audio Volume Control

This section is normative.

SMIL 2.0 AudioLayout module supports control of aural media volumes via a new property on the region element, soundLevel. Multimedia assigned to a region with an explicit soundLevel attribute will have its audio rendered at the given relative sound intensity.

5.5 SMIL 2.0 AudioLayout Module Syntax and Semantics

This section is normative.

5.5.1 Elements and Attributes

This section defines the elements and attributes that make up the SMIL 2.0 AudioLayout module.

The region element

The region element defined in the BasicLayout module is extended with the addition of the soundLevel attribute.
 

Element attributes

The region element can have the following aural attributes:

soundLevel
Specifies the relative volume of the audio portion of a media element assigned to play within the given region. Valid values are percentages relative to the recorded volume of the media, where a value of '100%' will play the media at its recorded volume and '0%' will play the media silently. Similarly, a value of '200%' will play the media twice as loud as it's recorded volume (subject to hardware limitations). The default value is '100%'. The absolute sound level of media perceived is further subject to system volume settings, which cannot be controlled with this attribute.

5.6 Overview of the SMIL 2.0 MultiWindowLayout Module

This section is informative.

This section defines the functionality in the SMIL 2.0 MultiWindowLayout module. This level contains elements and attributes providing for creation and control of multiple top level windows on the rendering device.

5.6.1 Integration Requirements for the MultiWindowLayout Module

This section is normative.

The functionality in this module builds on top of the functionality in the BasicLayout module, which is a required prerequisite for inclusion of the MultiWindowLayout module.

5.6.2 Multiple Top-Level Window Support

This section is normative.

In [[SMIL 1.0]], and the SMIL 2.0 BasicLayout module, each presentation is rendered into a single root window of a specific size/shape. The root window contains all of the regions used to manage the rendering of specific media objects.

This specification supports the concept of multiple top-level windows. Since there is no longer a single root window, we use the term top level instead. The assignment of the regions to individual top level windows allows independent placement and resizing of each top-level window, if supported by the including profile and implementation. The initial placement of the top level windows on the display device and any available means of relocating the top level windows is implementation dependent.

A top level window is declared with the viewport element in a manner similar to the SMIL 1.0 root-layout window, except that multiple instances of the viewport element may occur within a single layout element: 

    
<layout>
  <viewport id="WinV" title="Video" width="320" height="240"/>
    <region id="pictures" title="pictures" height="100%" fit="meet"/>
  </viewport>
  <viewport id="WinC" title="Captions" width="320" height="60">
    <region id="captions" title="caption text" top="90%" fit="meet"/>
  </viewport>
</layout>

In this example, two top-level windows are defined ("WinV" and "WinC"), and two regions are defined with one region ("pictures") assigned to WinV and the other ("captions") to WinC. The definitions of the top-level windows and the contained regions use a hierarchical syntax, unlike the older root-layout element.

The top-level windows function as rendering containers only, that is, they do not carry temporal significance. In other words, each window does not define a separate timeline or any other time-container properties. There is still a single master timeline for the SMIL presentation, no matter how many top-level windows have been created. This is important to allow synchronization between media displayed in separate top-level windows.

The display of top level windows can be controlled automatically by the player, or manually by the user of the application. If a window is closed (by the user) while any of the elements displayed in that window are active, there is no effect on the timeline (if any) of those elements. However, a player may choose not to decode content as a performance improvement. The means provided to a user to close top level windows is implementation dependent. 

For SMIL 1.0 compatibility, the root-layout element will continue to support SMIL 1.0 layout semantics. The new viewport element will support the extension semantics and the improved, nested syntax.

Note also that any one region may belong to at most one top-level (or root-level) window. Regions not declared as children of a viewport element belong to the root-layout window. If no root-layout element has been declared, the region is assigned to an additional window according to the semantics in the BasicLayout module.

5.7 SMIL 2.0 MultiWindowLayout Module Syntax and Semantics

This section is normative.

5.7.1 Elements and Attributes

This section defines the elements and attributes that make up the SMIL 2.0 MultiWindowLayout module.

The viewport element

The viewport element determines the size of the a window in which the SMIL presentation is rendered, as well as serving as a top level window in which to place child region elements.

Multiple viewport elements may appear within a single layout element, each declaring an independent top-level window.

Each instance of a viewport element determines the size of a separate top-level presentation window, and the descendant regions are arranged within this top-level window and relative to the coordinate system of this window.

This module also provides control over when viewport windows open and close in a presentation. Note that the precise mapping of viewport windows on to the host environment is implementation dependent. It is expected that implementations will "pop up" independent desktop windows if they can, but other means of supporting multiple viewports, such as by using frames, are allowed. When automatically opening and closing windows, applications should try to comply with the WAI User Agent Guidelines [UAAG] and allow the user to choose whether to be warned that windows are being opened and closed, and given a method for disabling automatic opening and closing of windows.

Element attributes

The viewport element can have the following attributes:

backgroundColor
Defined in backgroundColor under the region element. Note that the default background color is transparent, which implies that, by default, the implementation dependent window background will be shown.
close
Specifies when the top level window should be closed. If the value of close is never, then the top level window should not be closed automatically by the player and will only close if the user explicitly closes it via the user interface. If the value of close is whenNotActive, then the top level window should close automatically when no media is being displayed in any one of the window's regions. For timed media using the SMIL 2.0 timing and synchronization modules, this means when there is no media within its active duration or freeze period using any region of the viewport. The default value of close is never.
height
Sets the height of the top-level window. Only length values are allowed.
open
Specifies when the top level window should be opened. If the value of open is always, then the top level window should be opened when the presentation begins, and should remain open for the duration of the presentation unless the user explicitly closes it via the user interface. If the value of open is whenActive, then, if not already open, the top level window should be opened when media is displayed in one of the window's regions. For timed media using the SMIL 2.0 timing and synchronization modules, this means when there is any media within its active duration or freeze period using any region of the viewport. The default value of  open is always. 
width
Sets the width of the top-level window. Only length values are allowed.
Element content

The viewport element may contain any number of region elements, or be empty.

Allowing multiple viewport elements within a single layout element supports multiple top level windows.

The layout element

Element content

The layout element defined in the SMIL BasicLayout module is extended with the addition that the viewport element is added to the content model of the layout element if the type attribute of the layout element has the value "text/smil-basic-layout". In this case it can contain the following elements:

region
root-layout
viewport

5.7.2 Document Type Definition (DTD) for the MultiWindowLayout Module

See the full DTD for the SMIL Layout modules.

5.8 Overview of the SMIL 2.0 HierarchicalLayout Module

This section is informative.

This section defines the functionality in the SMIL 2.0 HierarchicalLayout module. This module contains elements and attributes for advanced positioning of media elements on the visual rendering surface and builds upon the SMIL 2.0 BasicLayout module.

The SMIL 2.0 HierarchicalLayout module extends the basic layout model for organizing media elements into regions on the visual rendering surface providing much greater author control and flexibility. These extensions are important for certain classes of multimedia presentations in which author control of object placement is critical.

 This module:

5.8.1 Integration Requirements for the HierarchicalLayout Module

This section is normative.

The functionality in this module builds on top of the functionality in the BasicLayout module, which is a required prerequisite for inclusion of the HierarchicalLayout module.

5.9 New Features in the SMIL 2.0 HierarchicalLayout Module

This section is normative.

5.9.1 Hierarchical Region Layout

A new feature in this module is support for hierarchical layout. This allows for the declaration of regions nested inside other regions, much like regions are laid out inside the top level window declared by the viewport element. For example, the following declares a top level window of 640 by 480 pixels, regions "left" and "right" which covers the left and right sides of the window respectively, and a hierarchical region "inset" that is centered within "right". 

<layout>
        <viewport width="640px" height="480px" />
                <region id="left" top="0%" left="0%"
                             width="50%" height="100%" />
                <region id="right" top="0%" left="50%"
                               width="50%" height="100%">
                        <region id="inset" top="25%" left="25%"
                                         width="50%" height="50%" />
                </region>
        </viewport>
</layout>

The resulting layout looks like this:

picture of layout

By default, each hierarchical region shares the z-index (depth) value of its parent. Hierarchical regions may also introduce their own local z-index value. In this case, all hierarchical regions with a common direct parent define local z-indexes within the z-index value of their parent. For example, if a parent region has a z-index value of "4" and two hierarchical children of that parent define z-indexes of "1" and "2", respectively, then each of these are treated as further sub-divisions of the parent's z-index of "4".

If two hierarchical regions with the same z-index attribute value overlap, the existing rules for z-index processing (from the BasicLayout module) are applied. Specifically, the rule concerning time priority is maintained, meaning that in the case of a z-index conflict, the media visible in the overlap will be determined by the region that is rendering the media that has most recently begun in time. If the conflicting media began at the same time, then the rule using the textual order of the media elements in the SMIL document is applied.

For example: 

<layout>
   <root-layout width="640px" height="480px" />
   <region id="whole" top="0px" left="0px" width="640px" 
                                height="480px" z-index="5"/>
   <region id="right" top="0px" left="320px" width="320px"
                                height="480px" z-index="4">
       <region id="inset" top="140px" left="80" width="160px" 
                                height="200px" z-index="6"/>
       <region id="inset2" top="140px" left="80" width="160px" 
                                height="200px" z-index="6"/>
       <region id="inset3" top="140px" left="80" width="160px" 
                                height="200px" z-index="7"/>
   </region>
</layout>
...
<par>
        <img id="A" region="whole" src="imageA.jpg" dur="10s"/>
        <img id="B" region="inset" src="imageB.jpg" dur="10s"/>
</par>
<par>
        <img id="D" region="inset2" src="imageD.jpg" begin="1s" dur="10s"/>
        <img id="C" region="inset" src="imageC.jpg" begin="0s" dur="10s"/>
</par>
<par>
        <img id="E" region="inset2" src="imageE.jpg" dur="10s"/>
        <img id="F" region="inset3" src="imageF.jpg" dur="10s"/>
</par>
  1. In the first "par", image "A" and image "B" begin at the same time. Image A will obscure image "B", even though the z-index of "inset is greater than that of "whole". This is because the z-index of "right", which is the region containing "inset" is less than that of "whole". 
  2. In the second "par", images "C" and "D" are rendered into regions occupying the same area of the rendering surface. Image "C" will be shown for one second and then obscured by Image "D", since "D" begins after image "C". Note that lexical order is irrelevant here. 
  3. In the third "par", the z-index of region "inset" is considered when computing stacking between siblings, and therefore image "F" will be shown, but image "E" will be obscured for the entire 10 seconds that they are both active.

5.9.2 Sub-Region Layout

Where hierarchical layout provides a facility for defining a set of regions with a common parent, it does not provide any facility for determining where in any particular region a given media object will be placed. The SMIL 2.0 HierarchicalLayout module solves this problem by defining a set of attributes which, when placed on an object using the region attribute, allow that media item to be explicitly positioned within a region. These attributes are collectively referred to as sub-region positioning attributes. The sub-region positioning argument values follow the conventions of CSS2 the absolute positioning property values.

For example, suppose a region "d" is defined: 

  <layout>
     ...
    <region id="d" ... />
     ...
  </layout> 

The following code describes the placement of an object at a particular offset within a region, using the SMIL 2.0 HierarchicalLayout syntax: 

    
     <ref id="a" ... region="d" top="5%" left="3" />

Each placement attribute defines a new, temporary boundary of the region for the referenced media object. In this case, the top-left point of the media object is displayed 5% from the top and 3 pixels from the left in region "d".

All other placement operations, such as the fit attribute, operate on the region as if it had its relevant edges moved to the position specified by the placement attributes. For example, the following document fragment describes a region and a media object reference that make use of sub-region positioning: 

  <layout>
     ...
    <region id="d" ... fit ="fill" />
     ...
  </layout>  

  <body>     ...
     <ref src="..." ... region="d" fit="hidden"
                top="5%" left="3" bottom="10%" right="15%" />
     ...
  </body>

In this example, the effective boundaries of the region for the placement of this object are defined by adjusting the top, bottom, left and right edges of the region by the values shown, and then filling the resulting sub-region with the specified image as directed by the fit attribute. If the size of the media object being displayed is smaller than that of the resulting sub-region, the display will be similar to:

picture of sub-regions

The use of sub-region placement is intended as a light-weight alternative to defining many single-use regions. Often, the dimensions used for the sub-region will match the dimensions of the media object being placed, but in all cases the values of the fit attribute will govern rendering of the object in the sub-region.

Rules for handling clipping of objects within regions based on the sub-region attributes are provided below.

5.9.3 Media Object fit and backgroundColor Override

The SMIL 2.0 HierarchicalLayout module includes the ability to use the fit and backgroundColor attributes on objects displayed in a region in order to override the declared behavior of the region.

5.9.4 Registration Points

A registration element is an element defined within this module that is used to define a point within a region and a default object alignment algorithm about that point. The element can be used in a media object element, where it is associated with a region and an optional override alignment algorithm. The placement values within registration elements can be either percentages or pixels.

The use of registration points allows for consistent relative placement across regions. As such, registration points are defined outside of any single region.

For example, the following code describes two registration points (with id values "midPoint" and "topMargin"), one of which is defined as a relative location and one at a fixed pixel location, using the SMIL 2.0 HierarchicalLayout syntax: 

    <layout>
      <regPoint id="midPoint" top="50%" left="50%" regAlign="center" />
      <regPoint id="topMargin" top="10" left="15" regAlign="topLeft" />
      <region id="a" ... />
      <region id="b" ... />
    </layout> 

In this example, the registration point with the id value "midPoint" has a default alignment algorithm that centers the media object about the defined point, while the registration point with the id value "topMargin" has a default alignment algorithm that places the top-left point of the media object at the registration point.

Various media elements could be displayed in the regions using the alignment points as follows: 

  
    <ref region="a" src="rtsp://..." dur="2s" regPoint="midPoint" /> 
    <ref region="b" src="http://..." dur="2s" 
                         regPoint="midPoint" regAlign="bottomRight"/>
    <ref region="a" src="http://..." dur="2s" regPoint="topMargin" />
    <ref region="b" src="http://..." dur="2s" 
                         regPoint="topMargin" regAlign="center"/>

In the first example, a media object is centered in the middle of region a. In the second example, a media object has its bottom right corner centered in the middle of region b. Similarly, in the third example, a media object has its top left corner placed at a point 10,15 within region a, and in the fourth example, an object is centered around the point 10,15 in region b.

Registration points can be used to coordinate the placement of a set of media objects that do not share the same sizes. (For example, a set of images can be aligned to the center of a region.) They can also be used to coordinate the display of images about a particular point in a region, as in: 

   <layout>
      <regPoint id="middle" top="50%" left="50%" regAlign="center" />
      <region id="a" ... />
   </layout> 
   ...
   <seq>   
    <ref region="a" src="rtsp://..." dur="2s" regPoint="middle" 
                                        regAlign="bottomRight"/> 
    <ref region="a" src="http://..." dur="2s" regPoint="middle" 
                                        regAlign="bottomLeft"/>
    <ref region="a" src="http://..." dur="2s" regPoint="middle" 
                                        regAlign="topLeft"/>
    <ref region="a" src="http://..." dur="2s" regPoint="middle" 
                                        regAlign="topRight"/>
  </seq>

In this example, four objects are aligned over time to the middle of region. If any media element extends outside the bounds of a region, it will be clipped to the region.

Note that registration points are global within the context of a layout, and are not tied to a particular region, but can be reused across regions. As such, pixel-based offsets should be used with care.

 For authoring convenience, SMIL HierarchicalLayout module provides several pre-defined region registration points including topLeft, topMid, topRight, midLeft, center, midRight, bottomLeft, bottomMid, and bottomRight.

For example, media objects can be centered in any region like this: 

    <ref ..." regPoint="center" regAlign="center" />

The default value of regAlign for a region is topLeft. If the regAlign attribute is used without a regPoint attribute, the alignment operation is relative to the upper left point of the region containing this object, that is, the behavior is the same as if the regPoint were to be specified as topLeft.

Rules for handling clipping of objects within regions based on the regPoint and regAlign attributes are defined below.

5.10 SMIL 2.0 HierarchicalLayout Syntax and Semantics

This section is normative.

5.10.1 Elements and attributes

This section defines the elements and attributes that make up the SMIL 2.0 HierarchicalLayout module.

The layout element

This element is defined as in the BasicLayout module with extensions presented here. 

In order to support the registration point functionality described above, one new element is added to the content model of the layout element.

Element attributes

SMIL HierarchicalLayout module does not provide any new attributes to the layout element.

Element content

If the type attribute of the layout element has the value "text/smil-basic-layout", it can contain the following elements:

region
root-layout
viewport
regPoint

All element content except regPoint are defined above in the BasicLayout and MultiWindowLayout modules. The regPoint element is described below.

The region element

The region element controls the position, size and scaling of media object elements. This module extends the definition of the region element to include the definition of hierarchical regions.

The position of a region, as specified by its top and left attributes, is always relative to the parent geometry, which is defined by the parent element. For the SMIL 2.0 HierarchicalLayout module, all hierarchical region elements must have as their immediate parent a region or viewport element. The position of the hierarchical region is defined relative to that parent element.

When region sizes, as specified by width and height attributes are declared relative with the "%" notation, the size of the hierarchical region is relative to the size of the parent region. Sizes declared as absolute pixel values are absolute values even when used with a child region.

Note that a (hierarchical) region may be defined in such a way as to extend beyond the limits of its parent. In this case the child region must be clipped to the parent boundaries.

If a z-index attribute is defined on the hierarchical region, it is evaluated as a local index within that of the parent.

 

Element attributes

In the HierarchicalLayout module, the region element has no additional attributes beyond that provided in the other included layout modules. However, the semantics of the z-index attribute are extended to support hierarchical regions.

z-index
This attribute is defined as in the BasicLayout module with extensions presented here. 
 
The z-index attribute defines the level of the region within the parent region stacking context. Elements assigned to higher level regions are rendered in front of lower level regions within the same parent region. Child regions are always placed in front of their parent region. This results in a two stage sorting of region visibility: first by parent-child containment, and then by z-index within siblings.
 

Element content

SMIL HierarchicalLayout module extends the region element content model to optionally include other region elements.

The regPoint element

The regPoint element determines the (x, y) coordinates of a point relative to a region upper-left corner for use in aligning elements in the document's body on regions within a visual rendering surface. A regPoint may be defined using absolute (pixel) or relative (percentage) based values. The regPoint functionality is not defined and may not be used for media without intrinsic size.

For the purposes of regPoint functionality, media and regions are defined to be rectangular, with perpendicular sides, with the sides ordered clockwise top, right, bottom, and left. The top side is the edge closest to the point or edge of the display device considered "up". 

The regPoint element may only appear as an immediate child of a layout element.

If the registration point or alignment functionality is used on a media object, the interaction between the regPoint value, the regAlign value, and the fit attribute value of the region in which the media object is displayed is as follows:

fill fit value:
This depends on the value of the  regAlign attribute. (Note: in all cases, the media must maintain proper alignment over the regPoint):
topLeft regAlign value:
Scale the object's height and width independently so that the content just touches the bottom and right edges of the box.
topMid regAlign value:
Scale the object's height and width independently so that the content just touches the bottom edge of the box, and the nearest (to the regPoint) of the left or right edges of the box.
topRight regAlign value:
Scale the object's height and width independently so that the content just touches the bottom and left edges of the box.
midLeft regAlign value:
Scale the object's height and width independently so that the content just touches the nearest (to the regPoint) of the top or bottom edges of the box, and touches the right edge of the box.
center regAlign value:
Scale the object's height and width independently so that the content just touches the nearest (to the regPoint) of the top or bottom edges of the box, and touches the nearest (to the regPoint) of the left or right edges of the box.
midRight regAlign value:
Scale the object's height and width independently so that the content just touches the nearest (to the regPoint) of the top or bottom edges of the box, and touches the left edge of the box.
bottomLeft regAlign value:
Scale the object's height and width independently so that the content just touches the top and right edges of the box.
bottomMid regAlign value:
Scale the object's height and width independently so that the content just touches the top edge of the box, and the nearest (to the regPoint) of the left or right edges of the box.
bottomRight regAlign value:
Scale the object's height and width independently so that the content just touches the top and left edges of the box.
hidden fit value:
Align the media over the given regPoint per the regAlign attribute. If the media so positioned extends past the bounds of the region, clip the excess media. If the media so positioned doesn't meet the bounds of the region, fill the remaining space with the background color of the region.
meet fit value:
This depends on the value of the  regAlign attribute. Any part of the region that is not covered by the media is then filled with the region's background color. (Note: in all cases, the media must maintain proper alignment over the regPoint):
topLeft regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the right or bottom edge of the box while none of the content is clipped.
topMid regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches at least one of the left, right, or bottom edges while none of the content is clipped.
topRight regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the left or bottom edge of the box while none of the content is clipped.
midLeft regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches at least one of the top, right, or bottom edges while none of the content is clipped.
center regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches at least one of the top, left, right, or bottom edges while none of the content is clipped.
midRight regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches at least one of the top, left, or bottom edges while none of the content is clipped.
bottomLeft regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the top or right edge of the box while none of the content is clipped.
bottomMid regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches at least one of the top, left, or right edges while none of the content is clipped.
bottomRight regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the top or left edge of the box while none of the content is clipped.
scroll fit value:
Align the media over the given regPoint per the regAlign attribute. If any part of the media extends beyond the bounds of the region, a scrolling mechanism should be invoked that allows viewing of the media that is clipped beyond the bounds of the region.
slice fit value:
This depends on the value of the  regAlign attribute. (Note: in all cases, the media must maintain proper alignment over the regPoint):
topLeft regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the right or bottom edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped.
topMid regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the left, right, or bottom edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped. Clipping will occur on up to two sides of the region.
topRight regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the left or bottom edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped.
midLeft regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the top, right, or bottom edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped. Clipping will occur on up to two sides of the region.
center regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the top, left, right, or bottom edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped. Clipping will occur on up to three sides of the region.
midRight regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the top, left, or bottom edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped. Clipping will occur on up to two sides of the region.
bottomLeft regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the top or right edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped.
bottomMid regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the top, left, or right edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped. Clipping will occur on up to two sides of the region.
bottomRight regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the top or left edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped.

For example, a wide-screen video can be made to play in "letterbox" mode in a region, whose width-to-height ratio is smaller, by using regPoint ="center" and regAlign ="center" and setting the region's fit value to "meet". The result is the video will touch the left and right edges of the region and will be centered vertically with the gaps above and below filled in with the region's background color.

Element attributes
top
This value uniquely identifies the position or the distance (in pixels or %) of the registration point relative to the top of the region. The default value of top is auto.
bottom
This value uniquely identifies the position or the distance (in pixels or %) of the registration point relative to the bottom of the region. The default value of bottom is auto.
left
This value uniquely identifies the position or the distance (in pixels or %) of the registration point relative to the left location of the region. The default value of left is auto.
right
This value uniquely identifies the position or the distance (in pixels or %) of the registration point relative to the right location of the region. The default value of right is auto.
regAlign
This attribute specifies the default alignment algorithm which is associated with a regPoint relative to the media object. If no value is specified the value of topLeft is the default for the regPoint. The following values are allowed:
topLeft
Align the top-left corner of the object with the registration point.
topMid
Align the top-middle point of the object with the registration point. The top-middle is the point offset width/2 to the right of the object top-left corner.
topRight
Align the top-right corner of the object with the registration point.
midLeft
Align the middle-left point of the object with the registration point. The middle-left is the point offset height/2 down from the object top-left corner.
center
Align the center of the object with the registration point.
midRight
Align the middle-right point of the object with the registration point. The middle-right is the point offset height/2 down from the object top-right corner.
bottomLeft
Align the bottom-left corner of the object with the registration point.
bottomMid
Align the bottom-middle point of the object with the registration point. The bottom-middle is the point offset width/2 right from the object bottom-left corner.
bottomRight
Align the bottom-right corner of the object with the registration point.

Element content

None.

5.10.2 SMIL HierarchicalLayout Positioning and Presentation Attributes

While the SMIL 2.0 BasicLayout module provides only the region attribute on elements to place them on the rendering surface, the HierarchicalLayout module includes attributes to refine the position of media content within a region, and to refine the visual presentation of the media within the region.

This module provides fine control over the background color surrounding media elements by allowing the media element to override the background color of a region in which the media is being shown.

One set of attributes (the sub-region positioning attributes) allows a "sub-region" to be defined that is wholly contained within the enclosing layout region for that object; the other set of attributes can be used to define a registration point to be used with that object and an optional layout algorithm that will override the default algorithm associated with the registration point.

If the fit attribute and registration alignment attributes are both relevant to the placement of a particular object, the interaction is the same as described in the regPoint definition. If sub-region positioning attributes are used on an object with applicable fit or alignment attributes, the fit or alignment attributes apply to the sub-region. The fit setting on the referenced region does not apply to a sub-region.

For both sub-region positioning and registration point use, the value of the z-index attribute on the associated region is used. If media objects overlap, existing rules for resolving z-index conflicts are applied.

Note that placement within the region may be defined in such a way as to extend the media object beyond the limits of the region. In this case the media object must be clipped to the region boundaries.

Media specific background color

backgroundColor
This attribute allows specifying the background color that will be used when a media element is being shown in a region, and overrides the default background color for that region while the media is being shown in that region. For profiles using SMIL 2.0 Timing and Synchronization, this includes the duration of any frozen period as well as the active duration of the media element. The background color override of more recently activated media will have priority over that of any media activated earlier. The range of legal values are the same as the backgroundColor attribute on the region element. There is no default value for this attribute, and it has no effect if not declared explicitly.

The media specific background color attribute will be ignored if it is used on an element without a region attribute that specifies the identifier of region element in the layout section. 

Sub-region Positioning Attributes

top
This value uniquely identifies the position or the distance (in pixels or %) of the top edge of the sub-region relative to the top of the region. The default value of top is auto.
bottom
This value uniquely identifies the position or the distance (in pixels or %) of the bottom edge of the sub-region relative to the bottom of the region. The default value of bottom is auto.
left
This value uniquely identifies the position or the distance (in pixels or %) of the left edge of the sub-region relative to the left of the region. The default value of left is auto.
right
This value uniquely identifies the position or the distance (in pixels or %) of the right edge of the sub-region relative to the right side of the region. The default value of right is auto.

Conflicts between the region size attributes bottom, left, right, and top are resolved according to the rules for absolutely positioned, replaced elements in [CSS2].

The sub-region positioning attributes will be ignored if they are used on an element without a region attribute that specifies the identifier of region element in the layout section.

Registration point attributes

The regPoint attribute is used in conjunction with the regPoint element. If a regPoint attribute is missing or refers to a non-existent regPoint element the value of the regAlign attributes are applied to the top-left point of the region containing the media object.

regPoint
This value uniquely identifies the registration point to be used for the placement of the object. The value should be an XML identifier of a regPoint element.
The following values are predefined registration points that do not have to be declared as regPoint elements before they are used:
topLeft
Same as using top="0%" left="0%" on the element without the regPoint attribute.
topMid
Same as using top="0%" left="50%" on the element without the regPoint attribute.
topRight
Same as using top="0%" left="100%" on the element without the regPoint attribute.
midLeft
Same as using top="50%" left="0%" on the element without the regPoint attribute.
center
Same as using top="50%" left="50%" on the element without the regPoint attribute.
midRight
Same as using top="50%" left="100%" on the element without the regPoint attribute.
bottomLeft
Same as using top="100%" left="0%" on the element without the regPoint attribute.
bottomMid
Same as using top="100%" left="50%" on the element without the regPoint attribute.
bottomRight
Same as using top="100%" left="100%" on the element without the regPoint attribute.
Note that the predefined registration points have the same meaning relative to the region as the regAlign attribute values have relative to the media. If no value is given, the default registration point of topLeft (top="0%", left="0%") is assumed, that is, the media is aligned with the top-left of the region.
regAlign
This value uniquely identifies the registration algorithm to be used for the regPoint defined for the object, and overrides any regAlign attribute on the referenced regPoint element. Permissible values are those defined under the regAlign attribute for the regPoint element. If used without an explicit regPoint attribute, the value is relative to the top left point of the region used by the associated media object.

Region fit override

The fit attribute is used on an element in conjunction with the region attribute to control the display of the element on the rendering surface. A value of the fit attribute given on the element will override the value of fit declared in the referenced region element.

fit
This attribute specifies the behavior if the intrinsic height and width of a visual media object differ from the values specified by the height and width attributes in the region element. It takes the same values as the fit attribute on the region element, and has the same semantics with the exception that the declared fit only applies to the media element which declares it, and not to other elements which may use the same region.

5.10.3 Document Type Definition (DTD) for the HierarchicalLayout Module

See the full DTD for the SMIL Layout modules.

5.11 Document Type Definition (DTD) for the SMIL 2.0 Layout Modules  

<!-- ======================================================================= -->
<!-- SMIL 2.0 Layout Modules =============================================== -->
<!-- file: SMIL-layout