Magnum::GL::AbstractFramebuffer class
#include <Magnum/GL/AbstractFramebuffer.h>

Base for default and named framebuffers.

See DefaultFramebuffer and Framebuffer for more information.

Performance optimizations and security

The engine tracks currently bound framebuffer and current viewport to avoid unnecessary calls to glBindFramebuffer() and glViewport() when switching framebuffers. Framebuffer limits and implementation-defined values (such as maxViewportSize()) are cached, so repeated queries don't result in repeated glGet() calls. See also Context::resetState() and Context::State::Framebuffers.

Pixel storage mode defined by PixelStorage is applied either right before doing image download via read() using glPixelStore() with GL_PACK_*. The engine tracks currently used pixel pack parameters to avoid unnecessary calls to glPixelStore(). See also Context::resetState() and Context::State::PixelStorage.

If extension ARB_direct_state_access (part of OpenGL 4.5) is available, blit(), clearDepth(), clearStencil() and clearDepthStencil() functions use DSA to avoid unnecessary call to glBindFramebuffer(). See their documentation for more information.

If ARB_robustness is available, read() operations are protected from buffer overflow.

Derived classes

class DefaultFramebuffer
Default framebuffer.
class Framebuffer
Framebuffer.

Public static functions

static auto maxViewportSize() -> Vector2i
Max supported viewport size.
static auto maxDrawBuffers() -> Int
Max supported draw buffer count.
static auto maxDualSourceDrawBuffers() -> Int
Max supported dual-source draw buffer count.
static void blit(AbstractFramebuffer& source, AbstractFramebuffer& destination, const Range2Di& sourceRectangle, const Range2Di& destinationRectangle, FramebufferBlitMask mask, FramebufferBlitFilter filter)
Copy a block of pixels.
static void blit(AbstractFramebuffer& source, AbstractFramebuffer& destination, const Range2Di& rectangle, FramebufferBlitMask mask)
Copy a block of pixels.

Public functions

void bind()
Bind framebuffer for drawing.
auto viewport() const -> Range2Di
Viewport rectangle.
auto setViewport(const Range2Di& rectangle) -> AbstractFramebuffer&
Set viewport.
auto implementationColorReadFormat() -> PixelFormat new in 2019.10
Implementation-specific color read format.
auto implementationColorReadType() -> PixelType new in 2019.10
Implementation-specific color read type.
auto clear(FramebufferClearMask mask) -> AbstractFramebuffer&
Clear specified buffers in the framebuffer.
auto clearDepth(Float depth) -> AbstractFramebuffer&
Clear depth buffer to specified value.
auto clearStencil(Int stencil) -> AbstractFramebuffer&
Clear stencil buffer to specified value.
auto clearDepthStencil(Float depth, Int stencil) -> AbstractFramebuffer&
Clear depth and stencil buffer to specified value.
void read(const Range2Di& rectangle, Image2D& image)
Read a block of pixels from the framebuffer to an image.
auto read(const Range2Di& rectangle, Image2D&& image) -> Image2D
void read(const Range2Di& rectangle, const MutableImageView2D& image) new in 2019.10
Read a block of pixels from the framebuffer to an image view.
void read(const Range2Di& rectangle, BufferImage2D& image, BufferUsage usage)
Read a block of pixels from the framebuffer to a buffer image.
auto read(const Range2Di& rectangle, BufferImage2D&& image, BufferUsage usage) -> BufferImage2D
void copyImage(const Range2Di& rectangle, Texture1D& texture, Int level, TextureFormat internalFormat)
Copy block of pixels from framebuffer to 1D texture image.
void copyImage(const Range2Di& rectangle, Texture2D& texture, Int level, TextureFormat internalFormat)
Copy block of pixels from framebuffer to 2D texture image.
void copyImage(const Range2Di& rectangle, RectangleTexture& texture, TextureFormat internalFormat)
Copy block of pixels from framebuffer to rectangle texture.
void copyImage(const Range2Di& rectangle, CubeMapTexture& texture, CubeMapCoordinate coordinate, Int level, TextureFormat internalFormat)
Copy block of pixels from framebuffer to cube map texture image.
void copyImage(const Range2Di& rectangle, Texture1DArray& texture, Int level, TextureFormat internalFormat)
Copy block of pixels from framebuffer to 1D texture array image.
void copySubImage(const Range2Di& rectangle, Texture1D& texture, Int level, Int offset)
Copy block of pixels from framebuffer to 1D texture subimage.
void copySubImage(const Range2Di& rectangle, Texture2D& texture, Int level, const Vector2i& offset)
Copy block of pixels from framebuffer to 2D texture subimage.
void copySubImage(const Range2Di& rectangle, RectangleTexture& texture, const Vector2i& offset)
Copy block of pixels from framebuffer to rectangle texture subimage.
void copySubImage(const Range2Di& rectangle, CubeMapTexture& texture, Int level, const Vector3i& offset)
Copy block of pixels from framebuffer to cube map texture subimage.
void copySubImage(const Range2Di& rectangle, Texture3D& texture, Int level, const Vector3i& offset)
Copy block of pixels from framebuffer to 3D texture subimage.
void copySubImage(const Range2Di& rectangle, Texture1DArray& texture, Int level, const Vector2i& offset)
Copy block of pixels from framebuffer to 1D texture array subimage.
void copySubImage(const Range2Di& rectangle, Texture2DArray& texture, Int level, const Vector3i& offset)
Copy block of pixels from framebuffer to 2D texture array subimage.
void copySubImage(const Range2Di& rectangle, CubeMapTextureArray& texture, Int level, const Vector3i& offset)
Copy block of pixels from framebuffer to cube map texture array subimage.

