Contents Previous Next

Java 3D API Specification


C H A P T E R6
Reusing Scene Graphs




Java 3D provides application programmers with two different means for reusing scene graphs. First, multiple scene graphs can share a common subgraph. Second, the node hierarchy of a common subgraph can be cloned, while still sharing large component objects such as geometry and texture objects. In the first case, changes in the shared subgraph affect all scene graphs that refer to the shared subgraph. In the second case, each instance is unique-a change in one instance does not affect any other instance.

6.1 Sharing Subgraphs

An application that wishes to share a subgraph from multiple places in a scene graph must do so through the use of the Link leaf node and an associated SharedGroup node. The SharedGroup node serves as the root of the shared subgraph. The Link leaf node refers to the SharedGroup node. It does not incorporate the shared scene graph directly into its scene graph.

6.1.1 SharedGroup Node

A SharedGroup node allows multiple Link leaf nodes to share its subgraph (see Figure 6-1) according to the following semantics:

A shared subgraph may contain any group node, except an embedded SharedGroup node (SharedGroup nodes may not have parents). However, only the following Leaf nodes may appear in a shared subgraph:

An IllegalSharingException is thrown if any of following Leaf nodes appear in a shared subgraph:

Methods

The SharedGroup node defines the following method. 

public final void compile()

This method compiles the source SharedGroup associated with this object and creates and caches a newly compiled scene graph.

6.1.2 Link Leaf Node

The Link leaf node allows an application to reference a shared graph, rooted by a SharedGroup node, from within a branch graph or another shared graph. See Figure 6-1. Any number of Link nodes can refer to the same SharedGroup node.

Constants

The Link node object defines two flags. 

public static final int ALLOW_SHARED_GROUP_READ
public static final int ALLOW_SHARED_GROUP_WRITE

These flags, when enabled using the setCapability method, allow an application to invoke methods that respectively read and write the SharedGroup node pointed to by this Link node. These capability flags are enforced only when the node is part of a live or compiled scene graph.

Constructors

The Link node object defines two constructors. 

public Link()
public Link(SharedGroup sharedGroup)

The first form constructs a Link node object that does not yet point to a SharedGroup node. The second form constructs a Link node object that points to the specified SharedGroup node.

Methods

The Link node object defines two methods. 

public final void setSharedGroup(SharedGroup sharedGroup)
public final SharedGroup getSharedGroup()

These methods access and modify the SharedGroup node associated with this Link leaf node.

6.2 Cloning Subgraphs

An application developer may wish to reuse a common subgraph without completely sharing that subgraph. For example, the developer may wish to create a parking lot scene consisting of multiple cars, each with a different color. The developer might define three basic types of cars, such as convertible, truck, and sedan. To create the parking lot scene, the application will instance each type of car several times. Then the application can change the color of the various instances to create more variety in the scene. Unlike shared subgraphs each instance is a separate copy of the scene graph definition-changes to one instance do not affect any other instance.

Java 3D provides the cloneTree method for this purpose. The cloneTree method allows the programmer to change some attributes (NodeComponent objects) in a scene graph, while at the same time, sharing the majority of the scene graph data-the geometry.

Methods
public Node cloneTree()
public Node cloneTree(boolean forceDuplicate)
public Node cloneTree(boolean forceDuplicate,
       boolean allowDanglingReferences)

These methods start the cloning of the subgraph. The optional forceDuplicate parameter, when set to true, causes Leaf NodeComponent objects to ignore their duplicateOnCloneTree value and always be duplicated (see Section 6.2.1, "References To Node Component Objects"). The allowDanglingReferences parameter, when set to true, will permit the cloning of a subgraph even when a dangling reference is generated (see Section 6.2.3, "Dangling References"). Setting forceDuplicate and allowDanglingReferences to false is the equivalent of calling cloneTree without any parameters and results in Node Component objects being either duplicated or referenced in the cloned node, based on their duplicateOnCloneTree value and a DanglingReferenceException to be thrown if a dangling reference is encountered.

When the cloneTree method is called on a node, that node is duplicated along with all internal state. Then, if the node is a Group node, cloneTree is called on each of the node's children.

The cloneTree method cannot be called on a live or compiled scene graph.

6.2.1 References To Node Component Objects

