10.1 Introduction

10.1.1 Name

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

10.1.2 Overview

This clause describes the Grouping component of this document. This includes how nodes are organized into groups to establish a transformation hierarchy for the X3D scene graph. Table 10.1 provides links to the major topics in this clause.

10.2 Concepts

10.2.1 Grouping and children node types

Grouping nodes have a field that contains a list of children nodes. Each grouping node defines a coordinate space for its children. This coordinate space is relative to the coordinate space of the node of which the group node is a child. Such a node is called a parent node. This means that transformations accumulate down the scene graph hierarchy.

This document defines several grouping nodes, including the following:

• Anchor
• Billboard
• Collision
• Group
• LOD
• Switch
• Transform

Components may add the following:

• new grouping node types,
• new node types that may be used as children, and
• node types that may not be used as children.

All grouping nodes have addChildren and removeChildren inputOnly fields. The addChildren event appends nodes to the children field of a grouping node. Any nodes passed to the addChildren inputOnly field that are already in the children list of the grouping node are ignored. For example, if the children field contains the nodes Q, L and S (in order) and the group receives an addChildren event containing (in order) nodes A, L, and Z, the result is a children field containing (in order) nodes Q, L, S, A, and Z.

The removeChildren event removes nodes from the children field of the grouping node. Any nodes in the removeChildren event that are not in the children list of the grouping node are ignored. For example, if the children field contains the nodes Q, L, S, A and Z and it receives a removeChildren event containing nodes A, L, and Z, the result is Q, S.

Note that a variety of node types reference other node types through fields. Some of these are parent-child relationships, while others are not (there are node-specific semantics).

All grouping nodes shall have a children field of type MFNode. Adding a node to this field will add that node to the grouping node's set of children. A children field is not allowed to directly contain multiple instances of the same node. A children field is not allowed to contain nodes that are ancestors of the grouping node.

A variety of node types reference other node types through fields. Some of these are parent-child relationships ( e.g., the children field of the Transform node) while others are not ( e.g., the appearance field of the Shape node). The field type specifies which type of node may be placed in them. For instance, the node type of the children field of the Transform node is MFNode where all nodes shall be derived from X3DChildNode. Therefore, only node types derived from X3DChildNode may be placed there. Shape is legal in the children field because it is derived from X3DChildNode, while Appearance is not. See Figure 4.2 for a complete derivation hierarchy.

New node types may be defined using extension mechanisms, typically PROTO/EXTERNPROTO declarations and instances. These new node types can be placed in a node field as long as the field type in the containing node is part of the derivation hierarchy of the new node type.

10.2.2 Bounding boxes

Several node types include a bounding box specification comprised of two fields, bboxSize and bboxCenter. A bounding box is a rectangular parallelepiped of dimension bboxSize centred on the location bboxCenter in the local coordinate system. This is typically used by grouping nodes to provide a hint to the X3D browser on the group's approximate size for culling optimizations. The default size for bounding boxes (−1, −1, −1) indicates that the user did not specify the bounding box and the effect shall be as if the bounding box were infinitely large. A bboxSize value of (0, 0, 0) is valid and represents a point in space ( i.e., an infinitely small box). Specified bboxSize field values shall be ≥ 0.0 or equal to (−1, −1, −1). The bboxCenter fields specify a position offset from the local coordinate system.

The bboxCenter and bboxSize fields may be used to specify a maximum possible bounding box for the objects inside a grouping node (EXAMPLE  Transform). These are used as hints to optimize certain operations such as determining whether or not the group needs to be drawn. The bounding box shall be large enough at all times to enclose the union of the group's children's bounding boxes; it shall not include any transformations performed by the group itself ( i.e., the bounding box is defined in the local coordinate system of the children). Results are undefined if the specified bounding box is smaller than the true bounding box of the group.

10.3 Abstract types

10.3.1 X3DBoundedObject

X3DBoundedObject { 
  SFBool  [in,out] bboxDisplay FALSE
  SFBool  [in,out] visible     TRUE
  SFVec3f []       bboxCenter  0 0 0    (-∞,∞)
  SFVec3f []       bboxSize    -1 -1 -1 [0,∞) or −1 −1 −1
}

This abstract interface is the basis for all node types that have bounds specified as part of the definition.

The bboxCenter and bboxSize fields specify a bounding box that encloses the grouping node's 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. A default bboxSize value, (-1, -1, -1), implies that the bounding box is not specified and, if needed, is calculated by the X3D browser. A description of the bboxCenter and bboxSize fields is contained in 10.2.2 Bounding boxes.

When bboxDisplay is true, the bounding box is displayed for the associated geometry so that both are aligned with world coordinates. The bounding box is displayed regardless of whether contained content is visible.

The visible field specifies whether or not the content within a node is visually displayed. The value of this field has no effect on animation behaviors, collision behaviors, event passing, or other non-visual characteristics.

10.3.2 X3DGroupingNode

X3DGroupingNode : X3DChildNode, X3DBoundedObject { 
  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
}

This abstract node type indicates that concrete node types derived from it contain children nodes and is the basis for all aggregation.

More details on the children, addChildren, and removeChildren fields can be found i 10.2.1 Grouping and children node types.

10.4 Node reference

10.4.1 Group

Group : 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
}

A Group node contains children nodes without introducing a new transformation. It is equivalent to a Transform node containing an identity transform.

More details on the children, addChildren, and removeChildren fields can be found in 10.2.1 Grouping and children node types.

The bboxCenter and bboxSize fields specify a bounding box that encloses the Group node's 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. A default bboxSize value, (-1, -1, -1), implies that the bounding box is not specified and, if needed, is calculated by the X3D browser. A description of the bboxCenter and bboxSize fields is contained in 10.2.2 Bounding boxes.

