W3C

Synchronized Multimedia Integration Language (SMIL) Boston Specification

W3C Working Draft 22 June 2000

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

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

Abstract

This document specifies the "Boston" version of the Synchronized Multimedia Integration Language (SMIL, pronounced "smile"). SMIL Boston 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 document is the fourth Working Draft of the specification for the next version of SMIL code-named "Boston". It has been produced as part of the W3C Synchronized Multimedia Activity. The document has been written by the SYMM Working Group (members only). The goals of this group are discussed in the SYMM Working Group charter (members only).

Many parts of the document are still preliminary, and do not constitute full consensus within the Working Group. Also, some of the functionality planned for SMIL Boston is not contained in this draft. Many parts are not yet detailed enough for implementation, and other parts are only suitable for highly experimental implementation work.

At this point, the W3C SYMM WG seeks input by the public on the concepts and directions described in this specification. Please send your comments to www-smil@w3.org. Since it is difficult to anticipate the number of comments that come in, the WG cannot guarantee an individual response to all comments. However, we will study each comment carefully, and try to be as responsive as time permits.

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 Boston

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

1.1 Introduction

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

SMIL Boston is defined as a set of markup modules, which define the semantics and an XML syntax for certain areas of SMIL functionality. All modules have an associated Document Object Model (DOM).

SMIL Boston 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 Boston 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 Boston names.

This specification is structured as a set of sections, defining module:

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

Finally, this specification defines a number of baseline media formats to be widely supported by SMIL players:

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:

2. Synchronized Multimedia Integration Language (SMIL) Modules

Editors:
Warner ten Kate (warner.ten.kate@philips.com), (Philips Electronics)
Ted Wugofski (ted.wugofski@corp.phone.com), (Phone.com)
Patrick Schmitz (pschmitz@microsoft.com), (Microsoft)

2.1 Introduction

This section is Normative.

Since the publication of SMIL 1.0 [SMIL10], interest in the integration of SMIL concepts with the HTML, the Hypertext Markup Language [HTML40], and other XML languages, has grown. Likewise, the W3C HTML Working Group is specifying how XHTML, the Extensible Hypertext Markup Language [XHTML10], can be subset, be extended, or be integrated with other languages. The strategy considered for integrating respective functionality with other XML languages is based on the concepts of modularization and profiling [MODMOD], [SMIL-MOD], [XMOD], [XPROF].

Modularization is a solution in which a language's functionality is partitioned into sets of semantically-related elements and attributes. Profiling is the combination of these feature sets to provide support for the functionality required within a particular application domain. The re-use of modules across profiles should enhance the interoperability between the various application domains.

This specification complies with the XHTML modularization conformance requirements as set forth in the XHTML Modularization specification [XMOD]. For the purposes of this specification we further define:

element
An element is a XML representation of a semantic feature. An element has one representation in any given namespace.
module
A module is a collection of semantically-related elements. Attributes and their value range may be divided over different modules.
module family
A module family is a collection of modules associated with the same namespace. Modules with related functionality are generally ordered in a module family by increasing functionality. Each module at a higher level requires all modules at the lower levels. Ideally, each element is in one and only one module family. Elements in different module families but representing the same semantic feature are said to be isomorphic.
The typical way of referring to elements from a certain module family is through their namespace. Examples are "XHTML" and "SMIL".
A module family is not to be confused with a language profile, which is defined below. However, a module family typically associates with a language profile, namely that language profile which uses (nearly) all modules and only modules from the module family.
A module family defines at least one module as mandatory for language profiles which wish to be part of the language-profile family (defined below) associated with that module family. That mandatory module is the so-called "Structure Module" and includes the document's root element (e.g., <html> and <smil>).
language profile
A language profile is a collection of modules particular to an application domain. For example, the "SMIL Language" profile corresponds to the collection of modules that make up for composition of multimedia presentations. Likewise, a "Timed-Text" language profile would correspond to the collection of modules for supporting timing of text content.
A language profile can include modules from different module families. This enables for the integration of functionality developed within different languages.
language profile family
A language profile family is a collection of language profiles which all share a common set of modules. The modules in that common set are defined as mandatory for that language profile family.
A special case are the so-called "Host Language" profiles [XMOD]. These are the language profiles which use all the mandatory modules defined by a module family. Those language profile families are typically referred to by the module family's namespace qualifier. Examples are "the XHTML language profile family" and "the SMIL language profile family". A language profile might use mandatory modules from different module families. As any language profile will have a single root element, the choice of Structure Module is decisive in assigning the language profile family name. A consequence of this is that, for example, a language profile may include modules used in the "SMIL Language", i.e. modules that are part from the "SMIL" module family, while the language profile may not be member of the "SMIL Language profile family". These profiles are called "Integration Set" in [XMOD]. "Integration Set" conformance differs from "Host Language" conformance in not requiring the inclusion of the (XHTML) Structure Module.

The main purpose of the notion of language profile family is to enhance interoperability. Language profiles within the same language profile family share the same MIME type(s). Preferably, the mandatory modules of a language profile family should be defined in such a way that any offered document conforming to a language profile in that language profile family will yield a reasonable presentation when the renderer, while supporting that language profile family's 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. For that purpose a language profile negotiation would have to be conducted.

There is an important difference between the concepts of module family and language profile family. The first indicates the functionality space, and the second has to do with the document type (and MIME type). A language profile associates with one doctype, which is called the "host language". Therefore, the "Structure Module", containing the doctype's root element, is an essential module in any language profile family.

@@ In respect of decreasing document size: should the remainder of this section stay?

SMIL functionality is partitioned into modules based on the following design requirements:

  1. Ensure that a language profile may be defined that is completely backward compatibility with SMIL 1.0.
  2. Ensure that a module's semantics maintain compatibility with SMIL semantics (this includes content and timing).
  3. Partition into modules of reasonable granularity, to support wide reuse in an interoperable manner.
  4. Specify modules that are isomorphic with other modules based on W3C recommendations.
  5. Specify modules that can complement XHTML modules.
  6. Specify how the modules support the document object model.

The first requirement specifies that a collection of modules can be "recombined" in such a way as to be backwardly compatible with SMIL 1.0 (it will properly play SMIL 1.0 conforming content).

The second requirement specifies that the semantics of SMIL must not change when they are embodied in a module. Fundamentally, this ensures the integrity of the SMIL content and timing models. This is particularly relevant when a different syntax is required to integrate SMIL functionality with other languages.

The third requirement states that modules be of reasonable granularity. This requirement reflects the core purpose of modularization and profiling. On the one hand, the modularization should lead to separation of functionality, such that language profile designs can optimize for performance and complexity. On the other hand, the range of modules should be limited, such that interoperability is promoted.

The fourth requirement specifies that, where functionality overlaps, modules be isomorphic with other modules from other W3C recommendations. This will assist designers when sharing modules across language profiles.

The fifth requirement states that specific attention be paid to providing multimedia functionality to the XHTML language. XHTML is the reformulation of HTML in XML.

The sixth requirement ensures that modules have integrated support for the document object model. This facilitates additional control through scripting and user agents.

These requirements led to a partitioning of SMIL functionality into twenty five modules.

2.2 SMIL Modules

This section is Informative.

SMIL functionality is partitioned into nine functional areas. Within each functional area a further partitioning is applied into modules. The modules are complementary. For example, the Timing Level 2 Module adds syncBehavior to the timing in the Timing Level 0 and Level 1 Modules.

@@ This is a Normative statement !! When a language profile includes a module of a higher level, the modules of the lower levels MUST be included. Some elements or attributes are labeled as Profile Specific. This means that those elements or attributes are optional to the language profile, as long as the module from which they stem is the top level module.

The functional areas and the modules are:

  1. Timing functionality
    1. Timing Level 0 Module
    2. Timing Level 1 Module
    3. Timing Level 2 Module
  2. Time Manipulations functionality
    1. Time Manipulations Module
  3. Animation functionality
    1. Animation Level 0 Module
    2. Animation Level 1 Module
  4. Transition Effects functionality
    1. Transition Effects Level 0 Module
    2. Transition Effects Level 1 Module
  5. Media functionality
    1. Media Object Level 0 Module
    2. Media Object Level 1 Module
  6. Streaming Media functionality
    1. Streaming Media Level 0 Module
  7. Content Control functionality
    1. Content Control Level 0 Module
    2. Content Control Level 1 Module
  8. Metainformation functionality
    1. Metainformation Level 0 Module
  9. Structure functionality
    1. Structure Level 0 Module
  10. Layout functionality
    1. Layout Level 0 Module
    2. Layout Level 1 Module
    3. Layout Level 2 Module
  11. Linking functionality
    1. Linking Level 0 Module
    2. Linking Level 1 Module
  12. DOM functionality
    1. SMIL DOM Modules

Each of these modules introduces a set of semantically-related elements, properties, and attributes.

All these modules, and only these modules, are members of the SMIL module family. @@ This is a Normative statement ??

The Structure Level 0 Module, Timing Level 0 Module, and Media Object Level 0 Module are mandatory modules in any language profile in the SMIL language profile family. This implies that the SMIL Structure Level 0 Module must at least be accompanied with the two other modules. Those modules themselves can still be used in other, non-SMIL family, language profiles.

Below, the modules are listed.

@@ Need check on completeness.

@@ Need check on correct division over levels.

@@ The names for the script to generate hyperlinks to the element and attribute definitions need check on being identical.

2.3 Timing functionality

This section is Informative.

The Timing and Synchronization Modules provide a framework for describing timing structure, timing control properties, and temporal relationships between elements. The Timing and Synchronization Modules define semantics for par, seq, and excl elements. In addition, the modules define semantics for attributes including begin, dur, end, repeatCount, repeatDur, and others.

2.3.1 Timing Level 0 Module

Elements
par
seq
Attributes
begin (single time condition; long syncarc; with syncbase syntax; with prev; with wall clock; with offset)
end (single time condition; long syncarc; with syncbase syntax; with prev; with wall clock; with offset)
endsync
dur
repeat (deprecated)
repeatCount
repeatDur
timeAction
timeContainer

The Timing Level 0 Module is a mandatory module in any language profile in the SMIL language profile family.

Note that upon building a language profile which integrates SMIL timing with other, non-SMIL, modules, that the elements from this Timing Level 0 Module may appear as attributes to the elements from the other XML language, rather than as these elements themselves. In that case, the element's functionality is declared using the timeContainer attribute.

@@ To be moved to corresponding module
The timing attributes are used by the elements in this Timing Level 0 Module and in the other Timing Modules, and by the elements in the Media Modules, in the Linking Modules, and in the Content Control Modules. As upon integration with non-SMIL modules, the elements from this module may appear as attributes instead of elements, the referenced timing attributes are also used by those non-SMIL elements.

2.3.2 Timing Level 1 Module

Elements
excl
priorityClass
Attributes
begin (multiple time conditions; events)
end (multiple time conditions; events)
restart
restartDefault
fill

Usage of the Timing Level 1 Module requires inclusion of the Timing Level 0 Module. (@@ Therefore, should we design the modules as inclusive, rather than complementary?) Consequently, the same usage rules apply.

This means that upon integrating with a non-SMIL language, the excl element may appear as an attribute using the timeContainer construct. Another implication is that the added attributes (restart etc.) are adopted by the same elements who have adopted the attributes in the Timing Level 0 Module.

When this module is used it adds the 'multiple time conditions' and 'events' semantics to the begin and end attributes.

@@ To be moved to corresponding module
When this module is used it adds the restart, the restartDefault, the syncBehavior, and the syncBehaviorDefault attributes to the par, seq, and excl elements.

2.3.3 Timing Level 2 Module

Elements
<!-- NONE -->
Attributes
begin (with media markers)
end (with media markers)
syncMaster
syncTolerance
syncToleranceDefault
syncBehavior
syncBehaviorDefault

Usage of the Timing Level 2 Module requires inclusion of the Timing Level 0 Module and the Timing Level 1 Module. Consequently, the same usage rules apply.

@@ To be moved to corresponding module
When this module is used it adds the 'media marker' semantics to the begin and end attributes.

2.4 Time Manipulations functionality

This section is Informative.

2.4.1 Time Manipulations Module

Elements
<!-- NONE -->
Attributes
speed
accelerate
decelerate
autoReverse

2.5 Animation functionality

This section is Informative.

The Animation Modules provide a framework for incorporating animation onto a timeline (a timing model) and a mechanism for composing the effects of multiple animations (a composition model). The Animation Modules define semantics for the animate, set, animateMotion, and animateColor elements.

2.5.1 Animation Level 0 Module

