Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Related Pages

Ogre::ResourceGroupManager Class Reference

This singleton class manages the list of resource groups, and notifying the various resource managers of their obligations to load / unload resources in a group. More...

#include <OgreResourceGroupManager.h>

Inheritance diagram for Ogre::ResourceGroupManager:

Ogre::Singleton< ResourceGroupManager > List of all members.

Public Types

typedef std::list< ResourceDeclarationResourceDeclarationList
 List of resource declarations.


Public Member Functions

 ResourceGroupManager ()
virtual ~ResourceGroupManager ()
void createResourceGroup (const String &name)
 Create a resource group.

void initialiseResourceGroup (const String &name)
 Initialises a resource group.

void initialiseAllResourceGroups (void)
 Initialise all resource groups which are yet to be initialised.

void loadResourceGroup (const String &name, bool loadMainResources=true, bool loadWorldGeom=true)
 Loads a resource group.

void unloadResourceGroup (const String &name, bool reloadableOnly=true)
 Unloads a resource group.

void unloadUnreferencedResourcesInGroup (const String &name, bool reloadableOnly=true)
 Unload all resources which are not referenced by any other object.

void clearResourceGroup (const String &name)
 Clears a resource group.

void destroyResourceGroup (const String &name)
 Destroys a resource group, clearing it first, destroying the resources which are part of it, and then removing it from the list of resource groups.

void addResourceLocation (const String &name, const String &locType, const String &resGroup=DEFAULT_RESOURCE_GROUP_NAME, bool recursive=false)
 Method to add a resource location to for a given resource group.

void removeResourceLocation (const String &name, const String &resGroup=DEFAULT_RESOURCE_GROUP_NAME)
 Removes a resource location from the search path.

void declareResource (const String &name, const String &resourceType, const String &groupName=DEFAULT_RESOURCE_GROUP_NAME, const NameValuePairList &loadParameters=NameValuePairList())
 Declares a resource to be a part of a resource group, allowing you to load and unload it as part of the group.

void declareResource (const String &name, const String &resourceType, const String &groupName, ManualResourceLoader *loader, const NameValuePairList &loadParameters=NameValuePairList())
 Declares a resource to be a part of a resource group, allowing you to load and unload it as part of the group.

void undeclareResource (const String &name, const String &groupName)
 Undeclare a resource.

DataStreamPtr openResource (const String &resourceName, const String &groupName=DEFAULT_RESOURCE_GROUP_NAME, bool searchGroupsIfNotFound=true, Resource *resourceBeingLoaded=0)
 Open a single resource by name and return a DataStream pointing at the source of the data.

DataStreamListPtr openResources (const String &pattern, const String &groupName=DEFAULT_RESOURCE_GROUP_NAME)
 Open all resources matching a given pattern (which can contain the character '*' as a wildcard), and return a collection of DataStream objects on them.

StringVectorPtr listResourceNames (const String &groupName)
 List all file names in a resource group.

FileInfoListPtr listResourceFileInfo (const String &groupName)
 List all files in a resource group with accompanying information.

StringVectorPtr findResourceNames (const String &groupName, const String &pattern)
 Find all file names matching a given pattern in a resource group.

bool resourceExists (const String &group, const String &filename)
 Find out if the named file exists in a group.

bool resourceExists (ResourceGroup *group, const String &filename)
 Find out if the named file exists in a group.

const StringfindGroupContainingResource (const String &filename)
 Find the group in which a resource exists.

FileInfoListPtr findResourceFileInfo (const String &group, const String &pattern)
 Find all files matching a given pattern in a group and get some detailed information about them.

void addResourceGroupListener (ResourceGroupListener *l)
 Adds a ResourceGroupListener which will be called back during resource loading events.

void removeResourceGroupListener (ResourceGroupListener *l)
 Removes a ResourceGroupListener.

void setWorldResourceGroupName (const String &groupName)
 Sets the resource group that 'world' resources will use.

const StringgetWorldResourceGroupName (void) const
 Sets the resource group that 'world' resources will use.

void linkWorldGeometryToResourceGroup (const String &group, const String &worldGeometry, SceneManager *sceneManager)
 Associates some world geometry with a resource group, causing it to be loaded / unloaded with the resource group.

void unlinkWorldGeometryFromResourceGroup (const String &group)
 Clear any link to world geometry from a resource group.

void shutdownAll (void)
 Shutdown all ResourceManagers, performed as part of clean-up.

void _registerResourceManager (const String &resourceType, ResourceManager *rm)
 Internal method for registering a ResourceManager (which should be a singleton).

void _unregisterResourceManager (const String &resourceType)
 Internal method for unregistering a ResourceManager.

void _registerScriptLoader (ScriptLoader *su)
 Internal method for registering a ScriptLoader.

void _unregisterScriptLoader (ScriptLoader *su)
 Internal method for unregistering a ScriptLoader.

