JSignage:Layer implementation in SVG

Representation in the DOM

A "layer" for the jSignage library is implemented as a combination of one or more SVG elements and manipulated with a set of jSignage internal helper functions described below.

In the simplest case, it may just be one of the media elements, like <video>, but in general there are a few elements working together under a subtree.

The constitutive elements of this subtree are explained below in top-down order.

The effect wrapper elements

The root-most elements of a layer are typically <g> wrapper elements implementing effects. Such an element must have a non-empty spx:effect-target-id attribute that points back either to another effect down in the effect stack or to the "real media target". If multiple effects are applied, then each one is wrapped in turn into the other one, forming a stack of effects. The implementation of effects is detailed on the Creating new effects page.

Use the $.getRealMediaTarget() to locate the "real media target" element. The will return the element itself if there are not effects so it is safe to always use it.

For instance in this sample code, $.getRealMediaTarget() function will return a handle to the <image> element.

<g spx:effect-target-id='guuid_1' xml:id='guuid_2'>
  <video xlink:href='clip.mpg' xml:id='guuid_1' />
  <animate attributeName='opacity' from='0' to='1' begin='guuid1.begin+0' dur='1s' />
</g>

The "real media target"

At the center is the "real media target" element, i.e. <image>, <video>, <audio>, <animation>, <textArea>, or, more often than not, <g>.

• If the "real media target" element is a <g>, then it must have a non-empty spx:layer-type attribute.
• The $.isLayer function may be used to test whether a given element is indeed the "real media target" of a layer.

The "timing element"

Each layer has a "timing element", which is a SMIL element whose active interval defines the active interval of the layer.

For the <audio>, <video> and <animation> elements, the timing element is the "real media target" itself.

Use the $.getTimingElement() function to access the timing element from the "real media target". This function is always guaranteed to return the right element, including itself.

For <image>, <textArea> and <g>, the timing element is the first child of the "real media target" and must be either a <set> or <animate>. This assumes the convention that to show a static element for some interval, its display attribute is set to 'none' and a <set> animation element is used to set the display attribute to 'inherit'.

There are four possible combinations to consider:

• when initialVisibility='whenStarted' and fill='remove' (the default case):

  <g display='none'><set attributeName='display' to='inherit' begin='...' dur='...'></g>

• when initialVisibiliy='whenStarted' and fill='freeze':

  <g display='none'><set attributeName='display' to='inherit' begin='...' dur='...' fill='freeze'></g>

• when initialVisibility='always' and fill='remove':

  <g display='inherit'><animate attributeName='display' to='inherit;none' keyTimes='0;1' begin='...' dur='...' fill='freeze'></g>

• when initialVisibiliy='always' and fill='freeze':

  <g display='inherit'><set attributeName='display' to='inherit' begin='...' dur='...'></g>

Frame decoration and G2

When frame decoration is present, the "real media target" is always a <g>. Frame decoration causes the content to de defferred one level into an inner element, which is a direct child of the "real media target", but with some elements implementing the frame decoration before and after it.

Use the $.getG2() function to retreive this "G2" element from the "real media target". This function is always guaranteed to return the right element, including itself.

Example: a textArea with a semi-transparent background. $.getG2() will return a handler to the <textArea> element.

<g spx:layer-type='textArea' display='none'>
  <set attributeName='display' to='inherit' begin='0' dur='indefinite' />
  <rect width='1280' height='720' fill='blue' fill-opacity='0.5' />
  <textArea width='1280' height='720'>
    Some text
  </textArea>
</g>

Hierarchical layout

The following attributes in the spx namespace: top, left, bottom, right, width and height are used, if present on the top level element of a layer, to convey layout instructions to the library.
This instructions are used when a layer is added to a layer group to provide CSS like automatic layout of boxes inside boxes. The valid values are pixel values, relative values expressed as percentage of the parent bounding box and 'auto'. When the dimension of a group layer is changed, the instructions are used again to compute a new layout.
If an attribute is not present it is as if 'auto' were specified for this attribute.
The current box assigned by the layout coded is contained in the transform, width and height attributes of a layer element (in the SVG namespace), where transform is expected to be of the form translate(x,y). The width and height attributes are used to store the allocated box dimensions for <g> elements as well.
The hierarchical layout calculation is applied only when a layer is added to a <g> element or the <svg> element with the .add() or .addTo() methods and that element is in the presentation tree. A viewport is computed based on the width and height attributes found on the parent element, searching for ancestors if the parent does not have one until the <svg> element is reached, whose viewBox attribute is then used. When a layer is added to <g> which is not in the presentation tree, the computation of the layout is delayed until the parent layer is itself added to the presentation tree.

Effects and transitions

Effects and transitions are implemented as a <g> wrapping the layer. The element has a mandatory spx:effect-target-id attribute which links to the id of the next effect in the chain or to the original layer element. The element pointed to must be a child, direct or indirect.
The layout attribute are set on the layer element itself. Effects use callbacks to be notified of when the dimension of the layer is allocated or reallocated if it needs to update some of the SVG code in the effect to the size or position of the layer.