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

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

		Author:	Charles
		Date:	12/4/2002

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

#ifndef __I3DShMasterGroup__
#define __I3DShMasterGroup__

#if CP_PRAGMA_ONCE
#pragma once
#endif

#include "ApiTypes.h"
#include "MCCompObj.h"
#include "Id.h"
#include "TransformsFwd.h"

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

MCDEFINE_GUID_H(IID_I3DShMasterGroup);
MCDEFINE_GUID_H(CLSID_MasterGroup);

//****** Forward declarations *************************************************

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 CollisionInfo;
struct IShComponent;
struct ITimeBased;
struct I3DShScene;

class TMCPixelBucket;
class TMCString;

/// \addtogroup ShellInterface
/// \{

// ****************************************************************************
//								I3DShMasterGroup
// 
/// <P>A master group is a group that can be instantiated in a scene. Note that a
/// scene is a master group.</P>
///
/// <P>A master group is also a Master Object so it implements I3DShObject too.</P>
///
struct I3DShMasterGroup: public IMCUnknown
{

	// ****************************************************************************
	//								SetScene
	// 
	/// Call this just after the creation of a master group with the scene attached
	/// to the document.
	/// 
	/// \param topScene  
	/// 
	virtual MCCOMErr MCCOMAPI SetScene(I3DShScene* topScene) = 0;

	// ****************************************************************************
	//								GetScene
	// 
	/// Returns a pointer to the scene that contains this master group.
	/// 
	/// \return NULL if the master is not contained in a scene.
	///
	virtual I3DShScene* MCCOMAPI GetScene() = 0;

	// ****************************************************************************
	//								GetTreeRoot
	// 
	/// Returns the group that is the root of the Master Group.
	/// 
	/// \param group  A pointer to the root of the Master Group.
	/// 
	virtual MCCOMErr MCCOMAPI GetTreeRoot					(I3DShGroup** group) = 0;
	
	// ****************************************************************************
	//								SetTreeRoot
	// 
	/// Sets the group that is the root of the Master Group.
	/// (Works only if there was no tree root in the Master Group)
	///
	/// \param universe  A pointer to the new root of the Master Group.
	/// 
	virtual MCCOMErr MCCOMAPI SetTreeRoot					(I3DShGroup* universe) = 0;
	
	// ****************************************************************************
	//								CreateTreeRootIfNone
	// 
	/// Create an empty group at the root of the Master Group if there is not already
	/// a root.
	/// 
	virtual MCCOMErr MCCOMAPI CreateTreeRootIfNone			() = 0;

	// ****************************************************************************
	//								GetTreeElementByName
	// 
	/// Returns a sub tree of the Master Group by Name.
	/// 
	/// \param treeElement  A pointer to the tree element that is returned. (NULL if not found)
	/// \param name         The name of the tree element.
	/// 
	virtual MCCOMErr MCCOMAPI GetTreeElementByName			(I3DShTreeElement** treeElement, const TMCString& name) = 0;
	
	// ****************************************************************************
	//								GetInstanceListCount
	// 
	/// Returns the number of instances inside this Master Group. Note that this is
	/// not the instances of the Master Group (to access that, you should QueryInterface
	/// for I3DShObject
	/// 
	virtual uint32   MCCOMAPI GetInstanceListCount			() = 0;
	
	// ****************************************************************************
	//								GetInstanceByIndex
	// 
	/// Returns an instance that is contained in the Master Group. (See GetInstanceListCount()).
	/// 
	/// \param instance  A pointer to the instance.
	/// \param index     The index of the instance in the Master Group.
	/// 
	virtual MCCOMErr MCCOMAPI GetInstanceByIndex			(I3DShInstance** instance, uint32 index) = 0;
	
	// ****************************************************************************
	//								GetLightsourcesCount
	// 
	/// Returns the number of light sources contained in the Master Group.
	/// 
	virtual uint32   MCCOMAPI GetLightsourcesCount			() = 0;
	
