A VisualAnimation is constructed with an AnimatedProperty. More...

#include <VisualAnimation.h>

Inheritance diagram for VizKit::VisualAnimation:

Public Member Functions
	VisualAnimation (AnimatedProperty theAnimatedProperty, bool aDebugMode=false)
	Constructor.
	~VisualAnimation ()
	The destructor.
	VisualAnimation (const VisualAnimation &other)
	Copy constructor.
VisualAnimation &	operator= (const VisualAnimation &other)
	Assignment operator.
virtual VisualAnimationComponent *	clone (void) const
	Copies the current VisualAnimation and returns a pointer to a new VisualAnimation.
void	setAnimateCallbackFunctionPtr (VisualAnimationAnimateCallback theCallback, void *someUserData=NULL)
	Sets the callback function that is repeatedly called in animation's duration time.
virtual void	setIdentifierOfParentCollection (const VisualItemIdentifier &aCollectionIdentifier)
	Sets the identifier of the parent collection (the collection which the current animation is part of).
virtual void	handleOneCollectionItemAnimationDied (void)
	Executes the appropriate action for the case that one animation of the current collection died.
virtual VisualAnimationComponent *	getVisualAnimation (const VisualItemIdentifier &anAnimationIdentifier)
	Returns the VisualAnimation if the VisualItemIdentifier matches.
virtual void	animate (void)
	Executes the callback function to animate a property.
virtual void	start (void)
	Starts the Animation.
virtual void	stop (void)
	Stops the Animation.
void	setDurationInMilliseconds (uint32 numberOfMilliseconds)
	Sets the duration of the animation.
uint32	getDurationInMilliseconds (void) const
	Returns the duration of the animation.
void	setCurrentValue (double aCurrentValue)
	Sets the current value of the animation.
double	getCurrentValue (void) const
	Returns the current value of the animation.
void	setStartValue (double aStartValue, bool startAnimationWithCurrentPropertyValue=false)
	Sets the start value of the animation.
void	setStartValue (const VisualStagePosition &aPosition, bool startAnimationWithCurrentPropertyValue=false)
	Sets the start value of the animation.
double	getStartValue (void) const
	Returns the start value of the animation.
void	setStopValue (double aStopValue)
	Sets the stop value of the animation.
void	setStopValue (const VisualStagePosition &aPosition)
	Sets the stop value of the animation.
double	getStopValue (void) const
	Returns the stop value of the animation.
void	setLoopMode (LoopMode aLoopMode, sint32 requestedNumberOfLoops=1)
	Sets the loop mode of the animation.
void	setInterpolationType (InterpolationType anInterpolationType)
	Sets the type of interpolation.
uint32	getStartDelayInMilliseconds (void) const
	Returns the number of milliseconds until the animation is supposed to actually start.
void	setStartDelayInMilliseconds (uint32 aStartDelayInMilliseconds)
	Sets the number of milliseconds until the animation actually starts.
virtual void	setCallbackToPerformAnyAdditionalAction (VisualAnimationPerformAnyAdditionalActionCallback theCallback, void *userData=NULL)
	Sets the callback function that is repeatedly called back during animation component's duration time.
virtual void	setCallbackToNotifyBeforeDeath (VisualAnimationWillDieCallback theCallback, void *userData=NULL)
	Sets the callback function that is called right before the death of the animation component.
virtual void	notifyBeforeDeath (void)
	Calls any callback functions right before the death of the animation component.
virtual AnimatedProperty	getAnimatedProperty (void) const
	Returns the animated property of the animation.
MovingDirection	getMovingDirection (void) const
	Returns the moving direction (running direction) of the animation.
RepeatMode	getRepeatMode (void) const
	Returns the current repeat mode of the animation.
virtual void	update (void)
	Updates the state of the animation.
virtual bool	isRunning (void) const
	Answers the question whether the animation is (still) running.
virtual bool	isReadyToDie (void) const
	Answers the question whether the animation ended and is ready to be destroyed.
void	setDebugMode (bool requestedDebugMode)
	Sets the debug mode.
virtual void	preparePriorToAddingToAsset (VisualAsset &visualAsset)
	Prepares the animation before it is added to an asset.
virtual const VisualAsset *const	getEnclosingAsset (void) const
	Returns the asset the animation has been added to.
