This section is informative.

Authors are encouraged to use meaningful synonyms (animation, audio, img,video, text or textstream) when referencing external media objects. This isin order to increase the readability of the SMIL document. Some SMILimplementations may require the use of an element type that matches theinformation type of the object. When in doubt about the group of a mediaobject, authors should use the generic "ref" element.

The animation element defined here should not be confused with theelements defined in the SMIL 3.0AnimationModule. The animation element defined in this module is used to includean external animation object file (such as a vector graphics animation) byreference. This is in contrast to the elements defined in the Animationmodule, which provide an in-line syntax for the animation of attributes andproperties of other elements.

SMIL 3.0 also supports thesmilText element for defining in-linetimed text content. This functionality is described in thesmilText Modules specification.

Languages implementing the SMIL BasicMedia Module must define whichattributes may be attached to media object elements. In all languagesimplementing the SMIL BasicMedia module, media object elements may have thefollowing attributes:

src

The value of the src attribute is the IRI[IRI] of the media element, used for locating and fetching the associated media.

The attribute supports fragment identifiers and the '#' connector in the IRI value. The fragment part is an id value that identifies one of the elements within the referenced media item. With this construct, SMIL 3.0 supports locators as currently used in HTML (that is, it uses locators of the formhttp://www.example.org/some/path#anchor1), with the difference that the values are of unique identifiers and not the values of "name" attributes. Generally speaking, this type of addressing implies that the target media is of a structured type that supports the concept of id, such as HTML or XML-based languages.

Note that this attribute is not required. A media object with nosrc attribute has an intrinsic duration of zero, and participates in timing just as any other media element. No media will be fetched by the SMIL implementation for a media element without asrc attribute.

type

Content type of the media object referenced by thesrc attribute. The usage of this attribute depends on the protocol of thesrc attribute.

RTSP[RTSP]

Thetype attribute is used for purposes of content selection and when the type of the referenced media is not otherwise available. It may be overridden by the contents of the RTSP DESCRIBE response or by the static RTP payload number.

HTTP[HTTP]

Thetype attribute is used as an alternative method of content selection and when the type of the referenced media is not otherwise available. It may override the contents of the "Content-type" field in an HTTP exchange only if a user has allowed such overrides, as specified in the TAG Finding Authoritative Metadata[AM]. The nominal precedence order for type resolution is: via the HTTP content-type field, via the type attribute, and then by using other clues (such as file inspection or use of the file extension).

FTP[FTP] and local file playback IRI[URI]

Thetype attribute value takes precedence over other possible sources of the media type (for instance, the file extension).

When the content represented by a URL is available in many data formats, implementations MAY use thetype value to influence which of the multiple formats is used. For instance, on a server implementing HTTP content negotiation, the client may use thetype attribute to order the preferences in the negotiation. Thetype attribute is not intended for use in media sub-stream selection.

For protocols not enumerated in this specification, implementations should use the following rules: When the media is encapsulated in a media file and delivered intact to the SMIL user agent via a protocol designed for delivery as a complete file, the media type as provided by this protocol should take precedence over thetype attribute value. For protocols which deliver the media in a media-aware fashion, such as those delivering media in a manner using or dependent upon the specific type of media, the application of the type attribute is not defined by this specification.

name

(CDATA) This attribute defines the name of a run-time parameter, assumed to be known by the inserted object. Whether the property name is case-sensitive depends on the specific object implementation.

value

(CDATA) This attribute specifies the value of a run-time parameter specified byname. Property values have no meaning to SMIL; their meaning is determined by the object in question.

valuetype

["data"|"ref"|"object"] This attribute specifies the type of thevalue attribute. Possible values:

• data This is default value for the attribute. It means that the value specified byvalue will be evaluated and passed to the object's implementation as a string.
• ref The value specified byvalue is a IRI[IRI]that designates a resource where run-time values are stored. This allows support tools to identify URIs given as parameters. The IRI must be passed to the objectas is, i.e., unresolved.
• object The value specified byvalue is an identifier that refers to a media object declaration in the same document. The identifier must be the value of theid attribute set for the declared media object element.

type

This attribute specifies the content type of the resource designated by thevalue attributeonly in the case wherevaluetype is set to "ref". This attribute thus specifies for the user agent, the type of values that will be found at the IRI designated byvalue. See6.7 Content Type in[HTML4] for more information.

This section is informative.

<ref src="http://www.example.com/herbert.face">  <param name="mood" value="surly" valuetype="data"/>  <param name="accessories" value="baseball-cap,nose-ring" valuetype="data"/></ref>

Element attributes

This element does not define any new attributes. Profiles integrating thiselement must specify an attribute of type ID[XML11] by which the paramgroup is referenced in a media object reference. For SMIL 3.0, the xml:idattribute will typically be used.

This section is informative.

This section contains several fragments that illustrate uses of theparamGroup element.

In the following fragment, a paramGroup is created to define parametersthat are passed to several different media objects:

<smil ... >  <head>    ...    <paramGroup xml:id="clown">       <param name="mood" value="upBeat" valuetype="data"/>       <param name="accessories" value="flowers,dunceCap"/>    </paramGroup>    ...  </head>  <body>    ...    <ref src="http://www.example.com/andy.face" paramGroup="clown"/>    ...    <ref src="http://www.example.com/sally.face" paramGroup="clown"/>    ...  </body></smil>

In the following example, a media object provides an additional paramvalue:

<smil ... >  <head>    ...    <paramGroup xml:id="clown">       <param name="mood" value="upBeat" valuetype="data"/>       <param name="accessories" value="flowers,dunceCap"/>    </paramGroup>    ...  </head>  <body>    ...    <ref src="http://www.example.com/andy.face" paramGroup="clown">      <param name="gender" value="male"/>    </ref>    ...  </body></smil>

In this final example, a media object provides a duplicate param value.The behavior in this case depends on the media renderer; all param values arepassed to the renderer in the lexical order of the SMIL source file. It isexpected that the lexically last value for any parameter sent to the rendererbe used, if possible.

<smil ... >  <head>    ...    <paramGroup xml:id="clown">       <param name="mood" value="upBeat" valuetype="data"/>       <param name="accessories" value="flowers,dunceCap"/>    </paramGroup>    ...  </head>  <body>    ...    <ref src="http://www.example.com/andy.face" paramGroup="clown">      <param name="gender" value="male"/>      <param name="mood" value="depressed" valuetype="data"/>    </ref>    ...  </body></smil>

paramGroup

Used to specify the name of aparamGroup that was defined in the documenthead. The value is a single IDREF[XML11] that refers to the ID[XML11] of aparamGroup element. If the namedparamGroup does not exist, this attribute is ignored. If this attribute is defined on a SMIL layout region definition, it specifies a default value for all content displayed within that region.

erase

Controls the behavior of the media object after the effects of any timing are complete. For example, when SMIL Timing is applied to a media element, erase controls the display of the media when the active duration of the element and when the freeze period defined by thefill attribute is complete (seeSMIL Timing and Synchronization module). If this attribute is defined on a SMIL layout region definition, it specifies a default value for all content displayed within that region.

Values:

whenDone (default)

When this is specified (or implied) the media removal occurs at the end of any applied timing.

never

When this value is specified, the last state of the media is kept displayed until the display area is reused (or if the display area is already being used by another media object). Any profile that integrates this element must define what is meant by "display area" and further define the interaction. Intrinsic hyperlinks (e.g., Flash, HTML) and explicit hyperlinks (e.g.,area,a) stay active as long as the hyperlink is displayed. If timing is re-applied to an element, the effect of the erase=never is cleared. For example, when an element is restarted according to theSMIL Timing and Synchronization module, the element is cleared immediately before it restarts.

Example:

This section is informative.

<par>  <seq>    <par>      <img src="image1.jpg" region="foo1" fill="freeze" erase="never" .../>      <audio src="audio1.au"/>            </par>    <par>      <img src="image2.jpg" region="foo2" fill="freeze" erase="never" .../>      <audio src="audio2.au"/>            </par>     ...    <par>      <img src="imageN.jpg" region="fooN" fill="freeze" erase="never" .../>      <audio src="audioN.au"/>            </par>  </seq></par>

In this example, each image is successively displayed and remains displayed until the end of the presentation.

mediaRepeat

Used to strip the intrinsic repeat value of the underlying media object. The interpretation of this attribute is specific to the media type of the media object, and is only applicable to those media types for which there is a definition of a repeat value found in the media type format specification. Media type viewers used in SMIL implementations should expose an interface for controlling the repeat value of the media for this attribute to be applied. For all media types where there is an expectation of interoperability between SMIL implementations, there should be a formal specification of the exact repeat value to which the mediaRepeat attribute applies. If this attribute is defined on a SMIL layout region definition, it specifies a default value for all content displayed within that region.

Values:

strip

Strip the intrinsic repeat value of the media object.

preserve (default)

Leave the intrinsic repeat value of the media object intact.

As an example of how this would be used, many animated GIFs intrinsically repeat indefinitely. The application ofmediaRepeat= "strip" allows an author to remove the intrinsic repeat behavior of an animated GIF on a per-reference basis, causing the animation to display only once, regardless of the repeat value embedded in the GIF.

WhenmediaRepeat is used in conjunction with SMIL Timing Module attributes, this attribute is applied first, so that the repeat behavior can then be controlled with the SMIL Timing Module attributes such asrepeatCount andrepeatDur.

sensitivity

Used to provide author control over the sensitivity of media to user interface selection events, such as the SMIL 2.1 activateEvent, and hyperlink activation. If the media is sensitive at the event location, it captures the event, and will not pass the event through to underlying media objects. If not, it allows the event to be passed through to any media objects lower in the display hierarchy. If this attribute is defined on a SMIL layout region definition, it specifies a default value for all content displayed within that region.

Values:

opaque

The media is sensitive to user interface selection events over the entire area of the media. This is the default.

transparent

The media is not sensitive to user interface selection events over the entire area of the media. Any user interface selection events will be "passed through" to any underlying media.

percentage-value

The media sensitivity to user interface selection events is dependent upon the opacity of the media at the location of the event (the alpha channel value). If rendered media supports an alpha channel and the opacity of the media is less than the given percentage value at the event location, the behavior will betransparentas specified above. Otherwise the behavior will be asopaque. Valid values are non-negativeCSS2 percentage values.

chromaKey

This attribute defines the color to be used for chroma key opacity manipulation. It accepts a single CSS2 color value. If media objects or implementations cannot support manipulation of the chroma key value, this attribute is ignored. If this attribute is defined on a SMIL layout region definition, it specifies a default value for all content displayed within that region.

chromaKeyOpacity

This attribute defines the opacity of the chroma key value defined with thechromaKey attribute. It accepts a percentage value in the range 0-100% or a number in the range 0.0-1.0, with 100% or 1.0 meaning fully opaque. If a chroma key color is defined, the default value is0% (fully transparent). If no chroma key color is defined or if implementations cannot support manipulation of the media opacity value, this attribute is ignored. If this attribute is defined on a SMIL layout region definition, it specifies a default value for all content displayed within that region.

chromaKeyTolerance

This attribute defines a color value that specifies a tolerance value that is added and subtracted from the effective chroma key. If a chroma key color was defined, the default value of this attribute is#000000. If no chroma key color was defined or if implementations cannot support manipulation of the chroma key value, this attribute is ignored. If this attribute is defined on a SMIL layout region definition, it specifies a default value for all content displayed within that region.

mediaOpacity

This attribute defines the opacity of the media object. It accepts a percentage value in the range 0-100% or a number in the range 0.0-1.0, with 100% or 1.0 meaning fully opaque. If implementations cannot support manipulation of the media opacity value, this attribute is ignored. The default value of this attribute is100%. If this attribute is defined on a SMIL layout region definition, it specifies a default value for all content displayed within that region. The media opacity manipulation does not apply to a background color for a media object, if such a color is defined. The background color opacity is manipulated using themediaBackgroundOpacity attribute.

mediaBackgroundOpacity

This attribute defines the background color opacity of the media object for media objects that explicitly define a media background color. It accepts a percentage value in the range 0-100% or a number in the range 0.0-1.0, with 100% or 1.0 meaning fully opaque. If either media objects or implementations cannot support manipulation of the media background color opacity, this attribute is ignored. The default value of this attribute is100%. If this attribute is defined on a SMIL layout region definition, it specifies a default value for all media background opacity displayed within that region.

This section is informative.

The attributes in this module allow the opacity (that is, the degree towhich a media object is transparent) to be defined. Opacity may be controlledin several ways, depending on the type of media being used. For unstructuredmedia (that is, media that does not contain an explicitly-defined backgroundcolor), the chromaKey attribute may be used to identify a particular colorthat will serve as the background color for purposes of opacity manipulation.If a chromaKey is used, the chromaKeyOpacity attribute may specify the degreeof transparency desired. Since the color used to define a background may notbe exactly preserved within a media object, the chromaKeyTolerance attributeallows a tolerance range to be defined for the chroma key color.

Some media objects, such as RealText, smilText, GIF, PNG, and Flash,define an explicit background color. In these cases, the specification of theopacity of that color can be done using the mediaBackgroundOpacity attribute.In these cases, only the defined color is manipulated.

In addition to specifying the transparency level of a particularbackground color, SMIL also allows the specification of the transparencylevel of a total media object. This is accomplished using the mediaOpacityattribute.

Note that SMIL layout also defines thebackgroundOpacity attribute tocontrol the transparency of a layout region.

clipBegin(clip-begin)

The clipBegin attribute specifies the beginning of a sub-clip of a continuous media object as offset from the start of the media object. This offset is measured in normal media playback time from the beginning of the media.
Values in the clipBegin attribute have the following syntax:

Clip-value-MediaClipping ::= [ Metric "=" ] ( Clock-val | Smpte-val )Metric            ::= Smpte-type | "npt" Smpte-type        ::= "smpte" | "smpte-30-drop" | "smpte-25"Smpte-val         ::= Hours ":" Minutes ":" Seconds                       [ ":" Frames [ "." Subframes ]]Hours             ::= DIGIT+Minutes           ::= DIGIT DIGIT /* range from 00 to 59 */Seconds           ::= DIGIT DIGIT /* range from 00 to 59 */Frames            ::= DIGIT DIGIT /* smpte range = 00-29, smpte-30-drop range = 00-29, smpte-25 range = 00-24 */Subframes         ::= DIGIT DIGIT /* smpte range = 00-01, smpte-30-drop range = 00-01, smpte-25 range = 00-01 */DIGIT             ::= [0-9]

The value of this attribute consists of a metric specifier, followed by a time value whose syntax and semantics depend on the metric specifier. The following formats are allowed:

SMPTE Timestamp

SMPTE time codes[SMPTE] may be used for frame-level access accuracy. The metric specifier may have the following values:

smpte

smpte-30-drop

These values indicate the use of the "SMPTE 30 drop" format (approximately 29.97 frames per second), as defined in the SMPTE specification (also referred to as "NTSC drop frame"). The "frames" field in the time value may assume the values 0 through 29. The difference between 30 and 29.97 frames per second is handled by dropping the first two frame indices (values 00 and 01) of every minute, except every tenth minute.

smpte-25

The "frames" field in the time specification may assume the values 0 through 24. This corresponds to the PAL standard as noted in[SMPTE]

The time value has the format hours:minutes:seconds:frames.subframes. If the subframe value is zero, it may be omitted. Subframes are measured in one-hundredths of a frame.
Examples:
clipBegin="smpte=10:12:33"

This section is informative.

The introduction of subframe notation in SMIL 2.1 introduced an inconsistency with SMIL 1.0. As of this draft, SMIL 3.0 has deprecated the subframe notation.

Normal Play Time

Normal Play Time expresses time in terms of SMIL clock values. The metric specifier is "npt", and the syntax of the time value is identical to the syntax of SMIL clock values.
Examples:
clipBegin="npt=123.45s"
clipBegin="npt=12:05:35.3"

Marker

Not defined in this module. SeeclipBegin Media Marker attribute extension in the MediaClipMarkers module.

If no metric specifier is given, then a default of "npt=" is presumed.

When used in conjunction with the timing attributes from the SMIL Timing Module, this attribute is applied before any SMIL Timing Module attributes.

clipBegin may also be expressed asclip-begin for compatibility with SMIL 1.0. Software supporting the SMIL 2.1 Language Profile must be able to handle bothclipBegin andclip-begin, whereas software supporting only the SMIL MediaClipping module only needs to supportclipBegin. If an element contains both aclipBegin and aclip-begin attribute, thenclipBegin takes precedence overclip-begin.

Example:

This section is informative.

<audio src="radio.wav" clip-begin="5s" clipBegin="10s" />

The clip begins at second 10 of the audio, and not at second 5, since theclip-begin attribute is ignored. A strict SMIL 1.0 implementation will start the clip at second 5 of the audio, since the clipBegin attribute will not be recognized by that implementation. SeeChanges to SMIL 1.0 Media Object Attributes for more discussion on this topic.

clipEnd(clip-end)

The clipEnd attribute specifies the end of a sub-clip of a continuous media object as offset from the start of the media object. This offset is measured in normal media playback time from the beginning of the media. It uses the same attribute value syntax as the clipBegin attribute.
If the value of theclipEnd attribute exceeds the duration of the media object, the value is ignored, and the clip end is set equal to the effective end of the media object.clipEnd may also be expressed asclip-end for compatibility with SMIL 1.0. Software supporting the SMIL 2.1 Language Profile must be able to handle bothclipEnd andclip-end, whereas software supporting only the SMIL media object module only needs to supportclipEnd. If an element contains both aclipEnd and aclip-end attribute, thenclipEnd takes precedence overclip-end. When used in conjunction with the timing attributes from the SMIL Timing Module, this attribute is applied before any SMIL Timing Module attributes.

SeeChanges to SMIL 1.0 Media Object Attributes for more discussion on this topic.

clipBegin Media Marker attribute extension

Used to define a clip using named time points in a media object, rather than using clock values or SMPTE values. The metric specifier is "marker", and the marker value is a IRI (see[IRI]). The IRI is relative to thesrc attribute, rather than to the document root or the XML base of the SMIL document.

Clip-value-MediaClipMarkers ::= Clip-value-MediaClipping |                      "marker" "=" URI-reference   /* "URI-reference" is defined in[URI] */

Example: Assume that a recorded radio transmission consists of a sequence of songs, which are separated by announcements by a disk jockey. The audio format supports marked time points, and the begin of each song or announcement with number X is marked as songX or djX respectively. To extract the first song using the "marker" metric, the following audio media element may be used:

<audio clipBegin="marker=#song1" clipEnd="marker=#dj1" />

clipEnd Media Marker attribute extension

clipEnd media markers use the same attribute value syntax as theclipBegin media marker extension media marker attribute extension. For the complete description, seeclipBegin media marker extension.

color

The use and definition of this attribute are identical to the "background-color" property in the CSS2 specification.

alt

For user agents that cannot display a particular media object, this attribute specifies alternate text.alt may be displayed in addition to the media, or instead of media when the user has configured the user agent to not display the given media type.

It is strongly recommended that all media object elements have an "alt" attribute with a brief, meaningful description. Authoring tools should ensure that no element may be introduced into a SMIL document without this attribute.

The value of this attribute is a CDATA text string.

longdesc

This attribute specifies a IRI link ([IRI]) to a long description of a media object. This description should supplement the short description provided using the alt attribute or the abstract attribute. When the media object has associated hyperlinked content, this attribute should provide information about the hyperlinked content.

readIndex

This attribute specifies the position of the current element in the order in whichlongdesc,title andalt text are read aloud by assistive devices (such as screen readers) for the current document. User agents should ignore leading zeros. The default value is 0.

Elements that containalt,title orlongdesc attributes are read by the assistive technology according to the following rules:

• Those elements that assign a positive value to the readindex attribute are read out first. Navigation proceeds from the element with the lowest readindex value to the element with the highest value. Values need not be sequential nor must they begin with any particular value. Elements that have identical readindex values should be read out in the order they appear in the character stream of the document.
• Those elements that assign it a value of "0" are read out in the order they appear in the character stream of the document.
• Elements in a switch statement that have test-attributes which evaluate to "false" are not read out.

Example

This section is informative.

<par>  <video xml:id="carvideo" src="car.rm" region="videoregion" title="Car video"         alt="Illustration of relativistic time dilation and length               contraction."          longdesc="carvideodesc.html" readIndex="3"/>  <audio xml:id="caraudio" src="caraudio.rm" region="videoregion"          title="Car presentation voiceover" begin="bar.begin"/>  <animation xml:id="cardiagram" src="car.svg" region="animregion"          title="Diagram of the car" readIndex="2"/>  <img xml:id="scvad" src="scv.png" region="videoregion"          title="Advertisement for Sugar Coated Vegetables"         readIndex="1"/></par>

In this example, an assistive device that is presenting titles should present the "scvad" element title first (having the lowest readIndex value of "1"), followed by the "cardiagram" title, followed by the "carvideo" element title, and finally present the "caraudio" element title (having an implicit readIndex value of "0").

Note that not all examples in this specification use all media accessibility attributes because the purpose of the sample code is to illustrate specific language features.

abstract

A brief description of the content contained in the element. Unlikealt, this attribute is generally not displayed as alternate content to the media object. It is typically used as a description when table of contents information is generated from a SMIL presentation, and typically contains more information than would be advisable to put in analt attribute.

This attribute is deprecated in favor of using appropriate SMIL metadata markup in RDF. For example, this attribute maps well to the "description" attribute as defined by the Dublin Core Metadata Initiative[DC].

author

The name of the author of the content contained in the element.

The value of this attribute is a CDATA text string.

copyright

The copyright notice of the content contained in the element.

The value of this attribute is a CDATA text string.

title

Thetitle attribute as defined in the SMIL Structure module. It is strongly recommended that all media object elements have atitle attribute with a brief, meaningful description. Authoring tools should ensure that no element may be introduced into a SMIL document without this attribute.

xml:lang

Used to identify the natural or formal language for the element. For a complete description, seesection 2.12 Language Identification of[XML11].

xml:lang differs from thesystemLanguage test attribute in one important respect.xml:lang provides information about the content's language independent of what implementations do with the information, whereassystemLanguage is a test attribute with specific associated behavior (seesystemLanguage inSMIL Content Control Module for details)

This section is informative.

SMIL 3.0 also supports the use of themetadata element within theMetaInformation Module to supply additional oralternative forms of metainformation for any media object.

This section is informative.

The SMIL MediaPanZoom module integrates the functionality of the SVGviewBox attribute and adapts it for use within the SMIL media framework. TheSMILpanZoom attribute allows a SMILauthor to define a two-dimensional extent over the visible surface of a mediaobject and to subsequently project the contents within the panZoom area intoa SMIL presentation.

Most of SMIL's layout elements and attributes provide the ability todefine and manage a two-dimensional rendering space. This space is definedrelative to a root-layout (or topLayout) specification. All of the coordinateand size specifications are in terms of the coordinate space defined for thelayout root. In contrast, the panZoom attribute allows users to define anarea in terms of the coordinate space used by the media object that isassociated with the panZoom area. The panZoom area may be smaller, equal to,or larger than the related media object.

The following illustration shows three views of a 300x200 pixel image. Inthe left view, a panZoom area is shown that is the same size as the mediaobject; in the middle view, a panZoom area is defined that covers the middlepart of the image only; in the right view, a panZoom area is illustrated thatis positioned (in both dimensions) partially outside the media object. Notethat while this illustration shows the panZoom area projected onto an image,similar illustrations could be defined for videos or text objects, or anyother object that may be mapped to a particular media bounding box.

Once a portion of a media object's visible area is defined with a panZoomarea, the portion within the panZoom area is processed further as if itdefined the full native view of the media object. The content within thepanZoom area is projected into a region in a manner that is dependent on theregion element associated with thatobject, including any scaling dictated by thefit attribute or (if appropriate), sub-regionpositioning and alignment directives.

If the region and the panZoom area have the same aspect ratios, then thepanZoom area will, by default, fill the entire region. If the effective pixeldimensions of the region are larger than that of the panZoom area, the effectwill be an enlargement of the media content. If the effective pixeldimensions of the window are smaller than that of the panZoom area, theeffect will be a reduction in size of the media object. Other effects may beobtained by manipulating thefitattribute of the region.

If supported by the profile implementing this module, a dynamicpan-and-zoom effect may be obtained by applying standard SMIL animationprimitives to the dimensions of the panZoom area. A pan effect may beobtained by varying the X and Y positioning values, and a zoom effect may beobtained by changing the size dimensions of the panZoom area. Examples ofthese effects are given later in this module description. Given the nature ofindependently animating collections of attribute values, care should be takenwhen specifying animation behavior.

If a panZoom area extends past the viewable extents of a media object(such as in the rightmost illustration, above), then the effective contentsof these extended areas will be transparent.

Elementattributes

panZoom

This attribute specifies a rectangular area in media coordinates that defines the portion of a media object that is to be used within a SMIL presentation. The panZoom attribute defines an ordered list of four values, separated by a comma:

left

A value (using CSS2 pixel or percentage values) that defines the minimum X coordinate of a rectangle in media space that serves as the X origin of the panZoom area. If pixel notation is used, the 'px' suffix may be omitted. An effective value of '0px' represents the left edge of the media object.

top

A value (using CSS2 pixel or percentage values) that defines the minimum Y coordinate of a rectangle in media space that serves as the Y origin of the panZoom area. If pixel notation is used, the 'px' suffix may be omitted. A value of '0' represents the top edge of the media object.

width

A non-negative length value (using CSS2 pixel or non-negative percentage values) that defines the horizontal dimension of the panZoom area. If pixel notation is used, the 'px' suffix may be omitted. A negative value is an error. The default value of width is set to the intrinsic width of the associated media object.

height

A non-negative length value (using CSS2 pixel or non-negative percentage values) that defines the vertical dimension of the panZoom area. If pixel notation is used, the 'px' suffix may be omitted. A negative value is an error. The default value of set to the intrinsic height of the associated media object.

The default panZoom area behavior is to select the entire visual space of the media object; this is equivalent topanZoom="0, 0, 100%, 100%".

The panZoom area is processed on the media object before any other SMILlayout processing occurs. The actual visual rendering of the contentresulting from the processed panZoom area will be determined by, among otherfactors: the size of the target region, the application of sub-regionpositioning in that region (if supported by the profile), the value of thefit attribute on the region, and the effect of SMIL alignment attributes (ifsupported by the profile).

Elementattributes

panZoom

This attribute is identical in definition to thepanZoom attribute defined for the ref element in this section, with the exception that it defines a default panZoom area that is applied to all media rendered in the associated region. All other aspects of panZoom area processing are the same as with the ref element, except that the values defined for the panZoom area on a region may be overridden by a panZoom area specification on the ref element.

This section is informative.

Assume the following SMIL example:

<smil ...>  <head>  ...    <layout>      <root-layout height="200" width="300" backgroundColor="red" />      <region xml:id="I" top="0" left="0" height="200" width="300"  backgroundColor="blue" />    </layout>  </head>  <body>    <seq>       <ref xml:id="R1" src="table.jpg" panZoom="0,0,300,200" dur="5s" region="I" />      <ref xml:id="R2" src="table.jpg" panZoom="80,50,160,125" dur="5s" region="I" fit="meet"/>      <ref xml:id="R3" src="table.jpg" panZoom="80,50,160,125" dur="5s" region="I" fit="meetBest"/>      <ref xml:id="R4" src="table.jpg" panZoom="240,120,85,110" dur="5s" region="I" fit="meet"/>    </seq>  </body></smil>

In this example, a single region is defined that is used to display fourinstances of the same image. Each media reference within the sequence Scontains a different panZoom area definition, each of which will result inthe following behavior:

1. The media reference R1 defines a panZoom area that encompasses the entire media object space; the full image will be shown in region I, as is shown in the following image:
   
   Note that the origin of the image is aligned with the origin of the media object, at the top-left of the region.
2. The media reference R2 defines a panZoom area that encompasses the center portion of the media object space. The projection of the media into region I will result in a zoom into the source image, as is shown in the following image:
   
   

   Note that the origin of the sub-image defined by the panZoom area is placed at the origin of the top-left of the region. Note also that the value of the fit attribute determines that the image is scaled (while maintaining the aspect ratio), resulting in the zoom effect.

3. The media reference R3 defines a panZoom area that is the same as in reference R2; the difference in this example is that the value of the fit attribute does not permit enlargement of the source image into the region. As a result, the image is placed at top-left in an unscaled rendering:
   
   
4. The media reference R4 defines a panZoom area that extends beyond the boundaries of the media object. When it is projected into the region I with a fit value that scales the image with preserved aspect ratio, the entire extent of the panZoom area is scaled: the areas that extend beyond the image content are rendered as (scaled) transparent content:
   
   

All of the previous examples illustrate how a panZoom area operates on amedia object that contains a media-defined viewable extent. The panZoomattribute may also be applied to visual objects that do not have predefinedextents. Consider the following example, in which an unstructured text objectis placed in a region:

<smil ...>  <head>  ...    <layout>      <root-layout height="200" width="300" backgroundColor="red" />      <region xml:id="T" top="0" left="0" height="50" width="300"  backgroundColor="blue" />    </layout>  </head>  <body>    <seq>       <ref xml:id="R0" src="short_story.txt" panZoom="0,10,50,200" dur="10s" region="T" />    </seq>  </body></smil>

In this example, a single region is defined that is used to display aundimensioned text object. In SMIL 3.0, the text object would first berendered to an off-screen bitmap based on the default settings for the mediaobject (font, font size, font color) and then a panZoom area of the definedsize would be overlaid on this text representation. This facility isespecially useful when combined with SMIL Animation, as discussed in the nextexample.

The ability to define a panZoom area, when combined with SMIL animationprimitives, provides a simple mechanism for doing pan/zoom animations over avisual object. (These pan/zoom animations are often called 'Ken Burns'animations.) The following example illustrates how a pan window may bepositioned and moved over an image area:

<smil ...>  <head>  ...    <layout>      <root-layout height="200" width="300" backgroundColor="red" />      <region xml:id="B" top="0" left="0" height="50" width="75"  backgroundColor="blue" />    </layout>  </head>  <body>    <seq>       <ref xml:id="R0" src="table_233x150.jpg" panZoom="0,0,50,75" dur="20s" region="B" fit="meet" >         <animate attributeName="panZoom"                      values="25,20,50,75; 45,55,50,75; 140,40,50,75; 35,0,100,150; 0,0,100,150"                      dur="20s" />      </ref>      ...    </seq>  </body></smil>

In this example, an image with intrinsic size of 233x150 pixels isrendered into a region of size 50x75. An initial panZoom area is defined thatdisplays a 50x75 portion of that image, positioned in its top-left corner.During the following 20 seconds, the panZoom area is moved across the imageaccording to the behavior of the animate element; the panZoom area changesare scheduled at equal points across the animation timeline (in this case,every 5 seconds). During the final animation, the panZoom area is extended toimplement a zoom-out across the entire image. An illustration of therendering results is shown below: