MeshTools: document a non-obvious usage for combineIndexedAttributes().

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 function preserves all attribute data including repeated or custom
-The resulting mesh is interleaved, with all attributes packed tightly together.
+attributes. The resulting mesh is interleaved, with all attributes packed
-If you need to add specific padding for alignment preservation, pass the result
+tightly together. If you need to add specific padding for alignment
-to @ref interleave() and specify the paddings between attributes manually.
+preservation, pass the result to @ref interleave() and specify the paddings
-Similarly, for simplicity the resulting mesh has always
+between attributes manually. Similarly, for simplicity the resulting mesh has
-@ref MeshIndexType::UnsignedInt --- use @ref compressIndices(const Trade::MeshData&, MeshIndexType)
+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

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");