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

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

		Author:	Pierre-Sylvain
		Date:	7/7/2006

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

#ifndef __I3DShAttributesSet__
#define __I3DShAttributesSet__

#if CP_PRAGMA_ONCE
#pragma once
#endif

#include "ComTypes.h"


//****** Globally Unique Ids *************************************************

MCDEFINE_GUID_H(IID_I3DShAttributesSet);
MCDEFINE_GUID_H(CLSID_AttributeSetNode);


struct I3DShAttributesSetControler;
struct I3DExAttributesSetControler;
struct I3DShParamInfo;
struct I3DShTimeBasedData;
struct I3DShScene;
template<class T> class TMCCountedPtrArray;


/// \addtogroup ShellInterface
/// \{

struct I3DShAttributesIterator : public IMCUnknown
{
	virtual void				MCCOMAPI Reset() = 0;
	virtual I3DShParamInfo*		MCCOMAPI GetNextAttribute() = 0;
	virtual int32				MCCOMAPI GetAttributesCount() = 0;
};


// ****************************************************************************
//								I3DShAttributesSet
// 
/// <P>The attributes set is a holder for a set of attributes. Those attributes
/// are controled by a list of controlers. There is actualy two lists of controllers.
/// The first one is a list of global controllers that are going to modify the
/// parameter values depending on some external data (like the non linear
/// animation controller that uses data stored into clips). Those controller are
/// called one after each other in order when reading or writing a parameter. The
/// second list is a list of local controllers. Those controllers when computing
/// the value of one of the parameter, use only other parameters of the scene (for
/// instance the linked parameter controller is a local controller as it provide
/// a way to link two parameter of the scene). The local controllers are called
/// multiple times. They are called between two global controllers and should be
/// able to apply the modification depending on the parameter modifications done
/// by the current global controller.</P>
///
/// \see I3DShAttributesSetControler
/// \see I3DExAttributesSetControler
///
struct I3DShAttributesSet : public IMCUnknown
{
	// ****************************************************************************
	//								GetScene
	// 
	/// Returns a pointer to the scene that contains this attributes set.
	/// 
	virtual I3DShScene*			MCCOMAPI GetScene			() = 0;

	// ****************************************************************************
	//								InsertControler
	// 
	/// Inserts a new attributes set controler.
	///
	/// \param controler		The controler to add.
	/// \param index			Where to insert the controler in the list (could be the local or
	///							global controller list depending on the controller type).
	/// 
	virtual MCCOMErr			MCCOMAPI InsertControler(I3DShAttributesSetControler* controler, uint32 index=kUnusedIndex) = 0;

	// ****************************************************************************
	//								InsertControlerByID
	// 
	/// Creates and inserts a new attributes set controler.
	///
	/// \param kindId			The id of the controler.
	/// \param index			Where to insert the controler in the list (could be the local or
	///							global controller list depending on the controller type).
	/// 
	virtual MCCOMErr			MCCOMAPI InsertControlerByID(int32 kindId, uint32 index=kUnusedIndex) = 0;

	// ****************************************************************************
	//								RemoveControler
	// 
	/// Removes an attributes set controler.
	///
	/// \param localController	Which list (global or local controllers).
	/// \param index			Index of the controler to remove.
	/// 
	virtual MCCOMErr			MCCOMAPI RemoveControler	(boolean localController, uint32 index) = 0;

	// ****************************************************************************
	//								GetControlersCount
	// 
	/// Returns the number of controlers.
	///
	/// \param localController	Which list (global or local controllers).
	///
	virtual uint32				MCCOMAPI GetControlersCount	(boolean localController) = 0;

	// ****************************************************************************
	//								GetControlerByIndex
	// 
	/// Returns a controler.
	///
	/// \param localController	Which list (global or local controllers).
	/// \param index			Index of the controler.
	///
	virtual I3DShAttributesSetControler* MCCOMAPI GetControlerByIndex(boolean localController, uint32 index) = 0;

