Extensible 3D (X3D)
Part 1: Architecture and base components

36 Layout component

36.1 Introduction

36.1.1 Name

The name of this component is "Layout". This name shall be used when referring to this component in the COMPONENT statement (see 7.2.5.4 Component statement).

36.1.2 Overview

This subclause describes the Layout component of this document. This includes how to precisely position content in a scene in relation to the rendered results. Table 36.1 provides links to the major topics in this subclause.

36.2 Concepts

36.2.1 Overview

This component provides a set of nodes that allow users to better integrate 2D content with 3D content. In X3D, authors have historically generated a Heads-Up Display (HUD) by placing content in a group that moves along with the user’s viewpoint. This approach is limited in that the author has limited control over where the HUD geometry is rendered relative to the display viewport.

EXAMPLE  There is no way to ensure that the content will be aligned with a particular edge of the display viewport.

This component provides several nodes that enable the integration of 2D content into the 3D scene. It allows for constructing a hierarchy of rectangular regions that are well suited to contain 2D content, but can also contain 3D content. These 2D regions are not affected by the user navigation or the bound X3DViewpointNode. They are aligned relative to the main scene viewport, or the 2D region that act as its parent.

This component also contains a X3DFontStyleNode node that can render text so that it appears identical to typical 2D applications, with the eye soothing technique of anti-aliasing.

36.2.2 Pixel-specific addressing

This component also provides utilities that allowing content authors the ability to scale and locate 2D regions and content using pixel-specific addressing. Therefore, some of the nodes and options in this component are dependent on the concept of pixel-based display devices. It is recognized that some implementations do not use such devices. Therefore, those pixel-specific nodes and options are not applicable to those implementations. The pixel-specific nodes and options are contained in a support level designated for pixel-specific concepts.

A node is specified that can exist anywhere in the scene hierarchy. This node forces a scale so that one unit is one pixel.

36.2.3 Viewports

The output to a surface can be constrained further by using an X3DViewportNode node. This node is a special grouping node that defines a set of clipping bounds within the extent of a surface within which the children nodes of the viewport will appear. This provides support for the typical front/side/back/oblique views used by CAD systems.

36.3 Abstract types

36.3.1 X3DLayoutNode

X3DLayoutNode : X3DChildNode {
  SFNode [in,out] metadata NULL [X3DMetadataObject]
}

This is the base node type for layout nodes.

36.4 Node Reference

36.4.1 Layout

Layout : X3DLayoutNode { 
  MFString [in,out] align       ["CENTER","CENTER"] ["LEFT"|"CENTER"|"RIGHT"],["BOTTOM"|"CENTER"|"TOP"] 
  SFNode   [in,out] metadata    NULL                [X3DMetadataObject]
  MFFloat  [in,out] offset      [0,0]               (-∞,∞)
  MFString [in,out] offsetUnits ["WORLD","WORLD"]   ["WORLD"|"FRACTION"|"PIXEL"],["WORLD"|"FRACTION"|"PIXEL"] 
  MFString [in,out] scaleMode   ["NONE","NONE"]     ["NONE"|"FRACTION"|"STRETCH"|"PIXEL"],["NONE"|"FRACTION"|"STRETCH"|"PIXEL"] 
  MFFloat  [in,out] size        [1,1]               (0,∞)
  MFString [in,out] sizeUnits   ["WORLD","WORLD"]   ["WORLD"|"FRACTION"|"PIXEL"],["WORLD"|"FRACTION"|"PIXEL"] 
}

The Layout node is used in the layout field of the LayoutLayer and LayoutGroup nodes. The Layout node provides all the parameters that are required to define the size and location of a 2D rectangular region that is associated with the containing node. Also, it contains a field that defines how the content of the containing node shall be scaled.

The fields of interest in the Layout node are MFString and MFFloat fields. All have two elements. The first value corresponds to the horizontal direction and the second field corresponds to the vertical direction. If a field has a length of one, that value applies to both the horizontal and vertical directions. If the align field has only one value, that value shall be "CENTER".

The width and height of the layout rectangle is defined by two values in the size field. The sizeUnits field specifies how to interpret the size values. If the value of the sizeUnits field is "FRACTION", the size of the corresponding dimension is interpreted as a fraction of the corresponding parent’s dimension.

EXAMPLE  If the size value is (0.25, 0.5) and the value of sizeUnits (["FRACTION", "FRACTION"]), the width of the region is one quarter of the width of the parent and the height of the region is one half of the height of the parent.

