Java 3D API Specification

C H A P T E R2

A scene graph consists of Java 3D objects, called nodes, arranged in a tree structure. The user creates one or more scene subgraphs and attaches them to a virtual universe. The individual connections between Java 3D nodes always represent a directed relationship: parent to child. Java 3D restricts scene graphs in one major way: Scene graphs may not contain cycles. Thus, a Java 3D scene graph is a directed acyclic graph (DAG). See Figure 2-1.

Java 3D refines the Node object class into two subclasses: Group and Leaf node objects. Group node objects group together one or more child nodes. A group node can point to zero or more children but can have only one parent. The SharedGroup node cannot have any parents (although it allows sharing portions of a scene graph, as described in Chapter 6, "Reusing Scene Graphs"). Leaf node objects contain the actual definitions of shapes (geometry), lights, fog, sounds, and so forth. A leaf node has no children and only one parent. The semantics of the various group and leaf nodes are described in subsequent chapters.

2.1 Scene Graph Structure

A scene graph organizes and controls the rendering of its constituent objects. The Java 3D renderer draws a scene graph in a consistent way that allows for concurrence. The Java 3D renderer can draw one object independently of other objects. Java 3D can allow such independence because its scene graphs have a particular form and cannot share state among branches of a tree.

2.1.1 Spatial Separation

The hierarchy of the scene graph encourages a natural spatial grouping on the geometric objects found at the leaves of the graph. Internal nodes act to group their children together. A group node also defines a spatial bound that contains all the geometry defined by its descendants. Spatial grouping allows for efficient implementation of operations such as proximity detection, collision detection, view frustum culling, and occlusion culling.

Figure 2-1 A Java 3D Scene Graph Is a DAG (Directed Acyclic Graph)

2.1.2 State Inheritance

A leaf node's state is defined by the nodes in a direct path between the scene graph's root and the leaf. Because a leaf's graphics context only relies on a linear path between the root and that node, the Java 3D renderer can decide to traverse the scene graph in whatever order it wishes. It can traverse the scene graph from left to right and top to bottom, in level order from right to left, or even in parallel. The only exceptions to this rule are spatially bounded attributes such as lights and fog.

