canvas3d.java

JAVA3D矩陈的相关类

/*
 * $RCSfile: Canvas3D.java,v $
 *
 * Copyright (c) 2007 Sun Microsystems, Inc. All rights reserved.
 *
 * Use is subject to license terms.
 *
 * $Revision: 1.44 $
 * $Date: 2007/04/26 21:51:17 $
 * $State: Exp $
 */

package javax.media.j3d;

import javax.vecmath.*;
import java.awt.*;
import java.awt.image.BufferedImage;
import java.util.*;


/**
 * The Canvas3D class provides a drawing canvas for 3D rendering.  It
 * is used either for on-screen rendering or off-screen rendering.
 * Canvas3D is an extension of the AWT Canvas class that users may
 * further subclass to implement additional functionality.
 * <p>
 * The Canvas3D object extends the Canvas object to include 
 * 3D-related information such as the size of the canvas in pixels, 
 * the Canvas3D's location, also in pixels, within a Screen3D object, 
 * and whether or not the canvas has stereo enabled.
 * <p>
 * Because all Canvas3D objects contain a 
 * reference to a Screen3D object and because Screen3D objects define 
 * the size of a pixel in physical units, Java 3D can convert a Canvas3D 
 * size in pixels to a physical world size in meters. It can also 
 * determine the Canvas3D's position and orientation in the
 * physical world.
 * <p>
 * <b>On-screen Rendering vs. Off-screen Rendering</b>
 * <p>
 * The Canvas3D class is used either for on-screen rendering or 
 * off-screen rendering.
 * On-screen Canvas3Ds are added to AWT or Swing Container objects
 * like any other canvas.  Java 3D automatically and continuously
 * renders to all on-screen canvases that are attached to an active
 * View object.  On-screen Canvas3Ds can be either single or double
 * buffered and they can be either stereo or monoscopic.
 * <p>
 * Off-screen Canvas3Ds must not be added to any Container.  Java 3D
 * renders to off-screen canvases in response to the
 * <code>renderOffScreenBuffer</code> method.  Off-screen Canvas3Ds
 * are single buffered.  However, on many systems, the actual
 * rendering is done to an off-screen hardware buffer or to a 3D
 * library-specific buffer and only copied to the off-screen buffer of
 * the Canvas when the rendering is complete, at "buffer swap" time.
 * Off-screen Canvas3Ds are monoscopic.
 * <p>
 * The setOffScreenBuffer method sets the off-screen buffer for this 
 * Canvas3D. The specified image is written into by the Java 3D renderer. 
 * The size of the specified ImageComponent determines the size, in 
 * pixels, of this Canvas3D - the size inherited from Component is 
 * ignored. Note that the size, physical width, and physical height of the
 * associated Screen3D must be set
 * explicitly prior to rendering. Failure to do so will result in an 
 * exception.
 * <p>
 * The getOffScreenBuffer method retrieves the off-screen 
 * buffer for this Canvas3D.
 * <p>
 * The renderOffScreenBuffer method schedules the rendering of a frame 
 * into this Canvas3D's off-screen buffer. The rendering is done from 
 * the point of view of the View object to which this Canvas3D has been 
 * added. No rendering is performed if this Canvas3D object has not been 
 * added to an active View. This method does not wait for the rendering 
 * to actually happen. An application that wishes to know when the 
 * rendering is complete must either subclass Canvas3D and
 * override the postSwap method, or call waitForOffScreenRendering.
 * <p>
 * The setOfScreenLocation methods set the location of this off-screen 
 * Canvas3D.  The location is the upper-left corner of the Canvas3D 
 * relative to the upper-left corner of the corresponding off-screen 
 * Screen3D. The function of these methods is similar to that of 
 * Component.setLocation for on-screen Canvas3D objects. The default 
 * location is (0,0).
 * <p>
 * <b>Accessing and Modifying an Eye's Image Plate Position</b>
 * <p>
 * A Canvas3D object provides sophisticated applications with access 
 * to the eye's position information in head-tracked, room-mounted 
 * runtime environments. It also allows applications to manipulate 
 * the position of an eye relative to an image plate in non-head-tracked 
 * runtime environments.
 * <p>
 * The setLeftManualEyeInImagePlate and setRightManualEyeInImagePlate
 * methods set the position of the manual left and right eyes in image 
 * plate coordinates. These values determine eye placement when a head 
 * tracker is not in use and the application is directly controlling the 
 * eye position in image plate coordinates. In head-tracked mode or 
 * when the windowEyepointPolicy is RELATIVE_TO_FIELD_OF_VIEW or
 * RELATIVE_TO_COEXISTENCE, this 
 * value is ignored. When the windowEyepointPolicy is RELATIVE_TO_WINDOW, 
 * only the Z value is used.
 * <p>
 * The getLeftEyeInImagePlate, getRightEyeInImagePlate, and
 * getCenterEyeInImagePlate methods retrieve the actual position of the 
 * left eye, right eye, and center eye in image plate coordinates and 
 * copy that value into the object provided. The center eye is the 
 * fictional eye half-way between the left and right eye. These three 
 * values are a function of the windowEyepointPolicy, the tracking 
 * enable flag, and the manual left, right, and center eye positions.
 * <p>
 * <b>Monoscopic View Policy</b>
 * <p>
 * The setMonoscopicViewPolicy and getMonoscopicViewPolicy methods
 * set and retrieve the policy regarding how Java 3D generates monoscopic 
 * view. If the policy is set to View.LEFT_EYE_VIEW, the view generated 
 * corresponds to the view as seen from the left eye. If set to 
 * View.RIGHT_EYE_VIEW, the view generated corresponds to the view as 
 * seen from the right eye. If set to View.CYCLOPEAN_EYE_VIEW, the view 
 * generated corresponds to the view as seen from the "center eye," the 
 * fictional eye half-way between the left and right eye. The default 
 * monoscopic view policy is View.CYCLOPEAN_EYE_VIEW.
 * <p>
 * <b>Immediate Mode Rendering</b>
 * <p>
 * Pure immediate-mode rendering provides for those applications and 
 * applets that do not want Java 3D to do any automatic rendering of 
 * the scene graph. Such applications may not even wish to build a 
 * scene graph to represent their graphical data. However, they use 
 * Java 3D's attribute objects to set graphics state and Java 3D's 
 * geometric objects to render geometry.
 * <p>
 * A pure immediate mode application must create a minimal set of 
 * Java 3D objects before rendering. In addition to a Canvas3D object, 
 * the application must create a View object, with its associated 
 * PhysicalBody and PhysicalEnvironment objects, and the following 
 * scene graph elements: a VirtualUniverse object, a high-resolution 
 * Locale object, a BranchGroup node object, a TransformGroup node 
 * object with associated transform, and a ViewPlatform 
 * leaf node object that defines the position and orientation within
 * the virtual universe that generates the view.
 * <p>
 * In immediate mode, all rendering is done completely under user 
 * control. It is necessary for the user to clear the 3D canvas, 
 * render all geometry, and swap the buffers.  Additionally, 
 * rendering the right and left eye for stereo viewing becomes the
 * sole responsibility of the application.  In pure immediate mode, 
 * the user must stop the Java 3D renderer, via the
 * Canvas3D object <code>stopRenderer</code> method, prior to adding the 
 * Canvas3D object to an active View object (that is, one that is 
 * attached to a live ViewPlatform object).
 * <p>
 * Other Canvas3D methods related to immediate mode rendering are:
 * <p>
 * <ul>
 * <code>getGraphicsContext3D</code> retrieves the immediate-mode 
 * 3D graphics context associated with this Canvas3D. It creates a 
 * new graphics context if one does not already exist.
 * <p>
 * <code>getGraphics2D</code> retrieves the 
 * 2D graphics object associated with this Canvas3D. It creates a 
 * new 2D graphics object if one does not already exist.
 * <p>
 * <code>swap</code> synchronizes and swaps buffers on a 
 * double-buffered canvas for this Canvas3D object. This method 
 * should only be called if the Java 3D renderer has been stopped. 
 * In the normal case, the renderer automatically swaps
 * the buffer.
 * </ul>
 *
 * <p>
 * <b>Mixed Mode Rendering</b>
 * <p>
 * Mixing immediate mode and retained or compiled-retained mode 
 * requires more structure than pure immediate mode. In mixed mode, 
 * the Java 3D renderer is running continuously, rendering the scene 
 * graph into the canvas.
 *
 * <p>
 * Canvas3D methods related to mixed mode rendering are:
 *
 * <p>
 * <ul>
 * <code>preRender</code> called by the Java 3D rendering loop after 
 * clearing the canvas and before any rendering has been done for 
 * this frame. 
 * <p>
 * <code>postRender</code> called by the Java 3D rendering loop after
 * completing all rendering to the canvas for this frame and before 
 * the buffer swap.
 * <p>
 * <code>postSwap</code> called by the Java 3D rendering loop after 
 * completing all rendering to the canvas, and all other canvases 
 * associated with this view, for this frame following the
 * buffer swap.
 * <p>
 * <code>renderField</code> called by the Java 3D rendering loop 
 * during the execution of the rendering loop. It is called once 
 * for each field (i.e., once per frame on a mono system or once 
 * each for the right eye and left eye on a two-pass stereo system. 
 * </ul>
 * <p>
 * The above callback methods are called by the Java 3D rendering system
 * and should <i>not</i> be called by an application directly.
 *
 * <p>
 * The basic Java 3D <i>stereo</i> rendering loop, 
 * executed for each Canvas3D, is as follows:
 * <ul><pre>
 * clear canvas (both eyes)
 * call preRender()                           // user-supplied method
 * set left eye view
 * render opaque scene graph objects
 * call renderField(FIELD_LEFT)               // user-supplied method
 * render transparent scene graph objects
 * set right eye view
 * render opaque scene graph objects again
 * call renderField(FIELD_RIGHT)              // user-supplied method
 * render transparent scene graph objects again
 * call postRender()                          // user-supplied method
 * synchronize and swap buffers
 * call postSwap()                            // user-supplied method
 * </pre></ul>
 * <p>
 * The basic Java 3D <i>monoscopic</i> rendering loop is as follows:
 * <ul><pre>
 * clear canvas
 * call preRender()                            // user-supplied method
 * set view
 * render opaque scene graph objects
 * call renderField(FIELD_ALL)                 // user-supplied method
 * render transparent scene graph objects
 * call postRender()                           // user-supplied method
 * synchronize and swap buffers
 * call postSwap()                             // user-supplied method
 * </pre></ul>
 * <p>
 * In both cases, the entire loop, beginning with clearing the canvas 
 * and ending with swapping the buffers, defines a frame. The application 
 * is given the opportunity to render immediate-mode geometry at any of 
 * the clearly identified spots in the rendering loop. A user specifies 
 * his or her own rendering methods by extending the Canvas3D class and 
 * overriding the preRender, postRender, postSwap, and/or renderField 
 * methods.
 * Updates to live Geometry, Texture, and ImageComponent objects
 * in the scene graph are not allowed from any of these callback
 * methods.
 *
 * <p>
 * <b>Serialization</b>
 * <p>
 * Canvas3D does <i>not</i> support serialization.  An attempt to
 * serialize a Canvas3D object will result in an
 * UnsupportedOperationException being thrown.
 *
 * <p>
 * <b>Additional Information</b>
 * <p>
 * For more information, see the
 * <a href="doc-files/intro.html">Introduction to the Java 3D API</a> and
 * <a href="doc-files/ViewModel.html">View Model</a>
 * documents.
 *
 * @see Screen3D
 * @see View
 * @see GraphicsContext3D
 */