Elements
animate (without keyTimes and keySplines)
set
animateMotion
animateColor
Attributes
targetElement
attributeName
attributeType
from
to
by
values
accumulate
additive
calcMode
path
origin

@@ To be moved to corresponding module
When this module is used, it adds the animate, set, animateMotion, and animateColor elements to the content model of the ref, animation, audio, img, video, text, and textstream elements of the Media Object Modules (if those are present in the language profile). It also adds these elements to the content model of the par, seq, and excl elements of the Timing Modules, and to the content model of the body element of the Structure Level 0 Module (if those are present in the language profile).

2.5.2 Animation Level 1 Module

Elements
<!-- NONE -->
Attributes
keyTimes
keySplines

Usage of the Animation Level 1 Module requires inclusion of the Animation Level 0 Module. Consequently, the same usage rules apply.

@@ To be moved to corresponding module
When this module is used it adds the keyTimes and keySplines attributes to the animate element.

2.6 Transition Effects functionality

This section is Informative.

The Transition Effects Modules define a taxonomy of transition effects as well as semantics and syntax for integrating these effects into XML documents.

2.6.1 Transition Effects Level 0 Module

Elements
transition (on single elements)
Attributes
transition
type
subtype
startPercent
endPercent
direction
horzRepeat
vertRepeat
borderWidth
color
multiElement
childrenClip

@@ To be moved to corresponding module
When this module is used, it adds the transition element to the content model of the layout element of the Layout Level 0 Module (if present in the language profile). The transition attribute is added to the elements in the Media Object Level 0 Module (if present in the language profile).

2.6.2 Transition Effects Level 1 Module

Elements
transition (on multi-element regions)
transitionFilter
Attributes
percentDone

Usage of the Transition Effects Level 1 Module requires inclusion of the Transition Effects Level 0 Module. Consequently, the same usage rules apply.
In addition, the usage of the Transition Effects Level 1 Module requires support for hierarchical layout, such as supported by the Layout Level 1 Module.

@@ To be moved to corresponding module
When this module is used it adds transition effects functionality for transitions over multiple regions.

2.7 Media functionality

This section is Informative.

The Media Object Modules provide a framework for declaring media. The Media Object Modules define semantics for the ref, animation, audio, img, video, text, and textstream elements.

2.7.1 Media Object Level 0 Module

Elements
ref
img
text
audio
video
animation
textstream
Attributes
abstract
alt
author
clipBegin (clip-begin)
clipEnd (clip-end)
copyright
longdesc
src
type

The Media Object Level 0 Module is a mandatory module in any language profile in the SMIL language profile family.

@@ To be moved to corresponding module
When this module is used, it adds the ref, animation, audio, img, video, text, and textstream elements to the content model of the par, seq, and excl elements of the Timing Modules (if those are present in the language profile). It also adds these elements to the content model of the body element of the Structure Level 0 Module (if those are present in the language profile). It also adds these elements to the content model of the a element of the Linking Modules (if those are present in the language profile).

2.7.2 Media Object Level 1 Module

Elements
Profile Specific:brush
Profile Specific:param
Attributes
Profile Specific:stripRepeat
Profile Specific:readIndex
Profile Specific:shape
erase
name
value
valuetype
type
color

Usage of the Media Object Level 1 Module requires inclusion of the Media Object Level 0 Module. Consequently, the same usage rules apply.

@@ To be moved to corresponding module
When this module is used it adds the stripRepeat and the readIndex attributes to the ref, animation, audio, img, video, text, and textstream elements of the Media Object Level 0 Module (if present in the language profile).

@@ To be moved to corresponding module
When this module is used, it adds the param element to the content model of the ref, animation, audio, img, video, text, and textstream elements of the Media Object Level 0 Module (if present in the language profile).

@@ To be moved to corresponding module
When this module is used, it adds the rtpmap element to the content model of the ref, animation, audio, img, video, text, and textstream elements of the Media Object Level 0 Module (if present in the language profile).

@@ To be moved to corresponding module
When this module is used it adds the port, the transport, and the rtpformat attributes to the ref, animation, audio, img, video, text, and textstream elements of the Media Object Level 0 Module (if present in the language profile).

@@ To be moved to corresponding module
When this module is used, it adds the brush element to the content model of ?? (@@ needs completion).

2.8 Streaming Media functionality

This section is Informative.

2.8.1 Streaming Media Level 0 Module

Elements
Profile Specific:rtpmap
Attributes
Profile Specific:payload
Profile Specific:encoding
Profile Specific:port
Profile Specific:transport
Profile Specific:rtpformat

2.9 Content Control functionality

This section is Informative.

The Content Control Modules provide a framework for selecting content based on a set of test attributes. The Content Control Modules define semantics for the switch, prefetch and uGroup elements.

2.9.1 Content Control Level 0 Module

Elements
switch
Attributes
skipContent (skip-content)
systemBitrate (system-bitrate)
systemCaptions (system-captions)
systemLanguage (system-language)
systemOverdubOrSubtitle (system-overdub-or-caption)
systemRequired (system-required)
systemScreenSize (system-screen-size)
systemScreenDepth (system-screen-depth)
systemAudioDesc
systemOperatingSystem
systemCPU
systemComponent

@@ To be moved to corresponding module
When this module is used, it adds the switch element to the content model of the par, seq, and excl elements of the Timing Modules (if those are present in the language profile). It also adds this element to the content model of the body element of the Structure Level 0 Module (if present in the language profile). It also adds this element to the content model of the a element of the Linking Modules (if present in the language profile). It also adds this element to the content model of the head element of the Structure Level 0 Module (if present in the language profile).

@@ To be moved to corresponding module
When this module is used, the test attributes are added to the attribute lists of all the elements in the Layout Modules, the Media Object Modules, the Timing Modules, and the Transition Effects Modules (if those are present in the language profile).

@@ To be moved to corresponding module
When this module is used, it adds the skipContent attribute to all other elements in the language profile.

2.9.2 Content Control Level 1 Module

Elements
Profile Specific: prefetch
Profile Specific: uGroup
Profile Specific: userAttributes
Attributes
Profile Specific: uState
Profile Specific: uGroup

Usage of the Content Control Level 1 Module requires inclusion of the Content Control Level 0 Module. Consequently, the same usage rules apply.

@@ To be moved to corresponding module
When this module is used, it adds the prefetch element to the content model of the par, seq, and excl elements of the the Timing Modules (if those are present in the language profile). It also adds this element to the content model of the body element of the Structure Level 0 Module (if present in the language profile). It also adds this element to the content model of the a element of the Linking Modules (if those are present in the language profile).

@@ To be moved to corresponding module
When this module is used, the userAttributes element is added to the content model of the head element (where the uGroup is part of the content model of the userAttributes element). The uGroup attribute is added to the attribute lists of all the elements in the Media Object Modules, and the Timing Modules (if those are present in the language profile).

2.10 Metainformation functionality

This section is Informative.

2.10.1 Metainformation Level 0 Module

The Metainformation Module provides a framework for describing a document, either to inform the human user or to assist in automation. The Metainformation Module defines semantics for the meta and the metadata elements.

Elements
meta
metadata
Attributes
content@@ shouldn't we use a more specific naming for this attribute?
name

@@ To be moved to corresponding module
When this module is used, it adds the meta and the metadata elements to the content model of the head element of the Structure Level 0 Module (if present in the language profile).

2.11 Structure functionality

This section is Informative.

2.11.1 Structure Level 0 Module

The Structure Module provides a framework for structuring a SMIL document. The Structure Module defines semantics for the smil, head, and body elements.

Elements
smil
body
head
Attributes
id
class
xml:lang
title
xmlns
profile

The Structure Level 0 Module is a mandatory module in any language profile in the SMIL language profile family.

2.12 Layout functionality

This section is Informative.

The Layout Modules provide a framework for spatial layout of visual components. The Layout Modules define semantics for the layout, root-layout, and region elements.

2.12.1 Layout Level 0 Module

Elements
layout
region
root-layout
Attributes
type
backgroundColor
background-color (deprecated)
fit
left
right
top
bottom
height
width
z-index

@@ To be moved to corresponding module
When this module is used, it adds the layout element to the content model of the head element of the Structure Level 0 Module (if present in the language profile). It also adds this element to the content model of the switch element of the Content Control Modules (if present in the language profile).

2.12.2 Layout Level 1 Module

Elements
viewport
Attributes
soundLevel

Usage of the Layout Level 1 Module requires inclusion of the Layout Level 0 Module. Consequently, the same usage rules apply.

@@ To be moved to corresponding module
When this module is used, it adds the viewport element to the content model of the layout element.

@@ To be moved to corresponding module
When this module is used, it adds the soundLevel attribute to the region element.

2.12.3 Layout Level 2 Module

Elements
regPoint
Attributes
regPoint
regAlign

Usage of the Layout Level 2 Module requires inclusion of the Layout Level 0 Module and the Layout Level 1 Module. Consequently, the same usage rules apply.

2.13 Linking functionality

This section is Informative.

The Linking Modules provide a framework for relating documents to content, documents and document fragments. The Linking Modules define semantics for the a and the area elements.

2.13.1 Linking Level 0 Module

Elements
<!-- NONE -->
Attributes
sourceLevel
destinationLevel
sourcePlaystate
destinationPlaystate
show
accesskey
tabindex
target
external
actuate

2.13.2 Linking Level 1 Module

Elements
a
anchor
area (as substitute for anchor with shape)
Profile Specific: area supporting fragment attribute
Attributes
href
nohref
shape
coords

@@ To be moved to corresponding module
When this module is used, it adds the a and the anchor (deprected)elements to the content model of the par, seq, and excl elements of the Timing Modules (if those are present in the language profile). It also adds these elements to the content model of the body element of the Structure Level 0 Module (if present in the language profile).

Usage of the Linking Level 1 Module requires inclusion of the Linking Level 0 Module, except for the replacement defined below. Consequently, the same usage rules apply.

@@ To be moved to corresponding module
When this module is used, it adds the fragment attribute to the existing attribute range of the area element.

2.14 SMIL DOM

This section is Informative.

SMIL is an XML language and conforms to the (XML) DOM Core [DOM1], [DOM2]. The SMIL DOM specifies extensions to the DOM Core, adding 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.15 Isomorphism

This section is Informative.

A requirement for SMIL modularization is that the modules be isomorphic with other modules from other W3C recommendations. Isomorphism will assist designers when sharing modules across language profiles. The Table below lists the isomorphism between SMIL and XHTML modules.

@@ Update with final XHTML Mod REC
Table -- Isomorphism between SMIL modules and their corresponding XHTML modules.
SMIL modules XHTML modules
Functionality Module Name Elements Module Name Elements
Timing Timing Level 0 par, seq <none> -
Timing Level 1 excl, priorityClass <none> -
Animation Animation Level 0 animate, set, animateMotion, animationColor <none> -
Animation Level 1 - <none> -
Transition Effects Transition Effects Level 0 transition <none> -
Transition Effects Level 1 - <none> -
Media Media Object Level 0 ref, audio, video, text, img, animation, textstream Object object
Image img
Applet applet, param
Media Object Level 1 param Object param
rtpmap, brush <none> -
Content Control Content Control Level 0 switch <none> -
Content Control Level 1 prefetch, userAttributes, uGroup <none> -
Structure Structure Level 0 smil, head, body Structure html, head, body, title, span, div
Metainformation Metainformation Level 0 meta, metadata Metainformation meta
Link link
Base base
Layout Layout Level 0 layout, root-layout, region Stylesheet style (CSS)
Layout Level 1 viewport <none> -
Layout Level 2 advanced layout syntax (TBD) <none> -
Linking Linking Level 0 - Hypertext @@ ??
Linking Level 1 a Hypertext a
anchor - -
area Client-side Image Map map, area
DOM SMIL DOM - <none> -

As can be seen in the table, the Metainformation module appears in both SMIL and HTML. In SMIL the Linking Level 1 Module provides towards isomorphism between the corresponding Linking modules in SMIL and XHTML.

2.16 Multimedia Language Profiles

This section is Informative.

There are a range of possible language profiles that may be built using SMIL modules. Below, five language profiles are presented to inform the reader of how language profiles may be constructed to solve particular problems. These example language profiles are non-normative. However, the first three language profiles have been documented as normative specifications by the SYMM WG.

  1. SMIL-Boston Language Profile
  2. HTML+SMIL Language Profile
  3. SMIL-Basic Language Profile
  4. Lightweight Timed-Text Language Profile
  5. Web-Enhanced Media Language Profile

2.16.1 SMIL-Boston Language Profile

