3DScene.h

Go to the documentation of this file.

//! @file 3DScene.h
//! @brief C3DScene class definition
//////////////////////////////////////////////////////////////////////
 
#if !defined(AFX_3DScene_H__CA6BC29F_FAC2_11D1_A0DE_000000000000__INCLUDED_)
#define AFX_3DScene_H__CA6BC29F_FAC2_11D1_A0DE_000000000000__INCLUDED_
 
#ifdef _MSC_VER
#pragma once
#endif // _MSC_VER
 
#include "3DSceneNode.h"
#include "3DBaseObject.h"
#include "3DFaceList.h"
#include "3DMaterial.h"
#include "3DAnimatable.h"
#include "Tree.h"
 
BEGIN_MOOTOOLS_NAMESPACE
 
class CSceneExportOptions;
class CSceneImportOptions;
class C3DInstanceID;
class CParserSceneInfo;
 
//! @enum SCENE_DATA
//! These information might be retrieve through the C3DScene::GetCustomData() class.\n
//! If these information is missing, the default value should be taken into account.
typedef enum SCENE_DATA XEnumType(unsigned int)
{
    SCENE_DATA_FILENAME = MAKE_CUSTOM_ID('S', 'N', 'F', 'L'), //!< CXString: the scene file path
    SCENE_DATA_FILECLASS = MAKE_CUSTOM_ID('S', 'N', 'F', 'C'), //!< Unsigned int: the scene file class (Ie. FBX_3D_FILE, WAVEFRONT_3D_FILE...)
    SCENE_DATA_TEMPORARY_TEXTURES = MAKE_CUSTOM_ID('T', 'M', 'M', 'P'), //!< Bool (false): texture files are temporaries and can be deleted when scene deleted (ie, embedded textures in FBX or sketchup). Texture are not temporary if this information is missing.
    SCENE_DATA_PATCH_LEVEL = MAKE_CUSTOM_ID('P', 'A', 'L', 'V'), //!< unsigned int (C3DPreferences::Get3DPreferences()::GetPatchLevel())
    SCENE_DATA_SMOOTH_ANGLE = MAKE_CUSTOM_ID('S', 'M', 'A', 'N'), //!< float ((C3DPreferences::Get3DPreferences()::GetSmoothAngle()). Smooth angle in radian
    SCENE_DATA_SMOOTH_MODE = MAKE_CUSTOM_ID('S', 'M', 'M', 'O'), //!< unsigned int ((C3DPreferences::Get3DPreferences()::GetSmoothMode())
    SCENE_DATA_TEXTURE_PATHS = MAKE_CUSTOM_ID('T', 'X', 'P', 'H'), //!< string array: additional texture paths. Can be retrieve using C3DScene::GetTexturePaths
    SCENE_DATA_GEOLOCATION = MAKE_CUSTOM_ID('G', 'E', 'O', 'L'), //!< Binary (C3DScene::GeoLocation): longitude and latitude position of the scene
    SCENE_DATA_TARGET_MR_BBOX = MAKE_CUSTOM_ID('T', 'G', 'B', 'X'), //!< Binary - 6 floats - Target bounding box for multiresolution file
} SCENE_DATA;
 
//! @class C3DObjectCreator
//! @brief This class can be provided in C3DScene::Copy operations and allows to modify the created kind of class during the copy operation.
//! @details If you intend to overidde some specific class, such C3DPointList, you can create a copy of the scene that will use this new class.
//! C3DPolygonCruncherObjectCreator typically does this, using C3DExtPointList for object instead of the standard C3DPointList.
class DLL_3DFUNCTION C3DObjectCreator
{
    friend C3DScene;
 
public:
    //! @brief Destination scene to which the element is copied.
    //! @details The element GUID will remain the same if the destination scene differs from the original scene, or if no scene (= NULL) is defined.
    //! If no scene is defined, the element is not attached to any scene until it is attached to the scene (using C3DScene::AddNode for example)
    C3DObjectCreator(C3DScene *scene = NULL);
    virtual ~C3DObjectCreator();
 
    virtual C3DBaseObject *ConvertToType(const C3DSceneNode *refnode, const C3DBaseObject *refobject); //!< Convert refobject to another type. return the object itself if no conversion performed
    virtual C3DBaseObject *GetNewObjectFrom(const C3DBaseObject *refobject, bool& emptyCopy); //!< Return an object from the provided refobject. Returned object might be empty (empty points/faces/channels). In this case, object copy fills the returned empty object
 
    virtual bool CanProcess(const C3DSceneNode *node, const C3DBaseObject *object); //!< Return true if the node and its object should be copied / converted
 
    //! @name overriden possibilities
    //! The following methods are called to create the copy of the object
    //! It gives a chance to the copy method to copy the object to a different type
    //! @{
    virtual C3DFaceList *GetNewFaceList();
    virtual C3DPointList *GetNewPointList();
    virtual C3DObject *GetNewPolygonalObject();
    virtual C3DCurve *GetNewCurveObject();
    virtual C3DPatch *GetNewPatchObject();
    virtual C3DGroup *GetNewGroupObject();
    virtual C3DDummy *GetNewDummy();
    virtual C3DCamera *GetNewCamera();
    virtual C3DLight *GetNewLight();
    
    //! @}
 
    C3DScene *GetScene() const; //!< Set the scene to which the copied object will belong to. The element GUID is updated 
    void SetScene(C3DScene *scene); //!< Set the scene to which the copied object will belong to. The element GUID is updated 
    CCustomData& GetCustomData(); //!< Can be used to store some information
 
protected:
    C3DScene *scene;
    CCustomData data;
    CHashMap<BaseObjectID, BaseObjectID, BaseObjectID> ids; // Used internally to map object id
};
 
