doc: compiled code snippets for the MeshTools namespace.

This was quite okay, in fact.

doc/snippets/CMakeLists.txt

@@ -35,6 +35,7 @@ endif()
 
 add_library(snippets STATIC
     Magnum.cpp
+    MagnumMeshTools.cpp
     MagnumShaders.cpp
     MagnumText.cpp)
 target_link_libraries(snippets PRIVATE Magnum)

doc/snippets/MagnumMeshTools.cpp

@@ -0,0 +1,166 @@
+/*
+    This file is part of Magnum.
+
+    Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018
+              Vladimír Vondruš <mosra@centrum.cz>
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included
+    in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+*/
+
+#include "Magnum/Buffer.h"
+#include "Magnum/Math/Color.h"
+#include "Magnum/MeshTools/CombineIndexedArrays.h"
+#include "Magnum/MeshTools/CompressIndices.h"
+#include "Magnum/MeshTools/Duplicate.h"
+#include "Magnum/MeshTools/GenerateFlatNormals.h"
+#include "Magnum/MeshTools/Interleave.h"
+#include "Magnum/MeshTools/RemoveDuplicates.h"
+#include "Magnum/MeshTools/Transform.h"
+
+using namespace Magnum;
+using namespace Magnum::Math::Literals;
+
+int main() {
+
+{
+/* [combineIndexedArrays] */
+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))
+);
+/* [combineIndexedArrays] */
+}
+
+{
+/* [compressIndices] */
+std::vector<UnsignedInt> indices;
+
+Containers::Array<char> indexData;
+Mesh::IndexType indexType;
+UnsignedInt indexStart, indexEnd;
+std::tie(indexData, indexType, indexStart, indexEnd) =
+    MeshTools::compressIndices(indices);
+
+Buffer indexBuffer;
+indexBuffer.setData(indexData, BufferUsage::StaticDraw);
+
+Mesh mesh;
+mesh.setCount(indices.size())
+    .setIndexBuffer(indexBuffer, 0, indexType, indexStart, indexEnd);
+/* [compressIndices] */
+}
+
+{
+/* [compressIndicesAs] */
+std::vector<UnsignedInt> indices;
+Containers::Array<UnsignedShort> indexData =
+    MeshTools::compressIndicesAs<UnsignedShort>(indices);
+/* [compressIndicesAs] */
+}
+
+{
+/* [generateFlatNormals] */
+std::vector<UnsignedInt> vertexIndices;
+std::vector<Vector3> positions;
+
+std::vector<UnsignedInt> normalIndices;
+std::vector<Vector3> normals;
+std::tie(normalIndices, normals) =
+    MeshTools::generateFlatNormals(vertexIndices, positions);
+/* [generateFlatNormals] */
+}
+
+{
+struct MyShader {
+    typedef Attribute<0, Vector3> Position;
+    typedef Attribute<0, Vector2> TextureCoordinates;
+};
+/* [interleave1] */
+std::vector<Vector3> positions;
+std::vector<Vector2> textureCoordinates;
+
+Buffer vertexBuffer;
+vertexBuffer.setData(MeshTools::interleave(positions, textureCoordinates), BufferUsage::StaticDraw);
+
+Mesh mesh;
+mesh.setCount(positions.size())
+    .addVertexBuffer(vertexBuffer, 0, MyShader::Position{}, MyShader::TextureCoordinates{});
+/* [interleave1] */
+}
+
+{
+/* [interleave2] */
+std::vector<Vector4> positions;
+std::vector<UnsignedShort> weights;
+std::vector<Color3ub> vertexColors;
+
+auto data = MeshTools::interleave(positions, weights, 2, vertexColors, 1);
+/* [interleave2] */
+}
+
+{
+/* [removeDuplicates1] */
+std::vector<UnsignedInt> indices;
+std::vector<Vector3> positions;
+
+indices = MeshTools::duplicate(indices, MeshTools::removeDuplicates(positions));
+/* [removeDuplicates1] */
+}
+
+{
+/* [removeDuplicates2] */
+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))
+);
+/* [removeDuplicates2] */
+}
+
+{
+/* [transformVectors] */
+std::vector<Vector3> vectors;
+auto transformation = Quaternion::rotation(35.0_degf, Vector3::yAxis());
+MeshTools::transformVectorsInPlace(transformation, vectors);
+/* [transformVectors] */
+}
+
+{
+/* [transformPoints] */
+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);
+/* [transformPoints] */
+}
+
+}

src/Magnum/MeshTools/CombineIndexedArrays.h

@@ -158,19 +158,7 @@ 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:
 
-@code{.cpp}
+@snippet MagnumMeshTools.cpp combineIndexedArrays
-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))
-);
-@endcode
 
 See @ref combineIndexArrays() documentation for more information about the
 procedure.

src/Magnum/MeshTools/CompressIndices.h

@@ -48,21 +48,7 @@ sufficient.
 
 Example usage:
 