The SMIL-Boston Language Profile supports for composition of multimedia presentations. It uses modules from the SMIL module family only. As the language profile includes the three mandatory modules (Structure Level 0, Timing Level 0, and Media Object Level 0), it represents a language profile in the SMIL language profile family.

The SMIL-Boston Language Profile includes the following SMIL modules:

@@ to be checked (in particular by implementers)

A normative specification of the language profile is given in the SMIL Boston Language Profile specification.

2.16.2 HTML+SMIL Language Profile

The HTML+SMIL Language Profile integrates SMIL timing into HTML. It uses modules from the SMIL module family.

The HTML+SMIL Language Profile includes the following SMIL modules:

@@ to be checked (in particular by implementers)

The language profile uses XHTML modules for structure, layout, and linking and SMIL modules for multimedia and timing.

A normative specification of the language profile is given in the HTML+SMIL Language Profile specification.

2.16.3 SMIL-Basic Language Profile

The SMIL-Basic Language Profile supports a lightweight version of the SMIL-Boston language profile and is intended for use with resource-constrained devices such as mobile phones. It uses a subset of the modules used in the SMIL-Boston language profile, which are modules from the SMIL module family. As the language profile includes the three mandatory modules (Structure Level 0, Timing Level 0, and Media Object Level 0), it represents a language profile in the SMIL language profile family.

The SMIL-Basic Language Profile includes the following SMIL modules:

@@ to be checked (in particular by implementers)

2.16.4 Lightweight Timed-Text Language Profile

The Lightweight Timed-Text Language Profile handles simple presentations supporting timing of text content. It integrates SMIL timing with XHTML text markup. The simplest version of this could be used to sequence stock quotes or headlines on constrained devices such as a palmtop device or a smart phone. The language profile uses modules from the SMIL module family. Its complete module set forms a subset of the modules used in the HTML+SMIL language profile.

The Lightweight Timed-Text Language Profile includes the following SMIL modules:

This language profile uses XHTML modules [XMOD] for structure and layout and SMIL modules for timing and animation.

2.16.5 Web-Enhanced Media Language Profile

The Web-Enhanced Media Language Profile supports the integration of interactive broadcast or on-demand streaming media presentations with Web access browsing. The primary media will often define the main timeline. The language profile uses a subset of the modules used in the SMIL-Boston language profile and forms a superset of the modules used in the SMIL-Basic language profile, which are modules from the SMIL module family. However, it may incorporate modules from other namespaces. As the language profile includes the three mandatory modules (Structure Level 0, Timing Level 0, and Media Object Level 0), it represents a language profile in the SMIL language profile family.

The Web-Enhanced Media Language Profile includes the following SMIL modules:

3. The SMIL Animation Module

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

3.1 Introduction

The SMIL Animation module defines the SMIL document attributes and elements for incorporating animation onto a time line and a mechanism for composing the effects of multiple animations. This module depends on the SMIL Timing module, using elements and attributes from the Timing module for its time line. Level 0 of the SMIL timing module is a prerequisite for any profile using SMIL Animation.

The reader is presumed to have read and be familiar with the SMIL Timing module.

A set of basic animation elements are also described that can be applied to any [XML10]-based language. A language with which this module is integrated is referred to as a host language. A document containing animation elements is referred to as a host document.

It includes a set of basic animation elements that can be applied to any XML-based language. Since these elements and attributes are defined in a module, designers of other markup languages can reuse the functionality in the SMIL animation module when they need to include animation in their language. 

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.

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

3.2 Overview and terminology

3.2.1 Basics of animation

Animation is defined as a time-based manipulation 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.  Each animation defines an animation function that produces a value for the target attribute, for any time within the simple duration.

The target attribute is the name of a feature of a target element as defined in a host language document. This may be (e.g.) an XML attribute contained in the element or a CSS property that applies to the element.  By default, the target element of an animation will be the parent of the animation element (an animation element is typically a child of the target element). However, the target may be any element in the document, identified either by an 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 display 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.

The animation function is evaluated as needed over time by the implementation, and the resulting values are applied to the presentation value for the target attribute. Animation functions are continuous in time and can be sampled at whatever frame rate is appropriate for the rendering system. The syntactic representation of the animation function is independent of this model, and may be described in a variety of ways. The animation elements in this specification support syntax for a set of discrete or interpolated values, a path syntax for motion based upon SVG paths, keyframe based timing, evenly paced interpolation, and variants on these features. Animation functions could be defined that were purely or partially algorithmic (e.g. a random value function or a motion animation that tracks the mouse position). In all cases, the animation exposes this as a function of time.

The presentation value reflects the effect of the animation upon the base value. The effect is the change to the value of the target attribute at any given time. When an animation completes, the effect of the animation is no longer applied, and the presentation value reverts to the base value by default. The animation effect can also be extended to freeze the last value for the length of time determined by the semantics of the fill attribute.

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.

3.2.2 Animation function values

Many animations specify the 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 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.

3.2.3 Symbols used in the semantic descriptions

f(t)
The simple animation function that maps times within the simple duration to values for the target attribute (0 <= t <= simple duration). Note that while F(t) defines the mapping for the entire animation, f(t) has a simplified model that just handles the simple duration.
F(t)
The effect of an animation for any point in the animation. This maps any non-negative time to a value for the target attribute. A time value of 0 corresponds to the time at which the animation begins. Note that F(t) combines the animation function f(t) with all the other aspects of animation and timing controls.

3.3 Animation model

This section describes the attribute syntax and semantics for describing animations. The specific elements are not described here, but rather the common concepts and syntax that comprise the model for animation.  Document issues are described, as well as the means to target an element for animation. The animation model is then defined by building up from the simplest to the most complex concepts: first the simple duration and animation function f(t), and then the overall behavior F(t).  Finally, the model for combining animations is presented, and additional details of implications of the timing model on animation are described.

3.3.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.3.2 Implications of Timing Model for animation

The model of timing defined in the Timing module has several important results for animation: the intrinsic duration, the definition of repeat, and the value sampled during the "frozen" state.

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.

When repeating an animation, the arithmetic follows the end-point exclusive model. Consider the example: 

  <animation dur="4s" repeatCount="4" .../>

At time 0, the animation function is sampled at 0, and the first value is applied.  This is the inclusive begin of the interval. The simple duration is sampled normally up to 4 seconds. However, the appropriate way to map time on the active duration to time on the simple duration is to use the remainder of division by the simple duration:

  simpleTime = REMAINDER( activeTime, d )  where d is the simple duration

or

  F(t) = f( REMAINDER( t, d ) )  where t is within the active duration

Note: REMAINDER( t, d ) is defined as (t - d*floor(t/d))

Using this, a time of 4 (or 8 or 12) maps to the time of 0 on the simple duration. The endpoint of the simple duration is excluded from (i.e. not actually sampled on) the simple duration.

This implies that the last value of an animation function f(t) may never actually be applied (e.g. for a linear interpolation).  In the case of an animation that does not repeat and does not specify fill="freeze", this may in fact be the case. However, in the following example, the appropriate value for the frozen state is clearly the "to" value: 

   <animation from="0" to="5" dur="4s" fill="freeze" .../>

This does not break the interval timing model, but does require an additional qualification for the animation function F(t) while in the frozen state:

The definition of accumulate also aligns to this model. The arithmetic is effectively inverted and values accumulate by adding in a multiple of the last value defined for the animation function f(t).

3.3.3 Specifying the 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.

Animation function attributes
from
Specifies the starting value of the animation. Must be a legal value for the specified attribute.
to
Specifies the ending value of the animation. Must be a legal value for the specified attribute.
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.
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).

If a list of values is used, the animation will apply the values in order over the course of the animation (pacing and interpolation between these values is described in "Animation function calculation modes", below). If a list of values is specified, any from, to and by attribute values are ignored.

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, equivalent to a values list with 2 values. The animation function is defined to start with the from value, and to finish with the to value.
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).
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 addition.
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.

The last two forms, "by animation" and "to animation", have additional semantic constraints when combined with other animations. The details of this are described below in the section How from, to and by attributes affect additive behavior.

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.

Examples

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

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>

Animation function calculation modes

By default, a simple linear interpolation is performed over the values, evenly spaced over the duration of the animation.  Additional attributes can be used for finer control over the interpolation and timing of the values. The calcMode attribute defines the method of applying values to the attribute. The keyTimes attribute provides additional control over the timing of the animation function, associating a time with each value in the values list (or the points in a path description for the animateMotion element). Finally, the keySplines attribute provides a means of controlling the pacing of interpolation between the values in the values list.

Calculation mode attributes
 
calcMode
Specifies the interpolation mode for the animation. This can take any of the following values.  The default mode is linear, however if the attribute does not support linear interpolation (e.g. for strings), the calcMode attribute is ignored and discrete interpolation is used.
discrete
This specifies that the animation function will jump from one value to the next without any interpolation.
linear
Simple linear interpolation between values is used to calculate the animation function. 
This is the default calcMode.
paced
Defines interpolation to produce an even pace of change across the animation. This is only supported for values that define a linear numeric range, and for which some notion of "distance" between points can be calculated (e.g. position, width, height, etc.). If paced is specified, any keyTimes or keySplines will be ignored.
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.
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.

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

If calcMode is set to discrete, linear or spline, but the keyTimes attribute is not specified, the values in the values attribute are assumed to be equally spaced through the animation duration, according to the calcMode:

This semantic 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.

For the shorthand forms from-to animation and from-by animation, there are only 2 values.  A discrete from-to animation will set the from value for the first half of the simple duration and the to value for the second half of the simple duration. Similarly, a discrete from-by animation will set the from value for the first half of the simple duration and for the second half of the simple duration will set the computed result of applying the by value. For the shorthand form to animation, there is only 1 value; a discrete to animation will simply set the to value for the simple duration.

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.

Interpolation modes illustrated

The three illustrations 1a, 1b and 1c below show how the same basic animation will change a value over time, given different interpolation modes. All examples use the default timing (no keyTimes or keySplines specified). All examples are based upon the following example, but with different values for calcMode: 

<animate dur="30s" values="0; 1; 2; 4; 8; 15" calcMode="[as specified]" />

Figure 1 - Discrete, linear and paced animation
Diagram of linear interpolation

Figure 1a: Default discrete animation.

calcMode="discrete"

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

Figure 1b: Default linear animation.

calcMode="linear"

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

Figure 1c: 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.

Discrete animation can also 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 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 with no keyTimes specified; in this case the result is a much larger actual change in the value during the second half of the animation. Contrast this with the same example changed to use "paced" interpolation: 

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

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 2 shows the curves that these keySplines values define.

Figure 2 - 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 2 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.3.4 Specifying the animation effect F(t)

As described above, the animation function f(t) defines the animation for the simple duration. 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 syntax and associated semantics for the additional functionality. A detailed model for combining animations is described, along with a state model for animations, and additional details of the timing model.

The period of time during which the animation is actively playing, including any repeat behavior, is described as the active duration. The active duration may be computed from the simple duration and the repeat specification, and it may be constrained with the end attribute.  The complete rules for computing the active duration are presented in the section Computing the active duration.

Repeating animations

Repeating an animation causes the animation function f(t) to be "played" several times in sequence.  The author can specify either how many times to repeat, using repeatCount, or how long to repeat, using repeatDur. Each repeat iteration is one instance of "playing" the animation function f(t).

If the simple duration is indefinite, the animation cannot repeat. See also the section Computing the active duration.

The repeatCount and repeatDur attributes are described in detail in the Timing module.

Examples

In the following example, the 2.5 second animation function will be repeated twice; the active duration will be 5 seconds.

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

Using the path notation for a simple arc (detailed in The animateMotion element), we describe this example as: 

<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 3, below. In this way, the image "bounces" across the screen. The same animation could be described as a complete path of 4 arcs, but in the general case the path description can get quite large and cumbersome to edit.

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

Diagram showing accumlating animation

Figure 3 - Repeating animation with accumulate set to sum. Each repeat iteration builds upon the previous.

Note that cumulative animation only controls how a single animation accumulates the results of the animation function as it repeats. It specifically does not control how one animation interacts with other animations to produce a presentation value. This latter behavior is described in the section Additive animation. Similarily, if an element restarts, the accumulate from the first run is not applied to the second. See Restarting animations.

The cumulative behavior of repeating animations is controlled with the accumulate attribute:

Cumulative animation attribute
 
accumulate
Controls whether or not the animation is cumulative. May be either of the following two values:
sum
Each repeat iteration after the first builds upon the last value of the previous iteration.
none
Repeat iterations are not cumulative, and 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.

Cumulative animation is not defined for "to animation". This attribute will be ignored if the animation function is specified with only the to attribute. See also Specifying function values.

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.

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.

Computing cumulative animation values

