#define __DALI_QUATERNION_H__
/*
- * Copyright (c) 2015 Samsung Electronics Co., Ltd.
+ * Copyright (c) 2018 Samsung Electronics Co., Ltd.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
namespace Dali
{
+/**
+ * @addtogroup dali_core_math
+ * @{
+ */
// Forward declaration
class Matrix;
/**
* @brief The Quaternion class encapsulates the mathematics of the quaternion.
+ * @SINCE_1_0.0
*/
-class DALI_IMPORT_API Quaternion
+class DALI_CORE_API Quaternion
{
public:
/**
- * @brief Default Constructor
+ * @brief Default Constructor.
+ * @SINCE_1_0.0
*/
Quaternion();
/**
- * @brief Construct from a quaternion represented by floats.
+ * @brief Constructs from a quaternion represented by floats.
*
+ * @SINCE_1_0.0
* @param[in] cosThetaBy2
* @param[in] iBySineTheta
* @param[in] jBySineTheta
Quaternion( float cosThetaBy2, float iBySineTheta, float jBySineTheta, float kBySineTheta );
/**
- * @brief Construct from a quaternion represented by a vector.
+ * @brief Constructs from a quaternion represented by a vector.
*
- * @param[in] vector - x,y,z fields represent i,j,k coefficients, w represents cos(theta/2)
+ * @SINCE_1_0.0
+ * @param[in] vector x,y,z fields represent i,j,k coefficients, w represents cos(theta/2)
*/
explicit Quaternion( const Vector4& vector );
/**
* @brief Constructor from an axis and angle.
*
- * @param[in] angle - the angle around the axis
- * @param[in] axis - the vector of the axis
+ * @SINCE_1_0.0
+ * @param[in] angle The angle around the axis
+ * @param[in] axis The vector of the axis
*/
Quaternion( Radian angle, const Vector3& axis );
/**
- * @brief Construct from Euler angles.
+ * @brief Constructs from Euler angles.
*
+ * @SINCE_1_0.0
* @param[in] pitch
* @param[in] yaw
* @param[in] roll
Quaternion( Radian pitch, Radian yaw, Radian roll );
/**
- * @brief Construct from a matrix.
+ * @brief Constructs from a matrix.
*
+ * @SINCE_1_0.0
* @param[in] matrix
*/
explicit Quaternion(const Matrix& matrix);
/**
- * @brief Construct from 3 orthonormal axes.
+ * @brief Constructs from 3 orthonormal axes.
*
+ * @SINCE_1_0.0
* @param[in] xAxis The X axis
* @param[in] yAxis The Y axis
* @param[in] zAxis The Z axis
explicit Quaternion( const Vector3& xAxis, const Vector3& yAxis, const Vector3& zAxis );
/**
- * @brief Construct quaternion which describes minimum rotation to align v0 with v1
- * @pre v0 and v1 should be normalized
- *
+ * @brief Constructs quaternion which describes minimum rotation to align v0 with v1.
+ * @SINCE_1_0.0
* @param[in] v0 First normalized vector
* @param[in] v1 Second normalized vector
+ * @pre v0 and v1 should be normalized
+ *
*/
explicit Quaternion( const Vector3& v0, const Vector3& v1 );
/**
* @brief Destructor, nonvirtual as this is not a base class.
*
+ * @SINCE_1_0.0
*/
~Quaternion();
static const Quaternion IDENTITY; ///< (0.0f,0.0f,0.0f,1.0f)
/**
- * @brief Helper to check if this is an identity quaternion
+ * @brief Helper to check if this is an identity quaternion.
*
- * @return true if this is identity quaternion
+ * @SINCE_1_0.0
+ * @return True if this is identity quaternion
*/
bool IsIdentity() const;
/**
- * @brief Convert the quaternion to an axis/angle pair.
+ * @brief Converts the quaternion to an axis/angle pair.
*
+ * @SINCE_1_0.0
* @param[out] axis
- * @param[out] angle in radians
- * @return true if converted correctly
+ * @param[out] angle Angle in radians
+ * @return True if converted correctly
*/
bool ToAxisAngle( Vector3& axis, Radian& angle ) const;
/**
- * @brief Return the quaternion as a vector.
+ * @brief Returns the quaternion as a vector.
*
- * @return the vector representation of the quaternion
+ * @SINCE_1_0.0
+ * @return The vector representation of the quaternion
*/
const Vector4& AsVector() const;
/**
* @brief SetEuler sets the quaternion from the Euler angles applied in x, y, z order.
*
+ * @SINCE_1_0.0
* @param[in] pitch
* @param[in] yaw
* @param[in] roll
void SetEuler( Radian pitch, Radian yaw, Radian roll );
/**
- * @brief returns the Euler angles from a rotation Quaternion.
+ * @brief Returns the Euler angles from a rotation Quaternion.
*
- * @return a vector of Euler angles (x == pitch, y == yaw, z == roll)
+ * @SINCE_1_0.0
+ * @return A vector of Euler angles (x == pitch, y == yaw, z == roll)
*/
Vector4 EulerAngles() const;
/**
* @brief Addition operator.
*
+ * @SINCE_1_0.0
* @param[in] other The quaternion to add
* @return A quaternion containing the result of the addition
*/
/**
* @brief Subtraction operator.
*
+ * @SINCE_1_0.0
* @param[in] other The quaternion to subtract
* @return A quaternion containing the result of the subtract
*/
/**
* @brief Multiplication operator.
*
+ * @SINCE_1_0.0
* @param[in] other The quaternion to multiply
* @return A quaternion containing the result
*/
/**
* @brief Multiplication operator.
*
+ * @SINCE_1_0.0
* @param[in] other The vector to multiply
* @return A vector containing the result of the multiplication
*/
/**
* @brief Division operator.
*
- * @param[in] other a quaternion to divide by
+ * @SINCE_1_0.0
+ * @param[in] other A quaternion to divide by
* @return A quaternion containing the result
*/
const Quaternion operator/( const Quaternion& other ) const;
/**
* @brief Scale operator.
*
+ * @SINCE_1_0.0
* @param[in] scale A value to scale by
* @return A quaternion containing the result
*/
/**
* @brief Scale operator.
*
+ * @SINCE_1_0.0
* @param[in] scale A value to scale by
* @return A quaternion containing the result
*/
/**
* @brief Unary Negation operator.
*
+ * @SINCE_1_0.0
* @return A quaternion containing the negated result
*/
Quaternion operator-() const;
/**
* @brief Addition with Assignment operator.
*
+ * @SINCE_1_0.0
* @param[in] other The quaternion to add
- * @return itself
+ * @return A reference to this
*/
const Quaternion& operator+=( const Quaternion& other );
/**
* @brief Subtraction with Assignment operator.
*
+ * @SINCE_1_0.0
* @param[in] other The quaternion to subtract
- * @return itself
+ * @return A reference to this
*/
const Quaternion& operator-=( const Quaternion& other );
/**
* @brief Multiplication with Assignment operator.
*
+ * @SINCE_1_0.0
* @param[in] other The quaternion to multiply
- * @return itself
+ * @return A reference to this
*/
const Quaternion& operator*=( const Quaternion& other );
/**
* @brief Scale with Assignment operator.
*
+ * @SINCE_1_0.0
* @param[in] scale the value to scale by
- * @return itself
+ * @return A reference to this
*/
const Quaternion& operator*=( float scale );
/**
* @brief Scale with Assignment operator.
*
- * @param[in] scale the value to scale by
- * @return itself
+ * @SINCE_1_0.0
+ * @param[in] scale The value to scale by
+ * @return A reference to this
*/
const Quaternion& operator/=( float scale );
/**
* @brief Equality operator.
*
- * @param[in] rhs The quaterion to compare with.
- * @return True if the quaternions are equal.
+ * @SINCE_1_0.0
+ * @param[in] rhs The quaternion to compare with
+ * @return True if the quaternions are equal
*/
bool operator==( const Quaternion& rhs ) const;
/**
* @brief Inequality operator.
*
- * @param[in] rhs The quaterion to compare with.
- * @return True if the quaternions are not equal.
+ * @SINCE_1_0.0
+ * @param[in] rhs The quaternion to compare with
+ * @return True if the quaternions are not equal
*/
bool operator!=( const Quaternion& rhs ) const;
/**
- * @brief Return the length of the quaternion.
+ * @brief Returns the length of the quaternion.
*
- * @return the length of the quaternion
+ * @SINCE_1_0.0
+ * @return The length of the quaternion
*/
float Length() const;
/**
- * @brief Return the squared length of the quaternion.
+ * @brief Returns the squared length of the quaternion.
*
- * @return the squared length of the quaternion
+ * @SINCE_1_0.0
+ * @return The squared length of the quaternion
*/
float LengthSquared() const;
/**
- * @brief Normalize this to unit length.
+ * @brief Normalizes this to unit length.
*
+ * @SINCE_1_0.0
*/
void Normalize();
/**
* @brief Normalized.
*
- * @return a normalized version of this quaternion
+ * @SINCE_1_0.0
+ * @return A normalized version of this quaternion
*/
Quaternion Normalized() const;
/**
- * @brief Conjugate this quaternion.
+ * @brief Conjugates this quaternion.
*
+ * @SINCE_1_0.0
*/
void Conjugate();
/**
- * @brief Invert this quaternion.
+ * @brief Inverts this quaternion.
*
+ * @SINCE_1_0.0
*/
void Invert();
/**
* @brief Performs the logarithm of a Quaternion = v*a where q = (cos(a),v*sin(a)).
*
- * @return a quaternion representing the logarithm
+ * @SINCE_1_0.0
+ * @return A quaternion representing the logarithm
*/
Quaternion Log() const;
/**
* @brief Performs an exponent e^Quaternion = Exp(v*a) = (cos(a),vsin(a)).
*
- * @return a quaternion representing the exponent
+ * @SINCE_1_0.0
+ * @return A quaternion representing the exponent
*/
Quaternion Exp() const;
/**
- * @brief Return the dot product of two quaternions.
+ * @brief Returns the dot product of two quaternions.
*
- * @param[in] q1 - the first quaternion
- * @param[in] q2 - the second quaternion
- * @return the dot product of the two quaternions
+ * @SINCE_1_0.0
+ * @param[in] q1 The first quaternion
+ * @param[in] q2 The second quaternion
+ * @return The dot product of the two quaternions
*/
static float Dot( const Quaternion &q1, const Quaternion &q2 );
/**
* @brief Linear Interpolation (using a straight line between the two quaternions).
*
- * @param[in] q1 - the start quaternion
- * @param[in] q2 - the end quaternion
- * @param[in] t - a progress value between 0 and 1
- * @return the interpolated quaternion
+ * @SINCE_1_0.0
+ * @param[in] q1 The start quaternion
+ * @param[in] q2 The end quaternion
+ * @param[in] t A progress value between 0 and 1
+ * @return The interpolated quaternion
*/
static Quaternion Lerp( const Quaternion &q1, const Quaternion &q2, float t );
* @brief Spherical Linear Interpolation (using the shortest arc of a great circle between
* the two quaternions).
*
- * @param[in] q1 - the start quaternion
- * @param[in] q2 - the end quaternion
- * @param[in] progress - a progress value between 0 and 1
- * @return the interpolated quaternion
+ * @SINCE_1_0.0
+ * @param[in] q1 The start quaternion
+ * @param[in] q2 The end quaternion
+ * @param[in] progress A progress value between 0 and 1
+ * @return The interpolated quaternion
*/
static Quaternion Slerp( const Quaternion &q1, const Quaternion &q2, float progress );
/**
* @brief This version of Slerp, used by Squad, does not check for theta > 90.
*
- * @param[in] q1 - the start quaternion
- * @param[in] q2 - the end quaternion
- * @param[in] t - a progress value between 0 and 1
- * @return the interpolated quaternion
+ * @SINCE_1_0.0
+ * @param[in] q1 The start quaternion
+ * @param[in] q2 The end quaternion
+ * @param[in] t A progress value between 0 and 1
+ * @return The interpolated quaternion
*/
static Quaternion SlerpNoInvert( const Quaternion &q1, const Quaternion &q2, float t );
/**
* @brief Spherical Cubic Interpolation.
*
- * @param[in] start - the start quaternion
- * @param[in] end - the end quaternion
- * @param[in] ctrl1 - the control quaternion for q1
- * @param[in] ctrl2 - the control quaternion for q2
- * @param[in] t - a progress value between 0 and 1
- * @return the interpolated quaternion
+ * @SINCE_1_0.0
+ * @param[in] start The start quaternion
+ * @param[in] end The end quaternion
+ * @param[in] ctrl1 The control quaternion for q1
+ * @param[in] ctrl2 The control quaternion for q2
+ * @param[in] t A progress value between 0 and 1
+ * @return The interpolated quaternion
*/
static Quaternion Squad( const Quaternion& start, const Quaternion& end, const Quaternion& ctrl1, const Quaternion& ctrl2, float t );
/**
* @brief Returns the shortest angle between two quaternions in Radians.
*
- * @param[in] q1 - the first quaternion
- * @param[in] q2 - the second quaternion
- * @return the angle between the two quaternions.
+ * @SINCE_1_0.0
+ * @param[in] q1 The first quaternion
+ * @param[in] q2 The second quaternion
+ * @return The angle between the two quaternions
*/
static float AngleBetween( const Quaternion& q1, const Quaternion& q2 );
/**
- * @brief Rotate v by this Quaternion (Quaternion must be unit).
+ * @brief Rotates v by this Quaternion (Quaternion must be unit).
*
- * @param[in] vector a vector to rotate
- * @return the rotated vector
+ * @SINCE_1_0.0
+ * @param[in] vector A vector to rotate
+ * @return The rotated vector
*/
Vector4 Rotate( const Vector4& vector ) const;
/**
- * @brief Rotate v by this Quaternion (Quaternion must be unit).
+ * @brief Rotates v by this Quaternion (Quaternion must be unit).
*
- * @param[in] vector a vector to rotate
- * @return the rotated vector
+ * @SINCE_1_0.0
+ * @param[in] vector A vector to rotate
+ * @return The rotated vector
*/
Vector3 Rotate( const Vector3& vector ) const;
private:
+ /// @cond internal
/**
- * @brief Set the quaternion from 3 orthonormal axes.
+ * @brief Sets the quaternion from 3 orthonormal axes.
*
+ * @SINCE_1_0.0
* @param[in] xAxis The X axis
* @param[in] yAxis The Y axis
* @param[in] zAxis The Z axis
*/
DALI_INTERNAL void SetFromAxes( const Vector3& xAxis, const Vector3& yAxis, const Vector3& zAxis );
+ /// @endcond
public:
};
/**
- * @brief Print a Quaternion.
+ * @brief Prints a Quaternion.
*
- * @param [in] o The output stream operator.
- * @param [in] quaternion The quaternion to print.
- * @return The output stream operator.
+ * @SINCE_1_0.0
+ * @param[in] o The output stream operator
+ * @param[in] quaternion The quaternion to print
+ * @return The output stream operator
*/
-DALI_IMPORT_API std::ostream& operator<< (std::ostream& o, const Quaternion& quaternion);
+DALI_CORE_API std::ostream& operator<< (std::ostream& o, const Quaternion& quaternion);
// Allow Quaternion to be treated as a POD type
template <> struct TypeTraits< Quaternion > : public BasicTypes< Quaternion > { enum { IS_TRIVIAL_TYPE = true }; };
+/**
+ * @}
+ */
} // namespace Dali
#endif // __DALI_QUATERNION_H__
projects / platform / core / uifw / dali-core.git / blobdiff