This characteristic is in marked contrast to many older scene graph-based APIs (including PHIGS and SGI's Inventor), where if a node above or to the left of a node changes the graphics state, the change affects the graphics state of all nodes below it or to its right.

The most common node object, along the path from the root to the leaf, that changes the graphics state is the TransformGroup object. The TransformGroup object can change the position, orientation, and scale of the objects below it.

Most graphics state attributes are set by a Shape3D leaf node through its constituent Appearance object, thus allowing parallel rendering. The Shape3D node also has a constituent Geometry object that specifies its geometry-this permits different shape objects to share common geometry without sharing material attributes (or vice versa).

2.1.3 Rendering

The Java 3D renderer incorporates all graphics state changes made in a direct path from a scene graph root to a leaf object in the drawing of that leaf object. Java 3D provides this semantic for both retained and compiled-retained modes.

2.2 Scene Graph Objects

A Java 3D scene graph consists of a collection of Java 3D node objects connected in a tree structure. These node objects reference other scene graph objects called node component objects. All scene graph node and component objects are subclasses of a common SceneGraphObject class. The SceneGraphObject class is an abstract class that defines methods that are common among nodes and component objects.

Scene graph objects are constructed by creating a new instance of the desired class and are accessed and manipulated using the object's set and get methods. Once a scene graph object is created and connected to other scene graph objects to form a subgraph, the entire subgraph can be attached to a virtual universe---via a high-resolution Locale object-making the object live (see Section 3.6.2, "Locale Object"). Prior to attaching a subgraph to a virtual universe, the entire subgraph can be compiled into an optimized, internal format (see Section 4.2, "BranchGroup Node").

An important characteristic of all scene graph objects is that they can only be accessed or modified during the creation of a scene graph, except where explicitly allowed. Access to most set and get methods of objects that are part of a live or compiled scene graph is restricted. Such restrictions provide the scene graph compiler with usage information it can use in optimally compiling or rendering a scene graph. Each object has a set of capability bits that enable certain functionality when the object is live or compiled. By default, all capability bits are disabled (cleared). Only those set and get methods corresponding to capability bits that are explicitly enabled (set) prior to the object being compiled or made live are legal. The methods for setting and getting capability bits are described next.

Constructors

The SceneGraphObject specifies one constructor.

public SceneGraphObject()

Constructs a new SceneGraphObject with default parameters:

Parameters	Default Values
capability bits	clear (all bits)
isLive	false
isCompiled	false
userData	null

Methods

The following methods are available on all scene graph objects.

public final boolean isCompiled()
public final boolean isLive()

The first method returns a flag that indicates whether the node is part of a scene graph that has been compiled. If so, only those capabilities explicitly allowed by the object's capability bits are allowed. The second method returns a flag that indicates whether the node is part of a scene graph that has been attached to a virtual universe via a high-resolution Locale object.

public final boolean getCapability(int bit)
public final void setCapability(int bit)
public final void clearCapability(int bit)

These three methods provide applications with the means for accessing and modifying the capability bits of a scene graph object. The bit positions of the capability bits are defined as public static final constants on a per-object basis. Every instance of every scene graph object has its own set of capability bits. An example of a capability bit is the ALLOW_BOUNDS_WRITE bit in node objects. Only those methods corresponding to capabilities that are enabled before the object is first compiled or made live are subsequently allowed for that object. A RestrictedAccessException is thrown if an application calls setCapability or clearCapability on live or compiled objects. Note that only a single bit may be set or cleared per method invocation-bits may not be ORed together.

public void setUserData(Object userData)
public Object getUserData()

These methods access or modify the userData field associated with this scene graph object. The userData field is a reference to an arbitrary object and may be used to store any user-specific data associated with this scene graph object-it is not used by the Java 3D API. If this object is cloned, the userData field is copied to the newly cloned object.

2.2.1 Node Objects

Node objects divide into group node objects and leaf node objects. Group nodes serve to group their child node objects together according to the group node's semantics. Leaf nodes specify the actual elements that Java 3D uses in rendering; specifically, geometric objects, lights, and sounds. These node objects are described in Chapter 4, "Group Node Objects" and Chapter 5, "Leaf Node Objects."

Constants

Node object constants allow an application to individually enable runtime capabilities. These capability bits are enforced only when the node is part of a live or compiled scene graph.

public static final int ALLOW_PICK

This is a deprecated capability bit. Use setPickable(boolean) instead.

public static final int ALLOW_BOUNDS_READ
public static final int ALLOW_BOUNDS_WRITE

These bits, when set using the setCapability method, specify that the node will permit an application to invoke the getBounds and setBounds methods, respectively. An application can choose to enable a particular set method but not the associated get method, or vice versa. The application can choose to enable both methods or, by default, leave the method(s) disabled.

public static final int ALLOW_AUTO_COMPUTE_BOUNDS_READ
public static final int ALLOW_AUTO_COMPUTE_BOUNDS_WRITE

These bits, when set using the setCapability method, specify that the node will permit an application to invoke the getBoundsAutoCompute and set-BoundsAutoCompute methods, respectively. An application can choose to enable a particular set method but not the associated get method, or vice versa. The application can choose to enable both methods or, by default, leave the method(s) disabled.

public static final int ENABLE_PICK_REPORTING

This flag specifies that this node will be reported in a SceneGraphPath. By default, this is disabled.

public static final int ALLOW_PICKABLE_READ
public static final int ALLOW_PICKABLE_WRITE

These flags specify that this Node can have its pickability read or changed.

public static final int ENABLE_COLLISION_REPORTING

This flag specifies that this Node will be reported in the collision SceneGraphPath if a collision occurs. This capability is only specifiable for Group nodes; it is ignored for Leaf nodes. The default for Group nodes is false. All interior nodes not needed for uniqueness in a SceneGraphPath that don't have this flag set to true will not be reported in the SceneGraphPath.

public static final int ALLOW_COLLIDABLE_READ
public static final int ALLOW_COLLIDABLE_WRITE

These flags specify that this Node allows read or write access to its collidability state.

public static final int ALLOW_LOCAL_TO_VWORLD_READ

This flag specifies that this node allows read access to its local-coordinates-to-virtual-world-(Vworld)-coordinates transform.

Constructors

The Node object specifies the following constructor.

public Node()

This constructor constructs and initializes a Node object with default values. The Node class provides an abstract class for all group and leaf nodes. It provides a common framework for constructing a Java 3D scene graph, specifically, bounding volumes. The default values are:

Parameters	Default Value
pickable	true
collidable	true
bounds autoCompute	true
bounds	N/A (automatically computed)

Methods

The following methods are available on Node objects, subject to the capabilities that are enabled for live or compiled nodes.

public final Node getParent()

Retrieves the parent of this node, or null if this node has no parent. This method is only valid during the construction of the scene graph. If this object is part of a live or compiled scene graph, a RestrictedAccessException will be thrown.

public final Bounds getBounds()
public final void setBounds(Bounds bounds)

These methods access or modify this node's geometric bounds.

public final void getLocalToVworld(Transform3D t)
public final void getLocalToVworld(SceneGraphPath path, 
       Transform3D t)

These methods access the local-coordinates-to-virtual-world-coordinates transform for this node and place the result into the specified Transform3D argument. The first form is used for nodes that are not part of a shared subgraph, the second form is used for nodes that are part of a shared subgraph. The local-coordinates-to-Vworld-coordinates transform is the composite of all transforms in the scene graph from the root down to this node (via the specified Link nodes, in the second case). It is only valid for nodes that are part of a live scene graph. An exception will be thrown if the node is not part of a live scene graph or if the appropriate capability is not set. Additionally, the first form will throw an exception if the node is part of a shared subgraph.

public final void setBoundsAutoCompute(boolean autoCompute)
public final boolean getBoundsAutoCompute()

These methods set and get the value that determines whether the node's geometric bounds are computed automatically, in which case the bounds will be read-only, or are set manually, in which case the value specified by setBounds will be used. The default is automatic.

public void setPickable(boolean pickable)
public boolean getPickable()

These methods set and retrieve the flag indicating whether this node can be picked. A setting of false means that this node and its children are all unpickable.

public void setCollidable(boolean collidable)
public boolean getCollidable()

The set method sets the collidable value. The get method returns the collidable value. This value determines whether this node and its children, if a group node, can be considered for collision purposes. If the value is false, neither this node nor any children nodes will be traversed for collision purposes. The default value is true. The collidable setting is the way that an application can perform collision culling.

public Node cloneNode(boolean forceDuplicate)

This method creates a new instance of the node. This routine is called by cloneTree to duplicate the current node. cloneNode should be overridden by any user-subclassed objects. All subclasses must have their cloneNode method consist of the following lines:

public Node cloneNode(boolean forceDuplicate) {

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

}

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 each NodeComponent object contained by the object being duplicated, the NodeComponent'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 Node cloneTree()
public Node cloneTree(boolean forceDuplicate)
public Node cloneTree(boolean forceDuplicate, 
       boolean  allowDanglingReference)

These methods duplicate all the nodes of the specified subgraph. Group nodes are 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. The forceDuplicate parameter, when set to true, causes the duplicateOnCloneTree flag to be ignored. The allowDanglingReferences flag, when set to true, allows the cloneTree method to complete even when a dangling reference is discovered. When this parameter is false, a DanglingReferenceException is generated as soon as cloneTree detects this situation.

2.2.2 NodeComponent Objects

Node component objects include the actual geometry and appearance attributes used to render the geometry. These component objects are described in Chapter 7, "Node Component Objects."

Constructors

The NodeComponent object specifies the following constructor.

public NodeComponent()

This constructor constructs and initializes a NodeComponent object with default parameters. The NodeComponent class provides an abstract class for all component objects. The default values are as follows:

Parameters	Default Value
duplicate on clone tree	false

Methods

The following methods are available on NodeComponent objects.

public void setDuplicateOnCloneTree(boolean duplicate)
public boolean getDuplicateOnCloneTree()

These methods access or modify the duplicateOnCloneTree value of the NodeComponent object. The duplicateOnCloneTree value is used by the cloneTree method to determine if NodeComponent objects should be duplicated or just referenced in the cloned leaf object.

public NodeComponent cloneNodeComponent()

This method creates a new instance of a NodeComponent object. This method is called by the cloneNode method to duplicate the current node. The cloneNodeComponent should be overridden by any user-subclassed NodeComponent objects. All subclasses must have their cloneNodeComponent method consist of the following lines:

public NodeComponent cloneNodeComponent() {

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

}

public void duplicateNodeComponent(NodeComponent 
       originalNodeComponent)

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

2.3 Scene Graph Superstructure Objects

Java 3D defines two scene graph superstructure objects, VirtualUniverse and Locale, which are used to contain collections of subgraphs that comprise the scene graph. These objects are described in more detail in Chapter 3, "Scene Graph Superstructure."

2.3.1 VirtualUniverse Object

A VirtualUniverse object consists of a list of Locale objects that contain a collection of scene graph nodes that exist in the universe. Typically, an application will need only one VirtualUniverse, even for very large virtual databases. Operations on a VirtualUniverse include enumerating the Locale objects contained within the universe. See Section 3.6.1, "VirtualUniverse Object," for more information.

2.3.2 Locale Object

The Locale object acts as a container for a collection of subgraphs of the scene graph that are rooted by a BranchGroup node. A Locale also defines a location within the virtual universe using high-resolution coordinates (HiResCoord) to specify its position. The HiResCoord serves as the origin for all scene graph objects contained within the Locale.

A Locale has no parent in the scene graph, but is implicitly attached to a virtual universe when it is constructed. A Locale may reference an arbitrary number of BranchGroup nodes, but has no explicit children.

The coordinates of all scene graph objects are relative to the HiResCoord of the Locale in which they are contained. Operations on a Locale include setting or getting the HiResCoord of the Locale, adding a subgraph, and removing a subgraph (see Section 3.6.2, "Locale Object," for more information).

2.4 Scene Graph Viewing Objects

Java 3D defines five scene graph viewing objects that are not part of the scene graph per se but serve to define the viewing parameters and to provide hooks into the physical world. These objects are Canvas3D, Screen3D, View, PhysicalBody, and PhysicalEnvironment. They are described in more detail in Chapter 8, "View Model," and Appendix C, "View Model Details."

2.4.1 Canvas3D Object

The Canvas3D object encapsulates all of the parameters associated with the window being rendered into (see Section 8.9, "The Canvas3D Object"). When a Canvas3D object is attached to a View object, the Java 3D traverser renders the specified view onto the canvas. Multiple Canvas3D objects can point to the same View object.

2.4.2 Screen3D Object

The Screen3D object encapsulates all of the parameters associated with the physical screen containing the canvas, such as the width and height of the screen in pixels, the physical dimensions of the screen, and various physical calibration values (see Section 8.8, "The Screen3D Object").

2.4.3 View Object

The View object specifies information needed to render the scene graph. Figure 2-2 shows a View object attached to a simple scene graph for viewing the scene.

Figure 2-2 Viewing a Scene Graph

The View object is the central Java 3D object for coordinating all aspects of viewing (see Section 8.7, "The View Object"). All viewing parameters in Java 3D are either directly contained within the View object or within objects pointed to by a View object. Java 3D supports multiple simultaneously active View objects, each of which can render to one or more canvases.

2.4.4 PhysicalBody Object

The PhysicalBody object encapsulates all of the parameters associated with the physical body, such as head position, right and left eye position, and so forth. (see Section 8.10, "The PhysicalBody Object").

2.4.5 PhysicalEnvironment Object

The PhysicalEnvironment object encapsulates all of the parameters associated with the physical environment, such as calibration information for the tracker base for the head or hand tracker (see Section 8.11, "The PhysicalEnvironment Object").

---

Java 3D API Specification

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