To produce the cumulative animation behavior, the animation function f(t) must be modified slightly. Each iteration after the first must add in the last value of the previous iteration - this is expressed as a multiple of the last value specified for the animation function. Note that cumulative animation is defined in terms of the values specified for the animation behavior, and not in terms of sampled or rendered animation values. The latter would vary from machine to machine, and could even vary between document views on the same machine.

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 animation function definition.

f0(t) = f(t)

Let ve be the last value specified for the animation function (e.g. the to value, the last value in a values list, or the end of a path).  Each iteration after the first adds in the computed offset:

fi(t) = (ve * i) + f(t)     ; i >= 1

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>

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

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. 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 simple duration.

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 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 15:  

<animate from="10" to="20" dur="4s" 
         repeatCount="2.5" fill="freeze" .../> 

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. Since interpolation is not defined, the value while frozen will be 10: 

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

Additive animation

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

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

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.

In addition, many complex animations are best expressed as combinations of simpler animations. A "vibrating" path, for example, can be described as a repeating up and down motion added to any other motion: 

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

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.

The additive behavior of an animation is controlled by the additive attribute:

Additive attribute
additive
Controls whether or not the animation is additive. 
sum
Specifies that the animation will add to the underlying value of the attribute and other lower priority animations.
replace
Specifies that the animation will override the underlying value of the attribute and other lower priority animations. This is the default, however the behavior is also affected by the animation value attributes by and to, as described in "How from, to and by attributes affect additive behavior", below.
This attribute is ignored if the target attribute does not support additive animation.

Additive animation is defined for numeric attributes and other data types for which some addition function is defined. This includes numeric attributes for concepts such as position, widths and heights, sizes, etc. This also includes color (refer to 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.

How from, to and by attributes affect additive behavior.

The attribute values to and by, used to describe the animation function, can override the additive attribute in certain cases:

For the hybrid case of a to-animation, the animation function f(t) is defined in terms of the underlying value, the specified to value, and the current value of t (i.e. time) relative to the simple duration d.

d
is the simple duration
t
is a time within the simple duration (0 <= t <= d)
vcur
is the current base value (at time t)
vto
is the defined "to" value

f(t) = vcur + ((vto - vcur) * (t/d))

Note that if no other (lower priority) animations are active or frozen, this defines simple interpolation. However if another animation is manipulating the base value, the to-animation will add to the effect of the lower priority, but will dominate it as it nears the end of the simple duration, eventually overriding it completely. The value for F(t) when a to-animation is frozen (at the end of the simple duration) is just the to value. If a to-animation is frozen anywhere within the simple duration (e.g. using a repeatCount of "2.5"), the value for F(t) when the animation is frozen is the value computed for the end of the active duration. Even if other, lower priority animations are active while a to-animation is frozen, the value for F(t) does not change.

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.

Multiple by-animations combine according to the general rules for additive animation and the animation sandwich model.

The use of from values does not imply either additive or non-additive animation, and both are possible. The from value for an additive animation is simply added to the underlying value, just as for the initial value is in animations specified with a values list. Additive behavior for from-to and from-by animations is controlled by the additive attribute, as in the general case.

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 4 below. These values are simply computed using the formula described above. Note that the value for F(t) for A2 is the presentation value for "x".

Figure 4 - Effect of Additive to-animation example

Time F(t) for A1 F(t) 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
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 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 30 and moves down by another 10 to 40. Etc.

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

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

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

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

Animation function values must be legal values for the specified 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 numbers 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.

3.4 Animation elements

This section defines the syntax and semantics of animation elements. For the DTD, see SMIL Animation Document Type Definition (DTD), below. Timing attributes are defined in the SMIL Timing module.

3.4.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,
keyTimes,
keySplines,
calcMode,
accumulate, and
additive
 
Specify the animation function and effect. See Specifying the animation function f(t) and Specifying the animation effect F(t).

Numerous examples are provided above.

3.4.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 no interpolation control 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 duration of the set element. The argument value must match the target attribute type.

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.4.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 several 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.

The animateMotion element adds an additional syntax alternative for specifying the animation, the path attribute. This allows the description of a path using a subset of the SVG path syntax. Note that if a path is specified, it will override any specified values for values or from/to/by attributes. 

As noted in Animation function values, if any values (i.e. the argument-values for from, to, by or values attributes, or for the path attribute) are not legal, the animation will have no effect (see also Handling Syntax Errors). The same is true if none of the from, to, by, values or path attributes are specified.

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, authors should note that the addition of two or more paced (constant velocity) animations may not result in a combined motion animation with constant velocity.

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

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. If the keyTimes attribute is not specified, the times are derived from the points in the path specification (as described in Animation function calculation modes).

The use of linear for the calcMode with more than 2 points described in values, path or keyTimes may result in motion with varying velocity. The linear calcMode specifies that time is evenly divided among the segments defined by the values or path (note: any "keyTimes" list defines the same number of segments). 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".

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

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.

When a path is combined with discrete, linear or spline calcMode settings, the number of values is defined to be the number of points defined by the path, unless there are "move to" commands within the path.  A "move to" command does not define an additional "segment" for the purposes of timing or interpolation. A "move to" command does not count as an additional point when dividing up the duration, or when associating keyTimes and keySplines values. When a path is combined with a paced calcMode setting, all "move to" commands are considered to have 0 length (i.e. they always happen instantaneously), and should not be considered in computing the pacing.

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.4.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,
keyTimes,
keySplines,
calcMode,
accumulate, and
additive
 
Specify the animation function and effect. See Specifying the animation function f(t) and Specifying the animation effect F(t).

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 function values and How from, to and by attributes affect additive behavior. 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.5 Integrating SMIL Animation into a host language

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.

3.5.1 Required host language definitions

The host language profile must integrate Level 0 of the SMIL Timing module into the host language, satisfying all requirements of that module. If higher levels of SMIL Timing are also integrated into the host language, those levels must be available on Animation elements.

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.

3.5.2 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 integer values and especially floating point values for attributes such as keyTimes and keySplines. 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.

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 must stay within the framework provided by SMIL Timing and 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.

Language integration example: SVG

As an example, SVG [SVG] integrates SMIL Animation. It specifies which of the elements, attributes and CSS properties may be animated.  Some attributes (e.g. viewbox and fill-rule) support only discrete animation, and others (e.g. width, opacity and stroke) support interpolated and additive animation. An example of an attribute that does not support any animation is the xlink:actuate attribute on the <use> element.

SVG details the format of numeric values, describing the legal ranges and allowing "scientific" (exponential) notation for floating point values.

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

3.5.4 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.5.5 SMIL Animation namespace

Language designers can choose to integrate SMIL Animation as an independent namespace, or can integrate SMIL Animation names into a new namespace defined as part of the host language. Language designers that wish to put the SMIL Animation functionality in an isolated namespace should use the general namespace for this version of SMIL.

3.6 Document Object Model support

Any XML-based language that integrates SMIL Animation will inherit the basic interfaces defined in DOM [DOM2] (although not all languages may require a DOM implementation). SMIL Animation specifies the interaction of animation and DOM. SMIL Animation also defines constraints upon the basic DOM interfaces, and specific DOM interfaces to support SMIL Animation.

Note that DOM support in the Timing module provides support for starting and stopping animations and related operations.

Note that the language designer integrating SMIL Animation must specify any additional constraints upon SMIL Animation with respect to the DOM. This includes the specification of language attributes that can or cannot be animated, as well as the definition of addition for any attributes that support additive animation.

3.7 SMIL Animation Document Type Definition (DTD)  

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

     This is Smil-Boston.
     Copyright 2000 W3C (MIT, INRIA, Keio), All Rights Reserved.

        Author:     Patrick Schmitz, Ken Day 
        Revision:   $Id: smil-boston.html,v 1.12 2000/06/22 17:41:51 hugo Exp $


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

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

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


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

<!-- "Core" and "System" attributes:  All Animation elements will
     include these.
 -->
<!ENTITY % Core.attrib "">
<!ENTITY % System.attrib "">

<!-- Animation depends on SMIL Timing, importing the attributes listed
     in the time.attrib entity.  If the integrating profile does not
     provide time.attrib, it is defaulted to Time-level0.attrib, which
     is the minimum requirement.
     
     The profile is also expected to define Fill.attrib.
 -->
<!ENTITY % time.attrib "%Time-level0.attrib;">
<!ENTITY % Fill.attrib "">
<!ENTITY % animTimingAttrs
 "%time.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 encouraged 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        (user | auto) #FIXED 'auto'
    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;
  %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 -->
<!ENTITY % animValueAttrs
 "calcMode (discrete | linear | evenPace | spline) 'linear'
  values CDATA #IMPLIED
  from CDATA #IMPLIED
  to CDATA #IMPLIED
  by CDATA #IMPLIED
  keyTimes CDATA #IMPLIED
  keySplines CDATA #IMPLIED" >

<!-- All except set support additive and cumulative animation -->
<!ENTITY % animAdditionValueAttrs
 "%animValueAttrs;
  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;
  %animAdditionValueAttrs;
>

<!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;
  %animAdditionValueAttrs;
  path           CDATA  #IMPLIED
  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;
  %animAdditionValueAttrs;
>

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

4. The SMIL Content Control

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

4.1 Introduction

This Section defines the SMIL content control module. This module contains elements and attributes which provide for runtime content choices and optimized content delivery. Since these elements and attributes are defined in a module, designers of other markup languages can reuse the functionality in the SMIL content control module when they need to include media content control in their language. Conversely, language designers incorporating other SMIL modules do not need to include the content module if other content control functionality is already present.

This module is broken up into 2 levels. Level 0 contains Content Selection and system test attributes and Level 1 contains user defined test attributes and presentation optimization elements and attributes. It is the intent that the levels build on each other so profiles implementing Level 1 should also implement Level 0.

4.2 Content Selection

SMIL 1.0 provides a "test-attribute" mechanism to process an element only when certain conditions are true, for example when the client has a certain screen-size. 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 to have the client select one of them. This version includes these features and extends them by supporting new system test-attributes, as well as the ability to customize a presentation to an individual viewer by providing author defined, user selected test-attributes.

4.2.1 Level 0

The switch Element

The switch element allows an author to specify a set of alternative elements from which only the first acceptable element should be chosen. An element is acceptable if the language allows the element as a child of a switch, the media-type can be decoded (if the element declares media), and all of the test-attributes of the element evaluate to true. When integrating content control into a profile, the profile must specify what constitutes an "acceptable element."

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.

Thus, authors should order the alternatives from the most desirable to the least desirable. Furthermore, authors should 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). Implementations should NOT arbitrarily pick an object within a switch when test-attributes for all child elements fail.

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.

The skipContent attribute

This attribute is introduced for future extensibility of SMIL. Note that the hyphenated attribute name from SMIL 1.0 has been deprecated in favor of using the current SMIL camelCase convention. The deprecated SMIL 1.0 name is shown in parentheses after the preferred name.

skipContent (skip-content)
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, and this element allows markup from a previous version of the language as element content, the skipContent 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 skipContent attribute controls whether this content is ignored by a user-agent, or results in a syntax error.

If the value of the skipContent 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 skipContent is true.

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

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

Within the list below, the concept of "user preference" may show up. 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.

This version of SMIL defines the following test attributes. Note that some 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.

It is implementation dependent when system or user test attributes are evaluated. Attributes may be evaluated multiple times. Dynamic reevaluation is allowed but not required.

systemBitrate (system-bitrate)
This attribute specifies 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. Such as one intended for audiences with hearing disabilities, those learning to read, or anyone who wants or needs this information. Setting systemCaptions to on means the source will play if the user wants to see captions. Setting it to off means the source will play if the user has indicated that they don't wish to see captions.
Evaluates to true if the user preference matches this attribute value. Evaluates to false if they do not match.
systemLanguage (system-language)
The attribute value is a comma-separated list of language names as defined in [RFC1766].
Evaluates to true if one of the languages indicated by user preferences exactly equals one of the languages given in the value of this parameter, or if one of the languages indicated by user preferences exactly equals 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.
Note: This use of a prefix matching rule does not imply that language tags are assigned to languages in such a way that it is always true that if a user understands a language with a certain tag, then this user will also understand all languages with tags for which this tag is a prefix.

The prefix rule simply allows the use of prefix tags if this is the case.

Implementation note: When making the choice of linguistic preference available to the user, implementers should take into account the fact that users are not familiar with the details of language matching as described above, and should provide appropriate guidance. As an example, users may 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.

Multiple languages MAY be listed for content that is intended for multiple audiences. For example, a rendition of the "Treaty of Waitangi", presented simultaneously in the original Maori and English versions, would call for:

