javax.media.j3d.doc-files.intro.html Maven / Gradle / Ivy
The Java 3D API - Introduction
Disclaimer
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.
Introduction to the Java 3D API
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.
Programming Paradigm
Java 3D is an object-oriented API. Applications construct individual
graphics elements as separate objects and connect them together into a
treelike structure called a scene graph. The application
manipulates these objects using their predefined accessor, mutator, and
node-linking methods.
The Scene Graph Programming
Model
Java 3D's scene graph-based programming model provides a simple and
flexible mechanism for representing and rendering scenes. 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 "Scene
Graph Basics" document provides more information on the Java 3D
scene graph programming model.
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.
Rendering Modes
Java 3D includes three different rendering modes: immediate mode,
retained mode, and compiled-retained mode (see "Execution
and Rendering Model").
Each successive rendering mode allows Java 3D more freedom in
optimizing an application's execution. Most Java 3D applications will
want to take advantage of the convenience and performance benefits that
the retained and compiled-retained modes provide.
Immediate Mode
Immediate mode leaves little room for global
optimization at the scene graph level. Even so, Java 3D has raised the
level of abstraction and accelerates immediate mode rendering on a
per-object basis. An application must provide a Java 3D draw method
with a complete set of points, lines, or triangles, which are then
rendered by the high-speed Java 3D renderer. 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 compiles these graphs into an internal format. The compiled
representation of the scene graph may bear little resemblance to the
original tree structure provided by the application, however, it is
functionally equivalent. Compiled-retained mode provides the highest
performance.
Extensibility
Most Java 3D classes expose only accessor and mutator methods. Those
methods operate only on that object's internal state, making it
meaningless for an application to override them. Therefore, Java 3D
does not provide the capability to override the behavior of Java 3D
attributes. To make Java 3D work correctly, applications must call "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.
High Performance
Java 3D's programming model allows the Java 3D API to do the mundane
tasks, such as scene graph traversal, managing attribute state changes,
and so forth, thereby simplifying the application's job. Java 3D does
this without sacrificing performance. At first glance, it might appear
that this approach would create more work for the API; however, it
actually has the opposite effect. Java 3D's higher level of abstraction
changes not only the amount but, more important, also the kind of work
the API must perform. Java 3D does not need to impose the same type of
constraints as do APIs with a lower level of abstraction, thus allowing
Java 3D to introduce optimizations not possible with these lower-level
APIs.
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.
Layered Implementation
Besides optimizations at the scene graph level, one of the more
important factors that determines the performance of Java 3D is the
time it takes to render the visible geometry. Java 3D implementations
are layered to take advantage of the native, low-level API that is
available on a given system. In particular, Java 3D implementations
that use Direct3D and OpenGL are available. This means that Java 3D
rendering will be accelerated across the same wide range of systems
that are supported by these lower-level APIs.
Target Hardware Platforms
Java 3D is aimed at a wide range of 3D-capable hardware and software
platforms, from low-cost PC game cards and software renderers at the
low end, through midrange workstations, all the way up to very
high-performance specialized 3D image generators.
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.
Structuring the Java 3D Program
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.
Java 3D Application Scene
Graph
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."
Figure 1 – Application Scene Graph
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.
Recipe for a Java 3D Program
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:
1. Create a Canvas3D object and add it to the Applet panel.
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:
a. Establish a virtual universe with a single high-resolution Locale
(see "Scene Graph Basics").
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.
6. Insert the scene branch graph into the simple universe's Locale.
The Java 3D 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
HelloUniverse: A Sample Java
3D Program
Click here to see code fragments
from a simple program, HelloUniverse.java,
that creates a cube and a RotationInterpolator behavior object that
rotates the cube at a constant rate of pi/2 radians per second.
Other Documents
Here are other documents that provide explanatory material,
previously included as part of
the Java 3D API Specification Guide.
- Java 3D Concepts
- Scene Graph Basics
- Scene Graph Superstructure
- Reusing Scene Graphs
- View Model
- Behaviors and Interpolators
- Execution and Rendering Model
- Immediate-Mode Rendering
