dali/public-api/modeling/entity.h

   1 #ifndef __DALI_ENTITY_H__
   2 #define __DALI_ENTITY_H__
   3
   4 /*
   5  * Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21
  22 // INTERNAL INCLUDES
  23 #include <dali/public-api/geometry/mesh.h>
  24
  25 namespace Dali
  26 {
  27
  28 class Entity;
  29 class Matrix;
  30 class Mesh;
  31 class ModelData;
  32 struct Vector4;
  33
  34 namespace Internal DALI_INTERNAL
  35 {
  36 class Entity;
  37 }
  38
  39 typedef std::vector<Entity>             EntityContainer;    ///< Container of Entity handles
  40 typedef EntityContainer::iterator       EntityIter;         ///< iterator for Entity container
  41 typedef EntityContainer::const_iterator EntityConstIter;    ///< const_iterator for Entity container
  42 typedef std::vector<unsigned int>       EntityMeshIndices;  ///< Container to hold indexes of meshes this entity uses in the associated Dali::Model.
  43
  44 /**
  45  * @brief A 3D model comprises a tree of named entities. Each entity has a
  46  * transform, regardless of type.
  47  *
  48  * It can contain zero or more meshes.  The entity names are used for
  49  * cross referencing, e.g. from animations or from bone structures.
  50  */
  51 class DALI_IMPORT_API Entity : public BaseHandle
  52 {
  53 public:
  54
  55   /**
  56    * @brief The entity type
  57    */
  58   enum EntityType
  59   {
  60     OBJECT, ///< A generic entity
  61     CAMERA, ///< The entity represents a camera
  62     LIGHT,  ///< The entity represents a light
  63   };
  64
  65   /**
  66    * @brief Create an uninitialized Entity; this can be initialized with Entity::New().
  67    *
  68    * Calling member functions with an uninitialized Dali::Object is not allowed.
  69    */
  70   Entity();
  71
  72   /**
  73    * @brief Create an initialized handle.
  74    *
  75    * @param[in] name The name of the entity
  76    * @return a handle to a newly allocated Dali resource
  77    */
  78   static Entity New(const std::string name);
  79
  80   /**
  81    * @brief Downcast an Object handle to Entity handle.
  82    *
  83    * If handle points to a Entity object the downcast produces valid
  84    * handle. If not the returned handle is left uninitialized.
  85    *
  86    * @param[in] handle to An object
  87    * @return handle to a Entity object or an uninitialized handle
  88    */
  89   static Entity DownCast( BaseHandle handle );
  90
  91   /**
  92    * @brief Destructor
  93    *
  94    * This is non-virtual since derived Handle types must not contain data or virtual methods.
  95    */
  96   ~Entity();
  97
  98   /**
  99    * @brief This copy constructor is required for (smart) pointer semantics.
 100    *
 101    * @param [in] handle A reference to the copied handle
 102    */
 103   Entity(const Entity& handle);
 104
 105   /**
 106    * @brief This assignment operator is required for (smart) pointer semantics.
 107    *
 108    * @param [in] rhs  A reference to the copied handle
 109    * @return A reference to this
 110    */
 111   Entity& operator=(const Entity& rhs);
 112
 113   /**
 114    * @brief Find an entity by name.
 115    *
 116    * The search includes this entity and it's children.
 117    * @param[in] name The search name.
 118    * @return    A handle to the searched entity, or an uninitialized handle if not found.
 119    */
 120   Entity Find(const std::string& name) const;
 121
 122   /**
 123    * @brief Set the name of the entity.
 124    *
 125    * @param[in] name The name for the entity.
 126    */
 127   void SetName(const char* name);
 128
 129   /**
 130    * @copydoc SetName(const char*)
 131    */
 132   void SetName(const std::string& name);
 133
 134   /**
 135    * @brief Get the name of the entity.
 136    *
 137    * @return The name of the entity.
 138    */
 139   const std::string& GetName() const;
 140
 141   /**
 142    * @brief Set the entity type.
 143    *
 144    * @param[in] type The entity's type, a member of the EntityType enumeration.
 145    */
 146   void SetType(const EntityType type);
 147
 148   /**
 149    * @brief Get the entity's type.
 150    *
 151    * @return The entity's type, a member of the EntityType enumeration.
 152    */
 153   EntityType GetType() const;
 154
 155   /**
 156    * @brief Set the transform matrix.
 157    *
 158    * @param[in] matrix The transform matrix
 159    */
 160   void SetTransformMatrix(Matrix& matrix);
 161
 162   /**
 163    * @brief Returns a reference to the transform matrix.
 164    *
 165    * @return The transform matrix
 166    */
 167   const Matrix& GetTransformMatrix() const;
 168
 169   /**
 170    * @brief Checks if the entity has children.
 171    *
 172    * @return true if the entity has children, otherwise false.
 173    */
 174   bool HasChildren() const;
 175
 176   /**
 177    * @brief Get the number of children.
 178    *
 179    * @return The number of children.
 180    */
 181   int NumberOfChildren() const;
 182
 183   /**
 184    * @brief Get the list of children.
 185    *
 186    * @return A reference to the list of children.
 187    */
 188   const EntityContainer& GetChildren() const;
 189
 190   /**
 191    * @brief Add an entity to the end of the child list.
 192    *
 193    * Sets the child's parent.
 194    * @param[in] child A handle to a child Entity.
 195    */
 196   void Add(Entity child);
 197
 198   /**
 199    * @brief Get the entity's parent.
 200    *
 201    * @return A pointer to the entity's parent.
 202    */
 203   Entity GetParent() const;
 204
 205   /**
 206    * @brief Change the size of storage allocated to the mesh index list.
 207    *
 208    * This may be greater than the number of indices stored as returned
 209    * by NumberOfMeshes.
 210    *
 211    * @param[in] capacity The new size of the storage allocated to the mesh
 212    * index list.
 213    */
 214   void SetMeshCapacity(unsigned int capacity);
 215
 216   /**
 217    * @brief Add a mesh to the entity.
 218    *
 219    * @param[in] meshIdx The mesh index into the model data's list of meshes
 220    */
 221   void AddMeshIndex(unsigned int meshIdx);
 222
 223   /**
 224    * @brief Checks if the entity references any meshes.
 225    *
 226    * @return true if the entity refers to 1 or more meshes, otherwise false.
 227    */
 228   bool HasMeshes() const;
 229
 230   /**
 231    * @brief Get the number of meshes referenced by this entity.
 232    *
 233    * @return The number of meshes referenced by this entity.
 234    */
 235   int NumberOfMeshes() const;
 236
 237   /**
 238    * @brief Returns a mesh in the model's mesh array.
 239    *
 240    * @param[in] meshIndex The index of the mesh within the entity.
 241    * @return The index of the mesh in the model's mesh array.
 242    */
 243   unsigned int GetMeshByIndex(unsigned int meshIndex) const;
 244
 245   /**
 246    * @brief Get the entity's list of mesh indices.
 247    *
 248    * @return The entity's list of mesh indices.
 249    */
 250   const EntityMeshIndices& GetMeshes() const;
 251
 252   /**
 253    * @brief Expand the bounding volume to include the child's bounding volume.
 254    *
 255    * @param[in] child A handle to the child.
 256    */
 257   void AddToBounds(Entity child);
 258
 259   /**
 260    * @brief Expand the entity bounding box to include the new boundaries.
 261    *
 262    * @param[in] lowerBounds to extend the entity bounds
 263    * @param[in] upperBounds to extend the entity bounds
 264    */
 265    void AddToBounds( const Vector3& lowerBounds, const Vector3& upperBounds );
 266
 267   /**
 268    * @brief Get the lower bounds of the bounding volume which contains all vertices in all meshes
 269    * referenced by this entity.
 270    *
 271    * @return A vector describing the lower bounds.
 272    */
 273   const Vector3&  GetLowerBounds() const;
 274
 275   /**
 276    * @brief Set the lower bounds of the bounding volume which contains all vertices in all meshes
 277    * referenced by this entity.
 278    *
 279    * @param[in] lowerBounds of the entity.
 280    */
 281   void SetLowerBounds( const Vector3& lowerBounds );
 282
 283   /**
 284    * @brief Get the upper bounds of the bounding volume which contains all vertices in all meshes
 285    * referenced by this entity.
 286    *
 287    * @return A vector describing the upper bounds.
 288    */
 289   const Vector3&  GetUpperBounds() const;
 290
 291   /**
 292    * @brief Set the upper bounds of the bounding volume which contains all vertices in all meshes
 293    * referenced by this entity.
 294    *
 295    * @param[in] upperBounds of the entity.
 296    */
 297   void SetUpperBounds( const Vector3& upperBounds );
 298
 299 public: // Not intended for application developers
 300
 301   /**
 302    * @brief This constructor is used by Dali New() methods.
 303    * @param [in] entity A pointer to a newly allocated Dali resource
 304    */
 305   explicit DALI_INTERNAL Entity(Internal::Entity* entity);
 306
 307 }; // class Entity
 308
 309 } // namespace Dali
 310
 311 #endif // __DALI_ENTITY_H__