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:

Classes
struct	ResourceDeclaration
	Nested struct defining a resource declaration. More...

struct	ResourceLocation
	Resource location entry. More...

Public Types
typedef list< ResourceLocation * >::type	LocationList
	List of possible file locations. More...

typedef list< ResourceDeclaration >::type	ResourceDeclarationList
	List of resource declarations. More...

typedef MapIterator< ResourceManagerMap >	ResourceManagerIterator

typedef map< String, ResourceManager * >::type	ResourceManagerMap

Public Member Functions
	ResourceGroupManager ()

virtual	~ResourceGroupManager ()

ScriptLoader *	_findScriptLoader (const String &pattern) const
	Method used to directly query for registered script loaders. More...

ResourceManager *	_getResourceManager (const String &resourceType) const
	Internal method for getting a registered ResourceManager. More...

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

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

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

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

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

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

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

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

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

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

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

void	addResourceLocation (const String &name, const String &locType, const String &resGroup=DEFAULT_RESOURCE_GROUP_NAME, bool recursive=false, bool readOnly=true)
	Adds a location to the list of searchable locations for a Resource type. More...

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

DataStreamPtr	createResource (const String &filename, const String &groupName=DEFAULT_RESOURCE_GROUP_NAME, bool overwrite=false, const String &locationPattern=BLANKSTRING)
	Create a new resource file in a given group. More...

void	createResourceGroup (const String &name, bool inGlobalPool=!OGRE_RESOURCEMANAGER_STRICT)
	Create a resource group. More...

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. More...

void	declareResource (const String &name, const String &resourceType, const String &groupName, ManualResourceLoader *loader, const NameValuePairList &loadParameters=NameValuePairList())
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...

void	deleteMatchingResources (const String &filePattern, const String &groupName=DEFAULT_RESOURCE_GROUP_NAME, const String &locationPattern=BLANKSTRING)
	Delete all matching resource files. More...

void	deleteResource (const String &filename, const String &groupName=DEFAULT_RESOURCE_GROUP_NAME, const String &locationPattern=BLANKSTRING)
	Delete a single resource file. More...

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. More...

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

FileInfoListPtr	findResourceFileInfo (const String &group, const String &pattern, bool dirs=false) const
	Find all files or directories matching a given pattern in a group and get some detailed information about them. More...

StringVectorPtr	findResourceLocation (const String &groupName, const String &pattern) const
	Find all resource location names matching a given pattern in a resource group. More...

StringVectorPtr	findResourceNames (const String &groupName, const String &pattern, bool dirs=false) const
	Find all file or directory names matching a given pattern in a resource group. More...

ResourceLoadingListener *	getLoadingListener () const
	Returns the current loading listener. More...

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

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

const LocationList &	getResourceLocationList (const String &groupName) const
	Get the list of resource locations for the specified group name. More...

ResourceManagerIterator	getResourceManagerIterator ()
	Get an iterator over the registered resource managers. More...

const String &	getWorldResourceGroupName (void) const
	Gets the resource group that 'world' resources will use. More...

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

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

bool	isResourceGroupInGlobalPool (const String &name) const
	Checks the status of a resource group. More...

bool	isResourceGroupInitialised (const String &name) const
	Checks the status of a resource group. More...

bool	isResourceGroupLoaded (const String &name) const
	Checks the status of a resource group. More...

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. More...

FileInfoListPtr	listResourceFileInfo (const String &groupName, bool dirs=false) const
	List all files in a resource group with accompanying information. More...

StringVectorPtr	listResourceLocations (const String &groupName) const
	List all resource locations in a resource group. More...

StringVectorPtr	listResourceNames (const String &groupName, bool dirs=false) const
	List all file or directory names in a resource group. More...

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

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

DataStreamPtr	openResource (const String &resourceName, const String &groupName, bool searchGroupsIfNotFound, Resource *resourceBeingLoaded=0) const

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

void	prepareResourceGroup (const String &name, bool prepareMainResources=true, bool prepareWorldGeom=true)
	Prepares a resource group. More...

