com.sun.j3d.utils.universe
Class ViewInfo

java.lang.Object
  com.sun.j3d.utils.universe.ViewInfo

public class ViewInfo
extends java.lang.Object

Provides methods to extract synchronized transform information from a View. These transforms are derived from application scene graph information, as opposed to similar core Java 3D methods that derive transforms from internally maintained data. This allows updates to the scene graph to be synchronized with the current view platform position.

The architecture of the Java 3D 1.3 sample implementation introduces a frame latency between updates to the application scene graph structure and their effects on internal Java 3D state. getImagePlateToVworld and other methods in the core Java 3D classes use a transform from view platform coordinates to virtual world coordinates that can be out of date with respect to the state of the view platform as set by the application. When an application uses the transforms returned by those methods to update view dependent parts of the scene graph, those updates might not be synchronized with what the viewer actually sees.

The methods in this class work around this problem at the expense of querying the application state of the scene graph to get the current transform from view platform to virtual world coordinates. This can involve a potential performance degradation, however, since the application scene graph state is not designed for high performance queries. The view platform must also have ALLOW_LOCAL_TO_VWORLD_READ capability set, which potentially inhibits internal scene graph optimization.

On the other hand, application behaviors that create the view platform transformation directly will have access to it without the need to query it from the scene graph; in that case, the transforms from physical coordinates to view platform coordinates provided by this class are all that are needed. The ALLOW_LOCAL_TO_VWORLD_READ view platform capability doesn't need to be set for these applications.

Other Synchronization Issues

Scene graph updates are guaranteed to take effect in the same frame only if run from the processStimulus() method of a Behavior. Updates from multiple behaviors are only guaranteed to take effect in the same frame if they're responding to a WakeupOnElapsedFrames(0) condition. Use a single behavior to perform view dependent updates if possible; otherwise, use WakeupOnElapsedFrames(0) and set behavior scheduling intervals to ensure that behaviors that need the current view platform transform are run after it's set. Updating scene graph elements from anything other than the Behavior thread, such as an external input thread or a renderer callback in Canvas3D, will not necessarily be synchronized with rendering.

Direct updates to geometry data have a different frame latency than updates to scene graph transforms and structure. In the Java 3D 1.3 architecture, updates to by-reference geometry arrays and texture data have a 1-frame latency, while updates to transforms and scene graph structure have a 2-frame latency. Because of bug 4799494, which is outstanding in Java 3D 1.3.1, updates to by-copy geometry arrays also have a 1-frame latency. It is therefore recommended that view dependent scene graph updates be limited to transforms and scene graph structure only.

If it is not possible to avoid updating geometry directly, then these updates must be delayed by one frame in order to remain synchronized with the view platform. This can be accomplished by creating an additional behavior to actually update the geometry, separate from the behavior that computes the changes that need to be made based on current view state. If the update behavior is awakened by a behavior post from the computing behavior then the update will be delayed by a single frame.

Implementation Notes

This utility is essentially a rewrite of a few private Java 3D core classes, but designed for public use and source code availability. The source code may be helpful in understanding some of the more complex aspects of the view model, especially with regards to various interactions between attributes which are not adequately documented. None of the actual core Java 3D source code is used, but the code is designed to comply with the view model as defined by the Java 3D Specification, so it can be considered an alternative implementation. This class will produce the same results as the Java 3D core implementation except for:

• The frame latency issue for virtual world transforms.
• Active clip node status. If a clip node is active in the scene graph, it should override the view's back clip plane. This class has no such information, so this can't be implemented.
• "Infinite" view transforms for background geometry. These are simply the rotation components of the normal view transforms with adjusted clip planes. Again, this function depends upon scene graph content inaccessible to this class.
• Small floating point precision differences resulting from the alternative computations.
• Bugs in this class and the Java 3D core.
• Tracked head position.

The last item deserves some mention. Java 3D provides no way to directly query the tracked head position being used by the renderer. The View's getUserHeadToVworld method always incorporates a virtual world transform that is out of date with respect to the application scene graph state. ViewInfo reads data from the head tracking sensor directly, but since head trackers are continuous input devices, getting the same data that the renderer is using is unlikely. See the source code for the private method getHeadInfo in this class for more information and possible workarounds.

Thread Safety

All transforms are lazily evaluated. The updateScreen, updateCanvas, updateViewPlatform, updateView, and updateHead methods just set flags indicating that derived transforms need to be recomputed; they are safe to call from any thread. updateCanvas, for example, can safely be called from an AWT event listener.

Screens and view platforms can be shared between separate views in the Java 3D view model. To remain accurate, ViewInfo also allows this sharing. Since it is likely that a multi-view application has separate threads managing each view, potential concurrent modification of data associated with a screen or a view platform is internally synchronized in this class. It is safe for each thread to use its own instance of a ViewInfo corresponding to the view it is managing.

Otherwise, none of the other methods in this class are internally synchronized. Except for the update methods mentioned above, a single instance of ViewInfo should not be used by more than one concurrent thread without external synchronization.

Since:

Java 3D 1.3.1

Field Summary