//! @enum NodePosFlags
//! Scene Node traversal flags
//! These flags can be used with C3DScene::GetFirstNode/C3DScene::GetNextNode to control the way the scene tree is 
typedef enum  NodePosFlags XEnumType(unsigned int)
{
    NODEPOS_DEFAULT = 0, //!< Do default traversal, which means it starts traversal from the first child of the provided node. If provided node is NULL, then all the scene will be traverse
    NODEPOS_INSTANCE_ONCE = 0x01, //!< When traversing the tree, settings this flag returns only once time each object instance. This is useful to perform an operation only once on objects when processing them.
    NODEPOS_INCLUDE_NODE = 0x02, //!< Include the node itself in the traversal. Node childs and right brothers will also be traversed.
    NODEPOS_BRANCH_ONLY = 0x04, //!< Traverse provided node childs. If NODEPOS_INCLUDE_NODE specified, traverse also right branch (brothers and childs).
    NODEPOS_ALLOW_EMPTY_NODES = 0x08, //!< During serialization some node might be provided with geometry. This allows to get access to such node, which are used only under special circumstances.
} NodePosFlags;
 
//! @enum NodeFilterFlags
//! These flags are used within C3DFilter to limit processing  to the nodes concerned.
typedef enum  NodeFilterFlags XEnumType(unsigned int)
{
    NODEFILTER_DEFAULT = 0, //!< Do default traversal, filter nothing
    NODEFILTER_VALID = 0x01, //!< Return only valid nodes
    NODEFILTER_SHOW = 0x02, //!< Return only displayed nodes
    NODEFILTER_SELECTED = 0x04, //!< Return only selected nodes
} NodeFilterFlags;
 
//! @class C3DFilter
//! @brief C3DFilter allows to filter the nodes / faces / points being processed.
//! @details Some C3DScene methods offers to provide C3DFilter
//! This is a convienient method to process or not some of the elements when they are traversed.\n
//! Depending on the method, some or all the callback (ProcessNode, ProcessFace, ProcessPoint) might be called.\n
//! The return value of these methods will make the element processed or not by the calling function.
//! 
class DLL_3DFUNCTION C3DFilter
{
protected:
    unsigned int flags, kindof;
    void *callbackData;
 
public:
    C3DFilter(unsigned int flags = NODEFILTER_DEFAULT, unsigned int kindOfObject = OBJECT_ALL_KINDOF); //!< By default all the nodes are transmitted to ProcessNode.
 
    void SetCallbackData(void* data); //!< specific that can be used in the callback operation 
    void* GetCallbackData() { return callbackData; } //!< specific that can be used in the callback operation 
 
    virtual bool ProcessNode(const C3DSceneNode *node) const; //!< Return true if the node should be processed, false otherwise.
    virtual bool ProcessFace(const C3DBaseObject *object, const C3DFace *face) const; //!< Return true if the face should be processed, false otherwise.
    virtual bool ProcessPoint(const C3DBaseObject *object, const C3DPoint *point) const; //!< Return true if the point should be processed, false otherwise.
 
    static bool ProcessNode(unsigned int filterFlags, const C3DSceneNode *node, unsigned int kindOfObject = OBJECT_ALL_KINDOF); //!< Flags is one or more NodeFilterFlags. Call this static method allows a simple filter on the nodes.
};
 
//! @class C3DFlagFilter
//! This C3DFilter derived class adds a way to define some flags the node must / mustn't have
class DLL_3DFUNCTION C3DFlagFilter : public C3DFilter
{
protected:
    unsigned int neededFlags;
    unsigned int excludingFlags;
    void* callbackData;
 
public:
    C3DFlagFilter(unsigned int kindOfObject = OBJECT_ALL_KINDOF); //!< By default all the nodes are transmitted to ProcessNode.
 
    void NeededFlags(unsigned int flags); //!< Defines flags required for the node to be processed
    void ExcludindFlags(unsigned int flags); //!< Defines flags that the node must not have
 
    virtual bool ProcessNode(const C3DSceneNode* node) const; //!< Return true if the node should be processed, false if not
};
 
//! @class C3DConcatenateFilter
//! This C3DFilter derived class is used as a callback in the concatenation process. It allows to have a fine control on what should be concatenated
class DLL_3DFUNCTION C3DConcatenateFilter : public C3DFilter
{
protected:
    C3DScene *scene; // The scene from which concatenation is performed
    FBMaterialID fbmatid; // MATERIAL_UNDEFINED by default, unless if only faces with this material is to be extracted
 
    bool mustHave;
    enum XEnumType(unsigned char)
    {
        NO_FILTER = 0,
        SINGLESIDE_FILTER,
        DOUBLESIDE_FILTER,
    } materialFilteringMode;
 
public:
    C3DConcatenateFilter(unsigned int flags = NODEFILTER_DEFAULT, unsigned int kindOfObject = OBJECT_ALL_KINDOF);
 
    void SetScene(C3DScene *refscene) { this->scene = refscene; }
    void SetMaterial(MaterialID matid, bool musHave); //!< Used to perform material filtering (used by ConcatenateByMaterial)
    bool PerformMaterialFiltering() const; //!< Return true if material filtering is performed
    void SetFBMaterial(FBMaterialID matid, bool musHave); //!< Used to perform material filtering (used by ConcatenateByMaterial)
    FBMaterialID GetFBMaterialID() const; //!< Get the material that was set. If SetMaterial call, the return material as only frontID defined
    virtual bool ProcessNode(const C3DSceneNode *node) const; //!< Must be called by overriden methods to handle material filtering if needed.
    virtual bool ProcessFace(const C3DBaseObject *object, const C3DFace *face) const; //!< Must be called by overriden methods to handle material filtering if needed.
 
    virtual C3DSceneNode *OnConcatenateBegin(); //!< A new concatenated node need to be created with its object. We will try to add something to it, if filter allows it. This give the chance to set a node name, or some custom data if needed.
    virtual void OnConcatenateEnd(C3DSceneNode *dstnode, bool validNode) {}; //!< The dstnode send previously in OnConcatenateBegin is finished to be processed. If validNode == true, this means that dstnode contains an Object (available with C3DSceneNode::GetObject). Otherwise the node will be destroyed.
    virtual void OnConcatenate(C3DSceneNode *dstnode, const C3DSceneNode *srcnode) {}; //!< This is called when something from srcnode object goes into dstnode object. This give a chance to merge the customdata for example
    virtual void OnConcatenate(C3DGeomObject *dstobject, const C3DBaseObject *srcobject) {}; //!< This is calledwhen something from srcobject goes into dstobject. dstobject is a geom object, but srcobject is an object that belong to a node which has been approved by filter (ie, a group)
    virtual void OnConcatenate(C3DFaceList *dstfaces, unsigned int dstindex, const C3DFaceList *srcfacelist, unsigned int srcindex) {}; //!< This is called when the #srcindex from srcfacelist, is added to #dstindex of dstfaces. This can be used for advanced DataChunk processing.
};
 
