nrEngine::ResourceManager Class Reference
[Resource managment]

General pointer/handle based resource management system. More...

Public Types
typedef std::map< std::string, std::list< ResourceHandle > >	ResourceGroupMap
	Typedef for the resource map returned by the getResourceMap() method.
Public Member Functions
virtual	~ResourceManager ()
Result	registerLoader (const std::string &name, ResourceLoader loader)
Result	removeLoader (const std::string &name)
ResourceLoader	getLoaderByFile (const std::string &fileType)
ResourceLoader	getLoaderByResource (const std::string &resType)
ResourceLoader	getLoader (const std::string &name)
IResourcePtr	createResource (const std::string &name, const std::string &group, const std::string &resourceType, PropertyList *params=NULL)
IResourcePtr	loadResource (const std::string &name, const std::string &group, const std::string &fileName, const std::string &resourceType=std::string(), PropertyList *params=NULL, ResourceLoader manualLoader=ResourceLoader())
virtual Result	lockResource (const std::string &name)
virtual Result	lockResource (IResourcePtr &res)
virtual Result	lockResource (ResourceHandle &handle)
virtual Result	unlockResource (const std::string &name)
virtual Result	unlockResource (IResourcePtr &res)
virtual Result	unlockResource (ResourceHandle &handle)
Result	unload (const std::string &name)
Result	unload (IResourcePtr &res)
	See also: unload(name)
Result	unload (ResourceHandle &handle)
	See also: unload(name)
Result	reload (const std::string &name)
Result	reload (IResourcePtr &res)
	See also: reload(name)
Result	reload (ResourceHandle &handle)
	See also: reload(name)
Result	remove (const std::string &name)
Result	remove (IResourcePtr &res)
	See also: remove(name)
Result	remove (ResourceHandle &handle)
	See also: remove(name)
IResourcePtr	getByName (const std::string &name)
IResourcePtr	getByHandle (const ResourceHandle &handle)
Result	unloadGroup (const std::string &group)
Result	reloadGroup (const std::string &group)
Result	removeGroup (const std::string &group)
const std::list< ResourceHandle > &	getGroupHandles (const std::string &name)
const ResourceGroupMap &	getResourceMap ()
Friends
class	Engine
	Only engine can create the instance.
class	IResourceLoader
	Resource loader have access to certain functions.
class	IResource
	Resource object hast got access to certain objects.

---

Detailed Description

General pointer/handle based resource management system.

This class is a manger for every kind of resource used in our games. Textures, sounds, meshes, ... - all things that can be loaded from disk are resources managed by this module. You can derive your own classes to write own storing algorithms for different kind of resources. This class will use standard implementation and will try to be as efficient as possible. This manager can index resources, look them up, load and destroy them, and temporaly unload resources from memory to use only allowd size of memory.

We will use a priority system to determine which resources can be unloaded and for two resources of the same priority the most used will stay in memory.

This code and idea was get from Game Programming Gems 4. Ogre3D-Library was also used to get an idea how to get the resource manager working without using a whole library behind.

- Meaning of resource groups:

- Each resource can exists in a group.

• Each group has got it's unique names.
• You can access to whole groups either to single resources.
• E.g: you can split your level in patches and each resource in such a patch is in patch's resource group. So if the player go to far away from such a patch, it can be disabled or unloaded from the memory. You have now just to call one unload function for the whole group.
• Groups must not be disjoint, so you can have same resource in different groups.

Definition at line 57 of file ResourceManager.h.

---

Constructor & Destructor Documentation

nrEngine::ResourceManager::~ResourceManager

(

)

[virtual]

Release all used memory and also mark all loaded resources to unload. After you calling the destructor of ResourceManager class all created resources and loaders will be removed from the memory.

Definition at line 76 of file ResourceManager.cpp.

References nrEngine::ScriptEngine::del(), and nrEngine::Engine::sScriptEngine().

---

Member Function Documentation

Result nrEngine::ResourceManager::registerLoader	(	const std::string &	name,
		ResourceLoader	loader
	)

Here you can register any loader by the manager. Loader are used to load resources from files/memory and to store resources in the memory. By registration of a loader you have to specify his unique name. This name will be used to access to stored loader (for example to remove it).

Parameters:

	name	Unique loader name
	loader	Smart pointer containing the loader