<audio src="foo.rm" systemLanguage="mi, en"/>

However, just because multiple languages are present within the object on which the systemLanguage test attribute is placed, this does not mean that it is intended for multiple linguistic audiences. An example would be a beginner's language primer, such as "A First Lesson in Latin," which is clearly intended to be used by an English-literate audience. In this case, the systemLanguage test attribute should only include "en".

Authoring note: Authors should realize that if several alternative language objects are enclosed in a "switch", and none of them matches, this may lead to situations such as a video being shown without any audio track. It is thus recommended to include a "catch-all" choice at the end of such a switch which is acceptable in all cases.

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)
This attribute specifies the namespace prefix of a language extension, such as a set of new elements or attributes. Evaluates to true if the extension is supported by the implementation, otherwise, this evaluates to false. [NAMESPACES]
systemScreenSize (system-screen-size)
Attribute values have the following syntax: screen-size-val ::= 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.
systemScreenDepth (system-screen-depth)
values: a number greater than 0. Typical values are 1 | 4 | 8 | 24 | 32
This attribute specifies the depth of the screen color palette in bits required for displaying the element.
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.
systemOverdubOrSubtitle
values: overdub | subtitle
This attribute specifies whether subtitles or overdub is rendered for people who are watching a presentation where the audio may be in a language in which they are not fluent. 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.
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 for blind users like systemCaptions provides text captions for deaf users. Setting systemAudioDesc to on means the source will play if the user has indicated a desire to hear audio descriptions. A value of off means the source will play if the user has indicated that they don't wish to hear audio descriptions.
Evaluates to true if the user preference matches this attribute value. Evaluates to false if they do not match.
systemOperatingSystem
The value is an XML NMTOKEN [XML10].
This test attribute specifies the operating system a user-agent may be running on. 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, SONY, SUNOS, UNIXWARE, WIN16, WIN32, WIN9X, WINNT, WINCE, UNKNOWN.

These values come from the _PR_SI_SYSNAME constants defined by the mozilla project http://www.mozilla.org

Evaluates to true if the user preference matches this attribute value. Evaluates to false if they do not match. The value is not case-sensitive
systemCPU
The value is an XML NMTOKEN [XML10].
This test attribute specifies the CPU a user-agent may be running on. 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 http://www.mozilla.org

Evaluates to true if the user preference matches this attribute value. Evaluates to false if they do not match. The value is not case-sensitive
systemComponent
The value is an XML CDATA string
The value describes a component of the playback system, e.g. user-agent component/feature, number of audio channels, codec, HW mpeg decoder, etc. The syntax of the value is implementation dependent.
Evaluates to true if the user-agent supports the described component. Evaluates to false otherwise."

Examples

  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 media player evaluates each of the "choices" (elements within the switch) one at a time, looking for an acceptable bitrate given the known characteristics of the link between the media player and media server.

     0  ...
 1  <par>
 2    <text .../>
 3    <switch>
 4      <par systemBitrate="40000">
 5        ...
 6      </par>
 7      <par systemBitrate="24000">
 8        ...
 9      </par>
10      <par systemBitrate="10000">
11        ...
12      </par>
13    </switch>
14  </par>
15  ...
  2. Choosing between audio resources with different bitrates

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

     0  ...
 1  <switch>
 2     <audio src="joe-audio-better-quality" systemBitrate="16000" />
 3     <audio src="joe-audio" systemBitrate="8000" />
 4  </switch>
 5  ...
  3. Choosing between audio resources in different languages

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

     0  ...
 1  <switch>
 2     <audio src="joe-audio-french" systemLanguage="fr"/>
 3     <audio src="joe-audio-english" systemLanguage="en"/>
 4  </switch>
 5  ...
  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 can choose one of the alternatives.

     0  ...
 1  <par>
 2    <text .../>
 3    <switch>
 4      <par systemScreenSize="1280X1024" systemScreenDepth="16">
 5      ...
 6      </par>
 7      <par systemScreenSize="640X480" systemScreenDepth="32">
 8      ...
 9      </par>
10      <par systemScreenSize="640X480" systemScreenDepth="16">
11      ...
12      </par>
13    </switch>
14  </par>
15  ...
  5. Distinguishing caption tracks from stock tickers

    In the following example, captions are shown only if the user wants captions on.

     0  ...
 1  <seq>
 2    <par>
 3      <audio      src="audio.rm"/>
 4      <video      src="video.rm"/>
 5      <textstream src="stockticker.rt"/>
 6      <textstream src="closed-caps.rt" systemCaptions="on"/>
 7    </par>
 8  </seq>
 9  ...
  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.

     0  ...
 1  <par>
 2    <switch>
 3      <audio src="movie-aud-en.rm" systemLanguage="en" 
 4        systemOverdubOrSubtitle="overdub"/>
 5      <audio src="movie-aud-de.rm" systemLanguage="de" 
 6        systemOverdubOrSubtitle="overdub"/>
 7      <audio src="movie-aud-nl.rm" systemLanguage="nl" 
 8        systemOverdubOrSubtitle="overdub"/>
 9      <!-- French for everyone else -->
10      <audio src="movie-aud-fr.rm"/>
11    </switch>
12    <video src="movie-vid.rm"/>
13    <switch>
14      <textstream src="movie-sub-en.rt" systemLanguage="en"
15        systemOverdubOrSubtitle="subtitle"/>
16      <textstream src="movie-sub-de.rt" systemLanguage="de"
17        systemOverdubOrSubtitle="subtitle"/>
18      <textstream src="movie-sub-nl.rt" systemLanguage="nl"
19        systemOverdubOrSubtitle="subtitle"/>
20      <!-- French captions for those that really want them -->
21      <textstream src="movie-caps-fr.rt" systemCaptions="on"/>
22    </switch>
23  </par>
24  ...

System Test Attribute In-Line Use

When using a switch element for selection only the first element for which all test attributes evaluate to true is selected. This can lead to complex nesting of switch elements to get the desired combinations. Additionally, only the combinations that the author created can be selected. To allow more flexibility in element selection, this version of SMIL allows test attributes outside of the switch element.

An example of how a switch might be used to control the alternatives that could accompany a piece of video in a presentation would be:

 0  ...
 1  <par>
 2    <video src="anchor.mpg" ... />
 3    <switch>
 4      <audio src="dutch.aiff"   systemLanguage="DU" systemOverdubOrSubtitle="overdub" ... />
 5      <audio src="english.aiff" systemLanguage="EN" systemOverdubOrSubtitle="overdub"... />
 6      <text  src="dutch.html"   systemLanguage="DU" systemOverdubOrSubtitle="subtitle"... />
 7      <text  src="english.html" systemLanguage="EN" systemOverdubOrSubtitle="subtitle"... />
 8    </switch>
 9  </par> 
10  ...

This fragment (which is pseudo-SMIL for clarity) says that a video is played in parallel with one of: Dutch audio, English audio, Dutch text, or English text. SMIL does not specify the selection mechanism, only a way of specifying the alternatives. If the user wanted Dutch audio and English text, this possibility must have been considered at authoring time. 

Here is the same example with in-line test attributes:

 0  ...
 1  <par>
 2    <video src="anchor.mpg" ... />
 3    <audio src="dutch.aiff"   systemLanguage="DU" systemOverdubOrSubtitle="overdub" ... />
 4    <audio src="english.aiff" systemLanguage="EN" systemOverdubOrSubtitle="overdub"... />
 5    <text  src="dutch.html"   systemLanguage="DU" systemOverdubOrSubtitle="subtitle"... />
 6    <text  src="english.html" systemLanguage="EN" systemOverdubOrSubtitle="subtitle"... />
 7  </par> 
 8  ...

This example says: a video is accompanied by four other data objects, all of which are (logically) shown in parallel. This is, of course, exactly what happens: all five do run in parallel, but it could be that only the video and one audio stream are actually selected by the user (or a user agent) to be rendered during the presentation. At author time you know which logical streams are available, but it is only at runtime that you know which combination of all potentially available stream actually meet the user's needs. Logically, 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 in the case that many independent alternatives exist.

4.2.2 Level 1

Attributes and elements specified as part of Level 1 are profile specific features. Inclusion of a Level 1 feature requires support for Level 0 features.

User Groups

The provision of switch-based and in-line system test attributes provides a selection mechanism based on general system attributes. This version of SMIL extends this notion with the definition of user test attributes. User test attributes allow presentation authors to define their own test attributes for use in a specific document. 

The elements used to provide user group functionality are: 

The userAttributes element
The userAttributes element contains definitions of each of the user groups. The elements within the section define a collection of author-specified test attributes that can be used in the document. 
The uGroup element 
An author-defined grouping of related media objects. These are defined within the section delineated by the userAttributes elements that make up part of the document header, and they are referenced within a media object definition. 
Attributes: 
uState
values: RENDERED | NOT_RENDERED The values are not case-sensitive.
The initial state for the uGroup is given in the value of this attribute. If unspecified, it defaults to RENDERED. The run-time state is defined by the user or the user agent via the SMIL DOM. If a particular playback environment does not (or cannot) support user selection, the uState attribute controls the author-specified default presentation. 
override
values: allowed | ???? The values are not case-sensitive.
The author is given the ability to block overrides to the initial state by explicitly prohibiting this in the uGroup definition. It is up to the runtime environment to enforce this attribute. The attribute can also be used to influence adaptive behavior at lower level in the transport hierarchy.

It would be good to have more explanation of this last use.

In addition to the userAttributes and uGroup elements, this module provides a uGroup attribute that can be applied to content requiring selection.

The uGroup attribute
uGroup
The uGroup attribute is evaluated as a test attribute, if the uGroup attribute evaluates to true, the associated element is evaluated, otherwise it and its content is skipped. uGroup attributes whose value doesn't match the id of a uGroup element evaluate to false.

The following example shows how user groups can be applied within a SMIL document:

  1 <smil>
  2    <head>
  3       <layout>
  4          <!-- define projection regions -->
  5       </layout>
  6       userAttributes
  7          <uGroup id="nl_aud" uState="RENDERED" title="Dutch Audio Cap" override="allowed" />
  8          <uGroup id="uk_aud" uState="NOT_RENDERED" title="English Audio Cap" override="allowed" />
  9          <uGroup id="nl_txt" uState="NOT_RENDERED" title="Dutch Text Cap" override="allowed" />
 10          <uGroup id="UK_txt" uState="NOT_RENDERED" title="English Text Cap" override="allowed" />
 11       </userAttributes>
 12    </head>
 13    <body>
 14       ...
 15       <par>
 16          <video src="announcer.rm" region="a"/>
 17          <text src="news_headline.html" region="b"/>
 18          <audio src="story_1_nl.rm" uGroup="nl_aud"/>
 19          <audio src="story_1_uk.rm" uGroup="UK_aud-cam"/>
 20          <text src="story_1_nl.html" uGroup="nl_txt" region="c"/>
 21          <text src="story_1_uk.html" uGroup="UK_txt" region="d"/>
 22       </par>
 23       ...
 24    </body>
 25 </smil>

Lines 6 through 11 define the available groups. Each group contains an identifier and a title (which can be used by the user-agent to label the group), as well as the (optional) initial state definition and override flag. 

In line 7, a uGroup named "nl_aud" is defined for Dutch audio captions that is initially set to RENDERED. The other groups in this (very simple) example are set to NOT_RENDERED. 

In lines 15 through 22, a SMIL <par> construct is used to identify a portion of a presentation. In this <par>, a single video (line 16) is accompanied by two audio streams (18,19) and two text streams (20,21), one each for English and Dutch. The <par> also contains a text title that contains a headline.

The interaction of the user interface and the initial state determine which objects are rendered. Note that the same attributes are used across the entire document, meaning that the user only needs to select his/her content preferences once to control related groups of information. In the example, user is free to have the video and headline text accompanied by any combination of English and Dutch captions. (Note that if two audio captions are selected, the player will need to determine how these are processed for delivery.) 

While this example shows in-line use of user groups, the groups could also be applied as test attributes in a switch. Similarly, the system test attributes typically found in a switch could also be used in-line as a control attribute on an element along with the uGroup attribute.

4.3 Presentation Optimization

4.3.1 Level 1

Theprefetch element

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.

The prefetch element, like media object elements, can have id and src. If SMIL Boston Timing is integrated into the document, begin, end, dur, clipBegin, and clipEnd attributes are also available. The id and src elements are the same as for other media objects. id names the element for reference in the document and src names the resource to be prefetched. When a media object with the same src URL is encountered the user-agent can use any data it prefetched to begin playback without rebuffering or other interruption. The timing attributes begin, end, dur would constrain the presentation time period for prefetching the element. At the end of the presentation time specified by end or dur, the prefetch operation should stop. The clipBegin, and clipEnd elements are used to identify the part of the src clip to prefetch, if only the last 30s of the clip are being played, we don't want to prefetch it from the beginning. Likewise if only the middle 30 seconds of the clip are begin played, we don't want to prefetch more data than will be played.