public class Canvas3D extends Canvas {
    /**
     * Specifies the left field of a field-sequential stereo rendering loop.
     * A left field always precedes a right field.
     */
    public static final int FIELD_LEFT = 0;

    /**
     * Specifies the right field of a field-sequential stereo rendering loop.
     * A right field always follows a left field.
     */
    public static final int FIELD_RIGHT = 1;

    /**
     * Specifies a single-field rendering loop.
     */
    public static final int FIELD_ALL = 2;

    // 
    // The following constants are bit masks to specify which of the node
    // components are dirty and need updates.
    // 
    // Values for the geometryType field.
    static final int POLYGONATTRS_DIRTY      = 0x01;
    static final int LINEATTRS_DIRTY         = 0x02;
    static final int POINTATTRS_DIRTY        = 0x04;
    static final int MATERIAL_DIRTY          = 0x08;
    static final int TRANSPARENCYATTRS_DIRTY = 0x10;
    static final int COLORINGATTRS_DIRTY     = 0x20;

    // Values for lightbin, env set, texture, texture setting etc.
    static final int LIGHTBIN_DIRTY            = 0x40;
    static final int LIGHTENABLES_DIRTY        = 0x80;
    static final int AMBIENTLIGHT_DIRTY        = 0x100;
    static final int ATTRIBUTEBIN_DIRTY        = 0x200;
    static final int TEXTUREBIN_DIRTY          = 0x400;
    static final int TEXTUREATTRIBUTES_DIRTY   = 0x800;
    static final int RENDERMOLECULE_DIRTY      = 0x1000;
    static final int FOG_DIRTY                 = 0x2000;
    static final int MODELCLIP_DIRTY           = 0x4000;    
    static final int VIEW_MATRIX_DIRTY         = 0x8000;
    // static final int SHADER_DIRTY              = 0x10000; Not ready for this yet -- JADA