void	removeResourceGroupListener (ResourceGroupListener *l)
	Removes a ResourceGroupListener. More...

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

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

bool	resourceExistsInAnyGroup (const String &filename) const
	Find out if the named file exists in any group. More...

bool	resourceGroupExists (const String &name) const

bool	resourceLocationExists (const String &name, const String &resGroup=DEFAULT_RESOURCE_GROUP_NAME) const
	Verify if a resource location exists for the given group. More...

time_t	resourceModifiedTime (const String &group, const String &filename) const
	Retrieve the modification time of a given file. More...

void	setLoadingListener (ResourceLoadingListener *listener)
	Sets a new loading listener. More...

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

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

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

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

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

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

Static Public Member Functions
static ResourceGroupManager &	getSingleton (void)
	Get the singleton instance. More...

static ResourceGroupManager *	getSingletonPtr (void)
	Get the singleton instance. More...

Public Attributes
	OGRE_AUTO_MUTEX

Static Public Attributes
static const 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. More...

static const String	DEFAULT_RESOURCE_GROUP_NAME
	Default resource group name. More...

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

static const long	RESOURCE_SYSTEM_NUM_REFERENCE_COUNTS
	The number of reference counts held per resource by the resource system. More...

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

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 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 clearResourceGroup.
Declared. Ogre has some forewarning of this resource, either through calling 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 initialiseResourceGroup is called (which is automatic if you declare the resource group before Root::initialise).
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 initialiseResourceGroup (either from a script, or from a call to declareResource), by being created directly from code (ResourceManager::createResource), or it may have previously been loaded and has been unloaded, either individually through Resource::unload, or as a group through 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.

Member Typedef Documentation

◆ ResourceDeclarationList

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

List of resource declarations.

◆ ResourceManagerMap

typedef map<String, ResourceManager*>::type Ogre::ResourceGroupManager::ResourceManagerMap

◆ ResourceManagerIterator

typedef MapIterator<ResourceManagerMap> Ogre::ResourceGroupManager::ResourceManagerIterator

◆ LocationList

typedef list<ResourceLocation*>::type Ogre::ResourceGroupManager::LocationList

List of possible file locations.

Constructor & Destructor Documentation

◆ ResourceGroupManager()

Ogre::ResourceGroupManager::ResourceGroupManager ( )

◆ ~ResourceGroupManager()

virtual Ogre::ResourceGroupManager::~ResourceGroupManager ( )

virtual

Member Function Documentation

◆ createResourceGroup()

void Ogre::ResourceGroupManager::createResourceGroup	(	const String &	name,
		bool	inGlobalPool = `!OGRE_RESOURCEMANAGER_STRICT`
	)

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 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 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, 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::createResource 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.

◆ initialiseResourceGroup()

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:

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.

Parameters

name	The name of the resource group to initialise

◆ initialiseAllResourceGroups()

void Ogre::ResourceGroupManager::initialiseAllResourceGroups ( void )

Initialise all resource groups which are yet to be initialised.

See also: initialiseResourceGroup

◆ prepareResourceGroup()

void Ogre::ResourceGroupManager::prepareResourceGroup	(	const String &	name,
		bool	prepareMainResources = `true`,
		bool	prepareWorldGeom = `true`
	)

Prepares a resource group.

Remarks: Prepares any created resources which are part of the named group. Note that resources must have already been created by calling ResourceManager::createResource, 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 ResourceGroupListener 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)
prepareWorldGeom	If true, prepares any linked world geometry

See also: linkWorldGeometryToResourceGroup

◆ loadResourceGroup()

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

◆ unloadResourceGroup()

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.

◆ unloadUnreferencedResourcesInGroup()

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

◆ clearResourceGroup()

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.

◆ destroyResourceGroup()

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.

◆ isResourceGroupInitialised()

bool Ogre::ResourceGroupManager::isResourceGroupInitialised ( const String & name ) const

Checks the status of a resource group.

