edu.umd.cs.jazz.animation
Class ZAlpha

java.lang.Object
  |
  +--edu.umd.cs.jazz.animation.ZAlpha

public class ZAlpha
extends java.lang.Object

ZAlpha provides a uniform way to generate alpha values (floats that range from 0.0 to 1.0) over time. This classes interface is heavily based on the class javax.media.j3d.Alpha used with Java3D. You can read about that class here for supplemental documention here. http://java.sun.com/products/java-media/3D/.

Each ZAnimation is associated with a ZAlpha. ZAnimations and the animation system in general use alpha objects in two ways.

Its first purpose is to generate alpha values that animation classes use to interpolate from one value to another. For example the ZTransformAnimation uses a ZAlpha to interpolate between its source and destination transforms over time. By changing the alpha function you it is easy to change the rate that these interpolations happen at. The methodes concenrted with the alpha function aspect are:

The second way that alphas are used is to schedule when the animation will start when it will stop. The methods concerned with the scheduling aspect are:

ZAlpha objects can seem difficult to create with their many parameters and options. The convienience methods ZAlpha.createStandardAlpha and ZAlpha.createStandardSlowInSlowOutAlpha allow for quick and easy object creation. The following example code shows how to construct more complicated alpha objects.

 // Create a new ZAlpha that starts imediatly, runs once, changes linearly from 0 to 1, has a duration of one second.
 int loopCount = 1;
 long increasingDuration = 1000;
 alpha = new ZAlpha(loopCount, increasingDuration);


 // Create a new ZAlpha that starts two seconds after it is constructed,
 // runs once, changes linearly from 0 to 1, has a duration of one second.
 int loopCount = 1;
 long triggerTime = System.currentTime() + 1000;
 long phaseDelay = 0;
 long increasingDuration = 1000;
 alpha = new ZAlpha(loopCount, triggerTime, phaseDelay, increasingDuration);

 // Create a new ZAlpha that starts two seconds after it is constructed,
 // runs twice, changes from 0 to 1 (accelerating durring the first 250 milliseconds,
 // decelearting during the last 250 milliseconds) with a duration of one second, then pauses
 // at value 1 for 500 milliseconds before starting the next loop.
 int loopCount = 2;
 long triggerTime = System.currentTimeMillis() + 1000;
 long phaseDelay = 1000;
 long increasingDuration = 1000;
 long increasingRampDuration = 250;
 long alphaAtOneDuration = 500;
 alpha = new ZAlpha(loopCount,
                    triggerTime,
                    phaseDelay,
                    increasingDuration,
                    increasingRampDuration,
                    alphaAtOneDuration);
 

Author:
Jesse Grosjean
See Also:
ZAnimation

Field Summary
static int ALPHA_DECREASING
           
static int ALPHA_INCREASING
           
static int ALPHA_INCREASING_AND_DECREASING
           
 
Constructor Summary
ZAlpha()
          Construct a new ZAlpha using default parameters.
ZAlpha(int aLoopCount, int aMode, long aTriggerTime, long aPhaseDelayDuration, long aIncreasingAlphaDuration, long aIncreasingAlphaRampDuration, long aAlphaAtOneDuration, long aDecreasingAlphaDuration, long aDecreasingAlphaRampDuration, long aAlphaAtZeroDuration)
          Construct a new ZAlpha with all parameters.
ZAlpha(int aLoopCount, long aIncreasingAlphaDuration)
          Construct a new ZAlpha that will start immediately in ALPHA_INCREASING mode.
ZAlpha(int aLoopCount, long aTriggerTime, long aPhaseDelayDuration, long aIncreasingAlphaDuration)
          Construct a new ZAlpha in ALPHA_INCREASING mode whose alpha values change linearly.
ZAlpha(int aLoopCount, long aTriggerTime, long aPhaseDelayDuration, long aIncreasingAlphaDuration, long aIncreasingAlphaRampDuration, long aAlphaAtOneDuration)
          Construct a new ZAlpha with all parameter needed for ALPHA_INCREASING mode.
 
Method Summary
static ZAlpha createStandardAlpha(long aIncreasingAlphaDuration)
          Return a new ZAlpha that changes from 0 to 1, starting at the time this method is called and lasting for the supplied duration parameter.
