#ifndef __I3DSHANIMATIONMETHOD__
#define __I3DSHANIMATIONMETHOD__
/****************************************************************************************

		I3dShAnimationMethod.h

		Copyright: (c) 2001 Eovia Corp. All rights reserved.

		I3DShAnimationMethod definition

		Author:	Joshua
		Date:	7/8/98

		Revision History

		when		who			what & why
		==========	==========	======================================================
		09/30/99	Mathieu		GetInitialTransform()
		6/10/99		Ian			Array API changes.
		1/4/99		Joshua		Added API members

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

#if CP_PRAGMA_ONCE
#pragma once
#endif

#include "I3DExAnimationMethod.h"

class  TTreeTransform;
struct I3DShTreeElement;
template<class T> class TMCArray;

MCDEFINE_GUID_SAFELIB(IID_I3DShAnimationMethod, 0x44262e80, 0x2813, 0x11d2, 0xab, 0x4c, 0x0, 0x60, 0x8, 0x15, 0xad, 0x45);

/// \addtogroup ShellInterface
/// \{

/// An Animation Method defines the trajectory of an object. For instance,
/// an object can be animation by interpolating between positions (key frames)
/// or using a physical simulation...
///
/// <P>There are two interfaces to access a component: The shell interface (ISh. or I3DSh.) and
/// the external interface (IEx. or I3DEx.) . You can get one from the other using QueryInterface.</P>
///
/// <P>Whenever it is possible you should use the Shell interface to access the component
/// because the Shell will make sure that the parameter map of the external component is valid.
/// This is especially important if the component is animated. For more information on components
/// see the Overview of the SDK.</P>
///
/// \see I3DExAnimationMethod
///
struct I3DShAnimationMethod : public IMCUnknown
{
	// ****************************************************************************
	//								SetTree
	// 
	/// Sets the Tree Element whose position is controled by this animation method.
	///
	/// \param tree The tree that is controlled by this animation method.
	///
	virtual MCCOMErr MCCOMAPI SetTree(I3DShTreeElement* tree)=0;
	
	// ****************************************************************************
	//								GetTransform
	// 
	/// Returns the current transform of the object.
	///
	/// \param transform  A reference to the transform where the result should be stored.
	///
	virtual boolean  MCCOMAPI GetTransform(TTreeTransform& transform)=0;
	
	// ****************************************************************************
	//								GetTransform
	// 
	/// Evaluates the transform of the object at the given time.
	///
	/// \param time			The time where you want to evaluate the tree transform.
	/// \param transform	A reference to the transform where the result should be stored.
	///
	virtual boolean  MCCOMAPI GetTransform(MicroTick time, TTreeTransform& transform)=0;

	// ****************************************************************************
	//								GetInitialTransform
	// 
	/// Returns the initial transform of the object (transform at time 0).
	/// 
	/// \param transform  A reference to the transform where the result should be stored.
	/// 
	virtual boolean  MCCOMAPI GetInitialTransform(TTreeTransform& transform)=0;
	
	// ****************************************************************************
	//								SetTransform
	// 
	/// Sets transform of the object at the current time.
	///
	/// \param transform The transform of the object.
	///
	virtual MCCOMErr MCCOMAPI SetTransform(const TTreeTransform& transform)=0;

	// ****************************************************************************
	//								TransformIsLocal
	// 
	///	Returns true if the animation method defines the local transform of the
	/// object (meaning that the transform should be multiplied by the parent global
	/// transform to obtain the global transform of the object).
	///
	/// <P>By default transforms are local but it can be useful to have an object hierarchy
	/// in which the last object's position is defined in global coordinates (eg motion path)</P>
	///
	///	\return true if the transform is local
	///
	virtual boolean  MCCOMAPI TransformIsLocal()=0;

	// ****************************************************************************
	//								OffsetAnimation
	// 
	/// Offset the transform of the whole animation
	/// 
	/// \param offset  the offset to add
	/// 
	virtual boolean  MCCOMAPI OffsetAnimation(const TTreeTransform& offset)=0;

	// ****************************************************************************
	//								GetAnimationKeyTimes
	// 
	/// Returns a set of key times that approximates the trajectory of the object with
	/// a given accuracy. This is used when converting an animation method to key frames.
	///
	/// <P>Note that by setting outAutoCurveAnalysis or outAutoGetKeyFrames to true, you
	/// can tell the Shell to use a default implementation to evaluate the keyframes so that
	/// you do not have to provide an implementation of this method</P>
	///
	/// \param inAccuracy The accuray of the conversion (0 is the lowest accuracy, 1 means 100%)
	/// \param outKeyTimes The returned sampling times.
	/// \param outAutoGetKeyFrames Returns true if the keyframes of the animation method should be used instead.
	/// \param outAutoCurveAnalysis Retursn true if a default curve analysis method should be used instead.
	/// 
	virtual MCCOMErr MCCOMAPI GetAnimationKeyTimes(real inAccuracy, TMCArray<MicroTick>& outKeyTimes, boolean& outAutoGetKeyFrames, boolean& outAutoCurveAnalysis)=0;

	// ****************************************************************************
	//								NeedConvert
	// 
	/// Returns true if needs to force a convertion.
	///
	virtual boolean	 MCCOMAPI NeedConvert() = 0;

	// ****************************************************************************
	//								BeginConvert
	// 
	/// Starts the conversion from one animation method to another.
	///
	/// <P>Note that this method is only called if the GetXTranslationAnimationTrack
	/// are not implemented.</P>
	///
	/// \param source The source animation method.
	///
	virtual MCCOMErr MCCOMAPI BeginConvert			(I3DShAnimationMethod * source)=0;
	
	// ****************************************************************************
	//								Convert
	// 
	/// Converts one position (transform) at the current time from one animation
	/// method to another. This method is called for each of the times returned by
	/// GetAnimationKeyTimes().
	///
	/// \param source The source animation method.
	/// \param transform The transform at the current time from the source animation method.
	///
	virtual MCCOMErr MCCOMAPI Convert				(I3DShAnimationMethod * source, const TTreeTransform& transform)=0;
	
	// ****************************************************************************
	//								EndConvert
	// 
	/// Called at the end of the conversion from one animation method to another. See
	/// BeginConvert() and Convert() for details.
	///
	virtual MCCOMErr MCCOMAPI EndConvert			(I3DShAnimationMethod * source)=0;

	// ****************************************************************************
	//								GetXTranslationAnimationTrack
	//
	/// Returns the time line corresponding to the animation of the X parameter of
	/// position. This is used to make exact conversions between animation methods when
	/// it is possible. When it is not implemented then the animation method is sampled.
	/// (See GetAnimationKeyTimes() and BeginConvert())
	///
	/// \param animationTrack A pointer to the time line that is returned.
	///
	virtual MCCOMErr MCCOMAPI GetXTranslationAnimationTrack		(I3DShParamTimeLine ** animationTrack)=0;
	
	// ****************************************************************************
	//								GetYTranslationAnimationTrack
	//
	/// Returns the time line corresponding to the animation of the Y parameter of
	/// position. This is used to make exact conversions between animation methods when
	/// it is possible. When it is not implemented then the animation method is sampled.
	/// (See GetAnimationKeyTimes() and BeginConvert())
	///
	/// \param animationTrack A pointer to the time line that is returned.
	///
	virtual MCCOMErr MCCOMAPI GetYTranslationAnimationTrack		(I3DShParamTimeLine ** animationTrack)=0;
	
	// ****************************************************************************
	//								GetZTranslationAnimationTrack
	//
	/// Returns the time line corresponding to the animation of the Z parameter of
	/// position. This is used to make exact conversions between animation methods when
	/// it is possible. When it is not implemented then the animation method is sampled.
	/// (See GetAnimationKeyTimes() and BeginConvert())
	///
	/// \param animationTrack A pointer to the time line that is returned.
	///
	virtual MCCOMErr MCCOMAPI GetZTranslationAnimationTrack		(I3DShParamTimeLine ** animationTrack)=0;
	
	// ****************************************************************************
	//								GetHotPointAnimationTrack
	//
	/// Returns the time line corresponding to the animation of the hot point.
	/// This is used to make exact conversions between animation methods when
	/// it is possible. When it is not implemented then the animation method is sampled.
	/// (See GetAnimationKeyTimes() and BeginConvert())
	///
	/// \param animationTrack A pointer to the time line that is returned.
	///
	virtual MCCOMErr MCCOMAPI GetHotPointAnimationTrack			(I3DShParamTimeLine ** animationTrack)=0;
	
	// ****************************************************************************
	//								GetUniformScalingAnimationTrack
	//
	/// Returns the time line corresponding to the animation of the uniform scaling.
	/// This is used to make exact conversions between animation methods when
	/// it is possible. When it is not implemented then the animation method is sampled.
	/// (See GetAnimationKeyTimes() and BeginConvert())
	///
	/// \param animationTrack A pointer to the time line that is returned.
	///
	virtual MCCOMErr MCCOMAPI GetUniformScalingAnimationTrack	(I3DShParamTimeLine ** animationTrack)=0;
	
	// ****************************************************************************
	//								GetRotationAnimationTrack
	//
	/// Returns the time line corresponding to the animation of the rotation.
	/// This is used to make exact conversions between animation methods when
	/// it is possible. When it is not implemented then the animation method is sampled.
	/// (See GetAnimationKeyTimes() and BeginConvert())
	///
	/// \param animationTrack A pointer to the time line that is returned.
	///
	virtual MCCOMErr MCCOMAPI GetRotationAnimationTrack			(I3DShParamTimeLine ** animationTrack)=0;
	
	// ****************************************************************************
	//								GetEulerRotationAnimationTrack
	//
	/// Returns the time line corresponding to the animation of the rotation (as Euler angles).
	/// This is used to make exact conversions between animation methods when
	/// it is possible. When it is not implemented then the animation method is sampled.
	/// (See GetAnimationKeyTimes() and BeginConvert())
	///
	/// \param animationTrack A pointer to the time line that is returned.
	///
	virtual MCCOMErr MCCOMAPI GetRotationAnimationTrack			(I3DShParamTimeLine ** xAnimationTrack,
																 I3DShParamTimeLine ** yAnimationTrack,
																 I3DShParamTimeLine ** zAnimationTrack,
																 I3DShParamTimeLine ** mirrorAnimationTrack,
																 EEulerAnglesOrder&    anglesOrder)=0;

	// ****************************************************************************
	//								GetXScalingAnimationTrack
	//
	/// Returns the time line corresponding to the animation of the X parameter of
	/// the scaling. This is used to make exact conversions between animation methods when
	/// it is possible. When it is not implemented then the animation method is sampled.
	/// (See GetAnimationKeyTimes() and BeginConvert())
	///
	/// \param animationTrack A pointer to the time line that is returned.
	///
	virtual MCCOMErr MCCOMAPI GetXScalingAnimationTrack			(I3DShParamTimeLine ** animationTrack)=0;
	
	// ****************************************************************************
	//								GetYScalingAnimationTrack
	//
	/// Returns the time line corresponding to the animation of the Y parameter of
	/// the scaling. This is used to make exact conversions between animation methods when
	/// it is possible. When it is not implemented then the animation method is sampled.
	/// (See GetAnimationKeyTimes() and BeginConvert())
	///
	/// \param animationTrack A pointer to the time line that is returned.
	///
	virtual MCCOMErr MCCOMAPI GetYScalingAnimationTrack			(I3DShParamTimeLine ** animationTrack)=0;
	
	// ****************************************************************************
	//								GetZScalingAnimationTrack
	//
	/// Returns the time line corresponding to the animation of the Z parameter of
	/// the scaling. This is used to make exact conversions between animation methods when
	/// it is possible. When it is not implemented then the animation method is sampled.
	/// (See GetAnimationKeyTimes() and BeginConvert())
	///
	/// \param animationTrack A pointer to the time line that is returned.
	///
	virtual MCCOMErr MCCOMAPI GetZScalingAnimationTrack			(I3DShParamTimeLine ** animationTrack)=0;
};

/// \}

#endif