When cloneTree reaches a Leaf node, there are two possible actions for handling the Leaf node's NodeComponent objects (such as Material, Texture, etc.). First, the cloned Leaf node can reference the original Leaf node's NodeComponent object-the NodeComponent object itself is not duplicated. Since the cloned Leaf node shares the NodeComponent object with the original Leaf node, changing the data in the NodeComponent object will effect a change in both nodes. This mode would also be used for objects that are read-only at runtime.

Alternatively, the NodeComponent object can be duplicated, in which case the new Leaf node would reference the duplicated object. This mode allows data referenced by the newly-created leaf node to be modified without that modification affecting the original leaf node.

In Figure 6-2, for example, two instances of NodeComponent objects are shared while one NodeComponent element was duplicated for the cloned subgraph.

Methods
public final void setDuplicateOnCloneTree(boolean)
public final void getDuplicateOnCloneTree()

These methods set a flag that controls whether a NodeComponent object is duplicated or referenced on a call to cloneTree.

By default this flag is false, meaning that the NodeComponent object will not be duplicated on a call to cloneTree-newly created leaf nodes will refer to the original NodeComponent object.

If the cloneTree method is called with the forceDuplicate parameter set to true, the duplicateOnCloneTree flag is ignored and the entire scene graph is duplicated.

6.2.2 References to Other Scene Graph Nodes

Leaf nodes that contain references to other nodes (e.g., Light nodes reference a Group node) can create a problem for the cloneTree method. After the cloneTree operation is performed the reference in the cloned Leaf node will still refer to the node in the original subgraph - a situation that is most likely incorrect (Figure 6-3).

To handle these ambiguities, a callback mechanism is provided.

A Leaf node that needs to update referenced nodes upon being duplicated by a call to cloneTree must implement the updateNodeReferences method. By using this method, the cloned Leaf node can determine if any nodes referenced by it have been duplicated and, if so, update the appropriate references to their cloned counterparts.

Suppose, for instance, that the Leaf node Lf1 in Figure 6-3 implemented the updateNodeReferences method. Once all nodes had been duplicated, the cloneTree method would then call each cloned Leaf's node updateNodeReferences method. When cloned Leaf node Lf2's method was called, Lf2 could ask if the Node N1 had been duplicated during the cloneTree operation. If the node had been duplicated, Leaf Lf2 could then update its internal state with the cloned Node, N2 (see Figure 6-4).

All predefined Java 3D nodes will automatically have their updateNodeReferences method defined. Only subclassed nodes that reference other nodes need to have this method overridden by the user.

Methods
public void updateNodeReferences(NodeReferenceTable 
       referenceTable)

This Leaf node method is called by the cloneTree method after all nodes in the subgraph have been cloned. The user can query the NodeReferenceTable object to determine if any Nodes that the Leaf node references have been duplicated by the cloneTree call and, if so, what the corresponding Node is in the new subgraph. If a user extends a predefined Java 3D object and adds a reference to another node, this method must be defined in order to ensure proper operation of the cloneTree method. The first statement in the user's updateNodeReferences method must be super.updateNodeReferences(referenceTable). For predefined Java 3D nodes, this method will be implemented automatically.

The NodeReferenceTable object is passed to the updateNodeReferences method and allows for references from the old subgraph to be translated into references in the cloned subgraph. The translation is performed by the getNewNodeReference method. 

public final Node getNewNodeReference(Node oldReference)

This method takes a reference to the node in the original subgraph as an input parameter and returns a reference to the equivalent node in the just-cloned subgraph. If the equivalent node in the cloned subgraph does not exist, either an exception is thrown or a reference to the original node is returned (see Section 6.2.3, "Dangling References").

6.2.3 Dangling References

Because cloneTree is able to start the cloning operation from any node, there is a potential for creating dangling references. A dangling reference can occur only when a Leaf node that contains a reference to another scene graph node is cloned. If the referenced node is not cloned, a dangling reference situation exists; there are now two Leaf nodes that access the same node (Figure 6-5). A dangling reference is discovered when a Leaf node's updateNodeReferences method calls the getNewNodeReference method and the cloned subgraph does not contain a counterpart to the node being looked up.