Function documentation

static Vector2i Magnum::GL::AbstractFramebuffer::maxViewportSize()

Max supported viewport size.

The result is cached, repeated queries don't result in repeated OpenGL calls.

static Int Magnum::GL::AbstractFramebuffer::maxDrawBuffers()

Max supported draw buffer count.

The result is cached, repeated queries don't result in repeated OpenGL calls. If neither EXT_draw_buffers nor NV_draw_buffers is available in OpenGL ES 2.0 and WEBGL_draw_buffers is not available in WebGL 1.0, returns 0.

static Int Magnum::GL::AbstractFramebuffer::maxDualSourceDrawBuffers()

Max supported dual-source draw buffer count.

The result is cached, repeated queries don't result in repeated OpenGL calls. If extension ARB_blend_func_extended (part of OpenGL 3.3) is not available, returns 0.

static void Magnum::GL::AbstractFramebuffer::blit(AbstractFramebuffer& source, AbstractFramebuffer& destination, const Range2Di& sourceRectangle, const Range2Di& destinationRectangle, FramebufferBlitMask mask, FramebufferBlitFilter filter)

Copy a block of pixels.

Parameters
source Source framebuffer
destination Destination framebuffer
sourceRectangle Source rectangle
destinationRectangle Destination rectangle
mask Which buffers to perform blit operation on
filter Interpolation filter

See DefaultFramebuffer::mapForRead(), Framebuffer::mapForRead(), DefaultFramebuffer::mapForDraw() and Framebuffer::mapForDraw() for specifying particular buffers for blitting operation. If ARB_direct_state_access (part of OpenGL 4.5) is not available, source framebuffer is bound to FramebufferTarget::Read and destination framebuffer to FramebufferTarget::Draw before the operation (if not already).

static void Magnum::GL::AbstractFramebuffer::blit(AbstractFramebuffer& source, AbstractFramebuffer& destination, const Range2Di& rectangle, FramebufferBlitMask mask)

Copy a block of pixels.

Convenience alternative to the above function when source rectangle is the same as destination rectangle. As the image is copied pixel-by-pixel, no interpolation is needed and thus FramebufferBlitFilter::Nearest filtering is used by default.

