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.

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.

A SharedGroup node allows multiple Link leaf nodes to share its subgraph as shown in Figure 1 below.

Figure 1 – Sharing a Subgraph

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 instantiate 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.

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, and so forth). 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 run time.

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.

Figure 2 shows two instances of NodeComponent objects that are shared and one NodeComponent element that is duplicated for the cloned subgraph.

Figure 2 – Referenced and Duplicated NodeComponent Objects

References to Other Scene Graph Nodes

To handle these ambiguities, a callback mechanism is provided.

Figure 3 – References to Other Scene Graph Nodes

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 3 implemented the updateNodeReferences method. Once all nodes had been duplicated, the clone-Tree 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 4).

Figure 4 – Updated Subgraph after updateNodeReferences Call

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.

Dangling References

Figure 5 – Dangling Reference: Bold Nodes Are Being Cloned

When a dangling reference is discovered, cloneTree can handle it in one of 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 update-NodeReferences 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 5.

Subclassing Nodes

Leaf node subclasses (for example, Behaviors) that contain any user node-specific data that needs to be duplicated during a cloneTree operation must define the following two methods:

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

UserSubClass usc = new UserSubClass();
usc.duplicateNode(this, forceDuplicate);
return usc;

NodeComponent subclasses that contain any user node-specific data must define the following two methods:

NodeComponent cloneNodeComponent();
void duplicateNodeComponent(NodeComponent nc, boolean forceDuplicate);

UserNodeComponent unc = new UserNodeComponent();
unc.duplicateNodeComponent(this, forceDuplicate);
return un;

NodeReferenceTable Object

Example: User Behavior Node

class RotationBehavior extends Behavior {
    TransformGroup objectTransform;
    WakeupOnElapsedFrames w;

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

    // Override Behavior's initialize method to set up 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.setIdentity();

        // 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, numFrames);
        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 originalNode, boolean 
     forceDuplicate) {
        super.duplicateNode(originalNode, 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.getNewObjectReference(
            objectTransform);
        setTransformGroup(newTg);
    }
}