Magnum::MeshTools namespace

enum class Magnum::MeshTools::CompileFlag: UnsignedByte new in 2019.10

#include <Magnum/MeshTools/Compile.h>

Mesh compilation flag.

typedef Containers::EnumSet<CompileFlag> Magnum::MeshTools::CompileFlags new in 2019.10

#include <Magnum/MeshTools/Compile.h>

Mesh compilation flags.

std::vector<UnsignedInt> Magnum::MeshTools::combineIndexArrays(const std::vector<std::reference_wrapper<std::vector<UnsignedInt>>>& arrays)

#include <Magnum/MeshTools/CombineIndexedArrays.h>

Combine index arrays.

Creates new combined index array and updates the original ones with translation to new ones. For example, when you have position and normal array, each indexed with separate indices and you want to index both of them with single index array:

a b c d e f         // positions
A B C D E F G       // normals

0 2 5 0 0 1 3 2 2   // position indices
1 3 4 1 4 6 1 3 1   // normal indices

In particular, first triangle in the mesh will have positions a c f and normals B D E. You can see that not all combinations are unique and also that there are some vertices unused. When you pass the two index arrays above to this function, the following combined index array is returned:

0 1 2 0 3 4 5 1 6

And the original arrays are cleaned up to have only unique combinations:

0 2 5 0 1 3 2
1 3 4 4 6 1 1

You can use these as translation table to create new vertex and normal arrays which can be then indexed with the combined index array:

a c f a b d c
B D E E G B B

Again, first triangle in the mesh will have positions a c f and normals B D E.

This function calls combineIndexArrays(const std::vector<UnsignedInt>&, UnsignedInt) internally. See also combineIndexedArrays() which does the vertex data reordering automatically.

std::vector<UnsignedInt> Magnum::MeshTools::combineIndexArrays(std::initializer_list<std::reference_wrapper<std::vector<UnsignedInt>>> arrays)

#include <Magnum/MeshTools/CombineIndexedArrays.h>

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

std::pair<std::vector<UnsignedInt>, std::vector<UnsignedInt>> Magnum::MeshTools::combineIndexArrays(const std::vector<UnsignedInt>& interleavedArrays, UnsignedInt stride)

#include <Magnum/MeshTools/CombineIndexedArrays.h>

Combine interleaved index arrays.

Unlike above, this function takes one interleaved array instead of separate index arrays. Continuing with the above example, you would call this function with the following array (odd value is vertex index, even is normal index, stride is thus 2):

0 1 2 3 5 4 0 1 0 4 1 6 3 1 2 3 2 1

Similarly to above this function will return the following combined index array as first pair value:

0 1 2 0 3 4 5 1 6

And second pair value is the cleaned up interleaved array:

0 1 2 3 5 4 0 4 1 6 3 1 2 1

#include <Magnum/MeshTools/CombineIndexedArrays.h>

template<class ... T>

std::vector<UnsignedInt> Magnum::MeshTools::combineIndexedArrays(const std::pair<const std::vector<UnsignedInt>&, std::vector<T>&>&... indexedArrays)

Combine indexed arrays.

Creates new combined index array and reorders original attribute arrays so they can be indexed with the new single index array.

The index array must be passed as const reference (to avoid copying) and attribute array as reference, so it can be replaced with combined data. To avoid explicit verbose specification of tuple type, you can write it with help of some STL functions like shown below. Also if one index array is shared by more than one attribute array, just pass the index array more times. Example:

std::vector<UnsignedInt> vertexIndices;
std::vector<Vector3> positions;
std::vector<UnsignedInt> normalTextureIndices;
std::vector<Vector3> normals;
std::vector<Vector2> textureCoordinates;

std::vector<UnsignedInt> indices = MeshTools::combineIndexedArrays(
    std::make_pair(std::cref(vertexIndices), std::ref(positions)),
    std::make_pair(std::cref(normalTextureIndices), std::ref(normals)),
    std::make_pair(std::cref(normalTextureIndices), std::ref(textureCoordinates))
);

See combineIndexArrays() documentation for more information about the procedure.