void Magnum::GL::AbstractFramebuffer::bind()

Bind framebuffer for drawing.

Binds the framebuffer for drawing and updates viewport to saved dimensions.

AbstractFramebuffer& Magnum::GL::AbstractFramebuffer::setViewport(const Range2Di& rectangle)

Set viewport.

Returns Reference to self (for method chaining)

Saves the viewport to be used at later time in bind(). If the framebuffer is currently bound, updates the viewport to given rectangle. Initial value in DefaultFramebuffer is set to cover whole window, in Framebuffer the initial value is specified in constructor.

PixelFormat Magnum::GL::AbstractFramebuffer::implementationColorReadFormat() new in 2019.10

Implementation-specific color read format.

The result is not cached in any way. If ARB_direct_state_access (part of OpenGL 4.5) is not available, the framebuffer is bound to some target before the operation (if not already).

PixelType Magnum::GL::AbstractFramebuffer::implementationColorReadType() new in 2019.10

Implementation-specific color read type.

The result is not cached in any way. If ARB_direct_state_access (part of OpenGL 4.5) is not available, the framebuffer is bound to some target before the operation (if not already).

AbstractFramebuffer& Magnum::GL::AbstractFramebuffer::clear(FramebufferClearMask mask)

Clear specified buffers in the framebuffer.

Parameters
mask Which buffers to clear
Returns Reference to self (for method chaining)

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.

AbstractFramebuffer& Magnum::GL::AbstractFramebuffer::clearDepth(Float depth)

Clear depth buffer to specified value.

Parameters
depth Value to clear with
Returns Reference to self (for method chaining)

Note that, unlike the color and stencil buffer which are often cleared to a zero value, the depth buffer should be cleared to 1.0f — unless a different (or inverse) range was set in Renderer::setDepthRange(), 0.0f is the depth at the near plane, which isn't a desirable value to clear to.

AbstractFramebuffer& Magnum::GL::AbstractFramebuffer::clearStencil(Int stencil)

Clear stencil buffer to specified value.

Parameters
stencil Value to clear with
Returns Reference to self (for method chaining)

AbstractFramebuffer& Magnum::GL::AbstractFramebuffer::clearDepthStencil(Float depth, Int stencil)

Clear depth and stencil buffer to specified value.

Parameters
depth Depth value to clear with
stencil Stencil value to clear with
Returns Reference to self (for method chaining)

void Magnum::GL::AbstractFramebuffer::read(const Range2Di& rectangle, Image2D& image)

Read a block of pixels from the framebuffer to an image.

Parameters
rectangle Framebuffer rectangle to read
image Image where to put the data

Image parameters like format and type of pixel data are taken from given image. ImageFlags of image get cleared. The storage is not reallocated if it is large enough to contain the new data — however if you want to read into existing memory or ensure a reallocation does not happen, use read(const Range2Di&, const MutableImageView2D&) instead.

On OpenGL ES 2.0 and WebGL 1.0, if PixelStorage::skip() is set, the functionality is emulated by adjusting the data pointer. If ARB_robustness is available, the operation is protected from buffer overflow.

Image2D Magnum::GL::AbstractFramebuffer::read(const Range2Di& rectangle, Image2D&& image)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Convenience alternative to the above, example usage:

Image2D image = framebuffer.read(framebuffer.viewport(),
    {PixelFormat::RGBA8Unorm});

void Magnum::GL::AbstractFramebuffer::read(const Range2Di& rectangle, const MutableImageView2D& image) new in 2019.10

Read a block of pixels from the framebuffer to an image view.

Compared to read(const Range2Di&, Image2D&) the function reads the pixels into the memory provided by image, expecting it's not nullptr and its size is the same as rectangle size. Any set of ImageFlags is allowed in image — e.g., it's possible to read a 2D framebuffer to an image marked as 1D array.

void Magnum::GL::AbstractFramebuffer::read(const Range2Di& rectangle, BufferImage2D& image, BufferUsage usage)

