Synchronized Multimedia Integration Language (SMIL 2.0) Specification

W3C Working Draft 01 March 2001

This version:

http://www.w3.org/TR/2001/WD-smil20-20010301/
(Other formats: single HTML file, zip archive)

Latest version:

http://www.w3.org/TR/smil20

Previous version:

http://www.w3.org/TR/2000/WD-smil20-20000921/

Editors:

Jeff Ayars (RealNetworks), Dick Bulterman (Oratrix), Aaron Cohen (Intel), Ken Day (Macromedia), Erik Hodge (RealNetworks), Philipp Hoschka (W3C), Eric Hyche (RealNetworks), Muriel Jourdan (INRIA), Michelle Kim (IBM), Kenichi Kubota (Panasonic), Rob Lanphier (RealNetworks), Nabil Layaïda (INRIA), Thierry Michel (W3C), Debbie Newman (Microsoft), Jacco van Ossenbruggen (CWI), Lloyd Rutledge (CWI), Bridie Saccocio (RealNetworks), Patrick Schmitz (Microsoft), Warner ten Kate (Philips).

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

---

Abstract

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

• Define an XML-based language that allows authors to write interactive multimedia presentations. Using SMIL 2.0, an author can describe the temporal behavior of a multimedia presentation, associate hyperlinks with media objects and describe the layout of the presentation on a screen.
• Allow reusing of SMIL syntax and semantics in other XML-based languages, in particular those who need to represent timing and synchronization. For example, SMIL 2.0 components are used for integrating timing into XHTML [XHTML10] and into SVG [SVG].

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.

This is a W3C Working Draft of the Synchronized Multimedia Integration Language (SMIL) 2.0 specification produced by the SYMM Working Group [members only]. This specification is a revision of the W3C Last Call Working Draft 21 September 2000, incorporating comments and suggestions received during the Last Call review. Only minor editing updates are expected in the upcoming Candidate Recommendation version.

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

This is a W3C Working Draft for review by W3C Members and other interested parties. It is a draft document and may be updated, replaced or obsoleted by other 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 is work in progress and does not imply endorsement by, or the consensus of, the W3C Membership.

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

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

1. About SMIL 2.0

Editors

Aaron Cohen (aaron.m.cohen@intel.com), Intel

Thierry Michel (tmichel@w3.org), W3C

1.1 Introduction

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

• Define an XML-based language that allows authors to write interactive multimedia presentations. Using SMIL 2.0, an author can describe the temporal behavior of a multimedia presentation, associate hyperlinks with media objects and describe the layout of the presentation on a screen.
• Allow reusing of SMIL 2.0 syntax and semantics in other XML-based languages, in particular those who need to represent timing and synchronization. For example, SMIL 2.0 components are used for integrating timing into XHTML [XHTML10] and into SVG [SVG].

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

1.1.1 Relation to SMIL 1.0

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

1.1.2 Content of this specification

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

• Section 2 is an overview of SMIL 2.0 modularization and the individual modules, and presents conformance criteria.
• Section 3 defines the declarative SMIL 2.0 Animation Modules.
• Section 4 presents the SMIL 2.0 Content Control Modules.
• Section 5 describes the SMIL 2.0 Layout Modules.
• Section 6 defines the SMIL 2.0  Linking Modules.
• Section 7 presents the SMIL 2.0  Media Object Modules.
• Section 8 defines the SMIL 2.0  Metainformation Module.
• Section 9 defines the SMIL 2.0 Structure Module.
• Section 10 defines the SMIL 2.0 Timing and Synchronization Modules.
• Section 11 defines the SMIL 2.0 Time Manipulations Module.
• Section 12 presents the SMIL 2.0 Transition effects Modules.

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

• Section 13 defines the SMIL 2.0 Language Profile.
• Section 14 describes the SMIL 2.0 Basic Profile and Scalability Framework.

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

1.2 Acknowledgements

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

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

2. The SMIL 2.0 Modules

Editors:

Warner ten Kate (warner.ten.kate@philips.com), (Philips Electronics)

Aaron Cohen (aaron.m.cohen@intel.com), (Intel)

Philipp Hoschka (ph@w3.org), (W3C)

2.1 Introduction

This section is informative.

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

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

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

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

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

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

2.1.1 Modularization and Profiling

This section is informative.

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

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

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

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

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

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

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

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

2.2 SMIL 2.0 Modules

This section is normative.

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

The functional areas and their corresponding modules are:

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

This section is informative.

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

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

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

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

2.2.1 SMIL DOM

This section is informative.

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

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

2.3 Identifiers for SMIL 2.0 Modules and Language Profiles

This section is informative.

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

2.3.1 The SMIL Mime Type

This section is normative.

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

2.3.2 XML Namespace Identifier for the SMIL 2.0 Modules

This section is normative.

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

http://www.w3.org/2001/SMIL20/WD/

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

2.3.3 Identifiers for SMIL 2.0 Modules and Features

This section is normative.

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

Table 2 summarizes the identifiers for SMIL 2.0 modules.

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

http://www.w3.org/2001/SMIL20/WD/NestedTimeContainers

Profile allows nesting of the par and seq time containers.

http://www.w3.org/2001/SMIL20/WD/DeprecatedFeatures

Profile supports deprecated SMIL 1.0 features.

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

Modules can also be identified collectively. The following four module collections are defined:

http://www.w3.org/2001/SMIL20/WD/

All the modules specified by the SMIL 2.0 specification.

http://www.w3.org/2001/SMIL20/WD/Language

The modules used by the SMIL 2.0 Language profile.

http://www.w3.org/2001/SMIL20/WD/HostLanguage

The modules required for SMIL Host Language Conformance.

http://www.w3.org/2001/SMIL20/WD/IntegrationSet

The modules required for SMIL Integration Set Conformance.

2.4 SMIL Conformance

This section is informative.

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

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

This section is normative.

The following two tables list names used to collectively reference certain sets of SMIL 2.0 elements and attributes. These are used in the definitions of the minimum support in the two sections below on SMIL host language conformance and SMIL integration set conformance. The term "minimum support" is used to refer to the minimum set of elements that an element can contain, and the minimum set of attributes that can be used on an element.

2.4.1 SMIL Host Language Conformance

This section is normative.

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

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

In addition, the following requirements must be satisfied:

1. The language profile defines what modules it collects.
2. The language profile includes all elements, attributes, and attribute values specified by the collected modules.
3. The language profile fullfills the "minimum support" requirements for elements and attributes as listed in Table 5 below.
4. The language profile complies with the integration requirements set forth by the modules it collects.
5. The language profile specifies the semantics related to the integration of the modules.
6. The language profile defines its DTD or XML Schema.
7. The language profile defines a unique identifier conforming to the requirements set forth in Requirements on Identifiers for SMIL Host Language Conformant Language Profiles.
8. The SyncbaseTiming module should be included in Host Language conformant profiles, although it is not strictly required. We strongly recommend inclusion of this module in Host Language conformant profiles to maintain a high level of consistency and interoperability with other languages that have integrated SMIL modules including the SMIL 2.0 Language, XHTML+SMIL, and SVG. Only profiles designed to operate on severely constrained devices may omit the SyncbaseTiming module.

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

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

2.4.2 SMIL Integration Set Conformance

This section is normative.

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

1. BasicContentControl
2. BasicInlineTiming
3. BasicMedia
4. BasicTimeContainers
5. MinMaxTiming
6. RepeatTiming
7. SyncbaseTiming

In addition, the following requirements must be satisfied:

1. The language profile defines what modules it collects.
2. The language profile includes all elements, attributes, and attribute values specified by the collected SMIL 2.0 modules.
3. The language profile fulfills the "minimum support" requirements for elements and attributes as listed in Table 6 below.
4. The language profile complies with the integration requirements set forth by the SMIL 2.0 modules it collects.
5. The SyncbaseTiming module should be included in Integration Set conformant profiles, although it is not strictly required. We strongly recommend inclusion of this module in Integration Set conformant profiles to maintain a high level of consistency and interoperability with other languages that have integrated SMIL modules including the SMIL 2.0 Language, XHTML+SMIL, and SVG. Only profiles designed to operate on severely constrained devices may omit the SyncbaseTiming module.

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

2.4.3 Requirements on Identifiers for SMIL Host Language Conformant Language Profiles

This section is informative.

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

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

as the namespace identifier for SMIL 1.0.

This section is normative.

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

1. The document should declare a default namespace [XML-NS].
2. The default namespace must be declared on the <smil> root element.
3. In case the SMIL host language conformant language profile has been issued as a W3C Recommendation, the default namespace identifier must satisfy the following requirements:
   1. The URI is constructed conformant to the requirements set forth by the W3C [W3C-NSURI].
   2. The default namespace identifier should identify the language profile.
      In case the language profile is a subset of a larger one, the default namespace identifier may also identify that larger language profile. The module collection that is required to be supported in the subset language profile may be indicated through the systemRequired attribute on the <smil> element.
      See the SMIL Basic language profile specification for an example.

