View Model

The Java 3D API Specification

JAVA 3D introduces a new view model that takes Java's vision of "write once, run anywhere" and generalizes it to include display devices and six-degrees-of-freedom input peripherals such as head trackers. This "write once, view everywhere" nature of the new view model means that an application or applet written using the Java 3D view model can render images to a broad range of display devices, including standard computer displays, multiple-projection display rooms, and head-mounted displays, without modification of the scene graph. It also means that the same application, once again without modification, can render stereoscopic views and can take advantage of the input from a head tracker to control the rendered view.
Java 3D's view model achieves this versatility by cleanly separating the virtual and the physical world. This model distinguishes between how an application positions, orients, and scales a ViewPlatform object (a viewpoint) within the virtual world and how the Java 3D renderer constructs the final view from that viewpoint's position and orientation. The application controls the ViewPlatform's position and orientation; the renderer computes what view to render using this position and orientation, a description of the end-user's physical environment, and the user's position and orientation within the physical environment.
This chapter first explains why Java 3D chose a different view model and some of the philosophy behind that choice. It next describes how that model operates in the simple case of a standard computer screen without head tracking-the most common case. Finally, it presents the relevant parts of the API from a developer's perspective. Appendix C, "View Model Details," describes the Java 3D view model from an advanced developer and Java 3D implementor's perspective.

9.1 Why a New Model?
Camera-based view models, as found in low-level APIs, give developers control over all rendering parameters. This makes sense when dealing with custom applications, less sense when dealing with systems that wish to have broader applicability: systems such as viewers or browsers that load and display whole worlds as a single unit or systems where the end users view, navigate, display, and even interact with the virtual world.
Camera-based view models emulate a camera in the virtual world, not a human in a virtual world. Developers must continuously reposition a camera to emulate "a human in the virtual world."
The Java 3D view model incorporates head tracking directly, if present, with no additional effort from the developer, thus providing end users with the illusion that they actually exist inside a virtual world.
The Java 3D view model, when operating in a non-head-tracked environment and rendering to a single, standard display, acts very much like a traditional camera-based view model, with the added functionality of being able to generate stereo views transparently.

9.1.1 The Physical Environment Influences the View
Letting the application control all viewing parameters is not reasonable in systems in which the physical environment dictates some of the view parameters.
One example of this is a head-mounted display (HMD), where the optics of the head-mounted display directly determine the field of view that the application should use. Different HMDs have different optics, making it unreasonable for application developers to hard-wire such parameters or to allow end users to vary that parameter at will.
Another example is a system that automatically computes view parameters as a function of the user's current head position. The specification of a world and a predefined flight path through that world may not exactly specify an end-user's view. HMD users would expect to look and thus see to their left or right even when following a fixed path through the environment-imagine an amusement park ride with vehicles that follow fixed paths to present content to their visitors, but visitors can continue to move their heads while on those rides.
Depending on the physical details of the end-user's environment, the values of the viewing parameters, particularly the viewing and projection matrices, will vary widely. The factors that influence the viewing and projection matrices include the size of the physical display, how the display is mounted (on the user's head or on a table), whether the computer knows the user's head location in three space, the head mount's actual field of view, the display's pixels per inch, and other such parameters. For more information, see Appendix C, "View Model Details."

9.2 Separation of Physical and Virtual
The Java 3D view model separates the virtual environment, where the application programmer has placed objects in relation to one another, from the physical environment, where the user exists, sees computer displays, and manipulates input devices.
Java 3D also defines a fundamental correspondence between the user's physical world and the virtual world of the graphic application. This physical-to-virtual-world correspondence defines a single common space, a space where an action taken by an end user affects objects within the virtual world and where any activity by objects in the virtual world affects the end user's view.

9.2.1 The Virtual World
The virtual world is a common space in which virtual objects exist. The virtual world coordinate system exists relative to a high-resolution Locale-each Locale object defines the origin of virtual world coordinates for all of the objects attached to that Locale. The Locale that contains the currently active ViewPlatform object defines the virtual world coordinates that are used for rendering. Java3D eventually transforms all coordinates associated with scene graph elements into this common virtual world space.

9.2.2 The Physical World
The physical world is just that-the real, physical world. This is the space in which the physical user exists and within which he or she moves his or her head and hands. This is the space in which any physical trackers define their local coordinates and in which several calibration coordinate systems are described.
The physical world is a space, not a common coordinate system between different execution instances of Java 3D. So while two different computers at two different physical locations on the globe may be running at the same time, there is no mechanism directly within Java 3D to relate their local physical world coordinate systems with each other. Because of calibration issues, the local tracker (if any) defines the local physical world coordinate system known to a particular instance of Java 3D.

9.3 The Objects That Define the View
Java 3D distributes its view model parameters across several objects, specifically, the View object and its associated component objects, the PhysicalBody object, the PhysicalEnvironment object, the Canvas3D object, and the Screen3D object. Figure 9-1 shows graphically the central role of the View object and the subsidiary role of its component objects.

Figure 9-1 View Object, Its Component Objects, and Their Interconnection

The view-related objects shown in Figure 9-1 and their roles are as follows. For each of these objects, the portion of the API that relates to modifying the virtual world and the portion of the API that is relevant to non-head-tracked standard display configurations are derived in this chapter. The remainder of the details are described in Appendix C, "View Model Details."

ViewPlatform: A leaf node that locates a view within a scene graph. The ViewPlatform's parents specify its location, orientation, and scale within the virtual universe. See Section 6.11, "ViewPlatform Node," and Section 9.4, "ViewPlatform: A Place in the Virtual World," for more information.

View: The main view object. It contains many pieces of view state. See Section 9.7, "The View Object," for more information.

Canvas3D: The 3D version of the Abstract Windowing Toolkit (AWT) Canvas object. It represents a window in which Java 3D will draw images. It contains a reference to a Screen3D object and information describing the Canvas3D's size, shape, and location within the Screen3D object. See Section 9.9, "The Canvas3D Object," for more information.

