Magnum::Trade::MeshAttributeData class new in 2020.06

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.

Offset-only attribute data

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:

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.