#include <Magnum/ResourceManager.h>
template<class... Types>
Magnum::ResourceManager class

Resource manager.

Provides storage for arbitrary set of types.

Usage

Each resource is referenced from Resource class. For optimizing performance, each resource can be set as mutable or final. Mutable resources can be modified by the manager and thus each Resource instance asks the manager for modifications on each access. On the other hand, final resources cannot be modified by the manager, so Resource instances don't have to ask the manager every time, which is faster.

It's possible to provide fallback for resources which are not available using setFallback(). Accessing data of such resources will access the fallback instead of failing on null pointer dereference. Availability and state of each resource can be queried through function state() on the manager or Resource::state() on each resource.

The resources can be managed in three ways - resident resources, which stay in memory for whole lifetime of the manager, manually managed resources, which can be deleted by calling free() if nothing references them anymore, and reference counted resources, which are deleted as soon as the last reference to them is removed.

Resource state and policy is configured when setting the resource data in set() and can be changed each time the data are updated, although already final resources cannot obviously be set as mutable again.

Basic usage is:

  • Typedef'ing manager of desired types, creating its instance.

    typedef ResourceManager<GL::Mesh, GL::Texture2D, GL::AbstractShaderProgram>
    MyResourceManager;
MyResourceManager manager;

  • Filling the manager with resource data and acquiring the resources. Note that a resource can be acquired with get() even before the manager contains the data for it, as long as the resource data are not accessed (or fallback is provided).

    MyResourceManager manager;
Resource<GL::Texture2D> texture{manager.get<GL::Texture2D>("texture")};
Resource<GL::AbstractShaderProgram, MyShader> shader =
    manager.get<GL::AbstractShaderProgram, MyShader>("shader");
Resource<GL::Mesh> cube = manager.get<GL::Mesh>("cube");

// The manager doesn't have data for the cube yet, add them
if(!cube) {
    GL::Mesh mesh;
    // ...
    manager.set(cube.key(), std::move(mesh));
}

  • Using the resource data.

    (*shader)
    .bindTexture(*texture)
    .draw(*cube);
  • Destroying resource references and deleting manager instance when nothing references the resources anymore.

Constructors, destructors, conversion operators

ResourceManager() explicit
Constructor.
~ResourceManager()
Destructor.

Public functions

template<class T>
auto count() -> std::size_t
Count of resources of given type.
template<class T, class U = T>
auto get(ResourceKey key) -> Resource<T, U>
Get resource reference.
template<class T>
auto referenceCount(ResourceKey key) const -> std::size_t
Reference count of given resource.
template<class T>
auto state(ResourceKey key) const -> ResourceState
Resource state.
template<class T>
auto set(ResourceKey key, T* data, ResourceDataState state, ResourcePolicy policy) -> ResourceManager<Types...>&
Set resource data.
template<class T>
auto set(ResourceKey key, Containers::Pointer<T>&& data, ResourceDataState state, ResourcePolicy policy) -> ResourceManager<Types...>& new in 2019.10
template<class U>
auto set(ResourceKey key, U&& data, ResourceDataState state, ResourcePolicy policy) -> ResourceManager<Types...>&
template<class T>
auto set(ResourceKey key, T* data) -> ResourceManager<Types...>&
Set resource data.
template<class T>
auto set(ResourceKey key, Containers::Pointer<T>&& data) -> ResourceManager<Types...>&
template<class U>
auto set(ResourceKey key, U&& data) -> ResourceManager<Types...>&
template<class T>
auto fallback() -> T*
Fallback for not found resources.
template<class T>
auto fallback() const -> const T*
template<class T>
auto setFallback(T* data) -> ResourceManager<Types...>&
Set fallback for not found resources.
template<class T>
auto setFallback(Containers::Pointer<T>&& data) -> ResourceManager<Types...>& new in 2019.10
template<class U>
auto setFallback(U&& data) -> ResourceManager<Types...>&
template<class T>
auto free() -> ResourceManager<Types...>&
Free all resources of given type which are not referenced.
auto free() -> ResourceManager<Types...>&
Free all resources which are not referenced.
template<class T>
auto clear() -> ResourceManager<Types...>&
Clear all resources of given type.
auto clear() -> ResourceManager<Types...>&
Clear all resources.
template<class T>
auto loader() -> AbstractResourceLoader<T>*
Loader for given type of resources.
template<class T>
auto loader() const -> const AbstractResourceLoader<T>*
template<class T>
auto setLoader(AbstractResourceLoader<T>* loader) -> ResourceManager<Types...>&
Set loader for given type of resources.
template<class T>
auto setLoader(Containers::Pointer<AbstractResourceLoader<T>>&& loader) -> ResourceManager<Types...>&

Function documentation

template<class... Types>
Magnum::ResourceManager<Types>::~ResourceManager()

Destructor.

Expects that all resources are not referenced anymore at the point of destruction.

template<class... Types> template<class T, class U = T>
Resource<T, U> Magnum::ResourceManager<Types>::get(ResourceKey key)

Get resource reference.

In some cases it's desirable to store various different types under one base type for memory efficiency reasons. To avoid putting the responsibility of proper casting on the user, the acquired resource can be defined to cast the type automatically when accessing the data. This is commonly used for shaders, e.g.:

Resource<GL::AbstractShaderProgram, MyShader> shader =
    manager.get<GL::AbstractShaderProgram, MyShader>("shader");

template<class... Types> template<class T>
std::size_t Magnum::ResourceManager<Types>::referenceCount(ResourceKey key) const

Reference count of given resource.

template<class... Types> template<class T>
ResourceState Magnum::ResourceManager<Types>::state(ResourceKey key) const

Resource state.

template<class... Types> template<class T>
ResourceManager<Types...>& Magnum::ResourceManager<Types>::set(ResourceKey key, T* data, ResourceDataState state, ResourcePolicy policy)

Set resource data.

Returns Reference to self (for method chaining)

Resources with ResourcePolicy::ReferenceCounted are added with zero reference count. It means that all reference counted resources which were only loaded but not used will stay loaded and you need to explicitly call free() to delete them.

template<class... Types> template<class T>
ResourceManager<Types...>& Magnum::ResourceManager<Types>::set(ResourceKey key, Containers::Pointer<T>&& data, ResourceDataState state, ResourcePolicy policy) new in 2019.10

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

template<class... Types> template<class U>
ResourceManager<Types...>& Magnum::ResourceManager<Types>::set(ResourceKey key, U&& data, ResourceDataState state, ResourcePolicy policy)

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

template<class... Types> template<class T>
ResourceManager<Types...>& Magnum::ResourceManager<Types>::set(ResourceKey key, T* data)

Set resource data.

Returns Reference to self (for method chaining)

Same as above with state set to ResourceDataState::Final and policy to ResourcePolicy::Resident.

template<class... Types> template<class T>
ResourceManager<Types...>& Magnum::ResourceManager<Types>::set(ResourceKey key, Containers::Pointer<T>&& data)

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

template<class... Types> template<class U>
ResourceManager<Types...>& Magnum::ResourceManager<Types>::set(ResourceKey key, U&& data)

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

template<class... Types> template<class T>
const T* Magnum::ResourceManager<Types>::fallback() const

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

template<class... Types> template<class T>
ResourceManager<Types...>& Magnum::ResourceManager<Types>::setFallback(T* data)

Set fallback for not found resources.

Returns Reference to self (for method chaining)

template<class... Types> template<class T>
ResourceManager<Types...>& Magnum::ResourceManager<Types>::setFallback(Containers::Pointer<T>&& data) new in 2019.10

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

template<class... Types> template<class U>
ResourceManager<Types...>& Magnum::ResourceManager<Types>::setFallback(U&& data)

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

template<class... Types> template<class T>
ResourceManager<Types...>& Magnum::ResourceManager<Types>::free()

Free all resources of given type which are not referenced.

Returns Reference to self (for method chaining)

template<class... Types>
ResourceManager<Types...>& Magnum::ResourceManager<Types>::free()

Free all resources which are not referenced.

Returns Reference to self (for method chaining)

template<class... Types> template<class T>
ResourceManager<Types...>& Magnum::ResourceManager<Types>::clear()

Clear all resources of given type.

Returns Reference to self (for method chaining)

Unlike free() this function assumes that no resource is referenced.

template<class... Types>
ResourceManager<Types...>& Magnum::ResourceManager<Types>::clear()

Clear all resources.

Returns Reference to self (for method chaining)

Unlike free() this function assumes that no resource is referenced.

template<class... Types> template<class T>
const AbstractResourceLoader<T>* Magnum::ResourceManager<Types>::loader() const

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

template<class... Types> template<class T>
ResourceManager<Types...>& Magnum::ResourceManager<Types>::setLoader(AbstractResourceLoader<T>* loader)

Set loader for given type of resources.

Parameters
loader Loader or nullptr if unsetting previous loader.
Returns Reference to self (for method chaining)

See AbstractResourceLoader documentation for more information.

template<class... Types> template<class T>
ResourceManager<Types...>& Magnum::ResourceManager<Types>::setLoader(Containers::Pointer<AbstractResourceLoader<T>>&& loader)

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