Screen3D: An object that contains information describing the display screen's physical properties. Java 3D places display-screen information in a separate object to prevent the duplication of screen information within every Canvas3D object that shares a common screen. See Section 9.8, "The Screen3D Object," for more information.

PhysicalBody: An object that contains calibration information describing the user's physical body. See Section 9.10, "The PhysicalBody Object," for more information.

PhysicalEnvironment: An object that contains calibration information describing the physical world, mainly information that describes the environment's six-degrees-of freedom tracking hardware, if present. See Section 9.11, "The PhysicalEnvironment Object," for more information.
Together, these objects describe the geometry of viewing rather than explicitly providing a viewing or projection matrix. The Java 3D renderer uses this information to construct the appropriate viewing and projection matrices. The geometric focus of these view objects provides more flexibility in generating views-a flexibility needed to support alternative display configurations.

9.4 ViewPlatform: A Place in the Virtual World
A ViewPlatform leaf node defines a coordinate system, and thus a reference frame with its associated origin or reference point, within the virtual world. The ViewPlatform serves as a point of attachment for View objects and as a base for determining a renderer's view.
Figure 9-2 shows a portion of a scene graph containing a ViewPlatform node. The nodes directly above a ViewPlatform determine where that ViewPlatform is located and how it is oriented within the virtual world. By modifying the Transform3D object associated with a TransformGroup node anywhere directly above a ViewPlatform, an application or behavior can move that ViewPlatform anywhere within the virtual world. A simple application might define one TransformGroup node directly above a ViewPlatform, as shown in Figure 9-2.
A VirtualUniverse may have many different ViewPlatforms, but a particular View object can attach itself only to a single ViewPlatform. Thus, each rendering onto a Canvas3D is done from the point of view of a single ViewPlatform.

Figure 9-2 A Portion of a Scene Graph Containing a ViewPlatform Object

9.4.1 Moving through the Virtual World
An application navigates within the virtual world by modifying a ViewPlatform's parent TransformGroup. Examples of applications that modify a ViewPlatform's location and orientation include browsers, object viewers that provide navigational controls, applications that do architectural walkthroughs, and even search-and-destroy games.
Controlling the ViewPlatform object can produce very interesting and useful results. Our first simple scene graph (see Figure 1-2) defines a scene graph for a simple application that draws an object in the center of a window and rotates that object about its center point. In that figure, the Behavior object modifies the TransformGroup directly above the Shape3D node.
An alternative application scene graph, shown in Figure 9-3, leaves the central object alone and moves the ViewPlatform around the world. If the shape node contains a model of the earth, this application could generate a view similar to that seen by astronauts as they orbit the earth.
Had we populated this world with more objects, this scene graph would allow navigation through the world via the Behavior node.

Figure 9-3 A Simple Scene Graph with View Control

Applications and behaviors manipulate a TransformGroup through its access methods. These methods (defined in Section 5.3, "TransformGroup Node") allow an application to retrieve and set the Group node's Transform3D object. Transform3D Node methods include getTransform and setTransform.

9.4.2 Dropping in on a Favorite Place
A scene graph may contain multiple ViewPlatform objects. If a user detaches a View object from a ViewPlatform and then reattaches that View to a different ViewPlatform, the image on the display will now be rendered from the point of view of the new ViewPlatform. For more information, see Section 9.7, "The View Object."

9.4.3 View Attach Policy
The actual view that Java 3D's renderer draws depends on the view attach policy specified within the currently attached ViewPlatform. The ViewPlatform defines the following methods for setting and retrieving the view attach policy:

Methods
public void setViewAttachPolicy(int policy)
public int getViewAttachPolicy()
These methods set and retrieve the coexistence center in virtual world policy. The default attach policy is View.NOMINAL_HEAD. A ViewPlatform's view attach policy determines how Java 3D places the virtual eyepoint within the ViewPlatform. The policy can have one of the following values:

