This guide, which contains documentation formerly published separately from the javadoc-generated API documentation, is not an official API specification. This documentation may contain references to Java and Java 3D, both of which are trademarks of Sun Microsystems, Inc. Any reference to these and other trademarks of Sun Microsystems are for explanatory purposes only. Their use does impart any rights beyond those listed in the source code license. In particular, Sun Microsystems retains all intellectual property and trademark rights as described in the proprietary rights notice in the COPYRIGHT.txt file.
The Java 3D API is an application programming interface used for writing three-dimensional graphics applications and applets. It gives developers high-level constructs for creating and manipulating 3D geometry and for constructing the structures used in rendering that geometry. Application developers can describe very large virtual worlds using these constructs, which provide Java 3D with enough information to render these worlds efficiently.
Java 3D delivers Java's "write once, run anywhere" benefit to developers of 3D graphics applications. Java 3D is part of the JavaMedia suite of APIs, making it available on a wide range of platforms. It also integrates well with the Internet because applications and applets written using the Java 3D API have access to the entire set of Java classes.
The Java 3D API draws its ideas from existing
graphics APIs and from
new technologies. Java 3D's low-level graphics constructs synthesize
the best ideas found in low-level APIs such as Direct3D, OpenGL,
QuickDraw3D, and XGL. Similarly, its higher-level constructs synthesize
the best ideas found in several scene graph-based systems. Java 3D
introduces some concepts not commonly considered part of the graphics
environment, such as 3D spatial sound. Java 3D's sound capabilities
help to provide a more immersive experience for the user.
The Java 3D API improves on previous graphics APIs by eliminating many of the bookkeeping and programming chores that those APIs impose. Java 3D allows the programmer to think about geometric objects rather than about triangles-about the scene and its composition rather than about how to write the rendering code for efficiently displaying the scene.
super.setXxxxx" for any attribute state set method that is overridden.
Applications can extend Java 3D's classes and add their own methods. However, they may not override Java 3D's scene graph traversal semantics because the nodes do not contain explicit traversal and draw methods. Java 3D's renderer retains those semantics internally.
Java 3D does provide hooks for mixing Java 3D-controlled scene graph rendering and user-controlled rendering using Java 3D's immediate mode constructs (see "Mixed-Mode Rendering"). Alternatively, the application can stop Java 3D's renderer and do all its drawing in immediate mode (see "Pure Immediate-Mode Rendering").
Behaviors require applications to extend the Behavior object and to override its methods with user-written Java code. These extended objects should contain references to those scene graph objects that they will manipulate at run time. The "Behaviors and Interpolators" document describes Java 3D's behavior model.
Additionally, leaving the details of rendering to Java 3D allows it to tune the rendering to the underlying hardware. For example, relaxing the strict rendering order imposed by other APIs allows parallel traversal as well as parallel rendering. Knowing which portions of the scene graph cannot be modified at run time allows Java 3D to flatten the tree, pretransform geometry, or represent the geometry in a native hardware format without the need to keep the original data.
Java 3D implementations are expected to provide useful rendering rates on most modern PCs, especially those with 3D graphics accelerator cards. On midrange workstations, Java 3D is expected to provide applications with nearly full-speed hardware performance.
Finally, Java 3D is designed to scale as the underlying hardware platforms increase in speed over time. Tomorrow's 3D PC game accelerators will support more complex virtual worlds than high-priced workstations of a few years ago. Java 3D is prepared to meet this increase in hardware performance.
This section illustrates how a developer might structure a Java 3D application. The simple application in this example creates a scene graph that draws an object in the middle of a window and rotates the object about its center point.
The scene graph for the sample application is shown below.
The scene graph consists of superstructure components—a VirtualUniverse object and a Locale object—and a set of branch graphs. Each branch graph is a subgraph that is rooted by a BranchGroup node that is attached to the superstructure. For more information, see "Scene Graph Basics."
A VirtualUniverse object defines a named universe. Java 3D permits the creation of more than one universe, though the vast majority of applications will use just one. The VirtualUniverse object provides a grounding for scene graphs. All Java 3D scene graphs must connect to a VirtualUniverse object to be displayed. For more information, see "Scene Graph Superstructure."
Below the VirtualUniverse object is a Locale object. The Locale object defines the origin, in high-resolution coordinates, of its attached branch graphs. A virtual universe may contain as many Locales as needed. In this example, a single Locale object is defined with its origin at (0.0, 0.0, 0.0).
The scene graph itself starts with the BranchGroup nodes. A BranchGroup serves as the root of a subgraph, called a branch graph, of the scene graph. Only BranchGroup objects can attach to Locale objects.
In this example there are two branch graphs and, thus, two BranchGroup nodes. Attached to the left BranchGroup are two subgraphs. One subgraph consists of a user-extended Behavior leaf node. The Behavior node contains Java code for manipulating the transformation matrix associated with the object's geometry.
The other subgraph in this BranchGroup consists of a TransformGroup node that specifies the position (relative to the Locale), orientation, and scale of the geometric objects in the virtual universe. A single child, a Shape3D leaf node, refers to two component objects: a Geometry object and an Appearance object. The Geometry object describes the geometric shape of a 3D object (a cube in our simple example). The Appearance object describes the appearance of the geometry (color, texture, material reflection characteristics, and so forth).
The right BranchGroup has a single subgraph that consists of a TransformGroup node and a ViewPlatform leaf node. The TransformGroup specifies the position (relative to the Locale), orientation, and scale of the ViewPlatform. This transformed ViewPlatform object defines the end user's view within the virtual universe.
Finally, the ViewPlatform is referenced by a View object that specifies all of the parameters needed to render the scene from the point of view of the ViewPlatform. Also referenced by the View object are other objects that contain information, such as the drawing canvas into which Java 3D renders, the screen that contains the canvas, and information about the physical environment.
The following steps are taken by the example program to create the scene graph elements and link them together. Java 3D will then render the scene graph and display the graphics in a window on the screen:
2. Create a BranchGroup as the root of the scene branch graph.
3. Construct a Shape3D node with a TransformGroup node above it.
4. Attach a RotationInterpolator behavior to the TransformGroup.
5. Call the simple universe utility function to do the following:
b. Create the PhysicalBody, PhysicalEnvironment, View, and ViewPlat-form objects.
c. Create a BranchGroup as the root of the view platform branch graph.
d. Insert the view platform branch graph into the Locale.
The Java 3D renderer then starts running in an infinite loop. The renderer conceptually performs the following operations:
If (request to exit) break
Traverse the scene graph and render visible objects
Cleanup and exit
Click here to see code fragments
from a simple program,
that creates a cube and a RotationInterpolator behavior object that
rotates the cube at a constant rate of pi/2 radians per second.
Here are other documents that provide explanatory material,
previously included as part of
the Java 3D API Specification Guide.