Java 3D API - Behaviors and Interpolators

From f2b8bc72cac9b037636cae419b57219da7f42886 Mon Sep 17 00:00:00 2001 From: Kevin Rushforth Date: Wed, 26 Oct 2005 23:43:42 +0000 Subject: 1. Added package description. 2. Added introductory material from former specification guide (since that is no longer being maintained). 3. Put copyright notice at bottom of all javadoc pages. git-svn-id: https://svn.java.net/svn/j3d-core~svn/trunk@450 ba19aa83-45c5-6ac9-afd3-db810772062c --- src/classes/build.xml | 26 +- .../share/javax/media/j3d/doc-files/Behaviors.html | 11 + .../share/javax/media/j3d/doc-files/Concepts.html | 11 + .../share/javax/media/j3d/doc-files/DAG.gif | Bin 0 -> 19099 bytes .../javax/media/j3d/doc-files/HelloUniverse.html | 21 ++ .../share/javax/media/j3d/doc-files/Immediate.html | 11 + .../share/javax/media/j3d/doc-files/Rendering.html | 11 + .../media/j3d/doc-files/SceneGraphOverview.html | 230 +++++++++++++++ .../media/j3d/doc-files/SceneGraphSharing.html | 11 + .../share/javax/media/j3d/doc-files/ViewBranch.gif | Bin 0 -> 19210 bytes .../share/javax/media/j3d/doc-files/ViewModel.html | 12 + .../javax/media/j3d/doc-files/VirtualUniverse.html | 11 + .../share/javax/media/j3d/doc-files/intro.gif | Bin 0 -> 19452 bytes .../share/javax/media/j3d/doc-files/intro.html | 319 +++++++++++++++++++++ src/classes/share/javax/media/j3d/package.html | 34 +++ 15 files changed, 702 insertions(+), 6 deletions(-) create mode 100644 src/classes/share/javax/media/j3d/doc-files/Behaviors.html create mode 100644 src/classes/share/javax/media/j3d/doc-files/Concepts.html create mode 100644 src/classes/share/javax/media/j3d/doc-files/DAG.gif create mode 100644 src/classes/share/javax/media/j3d/doc-files/HelloUniverse.html create mode 100644 src/classes/share/javax/media/j3d/doc-files/Immediate.html create mode 100644 src/classes/share/javax/media/j3d/doc-files/Rendering.html create mode 100644 src/classes/share/javax/media/j3d/doc-files/SceneGraphOverview.html create mode 100644 src/classes/share/javax/media/j3d/doc-files/SceneGraphSharing.html create mode 100644 src/classes/share/javax/media/j3d/doc-files/ViewBranch.gif create mode 100644 src/classes/share/javax/media/j3d/doc-files/ViewModel.html create mode 100644 src/classes/share/javax/media/j3d/doc-files/VirtualUniverse.html create mode 100644 src/classes/share/javax/media/j3d/doc-files/intro.gif create mode 100644 src/classes/share/javax/media/j3d/doc-files/intro.html create mode 100644 src/classes/share/javax/media/j3d/package.html (limited to 'src/classes') diff --git a/src/classes/build.xml b/src/classes/build.xml index 1cd3cc1..cb166b3 100644 --- a/src/classes/build.xml +++ b/src/classes/build.xml @@ -192,7 +192,15 @@ - + + + + + + + @@ -201,6 +209,7 @@ javax.vecmath.*" maxmemory="128m" destdir="${build}/${platform}/javadocs/docs-jcp" + bottom="${javadoc.bottom}" windowtitle="Java 3D ${version}"> @@ -210,13 +219,14 @@ - + + - + @@ -241,6 +251,7 @@ maxmemory="128m" private="true" destdir="${build}/${platform}/javadocs/docs-private" + bottom="${javadoc.bottom}" windowtitle="Java 3D ${version}"> @@ -251,13 +262,14 @@ - + + - + @@ -271,6 +283,7 @@ com.sun.j3d.utils.scenegraph.io.state.*" maxmemory="128m" destdir="${build}/${platform}/javadocs/docs-public" + bottom="${javadoc.bottom}" windowtitle="Java 3D ${version}"> @@ -280,9 +293,10 @@ - + + diff --git a/src/classes/share/javax/media/j3d/doc-files/Behaviors.html b/src/classes/share/javax/media/j3d/doc-files/Behaviors.html new file mode 100644 index 0000000..f6c4d00 --- /dev/null +++ b/src/classes/share/javax/media/j3d/doc-files/Behaviors.html @@ -0,0 +1,11 @@ + + + + + Java 3D API - Behaviors and Interpolators + + +

Behaviors and Interpolators

+ + diff --git a/src/classes/share/javax/media/j3d/doc-files/Concepts.html b/src/classes/share/javax/media/j3d/doc-files/Concepts.html new file mode 100644 index 0000000..e445240 --- /dev/null +++ b/src/classes/share/javax/media/j3d/doc-files/Concepts.html @@ -0,0 +1,11 @@ + + + + + Java 3D API - Concepts + + +