ResourceManager_getResourceManager (const String &resourceType)
 Internal method for getting a registered ResourceManager.

void _notifyResourceCreated (ResourcePtr &res)
 Internal method called by ResourceManager when a resource is created.

void _notifyResourceRemoved (ResourcePtr &res)
 Internal method called by ResourceManager when a resource is removed.

void _notifyResourceGroupChanged (const String &oldGroup, Resource *res)
 Internale method to notify the group manager that a resource has changed group (only applicable for autodetect group).

void _notifyAllResourcesRemoved (ResourceManager *manager)
 Internal method called by ResourceManager when all resources for that manager are removed.

void _notifyWorldGeometryStageStarted (const String &description)
 Notify this manager that one stage of world geometry loading has been started.

void _notifyWorldGeometryStageEnded (void)
 Notify this manager that one stage of world geometry loading has been completed.

StringVector getResourceGroups (void)
 Get a list of the currently defined resource groups.

ResourceDeclarationList getResourceDeclarationList (const String &groupName)
 Get the list of resource declarations for the specified group name.


Static Public Member Functions

ResourceGroupManagergetSingleton (void)
 Override standard Singleton retrieval.

ResourceGroupManagergetSingletonPtr (void)
 Override standard Singleton retrieval.


Static Public Attributes

OGRE_AUTO_MUTEX String DEFAULT_RESOURCE_GROUP_NAME
 Default resource group name.

String INTERNAL_RESOURCE_GROUP_NAME
 Internal resource group name (should be used by OGRE internal only).

String BOOTSTRAP_RESOURCE_GROUP_NAME
 Bootstrap resource group name (min OGRE resources).

String AUTODETECT_RESOURCE_GROUP_NAME
 Special resource group name which causes resource group to be automatically determined based on searching for the resource in all groups.

size_t RESOURCE_SYSTEM_NUM_REFERENCE_COUNTS
 The number of reference counts held per resource by the resource system.


Protected Types

typedef std::map< String,
ResourceManager * > 
ResourceManagerMap
 Map of resource types (strings) to ResourceManagers, used to notify them to load / unload group contents.

typedef std::multimap< Real,
ScriptLoader * > 
ScriptLoaderOrderMap
 Map of loading order (Real) to ScriptLoader, used to order script parsing.

typedef std::vector< ResourceGroupListener * > ResourceGroupListenerList
typedef std::map< String,
Archive * > 
ResourceLocationIndex
 Resource index entry, resourcename->location.

typedef std::list< ResourceLocation * > LocationList
 List of possible file locations.

typedef std::list< ResourcePtrLoadUnloadResourceList
 List of resources which can be loaded / unloaded.

typedef std::map< String,
ResourceGroup * > 
ResourceGroupMap
 Map from resource group names to groups.


Protected Member Functions

void parseResourceGroupScripts (ResourceGroup *grp)
 Parses all the available scripts found in the resource locations for the given group, for all ResourceManagers.

void createDeclaredResources (ResourceGroup *grp)
 Create all the pre-declared resources.

void addCreatedResource (ResourcePtr &res, ResourceGroup &group)
 Adds a created resource to a group.

ResourceGroupgetResourceGroup (const String &name)
 Get resource group.

void dropGroupContents (ResourceGroup *grp)
 Drops contents of a group, leave group there, notify ResourceManagers.

void deleteGroup (ResourceGroup *grp)
 Delete a group for shutdown - don't notify ResourceManagers.

ResourceGroupfindGroupContainingResourceImpl (const String &filename)
 Internal find method for auto groups.

void fireResourceGroupScriptingStarted (const String &groupName, size_t scriptCount)
 Internal event firing method.

void fireScriptStarted (const String &scriptName)
 Internal event firing method.

void fireScriptEnded (void)
 Internal event firing method.

void fireResourceGroupScriptingEnded (const String &groupName)
 Internal event firing method.

void fireResourceGroupLoadStarted (const String &groupName, size_t resourceCount)
 Internal event firing method.

void fireResourceStarted (const ResourcePtr &resource)
 Internal event firing method.

void fireResourceEnded (void)
 Internal event firing method.

void fireResourceGroupLoadEnded (const String &groupName)
 Internal event firing method.


Protected Attributes

ResourceManagerMap mResourceManagerMap
ScriptLoaderOrderMap mScriptLoaderOrderMap
ResourceGroupListenerList mResourceGroupListenerList
ResourceGroupMap mResourceGroupMap
String mWorldGroupName
 Group name for world resources.

ResourceGroupmCurrentGroup
 Stored current group - optimisation for when bulk loading a group.


Static Protected Attributes

ResourceGroupManagerms_Singleton

Detailed Description

This singleton class manages the list of resource groups, and notifying the various resource managers of their obligations to load / unload resources in a group.

It also provides facilities to monitor resource loading per group (to do progress bars etc), provided the resources that are required are pre-registered.