View.NOMINAL_HEAD: Ensures that the end user's nominal eye position in the physical world corresponds to the virtual eye's nominal eye position in the virtual world (the ViewPlatform's origin). In essence, this policy tells Java 3D to position the virtual eyepoint relative to the ViewPlatform origin in the same way as the physical eyepoint is positioned relative to its nominal physical-world origin. Deviations in the physical eye's position and orientation from nominal in the physical world generate corresponding deviations of the virtual eye's position and orientation in the virtual world.

View.NOMINAL_FEET: Ensures that the end user's virtual feet always touch the virtual ground. This policy tells Java 3D to compute the physical-to-virtual-world correspondence in a way that enforces this constraint. Java 3D does so by appropriately offsetting the physical eye's position by the end-user's physical height. Java 3D uses the nominalEyeHeightFromGround parameter found in the PhysicalBody object (see Section 9.10, "The PhysicalBody Object") to perform this computation.

View.NOMINAL_SCREEN: Allows an application always to have the virtual eyepoint appear at some "viewable" distance from a point of interest. This policy tells Java 3D to compute the physical-to-virtual-world correspondence in a way that ensures that the renderer moves the nominal virtual eyepoint away from the point of interest by the amount specified by the nominalEyeOffsetFromNominalScreen parameter found in the PhysicalBody object (see Section 9.10, "The PhysicalBody Object").

9.4.4 Associating Geometry with a ViewPlatform
Java 3D does not have any built-in semantics for displaying a visible manifestation of a ViewPlatform within the virtual world (an avatar). However, a developer can construct and manipulate an avatar using standard Java 3D constructs.
A developer can construct a small scene graph consisting of a TransformGroup node, a behavior leaf node, and a shape node and insert it directly under the BranchGroup node associated with the ViewPlatform object. The shape node would contain a geometric model of the avatar's head. The behavior node would change the TransformGroup's transform periodically to the value stored in a View object's UserHeadToVworld parameter (see Appendix C, "View Model Details"). The avatar's virtual head, represented by the shape node, will now move around in lock-step with the ViewPlatform's TransformGroup and any relative position and orientation changes of the user's actual physical head (if a system has a head tracker).

9.5 Generating a View
Java 3D generates viewing matrices in one of a few different ways, depending on whether the end user has a head-mounted or a room-mounted display environment and whether head tracking is enabled. This section describes the computation for a non-head-tracked, room-mounted display-a standard computer display. Other environments are described in Appendix C, "View Model Details."
In the absence of head tracking, the ViewPlatform's origin specifies the virtual eye's location and orientation within the virtual world. However, the eye location provides only part of the information needed to render an image. The renderer also needs a projection matrix. In the default mode, Java 3D uses the projection policy, the specified field-of-view information, and the front and back clipping distances to construct a viewing frustum.

9.5.1 Composing Model and Viewing Transformations
Figure 9-4 shows a simple scene graph. To draw the object labeled "S," Java 3D internally constructs the appropriate model, view platform, eye, and projection matrices. Conceptually, the model transformation for a particular object is computed by concatenating all the matrices in a direct path between the object and the VirtualUniverse. The view matrix is then computed-again, conceptually-by concatenating all the matrices between the VirtualUniverse object and the ViewPlatform attached to the current View object. The eye and projection matrices are constructed from the View object and its associated component objects.

Figure 9-4 Object and ViewPlatform Transformations

In our scene graph, what we would normally consider the model transformation would consist of the following three transformations: LT₁T₂. By multiplying LT₁T₂ by a vertex in the shape object, we would transform that vertex into the virtual universe's coordinate system. What we would normally consider the view platform transformation would be (LT_v1)^-1 or T_v1^-1L^-1. This presents a problem since coordinates in the virtual universe are 256-bit fixed-point values, which cannot be used to represent transformed points efficiently.
Fortunately, however, there is a solution to this problem. Composing the model and view platform transformations gives us

T_v1^-1L^-1LT₁T₂ = T_v1^-1IT₁T₂ = T_v1^-1T₁T₂,
the matrix that takes vertices in an object's local coordinate system and places them in the ViewPlatform's coordinate system. Note that the high-resolution Locale transformations cancel each other out, which removes the need to actually transform points into high-resolution VirtualUniverse coordinates. The general formula of the matrix that transforms object coordinates to ViewPlatform coordinates is T_vn^-1...T_v2^-1T_v1^-1T₁T₂...T_m.
As mentioned earlier, the View object contains the remainder of the view information, specifically, the eye matrix, E, that takes points in the View-Platform's local coordinate system and translates them into the user's eye coordinate system, and the projection matrix, P, that projects objects in the eye's coordinate system into clipping coordinates. The final concatenation of matrices for rendering our shape object "S" on the specified Canvas3D is PET_v1^-1T₁T₂. In general this is PET_vn^-1...T_v2^-1T_v1^-1T₁T₂...T_m.
The details of how Java 3D constructs the matrices E and P in different end-user configurations are described in Appendix C, "View Model Details."

9.5.2 Multiple Locales
Java 3D supports multiple high-resolution Locales. In some cases, these Locales are close enough to each other that they can "see" each other, meaning that objects can be rendered even though they are not in the same Locale as the ViewPlatform object that is attached to the View. Java 3D automatically handles this case without the application having to do anything. As in the previous example, where the ViewPlatform and the object being rendered are attached to the same Locale, Java 3D internally constructs the appropriate matrices for cases in which the ViewPlatform and the object being rendered are not attached to the same Locale.
Let's take two Locales, L₁ and L₂, with the View attached to a ViewPlatform in L₁. According to our general formula, the modeling transformation-the transformation that takes points in object coordinates and transforms them into VirtualUniverse coordinates-is LT₁T₂...T_m. In our specific example, a point in Locale L₂ would be transformed into VirtualUniverse coordinates by L₂T₁T₂...T_m. The view platform transformation would be (L₁T_v1T_v1...T_vn)^-1 or T_vn^-1...T_v2^-1T_v1^-1L₁^-1. Composing these two matrices gives us

T_vn^-1...T_v2^-1T_v1^-1L₁^-1L₂T₁T₂...T_m.
Thus, to render objects in another Locale, it is sufficient to compute L₁^-1L₂ and use that as the starting matrix when composing the model transformations. Given that a Locale is represented by a single high-resolution coordinate position, the transformation L₁^-1L₂ is a simple translation by L₂ - L₁. Again, it is not actually necessary to transform points into high-resolution VirtualUniverse coordinates.
In general, Locales that are close enough that the difference in their high-resolution coordinates can be represented in double precision by a noninfinite value are close enough to be rendered. In practice, more sophisticated culling techniques can be used to render only those Locales that really are "close enough."

9.6 A Minimal Environment
An application must create a minimal set of Java 3D objects before Java 3D can render to a display device. 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

A ViewPlatform leaf node object that defines the position and orientation within the virtual universe for generating views

9.7 The View Object
The View object coordinates all aspects of the rendering process. It contains all the parameters or references to objects containing the parameters that determine how to render images to the windows represented by its Canvas3D objects. It also contains the set of canvases that represent various "windows" onto a view.
Java 3D allows applications to specify multiple simultaneously active View objects, each controlling its own set of canvases. For more details on a View object's internals, see Section C.5, "The View Object."

Constructors
The View object specifies the following constructor:
public View()
Constructs and initializes a new View object with the following default parameters:

Parameter Default Value
view policy SCREEN_VIEW
projection policy PERSPECTIVE_PROJECTION
screen scale policy SCALE_SCREEN_SIZE
window resize policy PHYSICAL_WORLD
window movement policy PHYSICAL_WORLD
window eyepoint policy RELATIVE_TO_FIELD_OF_VIEW
monoscopic view policy
(deprecated in this class) CYCLOPEAN_EYE_VIEW
front clip policy PHYSICAL_EYE
back clip policy PHYSICAL_EYE
visibility policy VISIBILITY_DRAW_VISIBLE
coexistence centering flag true
compatibility mode false
left projection identity
right projection identity
vpc to ec transform identity
physical body null
physical environment null
screen scale 1.0
field of view /4
left manual eye in coexistence (-0.033, 0.0, 0.4572)
right manual eye in coexistence (0.033, 0.0, 0.4572)
front clip distance 0.1
back clip distance 10.0
tracking enable false
user head to vworld enable false
list of Canvas3D objects empty
depth buffer freeze transparent true
scene antialiasing false
local eye lighting false
view platform null
behavior scheduler running true
view running true
minimum frame duration 0

Methods
The View object specifies the following methods:
public void setPhysicalBody(PhysicalBody physicalBody)
public PhysicalBody getPhysicalBody()
These methods set and retrieve the View's PhysicalBody object. See Section 9.10, "The PhysicalBody Object," for more information on the PhysicalBody object.
public void setPhysicalEnvironment(PhysicalEnvironment
       physicalEnvironment)
public PhysicalEnvironment getPhysicalEnvironment()
These methods set and retrieve the View's PhysicalEnvironment object. See Section 9.11, "The PhysicalEnvironment Object," for more information on the PhysicalEnvironment object.
public void attachViewPlatform(ViewPlatform vp)
This method attaches a ViewPlatform leaf node to this View, replacing the existing ViewPlatform. If the ViewPlatform is part of a live scene graph, or is subsequently made live, the scene graph is rendered into all canvases in this View object's list of Canvas3D objects. To remove a ViewPlatform without attaching a new one-causing the View to no longer be rendered-a null reference may be passed to this method. In this case, the behavior is as if rendering were simultaneously stopped on all canvases attached to the View-the last frame that was rendered in each remains visible until the View is again attached to a live ViewPlatform object. See Section 6.11, "ViewPlatform Node," for more information on ViewPlatform objects.
public ViewPlatform getViewPlatform()
This method retrieves the currently attached ViewPlatform object.
public Canvas3D getCanvas3D(int index)
public void setCanvas3D(Canvas3D canvas3D, int index)
public void addCanvas3D(Canvas3D canvas3D)
public void insertCanvas3D(Canvas3D canvas3D, int index)
public void removeCanvas3D(int index)
public void removeCanvas3D(Canvas3D canvas3D)
These methods set, retrieve, add to, insert after, and remove a Canvas3D object from this View. The index specifies the reference to the Canvas3D object within the View object. See Section 9.9, "The Canvas3D Object" for more information on Canvas3D objects.
public int numCanvas3Ds()
This method returns the the number of Canvas3Ds in this View.
public Enumeration getAllCanvas3Ds()
This method gets the Enumeration object of all the Canvas3Ds.

9.7.1 Projection Policy
The projection policy informs Java 3D whether it should generate a parallel projection or a perspective projection. This policy is attached to the Java 3D View object.

Methods
public void setProjectionPolicy(int policy)
public int getProjectionPolicy()
These two methods set and retrieve the current projection policy for this view. The projection policies are as follows:

PARALLEL_PROJECTION: Specifies that Java 3D should compute a parallel projection.

PERSPECTIVE_PROJECTION: Specifies that Java 3D should compute a perspective projection. This is the default setting.
public void setLocalEyeLightingEnable(boolean flag)
public boolean getLocalEyeLightingEnable()
These methods set and retrieve the local eye lighting flag, which indicates whether the local eyepoint is used in lighting calculations for perspective projections. If this flag is set to true, the view vector is calculated per vertex based on the direction from the actual eyepoint to the vertex. If this flag is set to false, a single view vector is computed from the eyepoint to the center of the view frustum. This is called infinite eye lighting. Local eye lighting is disabled by default and is ignored for parallel projections.

9.7.1.1 Window Sizing and Movement
When users resize or move windows, Java 3D can choose to think of the window as attached either to the physical world or to the virtual world. The window resize policy allows an application to specify how the view model will handle resizing requests. The window resize policies are specified by two constants.

Constants
public static final int PHYSICAL_WORLD
This variable specifies the policy for resizing and moving windows and is used in specifying windowResizePolicy and windowMovementPolicy. This variable specifies that the specified action takes place only in the physical world.
public static final int VIRTUAL_WORLD
This variable specifies that Java 3D applies the associated policy in the virtual world.

Methods
public void setWindowResizePolicy(int policy)
public int getWindowResizePolicy()
This variable specifies how Java 3D modifies the view when a user resizes a window. A value of PHYSICAL_WORLD states that Java 3D will treat window resizing operations as happening only in the physical world. This implies that rendered objects continue to fill the same percentage of the newly sized window, using more or fewer pixels to draw those objects, depending on whether the window grew or shrank in size. A value of VIRTUAL_WORLD states that Java 3D will treat window resizing operations as also happening in the virtual world whenever a resizing occurs in the physical world. This implies that rendered objects remain the same size (use the same number of pixels), but since the window becomes larger or smaller, the user sees more or less of the virtual world. The default value is PHYSICAL_WORLD.
public void setWindowMovementPolicy(int policy)
public int getWindowMovementPolicy()
This variable specifies what part of the virtual world Java 3D will draw as a function of the window location on the display screen. A value of PHYSICAL_WORLD states that the window acts as if it moves only on the physical screen. As the user moves the window on the screen, the window's position on the screen changes, but Java 3D continues to draw exactly the same image within that window. A value of VIRTUAL_WORLD states that the window acts as if it also moves within the virtual world. As the user moves the window on the physical screen, the window's position on the screen changes, and the image that Java 3D draws changes as well to match what would be visible in the virtual world from a window in that new position. The default value is PHYSICAL_WORLD.

9.7.2 Clip Policies
The clip policies determine how Java 3D interprets clipping distances to both the near and far clip planes. The policies can contain one of four values specifying whether a distance measurement should be interpreted in the physical or the virtual world and whether that distance measurement should be interpreted relative to the physical eyepoint or the physical screen.

Methods
public void setFrontClipPolicy(int policy)
public int getFrontClipPolicy()
public void setBackClipPolicy(int policy)
public int getBackClipPolicy()
The front clip policy determines where Java 3D places the front clipping plane. The value is one of the following: PHYSICAL_EYE, PHYSICAL_SCREEN, VIRTUAL_EYE, or VIRTUAL_SCREEN. The default value is PHYSICAL_EYE.
The back clip policy determines where Java 3D places the back clipping plane. The value is one of the following: PHYSICAL_EYE, PHYSICAL_SCREEN, VIRTUAL_EYE, or VIRTUAL_SCREEN. The default value is PHYSICAL_EYE.
These policies are defined as follows.

PHYSICAL_EYE: Specifies that the plane is located relative to the eye's position as measured in the physical space (in meters).

PHYSICAL_SCREEN: Specifies that the plane is located relative to the screen (that is, the image plate) as measured in physical space (in meters).

VIRTUAL_EYE: Specifies that the plane is located relative to the virtual eyepoint as measured in virtual world coordinates.

VIRTUAL_SCREEN: Specifies that the plane is located relative to the screen (that is, the image plate) as measured in virtual world coordinates.

9.7.3 Projection and Clip Parameters
The projection and clip parameters determine the view model's field of view and the front and back clipping distances.
public void setFieldOfView(double fieldOfView)
public double getFieldOfView()
In the default non-head-tracked mode, this value specifies the view model's horizontal field of view in radians. This value is ignored when the view model is operating in head-tracked mode or when the Canvas3D's window eyepoint policy is set to a value other than the default setting of RELATIVE_TO_FIELD_OF_VIEW (see Section C.5.3, "Window Eyepoint Policy").
public void setFrontClipDistance(double distance)
public double getFrontClipDistance()
This value specifies the distance away from the clip origin, specified by the front clip policy variable, in the direction of gaze where objects stop disappearing. Objects closer than the clip origin (eye or screen) plus the front clip distance are not drawn. Measurements are done in the space (physical or virtual) that is specified by the associated front clip policy parameter.
public void setBackClipDistance(double distance)
public double getBackClipDistance()
This value specifies the distance away from the clip origin (specified by the back clip policy variable) in the direction of gaze where objects begin disappearing. Objects farther away from the clip origin (eye or screen) plus the back clip distance are not drawn. Measurements are done in the space (physical or virtual) that is specified by the associated back clip policy parameter. The View object's back clip distance is ignored if the scene graph contains an active Clip leaf node (see Section 6.5, "Clip Node").
There are several considerations that need to be taken into account when choosing values for the front and back clip distances.

The front clip distance must be greater than 0.0 in physical eye coordinates.

The front clipping plane must be in front of the back clipping plane; that is, the front clip distance must be less than the back clip distance in physical eye coordinates.

The front and back clip distances, in physical eye coordinates, must be less than the largest positive single-precision floating-point value, Float.MAX_VALUE. In practice, since these physical eye coordinate distances are in meters, the values should be much less than that.

The ratio of the back distance divided by the front distance, in physical eye coordinates, affects z-buffer precision. This ratio should be less than about 3000 to accommodate 16-bit z-buffers. Values of 100 to less than 1000 will produce better results.
Violating any of the above rules will result in undefined behavior. In many cases, no picture will be drawn.

9.7.4 Frame Start Time, Duration, and Number
The following methods are used to get information about system execution and performance:
public long getCurrentFrameStartTime()
This method returns the time at which the most recent rendering frame started. It is defined as the number of milliseconds since January 1, 1970, 00:00:00 GMT. Since multiple canvases might be attached to this View, the start of a frame is defined as the point just prior to clearing any canvas attached to this View.
public long getLastFrameDuration()
This method returns the duration, in milliseconds, of the most recently completed rendering frame. The time taken to render all canvases attached to this View is measured. This duration is computed as the difference between the start of the most recently completed frame and the end of that frame. Since multiple canvases might be attached to this View, the start of a frame is defined as the point just prior to clearing any canvas attached to this View, while the end of a frame is defined as the point just after swapping the buffer for all canvases.
public long getFrameNumber()
This method returns the frame number for this view. The frame number starts at 0 and is incremented prior to clearing all the canvases attached to this view.
public static int getMaxFrameStartTimes()
This method retrieves the implementation-dependent maximum number of frames whose start times will be recorded by the system. This value is guaranteed to be at least 10 for all implementations of the Java 3D API.
public long getFrameStartTimes(long times[])
This method copies the last k frame start-time values into the user-specified array. The most recent frame start time is copied to location 0 of the array, the next most recent frame start time is copied into location 1 of the array, and so on. If times.length is smaller than maxFrameStartTimes, only the last times.length values are copied. If times.length is greater than maxFrameStartTimes, all array elements after index maxFrameStartTimes - 1 are set to 0.
public void setMinimumFrameCycleTime(long duration)
public long getMinimumFrameCycleTime()
These methods set and retrieve the minimum frame cycle time, in milliseconds, for this view. The Java 3D renderer will ensure that the duration between each frame is at least the specified number of milliseconds. The default value is 0.

9.7.5 View Traversal and Behavior Scheduling
The following methods control the traversal, the rendering, and the execution of the behavior scheduler for this view:
public final long[] stopBehaviorScheduler()
public final void startBehaviorScheduler()
public final boolean isBehaviorSchedulerRunning()
The first method stops the behavior scheduler after all currently scheduled behaviors are executed. Any frame-based behaviors scheduled to wake up on the next frame will be executed at least once before the behavior scheduler is stopped. The method returns a pair of integers that specify the beginning and ending time (in milliseconds since January 1, 1970, 00:00:00 GMT) of the behavior scheduler's last pass. The second method starts the behavior scheduler running after it has been stopped. The third method retrieves a flag that indicates whether the behavior scheduler is currently running.
public final void stopView()
public final void startView()
public final boolean isViewRunning()
The first method stops traversing this view after the current state of the scene graph is reflected on all canvases attached to this view. The renderers associated with these canvases are also stopped. The second method starts traversing this view and starts the renderers associated with all canvases attached to this view. The third method returns a flag indicating whether the traverser is currently running on this view.

Note: The above six methods are heavy-weight methods intended for verification and image capture (recording). They are not intended to be used for flow control.
public void renderOnce()
This method renders one frame for a stopped View. Functionally, this method is equivalent to startView() followed by stopview(), except that it is atomic, which guarantees that only one frame is rendered.
public void repaint()
This method requests that this View be scheduled for rendering as soon as possible. The repaint method may return before the frame has been rendered. If the view is stopped or if the view is continuously running (for example, due to a free-running interpolator), this method will have no effect. Most applications will not need to call this method, since any update to the scene graph or to viewing parameters will automatically cause all affected views to be rendered.

9.7.6 Scene Antialiasing
public void setSceneAntialiasingEnable(boolean flag)
public boolean getSceneAntialiasingEnable()
These methods set and retrieve the scene antialiasing flag. Scene antialiasing is either enabled or disabled for this view. If enabled, the entire scene will be antialiased on each canvas in which scene antialiasing is available. Scene antialiasing is disabled by default.

Note: Line and point antialiasing are independent of scene antialiasing. If antialiasing is enabled for lines and points, the lines and points will be antialiased prior to scene antialiasing.

9.7.7 Depth Buffer
public void setDepthBufferFreezeTransparent(boolean flag)
public boolean getDepthBufferFreezeTransparent()
The set method enables or disables automatic freezing of the depth buffer for objects rendered during the transparent rendering pass (that is, objects rendered using alpha blending) for this view. If enabled, depth buffer writes are disabled during the transparent rendering pass regardless of the value of the depth-buffer-write-enable flag in the RenderingAttributes object for a particular node. This flag is enabled by default. The get method retrieves this flag.

9.8 The Screen3D Object
The Screen3D object provides a 3D version of the AWT screen object. It contains the screen's physical properties. Java 3D will support multiple active Screen3D objects as soon as AWT support is available. Of course, multiple screens are available only if the machine configuration has multiple output screens. Java 3D primarily needs to know the physical size (in meters) of the Screen3D's visible, addressable raster (the image plate) and, in head-tracking mode, the position and orientation of this raster relative to a well-defined physical world coordinate system, specifically, the tracker base coordinate system. Java 3D also needs to know how many pixels the raster can display in both the x and y dimensions. This information allows Java 3D to calculate a pixel's physical dimension.
Calibration utilities can change a Screen3D's physical characteristics or calibration transforms. See Section C.6, "The Screen3D Object."
The Screen3D object has no public constructors. Instead, the Screen3D object associated with a particular Canvas3D object can be obtained from the canvas by calling the getScreen3D method. See Section 9.9.3, "Other Canvas3D Parameters."
Default values for Screen3D parameters are as follows:

Parameter Default Value
physical screen width 0.0254/90.0 * screen width (in pixels)
physical screen height 0.0254/90.0 * screen height (in pixels)
tracker base to image plate transform identity
head tracker to left image plate transform identity
head tracker to right image plate transform identity
off-screen size (0,0)

Methods
These methods provide applications with information concerning the underlying display hardware, such as the screen's width and height in pixels or in meters.
public Dimension getSize()
public Dimension getSize(Dimension rv)
These methods retrieve the width and height (in pixels) of this Screen3D. The second method copies the width and height into the specified Dimension object.
public double getPhysicalScreenWidth()
public double getPhysicalScreenHeight()
These methods retrieve the screen's (image plate's) physical width and height in meters.

