From 66ae58987eb7251a912c7d42cf3d0c42d8b43c30 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Thu, 2 Sep 2021 18:53:10 +0200 Subject: [PATCH] [wip] docs --- doc/snippets/MagnumTrade.cpp | 57 +++++++++++++++++++++++++ src/Magnum/Trade/SceneData.h | 81 ++++++++++++++++++++++++++++++++++++ 2 files changed, 138 insertions(+) diff --git a/doc/snippets/MagnumTrade.cpp b/doc/snippets/MagnumTrade.cpp index 170253a948..5f48e6b273 100644 --- a/doc/snippets/MagnumTrade.cpp +++ b/doc/snippets/MagnumTrade.cpp @@ -887,4 +887,61 @@ CORRADE_IGNORE_DEPRECATED_POP } #endif +{ +/* [SceneData-populating] */ + +struct Trs { + Vector3 translation; + Quaternion rotation; + Vector3 scaling; +}; + +Containers::ArrayView transformations; + +// #error TODO accept strided array views here as well? +// Containers::ArrayTuple data{ +// {objectCount, transformation}, +// {objectCount, parent}, +// {objectCount, transformationParentObjectMapping}, +// {animatedObjectCount, trs}, +// {animatedObjectCount, animationId}, +// {animatedObjectCount, animatedObjectMapping}, +// {meshCount, meshMaterialId}, +// {meshCount, meshMaterialIdObjectMapping}, +// {lightCount, lightId}, +// {lightCount, lightIdObjectMapping}, +// {1, cameraId}, +// {1, cameraIdObjectMapping}, +// }; +// +// Trade::SceneData scene{objectCount, SceneObjectType::UnsignedInt, { +// Trade::SceneFieldData{Trade::SceneField::Transformation, +// transformation, transformationParentObjectMapping}, +// Trade::SceneFieldData{Trade::SceneField::Parent, +// transformation, transformationParentObjectMapping}, +// Trade::SceneFieldData{Trade::SceneField::Translation, +// Containers::stridedArrayView(transformation).slice(&Trs::translation), +// animatedObjectMapping}, +// Trade::SceneFieldData{Trade::SceneField::Rotation, +// Containers::stridedArrayView(transformation).slice(&Trs::rotation), +// animatedObjectMapping}, +// Trade::SceneFieldData{Trade::SceneField::Scaling, +// Containers::stridedArrayView(transformation).slice(&Trs::scaling), +// animatedObjectMapping}, +// Trade::SceneFieldData{Trade::SceneField::AnimationId, +// animationId, animatedObjectMapping}, +// Trade::SceneFieldData{Trade::SceneField::MeshId, +// Containers::stridedArrayView(meshMaterialId).slice(&MeshMaterial::mesh), +// meshMaterialIdObjectMapping}, +// Trade::SceneFieldData{Trade::SceneField::MeshMaterialId, +// Containers::stridedArrayView(meshMaterialId).slice(&MeshMaterial::material), +// meshMaterialIdObjectMapping}, +// Trade::SceneFieldData{Trade::SceneField::LightId, +// lightId, lightIdObjectMapping}, +// Trade::SceneFieldData{Trade::SceneField::CameraId, +// cameraId, cameraIdObjectMapping}, +// }}; +/* [SceneData-populating] */ +} + } diff --git a/src/Magnum/Trade/SceneData.h b/src/Magnum/Trade/SceneData.h index 9fa70c2207..c4a4337434 100644 --- a/src/Magnum/Trade/SceneData.h +++ b/src/Magnum/Trade/SceneData.h @@ -546,6 +546,29 @@ MAGNUM_TRADE_EXPORT UnsignedInt sceneFieldTypeAlignment(SceneFieldType type); Convenience type for populating @ref SceneData, see its documentation for an introduction. + +@section Trade-SceneFieldData-usage Usage + +The most straightforward usage is constructing an instance from a +@ref SceneField and a strided view for the field data and object mapping. The +@ref SceneObjectType and @ref SceneFieldType gets inferred from the view +types: + +@snippet MagnumTrade.cpp SceneFieldData-usage + +Alternatively, you can pass typeless @cpp const void @ce or 2D views and supply +@ref SceneObjectType and @ref SceneFieldType explicitly. + +@subsection Trade-SceneFieldData-usage-offset-only 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 @ref 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: + +@snippet MagnumTrade.cpp SceneFieldData-usage-offset-only */ class MAGNUM_TRADE_EXPORT SceneFieldData { public: @@ -795,6 +818,64 @@ Containers::Array MAGNUM_TRADE_EXPORT sceneFieldDataNonOwningArr Contains scene hierarchy, object transformations and association of mesh, material, camera, light and other resources with particular objects. +@section Trade-SceneData-terminology Terminology and representation + +The class stores all data in a single array and all metadata in another. The +internal design is similar to @ref MeshData, except that the contents are not +limited to what the GPU vertex pipeline can understand. The two major concepts +are Objects and Fields. + +- *Objects* in the scene are represented as a contiguous sequence of numeric + IDs from @cpp 0 @ce up to @ref objectCount() minus one. The object itself + contains *nothing* by default, not even the transformation, it's just a + unique index. +- *Fields* are properties associated with particular objects, such as a + transformation matrix, a mesh ID or any other from @ref SceneField. Data + for a particular field are described by a pair of (strided) array views, + one containing the actual field data (with a type from @ref SceneFieldType) + and the other describing which object index the field belongs to (all + indices being of a type from @ref SceneObjectType). The only restriction on + fields is that there can be at most one array for one particular + @ref SceneField, apart from that the same field can generally be be + associated with a particular object index multiple times (such as one + object having multiple meshes attached) and, conversely, a field doesn't + have to be defined for each object (so e.g. for a scene with a hundred + objects the @ref SceneField::Light can have just three items). The actual + data layout is also left up to the data producer / importer --- different + fields can share the same object mapping view, a group of fields that + applies to a set of objects can (but doesn't have to) be interleaved + together etc. + +@section Trade-SceneData-usage Basic usage + +@ref TODO asArray, expected to use those to fill some ECS thingy + +@subsection Trade-SceneData-usage-object Per-object access + +@ref TODO not recommended but available for debugging purposes + +@section Trade-SceneData-usage-advanced Advanced usage + +@ref TODO via direct accessors + +@section Trade-SceneData-usage-mutable Mutable data access + +@ref TODO possibly for storing global animated/simulated state? :O or for + reordering data + +@section Trade-SceneData-populating Populating an instance + +@ref TODO ArrayTuple FTW + +@snippet MagnumTrade.cpp SceneData-populating + +@ref TODO arrays etc? where it was in MeshDatA? + +---- + +@ref TODO describe what happens when there's multiple scenes, how to know which + object belongs to which scene, ability to compress the object range? + @see @ref AbstractImporter::scene() */ class MAGNUM_TRADE_EXPORT SceneData {