Defining new resource groups, and declaring the resources you intend to use in advance is optional, however it is a very useful feature. In addition, if a ResourceManager supports the definition of resources through scripts, then this is the class which drives the locating of the scripts and telling the ResourceManager to parse them.
There are several states that a resource can be in (the concept, not the object instance in this case):
  1. Undefined. Nobody knows about this resource yet. It might be in the filesystem, but Ogre is oblivious to it at the moment - there is no Resource instance. This might be because it's never been declared (either in a script, or using ResourceGroupManager::declareResource), or it may have previously been a valid Resource instance but has been removed, either individually through ResourceManager::remove or as a group through ResourceGroupManager::clearResourceGroup.
  2. Declared. Ogre has some forewarning of this resource, either through calling ResourceGroupManager::declareResource, or by declaring the resource in a script file which is on one of the resource locations which has been defined for a group. There is still no instance of Resource, but Ogre will know to create this resource when ResourceGroupManager::initialiseResourceGroup is called (which is automatic if you declare the resource group before Root::initialise).
  3. Unloaded. There is now a Resource instance for this resource, although it is not loaded. This means that code which looks for this named resource will find it, but the Resource is not using a lot of memory because it is in an unloaded state. A Resource can get into this state by having just been created by ResourceGroupManager::initialiseResourceGroup (either from a script, or from a call to declareResource), by being created directly from code (ResourceManager::create), or it may have previously been loaded and has been unloaded, either individually through Resource::unload, or as a group through ResourceGroupManager::unloadResourceGroup.
  4. LoadedThe Resource instance is fully loaded. This may have happened implicitly because something used it, or it may have been loaded as part of a group.
See also:
ResourceGroupManager::declareResource

ResourceGroupManager::initialiseResourceGroup

ResourceGroupManager::loadResourceGroup

ResourceGroupManager::unloadResourceGroup

ResourceGroupManager::clearResourceGroup

Definition at line 161 of file OgreResourceGroupManager.h.


Member Typedef Documentation

typedef std::list<ResourcePtr> Ogre::ResourceGroupManager::LoadUnloadResourceList [protected]
 

List of resources which can be loaded / unloaded.

Definition at line 211 of file OgreResourceGroupManager.h.

typedef std::list<ResourceLocation*> Ogre::ResourceGroupManager::LocationList [protected]
 

List of possible file locations.

Definition at line 209 of file OgreResourceGroupManager.h.

typedef std::list<ResourceDeclaration> Ogre::ResourceGroupManager::ResourceDeclarationList
 

List of resource declarations.

Definition at line 184 of file OgreResourceGroupManager.h.

typedef std::vector<ResourceGroupListener*> Ogre::ResourceGroupManager::ResourceGroupListenerList [protected]
 

Definition at line 194 of file OgreResourceGroupManager.h.

typedef std::map<String, ResourceGroup*> Ogre::ResourceGroupManager::ResourceGroupMap [protected]
 

Map from resource group names to groups.

Definition at line 239 of file OgreResourceGroupManager.h.

typedef std::map<String, Archive*> Ogre::ResourceGroupManager::ResourceLocationIndex [protected]
 

Resource index entry, resourcename->location.

Definition at line 198 of file OgreResourceGroupManager.h.

typedef std::map<String, ResourceManager*> Ogre::ResourceGroupManager::ResourceManagerMap [protected]
 

Map of resource types (strings) to ResourceManagers, used to notify them to load / unload group contents.

Definition at line 187 of file OgreResourceGroupManager.h.

typedef std::multimap<Real, ScriptLoader*> Ogre::ResourceGroupManager::ScriptLoaderOrderMap [protected]
 

Map of loading order (Real) to ScriptLoader, used to order script parsing.

Definition at line 191 of file OgreResourceGroupManager.h.


Constructor & Destructor Documentation

Ogre::ResourceGroupManager::ResourceGroupManager  ) 
 

virtual Ogre::ResourceGroupManager::~ResourceGroupManager  )  [virtual]
 


Member Function Documentation

ResourceManager* Ogre::ResourceGroupManager::_getResourceManager const String resourceType  ) 
 

Internal method for getting a registered ResourceManager.

Parameters:
resourceType String identifying the resource type.

void Ogre::ResourceGroupManager::_notifyAllResourcesRemoved ResourceManager manager  ) 
 

Internal method called by ResourceManager when all resources for that manager are removed.

Parameters:
manager Pointer to the manager for which all resources are being removed

void Ogre::ResourceGroupManager::_notifyResourceCreated ResourcePtr res  ) 
 

Internal method called by ResourceManager when a resource is created.

Parameters:
res Weak reference to resource

void Ogre::ResourceGroupManager::_notifyResourceGroupChanged const String oldGroup,
Resource res
 

Internale method to notify the group manager that a resource has changed group (only applicable for autodetect group).

