The Java 3D API Specification |
C H A P T E R2 |
Java 3D Concepts |
This chapter introduces Java 3D concepts and illustrates them with some simple program fragments. Appendix G, "The Example Programs" describes the examples included with the CD-ROM and highlights particular code segments for some examples.
2.1
A scene graph is a "tree" structure that contains data arranged in a hierarchical manner. The scene graph consists of parent nodes, child nodes, and data objects. The parent nodes, called Group nodes, organize and, in some cases, control how Java 3D interprets their descendants. Group nodes serve as the glue that holds a scene graph together. Child nodes can be either Group nodes or Leaf nodes. Leaf nodes have no children. They encode the core semantic elements of a scene graph- for example, what to draw (geometry), what to play (audio), how to illuminate objects (lights), or what code to execute (behaviors). Leaf nodes refer to data objects, called NodeComponent objects. NodeComponent objects are not scene graph nodes, but they contain the data that Leaf nodes require, such as the geometry to draw or the sound sample to play.Basic Scene Graph Concepts
2.1.1
The code shown in Listing 2-1 constructs a simple scene graph consisting of a group node and two leaf nodes. It first constructs one leaf node, the first of two Shape3D nodes, using a constructor that takes both a Geometry and an Appearance NodeComponent object. It then constructs the second Shape3D node, with only a Geometry object. Next, since the second Shape3D node was created without an Appearance object, it supplies the missing Appearance object using the Shape3D node'sConstructing a Simple Scene Graph setAppearance
method. At this point both leaf nodes have been fully constructed.
Listing 2-1 Code for Constructing a Simple Scene Graph
Shape3D myShape1 = new Shape3D(myGeometry1, myAppearance1); Shape3D myShape2 = new Shape3D(myGeometry2); myShape2.setAppearance(myAppearance2); Group myGroup = new Group(); myGroup.addChild(myShape1); myGroup.addChild(myShape2);
The code next constructs a group node to hold the two leaf nodes. It uses the Group node's
addChild
method to add the two leaf nodes as children to the group node, finishing the construction of the scene graph. Figure 2-1 shows the constructed scene graph, all the nodes, the node component objects, and the variables used in constructing the scene graph.
2.1.2
Once a scene graph has been constructed, the question becomes what to do with it? Java 3D cannot start rendering a scene graph until a program "gives" it the scene graph. The program does this by inserting the scene graph into the virtual universe.A Place For Scene Graphs
Figure 2-1 A Simple Scene Graph
Java 3D places restrictions on how a program can insert a scene graph into a universe.
A Java 3D environment consists of two superstructure objects, VirtualUniverse and Locale, and one or more graphs, rooted by a special BranchGroup node. Figure 2-2 shows these objects in context with other scene graph objects.
Figure 2-2 Content Branch, View Branch, and Superstructure
We could not insert the scene graph created by our simple example (Listing 2-1) into a Locale because it does not have a BranchGoup node for its root. Listing 2-2 shows a modified version of our first code example that creates a simple content branch graph and the minimum of superstructure objects. Of special note, Locales do not have children, and they are not part of the scene graph. The method for inserting a branch graph is
addBranchGraph
, whereasaddChild
is the method for adding children to all group nodes.
Listing 2-2 Code for Constructing a Scene Graph and Some Superstructure Objects
Shape3D myShape1 = new Shape3D(myGeometry1, myAppearance1); Shape3D myShape2 = new Shape3D(myGeometry2, myAppearance2); BranchGroup myBranch = new BranchGroup(); myBranch.addChild(myShape1); myBranch.addChild(myShape2); myBranch.compile(); VirtualUniverse myUniverse = new VirtualUniverse(); Locale myLocale = new Locale(myUniverse); myLocale.addBranchGraph(myBranch);
2.1.3
Most Java 3D programs build an identical set of superstructure and view branch objects, so the Java 3D utility packages provide aSimpleUniverse Utility universe
package for constructing and manipulating the objects in a view branch. The classes in theuniverse
package provide a quick means for building a single view (single window) application. Listing 2-3 shows a code fragment for using the SimpleUniverse class. Note that the SimpleUniverse constructor takes a Canvas3D as an argument, in this case referred to by the variablemyCanvas
.
Listing 2-3 Code for Constructing a Scene Graph Using the Universe Package
import com.sun.j3d.utils.universe.*; Shape3D myShape1 = new Shape3D(myGeometry1, myAppearance1); Shape3D myShape2 = new Shape3D(myGeometry2, myAppearance2); BranchGroup myBranch = new BranchGroup(); myBranch.addChild(myShape1); myBranch.addChild(myShape2); myBranch.compile(); SimpleUniverse myUniv = new SimpleUniverse(myCanvas); myUniv.addBranchGraph(myBranch);
2.1.4
When given a scene graph, Java 3D processes that scene graph as efficiently as possible. How a Java 3D implementation processes a scene graph can vary, as long as the implementation conforms to the semantics of the API. In general, a Java 3D implementation will render all visible objects, play all enabled sounds, execute all triggered behaviors, process any identified input devices, and check for and generate appropriate collision events.Processing a Scene Graph
2.2
Java 3D allows a programmer to specify a broad range of information. It allows control over the shape of objects, their color, and transparency. It allows control over background effects, lighting, and environmental effects such as fog. It allows control over the placement of all objects (even nonvisible objects such as lights and behaviors) in the scene graph and over their orientation and scale. It allows control over how those objects move, rotate, stretch, shrink, or morph over time. It allows control over what code should execute, what sounds should play, and how they should sound and change over time.Features of Java 3D
2.2.1
Bounds objects allow a programmer to define a volume in space. There are three ways to specify this volume: as a box, a sphere, or a set of planes enclosing a space.Bounds
2.2.2
All scene graph nodes have an implicit location in space of (0, 0, 0). For objects that exist in space, this implicit location provides a local coordinate system for that object, a fixed reference point. Even abstract objects that may not seem to have a well-defined location, such as behaviors and ambient lights, have this implicit location. An object's location provides an origin for its local coordinate system and, just as importantly, an origin for any bounding volume information associated with that object.Nodes
2.2.3
All scene graph objects, including nodes and node component objects, are either part of an active universe or not. An object is said to be live if it is part of an active universe. Additionally, branch graphs are either compiled or not. When a node is either live or compiled, Java 3D enforces access restrictions to nodes and node component objects. Java 3D allows only those operations that are enabled by the program before a node or node component becomes live or is compiled. It is best to set capabilities when you build your content. Listing 2-4 shows an example where we create a TransformGroup node and enable it for writing.Live and/or Compiled
Listing 2-4 Capabilities Example
TransformGroup myTrans = new TransformGroup(); myTrans.setCapability(Transform.ALLOW_TRANSFORM_WRITE);
By setting the capability to write the transform, Java 3D will allow the following code to execute:
myTrans.setTransform3D(myT3D);However, the following code will cause an exception:myTrans.getTransform3D(myT3D);The reason for the exception is that the TransformGroup is not enabled for reading (ALLOW_TRANSFORM_READ
).
The Java 3D API Specification
Copyright © 2000, Sun Microsystems, Inc. All rights reserved.