wandviewbehavior.java

JAVA3D矩陈的相关类

/*
 * $RCSfile: WandViewBehavior.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.4 $
 * $Date: 2007/02/09 17:20:15 $
 * $State: Exp $
 */

package com.sun.j3d.utils.behaviors.vp ;

import java.util.* ;
import javax.vecmath.* ;
import javax.media.j3d.* ;
import com.sun.j3d.utils.universe.* ;
import com.sun.j3d.utils.behaviors.sensor.* ;

/**
 * Manipulates view platform transforms using a motion-tracked wand or mouse
 * equipped with a six degree of freedom (6DOF) sensor.  An optional two axis
 * (2D) valuator sensor is also directly supported.  Default operation is set
 * up to enable both direct manipulation of the view transform and translation
 * back and forth along the direction the 6DOF sensor is pointing; rotation
 * is handled by the 2D valuator if available.  An arbitrary number of sensors
 * and action bindings can be customized by accessing this behavior's
 * <code>SensorEventAgent</code> directly.
 * <p>
 * This behavior can be instantiated from the configuration file read by
 * <code>ConfiguredUniverse</code> and fully configured using the
 * <code>ViewPlatformBehaviorProperties</code> command to set the properties
 * described below, but neither <code>ConfiguredUniverse</code> nor
 * <code>SimpleUniverse</code> are required by this behavior.  Conventional
 * <code>set</code> and <code>get</code> accessors are provided for
 * configuring this behavior directly; these methods have the same names as
 * the properties but are prefixed with <code>get</code> and <code>set</code>.
 * Property values are spelled with mixed case strings while the corresponding
 * constant field names for the conventional accessors are spelled with upper
 * case strings and underscores.
 * <p>
 * {@link #Sensor6D Sensor6D} is the 6DOF sensor to use.  This can also be set
 * directly with the appropriate constructor.  This sensor must generate 6
 * degree of freedom position and orientation reads relative to the tracker
 * base in physical units.  By default this behavior provides an echo for the
 * 6DOF sensor which indicates its position and orientation in the virtual
 * world; the echo attributes can be set by the {@link #EchoType EchoType},
 * {@link #EchoSize EchoSize}, {@link #EchoColor EchoColor}, and {@link
 * #EchoTransparency EchoTransparency} properties.  See also the {@link
 * #NominalSensorRotation NominalSensorRotation} property, and the
 * <code>setHotSpot</code> method of the <code>Sensor</code> class.
 * <p>
 * {@link #Sensor2D Sensor2D} is an optional 2D valuator to use in conjunction
 * with the 6DOF sensor.  This can be set directly with the appropriate
 * constructor.  The valuator should generate X and Y reads ranging from [-1.0
 * .. +1.0], with a nominal (deadzone) value of 0.0.  The default
 * configuration expects to find these values along the translation components
 * of the read matrix, at indices 3 and 7, but these indices can be also be
 * specified by the {@link #MatrixIndices2D MatrixIndices2D} property.
 * <p>
 * {@link #ButtonAction6D ButtonAction6D} sets an action for a specific button
 * on a 6DOF sensor.  The actions available are:
 * <ul>
 * <li>
 * <code>GrabView</code> - Directly manipulates the view platform by moving
 * it in inverse response to the sensor's position and orientation,
 * producing the effect of attaching the virtual world to the sensor's
 * movements.  If a button is available then this action is bound to button 0
 * by default.
 * </li>
 * <li>
 * <code>TranslateForward</code> - Translates the view platform forward along
 * the direction the sensor is pointing; the virtual world appears to move
 * towards the sensor.  The default is button 1 if two buttons are available.
 * Related properties are {@link #TranslationSpeed TranslationSpeed}, {@link
 * #AccelerationTime AccelerationTime}, {@link #ConstantSpeedTime
 * ConstantSpeedTime}, and {@link #FastSpeedFactor FastSpeedFactor}.
 * </li>
 * <li>
 * <code>TranslateBackward</code> - Translates the view platform backwards
 * along the direction the sensor is pointing; the virtual world appears to
 * move away from the sensor.  The default is button 2 if three buttons are
 * available. 
 * </li>
 * <li>
 * <code>RotateCCW</code> - Rotates the view platform counter-clockwise about
 * a Y axis; the virtual world appears to rotate clockwise.  This action is
 * not assigned by default.  Related properties are {@link #RotationSpeed
 * RotationSpeed}, {@link #RotationCoords RotationCoords}, {@link
 * #TransformCenterSource TransformCenterSource}, {@link #TransformCenter
 * TransformCenter}, and <code>AccelerationTime</code>.
 * </li>
 * <li>
 * <code>RotateCW</code> - Rotates the view platform clockwise about a Y axis;
 * the virtual world appears to rotate counter-clockwise.  This action is not
 * assigned by default.
 * </li>
 * <li>
 * <code>ScaleUp</code> - Scales the view platform larger so that the virtual
 * world appears to grow smaller.  This action is not assigned by default.
 * Related properties are {@link #ScaleSpeed ScaleSpeed},
 * <code>TransformCenterSource</code>, <code>TransformCenter</code>, and
 * <code>AccelerationTime</code>.
 * </li>
 * <li>
 * <code>ScaleDown</code> - Scales the view platform smaller so that the
 * virtual world appears to grow larger.  This action is not assigned by
 * default.
 * </li>
 * </ul>
 * <p>
 * {@link #ReadAction2D ReadAction2D} sets the action bound to 2D valuator
 * reads; that is, non-zero values generated by the device when no buttons
 * have been pressed.  If the value is (0.0, 0.0) or below the threshold value
 * set by {@link #Threshold2D Threshold2D}, then this behavior does nothing;
 * otherwise, the following actions can be performed:
 * <ul>
 * <li>
 * <code>Rotation</code> - Rotates the view platform.  This is the default 2D
 * valuator action set by this behavior. Related properties are
 * <code>RotationSpeed</code>, <code>RotationCoords</code>,
 * <code>TransformCenterSource</code>, and <code>TransformCenter</code>.
 * </li>
 * <li>
 * <code>Translation</code> - Translates the view platform.  The translation
 * occurs relative to the X and Z basis vectors of either the 6DOF sensor or
 * the view platform if one is not available.  The maximum speed is equal to
 * the product of the <code>TranslationSpeed</code> and
 * <code>FastSpeedFactor</code> property values.
 * </li>
 * <li>
 * <code>Scale</code> - Scales the view platform smaller with positive Y
 * values and larger with negative Y values.  The effect is to increase the
 * apparent size of the virtual world when pushing the valuator forwards and
 * to decrease it when pushing backwards.  Related properties are
 * <code>ScaleSpeed</code>, <code>TransformCenterSource</code>, and
 * <code>TransformCenter</code>.
 * </li>
 * </ul>
 * <p>
 * {@link #ButtonAction2D ButtonAction2D} sets an action for a specific button
 * on the 2D valuator. The available actions are the same as for
 * <code>ReadAction2D</code>.  No actions are bound by default to the 2D
 * valuator buttons.
 * <p>
 * The view transform may be reset to its home transform by pressing a number
 * of buttons simultaneously on the 6DOF sensor.  The minimum number of
 * buttons that must be pressed is set by {@link #ResetViewButtonCount6D
 * ResetViewButtonCount6D}.  This value must be greater than one; the default
 * is three.  This action may be disabled by setting the property value to
 * None.  The corresponding property for the 2D valuator is {@link
 * #ResetViewButtonCount2D ResetViewButtonCount2D}, with a default value of
 * None.  Note, however, that the reset view action will be ineffectual if an
 * action which always modifies the view transform is bound to reads on the
 * sensor used to reset the view, since the reset transform will get
 * overwritten by the read action.
 * <p>
 * The special value <code>None</code> can in general be assigned to any
 * button or read action to prevent any defaults from being bound to it.
 *
 * @see ConfiguredUniverse
 * @see SensorEventAgent
 * @since Java 3D 1.3
 */
