Magnum::Trade::MeshAttributeData class new in 2020.06
#include <Magnum/Trade/MeshData.h>

Mesh attribute data.

Convenience type for populating MeshData, see its documentation for an introduction. Additionally usable in various MeshTools algorithms such as MeshTools::duplicate(const Trade::MeshData& data, Containers::ArrayView<const Trade::MeshAttributeData>) or MeshTools::interleave(const Trade::MeshData& data, Containers::ArrayView<const Trade::MeshAttributeData>, InterleaveFlags).

Usage

The most straightforward usage is constructing an instance from a pair of a MeshAttribute and a strided view. The VertexFormat gets inferred from the view type:

Containers::StridedArrayView1D<const Vector3> positions;

Trade::MeshAttributeData data{Trade::MeshAttribute::Position, positions};

Alternatively, you can pass a typeless const void or a 2D view and supply VertexFormat explicitly.

If the actual attribute data location is not known yet, the instance can be created as "offset-only" using MeshAttributeData(MeshAttribute, VertexFormat, std::size_t, UnsignedInt, std::ptrdiff_t, UnsignedShort, Int), meaning the actual view gets created only later when passed to a MeshData instance with a concrete vertex data array. This is 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.

struct Vertex {
    Vector3 position;
    Vector4 color;
};

Trade::MeshAttributeData positions{Trade::MeshAttribute::Position,
    VertexFormat::Vector3, offsetof(Vertex, position), vertexCount, sizeof(Vertex)};
Trade::MeshAttributeData colors{Trade::MeshAttribute::Color,
    VertexFormat::Vector4, offsetof(Vertex, color), vertexCount, sizeof(Vertex)};

See the corresponding MeshData documentation for a complete usage example. Offset-only attributes return true for isOffsetOnly(). Note that MeshTools algorithms generally don't accept offset-only MeshAttributeData instances except when passed through a MeshData, as for a standalone offset-only MeshAttributeData it's impossible to know what data it points to.

Custom vertex formats

Apart from custom MeshAttribute names, shown in Custom mesh attributes, VertexFormat can be extended with implementation-specific formats as well. Formats that don't have a generic VertexFormat equivalent can be created using vertexFormatWrap(), however note that most APIs and MeshTools functions can't work with those as their size or contents can't be known:

Trade::MeshAttributeData normals{Trade::MeshAttribute::Normal,
    vertexFormatWrap(VK_FORMAT_B10G11R11_UFLOAT_PACK32),
    data};

Constructors, destructors, conversion operators

MeshAttributeData() explicit constexpr noexcept: Default constructor.
MeshAttributeData(MeshAttribute name, VertexFormat format, const Containers::StridedArrayView1D<const void>& data, UnsignedShort arraySize = 0, Int morphTargetId = -1) explicit noexcept: Type-erased constructor.
MeshAttributeData(MeshAttribute name, VertexFormat format, const Containers::StridedArrayView2D<const char>& data, UnsignedShort arraySize = 0, Int morphTargetId = -1) explicit noexcept: Constructor.
MeshAttributeData(MeshAttribute name, VertexFormat format, std::nullptr_t, UnsignedShort arraySize = 0, Int morphTargetId = -1) explicit noexcept
template<class T> MeshAttributeData(MeshAttribute name, const Containers::StridedArrayView1D<T>& data, Int morphTargetId = -1) explicit constexpr noexcept: Constructor.
template<class T> MeshAttributeData(MeshAttribute name, const Containers::ArrayView<T>& data, Int morphTargetId = -1) explicit constexpr noexcept
template<class T> MeshAttributeData(MeshAttribute name, const Containers::StridedArrayView2D<T>& data, Int morphTargetId = -1) explicit constexpr noexcept: Construct an array attribute.
MeshAttributeData(MeshAttribute name, VertexFormat format, std::size_t offset, UnsignedInt vertexCount, std::ptrdiff_t stride, UnsignedShort arraySize = 0, Int morphTargetId = -1) explicit constexpr noexcept: Construct an offset-only attribute.
MeshAttributeData(Int padding) explicit constexpr: Construct a pad value.

Public functions

