MeshTools: tighten up filter{Only,Except}Attributes() behavior.

Documenting & testing behavior with duplicated list items.

src/Magnum/MeshTools/Filter.h

@@ -62,8 +62,11 @@ MAGNUM_MESHTOOLS_EXPORT Trade::MeshData filterAttributes(const Trade::MeshData&
 Returns a non-owning reference to the vertex and index buffer from @p mesh with
 only the attributes that are listed in @p attributes. The index buffer, if
 present, is left untouched. Attributes from the list that are not present in
-@p mesh are skipped. All duplicates of a listed attribute are kept --- if you
+@p mesh are skipped, duplicates in the list are treated the same as if given
-want a different behavior, use the @ref filterOnlyAttributes(const Trade::MeshData&, Containers::ArrayView<const UnsignedInt>)
+attribute was listed just once. If given attribute is present multiple times in
+the mesh (such as secondary colors or texture coordinates), all its occurences
+are kept --- if you want a different behavior, use the
+@ref filterOnlyAttributes(const Trade::MeshData&, Containers::ArrayView<const UnsignedInt>)
 overload and pick attributes by their IDs instead.
 
 This function only operates on the attribute metadata --- if you'd like to have
@@ -87,10 +90,12 @@ MAGNUM_MESHTOOLS_EXPORT Trade::MeshData filterOnlyAttributes(const Trade::MeshDa
 Returns a non-owning reference to the vertex and index buffer from @p mesh with
 only the attributes that are not listed in @p attributes. The index buffer, if
 present, is left untouched. Attributes from the list that are not present in
-@p mesh are skipped. All duplicates of a listed attribute are removed --- if
+@p mesh are skipped, duplicates in the list are treated the same as if given
-you want a different behavior, use the @ref filterExceptAttributes(const Trade::MeshData&, Containers::ArrayView<const UnsignedInt>)
+attribute was listed just once. If given attribute is present multiple times in
-overload and pick attributes by their IDs instead. If @p attributes is empty,
+the mesh (such as secondary colors or texture coordinates), all its occurences
-the behavior is equivalent to @ref reference().
+are removed --- if you want a different behavior, use the
+@ref filterOnlyAttributes(const Trade::MeshData&, Containers::ArrayView<const UnsignedInt>)
+overload and pick attributes by their IDs instead.
 
 This function only operates on the attribute metadata --- if you'd like to have
 the vertex mesh repacked to contain just the remaining attributes as well, pass

src/Magnum/MeshTools/Test/FilterTest.cpp

@@ -238,9 +238,10 @@ void FilterTest::onlyAttributes() {
         }};
 
     Trade::MeshData filtered = filterOnlyAttributes(mesh, {
+        Trade::MeshAttribute::TextureCoordinates, /* present twice in the mesh */
         Trade::MeshAttribute::Position,
-        Trade::MeshAttribute::Normal, /* not present, ignored */
+        Trade::MeshAttribute::Normal, /* not present in the mesh, ignored */
-        Trade::MeshAttribute::TextureCoordinates, /* present twice */
+        Trade::MeshAttribute::Position, /* listed twice, ignored */
     });
     CORRADE_COMPARE(filtered.primitive(), MeshPrimitive::TriangleStrip);
 
@@ -257,6 +258,8 @@ void FilterTest::onlyAttributes() {
     /* Testing just the offset if it matches expectations, the
        MeshAttributeData is copied directly so no metadata should get lost */
     CORRADE_COMPARE(filtered.attributeCount(), 3);
+    /* The original order stays even though Position was specified after
+       TextureCoordinates in the list */
     CORRADE_COMPARE(filtered.attributeName(0), Trade::MeshAttribute::Position);
     CORRADE_COMPARE(filtered.attributeOffset(0), offsetof(Vertex, position));
     CORRADE_COMPARE(filtered.attributeName(1), Trade::MeshAttribute::TextureCoordinates);
@@ -483,8 +486,9 @@ void FilterTest::exceptAttributes() {
 
     Trade::MeshData filtered = filterExceptAttributes(mesh, {
         Trade::MeshAttribute::Position,
-        Trade::MeshAttribute::Normal, /* not present, ignored */
+        Trade::MeshAttribute::Normal, /* not present in the mesh, ignored */
-        Trade::MeshAttribute::TextureCoordinates, /* present twice */
+        Trade::MeshAttribute::TextureCoordinates, /* present twice in the mesh */
+        Trade::MeshAttribute::Position, /* listed twice, ignored */
     });
     CORRADE_COMPARE(filtered.primitive(), MeshPrimitive::TriangleStrip);