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

#include <Magnum/Shaders/MeshVisualizerGL.h>

Wireframe visualization

Wireframe visualization is done by enabling Flag::Wireframe. It is done either using geometry shaders or with help of additional vertex information. If you have geometry shaders available, you don't need to do anything else except calling setViewportSize() to correctly size the wireframe — without this, the mesh will be rendered in a single color.

If you don't have geometry shaders, you need to enable Flag::NoGeometryShader (done by default in OpenGL ES 2.0) and use only non-indexed triangle meshes (see MeshTools::duplicate() for a possible solution). Additionally, if you have OpenGL < 3.1 or OpenGL ES 2.0, you need to provide also the VertexIndex attribute.

If using geometry shaders on OpenGL ES, NV_shader_noperspective_interpolation is optionally used for improving line appearance. On desktop OpenGL this is done implicitly.

If you want to render just the wireframe on top of an existing mesh, call setColor() with 0x00000000_rgbaf. 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.

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

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

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

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

Shaders::MeshVisualizerGL3D shader{Shaders::MeshVisualizerGL3D::Flag::Wireframe};
shader.setColor(0x2f83cc_rgbf)
    .setWireframeColor(0xdcdcdc_rgbf)
    .setViewportSize(Vector2{GL::defaultFramebuffer.viewport().size()})
    .setTransformationMatrix(transformationMatrix)
    .setProjectionMatrix(projectionMatrix)
    .draw(mesh);

Containers::StridedArrayView1D<const UnsignedInt> indices;
Containers::StridedArrayView1D<const Vector3> indexedPositions;

/* De-indexing the position array */
GL::Buffer vertices{MeshTools::duplicate(indices, indexedPositions)};

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

Matrix4 transformationMatrix, projectionMatrix;

Shaders::MeshVisualizerGL3D shader{
    Shaders::MeshVisualizerGL3D::Flag::Wireframe|
    Shaders::MeshVisualizerGL3D::Flag::NoGeometryShader};
shader.setColor(0x2f83cc_rgbf)
    .setWireframeColor(0xdcdcdc_rgbf)
    .setTransformationMatrix(transformationMatrix)
    .setProjectionMatrix(projectionMatrix)
    .draw(mesh);

Containers::Array<Float> vertexIndex{Containers::arraySize(data)};
std::iota(vertexIndex.begin(), vertexIndex.end(), 0.0f);

GL::Buffer vertexIndices;
vertexIndices.setData(vertexIndex, GL::BufferUsage::StaticDraw);

mesh.addVertexBuffer(vertexIndices, 0, Shaders::MeshVisualizerGL3D::VertexIndex{});

Tangent space visualization

On platforms with geometry shaders (desktop GL, OpenGL ES 3.2), the shader is able to visualize tangent, bitangent and normal direction via colored lines coming out of vertices (red, green and blue for tangent, bitangent and normal, respectively). This can be enabled together with wireframe, object ID, vertex ID or primitive ID visualization, however note that when both are enabled, the lines are not antialiased to avoid depth ordering artifacts between faces and lines.

For tangents and normals, you need to provide the Tangent and Normal attributes and enable Flag::TangentDirection and Flag::NormalDirection, respectively. If any of the attributes isn't present, its data are implicitly zero and thus the direction isn't shown — which means you don't need to worry about having two active variants of the shader and switching between either depending on whether tangents are present or not.

For bitangents however, there are two possible representations — the more efficient one is via a fourth component in the tangent attribute that indicates tangent space handedness, in which case you'll be using the Tangent4 attribute instead of Tangent, and enable Flag::BitangentFromTangentDirection. The other, more obvious but less efficient representation, is a dedicated Bitangent attribute (in which case you'll enable Flag::BitangentDirection). Note that these two are mutually exclusive, so you need to choose either of them based on what given mesh contains. Example for the first case:

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

GL::Buffer vertices;
vertices.setData(data);

GL::Mesh mesh;
mesh.addVertexBuffer(vertices, 0,
    Shaders::MeshVisualizerGL3D::Position{},
    Shaders::MeshVisualizerGL3D::Tangent4{},
    Shaders::MeshVisualizerGL3D::Normal{});

Rendering setup:

Matrix4 transformationMatrix, projectionMatrix;