Returns:

either OK or error code:

• RES_LOADER_ALREADY_EXISTS
• BAD_PARAMETERS

Note:

If there is two loaders which do support loading of file of the same filetype, so the behavior of getting appropriate loader is undefined.

Definition at line 148 of file ResourceManager.cpp.

References nrEngine::BAD_PARAMETERS, nrEngine::Log::LOG_ENGINE, nrEngine::OK, and nrEngine::RES_LOADER_ALREADY_EXISTS.

Referenced by nrEngine::Engine::initializeEngine().

Result nrEngine::ResourceManager::removeLoader

(

const std::string &

name

)

Removes the loader from the loader list. All bounded filetypes registrations will also be removed. So after you calling this you have to check whenever you still able to load filetypes you want to use.

Parameters:

name

Unique name of the loader

Returns:

either OK or error code:

• RES_LOADER_NOT_REGISTERED
• RES_ERROR

Definition at line 191 of file ResourceManager.cpp.

References nrEngine::Log::LOG_ENGINE, nrEngine::OK, and nrEngine::RES_LOADER_NOT_REGISTERED.

ResourceLoader nrEngine::ResourceManager::getLoaderByFile

(

const std::string &

fileType

)

Return the loader by given filetype. If there is no loader which can load such a filetype NULL will be returned

Parameters:

fileType

File type for which one the loader should be found

Definition at line 207 of file ResourceManager.cpp.

References nrEngine::Log::LL_WARNING, and nrEngine::Log::LOG_ENGINE.

Referenced by loadResource().

ResourceLoader nrEngine::ResourceManager::getLoaderByResource

(

const std::string &

resType

)

Get a loader that support creating of resource instances of the given resource type

Parameters:

resType

Unique name of the resource type

Returns:

either NULL or resource loader

Definition at line 239 of file ResourceManager.cpp.

Referenced by createResource(), and loadResource().

ResourceLoader nrEngine::ResourceManager::getLoader

(

const std::string &

name

)

Return the loader by given name. If the loader with this name does not exists, so NULL will be given back

Definition at line 227 of file ResourceManager.cpp.

IResourcePtr nrEngine::ResourceManager::createResource	(	const std::string &	name,
		const std::string &	group,
		const std::string &	resourceType,
		PropertyList *	params = NULL
	)

Create a resource object of a certain type. An according resource loader has to be registered before to provide manager with creating function. If no loader was registered NULL will be returned.

After you created a resource you will still not be able to use it. You have to load a resource from a file. You have also to load it, because we are using concept of empty resources. So loader has to get access on the resource to initialize it with empty data.

Parameters:

	name	Unique name of that resource. The name must be specified !!!
	group	Name of the group to which this resource belongs.
	resourceType	Unique type name of the resource type
	params	Here you can specify parameter which will be send to the loader/creator so that he can setup resource parameters. Default is NULL, so no parameters.

Definition at line 255 of file ResourceManager.cpp.

References getByName(), getLoaderByResource(), nrEngine::IResourcePtr::isNull(), nrEngine::Log::LL_DEBUG, nrEngine::Log::LL_WARNING, nrEngine::Log::LOG_ENGINE, and NR_ASSERT.

IResourcePtr nrEngine::ResourceManager::loadResource	(	const std::string &	name,
		const std::string &	group,
		const std::string &	fileName,
		const std::string &	resourceType = std::string(),
		PropertyList *	params = NULL,
		ResourceLoader	manualLoader = ResourceLoader()
	)

Load a resource from a file. For loading of a resource the registered loader will be used. The filetype is defined by the last characters of the file name. If we can not find this characters so the manual loader will be used if such one is specified. Manual loader will also be used if it is specified and filetype is detected. You can assign your resource to special group. The group names has to be unique.

If such a resource could not load, NULL will be returned.

If you do not specify any resource type, so the loader which has to be used will be detected by the file name. If no such found error will be given back.

Parameters:

	name	Unique name fo the resource
	group	Group name to which this resource should be assigned
	resourceType	Unique type name of the resource
	fileName	File name of the file to be loaded
	params	Here you can specify parameter which will be send to the loader/creator so that he can setup resource parameters. Default is NULL, so no parameters.
	manualLoader	Loader which should be used if you want to overload all registered loader.

Definition at line 290 of file ResourceManager.cpp.

