1 /* 2 Copyright (C) 2005-2007 Feeling Software Inc. 3 Portions of the code are: 4 Copyright (C) 2005-2007 Sony Computer Entertainment America 5 6 MIT License: http://www.opensource.org/licenses/mit-license.php 7 */ 8 /* 9 Based on the FS Import classes: 10 Copyright (C) 2005-2006 Feeling Software Inc 11 Copyright (C) 2005-2006 Autodesk Media Entertainment 12 MIT License: http://www.opensource.org/licenses/mit-license.php 13 */ 14 15 /** 16 @file FCDEntityInstance.h 17 This file contains the FCDEntityInstance class. 18 */ 19 20 #ifndef _FCD_ENTITY_INSTANCE_H_ 21 #define _FCD_ENTITY_INSTANCE_H_ 22 23 #ifndef _FCD_ENTITY_H_ 24 #include "FCDocument/FCDEntity.h" 25 #endif // _FCD_ENTITY_H_ 26 27 class FCDocument; 28 class FCDENode; 29 class FCDSceneNode; 30 class FCDEntityInstanceFactory; 31 class FCDEntityReference; 32 class FCDEntityInstance; 33 class FUUri; 34 35 template <class T> class FUUniqueStringMapT; 36 typedef FUUniqueStringMapT<char> FUSUniqueStringMap; /**< A set of unique strings. */ 37 38 /** 39 A COLLADA entity instance. 40 COLLADA allows for quite a bit of per-instance settings 41 for entities. This information is held by the up-classes of this class. 42 This base class is simply meant to hold the entity that is instantiated. 43 44 The entity instance tracks the entity, so that when an entity is released, 45 all its instances are released. 46 47 @ingroup FCDocument 48 */ 49 class FCOLLADA_EXPORT FCDEntityInstance : public FCDObject, FUTracker 50 { 51 public: 52 /** The class type of the entity instance class. 53 Used this information to up-cast an entity instance. */ 54 enum Type 55 { 56 SIMPLE, /**< A simple entity instance that has no per-instance information. 57 This is used for lights, cameras, physics materials and force fields: there is no up-class. */ 58 GEOMETRY, /**< A geometry entity(FCDGeometryInstance). */ 59 CONTROLLER, /**< A controller entity(FCDControllerInstance). */ 60 MATERIAL, /**< A material entity(FCDMaterialInstance). */ 61 PHYSICS_MODEL, /**< A physics model(FCDPhysicsModelInstance). */ 62 PHYSICS_RIGID_BODY, /**< A physics rigid body(FCDPhysicsRigidBodyInstance). */ 63 PHYSICS_RIGID_CONSTRAINT, /**< A physics rigid constraint(FCDPhysicsRigidConstraintInstance). */ 64 PHYSICS_FORCE_FIELD, /**< A physics force field (FCDPhysicsForceFieldInstance). */ 65 TYPE_COUNT 66 }; 67 68 private: 69 DeclareObjectType(FCDObject); 70 friend class FCDEntityInstanceFactory; 71 72 FCDSceneNode* parent; // May be NULL for non-scene graph instances. 73 FCDEntity::Type entityType; 74 DeclareParameterPtr(FCDEntityReference, entityReference, FC("Entity Reference")); 75 76 // common attributes for instances 77 fstring name; 78 DeclareParameter(fm::string, FUParameterQualifiers::SIMPLE, wantedSubId, FC("Instance Sub-id")); 79 80 // Extra information for the entity instance. 81 DeclareParameterRef(FCDExtra, extra, FC("Extra Tree")); 82 83 protected: 84 /** Constructor: do not use directly. 85 Instead, use the appropriate allocation function. 86 For scene node instance: FCDSceneNode::AddInstance. 87 @param document The COLLADA document that owns the entity instance. 88 @param parent The visual scene node that contains the entity instance. This pointer will be NULL for 89 instances that are not directly under a visual scene node. 90 @param type The type of entity to instantiate. */ 91 FCDEntityInstance(FCDocument* document, FCDSceneNode* parent, FCDEntity::Type type); 92 93 public: 94 /** Destructor. */ 95 virtual ~FCDEntityInstance(); 96 97 /** Retrieves the entity instance class type. 98 This is used to determine the up-class for the entity instance object. 99 @deprecated Instead use: FCDEntityInstance::HasType(). 100 @return The class type: SIMPLE for entity instances with no up-class. */ GetType()101 virtual Type GetType() const { return SIMPLE; } 102 103 /** Retrieves the instantiated entity type. 104 The instantiated entity type will never change. 105 @return The instantiated entity type. */ GetEntityType()106 inline FCDEntity::Type GetEntityType() const { return entityType; } 107 108 /** Retrieves the instantiated entity. If the entity is an external reference, 109 this may load the external document and retrieve the entity. 110 @return The instantiated entity. */ 111 FCDEntity* GetEntity(); 112 113 /** Retrieves the instantiated entity. If the entity is an external reference, 114 this function will load the entity. Be careful when using this function 115 since it will change the object. 116 @return The instantiated entity, if loaded. */ GetEntity()117 inline const FCDEntity* GetEntity() const { return ((FCDEntityInstance*)(this))->GetEntity(); } 118 119 /** Retrieves the Uri to the skin target. 120 This can be an internal or external link 121 @return The uri to the target */ 122 const FUUri GetEntityUri() const; 123 124 /** Sets the URI of the target mesh. 125 @param uri The Uri to a local or external controller or geometry */ 126 void SetEntityUri(const FUUri& uri); 127 128 /** Sets the instantiated entity. 129 The type of the entity will be verified. 130 @param entity The instantiated entity. */ 131 void SetEntity(FCDEntity* entity); 132 133 /** Get the contained EntityReference object. */ GetEntityReference()134 inline FCDEntityReference* GetEntityReference() { return entityReference; } GetEntityReference()135 inline const FCDEntityReference* GetEntityReference() const { return entityReference; } /**< See above */ 136 137 /** Retrieves the name of the entity instance. This value has no direct use 138 in COLLADA but is useful to track the user-friendly name of an entity 139 instance. 140 @return The name. */ GetName()141 inline const fstring& GetName() const { return name; } 142 143 /** Sets the name of the entity instance. This value has no direct use in 144 COLLADA but is useful to track the user-friendly name of an entity 145 instance. 146 @param name The name. */ 147 void SetName(const fstring& name); 148 149 /** Retrieves the optional sub id and is not garanteed to exist. 150 This id is the same as that given in SetSubId or from the COLLADA document using LoadFromXML unless it clashes with another id and 151 CleanSubId has been called. 152 @return The set sub id of the node. */ GetWantedSubId()153 inline const fm::string& GetWantedSubId() const { return wantedSubId; } 154 155 /** Sets the sub id for this object. 156 This id must be unique within the scope of the parent element. If it is not, it can be corrected by calling CleanSubId. 157 @param _wantedSubId The new sub id of the object. */ SetWantedSubId(const fm::string & _wantedSubId)158 inline void SetWantedSubId(const fm::string& _wantedSubId) { wantedSubId = _wantedSubId; } 159 160 /** Retrieves the extra information tree for this entity instance. The 161 prefered way to save extra information in FCollada is at the entity 162 level. Use this extra information tree to store any information you 163 want exported and imported back. 164 @return The extra information tree. */ 165 FCDExtra* GetExtra(); GetExtra()166 inline const FCDExtra* GetExtra() const { return const_cast<FCDEntityInstance*>(this)->GetExtra(); } /**< See above. */ 167 168 /** Retrieves whether this entity instance points to an external entity. 169 @return Whether this is an external entity instantiation. */ 170 bool IsExternalReference() const; 171 172 /** Retrieves the parent of the entity instance. 173 @return the parent visual scene node. This pointer will be NULL 174 when the instance is not created in the visual scene graph. */ GetParent()175 inline FCDSceneNode* GetParent() { return parent; } GetParent()176 inline const FCDSceneNode* GetParent() const { return parent; } /**< See above. */ 177 178 /** Checks whether or not this instance is below the given scene node in 179 the scene hierarchy. 180 @param node The scene node. 181 @return True if parent is above this instance in the hierarchy, false otherwise.*/ 182 bool HasForParent(FCDSceneNode* node) const; 183 184 /** [INTERNAL] Cleans up the sub identifiers. 185 The sub identifiers must be unique with respect to its parent. This method corrects the sub ids if there are conflicts. 186 @param parentStringMap The string map from the parent of this instance in which the sub ids must be unique. */ 187 virtual void CleanSubId(FUSUniqueStringMap* parentStringMap = NULL); 188 189 /** Clones the entity instance. 190 @param clone The entity instance to become the clone. 191 @return The cloned entity instance. */ 192 virtual FCDEntityInstance* Clone(FCDEntityInstance* clone = NULL) const; 193 194 protected: 195 /** [INTERNAL] Retrieves the COLLADA name for the instantiation of a given entity type. 196 Children can override this method to easily add more class types. 197 @param type The entity class type. 198 @return The COLLADA name to instantiate an entity of the given class type. */ 199 //virtual const char* GetInstanceClassType(FCDEntity::Type type) const; 200 201 /** Callback when the instantiated entity is being released. 202 @param object A tracked object. */ 203 virtual void OnObjectReleased(FUTrackable* object); 204 }; 205 206 /** 207 [INTERNAL] A factory for COLLADA Entity instances. 208 Creates the correct instance object for a given entity type/XML tree node. 209 To create new instances, use the FCDSceneNode::AddInstance function. 210 */ 211 class FCOLLADA_EXPORT FCDEntityInstanceFactory 212 { 213 private: FCDEntityInstanceFactory()214 FCDEntityInstanceFactory() {} // Static class: do not instantiate. 215 216 public: 217 /** Creates a new COLLADA instance, given a entity type. 218 @param document The COLLADA document that will own the new instance. 219 @param parent The visual scene node that will contain the instance. 220 @param type The type of instance object to create. 221 @return The new COLLADA instance. This pointer will be NULL 222 if the given type is invalid. */ 223 static FCDEntityInstance* CreateInstance(FCDocument* document, FCDSceneNode* parent, FCDEntity::Type type); 224 225 /** Creates a new COLLADA instance of a given entity. 226 @param document The COLLADA document that will own the new instance. 227 @param parent The visual scene node that will contain the instance. 228 @param entity The entity to create an instance of. 229 @return The new COLLADA instance. This pointer will be NULL 230 if the given type is invalid. */ 231 static FCDEntityInstance* CreateInstance(FCDocument* document, FCDSceneNode* parent, FCDEntity *entity); 232 }; 233 234 235 #endif // _FCD_ENTITY_INSTANCE_H_ 236