static int	CANVAS_AUTO_UPDATE Indicates that updates to a Canvas3D associated with the View should be automatically checked with each call to a public method in this class.
static int	HEAD_AUTO_UPDATE Indicates that updates to the tracked head position should be automatically checked with each call to a public method in this class.
static int	PLATFORM_AUTO_UPDATE Indicates that updates to the ViewPlatform localToVworld transform should be automatically checked with each call to a public method in this class.
static int	SCREEN_AUTO_UPDATE Indicates that updates to a Screen3D associated with the View should be automatically checked with each call to a public method in this class.
static int	VIEW_AUTO_UPDATE Indicates that updates to the View should be automatically checked with each call to a public method in this class.

Constructor Summary

ViewInfo(javax.media.j3d.View view)
Creates a new ViewInfo for the specified View.

ViewInfo(javax.media.j3d.View view, int autoUpdateFlags)
Creates a new ViewInfo for the specified View.

ViewInfo(javax.media.j3d.View view, int autoUpdateFlags, java.util.Map screenMap, java.util.Map viewPlatformMap)
Creates a new ViewInfo for the specified View.

Method Summary

static void	clear() Release all static memory references held by ViewInfo, if any.
void	getCoexistenceToImagePlate(javax.media.j3d.Canvas3D c3d, javax.media.j3d.Transform3D coe2ipl, javax.media.j3d.Transform3D coe2ipr) Gets the current transforms from coexistence coordinates to image plate coordinates and copies them into the given Transform3Ds.
void	getCoexistenceToViewPlatform(javax.media.j3d.Canvas3D c3d, javax.media.j3d.Transform3D coe2vp) Gets the current transform from coexistence coordinates to view platform coordinates and copies it into the given transform.
void	getCoexistenceToVworld(javax.media.j3d.Canvas3D c3d, javax.media.j3d.Transform3D coe2vw) Gets the current transform from coexistence coordinates to virtual world coordinates and copies it into the given transform.
void	getEyeToImagePlate(javax.media.j3d.Canvas3D c3d, javax.media.j3d.Transform3D e2ipl, javax.media.j3d.Transform3D e2ipr) Gets the transforms from eye coordinates to image plate coordinates and copies them into the Transform3Ds specified.
void	getEyeToViewPlatform(javax.media.j3d.Canvas3D c3d, javax.media.j3d.Transform3D e2vpl, javax.media.j3d.Transform3D e2vpr) Gets the current transforms from eye coordinates to view platform coordinates and copies them into the given Transform3Ds.
void	getEyeToVworld(javax.media.j3d.Canvas3D c3d, javax.media.j3d.Transform3D e2vwl, javax.media.j3d.Transform3D e2vwr) Gets the current transforms from eye coordinates to virtual world coordinates and copies them into the given Transform3Ds.
void	getImagePlateToViewPlatform(javax.media.j3d.Canvas3D c3d, javax.media.j3d.Transform3D ip2vpl, javax.media.j3d.Transform3D ip2vpr) Gets the current transforms from image plate coordinates to view platform coordinates and copies them into the given Transform3Ds.
void	getImagePlateToVworld(javax.media.j3d.Canvas3D c3d, javax.media.j3d.Transform3D ip2vwl, javax.media.j3d.Transform3D ip2vwr) Gets the current transforms from image plate coordinates to virtual world coordinates and copies them into the given Transform3Ds.
void	getInverseProjection(javax.media.j3d.Canvas3D c3d, javax.media.j3d.Transform3D cc2el, javax.media.j3d.Transform3D cc2er) Gets the transforms from clipping coordinates to eye coordinates and copies them into the given Transform3Ds.
void	getInverseViewPlatformProjection(javax.media.j3d.Canvas3D c3d, javax.media.j3d.Transform3D cc2vpl, javax.media.j3d.Transform3D cc2vpr) Gets the transforms from clipping coordinates to view platform coordinates and copies them into the given Transform3Ds.
void	getInverseVworldProjection(javax.media.j3d.Canvas3D c3d, javax.media.j3d.Transform3D cc2vwl, javax.media.j3d.Transform3D cc2vwr) Gets the transforms from clipping coordinates to virtual world coordinates and copies them into the given Transform3Ds.
double	getPhysicalBackClipDistance(javax.media.j3d.Canvas3D c3d) Gets the back clip distance scaled to physical meters.
double	getPhysicalFrontClipDistance(javax.media.j3d.Canvas3D c3d) Gets the front clip distance scaled to physical meters.
double	getPhysicalHeight(javax.media.j3d.Canvas3D c3d) Gets the height of the specified canvas scaled to physical meters.
void	getPhysicalLocation(javax.media.j3d.Canvas3D c3d, javax.vecmath.Point3d location) Gets the location of the specified canvas relative to the image plate origin.
double	getPhysicalToViewPlatformScale(javax.media.j3d.Canvas3D c3d) Gets the scale factor from physical meters to view platform units.
double	getPhysicalToVirtualScale(javax.media.j3d.Canvas3D c3d) Gets the scale factor from physical meters to virtual units.
double	getPhysicalWidth(javax.media.j3d.Canvas3D c3d) Gets the width of the specified canvas scaled to physical meters.
void	getPixelLocationInImagePlate(javax.media.j3d.Canvas3D c3d, int x, int y, javax.vecmath.Point3d location) Gets the location of the AWT pixel value and copies it into the specified Point3d.
void	getProjection(javax.media.j3d.Canvas3D c3d, javax.media.j3d.Transform3D e2ccl, javax.media.j3d.Transform3D e2ccr) Gets the transforms from eye coordinates to clipping coordinates and copies them into the given Transform3Ds.
void	getSensorToVworld(javax.media.j3d.Canvas3D c3d, javax.media.j3d.Sensor sensor, javax.media.j3d.Transform3D s2vw) Gets a read from the specified sensor and transforms it to virtual world coordinates.
void	getTrackerBaseToViewPlatform(javax.media.j3d.Canvas3D c3d, javax.media.j3d.Transform3D tb2vp) Gets the transform from tracker base coordinates to view platform coordinates and copies it into the specified Transform3D.
void	getTrackerBaseToVworld(javax.media.j3d.Canvas3D c3d, javax.media.j3d.Transform3D tb2vw) Gets the transform from tracker base coordinates to virtual world coordinates and copies it into the specified Transform3D.
void	getViewPlatformToCoexistence(javax.media.j3d.Canvas3D c3d, javax.media.j3d.Transform3D vp2coe) Gets the current transform from view platform coordinates to coexistence coordinates and copies it into the given transform.
void	getViewPlatformToEye(javax.media.j3d.Canvas3D c3d, javax.media.j3d.Transform3D vp2el, javax.media.j3d.Transform3D vp2er) Gets the current transforms from view platform coordinates to eye coordinates and copies them into the given Transform3Ds.
void	updateCanvas(javax.media.j3d.Canvas3D c3d) Arrange for an update of cached canvas parameters.
void	updateHead() Arrange for an update of the cached head position if head tracking is enabled.
void	updateScreen(javax.media.j3d.Screen3D s3d) Arrange for an update of cached screen parameters.
void	updateView() Arrange for an update of cached view parameters.
void	updateViewPlatform() Arrange for an update of the cached localToVworld transform of the view platform.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SCREEN_AUTO_UPDATE

