The Java 3D^TM API Specification Version 0.98

Java 3D^TM API Overview

Historically, 3D graphics programmers have needed to wring every last ounce of performance from their graphics hardware in order to obtain a high degree of visual realism. Developers have often had to leverage extensive knowledge of underlying hardware details in order to obtain maximum performance from a given graphics accelerator.

Even low-level cross-platform APIs, like OpenGL, have required a high degree of programming expertise in order to exact optimized performance from different hardware platforms. These realities have resulted in a difficult and expensive development process which has mandated platform-specific development efforts — leaving few resources to focus on application functionality.

A Platform Independent 3D API

Java 3D API represents an evolution to a standard, high-level 3D API that yields a high degree of interactivity while preserving true platform independence.

Java 3D^TM API Design Goals

Java 3D API was designed to satisfy the following goals:

• High Performance
  Many design decisions were made so that Java 3D API implementations could deliver the highest level of performance to application users. In particular, when trade-offs were made, the alternative that benefited runtime execution was chosen.
• Rich set of 3D features
  Java 3D API was designed to provide a rich set of features for creating interesting 3D worlds, tempered by the need to avoid non-essential or obscure features. Features that could be written in the Java programming language and layered on top of Java 3D API were not included.
• High-level, Object-oriented paradigm
  Java 3D API was designed to offer a high-level, object-oriented, programming paradigm that enables developers to rapidly deploy sophisticated applications and applets.
• Wide Variety of File Formats
  Support for run-time loaders was included to allow Java 3D API to accommodate a wide variety of file formats such as vendor-specific CAD formats, interchange formats, VRML 1.0, and VRML 2.0.

High Performance

The Java 3D API's scene graph programming model (described later in this document) allows the Java 3D API to perform mundane tasks (traversal of the scene graph, management of state attribute changes, etc.), thereby simplifying the job for the application. The Java 3D API does this without sacrificing performance.

At first glance, it might appear that this high-level approach would create more work for the API. However, it actually has the opposite effect. Java 3D API's higher level of abstraction not only changes the amount, but more importantly, the kind of work that the API must perform. Java 3D API is freed from the constraints found in interfaces with a lower level of abstraction and allows introduction of optimizations not possible with these lower-level APIs.

Additionally, leaving the details of rendering to Java 3D API allows it to tune the rendering to the underlying hardware. For example, relaxing the strict rendering order imposed by other APIs allows parallel traversal of the scene graph as well as parallel rendering. Knowing which parts of the scene graph cannot be modified at runtime allows Java 3D API to flatten the tree, pre-transform geometry, or represent the geometry in a native hardware format without the need to keep the original data.

Layered Implementation

Besides optimizations at the API level, one of the more important factors that determines the performance of the Java 3D API is the time it takes to render the visible geometry.

To optimize rendering, Java 3D API implementations are layered to take advantage of the native, low-level API that is available on a given system. In particular, Java 3D API implementations that utilize OpenGL, Direct3D API, and QuickDraw3D will be available. This means that Java 3D API rendering will be accelerated across the same wide range of systems that are supported by these lower-level APIs.

Target Hardware Platforms

Java 3D API is aimed at a wide range of 3D-capable hardware and software platforms, from low cost PC game cards and software renderers, through mid-range workstations, all the way up to very high-performance, specialized, 3D image generators.

It is expected that Java 3D API implementations will provide useful rendering rates on most modern PCs, especially those with 3D graphics accelerator cards. On mid-range workstations, Java 3D API is expected to provide applications with nearly full-speed hardware performance.

Finally, Java 3D API was 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 the high-priced workstations of a few years ago. Java 3D API is prepared to meet this increase in hardware performance.

Programming Paradigm

The Java 3D API provides several basic classes that are used to construct and manipulate a scene graph, and to control viewing and rendering. Details for the object hierarchies and classes which make up the scene graph and its component parts are provided in Chapter 3.

The Scene Graph Programming Model

The Java 3D API's scene graph-based programming model provides a simple and flexible mechanism for representing and rendering potentially complex 3D environments. The scene graph contains a complete description of the entire scene, or virtual universe. This includes the geometric data, the attribute information, and the viewing information needed to render the scene from a particular point of view.

The Java 3D API improves on previous graphics APIs by eliminating many of the bookkeeping and programming chores that those APIs impose. Java 3D API 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.

A Java 3D^TM API Application Scene Graph Example

Figure 2-1 illustrates a scene graph for a fairly simple application. For source code appropriate to this example, please see HelloUniverse.java in Appendix A.

The scene graph consists of superstructure components—a VirtualUniverse object and a Locale object—and scene graph branches, or subgraphs. Each subgraph is rooted by a BranchGroup node that is attached to the superstructure. For more information, see Chapter 3, “Scene Graph Overview.”