void Ogre::ResourceGroupManager::_notifyResourceRemoved ResourcePtr res  ) 
 

Internal method called by ResourceManager when a resource is removed.

Parameters:
res Weak reference to resource

void Ogre::ResourceGroupManager::_notifyWorldGeometryStageEnded void   ) 
 

Notify this manager that one stage of world geometry loading has been completed.

Remarks:
Custom SceneManagers which load custom world geometry should call this method the number of times equal to the value they return from SceneManager::estimateWorldGeometry while loading their geometry.

void Ogre::ResourceGroupManager::_notifyWorldGeometryStageStarted const String description  ) 
 

Notify this manager that one stage of world geometry loading has been started.

Remarks:
Custom SceneManagers which load custom world geometry should call this method the number of times equal to the value they return from SceneManager::estimateWorldGeometry while loading their geometry.

void Ogre::ResourceGroupManager::_registerResourceManager const String resourceType,
ResourceManager rm
 

Internal method for registering a ResourceManager (which should be a singleton).

Creators of plugins can register new ResourceManagers this way if they wish.

Remarks:
ResourceManagers that wish to parse scripts must also call _registerScriptLoader.
Parameters:
resourceType String identifying the resource type, must be unique.
rm Pointer to the ResourceManager instance.

void Ogre::ResourceGroupManager::_registerScriptLoader ScriptLoader su  ) 
 

Internal method for registering a ScriptLoader.

Remarks:
ScriptLoaders parse scripts when resource groups are initialised.
Parameters:
su Pointer to the ScriptLoader instance.

void Ogre::ResourceGroupManager::_unregisterResourceManager const String resourceType  ) 
 

Internal method for unregistering a ResourceManager.

Remarks:
ResourceManagers that wish to parse scripts must also call _unregisterScriptLoader.
Parameters:
resourceType String identifying the resource type.

void Ogre::ResourceGroupManager::_unregisterScriptLoader ScriptLoader su  ) 
 

Internal method for unregistering a ScriptLoader.

Parameters:
su Pointer to the ScriptLoader instance.

void Ogre::ResourceGroupManager::addCreatedResource ResourcePtr res,
ResourceGroup group
[protected]
 

Adds a created resource to a group.

void Ogre::ResourceGroupManager::addResourceGroupListener ResourceGroupListener l  ) 
 

Adds a ResourceGroupListener which will be called back during resource loading events.

void Ogre::ResourceGroupManager::addResourceLocation const String name,
const String locType,
const String resGroup = DEFAULT_RESOURCE_GROUP_NAME,
bool  recursive = false
 

Method to add a resource location to for a given resource group.

Remarks:
Resource locations are places which are searched to load resource files. When you choose to load a file, or to search for valid files to load, the resource locations are used.
Parameters:
name The name of the resource location; probably a directory, zip file, URL etc.
locType The codename for the resource type, which must correspond to the Archive factory which is providing the implementation.
resGroup The name of the resource group for which this location is to apply. ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME is the default group which always exists, and can be used for resources which are unlikely to be unloaded until application shutdown. Otherwise it must be the name of a group; if it has not already been created with createResourceGroup then it is created automatically.
recursive Whether subdirectories will be searched for files when using a pattern match (such as *.material), and whether subdirectories will be indexed. This can slow down initial loading of the archive and searches. When opening a resource you still need to use the fully qualified name, this allows duplicate names in alternate paths.

void Ogre::ResourceGroupManager::clearResourceGroup const String name  ) 
 

Clears a resource group.

Remarks:
This method unloads all resources in the group, but in addition it removes all those resources from their ResourceManagers, and then clears all the members from the list. That means after calling this method, there are no resources declared as part of the named group any more. Resource locations still persist though.
Parameters:
name The name to of the resource group to clear.

void Ogre::ResourceGroupManager::createDeclaredResources ResourceGroup grp  )  [protected]
 

Create all the pre-declared resources.

Remarks:
Called as part of initialiseResourceGroup

void Ogre::ResourceGroupManager::createResourceGroup const String name  ) 
 

Create a resource group.

Remarks:
A resource group allows you to define a set of resources that can be loaded / unloaded as a unit. For example, it might be all the resources used for the level of a game. There is always one predefined resource group called ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME, which is typically used to hold all resources which do not need to be unloaded until shutdown. There is another predefined resource group called ResourceGroupManager::INTERNAL_RESOURCE_GROUP_NAME too, which should be used by OGRE internal only, the resources created in this group aren't supposed to modify, unload or remove by user. You can create additional ones so that you can control the life of your resources in whichever way you wish. There is one other predefined value, ResourceGroupManager::AUTODETECT_RESOURCE_GROUP_NAME; using this causes the group name to be derived at load time by searching for the resource in the resource locations of each group in turn.
Once you have defined a resource group, resources which will be loaded as part of it are defined in one of 3 ways:
  1. Manually through declareResource(); this is useful for scripted declarations since it is entirely generalised, and does not create Resource instances right away
  2. Through the use of scripts; some ResourceManager subtypes have script formats (e.g. .material, .overlay) which can be used to declare resources
  3. By calling ResourceManager::create to create a resource manually. This resource will go on the list for it's group and will be loaded and unloaded with that group
