diff --git a/src/Magnum/Trade/MeshData.h b/src/Magnum/Trade/MeshData.h index 672fd700a..f6bb54bbc 100644 --- a/src/Magnum/Trade/MeshData.h +++ b/src/Magnum/Trade/MeshData.h @@ -1379,7 +1379,8 @@ class MAGNUM_TRADE_EXPORT MeshData { * In case given attribute is an array (the equivalent of e.g. * @cpp int[30] @ce), returns array size, otherwise returns @cpp 0 @ce. * At the moment only custom attributes can be arrays, no builtin - * @ref MeshAttribute is an array attribute. You can also use + * @ref MeshAttribute is an array attribute. The @p id is expected to + * be smaller than @ref attributeCount() const. You can also use * @ref attributeArraySize(MeshAttribute, UnsignedInt) const to * directly get array size of given named attribute. * @@ -1447,22 +1448,18 @@ class MAGNUM_TRADE_EXPORT MeshData { /** * @brief Offset of a named attribute * - * Byte offset of the first element of given named attribute from the - * beginning of the @ref vertexData() array. The @p id is expected to - * be smaller than @ref attributeCount(MeshAttribute) const. - * @see @ref attributeOffset(UnsignedInt) const + * The @p id is expected to be smaller than + * @ref attributeCount(MeshAttribute) const. See + * @ref attributeOffset(UnsignedInt) const for more information. */ std::size_t attributeOffset(MeshAttribute name, UnsignedInt id = 0) const; /** * @brief Stride of a named attribute * - * Stride between consecutive elements of given named attribute in the - * @ref vertexData() array. In rare cases the stride may be zero or - * negative, such data layouts are however not commonly supported by - * GPU APIs. The @p id is expected to be smaller than - * @ref attributeCount(MeshAttribute) const. - * @see @ref attributeStride(UnsignedInt) const + * The @p id is expected to be smaller than + * @ref attributeCount(MeshAttribute) const. See + * @ref attributeStride(UnsignedInt) const for more information. */ Short attributeStride(MeshAttribute name, UnsignedInt id = 0) const; @@ -1489,7 +1486,9 @@ class MAGNUM_TRADE_EXPORT MeshData { * such data layouts are however not commonly supported by GPU APIs. * * Use the templated overload below to get the attribute in a concrete - * type. + * type. You can also use + * @ref attribute(MeshAttribute, UnsignedInt) const to directly get + * data for given named attribute. * @see @relativeref{Corrade,Containers::StridedArrayView::isContiguous()}, * @ref vertexFormatSize(), * @ref isVertexFormatImplementationSpecific() @@ -1567,15 +1566,9 @@ class MAGNUM_TRADE_EXPORT MeshData { * @brief Data for given named attribute * * The @p id is expected to be smaller than - * @ref attributeCount(MeshAttribute) 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. - * In rare cases the first dimension stride may be zero or negative, - * such data layouts are however not commonly supported by GPU APIs. - * - * Use the templated overload below to get the attribute in a concrete - * type. + * @ref attributeCount(MeshAttribute) const. See + * @ref attribute(UnsignedInt) const for more information. Use the + * templated overload below to get the attribute in a concrete type. * @see @ref attribute(UnsignedInt) const, * @ref mutableAttribute(MeshAttribute, UnsignedInt), * @relativeref{Corrade,Containers::StridedArrayView::isContiguous()}, diff --git a/src/Magnum/Trade/SceneData.h b/src/Magnum/Trade/SceneData.h index 536388b72..9f63f004b 100644 --- a/src/Magnum/Trade/SceneData.h +++ b/src/Magnum/Trade/SceneData.h @@ -496,15 +496,16 @@ enum class SceneFieldType: UnsignedShort { /** * @cpp const void* @ce, type is not preserved. For convenience it's - * possible to retrieve the value by calling @cpp field() @ce - * with an arbitrary `T` but the user has to ensure the type is correct. + * possible to retrieve the value by calling + * @ref SceneData::field() "field()" with an arbitrary `T` but + * the user has to ensure the type is correct. */ Pointer, /** * @cpp void* @ce, type is not preserved. For convenience it's possible to - * retrieve the value by calling @cpp field() @ce with an arbitrary `T` - * but the user has to ensure the type is correct. + * retrieve the value by calling @ref SceneData::field() "field()" with + * an arbitrary `T` but the user has to ensure the type is correct. */ MutablePointer, }; @@ -783,7 +784,7 @@ class MAGNUM_TRADE_EXPORT SceneFieldData { * @p fieldType / @p fieldArraySize checks against @p fieldStride can * be done. You're encouraged to use the @ref SceneFieldData(SceneField, SceneMappingType, const Containers::StridedArrayView1D&, SceneFieldType, const Containers::StridedArrayView1D&, UnsignedShort, SceneFieldFlags) * constructor if you want additional safeguards. - * @see @ref flags(), @ref fieldArraySize(), + * @see @ref flags(), @ref fieldArraySize() const, * @ref mappingData(Containers::ArrayView) const, * @ref fieldData(Containers::ArrayView) const */ @@ -1562,6 +1563,9 @@ class MAGNUM_TRADE_EXPORT SceneData { * * The @p fieldId is expected to be smaller than @ref fieldCount() and * @p object smaller than @ref mappingBound(). + * + * You can also use @ref hasFieldObject(SceneField, UnsignedLong) const + * to directly query object presence in given named field. */ bool hasFieldObject(UnsignedInt fieldId, UnsignedLong object) const; @@ -1606,8 +1610,11 @@ class MAGNUM_TRADE_EXPORT SceneData { * @brief Array size of a named field * @m_since_latest * - * The @p name is expected to exist. - * @see @ref hasField(), @ref fieldArraySize(UnsignedInt) const + * The @p name is expected to exist. Note that this is different from + * the count of entries for given field, which is exposed through + * @ref fieldSize(SceneField) const. See @ref fieldArraySize(UnsignedInt) const + * for more information. + * @see @ref hasField() */ UnsignedShort fieldArraySize(SceneField name) const; @@ -1619,7 +1626,8 @@ class MAGNUM_TRADE_EXPORT SceneData { * second dimension represents the actual data type (its size is equal * to @ref SceneMappingType size) and is guaranteed to be contiguous. * Use the templated overload below to get the mapping in a concrete - * type. + * type. You can also use @ref mapping(SceneField) const to directly + * get object mapping data for given named field. * @see @ref mutableMapping(UnsignedInt), * @ref Corrade::Containers::StridedArrayView::isContiguous(), * @ref sceneMappingTypeSize() @@ -1671,14 +1679,11 @@ class MAGNUM_TRADE_EXPORT SceneData { * @brief Object mapping data for given named field * @m_since_latest * - * The @p fieldName is expected to exist. The second dimension - * represents the actual data type (its size is equal to - * @ref SceneMappingType size) and is guaranteed to be contiguous. Use - * the templated overload below to get the object mapping in a concrete + * The @p fieldName is expected to exist. See + * @ref mapping(UnsignedInt) const for more information. Use the + * templated overload below to get the object mapping in a concrete * type. - * @see @ref hasField(), @ref mapping(UnsignedInt) const, - * @ref mutableMapping(SceneField), - * @ref Corrade::Containers::StridedArrayView::isContiguous() + * @see @ref hasField(), @ref mutableMapping(SceneField) */ Containers::StridedArrayView2D mapping(SceneField fieldName) const; @@ -1710,7 +1715,7 @@ class MAGNUM_TRADE_EXPORT SceneData { * converted to the usual type, but note that these operations involve * extra allocation and data conversion. * @see @ref hasField(), @ref mapping(UnsignedInt) const, - * @ref mutableMapping(UnsignedInt) + * @ref mutableMapping(SceneField) */ template Containers::StridedArrayView1D mapping(SceneField fieldName) const; @@ -1732,7 +1737,9 @@ class MAGNUM_TRADE_EXPORT SceneData { * second dimension represents the actual data type (its size is equal * to @ref SceneFieldType size, possibly multiplied by array size) and * is guaranteed to be contiguous. Use the templated overload below to - * get the field in a concrete type. + * get the field in a concrete type. You can also use + * @ref field(SceneField) const to directly get data for given named + * field. * @see @ref Corrade::Containers::StridedArrayView::isContiguous(), * @ref sceneFieldTypeSize(), @ref mutableField(UnsignedInt) */ @@ -1809,14 +1816,10 @@ class MAGNUM_TRADE_EXPORT SceneData { * @brief Data for given named field * @m_since_latest * - * The @p name is expected to exist. The second dimension represents - * the actual data type (its size is equal to @ref SceneFieldType size, - * possibly multiplied by array size) and is guaranteed to be - * contiguous. Use the templated overload below to get the field in a - * concrete type. - * @see @ref hasField(), @ref field(UnsignedInt) const, - * @ref mutableField(SceneField), - * @ref Corrade::Containers::StridedArrayView::isContiguous() + * The @p name is expected to exist. See @ref field(UnsignedInt) const + * for more information. Use the templated overload below to get the + * field in a concrete type. + * @see @ref hasField(), @ref mutableField(SceneField) */ Containers::StridedArrayView2D field(SceneField name) const; @@ -1848,7 +1851,8 @@ class MAGNUM_TRADE_EXPORT SceneData { * @ref importerStateAsArray() accessors to get common fields converted * to usual types, but note that these operations involve extra * allocation and data conversion. - * @see @ref field(UnsignedInt) const, @ref mutableField(SceneField) + * @see @ref hasField(), @ref field(UnsignedInt) const, + * @ref mutableField(SceneField) */ template::value>::type> Containers::StridedArrayView1D field(SceneField name) const; @@ -2828,7 +2832,7 @@ class MAGNUM_TRADE_EXPORT SceneData { be then passed to fieldData{Mapping,Field}ViewInternal(). */ MAGNUM_TRADE_LOCAL std::size_t findFieldObjectOffsetInternal(const SceneFieldData& field, UnsignedLong object, std::size_t offset) const; - /* Like objects() / field(), but returning just a 1D view, sliced from + /* Like mapping() / field(), but returning just a 1D view, sliced from offset to offset + size. The parameterless overloads are equal to offset = 0 and size = field.size(). */ MAGNUM_TRADE_LOCAL Containers::StridedArrayView1D fieldDataMappingViewInternal(const SceneFieldData& field, std::size_t offset, std::size_t size) const;