Engine/lib/bullet/src/LinearMath/btPolarDecomposition.h

   1 #ifndef POLARDECOMPOSITION_H
   2 #define POLARDECOMPOSITION_H
   3
   4 #include "btMatrix3x3.h"
   5
   6 /**
   7  * This class is used to compute the polar decomposition of a matrix. In
   8  * general, the polar decomposition factorizes a matrix, A, into two parts: a
   9  * unitary matrix (U) and a positive, semi-definite Hermitian matrix (H).
  10  * However, in this particular implementation the original matrix, A, is
  11  * required to be a square 3x3 matrix with real elements. This means that U will
  12  * be an orthogonal matrix and H with be a positive-definite, symmetric matrix.
  13  */
  14 class btPolarDecomposition
  15 {
  16   public:
  17
  18
  19     /**
  20      * Creates an instance with optional parameters.
  21      *
  22      * @param tolerance     - the tolerance used to determine convergence of the
  23      *                        algorithm
  24      * @param maxIterations - the maximum number of iterations used to achieve
  25      *                        convergence
  26      */
  27     btPolarDecomposition(btScalar tolerance = btScalar(0.0001),
  28       unsigned int maxIterations = 16);
  29
  30     /**
  31      * Decomposes a matrix into orthogonal and symmetric, positive-definite
  32      * parts. If the number of iterations returned by this function is equal to
  33      * the maximum number of iterations, the algorithm has failed to converge.
  34      *
  35      * @param a - the original matrix
  36      * @param u - the resulting orthogonal matrix
  37      * @param h - the resulting symmetric matrix
  38      *
  39      * @return the number of iterations performed by the algorithm.
  40      */
  41     unsigned int decompose(const btMatrix3x3& a, btMatrix3x3& u, btMatrix3x3& h) const;
  42
  43     /**
  44      * Returns the maximum number of iterations that this algorithm will perform
  45      * to achieve convergence.
  46      *
  47      * @return maximum number of iterations
  48      */
  49     unsigned int maxIterations() const;
  50
  51   private:
  52     btScalar m_tolerance;
  53     unsigned int m_maxIterations;
  54 };
  55
  56 /**
  57  * This functions decomposes the matrix 'a' into two parts: an orthogonal matrix
  58  * 'u' and a symmetric, positive-definite matrix 'h'. If the number of
  59  * iterations returned by this function is equal to
  60  * btPolarDecomposition::DEFAULT_MAX_ITERATIONS, the algorithm has failed to
  61  * converge.
  62  *
  63  * @param a - the original matrix
  64  * @param u - the resulting orthogonal matrix
  65  * @param h - the resulting symmetric matrix
  66  *
  67  * @return the number of iterations performed by the algorithm.
  68  */
  69 unsigned int polarDecompose(const btMatrix3x3& a, btMatrix3x3& u, btMatrix3x3& h);
  70
  71 #endif // POLARDECOMPOSITION_H
  72