From 81039fc2c912fbd4c8cbc718c4425df8ad16192c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Mon, 12 May 2014 23:40:38 +0200 Subject: [PATCH] Math: completed documentation review. --- src/Magnum/Math/Algorithms/GaussJordan.h | 9 +- src/Magnum/Math/Algorithms/GramSchmidt.h | 10 +- src/Magnum/Math/Algorithms/Svd.h | 2 +- src/Magnum/Math/Angle.h | 20 ++-- src/Magnum/Math/BoolVector.h | 12 ++- src/Magnum/Math/Complex.h | 58 +++++++---- src/Magnum/Math/Constants.h | 6 +- src/Magnum/Math/Dual.h | 6 +- src/Magnum/Math/DualComplex.h | 47 +++++---- src/Magnum/Math/DualQuaternion.h | 81 ++++++++------- src/Magnum/Math/Functions.h | 14 +-- src/Magnum/Math/Geometry/Distance.h | 29 +++--- src/Magnum/Math/Geometry/Intersection.h | 6 +- src/Magnum/Math/Math.h | 2 +- src/Magnum/Math/Matrix.h | 24 +++-- src/Magnum/Math/Matrix3.h | 87 +++++++++------- src/Magnum/Math/Matrix4.h | 123 ++++++++++++++--------- src/Magnum/Math/Quaternion.h | 91 ++++++++++------- src/Magnum/Math/Range.h | 6 +- src/Magnum/Math/RectangularMatrix.h | 60 ++++++----- src/Magnum/Math/Swizzle.h | 2 +- src/Magnum/Math/TypeTraits.h | 6 +- src/Magnum/Math/Unit.h | 4 +- src/Magnum/Math/Vector.h | 88 ++++++++++------ src/Magnum/Math/Vector2.h | 28 +++--- src/Magnum/Math/Vector3.h | 9 +- src/Magnum/Math/Vector4.h | 3 +- 27 files changed, 497 insertions(+), 336 deletions(-) diff --git a/src/Magnum/Math/Algorithms/GaussJordan.h b/src/Magnum/Math/Algorithms/GaussJordan.h index c978e3199..b749696dc 100644 --- a/src/Magnum/Math/Algorithms/GaussJordan.h +++ b/src/Magnum/Math/Algorithms/GaussJordan.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Function Magnum::Math::Algorithms::gaussJordanInPlaceTransposed(), Magnum::Math::Algorithms::gaussJordanInPlace() + * @brief Function @ref Magnum::Math::Algorithms::gaussJordanInPlaceTransposed(), @ref Magnum::Math::Algorithms::gaussJordanInPlace() */ #include "Magnum/Math/RectangularMatrix.h" @@ -42,7 +42,8 @@ namespace Magnum { namespace Math { namespace Algorithms { As Gauss-Jordan elimination works on rows and matrices in OpenGL are column-major, it is more efficient to operate on transposed matrices and treat -columns as rows. See also gaussJordanInPlace() which works with non-transposed matrices. +columns as rows. See also @ref gaussJordanInPlace() which works with +non-transposed matrices. The function eliminates matrix @p a and solves @p t in place. For efficiency reasons, only pure Gaussian elimination is done on @p a and the final @@ -94,8 +95,8 @@ template bool gaussJordanInPlaceTra /** @brief In-place Gauss-Jordan elimination -Transposes the matrices, calls gaussJordanInPlaceTransposed() on them and then -transposes them back. +Transposes the matrices, calls @ref gaussJordanInPlaceTransposed() on them and +then transposes them back. */ template bool gaussJordanInPlace(RectangularMatrix& a, RectangularMatrix& t) { a = a.transposed(); diff --git a/src/Magnum/Math/Algorithms/GramSchmidt.h b/src/Magnum/Math/Algorithms/GramSchmidt.h index 2e1ec677b..a35aa392e 100644 --- a/src/Magnum/Math/Algorithms/GramSchmidt.h +++ b/src/Magnum/Math/Algorithms/GramSchmidt.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Function Magnum::Math::Algorithms::gramSchmidtOrthogonalizeInPlace(), Magnum::Math::Algorithms::gramSchmidtOrthogonalize(), Magnum::Math::Algorithms::gramSchmidtOrthonormalizeInPlace(), Magnum::Math::Algorithms::gramSchmidtOrthonormalize() + * @brief Function @ref Magnum::Math::Algorithms::gramSchmidtOrthogonalizeInPlace(), @ref Magnum::Math::Algorithms::gramSchmidtOrthogonalize(), @ref Magnum::Math::Algorithms::gramSchmidtOrthonormalizeInPlace(), @ref Magnum::Math::Algorithms::gramSchmidtOrthonormalize() */ #include "Magnum/Math/RectangularMatrix.h" @@ -48,8 +48,8 @@ template void gramSchmidtOrthogonal /** @brief Gram-Schmidt matrix orthogonalization -Unlike gramSchmidtOrthogonalizeInPlace() returns the modified matrix instead -of performing the orthogonalization in-place. +Unlike @ref gramSchmidtOrthogonalizeInPlace() returns the modified matrix +instead of performing the orthogonalization in-place. */ template RectangularMatrix gramSchmidtOrthogonalize(RectangularMatrix matrix) { gramSchmidtOrthogonalizeInPlace(matrix); @@ -72,8 +72,8 @@ template void gramSchmidtOrthonorma /** @brief Gram-Schmidt matrix orthonormalization -Unlike gramSchmidtOrthonormalizeInPlace() returns the modified matrix instead -of performing the orthonormalization in-place. +Unlike @ref gramSchmidtOrthonormalizeInPlace() returns the modified matrix +instead of performing the orthonormalization in-place. */ template RectangularMatrix gramSchmidtOrthonormalize(RectangularMatrix matrix) { gramSchmidtOrthonormalizeInPlace(matrix); diff --git a/src/Magnum/Math/Algorithms/Svd.h b/src/Magnum/Math/Algorithms/Svd.h index e53c24ddf..c8db73760 100644 --- a/src/Magnum/Math/Algorithms/Svd.h +++ b/src/Magnum/Math/Algorithms/Svd.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Function Magnum::Math::Algorithms::svd() + * @brief Function @ref Magnum::Math::Algorithms::svd() */ #include diff --git a/src/Magnum/Math/Angle.h b/src/Magnum/Math/Angle.h index f67811fb3..f75447f0a 100644 --- a/src/Magnum/Math/Angle.h +++ b/src/Magnum/Math/Angle.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::Math::Deg, Magnum::Math::Rad and related operators. + * @brief Class @ref Magnum::Math::Deg, @ref Magnum::Math::Rad and related operators. */ #include @@ -119,7 +119,7 @@ std::sin(Float(Rad(b)); // required explicit conversion hints to user // (i.e., conversion to radians) @endcode -@see Magnum::Deg, Magnum::Degd +@see @ref Magnum::Deg, @ref Magnum::Degd */ template class Deg: public Unit { public: @@ -157,7 +157,8 @@ Double cosine = Math::cos(60.0_deg); // cosine = 0.5 Double cosine = Math::cos(1.047_rad); // cosine = 0.5 @endcode @see Magnum::operator""_deg(), operator""_degf(), operator""_rad() -@note Not available on GCC < 4.7. Use Deg::Deg(T) instead. +@todoc Make references explicit when Doxygen can link to operator"" +@note Not available on GCC < 4.7. Use @ref Deg::Deg(T) instead. @requires_gl Only single-precision types are available in OpenGL ES. */ constexpr Deg operator "" _deg(long double value) { return Deg(value); } @@ -172,7 +173,8 @@ Float tangent = Math::tan(60.0_degf); // tangent = 1.732f Float tangent = Math::tan(1.047_radf); // tangent = 1.732f @endcode @see Magnum::operator""_degf(), operator""_deg(), operator""_radf() -@note Not available on GCC < 4.7. Use Deg::Deg(T) instead. +@todoc Make references explicit when Doxygen can link to operator"" +@note Not available on GCC < 4.7. Use @ref Deg::Deg(T) instead. @requires_gl Only single-precision types are available in OpenGL ES. */ constexpr Deg operator "" _degf(long double value) { return Deg(value); } @@ -181,8 +183,8 @@ constexpr Deg operator "" _degf(long double value) { return Deg(va /** @brief Angle in radians -See Deg for more information. -@see Magnum::Rad, Magnum::Radd +See @ref Deg for more information. +@see @ref Magnum::Rad, @ref Magnum::Radd */ template class Rad: public Unit { public: @@ -216,7 +218,8 @@ template class Rad: public Unit { See operator""_rad() for more information. @see Magnum::operator""_rad(), operator""_radf(), operator""_deg() -@note Not available on GCC < 4.7. Use Rad::Rad(T) instead. +@todoc Make references explicit when Doxygen can link to operator"" +@note Not available on GCC < 4.7. Use @ref Rad::Rad(T) instead. */ constexpr Rad operator "" _rad(long double value) { return Rad(value); } #endif @@ -226,7 +229,8 @@ constexpr Rad operator "" _rad(long double value) { return Rad(v See operator""_degf() for more information. @see Magnum::operator""_radf(), operator""_rad(), operator""_degf() -@note Not available on GCC < 4.7. Use Rad::Rad(T) instead. +@todoc Make references explicit when Doxygen can link to operator"" +@note Not available on GCC < 4.7. Use @ref Rad::Rad(T) instead. */ constexpr Rad operator "" _radf(long double value) { return Rad(value); } #endif diff --git a/src/Magnum/Math/BoolVector.h b/src/Magnum/Math/BoolVector.h index 58d74f6f8..03da7127b 100644 --- a/src/Magnum/Math/BoolVector.h +++ b/src/Magnum/Math/BoolVector.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::Math::BoolVector + * @brief Class @ref Magnum::Math::BoolVector */ #include @@ -59,8 +59,8 @@ namespace Implementation { Result of component-wise comparison from Vector. The boolean values are stored as bits in array of unsigned bytes, unused bits have undefined value which -doesn't affect comparison or all() / none() / any() functions. See also -@ref matrix-vector for brief introduction. +doesn't affect comparison or @ref all() / @ref none() / @ref any() functions. +See also @ref matrix-vector for brief introduction. */ template class BoolVector { static_assert(size != 0, "BoolVector cannot have zero elements"); @@ -106,7 +106,8 @@ template class BoolVector { * @brief Raw data * @return %Array of DataSize length * - * @see operator[](), set() + * @todoc Make reference explicit when Doxygen can link to operator[] + * @see operator[](), @ref set() */ UnsignedByte* data() { return _data; } constexpr const UnsignedByte* data() const { return _data; } /**< @overload */ @@ -158,6 +159,7 @@ template class BoolVector { * @brief Bitwise AND * * @see operator&=() + * @todoc Make explicit reference when Doxygen can handle operators */ BoolVector operator&(const BoolVector& other) const { return BoolVector(*this) &= other; @@ -179,6 +181,7 @@ template class BoolVector { * @brief Bitwise OR * * @see operator|=() + * @todoc Make explicit reference when Doxygen can handle operators */ BoolVector operator|(const BoolVector& other) const { return BoolVector(*this) |= other; @@ -200,6 +203,7 @@ template class BoolVector { * @brief Bitwise XOR * * @see operator^=() + * @todoc Make explicit reference when Doxygen can handle operators */ BoolVector operator^(const BoolVector& other) const { return BoolVector(*this) ^= other; diff --git a/src/Magnum/Math/Complex.h b/src/Magnum/Math/Complex.h index 84c97fd31..ab8fd8b4a 100644 --- a/src/Magnum/Math/Complex.h +++ b/src/Magnum/Math/Complex.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::Math::Complex + * @brief Class @ref Magnum::Math::Complex */ #include @@ -51,11 +51,11 @@ namespace Implementation { @tparam T Data type Represents 2D rotation. See @ref transformations for brief introduction. -@see Magnum::Complex, Magnum::Complexd, Matrix3 +@see @ref Magnum::Complex, @ref Magnum::Complexd, @ref Matrix3 */ template class Complex { public: - typedef T Type; /**< @brief Underlying data type */ + typedef T Type; /**< @brief Underlying data type */ /** * @brief Dot product @@ -64,6 +64,7 @@ template class Complex { * c_0 \cdot c_1 = a_0 a_1 + b_0 b_1 * @f] * @see dot() const + * @todoc Explicit reference when Doxygen can handle const */ static T dot(const Complex& a, const Complex& b) { return a._real*b._real + a._imaginary*b._imaginary; @@ -75,7 +76,8 @@ template class Complex { * Expects that both complex numbers are normalized. @f[ * \theta = acos \left( \frac{Re(c_0 \cdot c_1))}{|c_0| |c_1|} \right) = acos (a_0 a_1 + b_0 b_1) * @f] - * @see isNormalized(), Quaternion::angle(), Vector::angle() + * @see @ref isNormalized(), @ref Quaternion::angle(), + * @ref Vector::angle() */ static Rad angle(const Complex& normalizedA, const Complex& normalizedB) { CORRADE_ASSERT(normalizedA.isNormalized() && normalizedB.isNormalized(), @@ -90,7 +92,8 @@ template class Complex { * @f[ * c = cos \theta + i sin \theta * @f] - * @see angle(), Matrix3::rotation(), Quaternion::rotation() + * @see @ref angle(), @ref Matrix3::rotation(), + * @ref Quaternion::rotation() */ static Complex rotation(Rad angle) { return {std::cos(T(angle)), std::sin(T(angle))}; @@ -100,7 +103,8 @@ template class Complex { * @brief Create complex number from rotation matrix * * Expects that the matrix is orthogonal (i.e. pure rotation). - * @see toMatrix(), DualComplex::fromMatrix(), Matrix::isOrthogonal() + * @see @ref toMatrix(), @ref DualComplex::fromMatrix(), + * @ref Matrix::isOrthogonal() */ static Complex fromMatrix(const Matrix<2, T>& matrix) { CORRADE_ASSERT(matrix.isOrthogonal(), @@ -132,7 +136,8 @@ template class Complex { * To be used in transformations later. @f[ * c = v_x + iv_y * @f] - * @see operator Vector2(), transformVector() + * @see operator Vector2(), @ref transformVector() + * @todoc Make explicit reference when Doxygen can handle operators */ constexpr explicit Complex(const Vector2& vector): _real(vector.x()), _imaginary(vector.y()) {} @@ -153,7 +158,7 @@ template class Complex { * Complex number is normalized if it has unit length: @f[ * |c \cdot c - 1| < 2 \epsilon + \epsilon^2 \cong 2 \epsilon * @f] - * @see dot(), normalized() + * @see @ref dot(), @ref normalized() */ bool isNormalized() const { return Implementation::isNormalizedSquared(dot()); @@ -182,7 +187,7 @@ template class Complex { * @f[ * \theta = atan2(b, a) * @f] - * @see rotation() + * @see @ref rotation() */ Rad angle() const { return Rad(std::atan2(_imaginary, _real)); @@ -197,8 +202,8 @@ template class Complex { * b & a * \end{pmatrix} * @f] - * @see fromMatrix(), DualComplex::toMatrix(), - * Matrix3::from(const Matrix<2, T>&, const Vector2&) + * @see @ref fromMatrix(), @ref DualComplex::toMatrix(), + * @ref Matrix3::from(const Matrix<2, T>&, const Vector2&) */ Matrix<2, T> toMatrix() const { return {Vector<2, T>(_real, _imaginary), @@ -222,6 +227,7 @@ template class Complex { * @brief Add complex number * * @see operator+=() + * @todoc Explicit reference when Doxygen can handle operators */ Complex operator+(const Complex& other) const { return Complex(*this) += other; @@ -255,6 +261,7 @@ template class Complex { * @brief Subtract complex number * * @see operator-=() + * @todoc Make explicit reference when Doxygen can handle operators */ Complex operator-(const Complex& other) const { return Complex(*this) -= other; @@ -277,6 +284,7 @@ template class Complex { * @brief Multiply with scalar * * @see operator*=(T) + * @todoc Make explicit reference when Doxygen can handle operators */ Complex operator*(T scalar) const { return Complex(*this) *= scalar; @@ -299,6 +307,7 @@ template class Complex { * @brief Divide with scalar * * @see operator/=(T) + * @todoc Make explicit reference when Doxygen can handle operators */ Complex operator/(T scalar) const { return Complex(*this) /= scalar; @@ -319,11 +328,12 @@ template class Complex { /** * @brief Dot product of the complex number * - * Should be used instead of length() for comparing complex number length - * with other values, because it doesn't compute the square root. @f[ + * Should be used instead of @ref length() for comparing complex number + * length with other values, because it doesn't compute the square + * root. @f[ * c \cdot c = a^2 + b^2 * @f] - * @see dot(const Complex&, const Complex&), isNormalized() + * @see @ref dot(const Complex&, const Complex&), @ref isNormalized() */ T dot() const { return dot(*this, *this); @@ -332,11 +342,11 @@ template class Complex { /** * @brief %Complex number length * - * See also dot() const which is faster for comparing length with other - * values. @f[ + * See also @ref dot() const which is faster for comparing length with + * other values. @f[ * |c| = \sqrt{c \cdot c} * @f] - * @see isNormalized() + * @see @ref isNormalized() */ T length() const { /** @todo Remove when newlib has this fixed */ @@ -350,7 +360,7 @@ template class Complex { /** * @brief Normalized complex number (of unit length) * - * @see isNormalized() + * @see @ref isNormalized() */ Complex normalized() const { return (*this)/length(); @@ -370,7 +380,7 @@ template class Complex { /** * @brief Inverted complex number * - * See invertedNormalized() which is faster for normalized + * See @ref invertedNormalized() which is faster for normalized * complex numbers. @f[ * c^{-1} = \frac{c^*}{|c|^2} = \frac{c^*}{c \cdot c} * @f] @@ -382,11 +392,11 @@ template class Complex { /** * @brief Inverted normalized complex number * - * Equivalent to conjugated(). Expects that the complex number is + * Equivalent to @ref conjugated(). Expects that the complex number is * normalized. @f[ * c^{-1} = \frac{c^*}{c \cdot c} = c^* * @f] - * @see isNormalized(), inverted() + * @see @ref isNormalized(), @ref inverted() */ Complex invertedNormalized() const { CORRADE_ASSERT(isNormalized(), @@ -401,7 +411,9 @@ template class Complex { * @f[ * v' = c v = c (v_x + iv_y) * @f] - * @see Complex(const Vector2&), operator Vector2(), Matrix3::transformVector() + * @see @ref Complex(const Vector2&), operator Vector2(), + * @ref Matrix3::transformVector() + * @todoc Make explicit reference when Doxygen can handle operators */ Vector2 transformVector(const Vector2& vector) const { return Vector2((*this)*Complex(vector)); @@ -415,6 +427,7 @@ template class Complex { @brief Multiply scalar with complex Same as Complex::operator*(T) const. +@todoc Make explicit reference when Doxygen can handle operators */ template inline Complex operator*(T scalar, const Complex& complex) { return complex*scalar; @@ -427,6 +440,7 @@ template inline Complex operator*(T scalar, const Complex& comple \frac t c = \frac t a + i \frac t b @f] @see Complex::operator/() +@todoc Make explicit reference when Doxygen can handle operators */ template inline Complex operator/(T scalar, const Complex& complex) { return {scalar/complex.real(), scalar/complex.imaginary()}; diff --git a/src/Magnum/Math/Constants.h b/src/Magnum/Math/Constants.h index 576e8f7f9..fc14397f6 100644 --- a/src/Magnum/Math/Constants.h +++ b/src/Magnum/Math/Constants.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::Math::Constants + * @brief Class @ref Magnum::Math::Constants */ #include "Magnum/Types.h" @@ -36,7 +36,7 @@ namespace Magnum { namespace Math { /** @brief Numeric constants -@see Magnum::Constants, Magnum::Constantsd +@see @ref Magnum::Constants, @ref Magnum::Constantsd */ template struct Constants { Constants() = delete; @@ -46,7 +46,7 @@ template struct Constants { /** * @brief Pi * - * @see Deg, Rad + * @see @ref Deg, @ref Rad */ static constexpr T pi(); diff --git a/src/Magnum/Math/Dual.h b/src/Magnum/Math/Dual.h index dacb48869..982a311c3 100644 --- a/src/Magnum/Math/Dual.h +++ b/src/Magnum/Math/Dual.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::Math::Dual + * @brief Class @ref Magnum::Math::Dual */ #include @@ -96,6 +96,7 @@ template class Dual { * @brief Add dual number * * @see operator+=() + * @todoc Make explicit reference when Doxygen can handle operators */ Dual operator+(const Dual& other) const { return Dual(*this)+=other; @@ -129,6 +130,7 @@ template class Dual { * @brief Subtract dual number * * @see operator-=() + * @todoc Make explicit reference when Doxygen can handle operators */ Dual operator-(const Dual& other) const { return Dual(*this)-=other; @@ -213,7 +215,7 @@ template Corrade::Utility::Debug operator<<(Corrade::Utility::Debug deb @f[ \sqrt{\hat a} = \sqrt{a_0} + \epsilon \frac{a_\epsilon}{2 \sqrt{a_0}} @f] -@see Math::sqrt(const T&) +@see @ref Math::sqrt(const T&) */ template Dual sqrt(const Dual& dual) { T sqrt0 = std::sqrt(dual.real()); diff --git a/src/Magnum/Math/DualComplex.h b/src/Magnum/Math/DualComplex.h index d5109510a..0b5ba54f8 100644 --- a/src/Magnum/Math/DualComplex.h +++ b/src/Magnum/Math/DualComplex.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::Math::DualComplex + * @brief Class @ref Magnum::Math::DualComplex */ #include "Magnum/Math/Complex.h" @@ -41,7 +41,8 @@ namespace Magnum { namespace Math { Represents 2D rotation and translation. See @ref transformations for brief introduction. -@see Magnum::DualComplex, Magnum::DualComplexd, Dual, Complex, Matrix3 +@see @ref Magnum::DualComplex, @ref Magnum::DualComplexd, @ref Dual, + @ref Complex, @ref Matrix3 @todo Can this be done similarly as in dual quaternions? It sort of works, but the math beneath is weird. */ @@ -56,8 +57,8 @@ template class DualComplex: public Dual> { * @f[ * \hat c = (cos \theta + i sin \theta) + \epsilon (0 + i0) * @f] - * @see angle(), Complex::rotation(), Matrix3::rotation(), - * DualQuaternion::rotation() + * @see @ref Complex::rotation(), @ref Matrix3::rotation(), + * @ref DualQuaternion::rotation() */ static DualComplex rotation(Rad angle) { return {Complex::rotation(angle), {{}, {}}}; @@ -70,8 +71,11 @@ template class DualComplex: public Dual> { * @f[ * \hat c = (0 + i1) + \epsilon (v_x + iv_y) * @f] - * @see translation() const, Matrix3::translation(const Vector2&), - * DualQuaternion::translation(), Vector2::xAxis(), Vector2::yAxis() + * @see translation() const, + * @ref Matrix3::translation(const Vector2&), + * @ref DualQuaternion::translation(), @ref Vector2::xAxis(), + * @ref Vector2::yAxis() + * @todoc Explicit reference when Doxygen can handle const */ static DualComplex translation(const Vector2& vector) { return {{}, {vector.x(), vector.y()}}; @@ -81,8 +85,8 @@ template class DualComplex: public Dual> { * @brief Create dual complex number from rotation matrix * * Expects that the matrix represents rigid transformation. - * @see toMatrix(), Complex::fromMatrix(), - * Matrix3::isRigidTransformation() + * @see @ref toMatrix(), @ref Complex::fromMatrix(), + * @ref Matrix3::isRigidTransformation() */ static DualComplex fromMatrix(const Matrix3& matrix) { CORRADE_ASSERT(matrix.isRigidTransformation(), @@ -136,7 +140,7 @@ template class DualComplex: public Dual> { * Dual complex number is normalized if its real part has unit length: @f[ * |c_0|^2 = |c_0| = 1 * @f] - * @see Complex::dot(), normalized() + * @see @ref Complex::dot(), @ref normalized() * @todoc Improve the equation as in Complex::isNormalized() */ bool isNormalized() const { @@ -146,7 +150,7 @@ template class DualComplex: public Dual> { /** * @brief Rotation part of dual complex number * - * @see Complex::angle() + * @see @ref Complex::angle() */ constexpr Complex rotation() const { return Dual>::real(); @@ -158,7 +162,7 @@ template class DualComplex: public Dual> { * @f[ * \boldsymbol a = (c_\epsilon c_0^*) * @f] - * @see translation(const Vector2&) + * @see @ref translation(const Vector2&) */ Vector2 translation() const { return Vector2(Dual>::dual()); @@ -167,7 +171,7 @@ template class DualComplex: public Dual> { /** * @brief Convert dual complex number to transformation matrix * - * @see fromMatrix(), Complex::toMatrix() + * @see @ref fromMatrix(), @ref Complex::toMatrix() */ Matrix3 toMatrix() const { return Matrix3::from(Dual>::real().toMatrix(), translation()); @@ -191,7 +195,8 @@ template class DualComplex: public Dual> { * @f[ * \hat c^* = c^*_0 + c^*_\epsilon * @f] - * @see dualConjugated(), conjugated(), Complex::conjugated() + * @see @ref dualConjugated(), @ref conjugated(), + * @ref Complex::conjugated() */ DualComplex complexConjugated() const { return {Dual>::real().conjugated(), Dual>::dual().conjugated()}; @@ -203,7 +208,8 @@ template class DualComplex: public Dual> { * @f[ * \overline{\hat c} = c_0 - \epsilon c_\epsilon * @f] - * @see complexConjugated(), conjugated(), Dual::conjugated() + * @see @ref complexConjugated(), @ref conjugated(), + * @ref Dual::conjugated() */ DualComplex dualConjugated() const { return Dual>::conjugated(); @@ -215,8 +221,8 @@ template class DualComplex: public Dual> { * Both complex and dual conjugation. @f[ * \overline{\hat c^*} = c^*_0 - \epsilon c^*_\epsilon = c^*_0 + \epsilon(-a_\epsilon + ib_\epsilon) * @f] - * @see complexConjugated(), dualConjugated(), Complex::conjugated(), - * Dual::conjugated() + * @see @ref complexConjugated(), @ref dualConjugated(), + * @ref Complex::conjugated(), @ref Dual::conjugated() */ DualComplex conjugated() const { return {Dual>::real().conjugated(), {-Dual>::dual().real(), Dual>::dual().imaginary()}}; @@ -254,7 +260,7 @@ template class DualComplex: public Dual> { * @f[ * c' = \frac{c_0}{|c_0|} * @f] - * @see isNormalized() + * @see @ref isNormalized() * @todo can this be done similarly to dual quaternions? */ DualComplex normalized() const { @@ -280,7 +286,7 @@ template class DualComplex: public Dual> { * Expects that the complex number is normalized. @f[ * \hat c^{-1} = c_0^{-1} - \epsilon c_\epsilon = c_0^* - \epsilon c_\epsilon * @f] - * @see isNormalized(), inverted() + * @see @ref isNormalized(), @ref inverted() * @todo can this be done similarly to dual quaternions? */ DualComplex invertedNormalized() const { @@ -294,8 +300,9 @@ template class DualComplex: public Dual> { * complex number. @f[ * v' = \hat c v = \hat c ((0 + i) + \epsilon(v_x + iv_y)) * @f] - * @see DualComplex(const Vector2&), dual(), Matrix3::transformPoint(), - * Complex::transformVector(), DualQuaternion::transformPoint() + * @see @ref DualComplex(const Vector2&), @ref dual(), + * @ref Matrix3::transformPoint(), @ref Complex::transformVector(), + * @ref DualQuaternion::transformPoint() */ Vector2 transformPoint(const Vector2& vector) const { return Vector2(((*this)*DualComplex(vector)).dual()); diff --git a/src/Magnum/Math/DualQuaternion.h b/src/Magnum/Math/DualQuaternion.h index 020459421..8c086ffa3 100644 --- a/src/Magnum/Math/DualQuaternion.h +++ b/src/Magnum/Math/DualQuaternion.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::Math::DualQuaternion + * @brief Class @ref Magnum::Math::DualQuaternion */ #include "Magnum/Math/Dual.h" @@ -41,7 +41,8 @@ namespace Magnum { namespace Math { Represents 3D rotation and translation. See @ref transformations for brief introduction. -@see Magnum::DualQuaternion, Magnum::DualQuaterniond, Dual, Quaternion, Matrix4 +@see @ref Magnum::DualQuaternion, @ref Magnum::DualQuaterniond, @ref Dual, + @ref Quaternion, @ref Matrix4 */ template class DualQuaternion: public Dual> { public: @@ -55,9 +56,11 @@ template class DualQuaternion: public Dual> { * Expects that the rotation axis is normalized. @f[ * \hat q = [\boldsymbol a \cdot sin \frac \theta 2, cos \frac \theta 2] + \epsilon [\boldsymbol 0, 0] * @f] - * @see rotation() const, Quaternion::rotation(), Matrix4::rotation(), - * DualComplex::rotation(), Vector3::xAxis(), Vector3::yAxis(), - * Vector3::zAxis(), Vector::isNormalized() + * @see rotation() const, @ref Quaternion::rotation(), + * @ref Matrix4::rotation(), @ref DualComplex::rotation(), + * @ref Vector3::xAxis(), @ref Vector3::yAxis(), + * @ref Vector3::zAxis(), @ref Vector::isNormalized() + * @todoc Explicit reference when Doxygen can handle const */ static DualQuaternion rotation(Rad angle, const Vector3& normalizedAxis) { return {Quaternion::rotation(angle, normalizedAxis), {{}, T(0)}}; @@ -72,9 +75,11 @@ template class DualQuaternion: public Dual> { * @f[ * \hat q = [\boldsymbol 0, 1] + \epsilon [\frac{\boldsymbol v}{2}, 0] * @f] - * @see translation() const, Matrix4::translation(const Vector3&), - * DualComplex::translation(), Vector3::xAxis(), Vector3::yAxis(), - * Vector3::zAxis() + * @see translation() const, + * @ref Matrix4::translation(const Vector3&), + * @ref DualComplex::translation(), @ref Vector3::xAxis(), + * @ref Vector3::yAxis(), @ref Vector3::zAxis() + * @todoc Explicit reference when Doxygen can handle const */ static DualQuaternion translation(const Vector3& vector) { return {{}, {vector/T(2), T(0)}}; @@ -84,8 +89,8 @@ template class DualQuaternion: public Dual> { * @brief Create dual quaternion from transformation matrix * * Expects that the matrix represents rigid transformation. - * @see toMatrix(), Quaternion::fromMatrix(), - * Matrix4::isRigidTransformation() + * @see @ref toMatrix(), @ref Quaternion::fromMatrix(), + * @ref Matrix4::isRigidTransformation() */ static DualQuaternion fromMatrix(const Matrix4& matrix) { CORRADE_ASSERT(matrix.isRigidTransformation(), @@ -124,7 +129,7 @@ template class DualQuaternion: public Dual> { * To be used in transformations later. @f[ * \hat q = [\boldsymbol 0, 1] + \epsilon [\boldsymbol v, 0] * @f] - * @see transformPointNormalized() + * @see @ref transformPointNormalized() * @todoc Remove workaround when Doxygen is predictable */ #ifdef DOXYGEN_GENERATING_OUTPUT @@ -142,7 +147,7 @@ template class DualQuaternion: public Dual> { * Dual quaternion is normalized if it has unit length: @f[ * |\hat q|^2 = |\hat q| = 1 + \epsilon 0 * @f] - * @see lengthSquared(), normalized() + * @see @ref lengthSquared(), @ref normalized() * @todoc Improve the equation as in Quaternion::isNormalized() */ bool isNormalized() const { @@ -156,7 +161,7 @@ template class DualQuaternion: public Dual> { /** * @brief Rotation part of unit dual quaternion * - * @see Quaternion::angle(), Quaternion::axis() + * @see @ref Quaternion::angle(), @ref Quaternion::axis() */ constexpr Quaternion rotation() const { return Dual>::real(); @@ -168,7 +173,7 @@ template class DualQuaternion: public Dual> { * @f[ * \boldsymbol a = 2 (q_\epsilon q_0^*)_V * @f] - * @see translation(const Vector3&) + * @see @ref translation(const Vector3&) */ Vector3 translation() const { return (Dual>::dual()*Dual>::real().conjugated()).vector()*T(2); @@ -177,7 +182,7 @@ template class DualQuaternion: public Dual> { /** * @brief Convert dual quaternion to transformation matrix * - * @see fromMatrix(), Quaternion::toMatrix() + * @see @ref fromMatrix(), @ref Quaternion::toMatrix() */ Matrix4 toMatrix() const { return Matrix4::from(Dual>::real().toMatrix(), translation()); @@ -189,7 +194,8 @@ template class DualQuaternion: public Dual> { * @f[ * \hat q^* = q_0^* + q_\epsilon^* * @f] - * @see dualConjugated(), conjugated(), Quaternion::conjugated() + * @see @ref dualConjugated(), @ref conjugated(), + * @ref Quaternion::conjugated() */ DualQuaternion quaternionConjugated() const { return {Dual>::real().conjugated(), Dual>::dual().conjugated()}; @@ -201,7 +207,8 @@ template class DualQuaternion: public Dual> { * @f[ * \overline{\hat q} = q_0 - \epsilon q_\epsilon * @f] - * @see quaternionConjugated(), conjugated(), Dual::conjugated() + * @see @ref quaternionConjugated(), @ref conjugated(), + * @ref Dual::conjugated() */ DualQuaternion dualConjugated() const { return Dual>::conjugated(); @@ -213,8 +220,8 @@ template class DualQuaternion: public Dual> { * Both quaternion and dual conjugation. @f[ * \overline{\hat q^*} = q_0^* - \epsilon q_\epsilon^* = q_0^* + \epsilon [\boldsymbol q_{V \epsilon}, -q_{S \epsilon}] * @f] - * @see quaternionConjugated(), dualConjugated(), Quaternion::conjugated(), - * Dual::conjugated() + * @see @ref quaternionConjugated(), @ref dualConjugated(), + * @ref Quaternion::conjugated(), @ref Dual::conjugated() */ DualQuaternion conjugated() const { return {Dual>::real().conjugated(), {Dual>::dual().vector(), -Dual>::dual().scalar()}}; @@ -223,8 +230,9 @@ template class DualQuaternion: public Dual> { /** * @brief %Dual quaternion length squared * - * Should be used instead of length() for comparing dual quaternion - * length with other values, because it doesn't compute the square root. @f[ + * Should be used instead of @ref length() for comparing dual + * quaternion length with other values, because it doesn't compute the + * square root. @f[ * |\hat q|^2 = \sqrt{\hat q^* \hat q}^2 = q_0 \cdot q_0 + \epsilon 2 (q_0 \cdot q_\epsilon) * @f] */ @@ -235,7 +243,7 @@ template class DualQuaternion: public Dual> { /** * @brief %Dual quaternion length * - * See lengthSquared() which is faster for comparing length with other + * See @ref lengthSquared() which is faster for comparing length with other * values. @f[ * |\hat q| = \sqrt{\hat q^* \hat q} = |q_0| + \epsilon \frac{q_0 \cdot q_\epsilon}{|q_0|} * @f] @@ -247,7 +255,7 @@ template class DualQuaternion: public Dual> { /** * @brief Normalized dual quaternion (of unit length) * - * @see isNormalized() + * @see @ref isNormalized() */ DualQuaternion normalized() const { return (*this)/length(); @@ -256,7 +264,7 @@ template class DualQuaternion: public Dual> { /** * @brief Inverted dual quaternion * - * See invertedNormalized() which is faster for normalized dual + * See @ref invertedNormalized() which is faster for normalized dual * quaternions. @f[ * \hat q^{-1} = \frac{\hat q^*}{|\hat q|^2} * @f] @@ -268,11 +276,11 @@ template class DualQuaternion: public Dual> { /** * @brief Inverted normalized dual quaternion * - * Equivalent to quaternionConjugated(). Expects that the quaternion is - * normalized. @f[ + * Equivalent to @ref quaternionConjugated(). Expects that the + * quaternion is normalized. @f[ * \hat q^{-1} = \frac{\hat q^*}{|\hat q|^2} = \hat q^* * @f] - * @see isNormalized(), inverted() + * @see @ref isNormalized(), @ref inverted() */ DualQuaternion invertedNormalized() const { CORRADE_ASSERT(isNormalized(), @@ -283,12 +291,14 @@ template class DualQuaternion: public Dual> { /** * @brief Rotate and translate point with dual quaternion * - * See transformPointNormalized(), which is faster for normalized dual - * quaternions. @f[ + * See @ref transformPointNormalized(), which is faster for normalized + * dual quaternions. @f[ * v' = \hat q v \overline{\hat q^{-1}} = \hat q ([\boldsymbol 0, 1] + \epsilon [\boldsymbol v, 0]) \overline{\hat q^{-1}} * @f] - * @see DualQuaternion(const Vector3&), dual(), Matrix4::transformPoint(), - * Quaternion::transformVector(), DualComplex::transformPoint() + * @see @ref DualQuaternion(const Vector3&), @ref dual(), + * @ref Matrix4::transformPoint(), + * @ref Quaternion::transformVector(), + * @ref DualComplex::transformPoint() */ Vector3 transformPoint(const Vector3& vector) const { return ((*this)*DualQuaternion(vector)*inverted().dualConjugated()).dual().vector(); @@ -297,13 +307,14 @@ template class DualQuaternion: public Dual> { /** * @brief Rotate and translate point with normalized dual quaternion * - * Faster alternative to transformPoint(), expects that the dual + * Faster alternative to @ref transformPoint(), expects that the dual * quaternion is normalized. @f[ * v' = \hat q v \overline{\hat q^{-1}} = \hat q v \overline{\hat q^*} = \hat q ([\boldsymbol 0, 1] + \epsilon [\boldsymbol v, 0]) \overline{\hat q^*} * @f] - * @see isNormalized(), DualQuaternion(const Vector3&), dual(), - * Matrix4::transformPoint(), Quaternion::transformVectorNormalized(), - * DualComplex::transformPointNormalized() + * @see @ref isNormalized(), @ref DualQuaternion(const Vector3&), + * @ref dual(), @ref Matrix4::transformPoint(), + * @ref Quaternion::transformVectorNormalized(), + * @ref DualComplex::transformPoint() */ Vector3 transformPointNormalized(const Vector3& vector) const { CORRADE_ASSERT(isNormalized(), diff --git a/src/Magnum/Math/Functions.h b/src/Magnum/Math/Functions.h index a1a42d060..94d89f6b5 100644 --- a/src/Magnum/Math/Functions.h +++ b/src/Magnum/Math/Functions.h @@ -67,7 +67,7 @@ template constexpr T pow(T base) { * @brief Base-2 integral logarithm * * Returns integral logarithm of given number with base `2`. - * @see log() + * @see @ref log() */ UnsignedInt MAGNUM_EXPORT log2(UnsignedInt number); @@ -75,7 +75,7 @@ UnsignedInt MAGNUM_EXPORT log2(UnsignedInt number); * @brief Integral logarithm * * Returns integral logarithm of given number with given base. - * @see log2() + * @see @ref log2() */ UnsignedInt MAGNUM_EXPORT log(UnsignedInt base, UnsignedInt number); @@ -289,7 +289,7 @@ template Vector ceil(const Vector& /** @brief Square root -@see sqrtInverted(), Vector::length() +@see @ref sqrtInverted(), @ref Vector::length() */ #ifdef DOXYGEN_GENERATING_OUTPUT template inline T sqrt(const T& a); @@ -308,7 +308,7 @@ template Vector sqrt(const Vector& /** @brief Inverse square root -@see sqrt(), Vector::lengthInverted() +@see @ref sqrt(), @ref Vector::lengthInverted() */ #ifdef DOXYGEN_GENERATING_OUTPUT template inline T sqrtInverted(const T& a); @@ -326,7 +326,7 @@ template Vector sqrtInverted(const Vector inline T clamp(const T& value, U min, U max); @@ -351,7 +351,7 @@ template Vector clamp(const Vector& The interpolation for vectors is done as in following, similarly for scalars: @f[ \boldsymbol v_{LERP} = (1 - t) \boldsymbol v_A + t \boldsymbol v_B @f] -@see lerpInverted(), Quaternion::lerp() +@see @ref lerpInverted(), @ref Quaternion::lerp() @todo http://fgiesen.wordpress.com/2012/08/15/linear-interpolation-past-present-and-future/ (when SIMD is in place) */ @@ -375,7 +375,7 @@ template inline Vector lerp(const V Returns interpolation phase *t*: @f[ t = \frac{\boldsymbol v_{LERP} - \boldsymbol v_A}{\boldsymbol v_B - \boldsymbol v_A} @f] -@see lerp() +@see @ref lerp() */ #ifdef DOXYGEN_GENERATING_OUTPUT template inline T lerpInverted(const T& a, const T& b, const T& lerp); diff --git a/src/Magnum/Math/Geometry/Distance.h b/src/Magnum/Math/Geometry/Distance.h index 8a4b23791..69254294b 100644 --- a/src/Magnum/Math/Geometry/Distance.h +++ b/src/Magnum/Math/Geometry/Distance.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::Math::Geometry::Distance + * @brief Class @ref Magnum::Math::Geometry::Distance */ #include "Magnum/Math/Functions.h" @@ -50,7 +50,7 @@ class Distance { * d = \frac{|(\boldsymbol b - \boldsymbol a)_\bot \cdot (\boldsymbol a - \boldsymbol p)|} {|\boldsymbol b - \boldsymbol a|} * @f] * Source: http://mathworld.wolfram.com/Point-LineDistance2-Dimensional.html - * @see linePointSquared(const Vector2&, const Vector2&, const Vector2&) + * @see @ref linePointSquared(const Vector2&, const Vector2&, const Vector2&) */ template static T linePoint(const Vector2& a, const Vector2& b, const Vector2& point) { const Vector2 bMinusA = b - a; @@ -63,7 +63,8 @@ class Distance { * @param b Second point of the line * @param point Point * - * More efficient than linePoint(const Vector2&, const Vector2&, const Vector2&) + * More efficient than + * @ref linePoint(const Vector2&, const Vector2&, const Vector2&) * for comparing distance with other values, because it doesn't * compute the square root. */ @@ -84,7 +85,7 @@ class Distance { * {|\boldsymbol b - \boldsymbol a|} * @f] * Source: http://mathworld.wolfram.com/Point-LineDistance3-Dimensional.html - * @see linePointSquared(const Vector3&, const Vector3&, const Vector3&) + * @see @ref linePointSquared(const Vector3&, const Vector3&, const Vector3&) */ template static T linePoint(const Vector3& a, const Vector3& b, const Vector3& point) { return std::sqrt(linePointSquared(a, b, point)); @@ -93,7 +94,7 @@ class Distance { /** * @brief %Distance of line and point in 3D, squared * - * More efficient than linePoint(const Vector3&, const Vector3&, const Vector3&) + * More efficient than @ref linePoint(const Vector3&, const Vector3&, const Vector3&) * for comparing distance with other values, because it doesn't * compute the square root. */ @@ -121,19 +122,19 @@ class Distance { * @f] * The last alternative is when the following equation applies. The * point then lies between **a** and **b** and the distance is - * computed the same way as in linePoint(). @f[ + * computed the same way as in @ref linePoint(). @f[ * |\boldsymbol b - \boldsymbol a|^2 > |\boldsymbol p - \boldsymbol a|^2 + |\boldsymbol p - \boldsymbol b|^2 * @f] * - * @see lineSegmentPointSquared() + * @see @ref lineSegmentPointSquared() */ template static T lineSegmentPoint(const Vector2& a, const Vector2& b, const Vector2& point); /** * @brief %Distance of point from line segment in 2D, squared * - * More efficient than lineSegmentPoint() for comparing distance with - * other values, because it doesn't compute the square root. + * More efficient than @ref lineSegmentPoint() for comparing distance + * with other values, because it doesn't compute the square root. */ template static T lineSegmentPointSquared(const Vector2& a, const Vector2& b, const Vector2& point); @@ -144,9 +145,9 @@ class Distance { * @param point Point * * Similar to 2D implementation - * lineSegmentPoint(const Vector2&, const Vector2&, const Vector2&). + * @ref lineSegmentPoint(const Vector2&, const Vector2&, const Vector2&). * - * @see lineSegmentPointSquared(const Vector3&, const Vector3&, const Vector3&) + * @see @ref lineSegmentPointSquared(const Vector3&, const Vector3&, const Vector3&) */ template static T lineSegmentPoint(const Vector3& a, const Vector3& b, const Vector3& point) { return std::sqrt(lineSegmentPointSquared(a, b, point)); @@ -155,8 +156,10 @@ class Distance { /** * @brief %Distance of point from line segment in 3D, squared * - * More efficient than lineSegmentPoint(const Vector3&, const Vector3&, const Vector3&) for comparing distance with - * other values, because it doesn't compute the square root. + * More efficient than + * @ref lineSegmentPoint(const Vector3&, const Vector3&, const Vector3&) + * for comparing distance with other values, because it doesn't compute + * the square root. */ template static T lineSegmentPointSquared(const Vector3& a, const Vector3& b, const Vector3& point); }; diff --git a/src/Magnum/Math/Geometry/Intersection.h b/src/Magnum/Math/Geometry/Intersection.h index 550d4462a..fc06ec9cd 100644 --- a/src/Magnum/Math/Geometry/Intersection.h +++ b/src/Magnum/Math/Geometry/Intersection.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::Math::Geometry::Intersection + * @brief Class @ref Magnum::Math::Geometry::Intersection */ #include "Magnum/Math/Vector3.h" @@ -66,7 +66,7 @@ class Intersection { * \end{array} * @f] * - * See also lineSegmentLine() which computes only **t**, which is + * See also @ref lineSegmentLine() which computes only **t**, which is * useful if you don't need to test that the intersection lies inside * line segment defined by `q` and `q + s`. */ @@ -89,7 +89,7 @@ class Intersection { * value is in range @f$ [ 0 ; 1 ] @f$, the intersection is inside * the line segment defined by `p` and `p + r`. * - * Unlike lineSegmentLineSegment() computes only **t**. + * Unlike @ref lineSegmentLineSegment() computes only **t**. */ template static T lineSegmentLine(const Vector2& p, const Vector2& r, const Vector2& q, const Vector2& s) { return Vector2::cross(q - p, s)/Vector2::cross(r, s); diff --git a/src/Magnum/Math/Math.h b/src/Magnum/Math/Math.h index 56e9a2bd3..a9acb5c95 100644 --- a/src/Magnum/Math/Math.h +++ b/src/Magnum/Math/Math.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Forward declarations for Magnum::Math namespace + * @brief Forward declarations for @ref Magnum::Math namespace */ #include diff --git a/src/Magnum/Math/Matrix.h b/src/Magnum/Math/Matrix.h index d01e2371c..0b088714e 100644 --- a/src/Magnum/Math/Matrix.h +++ b/src/Magnum/Math/Matrix.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::Math::Matrix + * @brief Class @ref Magnum::Math::Matrix, typedef @ref Magnum::Math::Matrix2x2, @ref Magnum::Math::Matrix3x3, @ref Magnum::Math::Matrix4x4 */ #include "Magnum/Math/RectangularMatrix.h" @@ -57,7 +57,7 @@ template class Matrix: public RectangularMatrix class Matrix: public RectangularMatrix(typename Implementation::GenerateSequence::Type(), @@ -113,8 +113,9 @@ template class Matrix: public RectangularMatrix class Matrix: public RectangularMatrix inverted() const; /** * @brief Inverted orthogonal matrix * - * Equivalent to transposed(), expects that the matrix is orthogonal. @f[ + * Equivalent to @ref transposed(), expects that the matrix is + * orthogonal. @f[ * A^{-1} = A^T * @f] - * @see inverted(), isOrthogonal(), Matrix3::invertedRigid(), - * Matrix4::invertedRigid() + * @see @ref inverted(), @ref isOrthogonal(), + * @ref Matrix3::invertedRigid(), + * @ref Matrix4::invertedRigid() */ Matrix invertedOrthogonal() const { CORRADE_ASSERT(isOrthogonal(), diff --git a/src/Magnum/Math/Matrix3.h b/src/Magnum/Math/Matrix3.h index eac1ce9b3..2fabe56be 100644 --- a/src/Magnum/Math/Matrix3.h +++ b/src/Magnum/Math/Matrix3.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::Math::Matrix3 + * @brief Class @ref Magnum::Math::Matrix3 */ #include "Magnum/Math/Matrix.h" @@ -40,8 +40,8 @@ namespace Magnum { namespace Math { Represents 2D transformation. See @ref matrix-vector and @ref transformations for brief introduction. -@see Magnum::Matrix3, Magnum::Matrix3d, DualComplex, - SceneGraph::MatrixTransformation2D +@see @ref Magnum::Matrix3, @ref Magnum::Matrix3d, @ref DualComplex, + @ref SceneGraph::MatrixTransformation2D @configurationvalueref{Magnum::Math::Matrix3} */ template class Matrix3: public Matrix<3, T> { @@ -50,9 +50,10 @@ template class Matrix3: public Matrix<3, T> { * @brief 2D translation matrix * @param vector Translation vector * - * @see translation(), DualComplex::translation(), - * Matrix4::translation(const Vector3&), Vector2::xAxis(), - * Vector2::yAxis() + * @see translation() const, @ref DualComplex::translation(), + * @ref Matrix4::translation(const Vector3&), + * @ref Vector2::xAxis(), @ref Vector2::yAxis() + * @todoc Explicit reference when Doxygen can handle const */ constexpr static Matrix3 translation(const Vector2& vector) { return {{ T(1), T(0), T(0)}, @@ -64,8 +65,9 @@ template class Matrix3: public Matrix<3, T> { * @brief 2D scaling matrix * @param vector Scaling vector * - * @see rotationScaling() const, Matrix4::scaling(const Vector3&), - * Vector2::xScale(), Vector2::yScale() + * @see @ref rotationScaling(), + * @ref Matrix4::scaling(const Vector3&), + * @ref Vector2::xScale(), @ref Vector2::yScale() */ constexpr static Matrix3 scaling(const Vector2& vector) { return {{vector.x(), T(0), T(0)}, @@ -77,8 +79,10 @@ template class Matrix3: public Matrix<3, T> { * @brief 2D rotation matrix * @param angle Rotation angle (counterclockwise) * - * @see rotation() const, Complex::rotation(), DualComplex::rotation(), - * Matrix4::rotation(Rad, const Vector3&) + * @see rotation() const, @ref Complex::rotation(), + * @ref DualComplex::rotation(), + * @ref Matrix4::rotation(Rad, const Vector3&) + * @todoc Explicit reference when Doxygen can handle const */ static Matrix3 rotation(Rad angle); @@ -87,7 +91,7 @@ template class Matrix3: public Matrix<3, T> { * @param normal Normal of the line through which to reflect * * Expects that the normal is normalized. - * @see Matrix4::reflection(), Vector::isNormalized() + * @see @ref Matrix4::reflection(), @ref Vector::isNormalized() */ static Matrix3 reflection(const Vector2& normal) { CORRADE_ASSERT(normal.isNormalized(), @@ -99,7 +103,8 @@ template class Matrix3: public Matrix<3, T> { * @brief 2D projection matrix * @param size Size of the view * - * @see Matrix4::orthographicProjection(), Matrix4::perspectiveProjection() + * @see @ref Matrix4::orthographicProjection(), + * @ref Matrix4::perspectiveProjection() */ static Matrix3 projection(const Vector2& size) { return scaling(2.0f/size); @@ -112,7 +117,8 @@ template class Matrix3: public Matrix<3, T> { * @param translation Translation part (first two elements of * third column) * - * @see rotationScaling() const, translation() const + * @see @ref rotationScaling(), translation() const + * @todoc Explicit reference when Doxygen can handle const */ constexpr static Matrix3 from(const Matrix<2, T>& rotationScaling, const Vector2& translation) { return {{rotationScaling[0], T(0)}, @@ -127,8 +133,8 @@ template class Matrix3: public Matrix<3, T> { * @brief Default constructor * * Creates identity matrix. You can also explicitly call this - * constructor with `Matrix3 m(Matrix3::Identity);`. Optional parameter - * @p value allows you to specify value on diagonal. + * constructor with `%Matrix3 m(Matrix3::Identity);`. Optional + * parameter @p value allows you to specify value on diagonal. */ constexpr /*implicit*/ Matrix3(typename Matrix<3, T>::IdentityType = (Matrix<3, T>::Identity), T value = T(1)): Matrix<3, T>(Matrix<3, T>::Identity, value) {} @@ -149,7 +155,7 @@ template class Matrix3: public Matrix<3, T> { * * Rigid transformation consists only of rotation and translation (i.e. * no scaling or projection). - * @see isOrthogonal() + * @see @ref isOrthogonal() */ bool isRigidTransformation() const { return rotationScaling().isOrthogonal() && row(2) == Vector3(T(0), T(0), T(1)); @@ -159,9 +165,11 @@ template class Matrix3: public Matrix<3, T> { * @brief 2D rotation and scaling part of the matrix * * Upper-left 2x2 part of the matrix. - * @see from(const Matrix<2, T>&, const Vector2&), rotation() const - * rotationNormalized(), @ref uniformScaling(), rotation(T), - * Matrix4::rotationScaling() const + * @see @ref from(const Matrix<2, T>&, const Vector2&), + * rotation() const, @ref rotationNormalized(), + * @ref uniformScaling(), @ref rotation(Rad), + * @ref Matrix4::rotationScaling() + * @todoc Explicit reference when Doxygen can handle const */ constexpr Matrix<2, T> rotationScaling() const { return {(*this)[0].xy(), @@ -176,6 +184,7 @@ template class Matrix3: public Matrix<3, T> { * @see rotation() const, @ref uniformScaling(), * @ref Matrix4::rotationNormalized() * @todo assert also orthogonality or this is good enough? + * @todoc Explicit reference when Doxygen can handle const */ Matrix<2, T> rotationNormalized() const { CORRADE_ASSERT((*this)[0].xy().isNormalized() && (*this)[1].xy().isNormalized(), @@ -189,8 +198,10 @@ template class Matrix3: public Matrix<3, T> { * * Normalized upper-left 2x2 part of the matrix. Expects uniform * scaling. - * @see rotationNormalized(), rotationScaling(), @ref uniformScaling(), - * rotation(T), Matrix4::rotation() const + * @see @ref rotationNormalized(), @ref rotationScaling(), + * @ref uniformScaling(), @ref rotation(Rad), + * Matrix4::rotation() const + * @todoc Explicit reference when Doxygen can handle const */ Matrix<2, T> rotation() const { CORRADE_ASSERT(TypeTraits::equals((*this)[0].xy().dot(), (*this)[1].xy().dot()), @@ -206,9 +217,10 @@ template class Matrix3: public Matrix<3, T> { * Expects that the scaling is the same in all axes. Faster alternative * to @ref uniformScaling(), because it doesn't compute the square * root. - * @see @ref rotationScaling(), @ref rotation(), + * @see @ref rotationScaling(), rotation() const, * @ref rotationNormalized(), @ref scaling(const Vector2&), * @ref Matrix4::uniformScaling() + * @todoc Explicit reference when Doxygen can handle const */ T uniformScalingSquared() const { const T scalingSquared = (*this)[0].xy().dot(); @@ -223,9 +235,10 @@ template class Matrix3: public Matrix<3, T> { * Length of vectors in upper-left 2x2 part of the matrix. Expects that * the scaling is the same in all axes. Use faster alternative * @ref uniformScalingSquared() where possible. - * @see @ref rotationScaling(), @ref rotation(), + * @see @ref rotationScaling(), rotation() const, * @ref rotationNormalized(), @ref scaling(const Vector2&), * @ref Matrix4::uniformScaling() + * @todoc Explicit reference when Doxygen can handle const */ T uniformScaling() const { return std::sqrt(uniformScalingSquared()); } @@ -233,7 +246,7 @@ template class Matrix3: public Matrix<3, T> { * @brief Right-pointing 2D vector * * First two elements of first column. - * @see up(), Vector2::xAxis(), Matrix4::right() + * @see @ref up(), @ref Vector2::xAxis(), @ref Matrix4::right() */ Vector2& right() { return (*this)[0].xy(); } constexpr Vector2 right() const { return (*this)[0].xy(); } /**< @overload */ @@ -242,7 +255,7 @@ template class Matrix3: public Matrix<3, T> { * @brief Up-pointing 2D vector * * First two elements of second column. - * @see right(), Vector2::yAxis(), Matrix4::up() + * @see @ref right(), @ref Vector2::yAxis(), @ref Matrix4::up() */ Vector2& up() { return (*this)[1].xy(); } constexpr Vector2 up() const { return (*this)[1].xy(); } /**< @overload */ @@ -251,8 +264,9 @@ template class Matrix3: public Matrix<3, T> { * @brief 2D translation part of the matrix * * First two elements of third column. - * @see from(const Matrix<2, T>&, const Vector2&), - * translation(const Vector2&), Matrix4::translation() + * @see @ref from(const Matrix<2, T>&, const Vector2&), + * @ref translation(const Vector2&), + * @ref Matrix4::translation() */ Vector2& translation() { return (*this)[2].xy(); } constexpr Vector2 translation() const { return (*this)[2].xy(); } /**< @overload */ @@ -261,20 +275,22 @@ template class Matrix3: public Matrix<3, T> { * @brief Inverted rigid transformation matrix * * Expects that the matrix represents rigid transformation. - * Significantly faster than the general algorithm in inverted(). - * @see isRigidTransformation(), invertedOrthogonal(), - * rotationScaling() const, translation() const + * Significantly faster than the general algorithm in @ref inverted(). + * @see @ref isRigidTransformation(), @ref invertedOrthogonal(), + * @ref rotationScaling(), translation() const + * @todoc Explicit reference when Doxygen can handle const */ Matrix3 invertedRigid() const; /** * @brief Transform 2D vector with the matrix * - * Unlike in transformPoint(), translation is not involved in the + * Unlike in @ref transformPoint(), translation is not involved in the * transformation. @f[ * \boldsymbol v' = \boldsymbol M \begin{pmatrix} v_x \\ v_y \\ 0 \end{pmatrix} * @f] - * @see Complex::transformVector(), Matrix4::transformVector() + * @see @ref Complex::transformVector(), + * @ref Matrix4::transformVector() * @todo extract 2x2 matrix and multiply directly? (benchmark that) */ Vector2 transformVector(const Vector2& vector) const { @@ -284,11 +300,12 @@ template class Matrix3: public Matrix<3, T> { /** * @brief Transform 2D point with the matrix * - * Unlike in transformVector(), translation is also involved in the - * transformation. @f[ + * Unlike in @ref transformVector(), translation is also involved in + * the transformation. @f[ * \boldsymbol v' = \boldsymbol M \begin{pmatrix} v_x \\ v_y \\ 1 \end{pmatrix} * @f] - * @see DualComplex::transformPoint(), Matrix4::transformPoint() + * @see @ref DualComplex::transformPoint(), + * @ref Matrix4::transformPoint() */ Vector2 transformPoint(const Vector2& vector) const { return ((*this)*Vector3(vector, T(1))).xy(); diff --git a/src/Magnum/Math/Matrix4.h b/src/Magnum/Math/Matrix4.h index f2564d0f4..05c666482 100644 --- a/src/Magnum/Math/Matrix4.h +++ b/src/Magnum/Math/Matrix4.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::Math::Matrix4 + * @brief Class @ref Magnum::Math::Matrix4 */ #include "Magnum/Math/Matrix.h" @@ -45,8 +45,8 @@ namespace Magnum { namespace Math { Represents 3D transformation. See @ref matrix-vector and @ref transformations for brief introduction. -@see Magnum::Matrix4, Magnum::Matrix4d, DualQuaternion, - SceneGraph::MatrixTransformation3D +@see @ref Magnum::Matrix4, @ref Magnum::Matrix4d, @ref DualQuaternion, + @ref SceneGraph::MatrixTransformation3D @configurationvalueref{Magnum::Math::Matrix4} */ template class Matrix4: public Matrix<4, T> { @@ -55,9 +55,10 @@ template class Matrix4: public Matrix<4, T> { * @brief 3D translation * @param vector Translation vector * - * @see translation(), DualQuaternion::translation(), - * Matrix3::translation(const Vector2&), Vector3::xAxis(), - * Vector3::yAxis(), Vector3::zAxis() + * @see @ref translation(), @ref DualQuaternion::translation(), + * @ref Matrix3::translation(const Vector2&), + * @ref Vector3::xAxis(), @ref Vector3::yAxis(), + * @ref Vector3::zAxis() */ constexpr static Matrix4 translation(const Vector3& vector) { return {{ T(1), T(0), T(0), T(0)}, @@ -70,8 +71,10 @@ template class Matrix4: public Matrix<4, T> { * @brief 3D scaling * @param vector Scaling vector * - * @see rotationScaling() const, Matrix3::scaling(const Vector2&), - * Vector3::xScale(), Vector3::yScale(), Vector3::zScale() + * @see @ref rotationScaling(), + * @ref Matrix3::scaling(const Vector2&), + * @ref Vector3::xScale(), @ref Vector3::yScale(), + * @ref Vector3::zScale() */ constexpr static Matrix4 scaling(const Vector3& vector) { return {{vector.x(), T(0), T(0), T(0)}, @@ -86,10 +89,13 @@ template class Matrix4: public Matrix<4, T> { * @param normalizedAxis Normalized rotation axis * * Expects that the rotation axis is normalized. If possible, use - * faster alternatives like rotationX(), rotationY() and rotationZ(). - * @see rotation() const, Quaternion::rotation(), DualQuaternion::rotation(), - * Matrix3::rotation(Rad), Vector3::xAxis(), Vector3::yAxis(), - * Vector3::zAxis(), Vector::isNormalized() + * faster alternatives like @ref rotationX(), @ref rotationY() and + * @ref rotationZ(). + * @see rotation() const, @ref Quaternion::rotation(), + * @ref DualQuaternion::rotation(), @ref Matrix3::rotation(Rad), + * @ref Vector3::xAxis(), @ref Vector3::yAxis(), + * @ref Vector3::zAxis(), @ref Vector::isNormalized() + * @todoc Explicit reference when Doxygen can handle const */ static Matrix4 rotation(Rad angle, const Vector3& normalizedAxis); @@ -97,9 +103,11 @@ template class Matrix4: public Matrix<4, T> { * @brief 3D rotation around X axis * @param angle Rotation angle (counterclockwise) * - * Faster than calling `Matrix4::rotation(angle, Vector3::xAxis())`. - * @see rotation(Rad, const Vector3&), rotationY(), rotationZ(), - * rotation() const, Quaternion::rotation(), Matrix3::rotation(Rad) + * Faster than calling `%Matrix4::rotation(angle, %Vector3::xAxis())`. + * @see @ref rotation(Rad, const Vector3&), @ref rotationY(), + * @ref rotationZ(), rotation() const, + * @ref Quaternion::rotation(), @ref Matrix3::rotation(Rad) + * @todoc Explicit reference when Doxygen can handle const */ static Matrix4 rotationX(Rad angle); @@ -107,9 +115,11 @@ template class Matrix4: public Matrix<4, T> { * @brief 3D rotation around Y axis * @param angle Rotation angle (counterclockwise) * - * Faster than calling `Matrix4::rotation(angle, Vector3::yAxis())`. - * @see rotation(Rad, const Vector3&), rotationX(), rotationZ(), - * rotation() const, Quaternion::rotation(), Matrix3::rotation(Rad) + * Faster than calling `%Matrix4::rotation(angle, %Vector3::yAxis())`. + * @see @ref rotation(Rad, const Vector3&), @ref rotationX(), + * @ref rotationZ(), rotation() const, + * @ref Quaternion::rotation(), @ref Matrix3::rotation(Rad) + * @todoc Explicit reference when Doxygen can handle const */ static Matrix4 rotationY(Rad angle); @@ -117,9 +127,11 @@ template class Matrix4: public Matrix<4, T> { * @brief 3D rotation matrix around Z axis * @param angle Rotation angle (counterclockwise) * - * Faster than calling `Matrix4::rotation(angle, Vector3::zAxis())`. - * @see rotation(Rad, const Vector3&), rotationX(), rotationY(), - * rotation() const, Quaternion::rotation(), Matrix3::rotation(Rad) + * Faster than calling `%Matrix4::rotation(angle, %Vector3::zAxis())`. + * @see @ref rotation(Rad, const Vector3&), @ref rotationX(), + * @ref rotationY(), rotation() const, + * @ref Quaternion::rotation(), @ref Matrix3::rotation(Rad) + * @todoc Explicit reference when Doxygen can handle const */ static Matrix4 rotationZ(Rad angle); @@ -128,7 +140,7 @@ template class Matrix4: public Matrix<4, T> { * @param normal Normal of the plane through which to reflect * * Expects that the normal is normalized. - * @see Matrix3::reflection(), Vector::isNormalized() + * @see @ref Matrix3::reflection(), @ref Vector::isNormalized() */ static Matrix4 reflection(const Vector3& normal); @@ -138,7 +150,7 @@ template class Matrix4: public Matrix<4, T> { * @param near Near clipping plane * @param far Far clipping plane * - * @see perspectiveProjection(), Matrix3::projection() + * @see @ref perspectiveProjection(), @ref Matrix3::projection() */ static Matrix4 orthographicProjection(const Vector2& size, T near, T far); @@ -148,7 +160,7 @@ template class Matrix4: public Matrix<4, T> { * @param near Near clipping plane * @param far Far clipping plane * - * @see orthographicProjection(), Matrix3::projection() + * @see @ref orthographicProjection(), @ref Matrix3::projection() */ static Matrix4 perspectiveProjection(const Vector2& size, T near, T far); @@ -159,7 +171,7 @@ template class Matrix4: public Matrix<4, T> { * @param near Near clipping plane * @param far Far clipping plane * - * @see orthographicProjection(), Matrix3::projection() + * @see @ref orthographicProjection(), @ref Matrix3::projection() */ static Matrix4 perspectiveProjection(Rad fov, T aspectRatio, T near, T far) { const T xyScale = 2*std::tan(T(fov)/2)*near; @@ -173,7 +185,8 @@ template class Matrix4: public Matrix<4, T> { * @param translation Translation part (first three elements of * fourth column) * - * @see rotationScaling() const, translation() const + * @see @ref rotationScaling(), translation() const + * @todoc Explicit reference when Doxygen can handle const */ constexpr static Matrix4 from(const Matrix<3, T>& rotationScaling, const Vector3& translation) { return {{rotationScaling[0], T(0)}, @@ -189,8 +202,8 @@ template class Matrix4: public Matrix<4, T> { * @brief Default constructor * * Creates identity matrix. You can also explicitly call this - * constructor with `Matrix4 m(Matrix4::Identity);`. Optional parameter - * @p value allows you to specify value on diagonal. + * constructor with `%Matrix4 m(Matrix4::Identity);`. Optional + * parameter @p value allows you to specify value on diagonal. */ constexpr /*implicit*/ Matrix4(typename Matrix<4, T>::IdentityType = (Matrix<4, T>::Identity), T value = T(1)): Matrix<4, T>(Matrix<4, T>::Identity, value) {} @@ -211,7 +224,7 @@ template class Matrix4: public Matrix<4, T> { * * Rigid transformation consists only of rotation and translation (i.e. * no scaling or projection). - * @see isOrthogonal() + * @see @ref isOrthogonal() */ bool isRigidTransformation() const { return rotationScaling().isOrthogonal() && row(3) == Vector4(T(0), T(0), T(0), T(1)); @@ -221,9 +234,11 @@ template class Matrix4: public Matrix<4, T> { * @brief 3D rotation and scaling part of the matrix * * Upper-left 3x3 part of the matrix. - * @see from(const Matrix<3, T>&, const Vector3&), rotation() const, - * rotationNormalized(), @ref uniformScaling(), - * rotation(T, const Vector3&), Matrix3::rotationScaling() const + * @see @ref from(const Matrix<3, T>&, const Vector3&), + * rotation() const, @ref rotationNormalized(), + * @ref uniformScaling(), @ref rotation(Rad, const Vector3&), + * Matrix3::rotationScaling() const + * @todoc Explicit reference when Doxygen can handle const */ /* Not Matrix3, because it is for affine 2D transformations */ constexpr Matrix<3, T> rotationScaling() const { @@ -240,6 +255,7 @@ template class Matrix4: public Matrix<4, T> { * @see rotation() const, @ref uniformScaling(), * @ref Matrix3::rotationNormalized() * @todo assert also orthogonality or this is good enough? + * @todoc Explicit reference when Doxygen can handle const */ /* Not Matrix3, because it is for affine 2D transformations */ Matrix<3, T> rotationNormalized() const { @@ -255,9 +271,10 @@ template class Matrix4: public Matrix<4, T> { * * Normalized upper-left 3x3 part of the matrix. Expects uniform * scaling. - * @see rotationNormalized(), rotationScaling() const, - * @ref uniformScaling(), rotation(T, const Vector3&), + * @see @ref rotationNormalized(), @ref rotationScaling(), + * @ref uniformScaling(), @ref rotation(Rad, const Vector3&), * Matrix3::rotation() const + * @todoc Explicit reference when Doxygen can handle const */ /* Not Matrix3, because it is for affine 2D transformations */ Matrix<3, T> rotation() const; @@ -269,9 +286,10 @@ template class Matrix4: public Matrix<4, T> { * Expects that the scaling is the same in all axes. Faster alternative * to @ref uniformScaling(), because it doesn't compute the square * root. - * @see @ref rotationScaling(), @ref rotation(), + * @see @ref rotationScaling(), rotation() const, * @ref rotationNormalized(), @ref scaling(const Vector3&), * @ref Matrix3::uniformScaling() + * @todoc Explicit reference when Doxygen can handle const */ T uniformScalingSquared() const; @@ -281,9 +299,10 @@ template class Matrix4: public Matrix<4, T> { * Length of vectors in upper-left 3x3 part of the matrix. Expects that * the scaling is the same in all axes. Use faster alternative * @ref uniformScalingSquared() where possible. - * @see @ref rotationScaling(), @ref rotation(), + * @see @ref rotationScaling(), rotation() const, * @ref rotationNormalized(), @ref scaling(const Vector3&), * @ref Matrix3::uniformScaling() + * @todoc Explicit reference when Doxygen can handle const */ T uniformScaling() const { return std::sqrt(uniformScalingSquared()); } @@ -291,7 +310,8 @@ template class Matrix4: public Matrix<4, T> { * @brief Right-pointing 3D vector * * First three elements of first column. - * @see up(), backward(), Vector3::xAxis(), Matrix3::right() + * @see @ref up(), @ref backward(), @ref Vector3::xAxis(), + * @ref Matrix3::right() */ Vector3& right() { return (*this)[0].xyz(); } constexpr Vector3 right() const { return (*this)[0].xyz(); } /**< @overload */ @@ -300,7 +320,8 @@ template class Matrix4: public Matrix<4, T> { * @brief Up-pointing 3D vector * * First three elements of second column. - * @see right(), backward(), Vector3::yAxis(), Matrix3::up() + * @see @ref right(), @ref backward(), @ref Vector3::yAxis(), + * @ref Matrix3::up() */ Vector3& up() { return (*this)[1].xyz(); } constexpr Vector3 up() const { return (*this)[1].xyz(); } /**< @overload */ @@ -309,7 +330,7 @@ template class Matrix4: public Matrix<4, T> { * @brief Backward-pointing 3D vector * * First three elements of third column. - * @see right(), up(), Vector3::yAxis() + * @see @ref right(), @ref up(), @ref Vector3::yAxis() */ Vector3& backward() { return (*this)[2].xyz(); } constexpr Vector3 backward() const { return (*this)[2].xyz(); } /**< @overload */ @@ -318,8 +339,9 @@ template class Matrix4: public Matrix<4, T> { * @brief 3D translation part of the matrix * * First three elements of fourth column. - * @see from(const Matrix<3, T>&, const Vector3&), - * translation(const Vector3&), Matrix3::translation() + * @see @ref from(const Matrix<3, T>&, const Vector3&), + * @ref translation(const Vector3&), + * @ref Matrix3::translation() */ Vector3& translation() { return (*this)[3].xyz(); } constexpr Vector3 translation() const { return (*this)[3].xyz(); } /**< @overload */ @@ -328,20 +350,22 @@ template class Matrix4: public Matrix<4, T> { * @brief Inverted rigid transformation matrix * * Expects that the matrix represents rigid transformation. - * Significantly faster than the general algorithm in inverted(). - * @see isRigidTransformation(), invertedOrthogonal(), - * rotationScaling() const, translation() const + * Significantly faster than the general algorithm in @ref inverted(). + * @see @ref isRigidTransformation(), @ref invertedOrthogonal(), + * @ref rotationScaling(), translation() const + * @todoc Explicit reference when Doxygen can handle const */ Matrix4 invertedRigid() const; /** * @brief Transform 3D vector with the matrix * - * Unlike in transformVector(), translation is not involved in the + * Unlike in @ref transformVector(), translation is not involved in the * transformation. @f[ * \boldsymbol v' = \boldsymbol M \begin{pmatrix} v_x \\ v_y \\ v_z \\ 0 \end{pmatrix} * @f] - * @see Quaternion::transformVector(), Matrix3::transformVector() + * @see @ref Quaternion::transformVector(), + * @ref Matrix3::transformVector() * @todo extract 3x3 matrix and multiply directly? (benchmark that) */ Vector3 transformVector(const Vector3& vector) const { @@ -351,11 +375,12 @@ template class Matrix4: public Matrix<4, T> { /** * @brief Transform 3D point with the matrix * - * Unlike in transformVector(), translation is also involved in the - * transformation. @f[ + * Unlike in @ref transformVector(), translation is also involved in + * the transformation. @f[ * \boldsymbol v' = \boldsymbol M \begin{pmatrix} v_x \\ v_y \\ v_z \\ 1 \end{pmatrix} * @f] - * @see DualQuaternion::transformPoint(), Matrix3::transformPoint() + * @see @ref DualQuaternion::transformPoint(), + * @ref Matrix3::transformPoint() */ Vector3 transformPoint(const Vector3& vector) const { return ((*this)*Vector4(vector, T(1))).xyz(); diff --git a/src/Magnum/Math/Quaternion.h b/src/Magnum/Math/Quaternion.h index f613e1476..035249ec5 100644 --- a/src/Magnum/Math/Quaternion.h +++ b/src/Magnum/Math/Quaternion.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::Math::Quaternion + * @brief Class @ref Magnum::Math::Quaternion */ #include @@ -44,11 +44,12 @@ namespace Magnum { namespace Math { @tparam T Underlying data type Represents 3D rotation. See @ref transformations for brief introduction. -@see Magnum::Quaternion, Magnum::Quaterniond, DualQuaternion, Matrix4 +@see @ref Magnum::Quaternion, @ref Magnum::Quaterniond, @ref DualQuaternion, + @ref Matrix4 */ template class Quaternion { public: - typedef T Type; /**< @brief Underlying data type */ + typedef T Type; /**< @brief Underlying data type */ /** * @brief Dot product @@ -57,6 +58,7 @@ template class Quaternion { * p \cdot q = \boldsymbol p_V \cdot \boldsymbol q_V + p_S q_S * @f] * @see dot() const + * @todoc Explicit reference when Doxygen can handle const */ static T dot(const Quaternion& a, const Quaternion& b) { /** @todo Use four-component SIMD implementation when available */ @@ -69,7 +71,8 @@ template class Quaternion { * Expects that both quaternions are normalized. @f[ * \theta = acos \left( \frac{p \cdot q}{|p| |q|} \right) = acos(p \cdot q) * @f] - * @see isNormalized(), Complex::angle(), Vector::angle() + * @see @ref isNormalized(), @ref Complex::angle(), + * @ref Vector::angle() */ static Rad angle(const Quaternion& normalizedA, const Quaternion& normalizedB); @@ -82,7 +85,7 @@ template class Quaternion { * Expects that both quaternions are normalized. @f[ * q_{LERP} = \frac{(1 - t) q_A + t q_B}{|(1 - t) q_A + t q_B|} * @f] - * @see isNormalized(), slerp(), Math::lerp() + * @see @ref isNormalized(), @ref slerp(), @ref Math::lerp() */ static Quaternion lerp(const Quaternion& normalizedA, const Quaternion& normalizedB, T t); @@ -97,7 +100,7 @@ template class Quaternion { * ~~~~~~~~~~ * \theta = acos \left( \frac{q_A \cdot q_B}{|q_A| \cdot |q_B|} \right) = acos(q_A \cdot q_B) * @f] - * @see isNormalized(), lerp() + * @see @ref isNormalized(), @ref lerp() */ static Quaternion slerp(const Quaternion& normalizedA, const Quaternion& normalizedB, T t); @@ -109,9 +112,10 @@ template class Quaternion { * Expects that the rotation axis is normalized. @f[ * q = [\boldsymbol a \cdot sin \frac \theta 2, cos \frac \theta 2] * @f] - * @see angle(), axis(), DualQuaternion::rotation(), - * Matrix4::rotation(), Complex::rotation(), Vector3::xAxis(), - * Vector3::yAxis(), Vector3::zAxis(), Vector::isNormalized() + * @see @ref angle(), @ref axis(), @ref DualQuaternion::rotation(), + * @ref Matrix4::rotation(), @ref Complex::rotation(), + * @ref Vector3::xAxis(), @ref Vector3::yAxis(), + * @ref Vector3::zAxis(), @ref Vector::isNormalized() */ static Quaternion rotation(Rad angle, const Vector3& normalizedAxis); @@ -119,7 +123,8 @@ template class Quaternion { * @brief Create quaternion from rotation matrix * * Expects that the matrix is orthogonal (i.e. pure rotation). - * @see toMatrix(), DualComplex::fromMatrix(), Matrix::isOrthogonal() + * @see @ref toMatrix(), @ref DualComplex::fromMatrix(), + * @ref Matrix::isOrthogonal() */ static Quaternion fromMatrix(const Matrix<3, T>& matrix); @@ -147,7 +152,7 @@ template class Quaternion { * To be used in transformations later. @f[ * q = [\boldsymbol v, 0] * @f] - * @see transformVector(), transformVectorNormalized() + * @see @ref transformVector(), @ref transformVectorNormalized() */ constexpr explicit Quaternion(const Vector3& vector): _vector(vector), _scalar(T(0)) {} @@ -164,10 +169,10 @@ template class Quaternion { /** * @brief Whether the quaternion is normalized * - * Quaternion is normalized if it has unit length: @f[ + * %Quaternion is normalized if it has unit length: @f[ * |q \cdot q - 1| < 2 \epsilon + \epsilon^2 \cong 2 \epsilon * @f] - * @see dot(), normalized() + * @see @ref dot(), @ref normalized() */ bool isNormalized() const { return Implementation::isNormalizedSquared(dot()); @@ -185,7 +190,7 @@ template class Quaternion { * Expects that the quaternion is normalized. @f[ * \theta = 2 \cdot acos q_S * @f] - * @see isNormalized(), axis(), rotation() + * @see @ref isNormalized(), @ref axis(), @ref rotation() */ Rad angle() const; @@ -197,15 +202,15 @@ template class Quaternion { * default-constructed quaternion. @f[ * \boldsymbol a = \frac{\boldsymbol q_V}{\sqrt{1 - q_S^2}} * @f] - * @see isNormalized(), angle(), rotation() + * @see @ref isNormalized(), @ref angle(), @ref rotation() */ Vector3 axis() const; /** * @brief Convert quaternion to rotation matrix * - * @see fromMatrix(), DualQuaternion::toMatrix(), - * Matrix4::from(const Matrix<3, T>&, const Vector3&) + * @see @ref fromMatrix(), @ref DualQuaternion::toMatrix(), + * @ref Matrix4::from(const Matrix<3, T>&, const Vector3&) */ Matrix<3, T> toMatrix() const; @@ -226,6 +231,7 @@ template class Quaternion { * @brief Add quaternion * * @see operator+=() + * @todoc Make explicit reference when Doxygen can handle operators */ Quaternion operator+(const Quaternion& other) const { return Quaternion(*this) += other; @@ -256,7 +262,7 @@ template class Quaternion { /** * @brief Subtract quaternion * - * @see operator-=() + * @see @ref operator-=() */ Quaternion operator-(const Quaternion& other) const { return Quaternion(*this) -= other; @@ -279,6 +285,7 @@ template class Quaternion { * @brief Multiply with scalar * * @see operator*=(T) + * @todoc Make explicit reference when Doxygen can handle operators */ Quaternion operator*(T scalar) const { return Quaternion(*this) *= scalar; @@ -301,6 +308,7 @@ template class Quaternion { * @brief Divide with scalar * * @see operator/=(T) + * @todoc Make explicit reference when Doxygen can handle operators */ Quaternion operator/(T scalar) const { return Quaternion(*this) /= scalar; @@ -319,29 +327,32 @@ template class Quaternion { /** * @brief Dot product of the quaternion * - * Should be used instead of length() for comparing quaternion length - * with other values, because it doesn't compute the square root. @f[ + * Should be used instead of @ref length() for comparing quaternion + * length with other values, because it doesn't compute the square + * root. @f[ * q \cdot q = \boldsymbol q_V \cdot \boldsymbol q_V + q_S^2 * @f] - * @see isNormalized(), dot(const Quaternion&, const Quaternion&) + * @see @ref isNormalized(), + * @ref dot(const Quaternion&, const Quaternion&) */ T dot() const { return dot(*this, *this); } /** * @brief %Quaternion length * - * See also dot() const which is faster for comparing length with other - * values. @f[ + * See also dot() const which is faster for comparing length with + * other values. @f[ * |q| = \sqrt{q \cdot q} * @f] - * @see isNormalized() + * @see @ref isNormalized() + * @todoc Explicit reference when Doxygen can handle const */ T length() const { return std::sqrt(dot()); } /** * @brief Normalized quaternion (of unit length) * - * @see isNormalized() + * @see @ref isNormalized() */ Quaternion normalized() const { return (*this)/length(); } @@ -357,7 +368,7 @@ template class Quaternion { /** * @brief Inverted quaternion * - * See invertedNormalized() which is faster for normalized + * See @ref invertedNormalized() which is faster for normalized * quaternions. @f[ * q^{-1} = \frac{q^*}{|q|^2} = \frac{q^*}{q \cdot q} * @f] @@ -367,23 +378,25 @@ template class Quaternion { /** * @brief Inverted normalized quaternion * - * Equivalent to conjugated(). Expects that the quaternion is + * Equivalent to @ref conjugated(). Expects that the quaternion is * normalized. @f[ * q^{-1} = \frac{q^*}{|q|^2} = q^* * @f] - * @see isNormalized(), inverted() + * @see @ref isNormalized(), @ref inverted() */ Quaternion invertedNormalized() const; /** * @brief Rotate vector with quaternion * - * See transformVectorNormalized(), which is faster for normalized + * See @ref transformVectorNormalized(), which is faster for normalized * quaternions. @f[ * v' = qvq^{-1} = q [\boldsymbol v, 0] q^{-1} * @f] - * @see Quaternion(const Vector3&), vector(), Matrix4::transformVector(), - * DualQuaternion::transformPoint(), Complex::transformVector() + * @see @ref Quaternion(const Vector3&), @ref vector(), + * @ref Matrix4::transformVector(), + * @ref DualQuaternion::transformPoint(), + * @ref Complex::transformVector() */ Vector3 transformVector(const Vector3& vector) const { return ((*this)*Quaternion(vector)*inverted()).vector(); @@ -392,12 +405,14 @@ template class Quaternion { /** * @brief Rotate vector with normalized quaternion * - * Faster alternative to transformVector(), expects that the quaternion - * is normalized. @f[ + * Faster alternative to @ref transformVector(), expects that the + * quaternion is normalized. @f[ * v' = qvq^{-1} = qvq^* = q [\boldsymbol v, 0] q^* * @f] - * @see isNormalized(), Quaternion(const Vector3&), vector(), Matrix4::transformVector(), - * DualQuaternion::transformPointNormalized(), Complex::transformVector() + * @see @ref isNormalized(), @ref Quaternion(const Vector3&), + * @ref vector(), @ref Matrix4::transformVector(), + * @ref DualQuaternion::transformPointNormalized(), + * @ref Complex::transformVector() */ Vector3 transformVectorNormalized(const Vector3& vector) const; @@ -420,6 +435,7 @@ template class Quaternion { @brief Multiply scalar with quaternion Same as Quaternion::operator*(T) const. +@todoc Make explicit reference when Doxygen can handle operators */ template inline Quaternion operator*(T scalar, const Quaternion& quaternion) { return quaternion*scalar; @@ -432,6 +448,7 @@ template inline Quaternion operator*(T scalar, const Quaternion& \frac a q = [\frac a {\boldsymbol q_V}, \frac a {q_S}] @f] @see Quaternion::operator/() +@todoc Make explicit reference when Doxygen can handle operators */ template inline Quaternion operator/(T scalar, const Quaternion& quaternion) { return {scalar/quaternion.vector(), scalar/quaternion.scalar()}; @@ -446,12 +463,16 @@ template Corrade::Utility::Debug operator<<(Corrade::Utility::Debug deb return debug; } +/** @todoc Remove the workaround when Doxygen is really able to preprocessor */ + /* Explicit instantiation for commonly used types */ #ifndef DOXYGEN_GENERATING_OUTPUT +/** @privatesection */ extern template Corrade::Utility::Debug MAGNUM_EXPORT operator<<(Corrade::Utility::Debug, const Quaternion&); #ifndef MAGNUM_TARGET_GLES extern template Corrade::Utility::Debug MAGNUM_EXPORT operator<<(Corrade::Utility::Debug, const Quaternion&); #endif +/** @endprivatesection */ #endif namespace Implementation { diff --git a/src/Magnum/Math/Range.h b/src/Magnum/Math/Range.h index 0bfa6562b..6f9fe0b25 100644 --- a/src/Magnum/Math/Range.h +++ b/src/Magnum/Math/Range.h @@ -62,7 +62,7 @@ template class Range { /** * Create range from minimal coordinates and size * @param min Minimal coordinates - * @param size Range size + * @param size %Range size */ static Range fromSize(const VectorType& min, const VectorType& size) { return {min, min+size}; @@ -122,7 +122,7 @@ template class Range { constexpr const VectorType max() const { return _max; } /**< @overload */ /** - * @brief Range size + * @brief %Range size * * @see @ref min(), @ref max(), @ref Range2D::sizeX(), * @ref Range2D::sizeY(), @ref Range3D::sizeX(), @@ -131,7 +131,7 @@ template class Range { VectorType size() const { return _max - _min; } /** - * @brief Range center + * @brief %Range center * * @see @ref Range2D::centerX(), @ref Range2D::centerY(), * @ref Range3D::centerX(), @ref Range3D::centerY(), diff --git a/src/Magnum/Math/RectangularMatrix.h b/src/Magnum/Math/RectangularMatrix.h index f93a9a71c..dd160b4ca 100644 --- a/src/Magnum/Math/RectangularMatrix.h +++ b/src/Magnum/Math/RectangularMatrix.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::Math::RectangularMatrix + * @brief Class @ref Magnum::Math::RectangularMatrix, typedef @ref Magnum::Math::Matrix2x3, @ref Magnum::Math::Matrix3x2, @ref Magnum::Math::Matrix2x4, @ref Magnum::Math::Matrix4x2, @ref Magnum::Math::Matrix3x4, @ref Magnum::Math::Matrix4x3 */ #include "Magnum/Math/Vector.h" @@ -43,8 +43,8 @@ namespace Implementation { @tparam rows Row count @tparam T Underlying data type -See @ref matrix-vector for brief introduction. See also Matrix (square) and -Vector. +See @ref matrix-vector for brief introduction. See also @ref Matrix (square) +and @ref Vector. The data are stored in column-major order, to reflect that, all indices in math formulas are in reverse order (i.e. @f$ \boldsymbol A_{ji} @f$ instead @@ -65,13 +65,13 @@ template class RectangularMatrix { /** * @brief Size of matrix diagonal * - * @see fromDiagonal(), diagonal() + * @see @ref fromDiagonal(), @ref diagonal() */ const static std::size_t DiagonalSize = (cols < rows ? cols : rows); /** * @brief %Matrix from array - * @return Reference to the data as if it was Matrix, thus doesn't + * @return Reference to the data as if it was matrix, thus doesn't * perform any copying. * * @attention Use with caution, the function doesn't check whether the @@ -90,7 +90,7 @@ template class RectangularMatrix { * * Rolls the vector into matrix, i.e. first `rows` elements of the * vector will make first column of resulting matrix. - * @see toVector() + * @see @ref toVector() */ static RectangularMatrix fromVector(const Vector& vector) { return *reinterpret_cast*>(vector.data()); @@ -99,7 +99,7 @@ template class RectangularMatrix { /** * @brief Construct diagonal matrix * - * @see diagonal() + * @see @ref diagonal() */ constexpr static RectangularMatrix fromDiagonal(const Vector& diagonal) { return RectangularMatrix(typename Implementation::GenerateSequence::Type(), diagonal); @@ -164,7 +164,8 @@ template class RectangularMatrix { * @return One-dimensional array of `cols*rows` length in column-major * order. * - * @see operator[] + * @see operator[]() + * @todoc Make explicit reference when Doxygen can handle operators */ T* data() { return _data[0].data(); } constexpr const T* data() const { return _data[0].data(); } /**< @overload */ @@ -172,13 +173,15 @@ template class RectangularMatrix { /** * @brief %Matrix column * - * Particular elements can be accessed using Vector::operator[], e.g.: + * Particular elements can be accessed using Vector::operator[](), + * e.g.: * @code * RectangularMatrix<4, 3, Float> m; * Float a = m[2][1]; * @endcode * - * @see row(), data() + * @see @ref row(), @ref data() + * @todoc Make explicit reference when Doxygen can handle operators */ Vector& operator[](std::size_t col) { return _data[col]; } constexpr const Vector& operator[](std::size_t col) const { return _data[col]; } /**< @overload */ @@ -186,9 +189,11 @@ template class RectangularMatrix { /** * @brief %Matrix row * - * Consider using transposed() when accessing rows frequently, as this - * is slower than accessing columns due to the way the matrix is stored. + * Consider using @ref transposed() when accessing rows frequently, as + * this is slower than accessing columns due to the way the matrix is + * stored. * @see operator[]() + * @todoc Make explicit reference when Doxygen can handle operators */ Vector row(std::size_t row) const; @@ -203,8 +208,9 @@ template class RectangularMatrix { /** * @brief Non-equality operator * - * @see Vector::operator<(), Vector::operator<=(), Vector::operator>=(), - * Vector::operator>() + * @see Vector::operator<(), Vector::operator<=(), + * Vector::operator>=(), Vector::operator>() + * @todoc Make explicit reference when Doxygen can handle operators */ bool operator!=(const RectangularMatrix& other) const { return !operator==(other); @@ -237,6 +243,7 @@ template class RectangularMatrix { * @brief Add matrix * * @see operator+=() + * @todoc Make explicit reference when Doxygen can handle operators */ RectangularMatrix operator+(const RectangularMatrix& other) const { return RectangularMatrix(*this)+=other; @@ -259,7 +266,7 @@ template class RectangularMatrix { /** * @brief Subtract matrix * - * @see operator-=() + * @see @ref operator-=() */ RectangularMatrix operator-(const RectangularMatrix& other) const { return RectangularMatrix(*this)-=other; @@ -283,6 +290,7 @@ template class RectangularMatrix { * @brief Multiply matrix with number * * @see operator*=(T), operator*(T, const RectangularMatrix&) + * @todoc Make explicit reference when Doxygen can handle operators */ RectangularMatrix operator*(T number) const { return RectangularMatrix(*this) *= number; @@ -307,6 +315,7 @@ template class RectangularMatrix { * * @see operator/=(T), * operator/(T, const RectangularMatrix&) + * @todoc Make explicit reference when Doxygen can handle operators */ RectangularMatrix operator/(T number) const { return RectangularMatrix(*this) /= number; @@ -336,14 +345,14 @@ template class RectangularMatrix { /** * @brief Transposed matrix * - * @see row() + * @see @ref row() */ RectangularMatrix transposed() const; /** * @brief Values on diagonal * - * @see fromDiagonal() + * @see @ref fromDiagonal() */ constexpr Vector diagonal() const; @@ -354,7 +363,7 @@ template class RectangularMatrix { * of the matrix will make first `rows` elements of resulting vector. * Useful for performing vector operations with the matrix (e.g. * summing the elements etc.). - * @see fromVector() + * @see @ref fromVector() */ Vector toVector() const { return *reinterpret_cast*>(data()); @@ -379,7 +388,7 @@ template class RectangularMatrix { #ifndef CORRADE_GCC46_COMPATIBILITY /** -@brief Matrix with 2 columns and 3 rows +@brief %Matrix with 2 columns and 3 rows Convenience alternative to %RectangularMatrix<2, 3, T>. See @ref RectangularMatrix for more information. @@ -390,7 +399,7 @@ Convenience alternative to %RectangularMatrix<2, 3, T>. See template using Matrix2x3 = RectangularMatrix<2, 3, T>; /** -@brief Matrix with 3 columns and 2 rows +@brief %Matrix with 3 columns and 2 rows Convenience alternative to %RectangularMatrix<3, 2, T>. See @ref RectangularMatrix for more information. @@ -401,7 +410,7 @@ Convenience alternative to %RectangularMatrix<3, 2, T>. See template using Matrix3x2 = RectangularMatrix<3, 2, T>; /** -@brief Matrix with 2 columns and 4 rows +@brief %Matrix with 2 columns and 4 rows Convenience alternative to %RectangularMatrix<2, 4, T>. See @ref RectangularMatrix for more information. @@ -412,7 +421,7 @@ Convenience alternative to %RectangularMatrix<2, 4, T>. See template using Matrix2x4 = RectangularMatrix<2, 4, T>; /** -@brief Matrix with 4 columns and 2 rows +@brief %Matrix with 4 columns and 2 rows Convenience alternative to %RectangularMatrix<4, 2, T>. See @ref RectangularMatrix for more information. @@ -423,7 +432,7 @@ Convenience alternative to %RectangularMatrix<4, 2, T>. See template using Matrix4x2 = RectangularMatrix<4, 2, T>; /** -@brief Matrix with 3 columns and 4 rows +@brief %Matrix with 3 columns and 4 rows Convenience alternative to %RectangularMatrix<3, 4, T>. See @ref RectangularMatrix for more information. @@ -434,7 +443,7 @@ Convenience alternative to %RectangularMatrix<3, 4, T>. See template using Matrix3x4 = RectangularMatrix<3, 4, T>; /** -@brief Matrix with 4 columns and 3 rows +@brief %Matrix with 4 columns and 3 rows Convenience alternative to %RectangularMatrix<4, 3, T>. See @ref RectangularMatrix for more information. @@ -449,6 +458,7 @@ template using Matrix4x3 = RectangularMatrix<4, 3, T>; @brief Multiply number with matrix Same as RectangularMatrix::operator*(T) const. +@todoc Make explicit reference when Doxygen can handle operators */ template inline RectangularMatrix operator*( #ifdef DOXYGEN_GENERATING_OUTPUT @@ -468,6 +478,7 @@ The computation is done column-wise. @f[ \boldsymbol B_j = \frac a {\boldsymbol A_j} @f] @see RectangularMatrix::operator/(T) const +@todoc Make explicit reference when Doxygen can handle operators */ template inline RectangularMatrix operator/( #ifdef DOXYGEN_GENERATING_OUTPUT @@ -492,6 +503,7 @@ Internally the same as multiplying one-column matrix with one-row matrix. @f[ (\boldsymbol {aA})_{ji} = \boldsymbol a_i \boldsymbol A_j @f] @see RectangularMatrix::operator*(const RectangularMatrix&) const +@todoc Make explicit reference when Doxygen can handle operators */ template inline RectangularMatrix operator*(const Vector& vector, const RectangularMatrix& matrix) { return RectangularMatrix<1, size, T>(vector)*matrix; diff --git a/src/Magnum/Math/Swizzle.h b/src/Magnum/Math/Swizzle.h index 66e6a07a2..47786aeae 100644 --- a/src/Magnum/Math/Swizzle.h +++ b/src/Magnum/Math/Swizzle.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Function Magnum::Math::swizzle() + * @brief Function @ref Magnum::Math::swizzle() */ #include "Magnum/Math/Vector.h" diff --git a/src/Magnum/Math/TypeTraits.h b/src/Magnum/Math/TypeTraits.h index 6d2a4c0c0..10c3fbbff 100644 --- a/src/Magnum/Math/TypeTraits.h +++ b/src/Magnum/Math/TypeTraits.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::Math::TypeTraits + * @brief Class @ref Magnum::Math::TypeTraits */ #include @@ -99,8 +99,8 @@ template struct TypeTraits: Implementation::TypeTraitsDefault { /** * @brief Fuzzy compare * - * Uses fuzzy compare for floating-point types (using epsilon() value), - * pure equality comparison everywhere else. + * Uses fuzzy compare for floating-point types (using @ref epsilon() + * value), pure equality comparison everywhere else. */ static bool equals(T a, T b); #endif diff --git a/src/Magnum/Math/Unit.h b/src/Magnum/Math/Unit.h index 1682fdd93..9b4803ed9 100644 --- a/src/Magnum/Math/Unit.h +++ b/src/Magnum/Math/Unit.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::Math::Unit + * @brief Class @ref Magnum::Math::Unit */ #include "Magnum/Math/TypeTraits.h" @@ -37,7 +37,7 @@ namespace Magnum { namespace Math { @brief Base class for units @tparam T Underlying data type -@see Deg, Rad +@see @ref Deg, @ref Rad */ template class Derived, class T> class Unit { template class, class> friend class Unit; diff --git a/src/Magnum/Math/Vector.h b/src/Magnum/Math/Vector.h index f8becd762..3d7de1285 100644 --- a/src/Magnum/Math/Vector.h +++ b/src/Magnum/Math/Vector.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::Math::Vector + * @brief Class @ref Magnum::Math::Vector */ #include @@ -92,7 +92,9 @@ template class Vector { * antiparallel. @f[ * \boldsymbol a \cdot \boldsymbol b = \sum_{i=0}^{n-1} \boldsymbol a_i \boldsymbol b_i * @f] - * @see dot() const, operator-(), Vector2::perpendicular() + * @see dot() const, @ref operator-(), + * @ref Vector2::perpendicular() + * @todoc Explicit reference when Doxygen can handle const */ static T dot(const Vector& a, const Vector& b) { return (a*b).sum(); @@ -104,7 +106,8 @@ template class Vector { * Expects that both vectors are normalized. @f[ * \theta = acos \left( \frac{\boldsymbol a \cdot \boldsymbol b}{|\boldsymbol a| |\boldsymbol b|} \right) = acos (\boldsymbol a \cdot \boldsymbol b) * @f] - * @see isNormalized(), Quaternion::angle(), Complex::angle() + * @see @ref isNormalized(), @ref Quaternion::angle(), + * @ref Complex::angle() */ static Rad angle(const Vector& normalizedA, const Vector& normalizedB); @@ -188,6 +191,7 @@ template class Vector { * @return One-dimensional array of `size` length. * * @see operator[]() + * @todoc Make explicit reference when Doxygen can handle operators */ T* data() { return _data; } constexpr const T* data() const { return _data; } /**< @overload */ @@ -195,7 +199,7 @@ template class Vector { /** * @brief Value at given position * - * @see data() + * @see @ref data() */ T& operator[](std::size_t pos) { return _data[pos]; } constexpr T operator[](std::size_t pos) const { return _data[pos]; } /**< @overload */ @@ -231,7 +235,7 @@ template class Vector { * @f[ * |\boldsymbol a \cdot \boldsymbol a - 0| < \epsilon^2 \cong \epsilon * @f] - * @see dot(), normalized() + * @see @ref dot(), @ref normalized() */ bool isZero() const { return Implementation::isZeroSquared(dot()); @@ -243,7 +247,7 @@ template class Vector { * The vector is normalized if it has unit length: @f[ * |\boldsymbol a \cdot \boldsymbol a - 1| < 2 \epsilon + \epsilon^2 \cong 2 \epsilon * @f] - * @see dot(), normalized() + * @see @ref dot(), @ref normalized() */ bool isNormalized() const { return Implementation::isNormalizedSquared(dot()); @@ -255,7 +259,7 @@ template class Vector { * @f[ * \boldsymbol b_i = -\boldsymbol a_i * @f] - * @see Vector2::perpendicular() + * @see @ref Vector2::perpendicular() */ Vector operator-() const; @@ -276,7 +280,8 @@ template class Vector { /** * @brief Add vector * - * @see operator+=(), sum() + * @see operator+=(), @ref sum() + * @todoc Make explicit reference when Doxygen can handle operators */ Vector operator+(const Vector& other) const { return Vector(*this) += other; @@ -299,7 +304,7 @@ template class Vector { /** * @brief Subtract vector * - * @see operator-=() + * @see @ref operator-=() */ Vector operator-(const Vector& other) const { return Vector(*this) -= other; @@ -313,6 +318,7 @@ template class Vector { * @f] * @see operator*=(const Vector&), * operator*=(Vector&, FloatingPoint) + * @todoc Make explicit reference when Doxygen can handle operators */ Vector& operator*=(T number) { for(std::size_t i = 0; i != size; ++i) @@ -327,6 +333,7 @@ template class Vector { * @see operator*(const Vector&) const, * operator*=(T), operator*(T, const Vector&), * operator*(const Vector&, FloatingPoint) + * @todoc Make explicit reference when Doxygen can handle operators */ Vector operator*(T number) const { return Vector(*this) *= number; @@ -340,6 +347,7 @@ template class Vector { * @f] * @see operator/=(const Vector&), * operator/=(Vector&, FloatingPoint) + * @todoc Make explicit reference when Doxygen can handle operators */ Vector& operator/=(T number) { for(std::size_t i = 0; i != size; ++i) @@ -354,6 +362,7 @@ template class Vector { * @see operator/(const Vector&) const, * operator/=(T), operator/(T, const Vector&), * operator/(const Vector&, FloatingPoint) + * @todoc Make explicit reference when Doxygen can handle operators */ Vector operator/(T number) const { return Vector(*this) /= number; @@ -367,6 +376,7 @@ template class Vector { * @f] * @see operator*=(T), * operator*=(Vector&, const Vector&) + * @todoc Make explicit reference when Doxygen can handle operators */ Vector& operator*=(const Vector& other) { for(std::size_t i = 0; i != size; ++i) @@ -381,6 +391,7 @@ template class Vector { * @see operator*(T) const, operator*=(const Vector&), * operator*(const Vector&, const Vector&), * @ref product() + * @todoc Make explicit reference when Doxygen can handle operators */ Vector operator*(const Vector& other) const { return Vector(*this) *= other; @@ -394,6 +405,7 @@ template class Vector { * @f] * @see operator/=(T), * operator/=(Vector&, const Vector&) + * @todoc Make explicit reference when Doxygen can handle operators */ Vector& operator/=(const Vector& other) { for(std::size_t i = 0; i != size; ++i) @@ -407,6 +419,7 @@ template class Vector { * * @see operator/(T) const, operator/=(const Vector&), * operator/(const Vector&, const Vector&) + * @todoc Make explicit reference when Doxygen can handle operators */ Vector operator/(const Vector& other) const { return Vector(*this) /= other; @@ -415,22 +428,24 @@ template class Vector { /** * @brief Dot product of the vector * - * Should be used instead of length() for comparing vector length with - * other values, because it doesn't compute the square root. @f[ + * Should be used instead of @ref length() for comparing vector length + * with other values, because it doesn't compute the square root. @f[ * \boldsymbol a \cdot \boldsymbol a = \sum_{i=0}^{n-1} \boldsymbol a_i^2 * @f] - * @see dot(const Vector&, const Vector&), isNormalized() + * @see @ref dot(const Vector&, const Vector&), + * @ref isNormalized() */ T dot() const { return dot(*this, *this); } /** * @brief %Vector length * - * See also dot() const which is faster for comparing length with other - * values. @f[ + * See also @ref dot() const which is faster for comparing length with + * other values. @f[ * |\boldsymbol a| = \sqrt{\boldsymbol a \cdot \boldsymbol a} * @f] - * @see lengthInverted(), Math::sqrt(), normalized(), resized() + * @see @ref lengthInverted(), @ref Math::sqrt(), @ref normalized(), + * @ref resized() * @todo something like std::hypot() for possibly better precision? */ T length() const { return std::sqrt(dot()); } @@ -441,14 +456,15 @@ template class Vector { * @f[ * \frac{1}{|\boldsymbol a|} = \frac{1}{\sqrt{\boldsymbol a \cdot \boldsymbol a}} * @f] - * @see length(), Math::sqrtInverted(), normalized(), resized() + * @see @ref length(), @ref Math::sqrtInverted(), @ref normalized(), + * @ref resized() */ T lengthInverted() const { return T(1)/length(); } /** * @brief Normalized vector (of unit length) * - * @see isNormalized(), lengthInverted(), resized() + * @see @ref isNormalized(), @ref lengthInverted(), @ref resized() */ Vector normalized() const { return *this*lengthInverted(); } @@ -456,12 +472,12 @@ template class Vector { * @brief Resized vector * * Convenience equivalent to the following code. Due to operation order - * this function is faster than the obvious way of sizing normalized() - * vector. + * this function is faster than the obvious way of sizing + * @ref normalized() vector. * @code * vec*(vec.lengthInverted()*length) // the brackets are important * @endcode - * @see normalized() + * @see @ref normalized() */ Vector resized(T length) const { return *this*(lengthInverted()*length); @@ -473,7 +489,7 @@ template class Vector { * Returns vector projected onto @p line. @f[ * \boldsymbol a_1 = \frac{\boldsymbol a \cdot \boldsymbol b}{\boldsymbol b \cdot \boldsymbol b} \boldsymbol b * @f] - * @see dot(), projectedOntoNormalized() + * @see @ref dot(), @ref projectedOntoNormalized() */ Vector projected(const Vector& line) const { return line*dot(*this, line)/line.dot(); @@ -482,8 +498,8 @@ template class Vector { /** * @brief %Vector projected onto normalized line * - * Slightly faster alternative to projected(), expects @p line to be - * normalized. @f[ + * Slightly faster alternative to @ref projected(), expects @p line to + * be normalized. @f[ * \boldsymbol a_1 = \frac{\boldsymbol a \cdot \boldsymbol b}{\boldsymbol b \cdot \boldsymbol b} \boldsymbol b = * (\boldsymbol a \cdot \boldsymbol b) \boldsymbol b * @f] @@ -495,6 +511,7 @@ template class Vector { * @brief Sum of values in the vector * * @see operator+() + * @todoc Make explicit reference when Doxygen can handle operators */ T sum() const; @@ -502,6 +519,7 @@ template class Vector { * @brief Product of values in the vector * * @see operator*(const Vector&) const + * @todoc Make explicit reference when Doxygen can handle operators */ T product() const; @@ -533,6 +551,7 @@ template class Vector { @brief Multiply number with vector Same as Vector::operator*(T) const. +@todoc Make explicit reference when Doxygen can handle operators */ template inline Vector operator*( #ifdef DOXYGEN_GENERATING_OUTPUT @@ -552,6 +571,7 @@ template inline Vector operator*( \boldsymbol c_i = \frac b {\boldsymbol a_i} @f] @see Vector::operator/(T) const +@todoc Make explicit reference when Doxygen can handle operators */ template inline Vector operator/( #ifdef DOXYGEN_GENERATING_OUTPUT @@ -842,6 +862,7 @@ operator>>(const Vector& vector, Similar to Vector::operator*=(T), except that the multiplication is done in floating-point. The computation is done in-place. +@todoc Make explicit reference when Doxygen can handle operators */ template inline #ifdef DOXYGEN_GENERATING_OUTPUT @@ -861,6 +882,7 @@ operator*=(Vector& vector, FloatingPoint number) { Similar to Vector::operator*(T) const, except that the multiplication is done in floating-point. +@todoc Make explicit reference when Doxygen can handle operators */ template inline #ifdef DOXYGEN_GENERATING_OUTPUT @@ -877,6 +899,7 @@ operator*(const Vector& vector, FloatingPoint number) { @brief Multiply floating-point number with integral vector Same as operator*(const Vector&, FloatingPoint). +@todoc Make explicit reference when Doxygen can handle operators */ template inline #ifdef DOXYGEN_GENERATING_OUTPUT @@ -893,6 +916,7 @@ operator*(FloatingPoint number, const Vector& vector) { Similar to Vector::operator/=(T), except that the division is done in floating-point. The computation is done in-place. +@todoc Make explicit reference when Doxygen can handle operators */ template inline #ifdef DOXYGEN_GENERATING_OUTPUT @@ -912,6 +936,7 @@ operator/=(Vector& vector, FloatingPoint number) { Similar to Vector::operator/(T) const, except that the division is done in floating-point. +@todoc Make explicit reference when Doxygen can handle operators */ template inline #ifdef DOXYGEN_GENERATING_OUTPUT @@ -929,6 +954,7 @@ operator/(const Vector& vector, FloatingPoint number) { Similar to Vector::operator*=(const Vector&), except that the multiplication is done in floating-point. The computation is done in-place. +@todoc Make explicit reference when Doxygen can handle operators */ template inline #ifdef DOXYGEN_GENERATING_OUTPUT @@ -946,10 +972,11 @@ operator*=(Vector& a, const Vector& b) { /** @relates Vector @brief Multiply integral vector with floating-point vector component-wise -Similar to Vector::operator*(const Vector&) const, except that the -multiplication is done in floating-point. The result is always integral vector, -convert both arguments to the same floating-point type to have floating-point -result. +Similar to Vector::operator*(const Vector&) const, except that +the multiplication is done in floating-point. The result is always integral +vector, convert both arguments to the same floating-point type to have +floating-point result. +@todoc Make explicit reference when Doxygen can handle operators */ template inline #ifdef DOXYGEN_GENERATING_OUTPUT @@ -966,6 +993,7 @@ operator*(const Vector& a, const Vector& b) @brief Multiply floating-point vector with integral vector component-wise Same as operator*(const Vector&, const Vector&). +@todoc Make explicit reference when Doxygen can handle operators */ template inline #ifdef DOXYGEN_GENERATING_OUTPUT @@ -982,6 +1010,7 @@ operator*(const Vector& a, const Vector& b) Similar to Vector::operator/=(const Vector&), except that the division is done in floating-point. The computation is done in-place. +@todoc Make explicit reference when Doxygen can handle operators */ template inline #ifdef DOXYGEN_GENERATING_OUTPUT @@ -999,10 +1028,11 @@ operator/=(Vector& a, const Vector& b) { /** @relates Vector @brief Divide integral vector with floating-point vector component-wise -Similar to Vector::operator/(const Vector&) const, except that the -division is done in floating-point. The result is always integral vector, +Similar to Vector::operator/(const Vector&) const, except that +the division is done in floating-point. The result is always integral vector, convert both arguments to the same floating-point type to have floating-point result. +@todoc Make explicit reference when Doxygen can handle operators */ template inline #ifdef DOXYGEN_GENERATING_OUTPUT diff --git a/src/Magnum/Math/Vector2.h b/src/Magnum/Math/Vector2.h index cbb9a7c7f..d40435e62 100644 --- a/src/Magnum/Math/Vector2.h +++ b/src/Magnum/Math/Vector2.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::Math::Vector2 + * @brief Class @ref Magnum::Math::Vector2 */ #include "Magnum/Math/Vector.h" @@ -38,7 +38,8 @@ namespace Magnum { namespace Math { @tparam T Data type See @ref matrix-vector for brief introduction. -@see Magnum::Vector2, Magnum::Vector2i, Magnum::Vector2ui, Magnum::Vector2d +@see @ref Magnum::Vector2, @ref Magnum::Vector2i, @ref Magnum::Vector2ui, + @ref Magnum::Vector2d @configurationvalueref{Magnum::Math::Vector2} */ template class Vector2: public Vector<2, T> { @@ -50,15 +51,15 @@ template class Vector2: public Vector<2, T> { * @code * Matrix3::translation(Vector2::xAxis(5.0f)); // same as Matrix3::translation({5.0f, 0.0f}); * @endcode - * @see yAxis(), xScale(), Matrix3::right() + * @see @ref yAxis(), @ref xScale(), @ref Matrix3::right() */ constexpr static Vector2 xAxis(T length = T(1)) { return {length, T(0)}; } /** * @brief %Vector in direction of Y axis (up) * - * See xAxis() for more information. - * @see yScale(), Matrix3::up() + * See @ref xAxis() for more information. + * @see @ref yScale(), @ref Matrix3::up() */ constexpr static Vector2 yAxis(T length = T(1)) { return {T(0), length}; } @@ -69,15 +70,15 @@ template class Vector2: public Vector<2, T> { * @code * Matrix3::scaling(Vector2::xScale(-2.0f)); // same as Matrix3::scaling({-2.0f, 1.0f}); * @endcode - * @see yScale(), xAxis() + * @see @ref yScale(), @ref xAxis() */ constexpr static Vector2 xScale(T scale) { return {scale, T(1)}; } /** * @brief Scaling vector in direction of Y axis (height) * - * See xScale() for more information. - * @see yAxis() + * See @ref xScale() for more information. + * @see @ref yAxis() */ constexpr static Vector2 yScale(T scale) { return {T(1), scale}; } @@ -85,12 +86,13 @@ template class Vector2: public Vector<2, T> { * @brief 2D cross product * * 2D version of cross product, also called perp-dot product, - * equivalent to calling Vector3::cross() with Z coordinate set to `0` - * and extracting only Z coordinate from the result (X and Y + * equivalent to calling @ref Vector3::cross() with Z coordinate set to + * `0` and extracting only Z coordinate from the result (X and Y * coordinates are always zero). @f[ * \boldsymbol a \times \boldsymbol b = \boldsymbol a_\bot \cdot \boldsymbol b = a_xb_y - a_yb_x * @f] - * @see perpendicular(), dot(const Vector&, const Vector&) + * @see @ref perpendicular(), + * @ref dot(const Vector&, const Vector&) */ static T cross(const Vector2& a, const Vector2& b) { return Vector<2, T>::dot(a.perpendicular(), b); @@ -131,7 +133,9 @@ template class Vector2: public Vector<2, T> { * Returns vector rotated 90° counterclockwise. @f[ * \boldsymbol v_\bot = \begin{pmatrix} -v_y \\ v_x \end{pmatrix} * @f] - * @see cross(), dot(const Vector&, const Vector&), operator-() const + * @see @ref cross(), + * @ref dot(const Vector&, const Vector&), + * @ref operator-() const */ Vector2 perpendicular() const { return {-y(), x()}; } diff --git a/src/Magnum/Math/Vector3.h b/src/Magnum/Math/Vector3.h index 038d7b78a..0bb553cc4 100644 --- a/src/Magnum/Math/Vector3.h +++ b/src/Magnum/Math/Vector3.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::Math::Vector3 + * @brief Class @ref Magnum::Math::Vector3 */ #include "Magnum/Math/Vector2.h" @@ -39,7 +39,8 @@ namespace Magnum { namespace Math { @tparam T Data type See @ref matrix-vector for brief introduction. -@see Magnum::Vector3, Magnum::Vector3i, Magnum::Vector3ui, Magnum::Vector3d +@see @ref Magnum::Vector3, @ref Magnum::Vector3i, @ref Magnum::Vector3ui, + @ref Magnum::Vector3d @configurationvalueref{Magnum::Math::Vector3} */ template class Vector3: public Vector<3, T> { @@ -107,7 +108,7 @@ template class Vector3: public Vector<3, T> { * \boldsymbol a \times \boldsymbol b = * \begin{pmatrix}a_yb_z - a_zb_y \\ a_zb_y - a_xb_z \\ a_xb_y - a_yb_x \end{pmatrix} * @f] - * @see Vector2::cross() + * @see @ref Vector2::cross() */ static Vector3 cross(const Vector3& a, const Vector3& b) { return swizzle<'y', 'z', 'x'>(a)*swizzle<'z', 'x', 'y'>(b) - @@ -199,7 +200,7 @@ template class Vector3: public Vector<3, T> { * @brief XY part of the vector * @return First two components of the vector * - * @see swizzle() + * @see @ref swizzle() */ Vector2& xy() { return Vector2::from(Vector<3, T>::data()); } constexpr const Vector2 xy() const { return {x(), y()}; } /**< @overload */ diff --git a/src/Magnum/Math/Vector4.h b/src/Magnum/Math/Vector4.h index 8a9f4e71c..fbedacf28 100644 --- a/src/Magnum/Math/Vector4.h +++ b/src/Magnum/Math/Vector4.h @@ -38,7 +38,8 @@ namespace Magnum { namespace Math { @tparam T Data type See @ref matrix-vector for brief introduction. -@see Magnum::Vector4, Magnum::Vector4i, Magnum::Vector4ui, Magnum::Vector4d +@see @ref Magnum::Vector4, @ref Magnum::Vector4i, @ref Magnum::Vector4ui, + @ref Magnum::Vector4d @configurationvalueref{Magnum::Math::Vector4} */ template class Vector4: public Vector<4, T> {