viewinfo.java

JAVA3D矩陈的相关类

/*
 * $RCSfile: ViewInfo.java,v $
 *
 * Copyright (c) 2007 Sun Microsystems, Inc. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * - Redistribution of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 *
 * - Redistribution in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in
 *   the documentation and/or other materials provided with the
 *   distribution.
 *
 * Neither the name of Sun Microsystems, Inc. or the names of
 * contributors may be used to endorse or promote products derived
 * from this software without specific prior written permission.
 *
 * This software is provided "AS IS," without a warranty of any
 * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
 * WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY
 * EXCLUDED. SUN MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL
 * NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF
 * USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS
 * DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR
 * ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
 * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
 * REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR
 * INABILITY TO USE THIS SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGES.
 *
 * You acknowledge that this software is not designed, licensed or
 * intended for use in the design, construction, operation or
 * maintenance of any nuclear facility.
 *
 * $Revision: 1.6 $
 * $Date: 2007/02/09 17:20:45 $
 * $State: Exp $
 */

package com.sun.j3d.utils.universe ;

import java.awt.GraphicsConfiguration ;
import java.awt.GraphicsEnvironment;
import java.awt.Point ;
import java.awt.Rectangle ;
import java.text.DecimalFormat ;
import java.text.FieldPosition ;
import java.util.* ;
import javax.media.j3d.* ;
import javax.vecmath.* ;

/**
 * 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.<p>
 *
 * 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. <code>getImagePlateToVworld</code>
 * 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.<p>
 *
 * 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 <code>ALLOW_LOCAL_TO_VWORLD_READ</code> capability
 * set, which potentially inhibits internal scene graph optimization.<p>
 *
 * 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 <code>ALLOW_LOCAL_TO_VWORLD_READ</code> view platform
 * capability doesn't need to be set for these applications.<p>
 *
 * <b>Other Synchronization Issues</b><p>
 * 
 * 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.<p>
 * 
 * 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.<p>
 *
 * 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.<p>
 * 
 * <b>Implementation Notes</b><p>
 * 
 * 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:<p><ul>
 * 
 * <li>The frame latency issue for virtual world transforms.</li><p>
 * 
 * <li>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.</li><p>
 * 
 * <li>"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.</li><p>
 * 
 * <li>Small floating point precision differences resulting from the
 *     alternative computations.</li><p>
 * 
 * <li>Bugs in this class and the Java 3D core.</li><p>
 * 
 * <li>Tracked head position.</li></ul><p>
 * 
 * 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
 * <code>getUserHeadToVworld</code> 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 <code>getHeadInfo</code> in this class for more information
 * and possible workarounds.<p>
 *
 * <b>Thread Safety</b><p>
 * 
 * All transforms are lazily evaluated.  The <code>updateScreen</code>,
 * <code>updateCanvas</code>, <code>updateViewPlatform</code>,
 * <code>updateView</code>, and <code>updateHead</code> methods just set flags
 * indicating that derived transforms need to be recomputed; they are safe to
 * call from any thread.  <code>updateCanvas</code>, for example, can safely
 * be called from an AWT event listener.<p>
 *
 * 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.<p>
 *
 * Otherwise, none of the other methods in this class are internally
 * synchronized.  <i>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.</i><p>
 *
 * @since Java 3D 1.3.1
 */
public class ViewInfo {
    private final static boolean verbose = false ;

    /**
     * Indicates that updates to a Screen3D associated with the View should
     * be automatically checked with each call to a public method in this
     * class.
     */
    public final static int SCREEN_AUTO_UPDATE = 1 ;

    /**
     * Indicates that updates to a Canvas3D associated with the View should
     * be automatically checked with each call to a public method in this
     * class.
     */
    public final static int CANVAS_AUTO_UPDATE = 2 ;

    /**
     * Indicates that updates to the View should be automatically checked
     * with each call to a public method in this class.
     */
    public final static int VIEW_AUTO_UPDATE = 4 ;

    /**
     * Indicates that updates to the tracked head position should be
     * automatically checked with each call to a public method in this class.
     */
    public final static int HEAD_AUTO_UPDATE = 8 ;

