From 6afbb4afd25fdd464d404cf98dc6e6abd93aa4ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Wed, 10 May 2023 20:02:46 +0200 Subject: [PATCH] Improve vertex format related docs. The documentation was written like 16-bytes-per-channel normalized zero-component formats were a totally normal thing. --- doc/snippets/Magnum.cpp | 13 ++++++ src/Magnum/Test/VertexFormatTest.cpp | 2 + src/Magnum/VertexFormat.h | 67 +++++++++++++++++++--------- 3 files changed, 62 insertions(+), 20 deletions(-) diff --git a/doc/snippets/Magnum.cpp b/doc/snippets/Magnum.cpp index e67c2fe42..dd0e230e4 100644 --- a/doc/snippets/Magnum.cpp +++ b/doc/snippets/Magnum.cpp @@ -30,6 +30,7 @@ #include "Magnum/Image.h" #include "Magnum/ImageView.h" #include "Magnum/PixelFormat.h" +#include "Magnum/VertexFormat.h" #ifdef MAGNUM_TARGET_GL #include "Magnum/ResourceManager.h" #include "Magnum/GL/AbstractShaderProgram.h" @@ -320,4 +321,16 @@ Resource myMesh = manager.get("my-mesh"); } #endif +{ +/* [vertexFormat] */ +VertexFormat normalFormat = DOXYGEN_ELLIPSIS({}); + +VertexFormat tangentFormat = vertexFormat( + normalFormat, + 4, + isVertexFormatNormalized(normalFormat)); +/* [vertexFormat] */ +static_cast(tangentFormat); +} + } diff --git a/src/Magnum/Test/VertexFormatTest.cpp b/src/Magnum/Test/VertexFormatTest.cpp index 934defab0..a68f64319 100644 --- a/src/Magnum/Test/VertexFormatTest.cpp +++ b/src/Magnum/Test/VertexFormatTest.cpp @@ -537,8 +537,10 @@ void VertexFormatTest::assembleInvalidComponentCount() { std::ostringstream out; Error redirectError{&out}; + vertexFormat(VertexFormat::Vector3, 0, false); vertexFormat(VertexFormat::Vector3, 5, false); CORRADE_COMPARE(out.str(), + "vertexFormat(): invalid component count 0\n" "vertexFormat(): invalid component count 5\n"); } diff --git a/src/Magnum/VertexFormat.h b/src/Magnum/VertexFormat.h index 56dcbc3d2..69e9905a4 100644 --- a/src/Magnum/VertexFormat.h +++ b/src/Magnum/VertexFormat.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Enum @ref Magnum::VertexFormat, function @ref Magnum::isVertexFormatImplementationSpecific(), @ref Magnum::vertexFormatWrap(), @ref Magnum::vertexFormatUnwrap(), @ref Magnum::vertexFormatSize(), @ref Magnum::vertexFormatComponentFormat(), @ref Magnum::vertexFormatComponentCount(), @ref Magnum::vertexFormatVectorCount(), @ref Magnum::vertexFormatVectorStride(), @ref Magnum::isVertexFormatNormalized() + * @brief Enum @ref Magnum::VertexFormat, function @ref Magnum::isVertexFormatImplementationSpecific(), @ref Magnum::vertexFormatWrap(), @ref Magnum::vertexFormatUnwrap(), @ref Magnum::vertexFormatSize(), @ref Magnum::vertexFormatComponentFormat(), @ref Magnum::vertexFormatComponentCount(), @ref Magnum::vertexFormatVectorCount(), @ref Magnum::vertexFormatVectorStride(), @ref Magnum::isVertexFormatNormalized(), @ref Magnum::vertexFormat() */ #include @@ -62,6 +62,12 @@ information about the mapping. Note that not every format may be available, use For D3D, corresponds to @m_class{m-doc-external} [DXGI_FORMAT](https://docs.microsoft.com/en-us/windows/win32/api/dxgiformat/ne-dxgiformat-dxgi_format); for Metal, corresponds to @m_class{m-doc-external} [MTLVertexFormat](https://developer.apple.com/documentation/metal/mtlvertexformat?language=objc). See documentation of each value for more information about the mapping. + +See also @ref vertexFormatSize(), @ref vertexFormatComponentFormat(), +@ref vertexFormatComponentCount(), @ref vertexFormatVectorCount(), +@ref vertexFormatVectorStride(), @ref isVertexFormatNormalized() and +@ref vertexFormat() for querying various aspects of a format and assembling it +from a set of singular properties. @see @ref Trade::MeshData, @ref Trade::MeshAttributeData, @ref Trade::MeshAttribute */ @@ -1364,8 +1370,9 @@ template constexpr T vertexFormatUnwrap(VertexFormat form @m_since{2020,06} To get size of a single component, call this function on a result of -@ref vertexFormatComponentFormat(). -@see @ref pixelFormatSize() +@ref vertexFormatComponentFormat(). Expects that the vertex format is *not* +implementation-specific. +@see @ref isVertexFormatImplementationSpecific(), @ref pixelFormatSize() */ MAGNUM_EXPORT UnsignedInt vertexFormatSize(VertexFormat format); @@ -1379,8 +1386,10 @@ The function also removes the normalization aspect from the format --- use @ref VertexFormat::UnsignedByte for @ref VertexFormat::Vector3ub. Calling @ref vertexFormatComponentCount() on the returned value will always give @cpp 1 @ce; calling @ref isVertexFormatNormalized() on the returned -value will always give @cpp false @ce. -@see @ref vertexFormat(VertexFormat, UnsignedInt, bool), +value will always give @cpp false @ce. Expects that the vertex format is *not* +implementation-specific. +@see @ref isVertexFormatImplementationSpecific(), + @ref vertexFormat(VertexFormat, UnsignedInt, bool), @ref pixelFormatChannelFormat() */ MAGNUM_EXPORT VertexFormat vertexFormatComponentFormat(VertexFormat format); @@ -1390,8 +1399,10 @@ MAGNUM_EXPORT VertexFormat vertexFormatComponentFormat(VertexFormat format); @m_since{2020,06} Returns @cpp 1 @ce for scalar formats and e.g. @cpp 3 @ce for -@ref VertexFormat::Vector3ub. -@see @ref vertexFormat(VertexFormat, UnsignedInt, bool), +@ref VertexFormat::Vector3ub. Expects that the vertex format is *not* +implementation-specific. +@see @ref isVertexFormatImplementationSpecific(), + @ref vertexFormat(VertexFormat, UnsignedInt, bool), @ref pixelFormatChannelCount() */ MAGNUM_EXPORT UnsignedInt vertexFormatComponentCount(VertexFormat format); @@ -1401,7 +1412,9 @@ MAGNUM_EXPORT UnsignedInt vertexFormatComponentCount(VertexFormat format); @m_since{2020,06} Returns @cpp 1 @ce for scalar and vector formats and e.g. @cpp 3 @ce for -@ref VertexFormat::Matrix3x2d. +@ref VertexFormat::Matrix3x2d. Expects that the vertex format is *not* +implementation-specific. +@see @ref isVertexFormatImplementationSpecific() */ MAGNUM_EXPORT UnsignedInt vertexFormatVectorCount(VertexFormat format); @@ -1411,7 +1424,9 @@ MAGNUM_EXPORT UnsignedInt vertexFormatVectorCount(VertexFormat format); Returns type size for scalar and vector formats and e.g. @cpp 8 @ce for @ref VertexFormat::Matrix2x3hAligned (but @cpp 6 @ce for -@ref VertexFormat::Matrix2x3h). +@ref VertexFormat::Matrix2x3h). Expects that the vertex format is *not* +implementation-specific. +@see @ref isVertexFormatImplementationSpecific() */ MAGNUM_EXPORT UnsignedInt vertexFormatVectorStride(VertexFormat format); @@ -1422,8 +1437,10 @@ MAGNUM_EXPORT UnsignedInt vertexFormatVectorStride(VertexFormat format); Returns @cpp true @ce for `*Normalized` formats, @cpp false @ce otherwise. In particular, floating-point formats are *not* treated as normalized, even though for example colors might commonly have values only in the @f$ [0.0, 1.0] @f$ -range (or normals in the @f$ [-1.0, 1.0] @f$ range). -@see @ref vertexFormat(VertexFormat, UnsignedInt, bool) +range (or normals in the @f$ [-1.0, 1.0] @f$ range). Expects that the vertex +format is *not* implementation-specific. +@see @ref isVertexFormatImplementationSpecific(), + @ref vertexFormat(VertexFormat, UnsignedInt, bool) */ MAGNUM_EXPORT bool isVertexFormatNormalized(VertexFormat format); @@ -1432,10 +1449,19 @@ MAGNUM_EXPORT bool isVertexFormatNormalized(VertexFormat format); @m_since{2020,06} Converts @p format to a new format of desired component count and -normalization. Expects that @p componentCount is not larger than @cpp 4 @ce and -@p normalized is @cpp true @ce only for 8- and 16-byte integer formats. -@see @ref vertexFormatComponentFormat(), - @ref vertexFormatComponentCount(), +normalization. Expects that @p componentCount is @cpp 1 @ce, @cpp 2 @ce, +@cpp 3 @ce or @cpp 4 @ce and @p normalized is @cpp true @ce only for 8- and +16-bit integer formats. Expects that the vertex format is *not* +implementation-specific. + +Example usage --- picking a format for four-component tangents to match an +existing (three-component) vertex normal format: + +@snippet Magnum.cpp vertexFormat + +@see @ref isVertexFormatImplementationSpecific(), + @ref vertexFormat(VertexFormat, UnsignedInt, UnsignedInt, bool), + @ref vertexFormatComponentFormat(), @ref vertexFormatComponentCount(), @ref isVertexFormatNormalized() */ MAGNUM_EXPORT VertexFormat vertexFormat(VertexFormat format, UnsignedInt componentCount, bool normalized); @@ -1447,11 +1473,12 @@ MAGNUM_EXPORT VertexFormat vertexFormat(VertexFormat format, UnsignedInt compone Converts @p format to a new format of desired component and vertex count and normalization. Expects that both @p vectorCount and @p componentCount is either @cpp 2 @ce, @cpp 3 @ce or @cpp 4 @ce, and @p format is floating-point or -8-/16-bit signed integer. -@see @ref vertexFormatComponentFormat(), - @ref vertexFormatComponentCount(), - @ref vertexFormatVectorCount(), - @ref vertexFormatVectorStride(), +8-/16-bit signed integer. Expects that the vertex format is *not* +implementation-specific. +@see @ref isVertexFormatImplementationSpecific(), + @ref vertexFormat(VertexFormat, UnsignedInt, bool), + @ref vertexFormatComponentFormat(), @ref vertexFormatComponentCount(), + @ref vertexFormatVectorCount(), @ref vertexFormatVectorStride(), @ref isVertexFormatNormalized() */ MAGNUM_EXPORT VertexFormat vertexFormat(VertexFormat format, UnsignedInt vectorCount, UnsignedInt componentCount, bool aligned);