public static final int SCREEN_AUTO_UPDATE

Indicates that updates to a Screen3D associated with the View should be automatically checked with each call to a public method in this class.

See Also:

Constant Field Values

CANVAS_AUTO_UPDATE

public static final int CANVAS_AUTO_UPDATE

Indicates that updates to a Canvas3D associated with the View should be automatically checked with each call to a public method in this class.

See Also:

Constant Field Values

VIEW_AUTO_UPDATE

public static final int VIEW_AUTO_UPDATE

Indicates that updates to the View should be automatically checked with each call to a public method in this class.

See Also:

Constant Field Values

HEAD_AUTO_UPDATE

public static final int HEAD_AUTO_UPDATE

Indicates that updates to the tracked head position should be automatically checked with each call to a public method in this class.

See Also:

Constant Field Values

PLATFORM_AUTO_UPDATE

public static final int PLATFORM_AUTO_UPDATE

Indicates that updates to the ViewPlatform localToVworld transform should be automatically checked with each call to a public method in this class. The View must be attached to a ViewPlatform which is part of a live scene graph, and the ViewPlatform node must have its ALLOW_LOCAL_TO_VWORLD_READ capability set.

See Also:

Constant Field Values

Constructor Detail

ViewInfo

public ViewInfo(javax.media.j3d.View view)

Creates a new ViewInfo for the specified View.

Applications are responsible for informing this class of changes to the View, its Canvas3D and Screen3D components, the tracked head position, and the ViewPlatform's localToVworld transform. These notifications are performed with the updateView, updateCanvas, updateScreen, updateHead, and updateViewPlatform methods.

The View must be attached to a ViewPlatform. If the ViewPlatform is attached to a live scene graph, then ALLOW_POLICY_READ capability must be set on the ViewPlatform node.

Parameters:

view - the View to use

See Also:

updateView, updateCanvas(Canvas3D), updateScreen(Screen3D), updateHead, updateViewPlatform()

ViewInfo

public ViewInfo(javax.media.j3d.View view,
                int autoUpdateFlags)

Creates a new ViewInfo for the specified View. The View must be attached to a ViewPlatform. If the ViewPlatform is attached to a live scene graph, then ALLOW_POLICY_READ capability must be set on the ViewPlatform node.

Parameters:

view - the View to use

autoUpdateFlags - a logical OR of any of the VIEW_AUTO_UPDATE, CANVAS_AUTO_UPDATE, SCREEN_AUTO_UPDATE, HEAD_AUTO_UPDATE, or PLATFORM_AUTO_UPDATE flags to control whether changes to the View, its Canvas3D or Screen3D components, the tracked head position, or the ViewPlatform's localToVworld transform are checked automatically with each call to a public method of this class; if a flag is not set, then the application must inform this class of updates to the corresponding data

ViewInfo

public ViewInfo(javax.media.j3d.View view,
                int autoUpdateFlags,
                java.util.Map screenMap,
                java.util.Map viewPlatformMap)

Creates a new ViewInfo for the specified View. The View must be attached to a ViewPlatform. If the ViewPlatform is attached to a live scene graph, then ALLOW_POLICY_READ capability must be set on the ViewPlatform node.

ViewInfo caches Screen3D and ViewPlatform data, but Screen3D and ViewPlatform instances are shared across multiple Views in the Java 3D view model. Since ViewInfo is per-View, all ViewInfo constructors except for this one use static references to manage the shared Screen3D and ViewPlatform objects. In this constructor, however, the caller supplies two Map instances to hold these references for all ViewInfo instances, so static references can be avoided; it can be used to wrap this class into a multi-view context that provides the required maps.

Alternatively, the other constructors can be used by calling ViewInfo.clear when done with ViewInfo, or by simply retaining the static references until the JVM exits.

