5. SMIL Layout Module

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

5.1 Introduction

This section defines the SMIL Layout Module, which is divided into three levels of increasing functionality. Each level builds on the functionality of the lower levels, and higher levels require lower levels as a prerequisite. This module contains elements and attributes allowing for positioning of media elements on the visual rendering surface, and control of audio volume. Since these elements and attributes are defined in a module, designers of other markup languages can choose whether or not to include this functionality in their languages. Therefore, language designers incorporating other SMIL modules do not need to include the layout module if sufficient layout functionality is already present.

5.2 Overview of SMIL Level 0 Layout

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

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

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

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

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

To create the same region using CSS2 syntax:

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

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

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

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

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

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

5.3 SMIL Layout Level 0 Syntax and Semantics

5.3.1 Layout Level 0 Elements and Attributes

This section defines the elements and attributes that make up the level 0 functionality in the SMIL layout module.

The layout element

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

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

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

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

Element attributes

type: This attribute specifies which layout language is used in the layout element. If the player does not understand this language, it must skip the element and all of its content up until the next </layout> tag. The default value of the type attribute is "text/smil-basic-layout". This identifier value supports SMIL 1.0 and SMIL Layout Level 0 layout semantics.

Element content

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

region
root-layout

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

The region element

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

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

<smil>
  <head>
    <layout>
        <root-layout width="320" height="480" />    
              <region id="a" top="5" />
    </layout>
  </head>
  <body>
    <text region="a" src="text.html" dur="10s" />
  </body>
</smil>

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

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

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

Element attributes

The region element can have the following visual attributes:

backgroundColor

The use and definition of this attribute are identical to the "background-color" property in the CSS2 specification, except that SMIL layout does not require support for "system colors".

background-color

Deprecated. Equivalent to backgroundColor, which replaces this attribute. The language profile must define whether or not the background-color attribute is supported. If both the backgroundColor and background-color attributes are absent, then the background is transparent.

bottom

The use and definition of this attribute are identical to the "bottom" property in the CSS2 specification. Attribute values can be "percentage" values, and a variation of the "length" values defined in CSS2. For "length" values, SMIL Layout Level 0 only supports pixel units as defined in CSS2. It allows the author to leave out the "px" unit qualifier in pixel values (the "px" qualifier is required in CSS2). Conflicts between the region size attributes bottom, left, right, top, width, and height are resolved according to the rules for absolutely positioned, replaced elements in [CSS2]. The default value of this attribute is auto.

fit

This attribute specifies the behavior if the intrinsic height and width of a visual media object differ from the values specified by the height and width attributes in the region element. This attribute does not have a one-to-one mapping onto a CSS2 property, but can be simulated in CSS2.
This attribute can have the following values:

fill

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

hidden

Has the following effect:

If the intrinsic height (width) of the media object element is smaller than the height (width) defined in the "region" element, render the object starting from the top (left) edge and fill up the remaining height (width) with the background color.
If the intrinsic height (width) of the media object element is greater than the height (width) defined in the "region" element, render the object starting from the top (left) edge until the height (width) defined in the "region" element is reached, and clip the parts of the object below (right of) the height (width).

meet

Scale the visual media object while preserving its aspect ratio until its height or width is equal to the value specified by the height or width attributes, while none of the content is clipped. The object's left top corner is positioned at the top-left coordinates of the box, and empty space at the left or bottom is filled up with the background color.

scroll

A scrolling mechanism should be invoked when the element's rendered contents exceed its bounds.

slice

Scale the visual media object while preserving its aspect ratio so that its height or width are equal to the value specified by the height and width attributes while some of the content may get clipped. Depending on the exact situation, either a horizontal or a vertical slice of the visual media object is displayed. Overflow width is clipped from the right of the media object. Overflow height is clipped from the bottom of the media object.

The default value of fill is hidden.

height

The use and definition of this attribute are identical to the "height" property in the CSS2 specification. Attribute values follow the same restrictions and rules as the values of the bottom attribute.