From 5d0624f03fbe90d01d0a1957f313ba213afc4b3a Mon Sep 17 00:00:00 2001 From: Gawaboumga Date: Wed, 30 Dec 2015 15:30:13 +0100 Subject: [PATCH] Documentation for EulerAngles + change Return of Set Former-commit-id: 7e269b89e880156d66d92cff202095c4e30f344d --- include/Nazara/Math/Config.hpp | 8 +- include/Nazara/Math/EulerAngles.hpp | 14 +- include/Nazara/Math/EulerAngles.inl | 196 +++++++++++++++++++++++++--- 3 files changed, 191 insertions(+), 27 deletions(-) diff --git a/include/Nazara/Math/Config.hpp b/include/Nazara/Math/Config.hpp index f265fdd52..3d27848af 100644 --- a/include/Nazara/Math/Config.hpp +++ b/include/Nazara/Math/Config.hpp @@ -28,15 +28,15 @@ #ifndef NAZARA_CONFIG_MATH_HPP #define NAZARA_CONFIG_MATH_HPP -/// Chaque modification d'un paramètre du module nécessite une recompilation de celui-ci +/// Each modification of a paramater of the module needs a recompilation of the unit -// Définit le radian comme l'unité utilisée pour les angles +// Define the radian as unit for angles #define NAZARA_MATH_ANGLE_RADIAN 0 -// Optimise automatiquement les opérations entre matrices affines (Demande plusieurs comparaisons pour déterminer si une matrice est affine) +// Optimize automatically the operation on affine matrices (Ask several comparisons to determine if the matrix is affine) #define NAZARA_MATH_MATRIX4_CHECK_AFFINE 0 -// Active les tests de sécurité basés sur le code (Conseillé pour le développement) +// Enable tests of security based on the code (Advised for the developpement) #define NAZARA_MATH_SAFE 1 #endif // NAZARA_CONFIG_MATH_HPP diff --git a/include/Nazara/Math/EulerAngles.hpp b/include/Nazara/Math/EulerAngles.hpp index d323fe641..3c9a6b684 100644 --- a/include/Nazara/Math/EulerAngles.hpp +++ b/include/Nazara/Math/EulerAngles.hpp @@ -28,14 +28,14 @@ namespace Nz void MakeZero(); - void Normalize(); + EulerAngles& Normalize(); - void Set(T P, T Y, T R); - void Set(const T angles[3]); - void Set(const EulerAngles& angles); - //void Set(const Matrix3& mat); - void Set(const Quaternion& quat); - template void Set(const EulerAngles& angles); + EulerAngles& Set(T P, T Y, T R); + EulerAngles& Set(const T angles[3]); + EulerAngles& Set(const EulerAngles& angles); + //EulerAngles& Set(const Matrix3& mat); + EulerAngles& Set(const Quaternion& quat); + template EulerAngles& Set(const EulerAngles& angles); //Matrix3 ToRotationMatrix() const; Quaternion ToQuaternion() const; diff --git a/include/Nazara/Math/EulerAngles.inl b/include/Nazara/Math/EulerAngles.inl index 79e3c1ded..3e4eabc6a 100644 --- a/include/Nazara/Math/EulerAngles.inl +++ b/include/Nazara/Math/EulerAngles.inl @@ -14,24 +14,58 @@ namespace Nz { + + /*! + * \class Nz::Vector4 + * \brief Math class that represents an Euler angle. Those describe a rotation transformation by rotating an object on its various axes in specified amounts per axis, and a specified axis order + * + * \remark Rotation are "left-handed", it means that you take your left hand, put your thumb finger in the direction you want and you other fingers represent the way of rotating + */ + + /*! + * \brief Constructs a EulerAngles object from its components + * + * \param P Pitch component = X axis + * \param Y Yaw component = Y axis + * \param R Roll component = Z axis + */ + template EulerAngles::EulerAngles(T P, T Y, T R) { Set(P, Y, R); } + /*! + * \brief Constructs a EulerAngles object from an array of three elements + * + * \param angles[3] angles[0] is pitch component, angles[1] is yaw component and angles[2] is roll component + */ + template EulerAngles::EulerAngles(const T angles[3]) { Set(angles); } + /*! + * \brief Constructs a EulerAngles object from a quaternion + * + * \param quat Quaternion representing a rotation of space + */ + template EulerAngles::EulerAngles(const Quaternion& quat) { Set(quat); } + /*! + * \brief Constructs a EulerAngles object from another type of EulerAngles + * + * \param angles EulerAngles of type U to convert to type T + */ + template template EulerAngles::EulerAngles(const EulerAngles& angles) @@ -39,57 +73,125 @@ namespace Nz Set(angles); } + /*! + * \brief Makes the euler angle (0, 0, 0) + * \return A reference to this euler angle with components (0, 0, 0) + * + * \see Zero + */ + template void EulerAngles::MakeZero() { Set(F(0.0), F(0.0), F(0.0)); } + /*! + * \brief Normalizes the euler angle + * \return A reference to this euler angle with has been normalized + * + * \remark Normalization depends on NAZARA_MATH_ANGLE_RADIAN, between 0..2*pi + * + * \see NormalizeAngle + */ + template - void EulerAngles::Normalize() + EulerAngles& EulerAngles::Normalize() { pitch = NormalizeAngle(pitch); yaw = NormalizeAngle(yaw); roll = NormalizeAngle(roll); + + return *this; } + /*! + * \brief Sets the components of the euler angle + * \return A reference to this euler angle + * + * \param P Pitch component = X axis + * \param Y Yaw component = Y axis + * \param R Roll component = Z axis + */ + template - void EulerAngles::Set(T P, T Y, T R) + EulerAngles& EulerAngles::Set(T P, T Y, T R) { pitch = P; yaw = Y; roll = R; + + return *this; } + /*! + * \brief Sets the components of the euler angle from an array of three elements + * \return A reference to this euler angle + * + * \param angles[3] angles[0] is pitch component, angles[1] is yaw component and angles[2] is roll component + */ + template - void EulerAngles::Set(const T angles[3]) + EulerAngles& EulerAngles::Set(const T angles[3]) { pitch = angles[0]; yaw = angles[1]; roll = angles[2]; + + return *this; } + /*! + * \brief Sets the components of the euler angle from another euler angle + * \return A reference to this euler angle + * + * \param angles The other euler angle + */ + template - void EulerAngles::Set(const EulerAngles& angles) + EulerAngles& EulerAngles::Set(const EulerAngles& angles) { std::memcpy(this, &angles, sizeof(EulerAngles)); + + return *this; } + /*! + * \brief Sets the components of the euler angle from a quaternion + * \return A reference to this euler angle + * + * \param quat Quaternion representing a rotation of space + */ + template - void EulerAngles::Set(const Quaternion& quat) + EulerAngles& EulerAngles::Set(const Quaternion& quat) { - Set(quat.ToEulerAngles()); + return Set(quat.ToEulerAngles()); } + /*! + * \brief Sets the components of the euler angle from another type of EulerAngles + * \return A reference to this euler angle + * + * \param angles EulerAngles of type U to convert its components + */ + template template - void EulerAngles::Set(const EulerAngles& angles) + EulerAngles& EulerAngles::Set(const EulerAngles& angles) { pitch = F(angles.pitch); yaw = F(angles.yaw); roll = F(angles.roll); + + return *this; } + /*! + * \brief Converts the euler angle to quaternion + * \return A Quaternion which represents the rotation of this euler angle + */ + template Quaternion EulerAngles::ToQuaternion() const { @@ -102,11 +204,16 @@ namespace Nz T s3 = std::sin(ToRadians(pitch) / F(2.0)); return Quaternion(c1 * c2 * c3 - s1 * s2 * s3, - s1 * s2 * c3 + c1 * c2 * s3, - s1 * c2 * c3 + c1 * s2 * s3, - c1 * s2 * c3 - s1 * c2 * s3); + s1 * s2 * c3 + c1 * c2 * s3, + s1 * c2 * c3 + c1 * s2 * s3, + c1 * s2 * c3 - s1 * c2 * s3); } + /*! + * \brief Gives a string representation + * \return A string representation of the object: "EulerAngles(pitch, yaw, roll)" + */ + template String EulerAngles::ToString() const { @@ -115,22 +222,43 @@ namespace Nz return ss << "EulerAngles(" << pitch << ", " << yaw << ", " << roll << ')'; } + /*! + * \brief Adds the components of the euler angle with other euler angle + * \return A euler angle where components are the sum of this euler angle and the other one + * + * \param angles The other euler angle to add components with + */ + template EulerAngles EulerAngles::operator+(const EulerAngles& angles) const { return EulerAngles(pitch + angles.pitch, - yaw + angles.yaw, - roll + angles.roll); + yaw + angles.yaw, + roll + angles.roll); } + /*! + * \brief Substracts the components of the euler angle with other euler angle + * \return A euler angle where components are the difference of this euler angle and the other one + * + * \param angles The other euler angle to substract components with + */ + template EulerAngles EulerAngles::operator-(const EulerAngles& angles) const { return EulerAngles(pitch - angles.pitch, - yaw - angles.yaw, - roll - angles.roll); + yaw - angles.yaw, + roll - angles.roll); } + /*! + * \brief Adds the components of other euler angle to this euler angle + * \return A reference to this euler angle where components are the sum of this euler angle and the other one + * + * \param angles The other euler angle to add components with + */ + template EulerAngles& EulerAngles::operator+=(const EulerAngles& angles) { @@ -141,6 +269,13 @@ namespace Nz return *this; } + /*! + * \brief Substracts the components of other euler angle to this euler angle + * \return A reference to this euler angle where components are the difference of this euler angle and the other one + * + * \param angle The other euler angle to substract components with + */ + template EulerAngles& EulerAngles::operator-=(const EulerAngles& angles) { @@ -151,20 +286,41 @@ namespace Nz return *this; } + /*! + * \brief Compares the euler angle to other one + * \return true if the euler angles are the same + * + * \param angles Other euler angle to compare with + */ + template bool EulerAngles::operator==(const EulerAngles& angles) const { return NumberEquals(pitch, angles.pitch) && - NumberEquals(yaw, angles.yaw) && - NumberEquals(roll, angles.roll); + NumberEquals(yaw, angles.yaw) && + NumberEquals(roll, angles.roll); } + /*! + * \brief Compares the euler angle to other one + * \return false if the euler angles are the same + * + * \param angles Other euler angle to compare with + */ + template bool EulerAngles::operator!=(const EulerAngles& angles) const { return !operator==(angles); } + /*! + * \brief Shorthand for the euler angle (0, 0, 0) + * \return A euler angle with components (0, 0, 0) + * + * \see MakeZero + */ + template EulerAngles EulerAngles::Zero() { @@ -175,6 +331,14 @@ namespace Nz } } +/*! +* \brief Output operator +* \return The stream +* +* \param out The stream +* \param angles The euler angle to output +*/ + template std::ostream& operator<<(std::ostream& out, const Nz::EulerAngles& angles) {