Contents Previous Next

Java 3D API Specification


C H A P T E R8
View Model




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.

8.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 transparently generate stereo views.

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

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

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

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

8.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 8-1 shows graphically the central role of the View object and the subsidiary role of its component objects.

The view-related objects shown in Figure 8-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."

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.

8.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 8-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 8-2.

A VirtualUniverse may have many different ViewPlatforms, but a particular View object can only attach itself to a single ViewPlatform. Thus, each rendering onto a Canvas3D is done from the point of view of a single ViewPlatform.

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

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

8.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 8.7, "The View Object."

8.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 final void setViewAttachPolicy(int policy)
public final int getViewAttachPolicy()
These methods set and retrieve the coexistence center in virtual world policy. 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:

8.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).

8.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 or not 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.

8.5.1 Composing Model and Viewing Transformations

Figure 8-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.

In our scene graph, what we would normally consider the model transformation would consist of the following three transformations: LT1T2. By multiplying LT1T2 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 (LTv1)-1 or Tv1-1L-1. This presents a problem since coordinates in the virtual universe are 256-bit fixed-point values, which cannot be used to efficiently represent transformed points.

Fortunately, however, there is a solution to this problem. Composing the model and view platform transformations gives us

Tv1-1L-1LT1T2 = Tv1-1IT1T2 = Tv1-1T1T2,

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 Tvn-1...Tv2-1Tv1-1T1T2...Tm.

As was mentioned above, 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 PETv1-1T1T2. In general this is PETvn-1...Tv2-1Tv1-1T1T2...Tm.

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

8.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, L1 and L2, with the View attached to a ViewPlatform in L1. According to our general formula, the modeling transformation-the transformation that takes points in object coordinates and transforms them into VirtualUniverse coordinates-is LT1T2...Tm. In our specific example, a point in Locale L2 would be transformed into VirtualUniverse coordinates by L2T1T2...Tm. The view platform transformation would be (L1Tv1Tv1...Tvn)-1 or Tvn-1...Tv2-1Tv1-1L1-1. Composing these two matrices gives us

Tvn-1...Tv2-1Tv1-1L1-1L2T1T2...Tm.

Thus, to render objects in another Locale, it is sufficient to compute L1-1L2 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 L1-1L2 is a simple translation by L2 - L1. Again, it is not necessary to actually 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 only render those Locales that really are "close enough."

8.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:

8.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 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 CYCLOPEAN_EYE_VIEW
front clip policy PHYSICAL_EYE
back clip policy PHYSICAL_EYE
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
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

Methods
The View object specifies the following methods. 

public final void setPhysicalBody(PhysicalBody physicalBody)
public final PhysicalBody getPhysicalBody()
These methods set and retrieve the View's PhysicalBody object. See Section 8.10, "The PhysicalBody Object," for more information on the PhysicalBody object. 

public final void setPhysicalEnvironment(PhysicalEnvironment 
physicalEnvironment)
public final PhysicalEnvironment getPhysicalEnvironment()
These methods set and retrieve the View's PhysicalEnvironment object. See Section 8.11, "The PhysicalEnvironment Object," for more information on the PhysicalEnvironment object. 

public final 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 5.10, "ViewPlatform Node," for more information on ViewPlatform objects. 

public final ViewPlatform getViewPlatform()
This method retrieves the currently attached ViewPlatform object. 

public final Canvas3D getCanvas3D(int index)
public final void setCanvas3D(Canvas3D canvas3D, int index)
public final void addCanvas3D(Canvas3D canvas3D)
public final void insertCanvas3D(Canvas3D canvas3D, int index)
public final void removeCanvas3D(int index)
public final 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 8.9, "The Canvas3D Object" for more information on Canvas3D objects. 

public final Enumeration getAllCanvas3Ds()
This method gets the Enumeration object of all the Canvas3Ds. 

public final void addInputDevice(InputDevice device)
public final Enumeration allInputDevices()
These methods are deprecated. Use PhysicalEnvironment.addInputDevice(InputDevice) instead of View.addInputDevice(InputDevice). Use Phys-ical-Environment.getAllInputDevices() instead of View.allInputDevices(). 

