Magnum::Shaders::MeshVisualizer3D class

#include <Magnum/Shaders/MeshVisualizer.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). Additionaly, 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::MeshVisualizer3D::Position{});

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

Shaders::MeshVisualizer3D shader{Shaders::MeshVisualizer3D::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::MeshVisualizer3D::Position{});

Matrix4 transformationMatrix, projectionMatrix;

Shaders::MeshVisualizer3D shader{
    Shaders::MeshVisualizer3D::Flag::Wireframe|
    Shaders::MeshVisualizer3D::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::MeshVisualizer3D::VertexIndex{});

Tangent space visualization

On platforms with geometry shaders (desktop GL, OpenGL ES 3.2), the shader is able to visualize tangents, 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 visualization, however note that when both are enabled, the lines are not antialiased to avoid depth ordering artifacts.

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::MeshVisualizer3D::Position{},
    Shaders::MeshVisualizer3D::Tangent4{},
    Shaders::MeshVisualizer3D::Normal{});

Rendering setup:

Matrix4 transformationMatrix, projectionMatrix;

Shaders::MeshVisualizer3D shader{
    Shaders::MeshVisualizer3D::Flag::TangentDirection|
    Shaders::MeshVisualizer3D::Flag::BitangentFromTangentDirection|
    Shaders::MeshVisualizer3D::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::MeshVisualizer3D shader{
    Shaders::MeshVisualizer3D::Flag::InstancedObjectId};
shader.setColorMapTransformation(0.0f, 1.0f/Math::max(objectIds))
    .setTransformationMatrix(transformationMatrix)
    .setProjectionMatrix(projectionMatrix)
    .bindColorMapTexture(colorMapTexture)
    .draw(mesh);

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.

Public types

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

enum class Flag: UnsignedShort { Wireframe = 1 << 0, NoGeometryShader = 1 << 1, InstancedObjectId = 1 << 2 new in 2020.06, 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 }

Flag.

using Position = Generic3D::Position

Vertex position.

using Tangent = Generic3D::Tangent new in 2020.06

Tangent direction.

using Tangent4 = Generic3D::Tangent4 new in 2020.06

Tangent direction with a bitangent sign.

using Bitangent = Generic3D::Bitangent new in 2020.06

Bitangent direction.

using Normal = Generic3D::Normal new in 2020.06

Normal direction.

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

Vertex index.

using ObjectId = Generic3D::ObjectId new in 2020.06

(Instanced) object ID

using Flags = Containers::EnumSet<Flag>

Flags.

Constructors, destructors, conversion operators

MeshVisualizer3D(Flags flags) explicit

Constructor.

MeshVisualizer3D() deprecated in 2020.06 explicit

Constructor.

MeshVisualizer3D(NoCreateT) explicit noexcept

Construct without creating the underlying OpenGL object.

MeshVisualizer3D(const MeshVisualizer3D&) deleted

Copying is not allowed.

MeshVisualizer3D(MeshVisualizer3D&&) defaulted noexcept

Move constructor.

Public functions

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

Copying is not allowed.

auto operator=(MeshVisualizer3D&&) -> MeshVisualizer3D& defaulted noexcept

Move assignment.

auto flags() const -> Flags

Flags.

auto setTransformationProjectionMatrix(const Matrix4& matrix) -> MeshVisualizer3D& deprecated in 2020.06

Set transformation and projection matrix.

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

Set transformation matrix.

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

Set projection matrix.

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

Set transformation matrix.

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

Set viewport size.

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

Set base object color.

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

Set wireframe color.

auto setWireframeWidth(Float width) -> MeshVisualizer3D&

Set wireframe width.

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

Set color map transformation.

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

Bind a color map texture.

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

Set line width.

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

Set line length.

auto setSmoothness(Float smoothness) -> MeshVisualizer3D&

Set line smoothness.

Related

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

Debug output operator.

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

Debug output operator.

Enum documentation

Typedef documentation

Function documentation