Static Protected Attributes

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):

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.

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.

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.

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.

This method creates a new file in a resource group and passes you back a writeable stream.

Parameters

filename

The name of the file to create

groupName

The name of the group in which to create the file

overwrite

If true, an existing file will be overwritten, if false an error will occur if the file already exists

locationPattern

If the resource group contains multiple locations, then usually the file will be created in the first writable location. If you want to be more specific, you can include a location pattern here and only locations which match that pattern (as determined by StringUtil::match) will be considered candidates for creation.

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:

Manually through declareResource(); this is useful for scripted declarations since it is entirely generalised, and does not create Resource instances right away

Through the use of scripts; some ResourceManager subtypes have script formats (e.g. .material, .overlay) which can be used to declare resources

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.

inGlobalPool

if true the resource will be loaded even a different group was requested in the load method as a parameter.

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:

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:

If the resource group contains multiple locations, then usually all matching files in any location will be deleted. If you want to be more specific, you can include a location pattern here and only locations which match that pattern (as determined by StringUtil::match) will be considered candidates for deletion.

If the resource group contains multiple locations, then usually first matching file found in any location will be deleted. If you want to be more specific, you can include a location pattern here and only locations which match that pattern (as determined by StringUtil::match) will be considered candidates for deletion.

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.

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.

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:

Scripts for all resource types which support scripting are parsed from the resource locations, and resources within them are created (but not loaded yet).

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.

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.

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 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)

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

Prepares 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 of the resource group to prepare.

prepareMainResources

If true, prepares normal resources associated with the group (you might want to set this to false if you wanted to just prepare world geometry in bulk)

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.

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.

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