[1030] | 1 | /*
|
---|
| 2 | -----------------------------------------------------------------------------
|
---|
| 3 | This source file is part of OGRE
|
---|
| 4 | (Object-oriented Graphics Rendering Engine)
|
---|
| 5 | For the latest info, see http://www.ogre3d.org/
|
---|
| 6 |
|
---|
| 7 | Copyright (c) 2000-2005 The OGRE Team
|
---|
| 8 | Also see acknowledgements in Readme.html
|
---|
| 9 |
|
---|
| 10 | This program is free software; you can redistribute it and/or modify it under
|
---|
| 11 | the terms of the GNU Lesser General Public License as published by the Free Software
|
---|
| 12 | Foundation; either version 2 of the License, or (at your option) any later
|
---|
| 13 | version.
|
---|
| 14 |
|
---|
| 15 | This program is distributed in the hope that it will be useful, but WITHOUT
|
---|
| 16 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
|
---|
| 17 | FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
|
---|
| 18 |
|
---|
| 19 | You should have received a copy of the GNU Lesser General Public License along with
|
---|
| 20 | this program; if not, write to the Free Software Foundation, Inc., 59 Temple
|
---|
| 21 | Place - Suite 330, Boston, MA 02111-1307, USA, or go to
|
---|
| 22 | http://www.gnu.org/copyleft/lesser.txt.
|
---|
| 23 | -----------------------------------------------------------------------------
|
---|
| 24 | */
|
---|
| 25 | #ifndef _ResourceManager_H__
|
---|
| 26 | #define _ResourceManager_H__
|
---|
| 27 |
|
---|
| 28 | #include "OgrePrerequisites.h"
|
---|
| 29 |
|
---|
| 30 | #include "OgreResource.h"
|
---|
| 31 | #include "OgreResourceGroupManager.h"
|
---|
| 32 | #include "OgreIteratorWrappers.h"
|
---|
| 33 | #include "OgreCommon.h"
|
---|
| 34 | #include "OgreDataStream.h"
|
---|
| 35 | #include "OgreStringVector.h"
|
---|
| 36 | #include "OgreScriptLoader.h"
|
---|
| 37 |
|
---|
| 38 | namespace Ogre {
|
---|
| 39 |
|
---|
| 40 | /** Defines a generic resource handler.
|
---|
| 41 | @remarks
|
---|
| 42 | A resource manager is responsible for managing a pool of
|
---|
| 43 | resources of a particular type. It must index them, look
|
---|
| 44 | them up, load and destroy them. It may also need to stay within
|
---|
| 45 | a defined memory budget, and temporaily unload some resources
|
---|
| 46 | if it needs to to stay within this budget.
|
---|
| 47 | @par
|
---|
| 48 | Resource managers use a priority system to determine what can
|
---|
| 49 | be unloaded, and a Least Recently Used (LRU) policy within
|
---|
| 50 | resources of the same priority.
|
---|
| 51 | @par
|
---|
| 52 | Resources can be loaded using the generalised load interface,
|
---|
| 53 | and they can be unloaded and removed. In addition, each
|
---|
| 54 | subclass of ResourceManager will likely define custom 'load' methods
|
---|
| 55 | which take explicit parameters depending on the kind of resource
|
---|
| 56 | being created.
|
---|
| 57 | @note
|
---|
| 58 | Resources can be loaded and unloaded through the Resource class,
|
---|
| 59 | but they can only be removed (and thus eventually destroyed) using
|
---|
| 60 | their parent ResourceManager.
|
---|
| 61 | @note
|
---|
| 62 | If OGRE_THREAD_SUPPORT is 1, this class is thread-safe.
|
---|
| 63 | */
|
---|
| 64 | class _OgreExport ResourceManager : public ScriptLoader
|
---|
| 65 | {
|
---|
| 66 | public:
|
---|
| 67 | OGRE_AUTO_MUTEX // public to allow external locking
|
---|
| 68 | ResourceManager();
|
---|
| 69 | virtual ~ResourceManager();
|
---|
| 70 |
|
---|
| 71 | /** Creates a new blank resource, but does not immediately load it.
|
---|
| 72 | @remarks
|
---|
| 73 | Resource managers handle disparate types of resources, so if you want
|
---|
| 74 | to get at the detailed interface of this resource, you'll have to
|
---|
| 75 | cast the result to the subclass you know you're creating.
|
---|
| 76 | @param name The unique name of the resource
|
---|
| 77 | @param group The name of the resource group to attach this new resource to
|
---|
| 78 | @param isManual Is this resource manually loaded? If so, you should really
|
---|
| 79 | populate the loader parameter in order that the load process
|
---|
| 80 | can call the loader back when loading is required.
|
---|
| 81 | @param loader Pointer to a ManualLoader implementation which will be called
|
---|
| 82 | when the Resource wishes to load (should be supplied if you set
|
---|
| 83 | isManual to true). You can in fact leave this parameter null
|
---|
| 84 | if you wish, but the Resource will never be able to reload if
|
---|
| 85 | anything ever causes it to unload. Therefore provision of a proper
|
---|
| 86 | ManualLoader instance is strongly recommended.
|
---|
| 87 | @param createParams If any parameters are required to create an instance,
|
---|
| 88 | they should be supplied here as name / value pairs
|
---|
| 89 | */
|
---|
| 90 | virtual ResourcePtr create(const String& name, const String& group,
|
---|
| 91 | bool isManual = false, ManualResourceLoader* loader = 0,
|
---|
| 92 | const NameValuePairList* createParams = 0);
|
---|
| 93 | /** Set a limit on the amount of memory this resource handler may use.
|
---|
| 94 | @remarks
|
---|
| 95 | If, when asked to load a new resource, the manager believes it will exceed this memory
|
---|
| 96 | budget, it will temporarily unload a resource to make room for the new one. This unloading
|
---|
| 97 | is not permanent and the Resource is not destroyed; it simply needs to be reloaded when
|
---|
| 98 | next used.
|
---|
| 99 | */
|
---|
| 100 | virtual void setMemoryBudget( size_t bytes);
|
---|
| 101 |
|
---|
| 102 | /** Get the limit on the amount of memory this resource handler may use.
|
---|
| 103 | */
|
---|
| 104 | virtual size_t getMemoryBudget(void) const;
|
---|
| 105 |
|
---|
| 106 | /** Unloads a single resource by name.
|
---|
| 107 | @remarks
|
---|
| 108 | Unloaded resources are not removed, they simply free up their memory
|
---|
| 109 | as much as they can and wait to be reloaded.
|
---|
| 110 | @see ResourceGroupManager for unloading of resource groups.
|
---|
| 111 | */
|
---|
| 112 | virtual void unload(const String& name);
|
---|
| 113 |
|
---|
| 114 | /** Unloads a single resource by handle.
|
---|
| 115 | @remarks
|
---|
| 116 | Unloaded resources are not removed, they simply free up their memory
|
---|
| 117 | as much as they can and wait to be reloaded.
|
---|
| 118 | @see ResourceGroupManager for unloading of resource groups.
|
---|
| 119 | */
|
---|
| 120 | virtual void unload(ResourceHandle handle);
|
---|
| 121 |
|
---|
| 122 | /** Unloads all resources.
|
---|
| 123 | @remarks
|
---|
| 124 | Unloaded resources are not removed, they simply free up their memory
|
---|
| 125 | as much as they can and wait to be reloaded.
|
---|
| 126 | @see ResourceGroupManager for unloading of resource groups.
|
---|
| 127 | */
|
---|
| 128 | virtual void unloadAll(void);
|
---|
| 129 | /** Caused all currently loaded resources to be reloaded.
|
---|
| 130 | @remarks
|
---|
| 131 | All resources currently being held in this manager which are also
|
---|
| 132 | marked as currently loaded will be unloaded, then loaded again.
|
---|
| 133 | */
|
---|
| 134 | virtual void reloadAll(void);
|
---|
| 135 |
|
---|
| 136 | /** Remove a single resource.
|
---|
| 137 | @remarks
|
---|
| 138 | Removes a single resource, meaning it will be removed from the list
|
---|
| 139 | of valid resources in this manager, also causing it to be unloaded.
|
---|
| 140 | @note
|
---|
| 141 | The word 'Destroy' is not used here, since
|
---|
| 142 | if any other pointers are referring to this resource, it will persist
|
---|
| 143 | until they have finished with it; however to all intents and purposes
|
---|
| 144 | it no longer exists and will likely get destroyed imminently.
|
---|
| 145 | @note
|
---|
| 146 | If you do have shared pointers to resources hanging around after the
|
---|
| 147 | ResourceManager is destroyed, you may get problems on destruction of
|
---|
| 148 | these resources if they were relying on the manager (especially if
|
---|
| 149 | it is a plugin). If you find you get problems on shutdown in the
|
---|
| 150 | destruction of resources, try making sure you release all your
|
---|
| 151 | shared pointers before you shutdown OGRE.
|
---|
| 152 | */
|
---|
| 153 | virtual void remove(ResourcePtr& r);
|
---|
| 154 |
|
---|
| 155 | /** Remove a single resource by name.
|
---|
| 156 | @remarks
|
---|
| 157 | Removes a single resource, meaning it will be removed from the list
|
---|
| 158 | of valid resources in this manager, also causing it to be unloaded.
|
---|
| 159 | @note
|
---|
| 160 | The word 'Destroy' is not used here, since
|
---|
| 161 | if any other pointers are referring to this resource, it will persist
|
---|
| 162 | until they have finished with it; however to all intents and purposes
|
---|
| 163 | it no longer exists and will likely get destroyed imminently.
|
---|
| 164 | @note
|
---|
| 165 | If you do have shared pointers to resources hanging around after the
|
---|
| 166 | ResourceManager is destroyed, you may get problems on destruction of
|
---|
| 167 | these resources if they were relying on the manager (especially if
|
---|
| 168 | it is a plugin). If you find you get problems on shutdown in the
|
---|
| 169 | destruction of resources, try making sure you release all your
|
---|
| 170 | shared pointers before you shutdown OGRE.
|
---|
| 171 | */
|
---|
| 172 | virtual void remove(const String& name);
|
---|
| 173 |
|
---|
| 174 | /** Remove a single resource by handle.
|
---|
| 175 | @remarks
|
---|
| 176 | Removes a single resource, meaning it will be removed from the list
|
---|
| 177 | of valid resources in this manager, also causing it to be unloaded.
|
---|
| 178 | @note
|
---|
| 179 | The word 'Destroy' is not used here, since
|
---|
| 180 | if any other pointers are referring to this resource, it will persist
|
---|
| 181 | until they have finished with it; however to all intents and purposes
|
---|
| 182 | it no longer exists and will likely get destroyed imminently.
|
---|
| 183 | @note
|
---|
| 184 | If you do have shared pointers to resources hanging around after the
|
---|
| 185 | ResourceManager is destroyed, you may get problems on destruction of
|
---|
| 186 | these resources if they were relying on the manager (especially if
|
---|
| 187 | it is a plugin). If you find you get problems on shutdown in the
|
---|
| 188 | destruction of resources, try making sure you release all your
|
---|
| 189 | shared pointers before you shutdown OGRE.
|
---|
| 190 | */
|
---|
| 191 | virtual void remove(ResourceHandle handle);
|
---|
| 192 | /** Removes all resources.
|
---|
| 193 | @note
|
---|
| 194 | The word 'Destroy' is not used here, since
|
---|
| 195 | if any other pointers are referring to these resources, they will persist
|
---|
| 196 | until they have been finished with; however to all intents and purposes
|
---|
| 197 | the resources no longer exist and will get destroyed imminently.
|
---|
| 198 | @note
|
---|
| 199 | If you do have shared pointers to resources hanging around after the
|
---|
| 200 | ResourceManager is destroyed, you may get problems on destruction of
|
---|
| 201 | these resources if they were relying on the manager (especially if
|
---|
| 202 | it is a plugin). If you find you get problems on shutdown in the
|
---|
| 203 | destruction of resources, try making sure you release all your
|
---|
| 204 | shared pointers before you shutdown OGRE.
|
---|
| 205 | */
|
---|
| 206 | virtual void removeAll(void);
|
---|
| 207 |
|
---|
| 208 | /** Retrieves a pointer to a resource by name, or null if the resource does not exist.
|
---|
| 209 | */
|
---|
| 210 | virtual ResourcePtr getByName(const String& name);
|
---|
| 211 | /** Retrieves a pointer to a resource by handle, or null if the resource does not exist.
|
---|
| 212 | */
|
---|
| 213 | virtual ResourcePtr getByHandle(ResourceHandle handle);
|
---|
| 214 |
|
---|
| 215 | /// Returns whether the named resource exists in this manager
|
---|
| 216 | virtual bool resourceExists(const String& name)
|
---|
| 217 | {
|
---|
| 218 | return !getByName(name).isNull();
|
---|
| 219 | }
|
---|
| 220 | /// Returns whether a resource with the given handle exists in this manager
|
---|
| 221 | virtual bool resourceExists(ResourceHandle handle)
|
---|
| 222 | {
|
---|
| 223 | return !getByHandle(handle).isNull();
|
---|
| 224 | }
|
---|
| 225 |
|
---|
| 226 | /** Notify this manager that a resource which it manages has been
|
---|
| 227 | 'touched', ie used.
|
---|
| 228 | */
|
---|
| 229 | virtual void _notifyResourceTouched(Resource* res);
|
---|
| 230 |
|
---|
| 231 | /** Notify this manager that a resource which it manages has been
|
---|
| 232 | loaded.
|
---|
| 233 | */
|
---|
| 234 | virtual void _notifyResourceLoaded(Resource* res);
|
---|
| 235 |
|
---|
| 236 | /** Notify this manager that a resource which it manages has been
|
---|
| 237 | unloaded.
|
---|
| 238 | */
|
---|
| 239 | virtual void _notifyResourceUnloaded(Resource* res);
|
---|
| 240 |
|
---|
| 241 | /** Generic load method, used to create a Resource specific to this
|
---|
| 242 | ResourceManager without using one of the specialised 'load' methods
|
---|
| 243 | (containing per-Resource-type parameters).
|
---|
| 244 | @param name The name of the Resource
|
---|
| 245 | @param group The resource group to which this resource will belong
|
---|
| 246 | @param isManual Is the resource to be manually loaded? If so, you should
|
---|
| 247 | provide a value for the loader parameter
|
---|
| 248 | @param loader The manual loader which is to perform the required actions
|
---|
| 249 | when this resource is loaded; only applicable when you specify true
|
---|
| 250 | for the previous parameter
|
---|
| 251 | @param loadParams Optional pointer to a list of name/value pairs
|
---|
| 252 | containing loading parameters for this type of resource.
|
---|
| 253 | */
|
---|
| 254 | virtual ResourcePtr load(const String& name,
|
---|
| 255 | const String& group, bool isManual = false,
|
---|
| 256 | ManualResourceLoader* loader = 0, const NameValuePairList* loadParams = 0);
|
---|
| 257 |
|
---|
| 258 | /** Gets the file patterns which should be used to find scripts for this
|
---|
| 259 | ResourceManager.
|
---|
| 260 | @remarks
|
---|
| 261 | Some resource managers can read script files in order to define
|
---|
| 262 | resources ahead of time. These resources are added to the available
|
---|
| 263 | list inside the manager, but none are loaded initially. This allows
|
---|
| 264 | you to load the items that are used on demand, or to load them all
|
---|
| 265 | as a group if you wish (through ResourceGroupManager).
|
---|
| 266 | @par
|
---|
| 267 | This method lets you determine the file pattern which will be used
|
---|
| 268 | to identify scripts intended for this manager.
|
---|
| 269 | @returns
|
---|
| 270 | A list of file patterns, in the order they should be searched in.
|
---|
| 271 | @see isScriptingSupported, parseScript
|
---|
| 272 | */
|
---|
| 273 | virtual const StringVector& getScriptPatterns(void) const { return mScriptPatterns; }
|
---|
| 274 |
|
---|
| 275 | /** Parse the definition of a set of resources from a script file.
|
---|
| 276 | @remarks
|
---|
| 277 | Some resource managers can read script files in order to define
|
---|
| 278 | resources ahead of time. These resources are added to the available
|
---|
| 279 | list inside the manager, but none are loaded initially. This allows
|
---|
| 280 | you to load the items that are used on demand, or to load them all
|
---|
| 281 | as a group if you wish (through ResourceGroupManager).
|
---|
| 282 | @param stream Weak reference to a data stream which is the source of the script
|
---|
| 283 | @param groupName The name of the resource group that resources which are
|
---|
| 284 | parsed are to become a member of. If this group is loaded or unloaded,
|
---|
| 285 | then the resources discovered in this script will be loaded / unloaded
|
---|
| 286 | with it.
|
---|
| 287 | */
|
---|
| 288 | virtual void parseScript(DataStreamPtr& stream, const String& groupName) {}
|
---|
| 289 |
|
---|
| 290 | /** Gets the relative loading order of resources of this type.
|
---|
| 291 | @remarks
|
---|
| 292 | There are dependencies between some kinds of resource in terms of loading
|
---|
| 293 | order, and this value enumerates that. Higher values load later during
|
---|
| 294 | bulk loading tasks.
|
---|
| 295 | */
|
---|
| 296 | virtual Real getLoadingOrder(void) const { return mLoadOrder; }
|
---|
| 297 |
|
---|
| 298 | /** Gets a string identifying the type of resource this manager handles. */
|
---|
| 299 | const String& getResourceType(void) const { return mResourceType; }
|
---|
| 300 |
|
---|
| 301 | protected:
|
---|
| 302 |
|
---|
| 303 | /** Allocates the next handle. */
|
---|
| 304 | ResourceHandle getNextHandle(void);
|
---|
| 305 |
|
---|
| 306 | /** Create a new resource instance compatible with this manager (no custom
|
---|
| 307 | parameters are populated at this point).
|
---|
| 308 | @remarks
|
---|
| 309 | Subclasses must override this method and create a subclass of Resource.
|
---|
| 310 | @param name The unique name of the resource
|
---|
| 311 | @param group The name of the resource group to attach this new resource to
|
---|
| 312 | @param isManual Is this resource manually loaded? If so, you should really
|
---|
| 313 | populate the loader parameter in order that the load process
|
---|
| 314 | can call the loader back when loading is required.
|
---|
| 315 | @param loader Pointer to a ManualLoader implementation which will be called
|
---|
| 316 | when the Resource wishes to load (should be supplied if you set
|
---|
| 317 | isManual to true). You can in fact leave this parameter null
|
---|
| 318 | if you wish, but the Resource will never be able to reload if
|
---|
| 319 | anything ever causes it to unload. Therefore provision of a proper
|
---|
| 320 | ManualLoader instance is strongly recommended.
|
---|
| 321 | @param createParams If any parameters are required to create an instance,
|
---|
| 322 | they should be supplied here as name / value pairs. These do not need
|
---|
| 323 | to be set on the instance (handled elsewhere), just used if required
|
---|
| 324 | to differentiate which concrete class is created.
|
---|
| 325 |
|
---|
| 326 | */
|
---|
| 327 | virtual Resource* createImpl(const String& name, ResourceHandle handle,
|
---|
| 328 | const String& group, bool isManual, ManualResourceLoader* loader,
|
---|
| 329 | const NameValuePairList* createParams) = 0;
|
---|
| 330 | /** Add a newly created resource to the manager (note weak reference) */
|
---|
| 331 | virtual void addImpl( ResourcePtr& res );
|
---|
| 332 | /** Remove a resource from this manager; remove it from the lists. */
|
---|
| 333 | virtual void removeImpl( ResourcePtr& res );
|
---|
| 334 | /** Checks memory usage and pages out if required.
|
---|
| 335 | */
|
---|
| 336 | virtual void checkUsage(void);
|
---|
| 337 | /** Gets the current memory usage, in bytes. */
|
---|
| 338 | virtual size_t getMemoryUsage(void) const { return mMemoryUsage; }
|
---|
| 339 |
|
---|
| 340 |
|
---|
| 341 | public:
|
---|
| 342 | typedef HashMap< String, ResourcePtr > ResourceMap;
|
---|
| 343 | typedef std::map<ResourceHandle, ResourcePtr> ResourceHandleMap;
|
---|
| 344 | protected:
|
---|
| 345 | ResourceHandleMap mResourcesByHandle;
|
---|
| 346 | ResourceMap mResources;
|
---|
| 347 | ResourceHandle mNextHandle;
|
---|
| 348 | size_t mMemoryBudget; // In bytes
|
---|
| 349 | size_t mMemoryUsage; // In bytes
|
---|
| 350 |
|
---|
| 351 | // IMPORTANT - all subclasses must populate the fields below
|
---|
| 352 |
|
---|
| 353 | /// Patterns to use to look for scripts if supported (e.g. *.overlay)
|
---|
| 354 | StringVector mScriptPatterns;
|
---|
| 355 | /// Loading order relative to other managers, higher is later
|
---|
| 356 | Real mLoadOrder;
|
---|
| 357 | /// String identifying the resource type this manager handles
|
---|
| 358 | String mResourceType;
|
---|
| 359 |
|
---|
| 360 | public:
|
---|
| 361 | typedef MapIterator<ResourceHandleMap> ResourceMapIterator;
|
---|
| 362 | /** Returns an iterator over all resources in this manager.
|
---|
| 363 | @note
|
---|
| 364 | Use of this iterator is NOT thread safe!
|
---|
| 365 | */
|
---|
| 366 | ResourceMapIterator getResourceIterator(void)
|
---|
| 367 | {
|
---|
| 368 | return ResourceMapIterator(mResourcesByHandle.begin(), mResourcesByHandle.end());
|
---|
| 369 | }
|
---|
| 370 |
|
---|
| 371 |
|
---|
| 372 |
|
---|
| 373 | };
|
---|
| 374 |
|
---|
| 375 | }
|
---|
| 376 |
|
---|
| 377 | #endif
|
---|