	// ****************************************************************************
	//								GetControlerByID
	// 
	/// Returns a controler.
	///
	/// \param localController	Which list (global or local controllers).
	/// \param id				ID of the controler.
	///
	virtual I3DShAttributesSetControler* MCCOMAPI GetControllerByID(uint32 id) = 0;

// ****************************************************************************
	//								GetControlerIndex
	// 
	/// Gets the index of a controller in the list of controlers according to its ID.
	///
	/// \param id			The id of the controller to look for.
	///	
	virtual uint32				MCCOMAPI GetControlerIndex(uint32 id) = 0;

	// ****************************************************************************
	//								SetControler
	// 
	/// Replace a controller in the list of controlers.
	///
	/// \param index			The index of the controler to be set in the controller's list.
	/// \param controler		The controler to be set.
	///	
	virtual MCCOMErr			MCCOMAPI SetControler(I3DShAttributesSetControler* controler, uint32 index) = 0;
	
	// ****************************************************************************
	//								SetControlers
	// 
	/// Set the list of controlers.
	///
	/// \param localController	Which list (global or local controllers).
	/// \param controlers		The list of controlers.
	/// \param cloneMode		The clone mode (see ECloneMode).
	///
	virtual MCCOMErr			MCCOMAPI SetControlers		(boolean localController, const TMCCountedPtrArray<I3DShAttributesSetControler>* controlers, ECloneMode cloneMode) = 0;

	// ****************************************************************************
	//								ValidateAttributesMapping
	// 
	/// Force a validation of the attributes mapping. You usually do not need to call
	/// this function directly as it will be done for you when you call any other
	/// functions of the attributes set.
	///
	virtual void				MCCOMAPI ValidateAttributesMapping	() = 0;


	/// Makes sure that ValidateAttributesMapping does something...
	virtual void				MCCOMAPI InvalidateAttributesMapping() = 0;

	// ****************************************************************************
	//								GetAttributeCount
	// 
	/// Returns the number of attributes.
	/// NOTE: this function is SMP safe.
	///
	virtual int32				MCCOMAPI GetAttributeCount	() = 0;

	// ****************************************************************************
	//								GetAttribute
	// 
	/// Get an attribute as a I3DShParamInfo.
	/// NOTE: this function is SMP safe.
	///
	/// \param index			The index of the attribute.
	///
	/// \see I3DShParamInfo
	///
	virtual I3DShParamInfo*		MCCOMAPI GetAttribute		(int32 index) = 0;

	// ****************************************************************************
	//								GetAttributeIndex
	// 
	/// Get an attribute as a I3DShTimeBasedData and the index of the parameter.
	/// NOTE: this function is SMP safe.
	///
	/// \param index			The index of the attribute.
	/// \param paramIndex		Will be set with the index of the parameter in the
	/// I3DShTimeBasedData that is returned.
	///
	virtual I3DShTimeBasedData*	MCCOMAPI GetAttributeIndex	(int32 index, int32& paramIndex) = 0;

	// ****************************************************************************
	//								FindAttributeIndex
	// 
	/// Returns the attribute's index for I3DShParamInfo. If the parameter is
	/// not part of this attributes set, it returns -1.
	/// NOTE: this function is SMP safe.
	///
	/// \param paramInfo			The parameter.
	///
	virtual int32				MCCOMAPI FindAttributeIndex	(I3DShParamInfo* paramInfo) const = 0;

	// ****************************************************************************
	//								Invalidate
	// 
	/// Invalidates all the parameters controled by this attributes set.
	///
	virtual	void				MCCOMAPI Invalidate			() = 0;

	// ****************************************************************************
	//								InvalidateTimeLines
	// 
	/// Invalidates all merged time lines controled by this attributes set.
	///
	virtual	void				MCCOMAPI InvalidateTimeLines() = 0;

	// ****************************************************************************
	//								CreateTimeLineUniqueId
	// 
	/// Creates a unique id that can be used as a unique id for additional time line
	/// on parameters controled by this attributes set.
	///
	virtual uint32				MCCOMAPI CreateTimeLineUniqueId() = 0;

	// ****************************************************************************
	//								IsTimeLineUniqueIdRegistered
	// 
	/// Checks if a given unique id is registered in the attributes set.
	//
	/// \param id		The id to check.
	///
	virtual boolean				MCCOMAPI IsTimeLineUniqueIdRegistered(uint32 id) = 0;

