Java Doc for View.java in  » 6.0-JDK-Modules » java-3d » javax » media » j3d » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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.

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.

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.

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.

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.

setSceneAntialiasingEnable sets the scene antialiasing flag.

getSceneAntialiasingEnable returns the scene antialiasing flag.

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.

setDepthBufferFreezeTransparent enables depth buffer freezing.

getDepthBufferFreezeTransparent retrieves the depth buffer flag.

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.

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.

setCompatibilityModeEnable turns compatibility mode on or off. Compatibility mode is disabled by default.

getCompatabilityModeEnable returns the compatibility mode enable flag.

Setting the Viewing Transform

The View object provides the following compatibility-mode methods that operate on the viewing transform.

setVpcToEc a compatibility mode method that specifies the ViewPlatform coordinates (VPC) to eye coordinates viewing transform.

getVpcToEc returns the VPC.

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 Also:   Canvas3D
See Also:   PhysicalBody
See Also:   PhysicalEnvironment
See Also:   ViewPlatform
See Also:   TransparencyAttributes

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

By default, coexistenceCentering is enabled.

NOTE: when this policy is specified, the Z coordinate of the derived eyepoint is used in place of nominalEyeOffsetFromNominalScreen.
See Also:   View.setWindowEyepointPolicy

physical_screen_width / 2.0

view policy : SCREEN_VIEW
projection policy : PERSPECTIVE_PROJECTION
screen scale policy : SCALE_SCREEN_SIZE
window resize policy : PHYSICAL_WORLD
window movement policy : PHYSICAL_WORLD
window eyepoint policy : RELATIVE_TO_FIELD_OF_VIEW
monoscopic view policy : CYCLOPEAN_EYE_VIEW
front clip policy : PHYSICAL_EYE
back clip policy : PHYSICAL_EYE
visibility policy : VISIBILITY_DRAW_VISIBLE
transparency sorting policy : TRANSPARENCY_SORT_NONE
coexistenceCentering flag : true
compatibility mode : false
left projection : identity
right projection : identity
vpc to ec transform : identity
physical body : null
physical environment : null
screen scale : 1.0
field of view : PI/4
left manual eye in coexistence : (-0.033, 0.0, 0.4572)
right manual eye in coexistence : (0.033, 0.0, 0.4572)
front clip distance : 0.1
back clip distance : 10.0
tracking enable : false
user head to vworld enable : false
list of Canvas3D objects : empty
depth buffer freeze transparent : true
scene antialiasing : false
local eye lighting : false
view platform : null
behavior scheduler running : true
view running : true
minimum frame cycle time : 0

There are several considerations that need to be taken into account when choosing values for the front and back clip distances. These are enumerated in the description of setFrontClipDistance.

Note that this attribute is only used if there is no Clip node that is in scope of the view platform associated with this view.
Parameters:
  distance - the new back clip distance
See Also:   View.setFrontClipDistance
See Also:   Clip.setBackDistance

• VIRTUAL_EYE, to specify that the associated distance is from the eye and in units of virtual distance
• PHYSICAL_EYE, to specify that the associated distance is from the eye and in units of physical distance (meters)
• VIRTUAL_SCREEN, to specify that the associated distance is from the screen and in units of virtual distance
• PHYSICAL_SCREEN, to specify that the associated distance is from the screen and in units of physical distance (meters)

By default, coexistenceCentering is enabled. It should be disabled if the trackerBaseToImagePlate calibration transform is set to a value other than the identity (for example, when rendering to multiple screens or when head tracking is enabled). This flag is ignored for HMD mode, or when the coexistenceCenterInPworldPolicy is not NOMINAL_SCREEN.
Parameters:
  flag - the new coexistenceCentering enable flag
since:
   Java 3D 1.2

There are several considerations that need to be taken 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 in order to accommodate 16-bit Z-buffers. Values of 100 to less than 1000 will produce better results.

• VIRTUAL_EYE, to specify that the associated distance is from the eye and in units of virtual distance
• PHYSICAL_EYE, to specify that the associated distance is from the eye and in units of physical distance (meters)
• VIRTUAL_SCREEN, to specify that the associated distance is from the screen and in units of virtual distance
• PHYSICAL_SCREEN, to specify that the associated distance is from the screen and in units of physical distance (meters)

NOTE: Scene antialiasing is ignored in pure immediate mode, but is supported in mixed-immediate mode.
Parameters:
  flag - indicates whether scene antialiasing is enabled
See Also:   Canvas3D.queryProperties

• TRANSPARENCY_SORT_NONE, to specify that no depth sorting of transparent objects is performed. Transparent objects are drawn after opaque objects, but are not sorted from back to front.
• TRANSPARENCY_SORT_GEOMETRY, to specify that 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.

• 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).
• HMD_VIEW specifies that Java 3D should compute a new viewpoint using the sequence of transforms appropriate to head mounted display environments.

• VISIBILITY_DRAW_VISIBLE, to specify that only visible objects are drawn.
• VISIBILITY_DRAW_INVISIBLE, to specify that only invisible objects are drawn.
• VISIBILITY_DRAW_ALL, to specify that both visible and invisible objects are drawn.

• RELATIVE_TO_SCREEN, Java 3D should interpret the given fixed-eyepoint position as relative to the screen (this implies that the view frustum shape will change whenever a user moves the location of a window on the screen).
• RELATIVE_TO_WINDOW, Java 3D should interpret the given fixed-eyepoint position as relative to the window. In this mode, the X and Y values are taken as the center of the window and the Z value is taken from the canvas eyepoint position.
• RELATIVE_TO_FIELD_OF_VIEW, Java 3D should modify the position of the eyepoint to match any changes in field of view (the view frustum will change whenever the application program changes the field of view).
• RELATIVE_TO_COEXISTENCE, Java 3D should 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 (this implies that the view frustum shape will change whenever a user moves the location of a window on the screen).

NOTE: This is a heavy-weight method intended for verification and image capture (recording); it is not intended to be used for flow control. a pair of integers that specify the beginning and endingtime (in milliseconds since January 1, 1970 00:00:00 GMT)of the behavior scheduler's last pass
exception:
  IllegalStateException - if this method is calledfrom a Behavior method or from any Canvas3D render callbackmethod

NOTE: This is a heavy-weight method intended for verification and image capture (recording); it is not intended to be used for flow control.
exception:
  IllegalStateException - if this method is calledfrom a Behavior method or from any Canvas3D render callbackmethod