Immediate Mode Rendering

Java 3D API Specification

Java 3D is fundamentally a scene-graph-based API. Most of the constructs in the API are biased toward retained mode and compiled-retained mode rendering. However, there are some applications that want both the control and the flexibility that immediate-mode rendering offers.
Immediate mode applications can either use or ignore Java 3D's scene graph structure. By using immediate mode, end-user applications have more freedom, but this freedom comes at the expense of performance. In immediate mode, Java 3D has no high-level information concerning graphical objects or their composition. Because it has minimal global knowledge, Java 3D can only perform localized optimizations on behalf of the application programmer.

12.1 Two Styles of Immediate Mode

Use of Java 3D's immediate mode falls into one of two categories: pure immediate-mode rendering and mixed-mode rendering where immediate mode and retained or compiled-retained mode inter-operate and render to the same canvas. The Java 3D renderer does not run in pure immediate mode, distinguishing it from mixed-mode rendering.

12.1.1 Pure Immediate Mode Rendering

Pure immediate-mode rendering provides for those applications and applets that do not want Java 3D to do any automatic rendering of the scene graph. Such applications may not even wish to build a scene graph to represent their graphical data. However, they use Java 3D's attribute objects to set graphics state and Java 3D's geometric objects to render geometry.
A pure immediate mode application must create a minimal set of Java 3D objects before rendering. In addition to a Canvas3D object, the application must create a View object, with its associated PhysicalBody and PhysicalEnvironment objects, and the following scene graph elements: a VirtualUniverse object, a high-resolution Locale object, a BranchGroup node object, a TransformGroup node object with associated transform and, finally, a ViewPlatform leaf node object that defines the position and orientation within the virtual universe that generates the view (see Figure 12-1).

Figure 12-1 Minimal Immediate Mode Structure

Java 3D provides utility functions that create much of this structure on behalf of a pure immediate mode application, making it less noticeable from the application's perspective-but the structure must exist.
All rendering is done completely under user control. It is necessary for the user to clear the 3D canvas, render all geometry, and swap the buffers. Additionally, rendering the right and left eye for stereo viewing becomes the sole responsibility of the application.
In pure immediate mode, the user should stop the Java 3D renderer, via the stopRenderer() method of the Canvas3D object, prior to adding the Canvas3D object to an active View object (i.e., one that is attached to a live ViewPlatform object).

12.1.2 Mixed Mode Rendering

Mixing immediate mode and retained or compiled-retained mode requires more structure than pure immediate mode. In mixed mode, the Java 3D renderer is running continuously, rendering the scene graph into the canvas. The basic Java 3D stereo rendering loop, executed for each Canvas3D, is as follows:
clear canvas (both eyes)
call preRender()                      /* user-supplied method */
set left eye view
render opaque scene graph objects
call renderField(FIELD_LEFT)          /* user-supplied method */
render transparent scene graph objects
set right eye view
render opaque scene graph objects again
call renderField(FIELD_RIGHT)         /* user-supplied method */
render transparent scene graph objects again
call postRender()                     /* user-supplied method */
synchronize and swap buffers
call postSwap()                       /* user-supplied method */
The basic Java 3D mono rendering loop is as follows:
clear canvas
call preRender()                      /* user-supplied method */
set view
render opaque scene graph objects
call renderField(FIELD_ALL)           /* user-supplied method */
render transparent scene graph objects
call postRender()                     /* user-supplied method */
synchronize and swap buffers
call postSwap()                       /* user-supplied method */
In both cases, the entire loop, beginning with clearing the canvas and ending with swapping the buffers, defines a frame. The application is given the opportunity to render immediate-mode geometry at any of the clearly-identified spots in the rendering loop. A user specifies his or her own rendering methods by extending the Canvas3D class and overriding the preRender, postRender, postSwap, and/or renderField methods.

12.2 Canvas3D Methods

The Canvas3D methods that directly affect immediate mode rendering are described here.
When a Canvas3D is created, it is initially marked as being started. This means that as soon as the Canvas3D is added to an active View object, the rendering loop will render the scene graph to the canvas. In pure immediate mode the renderer must be stopped prior to adding the canvas to an active View object.

Constants
public static final int FIELD_LEFT
public static final int FIELD_RIGHT
public static final int FIELD_ALL
These constants specify the field that the rendering loop for this Canvas3D is rendering. The FIELD_LEFT and FIELD_RIGHT values indicate the left and right fields of a field-sequential stereo rendering loop, respectively. The FIELD_ALL value indicates a monoscopic or single pass stereo rendering loop.

