previous   next   contents  

5. SMIL Layout Module

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

Table of contents

5.1 Introduction

This Section defines the SMIL layout module. This module contains elements and attributes allowing for positioning of media elements on the rendering surface (either visual or acoustic). Since these elements and attributes are defined in a module, designers of other markup languages can choose whether or not to include this functionality in their languages. Therefore, language designers incorporating other SMIL modules do not need to include the layout module if sufficient layout functionality is already present.

The major changes with respect to the layout elements and attributes in SMIL 1.0 [SMIL10] is the addition of support for:

Other changes are minor. SMIL 1.0 already provides for using alternative layout models, for example CSS [SMIL-CSS2], [CSS2], and these can provide much of the additional functionality desired over SMIL basic layout.

It is the intention of this version of the Layout Module to align SMIL Boston Layout with current CSS2 functionality. There are some conflicts in mapping CSS2 layout to a language, such as SMIL, where the layout hierarchy is not reflected in the XML structure of the SMIL document. This necessitated dropping desirable features that could not be directly supported by mapping CSS to SMIL such as: multiple z-ordering within hierarchical regions, the alignment of objects within regions, and object-specific placement offsets within regions. It is desired that a future version of W3C layout technology will add support for these features to the SMIL language. A future version of the Layout module may include proof-of-concept support for these features.

5.2 Brief overview of SMIL basic layout

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

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

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


    <layout>

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

    </layout>

   

To create the same region using CSS2 syntax:


    <layout type="text/css">

    [region="r"] { top: 15px; left: 20px; width: 100px; height:50px; }

    </layout>    

   

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


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

   

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


    <layout type="text/css">

    video, img { top:15px; left:20px; width:100px; height=50px; }

    </layout>  

   

Note that multiple layout models can be specified within a <switch> element, each with a different type. The first layout with a type supported by the implementation will be the one used.

5.3 Extensions to SMIL 1.0 Basic Layout

The extensions proposed for SMIL/Boston fall into two groups:

The characteristics of each extension group will be presented in this section.  The full syntax will be described in later sections.

5.3.1 Multiple Top-Level Window Support

In SMIL 1.0, each presentation was rendered into a root window of a specific size/shape. The root window contained regions 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.

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

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

In this example, two top-level windows are defined ("WinV" and "WinC"), and two regions are defined with one region assigned to WinV and the other to WinC. The definitions of the top-level windows and the contained regions use the new hierarchical layout functionality, as discussed in the next section.

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

All top level windows are opened as soon as the presentation is started. If a window is closed (by the user) while any of the elements displayed in that window are active, there is no effect on the timeline of those elements. However, a player may choose not to decode content as a performance improvement.

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

Note also that any one region may belong to at most one top-level (or root-level) window. Regions not declared as children of a <top-layout> element belong to the <root-layout> window. If no <root-layout> element has been declared, the region is assigned to a default window according to SMIL 1.0 layout semantics.

5.3.2 Hierarchical Region Layout

A new feature in this layout 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 <top-layout> 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 subregion "inset" that is centered within "right".

<layout>
	<top-layout width="640px" height="480px" />
	<region id="left" top="0px" left="0px" width="320px" height="480px" />
	<region id="right" top="0px" left="320px" width="320px" height="480px">
		<region id="inset" top="140px" left="80" width="160px" height="200px" />
	</region>
</layout>  

The resulting layout looks like this:

picture of layout

5.4 SMIL basic layout syntax and semantics

5.4.1 Elements and attributes

This section defines the elements and attributes that make up the SMIL basic layout module.

The <layout> element

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

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

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

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

Element attributes

id
This value uniquely identifies the layout element within a document. Its value is an XML identifier.
type
This attribute specifies which layout language is used in the layout element. If the player does not understand this language, it must skip the element and all of its content up until the next </layout> tag. The default value of the type attribute is "text/smil-basic-layout". This identifier value supports SMIL 1.0 layout semantics. To enable the multiple top-level window and hierarchical layout extensions in this specification, declare the value of this attribute to be "text/smil-extended-layout".