Shaders::MeshVisualizerGL3D shader{
    Shaders::MeshVisualizerGL3D::Flag::TangentDirection|
    Shaders::MeshVisualizerGL3D::Flag::BitangentFromTangentDirection|
    Shaders::MeshVisualizerGL3D::Flag::NormalDirection};
shader.setViewportSize(Vector2{GL::defaultFramebuffer.viewport().size()})
    .setTransformationMatrix(transformationMatrix)
    .setProjectionMatrix(projectionMatrix)
    .setNormalMatrix(transformationMatrix.normalMatrix())
    .setLineLength(0.3f)
    .draw(mesh);

Object, vertex and primitive ID visualization

If the mesh contains a per-vertex (or instanced) ObjectId, it can be visualized by enabling Flag::InstancedObjectId. For the actual visualization you need to provide a color map using bindColorMapTexture() and use setColorMapTransformation() to map given range of discrete IDs to the texture range. Various colormap presets are in the DebugTools::ColorMap namespace. Example usage:

const auto map = DebugTools::ColorMap::turbo();
const Vector2i size{Int(map.size()), 1};

GL::Texture2D colorMapTexture;
colorMapTexture
    .setMinificationFilter(SamplerFilter::Linear)
    .setMagnificationFilter(SamplerFilter::Linear)
    .setWrapping(SamplerWrapping::ClampToEdge)
    .setStorage(1, GL::TextureFormat::RGBA8, size)
    .setSubImage(0, {}, ImageView2D{PixelFormat::RGB8Srgb, size, map});

Shaders::MeshVisualizerGL3D shader{
    Shaders::MeshVisualizerGL3D::Flag::InstancedObjectId};
shader.setColorMapTransformation(0.0f, 1.0f/Math::max(objectIds))
    .setTransformationMatrix(transformationMatrix)
    .setProjectionMatrix(projectionMatrix)
    .bindColorMapTexture(colorMapTexture)
    .draw(mesh);

Consistently with the other shaders, textured object ID is also supported if Flag::ObjectIdTexture is enabled. In that case you need to provide also the TextureCoordinates attribute and bind an integer texture via bindObjectIdTexture(). Flag::TextureTransformation then enables texture transformation and Flag::TextureArrays texture arrays for the object ID texture.

If you enable Flag::VertexId, the shader will use the color map to visualize how are vertices shared among primitives. That's useful for inspecting mesh connectivity — primitives sharing vertices will have a smooth color map transition while duplicated vertices will cause a sharp edge. This relies on the gl_VertexID GLSL builtin.

The Flag::PrimitiveId then visualizes the order in which primitives are drawn. That's useful for example to see to see how well is the mesh optimized for a post-transform vertex cache. This by default relies on the gl_PrimitiveID GLSL builtin; with Flag::PrimitiveIdFromVertexId it's emulated using gl_VertexID, expecting you to draw a non-indexed triangle mesh. You can use MeshTools::duplicate() (and potentially MeshTools::generateIndices()) to conveniently convert the mesh to a non-indexed MeshPrimitive::Triangles.

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 setTransformationMatrix(). If one of Flag::TangentDirection, Flag::BitangentDirection or Flag::NormalDirection is set, additionally also a normal matrix from the NormalMatrix attribute is taken, applied before the matrix set by setNormalMatrix(). The snippet below shows adding a buffer with per-instance transformation to a mesh, including a normal matrix attribute for correct TBN visualization:

struct {
    Matrix4 transformation;
    Matrix3x3 normal;
} instanceData[] {
    {Matrix4::translation({1.0f, 2.0f, 0.0f}), {}},
    {Matrix4::translation({2.0f, 1.0f, 0.0f}), {}},
    {Matrix4::translation({3.0f, 0.0f, 1.0f}), {}},
    // ...
};
for(auto& instance: instanceData)
    instance.normal = instance.transformation.normalMatrix();

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

If Flag::ObjectIdTexture is used and Flag::InstancedTextureOffset is enabled, the TextureOffset attribute (or TextureOffsetLayer in case Flag::TextureArrays is enabled as well) then can supply per-instance texture offset (or offset and layer).

Uniform buffers

