#include <dali/public-api/actors/actor.h>
#include <dali/public-api/common/light.h>
+
namespace Dali DALI_IMPORT_API
{
}
/**
- * 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
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();
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();
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);
} // namespace Dali
+
#endif // __DALI_LIGHT_ACTOR_H__
// INTERNAL INCLUDES
#include <dali/public-api/animation/alpha-functions.h>
+
+
namespace Dali DALI_IMPORT_API
{
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
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.
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
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
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
} // namespace Dali
+
#endif /* __DALI_MODEL_ACTOR_FACTORY_H__ */
#include <dali/public-api/common/constants.h>
#include <dali/public-api/math/quaternion.h>
+
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__
// limitations under the License.
//
-/**
- * @addtogroup CAPI_DALI_FRAMEWORK
- * @{
- */
// EXTERNAL INCLUDES
#include <cstddef>
#include <dali/public-api/common/dali-common.h>
/**
- * 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 )
{
/**
- * 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.
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.
*/
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
SizeType Capacity() const;
/**
- * Release the data.
+ * @brief Release the data.
+ *
* Does not call destructors on objects held.
*/
void Release();
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.
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 >
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.
*/
}
/**
- * Reserve space in the vector.
+ * @brief Reserve space in the vector.
+ *
* @param count of elements to reserve.
* @param elementSize of a single element.
*/
}
/**
- * 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.
*/
}
/**
- * Clear the contents. For simple types nothing to do.
+ * @brief Clear the contents.
+ *
+ * For simple types nothing to do.
*/
void Clear()
{
}
/**
- * Release the vector.
+ * @brief Release the vector.
*/
void Release()
{
}
/**
- * Erase an element. Does not change capacity.
+ * @brief Erase an element. Does not change capacity.
+ *
* @param address to erase from.
* @param elementSize to erase.
*/
};
/**
- * 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.
};
/**
- * 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) >
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()
{
}
/**
- * Copy constructor
+ * @brief Copy constructor.
+ *
* @param vector Vector to copy from.
*/
Vector( const Vector& vector )
}
/**
- * Assignment operator
+ * @brief Assignment operator.
+ *
* @param vector Vector to assign from.
* @return reference to self for chaining.
*/
}
/**
- * 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 )
}
/**
- * 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.
*/
}
/**
- * 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.
*/
}
/**
- * 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.
*/
}
/**
- * 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 )
}
/**
- * Swap the contents of two vectors.
+ * @brief Swap the contents of two vectors.
+ *
* @param vector Vector to swap with.
*/
void Swap( Vector& vector )
}
/**
- * Clear the contents of the vector. Keeps its capacity.
+ * @brief Clear the contents of the vector. Keeps its capacity.
*/
void Clear()
{
}
/**
- * Release the memory that the vector holds.
+ * @brief Release the memory that the vector holds.
*/
void Release()
{
} // namespace Dali
-/**
- * @}
- */
#endif /* __DALI_VECTOR_H__ */
// INTERNAL INCLUDES
#include <dali/public-api/object/base-handle.h>
+
+/**
+ * The top level DALi namespace
+ */
namespace Dali DALI_IMPORT_API
{
class Light;
/**
- * Light source types
+ * @brief Light source types.
*/
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()
}
/**
- * Virtual destructor.
+ * @brief Virtual destructor.
*/
virtual ~Light();
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.
*/
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);
#endif //ifndef HIDE_DALI_INTERNALS
+
#endif /* __DALI_MAP_H__ */
#include <dali/public-api/common/dali-vector.h>
#include <dali/public-api/object/ref-object.h>
+
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
// limitations under the License.
//
+
// EXTERNAL INCLUDES
#ifndef HIDE_DALI_INTERNALS
} // namespace Internal
/**
- * Describes a DynamicsBody configuration
+ * @brief Describes a DynamicsBody configuration.
+ *
* Use to create multiple instances of a DynamicsBody
*/
class DynamicsBodyConfig : public BaseHandle
public:
/**
- * Enumeration of the types of dynamics bodies
+ * @brief Enumeration of the types of dynamics bodies.
*/
enum BodyType
{
}; // 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
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();
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
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
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.
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.
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.
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.
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.
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.
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.
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
*/
// 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 );
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();
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
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
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.
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
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()
} // 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();
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;
// 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 );
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
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();
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.
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.
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.
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)
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.
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.
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;
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);
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
{
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();
public:
/**
- * Get the type of shape
+ * @brief Get the type of shape.
+ *
* @return One of the ShapeType enumeration.
*/
ShapeType GetType() const;
// 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);
} // 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
{
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();
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
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)
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;
// 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 );
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.
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,
public:
/**
- * Create an uninitialized DynamicsWorld handle.
+ * @brief Create an uninitialized DynamicsWorld handle.
*/
DynamicsWorld();
/**
- * Virtual destructor.
+ * @brief Virtual destructor.
*/
virtual ~DynamicsWorld();
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;
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);
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 );
#include <dali/public-api/actors/actor.h>
#include <dali/public-api/common/stage.h>
+
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.
*
* <h3>Hit Test Algorithm:</h3>
*
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.
};
/**
- * 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.
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.
#include <dali/public-api/common/dali-common.h>
#include <dali/public-api/math/vector2.h>
+
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.
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;
// 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;
// limitations under the License.
//
+
// INTERNAL INCLUDES
#include <dali/public-api/common/dali-common.h>
#include <dali/public-api/math/vector4.h>
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
{
struct Vertex;
typedef std::vector<Vertex> 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<FaceIndex> 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.
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.
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.
*/
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
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
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.
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
{
{
}
- 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)
{
}
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];
};
// limitations under the License.
//
+
// INTERNAL INCLUDES
#include <dali/public-api/actors/actor.h>
#include <dali/public-api/geometry/mesh-data.h>
}
/**
- * 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();
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
const Rect<float>& textureCoordinates = Rect<float>(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 );
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__
// limitations under the License.
//
+
// INTERNAL INCLUDES
#include <dali/public-api/common/vector-wrapper.h>
#include <dali/public-api/math/vector2.h>
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
{
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].
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.
*
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
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
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.
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
const float ApproximateCubicBezierParameter (float atX, float P0_X, float C0_X, float C1_X, float P1_X ) const;
private:
- std::vector<Vector3> mKnots;
- std::vector<Vector3> mOutTangents;
- std::vector<Vector3> mInTangents;
+ std::vector<Vector3> mKnots; ///< The set of knot points
+ std::vector<Vector3> mOutTangents; ///< The set of out tangents (matching to mKnots)
+ std::vector<Vector3> 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__
// limitations under the License.
//
+
// INTERNAL INCLUDES
#include <dali/public-api/common/dali-common.h>
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.
// limitations under the License.
//
+
// INTERNAL INCLUDES
#include <dali/public-api/common/vector-wrapper.h>
#include <dali/public-api/math/matrix.h>
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;
// limitations under the License.
//
+
// INTERNAL INCLUDES
#include <dali/public-api/animation/key-frames.h>
#include <dali/public-api/modeling/entity.h>
class Entity;
class EntityAnimatorMap;
-typedef std::vector<EntityAnimatorMap> EntityAnimatorMapContainer;
-typedef EntityAnimatorMapContainer::const_iterator EntityAnimatorMapIter;
+typedef std::vector<EntityAnimatorMap> 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)
}
/**
- * 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
}
/**
- * Set the animated entity
+ * @brief Set the animated entity.
+ *
* @param[in] animatedEntity The animated entity
*/
void SetAnimatedEntity(Entity animatedEntity)
}
/**
- * Get the animated entity.
+ * @brief Get the animated entity.
+ *
* @return the animated entity
*/
Entity GetAnimatedEntity(void)
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)
};
// limitations under the License.
//
+
// INTERNAL INCLUDES
#include <dali/public-api/geometry/mesh.h>
typedef std::vector<Entity> 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<unsigned int> EntityMeshIndices;
+typedef std::vector<unsigned int> 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();
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);
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.
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 );
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);
// limitations under the License.
//
+
// INTERNAL INCLUDES
#include <dali/public-api/modeling/entity-animator-map.h>
{
struct ModelAnimationMap;
-typedef std::vector<ModelAnimationMap> ModelAnimationMapContainer;
+typedef std::vector<ModelAnimationMap> 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),
{
}
- 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__
-
// limitations under the License.
//
+
// EXTERNAL INCLUDES
#include <string>
}
/**
- * 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();
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.
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.
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.
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.
*/
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);
// limitations under the License.
//
+
// EXTERNAL INCLUDES
#include <boost/function.hpp>
#include <string>
}
/**
- * 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.
{
public:
- typedef SignalV2<void (Model)> ModelSignalV2;
- typedef SignalV2<void (Model,bool)> ModelSaveSignalV2;
+ typedef SignalV2<void (Model)> ModelSignalV2; ///< Signal type
+ typedef SignalV2<void (Model,bool)> 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();
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.
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.
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.
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
*/
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);
// limitations under the License.
//
+
// INTERNAL INCLUDES
#include <dali/public-api/object/base-handle.h>
};
/**
- * 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<Property::Value>&);
+ typedef BaseHandle (*CreateFunction)(); ///< Function signature for creating an instance of the associated object type.
+
+ typedef bool (*ActionFunction)(BaseObject*, const std::string&, const std::vector<Property::Value>&); ///< 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.
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.
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<std::string> NameContainer;
+ typedef std::vector<std::string> 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();
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();
// 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.
*/
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);
// limitations under the License.
//
+
// EXTERNAL INCLUDES
#include <typeinfo>
}
/**
- * 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)
class TypeRegistry : public BaseHandle
{
public:
- typedef std::vector<std::string> NameContainer;
+ typedef std::vector<std::string> 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();
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;
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
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
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
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
};
/**
- * 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
};
/**
- * 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
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
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
/**
- * 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)
/**
- * 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
// See the License for the specific language governing permissions and
// limitations under the License.
//
+
+
#include <dali/public-api/common/dali-common.h>
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.
*/
} // namespace Dali
-#endif // __DALI_UTF8_H__
+#endif // __DALI_UTF8_H__
<HTML>
<HEAD>
<TITLE>Dali C++ Coding Style</TITLE>
-<!--
+<!--
green code for good examples, same formatting as <pre> tag
red code for bad examples, same formatting as <pre> tag
-details hidden by default
+details hidden by default
-->
<style type="text/css">
code.good { color:green; white-space:pre; }
brains relies a great deal on these naming rules.
</P>
<P>
- Consistency is more important than individual preferences so regardless of
+ Consistency is more important than individual preferences so regardless of
whether you find them sensible or not, the rules are the rules.
</P>
<code>NumErrors</code>.
</P>
<P>
- Function names should typically be imperative (that is they should be commands):
+ Function names should typically be imperative (that is they should be commands):
e.g., <code>OpenFile()</code>, <code>set_num_errors()</code>. There is an exception for
accessors, which should be named the same as the variable they access.
</P>
<P>
In general, make your filenames very specific. For example,
use <code>http-server-logs.h</code> rather than <code>logs.h</code>.
- A class called <code>FooBar</code> should be declared in file
+ A class called <code>FooBar</code> should be declared in file
called <code>foobar.h</code> and defined in <code>foobar.cpp</code>.
</P>
<P>
Type names start with a capital letter and have a capital
letter for each new word, with no underscores:
<code>MyExcitingClass</code>, <code>MyExcitingEnum</code>.
- All type names are declared inside namespace so no prefixing is used.
+ All type names are declared inside a namespace so no prefixing is used.
</SUMMARY>
<H3>Examples <input type="button" value="Hide" onclick="toggleVisibility( this, 'type_name_examples' );"/></H3>
<ARTICLE class="detail" id="type_name_examples">
<p>
- The names of all types; classes, structs, typedefs have the same naming convention.
- Type names start with a capital letter and have a capital letter for each new word (CamelCase).
- No underscores. Enumerated types use same convention as Constants> all capitals.
+ The names of all types; classes, structs, typedefs have the same naming convention -
+ CamelCase with a leading capital letter, with no underscores. Enumerated type constants use the same convention as class constants, i.e. all uppercase with underscores.
For example:
</p>
<CODE class="good">
// classes and structs
- class UrlTable { ...
- class UrlTableTester { ...
- struct UrlTableProperties { ...
+ class UrlTable { ... };
+ class UrlTableTester { ... };
+ struct UrlTableProperties { ... };
// typedefs
typedef hash_map<UrlTableProperties *, string> PropertiesMap;
<ARTICLE>
<H2>Variable Names</H2>
<SUMMARY>
- Local variable names start with a lowercase. For example: <code>myExcitingLocalVariable</code>,
+ Variable names should use camel case, with an initial lower case letter.
+ Local variable names start with a lowercase letter. For example: <code>myExcitingLocalVariable</code>,
Class member variables have prefix m. For example: <code>mMember</code>.
The only exception to this rule is for public member variables in public structs where the prefix m is not required.
Such member variables should also start with a lowercase letter.
- Constants should be all capitals.
- Avoid underscore characters in names because it can be hard to spot.
- Global variables should be avoided, if one is needed, prefix it with <code>g</code>.
+ Avoid underscore characters in mixed case names.
+ Constants should be all upper case, with underscores between words.
+ Global variables should be avoided, however, if one is needed, prefix it with <code>g</code>.
</SUMMARY>
<H3>Examples <input type="button" value="Hide" onclick="toggleVisibility( this, 'variable_name_examples' );"/></H3>
<ARTICLE class="detail" id="variable_name_examples">
For example:
</p>
<CODE class="good">
- string tableName; // OK - starts lowercase
- string tablename; // OK - all lowercase.
+ void SomeFunction()
+ {
+ string tableName; // OK - starts lowercase
+ string tablename; // OK - all lowercase.
+ }
</CODE>
<CODE class="bad">
string TableName; // Bad - starts with capital.
</CODE>
<CODE class="good">
+ class Foo
+ {
+ public:
+ string mTable; // OK
+ string mTableName; // OK.
+ };
+ </CODE>
+ <CODE class="good">
struct Foo
{
- string mTable; // OK
- string mTableName; // OK.
- }
+ string table; // OK
+ string tableName; // OK.
+ };
</CODE>
<CODE class="good">
- const int DAYSINAWEEK = 7;
+ const int DAYS_IN_A_WEEK = 7;
+ </CODE>
+ <CODE class="bad">
+ const int DaysInAWeek = 7; // Bad - constants should not use camel case.
+ const int DAYSINAWEEK = 7; // Bad - without underscore, words run together.
</CODE>
</ARTICLE>
</ARTICLE>
<ARTICLE>
<H2>Function Names</H2>
<SUMMARY>
- Regular functions have camel case starting with uppercase; accessors and mutators match
- the name of the variable with Get or Set as prefix. No underscores
+ Regular function names are written in camel case starting with a
+ capital letter and no underscores; accessors and mutators match
+ the name of the variable with Get or Set as prefix.
</SUMMARY>
<H3>Examples <input type="button" value="Hide" onclick="toggleVisibility( this, 'function_name_examples' );"/></H3>
<ARTICLE class="detail" id="function_name_examples">
<CODE class="good">
- MyExcitingFunction();
- MyExcitingMethod();
+ void MyExcitingFunction();
+ void MyExcitingMethod();
class MyClass
{
public:
...
int GetNumEntries() const { return mNumEntries; }
- void SetNumEntries(int numEntries) { mNumEntries = numEntries; }
+ void SetNumEntries( int numEntries ) { mNumEntries = numEntries; }
private:
int mNumEntries;
};
</CODE>
+
+ <CODE class="bad">
+ void my_boring_function(); // bad - uses underscores and no camel case.
+ </CODE>
+
</ARTICLE>
</ARTICLE>
<H2>Macro Names</H2>
<SUMMARY>
Macros should not be used for programming, code should always be readable without preprocessor.
- Only allowed cases for macros are include guards, debug tracing and compile time feature flags
- <b>inside</b> .cpp files when no other variation mechanism is not possible. Always prefer variation
+ Only allowed cases for macros are include guards, debug tracing and compile time feature flags
+ <b>inside</b> .cpp files when no other variation mechanism is not possible. Always prefer variation
through design and template mechanisms rather than <i>#define</i>.
If you need to use macros, they're like this: <code>MY_MACRO_THAT_SCARES_SMALL_CHILDREN</code>.
</SUMMARY>
<H1>Comments</H1>
<SUMMARY>
- Comments are absolutely vital to keeping our code readable.
- The following rules describe what you should comment and where.
+ Comments are absolutely vital to keeping our code readable.
+ The following rules describe what you should comment and where.
But remember: while comments are very important, the best code is self-documenting.
Giving sensible names to types and variables is much better than using obscure
names that you must then explain through comments.
<H3>Class Comments</H3>
<SUMMARY>
Every class definition should have an accompanying comment that
- describes what it is for and how it should be used.
+ describes what it is for and how it should be used. It should have
+ a brief description, followed by a newline and a broader description.
</SUMMARY>
<CODE class="good">
/**
- * Iterates over the contents of a GargantuanTable.
+ * @brief Iterates over the contents of a GargantuanTable.
+ *
* Example usage:
* GargantuanTableIterator* iter = table->NewIterator();
- * for (iter->Seek("foo"); !iter->done(); iter->Next()) {
- * process(iter->key(), iter->value());
+ * for( iter->Seek("foo"); !iter->done(); iter->Next() )
+ * {
+ * process( iter->key(), iter->value() );
* }
* delete iter;
*/
</P>
<H3>Function Comments</H3>
<SUMMARY>
- Every function declaration (typically in a header file) must have comments immediately
- preceding it that describe what the function does and how to use it. These comments
- should be descriptive ("Opens the file") rather than imperative ("Open the file"); the
+ Every function declaration in a header file must have a brief comment
+ that describes what the function does, followed by a newline. It may
+ be followed by a detailed description on how to use it.
+ These comments should be descriptive ("Opens the file") rather than
+ imperative ("Open the file"); the
comment describes the function, it does not tell the function what to do.
+ Each parameter must be documented, as must any return value.
</SUMMARY>
<P>
Types of things to mention in comments at the function
</UL>
<CODE class="good">
/**
- * Get the iterator for this data table. Client's responsibility is to delete the iterator,
+ * @brief Get the iterator for this data table.
+ *
+ * It is the client's responsibility to delete the iterator,
* and it must not use the iterator once the GargantuanTable object
* on which the iterator was created has been deleted.
*
*
* This method is equivalent to:
* Iterator* iter = table->NewIterator();
- * iter->Seek("");
+ * iter->Seek( "" );
* return iter;
* If you are going to immediately seek to another place in the
* returned iterator, it will be faster to use NewIterator()
* and avoid the extra seek.
- * @return an iterator for this table.
+ * @return an iterator for this table.
*/
Iterator* GetIterator() const;
</CODE>
<SUMMARY>
In general the actual name of the variable should be descriptive
enough to give a good idea of what the variable is used for. In
- certain cases, more comments are required.
+ certain cases, more comments are required - use Doxygen formatting.
</SUMMARY>
<CODE class="good">
private:
- // Keeps track of the total number of entries in the table.
- // Used to ensure we do not go over the limit. -1 means
- // that we don't yet know how many entries the table has.
- int mNumTotalEntries;
+ /**
+ * @brief Keeps track of the total number of entries in the table.
+ *
+ * Used to ensure we do not go over the limit. -1 means
+ * that we don't yet know how many entries the table has.
+ */
+ int mNumTotalEntries;
+
+ float mDuration; ///< Duration in seconds.
</CODE>
+
<H3> Duplicate documentation</H3>
<SUMMARY>
Try to avoid duplicate documentation by using the @copydoc command.
documentation of an inherited member.
</P>
<CODE class="good">
- /*! @copydoc MyClass::myfunction()
- * More documentation.
+ /**
+ * @copydoc MyClass::myfunction()
+ * More documentation.
*/
</CODE>
<P>
- if the member is overloaded, you should specify the argument types
- explicitly (without spaces!), like in the following:
+ If the member is overloaded, you should specify the argument types
+ explicitly (without spaces!), like in the following:
</P>
<CODE class="good">
- /*! @copydoc MyClass::myfunction(type1,type2) */
+ /** @copydoc MyClass::myfunction(type1,type2) */
</CODE>
<H3>Punctuation, Spelling and Grammar</H3>
<SUMMARY>
</SUMMARY>
<H3>Deprecation Comments</H3>
<SUMMARY>
- Mark deprecated interface points with <code>DEPRECATED</code> comments.
+ Mark deprecated interface points with <code>@deprecated</code> comments.
</SUMMARY>
</ARTICLE>
<LI>Avoid unnecessary trailing whitescape</LI>
<LI>Avoid overly long lines, modern screens and editors can handle upto 120 characters</LI>
<LI>Use UTF-8 formatting for non-ASCII characters</LI>
+ <LI>Anything enclosed in parentheses should also have a space inside the parentheses. </LI>
+ <LI>Braces must each be in a line on their own.</LI>
</UL>
<P>
Hex encoding is also OK, and encouraged where it enhances
Typedefs and Enums first, Constructor(s) & Destructors & public API next, then virtual methods and implementation details last.
</SUMMARY>
<CODE class="good">
-
/**
- * Class documentation
- */
+ * @brief Class purpose.
+ *
+ * Long description.
+ */
class MyClass : public Base
{
public: // API
/**
+ * @brief Short description.
+ *
* Documentation
- */
+ */
MyClass(); // 2 space indent.
/**
- * Documentation
- */
+ * @brief Short description.
+ *
+ * @param[in] var Description
+ */
explicit MyClass( int var );
/**
+ * @brief Short description.
+ *
* Documentation
- */
- virtual ~MyClass() {}
+ */
+ virtual ~MyClass();
/**
+ * @brief Short description.
+ *
* Documentation
- */
+ */
void SomeFunction();
/**
+ * @brief Short description.
+ *
* Documentation
- */
+ */
void SomeFunctionThatDoesNothing();
/**
+ * @brief Short description.
+ *
* Documentation
- */
+ * @param[in] var Parameter description
+ */
void SetSomeVar( int var )
/**
- * Documentation
- */
+ * @brief Short description.
+ *
+ * Documentation.
+ * @return value description.
+ */
int GetSomeVar() const
private: // Implementation
- MyClass( MyClass& aRHs ); // no copying
- MyClass& operator=( const MyClass& aRHs ); // no copying.
+ MyClass( MyClass& aRHs ); ///< no copying
+ MyClass& operator=( const MyClass& aRHs ); ///< no copying.
bool SomeInternalFunction();
- int mSomeVar;
- int mSomeOtherVar;
+ int mSomeVar; ///< short description.
+ int mSomeOtherVar; ///< short description.
};
</CODE>
</SUMMARY>
<CODE class="good">
// When it all fits on one line:
- MyClass::MyClass( int var ) : Base( var), mSomeVar( var ), mSomeOtherVar( var + 1 ) {}
+ MyClass::MyClass( int var ) : Base( var), mSomeVar( var ), mSomeOtherVar( var + 1 )
+ {
+ }
// When it requires multiple lines, indent, putting the colon on
// the first initializer line:
MyClass::MyClass( int var )
- : Base( var )
+ : Base( var ),
mSomeVar( var ),
mSomeOtherVar( var + 1 )
{
<CODE class="good">
namespace
{
- void foo()
+
+ void Foo()
{ // Correct. No extra indentation within namespace.
...
}
+
} // namespace
</CODE>
<P>
When declaring nested namespaces, put each namespace on its own line.
</P>
<CODE class="good">
- namespace foo
+ /**
+ * @brief description of namespace
+ */
+ namespace Foo
{
- namespace bar
+
+ /**
+ * @brief description of namespace
+ */
+ namespace Bar
{
</CODE>
All parameters should be named, with identical names in the declaration and definition.
</SUMMARY>
<CODE class="good">
- ReturnType ClassName::FunctionName( Type par_name1, Type par_name2 )
+ ReturnType ClassName::FunctionName( Type parameterName1, Type parameterName2 )
{
DoSomething();
}
If you have too much text to fit on one line:
</P>
<CODE class="good">
- ReturnType ClassName::ReallyLongFunctionName( Type par_name1, Type par_name2,
- Type par_name3 )
+ ReturnType ClassName::ReallyLongFunctionName( Type parameterName1,
+ Type parameterName2,
+ Type parameterName3 )
{
DoSomething();
}
</P>
<CODE class="good">
ReturnType LongClassName::ReallyReallyReallyLongFunctionName(
- Type par_name1, // indent
- Type par_name2,
- Type par_name3 )
+ Type parameterName1, // 2 space indent
+ Type parameterName2,
+ Type parameterName3 )
{
DoSomething(); // 2 space indent
...
</P>
<CODE class="good">
// Everything in this function signature fits on a single line
- ReturnType FunctionName( Type par ) const
+ ReturnType FunctionName( Type parameter ) const
{
...
}
// This function signature requires multiple lines, but
// the const keyword is on the line with the last parameter.
- ReturnType ReallyLongFunctionName( Type par1,
- Type par2 ) const
+ ReturnType ReallyLongFunctionName( Type parameter1,
+ Type parameter2 ) const
{
...
}
}
// Comment out unused named parameters in definitions.
- void Circle::Rotate(double /*radians*/) {}
+ void Circle::Rotate( double /*radians*/ )
+ {
+ }
</CODE>
<CODE class="bad">
// Bad - if someone wants to implement later, it's not clear what the
// variable means.
- void Circle::Rotate( double ) {}
+ void Circle::Rotate( double )
+ {
+ }
</CODE>
<H3>Function Calls</H3>
aligned with the first argument:
</P>
<CODE class="good">
- bool retval = DoSomething( averyveryveryverylongargument1,
+ bool retval = DoSomething( aVeryVeryVeryVeryLongArgument1,
argument2, argument3 );
</CODE>
<P>
argument4 );
</CODE>
<P>
- If the function signature is so long that it cannot fit,
+ If the function signature is so long that it cannot fit,
place all arguments on subsequent lines:
</P>
<CODE class="good">
if( ... )
{
DoSomethingThatRequiresALongFunctionName(
- very_long_argument1, // indent
+ aVeryLongArgument1, // indent
argument2,
argument3,
- argument4);
+ argument4 );
}
</CODE>
<H3>Conditionals</H3>
<SUMMARY>
- <code>else</code> keyword belongs on its own line. Put one space inside the parentheses, none outside.
+ The <code>if</code> statement should be followed only by the conditional, with a space inside the parentheses, not outside. The following clause must always be surrounded by braces on separate lines.
+ The <code>else</code> keyword belongs on its own line, and the following clause must always be
+ surrounded by braces.
</SUMMARY>
<CODE class="good">
- if( condition ) // space inside
+ if( condition ) // space inside parentheses
{
...
}
}
</CODE>
<CODE class="bad">
- if(condition) // Bad - space missing after IF.
- if(condition){ // Doubly bad.
+ if(condition) // Bad - space missing inside parentheses
+ if(condition){ // Doubly bad. Mis-aligned parentheses are harder to read.
</CODE>
<P>
- Short conditional statements may be written on one line if
- this enhances readability. You may use this only when the
- line is brief and the statement does not use the
- <code>else</code> clause.
- </P>
- <CODE class="good">
- if( x == kFoo ) return new Foo();
- if( x == kBar ) return new Bar();
- </CODE>
- <P>
- This is not allowed when the if statement has an
- <code>else</code>:
- </P>
- <CODE class="bad">
- // Not allowed - IF statement on one line when there is an ELSE clause
- if (x) DoThis();
- else DoThat();
- </CODE>
- <P>
- In general, prefer curly braces for conditional
+ Must always have curly braces for the clauses, and they must always be on a line
+ on their own:
</P>
<CODE class="good">
if( condition )
{
DoSomething(); // 2 space indent.
}
+ else
+ {
+ DoSomethingElse(); // 2 space indent.
+ }
</CODE>
- <P>
- If one part of an <code>if</code>-<code>else</code>
- statement uses curly braces, the other part must too:
- </P>
- <CODE class="bad">
- // Not allowed - curly on IF but not ELSE
- if (condition) // space outside, not inside
- {
- foo;
- }
- else
- bar;
-
- // Not allowed - curly on ELSE but not IF
- if (condition)
- foo;
- else
- {
- bar;
- }
- </CODE>
<H3>Loops and Switch Statements</H3>
<SUMMARY>
{
// Repeat test until it returns false.
}
+
for( int i = 0; i < someNumber; ++i )
- {} // Good - empty body, clearly on its own line
+ {
+ } // Good - empty body, clearly separated.
+
while( condition )
continue; // Good - continue indicates no logic.
+
</CODE>
<CODE class="bad">
- while (condition); // Bad - looks like part of do/while loop.
+ while( condition ); // Bad - looks like part of do/while loop.
</CODE>
<H3>Pointer and Reference Expressions</H3>
<SUMMARY>
<P>
When declaring a pointer variable or argument, you may place
the asterisk adjacent to either the type or to the variable
- name:
+ name, however, placing with the type is preferred.
</P>
<CODE class="good">
// These are fine, space preceding.
of the lines:
</P>
<CODE class="good">
- if( this_one_thing > this_other_thing &&
- a_third_thing == a_fourth_thing &&
- yet_another && last_one )
+ if( thisOneThing > thisOtherThing &&
+ aThirdThing == aFourthThing &&
+ yetAnother && lastOne )
{
...
}
Do not needlessly surround the <code>return</code> expression with parentheses.
</SUMMARY>
<CODE class="good">
- return result; // No parentheses in the simple case.
- return ( some_long_condition && // Parentheses ok to make a complex
- another_condition ); // expression more readable.
+ return result; // No parentheses in the simple case.
+ return ( someLongCondition && // Parentheses ok to make a complex
+ anotherCondition ); // expression more readable.
</CODE>
<CODE class="bad">
return (value); // You wouldn't write var = (value);
</P>
<CODE class="good">
// Good - directives at beginning of line
- if( lopsided_score )
+ if( lopsidedScore )
{
#if DISASTER_PENDING // Correct -- Starts at beginning of line
DropEverything();
</CODE>
<CODE class="bad">
// Bad - indented directives
- if( lopsided_score )
+ if( lopsidedScore )
{
#if DISASTER_PENDING // Wrong! The "#if" should be at beginning of line
DropEverything();
projects / platform / core / uifw / dali-core.git / commitdiff