A VirtualUniverse object defines a named universe. The Java 3D API 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 APi scene graphs must connect to a Virtual Universe object to be displayed.

Below the VirtualUniverse object is a Locale object. The Locale object defines the origin, in high-resolution coordinates, of its attached subgraphs. 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, or branch graph, of the scene graph. Only BranchGroup objects can attach to Locales.

In the example in Figure 2-1, there are two subgraphs and, thus, two BranchGroup nodes. Attached to the left BranchGroup are two subtrees. One subtree consists of a user-extended Behavior leaf node which contains Java programming language code to manipulate the transform matrix associated with the object’s geometry.

The other subtree in this BranchGroup consists of a TransformGroup node that specifies the position (relative to the Locale), the orientation, and the scale of the geometric object in the virtual universe. A single child, a Shape3D 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, etc.).

The right BranchGroup has a single subtree that consists of a TransformGroup node and a ViewPlatform leaf node. The TransformGroup specifies the position (relative to the Locale), the orientation, and the 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 that Java 3D API renders into, the screen that contains the canvas, and information about the physical environment.

The Java 3D^TM API View Model

The Java 3D^TM API introduces a new view model that takes Java programming language's vision of “Write Once, Run Anywhere” and generalizes it to include display devices and six-degree-of-freedom input peripherals such as headtrackers.

An application or applet written using the Java 3D API view model can render images to a broad range of display devices including flat screen displays, portals/caves, and head-mounted displays all without modification to the code. The same application or applet, (once again without modification) can render stereoscopic views and can take advantage of the input from a head-tracker to control the rendered view.

Java 3D API's view model achieves this versatility by cleanly separating the virtual and the physical world. This model distinguishes between how an application positions, orients and scales a ViewPlatform object (a viewpoint) within the virtual world and how Java 3D API's renderer constructs the final view from that viewpoint’s position and orientation.

The application controls the ViewPlatform’s position and orientation while the renderer computes what view to render using this position and orientation, a description of the end-user’s physical environment, and the user’s position and orientation within the physical environment.

The Camera-Based Model

Most low-level APIs utilize a camera-based view model which emulates a camera in the virtual world. Developers must continuously reposition a simulated camera in such an API to emulate a human in the virtual world.

Camera-based view models give developers control over all rendering parameters. This control make sense when dealing with custom applications but is less useful when dealing with systems such as viewers or browsers that load and display whole worlds as a single unit, or that let their end-users view, navigate, display, and even interact with that world.

Making the application control all rendering parameters is problematic in systems where the physical environment dictates some of the view parameters: For example, a head-mounted display (HMD), where the optics of the head-mounted display directly determine the field-of-view that the application should use. Different HMDs have different optics, and hard-wiring such parameters into an application or allowing end-users to vary these parameters are poor solutions.

Additionally, view parameters change as a function of the user’s head position with an HMD. The specification of a world and a predefined flight path through that world may not exactly specify an end-user’s view should the user look to the side and change the view.
Java 3D API's view model incorporates the appropriate abstractions to compensate automatically for such variability in end-user hardware environments.

Camera-Based View Model Support
In order to assist with porting existing applications, the Java 3D API provides a compatibility mode which enables a camera-based view model. With a simple function-call, applications can enable compatibility mode for room-mounted, non head-tracked display environments.

It should be noted that use of these view compatibility functions will disable some of the Java 3D API's view model features and will limit portability.

Input

The java.awt package of classes already contains an abstraction for common desktop interaction peripherals like keyboards and mice. Java 3D API uses that implementation for simple devices rather than creating a separate, incompatible I/O model. However, since Java 3D API provides support for a variety of continuous input devices such as six-degree-of-freedom (6DOF) trackers and joysticks, a new input model was required.

For these time-critical devices, Java 3D API introduces a new real-time class of I/O device which provides for very low latency. In real-time graphics systems, low latency can be more important than missing an event since an event more than a few 30th’s of a second old may no longer be of any interest (particularly if it tracks a user’s current head position).

Java 3D API abstracts the idea of a tracking device or joystick in the form of a sensor. A sensor consists of a time-stamped sequence of input values and the state of any buttons or switches on the sensor at the time that Java 3D API sampled the value.

Behavior, Animation, and Picking

Behavior nodes provide the means for animating objects, processing keyboard and mouse inputs, reacting to movement, and enabling and processing pick events. Behavior nodes contain Java programming language code and state variables. The Java programming language code in a Behavior node can interact with Java objects, change node values within a Java 3D API scene graph, change internal state, and perform other computations.

Simple behaviors can add surprisingly interesting effects to a scene graph. For example, a rigid object can be animated by using a behavior node to repetitively modify the TransformGroup node that points to the object. Alternatively, a behavior node can track the current position of a mouse and modify portions of the scene graph to implement picking.

