The Java 3D API Specification |

C H A P T E R 5

Group Node Objects

> GROUP nodes are the glue elements used in constructing a scene graph. The following subsections list the seven group nodes (see Figure 5-1) and their definitions. All group nodes can have a variable number of child node objects-including other group nodes as well as leaf nodes. These children have an associated index that allows operations to specify a particular child. However, unless one of the special ordered group nodes is used, the Java 3D renderer can choose to render a group node's children in whatever order it wishes (including rendering the children in parallel).

> Figure 5-1 Group Node Hierarchy

> ## 5.1 Group Node

> The Group node object is a general-purpose grouping node. Group nodes have exactly one parent and an arbitrary number of children that are rendered in an unspecified order (or in parallel). Null children are allowed; no operation is performed on a null child node. Operations on Group node objects include adding, removing, and enumerating the children of the Group node. The subclasses of Group node add additional semantics.

> ##### Constants

>     public static final int ALLOW_CHILDREN_READ
>     public static final int ALLOW_CHILDREN_WRITE
>     public static final int ALLOW_CHILDREN_EXTEND

> These flags, when enabled using the `setCapability` method, specify that this Group node will allow the following methods, respectively:

> - `numChildren`, `getChild`, `getAllChildren`

> - `setChild`, `insertChild`, `removeChild`

> - `addChild`, `moveTo`

> These capability bits are enforced only when the node is part of a live or compiled scene graph.

>     public static final int ALLOW_COLLISION_BOUNDS_READ
>     public static final int ALLOW_COLLISION_BOUNDS_WRITE

> These flags, when enabled using the `setCapability` method, specify that this Group node will allow reading and writing of its collision bounds.

> ##### Constructors

>     public Group()

> Constructs and initializes a Group node object with default parameters:

>   collision bounds = null
>   alternate collision target = false

> ##### Methods

> The Group node class defines the following methods:

>     public int numChildren()
>     public Node getChild(int index)

> The first method returns a count of the number of children. The second method returns the child at the specified index.

>     public void setChild(Node child, int index)
>     public void insertChild(Node child, int index)
>     public void removeChild(int index)

> The first method replaces the child at the specified index with a new child. The second method inserts a new child before the child at the specified index. The third method removes the child at the specified index. Note that if this Group node is part of a live or compiled scene graph, only BranchGroup nodes may be added to or removed from it-and only if the appropriate capability bits are set.

>     public Enumeration getAllChildren()

> This method returns an Enumeration object of all children.

>     public void addChild(Node child)

> This method adds a new child as the last child in the group. Note that if this Group node is part of a live or compiled scene graph, only BranchGroup nodes may be added to it-and only if the appropriate capability bits are set.

>     public void moveTo(BranchGroup branchGroup)

> This method moves the specified BranchGroup node from its old location in the scene graph to the end of this group, in an atomic manner. Functionally, this method is equivalent to the following lines:

>         branchGroup.detach();
>         this.addChild(branchGroup);

> If either this Group or the specified BranchGroup is part of a live or compiled scene graph, the appropriate capability bits must be set in the affected nodes.

>     public Bounds setCollisionBounds(Bounds bounds)
>     public Bounds getCollisionBounds()

> These methods set and retrieve the collision bounding object for a node.

>     public void setAlternateCollisionTarget(boolean target)
>     public boolean getAlternateCollisionTarget()

> The set method causes this Group node to be reported as the collision target when collision is being used and this node or any of its children are in a collision. The default is false. This method tries to set the capability bit `Node.ENABLE_COLLISION_REPORTING`. The get method returns the collision target state.

> For collision with USE_GEOMETRY set, the collision traverser will check the geometry of all the Group node's leaf descendants. For collision with USE_BOUNDS set, the collision traverser will check the bounds at this Group node. In both cases, if there is a collision, this Group node will be reported as the colliding object in the SceneGraphPath.

> ## 5.2 BranchGroup Node

> A BranchGroup is the root of a subgraph of a scene that may be compiled as a unit, attached to a virtual universe, or included as a child of a group node in another subgraph. A subgraph, rooted by a BranchGroup node, can be thought of as a compile unit. The following may be done with BranchGroup:

> - A BranchGroup may be compiled by calling its `compile` method. This causes the entire subgraph to be compiled. If any BranchGroup nodes are contained within the subgraph, they are compiled as well (along with their descendants).

> - A BranchGroup may be inserted into a virtual universe by attaching it to a Locale. The entire subgraph is then said to be live.

> - A BranchGroup that is contained within another subgraph may be reparented or detached at run time if the appropriate capabilities are set. See Figure 5-2.

> Note that if a BranchGroup is included in another subgraph, as a child of some other group node, it may not be attached to a Locale.

> ##### Constants

> The BranchGroup class adds the following new constant:

>     public static final int ALLOW_DETACH

> This flag, when enabled using the `setCapability` method, allows this BranchGroup node to be detached from its parent group node. This capability flag is enforced only when the node is part of a live or compiled scene graph.

> ##### Constructors

>     public BranchGroup()

> Constructs and initializes a new BranchGroup node object.

> ##### Methods

> The BranchGroup class defines the following methods:

> Figure 5-2 Altering the Scene Graph at Run Time

>     public void compile()

> This method compiles the scene graph rooted at this BranchGroup and creates and caches a newly compiled scene graph.

>     public void detach()

> This method detaches the BranchGroup node from its parent.

> ## 5.3 TransformGroup Node

> The TransformGroup node specifies a single spatial transformation-via a Transform3D object (see Section 8.1.29, "Transform3D Object")-that can position, orient, and scale all of its children.

> The specified transformation must be affine. Further, if the TransformGroup node is used as an ancestor of a ViewPlatform node in the scene graph, then the transformation must be congruent-only rotations, translations, and uniform scales are allowed in a direct path from a Locale to a ViewPlatform node. A `BadTransformException` (see Section D.1, "BadTransformException") is thrown if an attempt is made to specify an illegal transform.

> Note: Even though arbitrary affine transformations are allowed, better performance will result if all matrices within a branch graph are congruent-containing only rotations, translation, and uniform scale.

> The effects of transformations in the scene graph are cumulative. The concatenation of the transformations of each TransformGroup in a direct path from the Locale to a Leaf node defines a composite model transformation (CMT) that takes points in that Leaf node's local coordinates and transforms them into Virtual World (Vworld) coordinates. This composite transformation is used to transform points, normals, and distances into Vworld coordinates. Points are transformed by the CMT. Normals are transformed by the inverse-transpose of the CMT. Distances are transformed by the scale of the CMT. In the case of a transformation containing a nonuniform scale or shear, the maximum scale value in any direction is used. This ensures, for example, that a transformed bounding sphere, which is specified as a point and a radius, continues to enclose all objects that are also transformed using a nonuniform scale.

> ##### Constants

> The TransformGroup class adds the following new flags:

>     public static final int ALLOW_TRANSFORM_READ
>     public static final int ALLOW_TRANSFORM_WRITE

> These flags, when enabled using the `setCapability` method, allow this node's Transform3D to be read or written. They are used only when the node is part of a live or compiled scene graph.

> ##### Constructors

>     public TransformGroup()
>     public TransformGroup(Transform3D t1)

> These construct and initialize a new TransformGroup. The first form initializes the node's Transform3D to the identity transformation; the second form initializes the node's Transform3D to a copy of the specified transform.

> ##### Methods

> The TransformGroup class defines the following methods:

>     public void setTransform(Transform3D t1)
>     public void getTransform(Transform3D t1)

> These methods retrieve or set this node's attached Transform3D object by copying the transform to or from the specified object.

>     public Node cloneNode(boolean forceDuplicate)
>     public void duplicateNode(Node originalNode,
>            boolean  forceDuplicate)

> The first method creates a new instance of the node. This method is called by `cloneTree` to duplicate the current node. The second method copies all the node information from the `originalNode` into the current node. This method is called from the `cloneNode` method, which in turn is called by the `cloneTree` method.

> For each NodeComponent object contained by the object being duplicated, the NodeComponent's `duplicateOnCloneTree` flag is used to determine whether the NodeComponent should be duplicated in the new node or a reference to the current node should be placed in the new node. This flag can be overridden by setting the `forceDuplicate` parameter in the `cloneTree` method to `true`.