A sizeUnits value of "WORLD" specifies that the corresponding size value is interpreted using the current world units of the parent node. Since the LayoutLayer node does not have a parent, a value of "WORLD" is equivalent to a value of "FRACTION". Lastly, a sizeUnits value of "PIXEL" specifies that the corresponding size value is in pixel units.

NOTE   Implementations that do not support the concept of a pixel are not required to support the "PIXEL" option.

The values of the align, offset, and offsetUnits fields are used to determine the location of the layout region. First, the align field values align the sized rectangle to an edge or center of the parent rectangle. Then, the offset is applied using the units specified in the offsetUnits field. The first value of the align field corresponds to the horizontal alignment. The value "LEFT" specifies that the left side of this rectangle shall be aligned with the left side of the parent rectangle. The value "RIGHT" specifies that the right side of this rectangle shall be aligned with the right side of the parent rectangle. The value "CENTER" specifies that this rectangle shall be horizontally centred in its parent. Similarly, the second align field value aligns the vertical position of the rectangle to either the "TOP", "BOTTOM" or "CENTER" of the parent rectangle.

After the alignment is applied, the values of the offset field are used to translate the location of this rectangle after the initial alignment. The value of the offset field is interpreted using the value of the offsetUnits field, using the same options and logic as the sizeUnits field, described above.

The scaleMode field specifies how the scale of the parent is modified. The scale field has two values, the first specifies the horizontal scale and the second value specifies the vertical scale. A scaleMode field value of "NONE" specifies that the corresponding scale value is not modified. Instead, the scale is inherited from its parent. Since a LayoutLayer node does not have a parent, the value of "NONE" reverts to "FRACTION". A scaleMode value of "FRACTION" specifies a scale in the corresponding direction so that one unit is equal to the dimension (width or height) of this rectangle. A value of "PIXEL" specifies a scale in the corresponding direction such that one unit is equal to one pixel.

NOTE   Implementations that do not support the concept of a pixel are not required to support this "PIXEL" option.

A scaleMode value of "STRETCH" specifies a scale in the corresponding direction such that the resulting scale in the horizontal direction is equal to the scale in the vertical direction, thus producing a uniform scale. If one of the dimensions has a scaleMode value of "STRETCH", and the other dimension has a value other than "STRETCH", the scale for the dimension that is not "STRETCH" shall be computed first and the dimension corresponding to the value of "STRETCH" can then be computed to achieve a uniform scale. If both components of the scaleMode field are "STRETCH", the scale component corresponding to the larger dimension of the rectangular region is set so that one unit is equal to the dimension of the rectangle, and the other scale component is set so that the resulting scale in the horizontal and vertical directions are the same.

36.4.2 LayoutGroup

LayoutGroup : X3DNode X3DGroupingNode {
   MFNode  [in]     addChildren          [X3DChildNode]
   MFNode  [in]     removeChildren       [X3DChildNode]
   MFNode  [in,out] children       []    [X3DChildNode]
   SFBool  [in,out] bboxDisplay    FALSE
   SFNode  [in,out] layout         NULL  [X3DLayoutNode]
   SFNode  [in,out] metadata       NULL  [X3DMetadataObject]
   SFNode  [in,out] viewport       NULL  [X3DViewportNode]
   SFBool  [in,out] visible        TRUE
   SFVec3f []       bboxCenter     0 0 0 (-∞,∞)
   SFVec3f []       bboxSize       0 0 0 (-∞,∞)
}

The LayoutGroup is a grouping node whose children are related by a common layout within a parent layout. Thus, a LayoutGroup can only be a child of a LayoutLayer node or another LayoutGroup node.

The layout field contains an X3DLayoutNode node that specifies the information required to locate and size the layout region of the LayoutGroup node relative to its parent’s layout region and to scale the contents of the LayoutGroup. The content of the LayoutGroup is clipped by the specified viewport.

10.2.1 Grouping and children node types specifies the children, addChildren, and removeChildren fields.

The origin of the node is always in the center of its layout region. Thus, children (with the exception of LayoutGroup) are specified in a coordinate system whose origin is located at the center of the rectangle and can be transformed from that location.

The LayoutGroup node does not directly have any pixel dependent concepts. However, the LayoutGroup node does contain a Layout node that does have pixel-specific options.

36.4.3 LayoutLayer