void	setSpeed (AnimationSpeed animationSpeed)
	Sets the speed of the animation.
AnimationSpeed	getSpeed (void) const
	Returns the current speed of the animation.
Static Public Member Functions
static AnimationSpeed	calcSpeed (double aStartValue, double aStopValue, uint32 aDurationInMilliseconds)
	Calculates the speed of an animation if it would use the passed start and stop values with the provided duration time.
static AnimationSpeed	calcSpeed (double aDistance, uint32 aDurationInMilliseconds)
	Calculates the speed of an animation of a certain distance and duration.
static uint32	calcDurationInMilliseconds (double aDistance, AnimationSpeed aSpeed)
	Calculates the time an animation will take to travel a certain distance with a certain constant speed.
Private Types
enum	VisualAnimationStatus { kIsNotRunning = 0, kIsRunning, kIsReadyToDie }
	The possible status values of the VisualAnimation. More...
enum	DurationSpeedConstraint { kDurationBound, kSpeedBound }
	Whether the animation is bound to speed or duration. More...
typedef std::vector< double >	DebugHistory
	Data entries stored for debug and monitoring purposes.
typedef DebugHistory::iterator	DebugHistoryIterator
	The DebugHistoryIterator is an iterator of the DebugHistory.
Private Member Functions
void	copy (const VisualAnimation &other)
	Copy method for assignment operator and copy constructor.
void	durationIsExceeded (void)
	Internal method called when the duration time of the timeline did exceed.
void	setCurrentTimelineValueToCurrentPropertyValue (const VisualAsset &visualAsset, AnimatedProperty anAnimatedProperty)
	Internal method to adjust the current timeline value to the current value of the animated property.
void	decrementRemainingNumberOfRepeats (void)
	Decrement the number of remaining repeats.
Private Attributes
AnimatedProperty	animatedProperty
	The property of the asset that is affected by the animation.
VisualTimeline *	theTimeline
	The pointer to the timeline of the animation.
sint32	remainingNumberOfRepeats
	The remaining number of times the animation should pass.
VisualAnimationAnimateCallback	animateCallback
	The callback function that is called during the animation.
