From f91ce085917cf972ac2f3e2459e2ebb658e4e252 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Thu, 31 Oct 2024 13:37:33 +0100 Subject: [PATCH] Trade: mention upfront that all *Data are basically immutable. --- src/Magnum/Trade/AnimationData.h | 17 +++++++++++------ src/Magnum/Trade/CameraData.h | 8 ++++++-- src/Magnum/Trade/ImageData.h | 13 +++++++------ src/Magnum/Trade/LightData.h | 8 ++++++-- src/Magnum/Trade/MaterialData.h | 8 +++++++- src/Magnum/Trade/MeshData.h | 8 +++++++- src/Magnum/Trade/SceneData.h | 6 ++++-- src/Magnum/Trade/SkinData.h | 9 +++++++-- src/Magnum/Trade/TextureData.h | 7 ++++++- 9 files changed, 61 insertions(+), 23 deletions(-) diff --git a/src/Magnum/Trade/AnimationData.h b/src/Magnum/Trade/AnimationData.h index 1555a47a9..fce3ed43a 100644 --- a/src/Magnum/Trade/AnimationData.h +++ b/src/Magnum/Trade/AnimationData.h @@ -680,12 +680,17 @@ class MAGNUM_TRADE_EXPORT AnimationTrackData { /** @brief Animation clip data -Provides access to animation data and track properties of given clip. The -instance is commonly returned from @ref AbstractImporter::animation() and a -typical usage is feeding all the tracks directly to @ref Animation::Player. -For every track, you need to query its concrete type and then feed the -resulting @ref Animation::TrackView of correct type to -@ref Animation::Player::add(), for example. +Provides access to animation data and track properties of given clip. Populated +instances of this class are returned from @ref AbstractImporter::animation() +and can be passed to @ref AbstractSceneConverter::add(const AnimationData&, Containers::StringView). +Like with other @ref Trade types, the internal representation is fixed upon +construction and allows only optional in-place modification of the data itself, +but not of the overall structure. + +Typical usage is feeding all the tracks directly to @ref Animation::Player. For +every track, you need to query its concrete type and then feed the resulting +@ref Animation::TrackView of correct type to @ref Animation::Player::add(), for +example. Note that this class owns the animation track data and the tracks are only views on it. In order to be able to destroy the @ref AnimationData instance and diff --git a/src/Magnum/Trade/CameraData.h b/src/Magnum/Trade/CameraData.h index abb03ca4b..ee4385ef6 100644 --- a/src/Magnum/Trade/CameraData.h +++ b/src/Magnum/Trade/CameraData.h @@ -55,8 +55,12 @@ enum class CameraType: UnsignedByte { /** @brief Camera data -@see @ref AbstractImporter::camera(), - @ref Math::Matrix4::perspectiveProjection(Rad, T, T, T), +Provides access to perspective and orthographic camera properties. Populated +instances of this class are returned from @ref AbstractImporter::camera() and +can be passed to @ref AbstractSceneConverter::add(const CameraData&, Containers::StringView). +Similarly to other @ref Trade types, the internal representation is fixed upon +construction and doesn't allow any modification afterwards. +@see @ref Math::Matrix4::perspectiveProjection(Rad, T, T, T), @ref Math::Matrix4::perspectiveProjection(const Vector2&, T, T), @ref Math::Matrix4::orthographicProjection(const Vector2&, T, T), @ref Math::Matrix3::projection(const Vector2&) diff --git a/src/Magnum/Trade/ImageData.h b/src/Magnum/Trade/ImageData.h index b48e228c2..3b6186ee6 100644 --- a/src/Magnum/Trade/ImageData.h +++ b/src/Magnum/Trade/ImageData.h @@ -59,12 +59,13 @@ Provides access to both uncompressed and compressed image data together with information about data layout, image size and pixel format. Populated instances of this class are returned from @ref AbstractImporter::image1D(), @relativeref{AbstractImporter,image2D()}, -@relativeref{AbstractImporter,image3D()}, -@ref AbstractImageConverter::convert() and other APIs. - -Used mainly by @ref AbstractImporter classes to store either compressed or -non-compressed multi-dimensional image data together with layout and pixel -format description. +@relativeref{AbstractImporter,image3D()}, can be passed to +@ref AbstractImageConverter::convert(), +@ref AbstractSceneConverter::add(const ImageData2D&, Containers::StringView) +and related APIs, as well as used in various @ref TextureTools algorithms. Like +with other @ref Trade types, the internal representation is fixed upon +construction and allows only optional in-place modification of the data itself, +but not of the overall structure. This class can act as a drop-in replacement for @ref Image or @ref CompressedImage, @ref ImageView or @ref CompressedImageView and is diff --git a/src/Magnum/Trade/LightData.h b/src/Magnum/Trade/LightData.h index b887032b6..022d210ce 100644 --- a/src/Magnum/Trade/LightData.h +++ b/src/Magnum/Trade/LightData.h @@ -96,6 +96,12 @@ MAGNUM_TRADE_EXPORT Debug& operator<<(Debug& debug, LightType value); /** @brief Light data +Provides access to light properties. Populated instances of this class are +returned from @ref AbstractImporter::light() and +can be passed to @ref AbstractSceneConverter::add(const LightData&, Containers::StringView). +Similarly to other @ref Trade types, the internal representation is fixed upon +construction and doesn't allow any modification afterwards. + @section Trade-LightData-usage Usage The class exposes light parameters in a way that makes sense as a whole, @@ -172,8 +178,6 @@ To follow physically-based principles in lighting calculation, intensity is assumed to be in in *candela* (lm/sr) for @ref LightType::Point and @ref LightType::Spot, and in *lux* (lm/m2) for @ref LightType::Directional. Distance @f$ d @f$ is in meters. - -@see @ref AbstractImporter::light() */ class MAGNUM_TRADE_EXPORT LightData { public: diff --git a/src/Magnum/Trade/MaterialData.h b/src/Magnum/Trade/MaterialData.h index c0f801316..29ff85746 100644 --- a/src/Magnum/Trade/MaterialData.h +++ b/src/Magnum/Trade/MaterialData.h @@ -1801,7 +1801,13 @@ MAGNUM_TRADE_EXPORT Debug& operator<<(Debug& debug, MaterialAlphaMode value); Key-value store for builtin as well as custom material attributes, with an ability to define additional layers further affecting the base material. Populated instances of this class are returned from -@ref AbstractImporter::material(). +@ref AbstractImporter::material(), can be passed to +@ref AbstractSceneConverter::add(const MaterialData&, Containers::StringView) +as well as used in various +@ref MaterialTools algorithms +. Like with other @ref Trade types, the internal +representation is fixed upon construction and allows only optional in-place +modification of the attribute values itself, but not of the overall structure. @section Trade-MaterialData-usage Usage diff --git a/src/Magnum/Trade/MeshData.h b/src/Magnum/Trade/MeshData.h index c4510e1a8..6ef70ce6b 100644 --- a/src/Magnum/Trade/MeshData.h +++ b/src/Magnum/Trade/MeshData.h @@ -767,7 +767,13 @@ Containers::Array MAGNUM_TRADE_EXPORT meshAttributeDataNonOwn Provides access to mesh vertex and index data, together with additional information such as primitive type. Populated instances of this class are returned from @ref AbstractImporter::mesh(), from particular functions in -the @ref Primitives library as well as from various @ref MeshTools algorithms. +the @ref Primitives library, can be passed to +@ref AbstractSceneConverter::convert(const MeshData&), +@ref AbstractSceneConverter::add(const MeshData&, Containers::StringView), +and related APIs, as well as used in various @ref MeshTools algorithms. Like +with other @ref Trade types, the internal representation is fixed upon +construction and allows only optional in-place modification of the data itself, +but not of the overall structure. @section Trade-MeshData-usage-compile Quick usage with MeshTools::compile() diff --git a/src/Magnum/Trade/SceneData.h b/src/Magnum/Trade/SceneData.h index ea77c5604..6ff8006f0 100644 --- a/src/Magnum/Trade/SceneData.h +++ b/src/Magnum/Trade/SceneData.h @@ -1553,8 +1553,10 @@ Containers::Array MAGNUM_TRADE_EXPORT sceneFieldDataNonOwningArr Contains scene node hierarchy, transformations, resource assignment as well as any other data associated with the scene. Populated instances of this class are -returned from @ref AbstractImporter::scene() as well as from various -@ref SceneTools algorithms. +returned from @ref AbstractImporter::scene() as well as used in various +@ref SceneTools algorithms. Like with other @ref Trade types, the internal +representation is fixed upon construction and allows only optional in-place +modification of the data itself, but not of the overall structure. @section Trade-SceneData-representation Data representation and terminology diff --git a/src/Magnum/Trade/SkinData.h b/src/Magnum/Trade/SkinData.h index b84e36502..0174800b4 100644 --- a/src/Magnum/Trade/SkinData.h +++ b/src/Magnum/Trade/SkinData.h @@ -43,8 +43,13 @@ namespace Magnum { namespace Trade { @brief Skin data @m_since_latest -@see @ref SkinData2D, @ref SkinData3D, @ref AbstractImporter::skin2D(), - @ref AbstractImporter::skin3D() +Provides access to skin properties used for skeletal animations. Populated +instances of this class are returned from @ref AbstractImporter::skin2D() or +@relativeref{AbstractImporter,skin3D()} and can be passed to +@ref AbstractSceneConverter::add(const SkinData3D&, Containers::StringView) and +overloads. Similarly to other @ref Trade types, the internal representation is +fixed upon construction and doesn't allow any modification afterwards. +@see @ref SkinData2D, @ref SkinData3D */ template class SkinData { public: diff --git a/src/Magnum/Trade/TextureData.h b/src/Magnum/Trade/TextureData.h index 169d678b3..55f1f9131 100644 --- a/src/Magnum/Trade/TextureData.h +++ b/src/Magnum/Trade/TextureData.h @@ -109,7 +109,12 @@ enum class TextureType: UnsignedByte { /** @brief Texture data -@see @ref AbstractImporter::texture() +Provides access to texture metadata such as sampler properties and association +with a concrete image. Populated instances of this class are returned from +@ref AbstractImporter::texture() and can be passed to +@ref AbstractSceneConverter::add(const TextureData&, Containers::StringView). +Similarly to other @ref Trade types, the internal representation is fixed upon +construction and doesn't allow any modification afterwards. */ class TextureData { public: