From 36a3556c68f2175ac59b2f512dc50ff2063c9524 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Mon, 18 May 2020 13:30:31 +0200
Subject: [PATCH] MeshTools: document a non-obvious usage for
 combineIndexedAttributes().

---
 src/Magnum/MeshTools/Combine.h            | 16 +++++++++------
 src/Magnum/MeshTools/Test/CombineTest.cpp | 24 +++++++++++++++++++++++
 2 files changed, 34 insertions(+), 6 deletions(-)

diff --git a/src/Magnum/MeshTools/Combine.h b/src/Magnum/MeshTools/Combine.h
index c1c7df06e..d4161f63c 100644
--- a/src/Magnum/MeshTools/Combine.h
+++ b/src/Magnum/MeshTools/Combine.h
@@ -66,14 +66,18 @@ indexing both positions and normals:
 {0, 1, 2, 0, 3, 4, 5, 1, 6}     // unified indices
 @endcode
 
-The function preserves all vertex data including repeated or custom attributes.
-The resulting mesh is interleaved, with all attributes packed tightly together.
-If you need to add specific padding for alignment preservation, pass the result
-to @ref interleave() and specify the paddings between attributes manually.
-Similarly, for simplicity the resulting mesh has always
-@ref MeshIndexType::UnsignedInt --- use @ref compressIndices(const Trade::MeshData&, MeshIndexType)
+The function preserves all attribute data including repeated or custom
+attributes. The resulting mesh is interleaved, with all attributes packed
+tightly together. If you need to add specific padding for alignment
+preservation, pass the result to @ref interleave() and specify the paddings
+between attributes manually. Similarly, for simplicity the resulting mesh has
+always @ref MeshIndexType::UnsignedInt --- use @ref compressIndices(const Trade::MeshData&, MeshIndexType)
 if you want to have it compressed to a smaller type.
 
+Vertex data unreferenced by the index buffers are discarded. This means the
+function can be also called with just a single argument to compact a mesh with
+a sparse index buffer.
+
 Expects that @p data is non-empty and all data have the same primitive and
 index count. All inputs have to be indexed, although the particular
 @ref MeshIndexType doesn't matter. For non-indexed attributes combining can be
diff --git a/src/Magnum/MeshTools/Test/CombineTest.cpp b/src/Magnum/MeshTools/Test/CombineTest.cpp
index 7dd6726ea..bb1bb2645 100644
--- a/src/Magnum/MeshTools/Test/CombineTest.cpp
+++ b/src/Magnum/MeshTools/Test/CombineTest.cpp
@@ -41,6 +41,7 @@ struct CombineTest: TestSuite::Tester {
 
     void combineIndexedAttributes();
     void combineIndexedAttributesIndicesOnly();
+    void combineIndexedAttributesSingleMesh();
 
     void combineIndexedAttributesNoMeshes();
     void combineIndexedAttributesNotIndexed();
@@ -66,6 +67,7 @@ constexpr struct {
 CombineTest::CombineTest() {
     addTests({&CombineTest::combineIndexedAttributes,
               &CombineTest::combineIndexedAttributesIndicesOnly,
+              &CombineTest::combineIndexedAttributesSingleMesh,
 
               &CombineTest::combineIndexedAttributesNoMeshes,
               &CombineTest::combineIndexedAttributesNotIndexed,
@@ -150,6 +152,28 @@ void CombineTest::combineIndexedAttributesIndicesOnly() {
     CORRADE_COMPARE(result.vertexCount(), 2);
 }
 
+void CombineTest::combineIndexedAttributesSingleMesh() {
+    const UnsignedInt indices[]{2, 1, 2, 0, 5, 7};
+    const Float data[]{0.0f, 1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f, 7.0f};
+    Trade::MeshData a{MeshPrimitive::LineLoop,
+        {}, indices, Trade::MeshIndexData{indices},
+        {}, data, {Trade::MeshAttributeData{
+            Trade::meshAttributeCustom(22), Containers::arrayView(data)}}};
+
+    Trade::MeshData result = MeshTools::combineIndexedAttributes({a});
+    CORRADE_COMPARE(result.primitive(), MeshPrimitive::LineLoop);
+    CORRADE_VERIFY(result.isIndexed());
+    CORRADE_COMPARE(result.indexType(), MeshIndexType::UnsignedInt);
+    CORRADE_COMPARE_AS(result.indices<UnsignedInt>(),
+        Containers::arrayView<UnsignedInt>({0, 1, 0, 2, 3, 4}),
+        TestSuite::Compare::Container);
+    CORRADE_COMPARE(result.attributeCount(), 1);
+    CORRADE_COMPARE(result.attributeFormat(0), VertexFormat::Float);
+    CORRADE_COMPARE_AS(result.attribute<Float>(0),
+        Containers::arrayView<Float>({2.0f, 1.0f, 0.0f, 5.0f, 7.0f}),
+        TestSuite::Compare::Container);
+}
+
 void CombineTest::combineIndexedAttributesNoMeshes() {
     #ifdef CORRADE_NO_ASSERT
     CORRADE_SKIP("CORRADE_NO_ASSERT defined, can't test assertions");