From 086ed8a278df652b8d72e513bbce8dce6d3eea5e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Thu, 26 Jul 2018 01:13:06 +0200 Subject: [PATCH] Math: improve docs of matrix queries. --- src/Magnum/Math/Matrix3.h | 93 ++++++++++++++++++++++++++++--- src/Magnum/Math/Matrix4.h | 112 +++++++++++++++++++++++++++++++++++--- 2 files changed, 188 insertions(+), 17 deletions(-) diff --git a/src/Magnum/Math/Matrix3.h b/src/Magnum/Math/Matrix3.h index 8b976746e..05f0df34d 100644 --- a/src/Magnum/Math/Matrix3.h +++ b/src/Magnum/Math/Matrix3.h @@ -259,7 +259,14 @@ template class Matrix3: public Matrix3x3 { /** * @brief 2D rotation and scaling part of the matrix * - * Upper-left 2x2 part of the matrix. + * Upper-left 2x2 part of the matrix. @f[ + * \begin{pmatrix} + * \color{m-danger} a_x & \color{m-success} b_x & t_x \\ + * \color{m-danger} a_y & \color{m-success} b_y & t_y \\ + * \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 + * \end{pmatrix} + * @f] + * * @see @ref from(const Matrix2x2&, const Vector2&), * @ref rotation() const, @ref rotationNormalized(), * @ref uniformScaling(), @ref rotation(Rad), @@ -274,7 +281,14 @@ template class Matrix3: public Matrix3x3 { * @brief 2D rotation part of the matrix assuming there is no scaling * * Similar to @ref rotationScaling(), but additionally checks that the - * base vectors are normalized. + * base vectors are normalized. Check its documentation for caveats. @f[ + * \begin{pmatrix} + * \color{m-danger} a_x & \color{m-success} b_x & t_x \\ + * \color{m-danger} a_y & \color{m-success} b_y & t_y \\ + * \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 + * \end{pmatrix} + * @f] + * * @see @ref rotation() const, @ref uniformScaling(), * @ref Matrix4::rotationNormalized() * @todo assert also orthogonality or this is good enough? @@ -290,7 +304,26 @@ template class Matrix3: public Matrix3x3 { * @brief 2D rotation part of the matrix * * Normalized upper-left 2x2 part of the matrix. Expects uniform - * scaling. + * scaling. @f[ + * \begin{pmatrix} + * \color{m-danger} a_x & \color{m-success} b_x & t_x \\ + * \color{m-danger} a_y & \color{m-success} b_y & t_y \\ + * \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 + * \end{pmatrix} + * @f] + * + * @note Extracting rotation part of a matrix this way will cause + * assertions in case you have unsanitized input (for example a + * model transformation loaded from an external source) or when + * you accumulate many transformations together (for example when + * controlling a FPS camera). To mitigate this, either renormalize + * the matrix using @ref Algorithms::gramSchmidtOrthogonalize() or + * @ref Algorithms::svd() first, use a different transformation + * representation that suffers less floating point error and can + * be easier renormalized such as @ref DualComplex, or, ignore the + * error and extract combined non-uniform rotation and scaling + * with @ref rotationScaling(). + * * @see @ref rotationNormalized(), @ref rotationScaling(), * @ref uniformScaling(), @ref rotation(Rad), * @ref Matrix4::rotation() const @@ -308,7 +341,14 @@ template class Matrix3: public Matrix3x3 { * Squared length of vectors in upper-left 2x2 part of the matrix. * Expects that the scaling is the same in all axes. Faster alternative * to @ref uniformScaling(), because it doesn't compute the square - * root. + * root. See its documentation for caveats. @f[ + * \begin{pmatrix} + * \color{m-warning} a_x & \color{m-warning} b_x & t_x \\ + * \color{m-warning} a_y & \color{m-warning} b_y & t_y \\ + * \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 + * \end{pmatrix} + * @f] + * * @see @ref rotationScaling(), @ref rotation() const, * @ref rotationNormalized(), @ref scaling(const Vector2&), * @ref Matrix4::uniformScaling() @@ -325,7 +365,23 @@ template class Matrix3: public Matrix3x3 { * * 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. + * @ref uniformScalingSquared() where possible. @f[ + * \begin{pmatrix} + * \color{m-warning} a_x & \color{m-warning} b_x & t_x \\ + * \color{m-warning} a_y & \color{m-warning} b_y & t_y \\ + * \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 + * \end{pmatrix} + * @f] + * + * @note Extracting uniform scaling of a matrix this way will cause + * assertions in case you have unsanitized input (for example a + * model transformation loaded from an external source) or when + * you accumulate many transformations together (for example when + * controlling a FPS camera). To mitigate this, either renormalize + * the matrix using @ref Algorithms::gramSchmidtOrthogonalize() or + * @ref Algorithms::svd() first or extract the scaling manually by + * calculating lengths of @ref right() and @ref up() vectors. + * * @see @ref rotationScaling(), @ref rotation() const, * @ref rotationNormalized(), @ref scaling(const Vector2&), * @ref Matrix4::uniformScaling() @@ -335,7 +391,14 @@ template class Matrix3: public Matrix3x3 { /** * @brief Right-pointing 2D vector * - * First two elements of first column. + * First two elements of first column. @f[ + * \begin{pmatrix} + * \color{m-danger} a_x & b_x & t_x \\ + * \color{m-danger} a_y & b_y & t_y \\ + * \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 + * \end{pmatrix} + * @f] + * * @see @ref up(), @ref Vector2::xAxis(), @ref Matrix4::right() */ Vector2& right() { return (*this)[0].xy(); } @@ -344,7 +407,14 @@ template class Matrix3: public Matrix3x3 { /** * @brief Up-pointing 2D vector * - * First two elements of second column. + * First two elements of second column. @f[ + * \begin{pmatrix} + * a_x & \color{m-success} b_x & t_x \\ + * a_y & \color{m-success} b_y & t_y \\ + * \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 + * \end{pmatrix} + * @f] + * * @see @ref right(), @ref Vector2::yAxis(), @ref Matrix4::up() */ Vector2& up() { return (*this)[1].xy(); } @@ -353,7 +423,14 @@ template class Matrix3: public Matrix3x3 { /** * @brief 2D translation part of the matrix * - * First two elements of third column. + * First two elements of third column. @f[ + * \begin{pmatrix} + * a_x & b_x & \color{m-warning} t_x \\ + * a_y & b_y & \color{m-warning} t_y \\ + * \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 + * \end{pmatrix} + * @f] + * * @see @ref from(const Matrix2x2&, const Vector2&), * @ref translation(const Vector2&), * @ref Matrix4::translation() diff --git a/src/Magnum/Math/Matrix4.h b/src/Magnum/Math/Matrix4.h index c62b660a3..7a2ad4e43 100644 --- a/src/Magnum/Math/Matrix4.h +++ b/src/Magnum/Math/Matrix4.h @@ -433,7 +433,15 @@ template class Matrix4: public Matrix4x4 { /** * @brief 3D rotation and scaling part of the matrix * - * Upper-left 3x3 part of the matrix. + * Upper-left 3x3 part of the matrix. @f[ + * \begin{pmatrix} + * \color{m-danger} a_x & \color{m-success} b_x & \color{m-info} c_x & t_x \\ + * \color{m-danger} a_y & \color{m-success} b_y & \color{m-info} c_y & t_y \\ + * \color{m-danger} a_z & \color{m-success} b_z & \color{m-info} c_z & t_z \\ + * \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 + * \end{pmatrix} + * @f] + * * @see @ref from(const Matrix3x3&, const Vector3&), * @ref rotation() const, @ref rotationNormalized(), * @ref uniformScaling(), @ref rotation(Rad, const Vector3&), @@ -449,7 +457,15 @@ template class Matrix4: public Matrix4x4 { * @brief 3D rotation part of the matrix assuming there is no scaling * * Similar to @ref rotationScaling(), but additionally checks that the - * base vectors are normalized. + * base vectors are normalized. Check its documentation for caveats. @f[ + * \begin{pmatrix} + * \color{m-danger} a_x & \color{m-success} b_x & \color{m-info} c_x & t_x \\ + * \color{m-danger} a_y & \color{m-success} b_y & \color{m-info} c_y & t_y \\ + * \color{m-danger} a_z & \color{m-success} b_z & \color{m-info} c_z & t_z \\ + * \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 + * \end{pmatrix} + * @f] + * * @see @ref rotation() const, @ref uniformScaling(), * @ref Matrix3::rotationNormalized() * @todo assert also orthogonality or this is good enough? @@ -466,7 +482,27 @@ template class Matrix4: public Matrix4x4 { * @brief 3D rotation part of the matrix * * Normalized upper-left 3x3 part of the matrix. Expects uniform - * scaling. + * scaling. @f[ + * \begin{pmatrix} + * \color{m-danger} a_x & \color{m-success} b_x & \color{m-info} c_x & t_x \\ + * \color{m-danger} a_y & \color{m-success} b_y & \color{m-info} c_y & t_y \\ + * \color{m-danger} a_z & \color{m-success} b_z & \color{m-info} c_z & t_z \\ + * \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 + * \end{pmatrix} + * @f] + * + * @note Extracting rotation part of a matrix this way will cause + * assertions in case you have unsanitized input (for example a + * model transformation loaded from an external source) or when + * you accumulate many transformations together (for example when + * controlling a FPS camera). To mitigate this, either renormalize + * the matrix using @ref Algorithms::gramSchmidtOrthogonalize() or + * @ref Algorithms::svd() first, use a different transformation + * representation that suffers less floating point error and can + * be easier renormalized such as @ref DualQuaternion, or, ignore + * the error and extract combined non-uniform rotation and scaling + * with @ref rotationScaling(). + * * @see @ref rotationNormalized(), @ref rotationScaling(), * @ref uniformScaling(), @ref rotation(Rad, const Vector3&), * @ref Matrix3::rotation() const @@ -479,7 +515,15 @@ template class Matrix4: public Matrix4x4 { * Squared length of vectors in upper-left 3x3 part of the matrix. * Expects that the scaling is the same in all axes. Faster alternative * to @ref uniformScaling(), because it doesn't compute the square - * root. + * root. See its documentation for caveats. @f[ + * \begin{pmatrix} + * \color{m-warning} a_x & \color{m-warning} b_x & \color{m-warning} c_x & t_x \\ + * \color{m-warning} a_y & \color{m-warning} b_y & \color{m-warning} c_y & t_y \\ + * \color{m-warning} a_z & \color{m-warning} b_z & \color{m-warning} c_z & t_z \\ + * \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 + * \end{pmatrix} + * @f] + * * @see @ref rotationScaling(), @ref rotation() const, * @ref rotationNormalized(), @ref scaling(const Vector3&), * @ref Matrix3::uniformScaling() @@ -491,7 +535,25 @@ template class Matrix4: public Matrix4x4 { * * 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. + * @ref uniformScalingSquared() where possible. @f[ + * \begin{pmatrix} + * \color{m-warning} a_x & \color{m-warning} b_x & \color{m-warning} c_x & t_x \\ + * \color{m-warning} a_y & \color{m-warning} b_y & \color{m-warning} c_y & t_y \\ + * \color{m-warning} a_z & \color{m-warning} b_z & \color{m-warning} c_z & t_z \\ + * \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 + * \end{pmatrix} + * @f] + * + * @note Extracting uniform scaling of a matrix this way will cause + * assertions in case you have unsanitized input (for example a + * model transformation loaded from an external source) or when + * you accumulate many transformations together (for example when + * controlling a FPS camera). To mitigate this, either renormalize + * the matrix using @ref Algorithms::gramSchmidtOrthogonalize() or + * @ref Algorithms::svd() first or extract the scaling manually by + * calculating lengths of @ref right(), @ref up() and + * @ref backward() vectors. + * * @see @ref rotationScaling(), @ref rotation() const, * @ref rotationNormalized(), @ref scaling(const Vector3&), * @ref Matrix3::uniformScaling() @@ -501,7 +563,15 @@ template class Matrix4: public Matrix4x4 { /** * @brief Right-pointing 3D vector * - * First three elements of first column. + * First three elements of first column. @f[ + * \begin{pmatrix} + * \color{m-danger} a_x & b_x & c_x & t_x \\ + * \color{m-danger} a_y & b_y & c_y & t_y \\ + * \color{m-danger} a_z & b_z & c_z & t_z \\ + * \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 + * \end{pmatrix} + * @f] + * * @see @ref up(), @ref backward(), @ref Vector3::xAxis(), * @ref Matrix3::right() */ @@ -511,7 +581,15 @@ template class Matrix4: public Matrix4x4 { /** * @brief Up-pointing 3D vector * - * First three elements of second column. + * First three elements of second column. @f[ + * \begin{pmatrix} + * a_x & \color{m-success} b_x & c_x & t_x \\ + * a_y & \color{m-success} b_y & c_y & t_y \\ + * a_z & \color{m-success} b_z & c_z & t_z \\ + * \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 + * \end{pmatrix} + * @f] + * * @see @ref right(), @ref backward(), @ref Vector3::yAxis(), * @ref Matrix3::up() */ @@ -521,7 +599,15 @@ template class Matrix4: public Matrix4x4 { /** * @brief Backward-pointing 3D vector * - * First three elements of third column. + * First three elements of third column. @f[ + * \begin{pmatrix} + * a_x & b_x & \color{m-info} c_x & t_x \\ + * a_y & b_y & \color{m-info} c_y & t_y \\ + * a_z & b_z & \color{m-info} c_z & t_z \\ + * \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 + * \end{pmatrix} + * @f] + * * @see @ref right(), @ref up(), @ref Vector3::yAxis() */ Vector3& backward() { return (*this)[2].xyz(); } @@ -530,7 +616,15 @@ template class Matrix4: public Matrix4x4 { /** * @brief 3D translation part of the matrix * - * First three elements of fourth column. + * First three elements of fourth column. @f[ + * \begin{pmatrix} + * a_x & b_x & c_x & \color{m-warning} t_x \\ + * a_y & b_y & c_y & \color{m-warning} t_y \\ + * a_z & b_z & c_z & \color{m-warning} t_z \\ + * \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 + * \end{pmatrix} + * @f] + * * @see @ref from(const Matrix3x3&, const Vector3&), * @ref translation(const Vector3&), * @ref Matrix3::translation()