source: NonGTP/FCollada/FCDocument/FCDObject.h @ 964

/*
        Copyright (C) 2005-2006 Feeling Software Inc.
        MIT License: http://www.opensource.org/licenses/mit-license.php
*/

/**
        @file FCDObject.h
        This file contains the FCDObject and the FCDObjectWithId classes.
*/

#ifndef __FCD_OBJECT_H_
#define __FCD_OBJECT_H_

#include "FUtils/FUObject.h"
#include "FCDocument/FCDocument.h"

/**
        A basic COLLADA document object.
        
        All the objects owned by the COLLADA document derive from this class.
        The FCDocument object is accessible through this interface to all the object which it owns.

        Space for an handle which has no meaning to FCollada is available in this base class, for our users.
        You can therefore attach your own objects to most FCollada objects. If you assign memory buffers
        to the user-specified handle, be aware that FCollada will make no attempt to release it.

        @ingroup FCDocument
*/
class FCOLLADA_EXPORT FCDObject : public FUObject
{
private:
        DeclareObjectType;

        // An handle which has no meaning to FCollada but is available for users to
        // attach objects to most FCollada objects.
        void* userHandle;

        // Don't use this constructor directly.
        FCDObject(FUObjectContainer* container);

public:
        /** Constructor: sets the COLLADA document object.
                @param document The COLLADA document which owns this object. */
        FCDObject(FCDocument* document);

        /** Destructor. */
        virtual ~FCDObject() {}

        /** Retrieves the COLLADA document which owns this object.
                @return The COLLADA document. */
        inline FCDocument* GetDocument() { return (FCDocument*) GetContainer(); }
        inline FCDocument* GetDocument() const { return (FCDocument*) GetContainer(); } /**< See above. */

        /** Retrieves the object's user-specified handle.
                This handle is available for users and has no
                meaning to FCollada.
                @return The object user-specified handle. */
        inline void* GetUserHandle() const { return userHandle; }
        
        /** Sets the object's user-specified handle.
                This handle is available for users and has no
                meaning to FCollada.
                @param handle The user-specified handle. */
        inline void SetUserHandle(void* handle) { userHandle = handle; }
};

/**
        A basic COLLADA object which has a unique COLLADA id.
        
        Many COLLADA structures such as entities and sources need a unique COLLADA id.
        The COLLADA document contains a map of all the COLLADA ids known in its scope.
        The interface of the FCDObjectWithId class allows for the retrieval and the modification
        of the unique COLLADA id attached to these objects.

        A unique COLLADA id is built, if none are provided, using the 'baseId' field of the constructor.
        A unique COLLADA id is generated only on demand.

        @ingroup FCDocument
*/
class FCOLLADA_EXPORT FCDObjectWithId : public FCDObject
{
private:
        DeclareObjectType;

        string daeId;
        bool hasUniqueId;

public:
        /** Constructor: sets the prefix COLLADA id to be used if no COLLADA id is provided.
                @param document The COLLADA document which owns this object.
                @param baseId The prefix COLLADA id to be used if no COLLADA id is provided. */
        FCDObjectWithId(FCDocument* document, const char* baseId = "ObjectWithID");

        /** Destructor. */
        virtual ~FCDObjectWithId();

        /** Retrieves the unique COLLADA id for this object.
                If no unique COLLADA id has been previously generated or provided, this function
                has the side-effect of generating a unique COLLADA id.
                @return The unique COLLADA id. */
        const string& GetDaeId() const;

        /** Sets the COLLADA id for this object.
                There is no guarantee that the given COLLADA id will be used, as it may not be unique.
                You can call the GetDaeId function after this call to retrieve the final, unique COLLADA id.
                @param id The wanted COLLADA id for this object. This COLLADA id does not need to be unique.
                        If the COLLADA id is not unique, a new unique COLLADA id will be generated. */
        void SetDaeId(const string& id);

        /** Sets the COLLADA id for this object.
                There is no guarantee that the given COLLADA id will be used, as it may not be unique.
                @param id The wanted COLLADA id for this object. This COLLADA id does not need to be unique.
                        If the COLLADA id is not unique, a new unique COLLADA id will be generated and
                        this formal variable will be modified to contain the new COLLADA id. */
        void SetDaeId(string& id);

        /** [INTERNAL] Release the unique COLLADA id of an object.
                Use this function wisely, as it leaves the object id-less and without a way to automatically
                generate a COLLADA id. */
        void RemoveDaeId();

        /** [INTERNAL] Clones the object. The unique COLLADA id will be copied over to the clone object.
                Use carefully: when a cloned object with an id is released, it
                does remove the unique COLLADA id from the unique name map.
                @param clone The object clone. */
        void Clone(FCDObjectWithId* clone) const;
};

#endif // __FCD_OBJECT_H_