The Java 3D API Specification |
C H A P T E R3 |
Scene Graph Basics |
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 3-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 7, "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.
3.1
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.Scene Graph Structure
3.1.1
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.Spatial Separation
Figure 3-1 A Java 3D Scene Graph Is a DAG (Directed Acyclic Graph)
3.1.2
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 relies only 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.State Inheritance
3.1.3
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.Rendering
3.2
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 Scene graph objects are constructed by creating a new instance of the desired class and are accessed and manipulated using the object's
set
andget
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 4.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 5.2, "BranchGroup Node").
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 theALLOW_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. ARestricted-AccessException
is thrown if an application callssetCapability
orclearCap-ability
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.
3.2.1
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 5, "Group Node Objects" and Chapter 6, "Leaf Node Objects."Node Objects
Constants
Node object constants allow an application to enable runtime capabilities individually. These capability bits are enforced only when the node is part of a live or compiled scene graph.public static final int ALLOW_BOUNDS_READ public static final int ALLOW_BOUNDS_WRITEThese bits, when set using thesetCapability
method, specify that the node will permit an application to invoke thegetBounds
andsetBounds
methods, respectively. An application can choose to enable a particularset
method but not the associatedget
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_WRITEThese bits, when set using thesetCapability
method, specify that the node will permit an application to invoke thegetBoundsAutoCompute
andset-BoundsAutoCompute
methods, respectively. An application can choose to enable a particularset
method but not the associatedget
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_REPORTINGThis 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_WRITEThese flags specify that this Node can have its pickability read or changed.public static final int ENABLE_COLLISION_REPORTINGThis flag specifies that this Node will be reported in the collision SceneGraphPath if a collision occurs. This capability is specifiable only for Group nodes; it is ignored for Leaf nodes. The default for Group nodes is false. Only interior nodes that have this flag set to true will be reported in the SceneGraphPath (unless they are needed for uniqueness).public static final int ALLOW_COLLIDABLE_READ public static final int ALLOW_COLLIDABLE_WRITEThese flags specify that this Node allows read or write access to its collidability state.public static final int ALLOW_LOCAL_TO_VWORLD_READThis 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 boundsAutoCompute 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 Node getParent()Retrieves the parent of this node, ornull
if this node has no parent. This method is valid only during the construction of the scene graph. If this object is part of a live or compiled scene graph, aRestrictedAccessException
will be thrown.public Bounds getBounds() public void setBounds(Bounds bounds)These methods access or modify this node's geometric bounds.public void getLocalToVworld(Transform3D t) public 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 valid only 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 void setBoundsAutoCompute(boolean autoCompute) public 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 bysetBounds
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 offalse
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.
3.2.2
Node component objects include the actual geometry and appearance attributes used to render the geometry. These component objects are described in Chapter 8, "Node Component Objects."NodeComponent 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 duplicateOnCloneTree false
Methods
The following methods are available on NodeComponent objects:public void setDuplicateOnCloneTree(boolean duplicate) public boolean getDuplicateOnCloneTree()These methods access or modify theduplicateOnCloneTree
value of the NodeComponent object. TheduplicateOnCloneTree
value is used by thecloneTree
method to determine if NodeComponent objects should be duplicated or just referenced in the cloned leaf object.
3.3
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 4, "Scene Graph Superstructure."Scene Graph Superstructure Objects
3.3.1
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 4.6.1, "VirtualUniverse Object," for more information.VirtualUniverse Object
3.3.2
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.Locale Object 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 4.6.2, "Locale Object," for more information).
3.4
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 9, "View Model," and Appendix C, "View Model Details."Scene Graph Viewing Objects
3.4.1
The Canvas3D object encapsulates all of the parameters associated with the window being rendered into (see Section 9.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.Canvas3D Object
3.4.2
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 9.8, "The Screen3D Object").Screen3D Object
3.4.3
The View object specifies information needed to render the scene graph. Figure 3-2 shows a View object attached to a simple scene graph for viewing the scene.View Object The View object is the central Java 3D object for coordinating all aspects of viewing (see Section 9.7, "The View Object"). All viewing parameters in Java 3D are directly contained either 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.
3.4.4
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 9.10, "The PhysicalBody Object").PhysicalBody Object
3.4.5
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 9.11, "The PhysicalEnvironment Object").PhysicalEnvironment Object
Figure 3-2 Viewing a Scene Graph
The Java 3D API Specification |