//! @class C3DNodePos
//! This is a C3DScene iterator for node traversal. Cf. @ref TRAVERSING for more information and C3DScene::GetFirstNode() / C3DScene::GetNextNode()
class DLL_3DFUNCTION C3DNodePos
{
    friend C3DScene;
 
public:
    C3DNodePos();
    C3DNodePos(const C3DNodePos& pos);
    virtual ~C3DNodePos();
 
    operator bool() { return (node != NULL); }
    C3DNodePos& operator=(const C3DNodePos& pos);
 
    void SetFilter(const C3DFilter* filter); //!< Place a filter to exclude node from being processed. To be set after C3DScene::GetFirstNode();
 
    // Special processing when NODEPOS_INSTANCE_ONCE is set. This allow to insert an ID if some object are replaced by new during the processing
    // Cf ConvertToType for example
    bool CheckObjectID(BaseObjectID id) const; //!< return true if specified object id has been seen (works in conjunction with AddObjectID)
    void AddObjectID(BaseObjectID id); //!< Add an ObjectID in the processed list. No other nodes with this object ID will be returned by GetNext any more. This can be used to exclude some nodes that would have been inserted during a traversal to be part of the traversal.
 
protected:
    typedef enum _NodePosInternalFlags
    {
        NODEPOS_INTERNAL_NONE = 0x00,
        NODEPOS_INTERNAL_STOP_TRAVERSAL = 0x01,
        NODEPOS_INTERNAL_ALLOW_EMPTY_GEOM = 0x02,
        NODEPOS_INTERNAL_IGNORE_INSTANCE_ONCE = 0x04,
    } NodePosInternalFlags;
 
    const C3DScene *scene;
    const C3DFilter *filter;
    unsigned int kindof; // kind of object required
    unsigned int internalflags; 
    C3DSceneNode *node; // The current node
    C3DSceneNode *stopNode; // Node to stop to
    C3DInstanceID *instances; // Instance already taken into account
};
 
//! @struct SceneSerializeData
//! This information can be retrieve through CXArchive::GetData during serialization, while all scene data is traversed
typedef struct SceneSerializeData
{
    unsigned int sceneVersion, materialsVersion;
    C3DScene *scene;
    CCustomData data;
} SceneSerializeData;
 
//! @enum SceneSelectionFlags
//! these flags control the selection for C3DScene::Select method
//! If these information is missing, the default value should be taken into account.
typedef enum  SceneSelectionFlags XEnumType(unsigned int)
{
    SELECTION_DEFAULT = 0,
    SELECTION_KEEP_SELECTION = 0x01, //!< Add the new selection to the existing one
    SELECTION_SELECT_INSTANCES = 0x02, //!< Select also the instances of the provided node
    SELECTION_SELECT_CHILDS = 0x04, //!< Select the child of the provided node
} SceneSelectionFlags;
 
//! @enum ConcatenateFlags
//! Used by C3DScene::Concatenate and C3DScene::ConcatenateByMaterials to control what is process and where the created nodes are inserted in the scene
typedef enum ConcatenateFlags XEnumType(unsigned int)
{
    CONCATENATE_DEFAULT = 0, //!< The scene is not modified, and a node is returned which can be added as you need in the scene graph
    CONCATENATE_INCLUDE_PARENT = 0x01, //!< parentNode is included in concatenation (could be useful if parent is a geom object)
 
    // Insert the concatenated node in the scene graph by replacing the parentNode or parentNode childs
    CONCATENATE_REMOVE_TO_ROOT = 0x10, //!< Parent and childs are deleted (or not depending on the optionnal C3DFilter::ProcessNode returned value) and concatenated node is added to the scene root
    CONCATENATE_REMOVE_AND_ADD_TO_PARENT = 0x20, //!< Parent childs are deleted (or not depending on the optionnal C3DFilter::ProcessNode returned value) and replace by concatenated node which become child of parent. 
    CONCATENATE_REPLACE_PARENT = 0x40, //!< Parent and its childs is replaced by concatenated node (whatever C3DFilter::ProcessNode returned value)
 
    CONCATENATE_PROCESSING_FLAGS = 0xFFFF000,
    CONCATENATE_SORT_BY_MATERIAL = 0x1000, //!< The result node has its faces sorted by material
} ConcatenateFlags;
 
//! @enum CreateBackFaceFlags
//! Flags for CreateBackfaceNodes method
typedef enum CreateBackFaceFlags XEnumType(unsigned int)
{
    BACKFACE_DEFAULT = 0, //!< Create back face for all geom and the whole geom
    BACKFACE_FBGEOM = 0x01, //!< Create back face only if geom have back face materials. In this case the whole geom is backfaced.
    BACKFACE_FBFACE_ONLY = 0x02, //!< Create back face only for face that have back face materials. In this case only the fb faces are backfaced
} CreateBackFaceFlags;
 
//! @enum ReplaceMatIDFlags
//! Flags to control how C3DScene::ReplaceNodeMaterialID handles material replacement
typedef enum ReplaceMatIDFlags XEnumType(unsigned int)
{
    REPLACEMATID_DEFAULT = 0, 
    REPLACEMATID_COPY_MATERIAL = 0x1, //!< the target material (newmatid) is replaced by the src material (if newmatid exits, it is deleted). If not set, newmatid material is supposed to exists in the material list
    REPLACEMATID_DELETE_SRC_MATERIAL = 0x2, //!< Delete the src material (matid). To be used only if pParentNode = NULL, otherwise some other might reference oldmatid
    REPLACEMATID_INCLUDE_PARENT = 0x100, //!< pParentNode is included in the change
} ReplaceMatIDFlags;
 
