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

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 defaultFramebuffer.

Usage

When you are using only the default framebuffer, the usage is simple. You must ensure that it is properly resized when window surface is resized. In case you're using one of the Platform::Application classes, pass the new size in your viewportEvent() implementation, for example:

void viewportEvent(ViewportEvent& event) override {
    GL::defaultFramebuffer.setViewport({{}, event.framebufferSize()});

    // ...
}

Next thing you probably want is to clear all used buffers before performing any drawing. Again, in case you're using one of the Platform::Application classes, do it in your drawEvent() implementation, for example:

void drawEvent() override {
    GL::defaultFramebuffer.clear(GL::FramebufferClear::Color|
                                 GL::FramebufferClear::Depth);

    // ...
}

See documentation of particular functions and Framebuffer documentation for more involved usage, usage of non-default or multiple framebuffers.

Performance optimizations

See also relevant section in AbstractFramebuffer.

If ARB_direct_state_access (part of OpenGL 4.5) is available, functions checkStatus(), mapForDraw(), mapForRead() and invalidate() use DSA to avoid unnecessary calls to glBindFramebuffer(). See their respective documentation for more information.

Base classes

class AbstractFramebuffer
Base for default and named framebuffers.

Public types

enum class Status: GLenum { Complete = GL_FRAMEBUFFER_COMPLETE, Undefined = GL_FRAMEBUFFER_UNDEFINED }
Status.
enum class DrawAttachment: GLenum { None = GL_NONE, FrontLeft = GL_FRONT_LEFT, FrontRight = GL_FRONT_RIGHT, BackLeft = GL_BACK_LEFT, BackRight = GL_BACK_RIGHT, Back = GL_BACK_LEFT }
Draw attachment.
enum class ReadAttachment: GLenum { None = GL_NONE, FrontLeft = GL_FRONT_LEFT, FrontRight = GL_FRONT_RIGHT, BackLeft = GL_BACK_LEFT, BackRight = GL_BACK_RIGHT, Left = GL_LEFT, Right = GL_RIGHT, Back = GL_BACK, Front = GL_FRONT, FrontAndBack = GL_FRONT_AND_BACK }
Read attachment.
enum class InvalidationAttachment: GLenum { FrontLeft = GL_FRONT_LEFT, FrontRight = GL_FRONT_RIGHT, BackLeft = GL_BACK_LEFT, BackRight = GL_BACK_RIGHT, Color = GL_COLOR, Depth = GL_DEPTH, Stencil = GL_STENCIL }
Invalidation attachment.

Constructors, destructors, conversion operators

DefaultFramebuffer() explicit constexpr
Constructor.
DefaultFramebuffer(const DefaultFramebuffer&) deleted
Copying is not allowed.
DefaultFramebuffer(DefaultFramebuffer&&) deleted
Moving is not allowed.

Public functions

auto operator=(const DefaultFramebuffer&) -> DefaultFramebuffer& deleted
Copying is not allowed.
auto operator=(DefaultFramebuffer&& other) -> DefaultFramebuffer& deleted
Moving is not allowed.
auto checkStatus(FramebufferTarget target) -> Status
Check framebuffer status.
auto clearColor(const Color4& color) -> DefaultFramebuffer&
Clear color buffer to specified value.
auto clearColor(const Vector4i& color) -> DefaultFramebuffer&
auto clearColor(const Vector4ui& color) -> DefaultFramebuffer&
auto mapForDraw(Containers::ArrayView<const Containers::Pair<UnsignedInt, DrawAttachment>> attachments) -> DefaultFramebuffer& new in Git master
Map shader outputs to buffer attachment.
auto mapForDraw(std::initializer_list<Containers::Pair<UnsignedInt, DrawAttachment>> attachments) -> DefaultFramebuffer&
auto mapForDraw(DrawAttachment attachment) -> DefaultFramebuffer&
Map shader output to buffer attachment.
auto mapForRead(ReadAttachment attachment) -> DefaultFramebuffer&
Map given attachment for reading.
void invalidate(Containers::ArrayView<const InvalidationAttachment> attachments) new in Git master
Invalidate framebuffer.
void invalidate(std::initializer_list<InvalidationAttachment> attachments)
void invalidate(Containers::ArrayView<const InvalidationAttachment> attachments, const Range2Di& rectangle) new in Git master
Invalidate framebuffer rectangle.
void invalidate(std::initializer_list<InvalidationAttachment> attachments, const Range2Di& rectangle)

Enum documentation

enum class Magnum::GL::DefaultFramebuffer::Status: GLenum

Status.

Enumerators
Complete

The framebuffer is complete
Undefined

The default framebuffer does not exist.

enum class Magnum::GL::DefaultFramebuffer::DrawAttachment: GLenum

Draw attachment.

Enumerators
None

Don't use the output.
FrontLeft

Write output to front left buffer.
FrontRight

Write output to front right buffer.
BackLeft

