From 79ddebefe3424a76934fe193496da61cd3a1adb3 Mon Sep 17 00:00:00 2001 From: David Steele Date: Mon, 17 Mar 2014 17:00:38 +0000 Subject: [PATCH] Updated non-capi public API documentation to new style. Updated coding style guide to reflect true dali style and new doxygen style. Change-Id: I30e697223143d3c096885d1b542e307cc8865970 Signed-off-by: David Steele --- dali/public-api/actors/light-actor.h | 35 ++- dali/public-api/actors/model-actor-factory.h | 20 +- dali/public-api/animation/animator-functions.h | 57 +++- dali/public-api/common/dali-vector.h | 124 +++++---- dali/public-api/common/light.h | 73 +++-- dali/public-api/common/map-wrapper.h | 1 + dali/public-api/common/ref-counted-dali-vector.h | 39 ++- dali/public-api/common/set-wrapper.h | 1 + dali/public-api/dynamics/dynamics-body-config.h | 115 +++++--- dali/public-api/dynamics/dynamics-body.h | 53 ++-- dali/public-api/dynamics/dynamics-collision.h | 28 +- dali/public-api/dynamics/dynamics-joint.h | 44 ++- dali/public-api/dynamics/dynamics-shape.h | 39 ++- dali/public-api/dynamics/dynamics-world-config.h | 35 ++- dali/public-api/dynamics/dynamics-world.h | 39 ++- dali/public-api/events/hit-test-algorithm.h | 23 +- dali/public-api/events/mouse-wheel-event.h | 33 ++- dali/public-api/geometry/mesh-data.h | 183 ++++++++----- dali/public-api/geometry/mesh.h | 31 ++- dali/public-api/geometry/spline.h | 88 +++--- dali/public-api/images/distance-field.h | 4 +- dali/public-api/modeling/bone.h | 29 +- dali/public-api/modeling/entity-animator-map.h | 75 +++-- dali/public-api/modeling/entity.h | 117 +++++--- dali/public-api/modeling/model-animation-map.h | 18 +- dali/public-api/modeling/model-data.h | 83 ++++-- dali/public-api/modeling/model.h | 58 ++-- dali/public-api/object/type-info.h | 53 ++-- dali/public-api/object/type-registry.h | 62 +++-- dali/public-api/scripting/scripting.h | 16 +- dali/public-api/text/utf8.h | 7 +- docs/coding-style.html | 332 +++++++++++++---------- 32 files changed, 1236 insertions(+), 679 deletions(-) diff --git a/dali/public-api/actors/light-actor.h b/dali/public-api/actors/light-actor.h index 94fa7f5..5de96d6 100644 --- a/dali/public-api/actors/light-actor.h +++ b/dali/public-api/actors/light-actor.h @@ -21,6 +21,7 @@ #include #include + namespace Dali DALI_IMPORT_API { @@ -30,7 +31,7 @@ class LightActor; } /** - * Controls a light source loaded from a file containing a 3D scene. + * @brief Controls a light source loaded from a file containing a 3D scene. * * Allows the developer to use actor semantics to control a light source. * see @ref Dali::Model @@ -50,27 +51,33 @@ public: static const Property::Index DIRECTION; ///< name "direction", type VECTOR3 /** - * Create an uninitialized LightActor handle. This can be initialised with LightActor::New(). + * @brief Create an uninitialized LightActor handle. + * + * This can be initialised with LightActor::New(). * Calling member functions with an uninitialized Dali::Object is not allowed. */ LightActor(); /** - * Create a LightActor object + * @brief Create a LightActor object. + * * @return A handle to a newly allocated LightActor. */ static LightActor New(); /** - * Downcast an Object handle to LightActor. If handle points to a LightActor the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to LightActor. + * + * If handle points to a LightActor the downcast produces valid + * handle. If not the returned handle is left uninitialized. * @param[in] handle to An object * @return handle to a LightActor or an uninitialized handle */ static LightActor DownCast( BaseHandle handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~LightActor(); @@ -81,25 +88,29 @@ public: using BaseHandle::operator=; /** - * Set the light properties for the actor + * @brief Set the light properties for the actor. + * * @param[in] light The light properties */ void SetLight(Light light); /** - * Get the current light properties for the actor + * @brief Get the current light properties for the actor. + * * @return The light properties */ Light GetLight(); /** - * Set this light's active state + * @brief Set this light's active state. + * * @param[in] active Set to true to activate this light */ void SetActive( bool active); /** - * Get the active status of this light. + * @brief Get the active status of this light. + * * @return true if this light is active */ bool GetActive(); @@ -108,7 +119,8 @@ public: public: // Not intended for application developers /** - * This constructor is used by Dali New() methods + * @brief This constructor is used by Dali New() methods. + * * @param [in] actor A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL LightActor(Internal::LightActor* actor); @@ -116,4 +128,5 @@ public: // Not intended for application developers } // namespace Dali + #endif // __DALI_LIGHT_ACTOR_H__ diff --git a/dali/public-api/actors/model-actor-factory.h b/dali/public-api/actors/model-actor-factory.h index f654cae..c8915e7 100644 --- a/dali/public-api/actors/model-actor-factory.h +++ b/dali/public-api/actors/model-actor-factory.h @@ -24,6 +24,8 @@ // INTERNAL INCLUDES #include + + namespace Dali DALI_IMPORT_API { @@ -32,15 +34,14 @@ class Animation; class Model; /** - * This factory class is used to generate actors and animations from a model - * resource. + * @brief This factory class is used to generate actors and animations from a model resource. */ class DALI_IMPORT_API ModelActorFactory { public: /** - * Create an initialized Actor and child actors. + * @brief Create an initialized Actor and child actors. * * This tree of actors is either the entire model * (use an empty name), or a specific entity within the model @@ -62,7 +63,8 @@ public: static Actor BuildActorTree(Model& model, const std::string& name); /** - * Create an animation on the actor and child actors using the indexed animation map. + * @brief Create an animation on the actor and child actors using the indexed animation map. + * * If the animation map does not exist in the model, then this returns an uninitialised * handle. Uses the duration from the model. Note, changing the duration of the animation * will not change the duration of the animators. Instead, use the other variant of this method. @@ -74,7 +76,8 @@ public: static Animation BuildAnimation(Model& model, Actor actor, size_t index); /** - * Create an animation on the actor and child actors using the indexed animation map. + * @brief Create an animation on the actor and child actors using the indexed animation map. + * * If the animation map does not exist in the model, then this returns an uninitialised * handle. * @param[in] model A model resource handle @@ -86,7 +89,8 @@ public: static Animation BuildAnimation(Model& model, Actor actor, size_t index, float durationSeconds); /** - * Create an animation on the actor and child actors using the indexed animation map. + * @brief Create an animation on the actor and child actors using the indexed animation map. + * * If the animation map does not exist in the model, then this returns an uninitialised * handle. * @param[in] model A model resource handle @@ -98,7 +102,8 @@ public: static Animation BuildAnimation(Model& model, Actor actor, size_t index, AlphaFunction alpha); /** - * Create an animation on the actor and child actors using the indexed animation map. + * @brief Create an animation on the actor and child actors using the indexed animation map. + * * If the animation map does not exist in the model, then this returns an uninitialised * handle. * @param[in] model A model resource handle @@ -114,4 +119,5 @@ public: } // namespace Dali + #endif /* __DALI_MODEL_ACTOR_FACTORY_H__ */ diff --git a/dali/public-api/animation/animator-functions.h b/dali/public-api/animation/animator-functions.h index 2c07cd0..75e7f94 100644 --- a/dali/public-api/animation/animator-functions.h +++ b/dali/public-api/animation/animator-functions.h @@ -21,52 +21,97 @@ #include #include + namespace Dali DALI_IMPORT_API { namespace AnimatorFunctions { +/** + * @brief Function object that interpolates using a bounce shape. + */ struct BounceFunc { + /** + * @brief Constructor. + */ BounceFunc(float x, float y, float z); + /** + * @brief functor + */ Vector3 operator()(float alpha, const Vector3& current); - Vector3 mDistance; + Vector3 mDistance; ///< Distance to bounce }; +/** + * @brief Function object that rotates about a random axis twice. + */ struct TumbleFunc { + /** + * @brief Factory method to create a functor with a random axis. + */ static TumbleFunc GetRandom(); + /** + * @brief Class method to return a random float in the given range + */ static float Randomize(float f0, float f1); + /** + * @brief Constructor. + * + * @param[in] x The x component of the axis + * @param[in] y The y component of the axis + * @param[in] z The z component of the axis + */ TumbleFunc(float x, float y, float z); + /** + * @brief Functor to get the current rotation. + * @param[in] alpha The alpha value (the output of an alpha function) + * @param[in] current The current property value + * @return The output rotation + */ Quaternion operator()(float alpha, const Quaternion& current); - Vector4 tumbleAxis; + Vector4 tumbleAxis; ///< The axis about which to rotate }; /** - * Animator functor that allows provide a timer as input to an animation. + * @brief Animator functor that allows provide a timer as input to an animation. + * * The functor returns: scale * ( numberOfLoops + progress ) */ struct Timer { + /** + * @brief Constructor + * + * @param[in] scale Factor by which to multiply progress. + */ Timer(float scale); + /** + * @brief Functor to return the time. + * @param[in] progress The animation progress (0-1) + * @param[in] current The current property value. + * @return Time since start of animation + */ float operator()(float progress, const float& current); private: - unsigned int mLoopCounter; - float mPrevious; - float mScale; + unsigned int mLoopCounter; ///< Number of times this functor has seen looping progress + float mPrevious; ///< The last progress value + float mScale; ///< factor by which to multiply progress. }; } // namespace AnimatorFunctions } // namespace Dali + #endif // __DALI_ANIMATOR_FUNCTIONS_H__ diff --git a/dali/public-api/common/dali-vector.h b/dali/public-api/common/dali-vector.h index 8393e2e..313c7ee 100644 --- a/dali/public-api/common/dali-vector.h +++ b/dali/public-api/common/dali-vector.h @@ -17,10 +17,6 @@ // limitations under the License. // -/** - * @addtogroup CAPI_DALI_FRAMEWORK - * @{ - */ // EXTERNAL INCLUDES #include @@ -29,7 +25,8 @@ #include /** - * For DALi internal use asserts are enabled in debug builds. + * @brief For DALi internal use asserts are enabled in debug builds. + * * For Application use asserts can be enabled manually. */ #if defined( DEBUG_ENABLED ) @@ -46,7 +43,8 @@ namespace Dali DALI_IMPORT_API { /** - * Base class to handle the memory of simple vector. + * @brief Base class to handle the memory of simple vector. + * * Memory layout is such that it has two std::size_t to hold the count * and capacity of the vector. mData is adjusted so that it points to the * beginning of the first real item so that iterating the items is quick. @@ -60,12 +58,14 @@ public: // Typedefs protected: // Construction /** - * Default constructor. Does not allocate space. + * @brief Default constructor. Does not allocate space. */ VectorBase(); /** - * Destructor. Does not release the space. Derived class needs to call Release. + * @brief Destructor. + * + * Does not release the space. Derived class needs to call Release. * Not virtual as should not be called directly and we do not want * a vtable for this class as it would unnecessarily increase size. */ @@ -74,7 +74,8 @@ protected: // Construction public: // API /** - * This method is inlined as its needed frequently for End() iterator. + * @brief This method is inlined as its needed frequently for End() iterator. + * * @return The count of elements in this vector. */ SizeType Count() const @@ -103,7 +104,8 @@ public: // API SizeType Capacity() const; /** - * Release the data. + * @brief Release the data. + * * Does not call destructors on objects held. */ void Release(); @@ -111,33 +113,39 @@ public: // API protected: // for Derived classes /** - * Helper to set the count. + * @brief Helper to set the count. + * * @param count Number of elements in the vector. */ void SetCount( SizeType count ); /** - * Reserve space in the vector. + * @brief Reserve space in the vector. + * * @param count of elements to reserve. * @param elementSize of a single element. */ void Reserve( SizeType count, SizeType elementSize ); /** - * Copy a vector. + * @brief Copy a vector. + * * @param vector Vector to copy from. * @param elementSize of a single element. */ void Copy( const VectorBase& vector, SizeType elementSize ); /** - * Swap the contents of two vectors. + * @brief Swap the contents of two vectors. + * * @param vector Vector to swap with. */ void Swap( VectorBase& vector ); /** - * Erase an element. Does not change capacity. + * @brief Erase an element. + * + * Does not change capacity. * @pre last element cannot be erased as there is nothing to move. * @param address to erase from. * @param elementSize to erase. @@ -147,17 +155,18 @@ protected: // for Derived classes private: // not copiable as it does not know the size of elements - VectorBase( const VectorBase& ); - VectorBase& operator=( const VectorBase& ); + VectorBase( const VectorBase& ); ///< Undefined + VectorBase& operator=( const VectorBase& ); ///< Undefined protected: // Data - void* mData; + void* mData; ///< Pointer to the data. }; /** - * Vector algorithm variant for trivial types. + * @brief Vector algorithm variant for trivial types. + * * Trivial types do not need destructor or copy constructor called. */ template< bool IsTrivial > @@ -168,19 +177,20 @@ protected: // API for deriving classes typedef VectorBase::SizeType SizeType; /** - * Empty constructor. + * @brief Empty constructor. */ VectorAlgorithms() { } /** - * Empty destructor. + * @brief Empty destructor. */ ~VectorAlgorithms() { } /** - * Copy vector contents. + * @brief Copy vector contents. + * * @param rhs to copy from. * @param elementSize of the content. */ @@ -197,7 +207,8 @@ protected: // API for deriving classes } /** - * Reserve space in the vector. + * @brief Reserve space in the vector. + * * @param count of elements to reserve. * @param elementSize of a single element. */ @@ -207,7 +218,8 @@ protected: // API for deriving classes } /** - * Resize the vector. Does not change capacity. + * @brief Resize the vector. Does not change capacity. + * * @param count to resize to. * @param elementSize of a single element. */ @@ -218,7 +230,9 @@ protected: // API for deriving classes } /** - * Clear the contents. For simple types nothing to do. + * @brief Clear the contents. + * + * For simple types nothing to do. */ void Clear() { @@ -229,7 +243,7 @@ protected: // API for deriving classes } /** - * Release the vector. + * @brief Release the vector. */ void Release() { @@ -237,7 +251,8 @@ protected: // API for deriving classes } /** - * Erase an element. Does not change capacity. + * @brief Erase an element. Does not change capacity. + * * @param address to erase from. * @param elementSize to erase. */ @@ -249,7 +264,8 @@ protected: // API for deriving classes }; /** - * Vector algorithm variant for complex types. + * @brief Vector algorithm variant for complex types. + * * Not yet supported so will lead to compile error * as constructor and destructor are private. * TODO add support for this variant. @@ -265,7 +281,8 @@ private: }; /** - * Vector class with minimum space allocation when its empty. + * @brief Vector class with minimum space allocation when its empty. + * * @param type of the data that the vector holds. */ template< class T, bool IsTrivialType = __has_trivial_destructor(T) && __has_trivial_copy(T) > @@ -274,25 +291,26 @@ class Vector : public VectorAlgorithms< IsTrivialType > public: // API /** - * Type definitions + * @brief Type definitions. */ typedef VectorBase::SizeType SizeType; - typedef T* Iterator; /// Most simple Iterator is a pointer + typedef T* Iterator; ///< Most simple Iterator is a pointer typedef const T* ConstIterator; typedef T ItemType; + enum { BaseType = IsTrivialType }; /** - * Default constructor. Does not allocate any space. + * @brief Default constructor. Does not allocate any space. */ Vector() { } /** - * Destructor. Releases the allocated space. + * @brief Destructor. Releases the allocated space. */ ~Vector() { @@ -300,7 +318,8 @@ public: // API } /** - * Copy constructor + * @brief Copy constructor. + * * @param vector Vector to copy from. */ Vector( const Vector& vector ) @@ -310,7 +329,8 @@ public: // API } /** - * Assignment operator + * @brief Assignment operator. + * * @param vector Vector to assign from. * @return reference to self for chaining. */ @@ -366,7 +386,8 @@ public: // API } /** - * Push back an element to the vector. + * @brief Push back an element to the vector. + * * @param element to be added. */ void PushBack( const ItemType& element ) @@ -385,7 +406,8 @@ public: // API } /** - * Reserve space in the vector. + * @brief Reserve space in the vector. + * * Reserving less than current Capacity is a no-op. * @param count of elements to reserve. */ @@ -395,7 +417,8 @@ public: // API } /** - * Resize the vector. Does not change capacity. + * @brief Resize the vector. Does not change capacity. + * * @param count to resize to. * @param item to insert to the new indeces. */ @@ -420,8 +443,9 @@ public: // API } /** - * Erase an element. Does not change capacity. - * Other elements get moved. + * @brief Erase an element. + * + * Does not change capacity. Other elements get moved. * @param iterator Iterator pointing to item to remove. * @return Iterator pointing to next element. */ @@ -442,10 +466,12 @@ public: // API } /** - * Removes an element. Does not maintain order. - * Swaps the element with end and decreases size by one. - * This is much faster than Erase so use this in case order - * does not matter. Does not change capacity. + * @brief Removes an element. + * + * Does not maintain order. Swaps the element with end and + * decreases size by one. This is much faster than Erase so use + * this in case order does not matter. Does not change capacity. + * * @param iterator Iterator pointing to item to remove. */ void Remove( Iterator iterator ) @@ -462,7 +488,8 @@ public: // API } /** - * Swap the contents of two vectors. + * @brief Swap the contents of two vectors. + * * @param vector Vector to swap with. */ void Swap( Vector& vector ) @@ -471,7 +498,7 @@ public: // API } /** - * Clear the contents of the vector. Keeps its capacity. + * @brief Clear the contents of the vector. Keeps its capacity. */ void Clear() { @@ -479,7 +506,7 @@ public: // API } /** - * Release the memory that the vector holds. + * @brief Release the memory that the vector holds. */ void Release() { @@ -490,7 +517,4 @@ public: // API } // namespace Dali -/** - * @} - */ #endif /* __DALI_VECTOR_H__ */ diff --git a/dali/public-api/common/light.h b/dali/public-api/common/light.h index ff1ba89..86b9427 100644 --- a/dali/public-api/common/light.h +++ b/dali/public-api/common/light.h @@ -23,6 +23,10 @@ // INTERNAL INCLUDES #include + +/** + * The top level DALi namespace + */ namespace Dali DALI_IMPORT_API { @@ -34,7 +38,7 @@ class Light; class Light; /** - * Light source types + * @brief Light source types. */ enum LightType { @@ -45,28 +49,32 @@ enum LightType }; /** - * Encapsulates the data describing a light source + * @brief Encapsulates the data describing a light source. */ class Light : public BaseHandle { public: /** - * Create an initialized Light. + * @brief Create an initialized Light. + * * @param[in] name The light's name * @return A handle to a newly allocated Dali resource. */ static Light New(const std::string& name); /** - * Downcast an Object handle to Light handle. If handle points to a Light object the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to Light handle. + * + * If handle points to a Light object the downcast produces valid + * handle. If not the returned handle is left uninitialized. * @param[in] handle to An object * @return handle to a Light object or an uninitialized handle */ static Light DownCast( BaseHandle handle ); /** - * Create an uninitialized light; this can be initialized with Light::New() + * @brief Create an uninitialized light; this can be initialized with Light::New(). + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ Light() @@ -74,7 +82,7 @@ public: } /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~Light(); @@ -84,103 +92,119 @@ public: using BaseHandle::operator=; /** - * Set the light's name + * @brief Set the light's name. + * * @param[in] name The light's name */ void SetName(const std::string& name); /** - * Get the light's name + * @brief Get the light's name. + * * @return The light's name */ const std::string& GetName() const; /** - * Set the light's type + * @brief Set the light's type. + * * @param[in] type The type of light */ void SetType(LightType type); /** - * Get the lights type. + * @brief Get the lights type. + * * @return The light's type */ LightType GetType() const; /** - * Set the distances at which the light's intensity starts to fall off and reaches zero + * @brief Set the distances at which the light's intensity starts to fall off and reaches zero. + * * @param[in] fallOff The fall off start and end. The start is in the x component and end is in the y component. */ void SetFallOff(const Vector2& fallOff); /** - * Get the distances at which the light's intensity starts to fall off and reaches zero. + * @brief Get the distances at which the light's intensity starts to fall off and reaches zero. + * * @return The distances at which the light's intensity starts to fall off, and reaches zero. * See @ref SetFallOff */ const Vector2& GetFallOff() const; /** - * Set the spotlight's inner and outer cone angles + * @brief Set the spotlight's inner and outer cone angles. + * * @param[in] angle The spotlight's inner and outer cone angles. * The inner is in the x component and outer is in the y component. */ void SetSpotAngle(const Vector2& angle); /** - * Get the spotlight's inner and outer cone angles + * @brief Get the spotlight's inner and outer cone angles. + * * @return The spotlight's inner and outer cone angles */ const Vector2& GetSpotAngle() const; /** - * Set the ambient color for the light + * @brief Set the ambient color for the light. + * * The color is composed of rgb * @param[in] color The color to set. */ void SetAmbientColor(const Vector3& color); /** - * Get the light's ambient color + * @brief Get the light's ambient color. + * * @return the light's color as rgb */ const Vector3& GetAmbientColor() const; /** - * Set the diffuse color for the light + * @brief Set the diffuse color for the light. + * * The color is composed of rgb * @param[in] color The color to set. */ void SetDiffuseColor(const Vector3& color); /** - * Get the light's ambient color + * @brief Get the light's ambient color. + * * @return the light's color as rgb */ const Vector3& GetDiffuseColor() const; /** - * Set the specular color for the light + * @brief Set the specular color for the light. + * * The color is composed of rgb * @param[in] color The color to set. */ void SetSpecularColor(const Vector3& color); /** - * Get the light's specular color + * @brief Get the light's specular color. + * * @return the light's specular color as rgb */ const Vector3& GetSpecularColor() const; /** - * Set the direction in which the light's rays are cast. + * @brief Set the direction in which the light's rays are cast. + * * Valid when the light's type is DIRECTIONAL (see @ref Dali::LightType). * @param [in] direction The direction in which the light's rays are cast. */ void SetDirection(const Vector3& direction); /** - * Get the direction in which the light's rays are cast. + * @brief Get the direction in which the light's rays are cast. + * * Valid when the light's type is DIRECTIONAL (see @ref LightType). * @return The direction in which the light's rays are cast. */ @@ -189,7 +213,8 @@ public: public: // Not intended for application developers /** - * This constructor is used by Dali New() methods + * @brief This constructor is used by Dali New() methods. + * * @param [in] light A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL Light(Internal::Light* light); diff --git a/dali/public-api/common/map-wrapper.h b/dali/public-api/common/map-wrapper.h index fef7250..061854d 100644 --- a/dali/public-api/common/map-wrapper.h +++ b/dali/public-api/common/map-wrapper.h @@ -42,4 +42,5 @@ #endif //ifndef HIDE_DALI_INTERNALS + #endif /* __DALI_MAP_H__ */ diff --git a/dali/public-api/common/ref-counted-dali-vector.h b/dali/public-api/common/ref-counted-dali-vector.h index 3010e59..400d521 100644 --- a/dali/public-api/common/ref-counted-dali-vector.h +++ b/dali/public-api/common/ref-counted-dali-vector.h @@ -21,36 +21,51 @@ #include #include + namespace Dali DALI_IMPORT_API { /** - * A reference counting wrapper for a vector class that allows a set of - * referencing smart pointers to collaborate in managing its lifetime - * and eventually cleaning it up. + * @brief A reference counting wrapper for a vector class that allows + * a set of referencing smart pointers to collaborate in managing its + * lifetime and eventually cleaning it up. + * * This should only be allocated on the new/delete heap, not a thread's * stack. - * @param T type of the data that the vector holds + * @tparam T type of the data that the vector holds */ template< typename T > class RefCountedVector : public RefObject { public: - /** Construct empty vector. */ - RefCountedVector() {} + /** + * @brief Construct empty vector. + */ + RefCountedVector() + { + } - /** @return A reference to the vector that this object wraps. */ - Vector< T >& GetVector() { return mVector; } + /** + * @brief Get the referenced vector. + * + * @return A reference to the vector that this object wraps. + */ + Vector< T >& GetVector() + { + return mVector; + } protected: - virtual ~RefCountedVector() {} + virtual ~RefCountedVector() + { + } private: // Disable copy-constructing and copying: - RefCountedVector(const RefCountedVector &); - RefCountedVector & operator = (const RefCountedVector &); + RefCountedVector(const RefCountedVector &); ///< Undefined + RefCountedVector & operator = (const RefCountedVector &); ///< Undefined - Vector< T > mVector; + Vector< T > mVector; ///< The vector of data }; } // namespace Dali diff --git a/dali/public-api/common/set-wrapper.h b/dali/public-api/common/set-wrapper.h index 42cfa36..bd13557 100644 --- a/dali/public-api/common/set-wrapper.h +++ b/dali/public-api/common/set-wrapper.h @@ -17,6 +17,7 @@ // limitations under the License. // + // EXTERNAL INCLUDES #ifndef HIDE_DALI_INTERNALS diff --git a/dali/public-api/dynamics/dynamics-body-config.h b/dali/public-api/dynamics/dynamics-body-config.h index 602236e..e42fbaf 100644 --- a/dali/public-api/dynamics/dynamics-body-config.h +++ b/dali/public-api/dynamics/dynamics-body-config.h @@ -37,7 +37,8 @@ class DynamicsBodyConfig; } // namespace Internal /** - * Describes a DynamicsBody configuration + * @brief Describes a DynamicsBody configuration. + * * Use to create multiple instances of a DynamicsBody */ class DynamicsBodyConfig : public BaseHandle @@ -45,7 +46,7 @@ class DynamicsBodyConfig : public BaseHandle public: /** - * Enumeration of the types of dynamics bodies + * @brief Enumeration of the types of dynamics bodies. */ enum BodyType { @@ -54,7 +55,8 @@ public: }; // enum BodyType /** - * Collision filtering flags.@n + * @brief Collision filtering flags. + * * A DynamicsBody pair are considered for collision detection if a bitwise AND of * the filter group from one DynamicsBody and the filter mask of the other DynamicsBody * gives a non-zero result.@n @@ -70,19 +72,23 @@ public: public: /** - * Create a new DynamicsBody configuration object + * @brief Create a new DynamicsBody configuration object. + * * All values are set to default values... * @pre Stage::InitializeDynamics() must have been called + * @return a handle to the new DynamicsBodyconfig. */ static DynamicsBodyConfig New(); /** - * Create an uninitialized handle. Initialize with one of the DynamicsBodyConfig New methods + * @brief Create an uninitialized handle. + * + * Initialize with one of the DynamicsBodyConfig New methods */ DynamicsBodyConfig(); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~DynamicsBodyConfig(); @@ -93,19 +99,22 @@ public: public: /** - * Set the type of DynamicsBody + * @brief Set the type of DynamicsBody. + * * @param[in] type A member of BodyType enumeration. */ void SetType( const BodyType type ); /** - * Get the type of DynamicsBody specified by the Configuration + * @brief Get the type of DynamicsBody specified by the Configuration. + * * @return A member of BodyType enumeration. */ BodyType GetType() const; /** - * Define the shape for the body + * @brief Define the shape for the body. + * * @param[in] type The type of shape * @param[in] dimensions The parameters defining the shape ... * - DynamicsShape::SPHERE @@ -131,31 +140,36 @@ public: void SetShape(const DynamicsShape::ShapeType type, const Vector3& dimensions); /** - * Set the shape for the body + * @brief Set the shape for the body. + * * @param[in] shape A DynamicsShape. */ void SetShape( DynamicsShape shape ); /** - * get the shape for the body + * @brief get the shape for the body. + * * @return A DynamicsShape. */ DynamicsShape GetShape() const; /** - * Set the mass for the body. + * @brief Set the mass for the body. + * * @param[in] mass The mass for the body. */ void SetMass( const float mass); /** - * Get the mass that will be set on bodies created from this config + * @brief Get the mass that will be set on bodies created from this config. + * * @return The mass that will be set on bodies created from this config */ float GetMass() const; /** - * Get the @"elasticity@" of the body. + * @brief Get the @"elasticity@" of the body. + * * @return The @"elasticity@". * * See @ref SetElasticity @@ -163,7 +177,8 @@ public: float GetElasticity() const; /** - * Affects the @"elasticity@" of the body. + * @brief Affects the @"elasticity@" of the body. + * * This function sets the coefficient of restitution (COR) of an object.@n * @param[in] elasticity The elasticity of the body. * Assuming the other body in a collision has a elasticity factor of 1. @@ -173,7 +188,8 @@ public: void SetElasticity(const float elasticity); /** - * Get the friction coefficient for any DynamicsBody created from this DynamicsBodyConfig. + * @brief Get the friction coefficient for any DynamicsBody created from this DynamicsBodyConfig. + * * @return The friction coefficient. * * See @ref SetFriction. @@ -181,29 +197,32 @@ public: float GetFriction() const; /** - * Set the friction coefficient for any DynamicsBody created from this DynamicsBodyConfig. + * @brief Set the friction coefficient for any DynamicsBody created from this DynamicsBodyConfig. + * * @param[in] friction The friction coefficient. * This will be clamped between 0 and 1 */ void SetFriction(const float friction); /** - * Get the linear damping coefficient for any DynamicsBody created from this DynamicsBodyConfig. - * @return The linear damping coefficient. + * @brief Get the linear damping coefficient for any DynamicsBody created from this DynamicsBodyConfig. * + * @return The linear damping coefficient. * See @ref SetLinearDamping. */ float GetLinearDamping() const; /** - * Set the linear damping coefficient for any DynamicsBody created from this DynamicsBodyConfig. + * @brief Set the linear damping coefficient for any DynamicsBody created from this DynamicsBodyConfig. + * * @param[in] damping The linear damping coefficient. * This will be clamped between 0 and 1 */ void SetLinearDamping( const float damping ); /** - * Get the angular damping coefficient for any DynamicsBody created from this DynamicsBodyConfig. + * @brief Get the angular damping coefficient for any DynamicsBody created from this DynamicsBodyConfig. + * * @return The angular damping coefficient. * * See @ref SetAngularDamping. @@ -211,14 +230,16 @@ public: float GetAngularDamping() const; /** - * Set the angular damping coefficient for any DynamicsBody created from this DynamicsBodyConfig. + * @brief Set the angular damping coefficient for any DynamicsBody created from this DynamicsBodyConfig. + * * @param[in] damping The angular damping coefficient. * This will be clamped between 0 and 1 */ void SetAngularDamping(const float damping); /** - * Get the linear velocity below which the DynamicsBody can be put to sleep by the simulation. + * @brief Get the linear velocity below which the DynamicsBody can be put to sleep by the simulation. + * * @return The linear sleep velocity. * * See @ref SetLinearSleepVelocity, DynamicsBody::SetSleepEnabled. @@ -226,7 +247,8 @@ public: float GetLinearSleepVelocity() const; /** - * Set the linear velocity below which the DynamicsBody can be put to sleep by the simulation. + * @brief Set the linear velocity below which the DynamicsBody can be put to sleep by the simulation. + * * @param[in] sleepVelocity The linear sleep velocity. * * See @ref DynamicsBody::SetSleepEnabled. @@ -234,7 +256,8 @@ public: void SetLinearSleepVelocity(const float sleepVelocity); /** - * Get the angular velocity below which the DynamicsBody can be put to sleep by the simulation. + * @brief Get the angular velocity below which the DynamicsBody can be put to sleep by the simulation. + * * @return The angular sleep velocity. * * See @ref SetAngularSleepVelocity, DynamicsBody::SetSleepEnabled. @@ -242,7 +265,8 @@ public: float GetAngularSleepVelocity() const; /** - * Set the angular velocity below which the DynamicsBody can be put to sleep by the simulation. + * @brief Set the angular velocity below which the DynamicsBody can be put to sleep by the simulation. + * * @param[in] sleepVelocity The angular sleep velocity. * * See @ref DynamicsBody::SetSleepEnabled. @@ -250,82 +274,94 @@ public: void SetAngularSleepVelocity(const float sleepVelocity); /** - * Get the collision filter group.@n + * @brief Get the collision filter group.@n + * * See @ref CollisionFilter * @return The collision filter group.@n */ short int GetCollisionGroup() const; /** - * Set the collision filter group + * @brief Set the collision filter group. + * * See @ref CollisionFilter * @param[in] collisionGroup The collision filter group */ void SetCollisionGroup(const short int collisionGroup); /** - * Get the collision filter mask.@n + * @brief Get the collision filter mask.@n + * * See @ref CollisionFilter * @return The collision filter mask.@n */ short int GetCollisionMask() const; /** - * Set the collision filter mask + * @brief Set the collision filter mask. + * * See @ref CollisionFilter * @param[in] collisionMask The collision filter mask */ void SetCollisionMask(const short int collisionMask); /** - * Get the stiffness coefficient for the soft body + * @brief Get the stiffness coefficient for the soft body. + * * See @ref SetStiffness * @return The stiffness coefficient for the soft body. */ float GetStiffness() const; /** - * Set the stiffness co-efficient for the soft body + * @brief Set the stiffness co-efficient for the soft body. + * * @param[in] stiffness A value clamped between 0 and 1. * Values closer to 1 make it more stiff. */ void SetStiffness( const float stiffness ); /** - * Get the anchor hardness.@n + * @brief Get the anchor hardness.@n + * * See @ref SetAnchorHardness. * @return The anchor hardness. */ float GetAnchorHardness() const; /** - * Set the hardness of an anchor, or how much the anchor is allowed to drift + * @brief Set the hardness of an anchor, or how much the anchor is allowed to drift. + * * @param[in] hardness 0 means a soft anchor with no drift correction, 1 mean a hard anchor with full correction * hardness will be clamped between 0 and 1. */ void SetAnchorHardness( const float hardness ); /** - * Get the volume conservation coefficient. + * @brief Get the volume conservation coefficient. + * * @return The volume conservation coefficient. */ float GetVolumeConservation() const; /** - * Set the volume conservation coefficient. + * @brief Set the volume conservation coefficient. + * * Defines the magnitude of the force used to conserve the volume of the body after DynamicsBody::ConserveVolume is invoked * @param[in] conservation Range 0 <= conservation < +infinity */ void SetVolumeConservation(const float conservation); /** - * Get the shape conservation factor. + * @brief Get the shape conservation factor. + * * @return The shape conservation factor. */ float GetShapeConservation() const; /** - * Set the shape conservation factor. + * @brief Set the shape conservation factor. + * * Defines the factor used to match the shape of the body when DynamicsBody::ConserveShape. is invoked * @param[in] conservation Range 0 <= conservation < 1 */ @@ -334,7 +370,8 @@ public: // Not intended for application developers private: /** - * This constructor is used internally by Dali + * @brief This constructor is used internally by Dali. + * * @param [in] internal A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL DynamicsBodyConfig( Internal::DynamicsBodyConfig* internal ); diff --git a/dali/public-api/dynamics/dynamics-body.h b/dali/public-api/dynamics/dynamics-body.h index 55d3c5d..f999a70 100644 --- a/dali/public-api/dynamics/dynamics-body.h +++ b/dali/public-api/dynamics/dynamics-body.h @@ -37,20 +37,22 @@ class DynamicsShape; class DynamicsWorld; /** - * Represents a physical object in the physics world. + * @brief Represents a physical object in the physics world. + * * The body is defined with a shape giving it dimension enabling it to collide with other bodies. */ class DynamicsBody : public BaseHandle { public: /** - * Constructor which creates an uninitialized DynamicsBody handle. + * @brief Constructor which creates an uninitialized DynamicsBody handle. + * * Use Actor::EnableDynamics or Actor::GetDynamicsBody to initialize this handle */ DynamicsBody(); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~DynamicsBody(); @@ -62,27 +64,31 @@ public: public: // Not intended for application developers /** - * This constructor is used by Dali New() methods + * @brief This constructor is used by Dali New() methods. + * * @param [in] body A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL DynamicsBody(Internal::DynamicsBody* body); public: /** - * Get the mass of the body. + * @brief Get the mass of the body. + * * @return The mass. */ float GetMass() const; /** - * Get the @"elasticity@" of the body. + * @brief Get the @"elasticity@" of the body. + * * @return The @"elasticity@". * @ref Dali::DynamicsBodyConfig::SetElasticity */ float GetElasticity() const; /** - * Set the linear velocity for the body. + * @brief Set the linear velocity for the body. + * * Sets the speed and direction the body moves through space. * This will cancel/override any forces/impulses currently acting on the body. * @param[in] velocity The linear velocity @@ -90,13 +96,15 @@ public: void SetLinearVelocity(const Vector3& velocity); /** - * Get the current linear velocity of the body. + * @brief Get the current linear velocity of the body. + * * @return The current linear velocity of the body. */ Vector3 GetCurrentLinearVelocity() const; /** - * Set the angular velocity for the body. + * @brief Set the angular velocity for the body. + * * Set the speed and axis that the body will rotate about itself. * This will cancel/override any forces/impulses currently acting on the body. * @param[in] velocity The angular velocity @@ -104,13 +112,15 @@ public: void SetAngularVelocity(const Vector3& velocity); /** - * Get the current angular velocity of the body. + * @brief Get the current angular velocity of the body. + * * @return The current angular velocity of the body. */ Vector3 GetCurrentAngularVelocity() const; /** - * Set the body to be kinematic. + * @brief Set the body to be kinematic. + * * Kinematic bodies can be animated by DALi's animation system, but there will be only one-way interaction * dynamic objects will be pushed away but there is no influence from dynamics objects * @pre Only rigid bodies can be kinematic. @@ -119,35 +129,40 @@ public: void SetKinematic( const bool flag ); /** - * Get the kinematic state of the body + * @brief Get the kinematic state of the body. + * * @return The kinematic state */ bool IsKinematic() const; /** - * Set whether or not the simulation can put this DynamicsBody to sleep.@n + * @brief Set whether or not the simulation can put this DynamicsBody to sleep. + * * The simulation monitors the velocity of non-static bodies and can elect to put motionless * bodies to sleep.@n * SleepEnabled is true by default. * @param[in] flag Set true to allow the simulation to put the DynamicsBody to sleep, set false - * to keep the DynamicsBody enabled and updated each simulation update. * + * to keep the DynamicsBody enabled and updated each simulation update. */ void SetSleepEnabled( const bool flag ); /** - * Get whether or not the simulation can put this DynamicsBody to sleep.@n + * @brief Get whether or not the simulation can put this DynamicsBody to sleep. + * * @return A flag, when true, the simulation can put the DynamicsBody to sleep. */ bool GetSleepEnabled() const; /** - * Wake up a DynamicsBody. If the DynamicsBody is currently sleeping it will be woken, + * @brief Wake up a DynamicsBody. + * + * If the DynamicsBody is currently sleeping it will be woken, * otherwise no action is taken. */ void WakeUp(); /** - * Anchor a node in a soft body + * @brief Anchor a node in a soft body. * @param[in] index A node index * @param[in] body A rigid body * @param[in] collisions Allow collisions between this soft body and the anchor rigid body @@ -155,14 +170,14 @@ public: void AddAnchor(const unsigned int index, DynamicsBody body, const bool collisions); /** - * Take a snapshot of the current volume of this body and conserve it while the shape is deformed. + * @brief Take a snapshot of the current volume of this body and conserve it while the shape is deformed. * @param[in] flag Set true, to enable volume conservation, false to disable * @ref Dali::DynamicsBodyConfig::SetVolumeConservation() */ void ConserveVolume(const bool flag); /** - * Take a snapshot of the current shape of this body and conserve it while the shape is deformed. + * @brief Take a snapshot of the current shape of this body and conserve it while the shape is deformed. * This resists the deformation of the body. * @param[in] flag Set true, to enable shape conservation, false to disable * @ref Dali::DynamicsBodyConfig::SetShapeConservation() diff --git a/dali/public-api/dynamics/dynamics-collision.h b/dali/public-api/dynamics/dynamics-collision.h index 9514d37..7db9de7 100644 --- a/dali/public-api/dynamics/dynamics-collision.h +++ b/dali/public-api/dynamics/dynamics-collision.h @@ -34,19 +34,20 @@ class DynamicsCollision; } // namespace Internal /** - * Contains information about a collision between two actors + * @brief Contains information about a collision between two actors. */ class DynamicsCollision : public BaseHandle { public: /** - * Create an uninitialized handle. + * @brief Create an uninitialized handle. + * * Initialized handles are received in DynamicsWorld::SignalCollision handlers */ DynamicsCollision(); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~DynamicsCollision(); @@ -57,38 +58,44 @@ public: public: /** - * Get the first actor in the collision + * @brief Get the first actor in the collision. + * * @return The first actor in the collision */ Actor GetActorA(); /** - * Get the second actor in the collision + * @brief Get the second actor in the collision. + * * @return The second actor in the collision */ Actor GetActorB(); /** - * Get the force of the impact + * @brief Get the force of the impact. + * * @return the impact force * @note currently returns 0.5f for a new collision and 0.0f for dispersal */ float GetImpactForce() const; /** - * Get the point of contact on the first Actor + * @brief Get the point of contact on the first Actor. + * * @return The point of contact on the first Actor */ Vector3 GetPointOnA() const; /** - * Get the point of contact on the second Actor + * @brief Get the point of contact on the second Actor. + * * @return The point of contact on the second Actor */ Vector3 GetPointOnB() const; /** - * Get the collision normal + * @brief Get the collision normal. + * * @return The collision normal */ Vector3 GetNormal() const; @@ -96,7 +103,8 @@ public: // Not intended for application developers public: /** - * This constructor is used internally by Dali + * @brief This constructor is used internally by Dali. + * * @param [in] internal A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL DynamicsCollision( Internal::DynamicsCollision* internal ); diff --git a/dali/public-api/dynamics/dynamics-joint.h b/dali/public-api/dynamics/dynamics-joint.h index 990336d..40b4e1a 100644 --- a/dali/public-api/dynamics/dynamics-joint.h +++ b/dali/public-api/dynamics/dynamics-joint.h @@ -33,13 +33,14 @@ class DynamicsJoint; class Actor; /** - * Represents a connection (or constraint) relationship between two dynamic bodies. + * @brief Represents a connection (or constraint) relationship between two dynamic bodies. */ class DynamicsJoint : public BaseHandle { public: /** - * Enumeration to access springs and motors + * @brief Enumeration to access springs and motors. + * * The fields in the enum can be bitwise ORed to access more than one spring/motor */ enum AxisIndex @@ -55,13 +56,14 @@ public: public: /** - * Constructor which creates an uninitialized DynamicsJoint handle. + * @brief Constructor which creates an uninitialized DynamicsJoint handle. + * * Use DynamicsJoint::New(...) to initialize this handle. */ DynamicsJoint(); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~DynamicsJoint(); @@ -72,7 +74,8 @@ public: public: /** - * Set the limit for one or more linear/translation axis. + * @brief Set the limit for one or more linear/translation axis. + * * @param[in] axisIndex A bitfield specifying which axis are affected. * A combination of AxisIndex::LINEAR_X, AxisIndex::LINEAR_Y and AxisIndex::LINEAR_Z * @param[in] lowerLimit The lower limit. @@ -81,7 +84,8 @@ public: void SetLinearLimit( const int axisIndex, const float lowerLimit, const float upperLimit ); /** - * Set the limit for one or more angular/rotation axis. + * @brief Set the limit for one or more angular/rotation axis. + * * @param[in] axisIndex A bitfield specifying which axis are affected. * A combination of AxisIndex::ANGULAR_X, AxisIndex::ANGULAR_Y and AxisIndex::ANGULAR_Z * @param[in] lowerLimit The lower limit. @@ -90,7 +94,8 @@ public: void SetAngularLimit( const int axisIndex, const Degree& lowerLimit, const Degree& upperLimit ); /** - * Enable a spring + * @brief Enable a spring. + * * This will disable the motor on axisIndex if it was enabled * @param[in] axisIndex A bitfield specifying which springs are affected. * @param[in] flag Set to true to enable the spring, or false to disable them. @@ -116,21 +121,24 @@ public: void EnableSpring(const int axisIndex, const bool flag); /** - * Set the stiffness of a spring + * @brief Set the stiffness of a spring. + * * @param[in] axisIndex A bitfield specifying which springs are affected. * @param[in] stiffness Values > 0, lower values are less stiff and larger values more stiff. */ void SetSpringStiffness(const int axisIndex, const float stiffness); /** - * Set the damping of a spring + * @brief Set the damping of a spring. + * * @param[in] axisIndex A bitfield specifying which springs are affected. * @param[in] damping Values clamped between 0 and 1, with 0 meaning no damping and 1 full damping [default: 0.5]. */ void SetSpringDamping(const int axisIndex, const float damping); /** - * Set the Center point or Equilibrium point of the spring + * @brief Set the Center point or Equilibrium point of the spring. + * * @param[in] axisIndex A bitfield specifying which springs are affected. * @param[in] ratio Values clamped between [0..1]. * CentrePoint = lower + ((upper - lower) * ratio) @@ -141,7 +149,8 @@ public: void SetSpringCenterPoint(const int axisIndex, const float ratio); /** - * Enable motor + * @brief Enable motor. + * * This will disable the spring on axisIndex if it was enabled * @param[in] axisIndex A bitfield specifying which motors are affected. * @param[in] flag Set to true to enable the motors, or false to disable them. @@ -150,14 +159,16 @@ public: void EnableMotor(const int axisIndex, const bool flag); /** - * Set the velocity of the motor + * @brief Set the velocity of the motor. + * * @param[in] axisIndex A bitfield specifying which motors are affected. * @param[in] velocity Set the target velocity of the motor. */ void SetMotorVelocity(const int axisIndex, const float velocity); /** - * Set the force (or torque) for the motor + * @brief Set the force (or torque) for the motor. + * * @param[in] axisIndex A bitfield specifying which motors are affected. * @param[in] force Values clamped between [0..1]. * 0 will apply no force and 1 will apply maximum force. @@ -165,10 +176,12 @@ public: void SetMotorForce(const int axisIndex, const float force); /** - * Get one of the Actors in the joint + * @brief Get one of the Actors in the joint. + * * @param[in] first If true returns the first actor, else the second actor. * The returned object may be uninitialized if the Actor has * been destroyed. + * @return The actor in the joint */ Actor GetActor( const bool first ) const; @@ -176,7 +189,8 @@ public: public: /** - * This constructor is used by Dali New() methods + * @brief This constructor is used by Dali New() methods. + * * @param [in] joint A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL DynamicsJoint(Internal::DynamicsJoint* joint); diff --git a/dali/public-api/dynamics/dynamics-shape.h b/dali/public-api/dynamics/dynamics-shape.h index 9cf0646..96789cf 100644 --- a/dali/public-api/dynamics/dynamics-shape.h +++ b/dali/public-api/dynamics/dynamics-shape.h @@ -35,13 +35,13 @@ class Mesh; class DynamicsWorld; /** - * Defines the shape of an object in the simulation + * @brief Defines the shape of an object in the simulation. */ class DynamicsShape : public BaseHandle { public: /** - * The types of shape available + * @brief The types of shape available. */ enum ShapeType { @@ -55,54 +55,67 @@ public: public: /** - * Creates a capsule. (A cylinder capped with half spheres) + * @brief Creates a capsule. (A cylinder capped with half spheres) + * * @param[in] radius The radius of the capsule. * @param[in] length The length of the capsule. + * @return a handle to the new shape. */ static DynamicsShape NewCapsule(const float radius, const float length); /** - * Creates a cone. + * @brief Creates a cone. + * * @param[in] radius The radius of the cone. * @param[in] length The length of the cone. + * @return a handle to the new shape. */ static DynamicsShape NewCone(const float radius, const float length); /** - * Creates a cube shape. + * @brief Creates a cube shape. + * * All angles are right angles, and opposite faces are equal. * @param[in] dimensions The dimensions of the cuboid ( width, height and depth ). + * @return A handle to the new shape */ static DynamicsShape NewCube(const Vector3& dimensions); /** - * Creates a cylinder. + * @brief Creates a cylinder. + * * @param[in] radius The radius of the cylinder. * @param[in] length The length of the cylinder. + * @return A handle to the new shape */ static DynamicsShape NewCylinder(const float radius, const float length); /** - * Creates a mesh. + * @brief Creates a mesh. + * * @param[in] mesh A mesh. + * @return A handle to the new shape */ static DynamicsShape NewMesh(Mesh mesh); /** - * Creates a sphere. + * @brief Creates a sphere. + * * @param[in] radius The radius of the sphere. + * @return A handle to the new shape */ static DynamicsShape NewSphere(const float radius); public: /** - * Constructor which creates an uninitialized DynamicsShape handle. + * @brief Constructor which creates an uninitialized DynamicsShape handle. + * * Use one of the DynamicsShape::New methods to initialise the handle. */ DynamicsShape(); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~DynamicsShape(); @@ -113,7 +126,8 @@ public: public: /** - * Get the type of shape + * @brief Get the type of shape. + * * @return One of the ShapeType enumeration. */ ShapeType GetType() const; @@ -121,7 +135,8 @@ public: // Not intended for application developers public: /** - * This constructor is used by Dali New() methods + * @brief This constructor is used by Dali New() methods. + * * @param [in] internal A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL DynamicsShape(Internal::DynamicsShape* internal); diff --git a/dali/public-api/dynamics/dynamics-world-config.h b/dali/public-api/dynamics/dynamics-world-config.h index 0288001..1aa9df9 100644 --- a/dali/public-api/dynamics/dynamics-world-config.h +++ b/dali/public-api/dynamics/dynamics-world-config.h @@ -34,13 +34,13 @@ class DynamicsWorldConfig; } // namespace Internal /** - * Describes the requirements/capabilities of a physics siumlation encapsulated by a DynamicsWorld + * @brief Describes the requirements/capabilities of a physics siumlation encapsulated by a DynamicsWorld. */ class DynamicsWorldConfig : public BaseHandle { public: /** - * Enumeration specifying the capabilities required by the dynamics simulation + * @brief Enumeration specifying the capabilities required by the dynamics simulation. */ enum WorldType { @@ -52,18 +52,20 @@ public: public: /** - * Create a new DynamicsWorld configuration object - * All values are set to default values... + * @brief Create a new DynamicsWorld configuration object. + * + * All values are set to default values. + * @return A handle to the new DynamicsWorld configuration object. */ static DynamicsWorldConfig New(); /** - * Default constructor, creates an uninitalized handle + * @brief Default constructor, creates an uninitalized handle. */ DynamicsWorldConfig(); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~DynamicsWorldConfig(); @@ -74,19 +76,22 @@ public: public: /** - * Set the type of Dynamics world required for the application + * @brief Set the type of Dynamics world required for the application. + * * @param[in] type A member of WorldType enumeration. */ void SetType( const WorldType type ); /** - * Get the type of Dynamics World specified by the Configuration + * @brief Get the type of Dynamics World specified by the Configuration. + * * @return A member of WorldType enumeration. */ WorldType GetType() const; /** - * Set the world unit. + * @brief Set the world unit. + * * The simulation units are in meters * The entire simulation can be scaled by changing the world unit * EG calling SetUnit(0.01f) will scale to centimeters @@ -96,14 +101,16 @@ public: void SetUnit(const float unit); /** - * Get the current world unit. + * @brief Get the current world unit. + * * @return The current world unit * @ref SetUnit */ const float GetUnit() const; /** - * Set the number of simulation steps / DALi update tick. + * @brief Set the number of simulation steps / DALi update tick. + * * Use this to advance the simulation in smaller time steps, thus gaining a more accurate * simulation for collision detection. * Example: assume DAli is updating at 60Hz (16.667ms / update) @@ -114,7 +121,8 @@ public: void SetSimulationSubSteps( const int subSteps); /** - * Get the number of simulation steps / DALi update tick + * @brief Get the number of simulation steps / DALi update tick. + * * @return The number of simulation steps per update tick */ const int GetSimulationSubSteps() const; @@ -122,7 +130,8 @@ public: // Not intended for application developers private: /** - * This constructor is used internally by Dali + * @brief This constructor is used internally by Dali. + * * @param [in] internal A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL DynamicsWorldConfig( Internal::DynamicsWorldConfig* internal ); diff --git a/dali/public-api/dynamics/dynamics-world.h b/dali/public-api/dynamics/dynamics-world.h index e655127..4c5563c 100644 --- a/dali/public-api/dynamics/dynamics-world.h +++ b/dali/public-api/dynamics/dynamics-world.h @@ -41,8 +41,9 @@ class DynamicsJoint; class DynamicsShape; /** - * DynamicsWorld gives the application developer an alternative method of moving and rotating + * @brief DynamicsWorld gives the application developer an alternative method of moving and rotating. * actors in the DALi scene. + * * Actors are represented by DynamicsBody objects in the dynamics simulation and are moved by * forces (eg gravity). Dynamics also allows collisions between objects to be * detected and responded to in signal handlers. @@ -80,13 +81,15 @@ class DynamicsWorld : public BaseHandle public: // Signal Names - static const char* const SIGNAL_COLLISION; + static const char* const SIGNAL_COLLISION; ///< name "collision" // signals - typedef SignalV2< void (DynamicsWorld, const DynamicsCollision) > CollisionSignalV2; + typedef SignalV2< void (DynamicsWorld, const DynamicsCollision) > CollisionSignalV2; ///< Type of collision signal public: - // enums + /** + * @brief Debug modes + */ enum DEBUG_MODES { DEBUG_MODE_NONE = 0, @@ -102,12 +105,12 @@ public: public: /** - * Create an uninitialized DynamicsWorld handle. + * @brief Create an uninitialized DynamicsWorld handle. */ DynamicsWorld(); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~DynamicsWorld(); @@ -120,38 +123,44 @@ public: public: /** - * Set the gravity for the world + * @brief Set the gravity for the world. + * * @param[in] gravity a Vector3 specifying the applicable gravity for the world. */ void SetGravity( const Vector3& gravity ); /** - * Get the gravity for the world + * @brief Get the gravity for the world. + * * @return A Vector3 specifying the gravity that will be applied in the world. */ const Vector3& GetGravity() const; /** - * Get the current debug drawmode + * @brief Get the current debug drawmode. + * * @return A combination of the flags in DEBUG_MODES or 0 if debug drawing is currently disabled. */ int GetDebugDrawMode() const; /** - * Set the debug drawmode for the simulation + * @brief Set the debug drawmode for the simulation. + * * @param[in] mode A combination of the flags in DEBUG_MODES or 0 to disable debug drawing */ void SetDebugDrawMode(const int mode); /** - * Set the actor which will represent the dynamics world + * @brief Set the actor which will represent the dynamics world. + * * All actors that will participate in the dynamics simulation must be direct children of this actor * @param[in] actor The root actor for the dynamics simulation */ void SetRootActor(Actor actor); /** - * Get the root actor for the simulation + * @brief Get the root actor for the simulation. + * * @return The root actor for the dynamics simulation */ Actor GetRootActor() const; @@ -159,7 +168,8 @@ public: public: // Signals /** - * This signal is emitted when a collision is detected between two DynamicsBodies + * @brief This signal is emitted when a collision is detected between two DynamicsBodies. + * * A callback of the following type may be connected: * @code * void YourCollisionHandler(Dali::DynamicsWorld world, const Dali::DynamicsCollision collisionData); @@ -172,7 +182,8 @@ public: // Signals public: // Not intended for application developers /** - * This constructor is used internally by Dali + * @brief This constructor is used internally by Dali. + * * @param [in] internal A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL DynamicsWorld( Internal::DynamicsWorld* internal ); diff --git a/dali/public-api/events/hit-test-algorithm.h b/dali/public-api/events/hit-test-algorithm.h index 959b968..2043526 100644 --- a/dali/public-api/events/hit-test-algorithm.h +++ b/dali/public-api/events/hit-test-algorithm.h @@ -20,13 +20,14 @@ #include #include + namespace Dali DALI_IMPORT_API { class RenderTask; /** - * This namespace is provided for application developers to do hit-test for the actors. + * @brief This namespace is provided for application developers to do hit-test for the actors. * *

