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::Configuration{}
    .setFlags(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::Configuration{}
    .setFlags(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::Configuration{}
    .setFlags(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::Configuration{}
    .setFlags(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.

Skinning

To render skinned meshes, bind up to two sets of up to four-component joint ID and weight attributes to JointIds / SecondaryJointIds and Weights / SecondaryWeights, set an appropriate joint count and per-vertex primary and secondary joint count in Configuration::setJointCount() and upload appropriate joint matrices with setJointMatrices(). The usage is similar for all shaders, see Skinning for an example. Currently, the mesh visualizer supports only transforming the mesh vertices for feature parity with other shaders, no skinning-specific visualization feature is implemented.

To avoid having to compile multiple shader variants for different joint matrix counts, set the maximum used joint count in Configuration::setJointCount() and then upload just a prefix via setJointMatrices(). Similarly, to avoid multiple variants for different per-vertex joint counts, enable Flag::DynamicPerVertexJointCount, set the maximum per-vertex joint count in Configuration::setJointCount() and then adjust the actual per-draw joint count with setPerVertexJointCount().

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).

For instanced skinning the joint buffer is assumed to contain joint transformations for all instances. By default all instances use the same joint transformations, seting setPerInstanceJointCount() will cause the shader to offset the per-vertex joint IDs with gl_InstanceID*perInstanceJointCount.

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 bound with bindProjectionBuffer() and bindTransformationBuffer(), respectively. To maximize use of the limited uniform buffer memory, materials are supplied separately in a MeshVisualizerMaterialUniform buffer bound with bindMaterialBuffer() and then referenced via materialId from a MeshVisualizerDrawUniform3D buffer bound with bindDrawBuffer(); for optional texture transformation a per-draw TextureTransformationUniform buffer bound with bindTextureTransformationBuffer() can be supplied as well. 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::Configuration{}
    .setFlags(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 via Configuration::setMaterialCount() and setDrawCount() and specify material references for every draw. The usage is similar for all shaders, see Multidraw and reducing driver overhead for an example.

For skinning, joint matrices are supplied via a TransformationUniform3D buffer bound with bindJointBuffer(). In an instanced scenario the per-instance joint count is supplied via MeshVisualizerDrawUniform3D::perInstanceJointCount, a per-draw joint offset for the multidraw scenario is supplied via MeshVisualizerDrawUniform3D::jointOffset. Altogether for a particular draw, each per-vertex joint ID is offset with gl_InstanceID*perInstanceJointCount + jointOffset. The setPerVertexJointCount() stays as an immediate uniform in the UBO and multidraw scenario as well, as it is tied to a particular mesh layout and thus doesn't need to vary per draw.

Derived classes

class Magnum::Shaders::MeshVisualizerGL3D::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 = 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, DynamicPerVertexJointCount = 1 << 18 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 JointIds = GenericGL3D::JointIds new in Git master

Joint ids.

using Weights = GenericGL3D::Weights new in Git master

Weights.

using SecondaryJointIds = GenericGL3D::SecondaryJointIds new in Git master

Secondary joint ids.

using SecondaryWeights = GenericGL3D::SecondaryWeights new in Git master

Secondary weights.

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.

Public static functions

static auto compile(const 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

MeshVisualizerGL3D(const Configuration& configuration) explicit new in Git master

Constructor.

MeshVisualizerGL3D() deprecated in 2020.06 explicit

Constructor.

MeshVisualizerGL3D(Flags flags) deprecated in Git master explicit

Constructor.

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

Construct for a multi-draw scenario.

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

Finalize an asynchronous compilation.

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 jointCount() const -> UnsignedInt new in Git master

Joint count.

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

Per-vertex joint count.

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

Secondary per-vertex joint count.

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

Material count.

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

Draw count.

auto setPerVertexJointCount(UnsignedInt count, UnsignedInt secondaryCount = 0) -> MeshVisualizerGL3D& new in Git master

Set dynamic per-vertex skinning joint 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.

auto setJointMatrices(const Containers::ArrayView<const Matrix4> matrices) -> MeshVisualizerGL3D& new in Git master

Set joint matrices.

auto setJointMatrices(std::initializer_list<Matrix4> matrices) -> MeshVisualizerGL3D& new in Git master

auto setJointMatrix(UnsignedInt id, const Matrix4& matrix) -> MeshVisualizerGL3D& new in Git master

Set joint matrix for given joint.

auto setPerInstanceJointCount(UnsignedInt count) -> MeshVisualizerGL3D& new in Git master

Set per-instance joint count.

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

Bind 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

Bind 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

Bind 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

Bind 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

Bind a material uniform buffer.

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

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

Bind a joint matrix uniform buffer.

auto bindJointBuffer(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