The View object contains all parameters needed in rendering a three dimensional scene from one viewpoint. A view contains a list of Canvas3D objects that the view is rendered into. It exists outside of the scene graph, but attaches to a ViewPlatform leaf node object in the scene graph. It also contains a reference to a PhysicalBody and a PhysicalEnvironment object.
The View object is the main Java 3D object for controlling the Java 3D viewing model. All of the components that specify the view transform used to render to the 3D canvases are either contained in the View object or in objects that are referenced by the View object.
Java 3D allows applications to specify multiple simultaneously active View objects, each controlling its own set of canvases.
The Java 3D View object has several instance variables and methods, but most are calibration variables or user-helping functions. The viewing policies defined by the View object are described below.
Policies
The View object defines the following policies:
- View policy - informs Java 3D whether it should generate the view using the head-tracked system of transformations or the head-mounted system of transformations. These policies are attached to the Java 3D View object. There are two view policies:
- SCREEN_VIEW - specifies that Java 3D should compute a new viewpoint using the sequence of transforms appropriate to screen-based head-tracked display environments (fish-tank VR/portals/VR-desks). This is the default setting.
- HMD_VIEW - specifies that Java 3D should compute a new viewpoint using the sequence of transforms appropriate to head mounted display environments. This policy is not available in compatibility mode (see the setCompatibilityModeEnable method description).
- Projection policy - specifies whether Java 3D should generate a parallel projection or a perspective projection. This policy is attached to the Java 3D View object. There are two projection policies:
- PARALLEL_PROJECTION - specifies that a parallel projection transform is computed.
- PERSPECTIVE_PROJECTION - specifies that a perspective projection transform is computed. This is the default policy.
- Screen scale policy - specifies where the screen scale comes from. There are two screen scale policies:
- SCALE_SCREEN_SIZE - specifies that the scale is derived from the physical screen according to the following formula (this is the default mode):
screenScale = physicalScreenWidth / 2.0
- SCALE_EXPLICIT - pecifies that the scale is taken directly from the user-provided
screenScale attribute (see the setScreenScale method description).
- Window resize policy - specifies how Java 3D modifies the view when users resize windows. When users resize or move windows, Java 3D can choose to think of the window as attached either to the physical world or to the virtual world. The window resize policy allows an application to specify how the view model will handle resizing requests. There are two window resize policies:
- VIRTUAL_WORLD - implies that the original image remains the same size on the screen but the user sees more or less of the virtual world depending on whether the window grew or shrank in size.
- PHYSICAL_WORLD - implies that the original image continues to fill the window in the same way using more or less pixels depending on whether the window grew or shrank in size.
- Window movement policy - specifies what part of the virtual world Java 3D draws as a function of window placement on the screen. There are two window movement policies:
- VIRTUAL_WORLD - implies that the image seen in the window changes as the position of the window shifts on the screen. (This mode acts as if the window were a window into the virtual world.)
- PHYSICAL_WORLD - implies that the image seen in the window remains the same no matter where the user positions the window on the screen.
- Window eyepoint policy - comes into effect in a non-head-tracked environment. The policy tells Java 3D how to construct a new view frustum based on changes in the field of view and in the Canvas3D's location on the screen. The policy only comes into effect when the application changes a parameter that can change the placement of the eyepoint relative to the view frustum. There are three window eyepoint policies:
- RELATIVE_TO_SCREEN - tells Java 3D to interpret the eye's position relative to the entire screen. No matter where an end user moves a window (a Canvas3D), Java 3D continues to interpret the eye's position relative to the screen. This implies that the view frustum changes shape whenever an end user moves the location of a window on the screen. In this mode, the field of view is read-only.
- RELATIVE_TO_WINDOW - specifies that Java 3D should interpret the eye's position information relative to the window (Canvas3D). No matter where an end user moves a window (a Canvas3D), Java 3D continues to interpret the eye's position relative to that window. This implies that the frustum remains the same no matter where the end user moves the window on the screen. In this mode, the field of view is read-only.
- RELATIVE_TO_FIELD_OF_VIEW - tells Java 3D that it should modify the eyepoint position so it is located at the appropriate place relative to the window to match the specified field of view. This implies that the view frustum will change whenever the application changes the field of view. In this mode, the eye position is read-only. This is the default setting.
- RELATIVE_TO_COEXISTENCE - tells Java 3D to interpret the eye's position in coexistence coordinates. In this mode, the eye position is taken from the view (rather than the Canvas3D) and transformed from coexistence coordinates to image plate coordinates for each Canvas3D. The resulting eye position is relative to the screen. As in RELATIVE_TO_SCREEN mode, this implies that the view frustum changes shape whenever an end user moves the location of a window on the screen. In this mode, the field of view is read-only.
- Front and back clip policies - specifies how Java 3D interprets clipping distances to both the near and far clip planes. The policies can contain one of four values specifying whether a distance measurement should be interpreted in the physical or the virtual world and whether that distance measurement should be interpreted relative to the physical eyepoint or the physical screen. The front and back clip policies are specified separately. The front clip policy determines where Java 3D places the front clipping plane. The back clip policy determines where Java 3D places the back clipping plane. The values for both front and back clipping planes are:
- VIRTUAL_EYE - specifies that the associated distance is from the eye and in units of virtual distance.
- PHYSICAL_EYE - specifies that the associated distance is from the eye and in units of physical distance (in meters). This is the default policy for both front and back clipping.
- VIRTUAL_SCREEN - specifies that the associated distance is from the screen and in units of virtual distance.
- PHYSICAL_SCREEN - specifies that the associated distance is from the screen and in units of physical distance (in meters).
- Visibility policy - specifies how visible and invisible objects are drawn. There are three visibility policies:
- VISIBILITY_DRAW_VISIBLE - only visible objects are drawn (this is the default).
- VISIBILITY_DRAW_INVISIBLE - only invisible objects are drawn.
- VISIBILITY_DRAW_ALL - both visible and invisible objects are drawn.
- Transparency sorting policy - specifies whether and how transparent objects are sorted. Sorting multiple transparent objects is necessary to avoid artifacts caused by overlapping transparent objects. There are two transparency sorting policies:
- TRANSPARENCY_SORT_NONE - no depth sorting of transparent objects is performed (this is the default). Transparent objects are drawn after opaque objects, but are not sorted from back to front.
- TRANSPARENCY_SORT_GEOMETRY - transparent objects are depth-sorted on a per-geometry basis. Each geometry object of each transparent Shape3D node is drawn from back to front. Note that this policy will not split geometry into smaller pieces, so intersecting or intertwined objects may not be sorted correctly. The method used for determining which geometry is closer is implementation dependent.
Projection and Clip Parameters The projection and clip parameters determine the view model's field of view and the front and back clipping distances.
- Field of view - specifies the view model's horizontal field of view in radians, when in the default non-head-tracked mode. This value is ignored when the view model is operating in head-tracked mode, or when the Canvas3D's window eyepoint policy is set to a value other than the default setting of RELATIVE_TO_FIELD_OF_VIEW.
- Front clip distance - specifies the distance away from the clip origin, specified by the front clip policy variable, in the direction of gaze where objects stop disappearing. Objects closer than the clip origin (eye or screen) plus the front clip distance are not drawn. Measurements are done in the space (physical or virtual) that is specified by the associated front clip policy parameter.
- Back clip distance - specifies the distance away from the clip origin (specified by the back clip policy variable) in the direction of gaze where objects begin disappearing. Objects farther away from the clip origin (eye or screen) plus the back clip distance are not drawn. Measurements are done in the space (physical or virtual) that is specified by the associated back clip policy parameter. The View object's back clip distance is ignored if the scene graph contains an active Clip leaf node.
There are several considerations to take into account when choosing values for the front and back clip distances.
- The front clip distance must be greater than 0.0 in physical eye coordinates.
- The front clipping plane must be in front of the back clipping plane, that is, the front clip distance must be less than the back clip distance in physical eye coordinates.
- The front and back clip distances, in physical eye coordinates, must be less than the largest positive single-precision floating point value, Float.MAX_VALUE. In practice, since these physical eye coordinate distances are in meters, the values should be much less than that.
- The ratio of the back distance divided by the front distance, in physical eye coordinates, affects Z-buffer precision. This ratio should be less than about 3000 to accommodate 16-bit Z-buffers. Values of 100 to less than 1000 will produce better results.
Violating any of the above rules will result in undefined behavior. In many cases, no picture will be drawn.
Frame Start Time, Duration, and Number There are five methods used to get information about system execution and performance:
getCurrentFrameStartTime returns the time at which the most recent rendering frame started. getLastFrameDuration returns the duration, in milliseconds, of the most recently completed rendering frame.
getFrameNumber returns the frame number for this view.
getMaxFrameStartTimes retrieves the implementation-dependent maximum number of frames whose start times will be recorded by the system.
getFrameStartTimes copies the last k frame start time values into the user-specified array.
View Traversal and Behavior Scheduling The following methods control the traversal, the rendering, and the execution of the behavior scheduler for this view:
startBehaviorScheduler starts the behavior scheduler running after it has been stopped. stopBehaviorScheduler stops the behavior scheduler after all currently-scheduled behaviors are executed.
isBehaviorSchedulerRunning retrieves a flag that indicates whether the behavior scheduler is currently running.
startView starts traversing this view and starts the renderers associated with all canvases attached to this view.
stopView stops traversing this view after the current state of the scene graph is reflected on all canvases attached to this view.
isViewRunning returns a flag indicating whether the traverser is currently running on this view.
Note: The above six methods are heavy-weight methods intended for verification and image capture (recording). They are not intended to be used for flow control.
Scene Antialiasing
The following methods set and retrieve the scene antialiasing flag. Scene antialiasing is either enabled or disabled for this view. If enabled, the entire scene will be antialiased on each canvas in which scene antialiasing is available. Scene antialiasing is disabled by default.
Note that line and point antialiasing are independent of scene antialiasing. If antialiasing is enabled for lines and points, the lines and points will be antialiased prior to scene antialiasing. If scene antialiasing is disabled, antialiased lines and points will still be antialiased.
Note: Scene antialiasing is ignored in pure immediate mode, but is supported in mixed-immediate mode.
Depth Buffer
The following two methods enable and disable automatic freezing of the depth buffer for objects rendered during the transparent rendering pass (that is, objects rendered using alpha blending) for this view. If enabled, depth buffer writes are disabled during the transparent rendering pass regardless of the value of the depth-buffer-write-enable flag in the RenderingAttributes object for a particular node. This flag is enabled by default.
Transparent objects include BLENDED transparent primitives and antialiased lines and points. Transparent objects do not include opaque objects or primitives rendered with SCREEN_DOOR transparency.
Sensors
The following methods retrieve the sensor's location in the virtual world:
getSensorToVworld takes the sensor's last reading and generates a sensor-to-vworld coordinate system transform. This Transform3D object takes points in that sensor's local coordinate system and transforms them into virtual world coordinates. getSensorHotSpotInVworld retrieves the specified sensor's last hotspot location in virtual world coordinates.
Compatibility Mode A camera-based view model allows application programmers to think about the images displayed on the computer screen as if a virtual camera took those images. Such a view model allows application programmers to position and orient a virtual camera within a virtual scene, to manipulate some parameters of the virtual camera's lens (specify its field of view), and to specify the locations of the near and far clipping planes.
Java 3D allows applications to enable compatibility mode for room-mounted, non-head-tracked display environments, or to disable compatibility mode using the following methods. Camera-based viewing functions are only available in compatibility mode.
Use of these view-compatibility functions will disable some of Java 3D's view model features and limit the portability of Java 3D programs. These methods are primarily intended to help jump-start porting of existing applications.
Setting the Viewing Transform
The View object provides the following compatibility-mode methods that operate on the viewing transform.
Setting the Projection Transform
The View object provides the following compatibility-mode methods that operate on the projection transform:
The setLeftProjection and setRightProjection methods specify a viewing frustum for the left and right eye that transforms points in eye coordinates to clipping coordinates. The getLeftProjection and getRightProjection methods return the viewing frustum for the left and right eye.
Additional Information
For more information, see the Introduction to the Java 3D API and View Model documents.
@see Canvas3D
@see PhysicalBody
@see PhysicalEnvironment
@see ViewPlatform
@see TransparencyAttributes