auto isOffsetOnly() const -> bool constexpr: If the attribute is offset-only.
auto name() const -> MeshAttribute constexpr: Attribute name.
auto format() const -> VertexFormat constexpr: Attribute format.
auto offset(Containers::ArrayView<const void> vertexData) const -> std::size_t: Attribute offset.
auto stride() const -> Short constexpr: Attribute stride.
auto arraySize() const -> UnsignedShort constexpr: Attribute array size.
auto morphTargetId() const -> Int constexpr new in Git master: Morph target ID.
auto data() const -> Containers::StridedArrayView1D<const void> constexpr: Type-erased attribute data.
auto data(Containers::ArrayView<const void> vertexData) const -> Containers::StridedArrayView1D<const void>: Type-erased attribute data for an offset-only attribute.

Function documentation

Magnum::Trade::MeshAttributeData::MeshAttributeData() explicit constexpr noexcept

Default constructor.

Leaves contents at unspecified values. Provided as a convenience for initialization of the attribute array for MeshData, expected to be replaced with concrete values later.

Magnum::Trade::MeshAttributeData::MeshAttributeData(MeshAttribute name, VertexFormat format, const Containers::StridedArrayView1D<const void>& data, UnsignedShort arraySize = 0, Int morphTargetId = -1) explicit noexcept

Type-erased constructor.

Parameters
name	Attribute name
format	Vertex format
data	Attribute data
arraySize	Array size. Use `0` for non-array attributes.
morphTargetId	Morph target ID. Use `-1` for attributes that are not morph targets.

Expects that data stride fits into a signed 16-bit value, that vertex count fits into 32 bits, and for builtin attributes that format corresponds to name, arraySize is either zero for non-array attributes or non-zero for array attributes. The morphTargetId is expected to be greater or equal to -1 and less than 128 and has to be -1 for builtin attributes that can't be morph targets. The stride can be zero or negative, but note that such data layouts are not commonly supported by GPU APIs.

Magnum::Trade::MeshAttributeData::MeshAttributeData(MeshAttribute name, VertexFormat format, const Containers::StridedArrayView2D<const char>& data, UnsignedShort arraySize = 0, Int morphTargetId = -1) explicit noexcept

Constructor.

Parameters
name	Attribute name
format	Vertex format
data	Attribute data
arraySize	Array size. Use `0` for non-array attributes.
morphTargetId	Morph target ID. Use `-1` for attributes that are not morph targets.

Expects that the second dimension of data is contiguous and its size matches format and arraySize, and for builtin attributes that format corresponds to name and arraySize is either zero for non-array attributes or non-zero for array attributes. The morphTargetId is expected to be greater or equal to -1 and less than 128 and has to be -1 for builtin attributes that can't be morph targets. The stride is expected to fit into a signed 16-bit value. It can be zero or negative, but note that such data layouts are not commonly supported by GPU APIs.

Magnum::Trade::MeshAttributeData::MeshAttributeData(MeshAttribute name, VertexFormat format, std::nullptr_t, UnsignedShort arraySize = 0, Int morphTargetId = -1) explicit noexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class T>
Magnum::Trade::MeshAttributeData::MeshAttributeData(MeshAttribute name, const Containers::StridedArrayView1D<T>& data, Int morphTargetId = -1) explicit constexpr noexcept

Constructor.

Parameters
name	Attribute name
data	Attribute data
morphTargetId	Morph target ID. Use `-1` for attributes that are not morph targets.

Detects VertexFormat based on T and calls MeshAttributeData(MeshAttribute, VertexFormat, const Containers::StridedArrayView1D<const void>&, UnsignedShort, Int). For most types known by Magnum, the detected VertexFormat is of the same name as the type (so e.g. Vector3ui gets recognized as VertexFormat::Vector3ui), with the following exceptions:

Color3ub is recognized as VertexFormat::Vector3ubNormalized
Color3us is recognized as VertexFormat::Vector3usNormalized
Color4ub is recognized as VertexFormat::Vector4ubNormalized
Color4us is recognized as VertexFormat::Vector4usNormalized
Matrix2x2b is recognized as VertexFormat::Matrix2x2bNormalized (and similarly for other matrix sizes)
Matrix2x2s is recognized as VertexFormat::Matrix2x2sNormalized (and similarly for other matrix sizes)

This also means that if you have a Vector2s, for example, and want to pick a VertexFormat::Vector2sNormalized instead of the (autodetected) VertexFormat::Vector2s, you need to specify it explicitly — there's no way the library can infer this from the type alone, except for the color types above (which are generally always normalized).

template<class T>
Magnum::Trade::MeshAttributeData::MeshAttributeData(MeshAttribute name, const Containers::ArrayView<T>& data, Int morphTargetId = -1) explicit constexpr noexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class T>
Magnum::Trade::MeshAttributeData::MeshAttributeData(MeshAttribute name, const Containers::StridedArrayView2D<T>& data, Int morphTargetId = -1) explicit constexpr noexcept