2.4.4 Error Handling in SMIL Host Language Conformant Documents

This section is normative.

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

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

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

2.5 Creating a DTD for a Language Profile

This section is informative.

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

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

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

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

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

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

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

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

The driver file.

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

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

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

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

The document model file.

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

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

For the same reasons, the SMIL module files only define a default attribute list for their elements. This default list only contains the SMIL 2.0 core attributes and the attributes that are defined in the same SMIL module file. All other attributes need to be added to this default list by defining the appropriate XML entities. For example, the Media Objects Module file only adds the core and media related attributes on the media objects, other attributes, such as the timing attributes, are added to this list by the document model file.

3. The SMIL 2.0 Animation Modules

Editors

Patrick Schmitz (pschmitz@microsoft.com), (Microsoft)

Aaron Cohen (aaron.m.cohen@intel.com), (Intel)

Ken Day (kday@macromedia.com), (Macromedia)

3.1 Introduction

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

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

While this document defines a base set of animation capabilities, it is assumed that host languages may build upon the support to define additional or more specialized animation elements.  Animation only manipulates attributes and properties of the target elements, and so does not require any knowledge of the target element semantics beyond basic type information.

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

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

3.2 Animation Model

This section describes the semantics underlying the SMIL 2.0 animation modules. The specific elements are not described here, but rather the common concepts and syntax that comprise the model for animation.  Document issues are described, as well as the means to target an element for animation. The animation model is then defined by building up from the simplest to the most complex concepts: first the simple duration and simple animation function f(t), and then the overall effect F(t,u). 

3.2.1 The simple animation function f(t)

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

Normative

A target attribute is the name of a feature of a target element as defined in a host language document.

This may be (e.g.) an XML attribute contained in the element or a CSS property that applies to the element.  By default, the target element of an animation will be the parent of the animation element (an animation element is typically a child of the target element). However, the target may be any element in the document, identified either by an XML ID reference or via an XLink [XLINK] locator reference.

As a simple example, the following defines an animation of an SVG rectangle shape.  The rectangle will change from being tall and thin to being short and wide.

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

The rectangle begins with a width of 10 pixels and increases to a width of 100 pixels over the course of 10 seconds. Over the same ten seconds, the height of the rectangle changes from 100 pixels to 10 pixels.

When an animation is running, it should not actually change the attribute values in the DOM [DOM2].  The animation runtime should maintain a presentation value for each animated attribute, separate from the DOM or CSS Object Model (OM). If an implementation does not support an object model, it should maintain the original value as defined by the document as well as the presentation value. The presentation value is reflected in the displayed form of the document. Animations thus manipulate the presentation value, and should not affect the base value exposed by DOM or CSS OM. This is detailed in The animation sandwich model.

Normative

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

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

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

An animation element defines a simple animation function which is evaluated as needed over time by the implementation. The resulting values are applied to the presentation value for the target attribute. Animation functions are continuous in time and can be sampled at whatever frame rate is appropriate for the rendering system. The syntactic representation of the simple animation function is independent of this model, and may be described in a variety of ways. The animation elements in this specification support syntax for a set of discrete or interpolated values, a path syntax for motion based upon SVG paths, keyframe based timing, evenly paced interpolation, and variants on these features.

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

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

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

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

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

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

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

Normative

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

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

Animations can be defined to either override or add to the base value of an attribute. In this context, the base value may be the DOM value, or the result of other animations that also target the same attribute. This more general concept of a base value is termed the underlying value. Animations that add to the underlying value are described as additive animations. Animations that override the underlying value are referred to as non-additive animations. The animation effect function of an element is the function which includes the affect of the underlying value and accounts for repeating and freezing of the element. Because the animation effect can be affected by repeating and freezing, it is defined over the active duration of the element rather than its simple duration.

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

Normative

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

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

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

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

3.2.2 Summary of symbols used in the semantic descriptions

a

The target attribute of an animation element.

d

The simple duration of the element.

AD

The active duration of the element.

t

A time. Depending on the context, t may be in user-perceived time, an element's active duration, or its simple duration.

u

The underlying value of the target attribute a, generally at a specific time t.

f(t)

The simple animation function of times within the simple duration. Note that while F(t,u) defines the mapping for the entire animation, f(t) has a simplified model that just handles the simple duration.

F(t,u)

The effect of an animation for any point in the active duration of the animation. This maps times within the active duration (t: 0<=t<=AD) and an underlying value to a value for the target attribute. A time value of 0 corresponds to the time at which the animation begins. F(t,u) combines the simple animation function f(t) with all the other aspects of animation and timing controls.

3.2.3 The animation sandwich model

When an animation is running, it does not actually change the attribute values in the DOM.  The animation runtime should ideally maintain a presentation value for any target attribute, separate from the DOM, CSS, or other object model (OM) in which the target attribute is defined. The presentation value is reflected in the display form of the document. The effect of animations is to manipulate this presentation value, and not to affect the underlying DOM or CSS OM values.

The remainder of this discussion uses the generic term OM for both the XML DOM [DOM2] as well as the CSS-OM. If an implementation does not support an object model, it should ideally maintain the original value as defined by the document as well as the presentation value; for the purposes of this section, we will consider this original value to be equivalent to the value in the OM.

In some implementations of DOM, it may be difficult or impractical to main a presentation value as described. CSS values should always be supported as described, as the CSS-OM provides a mechanism to do so. In implementations that do not support separate presentation values for general XML DOM properties, the implementation must at least restore the original value when animations no longer have an effect. 

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

The model accounting for the OM and concurrently active or frozen animations for a given attribute is described as a "sandwich", a loose analogy to the layers of meat and cheeses in a "submarine sandwich" (a long sandwich made with many pieces of meats and cheese layered along the length of the bread). In the analogy, time is associated with the length of the sandwich, and each animation has its duration represented by the length of bread that the layer covers. On the bottom of the sandwich is the base value taken from the OM. Each active (or frozen) animation is a layer above this. The layers (i.e. the animations) are placed on the sandwich both in time along the length of the bread, as well as in order according to priority, with higher priority animations placed above (i.e. on top of) lower priority animations. At any given point in time, you can take a slice of the sandwich and see how the animation layers stack up.

Note that animations manipulate the presentation value coming out of the OM in which the attribute is defined, and pass the resulting value on to the next layer of document processing. This does not replace or override any of the normal document OM processing cascade. 

Specifically, animating an attribute defined in XML will modify the presentation value before it is passed through the style sheet cascade, using the XML DOM value as its base. Animating an attribute defined in a style sheet language will modify the presentation value passed through the remainder of the cascade. 

In CSS2 and the DOM 2 CSS-OM, the terms "specified", "computed" and "actual" are used to describe the results of evaluating the syntax, the cascade and the presentation rendering. When animation is applied to CSS properties of a particular element, the base value to be animated is read using the (readonly) getComputedStyle() method on that element. The values produced by the animation are written into an override stylesheet for that element, which may be obtained using the getOverrideStyle() method. These new values then affect the cascade and are reflected in a new computed value (and thus, modified presentation). This means that the effect of animation overrides all style sheet rules, except for user rules with the !important property. This enables !important user style settings to have priority over animations, an important requirement for accessibility. Note that the animation may have side effects upon the document layout. See also section 6.1, "Specified, computed, and actual values," of [CSS2] and section 5.2.1, "Override and computed style sheet," of [DOM2CSS].

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

• If one animation is a time dependent of another (e.g. it is specified to begin when another begins), then the time dependent is considered to activate after the syncbase element, and so has higher priority. Time dependency is further discussed in Propagating changes to times. This rule applies independent of the timing described for the syncbase element - i.e. it does not matter whether the syncbase element begins on an offset, relative to another syncbase, relative to an event-base, or via hyperlinking. In all cases, the syncbase is begun before any time dependents are begun, and so the syncbase has lower priority than the time dependent.
• If two animations share no time dependency relationship (e.g. neither is defined relative to the other, even indirectly) the element that appears first in the document has lower priority. This includes the cases in which two animation elements are defined relative to the same syncbase or event-base. 

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

• If only additive animations are active or frozen (i.e. no non-additive animations are active or frozen for the given attribute) when the OM value is changed, the presentation value must reflect the changed OM value as well as the effect of the additive animations. When the animations complete and the effect of each is no longer applied, the presentation value will be equal to the changed OM value.
  
• If any non-additive animation is running when the OM value is changed, the presentation value will not reflect the changed OM value, but will only reflect the effect of the highest priority non-additive animation, and any still higher priority additive animations. When all non-additive animations complete and the effect of each is no longer applied, the presentation value will reflect the changed OM value and the effect of any additive animations that are active or frozen.