Remarks: Looks at the state of a resource group. If initialiseResourceGroup has been called for the resource group return true, otherwise return false.

Parameters

name	The name to of the resource group to access.

◆ isResourceGroupLoaded()

bool Ogre::ResourceGroupManager::isResourceGroupLoaded ( const String & name ) const

Checks the status of a resource group.

Remarks: Looks at the state of a resource group. If loadResourceGroup has been called for the resource group return true, otherwise return false.

Parameters

name	The name to of the resource group to access.

◆ resourceGroupExists()

bool Ogre::ResourceGroupManager::resourceGroupExists ( const String & name ) const

◆ addResourceLocation()

void Ogre::ResourceGroupManager::addResourceLocation	(	const String &	name,
		const String &	locType,
		const String &	resGroup = `DEFAULT_RESOURCE_GROUP_NAME`,
		bool	recursive = `false`,
		bool	readOnly = `true`
	)

Adds a location to the list of searchable locations for a Resource type.

Remarks: Resource files (textures, models etc) need to be loaded from specific locations. By calling this method, you add another search location to the list. Locations added first are preferred over locations added later.

: Locations can be folders, compressed archives, even perhaps remote locations. Facilities for loading from different locations are provided by plugins which provide implementations of the Archive class. All the application user has to do is specify a 'loctype' string in order to indicate the type of location, which should map onto one of the provided plugins. Ogre comes configured with the 'FileSystem' (folders) and 'Zip' (archive compressed with the pkzip / WinZip etc utilities) types.

: You can also supply the name of a resource group which should have this location applied to it. The DEFAULT_RESOURCE_GROUP_NAME group is the default, and one resource group which will always exist. You should consider defining resource groups for your more specific resources (e.g. per level) so that you can control loading / unloading better.

Parameters

name	The name of the location, e.g. './data' or '/compressed/gamedata.zip'
locType	A string identifying the location type, e.g. 'FileSystem' (for folders), 'Zip' etc. Must map to a registered plugin which deals with this type (FileSystem and Zip should always be available)
groupName	Type of name of the resource group which this location should apply to; defaults to the General group which applies to all non-specific resources.
recursive	If the resource location has a concept of recursive directory traversal, enabling this option will mean you can load resources in subdirectories using only their unqualified name. The default is to disable this so that resources in subdirectories with the same name are still unique.
readOnly	whether the Archive is read only

See also: Archive

◆ removeResourceLocation()

void Ogre::ResourceGroupManager::removeResourceLocation	(	const String &	name,
		const String &	resGroup = `DEFAULT_RESOURCE_GROUP_NAME`
	)

Removes a resource location from the search path.

◆ resourceLocationExists()

bool Ogre::ResourceGroupManager::resourceLocationExists	(	const String &	name,
		const String &	resGroup = `DEFAULT_RESOURCE_GROUP_NAME`
	)		const

Verify if a resource location exists for the given group.

◆ declareResource() [1/2]

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: Font GpuProgram HighLevelGpuProgram Material Mesh Skeleton Texture .. 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.

◆ declareResource() [2/2]

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

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

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.

◆ undeclareResource()

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.

◆ openResource() [1/2]

DataStreamPtr Ogre::ResourceGroupManager::openResource	(	const String &	resourceName,
		const String &	groupName = `DEFAULT_RESOURCE_GROUP_NAME`,
		Resource *	resourceBeingLoaded = `NULL`
	)		const

inline

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

◆ openResource() [2/2]

DataStreamPtr Ogre::ResourceGroupManager::openResource	(	const String &	resourceName,
		const String &	groupName,
		bool	searchGroupsIfNotFound,
		Resource *	resourceBeingLoaded = `0`
	)		const

inline

Deprecated:: use AUTODETECT_RESOURCE_GROUP_NAME instead of searchGroupsIfNotFound

References Ogre::BLANKSTRING.

◆ openResources()

DataStreamListPtr Ogre::ResourceGroupManager::openResources	(	const String &	pattern,
		const String &	groupName = `DEFAULT_RESOURCE_GROUP_NAME`
	)		const

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

