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

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.
pull/34/head
Vladimír Vondruš 13 years ago
parent
ce9a9212ca
commit
794c934dc1
11 changed files with 256 additions and 272 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 32
      src/AbstractTexture.h
  2. 192
      src/Buffer.h
  3. 37
      src/BufferTexture.h
  4. 26
      src/CubeMapTexture.h
  5. 57
      src/CubeMapTextureArray.h
  6. 2
      src/Math/Geometry/Rectangle.h
  7. 73
      src/Mesh.h
  8. 10
      src/MeshTools/CompressIndices.h
  9. 14
      src/MeshTools/Interleave.h
  10. 6
      src/Text/Renderer.h
  11. 79
      src/Texture.h

32
src/AbstractTexture.h
Unescape View File

@ -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

192
src/Buffer.h
Unescape View File

@ -42,78 +42,72 @@
namespace Magnum {
/**
* @brief %Buffer usage
*
* @see @ref Buffer::setData(Containers::ArrayReference<const void>, BufferUsage)
*/
@brief %Buffer usage
@see @ref Buffer, @ref Buffer::setData(Containers::ArrayReference<const void>, 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<Vector3> 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<Vector3> 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<const void> 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<const void>, Usage) "setData(Containers::ArrayReference<const void>, Usage)"
* @deprecated Use @ref Magnum::Buffer::setData(Containers::ArrayReference<const void>, BufferUsage) "setData(Containers::ArrayReference<const void>, 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<class T> Buffer& setData(const std::vector<T>& 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<const void> 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<class T> Buffer& setSubData(GLintptr offset, const std::vector<T>& 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

37
src/BufferTexture.h
Unescape View File

@ -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}

26
src/CubeMapTexture.h
Unescape View File

@ -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<Sampler::Wrapping>& 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);

57
src/CubeMapTextureArray.h
Unescape View File

@ -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<Sampler::Wrapping>& 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);

2
src/Math/Geometry/Rectangle.h
Unescape View File

@ -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 T> class Rectangle: public Range2D<T> {
public:

73
src/Mesh.h
Unescape View File

@ -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

10
src/MeshTools/CompressIndices.h
Unescape View File

@ -25,7 +25,7 @@
*/
/** @file
* @brief Function Magnum::MeshTools::compressIndices()
* @brief Function @ref Magnum::MeshTools::compressIndices()
*/
#include <tuple>
@ -52,7 +52,7 @@ Containers::Array<char> data;
std::tie(indexCount, indexType, data) = MeshTools::compressIndices(indices);
@endcode
See also compressIndices(Mesh*, Buffer*, Buffer::Usage, const std::vector<UnsignedInt>&),
See also @ref compressIndices(Mesh&, Buffer&, BufferUsage, const std::vector<UnsignedInt>&),
which writes the compressed data directly into index buffer of given mesh.
*/
std::tuple<std::size_t, Mesh::IndexType, Containers::Array<char>> MAGNUM_MESHTOOLS_EXPORT compressIndices(const std::vector<UnsignedInt>& indices);
@ -64,12 +64,12 @@ std::tuple<std::size_t, Mesh::IndexType, Containers::Array<char>> MAGNUM_MESHTOO
@param usage Index buffer usage
@param indices Index array
The same as compressIndices(const std::vector<UnsignedInt>&), but this
The same as @ref compressIndices(const std::vector<UnsignedInt>&), 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<UnsignedInt>& indices);

14
src/MeshTools/Interleave.h
Unescape View File

@ -25,7 +25,7 @@
*/
/** @file
* @brief Function Magnum::MeshTools::interleave()
* @brief Function @ref Magnum::MeshTools::interleave()
*/
#include <cstring>
@ -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<class T, class ...U> inline typename std::enable_if<!std::is_same<T, Me
@param usage Vertex buffer usage
@param attributes Attribute arrays and gaps
The same as interleave(const T&, const U&...), but this function writes the
The same as @ref interleave(const T&, const U&...), but this function writes the
output to given array buffer and updates vertex count in the mesh accordingly,
so you don't have to call Mesh::setVertexCount() on your own.
so you don't have to call @ref Mesh::setVertexCount() on your own.
@attention Setting primitive type and binding the attributes to shader is left
to user - see @ref Mesh-configuration "Mesh documentation".
@ -196,11 +196,11 @@ so you don't have to call Mesh::setVertexCount() on your own.
For only one attribute array this function is convenient equivalent to the
following, without any performance loss:
@code
buffer->setData(attribute, usage);
mesh->setVertexCount(attribute.size());
buffer.setData(attribute, usage);
mesh.setVertexCount(attribute.size());
@endcode
@see MeshTools::compressIndices()
@see @ref MeshTools::compressIndices()
*/
template<class ...T> inline void interleave(Mesh& mesh, Buffer& buffer, BufferUsage usage, const T&... attributes) {
return Implementation::Interleave()(mesh, buffer, usage, attributes...);

6
src/Text/Renderer.h
Unescape View File

@ -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");

79
src/Texture.h
Unescape View File

@ -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<UnsignedInt dimensions> class Texture: public AbstractTexture {
@ -224,7 +224,7 @@ template<UnsignedInt dimensions> 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<Dimensions>::target()): AbstractTexture(GLenum(target)) {}
@ -281,13 +281,14 @@ template<UnsignedInt dimensions> 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<UnsignedInt dimensions> 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<UnsignedInt dimensions> 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<dimensions>& image, BufferUsage usage) {
@ -352,8 +354,8 @@ template<UnsignedInt dimensions> 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<UnsignedInt dimensions> 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<UnsignedInt dimensions> 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<Dimensions, Int>::VectorType& offset, const typename DimensionTraits<Dimensions, Int>::VectorType& size) {
DataHelper<dimensions>::invalidateSubImage(this, level, offset, size);

Write Preview
Loading…
Cancel
Save