Ocular Engine
Ocular::Core::ResourceManager Class Reference

#include <ResourceManager.hpp>

Public Member Functions

void initialize ()
 
void unloadAllResources ()
 
void forceSourceRefresh ()
 
bool forceLoadResource (std::string const &path)
 
bool forceUnloadResource (std::string const &path)
 
bool addResource (std::string const &name, File const &sourceFile, Resource *resource, ResourceType type)
 
ResourceMemoryDetails getMemoryUsage ()
 
ResourcegetResource (std::string const &path)
 
template<class T >
T * getResource (std::string const &path)
 
ResourcegetEmptyResource (ResourceType type)
 
ResourcegetMissingResource (ResourceType type)
 
File getResourceFile (std::string const &path) const
 
std::string getResourceMappingName (File const &file) const
 
bool isInMemory (std::string const &path)
 
bool doesExist (std::string const &path)
 
ResourceloadUnmanagedFile (File const &file)
 
bool saveResource (Resource *resource, File const &file)
 
void setMemoryLimit (uint64_t maxMemory)
 
void setPriorityBehaviour (ResourcePriorityBehaviour behaviour)
 
void setSourceBlacklist (std::list< std::string > const &blacklist)
 
void setSourceDirectory (std::string const &directory)
 
std::string const & getSourceDirectory () const
 
void registerResourceLoader (std::shared_ptr< AResourceLoader > loader)
 
void registerResourceSaver (std::shared_ptr< AResourceSaver > loader)
 
unsigned getNumberOfResources () const
 
unsigned getNumberOfResourceLoaders () const
 
unsigned getNumberOfResourceSavers () const
 
void isFileTypeSupported (std::string const &extension, bool &canLoad, bool &canSave) const
 
void getResourcesOfType (ResourceType type, std::vector< std::string > &resources)
 

Protected Member Functions

void freeMemorySpace ()
 
ResourceDetailsfindLeastFrequentlyUsed ()
 
ResourceDetailsfindLeastRecentlyUsed ()
 
ResourceDetailsfindSizeAscending ()
 
ResourceDetailsfindSizeDescending ()
 

Detailed Description

The resource subsystem manages the loading, unloading, and tracking of all file-based resources used by the engine. This includes any textures, models, shaders, or any other form of data that is stored on-disk.

When requesting a resource, you simply provide the local path and filename of the resource from the root 'Resources/' directory (or directories), minus the extension. For example, if you have a resource structure as follows:

OcularProject/
    Binaries/
    Intermediate/
    Resources/
        Models/
        Textures/
            Buildings/
            Terrain/
                GrassDead.png
                GrassGreen.tga
    Source/

You would retrieve the GrassGreen.tga texture as follows:

Texture* texture = nullptr;
Resource* resource = OcularResources->getResource("Textures/Terrain/GrassGreen");

if(resource->getResourceType() == ResourceType::Texture)
{
    texture = dynamic_cast<Texture*>(resource);

    if(texture)
    {
        // ...
    }
}

or:

Texture* texture = OcularResources->getResource<Texture>("Textures/Terrain/GrassGreen");

if(texture)
{
    // ...
}

The returned Resource pointer will always be valid as long as the ResourceManager instance exists (so the life of the Engine). But, the internal data of the resource itself may not be valid. So before use of the Resource itself, one should verify that the Resource is loaded. Example:

if(!texture->isInMemory())
{
    texture->forceLoad();
}

Note that a retrieved texture (getResource) is guaranteed to be fully loaded into memory (at least until the next getResource request).

Member Function Documentation

bool Ocular::Core::ResourceManager::addResource ( std::string const &  name,
File const &  sourceFile,
Resource resource,
ResourceType  type 
)

Adds the Resource to the ResourceManager. The manager will assume ownership of the Resource and handle loading/unloading/destruction of it.