void *	animationUserData
	Internally stored pointer to provided user data (e.g.
VisualAnimationPerformAnyAdditionalActionCallback	performAnyAdditionalActionCallback
	The optional callback function that is called during the animation.
void *	performAnyAdditionalActionCallbackUserData
	The optional user data that is passed to callback function that is called during the animation.
uint32	startDelayInMilliseconds
	The number of milliseconds until the animation will be actually used by VisualStageControl.
bool	debugMode
	True if in debug mode, false otherwise.
uint32	currDebugHistoryEntry
	The current entry of the debug history.
DebugHistory	debugHistory
	The data entries stored for debug and monitoring purposes.
bool	debugHistoryIsInitialized
	True if the maximum number of data entries of debugHistory are initialized, false otherwise.
VisualAnimationStatus	status
	The status of the VisualAnimation.
VisualItemIdentifier *	collectionIdentifier
	The optional identifier of the collection of the animation (the cluster resp.
const VisualAsset *	enclosingAsset
	The asset the animation has been added to.
AnimationSpeed	speed
	The speed of the animation (the speed is driving value in case no start value has been set).
bool	doStartAnimationWithCurrentPropertyValue
	True if the animation is supposed to start with the current value of the animated property.
double	startValue
	The start value of the animation as it has been set by setStartValue().
VisualStagePosition	startValueVisualStagePosition
	The start value of the animation as it has been set by setStartValue(), with data type VisualStagePosition.
double	stopValue
	The stop value of the animation as it has been set by setStopValue().
VisualStagePosition	stopValueVisualStagePosition
	The stop value of the animation as it has been set by setStopValue(), with data type VisualStagePosition.
DurationSpeedConstraint	durationSpeedConstraint
	The constraint of the animation (whether bound to speed or duration).
VisualAnimationWillDieCallback	willDieCallback
	The optional callback function that is called right before the death of the animation cluster.
void *	willDieCallbackUserData
	The optional user data that is passed to callback function that is called right before the death of the animation cluster.
Static Private Attributes
static const uint32	maxNumberOfDebugHistoryEntries = 700
	The maximum number of data entries stored in history for debug and monitoring purposes.

Detailed Description

A VisualAnimation is constructed with an AnimatedProperty.

With VisualActor::addAnimation() specific properies of an asset can be animated. A provided callback function is called for the time of the duration of the animation. The animation tries to reach the stop value in the amount of time set by the duration value.

Member Typedef Documentation

typedef std::vector<double> VizKit::VisualAnimation::DebugHistory [private]

Data entries stored for debug and monitoring purposes.

typedef DebugHistory::iterator VizKit::VisualAnimation::DebugHistoryIterator [private]

The DebugHistoryIterator is an iterator of the DebugHistory.

Member Enumeration Documentation

enum VizKit::VisualAnimation::DurationSpeedConstraint [private]

Whether the animation is bound to speed or duration.

Enumerator:

kDurationBound	The speed of the animation is determined by setting the duration time.
kSpeedBound	The duration of the animation is dependent on the speed.

enum VizKit::VisualAnimation::VisualAnimationStatus [private]

The possible status values of the VisualAnimation.

Enumerator:

kIsNotRunning	Animation is not running.
kIsRunning	Animation is running.
kIsReadyToDie	Animation ended and will be destroyed next.

Constructor & Destructor Documentation

VisualAnimation::VisualAnimation	(	AnimatedProperty	theAnimatedProperty,
		bool	aDebugMode = `false`
	)

Constructor.

Parameters:

theAnimatedProperty	The property of the asset that is affected by the animation.
aDebugMode	If true, the animation is in debug mode.

VisualAnimation::~VisualAnimation ( )

The destructor.

VisualAnimation::VisualAnimation ( const VisualAnimation & other )

Copy constructor.

Parameters:

other Reference to another VisualAnimation.

Member Function Documentation

void VisualAnimation::animate ( void ) [virtual]

Executes the callback function to animate a property.

Implements VizKit::VisualAnimationComponent.

uint32 VisualAnimation::calcDurationInMilliseconds	(	double	aDistance,
		AnimationSpeed	aSpeed
	)		`[static]`

Calculates the time an animation will take to travel a certain distance with a certain constant speed.

Parameters:

aDistance	The distance of the values of the animation.
aSpeed	Speed of the animation.

Returns:: The duration of the animation measured in milliseconds.

AnimationSpeed VisualAnimation::calcSpeed	(	double	aStartValue,
		double	aStopValue,
		uint32	aDurationInMilliseconds
	)		`[static]`

Calculates the speed of an animation if it would use the passed start and stop values with the provided duration time.

Parameters:

aStartValue	A start value of an animation.
aStopValue	A stop value of an animation.
aDurationInMilliseconds	A duration of an animation measured in milliseconds.

Returns:: The speed of an animation.

AnimationSpeed VisualAnimation::calcSpeed	(	double	aDistance,
		uint32	aDurationInMilliseconds
	)		`[static]`

Calculates the speed of an animation of a certain distance and duration.

Parameters:

aDistance	The distance of the values of the animation.
aDurationInMilliseconds	Duration of the animation measured in milliseconds.

Returns:: The speed of the animation.

VisualAnimationComponent * VisualAnimation::clone ( void ) const [virtual]

Copies the current VisualAnimation and returns a pointer to a new VisualAnimation.

Implements VizKit::VisualAnimationComponent.

void VisualAnimation::copy ( const VisualAnimation & other ) [private]

Copy method for assignment operator and copy constructor.

Parameters:

other Another VisualAnimation.

void VisualAnimation::decrementRemainingNumberOfRepeats ( void ) [private]

Decrement the number of remaining repeats.

void VisualAnimation::durationIsExceeded ( void ) [private]

Internal method called when the duration time of the timeline did exceed.

AnimatedProperty VisualAnimation::getAnimatedProperty ( void ) const [virtual]

Returns the animated property of the animation.

Returns:: The animated property of the animation.

Implements VizKit::VisualAnimationComponent.

double VisualAnimation::getCurrentValue ( void ) const

Returns the current value of the animation.

Returns:: The current value of the animation.

uint32 VisualAnimation::getDurationInMilliseconds ( void ) const

Returns the duration of the animation.

Returns:: The duration of the animation.

const VisualAsset *const VisualAnimation::getEnclosingAsset ( void ) const [virtual]

Returns the asset the animation has been added to.

Returns:: The asset the animation has been added to.

Implements VizKit::VisualAnimationComponent.

MovingDirection VisualAnimation::getMovingDirection ( void ) const

Returns the moving direction (running direction) of the animation.

Returns:: The currently moving direction (running direction) of the animation.

RepeatMode VisualAnimation::getRepeatMode ( void ) const

Returns the current repeat mode of the animation.

Returns:: The current repeat mode of the animation.

AnimationSpeed VisualAnimation::getSpeed ( void ) const

Returns the current speed of the animation.

Returns:: The current speed of the animation.

uint32 VisualAnimation::getStartDelayInMilliseconds ( void ) const

Returns the number of milliseconds until the animation is supposed to actually start.

Returns:: The number of milliseconds until the animation is supposed to actually start.

Remarks:: The delay is set when calling setDurationInMilliseconds(). The value is used by VisualStageControl.

double VisualAnimation::getStartValue ( void ) const

Returns the start value of the animation.

Returns:: The start value of the animation.

double VisualAnimation::getStopValue ( void ) const

Returns the stop value of the animation.

Returns:: The stop value of the animation.

VisualAnimationComponent * VisualAnimation::getVisualAnimation ( const VisualItemIdentifier & anAnimationIdentifier ) [virtual]

Returns the VisualAnimation if the VisualItemIdentifier matches.

Parameters:

anAnimationIdentifier The identifier of the animation.

Returns:: The VisualAnimation with the specified VisualItemIdentifier.

Remarks:: Return value can be NULL if no VisualAnimation with the specified VisualItemIdentifier is found.

Implements VizKit::VisualAnimationComponent.

void VisualAnimation::handleOneCollectionItemAnimationDied ( void ) [virtual]

Executes the appropriate action for the case that one animation of the current collection died.

Remarks:: Only appropriate for collection (like cluster and sequence). VisualAnimation simply returns after printing an error message.

Implements VizKit::VisualAnimationComponent.

bool VisualAnimation::isReadyToDie ( void ) const [virtual]

Answers the question whether the animation ended and is ready to be destroyed.

Returns:: True is the animation ended. False otherwise.

Remarks:: The animation is redy to die when the duration is exceeded. VisualAnimationQueue acts on a true return value and deletes the VisualAnimation.

Implements VizKit::VisualAnimationComponent.

bool VisualAnimation::isRunning ( void ) const [virtual]

Answers the question whether the animation is (still) running.

Returns:: True if the animation is (still) running. False otherwise.

Implements VizKit::VisualAnimationComponent.

void VisualAnimation::notifyBeforeDeath ( void ) [virtual]

Calls any callback functions right before the death of the animation component.

Implements VizKit::VisualAnimationComponent.

VisualAnimation & VisualAnimation::operator= ( const VisualAnimation & other )

Assignment operator.

Parameters:

other Reference to another VisualAnimation.

void VisualAnimation::preparePriorToAddingToAsset ( VisualAsset & visualAsset ) [virtual]

Prepares the animation before it is added to an asset.

Parameters:

visualAsset The asset the animation is supposed to be added to.

Implements VizKit::VisualAnimationComponent.

void VisualAnimation::setAnimateCallbackFunctionPtr	(	VisualAnimationAnimateCallback	theCallback,
		void *	someUserData = `NULL`
	)

Sets the callback function that is repeatedly called in animation's duration time.

Parameters:

theCallback	Pointer to c-style function (static class function).
someUserData	Additional data (e.g. pointer to instance variable of initialized class).

void VisualAnimation::setCallbackToNotifyBeforeDeath	(	VisualAnimationWillDieCallback	theCallback,
		void *	userData = `NULL`
	)		`[virtual]`

Sets the callback function that is called right before the death of the animation component.

Parameters:

theCallback	Pointer to c-style function (static class function).
userData	Additional data (e.g. pointer to instance variable of initialized class).

Implements VizKit::VisualAnimationComponent.

void VisualAnimation::setCallbackToPerformAnyAdditionalAction	(	VisualAnimationPerformAnyAdditionalActionCallback	theCallback,
		void *	userData = `NULL`
	)		`[virtual]`

Sets the callback function that is repeatedly called back during animation component's duration time.

Parameters:

theCallback	Pointer to c-style function (static class function).
userData	Additional data (e.g. pointer to instance variable of initialized class).

Implements VizKit::VisualAnimationComponent.

void VisualAnimation::setCurrentTimelineValueToCurrentPropertyValue	(	const VisualAsset &	visualAsset,
		AnimatedProperty	anAnimatedProperty
	)		`[private]`

Internal method to adjust the current timeline value to the current value of the animated property.

Parameters:

visualAsset	The asset where a property is animated.
anAnimatedProperty	The animated property.

void VisualAnimation::setCurrentValue ( double aCurrentValue )

Sets the current value of the animation.

Parameters:

aCurrentValue The current value of the animation.

Remarks:: The animation always ranges from start value to stop value (default: 0.0 to 1.0). Setting a specific current value here means that the animation starts its first step with the specific current value. Can be useful if an animation is supposed to continue at the point in time of a prior animation. The initial value of the constructor (0.0) does not change the current value.

void VisualAnimation::setDebugMode ( bool requestedDebugMode )

Sets the debug mode.

Parameters:

requestedDebugMode The debug mode. True turns debug mode on, false turns it off.

void VisualAnimation::setDurationInMilliseconds ( uint32 numberOfMilliseconds )

Sets the duration of the animation.

Parameters:

numberOfMilliseconds The number of milliseconds the animation spans.

void VisualAnimation::setIdentifierOfParentCollection ( const VisualItemIdentifier & aCollectionIdentifier ) [virtual]

Sets the identifier of the parent collection (the collection which the current animation is part of).

Parameters:

aCollectionIdentifier The identifier of the parent collection.

Implements VizKit::VisualAnimationComponent.

void VisualAnimation::setInterpolationType ( InterpolationType anInterpolationType )

Sets the type of interpolation.

Parameters:

anInterpolationType The requested type of interpolation.

void VisualAnimation::setLoopMode	(	LoopMode	aLoopMode,
		sint32	requestedNumberOfLoops = `1`
	)

Sets the loop mode of the animation.

Parameters:

aLoopMode	The requested loop mode.
requestedNumberOfLoops	The number of times the animation should be repeated (default = 1).

void VisualAnimation::setSpeed ( AnimationSpeed animationSpeed )

Sets the speed of the animation.

Parameters:

animationSpeed The speed of the animation (as it has been calculated by static function VisualAnimation::calcSpeed());

void VisualAnimation::setStartDelayInMilliseconds ( uint32 aStartDelayInMilliseconds )

Sets the number of milliseconds until the animation actually starts.

Parameters:

aStartDelayInMilliseconds The number of milliseconds until the animation actually starts.

Remarks:: The delay counts from the moment start() is called.

void VisualAnimation::setStartValue	(	double	aStartValue,
		bool	startAnimationWithCurrentPropertyValue = `false`
	)

Sets the start value of the animation.

Parameters:

aStartValue	The start value of the animation.
startAnimationWithCurrentPropertyValue	If true, the animation starts with the current value of the animated property. Default is false as it is assumed that a set start value is meant to act as value to start the animation with.

Remarks:: Default is 0.0.

void VisualAnimation::setStartValue	(	const VisualStagePosition &	aPosition,
		bool	startAnimationWithCurrentPropertyValue = `false`
	)

Sets the start value of the animation.

Parameters:

aPosition	The start value of the animation as position.
startAnimationWithCurrentPropertyValue	If true, the animation starts with the current value of the animated property. Default is false as it is assumed that a set start value is meant to act as value to start the animation with.

Remarks:: Default is 0.0.

void VisualAnimation::setStopValue ( double aStopValue )

Sets the stop value of the animation.

Parameters:

aStopValue The stop value of the animation.

Remarks:: Default is 1.0.

void VisualAnimation::setStopValue ( const VisualStagePosition & aPosition )

Sets the stop value of the animation.

Parameters:

aPosition The stop value of the animation as position.

void VisualAnimation::start ( void ) [virtual]

Starts the Animation.

Remarks:: In case the start is delayed, the animation is only running after the delaying milliseconds did have passed.

Implements VizKit::VisualAnimationComponent.

void VisualAnimation::stop ( void ) [virtual]

Stops the Animation.

Implements VizKit::VisualAnimationComponent.

void VisualAnimation::update ( void ) [virtual]

Updates the state of the animation.

Remarks:: Called by VisualAnimationQueue. Updates the current value of the animation. Also tests whether the animation is supposed to be started in case the start was delayed.

Implements VizKit::VisualAnimationComponent.