class new in 2020.06
#include <Magnum/Trade/MeshData.h>
MeshAttributeData Mesh attribute data.
Convenience type for populating MeshData, see its documentation for an introduction. Additionally usable in various MeshTools algorithms such as MeshTools::
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::
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::
- 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::
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::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::
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.
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::
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.