alpha.java

JAVA3D矩陈的相关类

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

package javax.media.j3d;


/**
 * The alpha NodeComponent object provides common methods for
 * converting a time value into an alpha value (a value in the range 0
 * to 1).  The Alpha object is effectively a function of time that
 * generates alpha values in the range [0,1] when sampled: f(t) =
 * [0,1].  A primary use of the Alpha object is to provide alpha
 * values for Interpolator behaviors.  The function f(t) and the
 * characteristics of the Alpha object are determined by
 * user-definable parameters:
 *
 * <p>
 * <ul>
 *
 * <code>loopCount</code> -- This is the number of times to run this
 * Alpha; a value of -1 specifies that the Alpha loops
 * indefinitely.<p>
 *
 * <code>triggerTime</code> -- This is the time in milliseconds since
 * the start time that this object first triggers.  If (startTime +
 * triggerTime >= currentTime) then the Alpha object starts running.<p>
 *
 * <code>phaseDelayDuration</code> -- This is an additional number of
 * milliseconds to wait after triggerTime before actually starting
 * this Alpha.<p>
 *
 * <code>mode</code> -- This can be set to INCREASING_ENABLE,
 * DECREASING_ENABLE, or the Or'ed value of the two.
 * INCREASING_ENABLE activates the increasing Alpha parameters listed
 * below; DECREASING_ENABLE activates the decreasing Alpha parameters
 * listed below.<p>
 *
 * </ul> Increasing Alpha parameters:<p> <ul>
 *
 * <code>increasingAlphaDuration</code> -- This is the period of time
 * during which Alpha goes from zero to one. <p>
 *
 * <code>increasingAlphaRampDuration</code> -- This is the period of
 * time during which the Alpha step size increases at the beginning of
 * the increasingAlphaDuration and, correspondingly, decreases at the
 * end of the increasingAlphaDuration.  This parameter is clamped to
 * half of increasingAlphaDuration.  When this parameter is non-zero,
 * one gets constant acceleration while it is in effect; constant
 * positive acceleration at the beginning of the ramp and constant
 * negative acceleration at the end of the ramp.  If this parameter is
 * zero, then the effective velocity of the Alpha value is constant
 * and the acceleration is zero (ie, a linearly increasing alpha
 * ramp).<p>
 *
 * <code>alphaAtOneDuration</code> -- This is the period of time that
 * Alpha stays at one.<p> </ul> Decreasing Alpha parameters:<p> <ul>
 *
 * <code>decreasingAlphaDuration</code> -- This is the period of time
 * during which Alpha goes from one to zero.<p>
 *
 * <code>decreasingAlphaRampDuration</code> -- This is the period of
 * time during which the Alpha step size increases at the beginning of
 * the decreasingAlphaDuration and, correspondingly, decreases at the
 * end of the decreasingAlphaDuration.  This parameter is clamped to
 * half of decreasingAlphaDuration.  When this parameter is non-zero,
 * one gets constant acceleration while it is in effect; constant
 * positive acceleration at the beginning of the ramp and constant
 * negative acceleration at the end of the ramp.  If this parameter is
 * zero, the effective velocity of the Alpha value is constant and the
 * acceleration is zero (i.e., a linearly-decreasing alpha ramp).<p>
 *
 * <code>alphaAtZeroDuration</code> -- This is the period of time that
 * Alpha stays at zero.
 *
 * </ul>
 *
 * @see Interpolator
 */

public class Alpha extends NodeComponent {

    // loopCount <  -1 --> reserved
    // loopCount == -1 --> repeat forever
    // loopCount >=  0 --> repeat count
    private int loopCount;

    /**
     * Specifies that the increasing component of the alpha is used.
     */
    public static final int INCREASING_ENABLE = 1;

    /**
     * Specifies that the decreasing component of the alpha is used
     */
    public static final int DECREASING_ENABLE = 2;

    /**
     * This alpha's mode, specifies whether to process
     * increasing and decreasing alphas.
     */
    private int mode;

    private float triggerTime;
    private float phaseDelay;
    private float increasingAlpha;
    private long increasingAlphaRamp;
    private float incAlphaRampInternal;
    private float alphaAtOne;
    private float decreasingAlpha;
    private long decreasingAlphaRamp;
    private float decAlphaRampInternal;
    private float alphaAtZero;