Element content

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

region
root-layout

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

region
root-layout
top-layout

If the type attribute of the <layout> element has another value, the element contains character data.

The <region> element

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

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


<smil>

  <head>

    <layout>

	<root-layout width="320" height="480" />    

      	<region id="a" top="5" />

    </layout>

  </head>

  <body>

    <text region="a" src="text.html" dur="10s" />

  </body>

</smil>

The position of a region, as specified by its "top" and "left" attributes, is always relative to the parent geometry, which is defined by the parent element. For <region> elements whose immediate parent is a layout element, the region position is defined relative to the root window declared in the sibling <root-layout> element. For <region> elements that are children of a <top-layout> element the region position is defined relative to the top level window declared in the parent <top-layout> element. 

For <region> elements whose immediate parent is another <region> element, the sub-region position is defined relative to the position of the region defined by the parent element. Note that this is only allowed for regions that are descendants of a <top-layout> element.

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

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

Element  attributes

The <region> element can have the following visual attributes:

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

The default value of "fill" is "hidden".

height
The use and definition of this attribute are identical to the "height" property in the CSS2 specification. Attribute values follow the same restrictions and rules as the values of the "bottom" attribute.
The default value of this attribute is 'auto'.
id
A region element is applied to a position-able element by setting the region attribute of the position-able element to the id value of the region. The value of this attribute must be a valid XML identifier.
The "id" attribute is required for <region> elements.
left
The use and definition of this attribute are identical to the "left" property in the CSS2 specification. 
Attribute values follow the same restrictions and rules as the values of the "bottom" attribute.
The default value of this attribute is 'auto'.
right
The use and definition of this attribute are identical to the "right" property in the CSS2 specification. 
Attribute values follow the same restrictions and rules as the values of the "bottom" attribute.
The default value of this attribute is 'auto'.
title
This attribute offers advisory information about the element for which it is set. Values of the title attribute may be rendered by user agents in a variety of ways. For instance, visual browsers frequently display the title as a "tool tip" (a short message that appears when the pointing device pauses over an object).
It  is strongly recommended that all <region> elements have a "title" attribute with a meaningful description. Authoring tools should ensure that no element can be introduced into a SMIL document without this attribute.
top
The use and definition of this attribute are identical to the "top" property in the CSS2 specification. 
Attribute values follow the same restrictions and rules as the values of the "bottom" attribute.
The default value of this attribute is 'auto'.
volume
Specifies the relative volume of an audio media element assigned to play within the given region. Valid values are any number between '0' and '100'. '0' represents the minimum audible volume level and 100 corresponds to the maximum comfortable level.
width
The use and definition of this attribute are identical to the "width" property in the CSS2 specification. 
Attribute values follow the same restrictions and rules as the values of the "bottom" attribute.
The default value of this attribute is 'auto'.
z-index
This attribute defines the level of the region within the parent region stacking context. Elements assigned to higher level regions are rendered in front of lower level regions within the same parent region. Child regions are always placed in front of their parent region. This results in a two stage sorting of region visibility: first by parent-child containment, and then between regions within the same parent by assigned z-order.
 
The use and definition of this attribute are identical to the "z-index" property in the CSS2 specification, with the following exception:
If two boxes generated by elements A and B within the same parent region have the same stack level, then:

The default value of "z-index" is zero. To maintain compatibility with the CSS2 specification, the z-index attribute must always be zero for regions declared within a <top-level> element. Regions declared as children of the <layout> element may set the z-index to any CSS2 valid value.

The <region> element can have the following auditory attributes:

azimuth
Specifies the direction that the audio media element assigned to the region appears to emanate from.
Position is described in terms of an angle within the range '-360deg' to '360deg'. The value '0deg' means directly ahead in the center of the sound stage. '90deg' is to the right, '180deg' behind, and '270deg' (or, equivalently and more conveniently, '-90deg') to the left. The following values are also supported:
left-side
Same as '270deg'.
far-left
Same as '300deg'.
left
Same as '320deg'.
center-left
Same as '340deg'.
center
Same as '0deg'.
center-right
Same as '20deg'.
right
Same as '40deg'.
far-right
Same as '60deg'.
right-side
Same as '90deg'.
elevation
Specifies the elevation that the audio media element assigned to the region appears to emanate from. Value is an angle, between '-90deg' and '90deg'. '0deg' means on the forward horizon, which loosely means level with the listener. '90deg' means directly overhead and '-90deg' means directly below.

Element content

If the <region> element is a descendant of a <top-level> element, it may contain other <region> elements as children. Otherwise, the <region> element is an empty element.

The <root-layout> element

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

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

Element attributes

The <root-layout> element can have the following attributes:

backgroundColor
Defined in backgroundColor under the <region> element.
background-color
Defined in background-color under the <region> element.
height
Sets the height of the root element. Only length values are allowed.
id
Defined in id under the <region> element.
title
Defined in title under the <region> element.
width
Sets the width of the root element. Only length values are allowed.

Element content

The <root-layout> element is an empty element.

This element supports the SMIL 1.0 syntax where the <root-layout> element is an empty sibling of the top level <region> elements. Hierarchical region layout is not supported on windows declared with the <root-layout> element. That is, <region> elements that are assigned to the  window declared by <root-layout> may not be nested.

The semantics of the <root-layout> element are as in SMIL 1.0: the attributes of the <root-layout> element determine the size of the top-level presentation window, and the declared sibling regions are arranged within this top level window.

The <top-layout> element

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

Element attributes

The <top-layout> element can have the following attributes:

backgroundColor
Defined in backgroundColor under the <region> element.
background-color
Defined in background-color under the <region> element.
height
Sets the height of the root element. Only length values are allowed.
id
Defined in id under the <region> element.
title
Defined in title under the <region> element.
width
Sets the width of the root element. Only length values are allowed.

Element content

The <top-layout> element may contain <region> elements, or be empty.

The <top-layout> element supports the SMIL extended layout facilities. Allowing multiple  <top-layout> elements within a single <layout> element supports multiple top level windows. Allowing the nesting of regions within a  <top-layout> element provides support for  hierarchical layout.

Each instance of a <top-layout> element determine the size of a separate top-level presentation window, and the descendant regions are arranged within this top level window.

The region attribute

The "region" attribute is applied to an element in order to specify which rendering region is assigned to the element. The attribute specifies the XML identifier of the abstract rendering region (either visual or acoustic) defined within the layout section of the document.  If no rendering surface with the given identifier is defined in the layout section, the values of the formatting properties of this element are defined by the default layout.

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

5.4.2 SMIL basic layout language details

SMIL basic layout 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.

Fixed property values

Editor: This should probably be moved to the language profile.

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

	

a           {display:block}

anchor      {display:block}

animate     {display:none}

animation   {display: block;

             position: absolute}

area        {display:block}

body        {display: block}

head        {display: none}

excl        {display: block}

img         {display: block;

             position: absolute}

layout      {display: none}  

meta        {display: none}

par         {display: block}

region      {display: none}

ref         {display: block;

             position: absolute}

root-layout {display: none}

seq         {display: block}

smil        {display: block}

switch      {display:block}

text        {display: block;

             position: absolute}

textstream  {display: block;

             position: absolute}

video       {display: block;

             position: absolute}

Any other XML language using SMIL basic layout will have to define similar fixed attributes for its elements. Note that as a result of these definitions, all absolutely positioned elements ( <animation>, <img>, <ref>, <text>, <textstream> and <video>) are contained within a single containing block defined by the content edge of the root element.

Default values

A profile integrating the SMIL basic layout module must define default values for all layout-related attributes of elements. These should be consistent with the initial values of the corresponding properties in CSS2.

5.5 Differences from SMIL 1.0 basic layout

This section lists the differences between this layout module and SMIL 1.0 basic layout.

5.6 Open Issues


previous   next   contents