9.8.1 Off-Screen Rendering
New for Java 3D 1.2 is an off-screen mode that allows rendering to a memory image, which is possibly larger than the screen.
public void setSize(int width, int height)
public void setSize(Dimension d)
These methods set the width and height (in pixels) of this off-screen Screen3D. The default size for off-screen Screen3D objects is (0,0).

Note: The off-screen size, physical width, and physical height must be set prior to rendering to the associated off-screen canvas. Failure to do so will result in an exception.

9.9 The Canvas3D Object
The Canvas3D object extends the java.awt.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. The Canvas3D class is used either for on-screen rendering or for off-screen rendering. 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.
The Canvas3D class is used either for on-screen rendering or for 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 (see Section 9.9.2, "Off-Screen Rendering"). 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 copied only to the off-screen buffer of the Canvas when the rendering is complete, at "buffer swap" time. Off-screen Canvas3Ds are monoscopic.

Constructors
The Canvas3D object specifies the following constructors:
public Canvas3D(GraphicsConfiguration graphicsConfiguration)
This constructs and initializes a new Canvas3D object that Java 3D can render into. The following Canvas3D parameters are initialized to default values as shown:

Parameter Default Value
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)
public Canvas3D(GraphicsConfiguration graphicsConfiguration,
       boolean offScreen)
