Provided by: libcoin60-doc_3.1.3-2_all bug

NAME

       SbMatrix -

       The SbMatrix class is a 4x4 dimensional representation of a matrix.

       SbMatrix is used by many other classes in Coin. It provides storage for a 4x4 matrix of
       single-precision floating point values.

SYNOPSIS

       #include <Inventor/SbLinear.h>

   Public Member Functions
       SbMatrix (void)
       SbMatrix (const float a11, const float a12, const float a13, const float a14, const float
           a21, const float a22, const float a23, const float a24, const float a31, const float
           a32, const float a33, const float a34, const float a41, const float a42, const float
           a43, const float a44)
       SbMatrix (const SbMat &matrix)
       SbMatrix (const SbMat *matrix)
       ~SbMatrix (void)
       SbMatrix & operator= (const SbMat &m)
       operator float * (void)
       SbMatrix & operator= (const SbMatrix &m)
       void setValue (const SbMat &m)
       void setValue (const class SbDPMatrix &m)
       const SbMat & getValue (void) const
       void makeIdentity (void)
       void setRotate (const SbRotation &q)
       SbMatrix inverse (void) const
       float det3 (int r1, int r2, int r3, int c1, int c2, int c3) const
       float det3 (void) const
       float det4 (void) const
       SbBool equals (const SbMatrix &m, float tolerance) const
       operator SbMat & (void)
       float * operator[] (int i)
       const float * operator[] (int i) const
       SbMatrix & operator= (const SbRotation &q)
       SbMatrix & operator*= (const SbMatrix &m)
       void getValue (SbMat &m) const
       void setScale (const float s)
       void setScale (const SbVec3f &s)
       void setTranslate (const SbVec3f &t)
       void setTransform (const SbVec3f &t, const SbRotation &r, const SbVec3f &s)
       void setTransform (const SbVec3f &t, const SbRotation &r, const SbVec3f &s, const
           SbRotation &so)
       void setTransform (const SbVec3f &translation, const SbRotation &rotation, const SbVec3f
           &scaleFactor, const SbRotation &scaleOrientation, const SbVec3f &center)
       void getTransform (SbVec3f &t, SbRotation &r, SbVec3f &s, SbRotation &so) const
       void getTransform (SbVec3f &translation, SbRotation &rotation, SbVec3f &scaleFactor,
           SbRotation &scaleOrientation, const SbVec3f &center) const
       SbBool factor (SbMatrix &r, SbVec3f &s, SbMatrix &u, SbVec3f &t, SbMatrix &proj)
       SbBool LUDecomposition (int index[4], float &d)
       void LUBackSubstitution (int index[4], float b[4]) const
       SbMatrix transpose (void) const
       SbMatrix & multRight (const SbMatrix &m)
       SbMatrix & multLeft (const SbMatrix &m)
       void multMatrixVec (const SbVec3f &src, SbVec3f &dst) const
       void multVecMatrix (const SbVec3f &src, SbVec3f &dst) const
       void multDirMatrix (const SbVec3f &src, SbVec3f &dst) const
       void multLineMatrix (const SbLine &src, SbLine &dst) const
       void multVecMatrix (const SbVec4f &src, SbVec4f &dst) const
       void print (FILE *fp) const

   Static Public Member Functions
       static SbMatrix identity (void)

   Friends
       SbMatrix operator* (const SbMatrix &m1, const SbMatrix &m2)
       int operator== (const SbMatrix &m1, const SbMatrix &m2)
       int operator!= (const SbMatrix &m1, const SbMatrix &m2)