◆ listResourceNames()

StringVectorPtr Ogre::ResourceGroupManager::listResourceNames	(	const String &	groupName,
		bool	dirs = `false`
	)		const

List all file or directory 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
dirs	If true, directory names will be returned instead of file names

Returns: A list of filenames matching the criteria, all are fully qualified

◆ listResourceFileInfo()

FileInfoListPtr Ogre::ResourceGroupManager::listResourceFileInfo	(	const String &	groupName,
		bool	dirs = `false`
	)		const

List all files in a resource group with accompanying information.

Parameters

groupName	The name of the group
dirs	If true, directory names will be returned instead of file names

Returns: A list of structures detailing quite a lot of information about all the files in the archive.

◆ findResourceNames()

StringVectorPtr Ogre::ResourceGroupManager::findResourceNames	(	const String &	groupName,
		const String &	pattern,
		bool	dirs = `false`
	)		const

Find all file or directory 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
dirs	Set to true if you want the directories to be listed instead of files

Returns: A list of filenames matching the criteria, all are fully qualified

◆ resourceExists()

bool Ogre::ResourceGroupManager::resourceExists	(	const String &	group,
		const String &	filename
	)		const

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

◆ resourceExistsInAnyGroup()

bool Ogre::ResourceGroupManager::resourceExistsInAnyGroup ( const String & filename ) const

Find out if the named file exists in any group.

Parameters

filename Fully qualified name of the file to test for

◆ findGroupContainingResource()

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

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.

◆ findResourceFileInfo()

FileInfoListPtr Ogre::ResourceGroupManager::findResourceFileInfo	(	const String &	group,
		const String &	pattern,
		bool	dirs = `false`
	)		const

Find all files or directories 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
dirs	Set to true if you want the directories to be listed instead of files

Returns: A list of file information structures for all files matching the criteria.

◆ resourceModifiedTime()

time_t Ogre::ResourceGroupManager::resourceModifiedTime	(	const String &	group,
		const String &	filename
	)		const

Retrieve the modification time of a given file.

◆ listResourceLocations()

StringVectorPtr Ogre::ResourceGroupManager::listResourceLocations ( const String & groupName ) const

List all resource locations in a resource group.

Parameters

groupName The name of the group

Returns: A list of resource locations matching the criteria

◆ findResourceLocation()

StringVectorPtr Ogre::ResourceGroupManager::findResourceLocation	(	const String &	groupName,
		const String &	pattern
	)		const

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

Parameters

groupName	The name of the group
pattern	The pattern to search for; wildcards (*) are allowed

Returns: A list of resource locations matching the criteria

◆ createResource()

DataStreamPtr Ogre::ResourceGroupManager::createResource	(	const String &	filename,
		const String &	groupName = `DEFAULT_RESOURCE_GROUP_NAME`,
		bool	overwrite = `false`,
		const String &	locationPattern = `BLANKSTRING`
	)

Create a new resource file in a given group.

Remarks: 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.

◆ deleteResource()

void Ogre::ResourceGroupManager::deleteResource	(	const String &	filename,
		const String &	groupName = `DEFAULT_RESOURCE_GROUP_NAME`,
		const String &	locationPattern = `BLANKSTRING`
	)

Delete a single resource file.

Parameters

filename	The name of the file to delete.
groupName	The name of the group in which to search
locationPattern	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.

◆ deleteMatchingResources()

void Ogre::ResourceGroupManager::deleteMatchingResources	(	const String &	filePattern,
		const String &	groupName = `DEFAULT_RESOURCE_GROUP_NAME`,
		const String &	locationPattern = `BLANKSTRING`
	)

Delete all matching resource files.

Parameters

filePattern	The pattern (see StringUtil::match) of the files to delete.
groupName	The name of the group in which to search
locationPattern	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.

◆ addResourceGroupListener()

void Ogre::ResourceGroupManager::addResourceGroupListener ( ResourceGroupListener * l )

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

