MeshTools: doc++

doc/snippets/MagnumMeshTools-gl.cpp

@@ -115,15 +115,16 @@ struct MyShader {
     typedef GL::Attribute<0, Vector2> TextureCoordinates;
 };
 /* [interleave1] */
-std::vector<Vector3> positions;
+Containers::ArrayView<const Vector3> positions;
-std::vector<Vector2> textureCoordinates;
+Containers::ArrayView<const Vector2> textureCoordinates;
 
 GL::Buffer vertexBuffer;
-vertexBuffer.setData(MeshTools::interleave(positions, textureCoordinates), GL::BufferUsage::StaticDraw);
+vertexBuffer.setData(MeshTools::interleave(positions, textureCoordinates));
 
 GL::Mesh mesh;
 mesh.setCount(positions.size())
-    .addVertexBuffer(vertexBuffer, 0, MyShader::Position{}, MyShader::TextureCoordinates{});
+    .addVertexBuffer(vertexBuffer, 0, MyShader::Position{},
+                                      MyShader::TextureCoordinates{});
 /* [interleave1] */
 }
 

doc/snippets/MagnumMeshTools-stl.cpp

@@ -26,6 +26,7 @@
 #include <Corrade/Containers/StridedArrayView.h>
 #include <Corrade/Containers/ArrayViewStl.h>
 
+#include "Magnum/Math/Vector3.h"
 #include "Magnum/MeshTools/GenerateNormals.h"
 
 using namespace Magnum;

doc/snippets/MagnumMeshTools.cpp