GL::Mesh Magnum::MeshTools::compile(const Trade::MeshData2D& meshData)

#include <Magnum/MeshTools/Compile.h>

Compile 2D mesh data.

Configures a mesh for Shaders::Generic2D shader with vertex buffer and possibly also an index buffer, if the mesh is indexed. Positions are bound to Shaders::Generic2D::Position attribute. If the mesh contains texture coordinates, these are bound to Shaders::Generic2D::TextureCoordinates attribute. If the mesh contains colors, these are bound to Shaders::Generic3D::Color4 attribute. No data compression or index optimization (except for index buffer packing) is done, both the vertex buffer and the index buffer (if any) is owned by the mesh, both created with GL::BufferUsage::StaticDraw.

This is just a convenience function for creating generic meshes, you might want to use interleave() and compressIndices() functions together with GL::Mesh::setPrimitive(), GL::Mesh::setCount(), GL::Mesh::addVertexBuffer(), GL::Mesh::setIndexBuffer() instead for greater flexibility.

std::tuple<GL::Mesh, std::unique_ptr<GL::Buffer>, std::unique_ptr<GL::Buffer>> Magnum::MeshTools::compile(const Trade::MeshData2D& meshData, GL::BufferUsage usage)

#include <Magnum/MeshTools/Compile.h>

Compile 2D mesh data.

GL::Mesh Magnum::MeshTools::compile(const Trade::MeshData3D& meshData, CompileFlags flags = {})

#include <Magnum/MeshTools/Compile.h>

Compile 3D mesh data.

Configures mesh for Shaders::Generic3D shader with vertex buffer and possibly also index buffer, if the mesh is indexed. Positions are bound to Shaders::Generic3D::Position attribute. If the mesh contains normals, they are bound to Shaders::Generic3D::Normal attribute, texture coordinates are bound to Shaders::Generic3D::TextureCoordinates attribute. If the mesh contains colors, they are bound to Shaders::Generic3D::Color4 attribute. No data compression or index optimization (except for index buffer packing) is done, both the vertex buffer and the index buffer (if any) is owned by the mesh, both created with GL::BufferUsage::StaticDraw.

This is just a convenience function for creating generic meshes, you might want to use interleave() and compressIndices() functions together with GL::Mesh::setPrimitive(), GL::Mesh::setCount(), GL::Mesh::addVertexBuffer(), GL::Mesh::setIndexBuffer() instead for greater flexibility.

std::tuple<GL::Mesh, std::unique_ptr<GL::Buffer>, std::unique_ptr<GL::Buffer>> Magnum::MeshTools::compile(const Trade::MeshData3D& meshData, GL::BufferUsage usage)

#include <Magnum/MeshTools/Compile.h>

Compile 3D mesh data.

std::tuple<Containers::Array<char>, MeshIndexType, UnsignedInt, UnsignedInt> Magnum::MeshTools::compressIndices(const std::vector<UnsignedInt>& indices)

#include <Magnum/MeshTools/CompressIndices.h>

Compress vertex indices.

This function takes index array and outputs them compressed to smallest possible size. For example when your indices have maximum number 463, it's wasteful to store them in array of 32bit integers, array of 16bit integers is sufficient.

Example usage:

std::vector<UnsignedInt> indices;

Containers::Array<char> indexData;
MeshIndexType indexType;
UnsignedInt indexStart, indexEnd;
std::tie(indexData, indexType, indexStart, indexEnd) =
    MeshTools::compressIndices(indices);

GL::Buffer indexBuffer;
indexBuffer.setData(indexData, GL::BufferUsage::StaticDraw);

GL::Mesh mesh;
mesh.setCount(indices.size())
    .setIndexBuffer(indexBuffer, 0, indexType, indexStart, indexEnd);

#include <Magnum/MeshTools/CompressIndices.h>

template<class T>

Containers::Array<T> Magnum::MeshTools::compressIndicesAs(const std::vector<UnsignedInt>& indices)

Compress vertex indices as given type.

The type can be either UnsignedByte, UnsignedShort or UnsignedInt. Values in the index array are expected to be representable with given type.

