include/IMeshCache.h

   1 // Copyright (C) 2002-2012 Nikolaus Gebhardt\r
   2 // This file is part of the "Irrlicht Engine".\r
   3 // For conditions of distribution and use, see copyright notice in irrlicht.h\r
   4 \r
   5 #ifndef __I_MESH_CACHE_H_INCLUDED__\r
   6 #define __I_MESH_CACHE_H_INCLUDED__\r
   7 \r
   8 #include "IReferenceCounted.h"\r
   9 #include "path.h"\r
  10 \r
  11 namespace irr\r
  12 {\r
  13 \r
  14 namespace scene\r
  15 {\r
  16         class IMesh;\r
  17         class IAnimatedMesh;\r
  18         class IAnimatedMeshSceneNode;\r
  19         class IMeshLoader;\r
  20 \r
  21         //! The mesh cache stores already loaded meshes and provides an interface to them.\r
  22         /** You can access it using ISceneManager::getMeshCache(). All existing\r
  23         scene managers will return a pointer to the same mesh cache, because it\r
  24         is shared between them. With this interface, it is possible to manually\r
  25         add new loaded meshes (if ISceneManager::getMesh() is not sufficient),\r
  26         to remove them and to iterate through already loaded meshes. */\r
  27         class IMeshCache : public virtual IReferenceCounted\r
  28         {\r
  29         public:\r
  30 \r
  31                 //! Destructor\r
  32                 virtual ~IMeshCache() {}\r
  33 \r
  34                 //! Adds a mesh to the internal list of loaded meshes.\r
  35                 /** Usually, ISceneManager::getMesh() is called to load a mesh\r
  36                 from a file. That method searches the list of loaded meshes if\r
  37                 a mesh has already been loaded and returns a pointer to if it\r
  38                 is in that list and already in memory. Otherwise it loads the\r
  39                 mesh. With IMeshCache::addMesh(), it is possible to pretend\r
  40                 that a mesh already has been loaded. This method can be used\r
  41                 for example by mesh loaders who need to load more than one mesh\r
  42                 with one call. They can add additional meshes with this method\r
  43                 to the scene manager. The COLLADA loader for example uses this\r
  44                 method.\r
  45                 \param name Name of the mesh. When calling\r
  46                 ISceneManager::getMesh() with this name it will return the mesh\r
  47                 set by this method.\r
  48                 \param mesh Pointer to a mesh which will now be referenced by\r
  49                 this name. */\r
  50                 virtual void addMesh(const io::path& name, IAnimatedMesh* mesh) = 0;\r
  51 \r
  52                 //! Removes the mesh from the cache.\r
  53                 /** After loading a mesh with getMesh(), the mesh can be\r
  54                 removed from the cache using this method, freeing a lot of\r
  55                 memory.\r
  56                 \param mesh Pointer to the mesh which shall be removed. */\r
  57                 virtual void removeMesh(const IMesh* const mesh) = 0;\r
  58 \r
  59                 //! Returns amount of loaded meshes in the cache.\r
  60                 /** You can load new meshes into the cache using getMesh() and\r
  61                 addMesh(). If you ever need to access the internal mesh cache,\r
  62                 you can do this using removeMesh(), getMeshNumber(),\r
  63                 getMeshByIndex() and getMeshName().\r
  64                 \return Number of meshes in cache. */\r
  65                 virtual u32 getMeshCount() const = 0;\r
  66 \r
  67                 //! Returns current index number of the mesh or -1 when not found.\r
  68                 /** \param mesh Pointer to the mesh to search for.\r
  69                 \return Index of the mesh in the cache, or -1 if not found. */\r
  70                 virtual s32 getMeshIndex(const IMesh* const mesh) const = 0;\r
  71 \r
  72                 //! Returns a mesh based on its index number.\r
  73                 /** \param index: Index of the mesh, number between 0 and\r
  74                 getMeshCount()-1.\r
  75                 Note that this number is only valid until a new mesh is loaded\r
  76                 or removed.\r
  77                 \return Pointer to the mesh or 0 if there is none with this\r
  78                 number. */\r
  79                 virtual IAnimatedMesh* getMeshByIndex(u32 index) = 0;\r
  80 \r
  81                 //! Returns a mesh based on its name (often a filename).\r
  82                 /** \deprecated Use getMeshByName() instead. This method may be removed by\r
  83                 Irrlicht 1.9 */\r
  84                 _IRR_DEPRECATED_ IAnimatedMesh* getMeshByFilename(const io::path& filename)\r
  85                 {\r
  86                         return getMeshByName(filename);\r
  87                 }\r
  88 \r
  89                 //! Get the name of a loaded mesh, based on its index. (Name is often identical to the filename).\r
  90                 /** \deprecated Use getMeshName() instead. This method may be removed by\r
  91                 Irrlicht 1.9 */\r
  92                 _IRR_DEPRECATED_ const io::path& getMeshFilename(u32 index) const\r
  93                 {\r
  94                         return getMeshName(index).getInternalName();\r
  95                 }\r
  96 \r
  97                 //! Get the name of a loaded mesh, if there is any. (Name is often identical to the filename).\r
  98                 /** \deprecated Use getMeshName() instead. This method may be removed by\r
  99                 Irrlicht 1.9 */\r
 100                 _IRR_DEPRECATED_ const io::path& getMeshFilename(const IMesh* const mesh) const\r
 101                 {\r
 102                         return getMeshName(mesh).getInternalName();\r
 103                 }\r
 104 \r
 105                 //! Renames a loaded mesh.\r
 106                 /** \deprecated Use renameMesh() instead. This method may be removed by\r
 107                 Irrlicht 1.9 */\r
 108                 _IRR_DEPRECATED_ bool setMeshFilename(u32 index, const io::path& filename)\r
 109                 {\r
 110                         return renameMesh(index, filename);\r
 111                 }\r
 112 \r
 113                 //! Renames a loaded mesh.\r
 114                 /** \deprecated Use renameMesh() instead. This method may be removed by\r
 115                 Irrlicht 1.9 */\r
 116                 _IRR_DEPRECATED_ bool setMeshFilename(const IMesh* const mesh, const io::path& filename)\r
 117                 {\r
 118                         return renameMesh(mesh, filename);\r
 119                 }\r
 120 \r
 121                 //! Returns a mesh based on its name.\r
 122                 /** \param name Name of the mesh. Usually a filename.\r
 123                 \return Pointer to the mesh or 0 if there is none with this number. */\r
 124                 virtual IAnimatedMesh* getMeshByName(const io::path& name) = 0;\r
 125 \r
 126                 //! Get the name of a loaded mesh, based on its index.\r
 127                 /** \param index: Index of the mesh, number between 0 and getMeshCount()-1.\r
 128                 \return The name if mesh was found and has a name, else the path is empty. */\r
 129                 virtual const io::SNamedPath& getMeshName(u32 index) const = 0;\r
 130 \r
 131                 //! Get the name of the loaded mesh if there is any.\r
 132                 /** \param mesh Pointer to mesh to query.\r
 133                 \return The name if mesh was found and has a name, else the path is empty. */\r
 134                 virtual const io::SNamedPath& getMeshName(const IMesh* const mesh) const = 0;\r
 135 \r
 136                 //! Renames a loaded mesh.\r
 137                 /** Note that renaming meshes might change the ordering of the\r
 138                 meshes, and so the index of the meshes as returned by\r
 139                 getMeshIndex() or taken by some methods will change.\r
 140                 \param index The index of the mesh in the cache.\r
 141                 \param name New name for the mesh.\r
 142                 \return True if mesh was renamed. */\r
 143                 virtual bool renameMesh(u32 index, const io::path& name) = 0;\r
 144 \r
 145                 //! Renames the loaded mesh\r
 146                 /** Note that renaming meshes might change the ordering of the\r
 147                 meshes, and so the index of the meshes as returned by\r
 148                 getMeshIndex() or taken by some methods will change.\r
 149                 \param mesh Mesh to be renamed.\r
 150                 \param name New name for the mesh.\r
 151                 \return True if mesh was renamed. */\r
 152                 virtual bool renameMesh(const IMesh* const mesh, const io::path& name) = 0;\r
 153 \r
 154                 //! Check if a mesh was already loaded.\r
 155                 /** \param name Name of the mesh. Usually a filename.\r
 156                 \return True if the mesh has been loaded, else false. */\r
 157                 virtual bool isMeshLoaded(const io::path& name) = 0;\r
 158 \r
 159                 //! Clears the whole mesh cache, removing all meshes.\r
 160                 /** All meshes will be reloaded completely when using ISceneManager::getMesh()\r
 161                 after calling this method.\r
 162                 Warning: If you have pointers to meshes that were loaded with ISceneManager::getMesh()\r
 163                 and you did not grab them, then they may become invalid. */\r
 164                 virtual void clear() = 0;\r
 165 \r
 166                 //! Clears all meshes that are held in the mesh cache but not used anywhere else.\r
 167                 /** Warning: If you have pointers to meshes that were loaded with ISceneManager::getMesh()\r
 168                 and you did not grab them, then they may become invalid. */\r
 169                 virtual void clearUnusedMeshes() = 0;\r
 170         };\r
 171 \r
 172 \r
 173 } // end namespace scene\r
 174 } // end namespace irr\r
 175 \r
 176 #endif\r
 177 \r