[1092] | 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 _ResourceGroupManager_H__
|
---|
| 26 | #define _ResourceGroupManager_H__
|
---|
| 27 |
|
---|
| 28 | #include "OgrePrerequisites.h"
|
---|
| 29 | #include "OgreSingleton.h"
|
---|
| 30 | #include "OgreCommon.h"
|
---|
| 31 | #include "OgreDataStream.h"
|
---|
| 32 | #include "OgreResource.h"
|
---|
| 33 | #include "OgreArchive.h"
|
---|
| 34 |
|
---|
| 35 | namespace Ogre {
|
---|
| 36 |
|
---|
| 37 | /** This abstract class defines an interface which is called back during
|
---|
| 38 | resource group loading to indicate the progress of the load.
|
---|
| 39 | @remarks
|
---|
| 40 | Resource group loading is in 2 phases - creating resources from
|
---|
| 41 | declarations (which includes parsing scripts), and loading
|
---|
| 42 | resources. Note that you don't necessarily have to have both; it
|
---|
| 43 | is quite possible to just parse all the scripts for a group (see
|
---|
| 44 | ResourceGroupManager::initialiseResourceGroup, but not to
|
---|
| 45 | load the resource group.
|
---|
| 46 | The sequence of events is (* signifies a repeating item):
|
---|
| 47 | <ul>
|
---|
| 48 | <li>resourceGroupScriptingStarted</li>
|
---|
| 49 | <li>scriptParseStarted (*)</li>
|
---|
| 50 | <li>scriptParseEnded (*)</li>
|
---|
| 51 | <li>resourceGroupScriptingEnded</li>
|
---|
| 52 | <li>resourceGroupLoadStarted</li>
|
---|
| 53 | <li>resourceLoadStarted (*)</li>
|
---|
| 54 | <li>resourceLoadEnded (*)</li>
|
---|
| 55 | <li>worldGeometryStageStarted (*)</li>
|
---|
| 56 | <li>worldGeometryStageEnded (*)</li>
|
---|
| 57 | <li>resourceGroupLoadEnded</li>
|
---|
| 58 | </ul>
|
---|
| 59 | @note
|
---|
| 60 | If OGRE_THREAD_SUPPORT is 1, this class is thread-safe.
|
---|
| 61 |
|
---|
| 62 | */
|
---|
| 63 | class _OgreExport ResourceGroupListener
|
---|
| 64 | {
|
---|
| 65 | public:
|
---|
| 66 | virtual ~ResourceGroupListener() {}
|
---|
| 67 |
|
---|
| 68 | /** This event is fired when a resource group begins parsing scripts.
|
---|
| 69 | @param groupName The name of the group
|
---|
| 70 | @param scriptCount The number of scripts which will be parsed
|
---|
| 71 | */
|
---|
| 72 | virtual void resourceGroupScriptingStarted(const String& groupName, size_t scriptCount) = 0;
|
---|
| 73 | /** This event is fired when a script is about to be parsed.
|
---|
| 74 | @param scriptName Name of the to be parsed
|
---|
| 75 | */
|
---|
| 76 | virtual void scriptParseStarted(const String& scriptName) = 0;
|
---|
| 77 | /** This event is fired when the script has been fully parsed.
|
---|
| 78 | */
|
---|
| 79 | virtual void scriptParseEnded(void) = 0;
|
---|
| 80 | /** This event is fired when a resource group finished parsing scripts. */
|
---|
| 81 | virtual void resourceGroupScriptingEnded(const String& groupName) = 0;
|
---|
| 82 |
|
---|
| 83 | /** This event is fired when a resource group begins loading.
|
---|
| 84 | @param groupName The name of the group being loaded
|
---|
| 85 | @param resourceCount The number of resources which will be loaded, including
|
---|
| 86 | a number of stages required to load any linked world geometry
|
---|
| 87 | */
|
---|
| 88 | virtual void resourceGroupLoadStarted(const String& groupName, size_t resourceCount) = 0;
|
---|
| 89 | /** This event is fired when a declared resource is about to be loaded.
|
---|
| 90 | @param resource Weak reference to the resource loaded.
|
---|
| 91 | */
|
---|
| 92 | virtual void resourceLoadStarted(const ResourcePtr& resource) = 0;
|
---|
| 93 | /** This event is fired when the resource has been loaded.
|
---|
| 94 | */
|
---|
| 95 | virtual void resourceLoadEnded(void) = 0;
|
---|
| 96 | /** This event is fired when a stage of loading linked world geometry
|
---|
| 97 | is about to start. The number of stages required will have been
|
---|
| 98 | included in the resourceCount passed in resourceGroupLoadStarted.
|
---|
| 99 | @param description Text description of what was just loaded
|
---|
| 100 | */
|
---|
| 101 | virtual void worldGeometryStageStarted(const String& description) = 0;
|
---|
| 102 | /** This event is fired when a stage of loading linked world geometry
|
---|
| 103 | has been completed. The number of stages required will have been
|
---|
| 104 | included in the resourceCount passed in resourceGroupLoadStarted.
|
---|
| 105 | @param description Text description of what was just loaded
|
---|
| 106 | */
|
---|
| 107 | virtual void worldGeometryStageEnded(void) = 0;
|
---|
| 108 |
|
---|
| 109 | /** This event is fired when a resource group finished loading. */
|
---|
| 110 | virtual void resourceGroupLoadEnded(const String& groupName) = 0;
|
---|
| 111 |
|
---|
| 112 | };
|
---|
| 113 | /** This singleton class manages the list of resource groups, and notifying
|
---|
| 114 | the various resource managers of their obligations to load / unload
|
---|
| 115 | resources in a group. It also provides facilities to monitor resource
|
---|
| 116 | loading per group (to do progress bars etc), provided the resources
|
---|
| 117 | that are required are pre-registered.
|
---|
| 118 | @par
|
---|
| 119 | Defining new resource groups, and declaring the resources you intend to
|
---|
| 120 | use in advance is optional, however it is a very useful feature. In addition,
|
---|
| 121 | if a ResourceManager supports the definition of resources through scripts,
|
---|
| 122 | then this is the class which drives the locating of the scripts and telling
|
---|
| 123 | the ResourceManager to parse them.
|
---|
| 124 | @par
|
---|
| 125 | There are several states that a resource can be in (the concept, not the
|
---|
| 126 | object instance in this case):
|
---|
| 127 | <ol>
|
---|
| 128 | <li><b>Undefined</b>. Nobody knows about this resource yet. It might be
|
---|
| 129 | in the filesystem, but Ogre is oblivious to it at the moment - there
|
---|
| 130 | is no Resource instance. This might be because it's never been declared
|
---|
| 131 | (either in a script, or using ResourceGroupManager::declareResource), or
|
---|
| 132 | it may have previously been a valid Resource instance but has been
|
---|
| 133 | removed, either individually through ResourceManager::remove or as a group
|
---|
| 134 | through ResourceGroupManager::clearResourceGroup.</li>
|
---|
| 135 | <li><b>Declared</b>. Ogre has some forewarning of this resource, either
|
---|
| 136 | through calling ResourceGroupManager::declareResource, or by declaring
|
---|
| 137 | the resource in a script file which is on one of the resource locations
|
---|
| 138 | which has been defined for a group. There is still no instance of Resource,
|
---|
| 139 | but Ogre will know to create this resource when
|
---|
| 140 | ResourceGroupManager::initialiseResourceGroup is called (which is automatic
|
---|
| 141 | if you declare the resource group before Root::initialise).</li>
|
---|
| 142 | <li><b>Unloaded</b>. There is now a Resource instance for this resource,
|
---|
| 143 | although it is not loaded. This means that code which looks for this
|
---|
| 144 | named resource will find it, but the Resource is not using a lot of memory
|
---|
| 145 | because it is in an unloaded state. A Resource can get into this state
|
---|
| 146 | by having just been created by ResourceGroupManager::initialiseResourceGroup
|
---|
| 147 | (either from a script, or from a call to declareResource), by
|
---|
| 148 | being created directly from code (ResourceManager::create), or it may
|
---|
| 149 | have previously been loaded and has been unloaded, either individually
|
---|
| 150 | through Resource::unload, or as a group through ResourceGroupManager::unloadResourceGroup.</li>
|
---|
| 151 | <li><b>Loaded</b>The Resource instance is fully loaded. This may have
|
---|
| 152 | happened implicitly because something used it, or it may have been
|
---|
| 153 | loaded as part of a group.</li>
|
---|
| 154 | </ol>
|
---|
| 155 | @see ResourceGroupManager::declareResource
|
---|
| 156 | @see ResourceGroupManager::initialiseResourceGroup
|
---|
| 157 | @see ResourceGroupManager::loadResourceGroup
|
---|
| 158 | @see ResourceGroupManager::unloadResourceGroup
|
---|
| 159 | @see ResourceGroupManager::clearResourceGroup
|
---|
| 160 | */
|
---|
| 161 | class _OgreExport ResourceGroupManager : public Singleton<ResourceGroupManager>
|
---|
| 162 | {
|
---|
| 163 | public:
|
---|
| 164 | OGRE_AUTO_MUTEX // public to allow external locking
|
---|
| 165 | /// Default resource group name
|
---|
| 166 | static String DEFAULT_RESOURCE_GROUP_NAME;
|
---|
| 167 | /// Bootstrap resource group name (min OGRE resources)
|
---|
| 168 | static String BOOTSTRAP_RESOURCE_GROUP_NAME;
|
---|
| 169 | /// Nested struct defining a resource declaration
|
---|
| 170 | struct ResourceDeclaration
|
---|
| 171 | {
|
---|
| 172 | String resourceName;
|
---|
| 173 | String resourceType;
|
---|
| 174 | NameValuePairList parameters;
|
---|
| 175 | };
|
---|
| 176 | /// List of resource declarations
|
---|
| 177 | typedef std::list<ResourceDeclaration> ResourceDeclarationList;
|
---|
| 178 | protected:
|
---|
| 179 | /// Map of resource types (strings) to ResourceManagers, used to notify them to load / unload group contents
|
---|
| 180 | typedef std::map<String, ResourceManager*> ResourceManagerMap;
|
---|
| 181 | ResourceManagerMap mResourceManagerMap;
|
---|
| 182 |
|
---|
| 183 | /// Map of loading order (Real) to ScriptLoader, used to order script parsing
|
---|
| 184 | typedef std::multimap<Real, ScriptLoader*> ScriptLoaderOrderMap;
|
---|
| 185 | ScriptLoaderOrderMap mScriptLoaderOrderMap;
|
---|
| 186 |
|
---|
| 187 | typedef std::vector<ResourceGroupListener*> ResourceGroupListenerList;
|
---|
| 188 | ResourceGroupListenerList mResourceGroupListenerList;
|
---|
| 189 |
|
---|
| 190 | /// Resource index entry, resourcename->location
|
---|
| 191 | typedef std::map<String, Archive*> ResourceLocationIndex;
|
---|
| 192 |
|
---|
| 193 | /// Resource location entry
|
---|
| 194 | struct ResourceLocation
|
---|
| 195 | {
|
---|
| 196 | /// Pointer to the archive which is the destination
|
---|
| 197 | Archive* archive;
|
---|
| 198 | /// Whether this location was added recursively
|
---|
| 199 | bool recursive;
|
---|
| 200 | };
|
---|
| 201 | /// List of possible file locations
|
---|
| 202 | typedef std::list<ResourceLocation*> LocationList;
|
---|
| 203 | /// List of resources which can be loaded / unloaded
|
---|
| 204 | typedef std::list<ResourcePtr> LoadUnloadResourceList;
|
---|
| 205 | /// Resource group entry
|
---|
| 206 | struct ResourceGroup
|
---|
| 207 | {
|
---|
| 208 | OGRE_AUTO_MUTEX
|
---|
| 209 | /// Group name
|
---|
| 210 | String name;
|
---|
| 211 | /// Whether group has been initialised
|
---|
| 212 | bool initialised;
|
---|
| 213 | /// List of possible locations to search
|
---|
| 214 | LocationList locationList;
|
---|
| 215 | /// Index of resource names to locations, built for speedy access (case sensitive archives)
|
---|
| 216 | ResourceLocationIndex resourceIndexCaseSensitive;
|
---|
| 217 | /// Index of resource names to locations, built for speedy access (case insensitive archives)
|
---|
| 218 | ResourceLocationIndex resourceIndexCaseInsensitive;
|
---|
| 219 | /// Pre-declared resources, ready to be created
|
---|
| 220 | ResourceDeclarationList resourceDeclarations;
|
---|
| 221 | /// Created resources which are ready to be loaded / unloaded
|
---|
| 222 | // Group by loading order of the type (defined by ResourceManager)
|
---|
| 223 | // (e.g. skeletons and materials before meshes)
|
---|
| 224 | typedef std::map<Real, LoadUnloadResourceList*> LoadResourceOrderMap;
|
---|
| 225 | LoadResourceOrderMap loadResourceOrderMap;
|
---|
| 226 | /// Linked world geometry, as passed to setWorldGeometry
|
---|
| 227 | String worldGeometry;
|
---|
| 228 | /// Scene manager to use with linked world geometry
|
---|
| 229 | SceneManager* worldGeometrySceneManager;
|
---|
| 230 | };
|
---|
| 231 | /// Map from resource group names to groups
|
---|
| 232 | typedef std::map<String, ResourceGroup*> ResourceGroupMap;
|
---|
| 233 | ResourceGroupMap mResourceGroupMap;
|
---|
| 234 |
|
---|
| 235 | /// Group name for world resources
|
---|
| 236 | String mWorldGroupName;
|
---|
| 237 |
|
---|
| 238 | /** Parses all the available scripts found in the resource locations
|
---|
| 239 | for the given group, for all ResourceManagers.
|
---|
| 240 | @remarks
|
---|
| 241 | Called as part of initialiseResourceGroup
|
---|
| 242 | */
|
---|
| 243 | void parseResourceGroupScripts(ResourceGroup* grp);
|
---|
| 244 | /** Create all the pre-declared resources.
|
---|
| 245 | @remarks
|
---|
| 246 | Called as part of initialiseResourceGroup
|
---|
| 247 | */
|
---|
| 248 | void createDeclaredResources(ResourceGroup* grp);
|
---|
| 249 | /** Adds a created resource to a group. */
|
---|
| 250 | void addCreatedResource(ResourcePtr& res, ResourceGroup& group);
|
---|
| 251 | /** Get resource group */
|
---|
| 252 | ResourceGroup* getResourceGroup(const String& name);
|
---|
| 253 | /** Drops contents of a group, leave group there, notify ResourceManagers. */
|
---|
| 254 | void dropGroupContents(ResourceGroup* grp);
|
---|
| 255 | /** Delete a group for shutdown - don't notify ResourceManagers. */
|
---|
| 256 | void deleteGroup(ResourceGroup* grp);
|
---|
| 257 | /// Internal event firing method
|
---|
| 258 | void fireResourceGroupScriptingStarted(const String& groupName, size_t scriptCount);
|
---|
| 259 | /// Internal event firing method
|
---|
| 260 | void fireScriptStarted(const String& scriptName);
|
---|
| 261 | /// Internal event firing method
|
---|
| 262 | void fireScriptEnded(void);
|
---|
| 263 | /// Internal event firing method
|
---|
| 264 | void fireResourceGroupScriptingEnded(const String& groupName);
|
---|
| 265 | /// Internal event firing method
|
---|
| 266 | void fireResourceGroupLoadStarted(const String& groupName, size_t resourceCount);
|
---|
| 267 | /// Internal event firing method
|
---|
| 268 | void fireResourceStarted(const ResourcePtr& resource);
|
---|
| 269 | /// Internal event firing method
|
---|
| 270 | void fireResourceEnded(void);
|
---|
| 271 | /// Internal event firing method
|
---|
| 272 | void fireResourceGroupLoadEnded(const String& groupName);
|
---|
| 273 |
|
---|
| 274 |
|
---|
| 275 |
|
---|
| 276 | /// Stored current group - optimisation for when bulk loading a group
|
---|
| 277 | ResourceGroup* mCurrentGroup;
|
---|
| 278 | public:
|
---|
| 279 | ResourceGroupManager();
|
---|
| 280 | virtual ~ResourceGroupManager();
|
---|
| 281 |
|
---|
| 282 | /** Create a resource group.
|
---|
| 283 | @remarks
|
---|
| 284 | A resource group allows you to define a set of resources that can
|
---|
| 285 | be loaded / unloaded as a unit. For example, it might be all the
|
---|
| 286 | resources used for the level of a game. There is always one predefined
|
---|
| 287 | resource group called ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME,
|
---|
| 288 | which is typically used to hold all resources which do not need to
|
---|
| 289 | be unloaded until shutdown. You can create additional ones so that
|
---|
| 290 | you can control the life of your resources in whichever way you wish.
|
---|
| 291 | @par
|
---|
| 292 | Once you have defined a resource group, resources which will be loaded
|
---|
| 293 | as part of it are defined in one of 3 ways:
|
---|
| 294 | <ol>
|
---|
| 295 | <li>Manually through declareResource(); this is useful for scripted
|
---|
| 296 | declarations since it is entirely generalised, and does not
|
---|
| 297 | create Resource instances right away</li>
|
---|
| 298 | <li>Through the use of scripts; some ResourceManager subtypes have
|
---|
| 299 | script formats (e.g. .material, .overlay) which can be used
|
---|
| 300 | to declare resources</li>
|
---|
| 301 | <li>By calling ResourceManager::create to create a resource manually.
|
---|
| 302 | This resource will go on the list for it's group and will be loaded
|
---|
| 303 | and unloaded with that group</li>
|
---|
| 304 | </ol>
|
---|
| 305 | You must remember to call initialiseResourceGroup if you intend to use
|
---|
| 306 | the first 2 types.
|
---|
| 307 | @param name The name to give the resource group.
|
---|
| 308 | */
|
---|
| 309 | void createResourceGroup(const String& name);
|
---|
| 310 |
|
---|
| 311 |
|
---|
| 312 | /** Initialises a resource group.
|
---|
| 313 | @remarks
|
---|
| 314 | After creating a resource group, adding some resource locations, and
|
---|
| 315 | perhaps pre-declaring some resources using declareResource(), but
|
---|
| 316 | before you need to use the resources in the group, you
|
---|
| 317 | should call this method to initialise the group. By calling this,
|
---|
| 318 | you are triggering the following processes:
|
---|
| 319 | <ol>
|
---|
| 320 | <li>Scripts for all resource types which support scripting are
|
---|
| 321 | parsed from the resource locations, and resources within them are
|
---|
| 322 | created (but not loaded yet).</li>
|
---|
| 323 | <li>Creates all the resources which have just pre-declared using
|
---|
| 324 | declareResource (again, these are not loaded yet)</li>
|
---|
| 325 | </ol>
|
---|
| 326 | So what this essentially does is create a bunch of unloaded Resource entries
|
---|
| 327 | in the respective ResourceManagers based on scripts, and resources
|
---|
| 328 | you've pre-declared. That means that code looking for these resources
|
---|
| 329 | will find them, but they won't be taking up much memory yet, until
|
---|
| 330 | they are either used, or they are loaded in bulk using loadResourceGroup.
|
---|
| 331 | Loading the resource group in bulk is entirely optional, but has the
|
---|
| 332 | advantage of coming with progress reporting as resources are loaded.
|
---|
| 333 | @par
|
---|
| 334 | Failure to call this method means that loadResourceGroup will do
|
---|
| 335 | nothing, and any resources you define in scripts will not be found.
|
---|
| 336 | Similarly, once you have called this method you won't be able to
|
---|
| 337 | pick up any new scripts or pre-declared resources, unless you
|
---|
| 338 | call clearResourceGroup, set up declared resources, and call this
|
---|
| 339 | method again.
|
---|
| 340 | @note
|
---|
| 341 | When you call Root::initialise, all resource groups that have already been
|
---|
| 342 | created are automatically initialised too. Therefore you do not need to
|
---|
| 343 | call this method for groups you define and set up before you call
|
---|
| 344 | Root::initialise. However, since one of the most useful features of
|
---|
| 345 | resource groups is to set them up after the main system initialisation
|
---|
| 346 | has occurred (e.g. a group per game level), you must remember to call this
|
---|
| 347 | method for the groups you create after this.
|
---|
| 348 |
|
---|
| 349 | @param name The name of the resource group to initialise
|
---|
| 350 | */
|
---|
| 351 | void initialiseResourceGroup(const String& name);
|
---|
| 352 |
|
---|
| 353 | /** Initialise all resource groups which are yet to be initialised.
|
---|
| 354 | @see ResourceGroupManager::intialiseResourceGroup
|
---|
| 355 | */
|
---|
| 356 | void initialiseAllResourceGroups(void);
|
---|
| 357 |
|
---|
| 358 | /** Loads a resource group.
|
---|
| 359 | @remarks
|
---|
| 360 | Loads any created resources which are part of the named group.
|
---|
| 361 | Note that resources must have already been created by calling
|
---|
| 362 | ResourceManager::create, or declared using declareResource() or
|
---|
| 363 | in a script (such as .material and .overlay). The latter requires
|
---|
| 364 | that initialiseResourceGroup has been called.
|
---|
| 365 |
|
---|
| 366 | When this method is called, this class will callback any ResourceGroupListeners
|
---|
| 367 | which have been registered to update them on progress.
|
---|
| 368 | @param name The name to of the resource group to load.
|
---|
| 369 | @param loadMainResources If true, loads normal resources associated
|
---|
| 370 | with the group (you might want to set this to false if you wanted
|
---|
| 371 | to just load world geometry in bulk)
|
---|
| 372 | @param loadWorldGeom If true, loads any linked world geometry
|
---|
| 373 | @see ResourceGroupManager::linkWorldGeometryToResourceGroup
|
---|
| 374 | */
|
---|
| 375 | void loadResourceGroup(const String& name, bool loadMainResources = true,
|
---|
| 376 | bool loadWorldGeom = true);
|
---|
| 377 |
|
---|
| 378 | /** Unloads a resource group.
|
---|
| 379 | @remarks
|
---|
| 380 | This method unloads all the resources that have been declared as
|
---|
| 381 | being part of the named resource group. Note that these resources
|
---|
| 382 | will still exist in their respective ResourceManager classes, but
|
---|
| 383 | will be in an unloaded state. If you want to remove them entirely,
|
---|
| 384 | you should use clearResourceGroup or destroyResourceGroup.
|
---|
| 385 | @param name The name to of the resource group to unload.
|
---|
| 386 | */
|
---|
| 387 | void unloadResourceGroup(const String& name);
|
---|
| 388 |
|
---|
| 389 | /** Clears a resource group.
|
---|
| 390 | @remarks
|
---|
| 391 | This method unloads all resources in the group, but in addition it
|
---|
| 392 | removes all those resources from their ResourceManagers, and then
|
---|
| 393 | clears all the members from the list. That means after calling this
|
---|
| 394 | method, there are no resources declared as part of the named group
|
---|
| 395 | any more. Resource locations still persist though.
|
---|
| 396 | @param name The name to of the resource group to clear.
|
---|
| 397 | */
|
---|
| 398 | void clearResourceGroup(const String& name);
|
---|
| 399 |
|
---|
| 400 | /** Destroys a resource group, clearing it first, destroying the resources
|
---|
| 401 | which are part of it, and then removing it from
|
---|
| 402 | the list of resource groups.
|
---|
| 403 | @param name The name of the resource group to destroy.
|
---|
| 404 | */
|
---|
| 405 | void destroyResourceGroup(const String& name);
|
---|
| 406 |
|
---|
| 407 |
|
---|
| 408 | /** Method to add a resource location to for a given resource group.
|
---|
| 409 | @remarks
|
---|
| 410 | Resource locations are places which are searched to load resource files.
|
---|
| 411 | When you choose to load a file, or to search for valid files to load,
|
---|
| 412 | the resource locations are used.
|
---|
| 413 | @param name The name of the resource location; probably a directory, zip file, URL etc.
|
---|
| 414 | @param locType The codename for the resource type, which must correspond to the
|
---|
| 415 | Archive factory which is providing the implementation.
|
---|
| 416 | @param resGroup The name of the resource group for which this location is
|
---|
| 417 | to apply. ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME is the
|
---|
| 418 | default group which always exists, and can
|
---|
| 419 | be used for resources which are unlikely to be unloaded until application
|
---|
| 420 | shutdown. Otherwise it must be the name of a group; if it
|
---|
| 421 | has not already been created with createResourceGroup then it is created
|
---|
| 422 | automatically.
|
---|
| 423 | @param recursive Whether subdirectories will be searched for files when using
|
---|
| 424 | a pattern match (such as *.material), and whether subdirectories will be
|
---|
| 425 | indexed. This can slow down initial loading of the archive and searches.
|
---|
| 426 | When opening a resource you still need to use the fully qualified name,
|
---|
| 427 | this allows duplicate names in alternate paths.
|
---|
| 428 | */
|
---|
| 429 | void addResourceLocation(const String& name, const String& locType,
|
---|
| 430 | const String& resGroup = DEFAULT_RESOURCE_GROUP_NAME, bool recursive = false);
|
---|
| 431 | /** Removes a resource location from the search path. */
|
---|
| 432 | void removeResourceLocation(const String& name,
|
---|
| 433 | const String& resGroup = DEFAULT_RESOURCE_GROUP_NAME);
|
---|
| 434 |
|
---|
| 435 | /** Declares a resource to be a part of a resource group, allowing you
|
---|
| 436 | to load and unload it as part of the group.
|
---|
| 437 | @remarks
|
---|
| 438 | By declaring resources before you attempt to use them, you can
|
---|
| 439 | more easily control the loading and unloading of those resources
|
---|
| 440 | by their group. Declaring them also allows them to be enumerated,
|
---|
| 441 | which means events can be raised to indicate the loading progress
|
---|
| 442 | (@see ResourceGroupListener). Note that another way of declaring
|
---|
| 443 | resources is to use a script specific to the resource type, if
|
---|
| 444 | available (e.g. .material).
|
---|
| 445 | @par
|
---|
| 446 | Declared resources are not created as Resource instances (and thus
|
---|
| 447 | are not available through their ResourceManager) until initialiseResourceGroup
|
---|
| 448 | is called, at which point all declared resources will become created
|
---|
| 449 | (but unloaded) Resource instances, along with any resources declared
|
---|
| 450 | in scripts in resource locations associated with the group.
|
---|
| 451 | @param name The resource name.
|
---|
| 452 | @param resourceType The type of the resource. Ogre comes preconfigured with
|
---|
| 453 | a number of resource types:
|
---|
| 454 | <ul>
|
---|
| 455 | <li>Font</li>
|
---|
| 456 | <li>GpuProgram</li>
|
---|
| 457 | <li>HighLevelGpuProgram</li>
|
---|
| 458 | <li>Material</li>
|
---|
| 459 | <li>Mesh</li>
|
---|
| 460 | <li>Skeleton</li>
|
---|
| 461 | <li>Texture</li>
|
---|
| 462 | </ul>
|
---|
| 463 | .. but more can be added by plugin ResourceManager classes.
|
---|
| 464 | @param groupName The name of the group to which it will belong.
|
---|
| 465 | @param loadParameters A list of name / value pairs which supply custom
|
---|
| 466 | parameters to the resource which will be required before it can
|
---|
| 467 | be loaded. These are specific to the resource type.
|
---|
| 468 | */
|
---|
| 469 | void declareResource(const String& name, const String& resourceType,
|
---|
| 470 | const String& groupName = DEFAULT_RESOURCE_GROUP_NAME,
|
---|
| 471 | const NameValuePairList& loadParameters = NameValuePairList());
|
---|
| 472 | /** Undeclare a resource.
|
---|
| 473 | @remarks
|
---|
| 474 | Note that this will not cause it to be unloaded
|
---|
| 475 | if it is already loaded, nor will it destroy a resource which has
|
---|
| 476 | already been created if initialiseResourceGroup has been called already.
|
---|
| 477 | Only unloadResourceGroup / clearResourceGroup / destroyResourceGroup
|
---|
| 478 | will do that.
|
---|
| 479 | @param name The name of the resource.
|
---|
| 480 | @param groupName The name of the group this resource was declared in.
|
---|
| 481 | */
|
---|
| 482 | void undeclareResource(const String& name, const String& groupName);
|
---|
| 483 |
|
---|
| 484 | /** Open a single resource by name and return a DataStream
|
---|
| 485 | pointing at the source of the data.
|
---|
| 486 | @param resourceName The name of the resource to locate.
|
---|
| 487 | Even if resource locations are added recursively, you
|
---|
| 488 | must provide a fully qualified name to this method. You
|
---|
| 489 | can find out the matching fully qualified names by using the
|
---|
| 490 | find() method if you need to.
|
---|
| 491 | @param groupName The name of the resource group; this determines which
|
---|
| 492 | locations are searched.
|
---|
| 493 | @returns Shared pointer to data stream containing the data, will be
|
---|
| 494 | destroyed automatically when no longer referenced
|
---|
| 495 | */
|
---|
| 496 | DataStreamPtr openResource(const String& resourceName,
|
---|
| 497 | const String& groupName = DEFAULT_RESOURCE_GROUP_NAME);
|
---|
| 498 |
|
---|
| 499 | /** Open all resources matching a given pattern (which can contain
|
---|
| 500 | the character '*' as a wildcard), and return a collection of
|
---|
| 501 | DataStream objects on them.
|
---|
| 502 | @param pattern The pattern to look for. If resource locations have been
|
---|
| 503 | added recursively, subdirectories will be searched too so this
|
---|
| 504 | does not need to be fully qualified.
|
---|
| 505 | @param groupName The resource group; this determines which locations
|
---|
| 506 | are searched.
|
---|
| 507 | @returns Shared pointer to a data stream list , will be
|
---|
| 508 | destroyed automatically when no longer referenced
|
---|
| 509 | */
|
---|
| 510 | DataStreamListPtr openResources(const String& pattern,
|
---|
| 511 | const String& groupName = DEFAULT_RESOURCE_GROUP_NAME);
|
---|
| 512 |
|
---|
| 513 | /** List all file names in a resource group.
|
---|
| 514 | @note
|
---|
| 515 | This method only returns filenames, you can also retrieve other
|
---|
| 516 | information using listFileInfo.
|
---|
| 517 | @param groupName The name of the group
|
---|
| 518 | @returns A list of filenames matching the criteria, all are fully qualified
|
---|
| 519 | */
|
---|
| 520 | StringVectorPtr listResourceNames(const String& groupName);
|
---|
| 521 |
|
---|
| 522 | /** List all files in a resource group with accompanying information.
|
---|
| 523 | @param groupName The name of the group
|
---|
| 524 | @returns A list of structures detailing quite a lot of information about
|
---|
| 525 | all the files in the archive.
|
---|
| 526 | */
|
---|
| 527 | FileInfoListPtr listResourceFileInfo(const String& groupName);
|
---|
| 528 |
|
---|
| 529 | /** Find all file names matching a given pattern in a resource group.
|
---|
| 530 | @note
|
---|
| 531 | This method only returns filenames, you can also retrieve other
|
---|
| 532 | information using findFileInfo.
|
---|
| 533 | @param groupName The name of the group
|
---|
| 534 | @param pattern The pattern to search for; wildcards (*) are allowed
|
---|
| 535 | @returns A list of filenames matching the criteria, all are fully qualified
|
---|
| 536 | */
|
---|
| 537 | StringVectorPtr findResourceNames(const String& groupName, const String& pattern);
|
---|
| 538 |
|
---|
| 539 | /** Find out if the named file exists in a group.
|
---|
| 540 | @param group The name of the resource group
|
---|
| 541 | @param filename Fully qualified name of the file to test for
|
---|
| 542 | */
|
---|
| 543 | bool resourceExists(const String& group, const String& filename);
|
---|
| 544 |
|
---|
| 545 | /** Find all files matching a given pattern in a group and get
|
---|
| 546 | some detailed information about them.
|
---|
| 547 | @param group The name of the resource group
|
---|
| 548 | @param pattern The pattern to search for; wildcards (*) are allowed
|
---|
| 549 | @returns A list of file information structures for all files matching
|
---|
| 550 | the criteria.
|
---|
| 551 | */
|
---|
| 552 | FileInfoListPtr findResourceFileInfo(const String& group, const String& pattern);
|
---|
| 553 |
|
---|
| 554 |
|
---|
| 555 | /** Adds a ResourceGroupListener which will be called back during
|
---|
| 556 | resource loading events.
|
---|
| 557 | */
|
---|
| 558 | void addResourceGroupListener(ResourceGroupListener* l);
|
---|
| 559 | /** Removes a ResourceGroupListener */
|
---|
| 560 | void removeResourceGroupListener(ResourceGroupListener* l);
|
---|
| 561 |
|
---|
| 562 | /** Sets the resource group that 'world' resources will use.
|
---|
| 563 | @remarks
|
---|
| 564 | This is the group which should be used by SceneManagers implementing
|
---|
| 565 | world geometry when looking for their resources. Defaults to the
|
---|
| 566 | DEFAULT_RESOURCE_GROUP_NAME but this can be altered.
|
---|
| 567 | */
|
---|
| 568 | void setWorldResourceGroupName(const String& groupName) {mWorldGroupName = groupName;}
|
---|
| 569 |
|
---|
| 570 | /// Sets the resource group that 'world' resources will use.
|
---|
| 571 | const String& getWorldResourceGroupName(void) const { return mWorldGroupName; }
|
---|
| 572 |
|
---|
| 573 | /** Associates some world geometry with a resource group, causing it to
|
---|
| 574 | be loaded / unloaded with the resource group.
|
---|
| 575 | @remarks
|
---|
| 576 | You would use this method to essentially defer a call to
|
---|
| 577 | SceneManager::setWorldGeometry to the time when the resource group
|
---|
| 578 | is loaded. The advantage of this is that compatible scene managers
|
---|
| 579 | will include the estimate of the number of loading stages for that
|
---|
| 580 | world geometry when the resource group begins loading, allowing you
|
---|
| 581 | to include that in a loading progress report.
|
---|
| 582 | @param group The name of the resource group
|
---|
| 583 | @param worldGeometry The parameter which should be passed to setWorldGeometry
|
---|
| 584 | @param sceneManager The SceneManager which should be called
|
---|
| 585 | */
|
---|
| 586 | void linkWorldGeometryToResourceGroup(const String& group,
|
---|
| 587 | const String& worldGeometry, SceneManager* sceneManager);
|
---|
| 588 |
|
---|
| 589 | /** Clear any link to world geometry from a resource group.
|
---|
| 590 | @remarks
|
---|
| 591 | Basically undoes a previous call to linkWorldGeometryToResourceGroup.
|
---|
| 592 | */
|
---|
| 593 | void unlinkWorldGeometryFromResourceGroup(const String& group);
|
---|
| 594 |
|
---|
| 595 | /** Shutdown all ResourceManagers, performed as part of clean-up. */
|
---|
| 596 | void shutdownAll(void);
|
---|
| 597 |
|
---|
| 598 |
|
---|
| 599 | /** Internal method for registering a ResourceManager (which should be
|
---|
| 600 | a singleton). Creators of plugins can register new ResourceManagers
|
---|
| 601 | this way if they wish.
|
---|
| 602 | @remarks
|
---|
| 603 | ResourceManagers that wish to parse scripts must also call
|
---|
| 604 | _registerScriptLoader.
|
---|
| 605 | @param resourceType String identifying the resource type, must be unique.
|
---|
| 606 | @param rm Pointer to the ResourceManager instance.
|
---|
| 607 | */
|
---|
| 608 | void _registerResourceManager(const String& resourceType, ResourceManager* rm);
|
---|
| 609 |
|
---|
| 610 | /** Internal method for unregistering a ResourceManager.
|
---|
| 611 | @remarks
|
---|
| 612 | ResourceManagers that wish to parse scripts must also call
|
---|
| 613 | _unregisterScriptLoader.
|
---|
| 614 | @param resourceType String identifying the resource type.
|
---|
| 615 | */
|
---|
| 616 | void _unregisterResourceManager(const String& resourceType);
|
---|
| 617 |
|
---|
| 618 |
|
---|
| 619 | /** Internal method for registering a ScriptLoader.
|
---|
| 620 | @remarks ScriptLoaders parse scripts when resource groups are initialised.
|
---|
| 621 | @param su Pointer to the ScriptLoader instance.
|
---|
| 622 | */
|
---|
| 623 | void _registerScriptLoader(ScriptLoader* su);
|
---|
| 624 |
|
---|
| 625 | /** Internal method for unregistering a ScriptLoader.
|
---|
| 626 | @param su Pointer to the ScriptLoader instance.
|
---|
| 627 | */
|
---|
| 628 | void _unregisterScriptLoader(ScriptLoader* su);
|
---|
| 629 |
|
---|
| 630 | /** Internal method for getting a registered ResourceManager.
|
---|
| 631 | @param resourceType String identifying the resource type.
|
---|
| 632 | */
|
---|
| 633 | ResourceManager* _getResourceManager(const String& resourceType);
|
---|
| 634 |
|
---|
| 635 | /** Internal method called by ResourceManager when a resource is created.
|
---|
| 636 | @param res Weak reference to resource
|
---|
| 637 | */
|
---|
| 638 | void _notifyResourceCreated(ResourcePtr& res);
|
---|
| 639 |
|
---|
| 640 | /** Internal method called by ResourceManager when a resource is removed.
|
---|
| 641 | @param res Weak reference to resource
|
---|
| 642 | */
|
---|
| 643 | void _notifyResourceRemoved(ResourcePtr& res);
|
---|
| 644 |
|
---|
| 645 | /** Internal method called by ResourceManager when all resources
|
---|
| 646 | for that manager are removed.
|
---|
| 647 | @param manager Pointer to the manager for which all resources are being removed
|
---|
| 648 | */
|
---|
| 649 | void _notifyAllResourcesRemoved(ResourceManager* manager);
|
---|
| 650 |
|
---|
| 651 | /** Notify this manager that one stage of world geometry loading has been
|
---|
| 652 | started.
|
---|
| 653 | @remarks
|
---|
| 654 | Custom SceneManagers which load custom world geometry should call this
|
---|
| 655 | method the number of times equal to the value they return from
|
---|
| 656 | SceneManager::estimateWorldGeometry while loading their geometry.
|
---|
| 657 | */
|
---|
| 658 | void _notifyWorldGeometryStageStarted(const String& description);
|
---|
| 659 | /** Notify this manager that one stage of world geometry loading has been
|
---|
| 660 | completed.
|
---|
| 661 | @remarks
|
---|
| 662 | Custom SceneManagers which load custom world geometry should call this
|
---|
| 663 | method the number of times equal to the value they return from
|
---|
| 664 | SceneManager::estimateWorldGeometry while loading their geometry.
|
---|
| 665 | */
|
---|
| 666 | void _notifyWorldGeometryStageEnded(void);
|
---|
| 667 |
|
---|
| 668 | /** Get a list of the currently defined resource groups.
|
---|
| 669 | @note This method intentionally returns a copy rather than a reference in
|
---|
| 670 | order to avoid any contention issues in multithreaded applications.
|
---|
| 671 | @returns A copy of list of currently defined groups.
|
---|
| 672 | */
|
---|
| 673 | StringVector getResourceGroups(void);
|
---|
| 674 | /** Get the list of resource declarations for the specified group name.
|
---|
| 675 | @note This method intentionally returns a copy rather than a reference in
|
---|
| 676 | order to avoid any contention issues in multithreaded applications.
|
---|
| 677 | @param groupName The name of the group
|
---|
| 678 | @returns A copy of list of currently defined resources.
|
---|
| 679 | */
|
---|
| 680 | ResourceDeclarationList getResourceDeclarationList(const String& groupName);
|
---|
| 681 |
|
---|
| 682 | /** Override standard Singleton retrieval.
|
---|
| 683 | @remarks
|
---|
| 684 | Why do we do this? Well, it's because the Singleton
|
---|
| 685 | implementation is in a .h file, which means it gets compiled
|
---|
| 686 | into anybody who includes it. This is needed for the
|
---|
| 687 | Singleton template to work, but we actually only want it
|
---|
| 688 | compiled into the implementation of the class based on the
|
---|
| 689 | Singleton, not all of them. If we don't change this, we get
|
---|
| 690 | link errors when trying to use the Singleton-based class from
|
---|
| 691 | an outside dll.
|
---|
| 692 | @par
|
---|
| 693 | This method just delegates to the template version anyway,
|
---|
| 694 | but the implementation stays in this single compilation unit,
|
---|
| 695 | preventing link errors.
|
---|
| 696 | */
|
---|
| 697 | static ResourceGroupManager& getSingleton(void);
|
---|
| 698 | /** Override standard Singleton retrieval.
|
---|
| 699 | @remarks
|
---|
| 700 | Why do we do this? Well, it's because the Singleton
|
---|
| 701 | implementation is in a .h file, which means it gets compiled
|
---|
| 702 | into anybody who includes it. This is needed for the
|
---|
| 703 | Singleton template to work, but we actually only want it
|
---|
| 704 | compiled into the implementation of the class based on the
|
---|
| 705 | Singleton, not all of them. If we don't change this, we get
|
---|
| 706 | link errors when trying to use the Singleton-based class from
|
---|
| 707 | an outside dll.
|
---|
| 708 | @par
|
---|
| 709 | This method just delegates to the template version anyway,
|
---|
| 710 | but the implementation stays in this single compilation unit,
|
---|
| 711 | preventing link errors.
|
---|
| 712 | */
|
---|
| 713 | static ResourceGroupManager* getSingletonPtr(void);
|
---|
| 714 |
|
---|
| 715 | };
|
---|
| 716 | }
|
---|
| 717 |
|
---|
| 718 | #endif
|
---|