Example usage:

std::vector<UnsignedInt> indices;
Containers::Array<UnsignedShort> indexData =
    MeshTools::compressIndicesAs<UnsignedShort>(indices);

#include <Magnum/MeshTools/Duplicate.h>

template<class IndexType, class T>

Containers::Array<T> Magnum::MeshTools::duplicate(const Containers::StridedArrayView1D<const IndexType>& indices, const Containers::StridedArrayView1D<const T>& data)

Duplicate data using given index array.

Converts indexed array to non-indexed, for example data {a, b, c, d} with index array {1, 1, 0, 3, 2, 2} will be converted to {b, b, a, d, c, c}. The resulting array size is the same as size of indices, expects that all indices are in range for the data array.

If you want to fill an existing memory (or, for example a std::vector), use duplicateInto().

#include <Magnum/MeshTools/Duplicate.h>

template<class IndexType, class T>

void Magnum::MeshTools::duplicateInto(const Containers::StridedArrayView1D<const IndexType>& indices, const Containers::StridedArrayView1D<const T>& data, const Containers::StridedArrayView1D<T>& out) new in 2019.10

Duplicate data using an index array into given output array.

A variant of duplicate() that fills existing memory instead of allocating a new array.

#include <Magnum/MeshTools/Duplicate.h>

template<class T>

std::vector<T> Magnum::MeshTools::duplicate(const std::vector<UnsignedInt>& indices, const std::vector<T>& data)

Duplicate data using given index array.

Like duplicate(const Containers::StridedArrayView1D<const IndexType>&, const Containers::StridedArrayView1D<const T>&), but putting the result into a std::vector.

void Magnum::MeshTools::flipFaceWinding(std::vector<UnsignedInt>& indices)

#include <Magnum/MeshTools/FlipNormals.h>

Flip face winding.

The same as flipNormals(std::vector<UnsignedInt>&, std::vector<Vector3>&), but flips only face winding.

void Magnum::MeshTools::flipNormals(std::vector<Vector3>& normals)

#include <Magnum/MeshTools/FlipNormals.h>

Flip mesh normals.

The same as flipNormals(std::vector<UnsignedInt>&, std::vector<Vector3>&), but flips only normals, not face winding.

void Magnum::MeshTools::flipNormals(std::vector<UnsignedInt>& indices, std::vector<Vector3>& normals)

#include <Magnum/MeshTools/FlipNormals.h>

Flip mesh normals and face winding.

Flips normal vectors and face winding in index array for face culling to work properly too. See also flipNormals(std::vector<Vector3>&) and flipFaceWinding(), which flip normals or face winding only.

GL::Mesh Magnum::MeshTools::fullScreenTriangle(GL::Version version)

#include <Magnum/MeshTools/FullScreenTriangle.h>

Full screen triangle mesh.

Returns a pre-configured mesh along with vertex buffer which can be used for full-screen post-processing effects. The mesh is a single triangle covering whole screen area ( in both dimensions) and provides only vertex positions, as other attributes (such as texture coordinates) can be calculated from them. The vertex positions are, in order:

Based on the version parameter, on OpenGL 2.1, OpenGL ES 2.0 and WebGL 1 the vertex positions are passed explicitly as attribute 0, contained in a vertex buffer owned by the mesh. On OpenGL 3.0+, OpenGL ES 3.0+ and WebGL 2 the mesh is attribute-less and the vertex positions can be calculated using the gl_VertexID builtin shader variable.

Calculating positions in the shader in a portable way can be done like this. For OpenGL 2.1 and OpenGL ES 2.0 you then need to bind location of the position attribute to 0.

#if (!defined(GL_ES) && __VERSION__ >= 130) || (defined(GL_ES) && __VERSION__ >= 300)
#define NEW_GLSL
#endif

#ifndef NEW_GLSL
attribute lowp vec4 position;
#endif

void main() {
    #ifdef NEW_GLSL
    gl_Position = vec4((gl_VertexID == 2) ?  3.0 : -1.0,
                       (gl_VertexID == 1) ? -3.0 :  1.0, 0.0, 1.0);
    #else
    gl_Position = position;
    #endif
}

