Magnum::Trade::SceneFieldData class new in Git master

Scene field data.

Convenience type for populating SceneData, see its documentation for an introduction.

Usage

The most straightforward usage is constructing an instance from a SceneField and a strided view for the field data and object mapping. The SceneMappingType and SceneFieldType get inferred from the view types:

Containers::StridedArrayView1D<UnsignedInt> transformationMapping = ;
Containers::StridedArrayView1D<Matrix4> transformations = ;

Trade::SceneFieldData field{Trade::SceneField::Transformation,
    transformationMapping, transformations};

Alternatively, you can pass typeless const void or 2D views and supply SceneMappingType and SceneFieldType explicitly.

Offset-only field data

If the actual field / object 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 SceneData instance with a concrete data array. This is useful mainly to avoid pointer patching during data serialization, less so when the data layout is static (and thus can be defined at compile time), but the actual data is allocated / populated at runtime:

struct Node {
    UnsignedInt object;
    Int parent;
    Matrix4 transform;
};

/* Layout defined statically, 120 objects in total */
constexpr Trade::SceneFieldData parents{Trade::SceneField::Parent, 120,
    Trade::SceneMappingType::UnsignedInt, offsetof(Node, object), sizeof(Node),
    Trade::SceneFieldType::Int, offsetof(Node, parent), sizeof(Node)};
constexpr Trade::SceneFieldData transforms{Trade::SceneField::Transformation, 120,
    Trade::SceneMappingType::UnsignedInt, offsetof(Node, object), sizeof(Node),
    Trade::SceneFieldType::Matrix4x4, offsetof(Node, transform), sizeof(Node)};

/* Actual data populated later */
Containers::Array<char> data{120*sizeof(Node)};

Trade::SceneData{Trade::SceneMappingType::UnsignedInt, 120, std::move(data),
    {parents, transforms}};

Offset-only fields are marked with SceneFieldFlag::OffsetOnly in flags().

Ordered and implicit object mapping

If you can guarantee the object mapping field is monotonically non-decreasing, it's recommended to annotate it with SceneFieldFlag::OrderedMapping. This makes certain convenience APIs such as SceneData::findFieldObjectOffset() or e.g. transformation3DFor() perform the lookup in $ \mathcal{O}(\log{} n) $ instead of $ \mathcal{O}(n) $ . Data consuming algorithms on the application side can then also adapt based on what flags are present in SceneData::fieldFlags().

In some cases the object mapping is even implicit, i.e. the first entry of the field specifying data for object 0, second entry for object 1, third for object 2 and so on. You can annotate such fields with SceneFieldFlag::ImplicitMapping, which is a superset of OrderedMapping.

Constructors, destructors, conversion operators