◆ removeResourceGroupListener()

void Ogre::ResourceGroupManager::removeResourceGroupListener ( ResourceGroupListener * l )

Removes a ResourceGroupListener.

◆ setWorldResourceGroupName()

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

inline

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.

◆ getWorldResourceGroupName()

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

inline

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

◆ linkWorldGeometryToResourceGroup()

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

◆ unlinkWorldGeometryFromResourceGroup()

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.

◆ isResourceGroupInGlobalPool()

bool Ogre::ResourceGroupManager::isResourceGroupInGlobalPool ( const String & name ) const

Checks the status of a resource group.

Remarks: Looks at the state of a resource group. If loadResourceGroup has been called for the resource group return true, otherwise return false.

Parameters

name	The name to of the resource group to access.

◆ shutdownAll()

void Ogre::ResourceGroupManager::shutdownAll ( void )

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

◆ _registerResourceManager()

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.

◆ _unregisterResourceManager()

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.

◆ getResourceManagerIterator()

ResourceManagerIterator Ogre::ResourceGroupManager::getResourceManagerIterator ( )

inline

Get an iterator over the registered resource managers.

◆ _registerScriptLoader()

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.

◆ _unregisterScriptLoader()

void Ogre::ResourceGroupManager::_unregisterScriptLoader ( ScriptLoader * su )

Internal method for unregistering a ScriptLoader.

Parameters

su	Pointer to the ScriptLoader instance.

◆ _findScriptLoader()

ScriptLoader* Ogre::ResourceGroupManager::_findScriptLoader ( const String & pattern ) const

Method used to directly query for registered script loaders.

Parameters

pattern The specific script pattern (e.g. *.material) the script loader handles

◆ _getResourceManager()

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

Internal method for getting a registered ResourceManager.

Parameters

resourceType String identifying the resource type.

◆ _notifyResourceCreated()

void Ogre::ResourceGroupManager::_notifyResourceCreated ( ResourcePtr & res ) const

Internal method called by ResourceManager when a resource is created.

Parameters

res	Weak reference to resource

◆ _notifyResourceRemoved()

void Ogre::ResourceGroupManager::_notifyResourceRemoved ( const ResourcePtr & res ) const

Internal method called by ResourceManager when a resource is removed.

Parameters

res	Weak reference to resource

◆ _notifyResourceGroupChanged()

void Ogre::ResourceGroupManager::_notifyResourceGroupChanged	(	const String &	oldGroup,
		Resource *	res
	)		const

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

◆ _notifyAllResourcesRemoved()

void Ogre::ResourceGroupManager::_notifyAllResourcesRemoved ( ResourceManager * manager ) const

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

◆ _notifyWorldGeometryStageStarted()

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

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.

◆ _notifyWorldGeometryStageEnded()

void Ogre::ResourceGroupManager::_notifyWorldGeometryStageEnded ( void ) const

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.

◆ getResourceGroups()

StringVector Ogre::ResourceGroupManager::getResourceGroups ( void ) const

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.

◆ getResourceDeclarationList()

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

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.

◆ getResourceLocationList()

const LocationList& Ogre::ResourceGroupManager::getResourceLocationList ( const String & groupName ) const

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

Parameters

groupName The name of the group

Returns: The list of resource locations associated with the given group.

◆ setLoadingListener()

void Ogre::ResourceGroupManager::setLoadingListener ( ResourceLoadingListener * listener )

Sets a new loading listener.

◆ getLoadingListener()

ResourceLoadingListener* Ogre::ResourceGroupManager::getLoadingListener ( ) const

Returns the current loading listener.

◆ getSingleton()

static ResourceGroupManager& Ogre::ResourceGroupManager::getSingleton ( void )

static

Get the singleton instance.

◆ getSingletonPtr()

static ResourceGroupManager* Ogre::ResourceGroupManager::getSingletonPtr ( void )

static

Get the singleton instance.

Member Data Documentation

◆ OGRE_AUTO_MUTEX