class DLL_3DFUNCTION C3DInstanceMap : protected CAssociationMap<BaseObjectID, C3DSceneNode *, unsigned int>
{
    friend C3DScene;
    using CAssociationMap::Convert;
    using CAssociationMap::GetSize;
    
    mutable C3DSceneNode *refnode;
 
public:
    using CAssociationMap::Free;
    C3DSceneNode **GetInstancesByID(C3DSceneNode *node, int& size) const; //!< Return instances of the node. If the node has no instance, it return the a pointer to the node itself with size = 1
};
 
//! @class C3DScene
//! @brief The class allows to get access to the scene graph, node hierarchy, material.
//! @details C3DScene contains a C3DSceneNode tree and materials reference.
//! It allows to read and write different files and to perform some different operations on the scene such node concatenation, scene merging...
//!
//! @par
//! Most of the C3DScene method specify a parent node. If you want to process the whole scene you can either this parent node can be NULL or GetRoot()
//! @note
//! The scene can have multiple reference and CInstanciatedObject::Delete should be used to correctly release it.
//! 
class DLL_3DFUNCTION C3DScene : private CTree, public C3DAnimatable, public CInstanciatedObject
{
public:
    typedef struct SortSceneData
    {
        C3DScene* scene;
        unsigned int kindOfObject;
        unsigned int nodeFlags;
        bool nodeFlagSet;
        void* userData;
    } SortSceneData;
 
    typedef struct GeoLocation
    {
        double longitude, latitude, altitude; //!< altitude in m
        double northCorrection; //!< Rotation around Z axis to align Y axis to the north, in radian
    } GeoLocation;
 
public:
    C3DScene();
    virtual ~C3DScene(); //!< Use Delete instead, unless the C3DScene is created on the stack (take care that it is referenced once only in this case)
 
    static C3DScene *Create(); //!< Allocates and creates an empty scene. Use C3DScene::Delete to delete the scene. Same as xNew(C3DScene).
#ifdef MOOTOOLS_PRIVATE_BUILD
    int AddRef() const;
    virtual bool Delete();
#endif
 
    //! @name Scene information
    //! Various information about the scene
    //!
    //! @{
    C3DSceneNode *GetRoot() const; //!< Return the root node in the scene.
    CCustomData& GetCustomData(); //!< Get access to custom data which allows to set or retrieve specific information. cf. #SCENE_DATA to find or retrieve some particular information. You may also store you own information creating your own IDs.
 
    CFileNameSpec GetFilename() const;
    CXString GetFilepath() const;
    void SetFilename(const CFileNameSpec& filename);
    void SetParserData(bool isReading, unsigned int parserClass, void *data);
    void *GetParserData(unsigned int& parserClass, bool detachData);
 
    //! @}
 
    //! @name Scene units
    //! Set and retrieve units and scale factor. The SDK Internal unit is arbitrarly defined as centimeters, which means that by default an unit vector length is considered to be 1 cm. 
    //! @{
    double ConvertToUnit(double x) const; //!< Get a value in the current length / scale unit. (x * scale factor) / GetUnitFactor())
    double ConvertFromUnit(double x) const; //!< Get a value from the current length / scale unit. (x * GetUnitFactor()) / scale_factor)
    CXString GetUnitText(bool abreviation) const; //!< Return a text that describe the unit of the scene (ie. "centimers" or "cm" if abbreviation is true)
    bool IsUnitDefined() const; //!< Return false if unit has not been defined when reading file. This means that we are not able to convert the coordinates to a real size value.
    UNIT_MODE GetUnit() const; //!< By default UNIT_UNDEFINED is set unless the format specify it. C3DVector(1, 0, 0) has a length of 1 cm, unless GetScaleFactor is used to define another scale (ie. SetScaleFactor(100), means that C3DVector(1, 0, 0) has a length of 1 meter)
    void SetUnit(UNIT_MODE unit); //!< Set the scene unit
    double GetScaleFactor() const; //!< Return scene scale. Multiply the coordinates by this scale to get an information expressed in centimers
    void SetScaleFactor(double scale); //!< Define the scale factor, which is the coordinate multiplied by this factor to get values in centimers.
    static double GetUnitFactor(UNIT_MODE unit); //!< Return the value needed to convert centimer to the given unit. Ie. if unit = UNIT_M, the method will return 100.
 
    //! @}
 
    //! @name Scene node tree traversal
    //! Different methods to traverse the node's tree
    //! @ref TRAVERSAL
    //! @{
    bool IsChildNode(C3DSceneNode *parent, C3DSceneNode *node) const;
    C3DNodePos GetFirstNode(unsigned int kindof = OBJECT_ALL_KINDOF, unsigned int traverseFlags = NODEPOS_DEFAULT, const C3DSceneNode *startNode = NULL, const C3DSceneNode *stopNode = NULL) const;
    C3DNodePos GetFirstNode(const C3DSceneNode *startNode, unsigned int traverseFlags = NODEPOS_DEFAULT, const C3DSceneNode *stopNode = NULL) const;
    C3DSceneNode * GetNextNode(C3DNodePos & pos) const; //!< Return only the node (don't care about the object which can be obtained using C3DSceneNode::GetBaseObject())
    C3DSceneNode *GetNextNode(C3DBaseObject *&object, C3DNodePos& pos) const; //!< Return the node and it's object
    C3DSceneNode *GetNextNode(C3DGeomObject *&object, C3DNodePos& pos) const; //!< GetFirstNode must define OBJECT_GEOM when using this version
    C3DSceneNode *GetChildNode(const C3DSceneNode *node = NULL) const;
    C3DSceneNode *GetRightNode(const C3DSceneNode *node) const;
    C3DSceneNode *GetParent(const C3DSceneNode *node) const;
 
    //! @}
 
    //! @name Node retrievial
    //! Different methods to retrieve nodes
    //! @{
    bool IsSceneRoot(const C3DSceneNode *node) const;
    bool IsNodeInScene(C3DSceneNode *pParentNode = NULL) const;
 