Methods
public final GraphicsContext3D getGraphicsContext3D()
This method retrieves the immediate mode 3D graphics context associated with this Canvas3D. It creates a new graphics context if one does not already exist. It returns a GraphicsContext3D object that can be used for immediate mode rendering to this Canvas3D.
public void preRender()
Applications that wish to perform operations in the rendering loop, prior to any actual rendering, must override this method. The Java 3D rendering loop invokes this method after clearing the canvas and before any rendering has been done for this frame.
public void postRender()
Applications that wish to perform operations in the rendering loop, following any actual rendering, must override this method. The Java 3D rendering loop invokes this method after completing all rendering to the canvas for this frame and before the buffer swap.
public void postSwap()
Applications that wish to perform operations at the very end of the rendering loop must override this method. The Java 3D rendering loop invokes this method after completing all rendering to this canvas, and all other canvases associated with the current view, for this frame following the buffer swap.
public void renderField(int fieldDesc)
Applications that wish to perform operations during the rendering loop must override this function. The Java 3D rendering loop invokes this method, possibly twice, during the loop. It is called once for each field (once per frame on a mono system or once each for the right eye and left eye on a field-sequential stereo system). This method is called after all opaque objects are rendered and before any transparent objects are rendered (subject to restrictions imposed by OrderedGroup nodes). This is intended for use by applications that want to mix retained/compiled-retained mode rendering with some immediate mode rendering. The fieldDesc parameter is the field description, one of: FIELD_LEFT, FIELD_RIGHT, or FIELD_ALL. Applications that wish to work correctly in stereo mode should render the same image for both FIELD_LEFT and FIELD_RIGHT calls. If Java 3D calls the renderer with FIELD_ALL, the immediate mode rendering only needs to be done once.
public final void startRenderer()
public final void stopRenderer()
These methods start or stop the Java 3D renderer for this Canvas3D object. In the case of stopRenderer, if the Java 3D renderer is currently running the rendering will be synchronized before being stopped. No further rendering will be done to this canvas by Java 3D until the renderer is started again. In the case of startRenderer, if the Java 3D renderer is not currently running, any rendering to other Canvas3D objects sharing the same View will be synchronized before this Canvas3D's renderer is (re)started.
public final void swap()
This method synchronizes and swaps buffers on a double-buffered canvas for this Canvas3D object. This method may only be called if the Java 3D renderer has been stopped. In the normal case, the renderer automatically swaps the buffer. If the application invokes this method and the canvas has a running Java 3D renderer, an exception is thrown.

12.3 API for Immediate Mode

Java 3D's immediate mode allows an application to directly set attributes and draw three-dimensional geometry using the same objects as in Java 3D scene graphs. An immediate-mode application renders by passing these objects to the set and draw methods of a GraphicsContext3D object.

12.3.1 GraphicsContext3D

The GraphicsContext3D object is used for immediate-mode rendering into a 3D canvas. It is created by, and associated with, a specific Canvas3D object. A GraphicsContext3D defines methods that manipulate 3D graphics state and draw 3D geometric primitives.

Constructors

There are no publicly-accessible constructors of GraphicsContext3D. An application obtains a 3D graphics context object from the Canvas3D object that the application wishes to render into by using the getGraphicsContext3D method.
The Canvas3D object creates a new GraphicsContext3D the first time an application invokes getGraphicsContext3D. A new GraphicsContext3D initializes its state variables to the following defaults:

Background object: null
Fog object: null
Appearance object: null
List of Light objects: empty
high-res coordinate: (0, 0, 0)
modelTransform: identity
AuralAttributes object: null
List of Sound objects: empty

