From 794c934dc1b190f9a176e4886b4b18dd7145c6b4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Mon, 2 Dec 2013 01:18:15 +0100 Subject: [PATCH] Shotgun documentation updates. Fixed old references to Buffer::Usage, fixed parameter order in Image constructor, fixed some function references. Added explicit references to linkable stuff. --- src/AbstractTexture.h | 32 +++--- src/Buffer.h | 192 +++++++++++++++----------------- src/BufferTexture.h | 37 +++--- src/CubeMapTexture.h | 26 ++--- src/CubeMapTextureArray.h | 57 +++++----- src/Math/Geometry/Rectangle.h | 2 +- src/Mesh.h | 73 ++++++------ src/MeshTools/CompressIndices.h | 10 +- src/MeshTools/Interleave.h | 14 +-- src/Text/Renderer.h | 6 +- src/Texture.h | 79 ++++++------- 11 files changed, 256 insertions(+), 272 deletions(-) diff --git a/src/AbstractTexture.h b/src/AbstractTexture.h index 81121b703..406f4f674 100644 --- a/src/AbstractTexture.h +++ b/src/AbstractTexture.h @@ -25,7 +25,7 @@ */ /** @file - * @brief Class Magnum::AbstractTexture + * @brief Class @ref Magnum::AbstractTexture */ #include "Array.h" @@ -37,8 +37,9 @@ namespace Magnum { /** @brief Base for textures -See Texture, CubeMapTexture and CubeMapTextureArray documentation for more -information and usage examples. +Encapsulates one OpenGL texture object. See @ref Texture, @ref CubeMapTexture +and @ref CubeMapTextureArray documentation for more information and usage +examples. @section AbstractTexture-performance-optimization Performance optimizations and security @@ -49,15 +50,15 @@ affect active bindings in user layers. %Texture limits and implementation-defined values (such as @ref maxColorSamples()) are cached, so repeated queries don't result in repeated @fn_gl{Get} calls. -If extension @extension{EXT,direct_state_access} is available, bind() uses DSA -function to avoid unnecessary calls to @fn_gl{ActiveTexture}. Also all texture -configuration and data updating functions use DSA functions to avoid +If extension @extension{EXT,direct_state_access} is available, @ref bind() uses +DSA function to avoid unnecessary calls to @fn_gl{ActiveTexture}. Also all +texture configuration and data updating functions use DSA functions to avoid unnecessary calls to @fn_gl{ActiveTexture} and @fn_gl{BindTexture}. See respective function documentation for more information. If extension @extension{ARB,robustness} is available, image reading operations -(such as Texture::image()) are protected from buffer overflow. However, if both -@extension{EXT,direct_state_access} and @extension{ARB,robustness} are +(such as @ref Texture::image()) are protected from buffer overflow. However, if +both @extension{EXT,direct_state_access} and @extension{ARB,robustness} are available, the DSA version is used, because it is better for performance and there isn't any function combining both features. @@ -76,11 +77,12 @@ OpenGL ES 3.0 or @es_extension{EXT,texture_storage} in OpenGL ES 2.0 is not available, the feature is emulated with sequence of @ref Texture::setImage() "setImage()" calls. -You can use functions invalidateImage() and @ref Texture::invalidateSubImage() "invalidateSubImage()" -if you don't need texture data anymore to avoid unnecessary memory operations -performed by OpenGL in order to preserve the data. If running on OpenGL ES or -extension @extension{ARB,invalidate_subdata} is not available, these functions -do nothing. +You can use functions @ref invalidateImage() and +@ref Texture::invalidateSubImage() "invalidateSubImage()" if you don't need +texture data anymore to avoid unnecessary memory operations performed by OpenGL +in order to preserve the data. If running on OpenGL ES or extension +@extension{ARB,invalidate_subdata} is not available, these functions do +nothing. @todo all texture [level] parameters, global texture parameters @todo Add glPixelStore encapsulation @@ -182,8 +184,8 @@ class MAGNUM_EXPORT AbstractTexture { * @brief Set minification filter * @param filter Filter * @param mipmap Mipmap filtering. If set to anything else than - * BaseMipLevel, make sure textures for all mip levels are set or - * call generateMipmap(). + * @ref Sampler::Mipmap::Base, make sure textures for all mip + * levels are set or call @ref generateMipmap(). * @return Reference to self (for method chaining) * * Sets filter used when the object pixel size is smaller than the diff --git a/src/Buffer.h b/src/Buffer.h index 3dfb0d479..d65215739 100644 --- a/src/Buffer.h +++ b/src/Buffer.h @@ -42,78 +42,72 @@ namespace Magnum { /** - * @brief %Buffer usage - * - * @see @ref Buffer::setData(Containers::ArrayReference, BufferUsage) - */ +@brief %Buffer usage + +@see @ref Buffer, @ref Buffer::setData(Containers::ArrayReference, BufferUsage) +*/ enum class BufferUsage: GLenum { - /** - * Set once by the application and used infrequently for drawing. - */ + /** Set once by the application and used infrequently for drawing. */ StreamDraw = GL_STREAM_DRAW, #ifndef MAGNUM_TARGET_GLES2 /** - * Set once as output from an OpenGL command and used infequently - * for drawing. - * @requires_gles30 Only @ref Magnum::Buffer::Usage "Usage::StreamDraw" + * Set once as output from an OpenGL command and used infequently for + * drawing. + * @requires_gles30 Only @ref Magnum::BufferUsage::StreamDraw "BufferUsage::StreamDraw" * is available in OpenGL ES 2.0. */ StreamRead = GL_STREAM_READ, /** - * Set once as output from an OpenGL command and used infrequently - * for drawing or copying to other buffers. - * @requires_gles30 Only @ref Magnum::Buffer::Usage "Usage::StreamDraw" + * Set once as output from an OpenGL command and used infrequently for + * drawing or copying to other buffers. + * @requires_gles30 Only @ref Magnum::BufferUsage::StreamDraw "BufferUsage::StreamDraw" * is available in OpenGL ES 2.0. */ StreamCopy = GL_STREAM_COPY, #endif - /** - * Set once by the application and used frequently for drawing. - */ + /** Set once by the application and used frequently for drawing. */ StaticDraw = GL_STATIC_DRAW, #ifndef MAGNUM_TARGET_GLES2 /** - * Set once as output from an OpenGL command and queried many - * times by the application. - * @requires_gles30 Only @ref Magnum::Buffer::Usage "Usage::StaticDraw" + * Set once as output from an OpenGL command and queried many times by the + * application. + * @requires_gles30 Only @ref Magnum::BufferUsage::StaticDraw "BufferUsage::StaticDraw" * is available in OpenGL ES 2.0. */ StaticRead = GL_STATIC_READ, /** - * Set once as output from an OpenGL command and used frequently - * for drawing or copying to other buffers. - * @requires_gles30 Only @ref Magnum::Buffer::Usage "Usage::StaticDraw" + * Set once as output from an OpenGL command and used frequently for + * drawing or copying to other buffers. + * @requires_gles30 Only @ref Magnum::BufferUsage::StaticDraw "BufferUsage::StaticDraw" * is available in OpenGL ES 2.0. */ StaticCopy = GL_STATIC_COPY, #endif /** - * Updated frequently by the application and used frequently - * for drawing or copying to other images. + * Updated frequently by the application and used frequently for drawing or + * copying to other images. */ - DynamicDraw = GL_DYNAMIC_DRAW + DynamicDraw = GL_DYNAMIC_DRAW, #ifndef MAGNUM_TARGET_GLES2 - , - /** - * Updated frequently as output from OpenGL command and queried - * many times from the application. - * @requires_gles30 Only @ref Magnum::Buffer::Usage "Usage::DynamicDraw" + * Updated frequently as output from OpenGL command and queried many times + * from the application. + * @requires_gles30 Only @ref Magnum::BufferUsage::DynamicDraw "BufferUsage::DynamicDraw" * is available in OpenGL ES 2.0. */ DynamicRead = GL_DYNAMIC_READ, /** - * Updated frequently as output from OpenGL command and used - * frequently for drawing or copying to other images. - * @requires_gles30 Only @ref Magnum::Buffer::Usage "Usage::DynamicDraw" + * Updated frequently as output from OpenGL command and used frequently for + * drawing or copying to other images. + * @requires_gles30 Only @ref Magnum::BufferUsage::DynamicDraw "BufferUsage::DynamicDraw" * is available in OpenGL ES 2.0. */ DynamicCopy = GL_DYNAMIC_COPY @@ -128,18 +122,18 @@ data updates. @section Buffer-data Data updating -Default way to set or update buffer data with setData() or setSubData() is to -use @ref Corrade::Containers::ArrayReference. See its documentation for more -information about automatic conversions etc. +Default way to set or update buffer data with @ref setData() or @ref setSubData() +is to use @ref Corrade::Containers::ArrayReference. See its documentation for +more information about automatic conversions etc. @code Containers::ArrayReference data; -buffer.setData(data, Buffer::Usage::StaticDraw); +buffer.setData(data, BufferUsage::StaticDraw); @endcode There is also overload for array-like containers from STL, such as `std::vector` or `std::array`: @code std::vector data; -buffer.setData(data, Buffer::Usage::StaticDraw); +buffer.setData(data, BufferUsage::StaticDraw); @endcode @subsection Buffer-data-mapping Memory mapping @@ -147,7 +141,7 @@ buffer.setData(data, Buffer::Usage::StaticDraw); %Buffer data can be also updated asynchronously. First you need to allocate the buffer to desired size by passing `nullptr` to @ref setData(), e.g.: @code -buffer.setData({nullptr, 200*sizeof(Vector3)}, Buffer::Usage::StaticDraw); +buffer.setData({nullptr, 200*sizeof(Vector3)}, BufferUsage::StaticDraw); @endcode Then you can map the buffer to client memory and operate with the memory directly. After you are done with the operation, call @ref unmap() to unmap the @@ -174,20 +168,21 @@ CORRADE_INTERNAL_ASSERT_OUTPUT(buffer.unmap()); The engine tracks currently bound buffers to avoid unnecessary calls to @fn_gl{BindBuffer}. If the buffer is already bound to some target, functions -copy(), setData(), setSubData(), map(), flushMappedRange() and unmap() use -that target instead of binding the buffer to some specific target. You can -also use setTargetHint() to possibly reduce unnecessary rebinding. %Buffer -limits and implementation-defined values (such as @ref maxVertexAttributeBindings()) -are cached, so repeated queries don't result in repeated @fn_gl{Get} calls. +@ref copy(), @ref setData(), @ref setSubData(), @ref map(), @ref flushMappedRange() +and @ref unmap() use that target instead of binding the buffer to some specific +target. You can also use @ref setTargetHint() to possibly reduce unnecessary +rebinding. %Buffer limits and implementation-defined values (such as +@ref maxVertexAttributeBindings()) are cached, so repeated queries don't result +in repeated @fn_gl{Get} calls. If extension @extension{EXT,direct_state_access} is available, functions -copy(), setData(), setSubData(), map(), flushMappedRange() and unmap() use DSA -functions to avoid unnecessary calls to @fn_gl{BindBuffer}. See their -respective documentation for more information. +@ref copy(), @ref setData(), @ref setSubData(), @ref map(), @ref flushMappedRange() +and @ref unmap() use DSA functions to avoid unnecessary calls to +@fn_gl{BindBuffer}. See their respective documentation for more information. -You can use functions invalidateData() and invalidateSubData() if you don't -need buffer data anymore to avoid unnecessary memory operations performed by -OpenGL in order to preserve the data. If running on OpenGL ES or extension +You can use functions @ref invalidateData() and @ref invalidateSubData() if you +don't need buffer data anymore to avoid unnecessary memory operations performed +by OpenGL in order to preserve the data. If running on OpenGL ES or extension @extension{ARB,invalidate_subdata} is not available, these functions do nothing. @@ -201,7 +196,7 @@ class MAGNUM_EXPORT Buffer { /** * @brief %Buffer target * - * @see bind(Target), unbind(Target) + * @see @ref bind(Target), @ref unbind(Target) */ enum class Target: GLenum { /** Used for storing vertex attributes. */ @@ -218,7 +213,7 @@ class MAGNUM_EXPORT Buffer { #ifndef MAGNUM_TARGET_GLES2 /** - * Source for copies. See copy(). + * Source for copies. See @ref copy(). * @requires_gl31 %Extension @extension{ARB,copy_buffer} * @requires_gles30 Buffer copying is not available in OpenGL ES * 2.0. @@ -226,7 +221,7 @@ class MAGNUM_EXPORT Buffer { CopyRead = GL_COPY_READ_BUFFER, /** - * Target for copies. See copy(). + * Target for copies. See @ref copy(). * @requires_gl31 %Extension @extension{ARB,copy_buffer} * @requires_gles30 Buffer copying is not available in OpenGL ES * 2.0. @@ -319,7 +314,7 @@ class MAGNUM_EXPORT Buffer { * * @deprecated_gl Prefer to use @ref Magnum::Buffer::map(GLintptr, GLsizeiptr, MapFlags) "map(GLintptr, GLsizeiptr, MapFlags)" * instead, as it has more complete set of features. - * @see map(MapAccess), mapSub() + * @see @ref map(MapAccess), @ref mapSub() * @requires_es_extension %Extension @es_extension{OES,mapbuffer} or * @es_extension{CHROMIUM,map_sub} */ @@ -333,9 +328,7 @@ class MAGNUM_EXPORT Buffer { ReadOnly = GL_READ_ONLY, #endif - /** - * Map buffer for writing only. - */ + /** Map buffer for writing only. */ #ifdef MAGNUM_TARGET_GLES WriteOnly = GL_WRITE_ONLY_OES #else @@ -353,7 +346,7 @@ class MAGNUM_EXPORT Buffer { /** * @brief Memory mapping flag * - * @see MapFlags, map(GLintptr, GLsizeiptr, MapFlags) + * @see @ref MapFlags, @ref map(GLintptr, GLsizeiptr, MapFlags) * @requires_gl30 %Extension @extension{ARB,map_buffer_range} * @requires_gles30 %Extension @es_extension{EXT,map_buffer_range} */ @@ -373,9 +366,9 @@ class MAGNUM_EXPORT Buffer { #endif /** - * Previous contents of the entire buffer may be discarded. May - * not be used in combination with @ref MapFlag::Read. - * @see invalidateData() + * Previous contents of the entire buffer may be discarded. May not + * be used in combination with @ref MapFlag::Read. + * @see @ref invalidateData() */ #ifndef MAGNUM_TARGET_GLES2 InvalidateBuffer = GL_MAP_INVALIDATE_BUFFER_BIT, @@ -384,9 +377,9 @@ class MAGNUM_EXPORT Buffer { #endif /** - * Previous contents of mapped range may be discarded. May not - * be used in combination with @ref MapFlag::Read. - * @see invalidateSubData() + * Previous contents of mapped range may be discarded. May not be + * used in combination with @ref MapFlag::Read. + * @see @ref invalidateSubData() */ #ifndef MAGNUM_TARGET_GLES2 InvalidateRange = GL_MAP_INVALIDATE_RANGE_BIT, @@ -396,8 +389,8 @@ class MAGNUM_EXPORT Buffer { /** * Only one or more discrete subranges of the mapping will be - * modified. See flushMappedRange() for more information. May only - * be used in conjuction with @ref MapFlag::Write. + * modified. See @ref flushMappedRange() for more information. May + * only be used in conjuction with @ref MapFlag::Write. */ #ifndef MAGNUM_TARGET_GLES2 FlushExplicit = GL_MAP_FLUSH_EXPLICIT_BIT, @@ -419,7 +412,7 @@ class MAGNUM_EXPORT Buffer { /** * @brief Memory mapping flags * - * @see map(GLintptr, GLsizeiptr, MapFlags) + * @see @ref map(GLintptr, GLsizeiptr, MapFlags) * @requires_gl30 %Extension @extension{ARB,map_buffer_range} * @requires_gles30 %Extension @es_extension{EXT,map_buffer_range} */ @@ -511,7 +504,7 @@ class MAGNUM_EXPORT Buffer { * * If @extension{EXT,direct_state_access} is not available and the * buffers aren't already bound somewhere, they are bound to - * `Target::CopyRead` and `Target::CopyWrite` before the copy is + * @ref Target::CopyRead and @ref Target::CopyWrite before the copy is * performed. * @see @fn_gl{BindBuffer} and @fn_gl{CopyBufferSubData} or * @fn_gl_extension{NamedCopyBufferSubData,EXT,direct_state_access} @@ -525,10 +518,10 @@ class MAGNUM_EXPORT Buffer { /** * @brief Constructor - * @param targetHint Target hint, see setTargetHint() for more + * @param targetHint Target hint, see @ref setTargetHint() for more * information * - * Generates new OpenGL buffer. + * Creates new OpenGL buffer. * @see @fn_gl{GenBuffers} */ explicit Buffer(Target targetHint = Target::Array); @@ -565,11 +558,11 @@ class MAGNUM_EXPORT Buffer { * * If @extension{EXT,direct_state_access} is not available, the buffer * must be internally bound to some target before any operation. You - * can specify target which will always be used when binding the - * buffer internally, possibly saving some calls to @fn_gl{BindBuffer}. + * can specify target which will always be used when binding the buffer + * internally, possibly saving some calls to @fn_gl{BindBuffer}. * - * Default target hint is `Target::Array`. - * @see setData(), setSubData() + * Default target hint is @ref Target::Array. + * @see @ref setData(), @ref setSubData() * @todo Target::ElementArray cannot be used when no VAO is bound - * http://www.opengl.org/wiki/Vertex_Specification#Index_buffers * ... damned GL state @@ -610,7 +603,8 @@ class MAGNUM_EXPORT Buffer { * Returns data of whole buffer. If @extension{EXT,direct_state_access} * is not available and the buffer is not already bound somewhere, it * is bound to hinted target before the operation. - * @see size(), subData(), setData(), @fn_gl{BindBuffer} and @fn_gl{GetBufferParameter} or + * @see @ref size(), @ref subData(), @ref setData(), @fn_gl{BindBuffer} + * and @fn_gl{GetBufferParameter} or * @fn_gl_extension{GetNamedBufferParameter,EXT,direct_state_access} * with @def_gl{BUFFER_SIZE}, @fn_gl{GetBufferSubData} or * @fn_gl_extension{GetNamedBufferSubData,EXT,direct_state_access} @@ -627,8 +621,9 @@ class MAGNUM_EXPORT Buffer { * Returns data of given buffer portion. If @extension{EXT,direct_state_access} * is not available and the buffer is not already bound somewhere, it * is bound to hinted target before the operation. - * @see size(), data(), setSubData(), @fn_gl{BindBuffer} and @fn_gl{GetBufferSubData} - * or @fn_gl_extension{GetNamedBufferSubData,EXT,direct_state_access} + * @see @ref size(), @ref data(), @ref setSubData(), @fn_gl{BindBuffer} + * and @fn_gl{GetBufferSubData} or + * @fn_gl_extension{GetNamedBufferSubData,EXT,direct_state_access} * @requires_gl %Buffer data queries are not available in OpenGL ES. * Use @ref Magnum::Buffer::map() "map()" instead. */ @@ -644,8 +639,8 @@ class MAGNUM_EXPORT Buffer { * If @extension{EXT,direct_state_access} is not available and the * buffer is not already bound somewhere, it is bound to hinted target * before the operation. - * @see setTargetHint(), @fn_gl{BindBuffer} and @fn_gl{BufferData} or - * @fn_gl_extension{NamedBufferData,EXT,direct_state_access} + * @see @ref setTargetHint(), @fn_gl{BindBuffer} and @fn_gl{BufferData} + * or @fn_gl_extension{NamedBufferData,EXT,direct_state_access} */ Buffer& setData(Containers::ArrayReference data, BufferUsage usage) { (this->*dataImplementation)(data.size(), data, usage); @@ -655,22 +650,15 @@ class MAGNUM_EXPORT Buffer { #ifdef MAGNUM_BUILD_DEPRECATED /** * @brief Set buffer data - * @deprecated Use @ref Magnum::Buffer::setData(Containers::ArrayReference, Usage) "setData(Containers::ArrayReference, Usage)" + * @deprecated Use @ref Magnum::Buffer::setData(Containers::ArrayReference, BufferUsage) "setData(Containers::ArrayReference, BufferUsage)" * instead. */ - Buffer& setData(GLsizeiptr size, const GLvoid* data, Usage usage) { + Buffer& setData(GLsizeiptr size, const GLvoid* data, BufferUsage usage) { return setData({data, std::size_t(size)}, usage); } #endif - /** - * @brief Set buffer data - * @param data Vector with data - * @param usage %Buffer usage - * @return Reference to self (for method chaining) - * - * @see setData(GLsizeiptr, const GLvoid*, Usage) - */ + /** @overload */ template Buffer& setData(const std::vector& data, BufferUsage usage) { setData({data.data(), data.size()}, usage); return *this; @@ -691,7 +679,7 @@ class MAGNUM_EXPORT Buffer { * If @extension{EXT,direct_state_access} is not available and the * buffer is not already bound somewhere, it is bound to hinted target * before the operation. - * @see setTargetHint(), @fn_gl{BindBuffer} and @fn_gl{BufferSubData} + * @see @ref setTargetHint(), @fn_gl{BindBuffer} and @fn_gl{BufferSubData} * or @fn_gl_extension{NamedBufferSubData,EXT,direct_state_access} */ Buffer& setSubData(GLintptr offset, Containers::ArrayReference data) { @@ -710,14 +698,7 @@ class MAGNUM_EXPORT Buffer { } #endif - /** - * @brief Set buffer subdata - * @param offset Offset in the buffer - * @param data Vector with data - * @return Reference to self (for method chaining) - * - * @see setSubData(GLintptr, GLsizeiptr, const GLvoid*) - */ + /** @overload */ template Buffer& setSubData(GLintptr offset, const std::vector& data) { setSubData(offset, {data.data(), data.size()}); return *this; @@ -792,7 +773,8 @@ class MAGNUM_EXPORT Buffer { * target before the operation. * @deprecated_gl Prefer to use @ref Magnum::Buffer::map(GLintptr, GLsizeiptr, MapFlags) "map(GLintptr, GLsizeiptr, MapFlags)" * instead, as it has more complete set of features. - * @see unmapSub(), setTargetHint(), @fn_gl_extension{MapBufferSubData,CHROMIUM,map_sub} + * @see @ref unmapSub(), @ref setTargetHint(), + * @fn_gl_extension{MapBufferSubData,CHROMIUM,map_sub} * @requires_gles20 Not available in ES 3.0 or desktop OpenGL. Use * @ref Magnum::Buffer::map(GLintptr, GLsizeiptr, MapFlags) "map(GLintptr, GLsizeiptr, MapFlags)" * instead. @@ -805,8 +787,8 @@ class MAGNUM_EXPORT Buffer { * @brief Map buffer to client memory * @param offset Offset into the buffer * @param length Length of the mapped memory - * @param flags Flags. At least @ref MapFlag::Read or @ref MapFlag::Write - * must be specified. + * @param flags Flags. At least @ref MapFlag::Read or + * @ref MapFlag::Write must be specified. * @return Pointer to buffer data * * If @extension{EXT,direct_state_access} is not available and the @@ -829,13 +811,13 @@ class MAGNUM_EXPORT Buffer { * @return Reference to self (for method chaining) * * Flushes specified subsection of mapped range. Use only if you called - * map() with @ref MapFlag::FlushExplicit flag. See + * @ref map() with @ref MapFlag::FlushExplicit flag. See * @ref Buffer-data-mapping "class documentation" for usage example. * * If @extension{EXT,direct_state_access} is not available and the * buffer is not already bound somewhere, it is bound to hinted target * before the operation. - * @see setTargetHint(), @fn_gl{BindBuffer} and @fn_gl{FlushMappedBufferRange} + * @see @ref setTargetHint(), @fn_gl{BindBuffer} and @fn_gl{FlushMappedBufferRange} * or @fn_gl_extension{FlushMappedNamedBufferRange,EXT,direct_state_access} * @requires_gl30 %Extension @extension{ARB,map_buffer_range} * @requires_gles30 %Extension @es_extension{EXT,map_buffer_range} @@ -851,7 +833,7 @@ class MAGNUM_EXPORT Buffer { * the buffer was mapped (e.g. after screen was resized), `true` * otherwise. * - * Unmaps buffer previously mapped with map(), invalidating the + * Unmaps buffer previously mapped with @ref map(), invalidating the * pointer returned by these functions. If @extension{EXT,direct_state_access} * is not available and the buffer is not already bound somewhere, it * is bound to hinted target before the operation. @@ -867,7 +849,7 @@ class MAGNUM_EXPORT Buffer { /** * @brief Unmap portion of buffer * - * Unmaps portion of buffer previously mapped with mapSub(), + * Unmaps portion of buffer previously mapped with @ref mapSub(), * invalidating the pointer returned by the function. * @see @fn_gl_extension{UnmapBufferSubData,CHROMIUM,map_sub} * @requires_gles20 Not available in ES 3.0 or desktop OpenGL. Use diff --git a/src/BufferTexture.h b/src/BufferTexture.h index 4bb1dacdc..8d92854de 100644 --- a/src/BufferTexture.h +++ b/src/BufferTexture.h @@ -26,7 +26,7 @@ #ifndef MAGNUM_TARGET_GLES /** @file - * @brief Class Magnum::BufferTexture, enum Magnum::BufferTextureFormat + * @brief Class @ref Magnum::BufferTexture, enum @ref Magnum::BufferTextureFormat */ #endif @@ -38,7 +38,7 @@ namespace Magnum { /** @brief Internal buffer texture format -@see BufferTexture +@see @ref BufferTexture */ enum class BufferTextureFormat: GLenum { /** Red component, normalized unsigned byte. */ @@ -153,14 +153,14 @@ enum class BufferTextureFormat: GLenum { /** @brief %Buffer texture -This texture is, unlike classic textures such as Texture or CubeMapTexture, -used as simple data source, without any unnecessary interpolation and -wrapping methods. +This texture is, unlike classic textures such as @ref Texture or +@ref CubeMapTexture, used as simple data source, without any unnecessary +interpolation and wrapping methods. @section BufferTexture-usage Usage %Texture data are stored in buffer and after binding the buffer to the texture -using setBuffer(), you can fill the buffer at any time using data setting +using @ref setBuffer(), you can fill the buffer at any time using data setting functions in Buffer itself. Note that the buffer is not managed (e.g. deleted on destruction) by the @@ -177,23 +177,24 @@ texture.setBuffer(BufferTextureFormat::RGB32F, buffer); constexpr static Vector3 data[] = { // ... }; -buffer.setData(data, Buffer::Usage::StaticDraw); +buffer.setData(data, BufferUsage::StaticDraw); @endcode -The texture is bound to layer specified by shader via bind(). In shader, the -texture is used via `samplerBuffer`, `isamplerBuffer` or `usamplerBuffer`. +The texture is bound to layer specified by shader via @ref bind(). In shader, +the texture is used via `samplerBuffer`, `isamplerBuffer` or `usamplerBuffer`. Unlike in classic textures, coordinates for buffer textures are integer -coordinates passed to `texelFetch()`. See also AbstractShaderProgram +coordinates passed to `texelFetch()`. See also @ref AbstractShaderProgram documentation for more information. @section BufferTexture-performance-optimization Performance optimizations -If extension @extension{EXT,direct_state_access} is available, setBuffer() + +If extension @extension{EXT,direct_state_access} is available, @ref setBuffer() functions use DSA to avoid unnecessary calls to @fn_gl{ActiveTexture} and -@fn_gl{BindTexture}. See @ref AbstractTexture-performance-optimization -"relevant section in AbstractTexture documentation" and respective function -documentation for more information. +@fn_gl{BindTexture}. See +@ref AbstractTexture-performance-optimization "relevant section in AbstractTexture documentation" +and respective function documentation for more information. -@see Texture, CubeMapTexture, CubeMapTextureArray +@see @ref Texture, @ref CubeMapTexture, @ref CubeMapTextureArray @requires_gl31 %Extension @extension{ARB,texture_buffer_object} @requires_gl Texture buffers are not available in OpenGL ES. */ @@ -217,8 +218,8 @@ class MAGNUM_EXPORT BufferTexture: private AbstractTexture { * @param buffer %Buffer with data * * Binds given buffer to this texture. The buffer itself can be then - * filled with data of proper format at any time using Buffer own data - * setting functions. + * filled with data of proper format at any time using @ref Buffer "Buffer"'s + * own data setting functions. * @see @fn_gl{ActiveTexture}, @fn_gl{BindTexture} and @fn_gl{TexBuffer} * or @fn_gl_extension{TextureBuffer,EXT,direct_state_access} */ @@ -234,7 +235,7 @@ class MAGNUM_EXPORT BufferTexture: private AbstractTexture { * @param size Data size * * Binds range of given buffer to this texture. The buffer itself can - * be then filled with data of proper format at any time using Buffer + * be then filled with data of proper format at any time using @ref Buffer "Buffer"'s * own data setting functions. * @requires_gl43 %Extension @extension{ARB,texture_buffer_range} * @see @fn_gl{ActiveTexture}, @fn_gl{BindTexture} and @fn_gl{TexBufferRange} diff --git a/src/CubeMapTexture.h b/src/CubeMapTexture.h index 410b6125f..1183a5081 100644 --- a/src/CubeMapTexture.h +++ b/src/CubeMapTexture.h @@ -25,7 +25,7 @@ */ /** @file - * @brief Class Magnum::CubeMapTexture + * @brief Class @ref Magnum::CubeMapTexture */ #include "AbstractTexture.h" @@ -49,12 +49,12 @@ turned upside down (+Y is top): @section CubeMapTexture-usage Basic usage -See Texture documentation for introduction. +See @ref Texture documentation for introduction. Common usage is to fully configure all texture parameters and then set the data from e.g. set of Image objects: @code -Image2D positiveX({256, 256}, ColorFormat::RGBA, ColorType::UnsignedByte, dataPositiveX); +Image2D positiveX(ColorFormat::RGBA, ColorType::UnsignedByte, {256, 256}, data); // ... CubeMapTexture texture; @@ -66,11 +66,11 @@ texture.setMagnificationFilter(Sampler::Filter::Linear) // ... @endcode -The texture is bound to layer specified by shader via bind(). In shader, the -texture is used via `samplerCube`, `samplerCubeShadow`, `isamplerCube` or +The texture is bound to layer specified by shader via @ref bind(). In shader, +the texture is used via `samplerCube`, `samplerCubeShadow`, `isamplerCube` or `usamplerCube`. Unlike in classic textures, coordinates for cube map textures is signed three-part vector from the center of the cube, which intersects one -of the six sides of the cube map. See also AbstractShaderProgram for more +of the six sides of the cube map. See also @ref AbstractShaderProgram for more information about usage in shaders. @see @ref Renderer::Feature::SeamlessCubeMapTexture, @ref CubeMapTextureArray, @@ -99,7 +99,7 @@ class CubeMapTexture: public AbstractTexture { /** * @brief Set wrapping * - * See Texture::setWrapping() for more information. + * See @ref Texture::setWrapping() for more information. */ CubeMapTexture& setWrapping(const Array3D& wrapping) { DataHelper<3>::setWrapping(this, wrapping); @@ -112,7 +112,7 @@ class CubeMapTexture: public AbstractTexture { * @param coordinate Coordinate * @param level Mip level * - * See Texture::imageSize() for more information. + * See @ref Texture::imageSize() for more information. * @requires_gl %Texture image queries are not available in OpenGL ES. */ Vector2i imageSize(Coordinate coordinate, Int level) { @@ -123,7 +123,7 @@ class CubeMapTexture: public AbstractTexture { /** * @brief Set storage * - * See Texture::setStorage() for more information. + * See @ref Texture::setStorage() for more information. */ CubeMapTexture& setStorage(Int levels, TextureFormat internalFormat, const Vector2i& size) { DataHelper<2>::setStorage(this, _target, levels, internalFormat, size); @@ -137,7 +137,7 @@ class CubeMapTexture: public AbstractTexture { * @param level Mip level * @param image %Image where to put the data * - * See Texture::image(Int, Image&) for more information. + * See @ref Texture::image(Int, Image&) for more information. * @requires_gl %Texture image queries are not available in OpenGL ES. */ void image(Coordinate coordinate, Int level, Image2D& image) { @@ -151,7 +151,7 @@ class CubeMapTexture: public AbstractTexture { * @param image %Buffer image where to put the data * @param usage %Buffer usage * - * See Texture::image(Int, BufferImage&, Buffer::Usage) for more + * See @ref Texture::image(Int, BufferImage&, BufferUsage) for more * information. * @requires_gl %Texture image queries are not available in OpenGL ES. */ @@ -168,7 +168,7 @@ class CubeMapTexture: public AbstractTexture { * @param image %Image * @return Reference to self (for method chaining) * - * See Texture::setImage() for more information. + * See @ref Texture::setImage() for more information. */ CubeMapTexture& setImage(Coordinate coordinate, Int level, TextureFormat internalFormat, const ImageReference2D& image) { DataHelper<2>::setImage(this, GLenum(coordinate), level, internalFormat, image); @@ -191,7 +191,7 @@ class CubeMapTexture: public AbstractTexture { * @param image %Image * @return Reference to self (for method chaining) * - * See Texture::setSubImage() for more information. + * See @ref Texture::setSubImage() for more information. */ CubeMapTexture& setSubImage(Coordinate coordinate, Int level, const Vector2i& offset, const ImageReference2D& image) { DataHelper<2>::setSubImage(this, GLenum(coordinate), level, offset, image); diff --git a/src/CubeMapTextureArray.h b/src/CubeMapTextureArray.h index 99d72f2ae..c28489c90 100644 --- a/src/CubeMapTextureArray.h +++ b/src/CubeMapTextureArray.h @@ -26,7 +26,7 @@ #ifndef MAGNUM_TARGET_GLES /** @file - * @brief Class Magnum::CubeMapTextureArray + * @brief Class @ref Magnum::CubeMapTextureArray */ #endif @@ -38,26 +38,23 @@ namespace Magnum { /** @brief Cube map texture array -See CubeMapTexture documentation for introduction. +See @ref CubeMapTexture documentation for introduction. @section CubeMapTextureArray-usage Usage -Common usage is to specify each layer and face separately using setSubImage(). +Common usage is to specify each layer and face separately using @ref setSubImage(). You have to allocate the memory for all layers and faces first either by -calling setStorage() or by passing properly sized empty Image to setImage(). -Example: array with 16 layers of cube map faces, each face consisting of six -64x64 images: +calling @ref setStorage() or by passing properly sized empty image to +@ref setImage(). Example: array with 16 layers of cube map faces, each face +consisting of six 64x64 images: @code -Image3D dummy({64, 64, 16*6}, ColorFormat::RGBA, ColorType::UnsignedByte, nullptr); - CubeMapTextureArray texture; texture.setMagnificationFilter(Sampler::Filter::Linear) // ... .setStorage(Math::log2(64)+1, TextureFormat::RGBA8, {64, 64, 16}); for(std::size_t i = 0; i != 16; ++i) { - void* dataPositiveX = ...; - Image2D imagePositiveX({64, 64}, ColorFormat::RGBA, ColorType::UnsignedByte, imagePositiveX); + Image2D imagePositiveX(ColorFormat::RGBA, ColorType::UnsignedByte, {64, 64}, data); // ... texture.setSubImage(i, CubeMapTextureArray::Coordinate::PositiveX, 0, {}, imagePositiveX); texture.setSubImage(i, CubeMapTextureArray::Coordinate::NegativeX, 0, {}, imageNegativeX); @@ -67,13 +64,13 @@ for(std::size_t i = 0; i != 16; ++i) { // ... @endcode -The texture is bound to layer specified by shader via bind(). In shader, the -texture is used via `samplerCubeArray`, `samplerCubeArrayShadow`, +The texture is bound to layer specified by shader via @ref bind(). In shader, +the texture is used via `samplerCubeArray`, `samplerCubeArrayShadow`, `isamplerCubeArray` or `usamplerCubeArray`. Unlike in classic textures, coordinates for cube map texture arrays is signed four-part vector. First three parts define vector from the center of the cube which intersects with one of the six sides of the cube map, fourth part is layer in the array. See also -AbstractShaderProgram for more information about usage in shaders. +@ref AbstractShaderProgram for more information about usage in shaders. @see @ref Renderer::Feature::SeamlessCubeMapTexture, @ref CubeMapTexture, @ref Texture, @ref BufferTexture @@ -103,7 +100,7 @@ class CubeMapTextureArray: public AbstractTexture { /** * @brief Set wrapping * - * See Texture::setWrapping() for more information. + * See @ref Texture::setWrapping() for more information. */ CubeMapTextureArray& setWrapping(const Array3D& wrapping) { DataHelper<3>::setWrapping(this, wrapping); @@ -115,7 +112,7 @@ class CubeMapTextureArray: public AbstractTexture { * @param coordinate Coordinate * @param level Mip level * - * See Texture::imageSize() for more information. + * See @ref Texture::imageSize() for more information. */ Vector3i imageSize(Coordinate coordinate, Int level) { return DataHelper<3>::imageSize(this, GL_TEXTURE_CUBE_MAP_POSITIVE_X + GLenum(coordinate), level); @@ -124,7 +121,7 @@ class CubeMapTextureArray: public AbstractTexture { /** * @brief Set storage * - * See Texture::setStorage() for more information. + * See @ref Texture::setStorage() for more information. */ CubeMapTextureArray& setStorage(Int levels, TextureFormat internalFormat, const Vector3i& size) { DataHelper<3>::setStorage(this, _target, levels, internalFormat, size); @@ -138,7 +135,7 @@ class CubeMapTextureArray: public AbstractTexture { * @param level Mip level * @param image %Image where to put the data * - * See Texture::image(Int, Image&) for more information. + * See @ref Texture::image(Int, Image&) for more information. * @requires_gl %Texture image queries are not available in OpenGL ES. */ void image(Coordinate coordinate, Int level, Image3D& image) { @@ -152,11 +149,11 @@ class CubeMapTextureArray: public AbstractTexture { * @param image %Buffer image where to put the data * @param usage %Buffer usage * - * See Texture::image(Int, BufferImage&, Buffer::Usage) for more + * See @ref Texture::image(Int, BufferImage&, BufferUsage) for more * information. * @requires_gl %Texture image queries are not available in OpenGL ES. */ - void image(Coordinate coordinate, Int level, BufferImage3D& image, Buffer::Usage usage) { + void image(Coordinate coordinate, Int level, BufferImage3D& image, BufferUsage usage) { AbstractTexture::image<3>(GL_TEXTURE_CUBE_MAP_POSITIVE_X + GLenum(coordinate), level, image, usage); } #endif @@ -165,15 +162,15 @@ class CubeMapTextureArray: public AbstractTexture { * @brief Set image data * @param level Mip level * @param internalFormat Internal format - * @param image Image, ImageReference, BufferImage or - * Trade::ImageData of the same dimension count + * @param image @ref Image, @ref ImageReference, @ref BufferImage + * or @ref Trade::ImageData of the same dimension count * @return Reference to self (for method chaining) * * Sets texture image data from three-dimensional image for all cube * faces for all layers. Each group of 6 2D images is one cube map * layer. The images are ordered the same way as Coordinate enum. * - * See Texture::setImage() for more information. + * See @ref Texture::setImage() for more information. */ CubeMapTextureArray& setImage(Int level, TextureFormat internalFormat, const ImageReference3D& image) { DataHelper<3>::setImage(this, GL_TEXTURE_CUBE_MAP_ARRAY, level, internalFormat, image); @@ -190,8 +187,8 @@ class CubeMapTextureArray: public AbstractTexture { * @brief Set texture image 3D subdata * @param level Mip level * @param offset Offset where to put data in the texture - * @param image Image3D, ImageReference3D, BufferImage3D or - * Trade::ImageData3D + * @param image @ref Image3D, @ref ImageReference3D, @ref BufferImage3D + * or @ref Trade::ImageData3D * @return Reference to self (for method chaining) * * Sets texture image subdata for more than one level/face at once. @@ -199,11 +196,9 @@ class CubeMapTextureArray: public AbstractTexture { * Z coordinate of @p offset specifies layer and cube map face. If * you want to start at given face in layer *n*, you have to specify * Z coordinate as @f$ 6n + i @f$, where i is face index as specified - * in Coordinate enum. - * - * See Texture::setSubImage() for more information. + * in @ref Coordinate enum. * - * @see setSubImage(Int, Coordinate, Int, const Math::Vector<2, Int>&, const Image*) + * See @ref Texture::setSubImage() for more information. */ CubeMapTextureArray& setSubImage(Int level, const Vector3i& offset, const ImageReference3D& image) { DataHelper<3>::setSubImage(this, GL_TEXTURE_CUBE_MAP_ARRAY, level, offset, image); @@ -223,10 +218,10 @@ class CubeMapTextureArray: public AbstractTexture { * @param size Size of invalidated data * * Z coordinate is equivalent to layer * 6 + number of texture face, - * i.e. @ref Coordinate "Coordinate::PositiveX" is `0` and so on, in - * the same order as in the enum. + * i.e. @ref Coordinate::PositiveX is `0` and so on, in the same order + * as in the enum. * - * See Texture::invalidateSubImage() for more information. + * See @ref Texture::invalidateSubImage() for more information. */ void invalidateSubImage(Int level, const Vector3i& offset, const Vector3i& size) { DataHelper<3>::invalidateSubImage(this, level, offset, size); diff --git a/src/Math/Geometry/Rectangle.h b/src/Math/Geometry/Rectangle.h index 56d679a46..bd2153a41 100644 --- a/src/Math/Geometry/Rectangle.h +++ b/src/Math/Geometry/Rectangle.h @@ -36,7 +36,7 @@ namespace Magnum { namespace Math { namespace Geometry { /** @copybrief Math::Range2D -@deprecated Use @ref Math::Range2D instead. +@deprecated Use @ref Magnum::Math::Range2D instead. */ template class Rectangle: public Range2D { public: diff --git a/src/Mesh.h b/src/Mesh.h index 6888d8ced..8af843eec 100644 --- a/src/Mesh.h +++ b/src/Mesh.h @@ -83,7 +83,7 @@ Mesh mesh; static constexpr Vector3 positions[30] = { // ... }; -vertexBuffer.setData(positions, Buffer::Usage::StaticDraw); +vertexBuffer.setData(positions, BufferUsage::StaticDraw); // Set primitive and vertex count, add the buffer and specify its layout mesh.setPrimitive(Mesh::Primitive::Triangles) @@ -100,7 +100,7 @@ Buffer vertexBuffer; Mesh mesh; // Fill vertex buffer with interleaved position and normal data -MeshTools::interleave(mesh, buffer, Buffer::Usage::StaticDraw, +MeshTools::interleave(mesh, buffer, BufferUsage::StaticDraw, plane.positions(0), plane.normals(0)); // Set primitive and specify layout of interleaved vertex buffer, vertex count @@ -126,13 +126,13 @@ Mesh mesh; static constexpr Vector3 positions[300] = { // ... }; -vertexBuffer.setData(positions, Buffer::Usage::StaticDraw); +vertexBuffer.setData(positions, BufferUsage::StaticDraw); // Fill index buffer with index data static constexpr GLubyte indices[75] = { // ... }; -indexBuffer.setData(indices, Buffer::Usage::StaticDraw); +indexBuffer.setData(indices, BufferUsage::StaticDraw); // Set primitive, index count, specify the buffers mesh.setPrimitive(Mesh::Primitive::Triangles) @@ -148,11 +148,11 @@ Buffer vertexBuffer, indexBuffer; Mesh mesh; // Fill vertex buffer with interleaved position and normal data -MeshTools::interleave(mesh, vertexBuffer, Buffer::Usage::StaticDraw, +MeshTools::interleave(mesh, vertexBuffer, BufferUsage::StaticDraw, cube.positions(0), cube.normals(0)); // Fill index buffer with compressed index data -MeshTools::compressIndices(mesh, indexBuffer, Buffer::Usage::StaticDraw, +MeshTools::compressIndices(mesh, indexBuffer, BufferUsage::StaticDraw, cube.indices()); // Set primitive and specify layout of interleaved vertex buffer. Index count @@ -192,7 +192,7 @@ Buffer colorBuffer; GLubyte colors[4*30] = { // ... }; -colorBuffer.setData(colors, Buffer::Usage::StaticDraw); +colorBuffer.setData(colors, BufferUsage::StaticDraw); // Specify layout of color buffer -- BGRA, each component unsigned byte and we // want to normalize them from [0, 255] to [0.0f, 1.0f] @@ -241,7 +241,7 @@ class MAGNUM_EXPORT Mesh { /** * @brief Primitive type * - * @see primitive(), setPrimitive() + * @see @ref primitive(), @ref setPrimitive() */ enum class Primitive: GLenum { /** Single points. */ @@ -315,7 +315,7 @@ class MAGNUM_EXPORT Mesh { /** * @brief Index type * - * @see setIndexBuffer(), indexSize() + * @see @ref setIndexBuffer(), @ref indexSize() */ enum class IndexType: GLenum { UnsignedByte = GL_UNSIGNED_BYTE, /**< Unsigned byte */ @@ -365,7 +365,7 @@ class MAGNUM_EXPORT Mesh { /** * @brief Size of given index type * - * @see indexSize() const + * @see @ref indexSize() const */ static std::size_t indexSize(IndexType type); @@ -374,8 +374,8 @@ class MAGNUM_EXPORT Mesh { * @param primitive Primitive type * * Creates mesh with no vertex buffers and zero vertex count. - * @see setPrimitive(), setVertexCount(), @fn_gl{GenVertexArrays} (if - * @extension{APPLE,vertex_array_object} is available) + * @see @ref setPrimitive(), @ref setVertexCount(), @fn_gl{GenVertexArrays} + * (if @extension{APPLE,vertex_array_object} is available) */ explicit Mesh(Primitive primitive = Primitive::Triangles); @@ -402,7 +402,7 @@ class MAGNUM_EXPORT Mesh { /** * @brief Index size * - * @see indexSize(IndexType) + * @see @ref indexSize(IndexType) */ std::size_t indexSize() const { return indexSize(_indexType); } @@ -429,7 +429,8 @@ class MAGNUM_EXPORT Mesh { * @return Reference to self (for method chaining) * * Default is zero. - * @see setPrimitive(), addVertexBuffer(), MeshTools::interleave() + * @see @ref setPrimitive(), @ref addVertexBuffer(), + * @ref MeshTools::interleave() */ Mesh& setVertexCount(Int vertexCount) { _vertexCount = vertexCount; @@ -444,7 +445,7 @@ class MAGNUM_EXPORT Mesh { * @return Reference to self (for method chaining) * * Default is zero. - * @see setIndexBuffer(), MeshTools::compressIndices() + * @see @ref setIndexBuffer(), @ref MeshTools::compressIndices() */ Mesh& setIndexCount(Int count) { _indexCount = count; @@ -469,34 +470,34 @@ class MAGNUM_EXPORT Mesh { * position and normal, so you have to skip weight and texture * coordinate in each vertex: * @code - Buffer buffer; - Mesh mesh; - mesh.addVertexBuffer(buffer, 76, // initial array offset - 4, // skip vertex weight (Float) - Shaders::Phong::Position(), // vertex position - 8, // skip texture coordinates (Vector2) - Shaders::Phong::Normal()); // vertex normal - @endcode + * Buffer buffer; + * Mesh mesh; + * mesh.addVertexBuffer(buffer, 76, // initial array offset + * 4, // skip vertex weight (Float) + * Shaders::Phong::Position(), // vertex position + * 8, // skip texture coordinates (Vector2) + * Shaders::Phong::Normal()); // vertex normal + * @endcode * * You can also achieve the same effect by calling @ref addVertexBuffer() * more times with explicitly specified gaps before and after the * attributes. This can be used for e.g. runtime-dependent * configuration, as it isn't dependent on the variadic template: - @code - mesh.addVertexBuffer(buffer, 76, 4, Shaders::Phong::Position(), 20) - .addVertexBuffer(buffer, 76, 24, Shaders::Phong::Normal(), 0); - @endcode + * @code + * mesh.addVertexBuffer(buffer, 76, 4, Shaders::Phong::Position(), 20) + * .addVertexBuffer(buffer, 76, 24, Shaders::Phong::Normal(), 0); + * @endcode * * If specifying more than one attribute, the function assumes that * the array is interleaved. Adding non-interleaved vertex buffer can * be done by specifying one attribute at a time with specific offset. * Above example with weight, position, texture coordinate and normal * arrays one after another (non-interleaved): - @code - Int vertexCount = 352; - mesh.addVertexBuffer(buffer, 76 + 4*vertexCount, Shaders::Phong::Position()) - .addVertexBuffer(buffer, 76 + 24*vertexCount, Shaders::Phong::Normal()); - @endcode + * @code + * Int vertexCount = 352; + * mesh.addVertexBuffer(buffer, 76 + 4*vertexCount, Shaders::Phong::Position()) + * .addVertexBuffer(buffer, 76 + 24*vertexCount, Shaders::Phong::Normal()); + * @endcode * * @attention The buffer passed as parameter is not managed by the * mesh, you must ensure it will exist for whole lifetime of the @@ -528,10 +529,10 @@ class MAGNUM_EXPORT Mesh { * The smaller range is specified with @p start and @p end the less * memory operations are needed (and possibly some optimizations), * improving draw performance. Specifying `0` for both parameters - * behaves the same as setIndexBuffer(Buffer*, GLintptr, IndexType). + * behaves the same as @ref setIndexBuffer(Buffer&, GLintptr, IndexType). * On OpenGL ES 2.0 this function behaves always as - * setIndexBuffer(Buffer*, GLintptr, IndexType), as this functionality - * is not available there. + * @ref setIndexBuffer(Buffer&, GLintptr, IndexType), as this + * functionality is not available there. * @see @ref maxElementsIndices(), @ref maxElementsVertices(), * @ref setIndexCount(), @ref MeshTools::compressIndices(), * @fn_gl{BindVertexArray}, @fn_gl{BindBuffer} (if @@ -546,7 +547,7 @@ class MAGNUM_EXPORT Mesh { * @param type Index data type * @return Reference to self (for method chaining) * - * Prefer to use setIndexBuffer(Buffer*, GLintptr, IndexType, UnsignedInt, UnsignedInt) + * Prefer to use @ref setIndexBuffer(Buffer&, GLintptr, IndexType, UnsignedInt, UnsignedInt) * for better performance. * @see setIndexCount(), MeshTools::compressIndices(), * @fn_gl{BindVertexArray}, @fn_gl{BindBuffer} (if diff --git a/src/MeshTools/CompressIndices.h b/src/MeshTools/CompressIndices.h index 781b9d295..43ef9ae2e 100644 --- a/src/MeshTools/CompressIndices.h +++ b/src/MeshTools/CompressIndices.h @@ -25,7 +25,7 @@ */ /** @file - * @brief Function Magnum::MeshTools::compressIndices() + * @brief Function @ref Magnum::MeshTools::compressIndices() */ #include @@ -52,7 +52,7 @@ Containers::Array data; std::tie(indexCount, indexType, data) = MeshTools::compressIndices(indices); @endcode -See also compressIndices(Mesh*, Buffer*, Buffer::Usage, const std::vector&), +See also @ref compressIndices(Mesh&, Buffer&, BufferUsage, const std::vector&), which writes the compressed data directly into index buffer of given mesh. */ std::tuple> MAGNUM_MESHTOOLS_EXPORT compressIndices(const std::vector& indices); @@ -64,12 +64,12 @@ std::tuple> MAGNUM_MESHTOO @param usage Index buffer usage @param indices Index array -The same as compressIndices(const std::vector&), but this +The same as @ref compressIndices(const std::vector&), but this function writes the output to given buffer, updates index count and specifies index buffer with proper index range in the mesh, so you don't have to call -Mesh::setIndexCount() and Mesh::setIndexBuffer() on your own. +@ref Mesh::setIndexCount() and @ref Mesh::setIndexBuffer() on your own. -@see MeshTools::interleave() +@see @ref MeshTools::interleave() */ void MAGNUM_MESHTOOLS_EXPORT compressIndices(Mesh& mesh, Buffer& buffer, BufferUsage usage, const std::vector& indices); diff --git a/src/MeshTools/Interleave.h b/src/MeshTools/Interleave.h index 4e4dc804b..e5dae48cc 100644 --- a/src/MeshTools/Interleave.h +++ b/src/MeshTools/Interleave.h @@ -25,7 +25,7 @@ */ /** @file - * @brief Function Magnum::MeshTools::interleave() + * @brief Function @ref Magnum::MeshTools::interleave() */ #include @@ -171,7 +171,7 @@ possible performance loss. for) and function `size()` returning count of elements. In most cases it will be `std::vector` or `std::array`. -See also interleave(Mesh*, Buffer*, Buffer::Usage, const T&...), +See also @ref interleave(Mesh&, Buffer&, BufferUsage, const T&...), which writes the interleaved array directly into buffer of given mesh. */ /* enable_if to avoid clash with overloaded function below */ @@ -186,9 +186,9 @@ template inline typename std::enable_ifsetData(attribute, usage); -mesh->setVertexCount(attribute.size()); +buffer.setData(attribute, usage); +mesh.setVertexCount(attribute.size()); @endcode -@see MeshTools::compressIndices() +@see @ref MeshTools::compressIndices() */ template inline void interleave(Mesh& mesh, Buffer& buffer, BufferUsage usage, const T&... attributes) { return Implementation::Interleave()(mesh, buffer, usage, attributes...); diff --git a/src/Text/Renderer.h b/src/Text/Renderer.h index 235377b20..27da6a9c9 100644 --- a/src/Text/Renderer.h +++ b/src/Text/Renderer.h @@ -186,7 +186,7 @@ Mesh mesh; // Render the text Range2D rectangle; std::tie(mesh, rectangle) = Text::Renderer2D::render(*font, cache, 0.15f, - "Hello World!", vertexBuffer, indexBuffer, Buffer::Usage::StaticDraw); + "Hello World!", vertexBuffer, indexBuffer, BufferUsage::StaticDraw); // Draw white text centered on the screen shader.setTransformationProjectionMatrix(projection*Matrix3::translation(-rectangle.width()/2.0f)) @@ -196,7 +196,7 @@ glyphCache->texture()->bind(Shaders::VectorShader2D::FontTextureLayer); mesh.draw(); @endcode See @ref render(AbstractFont&, const GlyphCache&, Float, const std::string&, Alignment) and -@ref render(AbstractFont&, const GlyphCache&, Float, const std::string&, Buffer&, Buffer&, Buffer::Usage, Alignment) +@ref render(AbstractFont&, const GlyphCache&, Float, const std::string&, Buffer&, Buffer&, BufferUsage, Alignment) for more information. While this method is sufficient for one-shot rendering of static texts, for @@ -209,7 +209,7 @@ Shaders::VectorShader2D shader; // Initialize renderer and reserve memory for enough glyphs Text::Renderer2D renderer(*font, cache, 0.15f); -renderer.reserve(32, Buffer::Usage::DynamicDraw, Buffer::Usage::StaticDraw); +renderer.reserve(32, BufferUsage::DynamicDraw, BufferUsage::StaticDraw); // Update the text occasionally renderer.render("Hello World Countdown: 10"); diff --git a/src/Texture.h b/src/Texture.h index ed47fede3..6ed901b4d 100644 --- a/src/Texture.h +++ b/src/Texture.h @@ -25,7 +25,7 @@ */ /** @file - * @brief Class Magnum::Texture, typedef Magnum::Texture1D, Magnum::Texture2D, Magnum::Texture3D + * @brief Class @ref Magnum::Texture, typedef @ref Magnum::Texture1D, @ref Magnum::Texture2D, @ref Magnum::Texture3D */ #include "AbstractTexture.h" @@ -37,16 +37,15 @@ namespace Magnum { @brief %Texture Template class for one- to three-dimensional textures. See also -AbstractTexture documentation for more information. +@ref AbstractTexture documentation for more information. @section Texture-usage Usage Common usage is to fully configure all texture parameters and then set the -data from e.g. Image. Example configuration of high quality texture with +data from e.g. @ref Image. Example configuration of high quality texture with trilinear anisotropic filtering, i.e. the best you can ask for: @code -void* data; -Image2D image({4096, 4096}, ColorFormat::RGBA, ColorType::UnsignedByte, data); +Image2D image(ColorFormat::RGBA, ColorType::UnsignedByte, {4096, 4096}, data); Texture2D texture; texture.setMagnificationFilter(Sampler::Filter::Linear) @@ -54,22 +53,23 @@ texture.setMagnificationFilter(Sampler::Filter::Linear) .setWrapping(Sampler::Wrapping::ClampToEdge) .setMaxAnisotropy(Sampler::maxAnisotropy()) .setStorage(Math::log2(4096)+1, TextureFormat::RGBA8, {4096, 4096}) - .setSubImage(0, {}, &image) + .setSubImage(0, {}, image) .generateMipmap(); @endcode @attention Don't forget to fully configure the texture before use. Note that - default configuration (if setMinificationFilter() is not called with - another value) is to use mipmaps, so be sure to either call setMinificationFilter(), - explicitly specify all mip levels with setStorage() and setImage() or call - generateMipmap(). If using rectangle texture, you must also call - setWrapping(), because the initial value is not supported on rectangle - textures. See also setMagnificationFilter() and setBorderColor(). - -The texture is bound to layer specified by shader via bind(). In shader, the -texture is used via `sampler2D` and friends, see @ref Target enum documentation -for more information. See also AbstractShaderProgram documentation for more -information about usage in shaders. + default configuration (if @ref setMinificationFilter() is not called with + another value) is to use mipmaps, so be sure to either call @ref setMinificationFilter(), + explicitly specify all mip levels with @ref setStorage() and @ref setImage() + or call @ref generateMipmap(). If using rectangle texture, you must also + call @ref setWrapping(), because the initial value is not supported on + rectangle textures. See also @ref setMagnificationFilter() and + @ref setBorderColor(). + +The texture is bound to layer specified by shader via @ref bind(). In shader, +the texture is used via `sampler2D` and friends, see @ref Target enum +documentation for more information. See also AbstractShaderProgram +documentation for more information about usage in shaders. @section Texture-array Texture arrays @@ -77,10 +77,10 @@ You can create texture arrays by passing @ref Target::Texture1DArray "Texture2D::Target::Texture1DArray" or @ref Target::Texture2DArray "Texture3D::Target::Texture2DArray" to constructor. -It is possible to specify each layer separately using setSubImage(), but you -have to allocate the memory for all layers first either by calling setStorage() -or by passing properly sized empty Image to setImage(). Example: 2D texture -array with 16 layers of 64x64 images: +It is possible to specify each layer separately using @ref setSubImage(), but +you have to allocate the memory for all layers first either by calling +@ref setStorage() or by passing properly sized empty image to @ref setImage(). +Example: 2D texture array with 16 layers of 64x64 images: @code Texture3D texture(Texture3D::Target::Texture2DArray); texture.setMagnificationFilter(Sampler::Filter::Linear) @@ -88,8 +88,8 @@ texture.setMagnificationFilter(Sampler::Filter::Linear) .setStorage(levels, TextureFormat::RGBA8, {64, 64,16}); for(std::size_t i = 0; i != 16; ++i) { - void* data = ...; - Image2D image({64, 64}, ColorFormat::RGBA, ColorType::UnsignedByte, image); + // ... + Image2D image(ColorFormat::RGBA, ColorType::UnsignedByte, {64, 64}, data[i]); texture.setSubImage(0, Vector3i::zAxis(i), image); } @@ -97,8 +97,8 @@ for(std::size_t i = 0; i != 16; ++i) { @endcode Similar approach can be used for any other texture types (e.g. setting -Texture3D data using 2D layers, Texture2D data using one-dimensional chunks -etc.). +@ref Texture3D data using 2D layers, @ref Texture2D data using one-dimensional +chunks etc.). @requires_gl30 %Extension @extension{EXT,texture_array} for texture arrays. @requires_gles30 %Array textures are not available in OpenGL ES 2.0. @@ -130,8 +130,8 @@ documentation for more information. textures. @requires_gl Rectangle textures are not available in OpenGL ES. -@see Texture1D, Texture2D, Texture3D, CubeMapTexture, CubeMapTextureArray, - BufferTexture +@see @ref Texture1D, @ref Texture2D, @ref Texture3D, @ref CubeMapTexture, + @ref CubeMapTextureArray, @ref BufferTexture @todo @extension{AMD,sparse_texture} */ template class Texture: public AbstractTexture { @@ -224,7 +224,7 @@ template class Texture: public AbstractTexture { * is `Target::Texture1D`, `Target::Texture2D` or * `Target::Texture3D` based on dimension count. * - * Creates one OpenGL texture. + * Creates new OpenGL texture. * @see @fn_gl{GenTextures} */ explicit Texture(Target target = DataHelper::target()): AbstractTexture(GLenum(target)) {} @@ -281,13 +281,14 @@ template class Texture: public AbstractTexture { * Specifies entire structure of a texture at once, removing the need * for additional consistency checks and memory reallocations when * updating the data later. After calling this function the texture - * is immutable and calling setStorage() or setImage() is not allowed. + * is immutable and calling @ref setStorage() or @ref setImage() is not + * allowed. * * If @extension{EXT,direct_state_access} is not available, the * texture is bound to some layer before the operation. If * OpenGL 4.2, @extension{ARB,texture_storage}, OpenGL ES 3.0 or @es_extension{EXT,texture_storage} * in OpenGL ES 2.0 is not available, the feature is emulated with - * sequence of setImage() calls. + * sequence of @ref setImage() calls. * @see @fn_gl{ActiveTexture}, @fn_gl{BindTexture} and * @fn_gl{TexStorage1D}/@fn_gl{TexStorage2D}/@fn_gl{TexStorage3D} * or @fn_gl_extension{TextureStorage1D,EXT,direct_state_access}/ @@ -310,7 +311,8 @@ template class Texture: public AbstractTexture { * @param image %Image where to put the data * * %Image parameters like format and type of pixel data are taken from - * given image, image size is taken from the texture using imageSize(). + * given image, image size is taken from the texture using + * @ref imageSize(). * * If @extension{EXT,direct_state_access} is not available, the * texture is bound to some layer before the operation. If @@ -336,7 +338,7 @@ template class Texture: public AbstractTexture { * @param image %Buffer image where to put the data * @param usage %Buffer usage * - * See image(Int, Image&) for more information. + * See @ref image(Int, Image&) for more information. * @requires_gl %Texture image queries are not available in OpenGL ES. */ void image(Int level, BufferImage& image, BufferUsage usage) { @@ -352,8 +354,8 @@ template class Texture: public AbstractTexture { * @return Reference to self (for method chaining) * * For better performance when generating mipmaps using - * generateMipmap() or calling setImage() more than once use - * setStorage() and setSubImage() instead. + * @ref generateMipmap() or calling @ref setImage() more than once use + * @ref setStorage() and @ref setSubImage() instead. * * If @extension{EXT,direct_state_access} is not available, the * texture is bound to some layer before the operation. @@ -385,9 +387,10 @@ template class Texture: public AbstractTexture { * * If @extension{EXT,direct_state_access} is not available, the * texture is bound to some layer before the operation. - * @see setStorage(), setImage(), @fn_gl{ActiveTexture}, @fn_gl{BindTexture} - * and @fn_gl{TexSubImage1D}/@fn_gl{TexSubImage2D}/@fn_gl{TexSubImage3D} - * or @fn_gl_extension{TextureSubImage1D,EXT,direct_state_access}/ + * @see @ref setStorage(), @ref setImage(), @fn_gl{ActiveTexture}, + * @fn_gl{BindTexture} and @fn_gl{TexSubImage1D}/ + * @fn_gl{TexSubImage2D}/@fn_gl{TexSubImage3D} or + * @fn_gl_extension{TextureSubImage1D,EXT,direct_state_access}/ * @fn_gl_extension{TextureSubImage2D,EXT,direct_state_access}/ * @fn_gl_extension{TextureSubImage3D,EXT,direct_state_access} */ @@ -412,7 +415,7 @@ template class Texture: public AbstractTexture { * * If running on OpenGL ES or extension @extension{ARB,invalidate_subdata} * is not available, this function does nothing. - * @see invalidateImage(), @fn_gl{InvalidateTexSubImage} + * @see @ref invalidateImage(), @fn_gl{InvalidateTexSubImage} */ void invalidateSubImage(Int level, const typename DimensionTraits::VectorType& offset, const typename DimensionTraits::VectorType& size) { DataHelper::invalidateSubImage(this, level, offset, size);