Parameters:

view - the View to use

autoUpdateFlags - a logical OR of any of the VIEW_AUTO_UPDATE, CANVAS_AUTO_UPDATE, SCREEN_AUTO_UPDATE, HEAD_AUTO_UPDATE, or PLATFORM_AUTO_UPDATE flags to control whether changes to the View, its Canvas3D or Screen3D components, the tracked head position, or the ViewPlatform's localToVworld transform are checked automatically with each call to a public method of this class; if a flag is not set, then the application must inform this class of updates to the corresponding data

screenMap - a writeable Map to hold Screen3D information

viewPlatformMap - a writeable Map to hold ViewPlatform information

Method Detail

getImagePlateToViewPlatform

public void getImagePlateToViewPlatform(javax.media.j3d.Canvas3D c3d,
                                        javax.media.j3d.Transform3D ip2vpl,
                                        javax.media.j3d.Transform3D ip2vpr)

Gets the current transforms from image plate coordinates to view platform coordinates and copies them into the given Transform3Ds.

With a monoscopic canvas the image plate transform is copied to the first argument and the second argument is not used. For a stereo canvas the first argument receives the left image plate transform, and if the second argument is non-null it receives the right image plate transform. These transforms are always the same unless a head mounted display driven by a single stereo canvas is in use.

Parameters:

c3d - the Canvas3D associated with the image plate

ip2vpl - the Transform3D to receive the left transform

ip2vpr - the Transform3D to receive the right transform, or null

getImagePlateToVworld

public void getImagePlateToVworld(javax.media.j3d.Canvas3D c3d,
                                  javax.media.j3d.Transform3D ip2vwl,
                                  javax.media.j3d.Transform3D ip2vwr)

Gets the current transforms from image plate coordinates to virtual world coordinates and copies them into the given Transform3Ds.

With a monoscopic canvas the image plate transform is copied to the first argument and the second argument is not used. For a stereo canvas the first argument receives the left image plate transform, and if the second argument is non-null it receives the right image plate transform. These transforms are always the same unless a head mounted display driven by a single stereo canvas is in use.

The View must be attached to a ViewPlatform which is part of a live scene graph, and the ViewPlatform node must have its ALLOW_LOCAL_TO_VWORLD_READ capability set.

Parameters:

c3d - the Canvas3D associated with the image plate

ip2vwl - the Transform3D to receive the left transform

ip2vwr - the Transform3D to receive the right transform, or null

getCoexistenceToImagePlate

public void getCoexistenceToImagePlate(javax.media.j3d.Canvas3D c3d,
                                       javax.media.j3d.Transform3D coe2ipl,
                                       javax.media.j3d.Transform3D coe2ipr)

Gets the current transforms from coexistence coordinates to image plate coordinates and copies them into the given Transform3Ds. The default coexistence centering enable and window movement policies are true and PHYSICAL_WORLD respectively, which will center coexistence coordinates to the middle of the canvas, aligned with the screen (image plate). A movement policy of VIRTUAL_WORLD centers coexistence coordinates to the middle of the screen.

If coexistence centering is turned off, then canvases and screens can have arbitrary positions with respect to coexistence, set through the the Screen3D trackerBaseToImagePlate transform and the PhysicalEnvironment coexistenceToTrackerBase transform. These are calibration constants used for multiple fixed screen displays. For head mounted displays the transform is determined by the user head position along with calibration parameters found in Screen3D and PhysicalBody. (See the source code for the private method getEyesHMD for more information).

With a monoscopic canvas the image plate transform is copied to the first argument and the second argument is not used. For a stereo canvas the first argument receives the left image plate transform, and if the second argument is non-null it receives the right image plate transform. These transforms are always the same unless a head mounted display driven by a single stereo canvas is in use.

Parameters:

c3d - the Canvas3D associated with the image plate

coe2ipl - the Transform3D to receive the left transform

coe2ipr - the Transform3D to receive the right transform, or null

getViewPlatformToCoexistence

public void getViewPlatformToCoexistence(javax.media.j3d.Canvas3D c3d,
                                         javax.media.j3d.Transform3D vp2coe)

Gets the current transform from view platform coordinates to coexistence coordinates and copies it into the given transform. View platform coordinates are always aligned with coexistence coordinates but may differ in scale and in Y and Z offset. The scale is derived from the window resize and screen scale policies, while the offset is derived from the view attach policy.

Java 3D constructs a view from the physical position of the eyes relative to the physical positions of the image plates; it then uses a view platform to position that physical configuration into the virtual world and from there computes the correct projections of the virtual world onto the physical image plates. Coexistence coordinates are used to place the physical positions of the view platform, eyes, head, image plate, sensors, and tracker base in relation to each other. The view platform is positioned with respect to the virtual world through the scene graph, so the view platform to coexistence transform defines the space in which the virtual world and physical world coexist.

This method requires a Canvas3D. A different transform may be returned for each canvas in the view if any of the following apply:

• The window resize policy is PHYSICAL_WORLD, which alters the scale depending upon the width of the canvas.
• The screen scale policy is SCALE_SCREEN_SIZE, which alters the scale depending upon the width of the screen associated with the canvas.
• A window eyepoint policy of RELATIVE_TO_FIELD_OF_VIEW with a view attach policy of NOMINAL_HEAD in effect, which sets the view platform Z offset in coexistence coordinates based on the width of the canvas. These are the default policies. The offset also follows the width of the canvas when the NOMINAL_FEET view attach policy is used.