@@ -101,9 +101,9 @@ Containers::Array<Vector3> normals =
 
 {
 /* [interleave2] */
-std::vector<Vector4> positions;
+Containers::ArrayView<const Vector4> positions;
-std::vector<UnsignedShort> weights;
+Containers::ArrayView<const UnsignedShort> weights;
-std::vector<Color3ub> vertexColors;
+Containers::ArrayView<const Color3ub> vertexColors;
 
 auto data = MeshTools::interleave(positions, weights, 2, vertexColors, 1);
 /* [interleave2] */

src/Magnum/MeshTools/Duplicate.h

@@ -52,10 +52,10 @@ template<class IndexType, class T> void duplicateInto(const Containers::StridedA
 @brief Duplicate data using given index array
 @m_since{2019,10}
 
-Converts indexed array to non-indexed, for example data `{a, b, c, d}` with
+Converts indexed array to non-indexed, for example data @cpp {a, b, c, d} @ce
-index array `{1, 1, 0, 3, 2, 2}` will be converted to `{b, b, a, d, c, c}`.
+with index array @cpp {1, 1, 0, 3, 2, 2} @ce will be converted to
-The resulting array size is the same as size of @p indices, expects that all
+@cpp {b, b, a, d, c, c} @ce. The resulting array size is the same as size of
-indices are in range for the @p data array.
+@p indices, expects that all indices are in range for the @p data array.
 
 If you want to fill an existing memory (or, for example a @ref std::vector),
 use @ref duplicateInto().

src/Magnum/MeshTools/Interleave.h

@@ -120,7 +120,8 @@ template<class T, class ...U> void writeInterleaved(std::size_t stride, char* st
 @brief 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.
+data for each attribute are in continuous place in memory. Expects that all
+attributes have the same element count.
 
 Example usage:
 
@@ -134,14 +135,12 @@ achieve that, you can specify gaps between the attributes:
 All gap bytes are set zero. This way vertex stride is 24 bytes, without gaps it
 would be 21 bytes, causing possible performance loss.
 
-@attention The function expects that all arrays have the same size.
+@note The only requirements to the attribute array type is that it must have
-
+    either a typedef @cpp T::Type @ce (in case of Corrade types such as
-@note The only requirements to attribute array type is that it must have either
+    @ref Corrade::Containers::ArrayView) or a typedef @cpp T::value_type @ce
-    a typedef `T::Type` (in case of Corrade types such as
+    (in case of STL types such as @ref std::vector or @ref std::array), a
-    @ref Corrade::Containers::ArrayView) or a typedef `T::value_type` (in case
+    forward iterator (to be used with range-based for) and a @cpp size() @ce
-    of STL types such as @ref std::vector or @ref std::array) or a, a forward
+    method returning element count.
-    iterator (to be used with range-based for) and a function `size()`
-    returning count of elements.
 
 @see @ref interleaveInto()
 */
@@ -173,11 +172,8 @@ template<class T, class ...U
 Unlike @ref 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.
+parameters. Expects that all arrays have the same size and the passed buffer is
-
+large enough to contain the interleaved data.
-@attention Similarly to @ref interleave(), this function expects that all
-    arrays have the same size. The passed buffer must also be large enough to
-    contain the interleaved data.
 */
 template<class T, class ...U> void interleaveInto(Containers::ArrayView<char> buffer, const T& first, const U&... next) {
     /* Verify expected buffer size */
@@ -243,17 +239,20 @@ MAGNUM_MESHTOOLS_EXPORT Trade::MeshData interleavedLayout(const Trade::MeshData&
 @brief Interleave mesh data
 @m_since_latest
 
-Returns a copy of @p data with all attributes interleaved but everything else
+Returns a copy of @p data with all attributes interleaved. Indices (if any) are
-(indices, primitive type, ...) kept as-is. The @p extra attributes, if any, are
+kept as-is. The @p extra attributes, if any, are interleaved together with
-interleaved together with existing attributes (or, in case the attribute view
+existing attributes (or, in case the attribute view is empty, only the
-is empty, only the corresponding space for given attribute type is reserved,
+corresponding space for given attribute type is reserved, with memory left
-with memory left uninitialized). The data layouting is done by
+uninitialized). The data layouting is done by @ref interleavedLayout(), see its
-@ref interleavedLayout(), see its documentation for detailed behavior
+documentation for detailed behavior description. Note that offset-only
-description. Note that offset-only @ref Trade::MeshAttributeData instances are
+@ref Trade::MeshAttributeData instances are not supported in the @p extra
-not supported in the @p extra array.
+array.
 
 Expects that each attribute in @p extra has either the same amount of elements
-as @p data vertex count or has none.
+as @p data vertex count or has none. This function will unconditionally make a
+copy of all data even if @p data is already interleaved and needs no change,
+use @ref interleave(Trade::MeshData&&, Containers::ArrayView<const Trade::MeshAttributeData>)
+to avoid that copy.
 @see @ref isInterleaved(), @ref Trade::MeshData::attributeData()
 */
 MAGNUM_MESHTOOLS_EXPORT Trade::MeshData interleave(const Trade::MeshData& data, Containers::ArrayView<const Trade::MeshAttributeData> extra = {});

src/Magnum/MeshTools/RemoveDuplicates.h

@@ -128,7 +128,7 @@ MAGNUM_MESHTOOLS_EXPORT std::size_t removeDuplicatesInto(const Containers::Strid
 @m_since_latest
 
 Compared to @ref removeDuplicatesInPlace(const Containers::StridedArrayView2D<char>&)
-this variant is more suited for data that are already indexed as it works on
+this variant is more suited for data that is already indexed as it works on
 the existing index array instead of allocating a new one.
 */
 MAGNUM_MESHTOOLS_EXPORT std::size_t removeDuplicatesIndexedInPlace(const Containers::StridedArrayView1D<UnsignedInt>& indices, const Containers::StridedArrayView2D<char>& data);
@@ -205,7 +205,7 @@ template<class Vector> CORRADE_DEPRECATED("use removeDuplicatesInPlace() instead
 @m_since_latest
 
 Compared to @ref removeDuplicatesInPlace(const Containers::StridedArrayView1D<Vector>&, typename Vector::Type)
-this variant is more suited for data that are already indexed as it works on
+this variant is more suited for data that is already indexed as it works on
 the existing index array instead of allocating a new one.
 */
 template<class IndexType, class Vector> std::size_t removeDuplicatesIndexedInPlace(const Containers::StridedArrayView1D<IndexType>& indices, const Containers::StridedArrayView1D<Vector>& data, typename Vector::Type epsilon = Math::TypeTraits<typename Vector::Type>::epsilon()) {