-@code{.cpp}
+@snippet MagnumMeshTools.cpp compressIndices
-std::vector<UnsignedInt> indices;
-
-Containers::Array<char> indexData;
-Mesh::IndexType indexType;
-UnsignedInt indexStart, indexEnd;
-std::tie(indexData, indexType, indexStart, indexEnd) = MeshTools::compressIndices(indices);
-
-Buffer indexBuffer;
-indexBuffer.setData(indexData, BufferUsage::StaticDraw);
-
-Mesh mesh;
-mesh.setCount(indices.size())
-    .setIndexBuffer(indexBuffer, 0, indexType, indexStart, indexEnd);
-@endcode
 
 @see @ref compressIndicesAs()
 @todo Extract IndexType out of Mesh class
@@ -78,10 +64,7 @@ Values in the index array are expected to be representable with given type.
 
 Example usage:
 
-@code{.cpp}
+@snippet MagnumMeshTools.cpp compressIndicesAs
-std::vector<UnsignedInt> indices;
-Containers::Array<UnsignedShort> indexData = MeshTools::compressIndicesAs<UnsignedShort>(indices);
-@endcode
 
 @see @ref compressIndices()
 */

src/Magnum/MeshTools/GenerateFlatNormals.h

@@ -46,14 +46,7 @@ namespace Magnum { namespace MeshTools {
 For each face generates one normal vector, removes duplicates before
 returning. Example usage:
 
-@code{.cpp}
+@snippet MagnumMeshTools.cpp generateFlatNormals
-std::vector<UnsignedInt> vertexIndices;
-std::vector<Vector3> positions;
-
-std::vector<UnsignedInt> normalIndices;
-std::vector<Vector3> normals;
-std::tie(normalIndices, normals) = MeshTools::generateFlatNormals(vertexIndices, positions);
-@endcode
 
 You can then use @ref combineIndexedArrays() to combine normal and vertex array
 to use the same indices.

src/Magnum/MeshTools/Interleave.h

@@ -100,30 +100,12 @@ data for each attribute are in continuous place in memory.
 
 Example usage:
 
-@code{.cpp}
+@snippet MagnumMeshTools.cpp interleave1
-MeshPrimitive primitive;
-std::vector<Vector3> positions;
-std::vector<Vector2> textureCoordinates;
-
-Buffer vertexBuffer;
-vertexBuffer.setData(MeshTools::interleave(positions, textureCoordinates), BufferUsage::StaticDraw);
-
-Mesh mesh;
-mesh.setPrimitive(primitive)
-    .setCount(positions.count())
-    .addVertexBuffer(vertexBuffer, 0, MyShader::Position{}, MyShader::TextureCoordinates{});
-@endcode
 
 It's often desirable to align data for one vertex on 32bit boundaries. To
 achieve that, you can specify gaps between the attributes:
 
-@code{.cpp}
+@snippet MagnumMeshTools.cpp interleave2
-std::vector<Vector4> positions;
-std::vector<UnsignedShort> weights;
-std::vector<Color3ub> vertexColors;
-
-auto data = MeshTools::interleave(positions, weights, 2, textureCoordinates, 1);
-@endcode
 
 All gap bytes are set zero. This way vertex stride is 24 bytes, without gaps it
 would be 21 bytes, causing possible performance loss.

src/Magnum/MeshTools/RemoveDuplicates.h

@@ -66,30 +66,14 @@ 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 @ref duplicate()
 to combine the two index arrays:
 
-@code{.cpp}
+@snippet MagnumMeshTools.cpp removeDuplicates1
-std::vector<UnsignedInt> indices;
-std::vector<Vector3> positions;
-
-indices = MeshTools::duplicate(indices, MeshTools::removeDuplicates(positions));
-@endcode
 
 Removing duplicates in multiple indcidental arrays is also possible --- first
 remove duplicates in each array separately and then use @ref combineIndexedArrays()
 to combine the resulting index arrays to single index array and reorder the
 data accordingly:
 
-@code{.cpp}
+@snippet MagnumMeshTools.cpp removeDuplicates2
-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))
-);
-@endcode
 */
 template<class Vector> std::vector<UnsignedInt> removeDuplicates(std::vector<Vector>& data, typename Vector::Type epsilon = Math::TypeTraits<typename Vector::Type>::epsilon()) {
     /* Get bounds */

src/Magnum/MeshTools/Transform.h

@@ -48,11 +48,7 @@ translation.
 
 Example usage:
 
-@code{.cpp}
+@snippet MagnumMeshTools.cpp transformVectors
-std::vector<Vector3> vectors;
-auto transformation = Quaternion::rotation(35.0_degf, Vector3::yAxis());
-MeshTools::transformVectorsInPlace(rotation, vectors);
-@endcode
 
 @see @ref transformVectors(), @ref Matrix3::transformVector(),
     @ref Matrix4::transformVector(), @ref Complex::transformVector(),
@@ -104,12 +100,7 @@ translation.
 
 Example usage:
 
-@code{.cpp}
+@snippet MagnumMeshTools.cpp transformPoints
-std::vector<Vector3> points;
-auto transformation = DualQuaternion::rotation(35.0_degf, Vector3::yAxis())*
-    DualQuaternion::translation({0.5f, -1.0f, 3.0f});
-MeshTools::transformPointsInPlace(rotation, points);
-@endcode
 
 @see @ref transformPoints(), @ref Matrix3::transformPoint(),
     @ref Matrix4::transformPoint(),