class
#include <Magnum/GL/AbstractFramebuffer.h>
AbstractFramebuffer 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::
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::
If extension ARB_
If ARB_
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_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_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::source
framebuffer is bound to FramebufferTarget::destination
framebuffer to FramebufferTarget::
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::
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_
PixelType Magnum:: GL:: AbstractFramebuffer:: implementationColorReadType() new in 2019.10
Implementation-specific color read type.
The result is not cached in any way. If ARB_
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::
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::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::
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::
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::
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::
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::
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::
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_
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_
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_
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_
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_
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_
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_
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_