Parameters:

c3d - the Canvas3D to use

vp2coe - the Transform3D to receive the transform

getCoexistenceToViewPlatform

public void getCoexistenceToViewPlatform(javax.media.j3d.Canvas3D c3d,
                                         javax.media.j3d.Transform3D coe2vp)

Gets the current transform from coexistence coordinates to view platform coordinates and copies it into the given transform.

This method requires a Canvas3D. The returned transform may differ across canvases for the same reasons as discussed in the description of getViewPlatformToCoexistence.

Parameters:

c3d - the Canvas3D to use

coe2vp - the Transform3D to receive the transform

See Also:

getViewPlatformToCoexistence(Canvas3D, Transform3D)

getCoexistenceToVworld

public void getCoexistenceToVworld(javax.media.j3d.Canvas3D c3d,
                                   javax.media.j3d.Transform3D coe2vw)

Gets the current transform from coexistence coordinates to virtual world coordinates and copies it into the given transform.

The View must be attached to a ViewPlatform which is part of a live scene graph, and the ViewPlatform node must have its ALLOW_LOCAL_TO_VWORLD_READ capability set.

This method requires a Canvas3D. The returned transform may differ across canvases for the same reasons as discussed in the description of getViewPlatformToCoexistence.

Parameters:

c3d - the Canvas3D to use

coe2vw - the Transform3D to receive the transform

See Also:

getViewPlatformToCoexistence(Canvas3D, Transform3D)

getEyeToImagePlate

public void getEyeToImagePlate(javax.media.j3d.Canvas3D c3d,
                               javax.media.j3d.Transform3D e2ipl,
                               javax.media.j3d.Transform3D e2ipr)

Gets the transforms from eye coordinates to image plate coordinates and copies them into the Transform3Ds specified.

When head tracking is used the eye positions are taken from the head position and set in relation to the image plates with each Screen3D's trackerBaseToImagePlate transform. Otherwise the window eyepoint policy is used to derive the eyepoint relative to the image plate. When using a head mounted display the eye position is determined solely by calibration constants in Screen3D and PhysicalBody; see the source code for the private method getEyesHMD for more information.

Eye coordinates are always aligned with image plate coordinates, so these transforms are always just translations. With a monoscopic canvas the eye transform is copied to the first argument and the second argument is not used. For a stereo canvas the first argument receives the left eye transform, and if the second argument is non-null it receives the right eye transform.

Parameters:

c3d - the Canvas3D associated with the image plate

e2ipl - the Transform3D to receive left transform

e2ipr - the Transform3D to receive right transform, or null

getEyeToViewPlatform

public void getEyeToViewPlatform(javax.media.j3d.Canvas3D c3d,
                                 javax.media.j3d.Transform3D e2vpl,
                                 javax.media.j3d.Transform3D e2vpr)

Gets the current transforms from eye coordinates to view platform coordinates and copies them into the given Transform3Ds.

With a monoscopic canvas the eye transform is copied to the first argument and the second argument is not used. For a stereo canvas the first argument receives the left eye transform, and if the second argument is non-null it receives the right eye transform.

This method requires a Canvas3D. When using a head mounted display, head tracking with fixed screens, or a window eyepoint policy of RELATIVE_TO_COEXISTENCE, then the transforms returned may be different for each canvas if stereo is not in use and they have different monoscopic view policies. They may additionally differ in scale across canvases with the PHYSICAL_WORLD window resize policy or the SCALE_SCREEN_SIZE screen scale policy, which alter the scale depending upon the width of the canvas or the width of the screen respectively.

With window eyepoint policies of RELATIVE_TO_FIELD_OF_VIEW, RELATIVE_TO_SCREEN, or RELATIVE_TO_WINDOW, then the transforms returned may differ across canvases due to the following additional conditions:

• The window eyepoint policy is RELATIVE_TO_WINDOW or RELATIVE_TO_SCREEN, in which case the manual eye position in image plate can be set differently for each canvas.
• The window eyepoint policy is RELATIVE_TO_FIELD_OF_VIEW and the view attach policy is NOMINAL_SCREEN, which decouples the view platform's canvas Z offset from the eyepoint's canvas Z offset.
• The eyepoint X and Y coordinates are centered in the canvas with a window eyepoint policy of RELATIVE_TO_FIELD_OF_VIEW or RELATIVE_TO_WINDOW, and a window movement policy of VIRTUAL_WORLD centers the view platform's X and Y coordinates to the middle of the screen.
• Coexistence centering is set false, which allows each canvas and screen to have a different position with respect to coexistence coordinates.

Parameters:

c3d - the Canvas3D to use

e2vpl - the Transform3D to receive the left transform

e2vpr - the Transform3D to receive the right transform, or null

getViewPlatformToEye

public void getViewPlatformToEye(javax.media.j3d.Canvas3D c3d,
                                 javax.media.j3d.Transform3D vp2el,
                                 javax.media.j3d.Transform3D vp2er)

Gets the current transforms from view platform coordinates to eye coordinates and copies them into the given Transform3Ds.

With a monoscopic canvas the eye transform is copied to the first argument and the second argument is not used. For a stereo canvas the first argument receives the left eye transform, and if the second argument is non-null it receives the right eye transform.

This method requires a Canvas3D. The transforms returned may differ across canvases for all the same reasons discussed in the description of getEyeToViewPlatform.