    // Use to notify D3D Canvas when window change
    static final int RESIZE = 1;
    static final int TOGGLEFULLSCREEN = 2;
    static final int NOCHANGE = 0;
    static final int RESETSURFACE = 1;
    static final int RECREATEDDRAW = 2;

    //
    // Flag that indicates whether this Canvas3D is an off-screen Canvas3D
    //
    boolean offScreen = false;

    //
    // Issue 131: Flag that indicates whether this Canvas3D is a manually
    // rendered Canvas3D (versus an automatically rendered Canvas3D).
    //
    // NOTE: manualRendering only applies to off-screen Canvas3Ds at this time.
    // We have no plans to ever change this, but if we do, it might be necessary
    // to determine which, if any, of the uses of "manualRendering" should be
    // changed to "manualRendering&&offScreen"
    //
    boolean manualRendering = false;

    // user specified offScreen Canvas location
    Point offScreenCanvasLoc;

    // user specified offScreen Canvas dimension
    Dimension offScreenCanvasSize;

    //
    // Flag that indicates whether off-screen rendering is in progress or not
    //
    volatile boolean offScreenRendering = false;

    //
    // Flag that indicates we are waiting for an off-screen buffer to be
    // created or destroyed by the Renderer.
    //
    volatile boolean offScreenBufferPending = false;

    //
    // ImageComponent used for off-screen rendering
    //
    ImageComponent2D offScreenBuffer = null;

    // flag that indicates whether this canvas will use shared context
    boolean useSharedCtx = true;

    //
    // Read-only flag that indicates whether stereo is supported for this
    // canvas.  This is always false for off-screen canvases.