3.2.4 Animation elements as "continuous media"

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

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

3.2.5 The animation effect function F(t,u)

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

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

• The repeated animation function, fr(t), defines the effect of repeating an animation element.
• The cumulative animation function, fc(t), defines the effect of accumulating values from one iteration to the next of a repeated animation element.
• The frozen animation function, ff(t), includes the effect of freezing an animation element at the end of its active duration.
• The animation effect function, F(t,u), defines how a an animation element depends on the underlying value u of the target attribute.

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

Repeating animations

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

Normative

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

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

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

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

Examples

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

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

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

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

In the following example, the animation function will repeat for a total of 7 seconds. It will play fully two times, followed by a fractional part of 2 seconds. This is equivalent to a repeatCount of 2.8. The last (partial) iteration will apply values in the range "0" to "8". 

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

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

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

Note that if the simple duration is not defined (e.g. it is indefinite), repeat behavior is not defined (but repeatDur still defines the active duration). In the following example the simple duration is indefinite, and so the repeatCount is effectively ignored. Nevertheless, this is not considered an error: the active duration is also indefinite. The effect of the animation is to to just use the value for f(0), setting the fill color to red for the remainder of the animate element's duration.

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

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

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

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

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

Controlling behavior of repeating animation - Cumulative animation

The author may also select whether a repeating animation should repeat the original behavior for each iteration, or whether it should build upon the previous results, accumulating with each iteration. For example, a motion path that describes an arc can repeat by moving along the same arc over and over again, or it can begin each repeat iteration where the last left off, making the animated element bounce across the window. This is called cumulative animation.

Normative

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

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

If the element is cumulative:

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

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

f0(t) = f(t)

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

The cumulative animation function is then

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

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

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

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

The image moves from the original position along the arc over the course of 5 seconds. As the animation repeats, it builds upon the previous value and begins the second arc where the first one ended, as illustrated in Figure 1, below. In this way, the image "bounces" across the screen. The same animation could be described as a complete path of 4 arcs, but in the general case the path description can get quite large and cumbersome to edit.

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

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

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

Any numeric attribute that supports addition can support cumulative animation. For example, we can define a "pulsing" animation that will grow the "width" of an SVG <rect> element by 100 pixels in 50 seconds.

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

Each simple duration causes the rectangle width to bulge by 15 pixels and end up 10 pixels larger. The shape is 20 pixels wide at the beginning, and after 5 seconds is 30 pixels wide. The animation repeats, and builds upon the previous values. The shape will bulge to 45 pixels and then end up 40 pixels wide after 10 seconds, and will eventually end up 120 (20 + 100) pixels wide after all 10 repeats.

Freezing animations

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

By default when an animation element ends, its effect is no longer applied to the presentation value for the target attribute. For example, if an animation moves an image and the animation element ends, the image will "jump back" to its original position.

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

As shown in Figure 2, the image will appear stationary at the top value of "3" for 5 seconds, then move 100 pixels down in 10 seconds. 15 seconds after the document begin, the animation ends, the effect is no longer applied, and the image jumps back from 103 to 3 where it started (i.e. to the underlying DOM value of the top attribute).

Figure 2 - Illustration of animation without freezing.

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

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

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

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

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

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

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

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

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

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

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

Stating this formally:

Normative

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

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

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

ff(AD) = fc(AD).

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

ff(AD) = f(d).

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

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

3.2.6 Additive animation

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

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

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

The width begins at 20 pixels, and increases to 30 pixels over the course of 10 seconds.  If the animation were declared to be non-additive, the same from and to values would make the width go from 0 to 10 pixels over 10 seconds.

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

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

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

Normative

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

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

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

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

When there are multiple animations defined for a given attribute that overlap at any moment, the two either add together or one overrides the other. Animations overlap when they are both either active or frozen at the same moment. The ordering of animations (e.g. which animation overrides which) is determined by a priority associated with each animation. The animations are prioritized according to when each begins. The animation first begun has lowest priority and the most recently begun animation has highest priority.

Higher priority animations that are not additive will override all earlier (lower priority) animations, and simply set the attribute value.  Animations that are additive apply (i.e. add to) to the result of the earlier-activated animations. For details on how animations are combined, see The animation sandwich model.

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

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

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

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

While many animations of numerical attributes will be additive, this is not always the case. As an example of an animation that is defined to be non-additive, consider a hypothetical extension animation "mouseFollow" that causes an object to track the mouse. 

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

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

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

Additive and Cumulative animation

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

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

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

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

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

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

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

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

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

Refer also to The animation sandwich model.

3.2.7 Restarting animations

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

When an animation restarts, the defining semantic is that it behaves as though this were the first time the animation had begun, independent of any earlier behavior. The animation effect function F(t,u) is defined independent of the restart behavior. Any effect of an animation playing earlier is no longer applied, and only the current animation effect F(t,u) is applied.

If an additive animation is restarted while it is active or frozen, the previous effect of the animation (i.e. before the restart) is no longer applied to the attribute. Note in particular that cumulative animation is defined only within the active duration of an animation. When an animation restarts, all accumulated context is discarded, and the animation effect F(t,u) begins accumulating again from the first iteration of the restarted active duration.

3.2.8 Animation function value details

Many animations specify the simple animation function f(t) as a sequence of values to be applied over time. For some types of attributes (e.g. numbers), it is also possible to describe an interpolation function between values.

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

More complex forms specify a list of values, or even a path description for motion. Authors can also control the timing of the values, to describe "keyframe" animations, and even more complex functions.

In all cases, the animation effect function, F(t,u), must yield legal values for the target attribute. Three classes of values are described:

1. Unitless scalar values. These are simple scalar values that can be parsed and set without semantic constraints. This class includes integers (base 10) and floating point (format specified by the host language).
2. String values. These are simple strings.
3. Language abstract values. These are values like CSS-length and CSS-angle values that have more complex parsing, but that can yield values that may be interpolated.

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

In order to support interpolation on attributes that define numeric values with some sort of units or qualifiers (e.g. "10px", "2.3feet", "$2.99"), some additional support is required to parse and interpolate these values. One possibility is to require that the animation framework have built-in knowledge of the unit-qualified value types. However, this violates the principle of encapsulation and does not scale beyond CSS to XML languages that define new attribute value types of this form.

The recommended approach is for the animation implementation for a given host environment to support two interfaces that abstract the handling of the language abstract values. These interfaces are not formally specified, but are simply described as follows:

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

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

This is not an attempt to specify how an implementation provides this support, but rather a requirement for how values are interpreted. Animation behaviors should not have to understand and be able to convert among all the CSS-length units, for example. In addition, this mechanism allows for application of animation to new XML languages, if the implementation for a language can provide parsing and conversion support for attribute values.

The above recommendations notwithstanding, it is sometimes useful to interpolate values in a specific unit-space, and to apply the result using the specified units rather than canonical units. This is especially true for certain relative units such as those defined by CSS (e.g. em units). If an animation specifies all the values in the same units, an implementation may use knowledge of the associated syntax to interpolate in the unit space, and apply the result within the animation sandwich, in terms of the specified units rather than canonical units. As noted above, this solution does not scale well to the general case. Nevertheless, in certain applications (such as CSS properties), it may be desirable to take this approach.

Interpolation and indefinite simple durations

If the simple duration of an animation is indefinite (e.g. if no dur value is specified), interpolation is not generally meaningful. While it is possible to define an animation function that is not based upon a defined simple duration (e.g. some random number algorithm), most animations define the function in terms of the simple duration. If an animation function is defined in terms of the simple duration and the simple duration is indefinite, the first value of the animation function (i.e. f(0)) should be used (effectively as a constant) for the animation function.

3.3 Overview of the SMIL 2.0 BasicAnimation Module

The SMIL 2.0 BasicAnimation module provides

• Syntax for identifying target elements and attributes,
• Simple animation functions defined by sets of points to be visited in sequence, with the function defined between those using discrete, linear or paced interpolation.
• The animate element for generic animation.
• The set element for simply setting the value of the target attribute to a constant value
• The animateMotion element for defining motion on a path. And
• The animateColor element for defining color changes over time.

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

3.4 SMIL 2.0 BasicAnimation Module Common Attributes

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

3.4.1 Specifying the animation target

The animation target is defined as a specific attribute of a particular element. The means of specifying the target attribute and the target element are detailed in this section.

The target attribute

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

The attributes of an element that can be animated are often defined by different languages, and/or in different namespaces. For example, in many XML applications, the position of an element (which is a typical target attribute) is defined as a CSS property rather than as XML attributes. In some cases, the same attribute name is associated with attributes or properties in more than one language, or namespace.  To allow the author to disambiguate the name mapping, an additional attribute attributeType is provided that specifies the intended namespace. 

