From 6e1ca040dfad6b589ec8e76de839fa40470b2ffb Mon Sep 17 00:00:00 2001 From: Adeel Kazmi Date: Mon, 20 Nov 2023 17:12:18 +0000 Subject: [PATCH] (Scene3D) Cleaned up Doxygen tags in loader files Change-Id: Ic59dced14afde154a8c8fa389ae26df063c00f23 --- .../public-api/loader/alpha-function-helper.h | 11 +- dali-scene3d/public-api/loader/animated-property.h | 26 ++-- .../public-api/loader/animation-definition.h | 37 ++++- .../public-api/loader/blend-shape-details.h | 1 + dali-scene3d/public-api/loader/buffer-definition.h | 8 + dali-scene3d/public-api/loader/bvh-loader.h | 2 + dali-scene3d/public-api/loader/camera-parameters.h | 15 +- dali-scene3d/public-api/loader/customization.h | 21 ++- .../public-api/loader/dli-input-parameter.h | 6 + .../public-api/loader/environment-definition.h | 14 +- .../public-api/loader/environment-map-data.h | 17 ++- .../public-api/loader/environment-map-loader.h | 1 + .../public-api/loader/facial-animation-loader.h | 2 + dali-scene3d/public-api/loader/ktx-loader.h | 1 + dali-scene3d/public-api/loader/load-result.h | 8 + .../public-api/loader/load-scene-metadata.h | 12 +- .../public-api/loader/material-definition.h | 18 ++- dali-scene3d/public-api/loader/matrix-stack.h | 1 + dali-scene3d/public-api/loader/mesh-definition.h | 34 ++++- dali-scene3d/public-api/loader/mesh-geometry.h | 8 +- dali-scene3d/public-api/loader/model-loader.h | 23 ++- dali-scene3d/public-api/loader/node-definition.h | 17 +++ .../public-api/loader/parse-renderer-state.h | 7 +- dali-scene3d/public-api/loader/renderer-state.h | 32 ++-- dali-scene3d/public-api/loader/resource-bundle.h | 36 +++-- dali-scene3d/public-api/loader/scene-definition.h | 162 ++++++++++++--------- dali-scene3d/public-api/loader/shader-definition.h | 9 +- dali-scene3d/public-api/loader/shader-manager.h | 18 ++- dali-scene3d/public-api/loader/shader-option.h | 16 +- .../public-api/loader/skeleton-definition.h | 3 +- dali-scene3d/public-api/loader/skinning-details.h | 8 +- dali-scene3d/public-api/loader/string-callback.h | 6 +- dali-scene3d/public-api/loader/utils.h | 80 +++++----- dali-scene3d/public-api/loader/view-projection.h | 7 +- 34 files changed, 465 insertions(+), 202 deletions(-) diff --git a/dali-scene3d/public-api/loader/alpha-function-helper.h b/dali-scene3d/public-api/loader/alpha-function-helper.h index 3fdb4ed..a3235f3 100644 --- a/dali-scene3d/public-api/loader/alpha-function-helper.h +++ b/dali-scene3d/public-api/loader/alpha-function-helper.h @@ -27,14 +27,17 @@ namespace Dali::Scene3D::Loader { /** - * @return Given a name, provide a AlphaFunction; if the name was not - * recognised, get the default one. + * @brief Given a name, provides an AlphaFunction. + * @SINCE_2_0.7 + * @return The AlphaFunction + * @note If the name was not recognised, the default one is returned */ AlphaFunction DALI_SCENE3D_API GetAlphaFunction(const std::string& name, bool* found = nullptr); /** - * @brief Registers an alpha function only if one with the same @a name has - * not yet been registered. Throws Exception the name isn't unique. + * @brief Registers an alpha function only if one with the same @a name has not yet been registered. + * @SINCE_2_0.7 + * @note Throws an exception if the name is not unique */ void DALI_SCENE3D_API RegisterAlphaFunction(const std::string& name, AlphaFunction alphaFn) noexcept(false); diff --git a/dali-scene3d/public-api/loader/animated-property.h b/dali-scene3d/public-api/loader/animated-property.h index 90b8a02..1ba4ad2 100644 --- a/dali-scene3d/public-api/loader/animated-property.h +++ b/dali-scene3d/public-api/loader/animated-property.h @@ -31,22 +31,25 @@ namespace Dali::Scene3D::Loader { /** - * @brief Intermediate representation for a property that's given to - * a Animation to animate. Since there is no getting an - * animated property back from the Animation (i.e. past AnimateBetween/By/To()), - * changing properties (e.g. from the SDK) requires the whole Animation - * object to be recreated with all of its properties (incl. modifications). + * @brief Intermediate representation for a property that's given to a Animation to animate. + * + * Since there is no getting an animated property back from the Animation (i.e. past AnimateBetween/By/To()), + * changing properties (e.g. from the SDK) requires the whole Animation object to be recreated with all of + * its properties (incl. modifications). + * @SINCE_2_0.7 */ struct DALI_SCENE3D_API AnimatedProperty { public: // METHODS /** - * @brief Function to obtain an Actor based on its property. Its processing will - * ignore empty handles returned by it. + * @brief Function to obtain an Actor based on its property. Its processing will ignore empty handles returned by it. + * @SINCE_2_0.7 */ using GetActor = std::function; /** + * @brief Get the property object of the given actor. + * @SINCE_2_0.7 * @return The Property object (of the given @a actor) whose value is being animated. */ Property GetProperty(Actor& actor) const @@ -57,6 +60,7 @@ public: // METHODS /** * @brief The type of the Property (of the given @a actor) that is being animated. + * @SINCE_2_0.7 */ Property::Type GetPropertyType(Actor& actor) const { @@ -66,9 +70,11 @@ public: // METHODS /** * @brief Registers the animation of this property against the given @a anim. - * @a getActor will be used to obtain the Actor named by this property. - * Failing to find the actor purely means that this property will not be - * animated. + * + * @a getActor will be used to obtain the Actor named by this property. + * Failing to find the actor purely means that this property will not be + * animated. + * @SINCE_2_0.7 */ void Animate(Animation& anim, GetActor getActor) const; diff --git a/dali-scene3d/public-api/loader/animation-definition.h b/dali-scene3d/public-api/loader/animation-definition.h index 914dfa7..78e59a1 100644 --- a/dali-scene3d/public-api/loader/animation-definition.h +++ b/dali-scene3d/public-api/loader/animation-definition.h @@ -28,6 +28,7 @@ namespace Dali::Scene3D::Loader { /** * @brief Animation handle + name + definition of properties. + * @SINCE_2_0.7 */ class DALI_SCENE3D_API AnimationDefinition { @@ -39,8 +40,9 @@ public: // STATIC static const float MIN_DURATION_SECONDS; /** - * @brief Saves the original end action of @a anim, sets the end action to - * Discard, then stops the animation and returns the end action. + * @brief Saves the original end action of @a anim, sets the end action to Discard, then stops + * the animation and returns the end action. + * @SINCE_2_0.7 */ static Animation::EndAction StopForModification(Animation& anim); @@ -52,20 +54,25 @@ public: // METHODS AnimationDefinition& operator=(AnimationDefinition&& other); /** - * @brief Registers the properties against the given @a animation. @a getActor - * will be used to obtain the Actors for each AnimatedProperty. + * @brief Registers the properties against the given @a animation. + * + * @a getActor will be used to obtain the Actors for each AnimatedProperty. + * @SINCE_2_0.7 */ void Animate(Animation& animation, AnimatedProperty::GetActor getActor); /** - * @brief Creates a new Animation and Animates() its properties. @a getActor - * will be used to obtain the Actors for each AnimatedProperty. + * @brief Creates a new Animation and Animates() its properties. + * + * @a getActor will be used to obtain the Actors for each AnimatedProperty. + * @SINCE_2_0.7 */ Animation ReAnimate(AnimatedProperty::GetActor getActor); /** * @brief Set the name of the animation. * + * @SINCE_2_2.22 * @param[in] name The name of the animation. */ void SetName(const std::string& name); @@ -73,6 +80,7 @@ public: // METHODS /** * @brief Get the name of the animation. * + * @SINCE_2_2.22 * @return The name of the animation. */ const std::string& GetName() const; @@ -80,6 +88,7 @@ public: // METHODS /** * @brief Set the duration of the animation in seconds. * + * @SINCE_2_2.22 * @param[in] duration The duration of the animation in seconds. */ void SetDuration(float duration); @@ -87,6 +96,7 @@ public: // METHODS /** * @brief Get the duration of the animation in seconds. * + * @SINCE_2_2.22 * @return The duration of the animation in seconds. */ float GetDuration() const; @@ -94,6 +104,7 @@ public: // METHODS /** * @brief Set the number of times to loop the animation. * + * @SINCE_2_2.22 * @param[in] loopCount The number of times to loop the animation. Use -1 for infinite looping. */ void SetLoopCount(int32_t loopCount); @@ -101,6 +112,7 @@ public: // METHODS /** * @brief Get the number of times to loop the animation. * + * @SINCE_2_2.22 * @return The number of times to loop the animation. Use -1 for infinite looping. */ int GetLoopCount() const; @@ -108,6 +120,7 @@ public: // METHODS /** * @brief Set what should happen when an animation is disconnected from an object. * + * @SINCE_2_2.22 * @param[in] disconnectAction What should happen when an animation is disconnected from an object. */ void SetDisconnectAction(Animation::EndAction disconnectAction); @@ -115,6 +128,7 @@ public: // METHODS /** * @brief Get what should happen when an animation is disconnected from an object. * + * @SINCE_2_2.22 * @return What should happen when an animation is disconnected from an object. */ Animation::EndAction GetDisconnectAction() const; @@ -122,6 +136,7 @@ public: // METHODS /** * @brief Set what should happen when an animation reaches its end. * + * @SINCE_2_2.22 * @param[in] endAction What should happen when an animation reaches its end. */ void SetEndAction(Animation::EndAction endAction); @@ -129,6 +144,7 @@ public: // METHODS /** * @brief Get what should happen when an animation reaches its end. * + * @SINCE_2_2.22 * @return What should happen when an animation reaches its end. */ Animation::EndAction GetEndAction() const; @@ -136,6 +152,7 @@ public: // METHODS /** * @brief Set a speed factor for this animation. This can be used to speed up or slow down playback of this animation relative to other animations in a scene. * + * @SINCE_2_2.22 * @param[in] speedFactor The speed factor for this animation. 1.0 is normal speed, 2.0 is double speed, 0.5 is half speed, etc. */ void SetSpeedFactor(float speedFactor); @@ -143,6 +160,7 @@ public: // METHODS /** * @brief Get a speed factor for this animation. This can be used to speed up or slow down playback of this animation relative to other animations in a scene. * + * @SINCE_2_2.22 * @return The speed factor for this animation. 1.0 is normal speed, 2.0 is double speed, 0.5 is half speed, etc. */ float GetSpeedFactor() const; @@ -150,6 +168,7 @@ public: // METHODS /** * @brief Set a range within which to play this animation. This can be used to play only part of an animation or to play it backwards by setting playRange.y < playRange.x * + * @SINCE_2_2.22 * @param[in] playRange A range within which to play this animation. x = start time in seconds, y = end time in seconds */ void SetPlayRange(const Vector2& playRange); @@ -157,6 +176,7 @@ public: // METHODS /** * @brief Get a range within which to play this animation. This can be used to play only part of an animation or to play it backwards by setting playRange.y < playRange.x * + * @SINCE_2_2.22 * @return A range within which to play this animation. x = start time in seconds, y = end time in seconds */ Vector2 GetPlayRange() const; @@ -164,6 +184,7 @@ public: // METHODS /** * @brief Reserves Animated property vector's size * + * @SINCE_2_2.22 * @param[in] size The size to reserve property */ void ReserveSize(uint32_t size); @@ -171,6 +192,7 @@ public: // METHODS /** * @brief Retrieves the number of animated properties' count * + * @SINCE_2_2.22 * @return The count of animated properties. */ uint32_t GetPropertyCount() const; @@ -178,6 +200,7 @@ public: // METHODS /** * @brief Add a property that will be animated by this AnimationDefinition * + * @SINCE_2_2.22 * @param[in] index The index the property will be stored. * @param[in] property The property that will be animated by this AnimationDefinition */ @@ -186,6 +209,7 @@ public: // METHODS /** * @brief Retrieves animated property at the index * + * @SINCE_2_2.22 * @param[in] index The index of property to be retrieved. */ AnimatedProperty& GetPropertyAt(uint32_t index); @@ -193,6 +217,7 @@ public: // METHODS /** * @brief Retrieves animated property at the index * + * @SINCE_2_2.34 * @param[in] index The index of property to be retrieved. */ const AnimatedProperty& GetPropertyAt(uint32_t index) const; diff --git a/dali-scene3d/public-api/loader/blend-shape-details.h b/dali-scene3d/public-api/loader/blend-shape-details.h index d7d6325..7788532 100644 --- a/dali-scene3d/public-api/loader/blend-shape-details.h +++ b/dali-scene3d/public-api/loader/blend-shape-details.h @@ -80,6 +80,7 @@ struct DALI_SCENE3D_API BlendShapes /** * @brief Registers properties based on the mesh definition (and geometry) and identified by the above string constants, * on the given @a renderer and @a actor. + * @SINCE_2_0.7 */ static void ConfigureProperties(const BlendShapeData& data, Renderer renderer); diff --git a/dali-scene3d/public-api/loader/buffer-definition.h b/dali-scene3d/public-api/loader/buffer-definition.h index 533aa04..a59d330 100644 --- a/dali-scene3d/public-api/loader/buffer-definition.h +++ b/dali-scene3d/public-api/loader/buffer-definition.h @@ -30,7 +30,9 @@ namespace Dali::Scene3D::Loader { /** * @brief Defines a buffer that is loaded from input uri. + * * The buffer can contain 3D resource data such as mesh, animation, and texture. + * @SINCE_2_2.12 */ struct DALI_SCENE3D_API BufferDefinition { @@ -49,28 +51,34 @@ struct DALI_SCENE3D_API BufferDefinition /** * @brief Retrieves data stream of this buffer. + * @SINCE_2_2.12 * @return iostream of this buffer */ std::iostream& GetBufferStream(); /** * @brief Retrieves uri of this buffer + * @SINCE_2_2.12 * @return uri of the buffer */ std::string GetUri(); /** * @brief Checks whether the buffer is available or not. + * * It is available, if the buffer is successfully loaded from file or base64 stream. + * @SINCE_2_2.12 * @return True if it is available. */ bool IsAvailable(); private: + /// @cond internal /** * @brief Loads buffer from file or encoded stream. */ void LoadBuffer(); + /// @endcond public: // DATA std::string mResourcePath; diff --git a/dali-scene3d/public-api/loader/bvh-loader.h b/dali-scene3d/public-api/loader/bvh-loader.h index 950b2ea..d0c5955 100644 --- a/dali-scene3d/public-api/loader/bvh-loader.h +++ b/dali-scene3d/public-api/loader/bvh-loader.h @@ -26,6 +26,7 @@ namespace Dali::Scene3D::Loader /** * @brief Loads motion capture data from bvh file format. * + * @SINCE_2_1.32 * @param[in] path The file path. * @param[in] animationName Name of the motion capture animation * @param[in] scale The scale factor to set on the position property manually. @@ -36,6 +37,7 @@ DALI_SCENE3D_API AnimationDefinition LoadBvh(const std::string& path, const std: /** * @brief Loads motion capture data from bvh data stream. * + * @SINCE_2_2.23 * @param[in] rawBuffer The bvh buffer. * @param[in] rawBufferLength The length of buffer. * @param[in] animationName Name of the motion capture animation diff --git a/dali-scene3d/public-api/loader/camera-parameters.h b/dali-scene3d/public-api/loader/camera-parameters.h index b0b88b3..17b3ea1 100644 --- a/dali-scene3d/public-api/loader/camera-parameters.h +++ b/dali-scene3d/public-api/loader/camera-parameters.h @@ -49,21 +49,24 @@ struct DALI_SCENE3D_API CameraParameters bool isPerspective = true; /** - * @return The view-projection matrix of the camera. + * @brief Retrieves the view-projection of the camera. + * @SINCE_2_0.7 + * @return The view-projection matrix of the camera */ ViewProjection GetViewProjection() const; /** - * @brief Calculates the @a position, @a orientation and @a scale that's defined - * for this camera, and writes it into the respective variable. + * @brief Calculates the @a position, @a orientation and @a scale that's defined for this camera, + * and writes it into the respective variable. + * @SINCE_2_0.7 */ void CalculateTransformComponents(Vector3& position, Quaternion& orientation, Vector3& scale) const; /** - * @brief Configures the camera in the way that it is supposed to be used with - * scene3d scenes. This means inverted Y and a rotation of 180 degrees - * along the Y axis, plus whatever the parameters define. + * @brief Configures the camera in the way that it is supposed to be used with scene3d scenes. * + * This means inverted Y and a rotation of 180 degrees along the Y axis, plus whatever the parameters define. + * @SINCE_2_0.7 * @return True if success to generate camera. False otherwise. */ bool ConfigureCamera(CameraActor& camera, bool invertY = true) const; diff --git a/dali-scene3d/public-api/loader/customization.h b/dali-scene3d/public-api/loader/customization.h index 90a42bf..00f3082 100644 --- a/dali-scene3d/public-api/loader/customization.h +++ b/dali-scene3d/public-api/loader/customization.h @@ -31,6 +31,7 @@ namespace Dali::Scene3D::Loader * @brief Offers a description of an aspect of the scene that can be customized: * the number of options, and the name of the nodes that are registered * for the tag, whose children will be shown / hidden based on selection. + * @SINCE_2_0.7 */ struct DALI_SCENE3D_API Customization { @@ -39,6 +40,7 @@ struct DALI_SCENE3D_API Customization /** * @brief A mapping of customizations to tags. + * @SINCE_2_0.7 */ struct DALI_SCENE3D_API Map { @@ -47,27 +49,32 @@ struct DALI_SCENE3D_API Customization /** * @brief Maps the given @a customization to the given @a tag, overwriting any previous mapping to the same tag. + * @SINCE_2_0.7 * @return Pointer to the inserted (or pre-existing) Customization instance. */ Customization* Set(Tag tag, Customization&& customization); /** * @brief Attempts to retrieve a const Customization based on the given @a tag. + * @SINCE_2_0.7 */ const Customization* Get(Tag tag) const; /** * @brief Attempts to retrieve a Customization based on the given @a tag. + * @SINCE_2_0.7 */ Customization* Get(Tag tag); /** * @brief Returns the number of elements. + * @SINCE_2_0.7 */ uint32_t Size() const; - /* + /** * @brief Removes every element from the Map. + * @SINCE_2_0.7 */ void Clear(); @@ -78,6 +85,7 @@ struct DALI_SCENE3D_API Customization /** * @brief A mapping of choices - indices of children of customization nodes to use - to tags. + * @SINCE_2_0.7 */ struct DALI_SCENE3D_API Choices { @@ -86,21 +94,28 @@ struct DALI_SCENE3D_API Customization /** * @brief Maps the given @a option to the given @a tag, overwriting any previous mapping to the same tag. + * @SINCE_2_0.7 */ void Set(Tag tag, OptionType option); /** - * @brief Attempts to retrieve a Customization based on the given @a tag. Returns NONE if @a tag is not known. + * @brief Attempts to retrieve a Customization based on the given @a tag. + * @SINCE_2_0.7 + * @return A Customization based on the given @a tag. + * @note Returns NONE if @a tag is not known. */ OptionType Get(Tag tag) const; /** * @brief Returns the number of elements. + * @SINCE_2_0.7 + * @return The number of elements. */ uint32_t Size() const; - /* + /** * @brief Removes every element from the underlying map. + * @SINCE_2_0.7 */ void Clear(); diff --git a/dali-scene3d/public-api/loader/dli-input-parameter.h b/dali-scene3d/public-api/loader/dli-input-parameter.h index 1db4844..a161b75 100644 --- a/dali-scene3d/public-api/loader/dli-input-parameter.h +++ b/dali-scene3d/public-api/loader/dli-input-parameter.h @@ -43,11 +43,13 @@ public: public: /** * @brief The absolute path of animation binaries referenced in the .dli. + * @SINCE_2_2.17 */ std::string mAnimationsPath; /** * @brief Provides a facility to determine a color from a code instead of RGB(A) values. + * @SINCE_2_2.17 */ ConvertColorCode mConvertColorCode{nullptr}; @@ -56,6 +58,7 @@ public: * root) element, whom they will attempt to process. This will take place before * the parsing of scene Nodes and Animations, but after skeletons, environment, mesh, * shader and material resources. + * @SINCE_2_2.17 */ CategoryProcessorVector mPreNodeCategoryProcessors; @@ -63,12 +66,14 @@ public: * @brief A collection of handlers, mapped to the names of the top level (i.e. below * root) element, whom they will attempt to process. This will take place after * the parsing of the scene Nodes and Animations. + * @SINCE_2_2.17 */ CategoryProcessorVector mPostNodeCategoryProcessors; /** * @brief Provides an extension point to nodes. If provided, this function will be * called with each JSON element and definition, of a scene node. + * @SINCE_2_2.17 * @note Constraints rely on ID resolution (from .dli to scene definition), which * takes place after the parsing of the nodes; therefore AT THIS POINT the node * IDs seen in constraints will still be the .dli IDs - NOT to be relied on for @@ -79,6 +84,7 @@ public: /** * @brief Provides an extension point to animations. If provided, this function will be * called with each JSON element and fully processed definition, of an animation. + * @SINCE_2_2.17 */ AnimationProcessor mAnimationPropertyProcessor; }; diff --git a/dali-scene3d/public-api/loader/environment-definition.h b/dali-scene3d/public-api/loader/environment-definition.h index 36d8ae6..39aa53a 100644 --- a/dali-scene3d/public-api/loader/environment-definition.h +++ b/dali-scene3d/public-api/loader/environment-definition.h @@ -29,8 +29,8 @@ namespace Dali::Scene3D::Loader { /** - * @brief Defines an environment map with either or both of radiance - * and irradiance maps. + * @brief Defines an environment map with either or both of radiance and irradiance maps. + * @SINCE_2_0.7 */ struct DALI_SCENE3D_API EnvironmentDefinition { @@ -69,25 +69,31 @@ struct DALI_SCENE3D_API EnvironmentDefinition /** * @brief Loads raw pixel data for the given diffuse and specular maps. + * @SINCE_2_0.7 + * @return The raw data for the given diffuse and specular maps * @note This can be done on any thread. */ RawData LoadRaw(const std::string& environmentsPath); /** - * @brief Creates DALi cubemap Textures from the pixel data in @a raw, then - * returns them in a Textures object. + * @brief Creates DALi cubemap Textures from the pixel data in @a raw, then returns them in a Textures object. + * @SINCE_2_0.7 + * @return DALi cubemap Textures * @note This must only be called from the event thread. */ Textures Load(RawData&& raw); /** * @brief Get default intensity value. + * @SINCE_2_2.1 * @return Default intensity. (1.0f) */ static float GetDefaultIntensity(); private: + /// @cond internal static void LoadBrdfTexture(); + /// @endcond internal public: // DATA std::string mDiffuseMapPath; diff --git a/dali-scene3d/public-api/loader/environment-map-data.h b/dali-scene3d/public-api/loader/environment-map-data.h index 6d53cbc..e09beef 100644 --- a/dali-scene3d/public-api/loader/environment-map-data.h +++ b/dali-scene3d/public-api/loader/environment-map-data.h @@ -31,20 +31,24 @@ namespace Dali::Scene3D::Loader { /** * @brief Stores the pixel data objects for environment map texture. + * * EnvironmentMapData supports cube map that contains textures for 6 faces, or * an equirectangular image. + * @SINCE_2_2.11 */ class DALI_SCENE3D_API EnvironmentMapData { public: /** * @brief Retrieves environment map texture from image file + * @SINCE_2_2.11 * @return texture for loaded environment map. */ Texture GetTexture(); /** * @brief Sets environment map type + * @SINCE_2_2.11 * @param[in] environmentMapType environment map type */ void SetEnvironmentMapType(Dali::Scene3D::EnvironmentMapType environmentMapType) @@ -58,6 +62,7 @@ public: /** * @brief Retrieves environment map type. + * @SINCE_2_2.11 * @return environment map type */ Dali::Scene3D::EnvironmentMapType GetEnvironmentMapType() const @@ -65,12 +70,22 @@ public: return mEnvironmentMapType; } + /** + * @brief Sets the mipmap levels + * @SINCE_2_2.19 + * @param[in] mipmapLevels No. of mipmap levels + */ void SetMipmapLevels(uint32_t mipmapLevels) { mMipmapLevels = mipmapLevels; } - uint32_t GetMipmapLevels() + /** + * @brief Retrieves the number of mipmap levels + * @SINCE_2_2.19 + * @return No. of mipmap levels + */ + uint32_t GetMipmapLevels() const { return mMipmapLevels; } diff --git a/dali-scene3d/public-api/loader/environment-map-loader.h b/dali-scene3d/public-api/loader/environment-map-loader.h index f07f28c..ddbf86c 100644 --- a/dali-scene3d/public-api/loader/environment-map-loader.h +++ b/dali-scene3d/public-api/loader/environment-map-loader.h @@ -27,6 +27,7 @@ namespace Dali::Scene3D::Loader /** * @brief Loads environment map data from a environment map file. * + * @SINCE_2_1.32 * @param[in] environmentMapUrl The environment map file url. * @param[out] environmentMapData The data structure with all pixel data objects. * @return bool True if the loading is succeded. diff --git a/dali-scene3d/public-api/loader/facial-animation-loader.h b/dali-scene3d/public-api/loader/facial-animation-loader.h index a1658fc..fb96446 100644 --- a/dali-scene3d/public-api/loader/facial-animation-loader.h +++ b/dali-scene3d/public-api/loader/facial-animation-loader.h @@ -28,6 +28,7 @@ namespace Dali::Scene3D::Loader * * Throws a DaliException on error. * + * @SINCE_2_1.30 * @param[in] url The url of the file containing the facial animation. * * @return An animation definition. @@ -39,6 +40,7 @@ DALI_SCENE3D_API AnimationDefinition LoadFacialAnimation(const std::string& url) * * Throws a DaliException on error. * + * @SINCE_2_2.23 * @param[in] rawBuffer The raw buffer containing the facial animation. * @param[in] rawBufferLength The length of raw buffer. * diff --git a/dali-scene3d/public-api/loader/ktx-loader.h b/dali-scene3d/public-api/loader/ktx-loader.h index d495ee0..6c6b4de 100644 --- a/dali-scene3d/public-api/loader/ktx-loader.h +++ b/dali-scene3d/public-api/loader/ktx-loader.h @@ -26,6 +26,7 @@ namespace Dali::Scene3D::Loader /** * @brief Loads cube map data texture from a ktx file. * + * @SINCE_2_0.7 * @param[in] path The file path. * @param[out] environmentMapData The data structure with all pixel data objects. * @return bool True if the loading is succeded. diff --git a/dali-scene3d/public-api/loader/load-result.h b/dali-scene3d/public-api/loader/load-result.h index da05a36..b849279 100644 --- a/dali-scene3d/public-api/loader/load-result.h +++ b/dali-scene3d/public-api/loader/load-result.h @@ -31,41 +31,49 @@ class SceneDefinition; /** * @brief The outputs from loading and processing a scene. + * @SINCE_2_0.7 */ struct DALI_SCENE3D_API LoadResult { /** * @brief The bundle to store resources in. + * @SINCE_2_0.7 */ ResourceBundle& mResources; /** * @brief The scene definition to populate. + * @SINCE_2_0.7 */ SceneDefinition& mScene; /** * @brief The metadata of the scene. + * @SINCE_2_2.5 */ SceneMetadata& mSceneMetadata; /** * @brief The list of animation definitions, in lexicographical order of their names. + * @SINCE_2_0.7 */ std::vector& mAnimationDefinitions; /** * @brief The list of animation group definitions, in lexicographical order of their names. + * @SINCE_2_0.7 */ std::vector& mAnimationGroupDefinitions; /** * @brief The camera parameters that were loaded from the scene. + * @SINCE_2_0.7 */ std::vector& mCameraParameters; /** * @brief The light parameters that were loaded from the scene. + * @SINCE_2_0.7 */ std::vector& mLightParameters; }; diff --git a/dali-scene3d/public-api/loader/load-scene-metadata.h b/dali-scene3d/public-api/loader/load-scene-metadata.h index ca7e16f..6056b1e 100644 --- a/dali-scene3d/public-api/loader/load-scene-metadata.h +++ b/dali-scene3d/public-api/loader/load-scene-metadata.h @@ -29,16 +29,18 @@ namespace Dali::Scene3D::Loader { /** * @brief Defines the matadata for an image. + * @SINCE_2_2.5 */ struct ImageMetadata { - ImageDimensions mMinSize{}; ///< The minimum required image size for rendering - SamplingMode::Type mSamplingMode{SamplingMode::BOX_THEN_LINEAR}; ///< The sampling mode used to resize the image + ImageDimensions mMinSize{}; ///< The minimum required image size for rendering. @SINCE_2_2.5 + SamplingMode::Type mSamplingMode{SamplingMode::BOX_THEN_LINEAR}; ///< The sampling mode used to resize the image. @SINCE_2_2.5 }; /** * @brief Stores the metadata for a scene. * + * @SINCE_2_2.5 * @note The supported format is the following: * { * "images": (optional) [ { @@ -55,8 +57,10 @@ struct SceneMetadata }; /** - * @brief Attempts to load and process a json file specifying scene metadata - * for pre-processing the scene resources: e.g. the minimum size required for rendering images, etc. + * @brief Attempts to load and process a json file specifying scene metadata for pre-processing the scene resources. + * + * e.g. the minimum size required for rendering images, etc. + * @SINCE_2_2.5 * @note Will fail quietly if the file is not present. */ DALI_SCENE3D_API void LoadSceneMetadata(const std::string& url, SceneMetadata& sceneMetadata); diff --git a/dali-scene3d/public-api/loader/material-definition.h b/dali-scene3d/public-api/loader/material-definition.h index 43dabc1..39b9153 100644 --- a/dali-scene3d/public-api/loader/material-definition.h +++ b/dali-scene3d/public-api/loader/material-definition.h @@ -34,6 +34,7 @@ namespace Dali::Scene3D::Loader { /** * @brief Helper enum for encoding and decoding sampler states. + * @SINCE_2_0.7 */ struct DALI_SCENE3D_API SamplerFlags { @@ -76,38 +77,46 @@ struct DALI_SCENE3D_API SamplerFlags }; /** - * @return SamplerFlags bit pattern calculated from the given Dali Sampler settings. + * @brief Retrieves the bit pattern calculated from the given Dali Sampler settings. + * @SINCE_2_0.7 + * @return SamplerFlags bit pattern. */ static Type Encode(FilterMode::Type minFilter, FilterMode::Type magFilter, WrapMode::Type wrapS, WrapMode::Type wrapT); /** * @brief Decodes the minification filter patter of @a flags into the corresponding FilterMode. + * @SINCE_2_0.7 */ static FilterMode::Type GetMinFilter(Type flags); /** * @brief Decodes the magnification filter patter of @a flags into the corresponding FilterMode. + * @SINCE_2_0.7 */ static FilterMode::Type GetMagFilter(Type flags); /** * @brief Decodes the horizontal wrap pattern of @a flags into the corresponding WrapMode. + * @SINCE_2_0.7 */ static WrapMode::Type GetWrapS(Type flags); /** * @brief Decodes the vertical wrap pattern of @a flags into the corresponding WrapMode. + * @SINCE_2_0.7 */ static WrapMode::Type GetWrapT(Type flags); /** * @brief Creates a Sampler with the settings encoded in @a flags. + * @SINCE_2_0.7 */ static Sampler MakeSampler(Type flags); }; /** * @brief Defines a texture from a combination of an image URI and its sampler definition. + * @SINCE_2_0.7 */ struct DALI_SCENE3D_API TextureDefinition { @@ -128,6 +137,7 @@ struct DALI_SCENE3D_API TextureDefinition * is enabled, and an index of an environment (usually of all environments in a * scene). Textures from the environment are added last when the DALi TextureSet * is being created. + * @SINCE_2_0.7 */ struct DALI_SCENE3D_API MaterialDefinition { @@ -156,6 +166,7 @@ struct DALI_SCENE3D_API MaterialDefinition /** * @brief A(n image based) texture that's used in a material. + * @SINCE_2_0.7 */ struct TextureStage { @@ -187,6 +198,7 @@ struct DALI_SCENE3D_API MaterialDefinition /** * @brief Loads (or, in the case of solid color materials, creates) raw pixel data, * which is then returned. + * @SINCE_2_0.7 * @note This may be called from any thread. */ RawData LoadRaw(const std::string& imagesPath); @@ -195,6 +207,7 @@ struct DALI_SCENE3D_API MaterialDefinition * @brief Creates Textures from the pixel data in @a raw, gets the * the cube maps from the iEnvironment'th element of @a environments, * then creates a DALi TextureSet and returns it. + * @SINCE_2_0.7 * @note This must be called from the event thread. * @note The textures are added in the following order: 2D, cube maps. */ @@ -202,11 +215,13 @@ struct DALI_SCENE3D_API MaterialDefinition /** * @brief Checks if the given mask matches any of the textures defined. + * @SINCE_2_0.7 */ bool CheckTextures(uint32_t flags) const; /** * @return The alpha test reference value. + * @SINCE_2_0.7 * @note A value of 0.f means no alpha testing. */ float GetAlphaCutoff() const @@ -216,6 +231,7 @@ struct DALI_SCENE3D_API MaterialDefinition /** * @brief Encodes the alpha test reference @a value in flags. + * @SINCE_2_0.7 * @note A value of 0.f means no alpha testing. */ void SetAlphaCutoff(float value) diff --git a/dali-scene3d/public-api/loader/matrix-stack.h b/dali-scene3d/public-api/loader/matrix-stack.h index 58ae2c0..1889e09 100644 --- a/dali-scene3d/public-api/loader/matrix-stack.h +++ b/dali-scene3d/public-api/loader/matrix-stack.h @@ -29,6 +29,7 @@ namespace Dali::Scene3D::Loader /** * @brief A stack of matrices whereby each newly pushed matrix is stored * after being multiplied by the previous one (if any). + * @SINCE_2_0.7 * @note Current implementation reserves space for 16 matrices. */ class DALI_SCENE3D_API MatrixStack diff --git a/dali-scene3d/public-api/loader/mesh-definition.h b/dali-scene3d/public-api/loader/mesh-definition.h index ec3e160..911359c 100644 --- a/dali-scene3d/public-api/loader/mesh-definition.h +++ b/dali-scene3d/public-api/loader/mesh-definition.h @@ -35,6 +35,7 @@ namespace Dali::Scene3D::Loader * @brief Defines a mesh with its attributes, the primitive type to render it as, * and the file to load it from with the offset and length information for the * individual attribute buffers. + * @SINCE_2_0.7 */ struct DALI_SCENE3D_API MeshDefinition { @@ -95,7 +96,9 @@ struct DALI_SCENE3D_API MeshDefinition /** * @brief Describes raw data in terms of its position and size in a buffer. - * All units in bytes. + * + * All units in bytes. + * @SINCE_2_0.7 */ struct Blob { @@ -122,11 +125,13 @@ struct DALI_SCENE3D_API MeshDefinition /** * @brief Calculates the size of a tightly-packed buffer for the elements from the blob. + * @SINCE_2_0.7 */ uint32_t GetBufferSize() const; /** * @brief Convenience method to tell whether a Blob has meaningful data. + * @SINCE_2_0.7 */ bool IsDefined() const { @@ -134,8 +139,10 @@ struct DALI_SCENE3D_API MeshDefinition } /** - * @brief Convenience method to tell whether the elements stored in the blob follow each - * other tightly. The opposite would be interleaving. + * @brief Convenience method to tell whether the elements stored in the blob follow each other tightly. + * + * The opposite would be interleaving. + * @SINCE_2_0.7 */ bool IsConsecutive() const { @@ -144,8 +151,9 @@ struct DALI_SCENE3D_API MeshDefinition /** * @brief Computes the min / max of the input value data. - * The min and max are stored in mMin and mMax. * + * The min and max are stored in mMin and mMax. + * @SINCE_2_0.7 * @param[in] numComponents number of components of data type. e.g., 3 for Vector3. * @param[in] count The number of data. * @param[in] values Data for the mesh. @@ -155,10 +163,10 @@ struct DALI_SCENE3D_API MeshDefinition /** * @brief Applies the min / max values, if they're defined in the model * + * @SINCE_2_0.7 * @param[in] count The number of data. * @param[in] values Data for the mesh that min / max values will be applied. * @param[in] sparseIndices Pointer to array of sparse indices (or nullptr if not provided) - * */ void ApplyMinMax(uint32_t count, float* values, std::vector* sparseIndices = nullptr) const; }; @@ -167,6 +175,7 @@ struct DALI_SCENE3D_API MeshDefinition * @brief A sparse blob describes a change in a reference Blob. * @p indices describe what positions of the reference Blob change and * @p values describe the new values. + * @SINCE_2_0.7 */ struct SparseBlob { @@ -219,6 +228,7 @@ struct DALI_SCENE3D_API MeshDefinition /** * @brief Stores a blend shape. + * @SINCE_2_0.7 */ struct BlendShape { @@ -260,11 +270,13 @@ struct DALI_SCENE3D_API MeshDefinition /** * @brief Determines whether the mesh definition is that of a quad. + * @SINCE_2_0.7 */ bool IsQuad() const; /** * @brief Determines whether the mesh is used for skeletal animation. + * @SINCE_2_0.7 */ bool IsSkinned() const; @@ -276,17 +288,20 @@ struct DALI_SCENE3D_API MeshDefinition /** * @brief Returns the number of joint sets defined by the mesh * + * @SINCE_2_2.52 * @note Clamped to 4 to minimise GPU attrs. */ uint32_t GetNumberOfJointSets() const; /** * @brief Whether the mesh has blend shapes. + * @SINCE_2_0.7 */ bool HasBlendShapes() const; /** * @brief Requests normals to be generated. + * @SINCE_2_0.7 * @note Generation happens in LoadRaw(). * @note Must have Vector3 positions defined. */ @@ -294,14 +309,17 @@ struct DALI_SCENE3D_API MeshDefinition /** * @brief Requests tangents to be generated. + * @SINCE_2_0.7 * @note Generation happens in LoadRaw(). * @note Must have Vector3 normals defined. */ void RequestTangents(); /** - * @brief Loads raw geometry data, which includes index (optional) and - * attribute buffers, as well as blend shape data. This is then returned. + * @brief Loads raw geometry data, which includes index (optional) and attribute buffers, as well as blend shape data. + * + * This is then returned. + * @SINCE_2_0.7 * @note This can be done on any thread. */ RawData LoadRaw(const std::string& modelsPath, BufferDefinition::Vector& buffers); @@ -312,12 +330,14 @@ struct DALI_SCENE3D_API MeshDefinition * attribute (and index) buffers and blend shape information (if available) * from @a raw. * If mFlipVertical was set, the UVs are flipped in Y, i.e. v = 1.0 - v. + * @SINCE_2_0.7 */ MeshGeometry Load(RawData&& raw) const; /** * @brief Retrieves what Components information is in this mesh's BlendShape. * + * @SINCE_2_2.21 * @param[out] hasPositions True if the BlendShape has position components * @param[out] hasNormals True if the BlendShape has normal components * @param[out] hasTangents True if the BlendShape has tangent components diff --git a/dali-scene3d/public-api/loader/mesh-geometry.h b/dali-scene3d/public-api/loader/mesh-geometry.h index fa2ac1d..2e1b71e 100644 --- a/dali-scene3d/public-api/loader/mesh-geometry.h +++ b/dali-scene3d/public-api/loader/mesh-geometry.h @@ -29,10 +29,10 @@ namespace Dali::Scene3D::Loader { struct DALI_SCENE3D_API MeshGeometry { - Geometry geometry; ///< The array of vertices. - Texture blendShapeGeometry; ///< The array of vertices of the different blend shapes encoded inside a texture with power of two dimensions. - Vector blendShapeUnnormalizeFactor; ///< Factor used to unnormalize the geometry of the blend shape. - unsigned int blendShapeBufferOffset{0}; ///< Offset used to calculate the start of each blend shape. + Geometry geometry; ///< The array of vertices. @SINCE_2_0.7 + Texture blendShapeGeometry; ///< The array of vertices of the different blend shapes encoded inside a texture with power of two dimensions. @SINCE_2_0.7 + Vector blendShapeUnnormalizeFactor; ///< Factor used to unnormalize the geometry of the blend shape. @SINCE_2_0.7 + unsigned int blendShapeBufferOffset{0}; ///< Offset used to calculate the start of each blend shape. @SINCE_2_0.20 }; } // namespace Dali::Scene3D::Loader diff --git a/dali-scene3d/public-api/loader/model-loader.h b/dali-scene3d/public-api/loader/model-loader.h index 702b308..8a660de 100644 --- a/dali-scene3d/public-api/loader/model-loader.h +++ b/dali-scene3d/public-api/loader/model-loader.h @@ -41,6 +41,7 @@ public: /** * @brief ModelLoader Constructor. + * @SINCE_2_2.17 * @param[in] modelUrl Url of the model file to be loaded * @param[in] resourceDirectoryUrl Url of directory that contains resources. * @param[out] loadResult Loaded result that includes scene tree and resources. @@ -49,6 +50,7 @@ public: /** * @brief Request to load model from model url. + * @SINCE_2_2.17 * @param[in] pathProvider Path provider that defines resource paths. * @param[in] loadOnlyRawResource If true, load Raw resource only, and do not create Dali::Handle * If false, this loader load Raw resource and create Dali::Handle too. @@ -59,38 +61,45 @@ public: /** * @brief Set InputParameter. - * Thie method store only a pointer of InputParameter. + * + * This method store only a pointer of InputParameter. * The object of InputParameter should not be deleted until it is no longer used. + * @SINCE_2_2.17 * @param[in] inputParameter Input parameters that can be used in loading time. */ void SetInputParameter(InputParameter& inputParameter); /** - * @brief Retrieves loaded scene + * @brief Retrieves loaded scene. + * @SINCE_2_2.17 * @return SceneDefinition that is loaded from file */ Dali::Scene3D::Loader::SceneDefinition& GetScene(); /** - * @brief Retrieves resource bundle that includes resource information + * @brief Retrieves resource bundle that includes resource information. + * @SINCE_2_2.17 * @return ResourceBundle for model resources */ Dali::Scene3D::Loader::ResourceBundle& GetResources(); /** - * @brief Retrieves loaded AnimationDefinition + * @brief Retrieves loaded AnimationDefinition. + * @SINCE_2_2.17 * @return AnimationDefinition that is loaded from file */ std::vector& GetAnimations(); /** - * @brief Retrieves loaded CameraParameters + * @brief Retrieves loaded CameraParameters. + * @SINCE_2_2.17 * @return CameraParameters list that is loaded from file */ std::vector& GetCameras(); /** - * @brief Retrieves ResourceChoices + * @brief Retrieves ResourceChoices. + * @SINCE_2_2.17 * @return Choices for loaded Resources */ Dali::Scene3D::Loader::Customization::Choices& GetResourceChoices(); @@ -98,11 +107,13 @@ public: private: /** * @brief Create model loader for each file format. + * @SINCE_2_2.17 */ void CreateModelLoader(); /** * @brief Load resource of the model. + * @SINCE_2_2.17 */ void LoadResource(Dali::Scene3D::Loader::ResourceBundle::PathProvider& pathProvider, bool loadOnlyRawResource); diff --git a/dali-scene3d/public-api/loader/node-definition.h b/dali-scene3d/public-api/loader/node-definition.h index f3aa578..c1cea09 100644 --- a/dali-scene3d/public-api/loader/node-definition.h +++ b/dali-scene3d/public-api/loader/node-definition.h @@ -43,6 +43,7 @@ class ViewProjection; /** * @brief Interface to report (const) resource ids to. + * @SINCE_2_0.7 */ class DALI_SCENE3D_API IResourceReceiver { @@ -54,6 +55,7 @@ public: /** * @brief Interface to report modifiable resource ids to. + * @SINCE_2_0.7 * @note These are supposed to be transient. Obviously, the references collected * this way must not outlive the objects that they came from. */ @@ -69,6 +71,7 @@ public: * @brief Intermediate representation for a constraint that shall be * set up after the Actors were created. The target of the constraint * is the node definition that carries it. + * @SINCE_2_0.7 */ struct DALI_SCENE3D_API ConstraintDefinition { @@ -99,6 +102,7 @@ struct DALI_SCENE3D_API Transforms /** * @brief Information about a skeleton and the shader that needs to be configured with it. + * @SINCE_2_0.7 * @note Multiple skeletons shalt not share the same shader. */ struct DALI_SCENE3D_API SkinningShaderConfigurationRequest @@ -115,6 +119,7 @@ struct DALI_SCENE3D_API SkinningShaderConfigurationRequest /** * @brief Needed to configure blend shape properties. + * @SINCE_2_0.7 */ struct DALI_SCENE3D_API BlendshapeShaderConfigurationRequest { @@ -131,6 +136,7 @@ struct DALI_SCENE3D_API BlendshapeShaderConfigurationRequest /** * @brief Request for creating a constraint, output from NodeDefinition::OnCreate. + * @SINCE_2_0.7 */ struct DALI_SCENE3D_API ConstraintRequest { @@ -142,6 +148,7 @@ struct DALI_SCENE3D_API ConstraintRequest * @brief Defines a node, consisting of a name, a transform, a size, a list of child nodes, * and slots for customization and rendering logic, which are mutually exclusive in the * current implementation. + * @SINCE_2_0.7 */ struct DALI_SCENE3D_API NodeDefinition { @@ -221,18 +228,21 @@ public: // TYPES public: // METHODS /** * @brief Creates a ModelNode from this definition only. + * @SINCE_2_0.7 * @note Not recursive. */ ModelNode CreateModelNode(CreateParams& params); /** * @brief Gets local space matrix of this node + * @SINCE_2_1.32 * @return Matrix of local space. */ Matrix GetLocalSpace() const; /** * @brief Retrieves minimum and maximum position of this node in local space. + * @SINCE_2_1.32 * @param[in] resources ResourceBundle that contains mesh information of this node. * @param[out] min Minimum position of the mesh of this node. * @param[out] max Maximum position of the mesh of this node. @@ -242,21 +252,27 @@ public: // METHODS /** * @brief Retrieves Scale Factor uniform name. + * * This uniform name can be used to change scale factor for ibl. + * @SINCE_2_1.32 * @return std::string_view of the scale factor uniform name. */ static std::string_view GetIblScaleFactorUniformName(); /** * @brief Retrieves ibl Ydirection uniform name. + * * This uniform name can be used to flip y direction of ibl in shader. + * @SINCE_2_1.32 * @return std::string_view of the YDirection uniform name. */ static std::string_view GetIblYDirectionUniformName(); /** * @brief Retrieves ibl MaxLod uniform name. + * * This uniform name can be used to set max lod of ibl in shader. + * @SINCE_2_2.19 * @return std::string_view of the Max Lod uniform name. */ static std::string_view GetIblMaxLodUniformName(); @@ -299,6 +315,7 @@ public: // METHODS /** * @brief Parameters for an Arc node. + * @SINCE_2_0.7 */ class DALI_SCENE3D_API ArcRenderable : public ModelRenderable { diff --git a/dali-scene3d/public-api/loader/parse-renderer-state.h b/dali-scene3d/public-api/loader/parse-renderer-state.h index 2379fa6..3b558ee 100644 --- a/dali-scene3d/public-api/loader/parse-renderer-state.h +++ b/dali-scene3d/public-api/loader/parse-renderer-state.h @@ -25,13 +25,16 @@ namespace Dali::Scene3D::Loader { namespace RendererState { -/* - * @brief Attempts to interpret a string for renderer states, which can be a combination of the following +/** + * @brief Attempts to interpret a string for renderer states. + * + * Wwhich can be a combination of the following: * (using '|' as a delimiter, if multiple specified):
* - one of Value, exc. for NONE or those with the _BITS, _SHIFT, _MASK or _ITEMS suffix;
* - DEPTH_FUNC:${one of Comparison::Type, exc. OMIT};
* - BLEND_(SRC_DST)_(RGB|ALPHA):${one of BlendFactor::Type, exc. OMIT};
* - BUFFER_MODE:${one of BufferMode::Type, exc. OMIT}; + * @SINCE_2_0.7 * @param string The string to parse; * @param length The length of the string; If left at 0, strlen() will be called, which of * course is only suitable i the string is null-terminated. diff --git a/dali-scene3d/public-api/loader/renderer-state.h b/dali-scene3d/public-api/loader/renderer-state.h index 240a343..25365e9 100644 --- a/dali-scene3d/public-api/loader/renderer-state.h +++ b/dali-scene3d/public-api/loader/renderer-state.h @@ -25,8 +25,9 @@ namespace Dali::Scene3D::Loader { -/* +/** * @brief Contains values for comparison functions used in depth and stencil testing. + * @SINCE_2_0.7 * @note Relative order of members must match DepthFunction::Type and StencilFunction::Type. */ struct DALI_SCENE3D_API Comparison @@ -47,8 +48,9 @@ struct DALI_SCENE3D_API Comparison Comparison() = delete; }; -/* +/** * @brief Determines the blend factor used. + * @SINCE_2_0.7 * @note Relative order of members must match BlendFactor::Type. */ struct DALI_SCENE3D_API BlendFactor @@ -76,27 +78,29 @@ struct DALI_SCENE3D_API BlendFactor BlendFactor() = delete; }; -/* +/** * @brief Determines which buffers shall the Renderer write into. + * @SINCE_2_0.7 * @note Relative order of members must match RenderMode::Type. */ struct DALI_SCENE3D_API BufferMode { enum Type { - OMIT, ///< not specified - will not be updated - NONE, ///< Don’t write to either color or stencil buffer (But will potentially render to depth buffer). - AUTO, ///< Writes are managed by the Actor Clipping API. This is DALi's default. - COLOR, ///< Ignore stencil properties. Write to the color buffer. - STENCIL, ///< Use the stencil properties. Do not write to the color buffer. - COLOR_STENCIL ///< Use the stencil properties AND Write to the color buffer. + OMIT, ///< not specified - will not be updated. @SINCE_2_0.7 + NONE, ///< Don’t write to either color or stencil buffer (But will potentially render to depth buffer). @SINCE_2_0.7 + AUTO, ///< Writes are managed by the Actor Clipping API. This is DALi's default. @SINCE_2_0.7 + COLOR, ///< Ignore stencil properties. Write to the color buffer. @SINCE_2_0.7 + STENCIL, ///< Use the stencil properties. Do not write to the color buffer. @SINCE_2_0.7 + COLOR_STENCIL ///< Use the stencil properties AND Write to the color buffer. @SINCE_2_0.7 }; BufferMode() = delete; }; -/* +/** * @brief Contains values and functionality for configuring Renderers. + * @SINCE_2_0.7 */ namespace RendererState { @@ -133,9 +137,10 @@ enum DALI_SCENE3D_API Value : Type DEFAULT = DEPTH_WRITE | DEPTH_TEST | CULL_BACK | (Comparison::LESS_EQUAL << DEPTH_FUNCTION_SHIFT), }; -/* +/** * @brief Encodes the given blend factors into a RenderMode value, maskable into other options, - * passable into ApplyRenderMode(). + * passable into ApplyRenderMode(). + * @SINCE_2_0.7 */ inline DALI_SCENE3D_API constexpr uint32_t FromBlendFactors(BlendFactor::Type srcRgb, BlendFactor::Type destRgb, BlendFactor::Type srcAlpha, BlendFactor::Type destAlpha) { @@ -144,8 +149,9 @@ inline DALI_SCENE3D_API constexpr uint32_t FromBlendFactors(BlendFactor::Type sr << BLEND_FACTOR_BASE_SHIFT; } -/* +/** * @brief Applies the settings encoded in @a rendererState, to a @a renderer. + * @SINCE_2_0.7 * @note Depth function is only set if not Comparison::OMIT. * @note Blend factors are only set if not BlendFactor::OMIT. * @note Buffer mode is only set is not BufferMode::OMIT. diff --git a/dali-scene3d/public-api/loader/resource-bundle.h b/dali-scene3d/public-api/loader/resource-bundle.h index 08dea60..c701112 100644 --- a/dali-scene3d/public-api/loader/resource-bundle.h +++ b/dali-scene3d/public-api/loader/resource-bundle.h @@ -34,8 +34,9 @@ namespace Dali::Scene3D::Loader { -/* +/** * @brief The types of resources that .dli may define. + * @SINCE_2_0.7 */ struct DALI_SCENE3D_API ResourceType { @@ -50,17 +51,20 @@ struct DALI_SCENE3D_API ResourceType ResourceType() = delete; }; -/* - * @return The string value corresponding to the given resource @a type. +/** + * @brief The string value corresponding to the given resource @a type. + * @SINCE_2_0.7 + * @return The string value for type. */ DALI_SCENE3D_API const char* GetResourceTypeName(ResourceType::Value type); using ResourceRefCounts = std::vector>; -/* +/** * @brief Stores all resource definitions along with the DALi resources that * could be created from them, directly indexible into with values from a dli * document. + * @SINCE_2_0.7 */ class DALI_SCENE3D_API ResourceBundle { @@ -88,9 +92,11 @@ public: ResourceBundle& operator=(ResourceBundle&&) = default; /** - * @return A ResourceRefCounts object with the correct number of entries for + * @brief A ResourceRefCounts object with the correct number of entries for * all resource types (based on the various resource definition vectors), * with all reference counts set to 0. + * @SINCE_2_0.7 + * @return A ResourceRefCounts object. */ ResourceRefCounts CreateRefCounter() const; @@ -98,15 +104,19 @@ public: * @brief Based on a ResourceRefCounts, and more specifically the reference * count of materials therein, it will calculate the reference count of * environment maps. + * @SINCE_2_0.7 */ void CountEnvironmentReferences(); /** - * @brief Performs the loading of all resources based on their respective - * reference count in @a refCounts. Resources that had a non-zero ref count will be - * loaded unless we already have a handle to them (OR the ForceReload option was specified). + * @brief Performs the loading of all resources based on their respective reference count in @a refCounts. + * + * Resources that had a non-zero ref count will be loaded unless we already have a handle to them + * (OR the ForceReload option was specified). * Any handles we have to resources that come in with a zero ref count will be reset, * UNLESS the KeepUnused option was specified. + * + * @SINCE_2_0.7 * @param[in] pathProvider path provider for resource data. * @param[in] options Option to load resource * @note This method creates DALi objects like Dali::Texture, Dali::Geometry, etc. @@ -115,11 +125,14 @@ public: Options::Type options = Options::None); /** - * @brief Loads of all resources based on their respective - * reference count in @a refCounts. Resources that had a non-zero ref count will be - * loaded unless we already have a handle to them (OR the ForceReload option was specified). + * @brief Loads of all resources based on their respective reference count in @a refCounts. + * + * Resources that had a non-zero ref count will be loaded unless we already have a handle to them + * (OR the ForceReload option was specified). * Any handles we have to resources that come in with a zero ref count will be reset, * UNLESS the KeepUnused option was specified. + * + * @SINCE_2_2.9 * @note This method don't create any of DALi objects. * @param[in] pathProvider path provider for resource data. * @param[in] options Option to load resource @@ -132,6 +145,7 @@ public: /** * @brief Generates DALi objects from already loaded Raw Resources. + * @SINCE_2_2.9 * @param[in] options Option to load resource * @note This method generates DALi objects from raw data that is already * loaded by LoadRawResources method. Therefore, LoadRawResources should be called first diff --git a/dali-scene3d/public-api/loader/scene-definition.h b/dali-scene3d/public-api/loader/scene-definition.h index 312b9e6..776d161 100644 --- a/dali-scene3d/public-api/loader/scene-definition.h +++ b/dali-scene3d/public-api/loader/scene-definition.h @@ -35,9 +35,10 @@ namespace Dali::Scene3D::Loader { class MatrixStack; -/* +/** * @brief Intermediate representation of a scene with functionality required to - * create DALi objects (Actors, Renderers) from it. + * create DALi objects (Actors, Renderers) from it. + * @SINCE_2_0.7 */ class DALI_SCENE3D_API SceneDefinition { @@ -51,87 +52,102 @@ public: // METHODS SceneDefinition(SceneDefinition&& other); ~SceneDefinition(); - /* + /** * @brief Registers a scene root node. + * @SINCE_2_0.7 * @return The index of the scene root node *registration*. */ Index AddRootNode(Index iNode); - /* - * @return the list of scene root node IDs in the order of their loading. + /** + * @brief Retrieves a list of scene root node IDs in the order of loading. + * @SINCE_2_0.7 + * @return List of scene root node IDs in the order of loading */ const std::vector& GetRoots() const; - /* + /** * @brief Removes scene root registration at the given index @a iRoot. - * @note @a iRoot is the index of the registration (i.e. into the vector returned by GetRoots()), - * not of the node. + * @SINCE_2_0.7 + * @note @a iRoot is the index of the registration (i.e. into the vector returned by GetRoots()), not of the node. */ void RemoveRootNode(Index iRoot); - /* - * @return The number of node( definition)s in the scene. + /** + * @brief Retrieve the number of node(definition)s in the scene. + * @SINCE_2_0.7 + * @return The number of node(definition)s in the scene */ uint32_t GetNodeCount() const; - /* - * @return Const pointer to the node (definition) at the given index. + /** + * @brief Retrieve a const pointer to the node (definition) at the given index. + * @SINCE_2_0.7 + * @return Const pointer to the node (definition). */ const NodeDefinition* GetNode(Index iNode) const; - /* - * @return Pointer to the node (definition) at the given index. + /** + * @brief Retrive a pointer to the node (definition) at the given index. + * @SINCE_2_0.7 + * @return Pointer to the node (definition). */ NodeDefinition* GetNode(Index iNode); - /* - * @brief Traverses the scene starting from the node at the given index into - * nodes, using the given customization @a choices and the visitor @a v. + /** + * @brief Traverses the scene starting from the node at the given index into nodes, + * using the given customization @a choices and the visitor @a v. + * @SINCE_2_0.7 */ void Visit(Index iNode, const Customization::Choices& choices, NodeDefinition::IVisitor& v); - /* - * @brief Traverses the scene starting from the node at the given index into - * nodes, using the given customization @a choices and the visitor @a v. + /** + * @brief Traverses the scene starting from the node at the given index into nodes, + * using the given customization @a choices and the visitor @a v. + * @SINCE_2_0.7 */ void Visit(Index iNode, const Customization::Choices& choices, NodeDefinition::IConstVisitor& v) const; - /* - * @brief Counts the references to meshes, shaders, materials that nodes in - * the scene are holding, writing the results into @a refCounts. + /** + * @brief Counts the references to meshes, shaders, materials that nodes in the scene are holding, + * writing the results into @a refCounts. + * @SINCE_2_0.7 * @note @a refCounts' entries must have the correct size. Use ResourceBundle::GetRefCounter(). */ void CountResourceRefs(Index iNode, const Customization::Choices& choices, ResourceRefCounts& refCounts) const; - /* - * @brief Given a bundle of @a resources that are loaded, and customization - * @a choices, this method traverses the scene, creating the ModelNodes and renderers - * from node definitions. + /** + * @brief Given a bundle of @a resources that are loaded, and customization @a choices, + * this method traverses the scene, creating the ModelNodes and renderers from node definitions. + * @SINCE_2_0.7 * @return Handle to the root node. */ ModelNode CreateNodes(Index iNode, const Customization::Choices& choices, NodeDefinition::CreateParams& params); - /* - * @brief Creates / update a registry of mappings from customization tags to - * a lists of names of customizable nodes under each tag, and the number of - * options. If @a outMissingChoices was specified, each tag that it encounters - * in the scene but not in @a choices, will be registered on it with the default - * choice of 0. + /** + * @brief Creates / update a registry of mappings from customization tags to a lists of names of + * customizable nodes under each tag, and the number of options. + * + * If @a outMissingChoices was specified, each tag that it encounters in the scene but not in @a choices, + * will be registered on it with the default choice of 0. + * @SINCE_2_0.7 */ void GetCustomizationOptions(const Customization::Choices& choices, Customization::Map& outCustomizationOptions, Customization::Choices* outMissingChoices) const; - /* - * @brief Attempts to add @a nodeDef to the end of nodes, and its index to the end of - * its parent's list of children (if iParent != NodeDefinition::INVALID_PARENT). + /** + * @brief Attempts to add @a nodeDef to the end of nodes, and its index to the end of its parent's + * list of children (if iParent != NodeDefinition::INVALID_PARENT). + * @SINCE_2_0.7 * @return If the operation was successful - which requires nodeDef->name to be unique - * a pointer to the stored node definition; nullptr otherwise. */ NodeDefinition* AddNode(std::unique_ptr&& nodeDef); - /* + /** * @brief Moves the node to some other parent and / or to a different index. + * @SINCE_2_0.7 * @return Whether the operation was successful. * @note This is currently breaking an assumption of never having a child of a node at a lower * index as that of the node itself, due to the fact that we're only changing parent ids (and @@ -142,82 +158,90 @@ public: // METHODS */ bool ReparentNode(const std::string& name, const std::string& newParentName, Index siblingOrder); - /* + /** * @brief Removes a node with the given name, including all of its children, and updating * the indices on all remaining node definitions. + * @SINCE_2_0.7 * @return Whether the operation was successful. */ bool RemoveNode(const std::string& name); - /* + /** * @brief Builds the model matrix stack for the node at the given @a index. + * @SINCE_2_0.7 * @note It only pushes new matrices; does not require the stack to be empty (or cares if it was not). */ void GetNodeModelStack(Index index, MatrixStack& model) const; - /* + /** * @brief Attempts to find the definition of a node with the given @a name. Only upon * success, and if @a outIndex is non-null, the index of the node is written to it. + * @SINCE_2_0.7 * @return Pointer to the node definition; nullptr if not found. * @note No ownership transfer. */ NodeDefinition* FindNode(const std::string& name, Index* outIndex = nullptr); - /* + /** * @brief Attempts to find the definition of a node with the given @a name. Only upon * success, and if @a outIndex is non-null, the index of the node is written to it. + * @SINCE_2_0.7 * @return Pointer to the node definition; nullptr if not found. * @note No ownership transfer. */ const NodeDefinition* FindNode(const std::string& name, Index* outIndex = nullptr) const; - /* - * @return The index of the given NodeDefinition@ a node, or -1 if the node definition - * was not found. + /** + * @brief The index of the given NodeDefinition @a node, or -1 if the node definition was not found. + * @SINCE_2_0.7 + * @return The index of the given NodeDefinition @a node, or -1 if the node definition was not found */ Index FindNodeIndex(const NodeDefinition& node) const; - /* + /** * @brief Calls @a consumer with up to @a limit NodeDefinitions that evaluate to true * with @a predicate. + * @SINCE_2_0.7 * @note A @a limit value of 0 means no limit. */ void FindNodes(NodePredicate predicate, NodeConsumer consumer, unsigned int limit = 0); - /* - * @brief Calls @a consumer with up to @a limit NodeDefinitions that evaluate to true - * with @a predicate. + /** + * @brief Calls @a consumer with up to @a limit NodeDefinitions that evaluate to true with @a predicate. + * @SINCE_2_0.7 * @note A @a limit value of 0 means no limit. */ void FindNodes(NodePredicate predicate, ConstNodeConsumer consumer, unsigned int limit = 0) const; - /* + /** * @brief Applies constraints from the given requests. + * @SINCE_2_0.7 */ void ApplyConstraints(Actor& root, std::vector&& constrainables, StringCallback onError = DefaultErrorCallback) const; - /* - * @brief Ensures that there is no overlap between shaders used by nodes that have - * meshes skinned to different skeletons. + /** + * @brief Ensures that there is no overlap between shaders used by nodes that have meshes skinned to different skeletons. + * @SINCE_2_0.7 */ void EnsureUniqueSkinningShaderInstances(ResourceBundle& resources) const; - /* - * @brief Performs the configuration of the given skinning shaders with the given skeleton - * This means that the absolute transforms of the joints are calculated and set as one of - * the uniforms in the mat4 @b uBone array (in depth first traversal). Further, the following - * are created:
- * - a @b jointMatrix property on each joint Actor;
- * - constraint from the Actor's local position and rotation (and if it has a @e joint - * parent, the jointMatrix of the parent) to its @b jointMatrix property;
- * - a constraint from the the Actor's @b jointMatrix property to the related entry in - * the shader's @b uBone property;
- * This ensures the automatic update of the skeletal animation, should any of the joints' - * transform changes, by whatever means. - * @return The success of the operations. Error messages will be posted to the optional - * @a onError callback. + /** + * @brief Performs the configuration of the given skinning shaders with the given skeleton. + * + * This means that the absolute transforms of the joints are calculated and set as one of + * the uniforms in the mat4 @b uBone array (in depth first traversal). Further, the following + * are created:
+ * - a @b jointMatrix property on each joint Actor;
+ * - constraint from the Actor's local position and rotation (and if it has a @e joint + * parent, the jointMatrix of the parent) to its @b jointMatrix property;
+ * - a constraint from the the Actor's @b jointMatrix property to the related entry in + * the shader's @b uBone property;
+ * This ensures the automatic update of the skeletal animation, should any of the joints' transform changes, + * by whatever means. + * @SINCE_2_0.7 + * @note Error messages will be posted to the optional @a onError callback. * @note A maximum of SkinningDetails::MAX_JOINTS joints per skeleton are supported at the moment. * @note Even if multiple skinned meshes use the same skinning shader, the correct number * of separate instances need to be declared in the .dli to avoid clashing uniform @@ -227,8 +251,9 @@ public: // METHODS Actor root, std::vector&& requests) const; - /* + /** * @brief Ensures there is no two meshes with blend shapes sharing the same shader. + * @SINCE_2_0.7 */ void EnsureUniqueBlendShapeShaderInstances(ResourceBundle& resources) const; @@ -237,7 +262,8 @@ public: // METHODS * * For each node with blend shapes it registers into the actor the weights properties for each morph target * and some needed uniforms into the shader. - * + * + * @SINCE_2_0.7 * @param[in] root The root actor. * @param[in] requests The requests to configure blend shapes. * @param[in] resources The resources bundle. Meshes need to be accessed to configure the blend shapes. diff --git a/dali-scene3d/public-api/loader/shader-definition.h b/dali-scene3d/public-api/loader/shader-definition.h index f39ac5f..b4d8ea5 100644 --- a/dali-scene3d/public-api/loader/shader-definition.h +++ b/dali-scene3d/public-api/loader/shader-definition.h @@ -28,10 +28,11 @@ namespace Dali::Scene3D::Loader { -/* +/** * @brief Defines a shader with paths to the files which define its * vertex and fragment components, and a mapping of uniform names (which are * used to refer to them in GLSL) to data. + * @SINCE_2_0.7 */ struct DALI_SCENE3D_API ShaderDefinition { @@ -53,17 +54,19 @@ struct DALI_SCENE3D_API ShaderDefinition ShaderDefinition(ShaderDefinition&&) = default; ShaderDefinition& operator=(ShaderDefinition&&) = default; - /* + /** * @brief Attempts to load the source of the vertex and fragment shaders, * then performs pre-processing of defines. + * @SINCE_2_0.7 * @note This may be called from any thread. */ RawData LoadRaw(const std::string& shadersPath) const; - /* + /** * @brief Creates a DALi Shader from the sources in @a raw, traverses * uniforms to get them to register their data against their name, * then returns the Shader. + * @SINCE_2_0.7 * @note This must be called from the event thread. */ Shader Load(RawData&& raw) const; diff --git a/dali-scene3d/public-api/loader/shader-manager.h b/dali-scene3d/public-api/loader/shader-manager.h index af28cd8..2ef95ce 100644 --- a/dali-scene3d/public-api/loader/shader-manager.h +++ b/dali-scene3d/public-api/loader/shader-manager.h @@ -40,8 +40,10 @@ typedef IntrusivePtr ShaderManagerPtr; /** * @brief This class is to manage Shaders. + * * This class could be used as factory class to create Dali::Shader. * And once created Dali::Shader is kept in this manager and will be returned when the same Dali::Shader is requested to be created. + * @SINCE_2_2.34 */ class DALI_SCENE3D_API ShaderManager : public RefObject { @@ -51,8 +53,10 @@ public: /** * @brief Produces a Dali::Shader for the input materialDefinition and meshDefinition. + * * Returns a cached Dali::Shader if the requested Dali::Shader has already been created once. * (Although the input materialDefinition and meshDefinition are not identical to those used to create the cached Dali::Shader, they share the cached one.) + * @SINCE_2_2.34 * @param[in] materialDefinition MaterialDefinition that includes information of material to create Shader. * @param[in] meshDefinition meshDefinition that includes information of mesh to create Shader. * @return ShaderOption for the materialDefinition and meshDefinition. @@ -60,8 +64,10 @@ public: ShaderOption ProduceShaderOption(const MaterialDefinition& materialDefinition, const MeshDefinition& meshDefinition); /** - * @brief Produces a Dali::Shader for the input ShaderOption + * @brief Produces a Dali::Shader for the input ShaderOption. + * * Returns a cached Dali::Shader if the requested Dali::Shader has already been created once. + * @SINCE_2_2.34 * @param[in] shaderOption shader option to create Shader. * @return Dali::Shader of the shader option */ @@ -69,6 +75,7 @@ public: /** * @brief Returns RendererState of the input materialDefinition. + * @SINCE_2_2.34 * @param[in] materialDefinition MaterialDefinition to get RendererState * @return RendererState of the materialDefinition. */ @@ -76,6 +83,7 @@ public: /** * @brief Adds new lights for each of shaders. + * @SINCE_2_2.34 * @param[in] light Light object to be newly added. * @return True when the new light object is added successfully. */ @@ -83,35 +91,40 @@ public: /** * @brief Removes light from each of shaders. + * @SINCE_2_2.34 * @param[in] light Light object to be removed. */ void RemoveLight(Scene3D::Light light); /** * @brief Retrieves added light counts. + * @SINCE_2_2.34 * @return The number of added light count. */ uint32_t GetLightCount() const; /** * @brief Set a shadow to this scene by input light. - * + * @SINCE_2_2.34 * @param[in] light Light object to make shadow. */ void SetShadow(Scene3D::Light light); /** * @brief Removes Shadow from this SceneView. + * @SINCE_2_2.34 */ void RemoveShadow(); /** * @brief Update uniform properties of shadow for the input light. + * @SINCE_2_2.34 * @param[in] light Light object to update shadow uniform. */ void UpdateShadowUniform(Scene3D::Light light); private: + /// @cond internal /** * @brief Sets constraint to the shaders with light of light index. * @param[in] lightIndex index of light that will be connected with shaders by constraint. @@ -148,6 +161,7 @@ private: */ DALI_INTERNAL void SetShadowConstraintToShader(Dali::Shader shader); + /// @endcond private: struct Impl; const std::unique_ptr mImpl; diff --git a/dali-scene3d/public-api/loader/shader-option.h b/dali-scene3d/public-api/loader/shader-option.h index 378d85b..063d4c0 100644 --- a/dali-scene3d/public-api/loader/shader-option.h +++ b/dali-scene3d/public-api/loader/shader-option.h @@ -69,30 +69,35 @@ public: public: /** * @brief Sets transparency option. + * @SINCE_2_2.33 */ void SetTransparency(); /** * @brief Adds new shader definition option. - * If the option is already added, nothin is changed. * + * If the option is already added, nothin is changed. + * @SINCE_2_2.33 * @param[in] shaderOptionType Option to be added, */ void AddOption(Type shaderOptionType); /** - * Adds macro definitions for joints based on the number of joint sets. + * @brief Adds macro definitions for joints based on the number of joint sets. + * @SINCE_2_2.52 */ void AddJointMacros(size_t numberOfJointSets); /** - * Enables empty preprocessor definitions to be defined to a value + * @brief Enables empty preprocessor definitions to be defined to a value. + * @SINCE_2_2.52 */ void AddMacroDefinition(std::string macro, std::string definition); /** * @brief Retrieves current shader option hash * + * @SINCE_2_2.33 * @return Hash value of currently added options. */ HashType GetOptionHash() const; @@ -100,6 +105,7 @@ public: /** * @brief Retrieves a list of define keywords. * + * @SINCE_2_2.33 * @param[out] defines A list of define keywords those are used in this option. */ void GetDefines(std::vector& defines) const; @@ -107,13 +113,15 @@ public: /** * @brief Retrieves a single shader define keyword of input type. * + * @SINCE_2_2.33 * @param[in] shaderOptionType Shader definition option type to know its keyword. * @return string keyword of shader define. */ static std::string_view GetDefineKeyword(Type shaderOptionType); /** - * Get any macro definitions + * @brief Get any macro definitions. + * @SINCE_2_2.52 */ const std::vector& GetMacroDefinitions() const; diff --git a/dali-scene3d/public-api/loader/skeleton-definition.h b/dali-scene3d/public-api/loader/skeleton-definition.h index 0fca023..4db02ff 100644 --- a/dali-scene3d/public-api/loader/skeleton-definition.h +++ b/dali-scene3d/public-api/loader/skeleton-definition.h @@ -26,8 +26,9 @@ namespace Dali::Scene3D::Loader { -/* +/** * @brief A set of joints (stored as node indices), and an optional root node index. + * @SINCE_2_0.7 * @note The list of joints must not be empty and must not contain INVALID_INDEX. * @note Client code should not change the order of joints, as they are indexed by mesh vertex data. * @note Client code should make no assumption about the relation of the joint IDs. diff --git a/dali-scene3d/public-api/loader/skinning-details.h b/dali-scene3d/public-api/loader/skinning-details.h index 59f778a..7752219 100644 --- a/dali-scene3d/public-api/loader/skinning-details.h +++ b/dali-scene3d/public-api/loader/skinning-details.h @@ -18,8 +18,8 @@ */ // EXTERNAL INCLUDES -#include #include +#include #include // INTERNAL INCLUDES @@ -41,13 +41,15 @@ public: Matrix inverseMatrix; }; - /* + /** * @brief Upper limit on the number of joints supported. + * @SINCE_2_0.7 */ static const uint32_t MAX_JOINTS; - /* + /** * @brief Name of bone matrix uniform (array). + * @SINCE_2_0.7 */ static const char* BONE_UNIFORM_NAME; diff --git a/dali-scene3d/public-api/loader/string-callback.h b/dali-scene3d/public-api/loader/string-callback.h index 7a3564d..10a8c4c 100644 --- a/dali-scene3d/public-api/loader/string-callback.h +++ b/dali-scene3d/public-api/loader/string-callback.h @@ -26,13 +26,15 @@ namespace Dali::Scene3D::Loader { -/* +/** * @brief A callback to post strings to. + * @SINCE_2_0.7 */ using StringCallback = std::function; -/* +/** * @brief Simply passes the formatted message to LOGE(). + * @SINCE_2_0.7 */ DALI_SCENE3D_API void DefaultErrorCallback(const std::string& message); diff --git a/dali-scene3d/public-api/loader/utils.h b/dali-scene3d/public-api/loader/utils.h index 17d4261..8add8d5 100644 --- a/dali-scene3d/public-api/loader/utils.h +++ b/dali-scene3d/public-api/loader/utils.h @@ -29,11 +29,10 @@ namespace Dali::Scene3D::Loader { -/* - * @brief Fixed size backing buffer to use with std::ostreams where control over - * allocations (which this does not make), is required. - * @note All stream insertions that would overflow the buffer that StreamBuffer - * was created with, will fail. +/** + * @brief Fixed size backing buffer to use with std::ostreams where control over allocations (which this does not make), is required. + * @SINCE_2_0.7 + * @note All stream insertions that would overflow the buffer that StreamBuffer was created with, will fail. */ class DALI_SCENE3D_API StreamBuffer : public std::basic_streambuf { @@ -41,10 +40,11 @@ public: StreamBuffer(char* buffer, size_t size) noexcept(true); }; -/* - * @brief Wraps an ostream with a pre-allocated, fixed size backing buffer - * which a message can be formatted into. Upon destruction, it throws a - * DaliException with the message. +/** + * @brief Wraps an ostream with a pre-allocated, fixed size backing buffer which a message can be formatted into. + * + * Upon destruction, it throws a DaliException with the message. + * @SINCE_2_0.7 */ class DALI_SCENE3D_API ExceptionFlinger { @@ -80,39 +80,46 @@ private: std::ostream mStream; }; -/* +/** * @brief Formats the given printf-style varargs into a std::string. + * @SINCE_2_0.7 */ DALI_SCENE3D_API std::string FormatString(const char* format, ...); -/* - * @return The @n th bit in a bitmask. +/** + * @brief The @n th bit in a bitmask. + * @SINCE_2_0.7 + * @return The @n th bit in a bitmask */ DALI_SCENE3D_API constexpr size_t NthBit(size_t n) { return 1u << n; } -/* - * @return Whether all of @a mask 's bits are set on @a value. +/** + * @brief Whether all of @a mask 's bits are set on @a value. + * @SINCE_2_0.7 + * @return Whether all of @a mask 's bits are set on @a value */ inline DALI_SCENE3D_API bool MaskMatch(uint32_t value, uint32_t mask) { return (value & mask) == mask; } -/* +/** * @brief Convert a four-letter(, null-terminated) string literal into a uint32_t. + * @SINCE_2_0.7 */ inline DALI_SCENE3D_API constexpr uint32_t FourCC(const char (&fourCC)[5]) { return (fourCC[3] << 24) | (fourCC[2] << 16) | (fourCC[1] << 8) | fourCC[0]; } -/* +/** * @brief Insensitive case compare function. - * @param[in] a, compare string - * @param[in] b, compare string + * @SINCE_2_0.7 + * @param[in] a compare string + * @param[in] b compare string * @return true if strings are equal */ inline DALI_SCENE3D_API bool CaseInsensitiveCharacterCompare(unsigned char a, unsigned char b) @@ -121,10 +128,11 @@ inline DALI_SCENE3D_API bool CaseInsensitiveCharacterCompare(unsigned char a, un return std::tolower(a) == std::tolower(b); } -/* +/** * @return true if the lower cased ASCII strings are equal. - * @param[in] a, compare string - * @param[in] b, compare string + * @SINCE_2_0.7 + * @param[in] a compare string + * @param[in] b compare string */ inline DALI_SCENE3D_API bool CaseInsensitiveStringCompare(const std::string& a, const std::string& b) { @@ -136,17 +144,19 @@ inline DALI_SCENE3D_API bool CaseInsensitiveStringCompare(const std::string& a, return result; } -/* - * @brief Attempts to load the contents of a text file; returns empty string on - * failure. A pointer to a boolean may be passed in @a fail; this will be set - * to true in case of failure (should only be checked if the returned string - * was empty()). +/** + * @brief Attempts to load the contents of a text file; returns empty string on failure. + * + * A pointer to a boolean may be passed in @a fail; this will be set to true in case of failure + * (should only be checked if the returned string was empty()). + * @SINCE_2_0.7 */ DALI_SCENE3D_API std::string LoadTextFile(const char* path, bool* fail = nullptr); -/* - * @brief Makes a number of calls to @a fn, passing to each one the given - * @a actor then each of its children, in depth-first traversal. +/** + * @brief Makes a number of calls to @a fn, passing to each one the given @a actor then each of its children, in depth-first traversal. + * + * @SINCE_2_0.7 * @note @a fn must not change the actor hierarchy during traversal. * @note Use of a @a fn that is itself recursing in @a is also discouraged * for performance and stability reasons. @@ -163,9 +173,9 @@ inline DALI_SCENE3D_API void VisitActor(Actor a, Func fn) } } -/* - * @brief Convenience function to set the given actor @a 's anchor point - * and parent origin to center. +/** + * @brief Convenience function to set the given actor @a 's anchor point and parent origin to center. + * @SINCE_2_0.7 */ inline DALI_SCENE3D_API void SetActorCentered(Actor a) { @@ -184,13 +194,15 @@ enum DALI_SCENE3D_API Values : Type }; } // namespace TexturedQuadOptions -/* +/** * @brief Makes... geometry for a textured quad. + * @SINCE_2_0.7 */ DALI_SCENE3D_API Geometry MakeTexturedQuadGeometry(TexturedQuadOptions::Type options = TexturedQuadOptions::NONE); -/* +/** * @brief Fixes the path of a file. Replaces the '\\' separator by the '/' one. + * @SINCE_2_0.7 * @param[in,out] path The path to be fixed. */ DALI_SCENE3D_API void ToUnixFileSeparators(std::string& path); diff --git a/dali-scene3d/public-api/loader/view-projection.h b/dali-scene3d/public-api/loader/view-projection.h index c1e5532..3516a33 100644 --- a/dali-scene3d/public-api/loader/view-projection.h +++ b/dali-scene3d/public-api/loader/view-projection.h @@ -26,8 +26,8 @@ namespace Dali::Scene3D::Loader { /** - * @brief Contains view and projection matrices, also caching the view-projection - * and inverse projection matrices. + * @brief Contains view and projection matrices, also caching the view-projection and inverse projection matrices. + * @SINCE_2_0.7 */ class ViewProjection { @@ -41,8 +41,9 @@ public: return mProjection; } - /* + /** * @brief Updates the cached view projection and inverse projection matrices. + * @SINCE_2_0.7 */ void Update(); -- 2.7.4