ic
/
magnum
mirror of https://github.com/mosra/magnum.git
6
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Polished docs of ResourceManager API.

pull/51/head
Vladimír Vondruš 12 years ago
parent
b64a50c821
commit
e8aa600a34
3 changed files with 101 additions and 98 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 71
      src/Magnum/AbstractResourceLoader.h
  2. 22
      src/Magnum/Resource.h
  3. 106
      src/Magnum/ResourceManager.h

71
src/Magnum/AbstractResourceLoader.h
Unescape View File

@ -26,7 +26,7 @@
*/ */
/** @file /** @file
* @brief Class Magnum::AbstractResourceLoader * @brief Class @ref Magnum::AbstractResourceLoader
*/ */
#include <string> #include <string>
@ -38,28 +38,30 @@ namespace Magnum {
/** /**
@brief Base for resource loaders @brief Base for resource loaders
Provides (a)synchronous resource loading for ResourceManager. Provides (a)synchronous resource loading for @ref ResourceManager.
@section AbstractResourceLoader-usage Usage and subclassing @section AbstractResourceLoader-usage Usage and subclassing
Usage is done by subclassing. Subclass instances can be added to Usage is done by subclassing. Subclass instances can be added to
ResourceManager using ResourceManager::setLoader(). After adding the loader, @ref ResourceManager using @ref ResourceManager::setLoader(). After adding the
each call to ResourceManager::get() will call load() implementation unless the loader, each call to @ref ResourceManager::get() will call @ref load()
resource is already loaded (or loading is in progress). Note that resources implementation unless the resource is already loaded (or loading is in
requested before the loader was added are not be affected by the loader. progress). Note that resources requested before the loader was added are not
affected by the loader.
Subclassing is done by implementing at least doLoad() function. The loading can
be done synchronously or asynchronously (i.e., in another thread). The base Subclassing is done by implementing at least @ref doLoad() function. The
implementation provides interface to ResourceManager and manages loading loading can be done synchronously or asynchronously (i.e., in another thread).
progress (which is then available through functions requestedCount(), The base implementation provides interface to @ref ResourceManager and manages
loadedCount() and notFoundCount()). You shouldn't access the ResourceManager loading progress (which is then available through functions @ref requestedCount(),
directly when loading the data. @ref loadedCount() and @ref notFoundCount()). You shouldn't access the
@ref ResourceManager directly when loading the data.
In your doLoad() implementation, after your resources are loaded, call set() to
pass them to ResourceManager or call setNotFound() to indicate that the In your @ref doLoad() implementation, after your resources are loaded, call
resource was not found. @ref set() to pass them to @ref ResourceManager or call @ref setNotFound() to
indicate that the resource was not found.
You can also implement name() to provide meaningful names for resource keys.
You can also implement @ref name() to provide meaningful names for resource
keys.
Example implementation for synchronous mesh loader: Example implementation for synchronous mesh loader:
@code @code
@ -109,23 +111,23 @@ template<class T> class AbstractResourceLoader {
/** /**
* @brief Count of requested resources * @brief Count of requested resources
* *
* Count of resources requested by calling load(). * Count of resources requested by calling @ref load().
*/ */
std::size_t requestedCount() const { return _requestedCount; } std::size_t requestedCount() const { return _requestedCount; }
/** /**
* @brief Count of not found resources * @brief Count of not found resources
* *
* Count of resources requested by calling load(), but not found by * Count of resources requested by calling @ref load(), but not found
* the loader. * by the loader.
*/ */
std::size_t notFoundCount() const { return _notFoundCount; } std::size_t notFoundCount() const { return _notFoundCount; }
/** /**
* @brief Count of loaded resources * @brief Count of loaded resources
* *
* Count of resources requested by calling load(), but not found by * Count of resources requested by calling @ref load(), but not found
* the loader. * by the loader.
*/ */
std::size_t loadedCount() const { return _loadedCount; } std::size_t loadedCount() const { return _loadedCount; }
@ -145,8 +147,8 @@ template<class T> class AbstractResourceLoader {
* features is incremented. Depending on implementation the resource * features is incremented. Depending on implementation the resource
* might be loaded synchronously or asynchronously. * might be loaded synchronously or asynchronously.
* *
* @see ResourceManager::state(), requestedCount(), notFoundCount(), * @see @ref ResourceManager::state(), @ref requestedCount(),
* loadedCount() * @ref notFoundCount(), @ref loadedCount()
*/ */
void load(ResourceKey key); void load(ResourceKey key);
@ -155,9 +157,10 @@ template<class T> class AbstractResourceLoader {
* @brief Set loaded resource to resource manager * @brief Set loaded resource to resource manager
* *
* Also increments count of loaded resources. Parameter @p state must * Also increments count of loaded resources. Parameter @p state must
* be either @ref ResourceDataState::Mutable or @ref ResourceDataState::Final. * be either @ref ResourceDataState::Mutable or
* See @ref ResourceManager::set() for more information. * @ref ResourceDataState::Final. See @ref ResourceManager::set() for
* @see loadedCount() * more information.
* @see @ref loadedCount()
*/ */
void set(ResourceKey key, T* data, ResourceDataState state, ResourcePolicy policy); void set(ResourceKey key, T* data, ResourceDataState state, ResourcePolicy policy);
@ -184,9 +187,9 @@ template<class T> class AbstractResourceLoader {
/** /**
* @brief Mark resource as not found * @brief Mark resource as not found
* *
* Also increments count of not found resources. See * Also increments count of not found resources. See also
* ResourceManager::setNotFound() for more information. * @ref ResourceManager::set() for more information.
* @see notFountCount() * @see @ref notFoundCount()
*/ */
void setNotFound(ResourceKey key); void setNotFound(ResourceKey key);
@ -196,14 +199,14 @@ template<class T> class AbstractResourceLoader {
protected: protected:
#endif #endif
/** /**
* @brief Implementation for name() * @brief Implementation for @ref name()
* *
* Default implementation returns empty string. * Default implementation returns empty string.
*/ */
virtual std::string doName(ResourceKey key) const; virtual std::string doName(ResourceKey key) const;
/** /**
* @brief Implementation for load() * @brief Implementation for @ref load()
* *
* See class documentation for reimplementation guide. * See class documentation for reimplementation guide.
*/ */

22
src/Magnum/Resource.h
Unescape View File

@ -26,7 +26,7 @@
*/ */
/** @file /** @file
* @brief Class Magnum::ResourceKey, Magnum::Resource, enum Magnum::ResourceState * @brief Class @ref Magnum::ResourceKey, @ref Magnum::Resource, enum @ref Magnum::ResourceState
*/ */
#include <Corrade/Utility/Assert.h> #include <Corrade/Utility/Assert.h>
@ -37,11 +37,11 @@
namespace Magnum { namespace Magnum {
/** @relates Resource /**
* @brief %Resource state @brief %Resource state
*
* @see Resource::state(), ResourceManager::state() @see @ref Resource::state(), @ref ResourceManager::state()
*/ */
enum class ResourceState: UnsignedByte { enum class ResourceState: UnsignedByte {
/** The resource is not yet loaded (and no fallback is available). */ /** The resource is not yet loaded (and no fallback is available). */
NotLoaded, NotLoaded,
@ -74,9 +74,7 @@ Debug MAGNUM_EXPORT operator<<(Debug debug, ResourceState value);
/** /**
@brief Key for accessing resource @brief Key for accessing resource
See ResourceManager for more information. See @ref ResourceManager for more information.
@see ResourceManager::referenceCount(), ResourceManager::state(),
ResourceManager::get(), ResourceManager::set(), Resource::key()
*/ */
class ResourceKey: public Utility::MurmurHash2::Digest { class ResourceKey: public Utility::MurmurHash2::Digest {
public: public:
@ -110,7 +108,7 @@ namespace Implementation {
/** /**
@brief %Resource reference @brief %Resource reference
See ResourceManager for more information. See @ref ResourceManager for more information.
*/ */
#ifdef DOXYGEN_GENERATING_OUTPUT #ifdef DOXYGEN_GENERATING_OUTPUT
template<class T, class U = T> template<class T, class U = T>
@ -125,7 +123,7 @@ class Resource {
* @brief Default constructor * @brief Default constructor
* *
* Creates empty resource. Resources are acquired from the manager by * Creates empty resource. Resources are acquired from the manager by
* calling ResourceManager::get(). * calling @ref ResourceManager::get().
*/ */
explicit Resource(): manager(nullptr), lastCheck(0), _state(ResourceState::Final), data(nullptr) {} explicit Resource(): manager(nullptr), lastCheck(0), _state(ResourceState::Final), data(nullptr) {}
@ -157,7 +155,7 @@ class Resource {
/** /**
* @brief %Resource state * @brief %Resource state
* *
* @see operator bool(), ResourceManager::state() * @see @ref operator bool(), @ref ResourceManager::state()
*/ */
ResourceState state() { ResourceState state() {
acquire(); acquire();

106
src/Magnum/ResourceManager.h
Unescape View File

@ -26,7 +26,7 @@
*/ */
/** @file /** @file
* @brief Class Magnum::ResourceManager, enum Magnum::ResourceDataState, Magnum::ResourcePolicy * @brief Class @ref Magnum::ResourceManager, @ref Magnum::ResourceDataState, @ref Magnum::ResourcePolicy
*/ */
#include <unordered_map> #include <unordered_map>
@ -35,44 +35,44 @@
namespace Magnum { namespace Magnum {
/** @relates ResourceManager /**
* @brief %Resource data state @brief %Resource data state
*
* @see ResourceManager::set(), ResourceState @see @ref ResourceManager::set(), @ref ResourceState
*/ */
enum class ResourceDataState: UnsignedByte { enum class ResourceDataState: UnsignedByte {
/** /**
* The resource is currently loading. Parameter @p data in ResourceManager::set() * The resource is currently loading. Parameter @p data in
* should be set to `null`. * @ref ResourceManager::set() should be set to `nullptr`.
*/ */
Loading = UnsignedByte(ResourceState::Loading), Loading = UnsignedByte(ResourceState::Loading),
/** /**
* The resource was not found. Parameter @p data in ResourceManager::set() * The resource was not found. Parameter @p data in
* should be set to `null`. * @ref ResourceManager::set() should be set to `nullptr`.
*/ */
NotFound = UnsignedByte(ResourceState::NotFound), NotFound = UnsignedByte(ResourceState::NotFound),
/** /**
* The resource can be changed by the manager in the future. This is * The resource can be changed by the manager in the future. This is
* slower, as Resource needs to ask the manager for new version every time * slower, as @ref Resource needs to ask the manager for new version every
* the data are accessed, but allows changing the data for e.g. debugging * time the data are accessed, but allows changing the data for e.g.
* purposes. * debugging purposes.
*/ */
Mutable = UnsignedByte(ResourceState::Mutable), Mutable = UnsignedByte(ResourceState::Mutable),
/** /**
* The resource cannot be changed by the manager in the future. This is * The resource cannot be changed by the manager in the future. This is
* faster, as Resource instances will ask for the data only one time, thus * faster, as @ref Resource instances will ask for the data only one time,
* suitable for production code. * thus suitable for production code.
*/ */
Final = UnsignedByte(ResourceState::Final) Final = UnsignedByte(ResourceState::Final)
}; };
/** @relates ResourceManager /**
@brief %Resource policy @brief %Resource policy
@see ResourceManager::set(), ResourceManager::free() @see @ref ResourceManager::set(), @ref ResourceManager::free()
*/ */
enum class ResourcePolicy: UnsignedByte { enum class ResourcePolicy: UnsignedByte {
/** The resource will stay resident for whole lifetime of resource manager. */ /** The resource will stay resident for whole lifetime of resource manager. */
@ -80,7 +80,7 @@ enum class ResourcePolicy: UnsignedByte {
/** /**
* The resource will be unloaded when manually calling * The resource will be unloaded when manually calling
* ResourceManager::free() if nothing references it. * @ref ResourceManager::free() if nothing references it.
*/ */
Manual, Manual,
@ -160,43 +160,43 @@ template<class T> class ResourceManagerData {
@brief %Resource manager @brief %Resource manager
Provides storage for arbitrary set of types, accessible globally using Provides storage for arbitrary set of types, accessible globally using
instance(). @ref instance().
@section ResourceManager-usage Usage @section ResourceManager-usage Usage
Each resource is referenced from Resource class. For optimizing performance, Each resource is referenced from @ref Resource class. For optimizing
each resource can be set as mutable or final. Mutable resources can be performance, each resource can be set as mutable or final. Mutable resources
modified by the manager and thus each %Resource instance asks the manager for can be modified by the manager and thus each @ref Resource instance asks the
modifications on each access. On the other hand, final resources cannot be manager for modifications on each access. On the other hand, final resources
modified by the manager, so %Resource instances don't have to ask the manager cannot be modified by the manager, so @ref Resource instances don't have to ask
every time, which is faster. the manager every time, which is faster.
It's possible to provide fallback for resources which are not available using It's possible to provide fallback for resources which are not available using
setFallback(). Accessing data of such resources will access the fallback @ref setFallback(). Accessing data of such resources will access the fallback
instead of failing on null pointer dereference. Availability and state of each instead of failing on null pointer dereference. Availability and state of each
resource can be queried through function state() on the manager or resource can be queried through function @ref state() on the manager or
Resource::state() on each resource. @ref Resource::state() on each resource.
The resources can be managed in three ways - resident resources, which stay in The resources can be managed in three ways - resident resources, which stay in
memory for whole lifetime of the manager, manually managed resources, which memory for whole lifetime of the manager, manually managed resources, which
can be deleted by calling free() if nothing references them anymore, and can be deleted by calling @ref free() if nothing references them anymore, and
reference counted resources, which are deleted as soon as the last reference reference counted resources, which are deleted as soon as the last reference
to them is removed. to them is removed.
%Resource state and policy is configured when setting the resource data in %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 @ref set() and can be changed each time the data are updated, although already
final resources cannot obviously be set as mutable again. final resources cannot obviously be set as mutable again.
Basic usage is: Basic usage is:
- Typedef'ing manager of desired types, creating its instance. - Typedef'ing manager of desired types, creating its instance.
@code @code
typedef ResourceManager<Mesh, Texture2D, AbstractShaderProgram> MyResourceManager; typedef ResourceManager<Mesh, Texture2D, AbstractShaderProgram> MyResourceManager;
MyResourceManager manager; MyResourceManager manager;
@endcode @endcode
- Filling the manager with resource data and acquiring the resources. Note - Filling the manager with resource data and acquiring the resources. Note
that a resource can be acquired with get() even before the manager contains that a resource can be acquired with @ref get() even before the manager
the data for it, as long as the resource data are not accessed (or fallback contains the data for it, as long as the resource data are not accessed (or
is provided). fallback is provided).
@code @code
MyResourceManager* manager = MyResourceManager::instance(); MyResourceManager* manager = MyResourceManager::instance();
Resource<Texture2D> texture(manager->get<Texture2D>("texture")); Resource<Texture2D> texture(manager->get<Texture2D>("texture"));
@ -210,13 +210,13 @@ if(!cube) {
manager->set(cube.key(), mesh, ResourceDataState::Final, ResourcePolicy::Resident); manager->set(cube.key(), mesh, ResourceDataState::Final, ResourcePolicy::Resident);
} }
@endcode @endcode
- Using the resource data. - Using the resource data.
@code @code
shader->setTexture(layer); shader->setTexture(layer);
cube->draw(*shader); cube->draw(*shader);
@endcode @endcode
- Destroying resource references and deleting manager instance when nothing - Destroying resource references and deleting manager instance when nothing
references the resources anymore. references the resources anymore.
@see AbstractResourceLoader @see AbstractResourceLoader
*/ */
@ -238,7 +238,7 @@ template<class... Types> class ResourceManager: private Implementation::Resource
* Sets global instance pointer to itself. * Sets global instance pointer to itself.
* @attention Only one instance of given ResourceManager type can be * @attention Only one instance of given ResourceManager type can be
* created. * created.
* @see instance() * @see @ref instance()
*/ */
explicit ResourceManager(); explicit ResourceManager();
@ -246,7 +246,7 @@ template<class... Types> class ResourceManager: private Implementation::Resource
* @brief Destructor * @brief Destructor
* *
* Sets global instance pointer to `nullptr`. * Sets global instance pointer to `nullptr`.
* @see instance() * @see @ref instance()
*/ */
~ResourceManager(); ~ResourceManager();
@ -274,7 +274,7 @@ template<class... Types> class ResourceManager: private Implementation::Resource
/** /**
* @brief Reference count of given resource * @brief Reference count of given resource
* *
* @see set() * @see @ref set()
*/ */
template<class T> std::size_t referenceCount(ResourceKey key) const { template<class T> std::size_t referenceCount(ResourceKey key) const {
return this->Implementation::ResourceManagerData<T>::referenceCount(key); return this->Implementation::ResourceManagerData<T>::referenceCount(key);
@ -283,7 +283,7 @@ template<class... Types> class ResourceManager: private Implementation::Resource
/** /**
* @brief %Resource state * @brief %Resource state
* *
* @see set(), Resource::state() * @see @ref set(), @ref Resource::state()
*/ */
template<class T> ResourceState state(ResourceKey key) const { template<class T> ResourceState state(ResourceKey key) const {
return this->Implementation::ResourceManagerData<T>::state(key); return this->Implementation::ResourceManagerData<T>::state(key);
@ -293,20 +293,20 @@ template<class... Types> class ResourceManager: private Implementation::Resource
* @brief Set resource data * @brief Set resource data
* @return Reference to self (for method chaining) * @return Reference to self (for method chaining)
* *
* If @p policy is set to `ResourcePolicy::ReferenceCounted`, there * If @p policy is set to @ref ResourcePolicy::ReferenceCounted, there
* must be already at least one reference to given resource, otherwise * must be already at least one reference to given resource, otherwise
* the data will be deleted immediately and no resource will be * the data will be deleted immediately and no resource will be added.
* added. To avoid spending unnecessary loading time, add * To avoid spending unnecessary loading time, add reference-counted
* reference-counted resources only if they are already referenced: * resources only if they are already referenced:
* @code * @code
* if(manager.referenceCount<T>("myresource")) { * if(manager.referenceCount<T>("myresource")) {
* // load data... * // load data...
* manager.set("myresource", data, state, ResourcePolicy::ReferenceCounted); * manager.set("myresource", data, state, ResourcePolicy::ReferenceCounted);
* } * }
* @endcode * @endcode
* @attention If resource state is already `ResourceState::Final`, * @attention Subsequent updates are not possible if resource state is
* subsequent updates are not possible. * already @ref ResourceState::Final.
* @see referenceCount(), state() * @see @ref referenceCount(), @ref state()
*/ */
template<class T> ResourceManager<Types...>& set(ResourceKey key, T* data, ResourceDataState state, ResourcePolicy policy) { template<class T> ResourceManager<Types...>& set(ResourceKey key, T* data, ResourceDataState state, ResourcePolicy policy) {
this->Implementation::ResourceManagerData<T>::set(key, data, state, policy); this->Implementation::ResourceManagerData<T>::set(key, data, state, policy);
@ -380,7 +380,8 @@ template<class... Types> class ResourceManager: private Implementation::Resource
* @brief Clear all resources of given type * @brief Clear all resources of given type
* @return Reference to self (for method chaining) * @return Reference to self (for method chaining)
* *
* Unlike free() this function assumes that no resource is referenced. * Unlike @ref free() this function assumes that no resource is
* referenced.
*/ */
template<class T> ResourceManager<Types...>& clear() { template<class T> ResourceManager<Types...>& clear() {
this->Implementation::ResourceManagerData<T>::clear(); this->Implementation::ResourceManagerData<T>::clear();
@ -391,7 +392,8 @@ template<class... Types> class ResourceManager: private Implementation::Resource
* @brief Clear all resources * @brief Clear all resources
* @return Reference to self (for method chaining) * @return Reference to self (for method chaining)
* *
* Unlike free() this function assumes that no resource is referenced. * Unlike @ref free() this function assumes that no resource is
* referenced.
*/ */
ResourceManager<Types...>& clear() { ResourceManager<Types...>& clear() {
clearInternal<Types...>(); clearInternal<Types...>();
@ -413,7 +415,7 @@ template<class... Types> class ResourceManager: private Implementation::Resource
* @param loader Loader or `nullptr` if unsetting previous loader. * @param loader Loader or `nullptr` if unsetting previous loader.
* @return Reference to self (for method chaining) * @return Reference to self (for method chaining)
* *
* See AbstractResourceLoader documentation for more information. * See @ref AbstractResourceLoader documentation for more information.
* @attention The loader is deleted on destruction before unloading * @attention The loader is deleted on destruction before unloading
* all resources. * all resources.
*/ */

Write Preview
Loading…
Cancel
Save