You must remember to call initialiseResourceGroup if you intend to use the first 2 types.
Parameters:
name The name to give the resource group.

void Ogre::ResourceGroupManager::declareResource const String name,
const String resourceType,
const String groupName,
ManualResourceLoader loader,
const NameValuePairList loadParameters = NameValuePairList()
 

Declares a resource to be a part of a resource group, allowing you to load and unload it as part of the group.

Remarks:
By declaring resources before you attempt to use them, you can more easily control the loading and unloading of those resources by their group. Declaring them also allows them to be enumerated, which means events can be raised to indicate the loading progress (
See also:
ResourceGroupListener). Note that another way of declaring resources is to use a script specific to the resource type, if available (e.g. .material).
Declared resources are not created as Resource instances (and thus are not available through their ResourceManager) until initialiseResourceGroup is called, at which point all declared resources will become created (but unloaded) Resource instances, along with any resources declared in scripts in resource locations associated with the group.
Parameters:
name The resource name.
resourceType The type of the resource. Ogre comes preconfigured with a number of resource types: .. but more can be added by plugin ResourceManager classes.
groupName The name of the group to which it will belong.
loader Pointer to a ManualResourceLoader implementation which will be called when the Resource wishes to load. If supplied, the resource is manually loaded, otherwise it'll loading from file automatic.
Note:
We don't support declare manually loaded resource without loader here, since it's meaningless.
Parameters:
loadParameters A list of name / value pairs which supply custom parameters to the resource which will be required before it can be loaded. These are specific to the resource type.

void Ogre::ResourceGroupManager::declareResource const String name,
const String resourceType,
const String groupName = DEFAULT_RESOURCE_GROUP_NAME,
const NameValuePairList loadParameters = NameValuePairList()
 

Declares a resource to be a part of a resource group, allowing you to load and unload it as part of the group.

Remarks:
By declaring resources before you attempt to use them, you can more easily control the loading and unloading of those resources by their group. Declaring them also allows them to be enumerated, which means events can be raised to indicate the loading progress (
See also:
ResourceGroupListener). Note that another way of declaring resources is to use a script specific to the resource type, if available (e.g. .material).
Declared resources are not created as Resource instances (and thus are not available through their ResourceManager) until initialiseResourceGroup is called, at which point all declared resources will become created (but unloaded) Resource instances, along with any resources declared in scripts in resource locations associated with the group.
Parameters:
name The resource name.
resourceType The type of the resource. Ogre comes preconfigured with a number of resource types: .. but more can be added by plugin ResourceManager classes.
groupName The name of the group to which it will belong.
loadParameters A list of name / value pairs which supply custom parameters to the resource which will be required before it can be loaded. These are specific to the resource type.

void Ogre::ResourceGroupManager::deleteGroup ResourceGroup grp  )  [protected]
 

Delete a group for shutdown - don't notify ResourceManagers.

void Ogre::ResourceGroupManager::destroyResourceGroup const String name  ) 
 

Destroys a resource group, clearing it first, destroying the resources which are part of it, and then removing it from the list of resource groups.

Parameters:
name The name of the resource group to destroy.

void Ogre::ResourceGroupManager::dropGroupContents ResourceGroup grp  )  [protected]
 

Drops contents of a group, leave group there, notify ResourceManagers.

const String& Ogre::ResourceGroupManager::findGroupContainingResource const String filename  ) 
 

Find the group in which a resource exists.

Parameters:
filename Fully qualified name of the file the resource should be found as
Returns:
Name of the resource group the resource was found in. An exception is thrown if the group could not be determined.

ResourceGroup* Ogre::ResourceGroupManager::findGroupContainingResourceImpl const String filename  )  [protected]
 

Internal find method for auto groups.

FileInfoListPtr Ogre::ResourceGroupManager::findResourceFileInfo const String group,
const String pattern
 

Find all files matching a given pattern in a group and get some detailed information about them.

Parameters:
group The name of the resource group
pattern The pattern to search for; wildcards (*) are allowed
Returns:
A list of file information structures for all files matching the criteria.

StringVectorPtr Ogre::ResourceGroupManager::findResourceNames const String groupName,
const String pattern
 

Find all file names matching a given pattern in a resource group.

Note:
This method only returns filenames, you can also retrieve other information using findFileInfo.
Parameters:
groupName The name of the group
pattern The pattern to search for; wildcards (*) are allowed
Returns:
A list of filenames matching the criteria, all are fully qualified

void Ogre::ResourceGroupManager::fireResourceEnded void   )  [protected]
 