The The mediaSize, mediaTime, and bandwidth Attributes
In addition to the attributes allowed on Media Object Elements, the following attributes are allowed:
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%.
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%

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

For discrete media (non-time based media like text/html or image/png) using the mediaTime attribute causes the entire resource to be fetched.

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

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. is a prefetch has a dur="5s", elements that depend on the prefetch element's timing behave as if the prefetch took 5 seconds.

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.

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.

Note that prefetching data from a URL that changes the content dynamically is dangerous if the entire resource isn't prefetched as the 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.

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

Examples
  1. Prefetch the image so it can be displayed immediately after the video ends: 
      1 <smil>
  2   <body>
  3     <seq>
  4       <par>
  5         <prefetch id="endimage" 
  6           src="http://www.w3c.org/logo.gif"/>
  7         <text id="interlude" 
  8           src="http://www.w3c.org/pleasewait.html" fill="freeze"/>
  9       </par>
 10       <video id="main-event" src="rtsp://www.w3c.org/video.mpg"/>
 11       <image src="http://www.w3c.org/logo.gif" fill="freeze"/>
 12    </seq>
 13   </body>
 14 </smil>

    No timing is specified so default timing applies in the above example. 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: 
      1 <html>
  2   <body>
  3     <prefetch id="upimage" src="http://www.w3c.org/up.gif"/>
  4     <prefetch id="downimage" src="http://www.w3c.org/down.gif"/>
  5     ....
  6     <!-- script will change the graphic on rollover -->
  7     <img src="http://www.w3c.org/up.gif"/>
  8   </body>
  9 </html>

5. SMIL Layout Module

Editors
Aaron Cohen (aaron.m.cohen@intel.com), Intel
Dick Bulterman (Dick.Bulterman@oratrix.com), Oratrix

5.1 Introduction

This section defines the SMIL Layout Module, which is divided into three levels of increasing functionality. Each level builds on the functionality of the lower levels, and higher levels require lower levels as a prerequisite. This module contains 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 a module, 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 module if sufficient layout functionality is already present.

5.2 Overview of SMIL Level 0 Layout

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

Like SMIL 1.0, SMIL Layout Level 0 includes a basic 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="15" 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 Layout Level 0 Syntax and Semantics

5.3.1 Layout Level 0 Elements and Attributes

This section defines the elements and attributes that make up the level 0 functionality in the SMIL layout 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 Layout Level 0 module also support the SMIL Content Control Level 0 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 Content Control Level 0 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 Layout Level 0 layout semantics.
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

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 and left attributes, is always relative to the parent geometry, which is defined by the parent element. For SMIL Layout Level 0, 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, even when used on attributes in a sub-region.

Note that a sub-region may be defined in such a way as to extend beyond the limits of its parent. In this case the sub-region should be clipped to the parent boundaries.

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, except that SMIL layout does not require support for "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 Layout Level 0 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 left 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 fill is hidden.

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.
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.
title
This attribute offers advisory information about the element for which it is set. Values of the title attribute may be rendered by user agents in a variety of ways. For instance, visual browsers frequently display the title as a "tool tip" (a short message that appears when the pointing device pauses over an object). It is strongly recommended that all region elements have a title attribute with a meaningful description. Authoring tools should ensure that no element can be introduced into a SMIL document without this attribute.
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).

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

Element attributes

The root-layout element can have the following attributes:

backgroundColor
Defined in backgroundColor under the region element.
Defined in background-color under the region element.
height
Sets the height of the root element. Only length values are allowed.
title
Defined in title under the region element.
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 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.

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 specifies the XML identifier of the abstract rendering region (either visual or acoustic) defined within the layout section of the document. If no rendering surface with the given identifier is defined in the layout section, the values of the formatting properties of this element are defined by the default layout.

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

5.3.2 SMIL Layout Level 0 Language Details

SMIL Layout Level 0 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.

Editor: This should moved to the language profile and is only here as a reminder.

Fixed property values

The following stylesheet defines the values of the CSS2 properties "display" and "position" that are valid when using SMIL basic layout with the SMIL language. These property values are fixed: 

        
a           {display:block}
anchor      {display:block}
animate     {display:none}
animation   {display: block;
             position: absolute}
area        {display:block}
body        {display: block}
head        {display: none}
excl        {display: block}
img         {display: block;
             position: absolute}
layout      {display: none}  
meta        {display: none}
par         {display: block}
region      {display: none}
ref         {display: block;
             position: absolute}
root-layout {display: none}
seq         {display: block}
smil        {display: block}
switch      {display:block}
text        {display: block;
             position: absolute}
textstream  {display: block;
             position: absolute}
video       {display: block;
             position: absolute}

End of Ednote.

Default values

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

5.3.3 Document Type Definition (DTD) for Level 0

See the full DTD for the SMIL Layout module.

5.4 Overview of SMIL Level 1 Layout

This section defines the functionality in Level 1 of the SMIL Layout Module. This level contains elements and attributes allowing for multiple top-level windows and audio rendering surface volume control. 

5.5 Prerequisites and Requirements for Level 1 Layout

The functionality in this module builds on top of the Level 0 functionality in SMIL Layout, which is a required prerequisite for inclusion of these features.

5.6 New Features in SMIL Layout Level 1

5.6.1 Multiple Top-Level Window Support

In [[SMIL 1.0]], and SMIL Layout Level 0, 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.

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 to WinC ("captions"). 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.

All top level windows are opened as soon as the presentation is started. 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 of those elements. However, a player may choose not to decode content as a performance improvement.

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 an 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 a default window according to SMIL Layout Level 0 semantics.

5.6.2 Audio Volume Control

SMIL Layout Level 1 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.7 SMIL Layout Level 1 Syntax and Semantics

5.7.1 Layout Level 1 Elements and Attributes

This section defines the elements and attributes that make up the SMIL Layout Level 1 module.

The region element

The region element is defined as in SMIL Layout Level 0, 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.

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. 

Note that the precise mapping of viewport windows on to the host environment is implementation dependent. It is expected that implementations will popup independent desktop windows if they can, but other means of supporting multiple viewports, such as by using frames, are allowed.

Element attributes

The viewport element can have the following attributes:

backgroundColor
Defined in backgroundColor under the region element.
background-color
Defined in background-color under the region element.
height
Sets the height of the top-level window. Only length values are allowed.
title
Defined in title under the region element.
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 is defined as in SMIL Layout Level 0 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 Level 1

See the full DTD for the SMIL Layout module.

5.8 Overview of SMIL Layout Level 2

This section defines the functionality in Level 2 of the SMIL Layout Module. This level contains elements and attributes for advanced positioning of media elements on the visual rendering surface and builds upon the previous levels of SMIL Layout; language designers may also elect to include only SMIL Layout Modules Level 0 and Level 1. Note that if the facilities of SMIL Layout Level 2 are used, then support for SMIL Layout Levels 0 and 1 is required.

SMIL Layout Level 2 builds on the basic layout model for organizing media elements into regions on the visual rendering surface presented in SMIL Layout Modules 0 and 1. These extensions are important for certain classes of multimedia presentations in which author control of object placement is critical.

This level:

Where appropriate, CSS2 syntax is used to specify placement attributes. Where no existing CSS attributes or syntax exists, new functionality is proposed that could be merged with CSS in a future release of CSS.

5.9 New Features in SMIL Layout Level 2

5.9.1 Layout Level 2 Elements and Attributes

Hierarchical Region Layout

A new feature in this level 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="0px" left="0px" width="320px" height="480px" />
                <region id="right" top="0px" left="320px" width="320px" height="480px">
                        <region id="inset" top="140px" left="80" width="160px" height="200px" />
                </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 overlap, the existing rules for z-index processing (from Layout Level 0) are applied. Containment is maintained, meaning that in the case of a z-index conflict, the visible region will be determined by the parent region that has most recently (in time) been used to render new content (even if the other parent region has a less recently used hierarchical region with a local sub-division z-index of higher value). 

For example: 

<layout>
        <top-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="C" region="inset" src="imageC.jpg" begin="0s" dur="10s"/>
        <img id="D" region="inset2" src="imageD.jpg" begin="1s" 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>

Image "A" and image "B" begin at the same time. Image A will be shown and will obscure image "B" since the z-index of region "whole" is greater than the z-index of region "inset". 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". The z-index of region "inset" only comes is only considered when computing stacking between siblings, and therefore image "F" will be shown, but image "E" will be obscured.

Ed. note: As far as we know, the use of sub z-index values is consistent with the CSS box model.

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. SMIL Layout Level 2 solves this problem by defining a set of attributes which, when placed on a media object reference, 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 absolute positioning.

The sub-region placement facility is used in cases where exact positioning of a single media element is desired (for example, when you want to position an object a certain number of pixels to the left or right of another object); in these cases, the use of a hierarchical region facility -- while functionally equivalent -- can form an obstacle for presentation authors.

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 Layout Level 2 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="fill" top="5%" left="3" bottom="90%" right="85%" />
     ...
  </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. The resulting display is:

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.

Ed. Note: The ability to override the fit attribute allows for rational control over resizing and scrollbar placement on the object rather than on the containing region. One editor feels that the ability of the media item to override the region's default should be integrated into the fit attribute in Level 0. However, the current specification does not reflect this. A proposal should be made to address this.

Rules for handling clipping of objects within regions based on alignment attributes are provided below.

Registration Points

A registration element is an element within Layout Level 2 that is used to define a point and a default alignment algorithm about that point. The element can be used in a media object reference, 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 Layout Level 2 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 ids 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 b, 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. Use of the registration point facility takes precedence over use of the fit attribute (that is, the fit attribute is ignored if registration points are used).

Each of the media objects share the z-order of the parent. If used within a <par> construct, then the standard rules for objects with overlapping z-order are applied.

Ed. Note: The issue of multiple elements rendered to the same region in a <par> is not inherently an issue with Layout Level 2, but a more general SMIL layout concern. It is unclear if SMIL-1.0 actually prohibits this, even though it does not seem to be support now by RN or OX. Our view is that since regions are pure rendering spatial abstractions, it should be possible to render multiple objects in the same region under the existing z-index rules. The presence of hierarchical regions give authors extra control for special cases, but do not preclude the utility of multiple active objects. (Note that RealPix supports this functionality now, and a lot of our users like this functionality.)

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 Layout Level 2 provides a pre-defined center registration point named "center". This means that media objects can be centered in any region by including the attribute: 

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

in a media object reference. The default value of regAlign for a region is topLeft. If the regAlign attribute is used without a regPoint, the aligment operation is relative to the upper left point of the region containing this object.

Ed. Note: And the default value for regPoint is "upperLeft"? Should we predefine a regPoint named "upperLeft"?

Rules for handling clipping of objects within regions based on alignment attributes are defined below.

5.10 SMIL Layout Level 2 Syntax and Semantics

5.10.1 Layout Level 2 Elements and attributes

This section defines the elements and attributes that make up the SMIL Layout Level 2.

The layout element

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

Element attributes

SMIL Layout Level 2 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-level2-layout", it can contain the following elements:

region
root-layout
viewport
regPoint

All element content except regPoint are defined in SMIL Layout Level 0 or 1. The regPoint element is described below.

The region element

The region element controls the position, size and scaling of media object elements. Layout Level 2 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 SMIL Layout Level 2, 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 defined as relative to the parent 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 sub-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 Layout Level 2, the region element has no additional attributes beyond that provided in Layout Level 0 and 1. However, the semantics of the z-index attribute are extended to support hierarchical regions.

z-index
This 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.
 
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).

Element content

SMIL Layout Level 2 extends the region element content model to optionally include other region elements.

The regPoint element

The regPoint element defines a relative or absolute point for use in aligning elements in the document's body on a visual rendering surface.

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

If registration points are used on a media object, the fit attribute is ignored.

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 "0".
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 "100%".
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 top is "0".
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 "100%".
regAlign
This attribute specifies the default alignment algorithm which is associated with this regPoint, relative to the media object. 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
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
center
align the center of the object with the registration point
midRight
align the middle-right point of the object with the registration point
bottomLeft
align the lower-left corner of the object with the registration point
bottomMid
align the bottom-middle point of the object with the registration point
bottomRight
align the bottom-right corner of the object with the registration point.

Element content

None.

SMIL Layout Level 2 positioning attributes

