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>).

Usage

The most straightforward usage is constructing an instance from a pair of 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 view and supply VertexFormat explicitly, or a 2D view.

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 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:

struct Vertex {
    Vector3 position;
    Vector4 color;
};

/* Layout defined statically, 15 vertices in total */
constexpr Trade::MeshAttributeData positions{Trade::MeshAttribute::Position,
    VertexFormat::Vector3, offsetof(Vertex, position), 15, sizeof(Vertex)};
constexpr Trade::MeshAttributeData colors{Trade::MeshAttribute::Color,
    VertexFormat::Vector4, offsetof(Vertex, color), 15, sizeof(Vertex)};

/* Actual data populated later */
Containers::Array<char> vertexData{15*sizeof(Vertex)};
// ...
Trade::MeshData{MeshPrimitive::Triangles, std::move(vertexData),
    {positions, colors}};

Note that MeshTools algorithms generally don't accept offset-only MeshAttributeData instances except when passed through a MeshData instance.

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) explicit noexcept
Type-erased constructor.
MeshAttributeData(MeshAttribute name, VertexFormat format, const Containers::StridedArrayView2D<const char>& data, UnsignedShort arraySize = 0) explicit noexcept
Constructor.
MeshAttributeData(MeshAttribute name, VertexFormat format, std::nullptr_t, UnsignedShort arraySize = 0) explicit noexcept
template<class T>
MeshAttributeData(MeshAttribute name, const Containers::StridedArrayView1D<T>& data) explicit constexpr noexcept
Constructor.
template<class T>
MeshAttributeData(MeshAttribute name, const Containers::ArrayView<T>& data) explicit constexpr noexcept
template<class T>
MeshAttributeData(MeshAttribute name, const Containers::StridedArrayView2D<T>& data) 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) 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 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) explicit noexcept

Type-erased constructor.

Parameters
name Attribute name
format Vertex format
data Attribute data
arraySize Array size. Use 0 for non-array attributes.

Expects that data stride is large enough to fit all arraySize items of type, type corresponds to name and arraySize is zero for builtin attributes.

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

Constructor.

Parameters
name Attribute name
format Vertex format
data Attribute data
arraySize Array size. Use 0 for non-array attributes.

Expects that the second dimension of data is contiguous and its size matches type and arraSize, that type corresponds to name and arraySize is zero for builtin attributes.

Magnum::Trade::MeshAttributeData::MeshAttributeData(MeshAttribute name, VertexFormat format, std::nullptr_t, UnsignedShort arraySize = 0) 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) explicit constexpr noexcept

Constructor.

Parameters
name Attribute name
data Attribute data

Detects VertexFormat based on T and calls MeshAttributeData(MeshAttribute, VertexFormat, const Containers::StridedArrayView1D<const void>&, UnsignedShort). 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) 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) explicit constexpr noexcept

Construct an array attribute.

Parameters
name Attribute name
data Attribute data

Detects VertexFormat based on T and calls MeshAttributeData(MeshAttribute, VertexFormat, const Containers::StridedArrayView1D<const void>&, UnsignedShort) with the second dimension size passed to arraySize. Expects that the second dimension is contiguous. At the moment only custom attributes can be arrays, which means this function can't be used with a builtin name. See MeshAttributeData(MeshAttribute, const Containers::StridedArrayView1D<T>&) 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) 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.

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. Expects that arraySize is zero for builtin attributes. Note that instances created this way can't be used in most MeshTools algorithms.

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

Note that due to the constexpr nature of this constructor, no format / arraySize checks against stride can be done. You're encouraged to use the MeshAttributeData(MeshAttribute, VertexFormat, const Containers::StridedArrayView1D<const void>&, UnsignedShort) constructor if you want additional safeguards.

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.

Can be negative for pad values, never negative for real attributes.

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.

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.

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.