Internal event firing method.

void Ogre::ResourceGroupManager::fireResourceGroupLoadEnded const String groupName  )  [protected]
 

Internal event firing method.

void Ogre::ResourceGroupManager::fireResourceGroupLoadStarted const String groupName,
size_t  resourceCount
[protected]
 

Internal event firing method.

void Ogre::ResourceGroupManager::fireResourceGroupScriptingEnded const String groupName  )  [protected]
 

Internal event firing method.

void Ogre::ResourceGroupManager::fireResourceGroupScriptingStarted const String groupName,
size_t  scriptCount
[protected]
 

Internal event firing method.

void Ogre::ResourceGroupManager::fireResourceStarted const ResourcePtr resource  )  [protected]
 

Internal event firing method.

void Ogre::ResourceGroupManager::fireScriptEnded void   )  [protected]
 

Internal event firing method.

void Ogre::ResourceGroupManager::fireScriptStarted const String scriptName  )  [protected]
 

Internal event firing method.

ResourceDeclarationList Ogre::ResourceGroupManager::getResourceDeclarationList const String groupName  ) 
 

Get the list of resource declarations for the specified group name.

Note:
This method intentionally returns a copy rather than a reference in order to avoid any contention issues in multithreaded applications.
Parameters:
groupName The name of the group
Returns:
A copy of list of currently defined resources.

ResourceGroup* Ogre::ResourceGroupManager::getResourceGroup const String name  )  [protected]
 

Get resource group.

StringVector Ogre::ResourceGroupManager::getResourceGroups void   ) 
 

Get a list of the currently defined resource groups.

Note:
This method intentionally returns a copy rather than a reference in order to avoid any contention issues in multithreaded applications.
Returns:
A copy of list of currently defined groups.

ResourceGroupManager& Ogre::ResourceGroupManager::getSingleton void   )  [static]
 

Override standard Singleton retrieval.

Remarks:
Why do we do this? Well, it's because the Singleton implementation is in a .h file, which means it gets compiled into anybody who includes it. This is needed for the Singleton template to work, but we actually only want it compiled into the implementation of the class based on the Singleton, not all of them. If we don't change this, we get link errors when trying to use the Singleton-based class from an outside dll.
This method just delegates to the template version anyway, but the implementation stays in this single compilation unit, preventing link errors.

Reimplemented from Ogre::Singleton< ResourceGroupManager >.

ResourceGroupManager* Ogre::ResourceGroupManager::getSingletonPtr void   )  [static]
 

Override standard Singleton retrieval.

Remarks:
Why do we do this? Well, it's because the Singleton implementation is in a .h file, which means it gets compiled into anybody who includes it. This is needed for the Singleton template to work, but we actually only want it compiled into the implementation of the class based on the Singleton, not all of them. If we don't change this, we get link errors when trying to use the Singleton-based class from an outside dll.
This method just delegates to the template version anyway, but the implementation stays in this single compilation unit, preventing link errors.

Reimplemented from Ogre::Singleton< ResourceGroupManager >.

const String& Ogre::ResourceGroupManager::getWorldResourceGroupName void   )  const
 

Sets the resource group that 'world' resources will use.

Definition at line 670 of file OgreResourceGroupManager.h.

References Ogre::String.

void Ogre::ResourceGroupManager::initialiseAllResourceGroups void   ) 
 

Initialise all resource groups which are yet to be initialised.

See also:
ResourceGroupManager::intialiseResourceGroup

void Ogre::ResourceGroupManager::initialiseResourceGroup const String name  ) 
 

Initialises a resource group.

Remarks:
After creating a resource group, adding some resource locations, and perhaps pre-declaring some resources using declareResource(), but before you need to use the resources in the group, you should call this method to initialise the group. By calling this, you are triggering the following processes:
  1. Scripts for all resource types which support scripting are parsed from the resource locations, and resources within them are created (but not loaded yet).
  2. Creates all the resources which have just pre-declared using declareResource (again, these are not loaded yet)
So what this essentially does is create a bunch of unloaded Resource entries in the respective ResourceManagers based on scripts, and resources you've pre-declared. That means that code looking for these resources will find them, but they won't be taking up much memory yet, until they are either used, or they are loaded in bulk using loadResourceGroup. Loading the resource group in bulk is entirely optional, but has the advantage of coming with progress reporting as resources are loaded.
Failure to call this method means that loadResourceGroup will do nothing, and any resources you define in scripts will not be found. Similarly, once you have called this method you won't be able to pick up any new scripts or pre-declared resources, unless you call clearResourceGroup, set up declared resources, and call this method again.
Note:
When you call Root::initialise, all resource groups that have already been created are automatically initialised too. Therefore you do not need to call this method for groups you define and set up before you call Root::initialise. However, since one of the most useful features of resource groups is to set them up after the main system initialisation has occurred (e.g. a group per game level), you must remember to call this method for the groups you create after this.
Parameters:
name The name of the resource group to initialise