When a dangling reference is discovered, cloneTree can handle it two ways. If cloneTree is called without the allowDanglingReferences parameter set to true, a dangling reference will result in a DanglingReferenceException being thrown. The user can catch this exception if desired. If cloneTree is called with the allowDanglingReferences parameter set to true, the updateNodeReferences method will return a reference to the same object passed into the getNewNodeReference method. This will result in the cloneTree operation completing with dangling references as in Figure 6-5.

6.2.4 Subclassing Nodes

All Java 3D predefined nodes (i.e. Interpolators and LOD nodes), have all node reference operations and all node duplication operations handled automatically. When a user subclasses a Leaf or NodeComponent node, there are certain methods that must be provided in order to ensure the proper operation of cloneTree.

For Leaf node subclasses (i.e., Behaviors), if the subclass contains any user node-specific data that needs to be duplicated during a cloneTree operation, the following two methods must be defined: 

Node cloneNode(boolean forceDuplicate);
void duplicateNode(Node n, boolean forceDuplicate)

The cloneNode method consists of three lines: 

UserLeafNode un = new UserLeafNode();
un.duplicateNode(this, forceDuplicate);
return un;

The duplicateNode method must first call super.duplicateNode and then can duplicate any user-specific data or set any user-specific state as necessary.

For NodeComponent subclasses, if the subclass contains any user node specific data, the following two methods must be defined: 

NodeComponent cloneNodeComponent();
void duplicateNodeComponent(NodeComponent nc);

The cloneNodeComponent method consists of three lines: 

UserNodeComponent un = new UserNodeComponent();
un.duplicateNodeComponent(this);
return un;

The duplicateNodeComponent must first call super.duplicateNodeComponent and then can duplicate any user-specific data or set any user-specific state as necessary.

6.2.5 Example User Behavior Node

The following is an example user-defined Behavior object to show how to properly define a node to be compatible with the cloneTree operation. 

class RotationBehavior extends Behavior {
    TransformGroup objectTransform;
    WakeupOnElapsedFrames w;

    Matrix4d rotMat = new Matrix4d();
    Matrix4d objectMat = new Matrix4d();
    Transform3D t = new Transform();

    // Override Behavior's initialize method to setup wakeup
    // criteria
    public void initialize() {
        // Establish initial wakeup criteria
        wakeupOn(w);
   }

    // Override Behavior's stimulus method to handle the event
    public void processStimulus(Enumeration criteria) {
        // Rotate by another PI/120.0 radians
        objectMat.mul(objectMat, rotMat);
        t.set(objectMat);
        objectTransform.setTransform(t);

        // Set wakeup criteria for next time
        wakeupOn(w);
    }

    // Constructor for rotation behavior.
    public RotationBehavior(TransformGroup tg, int numFrames) {
        w = new WakeupOnElapsedFrames(numFrames);
        objectTransform = tg;
        objectMat.identity();

        // Create a rotation matrix that rotates PI/120.0
        // radians per frame
        rotMat.rotX(Math.PI/120.0);

        // Note: When this object is duplicated via cloneTree,
        // the cloned RotationBehavior node needs to point to
        // the TransformGroup in the just cloned tree.    
    }

    // sets a new TransformGroup.
    public void setTransformGroup(TransformGroup tg) {
        objectTransform = tg;
    }

    // the next two methods are needed for cloneTree to operate
    // correctly.

    // cloneNode is needed to provide a new instance of the user
    // derived subclass.
    public Node cloneNode(boolean forceDuplicate) {
        // get all data from current node needed for
        //the constructor
        int numFrames = w.getElapsedFrameCount();
        RotationBehavior r =
            new RotationBehavior(objectTransform, w);
        r.duplicateNode(this, forceDuplicate);
        return r;
    }

    // duplicateNode is needed to duplicate all super class
    // data as well as all user data.
    public void duplicateNode(Node n, boolean forceDuplicate) {
        super.duplicateNode(n, forceDuplicate);
        // nothing to do here - all unique data was handled
        // in the constructor in the cloneNode routine.
    }

    // callback for when this leaf is cloned. For this object
    // we want to find the cloned TransformGroup node that this
    // clone Leaf node should reference.
    public void updateNodeReferences(NodeReferenceTable t) {
        super.updateNodeReferences(t);

        // update node's TransformGroup to proper reference
        TransformGroup newTg =
            
(TransformGroup)t.getNewNodeReference(objectTransform);
        setTransformGroup(newTg);
    }

}


Contents Previous Next

Java 3D API Specification


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