Write output to back left buffer.
BackRight

Write output to back right buffer.
Back

Write output to back buffer.

On desktop OpenGL this is equal to DrawAttachment::BackLeft.

enum class Magnum::GL::DefaultFramebuffer::ReadAttachment: GLenum

Read attachment.

Enumerators
None

Don't read from any buffer
FrontLeft

Read from front left buffer.
FrontRight

Read from front right buffer.
BackLeft

Read from back left buffer.
BackRight

Read from back right buffer.
Left

Read from left buffer.
Right

Read from right buffer.
Back

Read from back buffer.
Front

Read from front buffer.
FrontAndBack

Read from front and back buffer.

enum class Magnum::GL::DefaultFramebuffer::InvalidationAttachment: GLenum

Invalidation attachment.

Enumerators
FrontLeft

Invalidate front left buffer.
FrontRight

Invalidate front right buffer.
BackLeft

Invalidate back left buffer.
BackRight

Invalidate back right buffer.
Color

Invalidate color buffer.
Depth

Invalidate depth bufer.
Stencil

Invalidate stencil buffer.

Function documentation

Magnum::GL::DefaultFramebuffer::DefaultFramebuffer() explicit constexpr

Constructor.

Not meant to be constructed on the application side, use the GL::defaultFramebuffer instance directly.

Status Magnum::GL::DefaultFramebuffer::checkStatus(FramebufferTarget target)

Check framebuffer status.

Parameters
target Target for which to check the status

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

The target parameter is ignored on OpenGL ES 2.0 if none of APPLE_framebuffer_multisample, ANGLE_framebuffer_blit or NV_framebuffer_blit is available and also on WebGL 1.0.

DefaultFramebuffer& Magnum::GL::DefaultFramebuffer::clearColor(const Color4& color)

Clear color buffer to specified value.

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

DefaultFramebuffer& Magnum::GL::DefaultFramebuffer::clearColor(const Vector4i& color)

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

DefaultFramebuffer& Magnum::GL::DefaultFramebuffer::clearColor(const Vector4ui& color)

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

DefaultFramebuffer& Magnum::GL::DefaultFramebuffer::mapForDraw(Containers::ArrayView<const Containers::Pair<UnsignedInt, DrawAttachment>> attachments) new in Git master

Map shader outputs to buffer attachment.

Returns Reference to self (for method chaining)

attachments is list of shader outputs mapped to buffer attachments. Shader outputs which are not listed are not used, you can achieve the same by passing DrawAttachment::None as attachment. Example usage:

GL::defaultFramebuffer.mapForDraw({
    {MyShader::ColorOutput, GL::DefaultFramebuffer::DrawAttachment::Back},
    {MyShader::NormalOutput, GL::DefaultFramebuffer::DrawAttachment::None}});

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

DefaultFramebuffer& Magnum::GL::DefaultFramebuffer::mapForDraw(std::initializer_list<Containers::Pair<UnsignedInt, DrawAttachment>> attachments)

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

DefaultFramebuffer& Magnum::GL::DefaultFramebuffer::mapForDraw(DrawAttachment attachment)

Map shader output to buffer attachment.

Parameters
attachment Buffer attachment
Returns Reference to self (for method chaining)

Similar to above function, can be used in cases when shader has only one (unnamed) output.

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

DefaultFramebuffer& Magnum::GL::DefaultFramebuffer::mapForRead(ReadAttachment attachment)

Map given attachment for reading.

Parameters
attachment Buffer attachment
Returns Reference to self (for method chaining)

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

void Magnum::GL::DefaultFramebuffer::invalidate(Containers::ArrayView<const InvalidationAttachment> attachments) new in Git master

Invalidate framebuffer.

Parameters
attachments Attachments to invalidate

If extension ARB_invalidate_subdata (part of OpenGL 4.3), extension EXT_discard_framebuffer in OpenGL ES 2.0 or OpenGL ES 3.0 is not available, this function does nothing. If ARB_direct_state_access (part of OpenGL 4.5) is not available, the framebuffer is bound before the operation (if not already).

void Magnum::GL::DefaultFramebuffer::invalidate(std::initializer_list<InvalidationAttachment> attachments)

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

void Magnum::GL::DefaultFramebuffer::invalidate(Containers::ArrayView<const InvalidationAttachment> attachments, const Range2Di& rectangle) new in Git master

Invalidate framebuffer rectangle.

Parameters
attachments Attachments to invalidate
rectangle Rectangle to invalidate

If extension ARB_invalidate_subdata (part of OpenGL 4.3) is not available, this function does nothing. If ARB_direct_state_access (part of OpenGL 4.5) is not available, the framebuffer is bound before the operation (if not already).

void Magnum::GL::DefaultFramebuffer::invalidate(std::initializer_list<InvalidationAttachment> attachments, const Range2Di& rectangle)

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

Debug& operator<<(Debug& debug, DefaultFramebuffer::Status value)

Debug output operator.