void Ogre::ResourceGroupManager::linkWorldGeometryToResourceGroup const String group,
const String worldGeometry,
SceneManager sceneManager
 

Associates some world geometry with a resource group, causing it to be loaded / unloaded with the resource group.

Remarks:
You would use this method to essentially defer a call to SceneManager::setWorldGeometry to the time when the resource group is loaded. The advantage of this is that compatible scene managers will include the estimate of the number of loading stages for that world geometry when the resource group begins loading, allowing you to include that in a loading progress report.
Parameters:
group The name of the resource group
worldGeometry The parameter which should be passed to setWorldGeometry
sceneManager The SceneManager which should be called

FileInfoListPtr Ogre::ResourceGroupManager::listResourceFileInfo const String groupName  ) 
 

List all files in a resource group with accompanying information.

Parameters:
groupName The name of the group
Returns:
A list of structures detailing quite a lot of information about all the files in the archive.

StringVectorPtr Ogre::ResourceGroupManager::listResourceNames const String groupName  ) 
 

List all file names in a resource group.

Note:
This method only returns filenames, you can also retrieve other information using listFileInfo.
Parameters:
groupName The name of the group
Returns:
A list of filenames matching the criteria, all are fully qualified

void Ogre::ResourceGroupManager::loadResourceGroup const String name,
bool  loadMainResources = true,
bool  loadWorldGeom = true
 

Loads a resource group.

Remarks:
Loads any created resources which are part of the named group. Note that resources must have already been created by calling ResourceManager::create, or declared using declareResource() or in a script (such as .material and .overlay). The latter requires that initialiseResourceGroup has been called.
When this method is called, this class will callback any ResourceGroupListeners which have been registered to update them on progress.
Parameters:
name The name to of the resource group to load.
loadMainResources If true, loads normal resources associated with the group (you might want to set this to false if you wanted to just load world geometry in bulk)
loadWorldGeom If true, loads any linked world geometry
See also:
ResourceGroupManager::linkWorldGeometryToResourceGroup

DataStreamPtr Ogre::ResourceGroupManager::openResource const String resourceName,
const String groupName = DEFAULT_RESOURCE_GROUP_NAME,
bool  searchGroupsIfNotFound = true,
Resource resourceBeingLoaded = 0
 

Open a single resource by name and return a DataStream pointing at the source of the data.

Parameters:
resourceName The name of the resource to locate. Even if resource locations are added recursively, you must provide a fully qualified name to this method. You can find out the matching fully qualified names by using the find() method if you need to.
groupName The name of the resource group; this determines which locations are searched.
searchGroupsIfNotFound If true, if the resource is not found in the group specified, other groups will be searched. If you're loading a real Resource using this option, you must also provide the resourceBeingLoaded parameter to enable the group membership to be changed
resourceBeingLoaded Optional pointer to the resource being loaded, which you should supply if you want
Returns:
Shared pointer to data stream containing the data, will be destroyed automatically when no longer referenced

DataStreamListPtr Ogre::ResourceGroupManager::openResources const String pattern,
const String groupName = DEFAULT_RESOURCE_GROUP_NAME
 

Open all resources matching a given pattern (which can contain the character '*' as a wildcard), and return a collection of DataStream objects on them.

Parameters:
pattern The pattern to look for. If resource locations have been added recursively, subdirectories will be searched too so this does not need to be fully qualified.
groupName The resource group; this determines which locations are searched.
Returns:
Shared pointer to a data stream list , will be destroyed automatically when no longer referenced

void Ogre::ResourceGroupManager::parseResourceGroupScripts ResourceGroup grp  )  [protected]
 

Parses all the available scripts found in the resource locations for the given group, for all ResourceManagers.

Remarks:
Called as part of initialiseResourceGroup

void Ogre::ResourceGroupManager::removeResourceGroupListener ResourceGroupListener l  ) 
 

Removes a ResourceGroupListener.

void Ogre::ResourceGroupManager::removeResourceLocation const String name,
const String resGroup = DEFAULT_RESOURCE_GROUP_NAME
 

Removes a resource location from the search path.

bool Ogre::ResourceGroupManager::resourceExists ResourceGroup group,
const String filename
 

Find out if the named file exists in a group.

Parameters:
group Pointer to the resource group
filename Fully qualified name of the file to test for

bool Ogre::ResourceGroupManager::resourceExists const String group,
const String filename
 

Find out if the named file exists in a group.

Parameters:
group The name of the resource group
filename Fully qualified name of the file to test for

void Ogre::ResourceGroupManager::setWorldResourceGroupName const String groupName  ) 
 

Sets the resource group that 'world' resources will use.

Remarks:
This is the group which should be used by SceneManagers implementing world geometry when looking for their resources. Defaults to the DEFAULT_RESOURCE_GROUP_NAME but this can be altered.

