diff --git a/src/Magnum/AbstractResourceLoader.h b/src/Magnum/AbstractResourceLoader.h index 4430dff5c..8eedaefcd 100644 --- a/src/Magnum/AbstractResourceLoader.h +++ b/src/Magnum/AbstractResourceLoader.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::AbstractResourceLoader + * @brief Class @ref Magnum::AbstractResourceLoader */ #include @@ -38,28 +38,30 @@ namespace Magnum { /** @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 Usage is done by subclassing. Subclass instances can be added to -ResourceManager using ResourceManager::setLoader(). After adding the loader, -each call to ResourceManager::get() will call load() implementation unless the -resource is already loaded (or loading is in progress). Note that resources -requested before the loader was added are not be 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 -implementation provides interface to ResourceManager and manages loading -progress (which is then available through functions requestedCount(), -loadedCount() and notFoundCount()). You shouldn't access the 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 -resource was not found. - -You can also implement name() to provide meaningful names for resource keys. +@ref ResourceManager using @ref ResourceManager::setLoader(). After adding the +loader, each call to @ref ResourceManager::get() will call @ref load() +implementation unless the resource is already loaded (or loading is in +progress). Note that resources requested before the loader was added are not +affected by the loader. + +Subclassing is done by implementing at least @ref doLoad() function. The +loading can be done synchronously or asynchronously (i.e., in another thread). +The base implementation provides interface to @ref ResourceManager and manages +loading progress (which is then available through functions @ref requestedCount(), +@ref loadedCount() and @ref notFoundCount()). You shouldn't access the +@ref ResourceManager directly when loading the data. + +In your @ref doLoad() implementation, after your resources are loaded, call +@ref set() to pass them to @ref ResourceManager or call @ref setNotFound() to +indicate that the resource was not found. + +You can also implement @ref name() to provide meaningful names for resource +keys. Example implementation for synchronous mesh loader: @code @@ -109,23 +111,23 @@ template class AbstractResourceLoader { /** * @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; } /** * @brief Count of not found resources * - * Count of resources requested by calling load(), but not found by - * the loader. + * Count of resources requested by calling @ref load(), but not found + * by the loader. */ std::size_t notFoundCount() const { return _notFoundCount; } /** * @brief Count of loaded resources * - * Count of resources requested by calling load(), but not found by - * the loader. + * Count of resources requested by calling @ref load(), but not found + * by the loader. */ std::size_t loadedCount() const { return _loadedCount; } @@ -145,8 +147,8 @@ template class AbstractResourceLoader { * features is incremented. Depending on implementation the resource * might be loaded synchronously or asynchronously. * - * @see ResourceManager::state(), requestedCount(), notFoundCount(), - * loadedCount() + * @see @ref ResourceManager::state(), @ref requestedCount(), + * @ref notFoundCount(), @ref loadedCount() */ void load(ResourceKey key); @@ -155,9 +157,10 @@ template class AbstractResourceLoader { * @brief Set loaded resource to resource manager * * Also increments count of loaded resources. Parameter @p state must - * be either @ref ResourceDataState::Mutable or @ref ResourceDataState::Final. - * See @ref ResourceManager::set() for more information. - * @see loadedCount() + * be either @ref ResourceDataState::Mutable or + * @ref ResourceDataState::Final. See @ref ResourceManager::set() for + * more information. + * @see @ref loadedCount() */ void set(ResourceKey key, T* data, ResourceDataState state, ResourcePolicy policy); @@ -184,9 +187,9 @@ template class AbstractResourceLoader { /** * @brief Mark resource as not found * - * Also increments count of not found resources. See - * ResourceManager::setNotFound() for more information. - * @see notFountCount() + * Also increments count of not found resources. See also + * @ref ResourceManager::set() for more information. + * @see @ref notFoundCount() */ void setNotFound(ResourceKey key); @@ -196,14 +199,14 @@ template class AbstractResourceLoader { protected: #endif /** - * @brief Implementation for name() + * @brief Implementation for @ref name() * * Default implementation returns empty string. */ virtual std::string doName(ResourceKey key) const; /** - * @brief Implementation for load() + * @brief Implementation for @ref load() * * See class documentation for reimplementation guide. */ diff --git a/src/Magnum/Resource.h b/src/Magnum/Resource.h index 57d701a03..787e39f90 100644 --- a/src/Magnum/Resource.h +++ b/src/Magnum/Resource.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::ResourceKey, Magnum::Resource, enum Magnum::ResourceState + * @brief Class @ref Magnum::ResourceKey, @ref Magnum::Resource, enum @ref Magnum::ResourceState */ #include @@ -37,11 +37,11 @@ namespace Magnum { -/** @relates Resource - * @brief %Resource state - * - * @see Resource::state(), ResourceManager::state() - */ +/** +@brief %Resource state + +@see @ref Resource::state(), @ref ResourceManager::state() +*/ enum class ResourceState: UnsignedByte { /** The resource is not yet loaded (and no fallback is available). */ NotLoaded, @@ -74,9 +74,7 @@ Debug MAGNUM_EXPORT operator<<(Debug debug, ResourceState value); /** @brief Key for accessing resource -See ResourceManager for more information. -@see ResourceManager::referenceCount(), ResourceManager::state(), - ResourceManager::get(), ResourceManager::set(), Resource::key() +See @ref ResourceManager for more information. */ class ResourceKey: public Utility::MurmurHash2::Digest { public: @@ -110,7 +108,7 @@ namespace Implementation { /** @brief %Resource reference -See ResourceManager for more information. +See @ref ResourceManager for more information. */ #ifdef DOXYGEN_GENERATING_OUTPUT template @@ -125,7 +123,7 @@ class Resource { * @brief Default constructor * * 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) {} @@ -157,7 +155,7 @@ class Resource { /** * @brief %Resource state * - * @see operator bool(), ResourceManager::state() + * @see @ref operator bool(), @ref ResourceManager::state() */ ResourceState state() { acquire(); diff --git a/src/Magnum/ResourceManager.h b/src/Magnum/ResourceManager.h index 1030abc0f..67d6dfcc8 100644 --- a/src/Magnum/ResourceManager.h +++ b/src/Magnum/ResourceManager.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::ResourceManager, enum Magnum::ResourceDataState, Magnum::ResourcePolicy + * @brief Class @ref Magnum::ResourceManager, @ref Magnum::ResourceDataState, @ref Magnum::ResourcePolicy */ #include @@ -35,44 +35,44 @@ namespace Magnum { -/** @relates ResourceManager - * @brief %Resource data state - * - * @see ResourceManager::set(), ResourceState - */ +/** +@brief %Resource data state + +@see @ref ResourceManager::set(), @ref ResourceState +*/ enum class ResourceDataState: UnsignedByte { /** - * The resource is currently loading. Parameter @p data in ResourceManager::set() - * should be set to `null`. + * The resource is currently loading. Parameter @p data in + * @ref ResourceManager::set() should be set to `nullptr`. */ Loading = UnsignedByte(ResourceState::Loading), /** - * The resource was not found. Parameter @p data in ResourceManager::set() - * should be set to `null`. + * The resource was not found. Parameter @p data in + * @ref ResourceManager::set() should be set to `nullptr`. */ NotFound = UnsignedByte(ResourceState::NotFound), /** * 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 - * the data are accessed, but allows changing the data for e.g. debugging - * purposes. + * slower, as @ref Resource needs to ask the manager for new version every + * time the data are accessed, but allows changing the data for e.g. + * debugging purposes. */ Mutable = UnsignedByte(ResourceState::Mutable), /** * 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 - * suitable for production code. + * faster, as @ref Resource instances will ask for the data only one time, + * thus suitable for production code. */ Final = UnsignedByte(ResourceState::Final) }; -/** @relates ResourceManager +/** @brief %Resource policy -@see ResourceManager::set(), ResourceManager::free() +@see @ref ResourceManager::set(), @ref ResourceManager::free() */ enum class ResourcePolicy: UnsignedByte { /** 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 - * ResourceManager::free() if nothing references it. + * @ref ResourceManager::free() if nothing references it. */ Manual, @@ -160,43 +160,43 @@ template class ResourceManagerData { @brief %Resource manager Provides storage for arbitrary set of types, accessible globally using -instance(). +@ref instance(). @section ResourceManager-usage 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. +Each resource is referenced from @ref 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 @ref Resource instance asks the +manager for modifications on each access. On the other hand, final resources +cannot be modified by the manager, so @ref 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 +@ref 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. +resource can be queried through function @ref state() on the manager or +@ref 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 +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 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 +@ref 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'ing manager of desired types, creating its instance. @code typedef ResourceManager MyResourceManager; MyResourceManager manager; @endcode -- 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). +- Filling the manager with resource data and acquiring the resources. Note + that a resource can be acquired with @ref get() even before the manager + contains the data for it, as long as the resource data are not accessed (or + fallback is provided). @code MyResourceManager* manager = MyResourceManager::instance(); Resource texture(manager->get("texture")); @@ -210,13 +210,13 @@ if(!cube) { manager->set(cube.key(), mesh, ResourceDataState::Final, ResourcePolicy::Resident); } @endcode -- Using the resource data. +- Using the resource data. @code shader->setTexture(layer); cube->draw(*shader); @endcode -- Destroying resource references and deleting manager instance when nothing - references the resources anymore. +- Destroying resource references and deleting manager instance when nothing + references the resources anymore. @see AbstractResourceLoader */ @@ -238,7 +238,7 @@ template class ResourceManager: private Implementation::Resource * Sets global instance pointer to itself. * @attention Only one instance of given ResourceManager type can be * created. - * @see instance() + * @see @ref instance() */ explicit ResourceManager(); @@ -246,7 +246,7 @@ template class ResourceManager: private Implementation::Resource * @brief Destructor * * Sets global instance pointer to `nullptr`. - * @see instance() + * @see @ref instance() */ ~ResourceManager(); @@ -274,7 +274,7 @@ template class ResourceManager: private Implementation::Resource /** * @brief Reference count of given resource * - * @see set() + * @see @ref set() */ template std::size_t referenceCount(ResourceKey key) const { return this->Implementation::ResourceManagerData::referenceCount(key); @@ -283,7 +283,7 @@ template class ResourceManager: private Implementation::Resource /** * @brief %Resource state * - * @see set(), Resource::state() + * @see @ref set(), @ref Resource::state() */ template ResourceState state(ResourceKey key) const { return this->Implementation::ResourceManagerData::state(key); @@ -293,20 +293,20 @@ template class ResourceManager: private Implementation::Resource * @brief Set resource data * @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 - * the data will be deleted immediately and no resource will be - * added. To avoid spending unnecessary loading time, add - * reference-counted resources only if they are already referenced: + * the data will be deleted immediately and no resource will be added. + * To avoid spending unnecessary loading time, add reference-counted + * resources only if they are already referenced: * @code * if(manager.referenceCount("myresource")) { * // load data... * manager.set("myresource", data, state, ResourcePolicy::ReferenceCounted); * } * @endcode - * @attention If resource state is already `ResourceState::Final`, - * subsequent updates are not possible. - * @see referenceCount(), state() + * @attention Subsequent updates are not possible if resource state is + * already @ref ResourceState::Final. + * @see @ref referenceCount(), @ref state() */ template ResourceManager& set(ResourceKey key, T* data, ResourceDataState state, ResourcePolicy policy) { this->Implementation::ResourceManagerData::set(key, data, state, policy); @@ -380,7 +380,8 @@ template class ResourceManager: private Implementation::Resource * @brief Clear all resources of given type * @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 ResourceManager& clear() { this->Implementation::ResourceManagerData::clear(); @@ -391,7 +392,8 @@ template class ResourceManager: private Implementation::Resource * @brief Clear all resources * @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& clear() { clearInternal(); @@ -413,7 +415,7 @@ template class ResourceManager: private Implementation::Resource * @param loader Loader or `nullptr` if unsetting previous loader. * @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 * all resources. */