From 1c3f4844e98bd90769f732e587a90f1409997c3c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Sun, 11 Jul 2021 00:23:22 +0200 Subject: [PATCH] Trade: doc++ --- src/Magnum/Trade/MeshData.h | 67 +++++++++++++++----------- src/Magnum/Trade/Test/MeshDataTest.cpp | 3 ++ 2 files changed, 43 insertions(+), 27 deletions(-) diff --git a/src/Magnum/Trade/MeshData.h b/src/Magnum/Trade/MeshData.h index 6b84034ae..40359f203 100644 --- a/src/Magnum/Trade/MeshData.h +++ b/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 -@ref VertexFormat explicitly, or a 2D view. +Alternatively, you can pass a typeless @cpp const void @ce or a 2D view and +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 -compile time), but the actual data is allocated / populated at runtime: +useful mainly to avoid pointer patching during data serialization, but also for +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 - * zero for builtin attributes. + * items of @p format, @p format corresponds to @p name and + * @p arraySize is zero for builtin attributes. */ explicit MeshAttributeData(MeshAttribute name, VertexFormat format, const Containers::StridedArrayView1D& 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 - * @p name and @p arraySize is zero for builtin attributes. + * size matches @p format and @p arraySize, that @p format corresponds + * to @p name and @p arraySize is zero for builtin attributes. */ explicit MeshAttributeData(MeshAttribute name, VertexFormat format, const Containers::StridedArrayView2D& 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 overload - * instead. + * @ref data(Containers::ArrayView) const overload instead. * @see @ref isOffsetOnly() */ constexpr Containers::StridedArrayView1D 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& 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 - * attribute stride for implementation-specific values) and is - * guaranteed to be contiguous. Use the templated overload below to get - * the attribute in a concrete type. + * equal to format size for known @ref VertexFormat values, possibly + * multiplied by array size, and to attribute stride for + * implementation-specific values) and is guaranteed to be contiguous. + * 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 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 - * use the non-templated @ref positions2DAsArray(), - * @ref positions3DAsArray(), @ref normalsAsArray(), - * @ref textureCoordinates2DAsArray() and @ref colorsAsArray() - * accessors to get common attributes converted to usual types, but - * note that these operations involve extra data conversion and an - * allocation. + * @ref attribute(MeshAttribute, UnsignedInt) const above. The + * attribute is also expected to not be an array, in that case you need + * to use the overload below by using @cpp T[] @ce instead of + * @cpp T @ce. You can also use the non-templated + * @ref positions2DAsArray(), @ref positions3DAsArray(), + * @ref normalsAsArray(), @ref textureCoordinates2DAsArray() and + * @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 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 constexpr MeshAttributeData::MeshAttributeData(MeshAttribute name, const Containers::StridedArrayView1D& data) noexcept: MeshAttributeData{nullptr, name, Implementation::vertexFormatFor::type>(), data, 0} {} -template constexpr MeshAttributeData::MeshAttributeData(MeshAttribute name, const Containers::StridedArrayView2D& data) noexcept: MeshAttributeData{(CORRADE_CONSTEXPR_ASSERT(data.stride()[1] == sizeof(T), "Trade::MeshAttributeData: second view dimension is not contiguous"), nullptr), name, Implementation::vertexFormatFor::type>(), Containers::StridedArrayView1D{{data.data(), ~std::size_t{}}, data.size()[0], data.stride()[0]}, UnsignedShort(data.size()[1])} {} +template constexpr MeshAttributeData::MeshAttributeData(MeshAttribute name, const Containers::StridedArrayView2D& 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::type>(), + Containers::StridedArrayView1D{{data.data(), ~std::size_t{}}, data.size()[0], data.stride()[0]}, + UnsignedShort(data.size()[1]) +} {} template Containers::ArrayView MeshData::indices() const { CORRADE_ASSERT(isIndexed(), diff --git a/src/Magnum/Trade/Test/MeshDataTest.cpp b/src/Magnum/Trade/Test/MeshDataTest.cpp index ce9bbfa0f..1e2f8a5fd 100644 --- a/src/Magnum/Trade/Test/MeshDataTest.cpp +++ b/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));