Read a block of pixels from the framebuffer to a buffer image.

Parameters
rectangle Framebuffer rectangle to read
image Buffer image where to put the data
usage Buffer usage

See read(const Range2Di&, Image2D&) for more information. The storage is not reallocated if it is large enough to contain the new data, which means that usage might get ignored.

BufferImage2D Magnum::GL::AbstractFramebuffer::read(const Range2Di& rectangle, BufferImage2D&& image, BufferUsage usage)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Convenience alternative to the above, example usage:

GL::BufferImage2D image = framebuffer.read(framebuffer.viewport(),
    {PixelFormat::RGBA8Unorm}, GL::BufferUsage::StaticRead);

void Magnum::GL::AbstractFramebuffer::copyImage(const Range2Di& rectangle, Texture1D& texture, Int level, TextureFormat internalFormat)

Copy block of pixels from framebuffer to 1D texture image.

Parameters
rectangle Framebuffer rectangle to copy. Height must be 1.
texture Texture where to put the data
level Texture mip level
internalFormat Texture internal format

On platforms that support it prefer to use Texture1D::setStorage() and copySubImage() instead, as it avoids unnecessary reallocations and has better performance characteristics. This call also has no equivalent in ARB_direct_state_access, thus the texture needs to be bound to some texture unit before the operation.

void Magnum::GL::AbstractFramebuffer::copyImage(const Range2Di& rectangle, Texture2D& texture, Int level, TextureFormat internalFormat)

Copy block of pixels from framebuffer to 2D texture image.

Parameters
rectangle Framebuffer rectangle to copy
texture Texture where to put the data
level Texture mip level
internalFormat Texture internal format

On platforms that support it prefer to use Texture2D::setStorage() and copySubImage() instead, as it avoids unnecessary reallocations and has better performance characteristics. This call also has no equivalent in ARB_direct_state_access, thus the texture needs to be bound to some texture unit before the operation.

void Magnum::GL::AbstractFramebuffer::copyImage(const Range2Di& rectangle, RectangleTexture& texture, TextureFormat internalFormat)

Copy block of pixels from framebuffer to rectangle texture.

Parameters
rectangle Framebuffer rectangle to copy
texture Texture where to put the data
internalFormat Texture internal format

On platforms that support it prefer to use RectangleTexture::setStorage() and copySubImage() instead, as it avoids unnecessary reallocations and has better performance characteristics. This call also has no equivalent in ARB_direct_state_access, thus the texture needs to be bound to some texture unit before the operation.

void Magnum::GL::AbstractFramebuffer::copyImage(const Range2Di& rectangle, CubeMapTexture& texture, CubeMapCoordinate coordinate, Int level, TextureFormat internalFormat)

Copy block of pixels from framebuffer to cube map texture image.

Parameters
rectangle Framebuffer rectangle to copy
texture Texture where to put the data
coordinate Cube map coordinate
level Texture mip level
internalFormat Texture internal format

On platforms that support it prefer to use CubeMapTexture::setStorage() and copySubImage() instead, as it avoids unnecessary reallocations and has better performance characteristics. This call also has no equivalent in ARB_direct_state_access, thus the texture needs to be bound to some texture unit before the operation.

void Magnum::GL::AbstractFramebuffer::copyImage(const Range2Di& rectangle, Texture1DArray& texture, Int level, TextureFormat internalFormat)

Copy block of pixels from framebuffer to 1D texture array image.

Parameters
rectangle Framebuffer rectangle to copy
texture Texture where to put the data
level Texture mip level
internalFormat Texture internal format

On platforms that support it prefer to use Texture2D::setStorage() and copySubImage() instead, as it avoids unnecessary reallocations and has better performance characteristics. This call also has no equivalent in ARB_direct_state_access, thus the texture needs to be bound to some texture unit before the operation.

void Magnum::GL::AbstractFramebuffer::copySubImage(const Range2Di& rectangle, Texture1D& texture, Int level, Int offset)