The attributeType attribute is optional. By default, the animation runtime will resolve the names according to the following rule: If there is a name conflict and attributeType is not specified, the list of CSS properties supported by the host language is matched first (if CSS is supported in the host language); if no CSS match is made (or CSS does not apply) the default namespace for the target element will be matched.

If a target attribute is defined in an XML Namespace other than the default namespace for the target element, the author must specify the namespace of the target attribute using the associated namespace prefix as defined in the scope of the target element. The prefix is prepended to the value for attributeName.

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

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:

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.

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

3.4.2 Specifying the simple animation function f(t)

Every animation function defines the value of the attribute at a particular moment in time. The time range for which the animation function is defined is the simple duration. The animation function does not produce defined results for times outside the range of 0 to the simple duration.

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

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

The following example using the values syntax animates the width of an SVG shape over the course of 10 seconds, interpolating from a width of 40 to a width of 100 and back to 40.

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

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

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

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

Normative

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

• For discrete animation, the duration is divided into n equal time periods, one per value. The animation function takes on the values in order, one value for each time period:

      f(t) = value[i]

• For linear animation, the duration is divided into n-1 equal periods, and the animation function is a linear interpolation between the values at the associated times:

        f(t) = value[i] + (value[i+1]-value[i]) * (t-ti)/d.

• For paced animations, the duration is divided into periods of lengths such that the rate of change of the attribute remains constant. If the distance between two values is dist(v1,v2), the total distance traversed D(i) up to and including value[i] is

  D(0) = 0, and

  D(i) = dist(value[0],value[1]) + dist(value[1],value[2]) +...+ dist(value[i-1],value[i]), for integers i with 0<i<=n.

  The animation function takes on the values in the values attribute at times determined by these distances:

    T(i) = (D(i)/D(n)) * d, for integers i with 0<=i<=n.

    f(t) = value[i] + (value[i+1]-value[i]) * (t-T(i))/d,

  where i is the largest non-negative integer such that T(i)<=t.

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

Interpolation modes illustrated

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

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

Figure 5 - Discrete, linear and paced animation

	Figure 5a: Default discrete animation. calcMode="discrete" There are 6 segments of equal duration: 1 segment per value.
	Figure 5b: Default linear animation. calcMode="linear" There are 5 segments of equal duration: n-1 segments for n values.
	Figure 5c: Default paced animation. calcMode="paced" There are 5 segments of varying duration: n-1 segments for n values, computed to yield a constant rate of change in the value.

Examples of calcMode

The following example describes a simple discrete animation:

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

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

The following example describes a simple linear animation:

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

The value of "x" will change from 0 to 10 in the first 5 seconds, and then from 10 to 100 in the second 5 seconds. Note that the values in the values attribute are spaced evenly in time; in this case the result is a much larger actual change in the value during the second half of the animation. Contrast this with the same example changed to use "paced" interpolation:

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

To produce an even pace of change to the attribute "x", the second segment defined by the values list gets most of the simple duration: The value of "x" will change from 0 to 10 in the first second, and then from 10 to 100 in the next 9 seconds. While this example could be easily authored as a from-to animation without paced interpolation, many examples (such as motion paths) are much harder to author without the paced value for calcMode. 

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

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

• Repeated or frozen, using the attributes repeatCount, repeatDur and fill of the BasicInlineTiming module.
• Defined as cumulative or non-cumulative when repeated.
• Defined as additive or non-additive when combined with the underlying value.

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

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

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

3.4.4 Simple animation functions specified by from, to and by

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

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

from-to animation

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

Normative: A from-to animation with a from value vf and a to value vt is equivalent to the same animation with a values list with 2 values, vf and vt.

from-by animation

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

Normative: A from-by animation with a from value vf and a by value vb is equivalent to the same animation with a values list with 2 values, vf and (vf+vb).

by animation

Specifying only a by value defines a simple animation in which the animation function is defined to offset the underlying value for the attribute, using a delta that varies over the course of the simple duration, starting from a delta of 0 and ending with the delta specified with the by attribute. This may only be used with attributes that support additive animation.

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

to animation

This describes an animation in which the animation function is defined to start with the underlying value for the attribute, and finish with the value specified with the to attribute. Using this form, an author can describe an animation that will start with any current value for the attribute, and will end up at the desired to value.

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

Examples

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

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

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

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

The following "by animation" example animates the width of an SVG shape over the course of 10 seconds from the original width of 40 to a width of 70.

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

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

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

The rectangle will grow from 10 to 20 pixels in the first 5 seconds, and then from 20 to 30 in the next 5 seconds, and so on up to 110 pixels after 10 repeats. Note that since the default value for additive is replace, the original value is ignored. The following example makes the animation explicitly additive:

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

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

To animation

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

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

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

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

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

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

Normative

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

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

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

Repeating to animations is the same as repeating other animations:

Normative

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

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

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

Normative

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

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

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

Normative

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

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

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

For example, consider

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

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

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

Normative

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

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

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

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

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

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

Figure 6 - Effect of Additive to animation example

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

3.5 SMIL 2.0 BasicAnimation Elements

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

3.5.1 The animate element

The animate element introduces a generic attribute animation that requires little or no semantic understanding of the attribute being animated. It can animate numeric scalars as well as numeric vectors. It can also animate a single non-numeric attribute through a discrete set of values. The animate element is an empty element; it cannot have child elements.

This element supports from/to/by and values descriptions for the animation function, as well as all of the calculation modes. It supports all the described timing attributes. These are all described in respective sections above.

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

3.5.2 The set element

The set element provides a simple means of just setting the value of an attribute for a specified duration. As with all animation elements, this only manipulates the presentation value, and when the animation completes, the effect is no longer applied. That is, set does not permanently set the value of the attribute. 

The set element supports all attribute types, including those that cannot reasonably be interpolated and that more sensibly support semantics of simply setting a value (e.g. strings and Boolean values). The set element is non-additive. The additive and accumulate attributes are not allowed, and will be ignored if specified.

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

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

Normative

The simple animation function defined by a set element is

f(t) = v

were v is the value of the to attribute.

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

Examples

The following changes the stroke-width of an SVG rectangle from the original value to 5 pixels wide. The effect begins at 5 seconds and lasts for 10 seconds, after which the original value is again used.

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

The following example sets the class attribute of the text element to the string "highlight" when the mouse moves over the element, and removes the effect when the mouse moves off the element. 

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

3.5.3 The animateMotion element

The animateMotion element will move an element along a path. The element abstracts the notion of motion and position across a variety of layout mechanisms - the host language defines the layout model and must specify the precise semantics of position and motion. The path can be described in either of two ways:

• Specifying x,y pairs for the from/to/by attributes. These will define a straight line motion path.
• Specifying x,y pairs for the values attribute. This will define a motion path of straight line segments, or points (if calcMode is set to discrete). This will override any from/to/by attribute values.

All values must be x, y value pairs. Each x and y value may specify any units supported for element positioning by the host language. The host language defines the default units. In addition, the host language defines the reference point for positioning an element. This is the point within the element that is aligned to the position described by the motion animation. The reference point defaults in some languages to the upper left corner of the element bounding box; in other languages the reference point may be implicit, or may be specified for an element.

The syntax for the x, y value pairs is:

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

Coordinate values are separated by at least one white space character or a comma. Additional white space around the separator is allowed. The values of coordinate must be defined as some sort of number in the host language.

The attributeName and attributeType attributes are not used with animateMotion, as the manipulated position attribute(s) are defined by the host language. If the position is exposed as an attribute or attributes that can also be animated (e.g. as "top" and "left", or "posX" and "posY"), implementations must combine animateMotion animations with other animations that manipulate individual position attributes. See also The animation sandwich model.

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

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

3.5.4 The animateColor element

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

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

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

The values in the from/to/by and values attributes may specify negative and out of gamut values for colors.  The function defined by an individual animateColor may yield negative or out of gamut values.  The implementation must correct the resulting presentation value, to be legal for the destination (display) colorspace. However, as described in The animation sandwich model, the implementation should only correct the final combined result of all animations for a given attribute, and should not correct the effect of individual animations.

Values are corrected by "clamping" the values to the correct range. Values less than the minimum allowed value are clamped to the minimum value (commonly 0, but not necessarily so for some color profiles). Values greater than the defined maximum are clamped to the maximum value (defined by the host language) .

Note that color values are corrected by clamping them to the gamut of the destination (display) colorspace. Some implementations may be unable to process values which are outside the source (sRGB) colorspace and must thus perform clamping to the source colorspace, then convert to the destination colorspace and clamp to its gamut. The point is to distinguish between the source and destination gamuts; to clamp as late as possible, and to realize that some devices, such as inkjet printers which appear to be RGB devices, have non-cubical gamuts.

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

3.6 SMIL 2.0 BasicAnimation Module Details

3.6.1 BasicAnimation integration requirements