SceneFieldData() explicit constexpr noexcept
Default constructor.
SceneFieldData(SceneField name, SceneMappingType mappingType, const Containers::StridedArrayView1D<const void>& mappingData, SceneFieldType fieldType, const Containers::StridedArrayView1D<const void>& fieldData, UnsignedShort fieldArraySize = 0, SceneFieldFlags flags = {}) explicit constexpr noexcept
Type-erased constructor.
SceneFieldData(SceneField name, SceneMappingType mappingType, const Containers::StridedArrayView1D<const void>& mappingData, SceneFieldType fieldType, const Containers::StridedArrayView1D<const void>& fieldData, SceneFieldFlags flags) explicit constexpr noexcept
SceneFieldData(SceneField name, const Containers::StridedArrayView2D<const char>& mappingData, SceneFieldType fieldType, const Containers::StridedArrayView2D<const char>& fieldData, UnsignedShort fieldArraySize = 0, SceneFieldFlags flags = {}) explicit noexcept
Constructor.
SceneFieldData(SceneField name, const Containers::StridedArrayView2D<const char>& mappingData, SceneFieldType fieldType, const Containers::StridedArrayView2D<const char>& fieldData, SceneFieldFlags flags) explicit noexcept
template<class T, class U>
SceneFieldData(SceneField name, const Containers::StridedArrayView1D<T>& mappingData, const Containers::StridedArrayView1D<U>& fieldData, SceneFieldFlags flags = {}) explicit constexpr noexcept
Constructor.
template<class T, class U>
SceneFieldData(SceneField name, const Containers::StridedArrayView1D<T>& mappingData, const Containers::ArrayView<U>& fieldData, SceneFieldFlags flags = {}) explicit constexpr noexcept
template<class T, class U>
SceneFieldData(SceneField name, const Containers::ArrayView<T>& mappingData, const Containers::StridedArrayView1D<U>& fieldData, SceneFieldFlags flags = {}) explicit constexpr noexcept
template<class T, class U>
SceneFieldData(SceneField name, const Containers::ArrayView<T>& mappingData, const Containers::ArrayView<U>& fieldData, SceneFieldFlags flags = {}) explicit constexpr noexcept
template<class T, class U>
SceneFieldData(SceneField name, const Containers::StridedArrayView1D<T>& mappingData, const Containers::StridedArrayView2D<U>& fieldData, SceneFieldFlags flags = {}) explicit constexpr noexcept
Construct an array field.
template<class T, class U>
SceneFieldData(SceneField name, const Containers::ArrayView<T>& mappingData, const Containers::StridedArrayView2D<U>& fieldData, SceneFieldFlags flags = {}) explicit constexpr noexcept
SceneFieldData(SceneField name, std::size_t size, SceneMappingType mappingType, std::size_t mappingOffset, std::ptrdiff_t mappingStride, SceneFieldType fieldType, std::size_t fieldOffset, std::ptrdiff_t fieldStride, UnsignedShort fieldArraySize = 0, SceneFieldFlags flags = {}) explicit constexpr noexcept
Construct an offset-only field.
SceneFieldData(SceneField name, std::size_t size, SceneMappingType mappingType, std::size_t mappingOffset, std::ptrdiff_t mappingStride, SceneFieldType fieldType, std::size_t fieldOffset, std::ptrdiff_t fieldStride, SceneFieldFlags flags) explicit constexpr noexcept

Public functions

auto flags() const -> SceneFieldFlags constexpr
Field flags.
auto name() const -> SceneField constexpr
Field name.
auto size() const -> UnsignedLong constexpr
Number of entries.
auto mappingType() const -> SceneMappingType constexpr
Object mapping type.
auto mappingData() const -> Containers::StridedArrayView1D<const void> constexpr
Type-erased object mapping data.
auto mappingData(Containers::ArrayView<const void> data) const -> Containers::StridedArrayView1D<const void>
Type-erased object mapping data for an offset-only attribute.
auto fieldType() const -> SceneFieldType constexpr
Field type.
auto fieldArraySize() const -> UnsignedShort constexpr
Field array size.
auto fieldData() const -> Containers::StridedArrayView1D<const void> constexpr
Type-erased field data.
auto fieldData(Containers::ArrayView<const void> data) const -> Containers::StridedArrayView1D<const void>
Type-erased field data for an offset-only attribute.

Function documentation

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

Default constructor.

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

Magnum::Trade::SceneFieldData::SceneFieldData(SceneField name, SceneMappingType mappingType, const Containers::StridedArrayView1D<const void>& mappingData, SceneFieldType fieldType, const Containers::StridedArrayView1D<const void>& fieldData, UnsignedShort fieldArraySize = 0, SceneFieldFlags flags = {}) explicit constexpr noexcept

Type-erased constructor.

Parameters
name Field name
mappingType Object mapping type
mappingData Object mapping data
fieldType Field type
fieldData Field data
fieldArraySize Field array size. Use 0 for non-array fields.
flags Field flags. SceneFieldFlag::OffsetOnly is not allowed here.