Detailed Description

       The SbMatrix class is a 4x4 dimensional representation of a matrix.

       SbMatrix is used by many other classes in Coin. It provides storage for a 4x4 matrix of
       single-precision floating point values.

       By definition, matrices in Coin should be set up in column-order mode. This is the same
       order as used by e.g. OpenGL, but note that books on geometry often uses the opposite row-
       order mode, which can confuse new-comers to the API.

       Another way to think of column-order matrices is that they use post-order multiplications:
       that is, to concatenate a transformation from a second matrix with your current matrix, it
       should be multiplied on the right-hand side, i.e. with the SbMatrix::multRight() method.

       If you have a matrix in row-order from some other source, it can be 'converted' to column-
       order by transposing it with SbMatrix::transpose(). A simple example will help to explain
       this.

       With row-order matrices, a transformation matrix with position, rotation and scale looks
       like this:

         M = T * R * S

       Where T is translation, R is rotation and S is the scale. What this means is that scale is
       applied first. The scaled matrix is then rotated, and finally the scaled and rotated
       matrix is translated. When using column-order matrices, as done in Coin, matrices are
       represented slightly differently; the order of multiplication is reversed:

         M = S * R * T

       The transformation is just the same as the row-order matrix. The only difference being the
       order of multiplication. To understand why this is so, consider the sample transformation:

         M = T * R * S

       Converting M from a row-order matrix to a column-order matrix is done as follows:

         M^t = (T * R * S)^t
         M^t = ((T * R) * S)^t
         M^t = S^t * (T * R)^t
         M^t = S^t * R^t * T^t

       All left to be done is to remove the transpose symbols, and the matrices have been
       converted to column-order matrices:

         M = S * R * T

       This was done using the fact that:

         A^t = (B * C)^t = C^t * B^t

       Converting from column-order to row-order is done using the same principle.

Constructor & Destructor Documentation

   SbMatrix::SbMatrix (void) The default constructor does nothing. The matrix will be
       uninitialized.
   SbMatrix::SbMatrix (const floata11, const floata12, const floata13, const floata14, const
       floata21, const floata22, const floata23, const floata24, const floata31, const floata32,
       const floata33, const floata34, const floata41, const floata42, const floata43, const
       floata44) Constructs a matrix instance with the given initial elements.
   SbMatrix::SbMatrix (const SbMat &matrixref) Constructs a matrix instance with the initial
       elements from the matrix argument.
   SbMatrix::SbMatrix (const SbMat *matrixptr) This constructor is courtesy of the Microsoft
       Visual C++ compiler.
   SbMatrix::~SbMatrix (void) Default destructor does nothing.