This section describes what a language designer must actually do to specify the integration of SMIL Animation into a host language. This includes basic definitions and constraints upon animation.

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

Required definitions and constraints on animation targets

Specifying the target element

The host language designer must choose whether to support the targetElement attribute or the XLink attributes for specifying the target element. Note that if the XLink syntax is used, the host language designer must decide how to denote the XLink namespace for the associated attributes. The namespace can be fixed in a DTD, or the language designer can require colonized attribute names (qnames) to denote the XLink namespace for the attributes. The required XLink attributes have fixed values, and so may also be specified in a DTD, or can be required on the animation elements. Host language designers may require that the optional XLink attributes be specified. These decisions are left to the host language designer - the syntax details for XLink attributes do not affect the semantics of SMIL Animation.

In general, target elements may be any element in the document. Host language designers must specify any exceptions to this. Host language designers are discouraged from allowing animation elements to target elements outside of the document in which the animation element is defined. The XLink syntax for the target element could allow this, but the SMIL timing and animation semantics of this are not defined in this version of SMIL Animation.

Target attribute issues

The definitions in this module can be used to animate any attribute of any element in a host document. However, it is expected that host language designers integrating SMIL Animation may choose to constrain which elements and attributes can support animation. For example, a host language may choose not to support animation of the language attribute of a script element. A host language which included a specification for DOM functionality might limit animation to the attributes which may legally be modified through the DOM.

Any attribute of any element not specifically excluded from animation by the host language may be animated, as long as the underlying data type (as defined by the host language for the attribute) supports discrete values (for discrete animation) and/or addition (for interpolated, additive and cumulative animation).

All constraints upon animation must be described in the host language specification or in an appropriate schema, as the DTD alone cannot reasonably express this.

The host language must define which language abstract values should be handled for animated attributes. For example, a host language that incorporates CSS may require that CSS length values be supported. This is further detailed in Animation function value details.

The host language must specify the interpretation of relative values. For example, if a value is specified as a percentage of the size of a container, the host language must specify whether this value will be dynamically interpreted as the container size is animated.

The host language must specify the semantics of clamping values for attributes. The language must specify any defined ranges for values, and how out of range values will be handled.

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

Integrating animateMotion functionality

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

3.6.2 Document type definition (DTD) for the BasicAnimation module

See the full DTD for the SMIL Animation Modules.

3.7 Overview of the SMIL 2.0 SplineAnimation Module

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

3.7.1 SMIL 2.0 SplineAnimation Module Attributes

Spline animation function calculation mode

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

• The calcMode attribute is extended to support splines.
• A path attribute is added to the animateMotion element, allowing authors to define a motion path using a subset of the SVG [SVG] path syntax, and providing smooth path motion.
• 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).
• The keySplines attribute provides a means of controlling the pacing of interpolation between the values in the values list.

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

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

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

Using:

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

Control point values are separated by at least one white space character or a comma. Additional white space around the separator is allowed. The allowed syntax for floating point numbers must be defined in the host language.

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

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

Examples of advanced uses of calcMode

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

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

This example also shows how keyTimes values can interact with an indefinite duration. The value of the "color" attribute will be set to green for 5 seconds, and then to yellow for 5 seconds, and then will remain red for the remainder of the document, since the (unspecified) duration defaults to "indefinite".

The following example illustrates the use of keyTimes:

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

The keyTimes values cause the "x" attribute to have a value of "0" at the start of the animation, "50" after 8 seconds (at 80% into the simple duration) and "100" at the end of the animation. The value will change more slowly in the first half of the animation, and more quickly in the second half.

Interpolation with keySplines

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

Extending the above example to use keySplines:

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

The keyTimes still cause the "x" attribute to have a value of "0" at the start of the animation, "50" after 8 seconds and "100" at the end of the animation. However, the keySplines values define a curve for pacing the interpolation between values. In the example above, the spline causes an ease-in and ease-out effect between time 0 and 8 seconds (i.e. between keyTimes 0 and .8, and values "0" and "50"), but a strict linear interpolation between 8 seconds and the end (i.e. between keyTimes .8 and 1, and values  "50" and "100"). Figure 7 shows the curves that these keySplines values define.

Figure 7 - Illustration of keySplines effect

	keySplines="0 0 1 1" (the default)		keySplines=".5 0 .5 1"
	keySplines="0 .75 .25 1"		keySplines="1 0 .25 .25"

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

To illustrate the calculations, consider the simple example:

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

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

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

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

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

The value will change from 10 to 20, using an "ease-in/ease-out" curve specified by the keySplines values. The keyTimes values cause the value of 20 to be reached at 7 seconds, and to hold there for the remainder of the 10 second simple duration.

The following example describes a somewhat unusual usage, a from-to animation with discrete animation. The stroke-linecap attribute of SVG elements takes a string, and so implies a calcMode of discrete. The animation will set the stroke-linecap attribute to round for 5 seconds (half the simple duration) and then set the stroke-linecap to square for 5 seconds.

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

3.7.2 SMIL 2.0 SplineAnimation Module Elements

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

3.7.3 The spline animate element

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

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

3.7.4 The spline animateMotion element

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

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

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

3.7.5 The spline animateColor element

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

3.8 SMIL 2.0 SplineAnimation Module Details

3.8.1 SplineAnimation integration requirements

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

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

3.8.2 Document type definition (DTD) for the SplineAnimation module

See the full DTD for the SMIL Animation Modules.

3.9 Common Animation Integration Requirements

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

3.9.1 Integration requirements

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

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

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

Extending Animation

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

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

Constraints on manipulating animation elements

Language designers integrating SMIL Animation are encouraged to disallow manipulation of attributes of the animation elements after the document has begun. This includes both the attributes specifying targets and values, as well as the timing attributes. In particular, the id attribute (of type ID) on all animation elements must not be mutable (i.e. should be read-only). Requiring animation runtimes to track changes to id values introduces considerable complexity, for what is at best a questionable feature.

It is recommended that language specifications disallow manipulation of animation element attributes through DOM interfaces after the document has begun.  It is also recommended that language specifications disallow the use of animation elements to target other animation elements.

Note in particular that if the attributeName attribute can be changed (either by animation or script), problems may arise if the target attribute has a namespace qualified name. Current DOM specifications do not include a mechanism to handle this binding.

Dynamically changing the attribute values of animation elements introduces semantic complications to the model that are not yet sufficiently resolved. This constraint may be lifted in a future version of SMIL Animation.

Handling syntax errors

The specific error handling mechanisms for each attribute are described with the individual syntax descriptions.  Some of these specifications describe the behavior of an animation with syntax errors as "having no effect".  This means that the animation will continue to behave normally with respect to timing, but will not manipulate any presentation value, and so will have no visible impact upon the presentation. 

In particular, this means that if other animation elements are defined to begin or end relative to an animation that "has no effect", the other animation elements will begin and end as though there were no syntax errors. The presentation runtime may indicate an error, but need not halt presentation or animation of the document. 

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

Error handling semantics

The host language designer may impose stricter constraints upon the error handling semantics. That is, in the case of syntax errors, the host language may specify additional or stricter mechanisms to be used to indicate an error. An example would be to stop all processing of the document, or to halt all animation.

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

4. The SMIL 2.0 Content Control Modules

Editors

Dick Bulterman, (Dick.Bulterman@oratrix.com), Oratrix

Jeffrey Ayars (jeffa@real.com), RealNetworks

4.1 Introduction

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

• BasicContentControl, containing content selection elements and predefined system test attributes;
• CustomTestAttributes, containing author-defined custom test elements and attributes;
• PrefetchControl, containing presentation optimization elements and attributes; and
• SkipContentControl, containing attributes that support selective attribute evaluation.

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

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

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

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

4.2 The SMIL 2.0 BasicContentControl Module

4.2.1 SMIL 2.0 BasicContentControl Module Overview

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

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

Predefined System Test Attributes

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

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

• systemBitrate
• systemCaptions
• systemLanguage
• system-overdub-or-caption (note: this attribute has been deprecated in favor of systemCaptions or systemOverdubOrSubtitle)
• systemRequired
• systemScreenDepth
• systemScreenSize

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

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

• systemAudioDesc
• systemCPU
• systemComponent
• systemOperatingSystem
• systemOverdubOrSubtitle

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

The switch element

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

An example of the use of the switch is:

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

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

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

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

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

System Test Attribute In-Line Use

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

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

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

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

Examples of Switch and Test Attribute Use

1. Choosing between content with different total bitrates

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

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

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

2. Choosing between audio resources with different bitrates

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

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

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

3. Choosing between audio resources in different languages

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

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

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

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

4. Choosing between content written for different screens

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

    ...
    <par>
       <text .../>
       <switch>
          <par systemScreenSize="1280X1024" systemScreenDepth="16">
          ...
          </par>
          <par systemScreenSize="640X480" systemScreenDepth="32">
          ...
          </par> 
          <par systemScreenSize="640X480" systemScreenDepth="16"> 
          ... 
          </par> 
       </switch> 
    </par> 
    ...
   