Copy block of pixels from framebuffer to 1D texture subimage.

Parameters
rectangle Framebuffer rectangle to copy. Height must be 1.
texture Texture where to put the data
level Texture mip level
offset Offset inside the texture

If ARB_direct_state_access (part of OpenGL 4.5) is not available, the texture is bound before the operation (if not already).

void Magnum::GL::AbstractFramebuffer::copySubImage(const Range2Di& rectangle, Texture2D& texture, Int level, const Vector2i& offset)

Copy block of pixels from framebuffer to 2D texture subimage.

Parameters
rectangle Framebuffer rectangle to copy
texture Texture where to put the data
level Texture mip level
offset Offset inside the texture

If ARB_direct_state_access (part of OpenGL 4.5) is not available, the texture is bound before the operation (if not already).

void Magnum::GL::AbstractFramebuffer::copySubImage(const Range2Di& rectangle, RectangleTexture& texture, const Vector2i& offset)

Copy block of pixels from framebuffer to rectangle texture subimage.

Parameters
rectangle Framebuffer rectangle to copy
texture Texture where to put the data
offset Offset inside the texture

If ARB_direct_state_access (part of OpenGL 4.5) is not available, the texture is bound before the operation (if not already).

void Magnum::GL::AbstractFramebuffer::copySubImage(const Range2Di& rectangle, CubeMapTexture& texture, Int level, const Vector3i& offset)

Copy block of pixels from framebuffer to cube map texture subimage.

Parameters
rectangle Framebuffer rectangle to copy
texture Texture where to put the data
level Texture mip level
offset Offset inside the texture

Z coordinate of the offset is equivalent to number of texture face, i.e. +X is 0 and so on, in order of (+X, -X, +Y, -Y, +Z, -Z). If ARB_direct_state_access (part of OpenGL 4.5) is not available, the texture is bound before the operation (if not already).

void Magnum::GL::AbstractFramebuffer::copySubImage(const Range2Di& rectangle, Texture3D& texture, Int level, const Vector3i& offset)

Copy block of pixels from framebuffer to 3D texture subimage.

Parameters
rectangle Framebuffer rectangle to copy
texture Texture where to put the data
level Texture mip level
offset Offset inside the texture

If ARB_direct_state_access (part of OpenGL 4.5) is not available, the texture is bound before the operation (if not already).

void Magnum::GL::AbstractFramebuffer::copySubImage(const Range2Di& rectangle, Texture1DArray& texture, Int level, const Vector2i& offset)

Copy block of pixels from framebuffer to 1D texture array subimage.

Parameters
rectangle Framebuffer rectangle to copy
texture Texture where to put the data
level Texture mip level
offset Offset inside the texture

If ARB_direct_state_access (part of OpenGL 4.5) is not available, the texture is bound before the operation (if not already).

void Magnum::GL::AbstractFramebuffer::copySubImage(const Range2Di& rectangle, Texture2DArray& texture, Int level, const Vector3i& offset)

Copy block of pixels from framebuffer to 2D texture array subimage.

Parameters
rectangle Framebuffer rectangle to copy
texture Texture where to put the data
level Texture mip level
offset Offset inside the texture

If ARB_direct_state_access (part of OpenGL 4.5) is not available, the texture is bound before the operation (if not already).

void Magnum::GL::AbstractFramebuffer::copySubImage(const Range2Di& rectangle, CubeMapTextureArray& texture, Int level, const Vector3i& offset)

Copy block of pixels from framebuffer to cube map texture array subimage.

Parameters
rectangle Framebuffer rectangle to copy
texture Texture where to put the data
level Texture mip level
offset Offset inside the texture

Z coordinate of the offset is equivalent to layer * 6 + number of texture face, i.e. +X is 0 and so on, in order of (+X, -X, +Y, -Y, +Z, -Z). If ARB_direct_state_access (part of OpenGL 4.5) is not available, the texture is bound before the operation (if not already).