    /**
     * Indicates that updates to the ViewPlatform <code>localToVworld</code>
     * 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 <code>ALLOW_LOCAL_TO_VWORLD_READ</code> capability set.
     */
    public final static int PLATFORM_AUTO_UPDATE = 16 ;

    //
    // Screen3D and ViewPlatform instances are shared across multiple Views in
    // the Java 3D view model.	Since ViewInfo is per-View and we want to
    // cache screen and platform derived data, we maintain static references
    // to the screens and platforms here.
    // 
    // From a design standpoint our ViewInfo objects should probably be in the
    // scope of an object that encloses these maps so they can be gc'ed
    // properly.  This is cumbersome with the current design constraints, so
    // for now we provide an alternative constructor to override these static
    // maps and a method to explicitly clear them.  The alternative
    // constructor can be used to wrap this class into a multi-view context
    // that provides the maps.
    //
    private static Map staticVpMap = new HashMap() ;
    private static Map staticSiMap = new HashMap() ;

    private Map screenMap = null ;
    private Map viewPlatformMap = null ;

    // The target View and some derived data.
    private View view = null ;
    private Sensor headTracker = null ;
    private boolean useTracking = false ;
    private boolean clipVirtual = false ;

    // The current ViewPlatform and Canvas3D information used by this object.
    private ViewPlatformInfo vpi = null ;
    private int canvasCount = 0 ;
    private Map canvasMap = new HashMap() ;
    private CanvasInfo[] canvasInfo = new CanvasInfo[1] ;

    // This View's update flags.  The other update flags are maintained by
    // ScreenInfo, CanvasInfo, and ViewPlatformInfo.
    private boolean updateView = true ;
    private boolean updateHead = true ;
    private boolean autoUpdate = false ;
    private int autoUpdateFlags = 0 ;

    // Cached View policies.  
    private int viewPolicy = View.SCREEN_VIEW ;
    private int resizePolicy = View.PHYSICAL_WORLD ;
    private int movementPolicy = View.PHYSICAL_WORLD ;
    private int eyePolicy = View.RELATIVE_TO_FIELD_OF_VIEW ;
    private int projectionPolicy = View.PERSPECTIVE_PROJECTION ;
    private int frontClipPolicy = View.PHYSICAL_EYE ;
    private int backClipPolicy = View.PHYSICAL_EYE ;
    private int scalePolicy = View.SCALE_SCREEN_SIZE ;
    private boolean coeCentering = true ;

    // This View's cached transforms.  See ScreenInfo, CanvasInfo, and
    // ViewPlatformInfo for the rest of the cached transforms.
    private Transform3D coeToTrackerBase = null ;
    private Transform3D headToHeadTracker = null ;

    // These are from the head tracker read.
    private Transform3D headTrackerToTrackerBase = null ;
    private Transform3D trackerBaseToHeadTracker = null ;

    // These are derived from the head tracker read.
    private Transform3D headToTrackerBase = null ;
    private Transform3D coeToHeadTracker = null ;

    // Cached physical body and environment.
    private PhysicalEnvironment env = null ;
    private PhysicalBody body = null ;
    private Point3d leftEyeInHead = new Point3d() ;
    private Point3d rightEyeInHead = new Point3d() ;

    // Temporary variables.  These could just be new'ed as needed, but we'll
    // assume that ViewInfo instances are used much more than they're created.
    private Vector3d v3d = new Vector3d() ;
    private double[] m16d = new double[16] ;
    private Point3d leftEye = new Point3d() ;
    private Point3d rightEye = new Point3d() ;
    private Map newMap = new HashMap() ;
    private Set newSet = new HashSet() ;

    /**
     * Creates a new ViewInfo for the specified View.<p>
     *
     * 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 <code>localToVworld</code> transform.  These
     * notifications are performed with the <code>updateView</code>,
     * <code>updateCanvas</code>, <code>updateScreen</code>,
     * <code>updateHead</code>, and <code>updateViewPlatform</code>
     * methods.<p>
     *
     * The View must be attached to a ViewPlatform.  If the ViewPlatform is
     * attached to a live scene graph, then <code>ALLOW_POLICY_READ</code>
     * capability must be set on the ViewPlatform node.