Java Doc for Canvas3D.java in  » 6.0-JDK-Modules » java-3d » javax » media » j3d » Java Source Code / Java DocumentationJava Source Code and Java Documentation

The Canvas3D object extends the Canvas object to include 3D-related information such as the size of the canvas in pixels, the Canvas3D's location, also in pixels, within a Screen3D object, and whether or not the canvas has stereo enabled.

Because all Canvas3D objects contain a reference to a Screen3D object and because Screen3D objects define the size of a pixel in physical units, Java 3D can convert a Canvas3D size in pixels to a physical world size in meters. It can also determine the Canvas3D's position and orientation in the physical world.

On-screen Rendering vs. Off-screen Rendering

The Canvas3D class is used either for on-screen rendering or off-screen rendering. On-screen Canvas3Ds are added to AWT or Swing Container objects like any other canvas. Java 3D automatically and continuously renders to all on-screen canvases that are attached to an active View object. On-screen Canvas3Ds can be either single or double buffered and they can be either stereo or monoscopic.

Off-screen Canvas3Ds must not be added to any Container. Java 3D renders to off-screen canvases in response to the renderOffScreenBuffer method. Off-screen Canvas3Ds are single buffered. However, on many systems, the actual rendering is done to an off-screen hardware buffer or to a 3D library-specific buffer and only copied to the off-screen buffer of the Canvas when the rendering is complete, at "buffer swap" time. Off-screen Canvas3Ds are monoscopic.

The setOffScreenBuffer method sets the off-screen buffer for this Canvas3D. The specified image is written into by the Java 3D renderer. The size of the specified ImageComponent determines the size, in pixels, of this Canvas3D - the size inherited from Component is ignored. Note that the size, physical width, and physical height of the associated Screen3D must be set explicitly prior to rendering. Failure to do so will result in an exception.

The getOffScreenBuffer method retrieves the off-screen buffer for this Canvas3D.

The renderOffScreenBuffer method schedules the rendering of a frame into this Canvas3D's off-screen buffer. The rendering is done from the point of view of the View object to which this Canvas3D has been added. No rendering is performed if this Canvas3D object has not been added to an active View. This method does not wait for the rendering to actually happen. An application that wishes to know when the rendering is complete must either subclass Canvas3D and override the postSwap method, or call waitForOffScreenRendering.

The setOfScreenLocation methods set the location of this off-screen Canvas3D. The location is the upper-left corner of the Canvas3D relative to the upper-left corner of the corresponding off-screen Screen3D. The function of these methods is similar to that of Component.setLocation for on-screen Canvas3D objects. The default location is (0,0).

Accessing and Modifying an Eye's Image Plate Position

A Canvas3D object provides sophisticated applications with access to the eye's position information in head-tracked, room-mounted runtime environments. It also allows applications to manipulate the position of an eye relative to an image plate in non-head-tracked runtime environments.

The setLeftManualEyeInImagePlate and setRightManualEyeInImagePlate methods set the position of the manual left and right eyes in image plate coordinates. These values determine eye placement when a head tracker is not in use and the application is directly controlling the eye position in image plate coordinates. In head-tracked mode or when the windowEyepointPolicy is RELATIVE_TO_FIELD_OF_VIEW or RELATIVE_TO_COEXISTENCE, this value is ignored. When the windowEyepointPolicy is RELATIVE_TO_WINDOW, only the Z value is used.

The getLeftEyeInImagePlate, getRightEyeInImagePlate, and getCenterEyeInImagePlate methods retrieve the actual position of the left eye, right eye, and center eye in image plate coordinates and copy that value into the object provided. The center eye is the fictional eye half-way between the left and right eye. These three values are a function of the windowEyepointPolicy, the tracking enable flag, and the manual left, right, and center eye positions.

Monoscopic View Policy

The setMonoscopicViewPolicy and getMonoscopicViewPolicy methods set and retrieve the policy regarding how Java 3D generates monoscopic view. If the policy is set to View.LEFT_EYE_VIEW, the view generated corresponds to the view as seen from the left eye. If set to View.RIGHT_EYE_VIEW, the view generated corresponds to the view as seen from the right eye. If set to View.CYCLOPEAN_EYE_VIEW, the view generated corresponds to the view as seen from the "center eye," the fictional eye half-way between the left and right eye. The default monoscopic view policy is View.CYCLOPEAN_EYE_VIEW.

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 a ViewPlatform leaf node object that defines the position and orientation within the virtual universe that generates the view.

In immediate mode, 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 must stop the Java 3D renderer, via the Canvas3D object stopRenderer method, prior to adding the Canvas3D object to an active View object (that is, one that is attached to a live ViewPlatform object).

Other Canvas3D methods related to immediate mode rendering are:

getGraphicsContext3D retrieves the immediate-mode 3D graphics context associated with this Canvas3D. It creates a new graphics context if one does not already exist.

getGraphics2D retrieves the 2D graphics object associated with this Canvas3D. It creates a new 2D graphics object if one does not already exist.

swap synchronizes and swaps buffers on a double-buffered canvas for this Canvas3D object. This method should only be called if the Java 3D renderer has been stopped. In the normal case, the renderer automatically swaps the buffer.

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.

Canvas3D methods related to mixed mode rendering are:

preRender called by the Java 3D rendering loop after clearing the canvas and before any rendering has been done for this frame.

postRender called by the Java 3D rendering loop after completing all rendering to the canvas for this frame and before the buffer swap.

postSwap called by the Java 3D rendering loop after completing all rendering to the canvas, and all other canvases associated with this view, for this frame following the buffer swap.

renderField called by the Java 3D rendering loop during the execution of the rendering loop. It is called once for each field (i.e., once per frame on a mono system or once each for the right eye and left eye on a two-pass stereo system.

The above callback methods are called by the Java 3D rendering system and should not be called by an application directly.

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 monoscopic 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. Updates to live Geometry, Texture, and ImageComponent objects in the scene graph are not allowed from any of these callback methods.

Serialization

Canvas3D does not support serialization. An attempt to serialize a Canvas3D object will result in an UnsupportedOperationException being thrown.

Additional Information

For more information, see the Introduction to the Java 3D API and View Model documents.
See Also:   Screen3D
See Also:   View
See Also:   GraphicsContext3D

left manual eye in image plate : (0.142, 0.135, 0.4572)
right manual eye in image plate : (0.208, 0.135, 0.4572)
stereo enable : true
double buffer enable : true
monoscopic view policy : View.CYCLOPEAN_EYE_VIEW
off-screen mode : false
off-screen buffer : null
off-screen location : (0,0)