Ogre::ResourceGroupManager::OGRE_AUTO_MUTEX

◆ DEFAULT_RESOURCE_GROUP_NAME

const String Ogre::ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME

static

Default resource group name.

Referenced by Ogre::ManualObject::_releaseManualHardwareResources(), Ogre::Root::createSceneManager(), Ogre::ExternalTextureSourceManager::getCurrentPlugIn(), Ogre::ExternalTextureSource::getDictionaryStringName(), and Ogre::ManualObject::getDynamic().

◆ INTERNAL_RESOURCE_GROUP_NAME

const String Ogre::ResourceGroupManager::INTERNAL_RESOURCE_GROUP_NAME

static

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

◆ AUTODETECT_RESOURCE_GROUP_NAME

const 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.

Referenced by Ogre::SceneManager::_getLightsDirtyCounter(), Ogre::ManualObject::ManualObjectSection::getMaterialGroup(), Ogre::BillboardChain::getMaterialName(), Ogre::SceneManager::getOptionKeys(), Ogre::SceneManager::getSkyBoxGenParameters(), Ogre::SceneManager::getSkyPlaneGenParameters(), and Ogre::Entity::getSubEntities().

◆ RESOURCE_SYSTEM_NUM_REFERENCE_COUNTS

const long Ogre::ResourceGroupManager::RESOURCE_SYSTEM_NUM_REFERENCE_COUNTS

static

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

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

OgreResourceGroupManager.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ ResourceDeclarationList

◆ ResourceManagerMap

◆ ResourceManagerIterator

◆ LocationList

Constructor & Destructor Documentation

◆ ResourceGroupManager()

◆ ~ResourceGroupManager()

Member Function Documentation

◆ createResourceGroup()

◆ initialiseResourceGroup()

◆ initialiseAllResourceGroups()

◆ prepareResourceGroup()

◆ loadResourceGroup()

◆ unloadResourceGroup()

◆ unloadUnreferencedResourcesInGroup()

◆ clearResourceGroup()

◆ destroyResourceGroup()

◆ isResourceGroupInitialised()

◆ isResourceGroupLoaded()

◆ resourceGroupExists()

◆ addResourceLocation()

◆ removeResourceLocation()

◆ resourceLocationExists()

◆ declareResource() [1/2]

◆ declareResource() [2/2]

◆ undeclareResource()

◆ openResource() [1/2]

◆ openResource() [2/2]

◆ openResources()

◆ listResourceNames()

◆ listResourceFileInfo()

◆ findResourceNames()

◆ resourceExists()

◆ resourceExistsInAnyGroup()

◆ findGroupContainingResource()

◆ findResourceFileInfo()

◆ resourceModifiedTime()

◆ listResourceLocations()

◆ findResourceLocation()

◆ createResource()

◆ deleteResource()

◆ deleteMatchingResources()

◆ addResourceGroupListener()

◆ removeResourceGroupListener()

◆ setWorldResourceGroupName()

◆ getWorldResourceGroupName()

◆ linkWorldGeometryToResourceGroup()

◆ unlinkWorldGeometryFromResourceGroup()

◆ isResourceGroupInGlobalPool()

◆ shutdownAll()

◆ _registerResourceManager()

◆ _unregisterResourceManager()

◆ getResourceManagerIterator()

◆ _registerScriptLoader()

◆ _unregisterScriptLoader()

◆ _findScriptLoader()

◆ _getResourceManager()

◆ _notifyResourceCreated()

◆ _notifyResourceRemoved()

◆ _notifyResourceGroupChanged()

◆ _notifyAllResourcesRemoved()

◆ _notifyWorldGeometryStageStarted()

◆ _notifyWorldGeometryStageEnded()

◆ getResourceGroups()

◆ getResourceDeclarationList()

◆ getResourceLocationList()

◆ setLoadingListener()

◆ getLoadingListener()

◆ getSingleton()

◆ getSingletonPtr()

Member Data Documentation

◆ OGRE_AUTO_MUTEX