#include <Magnum/Shaders/FlatGL.h>
template<UnsignedInt dimensions>
FlatGL class new in Git master
Flat OpenGL 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.

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::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::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::
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::
An alternative is to enable Flag::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::
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::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::
Instanced rendering
Enabling Flag::
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::Flag::UniformBuffers}; shader .bindTransformationProjectionBuffer(projectionTransformationUniform) .bindMaterialBuffer(materialUniform) .bindDrawBuffer(drawUniform) .draw(mesh);
For a multidraw workflow enable Flag::
Base classes
- class Magnum::GL::AbstractShaderProgram
- Base for shader program implementations.
Public types
- 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.
Constructors, destructors, conversion operators
- FlatGL(Flags flags = {}) explicit
- Constructor.
- FlatGL(Flags flags, UnsignedInt materialCount, UnsignedInt drawCount) explicit
- Construct for a multi-draw scenario.
- 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::
- 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.
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.
Enum documentation
template<UnsignedInt dimensions>
enum Magnum:: Shaders:: FlatGL<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:: |
template<UnsignedInt dimensions>
enum class Magnum:: Shaders:: FlatGL<dimensions>:: Flag: UnsignedShort
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 |
VertexColor new in 2019.10 |
Multiply the color with a vertex color. Requires either the Color3 or Color4 attribute to be present. |
TextureTransformation new in 2020.06 |
Enable texture coordinate transformation. If this flag is set, the shader expects that Flag:: |
ObjectId new in 2019.10 |
Enable object ID output. See Object ID output for more information. |
InstancedObjectId new in 2020.06 |
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() or FlatDrawUniform:: |
ObjectIdTexture new in Git master |
Object ID texture. Retrieves object IDs from a texture bound with bindObjectIdTexture(), outputting a sum of the object ID texture, the ID coming from setObjectId() or FlatDrawUniform:: |
InstancedTransformation new in 2020.06 |
Instanced transformation. Retrieves a per-instance transformation matrix from the TransformationMatrix attribute and uses it together with the matrix coming from setTransformationProjectionMatrix() or TransformationProjectionUniform2D:: |
InstancedTextureOffset new in 2020.06 |
Instanced texture offset. Retrieves a per-instance offset vector from the TextureOffset attribute and uses it together with the matrix coming from setTextureMatrix() or TextureTransformationUniform:: If Flag:: |
UniformBuffers new in Git master |
Use uniform buffers. Expects that uniform data are supplied via bindTransformationProjectionBuffer(), bindDrawBuffer(), bindTextureTransformationBuffer() and bindMaterialBuffer() instead of direct uniform setters. |
MultiDraw new in Git master |
Enable multidraw functionality. Implies Flag:: |
TextureArrays new in Git master |
Use 2D texture arrays. Expects that the texture is supplied via bindTexture(GL:: |
Typedef documentation
template<UnsignedInt dimensions>
typedef GenericGL<dimensions>::Position Magnum:: Shaders:: FlatGL<dimensions>:: Position
Vertex position.
Generic attribute, Vector2 in 2D, Vector3 in 3D.
template<UnsignedInt dimensions>
typedef GenericGL<dimensions>::TextureCoordinates Magnum:: Shaders:: FlatGL<dimensions>:: TextureCoordinates
2D texture coordinates
Generic attribute, Vector2. Used only if Flag::
template<UnsignedInt dimensions>
typedef GenericGL<dimensions>::Color3 Magnum:: Shaders:: FlatGL<dimensions>:: Color3 new in 2019.10
Three-component vertex color.
Generic attribute, Magnum::
template<UnsignedInt dimensions>
typedef GenericGL<dimensions>::Color4 Magnum:: Shaders:: FlatGL<dimensions>:: Color4 new in 2019.10
Four-component vertex color.
Generic attribute, Magnum::
template<UnsignedInt dimensions>
typedef GenericGL<dimensions>::ObjectId Magnum:: Shaders:: FlatGL<dimensions>:: ObjectId new in 2020.06
(Instanced) object ID
Generic attribute, Magnum::
template<UnsignedInt dimensions>
typedef GenericGL<dimensions>::TransformationMatrix Magnum:: Shaders:: FlatGL<dimensions>:: TransformationMatrix new in 2020.06
(Instanced) transformation matrix
Generic attribute, Magnum::
template<UnsignedInt dimensions>
typedef GenericGL<dimensions>::TextureOffset Magnum:: Shaders:: FlatGL<dimensions>:: TextureOffset new in 2020.06
(Instanced) texture offset
Generic attribute, Magnum::
template<UnsignedInt dimensions>
typedef GenericGL<dimensions>::TextureOffsetLayer Magnum:: Shaders:: FlatGL<dimensions>:: TextureOffsetLayer new in Git master
(Instanced) texture offset and layer
Generic attribute, Magnum::
template<UnsignedInt dimensions>
typedef Containers:: EnumSet<Flag> Magnum:: Shaders:: FlatGL<dimensions>:: Flags
Flags.
Function documentation
template<UnsignedInt dimensions>
Magnum:: Shaders:: FlatGL<dimensions>:: FlatGL(Flags flags = {}) explicit
Constructor.
Parameters | |
---|---|
flags | Flags |
While this function is meant mainly for the classic uniform scenario (without Flag::materialCount
and drawCount
set to 1
.
template<UnsignedInt dimensions>
Magnum:: Shaders:: FlatGL<dimensions>:: FlatGL(Flags flags,
UnsignedInt materialCount,
UnsignedInt drawCount) explicit
Construct for a multi-draw scenario.
Parameters | |
---|---|
flags | Flags |
materialCount | Size of a FlatMaterialUniform buffer bound with bindMaterialBuffer() |
drawCount | Size of a TransformationProjectionUniform2D / TransformationProjectionUniform3D / FlatDrawUniform / TextureTransformationUniform buffer bound with bindTransformationProjectionBuffer(), bindDrawBuffer() and bindTextureTransformationBuffer() |
If flags
contains Flag::materialCount
and drawCount
describe the uniform buffer sizes as these are required to have a statically defined size. The draw offset is then set via setDrawOffset() and the per-draw materials specified via FlatDrawUniform::
If flags
don't contain Flag::materialCount
and drawCount
is ignored and the constructor behaves the same as FlatGL(Flags).
template<UnsignedInt dimensions>
Magnum:: Shaders:: FlatGL<dimensions>:: FlatGL(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>
UnsignedInt Magnum:: Shaders:: FlatGL<dimensions>:: materialCount() const new in Git master
Material count.
Statically defined size of the FlatMaterialUniform uniform buffer. Has use only if Flag::
template<UnsignedInt dimensions>
UnsignedInt Magnum:: Shaders:: FlatGL<dimensions>:: drawCount() const new in Git master
Draw count.
Statically defined size of each of the TransformationProjectionUniform2D / TransformationProjectionUniform3D, FlatDrawUniform and TextureTransformationUniform uniform buffers. Has use only if Flag::
template<UnsignedInt dimensions>
FlatGL<dimensions>& Magnum:: Shaders:: FlatGL<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. If Flag::
Expects that Flag::
template<UnsignedInt dimensions>
FlatGL<dimensions>& Magnum:: Shaders:: FlatGL<dimensions>:: setTextureMatrix(const Matrix3& matrix) new in 2020.06
Set texture coordinate transformation matrix.
Returns | Reference to self (for method chaining) |
---|
Expects that the shader was created with Flag::
Expects that Flag::
template<UnsignedInt dimensions>
FlatGL<dimensions>& Magnum:: Shaders:: FlatGL<dimensions>:: setTextureLayer(UnsignedInt layer) new in Git master
Set texture array layer.
Returns | Reference to self (for method chaining) |
---|
Expects that the shader was created with Flag::0
. If Flag::
Expects that Flag::
template<UnsignedInt dimensions>
FlatGL<dimensions>& Magnum:: Shaders:: FlatGL<dimensions>:: setColor(const Magnum:: Color4& color)
Set color.
Returns | Reference to self (for method chaining) |
---|
Initial value is 0xffffffff_rgbaf
. If Flag::
Expects that Flag::
template<UnsignedInt dimensions>
FlatGL<dimensions>& Magnum:: Shaders:: FlatGL<dimensions>:: setAlphaMask(Float mask)
Set alpha mask value.
Returns | Reference to self (for method chaining) |
---|
Expects that the shader was created with Flag::0.5f
. See the flag documentation for further information.
This corresponds to glAlphaFunc() in classic OpenGL.
Expects that Flag::
template<UnsignedInt dimensions>
FlatGL<dimensions>& Magnum:: Shaders:: FlatGL<dimensions>:: setObjectId(UnsignedInt id)
Set object ID.
Returns | Reference to self (for method chaining) |
---|
Expects that the shader was created with Flag::0
. If Flag::
Expects that Flag::
template<UnsignedInt dimensions>
FlatGL<dimensions>& Magnum:: Shaders:: FlatGL<dimensions>:: setDrawOffset(UnsignedInt offset) new in Git master
Set a draw offset.
Returns | Reference to self (for method chaining) |
---|
Specifies which item in the TransformationProjectionUniform2D / TransformationProjectionUniform3D, FlatDrawUniform and TextureTransformationUniform buffers bound with bindTransformationProjectionBuffer(), bindDrawBuffer() and bindTextureTransformationBuffer() should be used for current draw. Expects that Flag::offset
is less than drawCount(). Initial value is 0
, if drawCount() is 1
, the function is a no-op as the shader assumes draw offset to be always zero.
If Flag::gl_DrawID
is added to this value, which makes each draw submitted via GL::
template<UnsignedInt dimensions>
FlatGL<dimensions>& Magnum:: Shaders:: FlatGL<dimensions>:: bindTransformationProjectionBuffer(GL:: Buffer& buffer) new in Git master
Set a transformation and projection uniform buffer.
Returns | Reference to self (for method chaining) |
---|
Expects that Flag::
template<UnsignedInt dimensions>
FlatGL<dimensions>& Magnum:: Shaders:: FlatGL<dimensions>:: bindTransformationProjectionBuffer(GL:: Buffer& buffer,
GLintptr offset,
GLsizeiptr size) new in Git master
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
template<UnsignedInt dimensions>
FlatGL<dimensions>& Magnum:: Shaders:: FlatGL<dimensions>:: bindDrawBuffer(GL:: Buffer& buffer) new in Git master
Set a draw uniform buffer.
Returns | Reference to self (for method chaining) |
---|
Expects that Flag::
template<UnsignedInt dimensions>
FlatGL<dimensions>& Magnum:: Shaders:: FlatGL<dimensions>:: bindDrawBuffer(GL:: Buffer& buffer,
GLintptr offset,
GLsizeiptr size) new in Git master
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
template<UnsignedInt dimensions>
FlatGL<dimensions>& Magnum:: Shaders:: FlatGL<dimensions>:: bindTextureTransformationBuffer(GL:: Buffer& buffer) new in Git master
Set a texture transformation uniform buffer.
Returns | Reference to self (for method chaining) |
---|
Expects that both Flag::
template<UnsignedInt dimensions>
FlatGL<dimensions>& Magnum:: Shaders:: FlatGL<dimensions>:: bindTextureTransformationBuffer(GL:: Buffer& buffer,
GLintptr offset,
GLsizeiptr size) new in Git master
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
template<UnsignedInt dimensions>
FlatGL<dimensions>& Magnum:: Shaders:: FlatGL<dimensions>:: bindMaterialBuffer(GL:: Buffer& buffer) new in Git master
Set a material uniform buffer.
Returns | Reference to self (for method chaining) |
---|
Expects that Flag::
template<UnsignedInt dimensions>
FlatGL<dimensions>& Magnum:: Shaders:: FlatGL<dimensions>:: bindMaterialBuffer(GL:: Buffer& buffer,
GLintptr offset,
GLsizeiptr size) new in Git master
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
template<UnsignedInt dimensions>
FlatGL<dimensions>& Magnum:: Shaders:: FlatGL<dimensions>:: bindTexture(GL:: Texture2D& texture)
Bind a color texture.
Returns | Reference to self (for method chaining) |
---|
Expects that the shader was created with Flag::
template<UnsignedInt dimensions>
FlatGL<dimensions>& Magnum:: Shaders:: FlatGL<dimensions>:: bindTexture(GL:: Texture2DArray& texture) new in Git master
Bind a color array texture.
Returns | Reference to self (for method chaining) |
---|
Expects that the shader was created with both Flag::
template<UnsignedInt dimensions>
FlatGL<dimensions>& Magnum:: Shaders:: FlatGL<dimensions>:: bindObjectIdTexture(GL:: Texture2D& texture) new in Git master
Bind an object ID texture.
Returns | Reference to self (for method chaining) |
---|
Expects that the shader was created with Flag::
template<UnsignedInt dimensions>
FlatGL<dimensions>& Magnum:: Shaders:: FlatGL<dimensions>:: bindObjectIdTexture(GL:: Texture2DArray& texture) new in Git master
Bind an object ID array texture.
Returns | Reference to self (for method chaining) |
---|
Expects that the shader was created with both Flag::
template<UnsignedInt dimensions>
template<UnsignedInt dimensions>
Debug& operator<<(Debug& debug,
FlatGL<dimensions>::Flag value)
Debug output operator.
template<UnsignedInt dimensions>
template<UnsignedInt dimensions>
Debug& operator<<(Debug& debug,
FlatGL<dimensions>::Flags value)
Debug output operator.