view.java

JAVA3D矩陈的相关类

/*
 * $RCSfile: View.java,v $
 *
 * Copyright (c) 2007 Sun Microsystems, Inc. All rights reserved.
 *
 * Use is subject to license terms.
 *
 * $Revision: 1.12 $
 * $Date: 2007/04/12 17:34:07 $
 * $State: Exp $
 */

package javax.media.j3d;

import javax.vecmath.*;
import java.util.Vector;
import java.util.ArrayList;
import java.util.LinkedList;
import java.util.Iterator;
import java.util.Enumeration;
import java.awt.*;
import com.sun.j3d.utils.universe.Viewer; // Needed for Support of DVR.

/**
 * 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.
 * <P>
 * 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.
 * <P>
 * Java 3D allows applications to specify multiple simultaneously active
 * View objects, each controlling its own set of canvases.
 * <P>
 * 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.
 * <P>
 * <b>Policies</b><P>
 *
 * The View object defines the following policies:<P>
 * <UL>
 * <LI>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:</LI><P>
 * <UL>
 * <LI>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.</LI><P>
 * <LI>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).</LI><P>
 * </UL>
 * <LI>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:</LI><P>
 * <UL>
 * <LI>PARALLEL_PROJECTION - specifies that a parallel projection
 * transform is computed.</LI><P>
 * <LI>PERSPECTIVE_PROJECTION - specifies that a perspective projection
 * transform is computed. This is the default policy.</LI><P>
 * </UL>
 * <LI>Screen scale policy - specifies where the screen scale comes from.
 * There are two screen scale policies:</LI><P>
 * <UL>
 * <LI>SCALE_SCREEN_SIZE - specifies that the scale is derived from the
 * physical screen according to the following formula (this is the
 * default mode):</LI>
 * <UL>
 * <code>screenScale = physicalScreenWidth / 2.0</code><P>
 * </UL>
 * <LI>SCALE_EXPLICIT - pecifies that the scale is taken directly from
 * the user-provided <code>screenScale</code> attribute (see the
 * setScreenScale method description).</LI><P>
 * </UL>
 * <LI>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:</LI><P>
 * <UL>
 * <LI>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.</LI><P>
 * <LI>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.</LI><P>
 * </UL>
 * <LI>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:</LI><P>
 * <UL>
 * <LI>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.)</LI><P>
 * <LI>PHYSICAL_WORLD - implies that the image seen in the window
 * remains the same no matter where the user positions the window
 * on the screen.</LI><P>
 * </UL>
 * <LI>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:</LI><P>
 * <UL>
 * <LI>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.</LI><P>
 * <LI>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.</LI><P>
 * <LI>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.</LI><P>
 * <LI>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.</LI><P>
 * </UL>
 * <LI>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:</LI><P>
 * <UL>
 * <LI>VIRTUAL_EYE - specifies that the associated distance is from
 * the eye and in units of virtual distance.</LI><P>
 * <LI>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.</LI><P>
 * <LI>VIRTUAL_SCREEN  - specifies that the associated distance is
 * from the screen and in units of virtual distance. </LI><P>
 * <LI>PHYSICAL_SCREEN - specifies that the associated distance is
 * from the screen and in units of physical distance (in meters).
 * </LI><P>
 * </UL>
 * <LI>Visibility policy - specifies how visible and invisible objects
 * are drawn. There are three visibility policies:</LI><P>
 * <UL>
 * <LI>VISIBILITY_DRAW_VISIBLE - only visible objects are drawn
 * (this is the default).</LI><P>
 * <LI>VISIBILITY_DRAW_INVISIBLE - only invisible objects are drawn.</LI><P>
 * <LI>VISIBILITY_DRAW_ALL - both visible and invisible
 * objects are drawn. </LI><P>
 * </UL>
 * <LI>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:</LI><P>
 * <UL>
 * <LI>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.</LI><P>
 * <LI>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.</LI><P>
 * </UL>
 * </UL>
 * <b>Projection and Clip Parameters</b><P>
 * The projection and clip parameters determine the view model's
 * field of view and the front and back clipping distances.<P>
 * <UL>
 * <LI>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.</LI><P>
 * <LI>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.</LI><P>
 * <LI>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.</LI><P>
 * There are several considerations to take into account when
 * choosing values for the front and back clip distances.<P>
 * <UL>
 * <LI>The front clip distance must be greater than 0.0 in physical
 * eye coordinates.</LI><P>
 * <LI>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.</LI><P>
 * <LI>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.</LI><P>
 * <LI>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.</LI><P>
 * </UL>
 * Violating any of the above rules will result in undefined behavior.
 * In many cases, no picture will be drawn.<P>
 * </UL>
 * <b>Frame Start Time, Duration, and Number</b><P>
 *
 * There are five methods used to get information about system
 * execution and performance:<P>
 * <UL>
 * <code>getCurrentFrameStartTime</code> returns the time at which 
 * the most recent rendering frame started.<P>
 * <code>getLastFrameDuration</code> returns the duration, in milliseconds, of
 * the most recently completed rendering frame.<P>
 * <code>getFrameNumber</code> returns the frame number for this view.<P>
 * <code>getMaxFrameStartTimes</code> retrieves the implementation-dependent
 * maximum number of frames whose start times will be recorded by
 * the system.<P>
 * <code>getFrameStartTimes</code> copies the last k frame start time values
 * into the user-specified array.<P>
 * </UL>
 * <b>View Traversal and Behavior Scheduling</b><P>
 * The following methods control the traversal, the rendering, and
 * the execution of the behavior scheduler for this view:<P>
 * <UL>
 * <code>startBehaviorScheduler</code> starts the behavior scheduler 
 * running after it has been stopped.<P>
 * <code>stopBehaviorScheduler</code> stops the behavior scheduler after all
 * currently-scheduled behaviors are executed.<P>
 * <code>isBehaviorSchedulerRunning</code> retrieves a flag that indicates
 * whether the behavior scheduler is currently running.<P>
 * <code>startView</code> starts traversing this view and starts the renderers
 * associated with all canvases attached to this view.<P>
 * <code>stopView</code> stops traversing this view after the current state of
 * the scene graph is reflected on all canvases attached to this
 * view.<P>
 * <code>isViewRunning</code> returns a flag indicating whether the traverser
 * is currently running on this view.<P>
 * </UL>
 * 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.<P>
 *
 * <b>Scene Antialiasing</b><P>
 *
 * 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.<P>
 * <UL>
 * <code>setSceneAntialiasingEnable</code> sets the scene antialiasing flag.<P>
 * <code>getSceneAntialiasingEnable</code> returns the scene antialiasing
 * flag.<P>
 * </UL>
 * 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.
 * <p>
 * <b>Note:</b> Scene antialiasing is ignored in pure immediate mode,
 * but is supported in mixed-immediate mode.
 * <p>
 * <b>Depth Buffer</b><P>
 *
 * 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.<P>
 * <UL>
 * <code>setDepthBufferFreezeTransparent</code> enables depth buffer freezing.<P>
 * <code>getDepthBufferFreezeTransparent</code> retrieves the depth buffer
 * flag.<P>
 * </UL>
 * 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.<p>
 *
 * <b>Sensors</b><P>
 *
 * The following methods retrieve the sensor's location in the
 * virtual world:<P>
 * <UL>
 * <code>getSensorToVworld</code> 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.<P>
 *
 * <code>getSensorHotSpotInVworld</code> retrieves the specified sensor's
 * last hotspot location in virtual world coordinates.<P>
 * </UL>
 *
 * <b>Compatibility Mode</b><P>
 *