Parameters:

c3d - the Canvas3D to use

vp2el - the Transform3D to receive the left transform

vp2er - the Transform3D to receive the right transform, or null

See Also:

getEyeToViewPlatform(Canvas3D, Transform3D, Transform3D)

getEyeToVworld

public void getEyeToVworld(javax.media.j3d.Canvas3D c3d,
                           javax.media.j3d.Transform3D e2vwl,
                           javax.media.j3d.Transform3D e2vwr)

Gets the current transforms from eye coordinates to virtual world coordinates and copies them into the given Transform3Ds.

With a monoscopic canvas the eye transform is copied to the first argument and the second argument is not used. For a stereo canvas the first argument receives the left eye transform, and if the second argument is non-null it receives the right eye transform.

The View must be attached to a ViewPlatform which is part of a live scene graph, and the ViewPlatform node must have its ALLOW_LOCAL_TO_VWORLD_READ capability set.

This method requires a Canvas3D. The transforms returned may differ across canvases for all the same reasons discussed in the description of getEyeToViewPlatform.

Parameters:

c3d - the Canvas3D to use

e2vwl - the Transform3D to receive the left transform

e2vwr - the Transform3D to receive the right transform, or null

See Also:

getEyeToViewPlatform(Canvas3D, Transform3D, Transform3D)

getProjection

public void getProjection(javax.media.j3d.Canvas3D c3d,
                          javax.media.j3d.Transform3D e2ccl,
                          javax.media.j3d.Transform3D e2ccr)

Gets the transforms from eye coordinates to clipping coordinates and copies them into the given Transform3Ds. These transforms take a viewing volume bounded by the physical canvas edges and the physical front and back clip planes and project it into a range bound to [-1.0 .. +1.0] on each of the X, Y, and Z axes. If a perspective projection has been specified then the physical image plate eye location defines the apex of a viewing frustum; otherwise, the orientation of the image plate determines the direction of a parallel projection.

With a monoscopic canvas the projection transform is copied to the first argument and the second argument is not used. For a stereo canvas the first argument receives the left projection transform, and if the second argument is non-null it receives the right projection transform.

If either of the clip policies VIRTUAL_EYE or VIRTUAL_SCREEN are used, then the View should be attached to a ViewPlatform that is part of a live scene graph and that has its ALLOW_LOCAL_TO_VWORLD_READ capability set; otherwise, a scale factor of 1.0 will be used for the scale factor from virtual world units to view platform units.

Parameters:

c3d - the Canvas3D to use

e2ccl - the Transform3D to receive left transform

e2ccr - the Transform3D to receive right transform, or null

getInverseProjection

public void getInverseProjection(javax.media.j3d.Canvas3D c3d,
                                 javax.media.j3d.Transform3D cc2el,
                                 javax.media.j3d.Transform3D cc2er)

Gets the transforms from clipping coordinates to eye coordinates and copies them into the given Transform3Ds. These transforms take the clip space volume bounded by the range [-1.0 .. + 1.0] on each of the X, Y, and Z and project it into eye coordinates.

With a monoscopic canvas the projection transform is copied to the first argument and the second argument is not used. For a stereo canvas the first argument receives the left projection transform, and if the second argument is non-null it receives the right projection transform.

If either of the clip policies VIRTUAL_EYE or VIRTUAL_SCREEN are used, then the View should be attached to a ViewPlatform that is part of a live scene graph and that has its ALLOW_LOCAL_TO_VWORLD_READ capability set; otherwise, a scale factor of 1.0 will be used for the scale factor from virtual world units to view platform units.

Parameters:

c3d - the Canvas3D to use

cc2el - the Transform3D to receive left transform

cc2er - the Transform3D to receive right transform, or null

getInverseViewPlatformProjection

public void getInverseViewPlatformProjection(javax.media.j3d.Canvas3D c3d,
                                             javax.media.j3d.Transform3D cc2vpl,
                                             javax.media.j3d.Transform3D cc2vpr)

Gets the transforms from clipping coordinates to view platform coordinates and copies them into the given Transform3Ds. These transforms take the clip space volume bounded by the range [-1.0 .. +1.0] on each of the X, Y, and Z axes and project into the view platform coordinate system.

With a monoscopic canvas the projection transform is copied to the first argument and the second argument is not used. For a stereo canvas the first argument receives the left projection transform, and if the second argument is non-null it receives the right projection transform.

If either of the clip policies VIRTUAL_EYE or VIRTUAL_SCREEN are used, then the View should be attached to a ViewPlatform that is part of a live scene graph and that has its ALLOW_LOCAL_TO_VWORLD_READ capability set; otherwise, a scale factor of 1.0 will be used for the scale factor from virtual world units to view platform units.

Parameters:

c3d - the Canvas3D to use

cc2vpl - the Transform3D to receive left transform

cc2vpr - the Transform3D to receive right transform, or null

getInverseVworldProjection

public void getInverseVworldProjection(javax.media.j3d.Canvas3D c3d,
                                       javax.media.j3d.Transform3D cc2vwl,
                                       javax.media.j3d.Transform3D cc2vwr)

Gets the transforms from clipping coordinates to virtual world coordinates and copies them into the given Transform3Ds. These transforms take the clip space volume bounded by the range [-1.0 .. +1.0] on each of the X, Y, and Z axes and project into the virtual world.

