Resources Class Reference

Description

Manager for dealing with all engine resources.

It allows you to save new resources and load existing ones.

Note
Sim thread only.

Inherits Module< Resources >.

Methods

HResource load (const Path &filePath, ResourceLoadFlags loadFlags=ResourceLoadFlag::Default)
 Loads the resource from a given path. More...
 
template<class T >
ResourceHandle< T > load (const Path &filePath, ResourceLoadFlags loadFlags=ResourceLoadFlag::Default)
 Loads the resource from a given path. More...
 
HResource load (const WeakResourceHandle< Resource > &handle, ResourceLoadFlags loadFlags=ResourceLoadFlag::Default)
 Loads the resource for the provided weak resource handle, or returns a loaded resource if already loaded. More...
 
template<class T >
ResourceHandle< T > load (const WeakResourceHandle< T > &handle, ResourceLoadFlags loadFlags=ResourceLoadFlag::Default)
 Loads the resource for the provided weak resource handle, or returns a loaded resource if already loaded. More...
 
HResource loadAsync (const Path &filePath, ResourceLoadFlags loadFlags=ResourceLoadFlag::Default)
 Loads the resource asynchronously. More...
 
template<class T >
ResourceHandle< T > loadAsync (const Path &filePath, ResourceLoadFlags loadFlags=ResourceLoadFlag::Default)
 Loads the resource asynchronously. More...
 
HResource loadFromUUID (const String &uuid, bool async=false, ResourceLoadFlags loadFlags=ResourceLoadFlag::Default)
 Loads the resource with the given UUID. More...
 
void release (ResourceHandleBase &resource)
 Releases an internal reference to the resource held by the resources system. More...
 
void unloadAllUnused ()
 Finds all resources that aren't being referenced outside of the resources system and unloads them. More...
 
void save (const HResource &resource, const Path &filePath, bool overwrite, bool compress=false)
 Saves the resource at the specified location. More...
 
void save (const HResource &resource, bool compress=false)
 Saves an existing resource to its previous location. More...
 
void update (HResource &handle, const SPtr< Resource > &resource)
 Updates an existing resource handle with a new resource. More...
 
Vector< StringgetDependencies (const Path &filePath)
 Returns a list of dependencies from the resources at the specified path. More...
 
bool isLoaded (const String &uuid, bool checkInProgress=true)
 Checks is the resource with the specified UUID loaded. More...
 
void registerResourceManifest (const SPtr< ResourceManifest > &manifest)
 Allows you to set a resource manifest containing UUID <-> file path mapping that is used when resolving resource references. More...
 
void unregisterResourceManifest (const SPtr< ResourceManifest > &manifest)
 Unregisters a resource manifest previously registered with registerResourceManifest(). More...
 
SPtr< ResourceManifestgetResourceManifest (const String &name) const
 Allows you to retrieve resource manifest containing UUID <-> file path mapping that is used when resolving resource references. More...
 
bool getFilePathFromUUID (const String &uuid, Path &filePath) const
 Attempts to retrieve file path from the provided UUID. More...
 
bool getUUIDFromFilePath (const Path &path, String &uuid) const
 Attempts to retrieve UUID from the provided file path. More...
 
Internal
HResource _createResourceHandle (const SPtr< Resource > &obj)
 Creates a new resource handle from a resource pointer. More...
 
HResource _createResourceHandle (const SPtr< Resource > &obj, const String &UUID)
 Creates a new resource handle from a resource pointer, with a user defined UUID. More...
 
HResource _getResourceHandle (const String &uuid)
 Returns an existing handle for the specified UUID if one exists, or creates a new one. More...
 

Fields

Event< void(const HResource &)> onResourceLoaded
 Called when the resource has been successfully loaded. More...
 
Event< void(const String &)> onResourceDestroyed
 Called when the resource has been destroyed. More...
 
Event< void(const HResource &)> onResourceModified
 Called when the internal resource the handle is pointing to has changed. More...
 

Additional Inherited Members

- Static methods inherited from Module< Resources >
static Resourcesinstance ()
 Returns a reference to the module instance. More...
 
static ResourcesinstancePtr ()
 Returns a pointer to the module instance. More...
 
static void startUp (Args &&...args)
 Constructs and starts the module using the specified parameters. More...
 
static void startUp (Args &&...args)
 Constructs and starts a specialized type of the module. More...
 
static void shutDown ()
 Shuts down this module and frees any resources it is using. More...
 
static bool isStarted ()
 Query if the module has been started. More...
 

Method documentation

HResource _createResourceHandle ( const SPtr< Resource > &  obj)

Creates a new resource handle from a resource pointer.

Note
Internal method used primarily be resource factory methods.
HResource _createResourceHandle ( const SPtr< Resource > &  obj,
const String UUID 
)

Creates a new resource handle from a resource pointer, with a user defined UUID.

Note
Internal method used primarily be resource factory methods.
HResource _getResourceHandle ( const String uuid)

Returns an existing handle for the specified UUID if one exists, or creates a new one.

Vector<String> getDependencies ( const Path filePath)

Returns a list of dependencies from the resources at the specified path.

Resource will not be loaded or parsed, but instead the saved list of dependencies will be read from the file and returned.

Parameters
[in]filePathFull path to the resource to get dependencies for.
Returns
List of dependencies represented as UUIDs.
bool getFilePathFromUUID ( const String uuid,
Path filePath 
) const

Attempts to retrieve file path from the provided UUID.

Returns true if successful, false otherwise.

SPtr<ResourceManifest> getResourceManifest ( const String name) const

Allows you to retrieve resource manifest containing UUID <-> file path mapping that is used when resolving resource references.

Note
Resources module internally holds a "Default" manifest that it automatically updated whenever a resource is saved.
See also
registerResourceManifest
bool getUUIDFromFilePath ( const Path path,
String uuid 
) const

Attempts to retrieve UUID from the provided file path.

Returns true if successful, false otherwise.

bool isLoaded ( const String uuid,
bool  checkInProgress = true 
)

Checks is the resource with the specified UUID loaded.

Parameters
[in]uuidUUID of the resource to check.
[in]checkInProgressShould this method also check resources that are in progress of being asynchronously loaded.
Returns
True if loaded or loading in progress, false otherwise.
HResource load ( const Path filePath,
ResourceLoadFlags  loadFlags = ResourceLoadFlag::Default 
)

Loads the resource from a given path.

Returns an empty handle if resource can't be loaded. Resource is loaded synchronously.

Parameters
[in]filePathFile path to the resource to load. This can be absolute or relative to the working folder.
[in]loadFlagsFlags used to control the load process.
See also
release(ResourceHandleBase&), unloadAllUnused()
ResourceHandle<T> load ( const Path filePath,
ResourceLoadFlags  loadFlags = ResourceLoadFlag::Default 
)

Loads the resource from a given path.

Returns an empty handle if resource can't be loaded. Resource is loaded synchronously.

Parameters
[in]filePathFile path to the resource to load. This can be absolute or relative to the working folder.
[in]loadFlagsFlags used to control the load process.
See also
release(ResourceHandleBase&), unloadAllUnused()
HResource load ( const WeakResourceHandle< Resource > &  handle,
ResourceLoadFlags  loadFlags = ResourceLoadFlag::Default 
)

Loads the resource for the provided weak resource handle, or returns a loaded resource if already loaded.

See also
load(const Path&, ResourceLoadFlags)
ResourceHandle<T> load ( const WeakResourceHandle< T > &  handle,
ResourceLoadFlags  loadFlags = ResourceLoadFlag::Default 
)

Loads the resource for the provided weak resource handle, or returns a loaded resource if already loaded.

See also
load(const Path&, ResourceLoadFlags)
HResource loadAsync ( const Path filePath,
ResourceLoadFlags  loadFlags = ResourceLoadFlag::Default 
)

Loads the resource asynchronously.

Initially returned resource handle will be invalid until resource loading is done. Use ResourceHandle<T>::isLoaded to check if resource has been loaded, or ResourceHandle<T>::blockUntilLoaded to wait until load completes.

Parameters
[in]filePathFull pathname of the file.
[in]loadFlagsFlags used to control the load process.
See also
load(const Path&, ResourceLoadFlags)
ResourceHandle<T> loadAsync ( const Path filePath,
ResourceLoadFlags  loadFlags = ResourceLoadFlag::Default 
)

Loads the resource asynchronously.

Initially returned resource handle will be invalid until resource loading is done. Use ResourceHandle<T>::isLoaded to check if resource has been loaded, or ResourceHandle<T>::blockUntilLoaded to wait until load completes.

Parameters
[in]filePathFull pathname of the file.
[in]loadFlagsFlags used to control the load process.
See also
load(const Path&, ResourceLoadFlags)
HResource loadFromUUID ( const String uuid,
bool  async = false,
ResourceLoadFlags  loadFlags = ResourceLoadFlag::Default 
)

Loads the resource with the given UUID.

Returns an empty handle if resource can't be loaded.

Parameters
[in]uuidUUID of the resource to load.
[in]asyncIf true resource will be loaded asynchronously. Handle to non-loaded resource will be returned immediately while loading will continue in the background.
[in]loadFlagsFlags used to control the load process.
See also
load(const Path&, bool)
void registerResourceManifest ( const SPtr< ResourceManifest > &  manifest)

Allows you to set a resource manifest containing UUID <-> file path mapping that is used when resolving resource references.

Note
If you want objects that reference resources (using ResourceHandles) to be able to find that resource even after application restart, then you must save the resource manifest before closing the application and restore it upon startup. Otherwise resources will be assigned brand new UUIDs and references will be broken.
void release ( ResourceHandleBase resource)

Releases an internal reference to the resource held by the resources system.

This allows the resource to be unloaded when it goes out of scope, if the resource was loaded with keepInternalReference parameter.

Alternatively you can also skip manually calling release() and call unloadAllUnused() which will unload all resources that do not have any external references, but you lose the fine grained control of what will be unloaded.

Parameters
[in]resourceHandle of the resource to release.
void save ( const HResource resource,
const Path filePath,
bool  overwrite,
bool  compress = false 
)

Saves the resource at the specified location.

Parameters
[in]resourceHandle to the resource.
[in]filePathFull pathname of the file to save as.
[in]overwriteIf true, any existing resource at the specified location will be overwritten.
[in]compressShould the resource be compressed before saving. Some resource have data that is already compressed and this option will be ignored for such resources.
Note
If the resource is a GpuResource and you are in some way modifying it from the core thread, make sure all those commands are submitted before you call this method. Otherwise an obsolete version of the resource might get saved.
If saving a core thread resource this is a potentially very slow operation as we must wait on the core thread and the GPU in order to read the resource.
void save ( const HResource resource,
bool  compress = false 
)

Saves an existing resource to its previous location.

Parameters
[in]resourceHandle to the resource.
[in]compressShould the resource be compressed before saving. Some resource have data that is already compressed and this option will be ignored for such resources.
Note
If the resource is a GpuResource and you are in some way modifying it from the Core thread, make sure all those commands are submitted before you call this method. Otherwise an obsolete version of the resource might get saved.
If saving a core thread resource this is a potentially very slow operation as we must wait on the core thread and the GPU in order to read the resource.
void unloadAllUnused ( )

Finds all resources that aren't being referenced outside of the resources system and unloads them.

See also
release(ResourceHandleBase&)
void unregisterResourceManifest ( const SPtr< ResourceManifest > &  manifest)

Unregisters a resource manifest previously registered with registerResourceManifest().

void update ( HResource handle,
const SPtr< Resource > &  resource 
)

Updates an existing resource handle with a new resource.

Caller must ensure that new resource type matches the original resource type.

Member Data Documentation

Event<void(const String&)> onResourceDestroyed

Called when the resource has been destroyed.

Provides UUID of the destroyed resource.

Note
It is undefined from which thread this will get called from.
Event<void(const HResource&)> onResourceLoaded

Called when the resource has been successfully loaded.

Note
It is undefined from which thread this will get called from. Most definitely not the sim thread if resource was being loaded asynchronously.
Event<void(const HResource&)> onResourceModified

Called when the internal resource the handle is pointing to has changed.

Note
It is undefined from which thread this will get called from.