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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `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

    Constructors
    Constructor and Description
    `ViewInfo(View view)` Creates a new ViewInfo for the specified View.
    `ViewInfo(View view, int autoUpdateFlags)` Creates a new ViewInfo for the specified View.
    `ViewInfo(View view, int autoUpdateFlags, java.util.Map screenMap, java.util.Map viewPlatformMap)` Creates a new ViewInfo for the specified View.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `clear()` Release all static memory references held by ViewInfo, if any.
    `void` | `getCoexistenceToImagePlate(Canvas3D c3d, Transform3D coe2ipl, Transform3D coe2ipr)` Gets the current transforms from coexistence coordinates to image plate coordinates and copies them into the given Transform3Ds.
    `void` | `getCoexistenceToViewPlatform(Canvas3D c3d, Transform3D coe2vp)` Gets the current transform from coexistence coordinates to view platform coordinates and copies it into the given transform.
    `void` | `getCoexistenceToVworld(Canvas3D c3d, Transform3D coe2vw)` Gets the current transform from coexistence coordinates to virtual world coordinates and copies it into the given transform.
    `void` | `getEyeToImagePlate(Canvas3D c3d, Transform3D e2ipl, Transform3D e2ipr)` Gets the transforms from eye coordinates to image plate coordinates and copies them into the Transform3Ds specified.
    `void` | `getEyeToViewPlatform(Canvas3D c3d, Transform3D e2vpl, Transform3D e2vpr)` Gets the current transforms from eye coordinates to view platform coordinates and copies them into the given Transform3Ds.
    `void` | `getEyeToVworld(Canvas3D c3d, Transform3D e2vwl, Transform3D e2vwr)` Gets the current transforms from eye coordinates to virtual world coordinates and copies them into the given Transform3Ds.
    `protected Transform3D` | `getHeadTrackerToTrackerBase()` Returns a reference to a Transform3D containing the current transform from head tracker coordinates to tracker base coordinates.
    `void` | `getImagePlateToViewPlatform(Canvas3D c3d, Transform3D ip2vpl, Transform3D ip2vpr)` Gets the current transforms from image plate coordinates to view platform coordinates and copies them into the given Transform3Ds.
    `void` | `getImagePlateToVworld(Canvas3D c3d, Transform3D ip2vwl, Transform3D ip2vwr)` Gets the current transforms from image plate coordinates to virtual world coordinates and copies them into the given Transform3Ds.
    `void` | `getInverseProjection(Canvas3D c3d, Transform3D cc2el, Transform3D cc2er)` Gets the transforms from clipping coordinates to eye coordinates and copies them into the given Transform3Ds.
    `void` | `getInverseViewPlatformProjection(Canvas3D c3d, Transform3D cc2vpl, Transform3D cc2vpr)` Gets the transforms from clipping coordinates to view platform coordinates and copies them into the given Transform3Ds.
    `void` | `getInverseVworldProjection(Canvas3D c3d, Transform3D cc2vwl, Transform3D cc2vwr)` Gets the transforms from clipping coordinates to virtual world coordinates and copies them into the given Transform3Ds.
    `double` | `getPhysicalBackClipDistance(Canvas3D c3d)` Gets the back clip distance scaled to physical meters.
    `double` | `getPhysicalFrontClipDistance(Canvas3D c3d)` Gets the front clip distance scaled to physical meters.
    `double` | `getPhysicalHeight(Canvas3D c3d)` Gets the height of the specified canvas scaled to physical meters.
    `void` | `getPhysicalLocation(Canvas3D c3d, Point3d location)` Gets the location of the specified canvas relative to the image plate origin.
    `double` | `getPhysicalToViewPlatformScale(Canvas3D c3d)` Gets the scale factor from physical meters to view platform units.
    `double` | `getPhysicalToVirtualScale(Canvas3D c3d)` Gets the scale factor from physical meters to virtual units.
    `double` | `getPhysicalWidth(Canvas3D c3d)` Gets the width of the specified canvas scaled to physical meters.
    `void` | `getPixelLocationInImagePlate(Canvas3D c3d, int x, int y, Point3d location)` Gets the location of the AWT pixel value and copies it into the specified Point3d.
    `void` | `getProjection(Canvas3D c3d, Transform3D e2ccl, Transform3D e2ccr)` Gets the transforms from eye coordinates to clipping coordinates and copies them into the given Transform3Ds.
    `void` | `getSensorToVworld(Canvas3D c3d, Sensor sensor, Transform3D s2vw)` Gets a read from the specified sensor and transforms it to virtual world coordinates.
    `void` | `getTrackerBaseToViewPlatform(Canvas3D c3d, Transform3D tb2vp)` Gets the transform from tracker base coordinates to view platform coordinates and copies it into the specified Transform3D.
    `void` | `getTrackerBaseToVworld(Canvas3D c3d, Transform3D tb2vw)` Gets the transform from tracker base coordinates to virtual world coordinates and copies it into the specified Transform3D.
    `void` | `getViewPlatformToCoexistence(Canvas3D c3d, Transform3D vp2coe)` Gets the current transform from view platform coordinates to coexistence coordinates and copies it into the given transform.
    `void` | `getViewPlatformToEye(Canvas3D c3d, Transform3D vp2el, Transform3D vp2er)` Gets the current transforms from view platform coordinates to eye coordinates and copies them into the given Transform3Ds.
    `void` | `updateCanvas(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(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.
    `protected boolean` | `useHeadTracking()` Returns `true` if head tracking should be used.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, 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(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(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(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(Canvas3D c3d,
                                         Transform3D ip2vpl,
                                         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(Canvas3D c3d,
                                   Transform3D ip2vwl,
                                   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(Canvas3D c3d,
                                        Transform3D coe2ipl,
                                        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(Canvas3D c3d,
                                          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(Canvas3D c3d,
                                          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(Canvas3D c3d,
                                    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(Canvas3D c3d,
                                Transform3D e2ipl,
                                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(Canvas3D c3d,
                                  Transform3D e2vpl,
                                  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(Canvas3D c3d,
                                  Transform3D vp2el,
                                  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(Canvas3D c3d,
                            Transform3D e2vwl,
                            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(Canvas3D c3d,
                           Transform3D e2ccl,
                           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(Canvas3D c3d,
                                  Transform3D cc2el,
                                  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(Canvas3D c3d,
                                              Transform3D cc2vpl,
                                              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(Canvas3D c3d,
                                        Transform3D cc2vwl,
                                        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(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(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(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(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(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(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(Canvas3D c3d,
                                 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(Canvas3D c3d,
                                          int x,
                                          int y,
                                          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(Canvas3D c3d,
                               Sensor sensor,
                               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(Canvas3D c3d,
                                          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(Canvas3D c3d,
                                    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(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(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.

    - #### getHeadTrackerToTrackerBase

          protected Transform3D getHeadTrackerToTrackerBase()

      Returns a reference to a Transform3D containing the current transform from head tracker coordinates to tracker base coordinates. It is only called if `useHeadTracking` returns true and a head position update is specified with `updateHead` or the `HEAD_AUTO_UPDATE` constructor flag.

      The default implementation uses the head tracking sensor specified by the View's PhysicalEnvironment, and reads it by calling the sensor's `getRead` method directly. The result is a sensor reading that may have been taken at a slightly different time from the one used by the renderer. This method can be overridden to synchronize the two readings through an external mechanism.

      Returns:
        current head tracker to tracker base transform
      See Also:
        `useHeadTracking()`, `updateHead`, `HEAD_AUTO_UPDATE`

    - #### useHeadTracking

          protected boolean useHeadTracking()

      Returns `true` if head tracking should be used.

      The default implementation returns `true` if the View's `getTrackingEnable` method and the PhysicalEnvironment's `getTrackingAvailable` method both return `true`. These are the same conditions under which the Java 3D renderer uses head tracking. This method can be overridden if there is any need to decouple the head tracking status of ViewInfo from the renderer.

      Returns:
        `true` if ViewInfo should use head tracking

Copyright 1996-2008 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.