#include <Magnum/Shaders/FlatGL.h>

template<UnsignedInt dimensions>

Magnum::Shaders::FlatGL class new in Git master

Colored rendering

Common mesh setup:

struct Vertex {
    Vector3 position;
};
Vertex data[60]{
    //...
};

GL::Buffer vertices;
vertices.setData(data, GL::BufferUsage::StaticDraw);

GL::Mesh mesh;
mesh.addVertexBuffer(vertices, 0, Shaders::FlatGL3D::Position{})
    // ...
    ;

Common rendering setup:

Matrix4 transformationMatrix = Matrix4::translation(Vector3::zAxis(-5.0f));
Matrix4 projectionMatrix =
    Matrix4::perspectiveProjection(35.0_degf, 1.0f, 0.001f, 100.0f);

Shaders::FlatGL3D shader;
shader.setColor(0x2f83cc_rgbf)
    .setTransformationProjectionMatrix(projectionMatrix*transformationMatrix)
    .draw(mesh);

Textured rendering

If you want to use a texture, you need to provide also the TextureCoordinates attribute. Pass Flag::Textured to the constructor and then at render time don't forget to bind also the texture via bindTexture(). The texture is multiplied by the color, which is by default set to 0xffffffff_rgbaf. Common mesh setup:

struct Vertex {
    Vector3 position;
    Vector2 textureCoordinates;
};
Vertex data[60]{
    // ...
};

GL::Buffer vertices;
vertices.setData(data, GL::BufferUsage::StaticDraw);

GL::Mesh mesh;
mesh.addVertexBuffer(vertices, 0,
    Shaders::FlatGL3D::Position{},
    Shaders::FlatGL3D::TextureCoordinates{})
    // ...
    ;

Common rendering setup:

Matrix4 transformationMatrix, projectionMatrix;
GL::Texture2D texture;

Shaders::FlatGL3D shader{Shaders::FlatGL3D::Configuration{}
    .setFlags(Shaders::FlatGL3D::Flag::Textured)};
shader.setTransformationProjectionMatrix(projectionMatrix*transformationMatrix)
    .bindTexture(texture)
    .draw(mesh);

For coloring the texture based on intensity you can use the VectorGL shader. The 3D version of this shader is equivalent to PhongGL with zero lights, however this implementation is much simpler and thus likely also faster. See its documentation for more information. Conversely, enabling Flag::VertexColor and using a default color with no texturing makes this shader equivalent to VertexColorGL.

Alpha blending and masking

Alpha / transparency is supported by the shader implicitly, but to have it working on the framebuffer, you need to enable GL::Renderer::Feature::Blending and set up the blending function. See GL::Renderer::setBlendFunction() for details.

An alternative is to enable Flag::AlphaMask and tune setAlphaMask() for simple binary alpha-masked drawing that doesn't require depth sorting or blending enabled. Note that this feature is implemented using the GLSL discard operation which is known to have considerable performance impact on some platforms. With proper depth sorting and blending you'll usually get much better performance and output quality.

Object ID output

The shader supports writing object ID to the framebuffer for object picking or other annotation purposes. Enable it using Flag::ObjectId and set up an integer buffer attached to the ObjectIdOutput attachment. Note that for portability you should use GL::Framebuffer::clearColor() instead of GL::Framebuffer::clear() as the former usually emits GL errors when called on framebuffers with integer attachments.

GL::Renderbuffer color, objectId;
color.setStorage(GL::RenderbufferFormat::RGBA8, size);
objectId.setStorage(GL::RenderbufferFormat::R16UI, size); // large as needed
framebuffer.attachRenderbuffer(GL::Framebuffer::ColorAttachment{0}, color)
    .attachRenderbuffer(GL::Framebuffer::ColorAttachment{1}, objectId);

Shaders::FlatGL3D shader{Shaders::FlatGL3D::Configuration{}
    .setFlags(Shaders::FlatGL3D::Flag::ObjectId)};

// ...

framebuffer.mapForDraw({
        {Shaders::FlatGL3D::ColorOutput, GL::Framebuffer::ColorAttachment{0}},
        {Shaders::FlatGL3D::ObjectIdOutput, GL::Framebuffer::ColorAttachment{1}}})
    .clearColor(0, 0x1f1f1f_rgbf)
    .clearColor(1, Vector4ui{0})
    .bind();

shader.setObjectId(meshId)
    .draw(mesh);

If you have a batch of meshes with different object IDs, enable Flag::InstancedObjectId and supply per-vertex IDs to the ObjectId attribute. The object ID can be also supplied from an integer texture bound via bindObjectIdTexture() if Flag::ObjectIdTexture is enabled. The output will contain a sum of the per-vertex ID, texture ID and ID coming from setObjectId().

Instanced rendering