    unsigned int GetNodesByText(C3DSceneNode* pParent, const CXString& filter, bool matchCase, C3DNodeArray& nodes, bool resetArray = true);  //!< Advanced search: find all nodes which name match the given regular expression
    C3DSceneNode* GetNodeByName(C3DSceneNode* pParent, const CXString& name) const; //!< Beware node names are not supposed to be single. The first node encountered with the given name is returned by this method
    C3DSceneNode* GetNodeByID(SceneNodeID id, bool is32BitsID = false) const; //!< If is32BitsID, the method lookl for 32 bits ID get with GetNodeID32() method
 
    int GetNodeDepth(C3DSceneNode* pNode = NULL) const; //!< Return the node depth.A direct child of the root as the depth 0.
    int GetDirectChildCount(C3DSceneNode *pParentNode = NULL, unsigned int kindof = OBJECT_ALL_KINDOF) const; //!< Return the number of child below the given node (direct childs)
    int GetChildCount(C3DSceneNode *pParentNode = NULL, unsigned int kindof = OBJECT_ALL_KINDOF, unsigned int nodeFlag = SCENE_NODE_NONE, bool mustBeSet = true) const; //!< Return the number of child below the given node (all branch) of the given type and with the given flags (or not)
    C3DSceneNode* GetCommonParent(const C3DNodeArray& nodes) const; //!< Return the upper common parent in the hierarchy to the provided nodes
 
    unsigned int GetNodeIDMap(C3DSceneNodeIDMap& nodes, bool create32BitsIDMap) const; //!< Get a map that allows to get a C3DSceneNode from a SceneNodeID. If create32BitsIDMap, the method creates for 32 bits ID map
    //! @}
 
    //! @name Add / remove / copy nodes from scene
    //! The following methods attach / detach the node and its object to / from the scene and eventually update the elements GUID to avoid GUID conflict in the scene   
    //! @{
    unsigned int SetNodeObject(C3DSceneNode* node, C3DBaseObject* newobject, bool allObjectInstance, bool deletePreviousObject = true); //!< Replace node object with newobject and detach it from the scene. Replaces all object instance is needed. if newobject GUID and node object GUID is the same, the method avoid a new GUID being generated
    unsigned int SetNodeObject(BaseObjectID objectID, C3DBaseObject* newobject, bool deletePreviousObject = true); //!< Replace all objectID instances with the new object. If object is not deleted, it is detached from the scene and does not belong to it anymore
 
    C3DBaseObject* GetObjectByID(BaseObjectID id) const; //!< Look for object id through the whole scene. The first node with this ID is returned. As multiple nodes might reference id, this is better to use C3DScene::GetInstancesByID
 
    void AddNode(C3DSceneNode *parentNode, C3DSceneNode *node, bool lastNode = false); //!< Add a node to the scene which parent is parentNode. node is attached to the scene, and its child if it has some. if lastNode = true, the node is the last of its branch (slower)
    void DetachAndAddNode(C3DSceneNode* parentNode, C3DSceneNode* node, bool lastNode = false); //!< Same has AddNode, but remove the node from a previous scene if needed.
    bool ReplaceNode(C3DSceneNode * newNode, C3DSceneNode * oldNode, bool deleteOldNode); //!< Replace oldNode by newNode. newNode is attached to oldNode childs, and become a child of oldNode parent.
    bool ChangeNodeParent(C3DSceneNode *newParent, C3DSceneNode * node, bool updateMatrix = true ); //!< Attach node with its child to newParent. Matrix are update accordingly
    void RemoveAll();
    void RemoveAllNodes();
    C3DSceneNode *RemoveNode(C3DSceneNode *node, bool deleteIt = true); //!< Remove or delete a node from the scene graph. Childs are also removed, if any. Return the previous valid node in the scene. Return NULL if node can't be delete.
    bool RemoveNode(C3DSceneNode *node, C3DNodePos& pos, bool deleteIt = true); //!< Remove or delete the node (and its childs) from the scene graph. This version is to use when traversing the graph because if modify the node pos to the previous node. Return true if ok.
    unsigned int RemoveNodeByObjectID(C3DSceneNode *pParentNode, BaseObjectID objectID, bool deleteObject = true); //!< Remove all node that reference objectID. if deleteObject = false, the last object reference is kept
    unsigned int RemoveNodes(C3DNodeArray& nodes, bool deleteThem = true, bool cleanTree = true); //!< Remove or delete the nodes (and their childs) from the scene graph. if cleanTree = true, the empty groups of the tree are removed
    bool DeleteNodes(C3DSceneNode *node = NULL, const C3DFilter* filter = NULL, bool includeNode = false); //!< Delete the node descendance that match the C3DFilter criteria. if includeNode = true, the node itself is considered to be deleted
    bool MergeMatrixKeyframes(C3DSceneNode *fromNode, C3DSceneNode *toNode); //!< Multiply toNode's Matrix Keyframes by fromNode's ones.
 
    int ConvertToType(C3DSceneNode *parentNode, C3DObjectCreator *objectCreator); //!< perform object type conversion. Return number of object that has been modified.
    int DeleteInstanciation(C3DSceneNode *pParentNode = NULL); //!< Remove instanciation for the pParentNode and its childrend and replace it by a real copy. Return the number of instanciated object that were modified.
    void Inherit(const C3DScene *pFromScene, unsigned int flags = SCENE_COPY_DEFAULT);
    void InheritNode(C3DScene *pDestScene, C3DSceneNode *pSrcNode, unsigned int flags) const;
    C3DSceneNode *CopySingleNode(C3DScene *pDstScene, C3DSceneNode *pDestParentNode, C3DSceneNode *pSrcNode, int flags = SCENE_COPY_DEFAULT, C3DObjectCreator *objectCreator = NULL) const; //!< Copy only the node
    C3DSceneNode *CopyNode(C3DScene *pDstScene, C3DSceneNode *pDestParentNode, C3DSceneNode *pSrcNode, int flags = SCENE_COPY_DEFAULT, C3DObjectCreator *objectCreator = NULL) const; //!< Copy the node and its childs
    void CopyChilds(C3DScene *pDstScene, C3DSceneNode *pDestParentNode, C3DSceneNode *pParentNode = NULL, int flags = SCENE_COPY_DEFAULT, C3DObjectCreator *objectCreator = NULL) const; //!< Copy only node's childs
    C3DScene *Copy(C3DSceneNode *pSrcNode = NULL, int sceneCopyflags = SCENE_COPY_DEFAULT, C3DObjectCreator *objectCreator = NULL) const; //!< Return a copy of the scene, or NULL if the scene does not contains any node (unless SCENE_COPY_EMPTY_HIERARCHY is set)
    bool AddScene(const C3DScene *scene, int sceneCopyflags = SCENE_COPY_DEFAULT, C3DObjectCreator *objectCreator = NULL); //!< Copy scene to the current scene using sceneCopyflags
    bool Merge(C3DScene *sceneToMerge, C3DSceneNode *parentNode = NULL); //!< Merge sceneToMerge to parentNode or the root of the current scene. All sceneToMerge nodes are moved to the current scene (without copy), and sceneToMerge is deleted
    void Sort(C3DSceneNode* pParentNode = NULL, bool sortDirectChildOnly = false, unsigned int kindof = OBJECT_ALL_KINDOF, unsigned int nodeFlag = SCENE_NODE_NONE, bool mustBeSet = true, XQSORT_PROTO compareMethod = NULL, void* userData = NULL); //!< Sort scene using compareMethod. If compareMethod = NULL a sort by name is done, otherwise the compare method can be assimiled to void SortkMethod(const C3DSceneNode **node1, const C3DSceneNode **node2, SortSceneData *data)
    virtual void Serialize(CXArchive& ar);
 