References getByName(), getLoaderByFile(), getLoaderByResource(), nrEngine::IResourcePtr::isNull(), nrEngine::Log::LL_DEBUG, nrEngine::Log::LL_ERROR, nrEngine::Log::LL_WARNING, nrEngine::Log::LOG_ENGINE, and NR_ASSERT.

Referenced by nrEngine::ScriptEngine::load(), and nrEngine::Engine::loadPlugin().

Result nrEngine::ResourceManager::lockResource

(

const std::string &

name

)

[virtual]

This method is used to lock the resource with the given name for using. Locking of pure resource means here, that we want now to access to real resource either to empty resource. Because of our transparent functionality of changing between real and empty resource (if real resource is unloaded), we must have a possibility to access to real resources bypassing this changing mechanism. You will need this for example if you want to change some properties of a resource (for example texture flags). If your resource is currently unloaded from the memory and you will try to change properties, so there would be now effect because settings get changed in empty resource which would not change anything (Assumption: resources handles correctly).

Assume the resource is not loaded and you want to access it. resource->setPropertyOne(...); Affect to empty resource, because the resource is unloaded.
ResourceMgr.lockResource("resource");
resource->setPropertyOne(...);
ResourceMgr.unlockResource("resource");
Affect to the resource you probably means. You will set the property of the real resource and not the empty one.

Parameters:

name

Unique name of the resource

Returns:

either OK or error code

Note:

You have to decide whenever you want to lock your resource or just work as it is. It is safer to do locking if you have something like write function and do not lock anything for read only functions. e.g:

• ReadOnly by textures : getting of a ID, drawing, ...
• Write by texture: set new size, get name (it has also to be locked, because empty texture will return a name according to empty texture), load, ...

Definition at line 642 of file ResourceManager.cpp.

References getByName(), nrEngine::IResourcePtr::isNull(), nrEngine::IResourcePtr::lockResource(), and nrEngine::RES_NOT_FOUND.

Referenced by reload(), remove(), and unload().

Result nrEngine::ResourceManager::lockResource

(

IResourcePtr &

res

)

[virtual]

Overloaded function to allow locking through pointer directly

Parameters:

res

Pointer to the resource

Definition at line 667 of file ResourceManager.cpp.

References nrEngine::IResourcePtr::lockResource().

Result nrEngine::ResourceManager::lockResource

(

ResourceHandle &

handle

)

[virtual]

Overloaded function to allow locking through handle.

Parameters:

handle

Unique handle of the resource

Definition at line 654 of file ResourceManager.cpp.

References getByHandle(), nrEngine::IResourcePtr::isNull(), nrEngine::IResourcePtr::lockResource(), and nrEngine::RES_NOT_FOUND.

Result nrEngine::ResourceManager::unlockResource

(

const std::string &

name

)

[virtual]

This function is complement to the lockResource(...) methods. This will unlock the real resource from using

Parameters:

name

Unique name of the resource to be unlocked

Definition at line 675 of file ResourceManager.cpp.

References nrEngine::OK, and nrEngine::RES_NOT_FOUND.

Referenced by reload(), remove(), and unload().

Result nrEngine::ResourceManager::unlockResource

(

IResourcePtr &

res

)

[virtual]

Overloaded function to allow unlocking through pointer directly

Parameters:

res

Pointer to the resource

Definition at line 709 of file ResourceManager.cpp.

References nrEngine::IResourcePtr::getResourceHolder(), nrEngine::IResourcePtr::isNull(), nrEngine::OK, and nrEngine::RES_ERROR.

Result nrEngine::ResourceManager::unlockResource

(

ResourceHandle &

handle

)

[virtual]

Overloaded function to allow unlocking through handle.

Parameters:

handle

Unique handle of the resource

Definition at line 692 of file ResourceManager.cpp.

References nrEngine::OK, and nrEngine::RES_NOT_FOUND.

Result nrEngine::ResourceManager::unload

(

const std::string &

name

)

Unload the resource from the memory. After this call all the resource pointers assigned within the resource will point to an empty resource.

Parameters:

name

Unique name of the resource

Returns:

either OK or error code:

• RES_NOT_FOUND

See also:

IResourceLoader

Definition at line 343 of file ResourceManager.cpp.