Expects that mappingData and fieldData have the same size, fieldType corresponds to name and fieldArraySize is zero for builtin fields.

Magnum::Trade::SceneFieldData::SceneFieldData(SceneField name, SceneMappingType mappingType, const Containers::StridedArrayView1D<const void>& mappingData, SceneFieldType fieldType, const Containers::StridedArrayView1D<const void>& fieldData, SceneFieldFlags flags) 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.

Magnum::Trade::SceneFieldData::SceneFieldData(SceneField name, const Containers::StridedArrayView2D<const char>& mappingData, SceneFieldType fieldType, const Containers::StridedArrayView2D<const char>& fieldData, UnsignedShort fieldArraySize = 0, SceneFieldFlags flags = {}) explicit noexcept

Constructor.

Parameters
name Field name
mappingData Object mapping data
fieldType Field type
fieldData Field data
fieldArraySize Field array size. Use 0 for non-array fields.
flags Field flags. SceneFieldFlag::OffsetOnly is not allowed here.

Expects that mappingData and fieldData have the same size in the first dimension, that the second dimension of mappingData is contiguous and its size is either 1, 2, 4 or 8, corresponding to one of the SceneMappingType values, that the second dimension of fieldData is contiguous and its size matches fieldType and fieldArraySize and that fieldType corresponds to name and fieldArraySize is zero for builtin attributes.

Magnum::Trade::SceneFieldData::SceneFieldData(SceneField name, const Containers::StridedArrayView2D<const char>& mappingData, SceneFieldType fieldType, const Containers::StridedArrayView2D<const char>& fieldData, SceneFieldFlags flags) 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, class U>
Magnum::Trade::SceneFieldData::SceneFieldData(SceneField name, const Containers::StridedArrayView1D<T>& mappingData, const Containers::StridedArrayView1D<U>& fieldData, SceneFieldFlags flags = {}) explicit constexpr noexcept

Constructor.

Parameters
name Field name
mappingData Object mapping data
fieldData Field data
flags Field flags. SceneFieldFlag::OffsetOnly is not allowed here.

Detects SceneMappingType based on T and SceneFieldType based on U and calls SceneFieldData(SceneField, SceneMappingType, const Containers::StridedArrayView1D<const void>&, SceneFieldType, const Containers::StridedArrayView1D<const void>&, UnsignedShort, SceneFieldFlags). For all types known by Magnum, the detected SceneFieldType is of the same name as the type (so e.g. Vector3ui gets recognized as SceneFieldType::Vector3ui).

template<class T, class U>
Magnum::Trade::SceneFieldData::SceneFieldData(SceneField name, const Containers::StridedArrayView1D<T>& mappingData, const Containers::ArrayView<U>& fieldData, SceneFieldFlags flags = {}) 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, class U>
Magnum::Trade::SceneFieldData::SceneFieldData(SceneField name, const Containers::ArrayView<T>& mappingData, const Containers::StridedArrayView1D<U>& fieldData, SceneFieldFlags flags = {}) 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, class U>
Magnum::Trade::SceneFieldData::SceneFieldData(SceneField name, const Containers::ArrayView<T>& mappingData, const Containers::ArrayView<U>& fieldData, SceneFieldFlags flags = {}) 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, class U>
Magnum::Trade::SceneFieldData::SceneFieldData(SceneField name, const Containers::StridedArrayView1D<T>& mappingData, const Containers::StridedArrayView2D<U>& fieldData, SceneFieldFlags flags = {}) explicit constexpr noexcept

Construct an array field.

Parameters
name Field name
mappingData Object mapping data
fieldData Field data
flags Field flags. SceneFieldFlag::OffsetOnly is not allowed here.