    //! @}
 
    //! @name Object instanciation
    //! Object are referenced by their BaseObjectID. It is possible to create several instance on a given BaseObjectID. Each instances are attached to a specific C3DSceneNode
    //! @{
    C3DSceneNode *CreateInstance(const C3DSceneNode *node); //!< Instanciate the the object node and object subnode. Returned node, contains a node (with possibily sub nodes) that reference an instanciated object
    C3DBaseObject *CreateObjectInstance(const C3DBaseObject *refObject) const; //!< Create an instance of the given object. The returned instanciated node must be attached to a node then inserted into the scene
 
    unsigned int GetInstancesMap(C3DInstanceMap& instances) const; //!< Init an instance map when multiple call to GetInstancesByID is required. Return the number of instance sets.
    unsigned int GetInstancesByID(C3DSceneNode *pParentNode, C3DSceneNode *refnode, C3DNodeArray& nodes, bool resetArray) const; //!< Retrieve nodes that contains instance of object contained by refnode. Internally, the method looks if the object is instanciated and call the below method. This method does not traverse the scene if the node contains an object which is not instanciated.
    unsigned int GetInstancesByID(C3DSceneNode *pParentNode, BaseObjectID id, C3DNodeArray& nodes, bool resetArray) const; //!< Get nodes which object are instance of id. It adds the node itself if node is not instanciated. This method is slower than GetInstancesByID version above, because it traverse the scene each time it is called, wether or not the object is instanciated.
    unsigned int GetInstancesCount(C3DSceneNode* pParentNode, BaseObjectID id) const; //!< return the number of instance found in pParentNode branch.
    
    //! @}
 
    //! @name Scene default setting
    //! @{
    void SetSmoothAngle(float radianAngle, bool saveToPrefs = false);
    void SetSmoothMode(NormalSmoothMode mode, bool saveToPrefs = false);
    float GetSmoothAngle() const; //!< Return smooth angle in radian
    NormalSmoothMode GetSmoothMode() const;
    void SetPatchLevel(unsigned int level);
 
    //! @}
 
    //! @name Information about the scene
    //! @{
    C3DBBox GetBoundingBox(const C3DNodeArray& nodes) const;
    int GetBoundingBox(C3DBBox& bbox, C3DSceneNode* pParentNode = NULL, unsigned int kindof = OBJECT_ALL_KINDOF, unsigned int nodeFlag = SCENE_NODE_NONE, bool mustBeSet = true) const; //!< Return the number of node found that satisfies the condition
    int GetFaceNbr(C3DSceneNode* pParentNode = NULL, unsigned int kindof = OBJECT_ALL_KINDOF, unsigned int nodeFlag = SCENE_NODE_NONE, bool mustBeSet = true) const;
    int GetPointNbr(C3DSceneNode* pParentNode = NULL, unsigned int kindof = OBJECT_ALL_KINDOF, unsigned int nodeFlag = SCENE_NODE_NONE, bool mustBeSet = true) const;
 
    //! @}
 
    //! @name Selection
    //! @{
    void SelectAll();
    void SelectNone();
    void Unselect(C3DSceneNode *node);
    int Select(C3DSceneNode *node, unsigned int sceneSelectionFlags); //!< SelectionFlags is a combination of SceneSelectionFlags. Return the number of newly selected objects
    bool IsNodeSelected(unsigned int kindof = OBJECT_ALL_KINDOF) const; //!< Return true if one node is selected
    unsigned int GetNodesByFilter(C3DSceneNode* pParentNode, C3DNodeArray& nodes, const C3DFilter *filter = NULL) const; //!< Get nodes filtered by filter (or not) for the whole scene (pParentNode == NULL) or for the pParentNode childs (including itself). If filter is NULL there is no filtering and the whole scene nodes might be retrieved.
    unsigned int GetSelectedNodes(C3DSceneNode * pParentNode, C3DNodeArray& nodes, unsigned int kindof = OBJECT_ALL_KINDOF) const; //!< Get selected nodes for the whole scene (pParentNode == NULL) or for the pParentNode childs (including itself)
    unsigned int GetSelectedNodeNumber(C3DSceneNode* pParentNode = NULL, unsigned int kindof = OBJECT_ALL_KINDOF) const; //!< Get selected node count for the whole scene (pParentNode == NULL) or for the pParentNode childs (including itself)
 
    //! @}
 
    //! @name Animation
    //! @{
    CTimeRange GetTimeRange(longuint classid = KEYFRAME_NULLID) const;
    const C3DKeyframe *GetConstKey(int time, unsigned int pos, longuint classid, int *findKeyTime) const;
    int GetCurrentTime() const;
    bool SetCurrentTime(int newtime);
    void DeleteAllKeys();
 
    //! @}
 
