ic
/
magnum
mirror of https://github.com/mosra/magnum.git
6
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Math: improve docs of matrix queries.

pull/191/head
Vladimír Vondruš 8 years ago
parent
a3b425bd26
commit
086ed8a278
2 changed files with 188 additions and 17 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 93
      src/Magnum/Math/Matrix3.h
  2. 112
      src/Magnum/Math/Matrix4.h

93
src/Magnum/Math/Matrix3.h
Unescape View File

@ -259,7 +259,14 @@ template<class T> class Matrix3: public Matrix3x3<T> {
/**
* @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<T>&, const Vector2<T>&),
* @ref rotation() const, @ref rotationNormalized(),
* @ref uniformScaling(), @ref rotation(Rad<T>),
@ -274,7 +281,14 @@ template<class T> class Matrix3: public Matrix3x3<T> {
* @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 T> class Matrix3: public Matrix3x3<T> {
* @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<T>),
* @ref Matrix4::rotation() const
@ -308,7 +341,14 @@ template<class T> class Matrix3: public Matrix3x3<T> {
* 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<T>&),
* @ref Matrix4::uniformScaling()
@ -325,7 +365,23 @@ template<class T> class Matrix3: public Matrix3x3<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.
* @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<T>&),
* @ref Matrix4::uniformScaling()
@ -335,7 +391,14 @@ template<class T> class Matrix3: public Matrix3x3<T> {
/**
* @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<T>& right() { return (*this)[0].xy(); }
@ -344,7 +407,14 @@ template<class T> class Matrix3: public Matrix3x3<T> {
/**
* @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<T>& up() { return (*this)[1].xy(); }
@ -353,7 +423,14 @@ template<class T> class Matrix3: public Matrix3x3<T> {
/**
* @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<T>&, const Vector2<T>&),
* @ref translation(const Vector2<T>&),
* @ref Matrix4::translation()

112
src/Magnum/Math/Matrix4.h
Unescape View File

@ -433,7 +433,15 @@ template<class T> class Matrix4: public Matrix4x4<T> {
/**
* @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<T>&, const Vector3<T>&),
* @ref rotation() const, @ref rotationNormalized(),
* @ref uniformScaling(), @ref rotation(Rad, const Vector3<T>&),
@ -449,7 +457,15 @@ template<class T> class Matrix4: public Matrix4x4<T> {
* @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 T> class Matrix4: public Matrix4x4<T> {
* @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<T>&),
* @ref Matrix3::rotation() const
@ -479,7 +515,15 @@ template<class T> class Matrix4: public Matrix4x4<T> {
* 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<T>&),
* @ref Matrix3::uniformScaling()
@ -491,7 +535,25 @@ template<class T> class Matrix4: public Matrix4x4<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.
* @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<T>&),
* @ref Matrix3::uniformScaling()
@ -501,7 +563,15 @@ template<class T> class Matrix4: public Matrix4x4<T> {
/**
* @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 T> class Matrix4: public Matrix4x4<T> {
/**
* @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 T> class Matrix4: public Matrix4x4<T> {
/**
* @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<T>& backward() { return (*this)[2].xyz(); }
@ -530,7 +616,15 @@ template<class T> class Matrix4: public Matrix4x4<T> {
/**
* @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<T>&, const Vector3<T>&),
* @ref translation(const Vector3<T>&),
* @ref Matrix3::translation()

Write Preview
Loading…
Cancel
Save