5. Supporting multiple options via in-line use

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

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

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

6. Choosing the language of overdub and subtitle tracks

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

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

4.2.2 Elements and Attributes

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

The switch element

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

Predefined Test Attributes

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

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

For this version of SMIL elements with specified test attributes that evaluate to false, or elements within a switch that are not selected, are considered to be ignored and will behave as though they were not specified in the document. Any references to these elements will be as if the elements were not in the document. In particular, any ID references to the element will act as if there was no element with that ID. Languages that integrate this module must specify any additional behavior related to these ignored elements. In the SMIL 2.0 Language profile, timing attributes that reference invalid IDs are treated as being indefinite.

Authors should be aware that this model for handling ignored elements may be revised in a future version of SMIL, and the related semantics may well change. These changes should not affect implementations that only support parse-time (or equivalent) evaluation of test attributes and/or the switch element. However, the semantics of dynamic re-evaluation (i.e. re-evaluation during document presentation) of test attributes and/or switch elements are not defined in this version of SMIL; this will be addressed in a future version.

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

4.2.3 Integration Requirements for the BasicContentControl Module

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

4.2.4 Document Type Definition (DTD) for the BasicContentControl Module

See the full DTD for the SMIL Content Control modules.

4.3 The SMIL 2.0 CustomTestAttributes Module

4.3.1 SMIL 2.0 CustomTestAttributes Module Overview

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

As with system test attributes, custom test attributes can be used within timing structure and media object elements; if they evaluate to true, the containing element is activated and if they evaluate to false, the containing element is ignored. In this version of SMIL, an ignored element will be treated as if it were not part of the source document. As a result, any element referencing the ID of the ignored node will, in effect, reference an invalid ID. Languages that integrate this module must specify any additional behavior related to these ignored elements.

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

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

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

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

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

Example Use

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

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

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

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

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

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

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

Rules for Setting Values

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

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

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

4.3.2 Elements and Attributes

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

The customAttributes element

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

The customTest element

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

The customTest attribute

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

4.3.3 Integration Requirements for the CustomTestAttribute Module

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

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

4.3.4 Document Type Definition (DTD) for the CustomTestAttribute Module

See the full DTD for the SMIL Content Control modules.

4.4 The SMIL 2.0 PrefetchControl Module

4.4.1 SMIL 2.0 PrefetchControl Module Overview

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

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

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

Examples

1. Prefetch an image so it can be displayed immediately after a video ends:

    <smil> 
      <body> 
        <seq>
          <par>
            <prefetch id="endimage"
               src="http://www.example.org/logo.gif"/>
            <text id="interlude"
               src="http://www.example.org/pleasewait.html" fill="freeze"/>
          </par>
          <video id="main-event" src="rtsp://www.example.org/video.mpg"/> 
          <image src="http://www.example.org/logo.gif" dur="5s"/>  
       </seq> 
      </body> 
    </smil> 
   

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

2. Prefetch the images for a button so that rollover occurs quickly for the end user:

    <html>
    <body>
        <prefetch id="upimage" src="http://www.example.org/up.gif"/>
        <prefetch id="downimage" src="http://www.example.org/down.gif"/>
        ....
        <!-- script will change the graphic on rollover -->
        <img src="http://www.example.org/up.gif"/>
      </body>
    </html>
   

4.4.2 Elements and Attributes

The prefetch element

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

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

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

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

4.4.3 Integration Requirements for the PrefetchControl Module

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

4.4.4 Document Type Definition (DTD) for the PrefetchControl Module

See the full DTD for the SMIL Content Control modules.

4.5 The SMIL 2.0 SkipContentControl Module

4.5.1 SMIL 2.0 SkipContentControl Module Overview

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

4.5.2 Elements and Attributes

Element definition

The SkipContentControl module does not contain any element definitions.

The skip-content attribute

4.5.3 Integration Requirements for the SkipContentControl Module

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

5. The SMIL 2.0 Layout Modules

Editors

Aaron Cohen (aaron.m.cohen@intel.com), Intel

Dick Bulterman (Dick.Bulterman@oratrix.com), Oratrix

Erik Hodge (ehodge@real.com), RealNetworks

5.1 Introduction

This section is informative.

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

5.2  Overview of the SMIL 2.0 BasicLayout Module

This section is informative.

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

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

Each region has a set of CSS2 compatible properties such as top, left, height, width, and backgroundColor. These properties can be declared using a syntax defined by the type attribute of the layout element. In this way, media layout can be described using the either SMIL basic layout syntax or CSS2 syntax (note that these are not functionally identical). Other layout types are possible as well.

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 BasicLayout module:

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

To create the same region using CSS2 syntax:

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

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

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

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

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

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

5.3 SMIL 2.0 BasicLayout Module Syntax and Semantics

This section is normative.

5.3.1 Elements and Attributes

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

The layout element

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

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

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

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

Element content

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

region

root-layout

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

The region element

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

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

<smil xmlns="http://www.w3.org/2001/SMIL20/WD/">
  <head>
    <layout>
        <root-layout width="320" height="480" />    
              <region id="a" top="5" />
    </layout>
  </head>
  <body>
    <text region="a" src="text.html" dur="10s" />
  </body>
</smil>

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

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

Conflicts between the region size and position attributes width, height, bottom, left, right, and top are resolved according to the rules for placeholder elements as detailed below. The default values of region position and size attributes is specified as auto. This attribute value has the same meaning here that it does in [CSS2], when there is no distinction drawn between replaced and non-replaced element.

A placeholder element is one which has no intrinsic width or height, but does have a bounding-box which has a width and height. SMIL BasicLayout regions are placeholder elements. Placeholder elements are clipped to the bounding box.

The governing equation for the horizontal dimension is: 

bbw (bounding-box-width) = left + width + right 

Given that each of these three parameters can have either a value of "auto" or a defined value not "auto", then there are 8 possibilities:

The vertical attributes height, bottom, and top are resolved similarly. The governing equation for the vertical dimension is: 

bbh (bounding-box-height) = top + height + bottom 

Given that each of these three parameters can have either a value of "auto" or a defined value not "auto", then there are 8 possibilities:

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 user agent (e.g. because the enclosing layout element was skipped due to an unrecognized type or a test attribute evaluated to false).

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

Element content

The root-layout element is an empty element.

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

The region attribute

The region attribute is applied to an element in order to specify which rendering region is assigned to the element. The attribute refers to the abstract rendering region (either visual or acoustic) defined within the layout section of the document. The referenced abstract rendering region is determined by applying the following rules, in order:

1. Find all elements in the layout section with regionName attributes that are assigned the same value as that of the region attribute.
2. Remove the elements from this collection that are removed from the rendered presentation due to the processing of switch elements and test attributes.
3. If any elements remain, the media should be rendered in all of the referred to regions. If the application cannot render the media simultaneously in multiple regions, then the media should be rendered using the lexically first remaining element.
4. If no elements have a regionName attribute that is assigned the same value as that of the region attribute, then select the element in the layout section whose unique identifier is the value of the region attribute.

If this process selects no rendering surface defined in the layout section, the values of the formatting properties of this element are defined by the default layout values, which is described in the section on integration requirements for this module.

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

5.3.2 SMIL BasicLayout Module Details

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

Integration Requirements

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

A profile integrating the SMIL 2.0 BasicLayout module must provide a means of declaring an XML identifier on region elements if the profile intends on referring to region elements by XML identifier. This value is used as the argument value to the region attribute. This is not required if the profile will only use the regionName method of referring to a region element.

A profile integrating the SMIL 2.0 BasicLayout module must specify which elements have a region attribute and any inheritance of the attribute.

If not otherwise defined by the profile, the default values of the layout attributes listed in the SMIL 2.0 layout modules will apply to presented elements not otherwise specifying layout semantics.

An element that does not refer to a valid region element will display in the default region. If not otherwise specified by the profile, the default region is defined as filling and aligned to the upper-left corner of the presentation window. This default region takes on default values for all other region attributes.  

5.3.3 Document Type Definition (DTD) for the BasicLayout Module

See the full DTD for the SMIL Layout modules.

5.4 Overview of the SMIL 2.0 AudioLayout Module

This section is informative.

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

5.4.1 Integration Requirements for the AudioLayout Module

This section is normative.

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

5.4.2 Audio Volume Control

This section is normative.

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

5.5 SMIL 2.0 AudioLayout Module Syntax and Semantics

This section is normative.

5.5.1 Elements and Attributes

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

The region element

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

5.6 Overview of the SMIL 2.0 MultiWindowLayout Module

This section is informative.

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

5.6.1 Integration Requirements for the MultiWindowLayout Module

This section is normative.

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