With a monoscopic canvas the projection transform is copied to the first argument and the second argument is not used. For a stereo canvas the first argument receives the left projection transform, and if the second argument is non-null it receives the right projection transform.

The View must be attached to a ViewPlatform which is part of a live scene graph, and the ViewPlatform node must have its ALLOW_LOCAL_TO_VWORLD_READ capability set.

Parameters:

c3d - the Canvas3D to use

cc2vwl - the Transform3D to receive left transform

cc2vwr - the Transform3D to receive right transform, or null

getPhysicalFrontClipDistance

public double getPhysicalFrontClipDistance(javax.media.j3d.Canvas3D c3d)

Gets the front clip distance scaled to physical meters. This is useful for ensuring that objects positioned relative to a physical coordinate system (such as eye, image plate, or coexistence) will be within the viewable Z depth. This distance will be relative to either the eye or the image plate depending upon the front clip policy.

Note that this is not necessarily the clip distance as set by setFrontClipDistance, even when the front clip policy is PHYSICAL_SCREEN or PHYSICAL_EYE. If the window resize policy is PHYSICAL_WORLD, then physical clip distances as specified are in fact scaled by the ratio of the window width to the screen width. The Java 3D view model does this to prevent the physical clip planes from moving with respect to the virtual world when the window is resized.

If either of the clip policies VIRTUAL_EYE or VIRTUAL_SCREEN are used, then the View should be attached to a ViewPlatform that is part of a live scene graph and that has its ALLOW_LOCAL_TO_VWORLD_READ capability set; otherwise, a scale factor of 1.0 will be used for the scale factor from virtual world units to view platform units.

Parameters:

c3d - the Canvas3D to use

Returns:

the physical front clip distance

getPhysicalBackClipDistance

public double getPhysicalBackClipDistance(javax.media.j3d.Canvas3D c3d)

Gets the back clip distance scaled to physical meters. This is useful for ensuring that objects positioned relative to a physical coordinate system (such as eye, image plate, or coexistence) will be within the viewable Z depth. This distance will be relative to either the eye or the image plate depending upon the back clip policy.

Note that this is not necessarily the clip distance as set by setBackClipDistance, even when the back clip policy is PHYSICAL_SCREEN or PHYSICAL_EYE. If the window resize policy is PHYSICAL_WORLD, then physical clip distances as specified are in fact scaled by the ratio of the window width to the screen width. The Java 3D view model does this to prevent the physical clip planes from moving with respect to the virtual world when the window is resized.

If either of the clip policies VIRTUAL_EYE or VIRTUAL_SCREEN are used, then the View should be attached to a ViewPlatform that is part of a live scene graph and that has its ALLOW_LOCAL_TO_VWORLD_READ capability set; otherwise, a scale factor of 1.0 will be used for the scale factor from virtual world units to view platform units.

Parameters:

c3d - the Canvas3D to use

Returns:

the physical back clip distance

getPhysicalToViewPlatformScale

public double getPhysicalToViewPlatformScale(javax.media.j3d.Canvas3D c3d)

Gets the scale factor from physical meters to view platform units.

This method requires a Canvas3D. A different scale may be returned for each canvas in the view if any of the following apply:

• The window resize policy is PHYSICAL_WORLD, which alters the scale depending upon the width of the canvas.
• The screen scale policy is SCALE_SCREEN_SIZE, which alters the scale depending upon the width of the screen associated with the canvas.

Parameters:

c3d - the Canvas3D to use

Returns:

the physical to view platform scale

getPhysicalToVirtualScale

public double getPhysicalToVirtualScale(javax.media.j3d.Canvas3D c3d)

Gets the scale factor from physical meters to virtual units.

This method requires a Canvas3D. A different scale may be returned across canvases for the same reasons as discussed in the description of getPhysicalToViewPlatformScale.

The View must be attached to a ViewPlatform which is part of a live scene graph, and the ViewPlatform node must have its ALLOW_LOCAL_TO_VWORLD_READ capability set.

Parameters:

c3d - the Canvas3D to use

Returns:

the physical to virtual scale

See Also:

getPhysicalToViewPlatformScale(Canvas3D)

getPhysicalWidth

public double getPhysicalWidth(javax.media.j3d.Canvas3D c3d)

Gets the width of the specified canvas scaled to physical meters. This is derived from the physical screen width as reported by the Screen3D associated with the canvas. If the screen width is not explicitly set using the setPhysicalScreenWidth method of Screen3D, then Java 3D will derive the screen width based on a screen resolution of 90 pixels/inch.

Parameters:

c3d - the Canvas3D to use

Returns:

the width of the canvas scaled to physical meters

getPhysicalHeight

public double getPhysicalHeight(javax.media.j3d.Canvas3D c3d)

Gets the height of the specified canvas scaled to physical meters. This is derived from the physical screen height as reported by the Screen3D associated with the canvas. If the screen height is not explicitly set using the setPhysicalScreenHeight method of Screen3D, then Java 3D will derive the screen height based on a screen resolution of 90 pixels/inch.

Parameters:

c3d - the Canvas3D to use

Returns:

the height of the canvas scaled to physical meters

getPhysicalLocation

public void getPhysicalLocation(javax.media.j3d.Canvas3D c3d,
                                javax.vecmath.Point3d location)