Methods
public final Canvas3D getCanvas3D()
This method gets the Canvas3D that created this GraphicsContext3D.
public final void setAppearance(Appearance appearance)
public final Appearance getAppearance()
These methods access or modify the current Appearance component object used by this 3D graphics context. The graphics context stores a reference to the specified Appearance object. This means that the application may modify individual appearance attributes by using the appropriate methods on the Appearance object (see Section 7.1.1, "Appearance Object"). The Appearance component object must not be part of a live scene graph, nor may it subsequently be made part of a live scene graph. If the Appearance object is null, default values will be used for all appearance attributes-it is as if an Appearance node was created using the default constructor.
public final void setBackground(Background background)
public final Background getBackground()
These methods access or modify the current Background leaf node object used by this 3D graphics context. The graphics context stores a reference to the specified Background node. This means that the application may modify the background color or image by using the appropriate methods on the Background node object (see Section 5.4, "Background Node"). The Background node must not be part of a live scene graph, nor may it subsequently be made part of a live scene graph. If the Background object is null, the default background color of black (0,0,0) will be used to clear the canvas prior to rendering a new frame. The Background node's application region is ignored for immediate-mode rendering.
public final void setFog(Fog fog)
public final Fog getFog()
These methods access or modify the current Fog leaf node object used by this 3D graphics context. The graphics context stores a reference to the specified Fog node. This means that the application may modify the fog attributes by using the appropriate methods on the Fog node object (see Section 5.6, "Fog Node"). The Fog node must not be part of a live scene graph, nor may it subsequently be made part of a live scene graph. If the Fog object is null, fog is disabled. Both the region of influence and the hierarchical scope of the Fog node are ignored for immediate mode rendering.
public final void addLight(Light light)
public final void insertLight(Light light, int index)
public final void setLight(Light light, int index)
public final Light getLight(int index)
public final void removeLight(int index)
public final int numLights()
public final Enumeration getAllLights()
These methods access or modify the list of lights used by this 3D graphics context. The addLight method adds a new light to the end of the list of lights. The insertLight method inserts a new light before the light at the specified index. The setLight method replaces the light at the specified index with the light provided. The removeLight method removes the light at the specified index. The numLights method returns a count of the number of lights in the list. The getLight method returns the light at the specified index. The getAllLights method retrieves the enumeration object of all lights.
The graphics context stores a reference to each light object in the list of lights. This means that the application may modify the light attributes for any of the lights by using the appropriate methods on that Light node object (see Section 5.7, "Light Node"). None of the Light nodes in the list of lights may be part of a live scene graph, nor may they subsequently be made part of a live scene graph. It is an error to add a null Light object to the list. If the list of lights is empty, lighting is disabled. Both the region of influence and the hierarchical scope of all lights in the list are ignored for immediate mode rendering.
public void setHiRes(int x[], int y[], int z[])
public void setHiRes(HiResCoord hiRes)
public void getHiRes(HiResCoord hiRes)
These methods access or modify the high-resolution coordinate of this graphics context to the location specified by the parameters provided. In the first method, the parameters x, y, and z are arrays of eight 32-bit integers that specify the high-resolution coordinate.
public void setModelTransform(Transform3D t)
public void multiplyModelTransform(Transform3D t)
public void getModelTransform(Transform3D t)
These methods access or modify the current model transform. The multiplyModelTransform method multiplies the current model transform by the specified transform and stores the result back into the current model transform. The specified transformation must be angle and length preserving-only rotation, translation, and uniform scale are allowed. A BadTransformException is thrown (see Section D.1, "BadTransformException") if an attempt is made to specify an illegal Transform3D.
public final void setAuralAttributes(AuralAttributes attributes)
public final AuralAttributes getAuralAttributes()
These methods access or modify the current AuralAttributes component object used by this 3D graphics context. The graphics context stores a reference to the specified AuralAttributes object. This means that the application may modify individual audio attributes by using the appropriate methods on the AuralAttributes object (see Section 7.1.15, "AuralAttributes Object"). The AuralAttributes component object must not be part of a live scene graph, nor may it subsequently be made part of a live scene graph. If the AuralAttributes object is null, default values will be used for all audio attributes-it is as if an AuralAttributes object was created using the default constructor.
public final void readRaster(Raster raster)
This method reads an image from the frame buffer and copies it into the PixelArray and/or DepthImage objects referenced by the specified Raster object. All parameters of the Raster object and the component PixelArray and/or DepthImage objects must be set to the desired values prior to calling this method. These values determine the location, size, and format of the pixel data that is read.
public final void clear()
This method clears the canvas to the color or image specified by the current Background leaf node object.
public final void draw(Geometry geometry)
public final void draw(Shape3D shape)
The first draw method draws the specified Geometry component object using the current state in the graphics context. The second draw method draws the specified Shape3D leaf node object. This is a convenience method that is identical to calling the setAppearance(Appearance) and draw(Geometry) methods passing the Appearance and Geometry component objects of the specified Shape3D nodes as arguments.
public final void addSound(Sound sound)
public final void insertSound(Sound sound, int index)
public final void setSound(Sound sound, int index)
public final Sound getSound(int index)
public final void removeSound(int index)
public final int numSounds()
public final boolean isSoundPlaying(int index)
public final Enumeration getAllSounds()
These methods access or modify the list of sounds used by this 3D graphics context. The addSound method appends the specified sound to this graphics context's list of sounds. The insertSound method inserts the specified sound at the specified index location. The setSound method replaces the specified sound with the sound provided. The removeSound method removes the sound at the specified index location. The numSounds method retrieves the current number of sounds in this graphics context. The getSound method retrieves the index-selected sound. The isSoundPlaying method retrieves the sound-playing flag. The getAllSounds method retrieves the enumeration object of all the sounds.
The graphics context stores a reference to each sound object in the list of sounds. This means that the application may modify the sound attributes for any of the sounds by using the appropriate methods on that Sound node object (see Section 5.8, "Sound Node"). None of the Sound nodes in the list of sounds may be part of a live scene graph, nor may they subsequently be made part of a live scene graph. It is an error to add a null Sound object to the list. If the list of sounds is empty, sound rendering is disabled. Adding or inserting a sound to the list of sounds implicitly starts the sound playing. Once a sound is finished playing, it can be restarted by setting the sounds enable flag to true. The scheduling region of all sounds in the list is ignored for immediate mode rendering.

Java 3D API Specification

Copyright © 1997, Sun Microsystems, Inc. All rights reserved.