From 3868dba6ae372ed13f88915c9168488a0fbe1373 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Sun, 7 Oct 2012 14:28:28 +0200 Subject: [PATCH] Buffer documentation update. * Documented setData()/setSubData() overloads. * Alphabetically reordered Target * Linking related functions from enums --- src/Buffer.h | 90 +++++++++++++++++++++++++++++++++++----------------- 1 file changed, 61 insertions(+), 29 deletions(-) diff --git a/src/Buffer.h b/src/Buffer.h index c2403ec75..38ef73d5c 100644 --- a/src/Buffer.h +++ b/src/Buffer.h @@ -28,7 +28,33 @@ namespace Magnum { /** -@brief Class for managing buffers +@brief %Buffer + +Encapsulates one OpenGL buffer object and provides functions for convenient +data updates. + +@section Buffer-data Data updating +Default way to set or update buffer data with setData() or setSubData() is to +explicitly specify data size and pass the pointer to it: +@code +Vector3* data = new Vector3[200]; +buffer.setData(200*sizeof(Vector3), data, Buffer::Usage::StaticDraw); +@endcode +Howewer, in some cases, you have the data in fixed-size array with size known +at compile time. There is an convenient overload which detects the size of +passed array, so you don't have to repeat it: +@code +Vector3 data[] = { + // ... +}; +buffer.setData(data, Buffer::Usage::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); +@endcode @todo Support for buffer copying (OpenGL 3.1, @extension{ARB,copy_buffer}) @todo Support for AMD's query buffer (@extension{AMD,query_buffer_object}) @@ -40,7 +66,13 @@ class Buffer { Buffer& operator=(Buffer&& other) = delete; public: - /** @brief %Buffer target */ + /** + * @brief %Buffer target + * + * @see bind(Target), unbind(Target), + * setData(Target, GLsizeiptr, const GLvoid*, Usage), + * setSubData(Target, GLintptr, GLsizeiptr, const GLvoid*) + */ enum class Target: GLenum { /** Used for storing vertex attributes. */ Array = GL_ARRAY_BUFFER, @@ -59,26 +91,33 @@ class Buffer { */ CopyWrite = GL_COPY_WRITE_BUFFER, + #ifndef MAGNUM_TARGET_GLES + /** + * Used for supplying arguments for instanced drawing. + * @requires_gl + * @requires_gl40 Extension @extension{ARB,draw_indirect} + */ + DrawIndirect = GL_DRAW_INDIRECT_BUFFER, + #endif + /** Used for storing vertex indices. */ ElementArray = GL_ELEMENT_ARRAY_BUFFER, /** - * Source for texture update operations. + * Target for pixel pack operations. * @requires_gles30 (no extension providing this functionality) */ - PixelUnpack = GL_PIXEL_UNPACK_BUFFER, + PixelPack = GL_PIXEL_PACK_BUFFER, /** - * Target for pixel pack operations. + * Source for texture update operations. * @requires_gles30 (no extension providing this functionality) */ - PixelPack = GL_PIXEL_PACK_BUFFER, + PixelUnpack = GL_PIXEL_UNPACK_BUFFER, #ifndef MAGNUM_TARGET_GLES /** - * Source for texel fetches. - * - * @see BufferedTexture + * Source for texel fetches. See BufferedTexture. * @requires_gl * @requires_gl31 Extension @extension{ARB,texture_buffer_object} */ @@ -98,20 +137,13 @@ class Buffer { * @requires_gles30 (no extension providing this functionality) */ Uniform = GL_UNIFORM_BUFFER - - #ifndef MAGNUM_TARGET_GLES - , - - /** - * Used for supplying arguments for instanced drawing. - * @requires_gl - * @requires_gl40 Extension @extension{ARB,draw_indirect} - */ - DrawIndirect = GL_DRAW_INDIRECT_BUFFER - #endif }; - /** @brief %Buffer usage */ + /** + * @brief %Buffer usage + * + * @see setData(Target, GLsizeiptr, const GLvoid*, Usage) + */ enum class Usage: GLenum { /** * Set once by the application and used infrequently for drawing. @@ -174,7 +206,7 @@ class Buffer { /** * @brief Unbind any buffer from given target - * @param target %Target + * @param target %Target * * @see @fn_gl{BindBuffer} */ @@ -220,7 +252,7 @@ class Buffer { /** * @brief Bind buffer - * @param target %Target + * @param target %Target * * @see @fn_gl{BindBuffer} */ @@ -320,7 +352,7 @@ class Buffer { /** * @brief Set buffer subdata - * @param offset Offset + * @param offset Offset in the buffer * @param size Data size * @param data Pointer to data * @@ -333,7 +365,7 @@ class Buffer { /** * @brief Set buffer subdata - * @param offset Offset + * @param offset Offset in the buffer * @param data Fixed-size array with data * * Sets buffer subdata with default target. More convenient for @@ -347,7 +379,7 @@ class Buffer { /** * @brief Set buffer subdata - * @param offset Offset + * @param offset Offset in the buffer * @param data Vector with data * * Sets buffer subdata with default target. @@ -365,7 +397,7 @@ class Buffer { /** * @brief Set buffer subdata * @param target %Target - * @param offset Offset + * @param offset Offset in the buffer * @param size Data size * @param data Pointer to data * @@ -379,7 +411,7 @@ class Buffer { /** * @brief Set buffer subdata * @param target %Target - * @param offset Offset + * @param offset Offset in the buffer * @param data Fixed-size array with data * * More convenient for setting data from fixed-size arrays than @@ -393,7 +425,7 @@ class Buffer { /** * @brief Set buffer subdata * @param target %Target - * @param offset Offset + * @param offset Offset in the buffer * @param data Vector with data * * @see setSubData(Target, GLintptr, GLsizeiptr, const GLvoid*)