Behavior Object

A Behavior leaf node object contains a scheduling region and two methods: an initialization method called once when the behavior becomes “live” and a processStimulus method called whenever appropriate by the Java 3D API behavior scheduler. The behavior object will also contain whatever state information the Behavior code requires.

The scheduling region defines a spatial volume that serves to enable the scheduling of Behavior nodes. A Behavior node is active (can receive stimuli) whenever a ViewPlatform’s activation volume intersects a Behavior object’s scheduling region. Only active behaviors can receive stimuli.

The initialization method allows a behavior object to initialize its internal state and specify its initial wakeup condition(s). Java 3D API invokes a behavior’s initialization code when the behavior’s containing BranchGroup node is added to the virtual universe.

The processStimulus method receives and processes a behavior’s ongoing messages. Java 3D API invokes a behavior node’s processStimulus-method when a ViewPlatform’s activation volume intersects a behavior object’s scheduling region and one of the behavior’s wakeup criterion is satisfied. The processStimulus method performs its computations and actions (possibly including the registration of state change information that could cause Java 3D API to wake other behavior objects), establishes its wakeup conditions, and exits.

Scheduling

As a virtual universe grows large, Java 3D API must carefully husband its resources to ensure adequate performance. In a 10,000-object virtual universe with 400 or so behavior nodes, a naive implementation of Java 3D API could easily end up consuming the majority of its compute cycles by executing the behaviors associated with the 400 behavior objects before it draws a frame. In such a situation, the frame rate could easily drop to unacceptable levels.

Java 3D API mitigates the problem of a large number of behavior nodes in a high-population virtual universe through execution culling—choosing only to invoke those behaviors that have high relevance.

In a universe consisting of a large number of Behavior nodes controlling a similar number of objects, only a few of the controlled objects are typically visible at any one time. The sizeable fraction of the behavior nodes which are associated with non-visible objects, need never execute. The remaining, substantially smaller number of behavior objects associated with visible objects, must be executed.

Java 3D API requires each behavior to have a scheduling region and to post a wakeup condition. Together a behavior’s scheduling region and wakeup criterion provide Java 3D API's behavior scheduler with sufficient domain knowledge to selectively prune behavior invocations and only invoke those behaviors that absolutely need to execute.

Execution Culling
Java 3D API finds all scheduling regions associated with behavior nodes and constructs a scheduling-volume tree. It also creates an AND-OR tree containing all the behavior node wakeup criterion. These two data structures provide the domain knowledge Java 3D API needs to prune unneeded behavior execution.

Java 3D API must track a behavior’s activation conditions only if a ViewPlatform object’s activation volume intersects with that behavior object’s scheduling region. If the ViewPlatform object’s activation volume does not intersect with a behavior’s scheduling region, Java 3D API can safely ignore that behavior’s wakeup criterion.

In essence, the Java 3D API scheduler performs the following checks:

1. Find all Behavior objects with scheduling regions that intersect the ViewPlatform object’s activation volume.
   
2. For each Behavior object that falls within the ViewPlatform’s activation volume, check the Behavior’s WakupCondition
   
3. Schedule that behavior object for execution if the WakupCondition is true

Java 3D API's behavior scheduler executes those behavior objects that have been scheduled by calling the behavior’s processStimulus method.

Predefined Behaviors — Interpolators
Java 3D API provides a number of predefined behaviors. These predefined behaviors are known as Interpolators because they smoothly interpolate between a minimum and a maximum value.
The Java 3D API provides interpolators for a number of functions: for manipulating transformations within a TransformGroup, for modifying the values of a Switch node, and for modifying Material attributes such as color and transparency.

LOD Behaviors
The LOD (Level of Detail) behavior node is an abstract behavior class that operates on a list of Switch group nodes to select one of the children of the Switch node. Specializations of the LOD abstract behavior node implement various level-of-detail policies. For example, the Distance LOD behavior node implements a distance-based LOD policy by selecting one of the Switch nodes’ children based on distance from the viewer.

BillBoard Behaviors
The Billboard behavior node operates on a TransformGroup node to specify a transform that always aligns itself perpendicular to a specified world-coordinate axis or to a viewer’s view vector. This transform is independent of transforms above the specified node in the scene graph.

Billboard nodes provide the most benefit for complex, roughly-symmetric objects. In a typical application, a quadrilateral that contains a texture of a tree might be held perpendicular to the user.

Picking
Behavior nodes also provide the means for building developer-specific picking semantics. An application developer can define custom picking semantics using Java 3D API's behavior mechanism. For example, the developer might wish to define pick semantics that use a mouse to shoot a ray into the virtual universe from the current viewpoint, find the first object along that ray, and highlight that object when the user releases the mouse button.