5.6.2 Multiple Top-Level Window Support

This section is normative.

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

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

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

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

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

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

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

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

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

5.7 SMIL 2.0 MultiWindowLayout Module Syntax and Semantics

This section is normative.

5.7.1 Elements and Attributes

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

The topLayout element

The topLayout 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 topLayout elements may appear within a single layout element, each declaring an independent top-level window.

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

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

Element content

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

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

The layout element

Element content

The layout element defined in the SMIL BasicLayout module is extended with the addition that the topLayout 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

topLayout

5.7.2 MultiWindowLayout Module Events

This module includes two events that may be included in the integrating language profile.

topLayoutOpenEvent

Raised when a topLayout window opens. This event is delivered to the associated topLayout element. If a topLayout closes and then reopens when additional media becomes active in any of its regions, this event will be raised again, and will be raised every subsequent time it reopens.

topLayoutCloseEvent

Raised when a topLayout closes for any reason.  This event is delivered to the associated topLayout element. If a topLayout reopens when additional media becomes active in any of its regions, this event will be raised again if and when the topLayout closes again, and will be raised every subsequent time it closes.

Integration Requirements for the MultiWindowLayout Module Events

The language profile must specify the declarative names for binding these events, as well as the bubbling behavior of the events.

5.7.3 Document Type Definition (DTD) for the MultiWindowLayout Module

See the full DTD for the SMIL Layout modules.

5.8 Overview of the SMIL 2.0 HierarchicalLayout Module

This section is informative.

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

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

 This module:

• extends the definition of the region element to allow for the specification of hierarchical regions;
• introduces a new layout element, regPoint, for controlling relative placement with an associated region (the registration element facility);
• includes additional attributes, regPoint and regAlign, that specify how a media object's presentation can be aligned relative to the set of defined registration points (the registration alignment facility); and
• provides additional attributes, top, bottom, left, and right, that specify exact positioning of objects within a region (the so-called sub-region positioning facility);
• allows an object placed in a sub- region to set the sub- region's fit, z-index, and backgroundColor attributes.

5.8.1 Integration Requirements for the HierarchicalLayout Module

This section is normative.

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

5.9 New Features in the SMIL 2.0 HierarchicalLayout Module

This section is normative.

5.9.1 Hierarchical Region Layout

A new feature in this module is support for hierarchical layout. This allows for the declaration of regions nested inside other regions, much like regions are laid out inside the top level window declared by the topLayout 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>
        <topLayout width="640px" height="480px" />
                <region id="left" top="0%" left="0%"
                             width="50%" height="100%" />
                <region id="right" top="0%" left="50%"
                               width="50%" height="100%">
                        <region id="inset" top="25%" left="25%"
                                         width="50%" height="50%" />
                </region>
        </topLayout>
</layout>

The resulting layout looks like this:

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

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

For example:

<layout>
   <root-layout width="640px" height="480px" />
   <region id="whole" top="0px" left="0px" width="640px" 
                                height="480px" z-index="5"/>
   <region id="right" top="0px" left="320px" width="320px"
                                height="480px" z-index="4">
       <region id="inset" top="140px" left="80" width="160px" 
                                height="200px" z-index="6"/>
       <region id="inset2" top="140px" left="80" width="160px" 
                                height="200px" z-index="6"/>
       <region id="inset3" top="140px" left="80" width="160px" 
                                height="200px" z-index="7"/>
   </region>
</layout>
...
<par>
        <img id="A" region="whole" src="imageA.jpg" dur="10s"/>
        <img id="B" region="inset" src="imageB.jpg" dur="10s"/>
</par>
<par>
        <img id="D" region="inset2" src="imageD.jpg" begin="1s" dur="10s"/>
        <img id="C" region="inset" src="imageC.jpg" begin="0s" dur="10s"/>
</par>
<par>
        <img id="E" region="inset2" src="imageE.jpg" dur="10s"/>
        <img id="F" region="inset3" src="imageF.jpg" dur="10s"/>
</par>

1. In the first "par", image "A" and image "B" begin at the same time. Image A will obscure image "B", even though the z-index of "inset is greater than that of "whole". This is because the z-index of "right", which is the region containing "inset" is less than that of "whole". 
2. In the second "par", images "C" and "D" are rendered into regions occupying the same area of the rendering surface. Image "C" will be shown for one second and then obscured by Image "D", since "D" begins after image "C". Note that lexical order is irrelevant here. 
3. In the third "par", the z-index of region "inset" is considered when computing stacking between siblings, and therefore image "F" will be shown, but image "E" will be obscured for the entire 10 seconds that they are both active.

5.9.2 Sub-Region Layout

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

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

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

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

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

Each placement attribute defines a new, temporary child 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 of region "d", and extends to the right and bottom edges of the region "d". 

All other placement operations, such as the fit attribute, now operate on the sub-region. For example, the following document fragment describes a region and a media object reference that make use of sub-region positioning:

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

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

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

The use of sub-region placement is intended as a light-weight alternative to defining a large number of single-use regions. Often, the dimensions used for the sub-region will match the dimensions of the media object being placed, but in all cases the values of the fit attribute will govern rendering of the object in the sub-region. The other attributes on the media element that would have been applied to a referenced region are applied to the sub-region instead. Note that the default values for the sub-region attributes are all 'auto', resulting that, by default, a sub-region is created having the same size and position as the parent region.

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

5.9.3 Media Object fit, z-index, and backgroundColor

The SMIL 2.0 HierarchicalLayout module includes the ability to use the fit, z-index, and backgroundColor attributes on objects displayed in a sub-region in order to declare different behavior from that on the region element.

5.9.4 Registration Points

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

5.10 SMIL 2.0 HierarchicalLayout Syntax and Semantics

This section is normative.

5.10.1 Elements and attributes

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

The layout element

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

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

Element 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

topLayout

regPoint

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

The region element

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

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

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

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

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

Element content

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

The regPoint element

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

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

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

If the registration point functionality is used on a media object that also uses sub-region positioning, the registration point applies to the subregion.

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

fill fit value:

This depends on the value of the regAlign attribute. (Note: in all cases, the media must maintain proper alignment over the regPoint):

topLeft regAlign value:

Scale the object's height and width independently so that the content just touches the bottom and right edges of the box.

topMid regAlign value:

Scale the object's height and width independently so that the content just touches the bottom edge of the box, and the nearest (to the regPoint) of the left or right edges of the box.

topRight regAlign value:

Scale the object's height and width independently so that the content just touches the bottom and left edges of the box.

midLeft regAlign value:

Scale the object's height and width independently so that the content just touches the nearest (to the regPoint) of the top or bottom edges of the box, and touches the right edge of the box.

center regAlign value:

Scale the object's height and width independently so that the content just touches the nearest (to the regPoint) of the top or bottom edges of the box, and touches the nearest (to the regPoint) of the left or right edges of the box.

midRight regAlign value:

Scale the object's height and width independently so that the content just touches the nearest (to the regPoint) of the top or bottom edges of the box, and touches the left edge of the box.

bottomLeft regAlign value:

Scale the object's height and width independently so that the content just touches the top and right edges of the box.

bottomMid regAlign value:

Scale the object's height and width independently so that the content just touches the top edge of the box, and the nearest (to the regPoint) of the left or right edges of the box.

bottomRight regAlign value:

Scale the object's height and width independently so that the content just touches the top and left edges of the box.

hidden fit value:

Align the media over the given regPoint per the regAlign attribute. If the media so positioned extends past the bounds of the region, clip the excess media. If the media so positioned doesn't meet the bounds of the region, fill the remaining space with the background color of the region.

meet fit value:

This depends on the value of the regAlign attribute. Any part of the region that is not covered by the media is then filled with the region's background color. (Note: in all cases, the media must maintain proper alignment over the regPoint):

topLeft regAlign value:

Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the right or bottom edge of the box while none of the content is clipped.

topMid regAlign value:

Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches at least one of the left, right, or bottom edges while none of the content is clipped.

topRight regAlign value:

Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the left or bottom edge of the box while none of the content is clipped.

midLeft regAlign value:

Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches at least one of the top, right, or bottom edges while none of the content is clipped.

center regAlign value:

Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches at least one of the top, left, right, or bottom edges while none of the content is clipped.

midRight regAlign value:

Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches at least one of the top, left, or bottom edges while none of the content is clipped.

bottomLeft regAlign value:

Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the top or right edge of the box while none of the content is clipped.

bottomMid regAlign value:

Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches at least one of the top, left, or right edges while none of the content is clipped.

bottomRight regAlign value:

Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the top or left edge of the box while none of the content is clipped.

scroll fit value:

Align the media over the given regPoint per the regAlign attribute. If any part of the media extends beyond the bounds of the region, a scrolling mechanism should be invoked that allows viewing of the media that is clipped beyond the bounds of the region.

slice fit value:

This depends on the value of the regAlign attribute. (Note: in all cases, the media must maintain proper alignment over the regPoint):

topLeft regAlign value:

Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the right or bottom edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped.

topMid regAlign value:

Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the left, right, or bottom edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped. Clipping will occur on up to two sides of the region.

topRight regAlign value:

Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the left or bottom edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped.

midLeft regAlign value:

Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the top, right, or bottom edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped. Clipping will occur on up to two sides of the region.

centerregAlign value:

Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the top, left, right, or bottom edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped. Clipping will occur on up to three sides of the region.

midRight regAlign value:

Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the top, left, or bottom edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped. Clipping will occur on up to two sides of the region.

bottomLeft regAlign value:

Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the top or right edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped.

bottomMidregAlign value:

Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the top, left, or right edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped. Clipping will occur on up to two sides of the region.

bottomRight regAlign value:

Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the top or left edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped.

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

Element content

None.

5.10.2 SMIL HierarchicalLayout Positioning and Presentation Attributes

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

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

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

If the fit attribute and alignment attributes regPoint and regAlign are relevant to the placement of a particular media object, the interaction is the same as described in the definition of regPoint. If sub-region positioning attributes are used on a media object along with fit or the alignment attributes regPoint and regAlign, these attributes apply to the sub-region. In this case the fit setting on the referenced region element does not apply to the sub-region.

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

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

Media specific background color

backgroundColor

This attribute allows specifying the background color that will be used when a media element is being shown in a sub-region. The range of legal values are the same as the backgroundColor attribute on the region element. The default value for this attribute is transparent.

Sub-region Positioning Attributes

top

This value uniquely identifies the position or the distance (using CSS2 pixel or non-negative percentage values) of the top edge of the sub-region relative to the top of the region. The default value of top is auto.

bottom

This value uniquely identifies the position or the distance (using CSS2 pixel or non-negative percentage values) of the bottom edge of the sub-region relative to the bottom of the region. The default value of bottom is auto.

height

This value uniquely identifies the position or the distance (using CSS2 pixel or non-negative percentage values) of the bottom edge of the sub-region relative to the top side of the region. The default value of height is auto.

left

This value uniquely identifies the position or the distance (using CSS2 pixel or non-negative percentage values) of the left edge of the sub-region relative to the left of the region. The default value of left is auto.

right

This value uniquely identifies the position or the distance (using CSS2 pixel or non-negative percentage values) of the right edge of the sub-region relative to the right side of the region. The default value of right is auto.

width

This value uniquely identifies the position or the distance (using CSS2 pixel or non-negative percentage values) of the right edge of the sub-region relative to the left side of the region. The default value of width is auto.

Conflicts between the region size attributes  bottom, height, left, right, top, and width are resolved according to the rules for placeholder elements described in the section on the region element .

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

Registration point attributes

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

regPoint

This value uniquely identifies the registration point to be used for the placement of the object. The value should be an XML identifier of a regPoint element.

The following values are predefined registration points that do not have to be declared as regPoint elements before they are used:

topLeft

Same as using top="0%" left="0%" on the element without the regPoint attribute.

topMid

Same as using top="0%" left="50%" on the element without the regPoint attribute.

topRight

Same as using top="0%" left="100%" on the element without the regPoint attribute.

midLeft

Same as using top="50%" left="0%" on the element without the regPoint attribute.

center

Same as using top="50%" left="50%" on the element without the regPoint attribute.

midRight

Same as using top="50%" left="100%" on the element without the regPoint attribute.

bottomLeft

Same as using top="100%" left="0%" on the element without the regPoint attribute.

bottomMid

Same as using top="100%" left="50%" on the element without the regPoint attribute.

bottomRight

Same as using top="100%" left="100%" on the element without the regPoint attribute.

Note that the predefined registration points have the same meaning relative to the region as the regAlign attribute values have relative to the media. If no value is given, the default registration point of topLeft (top="0%", left="0%") is assumed, that is, the media is aligned with the top-left of the region.

regAlign

This value uniquely identifies the registration algorithm to be used for the regPoint defined for the object, and overrides any regAlign attribute on the referenced regPoint element. Permissible values are those defined under the regAlign attribute for the regPoint element. If used without an explicit regPoint attribute, the value is relative to the top left point of the region used by the associated media object.

Region fit override

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

fit

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

Region z-index override

The z-index attribute is used on an element in conjunction with the sub-region positioning attributes to control the display of the element on the rendering surface. A value of the z-index attribute given on the element will set the z-index for the sub-region within the context of the parent region stacking order.

z-index

This attribute specifies the stacking order behavior for the sub-region. It takes the same values as the z-index attribute on the region element, and has the same semantics with the exception that the declared z-index only applies to the sub-region declared by the media element, and not to other elements which may use the same parent region.

6. The SMIL 2.0 Linking Modules

Editors

Lloyd Rutledge (Lloyd.Rutledge@cwi.nl), (CWI)

Aaron Cohen (aaron.m.cohen@intel.com), (Intel)

6.1 Introduction

The SMIL 2.0 Linking Modules define the SMIL 2.0 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, such as temporal events. SMIL 2.0 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 2.0 Linking Modules are named LinkingAttributes, BasicLinking and ObjectLinking. The LinkingAttributes module includes a set of attributes used to provide SMIL linking semantics to linking elements. The BasicLinking module includes the SMIL 2.0 linking elements themselves. The ObjectLinking module includes additional optional linking features that a language profile may wish to include. Note that the BasicLinking module explicitly includes the attributes from the LinkingAttributes module on its elements.

6.2 Relationship with Other XML Linking-related Formats

6.2.1 Relationship with 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 [URI] attribute value. The SMIL 2.0 specification allows but does not require that user agents be able to process XPointers in SMIL 2.0 URI attribute values.

6.2.2 Relationship with XLink

Where possible, SMIL linking constructs have the same element, attribute and value names as constructs from XLink [XLINK]. This makes it easier to learn to write linking in code in both formats: authors familiar with XLink can more quickly learn SMIL linking, and vice versa. It also makes it easier for SMIL code to be processed into and recognized as XLink code once XLink is released as a recommendation and when the appropriate transform mechanisms become available. However, the SMIL linking attributes are distinct from the XLink constructs and are part of a separate namespace. Using SMIL's modularization mechanism, these constructs are not in the XLink namespace but in the namespaces defined in the SMIL 2.0 specification.

6.2.3 Relationship with XML Base

SMIL profiles may use XML Base [XMLBase]. The SMIL 2.0 Language Profile, for example, includes support for XML Base. When XML Base is incorporated into a profile, XML Base declarations apply to the URI attribute values of SMIL used in that profile's documents. These attributes include the href attribute of the SMIL BasicLinking Module and the src attribute of the SMIL BasicMedia Module.

6.2.4 Relationship with XHTML

The elements names, attributes names and attribute values of SMIL linking constructs are, where possible, the same as constructs in XHTML [XHTML11] with corresponding linking behavior. This facilitates learning and writing in both languages and avoids confusion. It may also facilitate the processibility of both language's linking constructs as XLink once the format is released. The linking constructs in SMIL, however, fall under the namespaces defined in SMIL 2.0, and not under any XHTML-related namespace.

6.3 Linking into SMIL 2.0 Documents

The SMIL 2.0 Linking Modules support 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 2.0 supports locators as currently used in HTML (that is, it uses locators of the form "http://www.example.org/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 fragment identifiers enable authors to encode links to a SMIL 2.0 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 2.0 Timing and Synchronization Modules 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 2.0 Timing and Synchronization Modules.

6.3.1 Handling of Links in Embedded Documents

Due to its integrating nature, the presentation of a SMIL 2.0 document may involve other (non-SMIL) applications or plug-ins. For example, a SMIL 2.0 user agent may use an HTML plug-in to display an embedded HTML page. Vice versa, an HTML user agent may use a SMIL plug-in to display a SMIL 2.0 document embedded in an HTML page. Note that this is only one of the supported methods of integrating SMIL 2.0 and HTML. Another alternative is to use the merged language approach. See the SMIL 2.0 Modules 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 user agent and the plug-in, SMIL 2.0 implementations may choose not to comply with this recommendation.

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

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

6.3.2 Error Handling

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

When a link into a SMIL 2.0 document contains a fragment identifier which identifies an element that is the content of a switch element, SMIL 2.0 software should interpret this link as going to the outermost ancestor switch element instead. In other words, the link should be considered as accessing the switch ancestor element that is not itself contained within a switch.

6.4 SMIL 2.0 LinkingAttributes Module

The SMIL 2.0 LinkingAttribues module defines several attributes that a language profile can include on linking elements to add SMIL linking semantics to those elements. The elements in the BasicLinking'>BasicLinking Module explicitly include these attributes. These attributes can be applied to linking elements from other namespaces if allowed by the language profile.