10.4.2 StaticGroup

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

The StaticGroup node contains children nodes which cannot be modified. StaticGroup children are guaranteed to not change, send events, receive events or contain any USE references outside the StaticGroup. This allows the X3D browser to optimize this content for faster rendering and less memory usage.

A X3D browser shall prevent all illegal attempts to modify the StaticGroup and its children. Children of the StaticGroup are guaranteed not to generate events.

Implementations are free to rearrange or remove nodes inside a StaticGroup as long as the final rendering is the same. These optimizations might include flattening a series of transformations into one transform, performing appearance bundling or heavy analysis of the scene graph for maximal rendering speed. A StaticGroup does not need to maintain its children's X3D representations (such as field data), as they cannot be accessed after creation time.

The visible field specifies whether or not the content within a node is visually displayed. The value of this field has no effect on animation behaviors, collision behaviors, event passing, or other non-visual characteristics.

10.4.3 Switch

Switch : 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
  SFInt32 [in,out] whichChoice    -1       [-1,∞)
  SFVec3f []       bboxCenter     0 0 0    (-∞,∞)
  SFVec3f []       bboxSize       -1 -1 -1 [0,∞) or −1 −1 −1
}

The Switch grouping node traverses zero or one of the nodes specified in the children field.

10.2.1 Grouping and children node types, describes details on the types of nodes that are legal values for children.

The whichChoice field specifies the index of the child to traverse, with the first child having index 0. If whichChoice is less than zero or greater than the number of nodes in the children field, nothing is chosen.

All nodes under a Switch continue to receive and send events regardless of the value of whichChoice. For example, if an active TimeSensor is contained within an inactive choice of an Switch, the TimeSensor sends events regardless of the Switch's state.

The bboxCenter and bboxSize fields specify a bounding box that encloses the Switch node's 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 child with the largest bounding box at any time. A default bboxSize value, (-1, -1, -1), implies that the bounding box is not specified and, if needed, is calculated by the X3D browser. A description of the bboxCenter and bboxSize fields is contained in 10.2.2 Bounding boxes.

10.4.4 Transform

Transform : X3DGroupingNode {
  MFNode     [in]     addChildren               [X3DChildNode]
  MFNode     [in]     removeChildren            [X3DChildNode]
  SFVec3f    [in,out] center           0 0 0    (-∞,∞)
  MFNode     [in,out] children         []       [X3DChildNode]
  SFBool     [in,out] bboxDisplay      FALSE
  SFNode     [in,out] metadata         NULL     [X3DMetadataObject]
  SFRotation [in,out] rotation         0 0 1 0  [-1,1] or (-∞,∞)
  SFVec3f    [in,out] scale            1 1 1    (-∞, ∞)
  SFRotation [in,out] scaleOrientation 0 0 1 0  [-1,1] or (-∞,∞)
  SFVec3f    [in,out] translation      0 0 0    (-∞,∞)
  SFBool     [in,out] visible          TRUE
  SFVec3f    []       bboxCenter       0 0 0    (-∞,∞)
  SFVec3f    []       bboxSize         -1 -1 -1 [0,∞) or −1 −1 −1
}

The Transform node is a grouping node that defines a coordinate system for its children that is relative to the coordinate systems of its ancestors. See 4.3.5 Transformation hierarchy and 4.3.6 Standard units and coordinate system for a description of coordinate systems and transformations.

10.2.1 Grouping and children node types, provides a description of the children, addChildren, and removeChildren fields.

The bboxCenter and bboxSize fields specify a bounding box that encloses the children of the Transform node. 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. A default bboxSize value, (-1, -1, -1), implies that the bounding box is not specified and, if needed, shall be calculated by the X3D browser. The bounding box shall be large enough at all times to enclose the union of the group's children's bounding boxes; it shall not include any transformations performed by the group itself ( i.e., the bounding box is defined in the local coordinate system of the children). A description of the bboxCenter and bboxSize fields is provided in 10.2.2 Bounding boxes.

The translation, rotation, scale, scaleOrientation and center fields define a geometric 3D transformation consisting of (in order):

1. a (possibly) non-uniform scale about an arbitrary point;
2. a rotation about an arbitrary point and axis;
3. a translation.

The center field specifies a translation offset from the origin of the local coordinate system (0,0,0). The rotation field specifies a rotation of the coordinate system. The scale field specifies a non-uniform scale of the coordinate system. Scale values may have any value: positive, negative (indicating a reflection), or zero. A value of zero indicates that any child geometry shall not be displayed. The scaleOrientation specifies a rotation of the coordinate system before the scale (to specify scales in arbitrary orientations). The scaleOrientation applies only to the scale operation. The translation field specifies a translation to the coordinate system.

Given a 3-dimensional point P and Transform node, P is transformed into point P' in its parent's coordinate system by a series of intermediate transformations. In matrix transformation notation, where C ( center), SR ( scaleOrientation), T ( translation), R ( rotation), and S ( scale) are the equivalent transformation matrices,

  P' = T * C * R * SR * S * -SR * -C * P

The following Transform node:

Transform {
  center           C
  rotation         R
  scale            S
  scaleOrientation SR
  translation      T
  children         [
    # Point P (or children holding other geometry)
  ]
}

is equivalent to the nested sequence of:

Transform {
  translation T 
  children Transform {
    translation C
    children Transform {
      rotation R
      children Transform {
        rotation SR 
        children Transform {
          scale S 
          children Transform {
            rotation -SR 
            children Transform {
              translation -C
              children [
                # Point P (or children holding other geometry)
              ]
}}}}}}}

10.5 Support levels

The Grouping component provides four levels of support as specified in Table 10.2.