GL::Mesh Magnum::MeshTools::fullScreenTriangle()

#include <Magnum/MeshTools/FullScreenTriangle.h>

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

This function implicitly uses current context version.

Containers::Array<Vector3> Magnum::MeshTools::generateFlatNormals(const Containers::StridedArrayView1D<const Vector3>& positions)

#include <Magnum/MeshTools/GenerateNormals.h>

Generate flat normals.

All vertices in each triangle face get the same normal vector. Expects that the position count is divisible by 3. If you need to generate flat normals for an indexed mesh, duplicate() the vertices first, after the operation you might want to remove the duplicates again using removeDuplicates(). Example usage:

Containers::ArrayView<UnsignedInt> indices;
Containers::ArrayView<Vector3> indexedPositions;

Containers::Array<Vector3> positions =
    MeshTools::duplicate<UnsignedInt, Vector3>(indices, indexedPositions);

Containers::Array<Vector3> normals =
    MeshTools::generateFlatNormals(positions);

void Magnum::MeshTools::generateFlatNormalsInto(const Containers::StridedArrayView1D<const Vector3>& positions, const Containers::StridedArrayView1D<Vector3>& normals) new in 2019.10

#include <Magnum/MeshTools/GenerateNormals.h>

Generate flat normals into an existing array.

A variant of generateFlatNormals() that fills existing memory instead of allocating a new array. The normals array is expected to have the same size as positions.

Useful when you need to interface for example with STL containers — in that case #include Corrade/Containers/ArrayViewStl.h to get implicit conversions:

#include <Corrade/Containers/ArrayViewStl.h>

// …

std::vector<Vector3> positions;

std::vector<Vector3> normals{positions.size()};
MeshTools::generateFlatNormalsInto(positions, normals);

std::pair<std::vector<UnsignedInt>, std::vector<Vector3>> Magnum::MeshTools::generateFlatNormals(const std::vector<UnsignedInt>& indices, const std::vector<Vector3>& positions)

#include <Magnum/MeshTools/GenerateNormals.h>

Generate flat normals.

All vertices in each triangle face get the same normal vector. Removes duplicates before returning. Expects that the position count is divisible by 3.

#include <Magnum/MeshTools/GenerateNormals.h>

template<class T>

Containers::Array<Vector3> Magnum::MeshTools::generateSmoothNormals(const Containers::StridedArrayView1D<const T>& indices, const Containers::StridedArrayView1D<const Vector3>& positions) new in 2019.10

Generate smooth normals.

Uses the indices array to discover adjacent triangles and then for each vertex position calculates a normal averaged from all triangles that share it. The normal is weighted according to adjacent triangle area and angle at given vertex; hard edges are preserved where adjacent triangles don't share vertices. Triangles with zero area or triangles containing invalid positions (NaNs) don't contribute to calculated vertex normals.

Implementation is based on the article Weighted Vertex Normals by Martijn Buijs.

#include <Magnum/MeshTools/GenerateNormals.h>

template<class T>

void Magnum::MeshTools::generateSmoothNormalsInto(const Containers::StridedArrayView1D<const T>& indices, const Containers::StridedArrayView1D<const Vector3>& positions, const Containers::StridedArrayView1D<Vector3>& normals)

Generate smooth normals into an existing array.

A variant of generateSmoothNormals() that fills existing memory instead of allocating a new array. The normals array is expected to have the same size as positions. Note that even with the output array this function isn't fully allocation-free — it still allocates three additional internal arrays for adjacent face calculation.

Useful when you need to interface for example with STL containers — in that case #include Corrade/Containers/ArrayViewStl.h to get implicit conversions:

#include <Corrade/Containers/ArrayViewStl.h>

// …

std::vector<UnsignedInt> indices;
std::vector<Vector3> positions;

std::vector<Vector3> normals{positions.size()};
MeshTools::generateSmoothNormalsInto<UnsignedInt>(indices, positions, normals);

#include <Magnum/MeshTools/Interleave.h>