This constructs and initializes a new Canvas3D object that Java 3D can render into.
Java 3D can render into this Canvas3D object. If the graphicsConfiguration argument is null, a GraphicsConfiguration object will be constructed using the default GraphicsConfigTemplate3D (see Section 9.9.4, "GraphicsConfigTem-plate3D Object").
For more information on the GraphicsConfiguration object, see the Java 2D specification, which is part of the AWT in JDK 1.2.

9.9.1 Window System-Provided Parameters
Java 3D specifies the size of a Canvas3D in pixels. It extracts this information directly from the AWT's window system. Java 3D allows applications only to access these values, not to change them.
public Dimension getLocationOnScreen()
public Dimension getSize()
These methods, inherited from the parent Canvas class, retrieve the Canvas3D's screen position and size in pixels.

9.9.2 Off-Screen Rendering
New for Java 3D 1.2 is an off-screen mode that allows rendering to a memory image, which is possibly larger than the screen.
public boolean isOffScreen()
This method retrieves the state of the renderer for this Canvas3D object.
public void setOffScreenBuffer(ImageComponent2D buffer)
public ImageComponent2D getOffScreenBuffer()
The first 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. The second method retrieves the off-screen buffer for this Canvas3D.

Note: 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.
public void renderOffScreenBuffer()
This 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. An IllegalStateException is thrown if this Canvas3D is not in off-screen mode, if either the width or the height of the associated Screen3D's size is 0, or if the associated Screen3D's physical width or height is 0.
public void waitForOffScreenRendering()
This method waits for this Canvas3D's off-screen rendering to be done. This method will wait until the postSwap method of this off-screen Canvas3D has completed. If this Canvas3D has not been added to an active view or if the renderer is stopped for this Canvas3D, this method will return immediately. This method must not be called from a render callback method of an off-screen Canvas3D.
public void setOffScreenLocation(int x, int y)
public void setOffScreenLocation(Point p)
These 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).
public Point getOffScreenLocation()
public Point getOffScreenLocation(Point rv)
These methods retrieve 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.getLocation for on-screen Canvas3D objects. The second method stores the location in the specified Point object. This method is useful if the caller wants to avoid allocating a new Point object on the heap.

