/*
 * Project: VizKit
 * Version: 2.3
 
 * Date: 20090823
 * File: VisualAnimation.h
 *
 */

/***************************************************************************

Copyright (c) 2004-2009 Heiko Wichmann (http://www.imagomat.de/vizkit)


This software is provided 'as-is', without any expressed or implied warranty. 
In no event will the authors be held liable for any damages
arising from the use of this software.

Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; 
   you must not claim that you wrote the original software. 
   If you use this software in a product, an acknowledgment 
   in the product documentation would be appreciated 
   but is not required.

2. Altered source versions must be plainly marked as such, 
   and must not be misrepresented as being the original software.

3. This notice may not be removed or altered from any source distribution.

 ***************************************************************************/

#ifndef VisualAnimation_h
#define VisualAnimation_h


#include "VisualTypes.h"
#include "VisualAnimationComponent.h"
#include "VisualAnimationTypes.h"
#include "VisualStagePosition.h"

#include <vector>


namespace VizKit {

	/** Animation callback */
	typedef void (*VisualAnimationAnimateCallback)(double currentPosition, void* userData);

	class VisualTimeline; // Forward declaration (to avoid include of header file).

	/**
	 * The type of looping.
	 */
	typedef enum {
		kNoLoop = 0x0, /**< 00000000 - After the duration of the timeline has been reached, the animation stops. */
		kLoop = 0x2, /**< 00000010 - After the duration of the timeline has been reached, the timeline starts anew at the start. The timeline is always processed in forward direction. */
		kMirroredLoop = 0x3 /**< 00000011 - After the duration of the timeline has been reached, the timeline is processed in backward direction. The moving direction toggles in mirrored loop. */
	} LoopMode;

	const sint32 kInfiniteRepetition = -1;

	/**
	 * 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.
	 */
	class VisualAnimation : public VisualAnimationComponent {

	public:

		/**
		 * Constructor.
		 * @param theAnimatedProperty The property of the asset that is affected by the animation.
		 * @param aDebugMode If true, the animation is in debug mode.
		 */
		VisualAnimation(AnimatedProperty theAnimatedProperty, bool aDebugMode = false);

		/**
		 * The destructor.
		 */		
		~VisualAnimation();

		/**
		 * Copy constructor.
		 * @param other Reference to another VisualAnimation.
		 */
		VisualAnimation(const VisualAnimation& other);

		/**
		 * Assignment operator.
		 * @param other Reference to another VisualAnimation.
		 */
		VisualAnimation& operator=(const VisualAnimation& other);

		/**
		 * Copies the current VisualAnimation and returns a pointer to a new VisualAnimation.
		 */
		virtual VisualAnimationComponent* clone(void) const;

		/**
		 * Sets the callback function that is repeatedly called in animation's duration time.
		 * @param theCallback Pointer to c-style function (static class function).
		 * @param someUserData Additional data (e.g. pointer to instance variable of initialized class).
		 */
		void setAnimateCallbackFunctionPtr(VisualAnimationAnimateCallback theCallback, void* someUserData = NULL);

		/**
		 * Sets the identifier of the parent collection (the collection which the current animation is part of).
		 * @param aCollectionIdentifier The identifier of the parent collection.
		 */
		virtual void setIdentifierOfParentCollection(const VisualItemIdentifier& aCollectionIdentifier);

		/**
		 * 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.
		 */
		virtual void handleOneCollectionItemAnimationDied(void);

		/**
		 * Returns the VisualAnimation if the VisualItemIdentifier matches.
		 * @param anAnimationIdentifier The identifier of the animation.
		 * @return The VisualAnimation with the specified VisualItemIdentifier.
		 * @remarks Return value can be NULL if no VisualAnimation with the specified VisualItemIdentifier is found.
		 */
		virtual VisualAnimationComponent* getVisualAnimation(const VisualItemIdentifier& anAnimationIdentifier);

		/**
		 * Executes the callback function to animate a property.
		 */
		virtual void animate(void);

		/**
		 * Starts the Animation.
		 * @remarks In case the start is delayed, the animation is only running after the delaying milliseconds did have passed.
		 */
		virtual void start(void);

		/**
		 * Stops the Animation.
		 */
		virtual void stop(void);

		/**
		 * Sets the duration of the animation.
		 * @param numberOfMilliseconds The number of milliseconds the animation spans.
		 */
		void setDurationInMilliseconds(uint32 numberOfMilliseconds);

		/**
		 * Returns the duration of the animation.
		 * @return The duration of the animation.
		 */
		uint32 getDurationInMilliseconds(void) const;

		/**
		 * Sets the current value of the animation.
		 * @param 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 setCurrentValue(double aCurrentValue);
		
		/**
		 * Returns the current value of the animation.
		 * @return The current value of the animation.
		 */
		double getCurrentValue(void) const;
		