static ZAlpha createStandardSlowInSlowOutAlpha(long aIncreasingAlphaDuration)
          Return a new ZAlpha that changes from 0 to 1, starting at the time this method is called and lasting for the supplied duration parameter.
 long getAlphaAtOneDuration()
          Return the number of milliseconds that alpha will remain at value 1 after the increasingAlphaDuration has finished, but before the next section starts.
 long getAlphaAtZeroDuration()
          Return the number of milliseconds that alpha will remain at value 0 after the decreasingAlphaDuration has finished, but before the next section starts.
 long getDecreasingAlphaDuration()
          Return the number of milliseconds that the alpha should take in its decreasing section where it moves from value 1 to 0.
 long getDecreasingAlphaRampDuration()
          Return the number of milliseconds that alpha accelerates at the beginning of its decreasingAlphaDuration and decelerates at the end of its decreasingAlphaDuration.
 long getIncreasingAlphaDuration()
          Return the number of milliseconds that the alpha should take in its increasing section where it moves from value 0 to 1.
 long getIncreasingAlphaRampDuration()
          Return the number of milliseconds that alpha accelerates at the beginning of its increasingAlphaDuration and decelerates at the end of its increasingAlphaDuration.
 int getLoopCount()
          Returns the number of times this alpha should run over its full range.
 int getMode()
          Return the mode that this alpha is using to generate its values.
 long getPhaseDelayDuration()
          Return the number of milliseconds after trigger time to wait before starting this alpha.
 long getStopTime()
          Returns the stop time for the alpha in milliseconds since midnight, January 1, 1970 UTC.
 long getTriggerTime()
          Returns the trigger time for the alpha in milliseconds since midnight, January 1, 1970 UTC.
protected  long getWaveLength()
          Return the amount of time in milliseconds that on iteration over the values of this alpha takes.
 boolean isFinished(long aTime)
          Return true if alpha has finished for the given time in milliseconds.
 boolean isStarted(long aTime)
          Return true if alpha has started for the given time in milliseconds.
protected  float lerp(long currentTime, long totalTime)
          Linearly interpolate between the currentTime and totalTime.
 void setAlphaAtOneDuration(long aAlphaAtOneDuration)
          Set the number of milliseconds that alpha will remain at value 1 after the increasingAlphaDuration has finished, but before the next section starts.
 void setAlphaAtZeroDuration(long aAlphaAtZeroDuration)
          Set the number of milliseconds that alpha will remain at value 0 after the decreasingAlphaDuration has finished, but before the next section starts.
 void setDecreasingAlphaDuration(long aDecreasingAlphaDuration)
          Set the number of milliseconds that the alpha should take in its decreasing section where it moves from value 1 to 0.
 void setDecreasingAlphaRampDuration(long aDecreasingAlphaRampDuration)
          Set the number of milliseconds that alpha accelerates at the beginning of its decreasingAlphaDuration and decelerates at the end of its decreasingAlphaDuration.
 void setIncreasingAlphaDuration(long aIncreasingAlphaDuration)
          Set the number of milliseconds that the alpha should take in its increasing section where it moves from value 0 to 1.
 void setIncreasingAlphaRampDuration(long aIncreasingAlphaRampDuration)
          Set the number of milliseconds that alpha accelerates at the beginning of its increasingAlphaDuration and decelerates at the end of its increasingAlphaDuration.
 void setLoopCount(int aLoopCount)
          Sets the number of times this alpha should run over its full range.
 void setMode(int aMode)
          Sets the mode that this alpha is using to generate its values.
 void setPhaseDelayDuration(long aPhaseDelayDuration)
          Set the number of milliseconds after trigger time to wait before starting this alpha.
 void setTriggerTime(long aTriggerTime)
          Sets the trigger time for the alpha in milliseconds since midnight, January 1, 1970 UTC.
protected  float sisoLerp(long aTotalTime, long aCurrentTime, long aRampTime)
          Slow in slow out interpolate between the currentTime and totalTime.
 float value(long aCurrentTime)
          Return the alpha value, from 0 to 1, based on the time to alpha mapping parameters set for this interpolator.
protected  float valueAlphaDecreasing(long aWaveRelativeTime)
          Return the alpha value for the given wave relative time (normalized to the start of the wave) using the mode ALPHA_DECREASING.
