The Java 3D API Specification Contents Previous Next Index


C H A P T E R5
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).

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:

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:

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: 

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 Contents Previous Next Index


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