		/**
		 * Sets the start value of the animation.
		 * @param aStartValue The start value of the animation.
		 * @param 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 setStartValue(double aStartValue, bool startAnimationWithCurrentPropertyValue = false);

		/**
		 * Sets the start value of the animation.
		 * @param aPosition The start value of the animation as position.
		 * @param 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 setStartValue(const VisualStagePosition& aPosition, bool startAnimationWithCurrentPropertyValue = false);

		/**
		 * Returns the start value of the animation.
		 * @return The start value of the animation.
		 */
		double getStartValue(void) const;

		/**
		 * Sets the stop value of the animation.
		 * @param aStopValue The stop value of the animation.
		 * @remarks Default is 1.0.
		 */
		void setStopValue(double aStopValue);

		/**
		 * Sets the stop value of the animation.
		 * @param aPosition The stop value of the animation as position.
		 */
		void setStopValue(const VisualStagePosition& aPosition);

		/**
		 * Returns the stop value of the animation.
		 * @return The stop value of the animation.
		 */
		double getStopValue(void) const;

		/**
		 * Sets the loop mode of the animation.
		 * @param aLoopMode The requested loop mode.
		 * @param requestedNumberOfLoops The number of times the animation should be repeated (default = 1).
		 */
		void setLoopMode(LoopMode aLoopMode, sint32 requestedNumberOfLoops = 1);

		/**
		 * Sets the type of interpolation.
		 * @param anInterpolationType The requested type of interpolation.
		 */	
		void setInterpolationType(InterpolationType anInterpolationType);

		/**
		 * Returns the number of milliseconds until the animation is supposed to actually start.
		 * @return 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.
		 */
		uint32 getStartDelayInMilliseconds(void) const;

		/**
		 * Sets the number of milliseconds until the animation actually starts.
		 * @param aStartDelayInMilliseconds The number of milliseconds until the animation actually starts.
		 * @remarks The delay counts from the moment start() is called.
		 */
		void setStartDelayInMilliseconds(uint32 aStartDelayInMilliseconds);

		/**
		 * Sets the callback function that is repeatedly called back during animation component's duration time.
		 * @param theCallback Pointer to c-style function (static class function).
		 * @param userData Additional data (e.g. pointer to instance variable of initialized class).
		 */
		virtual void setCallbackToPerformAnyAdditionalAction(VisualAnimationPerformAnyAdditionalActionCallback theCallback, void* userData = NULL);

		/**
		 * Sets the callback function that is called right before the death of the animation component.
		 * @param theCallback Pointer to c-style function (static class function).
		 * @param userData Additional data (e.g. pointer to instance variable of initialized class).
		 */
		virtual void setCallbackToNotifyBeforeDeath(VisualAnimationWillDieCallback theCallback, void* userData = NULL);

		/**
		 * Calls any callback functions right before the death of the animation component.
		 */
		virtual void notifyBeforeDeath(void);

		/**
		 * Returns the animated property of the animation.
		 * @return The animated property of the animation.
		 */
		virtual AnimatedProperty getAnimatedProperty(void) const;

		/**
		 * Returns the moving direction (running direction) of the animation.
		 * @return The currently moving direction (running direction) of the animation.
		 */	
		MovingDirection getMovingDirection(void) const;

		/**
		 * Returns the current repeat mode of the animation.
		 * @return The current repeat mode of the animation.
		 */
		RepeatMode getRepeatMode(void) const;

		/**
		 * 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.
		 */
		virtual void update(void);

		/**
		 * Answers the question whether the animation is (still) running.
		 * @return True if the animation is (still) running. False otherwise.
		 */
		virtual bool isRunning(void) const;

		/**
		 * Answers the question whether the animation ended and is ready to be destroyed.
		 * @return 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.
		 */
		virtual bool isReadyToDie(void) const;

		/**
		 * Sets the debug mode.
		 * @param requestedDebugMode The debug mode. True turns debug mode on, false turns it off.
		 */
		void setDebugMode(bool requestedDebugMode);
		
		/**
		 * Prepares the animation before it is added to an asset.
		 * @param visualAsset The asset the animation is supposed to be added to.
		 */
		virtual void preparePriorToAddingToAsset(VisualAsset& visualAsset);

		/**
		 * Returns the asset the animation has been added to.
		 * @return The asset the animation has been added to.
		 */
		virtual const VisualAsset* const getEnclosingAsset(void) const;

		/**
		 * Sets the speed of the animation.
		 * @param animationSpeed The speed of the animation (as it has been calculated by static function VisualAnimation::calcSpeed());
		 */
		void setSpeed(AnimationSpeed animationSpeed);

		/**
		 * Returns the current speed of the animation.
		 * @return The current speed of the animation.
		 */
		AnimationSpeed getSpeed(void) const;

		/**
		 * Calculates the speed of an animation if it would use the passed start and stop values with the provided duration time.
		 * @param aStartValue A start value of an animation.
		 * @param aStopValue A stop value of an animation.
		 * @param aDurationInMilliseconds A duration of an animation measured in milliseconds.
		 * @return The speed of an animation.
		 */
		static AnimationSpeed calcSpeed(double aStartValue, double aStopValue, uint32 aDurationInMilliseconds);

		/**
		 * Calculates the speed of an animation of a certain distance and duration.
		 * @param aDistance The distance of the values of the animation.
		 * @param aDurationInMilliseconds Duration of the animation measured in milliseconds.
		 * @return The speed of the animation.
		 */
		static AnimationSpeed calcSpeed(double aDistance, uint32 aDurationInMilliseconds);

		/**
		 * Calculates the time an animation will take to travel a certain distance with a certain constant speed.
		 * @param aDistance The distance of the values of the animation.
		 * @param aSpeed Speed of the animation.
		 * @return The duration of the animation measured in milliseconds.
		 */
		static uint32 calcDurationInMilliseconds(double aDistance, AnimationSpeed aSpeed);

	private:
	
		/**
		 * Copy method for assignment operator and copy constructor.
		 * @param other Another VisualAnimation.
		 */
		void copy(const VisualAnimation& other);
		
		/** The property of the asset that is affected by the animation. */
		AnimatedProperty animatedProperty;

		/**
		 * Internal method called when the duration time of the timeline did exceed.
		 */
		void durationIsExceeded(void);

		/**
		 * Internal method to adjust the current timeline value to the current value of the animated property.
		 * @param visualAsset The asset where a property is animated.
		 * @param anAnimatedProperty The animated property.
		 */
		void setCurrentTimelineValueToCurrentPropertyValue(const VisualAsset& visualAsset, AnimatedProperty anAnimatedProperty);

		/**
		 * Decrement the number of remaining repeats.
		 */
		void decrementRemainingNumberOfRepeats(void);

		/** The pointer to the timeline of the animation. */
		VisualTimeline* theTimeline;

		/** The remaining number of times the animation should pass. */
		sint32 remainingNumberOfRepeats;
		
		/** The callback function that is called during the animation. */
		VisualAnimationAnimateCallback animateCallback;

		/** Internally stored pointer to provided user data (e.g. pointer to instance variable of initialized class). */
		void* animationUserData;

		/** The optional callback function that is called during the animation. */
		VisualAnimationPerformAnyAdditionalActionCallback performAnyAdditionalActionCallback;
		
		/** The optional user data that is passed to callback function that is called during the animation. */
		void* performAnyAdditionalActionCallbackUserData;

		/** The number of milliseconds until the animation will be actually used by VisualStageControl. */
		uint32 startDelayInMilliseconds;
		
		bool debugMode; /**< True if in debug mode, false otherwise. */
		
		static const uint32 maxNumberOfDebugHistoryEntries; /**< The maximum number of data entries stored in history for debug and monitoring purposes. */
		
		uint32 currDebugHistoryEntry; /**< The current entry of the debug history. */
		
		/** Data entries stored for debug and monitoring purposes. */
		typedef std::vector<double> DebugHistory;
		
		/** The DebugHistoryIterator is an iterator of the DebugHistory. */
		typedef DebugHistory::iterator DebugHistoryIterator;
		
		/** The data entries stored for debug and monitoring purposes. */
		DebugHistory debugHistory;
		
		/** True if the maximum number of data entries of debugHistory are initialized, false otherwise. */
		bool debugHistoryIsInitialized;
		
		/** The possible status values of the VisualAnimation. */
		typedef enum {
			kIsNotRunning = 0, /**< Animation is not running. */
			kIsRunning, /**< Animation is running. */
			kIsReadyToDie /**< Animation ended and will be destroyed next. */
		} VisualAnimationStatus;
		
		/** The status of the VisualAnimation. */
		VisualAnimationStatus status;

		/** The optional identifier of the collection of the animation (the cluster resp. sequence the current animation is part of). */
		VisualItemIdentifier* collectionIdentifier;

		/** The asset the animation has been added to. */
		const VisualAsset* enclosingAsset;
		
		/** The speed of the animation (the speed is driving value in case no start value has been set). */
		AnimationSpeed speed;
		
		/** True if the animation is supposed to start with the current value of the animated property. Default is true. By calling setStartValue() it is usually set to false. */
		bool doStartAnimationWithCurrentPropertyValue;
		
		/** The start value of the animation as it has been set by setStartValue(). */
		double startValue;
		
		/** The start value of the animation as it has been set by setStartValue(), with data type VisualStagePosition. */
		VisualStagePosition startValueVisualStagePosition;

		/** The stop value of the animation as it has been set by setStopValue(). */
		double stopValue;

		/** The stop value of the animation as it has been set by setStopValue(), with data type VisualStagePosition. */
		VisualStagePosition stopValueVisualStagePosition;

		/**
		 * Whether the animation is bound to speed or duration.
		 */
		typedef enum {
			kDurationBound, /**< The speed of the animation is determined by setting the duration time. */
			kSpeedBound /**< The duration of the animation is dependent on the speed. */
		} DurationSpeedConstraint;
		
		/** The constraint of the animation (whether bound to speed or duration). */
		DurationSpeedConstraint durationSpeedConstraint;

		/** The optional callback function that is called right before the death of the animation cluster. */
		VisualAnimationWillDieCallback willDieCallback;

		/** The optional user data that is passed to callback function that is called right before the death of the animation cluster. */
		void* willDieCallbackUserData;
		
	};

}

#endif /* VisualAnimation_h */