    //! @name Prepare scene before Import / Export 
    //! @{
    void CheckoutImport(CSceneImportOptions& options); //!< This method is called after scene is imported using C3DIo::Read. It prepares the scene following the import requirements.
    C3DScene *InitExport(CSceneExportOptions& options); //!< this method is called before the scene is save using C3DIo::Save. It returns a scene copy (unless SCENE_EXPORT_COPY is used) following the export requirements.
    static bool InitExport(CSceneExportOptions& options, C3DScene *scene);
    static void ReleaseExport(CSceneExportOptions& options);
 
    //! @}
 
    //! @name Modifying scene content
    //! These methods allows to modify a node, a particular branch of the scene, or the whole scene.
    //! @{
    int ConvertToGlobalCoordinates(C3DSceneNode *pParentNode = NULL, bool includeNodeItself = false); //!<  Convert a node and its child to global coordinates. Return the number of node changed.
    void Scale(const C3DVector& scale);
 
    void PivotTransform(C3DSceneNode* node, const C4x4Matrix& toTransform, bool worldTransform, bool preserveChildPosition = true, bool preserveInstancePosition = true);
 
    void CompensateTransform(C3DSceneNode* node, const C4x4Matrix& transform); //!< Transform the points with the given matrix but apply the equivalent transform to the node, so the scene stays globally unchanged. This allows to recenter points around origin for example or avoid too small edge length.
 
    bool OrientScene(UP_AXIS_MODE mode, bool import); //!< return true if something changed
    bool SwapCoordinates(int swapmode); //!< return true if something changed
    bool GenerateNormals(C3DSceneNode *node = NULL, unsigned int mode = GENNORMAL_PER_VERTEX, NormalSmoothMode smooth = NORMAL_GLOBAL_MODE); //!< Generate normal in multithread process. Mode is one or a combination of GENNORMAL_MODE (if GENNORMAL_SPEC_CHANNEL is used). Return true if at least one normal has been computed, false if nothing need to be computed
    bool DisconnectBorderFaces(unsigned int channelType = ALL_CHANNELS_TYPE, unsigned int tagPointsFlags = POINT_BELONG_TO_BORDER|POINT_IS_CONFUSED, unsigned int tagFaceFlags = FACE_IS_BORDER|FACE_HAS_CONFUSED_POINTS);
    void Clean();
    bool MakeGroupForChilds(C3DSceneNode *pParentNode = NULL); //!< If an object has a child, make this child being attached to a C3DGroup instead. This guarantee that all object are leaves only.
    unsigned int CleanGroups(C3DSceneNode *pParent = NULL, bool onlyEmptyGroup = true, bool includeNodeItself = false); //!< Return the number of group removed
    void RemoveGroups();
    void CreatePersistentGuids(); //!< Give each node a persitent GUID based on mix of name, node properties and hierarchy position. This ID is made to be able to find back a specific node even if file has been modified
 
    //! Return a single node from the pParentNode childs (which can be selected by a C3DFilter).\n
    //! This node is automatically substituted to the nodes and added to scene root (if !CONCATENATE_KEEP_PARENT) is set to true.
    //! @param C3DFilter::ProcessNode can exclude some node in the processing. In such case, the branch might still contain some elements, and empty group might remain. If required, you may call CleanGroups to remove such elements.
    //! @return The returned node can be an existing node, if the parent when the parent has a single child and the caller ask to replace the node (and if there is no filter define and no special processing are request)
    C3DSceneNode *Concatenate(C3DSceneNode *pParentNode = NULL, unsigned int concatenateFlags = CONCATENATE_REMOVE_TO_ROOT|CONCATENATE_SORT_BY_MATERIAL, C3DConcatenateFilter *filter = NULL, C3DNodeArray* processedMeshes = NULL);
    int ConcatenateByMaterials(C3DSceneNode *parentNode = NULL, unsigned int concatenateFlags = CONCATENATE_REMOVE_TO_ROOT, C3DConcatenateFilter *filter = NULL, C3DNodeArray *createdNodes = NULL);
 
    //! Generate UV for the whole scene for material which have the planar/spherical/cubic projection type.\n
    //! Materials are modified and projection type is turned to UVW
    bool GenerateUVW();
 
    //! When an object has different front and backface materials, this create a new node that contains the back face content.
    //! @param createBackFaceFlags
    //! #BACKFACE_FBGEOM, if an object have double-sided material faces, then the whole object is duplicated. If such object has 100 faces, but only 10 are double sided, then a new node with 100 faces is created. If an object has no back face material, it is no duplicated.
    //! #BACKFACE_FBFACE_ONLY, only double sided material faces are duplicated. If an object has 100 faces, but only 10 are double sided, then a new node with 10 faces is created.
    //! In that case, a face is not duplicated if its front when its front material is transparent.
    unsigned int CreateBackfaceNodes(C3DSceneNode *pParentNode = NULL, unsigned int createBackFaceFlags = BACKFACE_DEFAULT, C3DFilter *pFilter = NULL);
 
    //! @}
 
    //! @name Textures path
    //! Different methods related to textures
    //! @{
    bool AddTexturePath(const CXString& path); //!< Add a specific texture path for the scene. The path is not added to preferences. Return true if the path is new, false if already added. Useful for format that embed textures (sketchup, kmz, fbx...)
    bool GetTexturePath(int index, CXString& path) const; //!< Get ith scene texture path, starting with index 0. Returns false if there is no path for the index, meaning that no more paths exists.
    int GetTexturePaths(CXStringArray& paths, bool removeAll = true) const; //!< Get scene texture path, and return the paths size (including any previous one, if removeAll = false)
    bool CopyTextures(const CXString& sceneFilename, const CXString& refDstPath, CSceneExportOptions *options);
    void AdjustPaths(const CXString& targetPath, bool relativePathAllowed); //!< This adjusts paths of files in relation with the scene in order to make them relative to the scene path. This can also resolves some issues with file which are incorrectly located (ie. texture maps, that are presume to be in a given folder but are finally in the scene folder)
    int GetLinkedFiles(CXStringArray& files, bool pathRelativeToScenePath = true, bool textureOnly = false) const; //!< This returns a list of file that are in relation with the scene (texture files...). When pathRelativeToScenePath, the returned path are relative to the scene path when they are contained in the scene folder.
 