protected  float valueAlphaIncreasing(long aWaveRelativeTime)
          Return the alpha value for the given wave relative time (normalized to the start of the wave) using the mode ALPHA_INCREASING.
protected  float valueAlphaIncreasingAndDecreasing(long aWaveRelativeTime)
          Return the alpha value for the given wave relative time (normalized to the start of the wave) using the mode ALPHA_INCREASING_AND_DECREASING.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ALPHA_INCREASING

public static final int ALPHA_INCREASING
See Also:
Constant Field Values

ALPHA_DECREASING

public static final int ALPHA_DECREASING
See Also:
Constant Field Values

ALPHA_INCREASING_AND_DECREASING

public static final int ALPHA_INCREASING_AND_DECREASING
See Also:
Constant Field Values
Constructor Detail

ZAlpha

public ZAlpha()
Construct a new ZAlpha using default parameters.


ZAlpha

public ZAlpha(int aLoopCount,
              long aIncreasingAlphaDuration)
Construct a new ZAlpha that will start immediately in ALPHA_INCREASING mode.

Parameters:
aLoopCount - The number of times this alpha should loop over its full range of values.
aIncreasingAlphaDuration - The amount of time that the alpha should spend in its increasing section.

ZAlpha

public ZAlpha(int aLoopCount,
              long aTriggerTime,
              long aPhaseDelayDuration,
              long aIncreasingAlphaDuration)
Construct a new ZAlpha in ALPHA_INCREASING mode whose alpha values change linearly.

Parameters:
aLoopCount - The number of times this alpha should loop over its full range of values.
aTriggerTime - The time that the alpha should start generating values.
aPhaseDelayDuration - The delay that the alpha should wait after trigger time before actually generating values.
aIncreasingAlphaDuration - The amount of time that the alpha should spend in its increasing section.

ZAlpha

public ZAlpha(int aLoopCount,
              long aTriggerTime,
              long aPhaseDelayDuration,
              long aIncreasingAlphaDuration,
              long aIncreasingAlphaRampDuration,
              long aAlphaAtOneDuration)
Construct a new ZAlpha with all parameter needed for ALPHA_INCREASING mode.

Parameters:
aLoopCount - The number of times this alpha should loop over its full range of values.
aTriggerTime - The time that the alpha should start generating values.
aPhaseDelayDuration - The delay that the alpha should wait after trigger time before actually generating values.
aIncreasingAlphaDuration - The amount of time that the alpha should spend in its increasing section.
aIncreasingAlphaRampDuration - The amount of time that the alpha should accelerate and then decelerate in its increasing section.
aAlphaAtOneDuration - The amount of time that the alpha should spend at 1 in its increasing section.

ZAlpha

public ZAlpha(int aLoopCount,
              int aMode,
              long aTriggerTime,
              long aPhaseDelayDuration,
              long aIncreasingAlphaDuration,
              long aIncreasingAlphaRampDuration,
              long aAlphaAtOneDuration,
              long aDecreasingAlphaDuration,
              long aDecreasingAlphaRampDuration,
              long aAlphaAtZeroDuration)
Construct a new ZAlpha with all parameters.

Parameters:
aLoopCount - The number of times this alpha should loop over its full range of values.
aMode - The mode alpha should use to generate values, ALPHA_INCREASING, ALPHA_DECREASING, ALPHA_INCREASING_AND_DECREASING.
aTriggerTime - The time that the alpha should start generating values.
aPhaseDelayDuration - The delay that the alpha should wait after trigger time before actually generating values.
aIncreasingAlphaDuration - The amount of time that the alpha should spend in its increasing section.
aIncreasingAlphaRampDuration - The amount of time that the alpha should accelerate and then decelerate in its increasing section.
aAlphaAtOneDuration - The amount of time that the alpha should spend at 1 in its increasing section.
aDecreasingAlphaDuration - The amount of time that the alpha should spend in its decreasing section.
aDecreasingAlphaRampDuration - The amount of time that the alpha should accelerate and then decelerate in its decreasing section.
aAlphaAtZeroDuration - The amount of time that the alpha should spend at 0 in its decreasing section.
Method Detail

createStandardAlpha