LayoutLayer : X3DLayerNode { 
  MFNode   [in]     addChildren          [X3DChildNode]
  MFNode   [in]     removeChildren       [X3DChildNode]
  MFNode   [in,out] children       []    [X3DChildNode]
  SFNode   [in,out] layout         NULL  [X3DLayoutNode]
  SFNode   [in,out] metadata       NULL  [X3DMetadataObject]
  MFString [in,out] objectType     "ALL" ["ALL","NONE","TERRAIN",...]
  SFBool   [in,out] pickable    TRUE
  SFNode   [in,out] viewport       NULL  [X3DViewportNode]
  SFBool   [in,out] visible        TRUE
}

The LayoutLayer node specifies a children field that contains a list of nodes that define the subscene.

10.2.1 Grouping and children node types specifies the children, addChildren, and removeChildren fields.

An OrthoViewpoint node is automatically established as the default node on the binding stack. Although not restricted to require this, the LayoutLayer node is typically used as the last rendered node in a LayerSet ordering.

The layout field contains an instance of X3DLayoutNode that contains the information required to locate and size the LayoutLayer node’s rectangular region relative to the main viewport, and to scale the content of the LayoutLayer. The content of the LayoutLayer is clipped by the defined rectangular region.

36.4.4 ScreenFontStyle

ScreenFontStyle : X3DFontStyleNode {
  SFNode   [in,out] metadata    NULL    [X3DMetadataObject]
  MFString [in,out] family      "SERIF"
  SFBool   [in,out] horizontal  TRUE
  MFString [in,out] justify     "BEGIN" ["BEGIN"|"END"|"FIRST"|"MIDDLE"|""],["BEGIN"|"END"|"FIRST"|"MIDDLE"|""] 
  SFString [in,out] language    ""
  SFBool   [in,out] leftToRight TRUE
  SFFloat  [in,out] pointSize   12.0    (0,∞)
  SFFloat  [in,out] spacing     1.0     [0,∞)
  SFString [in,out] style       "PLAIN" ["PLAIN"|"BOLD"|"ITALIC"|"BOLDITALIC"|""]
  SFBool   [in,out] topToBottom TRUE
}

The ScreenFontStyle node specifies font styles in terms of the characteristics of a particular presentation surface upon which the text is to be rendered.

The fields in the ScreenFontStyle node are the same as those in the FontStyle node with a single exception:  the size field of the FontStyle node is replaced with a pointSize field. The pointSize field specifies the size of text in points. Thus, the distance between the baseline of each line of text is (spacing  × pointSize) in the appropriate direction.

Otherwise, the attributes are as specified in 15.4.1 FontStyle and 15.2.2 Text formatting.

36.4.5 ScreenGroup

ScreenGroup : X3DGroupingNode {
  MFNode  [in]     addChildren             [X3DChildNode]
  MFNode  [in]     removeChildren          [X3DChildNode]
  MFNode  [in,out] children       []       [X3DChildNode]
  SFBool  [in,out] bboxDisplay    FALSE
  SFNode  [in,out] metadata       NULL     [X3DMetadataObject]
  SFBool  [in,out] visible        TRUE
  SFVec3f []       bboxCenter     0 0 0    (-∞,∞)
  SFVec3f []       bboxSize       -1 -1 -1 [0,∞) or -1 -1 -1
}

The ScreenGroup node is a node derived from X3DGroupingNode with one additional functional feature:  it modifies the scale in such a way that one unit is equal to one pixel in both the horizontal and vertical directions.

If the ScreenGroup node is a child of a Billboard node that is screen-aligned (i.e., has an axisOfRotation value of (0,0,0)), the children of the ScreenGroup shall be both screen-aligned and scaled so that one unit is equal to one pixel. This allows users to place screen-aligned and screen-scaled content into the 3D scene. It will maintain its location in the 3D scene but can be occluded by other geometry that lies in front. Additionally, it can occlude other geometry that lies in back.

10.2.1 Grouping and children node types specifies the children, addChildren, and removeChildren fields.

The bboxCenter and bboxSize fields specify a bounding box that encloses the children. This is a hint that may be used for optimization purposes. The results are undefined if the specified bounding box is smaller than the actual bounding box of the children at any time. The default bboxSize value, (-1, -1, -1), implies that the bounding box is not specified and, if needed, shall be calculated by the X3D browser. More details on the bboxCenter and bboxSize fields can be found in 10.2.2 Bounding boxes.

36.5 Support levels

The Layout component provides two levels of support as specified in Table 36.2. Level 1 provides the basic support for layout. Level 2 provides for pixel-specific addressing.