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 are always 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. The semantics of the various Group nodes are described in Chapter 4, "Group Node Objects." A group node can point to zero or more children but can have only one parent. The SharedGroup and Definition group nodes may not have any parents (although both allow 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, etc. The semantics of the various Leaf nodes are described in Chapter 5, "Leaf Node Objects." A leaf node has no children and only one parent.

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

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. Group nodes also define 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.

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, level order from right to left, or even in parallel. The only exception to this is spatially bounded attributes such as lights and fog.

This is in marked contrast with 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 graphic state, the change affects the graphic 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/or scale of the objects below it.

Most graphics state is set by a Shape3D leaf node through its constituent Appearance object. This allows for 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"). 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 below.

Constructors

The SceneGraphObject specifies one constructor.

public SceneGraphObject()

Constructs a new SceneGraphObject.

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

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 bit enables picking for a particular Node. By default, picking is disabled.

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.

Constructors

The Node object specifies the following constructor.

public Node()

This constructor constructs and initializes a Node object. 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.

Methods

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

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

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

---

Note: There will also be a method for controlling whether the bounds is computed automatically, in which case the bounds will be read-only, versus manually, in which case the value specified by setBounds will be used. The exact details of this API has not yet been finalized. The default will be automatic.

---

public Node cloneTree()
public Node cloneTree(boolean forceDuplicate)

These methods clone the entire tree structure of a subgraph. A reference to the new graph is returned. For Group Nodes, the group node is duplicated 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. See Section 6.2, "Cloning Subgraphs," for details.

public Node cloneNode(boolean forceDuplicate)

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

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.

2.2.2 Node Component 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. The NodeComponent class provides an abstract class for all component objects.

Methods

The following methods are available on NodeComponent objects.

public void setDuplicateOnCloneTree(boolean duplicate)
public boolean getGetDuplicateOnCloneTree()

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 cloneComponent()

This method creates a new instance of a NodeComponent object. This method is called by the cloneNode method to dusplicate 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," 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. This 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," 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, "The Java 3D View Model," and Appendix C, "View Model Implementation 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.

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.

Figure 2-2 Viewing a Scene Graph

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, etc. (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 © 1997, Sun Microsystems, Inc. All rights reserved.