The Canvas3D class provides a drawing canvas for 3D rendering. It
is used either for on-screen rendering or off-screen rendering.
Canvas3D is an extension of the AWT Canvas class that users may
further subclass to implement additional functionality.
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.