public static ZAlpha createStandardAlpha(long aIncreasingAlphaDuration)
Return a new ZAlpha that changes from 0 to 1, starting at the time this method is called and lasting for the supplied duration parameter. The alpha will change linearly.


createStandardSlowInSlowOutAlpha

public static ZAlpha createStandardSlowInSlowOutAlpha(long aIncreasingAlphaDuration)
Return a new ZAlpha that changes from 0 to 1, starting at the time this method is called and lasting for the supplied duration parameter. The alpha will change with slow in slow out behavior.


getLoopCount

public int getLoopCount()
Returns the number of times this alpha should run over its full range. A value of -1 means it should run indefinitely. The default loopCount value is -1.


setLoopCount

public void setLoopCount(int aLoopCount)
Sets the number of times this alpha should run over its full range. A value of -1 means it should run indefinitely. The default loopCount value is -1.


getMode

public int getMode()
Return the mode that this alpha is using to generate its values. Possible choices are

The default mode for alpha objects is ALPHA_INCREASING. By default alpha values will be generated from 0 to 1 for the increasingAlphaDuration and then 1 values will be generated for alphaAtOneDuration. Then the alpha will finish, or start another loop generating values.


setMode

public void setMode(int aMode)
Sets the mode that this alpha is using to generate its values. Possible choices are

The default mode for alpha objects is ALPHA_INCREASING. By default alpha values will be generated from 0 to 1 for the increasingAlphaDuration and then 1 values will be generated for alphaAtOneDuration. Then the alpha will finish, or start another loop generating values.


getTriggerTime

public long getTriggerTime()
Returns the trigger time for the alpha in milliseconds since midnight, January 1, 1970 UTC. This trigger time can be offset using setPhaseDelayDuration. The alpha will start running as soon as possible after System.currentTimeMillis() >= triggerTime + phaseDelayDuration.

The default value for trigger time is the value of System.currentTimeMillis() when the alpha object is constructed. This means that normally as soon as an alpha is constructed it will also be started.


setTriggerTime

public void setTriggerTime(long aTriggerTime)
Sets the trigger time for the alpha in milliseconds since midnight, January 1, 1970 UTC. This trigger time can be offset using setPhaseDelayDuration. The alpha will start running as soon as possible after System.currentTimeMillis() >= triggerTime + phaseDelayDuration.

The default value for trigger time is the value of System.currentTimeMillis() when the alpha object is constructed. This means that normally as soon as an alpha is constructed it will also be started.


getPhaseDelayDuration

public long getPhaseDelayDuration()
Return the number of milliseconds after trigger time to wait before starting this alpha. The default value is 0, the alpha will start at triggerTime.


setPhaseDelayDuration

public void setPhaseDelayDuration(long aPhaseDelayDuration)
Set the number of milliseconds after trigger time to wait before starting this alpha. The default value is 0, the alpha will start at triggerTime.


getIncreasingAlphaDuration

public long getIncreasingAlphaDuration()
Return the number of milliseconds that the alpha should take in its increasing section where it moves from value 0 to 1.


setIncreasingAlphaDuration

public void setIncreasingAlphaDuration(long aIncreasingAlphaDuration)
Set the number of milliseconds that the alpha should take in its increasing section where it moves from value 0 to 1.


getIncreasingAlphaRampDuration

public long getIncreasingAlphaRampDuration()
Return the number of milliseconds that alpha accelerates at the beginning of its increasingAlphaDuration and decelerates at the end of its increasingAlphaDuration. This value is clamped to half the increasingAlphaDuration. If the value is zero alpha will change linearly, at a constant velocity.

The default value is 0, increasing alpha changes linearly.


setIncreasingAlphaRampDuration

public void setIncreasingAlphaRampDuration(long aIncreasingAlphaRampDuration)
Set the number of milliseconds that alpha accelerates at the beginning of its increasingAlphaDuration and decelerates at the end of its increasingAlphaDuration. This value is clamped to half the increasingAlphaDuration. If the value is zero alpha will change linearly, at a constant velocity.

The default value is 0, increasing alpha changes linearly.


getAlphaAtOneDuration

public long getAlphaAtOneDuration()
Return the number of milliseconds that alpha will remain at value 1 after the increasingAlphaDuration has finished, but before the next section starts.