9.9.3 Other Canvas3D Parameters
public boolean getStereoAvailable()
This method specifies whether the underlying hardware supports field-sequential stereo on this canvas. This is equivalent to
((Boolean)queryProperties().get("stereoAvailable")).
    booleanValue()
public boolean getStereoEnable()
public void setStereoEnable(boolean flag)
These methods set or retrieve the flag indicating whether this Canvas3D has stereo enabled. If enabled, Java 3D generates left and right eye images. If the Canvas3D's StereoAvailable flag is false, Java 3D displays only the left eye's view even if an application sets StereoEnable to true. This parameter allows applications to enable or disable stereo on a canvas-by-canvas basis.
public void getDoubleBufferAvailable()
This method specifies whether the underlying hardware supports double buffering on this canvas. This is equivalent to
((Boolean)queryProperties().get("doubleBufferAvailable")).
    booleanValue()
public boolean getDoubleBufferEnable()
public void setDoubleBufferEnable(boolean flag)
These methods set or retrieve the flag indicating whether this Canvas3D has double buffering enabled. If disabled, all drawing is to the front buffer, and no buffer swap will be done between frames. It should be stressed that running Java 3D with double buffering disabled is not recommended.
public boolean getSceneAntialiasingAvailable()
This method specifies whether the underlying hardware supports scene-level antialiasing on this canvas. This is equivalent to
((Boolean)queryProperties().get("sceneAntialiasingAvailable")).
    booleanValue()