Gets the location of the specified canvas relative to the image plate origin. This is derived from the physical screen parameters as reported by the Screen3D associated with the canvas. If the screen width and height are not explicitly set in Screen3D, then Java 3D will derive those screen parameters based on a screen resolution of 90 pixels/inch.

Parameters:

c3d - the Canvas3D to use

location - the output position, in meters, of the lower-left corner of the canvas relative to the image plate lower-left corner; Z is always 0.0

getPixelLocationInImagePlate

public void getPixelLocationInImagePlate(javax.media.j3d.Canvas3D c3d,
                                         int x,
                                         int y,
                                         javax.vecmath.Point3d location)

Gets the location of the AWT pixel value and copies it into the specified Point3d.

Parameters:

c3d - the Canvas3D to use

x - the X coordinate of the pixel relative to the upper-left corner of the canvas

y - the Y coordinate of the pixel relative to the upper-left corner of the canvas

location - the output position, in meters, relative to the lower-left corner of the image plate; Z is always 0.0

getSensorToVworld

public void getSensorToVworld(javax.media.j3d.Canvas3D c3d,
                              javax.media.j3d.Sensor sensor,
                              javax.media.j3d.Transform3D s2vw)

Gets a read from the specified sensor and transforms it to virtual world coordinates. The View must be attached to a ViewPlatform which is part of a live scene graph, and the ViewPlatform node must have its ALLOW_LOCAL_TO_VWORLD_READ capability set.

This method requires a Canvas3D. The returned transform may differ across canvases for the same reasons as discussed in the description of getViewPlatformToCoexistence.

Parameters:

sensor - the Sensor instance to read

s2vw - the output transform

See Also:

getViewPlatformToCoexistence(Canvas3D, Transform3D)

getTrackerBaseToViewPlatform

public void getTrackerBaseToViewPlatform(javax.media.j3d.Canvas3D c3d,
                                         javax.media.j3d.Transform3D tb2vp)

Gets the transform from tracker base coordinates to view platform coordinates and copies it into the specified Transform3D.

This method requires a Canvas3D. The returned transform may differ across canvases for the same reasons as discussed in the description of getViewPlatformToCoexistence.

Parameters:

c3d - the Canvas3D to use

tb2vp - the output transform

See Also:

getViewPlatformToCoexistence(Canvas3D, Transform3D)

getTrackerBaseToVworld

public void getTrackerBaseToVworld(javax.media.j3d.Canvas3D c3d,
                                   javax.media.j3d.Transform3D tb2vw)

Gets the transform from tracker base coordinates to virtual world coordinates and copies it into the specified Transform3D. The View must be attached to a ViewPlatform which is part of a live scene graph, and the ViewPlatform node must have its ALLOW_LOCAL_TO_VWORLD_READ capability set.

This method requires a Canvas3D. The returned transform may differ across canvases for the same reasons as discussed in the description of getViewPlatformToCoexistence.

Parameters:

c3d - the Canvas3D to use

tb2vw - the output transform

See Also:

getViewPlatformToCoexistence(Canvas3D, Transform3D)

clear

public static void clear()

Release all static memory references held by ViewInfo, if any. These are the Screen3D and ViewPlatform maps shared by all existing ViewInfo instances if they're not provided by a constructor. Releasing the screen references effectively releases all canvas references in all ViewInfo instances as well.

It is safe to continue using existing ViewInfo instances after calling this method; the data in the released maps will be re-derived as needed.

updateScreen

public void updateScreen(javax.media.j3d.Screen3D s3d)

Arrange for an update of cached screen parameters. If automatic update has not been enabled, then this method should be called if any of the attributes of the Screen3D have changed. This method should also be called if the screen changes pixel resolution.

Parameters:

s3d - the Screen3D to update

updateCanvas

public void updateCanvas(javax.media.j3d.Canvas3D c3d)

Arrange for an update of cached canvas parameters. If automatic update has not been enabled, then this method should be called if any of the attributes of the Canvas3D have changed. These attributes include the canvas position and size, but do not include the attributes of the associated Screen3D, which are cached separately.

Parameters:

c3d - the Canvas3D to update

updateView

public void updateView()

Arrange for an update of cached view parameters. If automatic update has not been enabled for the View, then this method should be called if any of the attributes of the View associated with this object have changed.

These do not include the attributes of the existing Canvas3D or Screen3D components of the View, but do include the attributes of all other components such as the PhysicalEnvironment and PhysicalBody, and all attributes of the attached ViewPlatform except for its localToVworld transform. The screen and canvas components as well as the ViewPlatform's localToVworld are cached separately.

This method should also be called if the ViewPlatform is replaced with another using the View's attachViewPlatform method, or if any of the setCanvas3D, addCanvas3D, insertCanvas3D, removeCanvas3D, or removeAllCanvas3Ds methods of View are called to change the View's canvas list.

Calling this method causes most transforms to be re-derived. It should be used only when necessary.

updateHead

public void updateHead()

Arrange for an update of the cached head position if head tracking is enabled. If automatic update has not enabled for the head position, then this method should be called anytime a new head position is to be read.

updateViewPlatform

public void updateViewPlatform()

Arrange for an update of the cached localToVworld transform of the view platform. If automatic update has not been enabled for this transform, then this method should be called anytime the view platform has been repositioned in the virtual world and a transform involving virtual world coordinates is desired.

The View must be attached to a ViewPlatform which is part of a live scene graph, and the ViewPlatform node must have its ALLOW_LOCAL_TO_VWORLD_READ capability set.