The default value is 0, increasing alpha does not pause at 1.


setAlphaAtOneDuration

public void setAlphaAtOneDuration(long aAlphaAtOneDuration)
Set the number of milliseconds that alpha will remain at value 1 after the increasingAlphaDuration has finished, but before the next section starts.

The default value is 0, increasing alpha does not pause at 1.


getDecreasingAlphaDuration

public long getDecreasingAlphaDuration()
Return the number of milliseconds that the alpha should take in its decreasing section where it moves from value 1 to 0.


setDecreasingAlphaDuration

public void setDecreasingAlphaDuration(long aDecreasingAlphaDuration)
Set the number of milliseconds that the alpha should take in its decreasing section where it moves from value 1 to 0.


getDecreasingAlphaRampDuration

public long getDecreasingAlphaRampDuration()
Return the number of milliseconds that alpha accelerates at the beginning of its decreasingAlphaDuration and decelerates at the end of its decreasingAlphaDuration. This value is clamped to half the decreasingAlphaDuration. If the value is zero alpha will change linearly, at a constant velocity.

The default value is 0, decreasing alpha changes linearly.


setDecreasingAlphaRampDuration

public void setDecreasingAlphaRampDuration(long aDecreasingAlphaRampDuration)
Set the number of milliseconds that alpha accelerates at the beginning of its decreasingAlphaDuration and decelerates at the end of its decreasingAlphaDuration. This value is clamped to half the decreasingAlphaDuration. If the value is zero alpha will change linearly, at a constant velocity.

The default value is 0, decreasing alpha changes linearly.


getAlphaAtZeroDuration

public long getAlphaAtZeroDuration()
Return the number of milliseconds that alpha will remain at value 0 after the decreasingAlphaDuration has finished, but before the next section starts.

The default value is 0, decreasing alpha does not pause at 0.


setAlphaAtZeroDuration

public void setAlphaAtZeroDuration(long aAlphaAtZeroDuration)
Set the number of milliseconds that alpha will remain at value 0 after the decreasingAlphaDuration has finished, but before the next section starts.

The default value is 0, decreasing alpha does not pause at 0.


isStarted

public boolean isStarted(long aTime)
Return true if alpha has started for the given time in milliseconds. This is determined by testing if aTime >= triggerTime + phaseDelayDuration. If asked for an alpha value before it has been started it will return the first alpha value.


isFinished

public boolean isFinished(long aTime)
Return true if alpha has finished for the given time in milliseconds. This will always return false if the loopCount == -1, alpha is running indefinitaly. If asked for an alpha value after it has finished it will return the last alpha value.


getStopTime

public long getStopTime()
Returns the stop time for the alpha in milliseconds since midnight, January 1, 1970 UTC.


lerp

protected float lerp(long currentTime,
                     long totalTime)
Linearly interpolate between the currentTime and totalTime.


sisoLerp

protected float sisoLerp(long aTotalTime,
                         long aCurrentTime,
                         long aRampTime)
Slow in slow out interpolate between the currentTime and totalTime.


value

public float value(long aCurrentTime)
Return the alpha value, from 0 to 1, based on the time to alpha mapping parameters set for this interpolator. If the time to alpha mapping has not yet started then the starting alpha value is returned. If it has finished then the ending alpha value is returned.


valueAlphaIncreasing

protected float valueAlphaIncreasing(long aWaveRelativeTime)
Return the alpha value for the given wave relative time (normalized to the start of the wave) using the mode ALPHA_INCREASING.


valueAlphaDecreasing

protected float valueAlphaDecreasing(long aWaveRelativeTime)
Return the alpha value for the given wave relative time (normalized to the start of the wave) using the mode ALPHA_DECREASING.


valueAlphaIncreasingAndDecreasing

protected float valueAlphaIncreasingAndDecreasing(long aWaveRelativeTime)
Return the alpha value for the given wave relative time (normalized to the start of the wave) using the mode ALPHA_INCREASING_AND_DECREASING.


getWaveLength

protected long getWaveLength()
Return the amount of time in milliseconds that on iteration over the values of this alpha takes.



Copyright 2003 by University of Maryland, College Park, MD 20742, USA All rights reserved.