From c3462ea2668a4f671d093c86b07f9db085adde02 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Fri, 30 Nov 2012 15:40:58 +0100 Subject: [PATCH] Doc++ --- doc/building.dox | 3 +- src/AbstractResourceLoader.h | 63 +++++++++++++++++++++++++++++++++--- src/Math/RectangularMatrix.h | 2 +- src/ResourceManager.h | 5 +-- src/Texture.h | 2 +- 5 files changed, 65 insertions(+), 10 deletions(-) diff --git a/doc/building.dox b/doc/building.dox index 8d122190c..9bf5dd1b1 100644 --- a/doc/building.dox +++ b/doc/building.dox @@ -161,7 +161,8 @@ Tested version is `pepper_22`. Make sure you have `toolchains` Git submodule updated, as @ref building-download "explained above". Don't forget to adapt `NACL_PREFIX variable in `generic/NaCl-glibc-x86-32.cmake` and `generic/NaCl-glibc-x86-64.cmake` -to path where your SDK is installed. Default is `/usr/nacl`. +to path where your SDK is installed. Default is `/usr/nacl`. You may need to +adapt also `NACL_TOOLCHAIN_PATH` so CMake is able to find the compiler. Then create build directories for x86-32 and x86-64 and run cmake and make in them. The toolchains needs access to its platform file, so be sure to properly diff --git a/src/AbstractResourceLoader.h b/src/AbstractResourceLoader.h index 096d3d1fc..553529bf1 100644 --- a/src/AbstractResourceLoader.h +++ b/src/AbstractResourceLoader.h @@ -30,7 +30,59 @@ namespace Magnum { /** @brief Base for resource loaders -Provides asynchronous resource loading for ResourceManager. +Provides (a)synchronous resource loading for 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 load() 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. + +Your load() implementation must call the base implementation at the beginning +so ResourceManager is informed about loading state. Then, 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. + +Example implementation for synchronous mesh loader: +@code +class MeshResourceLoader: public AbstractResourceLoader { + public: + void load(ResourceKey key) { + // Indicate that loading has begun + AbstractResourceLoader::load(key); + + // Load the mesh... + + // Not found + if(!found) { + setNotFound(key); + return; + } + + // Found, pass it to resource manager + set(key, mesh, state, policy); + } +}; +@endcode + +You can then add it to resource manager instance like this: +@code +MyResourceManager manager; +MeshResourceLoader loader; + +manager->setLoader(loader); +@endcode */ template class AbstractResourceLoader { friend class Implementation::ResourceManagerData; @@ -78,11 +130,12 @@ template class AbstractResourceLoader { * * If the resource isn't yet loaded or loading, state of the resource * is set to @ref Resource::ResourceState "ResourceState::Loading" and count of - * requested features is incremented. + * requested features is incremented. Depending on implementation the + * resource might be loaded synchronously or asynchronously. + * + * See class documentation for reimplementation guide. * - * The resource might be loaded asynchronously and added to - * ResourceManager when loading is done. - * @see ResourceManager::state(), requestedCount(), notFountCount(), + * @see ResourceManager::state(), requestedCount(), notFoundCount(), * loadedCount() */ virtual void load(ResourceKey key) = 0; diff --git a/src/Math/RectangularMatrix.h b/src/Math/RectangularMatrix.h index e01321277..42e43559c 100644 --- a/src/Math/RectangularMatrix.h +++ b/src/Math/RectangularMatrix.h @@ -128,7 +128,7 @@ template class RectangularMatrix { */ #ifndef DOXYGEN_GENERATING_OUTPUT template inline constexpr RectangularMatrix(T first, U... next): _data{first, next...} { - static_assert(sizeof...(next)+1 == cols*rows, "Improper number of arguments passed to Matrix constructor"); + static_assert(sizeof...(next)+1 == cols*rows, "Improper number of arguments passed to RectangularMatrix constructor"); } #else template inline constexpr RectangularMatrix(T first, U... next); diff --git a/src/ResourceManager.h b/src/ResourceManager.h index 9546e3dc5..19bb8f1aa 100644 --- a/src/ResourceManager.h +++ b/src/ResourceManager.h @@ -325,6 +325,8 @@ cube->draw(); @endcode - Destroying resource references and deleting manager instance when nothing references the resources anymore. + +@see AbstractResourceLoader */ /* Due to too much work involved with explicit template instantiation (all Resource combinations, all ResourceManagerData...), this class doesn't have @@ -460,8 +462,7 @@ template class ResourceManager: private Implementation::Resource /** * @brief Set loader for given type of resources * - * The loader will affect only loading of resources requested after - * that. + * See AbstractResourceLoader documentation for more information. */ template inline void setLoader(AbstractResourceLoader* loader) { return this->Implementation::ResourceManagerData::setLoader(loader); diff --git a/src/Texture.h b/src/Texture.h index 91cca9459..9ca9d60b7 100644 --- a/src/Texture.h +++ b/src/Texture.h @@ -34,7 +34,7 @@ In shader, the texture is used via `sampler1D`, `sampler2D` or `sampler3D` depending on dimension count. Note that you can have more than one texture bound to the shader - the only requirement is to have each texture in another layer. -@section RectangleTextures Rectangle textures +@section Texture-rectangle Rectangle textures If you want to use rectangle textures, set target in constructor to `Target::Rectangle` and in shader use `sampler2DRect`. Unlike `sampler2D`,