Magnum::Ui::RendererGL class new in Git master
#include <Magnum/Ui/RendererGL.h>

OpenGL renderer implementation.

Performs renderer state management for OpenGL layer implementations such as BaseLayerGL or TextLayerGL.

Setting up a renderer instance

If you use one of the UserInterfaceGL constructors taking a style, UserInterfaceGL::create(), tryCreate(), setStyle() or trySetStyle(), an implicit renderer instance is already set up by those. If you don't, or if you want to set up a custom-configured renderer before specifying a style, pass its instance to AbstractUserInterface::setRendererInstance():

ui.setRendererInstance(Containers::pointer<Ui::RendererGL>());

When AbstractUserInterface::draw() is executed, the renderer internally enables GL::Renderer::Feature::Blending and/or Feature::ScissorTest for layers that advertise LayerFeature::DrawUsesBlending and/or LayerFeature::DrawUsesScissor, the scissor rectangle is then reset back to the whole framebuffer size (as supplied to the user interface constructor or AbstractUserInterface::setSize()) after drawing.

Use with a compositing framebuffer

By default, the RendererGL instance assumes some framebuffer is bound for drawing and it doesn't touch the binding in any way. Layers that implement compositing operations however need a framebuffer which can be both drawn into and read from, which is achieved by constructing the renderer with Flag::CompositingFramebuffer:

class MyApplication: public Platform::Application {
    …

    private:
        Ui::UserInterfaceGL _ui{NoCreate};
};

MyApplication::MyApplication(const Arguments& arguments): Platform::Application{…} {
    /* Create a renderer with a compositing framebuffer as the first thing */
    _ui.setRendererInstance(Containers::pointer<Ui::RendererGL>(
        Ui::RendererGL::Flag::CompositingFramebuffer));

    /* Then add appropriate compositing layers, set a style, etc */
    _ui
        .setSize(…)
        .setStyle(…)
        …;

    …
}

With the flag enabled, the application is then responsible for clearing the compositingFramebuffer() at frame start, drawing all content underneath the UI to it, and ultimately blitting it back to the main / default application framebuffer after the UI is drawn:

void MyApplication::drawEvent() {
    _ui.renderer().compositingFramebuffer().clear(GL::FramebufferClear::Color);

    // Render content underneath the UI to the compositing framebuffer here ...

    _ui.draw();

    GL::AbstractFramebuffer::blit(
        _ui.renderer().compositingFramebuffer(),
        GL::defaultFramebuffer,
        GL::defaultFramebuffer.viewport(),
        GL::FramebufferBlit::Color);

    swapBuffers();
    redraw();
}

Base classes

class AbstractRenderer new in Git master: Base for renderer implementations.

Public types

enum class Flag: UnsignedByte { CompositingFramebuffer = 1 << 0 }: Renderer flag.
using Flags = Containers::EnumSet<Flag>: Renderer flags.

Constructors, destructors, conversion operators

RendererGL(Flags flags = {}) explicit: Constructor.
RendererGL(const RendererGL&) deleted: Copying is not allowed.
RendererGL(RendererGL&&) noexcept: Move constructor.

Public functions

auto operator=(const RendererGL&) -> RendererGL& deleted: Copying is not allowed.
auto operator=(RendererGL&&) -> RendererGL& noexcept: Move assignment.
auto flags() const -> Flags: Renderer flags.
auto compositingFramebuffer() -> GL::Framebuffer&: Compositing framebuffer instance.
auto compositingFramebuffer() const -> const GL::Framebuffer&
auto compositingTexture() -> GL::Texture2D&: Compositing framebuffer texture instance.
auto compositingTexture() const -> const GL::Texture2D&

Enum documentation

enum class Magnum::Ui::RendererGL::Flag: UnsignedByte

Renderer flag.

Enumerators
CompositingFramebuffer	Create a framebuffer to be used as a target for drawing all UI contents and a source for compositing operations implemented by various layers. The framebuffer, with a single GL::TextureFormat::RGBA8 color attachment, is created on the first call to setupFramebuffers(), which is called as a consequence of AbstractUserInterface::setSize() or a user interface constructor taking a size parameter, and is recreated on all following AbstractUserInterface::setSize() calls. Then application is then responsible for clearing the compositingFramebuffer() at frame start, drawing all content underneath the UI to it, and ultimately blitting it back to the main / default application framebuffer after the UI is drawn.

Enumerators

CompositingFramebuffer

Create a framebuffer to be used as a target for drawing all UI contents and a source for compositing operations implemented by various layers.

The framebuffer, with a single GL::TextureFormat::RGBA8 color attachment, is created on the first call to setupFramebuffers(), which is called as a consequence of AbstractUserInterface::setSize() or a user interface constructor taking a size parameter, and is recreated on all following AbstractUserInterface::setSize() calls.

Then application is then responsible for clearing the compositingFramebuffer() at frame start, drawing all content underneath the UI to it, and ultimately blitting it back to the main / default application framebuffer after the UI is drawn.

Typedef documentation

typedef Containers::EnumSet<Flag> Magnum::Ui::RendererGL::Flags

Renderer flags.

Function documentation

Magnum::Ui::RendererGL::RendererGL(RendererGL&&) noexcept

Move constructor.

Performs a destructive move, i.e. the original object isn't usable afterwards anymore.

GL::Framebuffer& Magnum::Ui::RendererGL::compositingFramebuffer()

Compositing framebuffer instance.

With a compositing framebuffer enabled, the application is responsible for clearing the framebuffer at frame start, drawing all content underneath the UI to it, and ultimately blitting it back to the main / default application framebuffer after the UI is drawn.

const GL::Framebuffer& Magnum::Ui::RendererGL::compositingFramebuffer() const

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

GL::Texture2D& Magnum::Ui::RendererGL::compositingTexture()

Compositing framebuffer texture instance.

Available only if the renderer was constructed with Flag::CompositingFramebuffer and only after framebuffer sizes were set up with setupFramebuffers(), which is called as a consequence of AbstractUserInterface::setSize() or a user interface constructor taking a size parameter. The texture is implicitly set to a single GL::TextureFormat::RGBA8 level of framebufferSize(), with both minification and magnification filter being GL::SamplerFilter::Linear and with GL::SamplerWrapping::ClampToEdge.

The texture is meant to be accessed inside an AbstractLayer::doComposite() implementation. In other cases, such as in an AbstractLayer::doDraw(), using it may lead to a framebuffer corruption as it would be used for both sampling and as a framebuffer target.

const GL::Texture2D& Magnum::Ui::RendererGL::compositingTexture() const