Detects SceneMappingType based on T and SceneFieldType based on U and calls SceneFieldData(SceneField, SceneMappingType, const Containers::StridedArrayView1D<const void>&, SceneFieldType, const Containers::StridedArrayView1D<const void>&, UnsignedShort, SceneFieldFlags) with the fieldData second dimension size passed to fieldArraySize. Expects that the second dimension of fieldData is contiguous. At the moment only custom fields can be arrays, which means this function can't be used with a builtin name. See SceneFieldData(SceneField, const Containers::StridedArrayView1D<T>&, const Containers::StridedArrayView1D<U>&, SceneFieldFlags) for details about SceneMappingType and SceneFieldType detection.

template<class T, class U>
Magnum::Trade::SceneFieldData::SceneFieldData(SceneField name, const Containers::ArrayView<T>& mappingData, const Containers::StridedArrayView2D<U>& fieldData, SceneFieldFlags flags = {}) 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.

Magnum::Trade::SceneFieldData::SceneFieldData(SceneField name, std::size_t size, SceneMappingType mappingType, std::size_t mappingOffset, std::ptrdiff_t mappingStride, SceneFieldType fieldType, std::size_t fieldOffset, std::ptrdiff_t fieldStride, UnsignedShort fieldArraySize = 0, SceneFieldFlags flags = {}) explicit constexpr noexcept

Construct an offset-only field.

Parameters
name Field name
size Number of entries
mappingType Object mapping type
mappingOffset Object mapping data offset
mappingStride Object mapping data stride
fieldType Field type
fieldOffset Field data offset
fieldStride Field data stride
fieldArraySize Field array size. Use 0 for non-array fields.
flags Field flags. SceneFieldFlag::OffsetOnly is set implicitly.

Instances created this way refer to offsets in unspecified external scene data instead of containing the data views directly. Useful when the location of the scene data array is not known at field construction time. Expects that fieldType corresponds to name and fieldArraySize is zero for builtin attributes.

Note that due to the constexpr nature of this constructor, no mappingType checks against mappingStride or fieldType / fieldArraySize checks against fieldStride can be done. You're encouraged to use the SceneFieldData(SceneField, SceneMappingType, const Containers::StridedArrayView1D<const void>&, SceneFieldType, const Containers::StridedArrayView1D<const void>&, UnsignedShort, SceneFieldFlags) constructor if you want additional safeguards.

Magnum::Trade::SceneFieldData::SceneFieldData(SceneField name, std::size_t size, SceneMappingType mappingType, std::size_t mappingOffset, std::ptrdiff_t mappingStride, SceneFieldType fieldType, std::size_t fieldOffset, std::ptrdiff_t fieldStride, SceneFieldFlags flags) 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.

Containers::StridedArrayView1D<const void> Magnum::Trade::SceneFieldData::mappingData() const constexpr

Type-erased object mapping data.

Expects that the field does not have SceneFieldFlag::OffsetOnly set, in that case use the mappingData(Containers::ArrayView<const void>) const overload instead.

Containers::StridedArrayView1D<const void> Magnum::Trade::SceneFieldData::mappingData(Containers::ArrayView<const void> data) const

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

If the field does not have SceneFieldFlag::OffsetOnly set, the data parameter is ignored.

Containers::StridedArrayView1D<const void> Magnum::Trade::SceneFieldData::fieldData() const constexpr

Type-erased field data.

Expects that the field does not have SceneFieldFlag::OffsetOnly set, in that case use the fieldData(Containers::ArrayView<const void>) const overload instead.

Containers::StridedArrayView1D<const void> Magnum::Trade::SceneFieldData::fieldData(Containers::ArrayView<const void> data) const

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

If the field does not have SceneFieldFlag::OffsetOnly set, the data parameter is ignored.

Containers::Array<SceneFieldData> sceneFieldDataNonOwningArray(Containers::ArrayView<const SceneFieldData> view) new in Git master

Create a non-owning array of SceneFieldData items.

Useful when you have the field definitions statically defined (for example when the data themselves are already defined at compile time) and don't want to allocate just to pass those to SceneData.