public View getView()
Retrieves the View object that points to this Canvas3D.
public Screen3D getScreen3D()
Retrieves the Screen3D object to which this Canvas3D is attached.
public final Map queryProperties()
This method returns a read-only Map object containing key-value pairs that define various properties for this Canvas3D. All of the keys are String objects. The values are key-specific, but most will be Boolean, Integer, Double, or String objects. The currently-defined keys are

Key (String) Value Type Description
doubleBufferAvailable Boolean A Boolean indicating whether double buffering is available for this Canvas3D. This is equivalent to the getDoubleBufferAvailable method. If this flag is false, the Canvas3D will be rendered in single buffer mode; requests to enable double buffering will be ignored.
stereoAvailable Boolean A Boolean indicating whether stereo is available for this Canvas3D. This is equivalent to the getStereoAvailable method. If this flag is false, the Canvas3D will be rendered in monoscopic mode; requests to enable stereo will be ignored.
sceneAntialiasingAvailable Boolean A Boolean indicating whether scene antialiasing is available for this Canvas3D. This is equivalent to the getSceneAntialiasing-Available method. If this flag is false, requests to enable scene antialiasing will be ignored.
texture3DAvailable Boolean A Boolean indicating whether 3D Texture mapping is available for this Canvas3D. If this flag is false, 3D texture mapping is either not supported by the underlying rendering layer or is otherwise unavailable for this particular Canvas3D. All use of 3D texture mapping will be ignored in this case.
textureColorTableSize Integer An Integer indicating the maximum size of the texture color table for this Canvas3D. If the size is 0, the texture color table either is not supported by the underlying rendering layer or is otherwise unavailable for this particular Canvas3D. An attempt to use a texture color table larger than textureColorTableSize will be ignored; no color lookup will be performed.
compressedGeometry.
majorVersionNumber Integer An Integer indicating the major version number of the version of compressed geometry supported by this version of Java 3D.
compressedGeometry.
minorVersionNumber Integer An Integer indicating the minor version number of the version of compressed geometry supported by this version of Java 3D.
compressedGeometry.
minorMinorVersionNumber Integer An Integer indicating the minor-minor version number of the version of compressed geometry supported by this version of Java 3D.

9.9.4 GraphicsConfigTem-plate3D Object
This GraphicsConfigTemplate3D class is used to obtain a valid GraphicsConfiguration that can be used by Java 3D. A user instantiates one of these objects and then sets all nondefault attributes as desired. The getGraphicsConfiguration method found in the java.awt.GraphicsDevice class is then called with this GraphicsConfigTemplate. A valid GraphicsConfiguration that meets or exceeds what was requested in the java.awt.GraphicsConfigTemplate is returned.

Constructors
public GraphicsConfigTemplate3D()
This constructor constructs a new GraphicsConfigTemplate3D and sets all values to their default:

Parameter Default Value
doubleBuffer REQUIRED
stereo UNNECESSARY
sceneAntialiasing UNNECESSARY
depthSize 16
redSize 2
greenSize 2
blueSize 2