template<class T, class ... U>

Containers::Array<char> Magnum::MeshTools::interleave(const T& first, const U&... next)

Interleave vertex attributes.

This function takes list of attribute arrays and returns them interleaved, so data for each attribute are in continuous place in memory.

Example usage:

std::vector<Vector3> positions;
std::vector<Vector2> textureCoordinates;

GL::Buffer vertexBuffer;
vertexBuffer.setData(MeshTools::interleave(positions, textureCoordinates), GL::BufferUsage::StaticDraw);

GL::Mesh mesh;
mesh.setCount(positions.size())
    .addVertexBuffer(vertexBuffer, 0, MyShader::Position{}, MyShader::TextureCoordinates{});

It's often desirable to align data for one vertex on 32bit boundaries. To achieve that, you can specify gaps between the attributes:

std::vector<Vector4> positions;
std::vector<UnsignedShort> weights;
std::vector<Color3ub> vertexColors;

auto data = MeshTools::interleave(positions, weights, 2, vertexColors, 1);

All gap bytes are set zero. This way vertex stride is 24 bytes, without gaps it would be 21 bytes, causing possible performance loss.

#include <Magnum/MeshTools/Interleave.h>

template<class T, class ... U>

void Magnum::MeshTools::interleaveInto(Containers::ArrayView<char> buffer, const T& first, const U&... next)

Interleave vertex attributes into existing buffer.

Unlike interleave() this function interleaves the data into existing buffer and leaves gaps untouched instead of zero-initializing them. This function can thus be used for interleaving data depending on runtime parameters.

#include <Magnum/MeshTools/RemoveDuplicates.h>

template<class Vector>

std::vector<UnsignedInt> Magnum::MeshTools::removeDuplicates(std::vector<Vector>& data, typename Vector::Type epsilon = Math::TypeTraits<typename Vector::Type>::epsilon())

Remove duplicate floating-point vector data from given array.

Removes duplicate data from the array by collapsing them into buckets of size epsilon. First vector in given bucket is used, other ones are thrown away, no interpolation is done. Note that this function is meant to be used for floating-point data (or generally with non-zero epsilon), for discrete data the usual sorting method is much more efficient.

If you want to remove duplicate data from already indexed array, first remove duplicates as if the array wasn't indexed at all and then use duplicate() to combine the two index arrays:

std::vector<UnsignedInt> indices;
std::vector<Vector3> positions;

indices = MeshTools::duplicate(indices, MeshTools::removeDuplicates(positions));

Removing duplicates in multiple indcidental arrays is also possible — first remove duplicates in each array separately and then use combineIndexedArrays() to combine the resulting index arrays to single index array and reorder the data accordingly:

std::vector<Vector3> positions;
std::vector<Vector2> texCoords;

std::vector<UnsignedInt> positionIndices = MeshTools::removeDuplicates(positions);
std::vector<UnsignedInt> texCoordIndices = MeshTools::removeDuplicates(texCoords);

std::vector<UnsignedInt> indices = MeshTools::combineIndexedArrays(
    std::make_pair(std::cref(positionIndices), std::ref(positions)),
    std::make_pair(std::cref(texCoordIndices), std::ref(texCoords))
);

#include <Magnum/MeshTools/Subdivide.h>

template<class Vertex, class Interpolator>

void Magnum::MeshTools::subdivide(std::vector<UnsignedInt>& indices, std::vector<Vertex>& vertices, Interpolator interpolator)

Subdivide the mesh.

Goes through all triangle faces and subdivides them into four new. Removing duplicate vertices in the mesh is up to the user.

#include <Magnum/MeshTools/Subdivide.h>

template<class Vertex, class Interpolator>

void Magnum::MeshTools::subdivideInPlace(Containers::ArrayView<UnsignedInt> indices, Containers::ArrayView<Vertex> vertices, Interpolator interpolator)

Subdivide the mesh in-place.

Assumes the original triangle mesh indices are in the first quarter of the indices array and original vertices in a prefix of the vertices array, with indices.size() left at the end of it for newly added vertices. Then goes through all those triangle faces and subdivides them into four new, filling up the remaining space in both. Removing duplicate vertices in the mesh is up to the user.

