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

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

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

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

#ifndef __I3DShClip__
#define __I3DShClip__

#if CP_PRAGMA_ONCE
#pragma once
#endif

#include "ComTypes.h"
#include "I3DExClip.h"


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

MCDEFINE_GUID_H(IID_I3DShClip);
MCDEFINE_GUID_H(IID_I3DShMasterClip);
MCDEFINE_GUID_H(IID_I3DExMasterInstance);
MCDEFINE_GUID_H(CLSID_MasterClip);


struct I3DShAttributesSet;
struct I3DShParamInfo;
struct I3DShTimeBasedData;
struct I3DShMaster;
class  TParamHolder;
class  TMCOffscreen;


/// \addtogroup ShellInterface
/// \{

// ****************************************************************************
//								I3DShClip
// 
/// <P>There are two interfaces to access a component: The shell interface (I3DShClip) and
/// the external interface (I3DExClip). You can get one from the other using QueryInterface.</P>
///
/// \see I3DExClip
///
struct I3DShClip : public IMCUnknown
{
	// ****************************************************************************
	//								GetDuration
	// 
	/// Returns the duration of the clip in micro tick.
	/// 
	virtual MicroTick			MCCOMAPI GetDuration() = 0;

	// ****************************************************************************
	//								GetAttributesCount
	// 
	/// Returns the number of attributes stored in this clip.
	/// 
	virtual int32				MCCOMAPI GetAttributesCount() = 0;

	// ****************************************************************************
	//								GetAttribute
	// 
	/// Returns an attribute of this clip.
	///
	/// \param attributeSet		Attributes set to be used.
	/// \param index			Index of the parameter in this clip.
	/// 
	virtual I3DShParamInfo*		MCCOMAPI GetAttribute(I3DShAttributesSet* attributeSet, int32 index) = 0;

	// ****************************************************************************
	//								SetTime
	// 
	/// Set the time for this clip.
	///
	/// \param time				New time.
	/// 
	virtual void				MCCOMAPI SetTime(MicroTick time) = 0;

	// ****************************************************************************
	//								GetAttributeValue
	// 
	/// Get the value of one of the attribute.
	///
	/// \param paramIndex		The index of the attribute in the clip.
	/// \param outValue			Returned value.
	///
	virtual void				MCCOMAPI GetAttributeValue(int32 paramIndex, TParamHolder& outValue) = 0;

	// ****************************************************************************
	//								GetClipIcon
	// 
	/// Returns the image to be used as the icon for the clip.
	///
	/// \param outOffscreen		The offscreen to fill.
	///
	virtual void				MCCOMAPI GetClipIcon(TMCOffscreen* outOffscreen) = 0;
};


// ****************************************************************************
//								I3DExMasterInstance
// 
/// <P>I3DExMasterInstance represents a generic instance of a Master.</P>
///
struct I3DExMasterInstance : public IMCUnknown
{
	// ****************************************************************************
	//								MasterModified
	// 
	/// Called when the master has changed.
	/// 
	virtual void			MCCOMAPI MasterModified() = 0;

	// ****************************************************************************
	//								IsInScene
	// 
	/// Returns true if the instance is part of the given scene.
	/// 
	virtual boolean			MCCOMAPI IsInScene(I3DShScene* scene) = 0;

	// ****************************************************************************
	//								Unlink
	// 
	/// Unlink this instance. This function is called when the master is removed
	/// for instance.
	///
	/// \see I3DExMasterInstance::Relink
	/// 
	virtual void			MCCOMAPI Unlink() = 0;

	// ****************************************************************************
	//								Relink
	// 
	/// Relink this instance. This function is called when the master is readded
	/// after being removed using Unlink for instance.
	///
	/// \see I3DExMasterInstance::Unlink
	/// 
	virtual void			MCCOMAPI Relink() = 0;
};


// ****************************************************************************
//								I3DShMasterClip
// 
/// <P>I3DShMasterClip represents a Master Clip.</P>
///
/// <P>It supports multiple interfaces such as I3DShMaster and ISelectableObject</P>
///
struct I3DShMasterClip : public IMCUnknown
{
	// ****************************************************************************
	//								SetName
	// 
	/// <P>Sets the name of a master. Note that you should not call this method
	/// once the master is inserted in a scene because it does not garantee the
	/// unicity of the name.</P>
	///
	/// <P>If you want to change the name of a Master Clip once it is inserted in
	/// a scene, you should call I3DShScene::RenameMasterClip().</P>
	/// 
	/// \param name  The new name of the master.
	/// 
	virtual MCCOMErr		MCCOMAPI SetName(const TMCString& name) = 0;
	
	// ****************************************************************************
	//								GetName
	// 
	/// Returns the name of the Master Clip.
	/// 
	/// \param name  The name of the Master Clip.
	/// 
	virtual MCCOMErr		MCCOMAPI GetName(TMCString& name) = 0;

	// ****************************************************************************
	//								SetClip
	// 
	/// Sets the clip that defines this Master Clip.
	/// 
	/// \param clip       A pointer to the clip.
	/// \param cloneMode  The clone Mode (see ECloneMode).
	/// 
	virtual MCCOMErr		MCCOMAPI SetClip(I3DShClip* clip, ECloneMode cloneMode) = 0;
	
	// ****************************************************************************
	//								GetClip
	// 
	/// Returns a pointer to the clip that defines this Master Clip.
	/// 
	virtual I3DShClip*		MCCOMAPI GetClip() = 0;

	// ****************************************************************************
	//								Clone
	// 
	/// Makes a copy of the Master Clip.
	/// 
	/// \param clone      The copy that is returned.
	/// \param cloneMode  The clone Mode (see ECloneMode).
	/// 
	virtual MCCOMErr		MCCOMAPI Clone(I3DShMasterClip** clone, ECloneMode cloneMode) const = 0;

	// ****************************************************************************
	//								GetScene
	// 
	/// Returns the scene that contains this object.
	/// 
	/// \param scene  A pointer to the scene.
	/// 
	virtual I3DShScene*		MCCOMAPI GetScene() const = 0;

	// ****************************************************************************
	//								GetInstancesCount
	// 
	/// Returns the number of instances of this object. Exact same call as I3DShMaster::GetInstancesCount
	/// 
	virtual uint32			MCCOMAPI GetInstancesCount	() = 0;

	// ****************************************************************************
	//								GetInstanceArray
	// 
	/// Returns an array of all the instances that points to that class.
	/// 
	/// \param instances  An array of instances.
	/// 
	virtual void 			MCCOMAPI GetInstanceArray(TMCCountedPtrArray<I3DExMasterInstance>& instances) = 0;

	// ****************************************************************************
	//								AddInstance
	// 
	/// Adds and instance.
	/// 
	/// \param anInstance  The instance to add.
	/// 
	virtual void			MCCOMAPI AddInstance(I3DExMasterInstance* anInstance) = 0;

	// ****************************************************************************
	//								RemoveInstance
	// 
	/// Removes and instance.
	/// 
	/// \param anInstance  The instance to remove.
	/// 
	virtual void			MCCOMAPI RemoveInstance(I3DExMasterInstance* anInstance) = 0;

	// ****************************************************************************
	//								DataChanged
	// 
	/// You should call this function if you modify the I3DShClip. It will trigger
	/// the proper invalidations and post the correct message.
	/// 
	virtual void			MCCOMAPI DataChanged() = 0;

	// ****************************************************************************
	//								GetThisMaster
	// 
	/// Returns the I3DShMaster interface.
	/// 
	virtual I3DShMaster*	MCCOMAPI GetThisMaster() = 0;
};


/// \}

#endif