Rendering Model, Rendering Modes, and Execution Path

Java 3D API assumes a double-buffered, true-color, and Z-buffered rendering model. This was done primarily to avoid creating multiple APIs and incompatible programs to support indexed and true color, or Z-buffered and non Z-buffered environments.

Note that this set of minimal requirements is for the Java 3D API rendering model, and does not necessarily describe hardware necessary to run a Java 3D API-based application. The rendering model simply describes Java 3D API's frame of reference and defines those properties that must be present in a low-level API in order to use it as a base for a Java 3D API implementation. How a low-level API implements that functionality is arbitrary to Java 3D API.

Rendering Modes

The Java 3D API includes three different rendering modes: immediate mode, retained mode, and compiled-retained mode. Each successive rendering mode allows Java 3D API more freedom in optimizing an application’s execution. Most Java 3D API applications will want to take advantage of the convenience and performance benefits that retained and compiled-retained modes provide.

• Immediate Mode
  Immediate mode leaves very little room for optimization. Even so, Java 3D API has raised the level of abstraction. An application must provide a Java 3D API draw method with a complete set of points, lines, or triangles. Of course, the application can build these lists of points, lines, or triangles in any manner it chooses.
  
• Retained Mode
  Retained mode requires an application to construct a scene graph and specify which elements of that scene graph may change during rendering. The scene graph describes the objects in the virtual universe, the arrangement of those objects, and how the application animates those objects.
  
• Compiled-Retained Mode
  Compiled-retained mode, like retained mode, requires the application to construct a scene graph and specify which elements of the scene graph may change during rendering. Additionally, the application can compile some, or all, of the subgraphs that make up a complete scene graph.

Java 3D API compiles these graphs into an internal format. The compiled representation of the scene graph bears little resemblance to the original tree structure provided by the application but is functionally equivalent.

Java 3D^TM API Runtime Execution Path

Once a Java 3D API program has been created, the following steps are taken by the program to create the scene graph elements and link them together. Java 3D API will then render the scene graph and display it in a window on the screen:

1. Create the Canvas3D and View objects.
2. Establish the virtual universe and high-res Locale
3. Construct the scene graph elements.
4. Link them together to form the two subgraphs.
5. Optionally compile the subgraphs.
6. Insert the two subgraphs into the Locale.

The Java 3D API renderer then starts running in an infinite loop. The renderer conceptually performs the following operations:

while(true) {

Process input
If (request to exit) break
Perform Behaviors
Traverse the scene graph and render visible objects

}
Cleanup and exit

An example Java 3D API program is provided in Appendix A.

Sound Model

Java 3D API uses Java technology's standard audio API in order to provide general sound and midi support. Because Java 3D API is the only Java API that includes support for headtrackers, parameterization of a user’s physical head, generalized transformations, and other such concepts, Java 3D API adds additional support for fully spatialized audio.

Vector Math Library

Java 3D API defines a number of additional objects that are used in the construction and manipulation of other Java 3D API objects. These objects provide low-level storage and manipulation control for users. They provide methods for representing vertex components (e.g., color and position), volumes, vectors, and matrices.

The tuple and matrix math classes are not part of Java 3D API per se, but they are needed by Java 3D API and are defined here for convenience. Java 3D API uses these classes internally and also makes them available for use by applications. These classes will be delivered in a separate java.vecmath package for use with other Java^TM technology-based APIs. The vector and matrix math classes are described in detail in an Appendix of the “Java 3D API Specification”.

Vector Objects

The Vector objects included in java.vecmath (listed in Table 2-1), store vectors of length two, three, and four. Java 3D API vectors are used to store various kinds of information such as colors, normals, texture coordinates, vertices, etc.

The classes are further subdivided by storage class, whether the vector consists of single or double precision floating point numbers or bytes. Only the floating-point vector classes support math operations.

Matrix Objects

The matrix objects, listed inTable 2-2, define a complete 3 ´ 3 or 4 ´ 4 floating-point transform matrix. All vector subclasses operate using this matrix type.

Geometry Compression

The Java 3D API allows programmers to specify geometry using a binary geometry compression format. This compression format is used with APIs other than just Java 3D API, and can be used both as a run-time in-memory format for describing geometry, as well as a storage and network format.

Using geometry compression allows geometry to be represented in an order of magnitude less space than most traditional 3D representations, with very little loss in object quality. Parameters exist to allow the user to trade off space versus quality by adjusting the degree of loss in the compression algorithm.

Like the vector mathematics library, geometry compression is provided with the Java 3D API specification but is likely to become its own specification over time. The Java 3D API geometry compression format is fully described in an appendix to the Java 3D API specification.

Continue to next chapter

Download the complete document in .pdf format for offline reading and printing