public class WandViewBehavior extends ViewPlatformBehavior {
    /**
     * Indicates a null configuration choice.
     */
    public static final int NONE = 0 ;

    /**
     * Indicates that a 6DOF sensor button action should be bound
     * to grabbing the view.  The default is button 0.
     */
    public static final int GRAB_VIEW = 1 ;

    /**
     * Indicates that a 6DOF sensor button action should be bound
     * to translating the view forward.  The default is button 1.
     */
    public static final int TRANSLATE_FORWARD = 2 ;

    /**
     * Indicates that a 6DOF sensor button action should be bound
     * to translating the view backward.  The default is button 2.
     */
    public static final int TRANSLATE_BACKWARD = 3 ;

    /**
     * Indicates that a 6DOF sensor button action should be bound
     * to rotate the view plaform counter-clockwise about a Y axis.
     */
    public static final int ROTATE_CCW = 4 ;

    /**
     * Indicates that a 6DOF sensor button action should be bound
     * to rotate the view platform clockwise about a Y axis.
     */
    public static final int ROTATE_CW = 5 ;

    /**
     * Indicates that a 6DOF sensor button action should be bound
     * to scaling the view platform larger.
     */
    public static final int SCALE_UP = 6 ;

    /**
     * Indicates that a 6DOF sensor button action should be bound
     * to scaling the view platform smaller.
     */
    public static final int SCALE_DOWN = 7 ;