Java 3D Concepts

+ + diff --git a/src/classes/share/javax/media/j3d/doc-files/DAG.gif b/src/classes/share/javax/media/j3d/doc-files/DAG.gif new file mode 100644 index 0000000..8479136 Binary files /dev/null and b/src/classes/share/javax/media/j3d/doc-files/DAG.gif differ diff --git a/src/classes/share/javax/media/j3d/doc-files/HelloUniverse.html b/src/classes/share/javax/media/j3d/doc-files/HelloUniverse.html new file mode 100644 index 0000000..5e37bd6 --- /dev/null +++ b/src/classes/share/javax/media/j3d/doc-files/HelloUniverse.html @@ -0,0 +1,21 @@ + + + + + HelloUniverse + + +

HelloUniverse: A Sample Java +3D Program

Here are 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. The +HelloUniverse class creates the branch graph +that includes the cube and the RotationInterpolator behavior. It then +adds this branch graph to the Locale object generated by the +SimpleUniverse utility. +



public class HelloUniverse ... {
    public BranchGroup createSceneGraph() {
        // Create the root of the branch graph
        BranchGroup objRoot = new BranchGroup();

        // Create the TransformGroup node and initialize it to the
        // identity. Enable the TRANSFORM_WRITE capability so that
        // our behavior code can modify it at run time. Add it to
        // the root of the subgraph.
        TransformGroup objTrans = new TransformGroup();
        objTrans.setCapability(
                TransformGroup.ALLOW_TRANSFORM_WRITE);
        objRoot.addChild(objTrans);

        // Create a simple Shape3D node; add it to the scene graph.
        objTrans.addChild(new ColorCube(0.4));

        // Create a new Behavior object that will perform the
        // desired operation on the specified transform and add
        // it into the scene graph.
        Transform3D yAxis = new Transform3D();
        Alpha rotationAlpha = new Alpha(-1, 4000);
        RotationInterpolator rotator = new RotationInterpolator(
                rotationAlpha, objTrans, yAxis,
                0.0f, (float) Math.PI*2.0f);
        BoundingSphere bounds =
            new BoundingSphere(new Point3d(0.0,0.0,0.0), 100.0);
        rotator.setSchedulingBounds(bounds);
        objRoot.addChild(rotator);

        // Have Java 3D perform optimizations on this scene graph.
        objRoot.compile();

        return objRoot;
    }

    public HelloUniverse() {
        <set layout of container, construct canvas3d, add canvas3d>

        // Create the scene; attach it to the virtual universe
        BranchGroup scene = createSceneGraph();
        SimpleUniverse u = new SimpleUniverse(canvas3d);
        u.getViewingPlatform().setNominalViewingTransform();
        u.addBranchGraph(scene);
    }
}

+ + diff --git a/src/classes/share/javax/media/j3d/doc-files/Immediate.html b/src/classes/share/javax/media/j3d/doc-files/Immediate.html new file mode 100644 index 0000000..ab85602 --- /dev/null +++ b/src/classes/share/javax/media/j3d/doc-files/Immediate.html @@ -0,0 +1,11 @@ + + + + + Java 3D API - Immediate-Mode Rendering + + +

Immediate-Mode Rendering

+ + diff --git a/src/classes/share/javax/media/j3d/doc-files/Rendering.html b/src/classes/share/javax/media/j3d/doc-files/Rendering.html new file mode 100644 index 0000000..580931a --- /dev/null +++ b/src/classes/share/javax/media/j3d/doc-files/Rendering.html @@ -0,0 +1,11 @@ + + + + + Java 3D API - Execution and Rendering Model + + +

Execution and Rendering Model

+ + diff --git a/src/classes/share/javax/media/j3d/doc-files/SceneGraphOverview.html b/src/classes/share/javax/media/j3d/doc-files/SceneGraphOverview.html new file mode 100644 index 0000000..f10b9a1 --- /dev/null +++ b/src/classes/share/javax/media/j3d/doc-files/SceneGraphOverview.html @@ -0,0 +1,230 @@ + + + + + Java 3D API - Scene Graph Overview + + +

Scene Graph Basics

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 always represent 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 +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. A group node can point to zero or more children but can have +only one parent. The SharedGroup node cannot have any parents (although +it allows sharing portions of a scene graph, as described in "Reusing Scene Graphs"). +Leaf node objects contain the actual definitions of shapes (geometry), +lights, fog, sounds, and so forth. A leaf node has no children and only +one parent. The semantics of the various group and leaf nodes are +described in subsequent chapters.

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

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. A group node also defines 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. +

Directed Acyclic Graph

Figure 1 – A Java +3D Scene Graph Is a DAG +(Directed Acyclic Graph)

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

This characteristic is in marked contrast to 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 graphics state, the change +affects the graphics 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 scale +of the objects below it.