While SMIL Layout Level 0 provides only the region attribute on elements to place them on the rendering surface, Level 2 includes attributes to refine the position of media content within a region.

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 positioning attributes, the fit attribute, and registration alignment attributes are present on an object reference, the registration alignment attributes take precedence and the positioning and fit attributes are ignored.

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.

Sub-region Positioning Attributes
top
This value uniquely identifies the position or the distance (in pixels or %) of the top position of the media object relative to the top of the region. The default value of top is "0".
bottom
This value uniquely identifies the position or the distance (in pixels or %) of the bottom of the media object relative to the bottom of the region. The default value of bottom is "100%".
left
This value uniquely identifies the position or the distance (in pixels or %) of the left side of the media object relative to the left location of the region. The default value of left is "0".
right
This value uniquely identifies the position or the distance (in pixels or %) of the top-left position of the media object relative to the right side of the region. The default value of right is "100%".

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

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. A value of "center" is pre-defined by Layout Level 2 to be equal to top="50%", left="50%". If no value is given, the default registration point of top="0", left="0" is assumed.
regAlign
This value uniquely identifies the registration algorithm to be used for the regPoint defined for the object. Permissible values are those defined under the regAlign attribute for the regPoint element. If used within an explicit regPoint attribute, the value is relative to the top left point of the region used by the associated media object.

5.10.2 Document Type Definition (DTD) for Level 2

See the full DTD for the SMIL Layout module.

5.11 SMIL Layout Document Type Definition (DTD) 

<!-- ======================================================================= -->
<!-- SMIL Layout Module  =================================================== -->
<!-- file: SMIL-layout.mod

	This is Smil-Boston.
	Copyright 2000 W3C (MIT, INRIA, Keio), All Rights Reserved.

	Authors: Jacco van Ossenbruggen, Aaron Cohen
	Revision:   $Id: smil-boston.html,v 1.12 2000/06/22 17:41:51 hugo Exp $

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

	PUBLIC "-//W3C//ELEMENTS SMIL-Boston Layout//EN"
	SYSTEM "SMIL-layout.mod"

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

<!-- ================== Layout Level 0 Profiling Entities ================== -->
<!ENTITY % layout.attrib       "">
<!ENTITY % region-elem.attrib  "">
<!ENTITY % rootlayout.attrib   "">
<!ENTITY % layout.content     "EMPTY">
<!ENTITY % region.content     "EMPTY">
<!ENTITY % rootlayout.content "EMPTY">


<!-- ================== Layout Level 0 Layout Entities ===================== -->
<!ENTITY % viewport-attrs "
	backgroundColor     CDATA    #IMPLIED
	background-color    CDATA    #IMPLIED
	height              CDATA    'auto'
	width               CDATA    'auto'
">

<!ENTITY % region-attrs "
	bottom              CDATA    'auto'
	fit                 (hidden|fill|meet|scroll|slice)    'hidden'
	left		    CDATA    'auto'
	right	            CDATA    'auto'
	top                 CDATA    'auto'
	z-index             CDATA    #IMPLIED
">

<!-- ================== Layout Level 0 Layout Elements ===================== -->
<!--
     Layout contains the region and root-layout elements defined by
     smil-basic-layout or other elements defined an external layout
     mechanism.
-->

<!ELEMENT layout %layout.content;>
<!ATTLIST layout %layout.attrib;
        type CDATA   'text/smil-basic-layout'
>

<!--=================== Region Element ======================================-->
<!ELEMENT region %region.content;>
<!ATTLIST region %region-elem.attrib;
	%viewport-attrs;
	%region-attrs;
>

<!--=================== Root-layout Element =================================-->
<!ELEMENT root-layout %rootlayout.content; >
<!ATTLIST root-layout %rootlayout.attrib;
	%viewport-attrs;
>

<!-- ========================== Layout Level 1 ============================= -->
<!ENTITY % layout-level-1 "IGNORE">
<![%layout-level-1;[
  <!-- ================ Layout Level 1 Profiling Entities ================== -->
  <!ENTITY % viewport.attrib    "">
  <!ENTITY % viewport.content   "">

  <!-- don't need to add viewport element to 
     content of layout since it is assumed to be ANY  -->
  <!-- ================== Layout Level 1 Layout Entities =================== -->
  <!ENTITY % audio-attrs "
	soundLevel			CDATA    '100&#37;'
  ">

  <!-- ================== Layout Level 1 Layout Elements =================== -->

  <!--=================== Add soundLevel to region element ================= -->
  <!ATTLIST region %audio-attrs;>

  <!--=================== viewport element ================================= -->
  <!ELEMENT viewport (region %viewport.content;)* >
  <!ATTLIST viewport %viewport.attrib;
	%viewport-attrs;
  >
]]> <!-- end Layout Level 1 -->

<!-- ========================== Layout Level 2 ============================= -->
<!ENTITY % layout-level-2 "IGNORE">
<![%layout-level-2;[
  <!-- ================ Layout Level 2 Profiling Entities ================== -->
  <!ENTITY % regPoint.attrib     "">
  <!ENTITY % regPoint.content   "EMPTY">
  <!-- ================== Layout Level 2 Layout Entities =================== -->

  <!-- subregion positioning attributes for regPoint and media elements == -->
  <!ENTITY % positioning-attrs "
	top			CDATA    '0&#37;'
	bottom                  CDATA    '100&#37;'
	left			CDATA    '0&#37;'
	right			CDATA    '100&#37;'
  ">

  <!-- ================ regAlign attribute for regPoint and media elements = -->
  <!ENTITY % regalign-attrs "
	regAlign  (topLeft|topMid|topRight|midLeft|center|
		   midRight|bottomLeft|bottomMid|bottomRight) #IMPLIED
  ">

  <!-- ================== regPoint attribute for media elements ============ -->
  <!ENTITY % regpoint-attrs "
	regPoint			CDATA	#IMPLIED
  ">
  <!-- integrating language using this level must include regPoint attribute -->
  <!-- on media element ==================================================== -->

  <!-- ================== Layout Level 2 Layout Elements =================== -->
  <!ELEMENT regPoint %regPoint.content;>
  <!ATTLIST regPoint %regPoint.attrib;
	%positioning-attrs;
	%regalign-attrs;
  >
]]>
<!-- end of SMIL-layout.mod -->

6. The SMIL Linking Module

Editors
Lloyd Rutledge (Lloyd.Rutledge@cwi.nl), (CWI)
Aaron Cohen (aaron.m.cohen@intel.com), (Intel)

6.1 Introduction

The SMIL Linking module defines the SMIL document attributes and elements for navigational hyperlinking. These are navigations through the SMIL presentation that can be triggered by user interaction or other triggering events. SMIL provides only for in-line link elements. Links are limited to uni-directional single-headed links (i.e. all links have exactly one source and one destination resource).

The SMIL Linking module is divided into Levels 0, 1, and 2. Level 0 includes a set of attributes used to provide SMIL Linking semantics to linking elements, Level 1 includes the SMIL Linking elements themselves, and Level 2 includes additional optional linking features that a language profile may wish to include. Note that Level 1 explicitly includes the attributes from Level 0 on its elements.

6.2 Relationship to XPointer

XPointer [XPTR] allows components of XML documents to be addressed in terms of their placement in the XML structure rather than on their unique identifiers. This allows referencing of any portion of an XML document without having to modify that document. Without XPointer, pointing within a document may require adding unique identifiers to it, or inserting specific elements into the document, such as a named anchor in HTML. XPointers are put within the fragment identifier part of a URI. The SMIL specification does not require that browsers be able to process XPointers in SMIL URI attributes.

6.3 Linking into SMIL Documents

The SMIL Linking Module supports name fragment identifiers and the '#' connector. The fragment part is an id value that identifies one of the elements within the referenced SMIL document. With this construct, SMIL supports locators as currently used in HTML (that is, it uses locators of the form "http://foo.com/some/path#anchor1"), with the difference that the values are of unique identifiers and not the values of "name" attributes. Of course, this type of link can only target elements that have an attribute of type ID. 

Links using fragments enable authors to encode links to a SMIL presentation at the start time of a particular element rather than at the beginning of its presentation. If a link containing a fragment part is followed, the presentation should start as if the user had fast-forwarded the presentation represented by the destination document to the effective begin of the element designated by the fragment. See the discussion of linking to timing constructs in the SMIL Timing and Synchronization Module for more information.

There are special semantics defined for following a link containing a fragment part into a document containing SMIL timing. These semantics are defined in the SMIL Timing and Synchronization Module. In addition, the following rules apply for linking into a document written in the SMIL language:

  1. It is forbidden to link to elements that are the content of switch elements. If the element addressed by the link is content of a switch element, then the presentation should start with the switch element. See the section below on error handling.
  2. If the fragment part ID is not defined within the target document, the SMIL presentation should start from the beginning as if no fragment part were present in the URI.

6.3.1 Handling of Links in Embedded Documents

Due to its integrating nature, the presentation of a SMIL document may involve other (non-SMIL) applications or plug-ins. For example, a SMIL browser may use an HTML plug-in to display an embedded HTML page. Vice versa, an HTML browser may use a SMIL plug-in to display a SMIL document embedded in an HTML page. Note that this is only one of the supported methods of integrating SMIL and HTML. Another alternative is to use the merged language approach. See the SMIL Timing and Integration Module for further details.

In embedded presentations, links may be defined by documents at different levels and conflicts may arise. In this case, the link defined by the containing document should take precedence over the link defined by the embedded object. Note that since this might require communication between the browser and the plug-in, SMIL implementations may choose not to comply with this recommendation.

If a link is defined in an embedded SMIL document, traversal of the link affects only the embedded SMIL document.

If a link is defined in a non-SMIL document which is embedded in a SMIL document, link traversal can only affect the presentation of the embedded document and not the presentation of the containing SMIL document. This restriction may be relaxed in future versions of SMIL.

6.3.2 Error Handling

When a link into a SMIL document contains an un-resolvable fragment identifier ("dangling link") because it identifies an element that is not actually part of the document, SMIL software should ignore the fragment identifier, and start playback from the beginning of the document.

When a link into a SMIL document contains a fragment identifier which identifies an element that is the content of a switch element, SMIL software should interpret this link as going to the parent switch element instead. If the parent is also a switch, then the link should be considered as accessing the first switch ancestor element whose parent is not also a switch. The result of the link traversal is thus to play the child of the located switch element that passes the usual switch child selection process.

6.4 SMIL Linking Level 0 Attributes

The SMIL Linking module includes several attributes that a language profile can include on linking elements to add SMIL linking semantics to those elements. The SMIL Linking elements in the next section explicitly include these attributes. These attributes are designated SMIL Linking Level 0 and can be applied to linking elements from other namespaces if allowed by the language profile.

sourceLevel
This attribute sets the relative audio level of media objects in the presentation containing the link when the link is followed. Ignored if the presentation does not contain audio media objects. This attribute can take positive percentage values. The sourceLevel attribute is applied to the current audio level of the source.
destinationLevel
This attribute sets the relative audio level of media objects in the remote resource when the link is followed. Ignored if the remote resource does not contain audio media objects. This attribute can take positive percentage values. The destinationLevel attribute is applied to the natural or intrinsic audio level of the destination media, and therefore is relative to the level that the media would be played without application of the destinationLevel attribute.
sourcePlaystate
This attribute controls the temporal behavior of the presentation containing the link when the link is traversed. It can have the following values:
  • play: When the link is traversed, the presentation containing the link continues playing.
  • pause: When the link is traversed, the presentation containing the link pauses. When the display of the destination resource completes, the originating presentation resumes playing.
  • stop: When the link is traversed, the presentation containing the link stops. That is, it is reset to the beginning of the presentation. The termination of the destination resource will not cause the originating presentation to continue or restart.

The default value of the sourcePlaystate attribute depends on the value of the show attribute. If the show attribute has the value new, the default for the sourcePlaystate attribute is play. If the show attribute has the value replace or the deprecated value pause, then the default for the sourcePlaystate attribute is pause.

Note that the definition of what constitutes a resource completing needs to be defined in the language profile, or may be implementation dependent. Typical definitions would be when the user closes the display window, or when a continuous media object ends.

destinationPlaystate
This attribute controls the temporal behavior of the external resource (typically identified by the href attribute) when the link is followed. It only applies when this resource is a continuous media object. It can have the same values as the sourcePlaystate attribute. The default value is play.
show
This attribute specifies how to handle the current state of the presentation at the time in which the link is activated. The following values are allowed:
  • new: The presentation of the destination resource starts in a new context, not affecting the source resource. If both the presentation containing the link and the remote resource contain audio media, both are played in parallel.
  • pause: This value is deprecated in favor of setting the the "show" attribute to new and the sourcePlaystate attribute to pause.
  • replace: The current presentation is paused at its current state and is replaced by the destination resource. If the player offers a history mechanism, the source presentation resumes from the state in which it was paused when the user returns to it. The default value of  sourcePlaystate is pause when the show attribute has the value replace.