    //! @}
    
    //! @name Materials
    //! @{
    C3DMaterial *CreateNewMaterial(MATERIAL_CLASS materialClass); //!< Create material with automatic ID assignment
    C3DMaterial* CreateNewMaterial(MaterialID& matID, MATERIAL_CLASS materialClass); //!< Create material providing an ID (which might be modified if it already exists)
    MaterialID AddNewMaterial(C3DMaterial *material); //!< Add a material that has been created from scratch and which is not attached to any material list. The materialID is kept unless a material already exists with the same id. In that case, the new and different materialID assigned to the material is returned.
    bool RemoveMaterial(MaterialID matid, bool deleteIt = true); //!< Remove the material from the scene. This does not modify object material association, and face that used that materials remains unchanged
    const CMaterials& GetMaterials() const;
    HashPos GetFirstMaterial() const; //!< if matclass = MATERIAL_CLASS_UNDEFINED, return all type of materials, otherwise return materials of the given class
    C3DMaterial *GetNextMaterial(HashPos& pos) const; //!< if defined matclass should be the same than the one use in GetFirstMaterial
    unsigned int GetMaterials(C3DMaterialArray& mats, bool resetArray = true, MATERIAL_CLASS matclass = MATERIAL_CLASS_UNDEFINED) const; //!< Fill the material array and return the number of scene's material of the given class (or all class if MATERIAL_CLASS_UNDEFINED specified).
    int GetMaterialNumber(MATERIAL_CLASS matclass = MATERIAL_CLASS_UNDEFINED) const;
 
    int GetFBMaterials(C3DSceneNode * pParentNode, CFBMaterialHashMap & fbmatids, bool resetHash) const; //!< Collect front and back face material pairs referenced by pParentNode and childs. CFBMaterialHashMap is a map that associate a fbmaterial to the number of object that reference the material.
    int GetMaterials(C3DSceneNode *pParentNode, CMaterialHashMap& materials, bool resetHash) const; //!< Collect the materials referenced by pParentNode and childs. CMaterialHashMap is a map that associate a material to the number of object that reference the material.
    int GetChilds(C3DSceneNode* pParentNode, C3DNodeArray& array, bool singleInstance = false, bool includeParentNode = false) const; //!< Get childs of a node and potentially the node itself. If singleInstance = true, only one instance of a given object is added to the array
    int GetNodesByMaterial(C3DSceneNode *pParentNode, MaterialID matid, C3DNodeArray& array, bool resetArray, C3DFilter* filter = NULL) const;
    int GetNodesByType(C3DSceneNode *pParentNode, unsigned int objectKindof, C3DNodeArray& nodes, bool singleInstance, bool resetArray) const;
    int GetNodesByFlags(C3DSceneNode* pParentNode, unsigned int nodeflags, bool nodeflagset, unsigned int objectflags, bool objectflagset, C3DNodeArray& nodes, bool singleInstance, bool resetArray, unsigned int objectKindof = OBJECT_ALL_KINDOF) const; //!< Return the nodes that matches the required flags. When singleInstance = true, this return the first node found of a given instance. If a flag is required (is NODE_IS_SELECTED), this return the first instance of the node with the selected flag (the flag might be missing for other node instance).
    void SortNodesByDepth(C3DNodeArray& array, bool highToSmallDepth = true) const; //!< Sort a node array by its depth in the hierarchy from highest to smallest depth or the inverse if highToSmallDepth = false
    void CopyMaterials(const C3DScene& scene, unsigned int flags = MATERIAL_COPY_KEEP_ID|MATERIAL_COPY_REMOVE_ALL, const CMaterialHashMap *matids = NULL);
    bool ReplaceNodeMaterialID(C3DSceneNode* pParentNode, MaterialID srcmatid, MaterialID newmatid, unsigned int replaceNodeMaterialIDFlags = REPLACEMATID_DEFAULT); //!< Replace all occurences of srcmatid in the pParentNode childs with newmatid. replaceNodeMaterialIDFlags is one or more ReplaceMatIDFlags flags
 
    unsigned int GetMaterialsByText(const CXString& filter, bool matchCase, C3DMaterialIDArray& matids, bool resetHash); //!< Advanced search: find all materials which name match the given text
 
    C3DMaterial* GetMaterialByName(const CXString& name) const; //!< Beware material names are not supposed to be single. The first material encountered with a given name is returned by this method
    C3DMaterial* GetMaterialByID(MaterialID id, bool createIfMissing = false, MATERIAL_CLASS materialClass = MATERIAL_CLASS_STANDARD); //!< Find a material given its id. Return NULL if does not exists, or create it if createIfMissing = true
    C3DMaterial* GetMaterialByID2(MaterialID id, MATERIAL_CLASS materialClass) const; //!< Find a material given its id. if materialClass is specified, the material is returned only if it has the given class. NULL otherwise.
    C3DMaterial *FindMaterial(const C3DMaterial& material, bool sameName) const;
    MaterialID FindMaterialID(const C3DMaterial& material, bool sameName) const;
    MaterialID GetMaterialID(const CXString& name); //!< Same has GetMaterialByID except it returns a MaterialID.
 
    //! @}
 
    CTree *GetTree() { return this; } //!< CTree base class has protected access, so use this with precaution
    CGuidMgr& GetGuidMgr() { return guidMgr; }
 
protected:
    CParserSceneInfo *parserInfo;
    CGuidMgr guidMgr;
    CCustomData sceneData;
    CMaterials materials;
    int currentTime;
 
    bool CopyTextureFile(const CXString& srcfile, const CXString& dstPath, CXString& newFilePath, CSceneExportOptions *options);
    void CheckoutNode(CSceneImportOptions& options);
    void ReleaseParserInfo();
    void UpdateParenting(C3DScene *scene, C3DSceneNode *node); // Parenting changed for node, which now belong to scene. If scene is NULL, node, does not belong to anything.
};
 
END_MOOTOOLS_NAMESPACE
 
#endif // !defined(AFX_3DScene_H__CA6BC29F_FAC2_11D1_A0DE_000000000000__INCLUDED_)