See Using uniform buffers for a high-level overview that applies to all shaders. In this particular case, the shader needs a separate ProjectionUniform3D and TransformationUniform3D buffer. To maximize use of the limited uniform buffer memory, materials are supplied separately in a MeshVisualizerMaterialUniform and then referenced via materialId from a MeshVisualizerDrawUniform3D. A uniform buffer setup equivalent to the wireframe case at the top would look like this — note that setViewportSize() is an immediate uniform here as well, as it's assumed to be set globally and rarely changed:

GL::Buffer projectionUniform, materialUniform, transformationUniform,
    drawUniform;
projectionUniform.setData({
    Shaders::ProjectionUniform3D{}
        .setProjectionMatrix(projectionMatrix)
});
materialUniform.setData({
    Shaders::MeshVisualizerMaterialUniform{}
        .setColor(0x2f83cc_rgbf)
        .setWireframeColor(0xdcdcdc_rgbf)
});
transformationUniform.setData({
    Shaders::TransformationUniform3D{}
        .setTransformationMatrix(transformationMatrix)
});
drawUniform.setData({
    Shaders::MeshVisualizerDrawUniform3D{}
        .setMaterialId(0)
});

Shaders::MeshVisualizerGL3D shader{
    Shaders::MeshVisualizerGL3D::Flag::Wireframe|
    Shaders::MeshVisualizerGL3D::Flag::UniformBuffers
};
shader
    .setViewportSize(Vector2{GL::defaultFramebuffer.viewport().size()})
    .bindProjectionBuffer(projectionUniform)
    .bindMaterialBuffer(materialUniform)
    .bindTransformationBuffer(transformationUniform)
    .bindDrawBuffer(drawUniform)
    .draw(mesh);

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

Public types

enum (anonymous): UnsignedInt { ColorOutput = GenericGL3D::ColorOutput }

enum class Flag: UnsignedInt { Wireframe = 1 << 0, NoGeometryShader = 1 << 1, ObjectId = 1 << 12 new in Git master, InstancedObjectId = (1 << 2)|ObjectId new in 2020.06, ObjectIdTexture = (1 << 14)|ObjectId new in Git master, VertexId = 1 << 3 new in 2020.06, PrimitiveId = 1 << 4 new in 2020.06, PrimitiveIdFromVertexId = (1 << 5)|PrimitiveId new in 2020.06, TangentDirection = 1 << 6 new in 2020.06, BitangentFromTangentDirection = 1 << 7 new in 2020.06, BitangentDirection = 1 << 8 new in 2020.06, NormalDirection = 1 << 9 new in 2020.06, InstancedTransformation = 1 << 13 new in Git master, TextureTransformation = 1 << 15 new in Git master, InstancedTextureOffset = (1 << 16)|TextureTransformation new in Git master, UniformBuffers = 1 << 10 new in Git master, MultiDraw = UniformBuffers|(1 << 11) new in Git master, TextureArrays = 1 << 17 new in Git master }

Flag.

using Position = GenericGL3D::Position

Vertex position.

using Tangent = GenericGL3D::Tangent new in 2020.06

Tangent direction.

using Tangent4 = GenericGL3D::Tangent4 new in 2020.06

Tangent direction with a bitangent sign.

using Bitangent = GenericGL3D::Bitangent new in 2020.06

Bitangent direction.

using Normal = GenericGL3D::Normal new in 2020.06

Normal direction.

using TextureCoordinates = GenericGL3D::TextureCoordinates new in Git master

2D texture coordinates

using VertexIndex = GL::Attribute<4, Float>

Vertex index.

using ObjectId = GenericGL3D::ObjectId new in 2020.06

(Instanced) object ID

using TransformationMatrix = GenericGL3D::TransformationMatrix new in Git master

(Instanced) transformation matrix

using NormalMatrix = GenericGL3D::NormalMatrix new in Git master

(Instanced) normal matrix

using TextureOffset = GenericGL3D::TextureOffset new in Git master

(Instanced) texture offset for an object ID texture

using TextureOffsetLayer = GenericGL3D::TextureOffsetLayer new in Git master

(Instanced) texture offset and layer for an object ID texture

using Flags = Containers::EnumSet<Flag>

Flags.

Constructors, destructors, conversion operators

MeshVisualizerGL3D(Flags flags) explicit

Constructor.

MeshVisualizerGL3D() deprecated in 2020.06 explicit

Constructor.