The default value of show is replace.

accesskey
This attribute assigns a keyboard key whose activation by the user in turn activates this link. It has the same meaning as the attribute of the same name in HTML 4.01 [HTML401].
tabindex
This attribute provides the same functionality as the tabindex attribute in HTML 4.01 [HTML401]. It specifies the position of the element in the tabbing order for the current document. The tabbing order defines the order in which elements will receive focus when navigated by the user via the keyboard. At any particular point in time, only elements with an active timeline are taken into account for the tabbing order, and inactive elements that are are ignored for the tabbing order.
target
This attribute defines either the existing display environment in which the link should be opened (e.g., a SMIL region, an HTML frame or another named window), or triggers the creation of a new display environment with the given name. Its value is the identifier of the display environment. If no currently active display environment has this identifier, a new display environment is opened and assigned the identifier of the target. When a presentation uses different types of display environments (e.g. SMIL regions and HTML frames), the namespace for identifiers is shared between these different types of display environments. For example, one cannot use a target attribute with the value "foo" twice in a document, and have it point once to an HTML frame, and then to a SMIL region. If the element has both a show attribute and a target attribute, the show attribute is ignored.
external
This attribute defines whether the link destination should be opened by the current application or some external application. A value of true will open the link in an application defined on the system to handle this media type. A value of false will open the destination in the current application. The default value of external is false.
Note that the means of associating media types with external applications is system dependent and not defined here.
actuate
The actuate attribute determines whether or not the link is triggered by some event or automatically traversed when its time span is active. Its default value is onRequest, which means something must trigger the link traversal. This trigger is defined by the user interaction and event attributes of the linking element. A value of onLoad can also be assigned. This value indicates that the link is automatically traversed when the element becomes active. For linking elements containing SMIL timing, this is when the active duration of the element effectively begins, in other words, when the element's beginEvent event is fired. See the SMIL Timing and Synchronization module for more details.

6.5 SMIL Linking Level 1 Elements

The link elements allows the description of navigational links between objects. The SMIL Linking module provides only uni-directional, single-headed, in-line link elements. SMIL Linking Level 1 uses support from the Timing and Synchronization module and requires at least Level 0 of that module to be included with any profile using the SMIL Linking module Level 1.

6.5.1 The a Element

The functionality of the a element is very similar to the functionality of the a element in HTML 4.01 [HTML401]. For synchronization purposes, the a element is transparent. That is, it does not influence the synchronization of its child elements. a elements may not be nested. An a element must have an href attribute.

An a element can specify several triggers for its traversal simultaneously. For example, the element's content visual media can be selected by the user or the key specified by the accesskey attribute can be typed to trigger a traversal. In cases where multiple triggers are specified, any of them can activate the link's traversal. That is, an logical or is applied to the list of triggering conditions to determine if traversal occurs.

Traversal occurs if one of the conditions for traversal is met during the time that the a element is active. An a element is active if the media or elements that it contains are active. See the SMIL Timing and Synchronization and Media modules for further details.

Attributes
href
This attribute contains the URI of the link's destination. The href attribute is required for a elements.

The a element also includes the attributes defined in SMIL Linking Level 0:

Element Content

The content of the a element must be defined by the language profile. In general, it is expected that a elements may contain the media and timing elements present in the language profile as children. Since this level of the linking module requires Level 0 from the Timing and Synchronization Module, at least the following elements should be included in the content model of the a element:

par
seq

Examples

These examples assume that the a element has the same content model as in the SMIL Boston Language Profile.

Example 1

The link starts up the new presentation replacing the presentation that was playing. 

<a href="http://www.cwi.nl/somewhereelse.smi">
     <video src="rtsp://foo.com/graph.imf" region="l_window"/>
</a>

Example 2

The link starts up the new presentation in addition to the presentation that was playing. 

<a href="http://www.cwi.nl/somewhereelse.smi" show="new">
     <video src="rtsp://foo.com/graph.imf" region="l_window"/>
</a>

This could allow a SMIL player to spawn off an HTML browser: 

<a href="http://www.cwi.nl/somewebpage.html" show="new">
     <video src="rtsp://foo.com/graph.imf" region="l_window"/>
</a>

Example 3

The link starts up the new presentation and pauses the presentation that was playing. 

<a href="http://www.cwi.nl/somewhereelse.smi" show="new" behavior="pause">
     <video src="rtsp://foo.com/graph.imf" region="l_window"/>
</a>

Example 4

The following example contains a link from an element in one presentation A to the middle of another presentation B. This would play presentation B starting from the effective begin of the element with id "next". 

Presentation A:

     <a href="http://www.cwi.nl/presentationB#next">
       <video src="rtsp://foo.com/graph.imf"/>
     </a>


Presentation B (http://www.cwi.nl/presentation):

      ...
      <seq>
        <video src="rtsp://foo.com/graph.imf"/>
        <par>
          <video src="rtsp://foo.com/timbl.rm" region="l_window"/>
          <video id="next" src="rtsp://foo.com/v1.rm" region="r_window"/>
                 ^^^^^^^^^
          <text src="rtsp://foo.com/caption1.html" region="l_2_title"/>
          <text src="rtsp://foo.com/caption2.rtx" region="r_2_title"/>
        </par>
      </seq>
      ...

6.5.2 The area Element

The functionality of the a element is restricted in that it only allows associating a link with a complete media object. The HTML 4.0 area element [HTML401] has demonstrated that it is useful to associate links with spatial portions of an object's visual display.

The semantics of the area element in SMIL is the same as it is for HTML in that:

  1. The area element allows associating a link destination, specified by the href attribute, with spatial portions of a visual object. In contrast, the a element only allows associating a link with complete media.
  2. The area element allows making a subpart of the media object the destination of a link, using the ID attribute.
  3. The area element allows breaking up an object into spatial subparts, using the coords attribute.

It extends the syntax and semantics of the HTML area element by providing for linking from non-spatial portions of the media object's display. These extensions are:

  1. The area element allows breaking up an object into temporal subparts, using the begin and end attributes from the SMIL Timing and Synchronization module. The values of the begin and end attributes are relative to the beginning of the containing media object.
  2. The area element allows breaking up an XML-defined object into syntactic components, using the "fragment" attribute. The spatial and temporal portion of the display that activates the link is defined in terms of the syntactic structure of that object. This allows portions of the display of XML code integrated in a SMIL presentation to be starting areas for links in SMIL. An example is having an HTML file format the text for a menu of items. These are displayed as part of a SMIL presentation. Each item can be clicked upon to activate a link in the containing SMIL presentation.

The anchor element is deprecated in favor of area. For purposes of this specification of SMIL, the anchor element should be treated as a synonym for area

Attributes

The area element can have the attributes listed below, with the same syntax and semantics as in HTML 4.0 [HTML401]:

shape
This attribute specifies the shape of a region.
coords
This attribute specifies the position and shape on the screen. The number and order of values depends on the shape being defined.
href
nohref
When set, this boolean attribute specifies that a region has no associated link
alt

The area element also supports the follow attributes from the SMIL Timing and Synchronization module:

The following attributes are newly added to the area element in this specification, and defined above in the section on Linking Level 0 attributes:

Element Content

The area element is empty.

Examples

1) Decomposing a video into temporal segments

In the following example,  the temporal structure of an interview in a newscast (camera shot on interviewer asking a question followed by shot on interviewed person answering ) is exposed by fragmentation: 

<smil>
  <body>
    <video src="video" title="Tom Cruise interview 1995" >
      <seq>
        <area id="firstQ" dur="20s" title="first question" /> 
        <area id="firstA" dur="50s" title="first answer" />
      </seq>
    </video>
  </body>
</smil>

2) Associating links with spatial segments In the following example, the screen space taken up by a video clip is split into two sections. A different link is associated with each of these sections. 

<smil>
  <body>
    <video src="video" title="Tom Cruise interview 1995" >
      <area shape="rect" coords="5,5,50,50" 
              title="Journalist" href="http://www.cnn.com"/>
      <area shape="rect" coords="5,60,50,50" 
              title="Tom Cruise" href="http://www.brando.com" />
   </video>
  </body>
</smil>

3) Associating links with temporal segments

In the following example, the duration of a video clip is split into two sub-intervals. A different link is associated with each of these sub-intervals. 

<smil>
  <body>
    <video src="video" title="Tom Cruise interview 1995" >
      <seq> 
        <area dur="20s" title="first question" 
              href="http://www.cnn.com"/>
        <area dur="50s" title="first answer" 
              href="http://www.brando.com"/>
      </seq>
   </video>
  </body>
</smil>

4) Associating links with spatial subparts

In the following example, the screen space taken up by a video clip is split into two sections. A different link is associated with each of these sections. 

<video src="http://www.example.org/CoolStuff">
  <area href="http://www.example.org/AudioVideo" coords="0%,0%,50%,50%"/>
  <area href="http://www.example.org/Style"      coords="50%,50%,100%,100%"/>
</video>

5) Associating links with temporal subparts

In the following example, the duration of a video clip is split into two subintervals. A different link is associated with each of these subintervals. 

<video src="http://www.example.org/CoolStuff">
  <area href="http://www.example.org/AudioVideo" begin="0s" end="5s"/>
  <area href="http://www.example.org/Style"      begin="5s" end="10s"/>
</video>

6) Jumping to a subpart of an object

The following example contains a link from an element in one presentation A to the middle of a video object contained in another presentation B. This would play presentation B starting from second 5 in the video. That is, the presentation would start as if the user had fast-forwarded the whole presentation to the point at which the designated fragment in the "CoolStuff" video begins. 

Presentation A:

<a href="http://www.cwi.nl/mm/presentationB#tim">
   <video id="graph" src="rtsp://foo.com/graph.imf" region="l_window"/>
</a>


Presentation B:

<video src="http://www.example.org/CoolStuff">
  <area id="joe" begin="0s" end="5s"/>
  <area id="tim" begin="5s" end="10s"/>
</video>

7) Combining different uses of links

The following example shows how the different uses of associated links can be used in combination. 

Presentation A:

<a href="http://www.cwi.nl/mm/presentationB#tim">
  <video id="graph" src="rtsp://foo.com/graph.imf" region="l_window"/>
</a>


Presentation B:

<video src="http://www.example.org/CoolStuff">
  <area id="joe" begin="0s" end="5s" coords="0%,0%,50%,50%"
          href="http://www.example.org/"/>
  <area id="tim" begin="5s" end="10s" coords="0%,0%,50%,50%"
          href="http://www.www.example.org.org/Tim"/>
</video>

6.6 SMIL Linking Level 2 Attributes

The attributes in this section represent advanced capabilities that can be optionally included in the document profile. These features may or may not be included in a language profile, but they should not be optional features within a profile.

6.6.1 The fragment Attribute

A profile may choose to include the fragment attribute as part of the area element. It provides for a host document to externally include a link in a contained media object that will be processed at the level of the host document.

fragment
This attribute refers to a portion of the embedded media object that is to act as the starting point of this link in the SMIL presentation. If this user clicks on, or otherwise activates, this portion of the embedded media display, the SMIL browser recognizes this as the current link being activated. This overrides any linking that may happen within the embedded display of the media object.

The value of the fragment attribute must be recognizable by the process managing the media object as an activate-able portion of the object. If the referenced media object is an HTML file, then the value of the fragment attribute is a named anchor within the HTML file. If the referenced media object is an XML file, then the value of the fragment attribute is a fragment identifier (the part that comes after a '#' in a URI).

Take for example the following SMIL code. It establishes a portion of the display as a formatted text menu. Clicking on an item in this menu triggers a link to elsewhere within the presentation. The code defines embedded an HTML file and establishing a fragment area within it: 

<ref src="menu.html" region="menubar">
  <area fragment="menuitem1" href="#selection1"/>
</ref>

In the rendered HTML display, there is a portion of displayed text that is marked-up as an area with the name "menuitem1". If the user clicks on this during the SMIL presentation, a SMIL-activated link is triggered, navigating to the portion of the SMIL document with the ID "selection1". If the HTML area named "item1" has an href attribute itself, then this hyperlink is overridden - only the SMIL hyperlink is processed. HTML area with href attributes and no associated SMIL fragment attributes are not overridden. This HTML area activate links within the embedded HTML presentation when clicked upon.

Use of the fragment