From d96cb96d606a06358bcc82efe64170a53f33d10c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Mon, 20 Aug 2012 13:40:49 +0200 Subject: [PATCH] Documented convenience functions on vectors and angles. --- src/Math/Math.h | 16 +++++++++++----- src/Math/Matrix3.h | 4 ++-- src/Math/Matrix4.h | 4 ++-- src/Math/Vector2.h | 16 ++++++++++++++-- src/Math/Vector3.h | 23 ++++++++++++++++++++--- 5 files changed, 49 insertions(+), 14 deletions(-) diff --git a/src/Math/Math.h b/src/Math/Math.h index 21191b360..aa9d77723 100644 --- a/src/Math/Math.h +++ b/src/Math/Math.h @@ -130,17 +130,23 @@ template inline constexpr typename std::ena } /** - * @brief Angle in degrees - * - * Function to make angle entering less error-prone. Converts the value to - * radians at compile time. For example `deg(180.0f)` is converted to `3.14f`. +@brief Angle in degrees + +Function to make angle entering less error-prone. Converts the value to +radians at compile time. For example `deg(180.0f)` is converted to `3.14f`. + +Usable for entering e.g. rotation: +@code +Matrix4::rotation(deg(30.0f), Vector3::yAxis()); +@endcode +@see rad() */ template inline constexpr T deg(T value) { return value*Constants::pi()/180; } /** * @brief Angle in radians * - * See also deg(). + * See deg() for more information. */ template inline constexpr T rad(T value) { return value; } diff --git a/src/Math/Matrix3.h b/src/Math/Matrix3.h index 1dec2c7f3..190aa9832 100644 --- a/src/Math/Matrix3.h +++ b/src/Math/Matrix3.h @@ -36,7 +36,7 @@ template class Matrix3: public Matrix<3, T> { * @brief 2D translation matrix * @param vec Translation vector * - * @see Matrix4::translation() + * @see Matrix4::translation(), Vector2::xAxis(), Vector2::yAxis() */ inline constexpr static Matrix3 translation(const Vector2& vec) { return Matrix3( /* Column-major! */ @@ -64,7 +64,7 @@ template class Matrix3: public Matrix<3, T> { * @brief 3D rotation matrix * @param angle Rotation angle (counterclockwise, in radians) * - * @see Matrix4::rotation() + * @see Matrix4::rotation(), deg(), rad() */ static Matrix3 rotation(T angle) { return Matrix3( /* Column-major! */ diff --git a/src/Math/Matrix4.h b/src/Math/Matrix4.h index fcecef081..172c05f70 100644 --- a/src/Math/Matrix4.h +++ b/src/Math/Matrix4.h @@ -38,7 +38,7 @@ template class Matrix4: public Matrix<4, T> { * @brief 3D translation matrix * @param vec Translation vector * - * @see Matrix3::translation() + * @see Matrix3::translation(), Vector3::xAxis(), Vector3::yAxis(), Vector3::zAxis() */ inline constexpr static Matrix4 translation(const Vector3& vec) { return Matrix4( /* Column-major! */ @@ -69,7 +69,7 @@ template class Matrix4: public Matrix<4, T> { * @param angle Rotation angle (counterclockwise, in radians) * @param vec Rotation vector * - * @see Matrix3::rotation() + * @see Matrix3::rotation(), Vector3::xAxis(), Vector3::yAxis(), Vector3::zAxis(), deg(), rad() * @todo optimize - Assume the vectors are normalized? */ static Matrix4 rotation(T angle, const Vector3& vec) { diff --git a/src/Math/Vector2.h b/src/Math/Vector2.h index 8bd0e6f35..0caa28b5b 100644 --- a/src/Math/Vector2.h +++ b/src/Math/Vector2.h @@ -26,10 +26,22 @@ namespace Magnum { namespace Math { /** @brief Two-component vector */ template class Vector2: public Vector<2, T> { public: - /** @brief %Vector in direction of X axis */ + /** + * @brief %Vector in direction of X axis + * + * Usable for translation in given axis, for example: + * @code + * Matrix3::translation(Vector2::xAxis(5.0f)); // same as Matrix3::translation({5.0f, 0.0f}); + * @endcode + * @see yAxis() + */ inline constexpr static Vector2 xAxis(T length = T(1)) { return Vector2(length, T()); } - /** @brief %Vector in direction of Y axis */ + /** + * @brief %Vector in direction of Y axis + * + * See xAxis() for more information. + */ inline constexpr static Vector2 yAxis(T length = T(1)) { return Vector2(T(), length); } /** @copydoc Vector::Vector(T) */ diff --git a/src/Math/Vector3.h b/src/Math/Vector3.h index 29edd6df7..13c495332 100644 --- a/src/Math/Vector3.h +++ b/src/Math/Vector3.h @@ -26,13 +26,30 @@ namespace Magnum { namespace Math { /** @brief Three-component vector */ template class Vector3: public Vector<3, T> { public: - /** @brief %Vector in direction of X axis */ + /** + * @brief %Vector in direction of X axis + * + * Usable for translation or rotation along given axis, for example: + * @code + * Matrix4::translation(Vector3::xAxis(5.0f)); // same as Matrix4::translation({5.0f, 0.0f, 0.0f}); + * Matrix4::rotation(deg(30.0f), Vector3::xAxis()); // same as Matrix::rotation(deg(30.0f), {1.0f, 0.0f, 0.0f}); + * @endcode + * @see yAxis(), zAxis() + */ inline constexpr static Vector3 xAxis(T length = T(1)) { return Vector3(length, T(), T()); } - /** @brief %Vector in direction of Y axis */ + /** + * @brief %Vector in direction of Y axis + * + * See xAxis() for more information. + */ inline constexpr static Vector3 yAxis(T length = T(1)) { return Vector3(T(), length, T()); } - /** @brief %Vector in direction of Z axis */ + /** + * @brief %Vector in direction of Z axis + * + * See xAxis() for more information. + */ inline constexpr static Vector3 zAxis(T length = T(1)) { return Vector3(T(), T(), length); } /**