Construct an array attribute.

Parameters
name	Attribute name
data	Attribute data
morphTargetId	Morph target ID. Use `-1` for attributes that are not morph targets.

Detects VertexFormat based on T and calls MeshAttributeData(MeshAttribute, VertexFormat, const Containers::StridedArrayView1D<const void>&, UnsignedShort, Int) with the second dimension size passed to arraySize. Expects that the second dimension is contiguous, and if name is a builtin attribute, it's an array attribute. See MeshAttributeData(MeshAttribute, const Containers::StridedArrayView1D<T>&, Int) for details about VertexFormat detection.

Magnum::Trade::MeshAttributeData::MeshAttributeData(MeshAttribute name, VertexFormat format, std::size_t offset, UnsignedInt vertexCount, std::ptrdiff_t stride, UnsignedShort arraySize = 0, Int morphTargetId = -1) explicit constexpr noexcept

Construct an offset-only attribute.

Parameters
name	Attribute name
format	Attribute format
offset	Attribute data offset
vertexCount	Attribute vertex count
stride	Attribute stride
arraySize	Array size. Use `0` for non-array attributes.
morphTargetId	Morph target ID. Use `-1` for attributes that are not morph targets.

Instances created this way refer to an offset in unspecified external vertex data instead of containing the data view directly. Useful when the location of the vertex data array is not known at attribute construction time. Note that instances created this way can't be used in most MeshTools algorithms.

For builtin attributes expects that arraySize is zero for non-array attributes and non-zero for array attributes. The morphTargetId is expected to be greater or equal to -1 and less than 128 and has to be -1 for builtin attributes that can't be morph targets. The stride is expected to fit into a signed 16-bit value. It can be zero or negative, but note that such data layouts are not commonly supported by GPU APIs.

Additionally, for even more flexibility, the vertexCount can be overridden at MeshData construction time, however all attributes are still required to have the same vertex count to catch accidents.

Magnum::Trade::MeshAttributeData::MeshAttributeData(Int padding) explicit constexpr

Construct a pad value.

Usable in various MeshTools algorithms to insert padding between interleaved attributes. Negative values can be used to alias multiple different attributes onto each other. Not meant to be passed to MeshData.

bool Magnum::Trade::MeshAttributeData::isOffsetOnly() const constexpr

If the attribute is offset-only.

Returns true if the attribute doesn't contain the data view directly, but instead refers to unspecified external vertex data.

std::size_t Magnum::Trade::MeshAttributeData::offset(Containers::ArrayView<const void> vertexData) const

Attribute offset.

If the attribute is offset-only, returns the offset directly, otherwise uses the vertexData parameter to calculate the offset.

Short Magnum::Trade::MeshAttributeData::stride() const constexpr

Attribute stride.

In rare cases the stride may be zero or negative, such data layouts are however not commonly supported by GPU APIs.

UnsignedShort Magnum::Trade::MeshAttributeData::arraySize() const constexpr

Attribute array size.

Returns 0 if the attribute isn't an array.

Int Magnum::Trade::MeshAttributeData::morphTargetId() const constexpr new in Git master

Morph target ID.

Returns -1 if the attribute isn't a morph target.

Containers::StridedArrayView1D<const void> Magnum::Trade::MeshAttributeData::data() const constexpr

Type-erased attribute data.

Expects that the attribute is not offset-only, in that case use the data(Containers::ArrayView<const void>) const overload instead. In rare cases the stride of the returned view may be zero or negative, such data layouts are however not commonly supported by GPU APIs.

Containers::StridedArrayView1D<const void> Magnum::Trade::MeshAttributeData::data(Containers::ArrayView<const void> vertexData) const

Type-erased attribute data for an offset-only attribute.

If the attribute is not offset-only, the vertexData parameter is ignored. In rare cases the stride of the returned view may be zero or negative, such data layouts are however not commonly supported by GPU APIs.

Containers::Array<MeshAttributeData> meshAttributeDataNonOwningArray(Containers::ArrayView<const MeshAttributeData> view) new in 2020.06

Create a non-owning array of MeshAttributeData items.

Useful when you have the attribute definitions statically defined (for example when the vertex data themselves are already defined at compile time) and don't want to allocate just to pass those to MeshData. See documentation about populating a MeshData instance for more information.