    // For pausing and resuming Alpha
    private long pauseTime = 0L;
    private boolean paused = false;

    // Stop time gets used only for loopCount > 0
    private float stopTime;

    // Start time in milliseconds
    private long startTime = MasterControl.systemStartTime;

    /**
     * Constructs an Alpha object with default parameters.  The default
     * values are as follows:
     * <ul>
     * loopCount			: -1<br>
     * mode				: INCREASING_ENABLE<br>
     * startTime			: system start time<br>
     * triggerTime			: 0<br>
     * phaseDelayDuration		: 0<br>
     * increasingAlphaDuration		: 1000<br>
     * increasingAlphaRampDuration	: 0<br>
     * alphaAtOneDuration		: 0<br>
     * decreasingAlphaDuration		: 0<br>
     * decreasingAlphaRampDuration	: 0<br>
     * alphaAtZeroDuration		: 0<br>
     * isPaused				: false<br>
     * pauseTime			: 0<br>
     * </ul>
     */
    public Alpha() {
        loopCount = -1;
        mode = INCREASING_ENABLE;
        increasingAlpha = 1.0f;          // converted to seconds internally 
	/*
	// Java initialize them to zero by default
        triggerTime = 0L;
        phaseDelay = 0.0f;
        increasingAlphaRamp = 0.0f;
        alphaAtOne = 0.0f;
        decreasingAlpha = 0.0f;
        decreasingAlphaRamp = 0.0f;
        alphaAtZero = 0.0f;
	*/
    }


    /**
     * This constructor takes all of the Alpha user-definable parameters.
     * @param loopCount number of times to run this alpha; a value
     * of -1 specifies that the alpha loops indefinitely
     * @param mode indicates whether the increasing alpha parameters or
     * the decreasing alpha parameters or both are active.  This parameter
     * accepts the following values, INCREASING_ENABLE or
     * DECREASING_ENABLE, which may be ORed together to specify
     * that both are active.
     * The increasing alpha parameters are increasingAlphaDuration,
     * increasingAlphaRampDuration, and alphaAtOneDuration.
     * The decreasing alpha parameters are decreasingAlphaDuration,
     * decreasingAlphaRampDuration, and alphaAtZeroDuration.
     * @param triggerTime time in milliseconds since the start time
     * that this object first triggers
     * @param phaseDelayDuration number of milliseconds to wait after
     * triggerTime before actually starting this alpha
     * @param increasingAlphaDuration period of time during which alpha goes
     * from zero to one
     * @param increasingAlphaRampDuration period of time during which
     * the alpha step size increases at the beginning of the
     * increasingAlphaDuration and, correspondingly, decreases at the end
     * of the increasingAlphaDuration. This value is clamped to half of
     * increasingAlphaDuration. NOTE: a value of zero means that the alpha
     * step size remains constant during the entire increasingAlphaDuration.
     * @param alphaAtOneDuration period of time that alpha stays at one
     * @param decreasingAlphaDuration period of time during which alpha goes
     * from one to zero
     * @param decreasingAlphaRampDuration period of time during which
     * the alpha step size increases at the beginning of the
     * decreasingAlphaDuration and, correspondingly, decreases at the end
     * of the decreasingAlphaDuration. This value is clamped to half of
     * decreasingAlphaDuration. NOTE: a value of zero means that the alpha
     * step size remains constant during the entire decreasingAlphaDuration.
     * @param alphaAtZeroDuration period of time that alpha stays at zero
     */
    public Alpha(int loopCount, int mode,
		 long triggerTime, long phaseDelayDuration,
		 long increasingAlphaDuration, 
		 long increasingAlphaRampDuration,
		 long alphaAtOneDuration,
		 long decreasingAlphaDuration, 
		 long decreasingAlphaRampDuration,
		 long alphaAtZeroDuration) {

	this.loopCount = loopCount;
	this.mode = mode;
	this.triggerTime = (float) triggerTime * .001f;
	phaseDelay = (float) phaseDelayDuration * .001f;

	increasingAlpha = (float) increasingAlphaDuration * .001f;
	alphaAtOne = (float)alphaAtOneDuration * .001f;
	increasingAlphaRamp = increasingAlphaRampDuration;
	incAlphaRampInternal = increasingAlphaRampDuration * .001f;
	if (incAlphaRampInternal > (0.5f * increasingAlpha)) {
	    incAlphaRampInternal = 0.5f * increasingAlpha;
	}

	decreasingAlpha = (float)decreasingAlphaDuration * .001f;
	alphaAtZero = (float)alphaAtZeroDuration * .001f;
	decreasingAlphaRamp = decreasingAlphaRampDuration;
	decAlphaRampInternal = decreasingAlphaRampDuration * .001f;
	if (decAlphaRampInternal > (0.5f * decreasingAlpha)) {
	    decAlphaRampInternal = 0.5f * decreasingAlpha;
	}
	computeStopTime();
    }