Most graphics state attributes are set by a Shape3D leaf node +through +its constituent Appearance object, thus allowing 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).

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

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. Prior to attaching a subgraph +to a virtual +universe, the entire subgraph can be compiled into an +optimized, internal format (see the +BranchGroup.compile() +method).

An important characteristic of all scene graph objects is that +they can +be accessed or modified only 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.
+

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 +"Scene Graph Superstructure." +

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 "Scene Graph +Superstructure: VirtualUniverse Object," for more information. +

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. The 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 "Scene Graph Superstructure: Locale +Object," for more information).

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 the "View Model" +document.
+

Canvas3D Object

+The Canvas3D object encapsulates all of +the parameters associated with +the window being rendered into. +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. +

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

View Object

+The View object specifies information +needed to render the scene graph. +Figure +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. +All viewing parameters in Java 3D are directly contained either 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.

PhysicalBody Object

+The PhysicalBody object encapsulates all of the +parameters associated with the physical body, such as head position, +right and left eye position, and so forth. +

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

Viewing a Scene Graph +

Figure 2 – Viewing a Scene Graph

+ + diff --git a/src/classes/share/javax/media/j3d/doc-files/SceneGraphSharing.html b/src/classes/share/javax/media/j3d/doc-files/SceneGraphSharing.html new file mode 100644 index 0000000..ba707ef --- /dev/null +++ b/src/classes/share/javax/media/j3d/doc-files/SceneGraphSharing.html @@ -0,0 +1,11 @@ + + + + + Java 3D API - Reusing Scene Graphs + + +

Reusing Scene Graphs

+ + diff --git a/src/classes/share/javax/media/j3d/doc-files/ViewBranch.gif b/src/classes/share/javax/media/j3d/doc-files/ViewBranch.gif new file mode 100644 index 0000000..75cc40d Binary files /dev/null and b/src/classes/share/javax/media/j3d/doc-files/ViewBranch.gif differ diff --git a/src/classes/share/javax/media/j3d/doc-files/ViewModel.html b/src/classes/share/javax/media/j3d/doc-files/ViewModel.html new file mode 100644 index 0000000..b13bd37 --- /dev/null +++ b/src/classes/share/javax/media/j3d/doc-files/ViewModel.html @@ -0,0 +1,12 @@ + + + + + Java 3D API - View Model + + +

View Model +

+ + diff --git a/src/classes/share/javax/media/j3d/doc-files/VirtualUniverse.html b/src/classes/share/javax/media/j3d/doc-files/VirtualUniverse.html new file mode 100644 index 0000000..c4afb99 --- /dev/null +++ b/src/classes/share/javax/media/j3d/doc-files/VirtualUniverse.html @@ -0,0 +1,11 @@ + + + + + Java 3D API - Scene Graph Superstructure + + +

Scene Graph Superstructure

+ + diff --git a/src/classes/share/javax/media/j3d/doc-files/intro.gif b/src/classes/share/javax/media/j3d/doc-files/intro.gif new file mode 100644 index 0000000..503f818 Binary files /dev/null and b/src/classes/share/javax/media/j3d/doc-files/intro.gif differ diff --git a/src/classes/share/javax/media/j3d/doc-files/intro.html b/src/classes/share/javax/media/j3d/doc-files/intro.html new file mode 100644 index 0000000..ee53c66 --- /dev/null +++ b/src/classes/share/javax/media/j3d/doc-files/intro.html @@ -0,0 +1,319 @@ + + + + + The Java 3D API - Introduction + + +

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

NOTE: Prior to version 1.4, the +Java 3D API was formally specified by a +separate Java 3D API Specification Guide, published separately +from the javadoc. As of version 1.4, +the javadoc-generated API reference is definitive. Relevant portions of +the guide have been included here and supersede any previously +published +information. +

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." +

+ Application scene graph

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:

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:

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.

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

Behaviors and Interpolators

Java 3D Concepts

HelloUniverse: A Sample Java +3D Program

Immediate-Mode Rendering

Execution and Rendering Model

Scene Graph Basics

Scene Graph Structure

Spatial Separation

State Inheritance

Rendering

Scene Graph Objects

Scene Graph Superstructure +Objects

VirtualUniverse Object

Locale Object

Scene Graph Viewing Objects

Canvas3D Object

Screen3D Object

View Object

PhysicalBody Object

PhysicalEnvironment Object

Reusing Scene Graphs

View Model +

Scene Graph Superstructure

Introduction to the Java 3D API

Programming Paradigm

The Scene Graph Programming +Model

Rendering Modes

Immediate Mode

Retained Mode

Compiled-Retained Mode

Extensibility

High Performance

Layered Implementation

Target Hardware Platforms

Structuring the Java 3D Program

Java 3D Application Scene +Graph

Recipe for a Java 3D Program

HelloUniverse: A Sample Java +3D Program

Other Documents +

Other Documents
+