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

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.

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:
Generated on Wed Sep 12 23:19:43 2007 for nrEngine by  doxygen 1.5.1