Member Function Documentation

   SbMatrix & SbMatrix::operator= (const SbMat &m) Assignment operator. Copies the elements from
       m to the matrix.
   SbMatrix::operator float * (void) Return pointer to the matrix' 4x4 float array.
   SbMatrix & SbMatrix::operator= (const SbMatrix &m) Assignment operator. Copies the elements
       from m to the matrix.
   void SbMatrix::setValue (const SbMat &m) Copies the elements from m into the matrix.
       See also:
           getValue().

   const SbMat & SbMatrix::getValue (void) const Returns a pointer to the 2 dimensional float
       array with the matrix elements.
       See also:
           setValue().

   void SbMatrix::makeIdentity (void) Set the matrix to be the identity matrix.
       See also:
           identity().

   void SbMatrix::setRotate (const SbRotation &q) Set matrix to be a rotation matrix with the
       given rotation.
       See also:
           setTranslate(), setScale().

   SbMatrix SbMatrix::inverse (void) const Return a new matrix which is the inverse matrix of
       this.
       The user is responsible for checking that this is a valid operation to execute, by first
       making sure that the result of SbMatrix::det4() is not equal to zero.

   float SbMatrix::det3 (intr1, intr2, intr3, intc1, intc2, intc3) const Returns the determinant
       of the 3x3 submatrix specified by the row and column indices.
   float SbMatrix::det3 (void) const Returns the determinant of the upper left 3x3 submatrix.
   float SbMatrix::det4 (void) const Returns the determinant of the matrix.
   SbBool SbMatrix::equals (const SbMatrix &m, floattolerance) const Check if the m matrix is
       equal to this one, within the given tolerance value. The tolerance value is applied in the
       comparison on a component by component basis.
   SbMatrix::operator SbMat & (void) Return pointer to the matrix' 4x4 float array.
   float * SbMatrix::operator[] (inti) Returns pointer to the 4 element array representing a
       matrix row. i should be within [0, 3].
       See also:
           getValue(), setValue().

   const float * SbMatrix::operator[] (inti) const Returns pointer to the 4 element array
       representing a matrix row. i should be within [0, 3].
       See also:
           getValue(), setValue().

   SbMatrix & SbMatrix::operator= (const SbRotation &q) Set matrix to be a rotation matrix with
       the given rotation.
       See also:
           setRotate().

   SbMatrix & SbMatrix::operator*= (const SbMatrix &m) Right-multiply with the m matrix.
       See also:
           multRight().

   void SbMatrix::getValue (SbMat &m) const Return matrix components in the SbMat structure.
       See also:
           setValue().

   SbMatrix SbMatrix::identity (void) [static] Return the identity matrix.
       See also:
           makeIdentity().

   void SbMatrix::setScale (const floats) Set matrix to be a pure scaling matrix. Scale factors
       are specified by s.
       See also:
           setRotate(), setTranslate().

   void SbMatrix::setScale (const SbVec3f &s) Set matrix to be a pure scaling matrix. Scale
       factors in x, y and z is specified by the s vector.
       See also:
           setRotate(), setTranslate().

   void SbMatrix::setTranslate (const SbVec3f &t) Make this matrix into a pure translation matrix
       (no scale or rotation components) with the given vector as the translation.
       See also:
           setRotate(), setScale().

   void SbMatrix::setTransform (const SbVec3f &t, const SbRotation &r, const SbVec3f &s) Set
       translation, rotation and scaling all at once. The resulting matrix gets calculated like
       this:
         M = S * R * T

       where S, R and T is scaling, rotation and translation matrices.

       See also:
           setTranslate(), setRotate(), setScale() and getTransform().

   void SbMatrix::setTransform (const SbVec3f &t, const SbRotation &r, const SbVec3f &s, const
       SbRotation &so) Set translation, rotation and scaling all at once with a specified scale
       orientation. The resulting matrix gets calculated like this:
         M = Ro-¹ * S * Ro * R * T

       where Ro is the scale orientation, and S, R and T is scaling, rotation and translation.

       See also:
           setTranslate(), setRotate(), setScale() and getTransform().

   void SbMatrix::setTransform (const SbVec3f &translation, const SbRotation &rotation, const
       SbVec3f &scaleFactor, const SbRotation &scaleOrientation, const SbVec3f &center) Set
       translation, rotation and scaling all at once with a specified scale orientation and
       center point. The resulting matrix gets calculated like this:
         M = -Tc * Ro-¹ * S * Ro * R * T * Tc

       where Tc is the center point, Ro the scale orientation, S, R and T is scaling, rotation
       and translation.

       See also:
           setTranslate(), setRotate(), setScale() and getTransform().

   void SbMatrix::getTransform (SbVec3f &t, SbRotation &r, SbVec3f &s, SbRotation &so) const
       Factor the matrix back into its translation, rotation, scale and scaleorientation
       components.
       See also:
           factor()

   void SbMatrix::getTransform (SbVec3f &translation, SbRotation &rotation, SbVec3f &scaleFactor,
       SbRotation &scaleOrientation, const SbVec3f &center) const Factor the matrix back into its
       translation, rotation, scaleFactor and scaleorientation components. Will eliminate the
       center variable from the matrix.
       See also:
           factor()

   SbBool SbMatrix::factor (SbMatrix &r, SbVec3f &s, SbMatrix &u, SbVec3f &t, SbMatrix &proj)
       This function is not implemented in Coin.
       See also:
           getTransform()

   SbBool SbMatrix::LUDecomposition (intindex[4], float &d) This function produces a permuted LU
       decomposition of the matrix. It uses the common single-row-pivoting strategy.
       FALSE is returned if the matrix is singular, which it never is, because of small
       adjustment values inserted if a singularity is found (as Open Inventor does too).

       The parity argument is always set to 1.0 or -1.0. Don't really know what it's for, so it's
       not checked for correctness.

       The index[] argument returns the permutation that was done on the matrix to LU-decompose
       it. index[i] is the row that row i was swapped with at step i in the decomposition, so
       index[] is not the actual permutation of the row indexes!

       BUGS: The function does not produce results that are numerically identical with those
       produced by Open Inventor for the same matrices, because the pivoting strategy in OI was
       never fully understood.

       See also:
           SbMatrix::LUBackSubstitution

   void SbMatrix::LUBackSubstitution (intindex[4], floatb[4]) const This function does a solve on
       the 'Ax = b' system, given that the matrix is LU-decomposed in advance. First, a forward
       substitution is done on the lower system (Ly = b), and then a backwards substitution is
       done on the upper triangular system (Ux = y).
       The index[] argument is the one returned from SbMatrix::LUDecomposition(), so see that
       function for an explanation.

       The b[] argument must contain the b vector in 'Ax = b' when calling the function. After
       the function has solved the system, the b[] vector contains the x vector.

       BUGS: As is done by Open Inventor, unsolvable x values will not return NaN but 0.

   SbMatrix SbMatrix::transpose (void) const Returns the transpose of this matrix.
   SbMatrix & SbMatrix::multRight (const SbMatrix &m) Let this matrix be right-multiplied by m.
       Returns reference to self.
       This is the most common multiplication / concatenation operation when using column-order
       matrices, as SbMatrix instances are, by definition.

       See also:
           multLeft()

   SbMatrix & SbMatrix::multLeft (const SbMatrix &m) Let this matrix be left-multiplied by m.
       Returns reference to self.
       (Be aware that it is more common to use the SbMatrix::multRight() operation, when doing
       concatenation of transformations, as SbMatrix instances are by definition in column-order,
       and uses post-multiplication for common geometry operations.)

       See also:
           multRight()

   void SbMatrix::multMatrixVec (const SbVec3f &src, SbVec3f &dst) const Multiply src vector with
       this matrix and return the result in dst. Multiplication is done with the vector on the
       right side of the expression, i.e. dst = M * src.
       (Be aware that it is more common to use the SbMatrix::multVecMatrix() operation, when
       doing vector transformations, as SbMatrix instances are by definition in column-order, and
       uses post-multiplication for common geometry operations.)

       See also:
           multVecMatrix(), multDirMatrix() and multLineMatrix().

   void SbMatrix::multVecMatrix (const SbVec3f &src, SbVec3f &dst) const Multiply src vector with
       this matrix and return the result in dst. Multiplication is done with the vector on the
       left side of the expression, i.e. dst = src * M.
       It is safe to let src and dst be the same SbVec3f instance.

       This method can be used (using the current model matrix) to transform a point from an
       object coordinate systems to the world coordinate system.

       This operation is what you would usually do when transforming vectors, as SbMatrix
       instances are, by definition, column-order matrices.

       See also:
           multMatrixVec(), multDirMatrix() and multLineMatrix().

   void SbMatrix::multDirMatrix (const SbVec3f &src, SbVec3f &dst) const Multiplies src by the
       matrix. src is assumed to be a direction vector, and the translation components of the
       matrix are therefore ignored.
       Multiplication is done with the vector on the left side of the expression, i.e. dst = src
       * M.

       See also:
           multVecMatrix(), multMatrixVec() and multLineMatrix().

   void SbMatrix::multLineMatrix (const SbLine &src, SbLine &dst) const Multiplies line point
       with the full matrix and multiplies the line direction with the matrix without the
       translation components.
       See also:
           multVecMatrix(), multMatrixVec() and multDirMatrix().

   void SbMatrix::multVecMatrix (const SbVec4f &src, SbVec4f &dst) const This is an overloaded
       member function, provided for convenience. It differs from the above function only in what
       argument(s) it accepts.
   void SbMatrix::print (FILE *fp) const Write out the matrix contents to the given file.

Friends And Related Function Documentation

   SbMatrix operator* (const SbMatrix &m1, const SbMatrix &m2) [friend] Multiplies matrix m1 with
       matrix m2 and returns the resultant matrix.
   int operator== (const SbMatrix &m1, const SbMatrix &m2) [friend] Compare matrices to see if
       they are equal. For two matrices to be equal, all their individual elements must be equal.
       See also:
           equals().

   int operator!= (const SbMatrix &m1, const SbMatrix &m2) [friend] Compare matrices to see if
       they are not equal. For two matrices to not be equal, it is enough that at least one of
       their elements are unequal.
       See also:
           equals().

Author

       Generated automatically by Doxygen for Coin from the source code.