Trade: doc++

src/Magnum/Trade/MeshData.h

@@ -150,7 +150,7 @@ enum class MeshAttribute: UnsignedShort {
     /**
      * This and all higher values are for importer-specific attributes. Can be
      * of any type. See documentation of a particular importer for details.
-     * @see @ref isMeshAttributeCustom(MeshAttribute)
+     * @see @ref isMeshAttributeCustom(),
      *      @ref meshAttributeCustom(MeshAttribute),
      *      @ref meshAttributeCustom(UnsignedShort)
      */
@@ -294,22 +294,23 @@ or @ref MeshTools::interleave(const Trade::MeshData& data, Containers::ArrayView
 
 @section Trade-MeshAttributeData-usage Usage
 
-The most straightforward usage is constructing an instance from a pair of
+The most straightforward usage is constructing an instance from a pair of a
 @ref MeshAttribute and a strided view. The @ref VertexFormat gets inferred from
 the view type:
 
 @snippet MagnumTrade.cpp MeshAttributeData-usage
 
-Alternatively, you can pass a typeless @cpp const void @ce view and supply
+Alternatively, you can pass a typeless @cpp const void @ce or a 2D view and
-@ref VertexFormat explicitly, or a 2D view.
+supply @ref VertexFormat explicitly.
 
 @subsection Trade-MeshAttributeData-usage-offset-only Offset-only attribute data
 
 If the actual attribute data location is not known yet, the instance can be
 created as "offset-only", meaning the actual view gets created only later when
 passed to a @ref MeshData instance with a concrete vertex data array. This is
-useful for example when vertex layout is static (and thus can be defined at
+useful mainly to avoid pointer patching during data serialization, but also for
-compile time), but the actual data is allocated / populated at runtime:
+example when vertex layout is static (and thus can be defined at compile time),
+but the actual data is allocated / populated at runtime:
 
 @snippet MagnumTrade.cpp MeshAttributeData-usage-offset-only
 
@@ -350,8 +351,8 @@ class MAGNUM_TRADE_EXPORT MeshAttributeData {
          *      attributes.
          *
          * Expects that @p data stride is large enough to fit all @p arraySize
-         * items of @p type, @p type corresponds to @p name and @p arraySize is
+         * items of @p format, @p format corresponds to @p name and
-         * zero for builtin attributes.
+         * @p arraySize is zero for builtin attributes.
          */
         explicit MeshAttributeData(MeshAttribute name, VertexFormat format, const Containers::StridedArrayView1D<const void>& data, UnsignedShort arraySize = 0) noexcept;
 
@@ -364,8 +365,8 @@ class MAGNUM_TRADE_EXPORT MeshAttributeData {
          *      attributes.
          *
          * Expects that the second dimension of @p data is contiguous and its
-         * size matches @p type and @p arraSize, that @p type corresponds to
+         * size matches @p format and @p arraySize, that @p format corresponds
-         * @p name and @p arraySize is zero for builtin attributes.
+         * to @p name and @p arraySize is zero for builtin attributes.
          */
         explicit MeshAttributeData(MeshAttribute name, VertexFormat format, const Containers::StridedArrayView2D<const char>& data, UnsignedShort arraySize = 0) noexcept;
 
@@ -515,8 +516,7 @@ class MAGNUM_TRADE_EXPORT MeshAttributeData {
          * @brief Type-erased attribute data
          *
          * Expects that the attribute is not offset-only, in that case use the
-         * @ref data(Containers::ArrayView<const void>) const overload
+         * @ref data(Containers::ArrayView<const void>) const overload instead.
-         * instead.
          * @see @ref isOffsetOnly()
          */
         constexpr Containers::StridedArrayView1D<const void> data() const {
@@ -544,7 +544,9 @@ class MAGNUM_TRADE_EXPORT MeshAttributeData {
     private:
         friend MeshData;
 
-        /* nullptr first, to avoid accidental matches as much as possible */
+        /* Delegated to by all ArrayView constructors, which additionally check
+           either stride or second dimension size. Nullptr first, to avoid
+           accidental matches as much as possible. */
         constexpr explicit MeshAttributeData(std::nullptr_t, MeshAttribute name, VertexFormat format, const Containers::StridedArrayView1D<const void>& data, UnsignedShort arraySize) noexcept;
 
         VertexFormat _format;
@@ -1301,11 +1303,13 @@ class MAGNUM_TRADE_EXPORT MeshData {
          *
          * The @p id is expected to be smaller than @ref attributeCount() const.
          * The second dimension represents the actual data type (its size is
-         * equal to format size for known @ref VertexFormat values and to
+         * equal to format size for known @ref VertexFormat values, possibly
-         * attribute stride for implementation-specific values) and is
+         * multiplied by array size, and to attribute stride for
-         * guaranteed to be contiguous. Use the templated overload below to get
+         * implementation-specific values) and is guaranteed to be contiguous.
-         * the attribute in a concrete type.
+         * Use the templated overload below to get the attribute in a concrete
+         * type.
          * @see @ref Corrade::Containers::StridedArrayView::isContiguous(),
+         *      @ref vertexFormatSize(),
          *      @ref isVertexFormatImplementationSpecific()
          */
         Containers::StridedArrayView2D<const char> attribute(UnsignedInt id) const;
@@ -1338,7 +1342,7 @@ class MAGNUM_TRADE_EXPORT MeshData {
          * to usual types, but note that these operations involve extra
          * allocation and data conversion.
          * @see @ref attribute(MeshAttribute, UnsignedInt) const,
-         *      @ref mutableAttribute(MeshAttribute, UnsignedInt),
+         *      @ref mutableAttribute(UnsignedInt),
          *      @ref isVertexFormatImplementationSpecific(),
          *      @ref attributeArraySize()
          */
@@ -1409,13 +1413,15 @@ class MAGNUM_TRADE_EXPORT MeshData {
          * correspond to @ref attributeFormat(MeshAttribute, UnsignedInt) const.
          * Expects that the vertex format is *not* implementation-specific, in
          * that case you can only access the attribute via the typeless
-         * @ref attribute(MeshAttribute, UnsignedInt) const above. You can also
+         * @ref attribute(MeshAttribute, UnsignedInt) const above. The
-         * use the non-templated @ref positions2DAsArray(),
+         * attribute is also expected to not be an array, in that case you need
-         * @ref positions3DAsArray(), @ref normalsAsArray(),
+         * to use the overload below by using @cpp T[] @ce instead of
-         * @ref textureCoordinates2DAsArray() and @ref colorsAsArray()
+         * @cpp T @ce. You can also use the non-templated
-         * accessors to get common attributes converted to usual types, but
+         * @ref positions2DAsArray(), @ref positions3DAsArray(),
-         * note that these operations involve extra data conversion and an
+         * @ref normalsAsArray(), @ref textureCoordinates2DAsArray() and
-         * allocation.
+         * @ref colorsAsArray() accessors to get common attributes converted to
+         * usual types, but note that these operations involve extra data
+         * conversion and an allocation.
          * @see @ref attribute(UnsignedInt) const,
          *      @ref mutableAttribute(MeshAttribute, UnsignedInt),
          *      @ref isVertexFormatImplementationSpecific()
@@ -1808,7 +1814,7 @@ namespace Implementation {
     /* Implicit mapping from a format to enum (1:1) */
     template<class T> constexpr VertexFormat vertexFormatFor() {
         /* C++ why there isn't an obvious way to do such a thing?! */
-        static_assert(sizeof(T) == 0, "unsupported attribute type");
+        static_assert(sizeof(T) == 0, "unsupported vertex format");
         return {};
     }
     #ifndef DOXYGEN_GENERATING_OUTPUT
@@ -2093,7 +2099,14 @@ constexpr MeshAttributeData::MeshAttributeData(const MeshAttribute name, const V
 
 template<class T> constexpr MeshAttributeData::MeshAttributeData(MeshAttribute name, const Containers::StridedArrayView1D<T>& data) noexcept: MeshAttributeData{nullptr, name, Implementation::vertexFormatFor<typename std::remove_const<T>::type>(), data, 0} {}
 
-template<class T> constexpr MeshAttributeData::MeshAttributeData(MeshAttribute name, const Containers::StridedArrayView2D<T>& data) noexcept: MeshAttributeData{(CORRADE_CONSTEXPR_ASSERT(data.stride()[1] == sizeof(T), "Trade::MeshAttributeData: second view dimension is not contiguous"), nullptr), name, Implementation::vertexFormatFor<typename std::remove_const<T>::type>(), Containers::StridedArrayView1D<const void>{{data.data(), ~std::size_t{}}, data.size()[0], data.stride()[0]}, UnsignedShort(data.size()[1])} {}
+template<class T> constexpr MeshAttributeData::MeshAttributeData(MeshAttribute name, const Containers::StridedArrayView2D<T>& data) noexcept: MeshAttributeData{
+    /* Not using isContiguous<1>() as that's not constexpr */
+    (CORRADE_CONSTEXPR_ASSERT(data.stride()[1] == sizeof(T), "Trade::MeshAttributeData: second view dimension is not contiguous"), nullptr),
+    name,
+    Implementation::vertexFormatFor<typename std::remove_const<T>::type>(),
+    Containers::StridedArrayView1D<const void>{{data.data(), ~std::size_t{}}, data.size()[0], data.stride()[0]},
+    UnsignedShort(data.size()[1])
+} {}
 
 template<class T> Containers::ArrayView<const T> MeshData::indices() const {
     CORRADE_ASSERT(isIndexed(),

src/Magnum/Trade/Test/MeshDataTest.cpp

@@ -605,6 +605,9 @@ void MeshDataTest::constructAttributeDefault() {
 }
 
 void MeshDataTest::constructAttributeCustom() {
+    /* Verifying it doesn't hit any assertion about disallowed type for given
+       attribute */
+
     const Short idData[3]{};
     MeshAttributeData ids{meshAttributeCustom(13), Containers::arrayView(idData)};
     CORRADE_COMPARE(ids.name(), meshAttributeCustom(13));