> ## 5.4 OrderedGroup Node

> The OrderedGroup node guarantees that Java 3D will render its children in their index order. Only the OrderedGroup node and its subclasses make any use of the order of their children during rendering.

> ##### Constructors

>     public OrderedGroup()

> Constructs and initializes a new OrderedGroup node object.

> ## 5.5 DecalGroup Node

> The DecalGroup node is a subclass of the OrderedGroup node. The DecalGroup node is an ordered group node used for defining decal geometry on top of other geometry. The DecalGroup node specifies that its children should be rendered in index order and that they generate coplanar objects. Examples include painted decals or text on surfaces and a checkerboard layered on top of a table.

> The first child, at index 0, defines the surface on top of which all other children are rendered. The geometry of this child must encompass all other children; otherwise, incorrect rendering may result. The polygons contained within each of the children must be facing the same way. If the polygons defined by the first child are front facing, then all other surfaces should be front facing. In this case, the polygons are rendered in order. The renderer can use knowledge of the coplanar nature of the surfaces to avoid Z-buffer collisions. (If, for example, the underlying implementation supports stenciling or polygon offset, then these techniques may be employed.) If the main surface is back facing, then all other surfaces should be back facing and need not be rendered (even if back-face culling is disabled).

> Note that using the DecalGroup node does not guarantee that Z-buffer collisions are avoided. An implementation of Java 3D may fall back to treating DecalGroup node as an ordinary OrderedGroup node.

> ##### Constructors

>     public DecalGroup()

> Constructs and initializes a new DecalGroup node object.

> ## 5.6 Switch Node

> The Switch group node allows a Java 3D application to choose dynamically among a number of subgraphs. The Switch node contains an ordered list of children and a switch value. The switch value determines which child or children Java 3D will render. Note that the index order of children is used only for selecting the appropriate child or children-it does not specify rendering order.

> ##### Constants

>     public static final int ALLOW_SWITCH_READ
>     public static final int ALLOW_SWITCH_WRITE

> These flags, when enabled using the `setCapability` method, allow reading and writing of the values that specify the child-selection criteria. They are used only when the node is part of a live or compiled scene graph.

>     public static final int CHILD_NONE
>     public static final int CHILD_ALL
>     public static final int CHILD_MASK

> These values, when used in place of a nonnegative integer index value, indicate which children of the Switch node are selected for rendering. A value of `CHILD_NONE` indicates that no children are rendered. A value of `CHILD_ALL` indicates that all children are rendered, effectively making this Switch node operate as an ordinary Group node. A value of `CHILD_MASK` indicates that the `childMask` BitSet is used to select the children that are rendered.

> ##### Constructors

>     public Switch()

> Constructs a Switch node with default parameters:

> Parameters | Default Values
> --- | ---
> child selection index | CHILD_NONE
> child selection mask | false (for all children)

>     public Switch(int whichChild)
>     public Switch(int whichChild, BitSet childMask)

> These constructors initialize a new Switch node using the specified parameters.

> ##### Methods

> The Switch node class defines the following methods:

>     public void setWhichChild(int whichChild)
>     public int getWhichChild()

> These methods access or modify the index of the child that the Switch object will draw. The value may be a nonnegative integer, indicating a specific child, or it may be one of the following constants: `CHILD_NONE`, `CHILD_ALL`, or `CHILD_MASK`. If the specified value is out of range, then no children are drawn.

>     public void setChildMask(BitSet childMask)
>     public BitSet getChildMask()

> These methods access or modify the mask used to select the children that the Switch object will draw when the `whichChild` parameter is `CHILD_MASK`. This parameter is ignored during rendering if the `whichChild` parameter is a value other than `CHILD_MASK`.

>     public Node currentChild()

> This method returns the currently selected child. If `whichChild` is out of range, or is set to `CHILD_MASK`, `CHILD_ALL`, or `CHILD_NONE`, then `null` is returned.

> ## 5.7 SharedGroup Node

> A SharedGroup node provides a mechanism for sharing the same subgraph in different parts of the tree via a Link node. See Section 7.1.1, "SharedGroup Node," for a description of this node.

The Java 3D API Specification |

##### Copyright © 2000, Sun Microsystems, Inc. All rights reserved.