Contents Previous Next

Java 3D API Specification

C H A P T E R8

The Java 3D 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-degree-of-freedom input peripherals such as headtrackers. 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, without modification of the scene graph, images to a broad range of display devices including standard computer displays, multiple-projection display rooms, and head-mounted displays. 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 Java 3D's 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 Implementation 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 that the end user view, navigate, display, and even interact with that 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 where 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 view 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 Implementation 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 affect 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 Local 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 moves his or her head and hands within. 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 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-1 shows a portion of a scene graph containing a ViewPlatform. 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-1.

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.3.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 (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-2, 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 getTransform3D and setTransform3D.

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

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

public final void setViewAttachPolicy(int policy)
public final int getViewAttachPolicy()

The view attach policy determines how Java 3D places the user's eye point as a function of head position. The variable can contain one of: NOMINAL_SCREEN, NOMINAL_HEAD, or NOMINAL_FEET.

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.3.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 Section C.5, "The View Object"). 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.4 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-3 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-3 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 is derived in this chapter. The remainder of the details are described in Appendix C, "View Model Implementation Details."

Together, these objects describe the geometry of viewing rather than explicitly providing a viewing or projection matrix. Java 3D's renderer uses this information to construct the appropriate view 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.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 Implementation 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 clip distances to construct a viewing frustum.

8.5.1 Composite 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 transform 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 transform would consist of the three transforms: LT1T2. By multiplying LT1T2 by a vertex in the shape object, we would transform that vertex into the VirtualUniverse's coordinate system. What we would normally consider the view platform transform 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 transforms 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 transforms 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

As was mentioned above, the View object contains the remainder of the view information, specifically the eye matrix E that takes points in the ViewPlatform'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 is described in Appendix C, "View Model Implementation 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 in the case where 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. If we remember our general formula, the modeling transform-the transform 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 transform 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 transforms. Given that a Locale is represented by a single high-resolution coordinate position, the transform 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 such that the difference in their high-resolution coordinates can be represented in double precision by a non-infinite 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."


The View object specifies the following constructor.

public View()

Constructs and initializes a new View object.


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

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.

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 policy is as follows:

public final void setLocalEyeLightingEnable(boolean flag)
public final boolean getLocalEyeLightingEnable()

These methods set and retrieve the eye lighting flag, which indicates whether the local eye point 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 eye point to the vertex. If this flag is set to false, a single view vector is computed from the eye point 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.2 Clip Policies

The clip policies determine how Java 3D interprets clip 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.

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. Values are one of: 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. Values are one of: 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 clip 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. 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.7.1, "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 offset by 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 offset by the back-clip distance are not drawn. Measurements are done in the space (physical or virtual) as 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").

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 needs to primarily 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 trackerbase 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."


These methods provide applications with information concerning the underlying display hardware. This includes information such as whether the display screen supports stereo, the screen's width and height in pixels, and the screen's width and height 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 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.


The Canvas3D object specifies one constructor.

public Canvas3D()

This constructs and initializes a new Canvas3D object that Java 3D can render into.

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 View getView()

Retrieves the view object that points to this Canvas3D.

public final Screen3D getScreen3D()

Retrieves the Screen3D object that this Canvas3D is attached to.

8.9.3 Canvas3D Policies

Canvas3D policies tell Java 3D how to interpret various end-user changes to a Canvas3D such as a resize of a window or moving a window to another position on their display screen. The Java 3D API defaults use policies that mimic "normal" 2D window system semantics as closely as possible. Canvas (Window) Sizing and Movement

When users resize or move windows (canvas objects), Java 3D can choose to think of the canvas 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 resize requests. The window resize policies are specified by two constants.

public static final int PHYSICAL_WORLD

This variable specifies that Java 3D applies the associated policy in the physical world.

public static final int VIRTUAL_WORLD

This variable specifies that Java 3D applies the associated policy in the virtual world.

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 resize 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 resize operations as also happening in the virtual world whenever a resize 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.10 The PhysicalBody Object

Java 3D defines a PhysicalBody object that contains information concerning the end-user's body 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 eye-point.

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.

public PhysicalEnvironment()

Constructs and initializes a default PhysicalEnvironment object.

Contents Previous Next

Java 3D API Specification

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