References getByName(), nrEngine::IResourcePtr::isNull(), lockResource(), nrEngine::Log::LOG_ENGINE, nrEngine::RES_NOT_FOUND, and unlockResource().

Referenced by unloadGroup().

Result nrEngine::ResourceManager::reload

(

const std::string &

name

)

Reload the resource, so it will now contain it's real data. Call this function if want to get your resource back after it was unloaded.

Parameters:

name

Unique name of the resource

Returns:

either OK or error code:

• RES_NOT_FOUND

Definition at line 394 of file ResourceManager.cpp.

References getByName(), nrEngine::IResourcePtr::isNull(), nrEngine::Log::LL_DEBUG, lockResource(), nrEngine::Log::LOG_ENGINE, nrEngine::RES_NOT_FOUND, and unlockResource().

Referenced by reloadGroup().

Result nrEngine::ResourceManager::remove

(

const std::string &

name

)

This will remove the resource from the database. After you removed the resource and would try to access to it through the manager NULL will be returned.

If you remove the resource from the database all resource pointers for this resource will now point to the empty resource object.

Parameters:

name

Unique name of the resource

Returns:

either OK or error code:

• RES_NOT_FOUND

See also:

IResourcePtr

Definition at line 495 of file ResourceManager.cpp.

References nrEngine::IResourcePtr::getBase(), getByName(), nrEngine::IResourcePtr::isNull(), lockResource(), nrEngine::Log::LOG_ENGINE, nrEngine::IResource::remove(), nrEngine::RES_NOT_FOUND, and unlockResource().

Referenced by removeGroup().

IResourcePtr nrEngine::ResourceManager::getByName

(

const std::string &

name

)

Get the pointer to a resource by it's name. If there is no resource with this name, so NULL pointer will be returned

Parameters:

name

Unique name of the resource

Definition at line 572 of file ResourceManager.cpp.

Referenced by nrEngine::IResourceLoader::create(), createResource(), nrEngine::ScriptEngine::execute(), loadResource(), lockResource(), reload(), remove(), nrEngine::ScriptFunctionDec(), and unload().

IResourcePtr nrEngine::ResourceManager::getByHandle

(

const ResourceHandle &

handle

)

Same as getByName(), but here you get the resource by handle.

Definition at line 582 of file ResourceManager.cpp.

Referenced by lockResource(), reload(), remove(), and unload().

Result nrEngine::ResourceManager::unloadGroup

(

const std::string &

group

)

Unload all elements from the group.

Parameters:

group

Unique name of the group

Returns:

either OK or RES_GROUP_NOT_FOUND or an error code from unload(...) - method

Definition at line 723 of file ResourceManager.cpp.

References nrEngine::Log::LOG_ENGINE, nrEngine::OK, nrEngine::RES_GROUP_NOT_FOUND, and unload().

Result nrEngine::ResourceManager::reloadGroup

(

const std::string &

group

)

Reload all elements in the group

Parameters:

group

Unique name of the group

Returns:

either OK or RES_GROUP_NOT_FOUND or an error code from reload(...) - method

Definition at line 746 of file ResourceManager.cpp.

References nrEngine::Log::LOG_ENGINE, nrEngine::OK, reload(), and nrEngine::RES_GROUP_NOT_FOUND.

Result nrEngine::ResourceManager::removeGroup

(

const std::string &

group

)

Remove all elements in the group

Parameters:

group

Unique name of the group

Returns:

either OK or RES_GROUP_NOT_FOUND or an error code from remove(...) - method

Definition at line 770 of file ResourceManager.cpp.

References nrEngine::Log::LOG_ENGINE, nrEngine::OK, remove(), and nrEngine::RES_GROUP_NOT_FOUND.

const std::list< ResourceHandle > & nrEngine::ResourceManager::getGroupHandles

(

const std::string &

name

)

Get a list of all resource handles for a specified group. The list can be iterated to get the resource handles which are in this group. Use the handles to get a resource according to it.

Parameters:

name

Unique name of the group

Returns:

List of resource handles containing in this group

Definition at line 797 of file ResourceManager.cpp.

const ResourceGroupMap& nrEngine::ResourceManager::getResourceMap

(

)

Return the map containing group names and according resource list.

Definition at line 404 of file ResourceManager.h.

---

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

• ResourceManager.h
• ResourceManager.cpp

---