MeshVisualizerGL3D(Flags flags, UnsignedInt materialCount, UnsignedInt drawCount) explicit

Construct for a multi-draw scenario.

MeshVisualizerGL3D(NoCreateT) explicit noexcept

Construct without creating the underlying OpenGL object.

MeshVisualizerGL3D(const MeshVisualizerGL3D&) deleted

Copying is not allowed.

MeshVisualizerGL3D(MeshVisualizerGL3D&&) defaulted noexcept

Move constructor.

Public functions

auto operator=(const MeshVisualizerGL3D&) -> MeshVisualizerGL3D& deleted

Copying is not allowed.

auto operator=(MeshVisualizerGL3D&&) -> MeshVisualizerGL3D& 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 Matrix4& matrix) -> MeshVisualizerGL3D& deprecated in 2020.06

Set transformation and projection matrix.

auto setTransformationMatrix(const Matrix4& matrix) -> MeshVisualizerGL3D&

Set transformation matrix.

auto setProjectionMatrix(const Matrix4& matrix) -> MeshVisualizerGL3D&

Set projection matrix.

auto setNormalMatrix(const Matrix3x3& matrix) -> MeshVisualizerGL3D& new in 2020.06

Set transformation matrix.

auto setTextureMatrix(const Matrix3& matrix) -> MeshVisualizerGL3D& new in Git master

Set texture coordinate transformation matrix for an object ID texture.

auto setTextureLayer(UnsignedInt layer) -> MeshVisualizerGL3D& new in Git master

Set texture array layer for an object ID texture.

auto setViewportSize(const Vector2& size) -> MeshVisualizerGL3D&

Set viewport size.

auto setObjectId(UnsignedInt id) -> MeshVisualizerGL3D& new in Git master

Set object ID.

auto setColor(const Color4& color) -> MeshVisualizerGL3D&

Set base object color.

auto setWireframeColor(const Color4& color) -> MeshVisualizerGL3D&

Set wireframe color.

auto setWireframeWidth(Float width) -> MeshVisualizerGL3D&

Set wireframe width.

auto setColorMapTransformation(Float offset, Float scale) -> MeshVisualizerGL3D& new in 2020.06

Set color map transformation.

auto setLineWidth(Float width) -> MeshVisualizerGL3D& new in 2020.06

Set line width.

auto setLineLength(Float length) -> MeshVisualizerGL3D& new in 2020.06

Set line length.

auto setSmoothness(Float smoothness) -> MeshVisualizerGL3D&

Set line smoothness.

Uniform buffer binding and related uniform setters

Used if Flag::UniformBuffers is set.

auto setDrawOffset(UnsignedInt offset) -> MeshVisualizerGL3D& new in Git master

Set a draw offset.

auto bindProjectionBuffer(GL::Buffer& buffer) -> MeshVisualizerGL3D& new in Git master

Set a projection uniform buffer.

auto bindProjectionBuffer(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size) -> MeshVisualizerGL3D& new in Git master

auto bindTransformationBuffer(GL::Buffer& buffer) -> MeshVisualizerGL3D& new in Git master

Set a transformation uniform buffer.

auto bindTransformationBuffer(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size) -> MeshVisualizerGL3D& new in Git master

auto bindDrawBuffer(GL::Buffer& buffer) -> MeshVisualizerGL3D& new in Git master

Set a draw uniform buffer.

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

auto bindTextureTransformationBuffer(GL::Buffer& buffer) -> MeshVisualizerGL3D& new in Git master

Set a texture transformation uniform buffer for an object ID texture.

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

auto bindMaterialBuffer(GL::Buffer& buffer) -> MeshVisualizerGL3D& new in Git master

Set a material uniform buffer.

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

Texture binding

auto bindColorMapTexture(GL::Texture2D& texture) -> MeshVisualizerGL3D& new in 2020.06

Bind a color map texture.

auto bindObjectIdTexture(GL::Texture2D& texture) -> MeshVisualizerGL3D& new in Git master

Bind an object ID texture.

auto bindObjectIdTexture(GL::Texture2DArray& texture) -> MeshVisualizerGL3D& new in Git master

Bind an object ID array texture.

Related

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

Debug output operator.

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

Debug output operator.

Enum documentation

Typedef documentation

Function documentation