Hit Test Algorithm:

* @@ -100,12 +101,18 @@ class RenderTask; namespace HitTestAlgorithm { +/** + * @brief How the actor tree should be traversed. + */ enum TraverseType { CHECK_ACTOR, ///< Hit test the given actor. DESCEND_ACTOR_TREE ///< Check whether the actor tree should be descended to hit-test its children. }; +/** + * @brief Results structure containing the hit actor and where it was hit. + */ struct Results { Actor actor; ///< The hit actor. @@ -113,15 +120,18 @@ struct Results }; /** - * Definition of a hit-test function to use in HitTest() method to check if the actor is hittable (e.g. touchable or focusable). + * @brief Definition of a hit-test function to use in HitTest() method to check if the actor is hittable (e.g. touchable or focusable). + * * @return true, if the actor is hittable, false otherwise. */ typedef bool (*HitTestFunction)(Actor actor, TraverseType type); /** - * Given screen coordinates, this method returns the hit actor & the local coordinates relative to - * the top-left (0.0f, 0.0f, 0.5f) of the actor. An actor is only hittable if the actor meets all the - * conditions defined by the given function (see HitTestAlgorithm). + * @brief Given screen coordinates, this method returns the hit actor & the local coordinates relative to + * the top-left (0.0f, 0.0f, 0.5f) of the actor. + * + * An actor is only hittable if the actor meets all the conditions + * defined by the given function (see HitTestAlgorithm). * * Typically, if an actor has a zero size or its world color is fully transparent, it should not be * hittable; and if an actor's visibility flag is unset, its children should not be hittable either. @@ -134,7 +144,8 @@ typedef bool (*HitTestFunction)(Actor actor, TraverseType type); void HitTest( Stage stage, const Vector2& screenCoordinates, Results& results, HitTestFunction func ); /** - * Hit test specific to a given RenderTask + * @brief Hit test specific to a given RenderTask. + * * @param[in] renderTask The render task for hit test * @param[in] screenCoordinates The screen coordinates. * @param[out] results The results of the hit-test. diff --git a/dali/public-api/events/mouse-wheel-event.h b/dali/public-api/events/mouse-wheel-event.h index 261d09b..c64fc7f 100644 --- a/dali/public-api/events/mouse-wheel-event.h +++ b/dali/public-api/events/mouse-wheel-event.h @@ -21,24 +21,27 @@ #include #include + namespace Dali DALI_IMPORT_API { /** - * The mouse wheel event structure is used to store a mouse wheel rolling, it facilitates + * @brief The mouse wheel event structure is used to store a mouse wheel rolling, it facilitates * processing of the mouse wheel rolling and passing to other libraries like Toolkit. + * * There is a key modifier which relates to keys like alt, shift and control functions are * supplied to check if they have been pressed when the mouse wheel is being rolled. */ struct MouseWheelEvent { /** - * Default constructor + * @brief Default constructor. */ MouseWheelEvent(); /** - * Constructor + * @brief Constructor. + * * @param[in] direction The direction of mouse wheel rolling (0 = default vertical wheel, 1 = horizontal wheel) * @param[in] modifiers modifier keys pressed during the event (such as shift, alt and control) * @param[in] point The co-ordinates of the mouse cursor relative to the top-left of the screen. @@ -48,24 +51,27 @@ struct MouseWheelEvent MouseWheelEvent(int direction, unsigned int modifiers, Vector2 point, int z, unsigned int timeStamp); /** - * Destructor + * @brief Destructor. */ ~MouseWheelEvent(); /** - * Check to see if Shift key modifier has been supplied + * @brief Check to see if Shift key modifier has been supplied. + * * @return bool true if shift modifier */ bool IsShiftModifier() const; /** - * Check to see if Ctrl (control) key modifier has been supplied + * @brief Check to see if Ctrl (control) key modifier has been supplied. + * * @return bool true if ctrl modifier */ bool IsCtrlModifier() const; /** - * Check to see if Alt key modifier has been supplied + * @brief Check to see if Alt key modifier has been supplied. + * * @return bool true if alt modifier */ bool IsAltModifier() const; @@ -73,30 +79,31 @@ struct MouseWheelEvent // Data /** - * The direction in which the mouse wheel is being rolled + * @brief The direction in which the mouse wheel is being rolled. + * * 0 means the default vertical wheel, and 1 means horizontal wheel */ int direction; /** - * Modifier keys pressed during the event (such as shift, alt and control) + * @brief Modifier keys pressed during the event (such as shift, alt and control). */ unsigned int modifiers; /** - * The co-ordinates of the mouse cursor relative to the top-left of the screen + * @brief The co-ordinates of the mouse cursor relative to the top-left of the screen * when the wheel is being rolled. */ Vector2 point; /** - * The offset of the mouse wheel rolling, where positive value means rolling down - * and negative value means rolling up + * @brief The offset of the mouse wheel rolling, where positive value means rolling down + * and negative value means rolling up. */ int z; /** - * The time when the mouse wheel is being rolled. + * @brief The time when the mouse wheel is being rolled. */ unsigned int timeStamp; diff --git a/dali/public-api/geometry/mesh-data.h b/dali/public-api/geometry/mesh-data.h index bfdc6da..b56bf8d 100644 --- a/dali/public-api/geometry/mesh-data.h +++ b/dali/public-api/geometry/mesh-data.h @@ -17,6 +17,7 @@ // limitations under the License. // + // INTERNAL INCLUDES #include #include @@ -32,19 +33,39 @@ namespace Dali DALI_IMPORT_API class Matrix; /** - * The MeshData class encompasses all the data required to describe - * and render a 3D mesh. + * @brief The MeshData class encompasses all the data required to describe and + * render a 3D mesh. + * + * The mesh can have one of three geometry types: Points, Lines or Triangles. + * The Point type draws each vertex. The shader can control the point size. + * The Line type draws single pixel width lines between each specified vertex. + * The Triangles type draws solid color or texture between each specified + * vertex. * * When using the Points or Lines geometry type, normals aren't used. * - * If the HasColor property is set, the vertex color is used to draw - * the points, lines or faces, otherwise the material's diffuse color is + * If the HasColor property is set, the vertex color is used to draw the points, + * lines or triangles, otherwise the material's diffuse color or texture is * used. The material's diffuse alpha value is always used. * - * When using the Triangles geometry type, the normals are mutually - * exclusive with vertex color. This means that shading cannot be - * performed with vertex color. Instead, use material to color or - * texture the mesh. + * When using the Triangles geometry type, the normals are mutually exclusive + * with vertex color. This means that shading cannot be performed if vertex + * color is being used. + * + * It is possible to deform the mesh using skeletal deformation. To acheive + * this, a number of bones can be supplied during creation. These are named + * actors that can be anywhere in the actor tree. Each bone has an offset + * matrix. A vertex in the mesh can reference up to 4 bones in the bone + * container with an associated weighting. + * + * When the mesh is added to the scene graph, the node for each named actor is + * added to an internal container. Each Update frame after the node update pass, + * the node's world matrix is multiplied by the associated bone's offset matrix. + * When rendering the mesh, these transform matrices are multiplied by the view + * matrix, their inverse transforms calculated and passed onto the shaders. + * + * The mesh vertex shader then applies up to 4 weighted transforms to each + * vertex and vertex normal. */ class MeshData { @@ -53,43 +74,50 @@ public: struct Vertex; typedef std::vector VertexContainer; ///< Collection of vertices - typedef VertexContainer::iterator VertexIter; - typedef VertexContainer::const_iterator VertexConstIter; + typedef VertexContainer::iterator VertexIter; ///< Iterator for @ref Dali::MeshData::VertexContainer + typedef VertexContainer::const_iterator VertexConstIter; ///< Const iterator for @ref Dali::MeshData::VertexContainer typedef unsigned short FaceIndex; ///< index of one point of a polygonal face typedef std::vector FaceIndices; ///< Collection of FaceIndex items ( The span should match the geometry type: Lines - span is 2; Triangles - span is 3 ). - typedef FaceIndices::iterator FaceIndexIter; - typedef FaceIndices::const_iterator FaceIndexConstIter; + typedef FaceIndices::iterator FaceIndexIter; ///< Iterator for @ref Dali::MeshData::FaceIndices + typedef FaceIndices::const_iterator FaceIndexConstIter; ///< Const iterator for @ref Dali::MeshData::FaceIndices + /** + * @brief The type of geometry to draw + */ enum VertexGeometryType { - POINTS, - LINES, - TRIANGLES + POINTS, ///< Draw only points at each vertex + LINES, ///< Draw lines between specified vertices + TRIANGLES ///< Draw filled triangles between specified vertices }; public: // construction, destruction and initialisation /** - * Create a new mesh. + * @brief Create a new mesh. */ MeshData( ); /** - * Copy constructor. + * @brief Copy constructor. + * * @param[in] meshData object to copy */ explicit MeshData( const MeshData& meshData ); /** - * Assignment operator. + * @brief Assignment operator. + * * @param[in] rhs MeshData object to copy data from + * @return A reference to this */ MeshData& operator=(const MeshData& rhs); /** - * Sets the vertex coords, the face indices, the bones affecting this mesh and a default - * material + * @brief Sets the vertex coords, the face indices, the bones affecting this mesh and a default + * material. + * * @param[in] vertices The Vertex data (coordinates of each vertex) * @param[in] faceIndices The index into the vertices buffer for each corner of each triangular face. * @param[in] bones A container of Bones affecting this mesh. @@ -101,7 +129,8 @@ public: // construction, destruction and initialisation const Material material ); /** - * Set the vertex coords and end points of each line. + * @brief Set the vertex coords and end points of each line. + * * @param[in] vertices The vertex data (coords & color of each vertex) * @param[in] lineIndices A list of vertex indices for the start & end of each line. * @param[in] material A handle to a material object. @@ -111,7 +140,8 @@ public: // construction, destruction and initialisation const Material material ); /** - * Set the vertex coords for each point. + * @brief Set the vertex coords for each point. + * * @param[in] vertices The vertex data (coords & color of each vertex) * @param[in] material A handle to a material object. */ @@ -119,19 +149,22 @@ public: // construction, destruction and initialisation const Material material ); /** - * Set the vertex coords for each point. + * @brief Set the vertex coords for each point. + * * @param[in] vertices The vertex data (coords & color of each vertex) */ void SetVertices( const VertexContainer& vertices ); /** - * Sets the face indices + * @brief Sets the face indices. + * * @param[in] faceIndices The index into the vertices buffer for each corner of each triangular face.or for the start and end of each line. */ void SetFaceIndices( const FaceIndices& faceIndices ); /** - * Add the mesh to the bounding volume + * @brief Add the mesh to the bounding volume. + * * Expands a bounding volume to include the mesh * @param[in,out] min Lower bounds * @param[in,out] max Upper bounds @@ -140,52 +173,59 @@ public: // construction, destruction and initialisation void AddToBoundingVolume(Vector4& min, Vector4& max, const Matrix& transform); /** - * Get the geometry type. A mesh defaults to triangles if no data has been set. + * @brief Get the geometry type. + * + * A mesh defaults to triangles if no data has been set. * @return the geometry type; */ VertexGeometryType GetVertexGeometryType() const; /** - * Get the number of vertices + * @brief Get the number of vertices. + * * @return The number of vertices */ size_t GetVertexCount() const; /** - * Get the vertex array + * @brief Get the vertex array. * * @return The vertex array */ const VertexContainer& GetVertices() const; /** - * Get the number of points, lines or faces (note this is not the same as the number of face indices!) + * @brief Get the number of points, lines or faces (note this is not the same as the number of face indices!). + * * depending on the geometry type; * @return Number of points, lines or faces */ size_t GetFaceCount() const; /** - * Get the face index array + * @brief Get the face index array. * * @return The face index array */ const FaceIndices& GetFaces() const; /** - * Sets if the mesh has texture coordinates + * @brief Sets if the mesh has texture coordinates. + * * @param hasTexCoords - True if the mesh has texture coordinates. */ void SetHasTextureCoords(bool hasTexCoords); /** - * Checks if the mesh is textured. + * @brief Checks if the mesh is textured. + * * @return true if the mesh is texture mapped. */ bool HasTextureCoords() const; /** - * Sets if the mesh has normals. + * @brief Sets if the mesh has normals. + * * Mutually exclusive with HasColor. Setting this to true will force the * HasColor property to be set to false. * @param hasNormals - True if the mesh has normals @@ -193,13 +233,15 @@ public: // construction, destruction and initialisation void SetHasNormals(bool hasNormals); /** - * Checks if the mesh has normals + * @brief Checks if the mesh has normals. + * * @return true if the mesh contains normals. */ bool HasNormals() const; /** - * Sets if the mesh vertices have color + * @brief Sets if the mesh vertices have color. + * * Mutually exclusive with HasNormals. Setting this to true will force the * HasNormals property to be set to false. * @param hasColor - True if the mesh vertices have color. @@ -207,88 +249,96 @@ public: // construction, destruction and initialisation void SetHasColor(bool hasColor); /** - * Checks if the mesh vertices have color + * @brief Checks if the mesh vertices have color. + * * @return true if the mesh contains colored vertices. */ bool HasColor() const; /** - * Get the original material associated with this mesh. + * @brief Get the original material associated with this mesh. + * * @return Handle to the material */ Material GetMaterial() const; /** - * Set the default material associated with this mesh. + * @brief Set the default material associated with this mesh. */ void SetMaterial( Material material ); /** - * Get the number of bones affecting this mesh + * @brief Get the number of bones affecting this mesh. * * @return The number of bones affecting this mesh */ size_t GetBoneCount() const; /** - * Does this mesh have bones? + * @brief Does this mesh have bones?. + * * @return true if this mesh has bones. */ bool HasBones() const; /** - * Get the bone container + * @brief Get the bone container. + * * @return the bones */ const BoneContainer& GetBones() const; /** - * Get the lower bounds of the bounding box containing the vertices. + * @brief Get the lower bounds of the bounding box containing the vertices. + * * @return the lower bounds */ const Vector4& GetBoundingBoxMin() const; /** - * Set the lower bounds of the bounding box containing the vertices. + * @brief Set the lower bounds of the bounding box containing the vertices. + * * @param bounds The lower bounds */ void SetBoundingBoxMin(const Vector4& bounds); /** - * Get the upper bounds of the bounding box containing the vertices. + * @brief Get the upper bounds of the bounding box containing the vertices. + * * @return the upper bounds */ const Vector4& GetBoundingBoxMax() const; /** - * Set the upper bounds of the bounding box containing the vertices. + * @brief Set the upper bounds of the bounding box containing the vertices. + * * @param bounds The upper bounds */ void SetBoundingBoxMax(const Vector4& bounds); /** - * Destructor + * @brief Destructor. */ ~MeshData(); private: - VertexContainer mVertices; - FaceIndices mFaces; - VertexGeometryType mGeometryType; - bool mUseTextureCoords; - bool mUseNormals; - bool mUseColor; - BoneContainer mBones; + VertexContainer mVertices; ///< The vertex data + FaceIndices mFaces; ///< Indices of triangle faces or line terminators + VertexGeometryType mGeometryType; ///< The type of geometry to draw + bool mUseTextureCoords; ///< Whether the vertex data contains texture coords + bool mUseNormals; ///< Whether the vertex data contains normals + bool mUseColor; ///< Whether the vertex data contains vertex color + BoneContainer mBones; ///< Bones for skeletal deformation - Material mMaterial; + Material mMaterial; ///< Material of the mesh - Vector4 mMin; - Vector4 mMax; + Vector4 mMin; ///< The lower bounds of the bounding box + Vector4 mMax; ///< The upper bounds of the bounding box }; // class MeshData /** - * A vertex within a mesh, with the corresponding texture coordinate, normal and up to 4 bone influences. + * @brief A vertex within a mesh, with the corresponding texture coordinate, normal and up to 4 bone influences. */ struct MeshData::Vertex { @@ -301,10 +351,17 @@ struct MeshData::Vertex { } - Vertex( const Vector3& position, const Vector2& textureCoordinates, const Vector3& normals ) + /** + * @brief Constructor. + * + * @param[in] position The vertex position + * @param[in] textureCoordinates The texture coordinates + * @param[in] normal The surface normal + */ + Vertex( const Vector3& position, const Vector2& textureCoordinates, const Vector3& normal ) : x(position.x), y(position.y), z(position.z), u(textureCoordinates.x), v(textureCoordinates.y), - nX(normals.x), nY(normals.y), nZ(normals.z) + nX(normal.x), nY(normal.y), nZ(normal.z) { } @@ -334,10 +391,14 @@ struct MeshData::Vertex float vertexB; }; - // Bone indices specify which bones have an influence over the vertex (if any). + /** + * @brief Bone indices specify which bones have an influence over the vertex (if any). + */ unsigned char boneIndices[MAX_BONE_INFLUENCE]; - // Bone weights determine the strength of the influence of each bone. + /** + * @brief Bone weights determine the strength of the influence of each bone. + */ float boneWeights[MAX_BONE_INFLUENCE]; }; diff --git a/dali/public-api/geometry/mesh.h b/dali/public-api/geometry/mesh.h index 4892e52..76d4a4b 100644 --- a/dali/public-api/geometry/mesh.h +++ b/dali/public-api/geometry/mesh.h @@ -17,6 +17,7 @@ // limitations under the License. // + // INTERNAL INCLUDES #include #include @@ -35,28 +36,31 @@ class Mesh; } /** - * A Mesh holds a MeshData object supplied by the application writer. It is used to - * tell the Scene Graph if the mesh data has changed. + * @brief A Mesh holds a MeshData object supplied by the application writer. + * + * It is used to tell the Scene Graph if the mesh data has changed. */ class Mesh : public BaseHandle { public: /** - * Create an initialized Mesh. + * @brief Create an initialized Mesh. + * * @param[in] meshData The mesh data with which to initialize the handle * @return A handle to a newly allocated Dali resource. */ static Mesh New( const MeshData& meshData ); /** - * Create an uninitialized Mesh; this can be initialized with Mesh::New() + * @brief Create an uninitialized Mesh; this can be initialized with Mesh::New(). + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ Mesh(); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~Mesh(); @@ -66,7 +70,8 @@ public: using BaseHandle::operator=; /** - * Create an initialized plane aligned on the XY axis. + * @brief Create an initialized plane aligned on the XY axis. + * * @param[in] width The width of the plane * @param[in] height The height of the plane * @param[in] xSteps The number of vertices along the X axis @@ -81,15 +86,19 @@ public: const Rect& textureCoordinates = Rect(0.0f, 0.0f, 1.0f, 1.0f)); /** - * Downcast an Object handle to Mesh handle. If handle points to a Mesh object the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to Mesh handle. + * + * If handle points to a Mesh object the downcast produces valid + * handle. If not the returned handle is left uninitialized. + * * @param[in] handle to An object * @return handle to an Mesh object or an uninitialized handle */ static Mesh DownCast( BaseHandle handle ); /** - * Tell Dali to update it's internal meshes from the changed mesh data. + * @brief Tell Dali to update it's internal meshes from the changed mesh data. + * * @param[in] meshData */ void UpdateMeshData( const MeshData& meshData ); @@ -97,13 +106,13 @@ public: public: // Not intended for application developers /** - * This constructor is used by Dali New() methods + * @brief This constructor is used by Dali New() methods. + * * @param [in] mesh A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL Mesh(Internal::Mesh* mesh); }; - } // namespace Dali #endif // __DALI_MESH_H__ diff --git a/dali/public-api/geometry/spline.h b/dali/public-api/geometry/spline.h index 5e84bf6..c3922e1 100644 --- a/dali/public-api/geometry/spline.h +++ b/dali/public-api/geometry/spline.h @@ -17,6 +17,7 @@ // limitations under the License. // + // INTERNAL INCLUDES #include #include @@ -29,7 +30,7 @@ class Matrix; struct Vector3; /** - * The Spline class is used to interpolate through a series of points + * @brief The Spline class is used to interpolate through a series of points * (or knots) which are open (the end points do not connect). * * In Hermite splines, each knot has an in-tangent and an @@ -49,58 +50,64 @@ class Spline { public: /** - * Constructor + * @brief Constructor. */ Spline(); /** - * Destructor + * @brief Destructor. */ virtual ~Spline(); /** - * Add a knot to the spline + * @brief Add a knot to the spline. + * * @param[in] knot - the point or knot to add. */ void AddKnot(Vector3 knot); /** - * Get the knot at the given index + * @brief Get the knot at the given index. + * * @param[in] knotIndex the index of the knot * @return the knot vector */ Vector3 GetKnot(size_t knotIndex); /** - * Get the in tangent (or in control point) at the given index + * @brief Get the in tangent (or in control point) at the given index. + * * @param[in] knotIndex the index of the knot * @return the in tangent (or in control point) */ Vector3 GetInTangent(size_t knotIndex); /** - * Get the out tangent (or out control point) at the given index + * @brief Get the out tangent (or out control point) at the given index. + * * @param[in] knotIndex the index of the knot * @return the out tangent (or out control point) */ Vector3 GetOutTangent(size_t knotIndex); /** - * Set an in-tangent for the given knot. + * @brief Set an in-tangent for the given knot. + * * @param[in] knotIndex - the index of the knot * @param[in] inTangent - The in tangent or control point, depending on the spline type */ void SetInTangent(size_t knotIndex, Vector3 inTangent); /** - * Set an out-tangent for the given knot. + * @brief Set an out-tangent for the given knot. + * * @param[in] knotIndex - the index of the knot * @param[in] outTangent - The out tangent or control point, depending on the spline type */ void SetOutTangent(size_t knotIndex, Vector3 outTangent); /** - * For the given set of knot points, generate control points which result in a smooth join between the splines of each segment. + * @brief For the given set of knot points, generate control points which result in a smooth join between the splines of each segment. * * The generating algorithm is as follows: * For a given knot point K[N], find the vector that bisects K[N-1],[N] and [N],[N+1]. @@ -117,13 +124,18 @@ public: void GenerateControlPoints(float curvature=0.25f); /** - * Get the number of segments. This is the number of points - 1, or zero if there are fewer than 2 points. + * @brief Get the number of segments. + * + * This is the number of points - 1, or zero if there are fewer than 2 points. + * @return the number of segments */ unsigned int GetNumberOfSegments() const; /** - * Given an alpha value 0.0-1.0, return the associated point on the entire - * spline. The alpha value is split into each segment equally, so doesn't give a + * @brief Given an alpha value 0.0-1.0, return the associated point on the entire + * spline. + * + * The alpha value is split into each segment equally, so doesn't give a * constant speed along the spline. An alpha value of 0.0 returns the first knot * and an alpha value of 1.0 returns the last knot. * @@ -133,10 +145,12 @@ public: const Vector3 GetPoint(float alpha) const; /** - * Given a parameter 0.0 - 1.0, return the associated point on the spline given the - * relevant segment. Note, the parameter does not correspond to an axis, neither - * is it necessarily equally spaced along the curve. If the parameter is 0.0 or - * 1.0, then the first or second knot point is returned. + * @brief Given a parameter 0.0 - 1.0, return the associated point + * on the spline given the relevant segment. + * + * Note, the parameter does not correspond to an axis, neither is it + * necessarily equally spaced along the curve. If the parameter is + * 0.0 or 1.0, then the first or second knot point is returned. * * @param[in] segmentIndex the segment of the spline to interpolation. * @param[in] parameter the parameter to use in the parametric formula @@ -145,17 +159,22 @@ public: const Vector3 GetPoint(unsigned int segmentIndex, float parameter) const; /** - * Given a value X on the spline (between the first and last knot inclusively), + * @brief Given a value X on the spline (between the first and last knot inclusively), * calculate the corresponding Y value. Requires that there is only 1 Y per X. + * + * @param[in] x The X + * @return the Y value */ const float GetYFromMonotonicX(float x) const; /** - * For a 2 dimensional curve (z=0), given a parameter 0.0 - 1.0, return the - * associated Y value on the spline given the relevant segment. Note, the - * parameter does not correspond to an axis, neither is it necessarily equally - * spaced along the curve. If the parameter is 0.0 or 1.0, then the first or - * second knot point's Y value is returned. + * @brief For a 2 dimensional curve (z=0), given a parameter 0.0 - 1.0, return the + * associated Y value on the spline given the relevant segment. + * + * Note, the parameter does not correspond to an axis, neither is it + * necessarily equally spaced along the curve. If the parameter is + * 0.0 or 1.0, then the first or second knot point's Y value is + * returned. * * @param[in] segmentIndex - the segment of the spline to interpolation. * @param[in] parameter - the parameter to use in the parametric formula @@ -166,8 +185,9 @@ public: private: /** - * FindSegment searches through the control points to find the appropriate + * @brief FindSegment searches through the control points to find the appropriate * segment. + * * @param[in] x - the X value to search for * @param[out] segmentIndex - the returned segment index * @return True if the segment was found. @@ -175,8 +195,10 @@ private: const bool FindSegment(float x, int& segmentIndex) const; /** - * Given two knots and control points, interpolate to find the - * parameter that will give the required X value. Requires that X is monotonic. + * @brief Given two knots and control points, interpolate to find the + * parameter that will give the required X value. + * + * Requires that X is monotonic. * * @param[in] atX the X value to search for * @param[in] P0_X the starting knot's X @@ -188,17 +210,15 @@ private: const float ApproximateCubicBezierParameter (float atX, float P0_X, float C0_X, float C1_X, float P1_X ) const; private: - std::vector mKnots; - std::vector mOutTangents; - std::vector mInTangents; + std::vector mKnots; ///< The set of knot points + std::vector mOutTangents; ///< The set of out tangents (matching to mKnots) + std::vector mInTangents; ///< The set of in tangents (matching to mKnots) - Matrix mBasis; + Matrix mBasis; ///< The basis matrix to use - static const float BezierBasisA[]; + static const float BezierBasisA[]; ///< The basis matrix for Bezier splines }; - - -} +} //namespace Dali #endif //__DALI_SPLINE_H__ diff --git a/dali/public-api/images/distance-field.h b/dali/public-api/images/distance-field.h index ef6a9c9..a3e7dbf 100644 --- a/dali/public-api/images/distance-field.h +++ b/dali/public-api/images/distance-field.h @@ -17,6 +17,7 @@ // limitations under the License. // + // INTERNAL INCLUDES #include @@ -26,7 +27,8 @@ namespace Dali DALI_IMPORT_API struct Vector2; /** - * Generate a distance field map from a source image. + * @brief Generate a distance field map from a source image. + * * @param[in] imagePixels A pointer to a buffer containing the source image * @param[in] imageSize The size, width and height, of the source image * @param[out] distanceMap A pointer to a buffer to receive the calculated distance field map. diff --git a/dali/public-api/modeling/bone.h b/dali/public-api/modeling/bone.h index c6631a5..787512a 100644 --- a/dali/public-api/modeling/bone.h +++ b/dali/public-api/modeling/bone.h @@ -17,6 +17,7 @@ // limitations under the License. // + // INTERNAL INCLUDES #include #include @@ -27,51 +28,57 @@ namespace Dali DALI_IMPORT_API class Matrix; class Bone; -typedef std::vector< Bone > BoneContainer; -typedef BoneContainer::iterator BoneIter; -typedef BoneContainer::const_iterator BoneConstIter; +typedef std::vector< Bone > BoneContainer; ///< Container for bones +typedef BoneContainer::iterator BoneIter; ///< @ref Dali::BoneContainer iterator +typedef BoneContainer::const_iterator BoneConstIter; ///< @ref Dali::BoneContainer const iterator /** - * A single bone in a mesh + * @brief A single bone in a mesh. + * + * A Bone is a named actor that can be used to deform a mesh. @see Dali::MeshData for more + * information. */ class Bone { public: /** - * Default constructor + * @brief Default constructor. */ Bone (); /** - * Constructor + * @brief Constructor. + * * @param name of the bone * @param offsetMatrix for the bone */ Bone( const std::string& name, const Matrix& offsetMatrix ); /** - * Destructor. + * @brief Destructor. */ ~Bone(); /** - * Copy constructor + * @brief Copy constructor. */ Bone( const Bone& rhs ); /** - * Assignment operator + * @brief Assignment operator. */ Bone& operator=(const Bone& rhs); /** - * Get name + * @brief Get name. + * * @return returns the name of the bone */ const std::string& GetName() const; /** - * Get offset matrix + * @brief Get offset matrix. + * * @return returns the offset matrix for this bone */ const Matrix& GetOffsetMatrix() const; diff --git a/dali/public-api/modeling/entity-animator-map.h b/dali/public-api/modeling/entity-animator-map.h index 420dde8..68e5a9d 100644 --- a/dali/public-api/modeling/entity-animator-map.h +++ b/dali/public-api/modeling/entity-animator-map.h @@ -17,6 +17,7 @@ // limitations under the License. // + // INTERNAL INCLUDES #include #include @@ -27,30 +28,30 @@ namespace Dali DALI_IMPORT_API class Entity; class EntityAnimatorMap; -typedef std::vector EntityAnimatorMapContainer; -typedef EntityAnimatorMapContainer::const_iterator EntityAnimatorMapIter; +typedef std::vector EntityAnimatorMapContainer; ///< Container of Entity - Animator mappings +typedef EntityAnimatorMapContainer::const_iterator EntityAnimatorMapIter; ///< Iterator for @ref Dali::EntityAnimatorMapContainer /** - * The entity animator map class holds the keyframe channels associated - * with a named entity. - * (It only holds key frame data, it cannot be used by the animation system) + * @brief The entity animator map class is a mapping from an entity name to raw animation + * data for that entity, stored in 3 KeyFrames for position, scale and rotation. */ class EntityAnimatorMap { public: /** - * Constructor + * @brief Constructor. */ EntityAnimatorMap(const std::string& name); /** - * Destructor + * @brief Destructor. */ virtual ~EntityAnimatorMap(); /** - * Set the entity name + * @brief Set the entity name. + * * @param[in] name - the entity name */ void SetEntityName(const std::string& name) @@ -59,7 +60,8 @@ public: } /** - * Get the entity name + * @brief Get the entity name. + * * @return the name of the entity to which this animator applies */ const std::string& GetEntityName() const @@ -68,7 +70,8 @@ public: } /** - * Set the animated entity + * @brief Set the animated entity. + * * @param[in] animatedEntity The animated entity */ void SetAnimatedEntity(Entity animatedEntity) @@ -77,7 +80,8 @@ public: } /** - * Get the animated entity. + * @brief Get the animated entity. + * * @return the animated entity */ Entity GetAnimatedEntity(void) @@ -85,57 +89,88 @@ public: return mAnimatedEntity; } + /** + * @brief Set the key frames for animating the entity position. + * + * @param[in] keyFrames The keyframe data + */ void SetPositionKeyFrames(KeyFrames keyFrames) { mPositionKeyFrames = keyFrames; } + /** + * @brief Set the key frames for animating the entity scale. + * + * @param[in] keyFrames The keyframe data + */ void SetScaleKeyFrames(KeyFrames keyFrames) { mScaleKeyFrames = keyFrames; } + /** + * @brief Set the key frames for animating the entity rotation. + * + * @param[in] keyFrames The keyframe data + */ void SetRotationKeyFrames(KeyFrames keyFrames) { mRotationKeyFrames = keyFrames; } - + /** + * @brief Get the keyframes for animating the entity position. + * + * @return A handle to the keyframes + */ KeyFrames GetPositionKeyFrames() const { return mPositionKeyFrames; } + /** + * @brief Get the keyframes for animating the entity scale. + * + * @return A handle to the keyframes + */ KeyFrames GetScaleKeyFrames() const { return mScaleKeyFrames; } + /** + * @brief Get the keyframes for animating the entity rotation. + * + * @return A handle to the keyframes + */ KeyFrames GetRotationKeyFrames() const { return mRotationKeyFrames; } /** - * Set the duration of the animation on this entity. + * @brief Set the duration of the animation on this entity. + * * @param[in] duration - the duration in seconds. */ void SetDuration(float duration) { mDuration = duration; } /** - * Get the duration of the animation on this entity. + * @brief Get the duration of the animation on this entity. + * * @return the duration in seconds */ const float GetDuration() const { return mDuration; } private: - std::string mEntityName; - Entity mAnimatedEntity; - float mDuration; + std::string mEntityName; ///< The entity name + Entity mAnimatedEntity; ///< Unused + float mDuration; ///< Duration of this animator - KeyFrames mPositionKeyFrames; - KeyFrames mScaleKeyFrames; - KeyFrames mRotationKeyFrames; + KeyFrames mPositionKeyFrames; ///< Position key frames (may be null) + KeyFrames mScaleKeyFrames; ///< Scale key frames (may be null) + KeyFrames mRotationKeyFrames; ///< Rotation key frames (may be null) }; diff --git a/dali/public-api/modeling/entity.h b/dali/public-api/modeling/entity.h index 3cb2c70..ebc99a2 100644 --- a/dali/public-api/modeling/entity.h +++ b/dali/public-api/modeling/entity.h @@ -17,6 +17,7 @@ // limitations under the License. // + // INTERNAL INCLUDES #include @@ -37,48 +38,58 @@ class Entity; typedef std::vector EntityContainer; ///< Container of Entity handles typedef EntityContainer::iterator EntityIter; ///< iterator for Entity container typedef EntityContainer::const_iterator EntityConstIter; ///< const_iterator for Entity container -typedef std::vector EntityMeshIndices; +typedef std::vector EntityMeshIndices; ///< Container to hold indexes of meshes this entity uses in the associated Dali::Model. /** - * A 3D model comprises a tree of named entities. Each entity has a - * transform, regardless of type. It can contain zero or more meshes. - * The entity names are used for cross referencing, e.g. from animations - * or from bone structures. + * @brief A 3D model comprises a tree of named entities. Each entity has a + * transform, regardless of type. + * + * It can contain zero or more meshes. The entity names are used for + * cross referencing, e.g. from animations or from bone structures. */ class Entity : public BaseHandle { public: + /** + * @brief The entity type + */ enum EntityType { - OBJECT, - CAMERA, - LIGHT, + OBJECT, ///< A generic entity + CAMERA, ///< The entity represents a camera + LIGHT, ///< The entity represents a light }; /** - * Create an uninitialized Entity; this can be initialized with Entity::New(). + * @brief Create an uninitialized Entity; this can be initialized with Entity::New(). + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ Entity(); /** - * Create an initialized handle. + * @brief Create an initialized handle. + * * @param[in] name The name of the entity * @return a handle to a newly allocated Dali resource */ static Entity New(const std::string name); /** - * Downcast an Object handle to Entity handle. If handle points to a Entity object the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to Entity handle. + * + * If handle points to a Entity object the downcast produces valid + * handle. If not the returned handle is left uninitialized. + * * @param[in] handle to An object * @return handle to a Entity object or an uninitialized handle */ static Entity DownCast( BaseHandle handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~Entity(); @@ -89,14 +100,17 @@ public: using BaseHandle::operator=; /** - * Find an entity by name. The search includes this entity and it's children. + * @brief Find an entity by name. + * + * The search includes this entity and it's children. * @param[in] name The search name. * @return A handle to the searched entity, or an uninitialized handle if not found. */ Entity Find(const std::string& name) const; /** - * Set the name of the entity. + * @brief Set the name of the entity. + * * @param[in] name The name for the entity. */ void SetName(const char* name); @@ -107,69 +121,81 @@ public: void SetName(const std::string& name); /** - * Get the name of the entity. + * @brief Get the name of the entity. + * * @return The name of the entity. */ const std::string& GetName() const; /** - * Set the entity type. + * @brief Set the entity type. + * * @param[in] type The entity's type, a member of the EntityType enumeration. */ void SetType(const EntityType type); /** - * Get the entity's type. + * @brief Get the entity's type. + * * @return The entity's type, a member of the EntityType enumeration. */ EntityType GetType() const; /** - * Set the transform matrix. + * @brief Set the transform matrix. + * * @param[in] matrix The transform matrix */ void SetTransformMatrix(Matrix& matrix); /** - * Returns a reference to the transform matrix + * @brief Returns a reference to the transform matrix. + * * @return The transform matrix */ const Matrix& GetTransformMatrix() const; /** - * Checks if the entity has children + * @brief Checks if the entity has children. + * * @return true if the entity has children, otherwise false. */ bool HasChildren() const; /** - * Get the number of children. + * @brief Get the number of children. + * * @return The number of children. */ int NumberOfChildren() const; /** - * Get the list of children. + * @brief Get the list of children. + * * @return A reference to the list of children. */ const EntityContainer& GetChildren() const; /** - * Add an entity to the end of the child list. Sets the child's parent. + * @brief Add an entity to the end of the child list. + * + * Sets the child's parent. * @param[in] child A handle to a child Entity. */ void Add(Entity child); /** - * Get the entity's parent. + * @brief Get the entity's parent. + * * @return A pointer to the entity's parent. */ Entity GetParent() const; /** - * Change the size of storage allocated to the mesh index list. This - * may be greater than the number of indices stored as returned by - * NumberOfMeshes. + * @brief Change the size of storage allocated to the mesh index list. + * + * This may be greater than the number of indices stored as returned + * by NumberOfMeshes. * * @param[in] capacity The new size of the storage allocated to the mesh * index list. @@ -177,73 +203,84 @@ public: void SetMeshCapacity(unsigned int capacity); /** - * Add a mesh to the entity. + * @brief Add a mesh to the entity. + * * @param[in] meshIdx The mesh index into the model data's list of meshes */ void AddMeshIndex(unsigned int meshIdx); /** - * Checks if the entity references any meshes. + * @brief Checks if the entity references any meshes. + * * @return true if the entity refers to 1 or more meshes, otherwise false. */ bool HasMeshes() const; /** - * Get the number of meshes referenced by this entity. + * @brief Get the number of meshes referenced by this entity. + * * @return The number of meshes referenced by this entity. */ int NumberOfMeshes() const; /** - * Returns a mesh in the model's mesh array. + * @brief Returns a mesh in the model's mesh array. + * * @param[in] meshIndex The index of the mesh within the entity. * @return The index of the mesh in the model's mesh array. */ unsigned int GetMeshByIndex(unsigned int meshIndex) const; /** - * Get the entity's list of mesh indices. + * @brief Get the entity's list of mesh indices. + * * @return The entity's list of mesh indices. */ const EntityMeshIndices& GetMeshes() const; /** - * Expand the bounding volume to include the child's bounding volume. + * @brief Expand the bounding volume to include the child's bounding volume. + * * @param[in] child A handle to the child. */ void AddToBounds(Entity child); /** - * Expand the entity bounding box to include the new boundaries. + * @brief Expand the entity bounding box to include the new boundaries. + * * @param[in] lowerBounds to extend the entity bounds * @param[in] upperBounds to extend the entity bounds */ void AddToBounds( const Vector3& lowerBounds, const Vector3& upperBounds ); /** - * Get the lower bounds of the bounding volume which contains all vertices in all meshes + * @brief Get the lower bounds of the bounding volume which contains all vertices in all meshes * referenced by this entity. + * * @return A vector describing the lower bounds. */ const Vector3& GetLowerBounds() const; /** - * Set the lower bounds of the bounding volume which contains all vertices in all meshes + * @brief Set the lower bounds of the bounding volume which contains all vertices in all meshes * referenced by this entity. + * * @param[in] lowerBounds of the entity. */ void SetLowerBounds( const Vector3& lowerBounds ); /** - * Get the upper bounds of the bounding volume which contains all vertices in all meshes + * @brief Get the upper bounds of the bounding volume which contains all vertices in all meshes * referenced by this entity. + * * @return A vector describing the upper bounds. */ const Vector3& GetUpperBounds() const; /** - * Set the upper bounds of the bounding volume which contains all vertices in all meshes + * @brief Set the upper bounds of the bounding volume which contains all vertices in all meshes * referenced by this entity. + * * @param[in] upperBounds of the entity. */ void SetUpperBounds( const Vector3& upperBounds ); @@ -251,7 +288,7 @@ public: public: // Not intended for application developers /** - * This constructor is used by Dali New() methods + * @brief This constructor is used by Dali New() methods. * @param [in] entity A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL Entity(Internal::Entity* entity); diff --git a/dali/public-api/modeling/model-animation-map.h b/dali/public-api/modeling/model-animation-map.h index 76e95ea..0874135 100644 --- a/dali/public-api/modeling/model-animation-map.h +++ b/dali/public-api/modeling/model-animation-map.h @@ -17,6 +17,7 @@ // limitations under the License. // + // INTERNAL INCLUDES #include @@ -24,16 +25,16 @@ namespace Dali DALI_IMPORT_API { struct ModelAnimationMap; -typedef std::vector ModelAnimationMapContainer; +typedef std::vector ModelAnimationMapContainer; ///< Container of model animations /** - * ModelAnimationMap holds a set of entity animators for a given named animation, - * along with animation properties such as duration, repeats, etc. + * @brief ModelAnimationMap maps an animation name to a set of entity animators and animation + * properties such as duration and repeats. */ struct ModelAnimationMap { /** - * Destructor. + * @brief Destructor. **/ ModelAnimationMap() : duration(0.0f), @@ -41,13 +42,12 @@ struct ModelAnimationMap { } - std::string name; - EntityAnimatorMapContainer animators; - float duration; - int repeats; + std::string name; ///< Name of the animation + EntityAnimatorMapContainer animators; ///< Set of entity - animation mappings + float duration; ///< Duration of the animation + int repeats; ///< Number of times the animation should be repeated }; } // namespace Dali #endif // __DALI_MODEL_ANIMATION_MAP_H__ - diff --git a/dali/public-api/modeling/model-data.h b/dali/public-api/modeling/model-data.h index c6a0697..25d59d5 100644 --- a/dali/public-api/modeling/model-data.h +++ b/dali/public-api/modeling/model-data.h @@ -17,6 +17,7 @@ // limitations under the License. // + // EXTERNAL INCLUDES #include @@ -38,36 +39,42 @@ class ModelData; } /** - * Encapsulates a Dali 3D model/scene. This is usually generated by an - * external model loader (and is also used internally with the default - * model loader). + * @brief Encapsulates a Dali 3D model/scene. + * + * This is usually generated by an external model loader (and is also + * used internally with the default model loader). */ class ModelData : public BaseHandle { public: /** - * Constructs an uninitialized handle. + * @brief Constructs an uninitialized handle. */ ModelData(); /** - * Create an initialized ModelData. + * @brief Create an initialized ModelData. + * * @param[in] name The name of the model. * @return A handle to a newly allocated Dali resource. */ static ModelData New(const std::string& name); /** - * Downcast an Object handle to ModelData handle. If handle points to a ModelData object the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to ModelData handle. + * + * If handle points to a ModelData object the downcast produces + * valid handle. If not the returned handle is left uninitialized. + * * @param[in] handle to An object * @return handle to a ModelData object or an uninitialized handle */ static ModelData DownCast( BaseHandle handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~ModelData(); @@ -78,76 +85,88 @@ public: using BaseHandle::operator=; /** - * Returns the name of the model + * @brief Returns the name of the model. + * * @return The model name */ const std::string& GetName() const; /** - * Set the root Entity of the model. + * @brief Set the root Entity of the model. + * * @param root A handle to the root entity */ void SetRootEntity(Entity root); /** - * Get the root Entity of the model. + * @brief Get the root Entity of the model. + * * @return The root entity */ Entity GetRootEntity() const; /** - * Add a mesh to the model. + * @brief Add a mesh to the model. + * * @param mesh The mesh data to add. */ void AddMesh(MeshData& mesh); /** - * Get a mesh by index. + * @brief Get a mesh by index. + * * @param[in] index The zero based index to a mesh * @return The mesh. */ const MeshData& GetMesh(unsigned int index) const; /** - * Get a mesh by index. + * @brief Get a mesh by index. + * * @param[in] index The zero based index to a mesh * @return The mesh. */ MeshData& GetMesh(unsigned int index); /** - * Get Mesh count + * @brief Get Mesh count. + * * @returns number of meshes */ unsigned int NumberOfMeshes() const; /** - * Add material to the model + * @brief Add material to the model. + * * @param[in] material - the material to add to the model */ void AddMaterial(Material material); /** - * Get a material by index. + * @brief Get a material by index. + * * @param[in] index The index to a material * @return A handle to a material, or NULL. */ Material GetMaterial(unsigned int index) const; /** - * Get material count + * @brief Get material count. + * * @return The Number of materials */ unsigned int NumberOfMaterials() const; /** - * Get animation map container. + * @brief Get animation map container. + * * @return reference to the animation map container. */ ModelAnimationMapContainer& GetAnimationMapContainer(); /** - * Get an animation map from the model data. + * @brief Get an animation map from the model data. + * * @deprecated Use ModelActorFactory to generate animations * @param[in] index The index of the animation map. * @return a pointer to model animation map. @@ -155,7 +174,8 @@ public: const ModelAnimationMap* GetAnimationMap (unsigned int index) const; /** - * Get the animation for the given name. + * @brief Get the animation for the given name. + * * @deprecated Use ModelActorFactory to generate animations * @param[in] name The name of an animation map to search for. * @return a pointer to model animation map. @@ -163,7 +183,8 @@ public: const ModelAnimationMap* GetAnimationMap (const std::string& name) const; /** - * Find the index for the given animation name. + * @brief Find the index for the given animation name. + * * @param[in] name The name of the animation map to search for. * @param[out] index The index of the found map * @return true if the name was found, false otherwise. @@ -176,33 +197,38 @@ public: unsigned int NumberOfAnimationMaps() const; /** - * Add a light to the model + * @brief Add a light to the model. + * * @param light - the light to add to the model */ void AddLight(Light light); /** - * Get a light by index. + * @brief Get a light by index. + * * @param[in] index The zero based index to a light * @return A pointer to a light, or NULL. */ Light GetLight(unsigned int index) const; /** - * Get the number of lights contained in the model. + * @brief Get the number of lights contained in the model. + * * @return The number of lights contained in the model. */ unsigned int NumberOfLights() const; /** - * Read the model data from an open streambuf + * @brief Read the model data from an open streambuf. + * * @param[in] buf A streambuf opened for reading * @return true if data was read successfully. */ bool Read(std::streambuf& buf); /** - * Write the model data to an open streambuf + * @brief Write the model data to an open streambuf. + * * @param[in] buf A streambuf opened for writing * @return true if data was written successfully. */ @@ -210,7 +236,8 @@ public: public: // Not intended for application developers /** - * This constructor is used by Dali New() methods. + * @brief This constructor is used by Dali New() methods. + * * @param[in] modelData A pointer to a newly allocated modelData */ explicit DALI_INTERNAL ModelData(Internal::ModelData* modelData); diff --git a/dali/public-api/modeling/model.h b/dali/public-api/modeling/model.h index 979eb04..4f9cc5c 100644 --- a/dali/public-api/modeling/model.h +++ b/dali/public-api/modeling/model.h @@ -17,6 +17,7 @@ // limitations under the License. // + // EXTERNAL INCLUDES #include #include @@ -38,7 +39,7 @@ class Model; } /** - * A handle to 3D model data loaded as a resource. + * @brief A handle to 3D model data loaded as a resource. * * Use ModelActorFactory::BuildActorTree() to create actors from this model. * Use ModelActorFactory::BuildAnimation() to create animations on such actors. @@ -47,38 +48,47 @@ class Model : public BaseHandle { public: - typedef SignalV2 ModelSignalV2; - typedef SignalV2 ModelSaveSignalV2; + typedef SignalV2 ModelSignalV2; ///< Signal type + typedef SignalV2 ModelSaveSignalV2; ///< Signal type for saving models //Signal Names - static const char* const SIGNAL_MODEL_LOADING_FINISHED; - static const char* const SIGNAL_MODEL_SAVING_FINISHED; + static const char* const SIGNAL_MODEL_LOADING_FINISHED; ///< name "model-loading-finished" + static const char* const SIGNAL_MODEL_SAVING_FINISHED; ///< name "model-saving-finished" public: /** - * Create an uninitialized Model. This can be initialised with Model::New(). - * Calling member functions with an uninitialized Dali::Object is not allowed. + * @brief Create an uninitialized Model. + * + * This can be initialised with Model::New(). Calling member + * functions with an uninitialized Dali::Object is not allowed. */ Model(); /** - * Asynchronously load a model. Connect to SignalLoadingFinished() to determine - * when the model has finished loading. + * @brief Asynchronously load a model. + * + * Connect to SignalLoadingFinished() to determine when the model + * has finished loading. + * * @param [in] url The url of the model data. * @return A handle to a newly allocated Dali resource. */ static Model New(const std::string& url); /** - * Downcast an Object handle to Model handle. If handle points to a Model object the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to Model handle. + * + * If handle points to a Model object the downcast produces valid + * handle. If not the returned handle is left uninitialized. + * * @param[in] handle to An object * @return handle to an Model object or an uninitialized handle */ static Model DownCast( BaseHandle handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~Model(); @@ -89,7 +99,8 @@ public: using BaseHandle::operator=; /** - * Query whether the model data has loaded. + * @brief Query whether the model data has loaded. + * * The asynchronous loading begins when the Model object is created. * After the Model object is discarded, the model data will be released from memory. * @return The loading state, either Loading, Success or Failed. @@ -97,19 +108,22 @@ public: LoadingState GetLoadingState(); /** - * Emitted when the model data loads successfully or when the loading fails. + * @brief Emitted when the model data loads successfully or when the loading fails. + * * @return A signal object to Connect() with. */ ModelSignalV2& LoadingFinishedSignal(); /** - * Emitted when the model data save request completes. + * @brief Emitted when the model data save request completes. + * * @return A signal object to Connect() with. */ ModelSaveSignalV2& SavingFinishedSignal(); /** - * Get number of animations in the model. + * @brief Get number of animations in the model. + * * @pre The model has been loaded. * @return The number of animations encoded in the model, or zero if the model * hasn't finished loading. @@ -117,7 +131,8 @@ public: size_t NumberOfAnimations() const; /** - * Get the index of a named animation map in the model. + * @brief Get the index of a named animation map in the model. + * * @param[in] animationName The name of the animation to find * @param[out] animationIndex The index of the named animation if found * @return true if the animation was foud, false if not found. @@ -125,14 +140,16 @@ public: bool FindAnimation(const std::string& animationName, unsigned int& animationIndex); /** - * Write the model data to the standard output in textual format. + * @brief Write the model data to the standard output in textual format. + * * Note - will assert if any part of the model is on the scene graph (i.e. if * an actor has been created from this model) */ void Write(); /** - * Save a Dali representation of the mode data + * @brief Save a Dali representation of the mode data. + * * Used for faster loading on subsequent uses. * @param[in] url The resource url for the data */ @@ -141,7 +158,8 @@ public: public: // Not intended for application developers /** - * This constructor is used by Dali New() methods + * @brief This constructor is used by Dali New() methods. + * * @param [in] model A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL Model(Internal::Model* model); diff --git a/dali/public-api/object/type-info.h b/dali/public-api/object/type-info.h index d11c991..2ebe192 100644 --- a/dali/public-api/object/type-info.h +++ b/dali/public-api/object/type-info.h @@ -17,6 +17,7 @@ // limitations under the License. // + // INTERNAL INCLUDES #include @@ -32,18 +33,21 @@ namespace Internal DALI_INTERNAL }; /** - * TypeInfo class for instantiation of registered types and introspection of + * @brief TypeInfo class for instantiation of registered types and introspection of * their actions and signals. + * * See TypeRegistry for methods of type registration and TypeInfo retrieval. */ class TypeInfo : public BaseHandle { public: - typedef BaseHandle (*CreateFunction)(); - typedef bool (*ActionFunction)(BaseObject*, const std::string&, const std::vector&); + typedef BaseHandle (*CreateFunction)(); ///< Function signature for creating an instance of the associated object type. + + typedef bool (*ActionFunction)(BaseObject*, const std::string&, const std::vector&); ///< Function signature for creating scriptable actions /** - * Connects a callback function with the object's signals. + * @brief Connects a callback function with the object's signals. + * * @param[in] object The object providing the signal. * @param[in] tracker Used to disconnect the signal. * @param[in] signalName The signal to connect to. @@ -54,7 +58,9 @@ public: typedef bool (*SignalConnectorFunctionV2)(BaseObject* object, ConnectionTrackerInterface* tracker, const std::string& signalName, FunctorDelegate* functor); /** - * Callback to set an event-thread only property @see PropertyRegistration + * @brief Callback to set an event-thread only property. + * + * @see PropertyRegistration. * @param[in] object The object whose property should be set. * @param[in] index The index of the property being set. * @param[in] value The new value of the property for the object specified. @@ -62,22 +68,24 @@ public: typedef void (*SetPropertyFunction)( BaseObject* object, Property::Index index, const Property::Value& value ); /** - * Callback to get the value of an event-thread only property @see PropertyRegistration + * @brief Callback to get the value of an event-thread only property. + * + * @see PropertyRegistration. * @param[in] object The object whose property value is required. * @param[in] index The index of the property required. * @return The current value of the property for the object specified. */ typedef Property::Value (*GetPropertyFunction)( BaseObject* object, Property::Index index ); - typedef std::vector NameContainer; + typedef std::vector NameContainer; ///< Container of names for signals and actions /** - * Allows the creation of an empty TypeInfo handle. + * @brief Allows the creation of an empty TypeInfo handle. */ TypeInfo(); /** - * destructor. + * @brief destructor. */ virtual ~TypeInfo(); @@ -87,37 +95,43 @@ public: using BaseHandle::operator=; /** - * Retrieve the type name for this type + * @brief Retrieve the type name for this type. + * * @return string name */ const std::string& GetName(); /** - * Retrieve the base type name for this type + * @brief Retrieve the base type name for this type. + * * @return string of base name */ const std::string& GetBaseName(); /** - * Create an object from this type + * @brief Create an object from this type. + * * @return the BaseHandle for the newly created object */ BaseHandle CreateInstance(); /** - * Retrieve the creator function for this type + * @brief Retrieve the creator function for this type. + * * @return the creator function */ CreateFunction GetCreator(); /** - * Retrieve the actions for this type + * @brief Retrieve the actions for this type. + * * @return Container of action names */ NameContainer GetActions(); /** - * Retrieve the signals for this type + * @brief Retrieve the signals for this type. + * * @return Container of signal names */ NameContainer GetSignals(); @@ -125,14 +139,16 @@ public: // Properties /** - * Retrieve all the property indices for this type + * @brief Retrieve all the property indices for this type. + * * @param[out] indices Container of property indices * @note The container will be cleared */ void GetPropertyIndices( Property::IndexContainer& indices ) const; /** - * Given a property index, retrieve the property name associated with it. + * @brief Given a property index, retrieve the property name associated with it. + * * @param[in] index The property index. * @return The name of the property at the given index. */ @@ -141,7 +157,8 @@ public: public: // Not intended for application developers /** - * This constructor is used by Dali Get() method + * @brief This constructor is used by Dali Get() method. + * * @param [in] typeInfo A pointer to a Dali resource */ explicit DALI_INTERNAL TypeInfo(Internal::TypeInfo* typeInfo); diff --git a/dali/public-api/object/type-registry.h b/dali/public-api/object/type-registry.h index bb761f5..7d2e2a2 100644 --- a/dali/public-api/object/type-registry.h +++ b/dali/public-api/object/type-registry.h @@ -17,6 +17,7 @@ // limitations under the License. // + // EXTERNAL INCLUDES #include @@ -33,7 +34,8 @@ class TypeRegistry; } /** - * The TypeRegistry allows registration of type instance creation functions. + * @brief The TypeRegistry allows registration of type instance creation functions. + * * These can then be created later by name and down cast to the appropriate type. * * Usage: (Registering) @@ -88,21 +90,22 @@ class TypeRegistry; class TypeRegistry : public BaseHandle { public: - typedef std::vector NameContainer; + typedef std::vector NameContainer; ///< Container of type names /** - * Get Type Registry handle + * @brief Get Type Registry handle. + * * @return TypeRegistry handle */ static TypeRegistry Get(); /** - * Allows the creation of an empty typeRegistry handle. + * @brief Allows the creation of an empty typeRegistry handle. */ TypeRegistry(); /** - * destructor. + * @brief destructor. */ ~TypeRegistry(); @@ -112,21 +115,24 @@ public: using BaseHandle::operator=; /** - * Get TypeInfo for a registered type + * @brief Get TypeInfo for a registered type. + * * @param [in] uniqueTypeName A unique type name * @return TypeInfo if the type exists otherwise an empty handle */ TypeInfo GetTypeInfo( const std::string &uniqueTypeName ); /** - * Get TypeInfo for a registered type + * @brief Get TypeInfo for a registered type. + * * @param [in] registerType The registered type info * @return TypeInfo if the type exists otherwise an empty handle */ TypeInfo GetTypeInfo( const std::type_info& registerType ); /** - * Get type names + * @brief Get type names. + * * @return list of known types by name */ NameContainer GetTypeNames() const; @@ -134,20 +140,22 @@ public: public: // Not intended for application developers /** - * This constructor is used by Dali Get() method + * @brief This constructor is used by Dali Get() method. + * * @param [in] typeRegistry A pointer to a Dali resource */ explicit DALI_INTERNAL TypeRegistry(Internal::TypeRegistry*typeRegistry); }; /** - * Register a type from type info + * @brief Register a type from type info. */ class TypeRegistration { public: /** - * Constructor registers the type creation function + * @brief Constructor registers the type creation function. + * * @param [in] registerType the type info for the type to be registered * @param [in] baseType the base type info of registerType * @param [in] f registerType instance creation function @@ -156,7 +164,8 @@ public: TypeInfo::CreateFunction f ); /** - * Constructor registers the type creation function + * @brief Constructor registers the type creation function. + * * @param [in] registerType the type info for the type to be registered * @param [in] baseType the base type info of registerType * @param [in] f registerType instance creation function @@ -166,7 +175,8 @@ public: TypeInfo::CreateFunction f, bool callCreateOnInit ); /** - * Constructor registers the type creation function for a named class or type. + * @brief Constructor registers the type creation function for a named class or type. + * * This allows types to be created dynamically from script. The name must be * unique for successful registration. * @param [in] name the name of the type to be registered @@ -177,24 +187,26 @@ public: TypeInfo::CreateFunction f ); /** - * The name the type is registered under (derived from type_info) + * @brief The name the type is registered under (derived from type_info). + * * @return the registered name or empty if unregistered */ const std::string RegisteredName() const; private: - TypeRegistry mReference; - std::string mName; + TypeRegistry mReference; ///< Reference to the type registry + std::string mName; ///< Name of the type }; /** - * Register a signal connector function to a registered type + * @brief Register a signal connector function to a registered type. */ class SignalConnectorType { public: /** - * Constructor registers the type creation function + * @brief Constructor registers the type creation function. + * * @param [in] typeRegistration The TypeRegistration object * @param [in] name The signal name * @param [in] func The signal connector function @@ -203,13 +215,14 @@ public: }; /** - * Register an action function + * @brief Register an action function. */ class TypeAction { public: /** - * Constructor registers the type creation function + * @brief Constructor registers the type creation function. + * * @param [in] registered The TypeRegistration object * @param [in] name The action name * @param [in] f The action function @@ -218,15 +231,18 @@ public: }; /** - * Register a property for the given type. + * @brief Register a property for the given type. */ class PropertyRegistration { public: /** - * This constructor registers the property with the registered type. This constructor is for event-thread - * only properties where the value of the property can be retrieved and set via specified functions. + * @brief This constructor registers the property with the registered type. + * + * This constructor is for event-thread only properties where the + * value of the property can be retrieved and set via specified + * functions. * * Functions of the following type may be used for setFunc and getFunc respectively: * @code diff --git a/dali/public-api/scripting/scripting.h b/dali/public-api/scripting/scripting.h index 72b55eb..1b130d6 100644 --- a/dali/public-api/scripting/scripting.h +++ b/dali/public-api/scripting/scripting.h @@ -25,12 +25,15 @@ namespace Dali DALI_IMPORT_API { -// Utilities for scripting support +/** + * @brief Utilities for scripting support. + */ namespace Scripting { /** - * Permissive comparison for string enums + * @brief Permissive comparison for string enums. + * * Case insensitive and ignores '_', '-' in either string when comparing. * If both strings are empty return true; ie like if(a==b) but not like a.compare(b) * @param[in] input The input string @@ -40,7 +43,8 @@ namespace Scripting bool CompareEnums(const std::string& input, const std::string& enumString); /** - * Set the value if strings pass a permissive compare. + * @brief Set the value if strings pass a permissive compare. + * * @param[in] a The input string * @param[in] b The input string * @param[in] set The variable to set @@ -63,7 +67,8 @@ bool SetIfEqual(const std::string& a, const std::string& b, T& set, T value) /** - * Creates object with data from the property value map + * @brief Creates object with data from the property value map. + * * @param [in] map The property value map with the following valid fields * "filename": type STRING * "load-policy" type STRING (enum) @@ -81,7 +86,8 @@ Image NewImage( const Property::Value& map ); /** - * Creates object with data from the property value map + * @brief Creates object with data from the property value map. + * * @param [in] map The property value map with the following valid fields * // a program can be specified as string or a filename. * // some fields may be ignored depending on the geometry-type diff --git a/dali/public-api/text/utf8.h b/dali/public-api/text/utf8.h index e766cc0..feb06f5 100644 --- a/dali/public-api/text/utf8.h +++ b/dali/public-api/text/utf8.h @@ -16,12 +16,15 @@ // See the License for the specific language governing permissions and // limitations under the License. // + + #include namespace Dali DALI_IMPORT_API { /** - * Determine the length (in bytes) of a UTF-8 character + * @brief Determine the length (in bytes) of a UTF-8 character. + * * @param[in] leadByte The lead byte of a UTF-8 character sequence * @return The length of the sequence, or zero if the UTF-8 character is invalid. */ @@ -29,5 +32,5 @@ DALI_IMPORT_API size_t Utf8SequenceLength(const unsigned char leadByte); } // namespace Dali -#endif // __DALI_UTF8_H__ +#endif // __DALI_UTF8_H__ diff --git a/docs/coding-style.html b/docs/coding-style.html index 07f43c9..4a67b58 100644 --- a/docs/coding-style.html +++ b/docs/coding-style.html @@ -1,10 +1,10 @@ Dali C++ Coding Style -