	// ****************************************************************************
	//								ReleaseTimeLineUniqueId
	// 
	/// Releases an additional time line unique id.
	//
	/// \param id		The id to release.
	///
	virtual void				MCCOMAPI ReleaseTimeLineUniqueId(uint32 id) = 0;

	// ****************************************************************************
	//								GetRegisteredUniqueIds
	// 
	/// Returns the list of registered unique ids.
	/// NOTE: this function should not be used
	//
	virtual const TMCArray<uint32>& MCCOMAPI GetRegisteredUniqueIds() = 0;

	// ****************************************************************************
	//								SetRegisteredUniqueIds
	// 
	/// Sets the list of registered unique ids.
	/// NOTE: this function should not be used
	//
	virtual void				MCCOMAPI SetRegisteredUniqueIds(const TMCArray<uint32>& ids) = 0;

	// ****************************************************************************
	//								CreateAttributesIterator
	// 
	/// Creates an object that is able to iterate through all attributes that are
	/// controlled by this attributes set starting from a I3DShTreeElement. It could
	/// include parameters of sub trees of the given tree element, master objects
	/// of instances... Note that this iterator will work even of the tree is not
	/// part of the attributes set. In this case, the iterator will iterate through
	/// the parameters that would be controlled if the tree was part of it.
	//
	/// \param tree			The tree.
	/// \param outIter		Created iterator.
	/// \param removing		If true, the iterator will iterate through the parameter that
	///						will be removed if the tree is removed from the attributes set.
	///
	virtual void				MCCOMAPI CreateAttributesIterator(I3DShTreeElement* tree, I3DShAttributesIterator** outIter, boolean removing) const = 0;

	// ****************************************************************************
	//								BeginChange
	// 
	/// This function can be used for optimizing when doing some major changes in
	/// the time based and param infos. It will avoid multiple validation of the
	/// attributes. You MUST call EndChange() after doing all the modifications.
	///
	virtual void				MCCOMAPI BeginChange() = 0;

	// ****************************************************************************
	//								EndChange
	// 
	/// This function can be used for optimizing when doing some major changes in
	/// the time based and param infos. It must be called after a BeginChange().
	///
	virtual void				MCCOMAPI EndChange() = 0;

	// ****************************************************************************
	//								SetEnable
	// 
	/// Enable or disable the attributes set.
	///
	virtual void				MCCOMAPI SetEnable(boolean enable) = 0;


	/// Creates the conforming controler
	/// if kindId is 0, sets it to NULL.
	virtual MCCOMErr			MCCOMAPI SetConformingControler(int32 kindId) = 0;

	///Gets the conforming controler
	virtual I3DShAttributesSetControler* MCCOMAPI GetConformingController() const = 0;

	///Sets the conforming controler
	virtual void				MCCOMAPI SetConformingControler(I3DShAttributesSetControler* controler) = 0;


	///Can be used by a controler to notify other controlers of a param invalidation
	/// \param internalParamIndex	the index of the param in the attribute set.
	/// \param notificationSource	the controler that calls the notification (to avoid  loops)
	virtual void				MCCOMAPI ParamInvalidated(	int32	internalParamIndex, 
															I3DExAttributesSetControler* notificationSource) = 0;

	///Can be used by a controler to notify other controlers of a param modification
	/// \param internalParamIndex	the index of the param in the attribute set.
	/// \param notificationSource	the controler that calls the notification (to avoid  loops)
	virtual void				MCCOMAPI ParamModified	(	int32	internalParamIndex, 
															I3DExAttributesSetControler* notificationSource) = 0;
	

	virtual void			MCCOMAPI SetControleShaders(boolean enable) = 0;
	virtual boolean			MCCOMAPI GetControleShaders() const = 0;

	// Reserved for internal use only.
	virtual void			MCCOMAPI AddTemporaryController(I3DShAttributesSetControler* controler) = 0;
	virtual void			MCCOMAPI RemoveTemporaryController(I3DShAttributesSetControler* controler) = 0;

	virtual void			MCCOMAPI SetControleRootAnimationMethod(boolean enable) = 0;
	virtual boolean			MCCOMAPI GetControleRootAnimationMethod() const = 0;
};


/// \}

#endif
