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:

• setIncreasingAlphaDuration - Time spent going from 0 to 1
• setIncreasingAlphaRampDuration - Time spend accelerating and decelearting during the increasing phase.
• setAlphaAtOneDuration - Time spent at value 1 after the increasing phase.
• setDecreasingAlphaDuration - Time spent going from 1 to 0.
• setDecreasingAlphaRampDuration - Time spend accelerating and decelearting during the decreasing phase.
• setAlphaAtZeroDuration - Time spent at value 0 after the decreasing phase.

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:

• setMode - ALPHA_INCREASING = (0 to 1); ALPHA_DECREASING = (1 to 0); ALPHA_INCREASING_AND_DECREASING = (0 to 1 to 0).
• setLoopCount - Number of times to loop through all alpha values.
• setTriggerTime - Time to start the alpha.
• setPhaseDelayDuration - Time to wait after the trigger time until really starting the alpha.
• isStarted - Returns true if the alpha has started for the given time parameter.
• isFinished - Returns true if the alpha has finished for the given time parameter.

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

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

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.

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

• ZAlpha.ALPHA_INCREASING - alpha values will go from 0 to 1 over time.
• ZAlpha.ALPHA_DECREASING - alpha values will go from 1 to 0 over time.
• ZAlpha.ALPHA_INCREASING_AND_DECREASING - alpha values will go from 0 to 1 to 0 over time.

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

• ZAlpha.ALPHA_INCREASING - alpha values will go from 0 to 1 over time.
• ZAlpha.ALPHA_DECREASING - alpha values will go from 1 to 0 over time.
• ZAlpha.ALPHA_INCREASING_AND_DECREASING - alpha values will go from 0 to 1 to 0 over time.

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.