	// ****************************************************************************
	//								GetLightsourceByIndex
	// 
	/// Returns a light source that is is contained in the Master Group. (See GetLightsourcesCount()).
	/// 
	/// \param light  A pointer to the light source.
	/// \param index  The index of the light source in the Master Group.
	/// 
	virtual MCCOMErr MCCOMAPI GetLightsourceByIndex			(I3DShLightsource** light, uint32 index) = 0;
	
	// ****************************************************************************
	//								GetCamerasCount
	// 
	/// Returns the number of camera sources contained in the Master Group.
	/// 
	virtual uint32   MCCOMAPI GetCamerasCount				() = 0;
	
	// ****************************************************************************
	//								GetCameraByIndex
	// 
	/// Returns a camera that is is contained in the Master Group. (See GetCamerasCount()).
	/// 
	/// \param camera  A pointer to the camera.
	/// \param index  The index of the camera in the Master Group.
	/// 
	virtual MCCOMErr MCCOMAPI GetCameraByIndex				(I3DShCamera** camera, uint32 index) = 0;
	
	// ****************************************************************************
	//								GetFullPathName
	// 
	/// This function is only valid for scene. It is the fullpath name of the file
	/// where the scene is saved.
	/// 
	/// \param pathName  The full path name.
	/// 
	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     The full name of the tree Element
	/// 
	virtual MCCOMErr MCCOMAPI GetTreeElementFromFullName	(I3DShTreeElement** treeElement, TMCString& fullName) = 0; 

	// ****************************************************************************
	//								GetInstanceIndex
	// 
	/// Returns the index of a given instance inside the Master Group (see GetInstanceByIndex()).
	/// 
	/// \param instance  The instance of the scene for which you need the index
	/// 
	/// \return kUnusedIndex if the instance does not belong to this Master Group.
	///
	virtual uint32	 MCCOMAPI GetInstanceIndex				(const I3DShInstance* instance) = 0;
	
	// ****************************************************************************
	//								GetTreesCount
	// 
	/// Returns the number of tree elements that belongs to the Master Group.
	/// 
	virtual uint32	 MCCOMAPI GetTreesCount					() = 0;

	// ****************************************************************************
	//								GetTreeByIndex
	// 
	/// Returns the tree at the given index
	/// 
	/// \param index  Must be between 0 and GetTreesCount() - 1
	/// 
	virtual I3DShTreeElement* MCCOMAPI GetTreeByIndex(uint32 index) = 0;

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

	// ****************************************************************************
	//								GetTreeByPermanentID
	// 
	/// Returns the tree identified by the Permanent ID
	/// 
	/// \param tree         The tree to be found, the Permanent ID that is looked for
	/// \param permanentID  The unique ID of the tree.
	/// 
	virtual MCCOMErr	MCCOMAPI GetTreeByPermanentID(I3DShTreeElement ** tree, const TTreeId& permanentID)=0;

	// ****************************************************************************
	//								GetTreePermanentID
	// 
	/// Returns the tree PermanentID if find it, or else return 0;
	/// 
	/// \param tree  
	/// 
	virtual TTreeId		MCCOMAPI GetTreePermanentID(const I3DShTreeElement* tree)=0;

	// ****************************************************************************
	//								GetTreeByIDPath
	// 
	/// Returns the tree identified by the ID path
	/// 
	/// \param tree     The tree to be found
	/// \param IDPath   The path of the tree relative to the Master Group
	/// 
	virtual MCCOMErr	MCCOMAPI GetTreeByIDPath(I3DShTreeElement ** tree, const TTreeIdPath& IDPath)=0;

	// ****************************************************************************
	//								PermanentIDIsValid
	// 
	///	Checks if the passed ID is not already used by a registered instance.
	///	Also Checks if the counter that delivers the new IDs is at least as big as this value.
	/// 
	/// \param ID  The ID that needs to be checked.
	/// 
	virtual boolean		MCCOMAPI PermanentIDIsValid(const TTreeId& ID )=0;
};

/// \}


#endif
