Contents Previous Next

Java 3D API Specification


C H A P T E R4
Group Node Objects




Group nodes are the glue elements used in constructing a scene graph. The following subsections list the seven group nodes 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 associated with them an 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).

4.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). Operations on Group node objects include: adding, removing, and enumerating the children of the Group node. The subclasses of Group 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.

Constructors
public Group()

Constructs and initializes a Group node object.

Methods

The Group node class defines the following methods. 

public final int numChildren()
public final 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 final void setChild(Node child, int index)
public final void insertChild(Node child, int index)
public final void removeChild(int index)

The first method replaces the child at a 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 final Enumeration getAllChildren()

This method returns an Enumeration object of all children. 

public final void addChild(Node child)

This method extends this group by adding 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 Node cloneNode(boolean forceDuplicate)

This method duplicates the node as it were a single entity. This method does not duplicate children or the parent. 

public Node cloneTree(boolean forceDuplicate)

This method duplicates all nodes of the specified sub-graph. For Group Nodes, the group node is first duplicated via a call to cloneNode and then cloneTree is called for each child node. For Leaf Nodes, component data can either be duplicated or be made a reference to the original data. Leaf Node cloneTree behavior is determined by the duplicateOnCloneTree flag found in every Leaf Node's component data class and by the forceDuplicate parameter. 

public void duplicateNode(Node originalNode,
       boolean forceDuplicate)

This method copies all the node information from the originalNode into the current node. This method is called from the cloneNode method, which is in turn called by the cloneTree method.

For any NodeComponent objects contained by the object being duplicated, each NodeComponent object's duplicateOnCloneTree value is used to determine whether the NodeComponent should be duplicated in the new node or if just 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. 

public final 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: 

    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.

4.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 things 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.

Methods

The BranchGroup class defines the following methods. 

public final void compile()

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

public final void detach()

This method detaches the BranchGroup node from its parent.

4.3 TransformGroup Node

The TransformGroup node specifies a single spatial transformation that can position, orient, and scale all of its children. The specified transformation must be angle and length preserving-only rotation, translation and uniform scale are allowed in the scene graph. A BadTransformException is thrown (see Section D.1, "BadTransformException") if an attempt is made to specify an illegal Transform.

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 only used 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 transform, the second form initializes the node's Transform3D to a copy of the specified Transform.

Methods

The TransformGroup class defines the following methods. 

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

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

4.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) makes any use of the order of their children during rendering.

4.5 Coplanar Node

The Coplanar group node is a subclass of the OrderedGroup node. The Coplanar node specifies that its children generate coplanar objects. Java 3D renders the coplanar children in sequence order. (For example, decals, text on surfaces, or a checkerboard layered on top of a table.)

4.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/children Java 3D will render. Note that the index order of children is only used for selecting the appropriate child/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 the values that specify the child selection criteria. They are only used 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 non-negative 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()
public Switch(int whichChild)
public Switch(int whichChild, BitSet childMask)

These constructors initialize a new switch node using the specified parameters. The default values for those parameters not specified are as follows:

whichChild: CHILD_NONE
childMask: empty
Methods

The Switch node class defines the following methods. 

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

These methods access or modify the index of the child that the Switch object will draw. The value may be a non-negative 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 final void setChildMask(BitSet childMask)
public final 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 final 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.

4.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 6.1.1, "SharedGroup Node," for a description of this node.


Contents Previous Next

Java 3D API Specification


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