Definition at line 667 of file OgreResourceGroupManager.h.

References Ogre::String.

void Ogre::ResourceGroupManager::shutdownAll void   ) 
 

Shutdown all ResourceManagers, performed as part of clean-up.

void Ogre::ResourceGroupManager::undeclareResource const String name,
const String groupName
 

Undeclare a resource.

Remarks:
Note that this will not cause it to be unloaded if it is already loaded, nor will it destroy a resource which has already been created if initialiseResourceGroup has been called already. Only unloadResourceGroup / clearResourceGroup / destroyResourceGroup will do that.
Parameters:
name The name of the resource.
groupName The name of the group this resource was declared in.

void Ogre::ResourceGroupManager::unlinkWorldGeometryFromResourceGroup const String group  ) 
 

Clear any link to world geometry from a resource group.

Remarks:
Basically undoes a previous call to linkWorldGeometryToResourceGroup.

void Ogre::ResourceGroupManager::unloadResourceGroup const String name,
bool  reloadableOnly = true
 

Unloads a resource group.

Remarks:
This method unloads all the resources that have been declared as being part of the named resource group. Note that these resources will still exist in their respective ResourceManager classes, but will be in an unloaded state. If you want to remove them entirely, you should use clearResourceGroup or destroyResourceGroup.
Parameters:
name The name to of the resource group to unload.
reloadableOnly If set to true, only unload the resource that is reloadable. Because some resources isn't reloadable, they will be unloaded but can't load them later. Thus, you might not want to them unloaded. Or, you might unload all of them, and then populate them manually later.
See also:
Resource::isReloadable for resource is reloadable.

void Ogre::ResourceGroupManager::unloadUnreferencedResourcesInGroup const String name,
bool  reloadableOnly = true
 

Unload all resources which are not referenced by any other object.

Remarks:
This method behaves like unloadResourceGroup, except that it only unloads resources in the group which are not in use, ie not referenced by other objects. This allows you to free up some memory selectively whilst still keeping the group around (and the resources present, just not using much memory).
Parameters:
name The name of the group to check for unreferenced resources
reloadableOnly If true (the default), only unloads resources which can be subsequently automatically reloaded


Member Data Documentation

String Ogre::ResourceGroupManager::AUTODETECT_RESOURCE_GROUP_NAME [static]
 

Special resource group name which causes resource group to be automatically determined based on searching for the resource in all groups.

Definition at line 172 of file OgreResourceGroupManager.h.

String Ogre::ResourceGroupManager::BOOTSTRAP_RESOURCE_GROUP_NAME [static]
 

Bootstrap resource group name (min OGRE resources).

Definition at line 170 of file OgreResourceGroupManager.h.

OGRE_AUTO_MUTEX String Ogre::ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME [static]
 

Default resource group name.

Definition at line 166 of file OgreResourceGroupManager.h.

String Ogre::ResourceGroupManager::INTERNAL_RESOURCE_GROUP_NAME [static]
 

Internal resource group name (should be used by OGRE internal only).

Definition at line 168 of file OgreResourceGroupManager.h.

ResourceGroup* Ogre::ResourceGroupManager::mCurrentGroup [protected]
 

Stored current group - optimisation for when bulk loading a group.

Definition at line 286 of file OgreResourceGroupManager.h.

ResourceGroupListenerList Ogre::ResourceGroupManager::mResourceGroupListenerList [protected]
 

Definition at line 195 of file OgreResourceGroupManager.h.

ResourceGroupMap Ogre::ResourceGroupManager::mResourceGroupMap [protected]
 

Definition at line 240 of file OgreResourceGroupManager.h.

ResourceManagerMap Ogre::ResourceGroupManager::mResourceManagerMap [protected]
 

Definition at line 188 of file OgreResourceGroupManager.h.

ResourceGroupManager * Ogre::Singleton< ResourceGroupManager >::ms_Singleton [static, protected, inherited]
 

Definition at line 54 of file OgreSingleton.h.

ScriptLoaderOrderMap Ogre::ResourceGroupManager::mScriptLoaderOrderMap [protected]
 

Definition at line 192 of file OgreResourceGroupManager.h.

String Ogre::ResourceGroupManager::mWorldGroupName [protected]
 

Group name for world resources.

Definition at line 243 of file OgreResourceGroupManager.h.

size_t Ogre::ResourceGroupManager::RESOURCE_SYSTEM_NUM_REFERENCE_COUNTS [static]
 

The number of reference counts held per resource by the resource system.

Definition at line 174 of file OgreResourceGroupManager.h.


The documentation for this class was generated from the following file:

Copyright © 2000-2005 by The OGRE Team
Creative Commons License
This work is licensed under a Creative Commons Attribution-ShareAlike 2.5 License.
Last modified Sun Mar 12 14:42:42 2006