void Magnum::MeshTools::tipsify(std::vector<UnsignedInt>& indices, UnsignedInt vertexCount, std::size_t cacheSize)

#include <Magnum/MeshTools/Tipsify.h>

Tipsify the mesh.

Optimizes the mesh for vertex-bound applications by rearranging its index array for beter usage of post-transform vertex cache. Algorithm used: Pedro V. Sander, Diego Nehab, and Joshua Barczak — Fast Triangle Reordering for Vertex Locality and Reduced Overdraw, SIGGRAPH 2007, http://gfx.cs.princeton.edu/pubs/Sander_2007_%3ETR/index.php*.

#include <Magnum/MeshTools/Transform.h>

template<class T, class U>

void Magnum::MeshTools::transformVectorsInPlace(const Math::Matrix4<T>& matrix, U&& vectors)

Transform vectors in-place using given transformation.

Usable for one-time mesh transformations that would otherwise negatively affect dependent objects, such as (uneven) scaling. Accepts any forward-iterable type with compatible vector type as vectors. Expects that Quaternion is normalized, no further requirements are for other transformation representations.

Unlike in transformPointsInPlace(), the transformation does not involve translation.

Example usage:

std::vector<Vector3> vectors;
auto transformation = Quaternion::rotation(35.0_degf, Vector3::yAxis());
MeshTools::transformVectorsInPlace(transformation, vectors);

#include <Magnum/MeshTools/Transform.h>

template<class T, class U>

void Magnum::MeshTools::transformVectorsInPlace(const Math::Matrix3<T>& matrix, U&& vectors)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

#include <Magnum/MeshTools/Transform.h>

template<class T, class U>

void Magnum::MeshTools::transformVectorsInPlace(const Math::Complex<T>& complex, U&& vectors)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

#include <Magnum/MeshTools/Transform.h>

template<class T, class U>

void Magnum::MeshTools::transformVectorsInPlace(const Math::Quaternion<T>& normalizedQuaternion, U&& vectors)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

#include <Magnum/MeshTools/Transform.h>

template<class T, class U>

U Magnum::MeshTools::transformVectors(const T& transformation, U vectors)

Transform vectors using given transformation.

Returns transformed vectors instead of modifying them in-place. See transformVectorsInPlace() for more information.

#include <Magnum/MeshTools/Transform.h>

template<class T, class U>

void Magnum::MeshTools::transformPointsInPlace(const Math::Matrix4<T>& matrix, U&& points)

Transform points in-place using given transformation.

Usable for one-time mesh transformations that would otherwise negatively affect dependent objects, such as (uneven) scaling. Accepts any forward-iterable type with compatible vector type as vectors. Expects that DualQuaternion is normalized, no further requirements are for other transformation representations.

Unlike in transformVectorsInPlace(), the transformation also involves translation.

Example usage:

std::vector<Vector3> points;
auto transformation =
    DualQuaternion::rotation(35.0_degf, Vector3::yAxis())*
    DualQuaternion::translation({0.5f, -1.0f, 3.0f});
MeshTools::transformPointsInPlace(transformation, points);

#include <Magnum/MeshTools/Transform.h>

template<class T, class U>

void Magnum::MeshTools::transformPointsInPlace(const Math::Matrix3<T>& matrix, U&& points)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

#include <Magnum/MeshTools/Transform.h>

template<class T, class U>

void Magnum::MeshTools::transformPointsInPlace(const Math::DualComplex<T>& dualComplex, U&& points)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

#include <Magnum/MeshTools/Transform.h>

template<class T, class U>

void Magnum::MeshTools::transformPointsInPlace(const Math::DualQuaternion<T>& normalizedDualQuaternion, U&& points)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

#include <Magnum/MeshTools/Transform.h>

template<class T, class U>

U Magnum::MeshTools::transformPoints(const T& transformation, U vectors)

Transform points using given transformation.

Returns transformed points instead of modifying them in-place. See transformPointsInPlace() for more information.