template<UnsignedInt dimensions>
Magnum::Shaders::Flat class

Flat shader.

Draws the whole mesh with given color or texture. For a colored mesh you need to provide the Position attribute in your triangle mesh. By default, the shader renders the mesh with a white color in an identity transformation. Use setTransformationProjectionMatrix(), setColor() and others to configure the shader.

Image

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::Flat3D::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::Flat3D 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 multipled 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::Flat3D::Position{},
    Shaders::Flat3D::TextureCoordinates{})
    // ...
    ;

Common rendering setup:

Matrix4 transformationMatrix, projectionMatrix;
GL::Texture2D texture;

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

For coloring the texture based on intensity you can use the Vector shader. The 3D version of this shader is equivalent to Phong 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 VertexColor.

Alpha blending and masking

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::Flat3D shader{Shaders::Flat3D::Flag::ObjectId};

// ...

framebuffer.mapForDraw({
        {Shaders::Flat3D::ColorOutput, GL::Framebuffer::ColorAttachment{0}},
        {Shaders::Flat3D::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 output will contain a sum of the per-vertex 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::Flat3D::TransformationMatrix{},
        Shaders::Flat3D::Color3{});

Base classes

class Magnum::GL::AbstractShaderProgram
Base for shader program implementations.

Public types

enum (anonymous): UnsignedInt { ColorOutput = Generic<dimensions>::ColorOutput new in 2019.10, ObjectIdOutput = Generic<dimensions>::ObjectIdOutput new in 2019.10 }
enum class Flag: UnsignedByte { Textured = 1 << 0, AlphaMask = 1 << 1, VertexColor = 1 << 2 new in 2019.10, TextureTransformation = 1 << 3 new in Git master, ObjectId = 1 << 4 new in 2019.10, InstancedObjectId = (1 << 5)|ObjectId new in Git master, InstancedTransformation = 1 << 6 new in Git master, InstancedTextureOffset = (1 << 7)|TextureTransformation new in Git master }
Flag.
using Position = Generic<dimensions>::Position
Vertex position.
using TextureCoordinates = Generic<dimensions>::TextureCoordinates
2D texture coordinates
using Color3 = Generic<dimensions>::Color3 new in 2019.10
Three-component vertex color.
using Color4 = Generic<dimensions>::Color4 new in 2019.10
Four-component vertex color.
using ObjectId = Generic<dimensions>::ObjectId new in Git master
(Instanced) object ID
using TransformationMatrix = Generic<dimensions>::TransformationMatrix new in Git master
(Instanced) transformation matrix
using TextureOffset = Generic<dimensions>::TextureOffset new in Git master
(Instanced) texture offset
using Flags = Containers::EnumSet<Flag>
Flags.

Constructors, destructors, conversion operators

Flat(Flags flags = {}) explicit
Constructor.
Flat(NoCreateT) explicit noexcept
Construct without creating the underlying OpenGL object.
Flat(const Flat<dimensions>&) deleted
Copying is not allowed.
Flat(Flat<dimensions>&&) defaulted noexcept
Move constructor.

Public functions

auto operator=(const Flat<dimensions>&) -> Flat<dimensions>& deleted
Copying is not allowed.
auto operator=(Flat<dimensions>&&) -> Flat<dimensions>& defaulted noexcept
Move assignment.
auto flags() const -> Flags
Flags.
auto setTransformationProjectionMatrix(const MatrixTypeFor<dimensions, Float>& matrix) -> Flat<dimensions>&
Set transformation and projection matrix.
auto setTextureMatrix(const Matrix3& matrix) -> Flat<dimensions>& new in Git master
Set texture coordinate transformation matrix.
auto setColor(const Magnum::Color4& color) -> Flat<dimensions>&
Set color.
auto bindTexture(GL::Texture2D& texture) -> Flat<dimensions>&
Bind a color texture.
auto setAlphaMask(Float mask) -> Flat<dimensions>&
Set alpha mask value.
auto setObjectId(UnsignedInt id) -> Flat<dimensions>&
Set object ID.

Enum documentation

template<UnsignedInt dimensions>
enum Magnum::Shaders::Flat<dimensions>::(anonymous): UnsignedInt

Enumerators
ColorOutput new in 2019.10

Color shader output. Present always, expects three- or four-component floating-point or normalized buffer attachment.

ObjectIdOutput new in 2019.10

Object ID shader output. Generic output, present only if Flag::ObjectId is set. Expects a single-component unsigned integral attachment. Writes the value set in setObjectId() there, see Object ID output for more information.

template<UnsignedInt dimensions>
enum class Magnum::Shaders::Flat<dimensions>::Flag: UnsignedByte

Flag.

Enumerators
Textured

Multiply color with a texture.

AlphaMask

Enable alpha masking. If the combined fragment color has an alpha less than the value specified with setAlphaMask(), given fragment is discarded.

This uses the discard operation which is known to have considerable performance impact on some platforms. While useful for cheap alpha masking that doesn't require depth sorting, with proper depth sorting and blending you'll usually get much better performance and output quality.

VertexColor new in 2019.10

Multiply diffuse color with a vertex color. Requires either the Color3 or Color4 attribute to be present.

TextureTransformation new in Git master

Enable texture coordinate transformation. If this flag is set, the shader expects that Flag::Textured is enabled as well.

ObjectId new in 2019.10

Enable object ID output. See Object ID output for more information.

InstancedObjectId new in Git master

Instanced object ID. Retrieves a per-instance / per-vertex object ID from the ObjectId attribute, outputting a sum of the per-vertex ID and ID coming from setObjectId(). Implicitly enables Flag::ObjectId. See Object ID output for more information.

InstancedTransformation new in Git master

Instanced transformation. Retrieves a per-instance transformation matrix from the TransformationMatrix attribute and uses it together with the matrix coming from setTransformationProjectionMatrix() (first the per-instance, then the uniform matrix). See Instanced rendering for more information.

InstancedTextureOffset new in Git master

Instanced texture offset. Retrieves a per-instance offset vector from the TextureOffset attribute and uses it together with the matrix coming from setTextureMatrix() (first the per-instance vector, then the uniform matrix). Instanced texture scaling and rotation is not supported at the moment, you can specify that only via the uniform setTextureMatrix(). Implicitly enables Flag::TextureTransformation. See Instanced rendering for more information.

Typedef documentation

template<UnsignedInt dimensions>
typedef Generic<dimensions>::Position Magnum::Shaders::Flat<dimensions>::Position

Vertex position.

Generic attribute, Vector2 in 2D, Vector3 in 3D.

template<UnsignedInt dimensions>
typedef Generic<dimensions>::TextureCoordinates Magnum::Shaders::Flat<dimensions>::TextureCoordinates

2D texture coordinates

Generic attribute, Vector2. Used only if Flag::Textured is set.

template<UnsignedInt dimensions>
typedef Generic<dimensions>::Color3 Magnum::Shaders::Flat<dimensions>::Color3 new in 2019.10

Three-component vertex color.

Generic attribute, Magnum::Color3. Use either this or the Color4 attribute. Used only if Flag::VertexColor is set.

template<UnsignedInt dimensions>
typedef Generic<dimensions>::Color4 Magnum::Shaders::Flat<dimensions>::Color4 new in 2019.10

Four-component vertex color.

Generic attribute, Magnum::Color4. Use either this or the Color3 attribute. Used only if Flag::VertexColor is set.

template<UnsignedInt dimensions>
typedef Generic<dimensions>::ObjectId Magnum::Shaders::Flat<dimensions>::ObjectId new in Git master

(Instanced) object ID

Generic attribute, Magnum::UnsignedInt. Used only if Flag::InstancedObjectId is set.

template<UnsignedInt dimensions>
typedef Generic<dimensions>::TransformationMatrix Magnum::Shaders::Flat<dimensions>::TransformationMatrix new in Git master

(Instanced) transformation matrix

Generic attribute, Magnum::Matrix3 in 2D, Magnum::Matrix4 in 3D. Used only if Flag::InstancedTransformation is set.

template<UnsignedInt dimensions>
typedef Generic<dimensions>::TextureOffset Magnum::Shaders::Flat<dimensions>::TextureOffset new in Git master

(Instanced) texture offset

Generic attribute, Magnum::Vector2. Used only if Flag::InstancedTextureOffset is set.

template<UnsignedInt dimensions>
typedef Containers::EnumSet<Flag> Magnum::Shaders::Flat<dimensions>::Flags

Flags.

Function documentation

template<UnsignedInt dimensions>
Magnum::Shaders::Flat<dimensions>::Flat(Flags flags = {}) explicit

Constructor.

Parameters
flags Flags

template<UnsignedInt dimensions>
Magnum::Shaders::Flat<dimensions>::Flat(NoCreateT) explicit noexcept

Construct without creating the underlying OpenGL object.

The constructed instance is equivalent to a moved-from state. Useful in cases where you will overwrite the instance later anyway. Move another object over it to make it useful.

This function can be safely used for constructing (and later destructing) objects even without any OpenGL context being active. However note that this is a low-level and a potentially dangerous API, see the documentation of NoCreate for alternatives.

template<UnsignedInt dimensions>
Flat<dimensions>& Magnum::Shaders::Flat<dimensions>::setTransformationProjectionMatrix(const MatrixTypeFor<dimensions, Float>& matrix)

Set transformation and projection matrix.

Returns Reference to self (for method chaining)

Initial value is an identity matrix.

template<UnsignedInt dimensions>
Flat<dimensions>& Magnum::Shaders::Flat<dimensions>::setTextureMatrix(const Matrix3& matrix) new in Git master

Set texture coordinate transformation matrix.

Returns Reference to self (for method chaining)

Expects that the shader was created with Flag::TextureTransformation enabled. Initial value is an identity matrix.

template<UnsignedInt dimensions>
Flat<dimensions>& Magnum::Shaders::Flat<dimensions>::setColor(const Magnum::Color4& color)

Set color.

Returns Reference to self (for method chaining)

If Flag::Textured is set, initial value is 0xffffffff_rgbaf and the color will be multiplied with the texture.

template<UnsignedInt dimensions>
Flat<dimensions>& Magnum::Shaders::Flat<dimensions>::bindTexture(GL::Texture2D& texture)

Bind a color texture.

Returns Reference to self (for method chaining)

Expects that the shader was created with Flag::Textured enabled.

template<UnsignedInt dimensions>
Flat<dimensions>& Magnum::Shaders::Flat<dimensions>::setAlphaMask(Float mask)

Set alpha mask value.

Returns Reference to self (for method chaining)

Expects that the shader was created with Flag::AlphaMask enabled. Fragments with alpha values smaller than the mask value will be discarded. Initial value is 0.5f. See the flag documentation for further information.

template<UnsignedInt dimensions>
Flat<dimensions>& Magnum::Shaders::Flat<dimensions>::setObjectId(UnsignedInt id)

Set object ID.

Returns Reference to self (for method chaining)

Expects that the shader was created with Flag::ObjectId enabled. Value set here is written to the ObjectIdOutput, see Object ID output for more information. Default is 0. If Flag::InstancedObjectId is enabled as well, this value is combined with ID coming from the ObjectId attribute.

template<UnsignedInt dimensions> template<UnsignedInt dimensions>
Debug& operator<<(Debug& debug, Flat<dimensions>::Flag value)

Debug output operator.

template<UnsignedInt dimensions> template<UnsignedInt dimensions>
Debug& operator<<(Debug& debug, Flat<dimensions>::Flags value)

Debug output operator.