public final void addAudioDevice(AudioDevice device)
public final Enumeration allAudioDevices()
These methods are deprecated. Use PhysicalEnvironment.setAudioDevice(AudioDevice) instead of View.addAudioDevice(AudioDevice). Use PhysicalEnvironment.getAudioDevice() instead of View.allAudioDev-ices().

8.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 final void setProjectionPolicy(int policy)
public final int getProjectionPolicy()
These two methods set and retrieve the current projection policy for this view. The projection policies are as follows: 

public final void setLocalEyeLightingEnable(boolean flag)
public final 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.

8.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. This policy 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 final void setWindowResizePolicy(int policy)
public final 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 only happening in the physical world. This implies that rendered objects continue to fill the same percentage of the newly sized window, using more or less 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 final void setWindowMovementPolicy(int policy)
public final 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.

8.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 final void setFrontClipPolicy(int policy)
public final int getFrontClipPolicy()
public final void setBackClipPolicy(int policy)
public final 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.

8.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 final void setFieldOfView(double fieldOfView)
public final 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 5.5, "Clip Node").

There are several considerations that need to be taken into account when choosing values for the front and back clip distances.

Violating any of the above rules will result in undefined behavior. In many cases, no picture will be drawn.

8.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 that 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.

8.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 if 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.

8.7.6 Scene Antialiasing

public final void setSceneAntialiasingEnable(boolean flag)
public final 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.

8.7.7 Depth Buffer

public final void setDepthBufferFreezeTransparent(boolean flag)
public final 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.

8.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 only available 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 8.9.2, "Other Canvas3D Parameters."

Default values for Screen3D parameters are as follows:

Parameter Default Value
physical screen width 0.35
physical screen height 0.27
tracker base to image plate transform identity
head tracker to left image plate transform identity
head tracker to right image plate transform identity

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()
This method retrieves the screen's (image plate's) width and height in pixels. 

public final double getPhysicalScreenWidth()
public final double getPhysicalScreenHeight()
These methods retrieve the screen's (image plate's) physical width and height in meters.

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

Constructors
The Canvas3D object specifies one constructor. 

public Canvas3D(GraphicsConfiguration graphicsConfiguration)
This constructs and initializes a new Canvas3D object given a valid Graphics-Configuration object. 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

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 8.9.3, "GraphicsConfig-Temp-late-3D Object."

For more information on the GraphicsConfiguration object see the Java 2D specification, which will be part of the AWT in JDK 1.2.

8.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 only allows applications to access these values, not 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.

8.9.2 Other Canvas3D Parameters

public final boolean getStereoAvailable()
This method specifies whether the underlying hardware supports field-sequential stereo on this canvas. 

public final boolean getStereoEnable()
public final 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 final void getDoubleBufferAvailable()
This method specifies whether the underlying hardware supports double buffering on this canvas. 

public final boolean getDoubleBufferEnable()
public final 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 final boolean getSceneAntialiasingAvailable()
This method specifies whether the underlying hardware supports scene-level antialiasing. 

public final View getView()
Retrieves the View object that points to this Canvas3D. 

public final Screen3D getScreen3D()
Retrieves the Screen3D object to which this Canvas3D is attached.

8.9.3 GraphicsConfig-Temp-late-3D 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 non-default attributes as desired. The getGraphicsConfiguration method found in the java.awt.GraphicsDevice class is then called with this GraphicsConfigTemplate. A valid GraphicsConfiguration is returned that meets or exceeds what was requested in the java.awt.GraphicsConfigTemplate.

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" configuration possible that passes the criteria defined in the GraphicsConfigTemplate3D. 

public boolean 
       isGraphicsConfigSupported(java.awt.GraphicsConfiguration 
       gc)
This method returns a boolean indicating whether or not 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.

8.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 that do not manually set the eyepoint.

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

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


Contents Previous Next

Java 3D API Specification


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