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

		I3DShScene.h

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

		I3DShScene definition

		Author:	Ray Dream
		Date:	3/2/98

		Revision History

		when		who			what & why
		==========	==========	======================================================
		11/29/99	Greg		Moved JumpInOutChannel to ISceneDocument, changed GetInstancesCount
								to GetInstanceListCount (it was colliding with I3DShObject!)
		09/28/99	Mathieu		"Don't recompute" flag in SetTime
		9/06/99		Gilles		Added define of kChange_LastTimeUpdate
		4/20/99		Greg		Added GetRenderEffectsTimeBased
		3/3/99		Greg		Added ScenePropertyChangeChannel
		1/13/99		Greg		Changed MICROTICK3D to MicroTick (they're both int32s!)
								and added the notion of allocated time for the scrub bar
		11/5/98		Greg		Added TreePropertyChangeChannel
		11/5/98		Joshua		Changes for animate button
		10/30/98	Eml			Master Shaders

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

#ifndef __I3DSHSCENE__
#define __I3DSHSCENE__

#if CP_PRAGMA_ONCE
#pragma once
#endif

#include "MCCompObj.h"
#include "APITypes.h"
#include "TreeChanges.h"
#include "MCString.h"
#include "MCCountedPtr.h"
#include "ComTypes.h"
#include "Id.h"

//=====================================================
// Change Kinds for TimeChangeChannel
// (See I3DShScene::GetTimeChangeChannel()
//

#define kChange_CurrentTime		'time'
#define kChange_LastTimeUpdate	'ltim'
#define kChange_AllocatedTime	'aloc'
#define kChange_PunchInOut		'punc'
#define kChange_FPS				'fps '

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

MCDEFINE_GUID_SAFELIB(IID_I3DShScene, 0xD4E4AC00L, 0x3A02, 0x101C, 0x88, 0x5F, 0x04, 0x02, 0x1C, 0x00, 0x70, 0x02);
MCDEFINE_GUID_SAFELIB(CLSID_StandardScene, 0xce855ccc, 0x8443, 0x11d2, 0x9c, 0x44, 0x0, 0x0, 0xe8, 0xdd, 0x97, 0xd2);

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



/*****************************************************************************\
*  I3DShScene                                                                 *
*                                                                             *
*    Topmost data structure that contains all the data of a scene.            *
*                                                                             *
\*****************************************************************************/

struct I3DShObject;
struct I3DShShader;
struct I3DShMasterShader;
struct I3DShTreeElement;
struct I3DShGroup;
struct I3DShInstance;
struct I3DShLightsource;
struct I3DShCamera;
struct I3DExDataComponent;
struct I3DShBackground;
struct I3DShBackdrop;
struct I3DShAtmosphericShader;
struct I3DShAmbientLight;
struct I3DShEnvironment;
struct I3DShPostRenderer;
struct I3DShDataComponent;
struct I3DShTimeManager;
struct IChangeChannel;
struct ISceneDocument;
struct I3DRenderingModule;
struct IShComponent;
struct ITimeBased;
struct IShMasterSound;
struct I3DShSoundtrack;
struct I3DShPhysicsEngine;
struct I3DShMasterClip;
class  TMCPixelBucket;
class  TBBox2D;
template <class T> class TMCCountedPtrArray;

#undef  INTERFACE
#define INTERFACE   I3DShScene

/// \addtogroup ShellInterface
/// \{


// ****************************************************************************
//								I3DShScene
// 
/// I3DShScene represents a scene. The scene is usually associated with a
/// scene document (see GetSceneDocument()) although a scene could exist on
/// its own.
///
/// <P>The scene contains the list of the Master Objects, Shaders, Sounds as well
/// as the tree (hierarchy) of the scene that contains all the instances of those
/// objects</P>
/// 
/// <P>A scene is also a Master Group and thus implements I3DShMasterGroup as well
/// as I3DShObject.</P>
///
struct I3DShScene: public IMCUnknown
{
	// ****************************************************************************
	//								SetScene
	// 
	/// \deprecated This call is obsolete and should not be used !!
	/// 
	virtual MCCOMErr MCCOMAPI SetScene						(I3DShScene* topScene) = 0;	//call this just after the creation of a master group with the scene attached to the document.

	//-- 3D Objects list
	// ****************************************************************************
	//								Get3DObjectsCount
	// 
	/// Returns the number of Master Objects (see I3DShObject) in the scene.
	/// 
	virtual uint32   MCCOMAPI Get3DObjectsCount				() = 0;
	
	// ****************************************************************************
	//								Get3DObjectByIndex
	// 
	/// Returns a pointer to a Master Object.
	/// 
	/// \param object  A pointer to the Master Object.
	/// \param index   The index (0-based) of the object in the scene.
	/// 
	virtual MCCOMErr MCCOMAPI Get3DObjectByIndex			(I3DShObject** object, uint32 index) = 0;
	
	// ****************************************************************************
	//								Get3DObjectByName
	// 
	/// Returns a pointer to a Master Object.
	/// 
	/// \param object  A pointer to the Master Object.
	/// \param name    The name of the Master Object (Note that the names of Master Objects are unique in a scene).
	/// 
	virtual MCCOMErr MCCOMAPI Get3DObjectByName				(I3DShObject** object, const TMCString& name) = 0;
	
	// ****************************************************************************
	//								Insert3DObject
	// 
	/// Inserts a Master Object in the scene. If there is already another object
	/// with the same name, the name of this object will be changed so that it is
	/// unique.
	/// 
	/// \param object  The Master Object to insert.
	/// 
	virtual MCCOMErr MCCOMAPI Insert3DObject				(I3DShObject* object) = 0;
	
	// ****************************************************************************
	//								Rename3DObject
	// 
	/// Change the name of a Master Object and makes sure it is unique.
	/// 
	/// \param object   The object whose name should be changed.
	/// \param newName  The new name of the object.
	/// 
	virtual MCCOMErr MCCOMAPI Rename3DObject				(I3DShObject* object, TMCString& newName) = 0; // Note : newName can change (if another shader already uses this name). The shader's index in the list might change too (since the list is sorted in alphabetical order.
	
	// ****************************************************************************
	//								Remove3DObject
	// 
	/// Removes a Master Object from the scene.
	/// 
	/// \param object  A pointer to the object that should be removed.
	/// 
	virtual MCCOMErr MCCOMAPI Remove3DObject				(I3DShObject* object) = 0;
	
	// ****************************************************************************
	//								Changed3DObject
	// 
	/// Called to notify that a Master Object as been changed.
	/// 
	/// \param object  The object that has changed.
	/// 
	virtual MCCOMErr MCCOMAPI Changed3DObject				(I3DShObject* object) = 0;
	
	// ****************************************************************************
	//								Replace3DObject
	// 
	/// Replace a master object by another one.
	/// 
	/// \param oldObject  The old Master object.
	/// \param newObject  The new Master Object.
	/// 
	virtual MCCOMErr MCCOMAPI Replace3DObject				(I3DShObject* oldObject, I3DShObject* newObject) = 0;
	
	// ****************************************************************************
	//								Find3DObject
	// 
	/// Returns the index of a master object in the scene. Returns kUnusedIndex if not found
	/// 
	/// \param object  A pointer to the master object that we look for.
	/// 
	virtual uint32   MCCOMAPI Find3DObject					(I3DShObject* object) = 0; 

	// ****************************************************************************
	//								GetMasterShadersCount
	// 
	/// Returns the number of master shaders in the scene.
	/// 
	virtual uint32   MCCOMAPI GetMasterShadersCount			() = 0;
	
	// ****************************************************************************
	//								GetMasterShaderByIndex
	// 
	/// Returns a pointer to a master shader.
	/// 
	/// \param masterShader  The pointer to the shader that is returned.
	/// \param index         The index (0-based) of the shader in the scene.
	/// 
	virtual MCCOMErr MCCOMAPI GetMasterShaderByIndex		(I3DShMasterShader** masterShader, uint32 index) = 0;
	
	// ****************************************************************************
	//								GetMasterShaderByName
	// 
	/// Returns a pointer to a Master Shader.
	/// 
	/// \param masterShader  A pointer to the master shader.
	/// \param name          The name of the Master shader (Note that the names of Master shader are unique in a scene).
	/// 
	virtual MCCOMErr MCCOMAPI GetMasterShaderByName			(I3DShMasterShader** masterShader, const TMCString& name) = 0;
	
	// ****************************************************************************
	//								InsertMasterShader
	// 
	/// Inserts a master shader in the scene.
	/// 
	/// \param masterShader  A pointer to the master shader that is inserted in the scene.
	/// 
	virtual MCCOMErr MCCOMAPI InsertMasterShader			(I3DShMasterShader* masterShader) = 0;
	
	// ****************************************************************************
	//								RenameMasterShader
	// 
	/// Change the name of a master shader and makes sure it is unique. Note that
	/// the name of the master shader might be changed by this function in order
	/// to ensure that it is unique in the scene.
	/// 
	/// \param masterShader  The shader whose name should be changed.
	/// \param newName       The new name of the shader.
	/// 
	virtual MCCOMErr MCCOMAPI RenameMasterShader			(I3DShMasterShader* masterShader, TMCString& newName) = 0; // Note : newName can change (if another shader already uses this name). The shader's index in the list might change too (since the list is sorted in alphabetical order.
	
	// ****************************************************************************
	//								RemoveMasterShader
	// 
	/// Deletes a master shader from the scene.
	/// 
	/// \param masterShader  A pointer to the master shader that should be deleted
	/// from the scene.
	/// 
	virtual MCCOMErr MCCOMAPI RemoveMasterShader			(I3DShMasterShader* masterShader) = 0;		
	
	// ****************************************************************************
	//								RemoveDuplicatedAndUnusedMasterShaders
	// 
	/// Removes all Duplicated and unused master shaders.
	///
    /// \param[in] nonDeletableShaders An array of shaders that may not be deleted by this opetation.
	/// \param justRemoveDuplicatedLink  If true, this function will merge shaders that are identical but not remove shaders that are not referenced in the scene.
	/// \param lookForReferenceShaders   if false reference shaders are ignored. Note that if there are reference shaders in your scene, this would corrupt your shaders...
	/// 
	virtual MCCOMErr MCCOMAPI RemoveDuplicatedAndUnusedMasterShaders(
                                                             const TMCPtrArray<I3DShMasterShader>& nonDeletableShaders, 
															 boolean justRemoveDuplicatedLink = false, 
															 boolean lookForReferenceShaders  = true ) =0; // if justRemoveDuplicatedLink= true, will just remove link to duplicated shaders, will not removed shaders it self.		 
	
	// ****************************************************************************
	//								FindMasterShader
	// 
	/// Returns the index of a Master Shader in the scene. Returns kUnusedIndex if not found
	/// 
	/// \param masterShader  A pointer to the master shader that we look for.
	/// 
	virtual uint32   MCCOMAPI FindMasterShader				(const I3DShMasterShader* masterShader) const = 0;

	// ****************************************************************************
	//								ChangedMasterShader
	// 
	/// Called to indicate the a master shader was modified.
	/// 
	/// \param masterShader  A pointer to the master shader that was modified.
	/// 
	virtual MCCOMErr MCCOMAPI ChangedMasterShader			(I3DShMasterShader* masterShader) = 0;

	// ****************************************************************************
	//								IsEqualMasterShader
	// 
	/// Looks for an identical master shader in the scene. If one is found then a
	/// pointer is returned.
	/// 
	/// \param inOutMasterShader  The master shader that is compared to the scene. 
	///                           On exit, the shader that was found in the scene.
	/// 
	/// \return True if a shader is found.
	///
	virtual boolean  MCCOMAPI IsEqualMasterShader( TMCCountedPtr<I3DShMasterShader> &inOutMasterShader ) = 0;

	// ****************************************************************************
	//								GetDefaultMasterShader
	// 
	/// Returns the default master shader or create it if we don't have master
	/// shaders in the scene
	/// 
	/// \param masterShader  A pointer to the default master shader.
	/// 
	virtual void	 MCCOMAPI GetDefaultMasterShader(I3DShMasterShader ** masterShader)					 =0;

	// ****************************************************************************
	//								GetMasterSoundCount
	// 
	/// Returns the number of master sounds in the scene.
	/// 
	virtual uint32   MCCOMAPI GetMasterSoundCount			() = 0;
	
	// ****************************************************************************
	//								GetMasterSoundByIndex
	// 
	/// Returns a pointer to a master sounds.
	/// 
	/// \param masterSound  The pointer to the master sound.
	/// \param index        The index of the master sound in the scene.
	/// 
	virtual MCCOMErr MCCOMAPI GetMasterSoundByIndex			(IShMasterSound** masterSound, uint32 index) = 0;
	
	// ****************************************************************************
	//								GetMasterSoundByName
	// 
	/// Returns the name of a Master Sound.
	/// 
	/// \param masterSound  A pointer to a master sound.
	/// \param name         The name of the master sound.
	/// 
	virtual MCCOMErr MCCOMAPI GetMasterSoundByName			(IShMasterSound** masterSound, const TMCString& name) = 0;
	
	// ****************************************************************************
	//								InsertMasterSound
	// 
	/// Inserts a Master Sound in the scene.
	/// 
	/// \param masterSound  A pointer to the master sound to insert.
	/// 
	virtual MCCOMErr MCCOMAPI InsertMasterSound				(IShMasterSound* masterSound) = 0;
//	virtual MCCOMErr MCCOMAPI RenameMasterSound				(IShMasterSound* masterSound, TMCString& newName) = 0; // Note : newName can change (if another shader already uses this name). The shader's index in the list might change too (since the list is sorted in alphabetical order.
	
	// ****************************************************************************
	//								RemoveMasterSound
	// 
	/// Deletes a master sound from the scene.
	/// 
	/// \param masterSound  A pointer to the sound that should be removed from the scene.
	/// 
	virtual MCCOMErr MCCOMAPI RemoveMasterSound				(IShMasterSound* masterSound) = 0;		
	
	// ****************************************************************************
	//								GetSoundtrack
	// 
	/// Returns a pointer to the sound tracks.
	/// 
	virtual I3DShSoundtrack*	GetSoundtrack				() = 0;

	// ****************************************************************************
	//								GetMasterClipCount
	// 
	/// Returns the number of master clips in the scene.
	/// 
	virtual uint32   MCCOMAPI GetMasterClipCount			() = 0;
	
	// ****************************************************************************
	//								GetMasterClipByIndex
	// 
	/// Returns a pointer to a master clip.
	/// 
	/// \param masterClip  The pointer to the master clip.
	/// \param index        The index of the master clip in the scene.
	/// 
	virtual MCCOMErr MCCOMAPI GetMasterClipByIndex			(I3DShMasterClip** masterClip, uint32 index) = 0;
	
	// ****************************************************************************
	//								GetMasterClipByName
	// 
	/// Returns a pointer to a master clip.
	/// 
	/// \param masterClip  A pointer to a master clip.
	/// \param name         The name of the master clip.
	/// 
	virtual MCCOMErr MCCOMAPI GetMasterClipByName			(I3DShMasterClip** masterClip, const TMCString& name) = 0;
	
	// ****************************************************************************
	//								InsertMasterClip
	// 
	/// Inserts a Master Clip in the scene.
	/// 
	/// \param masterClip  A pointer to the master clip to insert.
	/// 
	virtual MCCOMErr MCCOMAPI InsertMasterClip				(I3DShMasterClip* masterClip) = 0;

	// ****************************************************************************
	//								RenameMasterClip
	// 
	/// Change the name of a master clip and makes sure it is unique. Note that
	/// the name of the master clip might be changed by this function in order
	/// to ensure that it is unique in the scene.
	/// 
	/// \param masterClip	 The shader whose name should be changed.
	/// \param newName       The new name of the shader.
	/// 
	virtual MCCOMErr MCCOMAPI RenameMasterClip				(I3DShMasterClip* masterClip, TMCString& newName) = 0;
	
	// ****************************************************************************
	//								RemoveMasterClip
	// 
	/// Deletes a master clip from the scene.
	/// 
	/// \param masterClip  A pointer to the clip that should be removed from the scene.
	/// 
	virtual MCCOMErr MCCOMAPI RemoveMasterClip				(I3DShMasterClip* masterClip) = 0;

	// ****************************************************************************
	//								GetTreeRoot
	// 
	/// Returns the group that is the root of the tree of instances. If NULL is
	/// returned there is no root (see CreateTreeRootIfNone()).
	/// 
	/// \param group  The group that is returned.
	/// 
	virtual MCCOMErr MCCOMAPI GetTreeRoot					(I3DShGroup** group) = 0;
	
	// ****************************************************************************
	//								SetTreeRoot
	// 
	/// Sets the group that is the root of the scene hierarchy.
	/// 
	/// \param universe  The root of the scene hierarchy
	/// 
	virtual MCCOMErr MCCOMAPI SetTreeRoot					(I3DShGroup* universe) = 0;		// Works only if there was no tree root in the scene
	
	// ****************************************************************************
	//								CreateTreeRootIfNone
	// 
	/// Creates a group at the root of the scene hierarchy if there is not one already.
	/// 
	virtual MCCOMErr MCCOMAPI CreateTreeRootIfNone			() = 0;

	// ****************************************************************************
	//								GetTreeElementByName
	// 
	/// Returns a tree element from the scene by name. Note that tree elements that
	/// are contained in a master group will not be returned.
	/// 
	/// \param treeElement  A pointer to the tree element that can be returned.
	/// \param name         The name of the tree that we look for.
	/// 
	virtual MCCOMErr MCCOMAPI GetTreeElementByName			(I3DShTreeElement** treeElement, const TMCString& name) = 0;
	
	// ****************************************************************************
	//								GetInstanceListCount
	// 
	/// Returns the number of instances that are contained in the scene (excluding
	/// instances contained in master groups).
	/// 
	virtual uint32   MCCOMAPI GetInstanceListCount			() = 0;
	
	// ****************************************************************************
	//								GetInstanceByIndex
	// 
	/// Returns a pointer to an instance.
	/// 
	/// \param instance  The instance that is returned.
	/// \param index     The index of the instance in the scene (see GetInstanceListCount())
	/// 
	virtual MCCOMErr MCCOMAPI GetInstanceByIndex			(I3DShInstance** instance, uint32 index) = 0;
	
	// ****************************************************************************
	//								GetLightsourcesCount
	// 
	/// Returns the number of light sources in the scene (excluding the light sources
	/// that are contained in Master Groups).
	/// 
	virtual uint32   MCCOMAPI GetLightsourcesCount			() = 0;
	
	// ****************************************************************************
	//								GetLightsourceByIndex
	// 
	/// Returns a pointer to a light source.
	/// 
	/// \param light  The light source that is returned.
	/// \param index  The index of the light source in the scene (see GetLightsourcesCount()).
	/// 
	virtual MCCOMErr MCCOMAPI GetLightsourceByIndex			(I3DShLightsource** light, uint32 index) = 0;
	
	// ****************************************************************************
	//								GetCamerasCount
	// 
	/// Returns the number of cameras in the scene (excluding the cameras that are
	/// contained in a Master Group).
	/// 
	virtual uint32   MCCOMAPI GetCamerasCount				() = 0;
	
	// ****************************************************************************
	//								GetCameraByIndex
	// 
	/// Returns a pointer to a camera of the scene.
	/// 
	/// \param camera  The camera that is returned.
	/// \param index   The index of the camera in the scene (see GetCamerasCount()).
	/// 
	virtual MCCOMErr MCCOMAPI GetCameraByIndex				(I3DShCamera** camera, uint32 index) = 0;
	
	// ****************************************************************************
	//								CreateRenderingCameraIfNone
	// 
	/// Creates a rendering camera if there was none.
	/// 
	/// \param cameraType          The classID of the camera that should be created.
	/// \param createDistantLight  True if a distance light should also be created.
	/// 
	virtual MCCOMErr MCCOMAPI CreateRenderingCameraIfNone	(uint32 cameraType, boolean createDistantLight) = 0;
	
	// ****************************************************************************
	//								AnimationDataChanged
	// 
	/// Called when animation data have changed.
	/// 
	virtual MCCOMErr	MCCOMAPI AnimationDataChanged		() = 0; 
	
	// ****************************************************************************
	//								SetTime
	// 
	/// Sets the current time of the scene. Note that this function can be slow
	/// since it will trigger some calculations (like physics or particle simulation).
	/// 
	/// \param inTime             The new time.
	/// \param inUpdateViews      True if the 3D View should be updated.
	/// \param isContinuePlaying  to know if it'll be a single set time or mutliple (ex: PlayAnim=multiple set time)
	/// \param dontRecompute      
	/// \param forceSetTime       
	/// \param dontPostChange
	/// \pram dontChangeSettings
	///
	virtual MCCOMErr	MCCOMAPI SetTime					(MicroTick inTime, boolean inUpdateViews, boolean isContinuePlaying=false, boolean dontRecompute=false, boolean forceSetTime = false, boolean dontPostChange = false, boolean dontChangeSettings = false) = 0; 
	
	// ****************************************************************************
	//								GetTime
	// 
	/// Returns the current time of the scene.
	/// 
	/// \param ioSeconds  A pointer to a real where the time is stored in seconds.
	/// 
	virtual	MicroTick	MCCOMAPI GetTime					(real* ioSeconds) = 0;
  	
	// ****************************************************************************
	//								SetAllocatedTime
	// 
	/// Sets the duration of time that is allocated.
	/// 
	/// \param inAllocatedTime  The allocated time.
	/// \param inUpdateViews    True if the view should be updated.
	/// 
	virtual MCCOMErr	MCCOMAPI SetAllocatedTime			(MicroTick inAllocatedTime, boolean inUpdateViews) = 0;
	
	// ****************************************************************************
	//								GetAllocatedTime
	// 
	/// Returns the allocated time.
	/// 
	/// \param ioSeconds  A pointer to a real where the time is stored in seconds.
	/// 
	virtual MicroTick	MCCOMAPI GetAllocatedTime			(real* ioSeconds) = 0;
	
	// ****************************************************************************
	//								GetTimeManager
	// 
	/// Returns the time manager associated with this scene.
	/// 
	/// \param timeManager  The time manager that is returned.
	/// 
	virtual MCCOMErr	MCCOMAPI GetTimeManager				(I3DShTimeManager** timeManager)=0;


	// ****************************************************************************
	//								GetFullPathName
	// 
	/// Returns the full path name of file where the scene is saved.
	/// 
	/// \param pathName  The full path name of the scene file.
	/// 
	virtual MCCOMErr MCCOMAPI GetFullPathName				(TMCString& pathName) = 0;
	
	// ****************************************************************************
	//								GetTreeElementFromFullName
	// 
	/// Returns instance with given full "path name" or NULL if no such instance is in the hierarchy
	/// 
	/// \param treeElement  A pointer to the tree element that is returned.
	/// \param fullName     
	/// 
	virtual MCCOMErr MCCOMAPI GetTreeElementFromFullName	(I3DShTreeElement** treeElement, TMCString& fullName) = 0;

	// ****************************************************************************
	//								DetectCollisionWithObject
	// 
	/// Returns true if the two objects intersect each other.
	/// 
	/// \param object1          The first object.
	/// \param object2          The second object.
	/// \param ci               Information about the collision that is returned.
	/// \param SurfaceFidelity  
	/// \param UseVelocity      True if the velocity should be taken into account.
	/// \param Velocity1        The velocity of object1
	/// \param Velocity2        The velocity of object2
	/// 
	virtual boolean MCCOMAPI DetectCollisionWithObject		(I3DShTreeElement* object1, I3DShTreeElement* object2, CollisionInfo& ci, int16 SurfaceFidelity, boolean UseVelocity, TVector3 Velocity1,TVector3 Velocity2) = 0;
	
	// ****************************************************************************
	//								DetectCollisionWithScene
	// 
	/// Returns if the objects collides with the scene
	/// 
	/// \param object1          The object
	/// \param ci               Information about the collision that is returned.
	/// \param SurfaceFidelity  
	/// \param UseVelocity      True if the velocity should be taken into account.
	/// \param Velocity1        The velocity of object1
	/// \param Velocity2        The velocity of object2
	/// 
	virtual boolean MCCOMAPI DetectCollisionWithScene		(I3DShTreeElement* object1, CollisionInfo& ci, int16 SurfaceFidelity, boolean UseVelocity, TVector3 Velocity1, TVector3 Velocity2) = 0;

	// ****************************************************************************
	//								GetComment
	// 
	/// Returns the comment string that is stored in the scene file.
	/// 
	/// \param comment  
	/// 
	virtual MCCOMErr MCCOMAPI GetComment					(TMCString& comment) = 0;
	
	// ****************************************************************************
	//								SetComment
	// 
	/// Sets the comment string that is saved with the scene file.
	/// 
	/// \param comment  A string.
	/// 
	virtual MCCOMErr MCCOMAPI SetComment					(const TMCString& comment) = 0;

	// ****************************************************************************
	//								GetDataComponentsCount
	// 
	/// Returns the number of datacomponents associated with the scene.
	/// 
	virtual uint32   MCCOMAPI GetDataComponentsCount		() = 0;
	
	// ****************************************************************************
	//								GetDataComponentByIndex
	// 
	/// Returns a datacomponent of the scene.
	/// 
	/// \param dataComp  A pointer to the data component that is returned.
	/// \param index     The index of the data component in the scene.
	/// 
	virtual MCCOMErr MCCOMAPI GetDataComponentByIndex		(I3DShDataComponent** dataComp, uint32 index) = 0;
	
	// ****************************************************************************
	//								SetDataComponentByID
	// 
	/// Sets a data component on the scene.
	/// 
	/// \param dataComp   A pointer to the data component.
	/// \param cloneMode  The clone Mode (see ECloneMode).
	/// 
	virtual MCCOMErr MCCOMAPI SetDataComponentByID			(I3DShDataComponent* dataComp, ECloneMode cloneMode) = 0;
	
	// ****************************************************************************
	//								GetDataComponentByID
	// 
	/// Returns a pointer to a data component for a given class ID.
	/// 
	/// \param dataComp  A pointer to the data component that is returned.
	/// \param kindID    The class ID of the data component we are looking for.
	/// 
	virtual MCCOMErr MCCOMAPI GetDataComponentByID			(I3DShDataComponent** dataComp, IDType kindID) = 0;

	// environment:   
	//
	// -Returns:
	//
	// ****************************************************************************
	//								GetEnvironment
	// 
	/// Creates a new environment (background, backdrop, atmosphere...) for the current time.
	/// Note that need to call this function for every frame of the rendering to get a valid
	/// environment
	/// 
	/// \param environment  A pointer on the new environment
	/// 
	virtual MCCOMErr MCCOMAPI GetEnvironment				(I3DShEnvironment** environment) = 0;
	
	// ****************************************************************************
	//								GetAmbientLightColor
	// 
	/// Returns the color of the ambient light.
	/// 
	virtual TMCColorRGB MCCOMAPI GetAmbientLightColor		() = 0;

	// fills bitmap with the background/backdrop corresponding to the uvBox
	// ****************************************************************************
	//								GetBackgroundBitMap
	// 
	/// Creates a texture of the backdrop.backdrop
	/// 
	/// \param bitmap  A pixelbucket where the image is stored.
	/// \param camera  The rendering camera.
	/// \param uvBox   The screen coordinates of the texture.
	/// 
	virtual MCCOMErr MCCOMAPI GetBackgroundBitMap			(TMCPixelBucket &bitmap,I3DShCamera *camera,TBBox2D& uvBox) = 0;

	// ****************************************************************************
	//								GetBackground
	// 
	/// Returns a pointer to the background of the scene.
	/// 
	/// \param background  A pointer to the background of the scene.
	/// 
	virtual MCCOMErr MCCOMAPI GetBackground					(I3DShBackground** background) = 0;
	
	// ****************************************************************************
	//								SetBackground
	// 
	/// Sets the background of the scene.
	/// 
	/// \param background  A pointer to the background of the scene.
	/// \param cloneMode   The clone mode (see ECloneMode).
	/// 
	virtual MCCOMErr MCCOMAPI SetBackground					(I3DShBackground* background, ECloneMode cloneMode) = 0;
	
	// ****************************************************************************
	//								SetBackgroundByID
	// 
	/// Sets the type of background on the scene.
	/// 
	/// \param kindID  The classID of the background.
	/// 
	virtual MCCOMErr MCCOMAPI SetBackgroundByID				(int32 kindID) = 0;

	// ****************************************************************************
	//								GetBackdrop
	// 
	/// Returns the backdrop of the scene.
	/// 
	/// \param backdrop  A pointer to the backdrop.
	/// 
	virtual MCCOMErr MCCOMAPI GetBackdrop					(I3DShBackdrop ** backdrop) = 0;
	
	// ****************************************************************************
	//								SetBackdrop
	// 
	/// Sets the backdrop of the scene.
	/// 
	/// \param backdrop   A pointer to the backdrop.
	/// \param cloneMode  The clone mode (see ECloneMode).
	/// 
	virtual MCCOMErr MCCOMAPI SetBackdrop					(I3DShBackdrop* backdrop, ECloneMode cloneMode) = 0;
	
	// ****************************************************************************
	//								SetBackdropByID
	// 
	/// Sets the type of backdrop.
	/// 
	/// \param kindID  The class ID of the backdrop.
	/// 
	virtual MCCOMErr MCCOMAPI SetBackdropByID				(int32 kindID) = 0;

	// ****************************************************************************
	//								GetAtmosphere
	// 
	/// Returns a pointer to the atmosphere of the scene.
	/// 
	/// \param atmosphere  A pointer to the atmosphere of the scene.
	/// 
	virtual MCCOMErr MCCOMAPI GetAtmosphere					(I3DShAtmosphericShader** atmosphere) = 0;
	
	// ****************************************************************************
	//								SetAtmosphere
	// 
	/// Sets the atmosphere.
	/// 
	/// \param atmosphere  The atmosphere.
	/// \param cloneMode   The clone mode (see ECloneMode).
	/// 
	virtual MCCOMErr MCCOMAPI SetAtmosphere					(I3DShAtmosphericShader* atmosphere, ECloneMode cloneMode) = 0;
	
	// ****************************************************************************
	//								SetAtmosphereByID
	// 
	/// Sets the type of atmosphere.
	/// 
	/// \param kindID  The classID of the atmosphere.
	/// 
	virtual MCCOMErr MCCOMAPI SetAtmosphereByID				(int32 kindID) = 0;

	// ****************************************************************************
	//								GetAmbientLight
	// 
	/// Returns the ambient light of the scene.
	/// 
	/// \param ambient  The ambient light.
	/// 
	virtual MCCOMErr MCCOMAPI GetAmbientLight				(I3DShAmbientLight** ambient) = 0;
	
	// ****************************************************************************
	//								SetAmbientLight
	// 
	/// Sets the ambient light of the scene.
	/// 
	/// \param ambient    The ambient light.
	/// \param cloneMode  The clone mode (see ECloneMode).
	/// 
	virtual MCCOMErr MCCOMAPI SetAmbientLight				(I3DShAmbientLight* ambient, ECloneMode cloneMode) = 0;
	
	// ****************************************************************************
	//								SetAmbientLightByID
	// 
	/// Sets the type of ambient light
	/// 
	/// \param kindID  The classID of the ambient light.
	/// 
	virtual MCCOMErr MCCOMAPI SetAmbientLightByID			(int32 kindID) = 0;

	// ****************************************************************************
	//								GetRenderFiltersCount
	// 
	/// Returns the number of post renderers applied to the scene. Note that it
	/// does not take into account the post renderers that are instantianted by
	/// a data component
	/// 
	virtual uint32   MCCOMAPI GetRenderFiltersCount			() = 0;
	
	// ****************************************************************************
	//								GetRenderFilter
	// 
	/// Returns a pointer of a postrenderer.
	/// 
	/// \param filter  The postrenderer.
	/// \param index   The index of the post renderer in the scene (see GetRenderFiltersCount()).
	/// 
	virtual MCCOMErr MCCOMAPI GetRenderFilter				(I3DShPostRenderer** filter,uint32 index) = 0;
	
	// ****************************************************************************
	//								InsertRenderFilter
	// 
	/// Inserts a post renderer in the scene.
	/// 
	/// \param filter     The post renderer.
	/// \param index      The index in the scene.
	/// \param cloneMode  The clone mode (see ECloneMode).
	/// 
	virtual MCCOMErr MCCOMAPI InsertRenderFilter			(I3DShPostRenderer* filter,uint32 index, ECloneMode cloneMode) = 0;
	
	// ****************************************************************************
	//								InsertRenderFilterByID
	// 
	/// Inserts a post renderer in the scene.
	/// 
	/// \param kindID  The classID of the postrenderer.
	/// \param index   The index in the scene.
	/// 
	virtual MCCOMErr MCCOMAPI InsertRenderFilterByID		(int32 kindID, int32 index) = 0;
	
	// ****************************************************************************
	//								RemoveRenderFilter
	// 
	/// Removed a post renderer from the scene.
	/// 
	/// \param index  The index of the post renderer to remove.
	/// 
	virtual MCCOMErr MCCOMAPI RemoveRenderFilter			(uint32 index) = 0;
	
	// ****************************************************************************
	//								SetPostRenderers
	// 
	/// Sets the list of post renders of the scene.
	/// 
	/// \param list       The list of post renderers.
	/// \param cloneMode  The clone mode (see ECloneMode).
	/// 
	virtual MCCOMErr MCCOMAPI SetPostRenderers				(TMCCountedPtrArray<I3DShPostRenderer>& list,ECloneMode cloneMode)=0;

	// ****************************************************************************
	//								InsertDataComponent
	// 
	/// Inserts a data component in the scene.
	/// 
	/// \param dataComp   The data component to insert.
	/// \param index      The index in the list.
	/// \param cloneMode  The clone mode (see ECloneMode).
	/// 
	virtual MCCOMErr MCCOMAPI InsertDataComponent			(I3DShDataComponent* dataComp, int32 index, ECloneMode cloneMode) = 0;
	
	// ****************************************************************************
	//								InsertDataComponentByID
	// 
	/// Inserts the data component in the list just before the given index if 
	/// index is between 0 and the number of data components, or inserts the data
	/// component at the end of the list
	/// 
	/// \param kindID  The class ID of the data component to insert.
	/// \param index   The index in the scene.
	/// 
	virtual MCCOMErr MCCOMAPI InsertDataComponentByID		(int32 kindID, int32 index) = 0;
	
	// ****************************************************************************
	//								RemoveDataComponent
	// 
	/// Removes a data component from the scene.
	/// 
	/// \param index  The index of the data component to remove.
	/// 
	virtual MCCOMErr MCCOMAPI RemoveDataComponent			(uint32 index) = 0;

	// ****************************************************************************
	//								GetTimeChangeChannel
	// 
	/// Returns a pointer to the time change channel.
	/// 
	/// \param channel  A pointer to the change channel that is returned.
	/// 
	virtual MCCOMErr MCCOMAPI GetTimeChangeChannel			(IChangeChannel** channel) = 0;
	
	// ****************************************************************************
	//								GetTreePropertyChangeChannel
	// 
	/// Returns a pointer to the tree property change channel.
	/// 
	/// \param channel  A pointer to the change channel that is returned.
	/// 
	virtual MCCOMErr MCCOMAPI GetTreePropertyChangeChannel	(IChangeChannel** channel) = 0;
	
	// ****************************************************************************
	//								GetScenePropertyChangeChannel
	// 
	/// Returns a pointer to the scene property change channel.
	/// 
	/// \param channel  A pointer to the change channel that is returned.
	/// 
	virtual MCCOMErr MCCOMAPI GetScenePropertyChangeChannel	(IChangeChannel** channel) = 0;

	// ****************************************************************************
	//								GetSceneDocument
	// 
	/// Returns a pointer to the scene document associated with this scene. Note
	/// that it can be NULL if the scene was created without a document.
	/// 
	/// \param sceneDoc  A pointer to the scene document.
	/// 
	virtual MCCOMErr MCCOMAPI GetSceneDocument				(ISceneDocument** sceneDoc) = 0;
	
	// ****************************************************************************
	//								GetSceneRenderingModule
	// 
	/// Returns a pointer to the scene rendering module.
	/// 
	/// \param renderingModule  A pointer to the scene rendering module.
	/// 
	virtual MCCOMErr MCCOMAPI GetSceneRenderingModule		(I3DRenderingModule** renderingModule) = 0;

	// ****************************************************************************
	//								GetAnimate
	// 
	/// Returns true if the scene is animated.
	/// 
	virtual boolean	 MCCOMAPI GetAnimate					()=0;
	
	// ****************************************************************************
	//								SetAnimate
	// 
	/// Sets the animation status of the scene.
	/// 
	/// \param animate  The animation status of the scene.
	/// 
	virtual void	 MCCOMAPI SetAnimate					(boolean animate)=0;

	// ****************************************************************************
	//								ApplyTreeModifiers
	// 
	/// Reapplies the tree behaviors (on each tree that has some)
	/// 
	/// \param inNotify  True if each affected tree calls PostChange(kChange_TreeModifier);
	/// 
	virtual MCCOMErr MCCOMAPI ApplyTreeModifiers			(boolean inNotify)=0;

	// ****************************************************************************
	//								GetRenderEffectsTimeBased
	// 
	/// Returns a pointer associated with the scene rendering effects.
	/// 
	/// \param outTimeBased  The timebased that is returned.
	/// 
	virtual MCCOMErr MCCOMAPI GetRenderEffectsTimeBased		(ITimeBased** outTimeBased) = 0;

	// ****************************************************************************
	//								GetRenderingCamera
	// 
	/// Returns a pointer to the rendering camera. Note that this call is only
	/// valid during the rendering of the scene. To access the rendering camera
	/// at other time you should use the scene rendering module.
	/// 
	/// \param camera  A pointer to the rendering camera.
	/// 
	virtual MCCOMErr MCCOMAPI GetRenderingCamera			(I3DShCamera** camera) = 0;
	
	// ****************************************************************************
	//								SetRenderingCamera
	// 
	/// Sets the rendering camera of the scene.
	/// 
	/// \param camera  The rendering camera of the scene.
	/// 
	virtual MCCOMErr MCCOMAPI SetRenderingCamera			(I3DShCamera*  camera) = 0;
	
	// ****************************************************************************
	//								SetIsDoingIK
	// 
	/// Tells the scene to avoid sending tree move messages while solving inverse kinematics
	///	(used by the IK solver in BasicComponents)
	/// 
	/// \param isDoingIK  True when solving IK, false when done
	/// 
	virtual void	 MCCOMAPI SetIsDoingIK					(boolean isDoingIK) = 0;

	// ****************************************************************************
	//								IsDoingIK
	// 
	/// Returns true if the IK solver is computing the solution
	/// 
	/// 
	virtual boolean	 MCCOMAPI IsDoingIK						() = 0;

	// ****************************************************************************
	//								SetConstraintsAndIKEnabled
	// 
	/// Enables or disables the Constraints (and therefore the IK)
	/// 
	/// \param inEnable  
	/// 
	virtual void	 MCCOMAPI SetConstraintsAndIKEnabled	(boolean inEnable) = 0;

	// ****************************************************************************
	//								GetConstraintsAndIKEnabled
	// 
	/// Returns true if the Constraints (and therefore the IK) are enabled
	/// 
	virtual boolean	 MCCOMAPI GetConstraintsAndIKEnabled	() = 0;

	// ****************************************************************************
	//								GetInstanceIndex
	// 
	/// Returns the index of an instance in the scene. Note that if the instance is
	/// inside a Master Group this method will not work.
	/// 
	/// \param instance  The instance of the scene for which you need the index
	/// 
	/// \return the instance's index, or kUnusedIndex if the instance does not belong to the scene
	///
	virtual uint32	 MCCOMAPI GetInstanceIndex				(const I3DShInstance* instance) = 0;

	// ****************************************************************************
	//								GetTreesCount
	// 
	/// Returns the number of trees elements in the scene
	/// 
	/// 
	virtual uint32	 MCCOMAPI GetTreesCount					() = 0;

	// ****************************************************************************
	//								GetTreeByIndex
	// 
	/// Returns a pointer to a tree element of the scene.
	/// 
	/// \param index  Must be between 0 and GetTreesCount() - 1
	/// 
	virtual I3DShTreeElement* MCCOMAPI GetTreeByIndex(uint32 index) = 0;

	// ****************************************************************************
	//								GetTreeIndex
	// 
	/// Returns the tree's index in the scene
	/// 
	/// \param tree  The tree of the scene for which you need the index
	/// 
	/// \return The tree's index, or kUnusedIndex if the tree does not belong to the scene.
	///
	virtual uint32	 MCCOMAPI GetTreeIndex				(const I3DShTreeElement* tree) = 0;

	// ****************************************************************************
	//								GetTreeByIDPath
	// 
	/// Returns the tree identified by the Path
	/// 
	/// \param tree      The tree to be found
	/// \param IDPath    The path of the tree in the scene.
	/// 
	virtual MCCOMErr	MCCOMAPI GetTreeByIDPath(I3DShTreeElement ** tree, const TTreeIdPath& IDPath)=0;

	// ****************************************************************************
	//								GetTreePermanentID
	// 
	/// Returns the tree ID if find it, or else return invalid tree ID;
	/// SHOULDN'T BE USED : does not take into account the master groups
	/// 
	/// \param tree  The tree.
	/// 
	virtual TTreeId		MCCOMAPI GetTreePermanentID(const I3DShTreeElement* tree)=0;

	// ****************************************************************************
	//								PermanentIDIsValid
	// 
	/// Checks if the passed ID is not already used by a registered instance.
	/// Checks at the same time if the counter that deliver the new IDs is at least as big as this value.
	/// 
	/// \param ID  The ID value to be checked
	///
	/// Return true if the ID is valid, false if it's already used by some instance.
	/// 
	virtual boolean		MCCOMAPI PermanentIDIsValid(const TTreeId& ID )=0;


	// ****************************************************************************
	//								StoreCurrentState
	// 
	/// Stores the current animation parameters of the scene for motion blur purpose.
	/// each object that can affect motion blur (skinned object, transforms...) should
	/// store their current state so that they can calculate the motion between that time
	/// (store) and the current time.
	/// 
	/// \param frameType  Indicates if the data are stored in the past or future (kPreviousFrame or kNextFrame)
	/// 
	virtual void		MCCOMAPI StoreCurrentState(EFrameType frameType)=0;

	// ****************************************************************************
	//								BeginRendering
	// 
	/// Called just before the rendering
	/// 
	/// 
	virtual void		MCCOMAPI BeginRendering()=0;

	// ****************************************************************************
	//								EndRendering
	// 
	/// Called just after a rendering
	/// 
	/// 
	virtual void		MCCOMAPI EndRendering()=0;

	// ****************************************************************************
	//								GetFramesPerSecond
	// 
	/// Get the frames per second
	/// 
	/// 
	virtual real32    MCCOMAPI GetFramesPerSecond() = 0;

	// ****************************************************************************
	//								SetFramesPerSecond
	// 
	/// Set the frames per second from the rendering settings
	/// 
	/// \param fps  
	/// 
	virtual void	  MCCOMAPI SetFramesPerSecond(real32 fps) = 0;

	// ****************************************************************************
	//								GetPhysicsEngine
	// 
	/// Returns a pointer to the physics engine. Returns NULL if there is no physics
	/// engine.
	/// 
	/// 
	virtual I3DShPhysicsEngine*	MCCOMAPI GetPhysicsEngine() = 0;

	// ****************************************************************************
	//								SetPhysicsEngine
	// 
	/// Set the physics engine.
	/// 
	/// 
	virtual void	MCCOMAPI SetPhysicsEngine(I3DShPhysicsEngine* physicsEngine) = 0;

	// ****************************************************************************
	//								GetMagnitude
	// 
	/// Returns the number of inches in a scene's unit
	/// 
	/// 
	virtual real32    MCCOMAPI GetMagnitude() const = 0;

	// ****************************************************************************
	//								SetMagnitude
	// 
	/// Sets the scene's magnitude order
	/// 
	/// \param unit		the new magnitude order, in inches
	/// 
	virtual void	  MCCOMAPI SetMagnitude(real32 unit) = 0;

	// ****************************************************************************
	//								Get3DUnit
	// 
	/// Returns the displayed unit for this scene
	/// 
	/// 
	virtual int32    MCCOMAPI Get3DUnit() const = 0;

	// ****************************************************************************
	//								Set3DUnit
	// 
	/// Sets the unit to be displayed for this scene
	/// 
	/// \param unit		the new unit
	/// 
	virtual void	  MCCOMAPI Set3DUnit(int32 unit) = 0;

	// ****************************************************************************
	//								GetDecimalsNumber
	// 
	/// Returns the number of decimals that are displayed in numerical requestors 
	/// 
	/// 
	virtual int8      MCCOMAPI GetDecimalsNumber() const = 0;

	// ****************************************************************************
	//								SetDecimalsNumber
	// 
	/// Sets the number of decimals that are displayed in numerical requestors
	/// 
	/// \param ndec		number of decimals number to display
	/// 
	virtual void	  MCCOMAPI SetDecimalsNumber(int8 ndec) = 0;

	// ****************************************************************************
	//								GetCameraMovementSpeed
	// 
	/// Returns the speed of the camera's movement (this value is relative
	/// to the current scene magnitude, and its default is 100%)
	/// 
	virtual real32    MCCOMAPI GetCameraMovementSpeed() const = 0;

	// ****************************************************************************
	//								SetCameraMovementSpeed
	// 
	/// Sets the camera's movement speed
	/// 
	/// \param speed	the new speed
	/// 
	virtual void	  MCCOMAPI SetCameraMovementSpeed(real32 speed) = 0;

	// ****************************************************************************
	//								GetCameraRotationSpeed
	// 
	/// Returns the speed of the camera's rotation (this value is relative
	/// to the current scene magnitude, and its default is 100%)
	/// 
	virtual real32    MCCOMAPI GetCameraRotationSpeed() const = 0;

	// ****************************************************************************
	//								SetCameraRotationSpeed
	// 
	/// Sets the camera's rotation speed
	/// 
	/// \param speed	the new speed
	/// 
	virtual void	  MCCOMAPI SetCameraRotationSpeed(real32 speed) = 0;

	// ****************************************************************************
	//								GetNudgeSize
	// 
	/// Returns the nudge size in this scene
	/// 
	virtual real32    MCCOMAPI GetNudgeSize() const = 0;

	// ****************************************************************************
	//								SetNudgeSize
	// 
	/// Sets the nudge size for this scene
	/// 
	/// \param speed	the new increment value
	/// 
	virtual void	  MCCOMAPI SetNudgeSize(real32 nudge) = 0;

	// ****************************************************************************
	//								SetFrameSkipping
	// 
	/// Returns whether or not the animation preview will skip frames during playback
	/// 
	virtual boolean	  MCCOMAPI GetFrameSkipping() = 0;

	// ****************************************************************************
	//								SetFrameSkipping
	// 
	/// Sets whether or not the animation preview will skip frames during playback
	/// 
	/// \param shouldSkip	should we skip frames or not
	/// 
	virtual void	  MCCOMAPI SetFrameSkipping(boolean shouldSkip) = 0;

	// ****************************************************************************
	//								SetAcceleratedTextureSize
	// 
	/// Sets the maximal size of texture used when rendering using hardware acceleration 
	/// 
	/// \param logTextureSize the log2 value of the maximal texture size 
	/// 
	virtual void	  MCCOMAPI SetAcceleratedTextureSize(uint32 logTextureSize) = 0;

	// ****************************************************************************
	//								GetAcceleratedTextureSize
	// 
	/// Gets the maximal size of texture used when rendering using hardware acceleration 
	/// 
	/// \return The log2 value of the maximal texture size 
	/// 
	virtual uint32	  MCCOMAPI GetAcceleratedTextureSize() const = 0;
};


/// \}


#endif
