previous   next   contents  

WD-smil-boston-19991115

5. The SMIL Layout Module

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

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 reuse the functionality in the SMIL layout module when they need to include media layout in their language. Conversely, language designers incorporating other SMIL modules do not need to include the layout module if other layout functionality is already present.

Changes with respect to the layout elements and attributes in SMIL 1.0 [SMIL10] are expected to be minor. SMIL 1.0 already provides for using alternative layout models, for example CSS [CSS2], and these can provide much of the additional functionality desired over the SMIL basic layout module. The support for hierarchical regions is one area in which the syntax may be extended. 

5.2 Brief review of SMIL 1.0 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, a set of regions can be described using the SMIL 1.0 basic layout syntax, CSS2 syntax, or some other syntax [SMIL-CSS2].

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

    <layout>

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

    </layout>
    

To create the same region using CSS2 syntax:

    <layout type="text/css">

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

    </layout>    
    

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

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

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

    <layout>

    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 SMIL basic layout syntax and semantics

5.3.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. Typically the <layout> element appears in the document head section. If a document contains no <layout> element, the positioning of the body elements is implementation-dependent.

A SMIL document can contain multiple alternative layouts by enclosing several <layout> elements within a "switch" element. This can be used for example to describe the document's layout using different layout languages.

Element attributes

id
This value uniquely identifies an 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 all content up until the next "</layout>" tag. The default value of the type attribute is "text/smil-basic-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 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>
      <region id="a" top="5" />
    </layout>
  </head>
  <body>
    <text region="a" src="text.html" dur="10s" />
  </body>
</smil>

Element  attributes

The "region" element can have the following 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".
If the backgroundColor attribute is absent, the background is transparent.
background-color
Deprecated. Equivalent to "backgroundColor", which replaces this attribute. Only SMIL document players are required to support "background-color".
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
  • 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 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 to leave out the "px" unit qualifier in pixel values (the "px" qualifier is required in CSS2).
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 "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 have the same restrictions as the attribute values of the "height" attribute.
The default value is zero.
skip-content
This attribute is introduced for future extensibility of SMIL. It is interpreted in the following two cases:

If the value of the "skip-content" attribute is "true", and one of the cases above apply, the content of the element is ignored. If the value is "false", the content of the element is processed.
The default value for  "skip-content" is "true".

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 have the same restrictions as the attribute values of the "height" attribute.
The default value is zero.
width
The use and definition of this attribute are identical to the "width" property in the CSS2 specification. Attribute values have the same restrictions as the attribute values of the "height" attribute.
z-index
The use and definition of this attribute are identical to the "z-index" property in the CSS2 specification, with the following exception:
If two boxes generated by elements A and B have the same stack level, then
  1. If the display of an element A starts later than the display of an element B, the box of A is stacked on top of the box of B (temporal order).
  2. If the display of the elements starts at the same time, and an element A occurs later in the SMIL document text than an element B, the box of A is stacked on top of the box of B (document tree order as defined in CSS2).

Element content

"region" 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 viewport, e.g. the window in which the SMIL presentation is rendered.

If a document contains more than one "root-layout" element, this is an error, and the document should not be displayed.

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.
skip-content
Defined in skip-content 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

"root-layout" is an empty element.

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

SMIL basic layout only controls the layout of media object elements. It is illegal to use SMIL basic layout for other SMIL elements.

The type identifier for SMIL basic layout is "text/smil-basic-layout".

Fixed property values

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

	
a           {display:block}
anchor      {display:block}
animation   {display: block;
             position: absolute}
body        {display: block}
head        {display: none}
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

SMIL basic layout defines default values for all layout-related attributes. These are consistent with the initial values of the corresponding properties in CSS2.

If the author wants to select the default layout values for all media object elements in a document, the document must contain an empty layout element of type "text/smil-basic-layout" such as:

<layout type="text/smil-basic-layout"></layout>

5.4 Extensions to SMIL 1.0 basic layout

The current SMIL 1.0 basic layout syntax is useful for its intended purpose as a simple, lightweight means of laying out a multimedia presentation that is available in all SMIL players. However, the need has arisen for additional layout functionality. It is expected that this additional functionality can be added at low implementation and runtime cost and not violate the original lightweight design goals of SMIL basic layout. 

Additional functionality expected to be provided via new syntax includes:

Additional functionality that may be provided via new syntax includes:

Additional functionality expected to be provided by support for additional CSS2/CSS3 properties includes:

5.5 Open Issues

Even given the straightforward extensions of the SMIL layout model discussed above, a number of open issues remain:


previous   next   contents