Enabling Flag::InstancedTransformation will turn the shader into an instanced one. It'll take per-instance transformation from the TransformationMatrix attribute, applying it before the matrix set by setTransformationProjectionMatrix(). Besides that, Flag::VertexColor (and the Color3 / Color4) attributes can work as both per-vertex and per-instance, and for texturing it's possible to have per-instance texture offset taken from TextureOffset when Flag::InstancedTextureOffset is enabled (similarly to transformation, applied before setTextureMatrix()). The snippet below shows adding a buffer with per-instance transformation and color to a mesh:

struct {
    Matrix4 transformation;
    Color3 color;
} instanceData[] {
    {Matrix4::translation({1.0f, 2.0f, 0.0f}), 0xff3333_rgbf},
    {Matrix4::translation({2.0f, 1.0f, 0.0f}), 0x33ff33_rgbf},
    {Matrix4::translation({3.0f, 0.0f, 1.0f}), 0x3333ff_rgbf},
    // ...
};

mesh.setInstanceCount(Containers::arraySize(instanceData))
    .addVertexBufferInstanced(GL::Buffer{instanceData}, 1, 0,
        Shaders::FlatGL3D::TransformationMatrix{},
        Shaders::FlatGL3D::Color3{});

Uniform buffers

See Using uniform buffers for a high-level overview that applies to all shaders. In this particular case, because the shader doesn't need a separate projection and transformation matrix, a combined one is supplied via a TransformationProjectionUniform2D / TransformationProjectionUniform3D buffer. To maximize use of the limited uniform buffer memory, materials are supplied separately in a FlatMaterialUniform buffer and then referenced via materialId from a FlatDrawUniform; for optional texture transformation a per-draw TextureTransformationUniform can be supplied as well. A uniform buffer setup equivalent to the colored case at the top would look like this:

GL::Buffer projectionTransformationUniform, materialUniform, drawUniform;
projectionTransformationUniform.setData({
    Shaders::TransformationProjectionUniform3D{}
        .setTransformationProjectionMatrix(projectionMatrix*transformationMatrix)
});
materialUniform.setData({
    Shaders::FlatMaterialUniform{}
        .setColor(0x2f83cc_rgbf)
});
drawUniform.setData({
    Shaders::FlatDrawUniform{}
        .setMaterialId(0)
});

Shaders::FlatGL3D shader{Shaders::FlatGL3D::Configuration{}
    .setFlags(Shaders::FlatGL3D::Flag::UniformBuffers)};
shader
    .bindTransformationProjectionBuffer(projectionTransformationUniform)
    .bindMaterialBuffer(materialUniform)
    .bindDrawBuffer(drawUniform)
    .draw(mesh);

For a multidraw workflow enable Flag::MultiDraw (and possibly Flag::TextureArrays), supply desired material and draw count in the FlatGL(Flags, UnsignedInt, UnsignedInt) constructor and specify material references and texture offsets/layers for every draw. The usage is similar for all shaders, see Multidraw and reducing driver overhead for an example.

Base classes

class Magnum::GL::AbstractShaderProgram

Base for shader program implementations.

Derived classes

class Magnum::Shaders::FlatGL::CompileState new in Git master

Asynchronous compilation state.

Public types

class CompileState new in Git master

Asynchronous compilation state.

class Configuration new in Git master

Configuration.

enum (anonymous): UnsignedInt { ColorOutput = GenericGL<dimensions>::ColorOutput new in 2019.10, ObjectIdOutput = GenericGL<dimensions>::ObjectIdOutput new in 2019.10 }

enum class Flag: UnsignedShort { Textured = 1 << 0, AlphaMask = 1 << 1, VertexColor = 1 << 2 new in 2019.10, TextureTransformation = 1 << 3 new in 2020.06, ObjectId = 1 << 4 new in 2019.10, InstancedObjectId = (1 << 5)|ObjectId new in 2020.06, ObjectIdTexture = (1 << 11)|ObjectId new in Git master, InstancedTransformation = 1 << 6 new in 2020.06, InstancedTextureOffset = (1 << 7)|TextureTransformation new in 2020.06, UniformBuffers = 1 << 8 new in Git master, MultiDraw = UniformBuffers|(1 << 9) new in Git master, TextureArrays = 1 << 10 new in Git master }

Flag.

using Position = GenericGL<dimensions>::Position

Vertex position.

using TextureCoordinates = GenericGL<dimensions>::TextureCoordinates

2D texture coordinates

using Color3 = GenericGL<dimensions>::Color3 new in 2019.10

Three-component vertex color.

using Color4 = GenericGL<dimensions>::Color4 new in 2019.10

Four-component vertex color.

using ObjectId = GenericGL<dimensions>::ObjectId new in 2020.06

(Instanced) object ID

using TransformationMatrix = GenericGL<dimensions>::TransformationMatrix new in 2020.06

(Instanced) transformation matrix