    /**
     * Constructs a new Alpha object that assumes that the mode is 
     * INCREASING_ENABLE.  
     *
     * @param loopCount number of times to run this alpha; a value
     * of -1 specifies that the alpha loops indefinitely.
     * @param triggerTime time in milliseconds since the start time
     * that this object first triggers
     * @param phaseDelayDuration number of milliseconds to wait after
     * triggerTime before actually starting this alpha
     * @param increasingAlphaDuration period of time during which alpha goes
     * from zero to one
     * @param increasingAlphaRampDuration period of time during which
     * the alpha step size increases at the beginning of the
     * increasingAlphaDuration and, correspondingly, decreases at the end
     * of the increasingAlphaDuration. This value is clamped to half of
     * increasingAlphaDuration. NOTE: a value of zero means that the alpha
     * step size remains constant during the entire increasingAlphaDuration.
     * @param alphaAtOneDuration period of time that alpha stays at one
     */

    public Alpha(int loopCount,
		 long triggerTime, long phaseDelayDuration,
		 long increasingAlphaDuration,
		 long increasingAlphaRampDuration,
		 long alphaAtOneDuration) {
	this(loopCount, INCREASING_ENABLE, 
	     triggerTime, phaseDelayDuration,
	     increasingAlphaDuration, increasingAlphaRampDuration,
	     alphaAtOneDuration, 0, 0, 0);
    }


    /**
      *  This constructor takes only the loopCount and increasingAlphaDuration
      *  as parameters and assigns the default values to all of the other
      *  parameters.  
      * @param loopCount number of times to run this alpha; a value
      * of -1 specifies that the alpha loops indefinitely
      * @param increasingAlphaDuration period of time during which alpha goes
      * from zero to one
      */ 
    public Alpha(int loopCount, long increasingAlphaDuration) {
        // defaults
        mode = INCREASING_ENABLE;
        increasingAlpha = (float) increasingAlphaDuration * .001f;
        this.loopCount = loopCount;

	if (loopCount >= 0) {
	    stopTime = loopCount*increasingAlpha;
	}
    }


    /**
     * Pauses this alpha object.  The current system time when this
     * method is called will be used in place of the actual current
     * time when calculating subsequent alpha values.  This has the
     * effect of freezing the interpolator at the time the method is
     * called.
     *
     * @since Java 3D 1.3
     */
    public void pause() {
	pause(J3dClock.currentTimeMillis());
    }

    /**
     * Pauses this alpha object as of the specified time.  The specified
     * time will be used in place of the actual current time when
     * calculating subsequent alpha values.  This has the effect of freezing
     * the interpolator at the specified time.  Note that specifying a
     * time in the future (that is, a time greater than
     * System.currentTimeMillis()) will cause the alpha to immediately
     * advance to that point before pausing.  Similarly, specifying a
     * time in the past (that is, a time less than
     * System.currentTimeMillis()) will cause the alpha to immediately
     * revert to that point before pausing.
     *
     * @param time the time at which to pause the alpha
     *
     * @exception IllegalArgumentException if time <= 0
     *
     * @since Java 3D 1.3
     */
    public void pause(long time) {
	if (time <= 0L) {
	    throw new IllegalArgumentException(J3dI18N.getString("Alpha0"));
	}

	paused = true;
	pauseTime = time;
	VirtualUniverse.mc.sendRunMessage(J3dThread.RENDER_THREAD);
    }

    /**
     * Resumes this alpha object.  If the alpha
     * object was paused, the difference between the current
     * time and the pause time will be used to adjust the startTime of
     * this alpha.  The equation is as follows: