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

Updated documentation of framebuffer classes.

pull/51/head
Vladimír Vondruš 13 years ago
parent
5e5b5e9c4c
commit
f0a8d5d047
5 changed files with 84 additions and 80 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. 28
      src/AbstractFramebuffer.h
  2. 29
      src/DefaultFramebuffer.h
  3. 95
      src/Framebuffer.h
  4. 8
      src/Renderbuffer.h
  5. 4
      src/RenderbufferFormat.h

28
src/AbstractFramebuffer.h
Unescape View File

@ -25,7 +25,7 @@
*/
/** @file
* @brief Class Magnum::AbstractFramebuffer
* @brief Class @ref Magnum::AbstractFramebuffer, enum @ref Magnum::FramebufferClear, @ref Magnum::FramebufferBlit, @ref Magnum::FramebufferBlitFilter, @ref Magnum::FramebufferTarget, enum set @ref FramebufferClearMask
*/
#include <Containers/EnumSet.h>
@ -128,7 +128,7 @@ enum class FramebufferTarget: GLenum {
/**
@brief Base for default and named framebuffers
See DefaultFramebuffer and Framebuffer for more information.
See @ref DefaultFramebuffer and @ref Framebuffer for more information.
@section AbstractFramebuffer-performance-optimization Performance optimizations and security
@ -138,8 +138,8 @@ switching framebuffers. %Framebuffer limits and implementation-defined values
(such as @ref maxViewportSize()) are cached, so repeated queries don't result
in repeated @fn_gl{Get} calls.
If @extension{ARB,robustness} is available, read() operations are protected
from buffer overflow.
If @extension{ARB,robustness} is available, @ref read() operations are
protected from buffer overflow.
@todo @extension{ARB,viewport_array} (and `GL_MAX_VIEWPORTS`)
*/
class MAGNUM_EXPORT AbstractFramebuffer {
@ -229,9 +229,9 @@ class MAGNUM_EXPORT AbstractFramebuffer {
* @brief Bind framebuffer for rendering
*
* Binds the framebuffer and updates viewport to saved dimensions.
* @see setViewport(), DefaultFramebuffer::mapForRead(),
* Framebuffer::mapForRead(), DefaultFramebuffer::mapForDraw(),
* Framebuffer::mapForDraw(), @fn_gl{BindFramebuffer},
* @see @ref setViewport(), @ref DefaultFramebuffer::mapForRead(),
* @ref Framebuffer::mapForRead(), @ref DefaultFramebuffer::mapForDraw(),
* @ref Framebuffer::mapForDraw(), @fn_gl{BindFramebuffer},
* @fn_gl{Viewport}
* @todo Bind internally to ReadDraw if separate binding points are not
* supported
@ -245,7 +245,7 @@ class MAGNUM_EXPORT AbstractFramebuffer {
* @brief Set viewport
* @return Reference to self (for method chaining)
*
* Saves the viewport to be used at later time in bind(). If the
* Saves the viewport to be used at later time in @ref bind(). If the
* framebuffer is currently bound, updates the viewport to given
* rectangle.
* @see @ref maxViewportSize(), @fn_gl{Viewport}
@ -257,11 +257,11 @@ class MAGNUM_EXPORT AbstractFramebuffer {
* @param mask Which buffers to clear
*
* To improve performance you can also use
* DefaultFramebuffer::invalidate() / Framebuffer::invalidate() instead
* of clearing given buffer if you will not use it anymore or fully
* overwrite it later.
* @see Renderer::setClearColor(), Renderer::setClearDepth(),
* Renderer::setClearStencil(), @fn_gl{BindFramebuffer},
* @ref DefaultFramebuffer::invalidate() / @ref Framebuffer::invalidate()
* instead of clearing given buffer if you will not use it anymore or
* fully overwrite it later.
* @see @ref Renderer::setClearColor(), @ref Renderer::setClearDepth(),
* @ref Renderer::setClearStencil(), @fn_gl{BindFramebuffer},
* @fn_gl{Clear}
*/
void clear(FramebufferClearMask mask);
@ -290,7 +290,7 @@ class MAGNUM_EXPORT AbstractFramebuffer {
* @param image %Buffer image where to put the data
* @param usage %Buffer usage
*
* See read(const Vector2i&, const Vector2i&, Image2D*) for more
* See @ref read(const Vector2i&, const Vector2i&, Image2D*) for more
* information.
* @requires_gles30 Pixel buffer objects are not available in OpenGL ES 2.0.
*/

29
src/DefaultFramebuffer.h
Unescape View File

@ -25,7 +25,7 @@
*/
/** @file
* @brief Class Magnum::DefaultFramebuffer
* @brief Class @ref Magnum::DefaultFramebuffer
*/
#include "AbstractFramebuffer.h"
@ -36,8 +36,9 @@ namespace Magnum {
@brief Default framebuffer
Default framebuffer, i.e. the actual screen surface. It is automatically
created when Context is created and it is available through global variable
@ref defaultFramebuffer. It is by default mapped to whole screen surface.
created when @ref Context is created and it is available through global
variable @ref defaultFramebuffer. It is by default mapped to whole screen
surface.
@section DefaultFramebuffer-usage Usage
@ -72,7 +73,7 @@ multiple framebuffers.
See also @ref AbstractFramebuffer-performance-optimization "relevant section in AbstractFramebuffer".
If extension @extension{EXT,direct_state_access} is available, functions
mapForDraw() and mapForRead() use DSA to avoid unnecessary calls to
@ref mapForDraw() and @ref mapForRead() use DSA to avoid unnecessary calls to
@fn_gl{BindFramebuffer}. See their respective documentation for more
information.
*/
@ -83,7 +84,7 @@ class MAGNUM_EXPORT DefaultFramebuffer: public AbstractFramebuffer {
/**
* @brief Status
*
* @see checkStatus()
* @see @ref checkStatus()
* @requires_gl30 %Extension @extension{ARB,framebuffer_object}
*/
enum class Status: GLenum {
@ -105,7 +106,7 @@ class MAGNUM_EXPORT DefaultFramebuffer: public AbstractFramebuffer {
/**
* @brief Draw attachment
*
* @see mapForDraw()
* @see @ref mapForDraw()
* @requires_gles30 Draw attachments for default framebuffer are
* available only in OpenGL ES 3.0.
*/
@ -166,7 +167,7 @@ class MAGNUM_EXPORT DefaultFramebuffer: public AbstractFramebuffer {
/**
* @brief Read attachment
*
* @see mapForRead()
* @see @ref mapForRead()
* @requires_gles30 %Extension @es_extension2{NV,read_buffer,GL_NV_read_buffer}
*/
enum class ReadAttachment: GLenum {
@ -236,7 +237,7 @@ class MAGNUM_EXPORT DefaultFramebuffer: public AbstractFramebuffer {
/**
* @brief Invalidation attachment
*
* @see invalidate()
* @see @ref invalidate()
* @requires_gl43 %Extension @extension{ARB,invalidate_subdata}
* @requires_gles30 %Extension @es_extension{EXT,discard_framebuffer}
*/
@ -354,8 +355,8 @@ class MAGNUM_EXPORT DefaultFramebuffer: public AbstractFramebuffer {
* If @extension{EXT,direct_state_access} is not available and the
* framebuffer is not currently bound, it is bound before the
* operation.
* @see mapForRead(), @fn_gl{BindFramebuffer}, @fn_gl{DrawBuffer} or
* @fn_gl_extension{FramebufferDrawBuffer,EXT,direct_state_access},
* @see @ref mapForRead(), @fn_gl{BindFramebuffer}, @fn_gl{DrawBuffer}
* or @fn_gl_extension{FramebufferDrawBuffer,EXT,direct_state_access},
* @fn_gl{DrawBuffers} in OpenGL ES 3.0
* @requires_gles30 Draw attachments for default framebuffer are
* available only in OpenGL ES 3.0.
@ -392,9 +393,9 @@ class MAGNUM_EXPORT DefaultFramebuffer: public AbstractFramebuffer {
* @see @fn_gl{InvalidateFramebuffer} or @fn_gles_extension{DiscardFramebuffer,EXT,discard_framebuffer}
* on OpenGL ES 2.0
* @requires_gl43 %Extension @extension{ARB,invalidate_subdata}. Use
* clear() instead where the extension is not supported.
* @ref clear() instead where the extension is not supported.
* @requires_gles30 %Extension @es_extension{EXT,discard_framebuffer}.
* Use clear() instead where the extension is not supported.
* Use @ref clear() instead where the extension is not supported.
*/
void invalidate(std::initializer_list<InvalidationAttachment> attachments);
@ -408,9 +409,9 @@ class MAGNUM_EXPORT DefaultFramebuffer: public AbstractFramebuffer {
* @see @fn_gl{InvalidateSubFramebuffer} or @fn_gles_extension{DiscardSubFramebuffer,EXT,discard_framebuffer}
* on OpenGL ES 2.0
* @requires_gl43 %Extension @extension{ARB,invalidate_subdata}. Use
* clear() instead where the extension is not supported.
* @ref clear() instead where the extension is not supported.
* @requires_gles30 %Extension @es_extension{EXT,discard_framebuffer}.
* Use clear() instead where the extension is not supported.
* Use @ref clear() instead where the extension is not supported.
*/
void invalidate(std::initializer_list<InvalidationAttachment> attachments, const Range2Di& rectangle);

95
src/Framebuffer.h
Unescape View File

@ -25,7 +25,7 @@
*/
/** @file
* @brief Class Magnum::Framebuffer
* @brief Class @ref Magnum::Framebuffer
*/
#include "AbstractFramebuffer.h"
@ -40,9 +40,9 @@ namespace Magnum {
/**
@brief %Framebuffer
Unlike DefaultFramebuffer, which is used for on-screen rendering, this class
is used for off-screen rendering, usable either in windowless applications,
texture generation or for various post-processing effects.
Unlike @ref DefaultFramebuffer, which is used for on-screen rendering, this
class is used for off-screen rendering, usable either in windowless
applications, texture generation or for various post-processing effects.
@section Framebuffer-usage Example usage
@ -71,10 +71,9 @@ framebuffer.mapForDraw({{MyShader::ColorOutput, Framebuffer::ColorAttachment(0)}
{MyShader::NormalOutput, Framebuffer::ColorAttachment(1)}});
@endcode
The actual @ref Platform::GlutApplication::drawEvent() "drawEvent()" might
look like this. First you clear all buffers you need, perform drawing to
off-screen framebuffer, then bind the default and render the textures on
screen:
The actual @ref Platform::Sdl2Application::drawEvent() "drawEvent()" might look
like this. First you clear all buffers you need, perform drawing to off-screen
framebuffer, then bind the default and render the textures on screen:
@code
void drawEvent() {
defaultFramebuffer.clear(FramebufferClear::Color)
@ -93,10 +92,10 @@ void drawEvent() {
See also @ref AbstractFramebuffer-performance-optimization "relevant section in AbstractFramebuffer".
If extension @extension{EXT,direct_state_access} is available, functions
mapForDraw(), mapForRead(), attachRenderbuffer(), attachTexture1D(),
attachTexture2D(), attachCubeMapTexture() and attachTexture3D() use DSA
to avoid unnecessary calls to @fn_gl{BindFramebuffer}. See their respective
documentation for more information.
@ref mapForDraw(), @ref mapForRead(), @ref attachRenderbuffer(),
@ref attachTexture1D(), @ref attachTexture2D(), @ref attachCubeMapTexture() and
@ref attachTexture3D() use DSA to avoid unnecessary calls to @fn_gl{BindFramebuffer}.
See their respective documentation for more information.
@requires_gl30 %Extension @extension{ARB,framebuffer_object}
@todo `MAX_COLOR_ATTACHMENTS`
@ -108,8 +107,9 @@ class MAGNUM_EXPORT Framebuffer: public AbstractFramebuffer, public AbstractObje
/**
* @brief Color attachment
*
* @see Attachment, attachRenderbuffer(), attachTexture1D(),
* attachTexture2D(), attachCubeMapTexture(), attachTexture3D()
* @see @ref Attachment, @ref attachRenderbuffer(),
* @ref attachTexture1D(), @ref attachTexture2D(),
* @ref attachCubeMapTexture(), @ref attachTexture3D()
*/
class ColorAttachment {
friend class Framebuffer;
@ -117,7 +117,7 @@ class MAGNUM_EXPORT Framebuffer: public AbstractFramebuffer, public AbstractObje
public:
/**
* @brief Constructor
* @param id Color attachment id
* @param id Color attachment ID
*
* @requires_gles30 %Extension @es_extension{NV,fbo_color_attachments}
* is required for @p id greater than 0.
@ -135,7 +135,7 @@ class MAGNUM_EXPORT Framebuffer: public AbstractFramebuffer, public AbstractObje
/**
* @brief Draw attachment
*
* @see mapForDraw()
* @see @ref mapForDraw()
*/
class DrawAttachment {
public:
@ -158,8 +158,9 @@ class MAGNUM_EXPORT Framebuffer: public AbstractFramebuffer, public AbstractObje
/**
* @brief %Buffer attachment
*
* @see attachRenderbuffer(), attachTexture1D(), attachTexture2D(),
* attachCubeMapTexture(), attachTexture3D()
* @see @ref attachRenderbuffer(), @ref attachTexture1D(),
* @ref attachTexture2D(), @ref attachCubeMapTexture(),
* @ref attachTexture3D()
*/
class MAGNUM_EXPORT BufferAttachment {
public:
@ -174,7 +175,9 @@ class MAGNUM_EXPORT Framebuffer: public AbstractFramebuffer, public AbstractObje
* @brief Both depth and stencil buffer
*
* @requires_gles30 Combined depth and stencil attachment is
* not available in OpenGL ES 2.0.
* not available in OpenGL ES 2.0. Attach the same object
* to both @ref Depth and @ref Stencil instead.
* @todo Support this in ES2 (bind to both depth and stencil internally)
*/
static const BufferAttachment DepthStencil;
#endif
@ -195,7 +198,7 @@ class MAGNUM_EXPORT Framebuffer: public AbstractFramebuffer, public AbstractObje
/**
* @brief Invalidation attachment
*
* @see invalidate()
* @see @ref invalidate()
* @requires_gl43 %Extension @extension{ARB,invalidate_subdata}
* @requires_gles30 %Extension @es_extension{EXT,discard_framebuffer}
*/
@ -223,7 +226,7 @@ class MAGNUM_EXPORT Framebuffer: public AbstractFramebuffer, public AbstractObje
/**
* @brief Status
*
* @see checkStatus()
* @see @ref checkStatus()
*/
enum class Status: GLenum {
/** The framebuffer is complete */
@ -296,7 +299,7 @@ class MAGNUM_EXPORT Framebuffer: public AbstractFramebuffer, public AbstractObje
* @brief Constructor
*
* Generates new OpenGL framebuffer.
* @see setViewport(), @fn_gl{GenFramebuffers}
* @see @ref setViewport(), @fn_gl{GenFramebuffers}
*/
explicit Framebuffer(const Range2Di& viewport);
@ -369,7 +372,7 @@ class MAGNUM_EXPORT Framebuffer: public AbstractFramebuffer, public AbstractObje
*
* @p attachments is list of shader outputs mapped to framebuffer
* color attachment IDs. %Shader outputs which are not listed are not
* used, you can achieve the same by passing Framebuffer::DrawAttachment::None
* used, you can achieve the same by passing @ref Framebuffer::DrawAttachment::None
* as color attachment ID. Example usage:
* @code
* framebuffer.mapForDraw({{MyShader::ColorOutput, Framebuffer::ColorAttachment(0)},
@ -409,6 +412,23 @@ class MAGNUM_EXPORT Framebuffer: public AbstractFramebuffer, public AbstractObje
return *this;
}
/**
* @brief Map given color attachment for reading
* @param attachment Color attachment
* @return Reference to self (for method chaining)
*
* If @extension{EXT,direct_state_access} is not available and the
* framebufferbuffer is not currently bound, it is bound before the
* operation.
* @see @ref mapForDraw(), @fn_gl{BindFramebuffer}, @fn_gl{ReadBuffer}
* or @fn_gl_extension{FramebufferReadBuffer,EXT,direct_state_access}
* @requires_gles30 %Extension @es_extension2{NV,read_buffer,GL_NV_read_buffer}
*/
Framebuffer& mapForRead(ColorAttachment attachment) {
(this->*readBufferImplementation)(GLenum(attachment));
return *this;
}
/**
* @brief Invalidate framebuffer
* @param attachments Attachments to invalidate
@ -418,9 +438,9 @@ class MAGNUM_EXPORT Framebuffer: public AbstractFramebuffer, public AbstractObje
* @see @fn_gl{InvalidateFramebuffer} or @fn_gles_extension{DiscardFramebuffer,EXT,discard_framebuffer}
* on OpenGL ES 2.0
* @requires_gl43 %Extension @extension{ARB,invalidate_subdata}. Use
* clear() instead where the extension is not supported.
* @ref clear() instead where the extension is not supported.
* @requires_gles30 %Extension @es_extension{EXT,discard_framebuffer}.
* Use clear() instead where the extension is not supported.
* Use @ref clear() instead where the extension is not supported.
*/
void invalidate(std::initializer_list<InvalidationAttachment> attachments);
@ -434,29 +454,12 @@ class MAGNUM_EXPORT Framebuffer: public AbstractFramebuffer, public AbstractObje
* @see @fn_gl{InvalidateSubFramebuffer} or @fn_gles_extension{DiscardSubFramebuffer,EXT,discard_framebuffer}
* on OpenGL ES 2.0
* @requires_gl43 %Extension @extension{ARB,invalidate_subdata}. Use
* clear() instead where the extension is not supported.
* @ref clear() instead where the extension is not supported.
* @requires_gles30 %Extension @es_extension{EXT,discard_framebuffer}.
* Use clear() instead where the extension is not supported.
* Use @ref clear() instead where the extension is not supported.
*/
void invalidate(std::initializer_list<InvalidationAttachment> attachments, const Range2Di& rectangle);
/**
* @brief Map given color attachment for reading
* @param attachment Color attachment
* @return Reference to self (for method chaining)
*
* If @extension{EXT,direct_state_access} is not available and the
* framebufferbuffer is not currently bound, it is bound before the
* operation.
* @see mapForDraw(), @fn_gl{BindFramebuffer}, @fn_gl{ReadBuffer} or
* @fn_gl_extension{FramebufferReadBuffer,EXT,direct_state_access}
* @requires_gles30 %Extension @es_extension2{NV,read_buffer,GL_NV_read_buffer}
*/
Framebuffer& mapForRead(ColorAttachment attachment) {
(this->*readBufferImplementation)(GLenum(attachment));
return *this;
}
/**
* @brief Attach renderbuffer to given buffer
* @param attachment %Buffer attachment
@ -505,7 +508,7 @@ class MAGNUM_EXPORT Framebuffer: public AbstractFramebuffer, public AbstractObje
* If @extension{EXT,direct_state_access} is not available and the
* framebufferbuffer is not currently bound, it is bound before the
* operation.
* @see attachCubeMapTexture(), @fn_gl{BindFramebuffer}, @fn_gl{FramebufferTexture}
* @see @ref attachCubeMapTexture(), @fn_gl{BindFramebuffer}, @fn_gl{FramebufferTexture}
* or @fn_gl_extension{NamedFramebufferTexture2D,EXT,direct_state_access}
*/
Framebuffer& attachTexture2D(BufferAttachment attachment, Texture2D& texture, Int level);
@ -521,7 +524,7 @@ class MAGNUM_EXPORT Framebuffer: public AbstractFramebuffer, public AbstractObje
* If @extension{EXT,direct_state_access} is not available and the
* framebufferbuffer is not currently bound, it is bound before the
* operation.
* @see attachTexture2D(), @fn_gl{BindFramebuffer}, @fn_gl{FramebufferTexture}
* @see @ref attachTexture2D(), @fn_gl{BindFramebuffer}, @fn_gl{FramebufferTexture}
* or @fn_gl_extension{NamedFramebufferTexture2D,EXT,direct_state_access}
*/
Framebuffer& attachCubeMapTexture(BufferAttachment attachment, CubeMapTexture& texture, CubeMapTexture::Coordinate coordinate, Int level) {

8
src/Renderbuffer.h
Unescape View File

@ -25,7 +25,7 @@
*/
/** @file
* @brief Class Magnum::Renderbuffer
* @brief Class @ref Magnum::Renderbuffer
*/
#include "AbstractObject.h"
@ -37,18 +37,18 @@ namespace Magnum {
/**
@brief %Renderbuffer
Attachable to framebuffer as render target, see Framebuffer documentation
Attachable to framebuffer as render target, see @ref Framebuffer documentation
for more information.
@section Renderbuffer-performance-optimization Performance optimizations
The engine tracks currently bound renderbuffer to avoid unnecessary calls to
@fn_gl{BindRenderbuffer} in setStorage(). %Renderbuffer limits and
@fn_gl{BindRenderbuffer} in @ref setStorage(). %Renderbuffer limits and
implementation-defined values (such as @ref maxSize()) are cached, so repeated
queries don't result in repeated @fn_gl{Get} calls.
If extension @extension{EXT,direct_state_access} is available, function
setStorage() uses DSA to avoid unnecessary calls to @fn_gl{BindRenderbuffer}.
@ref setStorage() uses DSA to avoid unnecessary calls to @fn_gl{BindRenderbuffer}.
See its documentation for more information.
@requires_gl30 %Extension @extension{ARB,framebuffer_object}

4
src/RenderbufferFormat.h
Unescape View File

@ -25,7 +25,7 @@
*/
/** @file
* @brief Enum Magnum::RenderbufferFormat
* @brief Enum @ref Magnum::RenderbufferFormat
*/
#include "OpenGL.h"
@ -35,7 +35,7 @@ namespace Magnum {
/**
@brief Internal renderbuffer format
@see Renderbuffer
@see @ref Renderbuffer
@requires_gl30 %Extension @extension{ARB,framebuffer_object}
@todo RGB, RGB8 ES only (ES3 + @es_extension{OES,rgb8_rgba8})
*/

Write Preview
Loading…
Cancel
Save