    /**
     * Indicates that a 2D sensor button or read action should be bound
     * to translation.  
     */
    public static final int TRANSLATION = 8 ;

    /**
     * Indicates that a 2D sensor button or read action should be bound
     * to scaling.  
     */
    public static final int SCALE = 9 ;

    /**
     * Indicates that a 2D sensor button or read action should be bound
     * to rotation.  The default is to bind rotation to the 2D sensor reads.
     */
    public static final int ROTATION = 10 ;

    /**
     * Indicates that translation, rotation, or scaling speeds are
     * per frame.
     */
    public static final int PER_FRAME = 11 ;

    /**
     * Use to indicate that translation, rotation, or scaling speeds are per
     * second.  This is the default.
     */
    public static final int PER_SECOND = 12 ;

    /**
     * Indicates that translation speed is in virtual world units.
     */
    public static final int VIRTUAL_UNITS = 13 ;

    /**
     * Indicates that translation speed is in physical world units
     * (meters per second or per frame).  This is the default.
     */
    public static final int PHYSICAL_METERS = 14 ;

    /**
     * Indicates that rotation speed should be in radians.
     */
    public static final int RADIANS = 15 ;
    
    /**
     * Indicates that rotation speed should be in degrees.  This is the
     * default.
     */
    public static final int DEGREES = 16 ;
    
    /**
     * Indicates that rotation should occur in view platform
     * coordinates.
     */
    public static final int VIEW_PLATFORM = 17 ;

    /**
     * Indicates that rotation should occur in head coordinates.
     */
    public static final int HEAD = 18 ;

    /**
     * Indicates that rotation should occur in sensor coordinates.
     * This is the default.
     */
    public static final int SENSOR = 19 ;

    /**
     * Indicates that rotation or scale should be about a fixed point
     * in virtual world coordinates.
     */
    public static final int VWORLD_FIXED = 20 ;

    /**
     * Indicates that rotation or scale should be about a 6DOF sensor
     * hotspot.  This is the default.
     */
    public static final int HOTSPOT = 21 ;

    /**
     * Indicates that the 6DOF sensor read action should be bound to
     * displaying the sensor's echo in the virtual world.  This is the
     * default.
     */
    public static final int ECHO = 22 ;
    
    /**
     * Indicates that the echo type is a gnomon displaying the
     * directions of the sensor's local coordinate system axes at the location
     * of the sensor's hotspot.
     */
    public static final int GNOMON = 23 ;