Methods
public void setDoubleBuffer(int value)
public int getDoubleBuffer()
These methods set and retrieve the double-buffering attribute. The valid values are REQUIRED, PREFERRED, and UNNECESSARY.
public void setStereo(int value)
public int getStereo()
These methods set and retrieve the stereo attribute. The valid values are REQUIRED, PREFERRED, and UNNECESSARY.
public void setSceneAntialiasing(int value)
public int getSceneAntialiasing()
These methods set and retrieve the scene antialiasing attribute. The valid values are REQUIRED, PREFERRED, and UNNECESSARY.
public void setDepthSize(int value)
public int getDepthSize()
These methods set and retrieve the depth buffer size requirement.
public void setRedSize(int value)
public int getRedSize()
public void setGreenSize(int value)
public int getGreenSize()
public void setBlueSize(int value)
public int getBlueSize()
These methods set and retrieve the number of red, green, and blue bits requested by this template.
public java.awt.GraphicsConfiguration
       getBestConfiguration(java.awt.GraphicsConfiguration[] gc)
This method returns the "best" possible configuration that passes the criteria defined in the GraphicsConfigTemplate3D.
public boolean
       isGraphicsConfigSupported(java.awt.GraphicsConfiguration
       gc)
This method returns a boolean indicating whether the given GraphicsConfiguration can be used to create a drawing surface that can be rendered to. This method returns true if this GraphicsConfiguration object can be used to create surfaces that can be rendered to, false if the GraphicsConfiguration cannot be used to create a drawing surface usable by this API.

9.10 The PhysicalBody Object
Java 3D defines a PhysicalBody object that contains information concerning the end user's physical characteristics. The head parameters allow end users to specify their own head's characteristics, such as the location of the eyes and the interpupilary distance. See Section C.8, "The PhysicalBody Object," for details. The default values are sufficient for applications that are running in a non-head-tracked environment and do not manually set the eyepoint.

Constructors
public PhysicalBody()
This constructor constructs and initializes a default PhysicalBody object.

9.11 The PhysicalEnvironment Object
The PhysicalEnvironment object defines several methods that are described in Section C.9, "The PhysicalEnvironment Object." The default values are sufficient for applications that do not use continuous input devices that are run in a non-head-tracked display environment.

Constructors
public PhysicalEnvironment()
Constructs and initializes a default PhysicalEnvironment object.

Parameter	Default Value
view policy	SCREEN_VIEW
projection policy	PERSPECTIVE_PROJECTION
screen scale policy	SCALE_SCREEN_SIZE
window resize policy	PHYSICAL_WORLD
window movement policy	PHYSICAL_WORLD
window eyepoint policy	RELATIVE_TO_FIELD_OF_VIEW
monoscopic view policy (deprecated in this class)	CYCLOPEAN_EYE_VIEW
front clip policy	PHYSICAL_EYE
back clip policy	PHYSICAL_EYE
visibility policy	VISIBILITY_DRAW_VISIBLE
coexistence centering flag	true
compatibility mode	false
left projection	identity
right projection	identity
vpc to ec transform	identity
physical body	null
physical environment	null
screen scale	1.0
field of view	/4
left manual eye in coexistence	(-0.033, 0.0, 0.4572)
right manual eye in coexistence	(0.033, 0.0, 0.4572)
front clip distance	0.1
back clip distance	10.0
tracking enable	false
user head to vworld enable	false
list of Canvas3D objects	empty
depth buffer freeze transparent	true
scene antialiasing	false
local eye lighting	false
view platform	null
behavior scheduler running	true
view running	true
minimum frame duration	0

Parameter	Default Value
physical screen width	0.0254/90.0 * screen width (in pixels)
physical screen height	0.0254/90.0 * screen height (in pixels)
tracker base to image plate transform	identity
head tracker to left image plate transform	identity
head tracker to right image plate transform	identity
off-screen size	(0,0)

Parameter	Default Value
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)

Key (String)	Value Type	Description
doubleBufferAvailable	Boolean	A Boolean indicating whether double buffering is available for this Canvas3D. This is equivalent to the getDoubleBufferAvailable method. If this flag is false, the Canvas3D will be rendered in single buffer mode; requests to enable double buffering will be ignored.
stereoAvailable	Boolean	A Boolean indicating whether stereo is available for this Canvas3D. This is equivalent to the getStereoAvailable method. If this flag is false, the Canvas3D will be rendered in monoscopic mode; requests to enable stereo will be ignored.
sceneAntialiasingAvailable	Boolean	A Boolean indicating whether scene antialiasing is available for this Canvas3D. This is equivalent to the getSceneAntialiasing-Available method. If this flag is false, requests to enable scene antialiasing will be ignored.
texture3DAvailable	Boolean	A Boolean indicating whether 3D Texture mapping is available for this Canvas3D. If this flag is false, 3D texture mapping is either not supported by the underlying rendering layer or is otherwise unavailable for this particular Canvas3D. All use of 3D texture mapping will be ignored in this case.
textureColorTableSize	Integer	An Integer indicating the maximum size of the texture color table for this Canvas3D. If the size is 0, the texture color table either is not supported by the underlying rendering layer or is otherwise unavailable for this particular Canvas3D. An attempt to use a texture color table larger than textureColorTableSize will be ignored; no color lookup will be performed.
compressedGeometry. majorVersionNumber	Integer	An Integer indicating the major version number of the version of compressed geometry supported by this version of Java 3D.
compressedGeometry. minorVersionNumber	Integer	An Integer indicating the minor version number of the version of compressed geometry supported by this version of Java 3D.
compressedGeometry. minorMinorVersionNumber	Integer	An Integer indicating the minor-minor version number of the version of compressed geometry supported by this version of Java 3D.

Parameter	Default Value
doubleBuffer	REQUIRED
stereo	UNNECESSARY
sceneAntialiasing	UNNECESSARY
depthSize	16
redSize	2
greenSize	2
blueSize	2

The Java 3D API Specification

9.4.4 Associating Geometry with a ViewPlatform

9.7 The View Object

9.7.3 Projection and Clip Parameters

9.7.7 Depth Buffer

9.9 The Canvas3D Object

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