using TextureOffset = GenericGL<dimensions>::TextureOffset new in 2020.06

(Instanced) texture offset

using TextureOffsetLayer = GenericGL<dimensions>::TextureOffsetLayer new in Git master

(Instanced) texture offset and layer

using Flags = Containers::EnumSet<Flag>

Flags.

Public static functions

static auto compile(const Configuration& configuration = Configuration{}) -> CompileState new in Git master

Compile asynchronously.

static auto compile(Flags flags) -> CompileState deprecated in Git master

Compile asynchronously.

static auto compile(Flags flags, UnsignedInt materialCount, UnsignedInt drawCount) -> CompileState deprecated in Git master

Compile for a multi-draw scenario asynchronously.

Constructors, destructors, conversion operators

FlatGL(const Configuration& configuration = Configuration{}) explicit new in Git master

Constructor.

FlatGL(Flags flags) deprecated in Git master explicit

Constructor.

FlatGL(Flags flags, UnsignedInt materialCount, UnsignedInt drawCount) deprecated in Git master explicit

Construct for a multi-draw scenario.

FlatGL(CompileState&& state) explicit new in Git master

Finalize an asynchronous compilation.

FlatGL(NoCreateT) explicit noexcept

Construct without creating the underlying OpenGL object.

FlatGL(const FlatGL<dimensions>&) deleted

Copying is not allowed.

FlatGL(FlatGL<dimensions>&&) defaulted noexcept

Move constructor.

Public functions

auto operator=(const FlatGL<dimensions>&) -> FlatGL<dimensions>& deleted

Copying is not allowed.

auto operator=(FlatGL<dimensions>&&) -> FlatGL<dimensions>& defaulted noexcept

Move assignment.

auto flags() const -> Flags

Flags.

auto materialCount() const -> UnsignedInt new in Git master

Material count.

auto drawCount() const -> UnsignedInt new in Git master

Draw count.

Uniform setters

Used only if Flag::UniformBuffers is not set.

auto setTransformationProjectionMatrix(const MatrixTypeFor<dimensions, Float>& matrix) -> FlatGL<dimensions>&

Set transformation and projection matrix.

auto setTextureMatrix(const Matrix3& matrix) -> FlatGL<dimensions>& new in 2020.06

Set texture coordinate transformation matrix.

auto setTextureLayer(UnsignedInt layer) -> FlatGL<dimensions>& new in Git master

Set texture array layer.

auto setColor(const Magnum::Color4& color) -> FlatGL<dimensions>&

Set color.

auto setAlphaMask(Float mask) -> FlatGL<dimensions>&

Set alpha mask value.

auto setObjectId(UnsignedInt id) -> FlatGL<dimensions>&

Set object ID.

Uniform buffer binding and related uniform setters

Used if Flag::UniformBuffers is set.

auto setDrawOffset(UnsignedInt offset) -> FlatGL<dimensions>& new in Git master

Set a draw offset.

auto bindTransformationProjectionBuffer(GL::Buffer& buffer) -> FlatGL<dimensions>& new in Git master

Set a transformation and projection uniform buffer.

auto bindTransformationProjectionBuffer(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size) -> FlatGL<dimensions>& new in Git master

auto bindDrawBuffer(GL::Buffer& buffer) -> FlatGL<dimensions>& new in Git master

Set a draw uniform buffer.

auto bindDrawBuffer(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size) -> FlatGL<dimensions>& new in Git master

auto bindTextureTransformationBuffer(GL::Buffer& buffer) -> FlatGL<dimensions>& new in Git master

Set a texture transformation uniform buffer.

auto bindTextureTransformationBuffer(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size) -> FlatGL<dimensions>& new in Git master

auto bindMaterialBuffer(GL::Buffer& buffer) -> FlatGL<dimensions>& new in Git master

Set a material uniform buffer.

auto bindMaterialBuffer(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size) -> FlatGL<dimensions>& new in Git master

Texture binding

auto bindTexture(GL::Texture2D& texture) -> FlatGL<dimensions>&

Bind a color texture.

auto bindTexture(GL::Texture2DArray& texture) -> FlatGL<dimensions>& new in Git master

Bind a color array texture.

auto bindObjectIdTexture(GL::Texture2D& texture) -> FlatGL<dimensions>& new in Git master

Bind an object ID texture.

auto bindObjectIdTexture(GL::Texture2DArray& texture) -> FlatGL<dimensions>& new in Git master

Bind an object ID array texture.

Related

template<UnsignedInt dimensions>

auto operator<<(Debug& debug, FlatGL<dimensions>::Flag value) -> Debug&

Debug output operator.

template<UnsignedInt dimensions>

auto operator<<(Debug& debug, FlatGL<dimensions>::Flags value) -> Debug&

Debug output operator.

Enum documentation

Typedef documentation

Function documentation