Parameters
[in]nameMapping name to associate with the Resource. Must be unique and not already in use by a pre-existing Resource.
[in]sourceFileFile to load the Resource from. File may be in use by multiple resources, such as with a MultiResource.
[in]resourceThe Resource to transfer ownership of.
[in]type
Returns
Returns FALSE if the specified path is already occupied.
bool Ocular::Core::ResourceManager::doesExist ( std::string const &  path)
Parameters
[in]pathResource path and name
Returns
TRUE if the specified resource exists on the system and is tracked.
ResourceDetails * Ocular::Core::ResourceManager::findLeastFrequentlyUsed ( )
protected

Frees memory based on usage frequency.

ResourceDetails * Ocular::Core::ResourceManager::findLeastRecentlyUsed ( )
protected

Frees memory based on when the resource was last used.

ResourceDetails * Ocular::Core::ResourceManager::findSizeAscending ( )
protected

Frees memory based on size.

ResourceDetails * Ocular::Core::ResourceManager::findSizeDescending ( )
protected

Frees memory based on size.

bool Ocular::Core::ResourceManager::forceLoadResource ( std::string const &  path)

Forces the resource to be loaded into memory.

Parameters
[in]pathResource path and name
Returns
TRUE if load was successful.
void Ocular::Core::ResourceManager::forceSourceRefresh ( )

Forces a refresh of all source folder contents.

bool Ocular::Core::ResourceManager::forceUnloadResource ( std::string const &  path)

Forces the resource to be unloaded from memory.

Parameters
[in]pathResource path and name
Returns
TRUE if unload was successful.
void Ocular::Core::ResourceManager::freeMemorySpace ( )
protected

Checks to ensure that the amount of memory currently in use does not exceed the maximum memory limit. If limit is surpassed, then it frees up space until back below the limit.

Resource * Ocular::Core::ResourceManager::getEmptyResource ( ResourceType  type)

Returns the pre-built 'empty' Resource for the specified type.

Parameters
[in]type
ResourceMemoryDetails Ocular::Core::ResourceManager::getMemoryUsage ( )

Retrieves the total amount of memory currently in use by the Resource Manager.

Returns
Resource * Ocular::Core::ResourceManager::getMissingResource ( ResourceType  type)

Returns the pre-built 'missing' Resource for the specified type.

Parameters
[in]type
unsigned Ocular::Core::ResourceManager::getNumberOfResourceLoaders ( ) const
Returns
Total number of registered Resource Loaders.
unsigned Ocular::Core::ResourceManager::getNumberOfResources ( ) const
Returns
Total number of tracked resources. This value does not represent the number of Resources in memory.
unsigned Ocular::Core::ResourceManager::getNumberOfResourceSavers ( ) const
Returns
Total number of registered Resource Savers.
Resource * Ocular::Core::ResourceManager::getResource ( std::string const &  path)

Returns the resource with the specified mapping name. The resource is loaded in memory if it is not already.

Parameters
[in]pathMapping name of the Resource. Relative path from Resources folder, sans extension.
Returns
Pointer to the resource; Returns nullptr if failed to fetch resource.
template<class T >
T* Ocular::Core::ResourceManager::getResource ( std::string const &  path)
inline

Returns the resource at the specified path if it exists. The resource is loaded in memory if it is not already.

Parameters
[in]pathResource path and name
Returns
Pointer to the resource; Returns nullptr if failed to fetch resource.
File Ocular::Core::ResourceManager::getResourceFile ( std::string const &  path) const

Returns the file associated with the specified resource mapping name.

For example, the mapping name

Textures/Grass

May return the file located at

/path/to/project/Resources/Textures/Grass.png
Parameters
[in]path
Returns
If there is no tracked Resource with the specified mapping name, then the current directory (default File value) will be returned.
std::string Ocular::Core::ResourceManager::getResourceMappingName ( File const &  file) const

Returns the mapping name associated with the specified file.

For example, the file located at

/path/to/project/Resources/Textures/Grass.png

Would return

Textures/Grass
Parameters
[in]file
Returns
If there is no tracked Resource at the specified file, then an empty string will be returned.
void Ocular::Core::ResourceManager::getResourcesOfType ( ResourceType  type,
std::vector< std::string > &  resources 
)

Finds all resources of the specified type, and returns a vector containing their mapping names.

Parameters
[in]type
[out]resources
std::string const & Ocular::Core::ResourceManager::getSourceDirectory ( ) const

Returns the directory path in which resources are expected.

void Ocular::Core::ResourceManager::isFileTypeSupported ( std::string const &  extension,
bool &  canLoad,
bool &  canSave 
) const

Checks if the specified resource extension is supported.

Parameters
[in]extensionFile extension to check for support
[out]canLoadIs set to TRUE if the specified file extension has an associated AResourceLoader and can be loaded.
[out]canSaveIs set to TRUE if the specified file extension has an associated AResourceSaver and can be saved.
bool Ocular::Core::ResourceManager::isInMemory ( std::string const &  path)
Parameters
[in]pathResource path and name
Returns
TRUE if the specified resource is currently in-memory.
Resource * Ocular::Core::ResourceManager::loadUnmanagedFile ( File const &  file)

Attempts to load the file at the specified path as a Resource.

Unlike other path parameters, this method requires the full path to the file. This is because the resource is untracked, and does not exist in a designated Resource folder.

It is up to the caller to properly clean up the returned resource (if not NULL) when they are done using it.

Parameters
[in]fileResource file to load
Returns
A new Resource object; Returns NULL if the file does not exist or unable to load it.
void Ocular::Core::ResourceManager::registerResourceLoader ( std::shared_ptr< AResourceLoader loader)

Registers the ResourceLoader

Parameters
[in]loader
void Ocular::Core::ResourceManager::registerResourceSaver ( std::shared_ptr< AResourceSaver loader)

Registers the ResourceSaver

Parameters
[in]saver
bool Ocular::Core::ResourceManager::saveResource ( Resource resource,
File const &  file 
)

Attempts to save the provided Resource to the specified file on disk.

In order for the Resource to be saved, all of the following must be true:

  • The provided Resource must not be NULL
  • The provided Resource must be currently loaded in memory
  • A AResourceSaver must be registered to the manager that supports the same file type as the specified output file. This may be verified using isFileTypeSupported()
  • The file and it's parent directories do not have to exist at the time of the method call, but they must be valid and the engine must have proper write access to create them.
Parameters
[in]resourceResource object to be saved to disk
[in]fileA valid resource file
Returns
TRUE if the Resource was successfully saved to disk.
void Ocular::Core::ResourceManager::setMemoryLimit ( uint64_t  maxMemory)

Sets the maximum amount of memory (in bytes) allocated for Resources. This value is clamped if it exceeds the amount of memory available to the system.

Parameters
[in]maxMemoryAmount of memory to allocate to Resources
void Ocular::Core::ResourceManager::setPriorityBehaviour ( ResourcePriorityBehaviour  behaviour)

Sets the priority behaviour when determining which Resource to unload when the memory limit has been reached.

Default is LeastRecentlyUsed.

Parameters
behaviourPriority behaviour to use.
void Ocular::Core::ResourceManager::setSourceBlacklist ( std::list< std::string > const &  blacklist)

Sets the blacklist for files to exclude as Resources. Each string is expected to be a file extension including the '.'.

Parameters
[in]blacklistContainer of file extensions to exclude.
void Ocular::Core::ResourceManager::setSourceDirectory ( std::string const &  directory)

Sets the expected name of the source directories to explore for resource files.

All directories underneath the application are explored, and those whose name matches the specified directory name will be cataloged.

Default is "Resources"

Note
To update the resource mappings, forceSourceRefresh must be called.
Parameters
[in]directoryName of resource directories

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