.TH "SbMatrix" 3 "Thu May 29 2014" "Version 4.0.0a" "Coin" \" -*- nroff -*- .ad l .nh .SH NAME SbMatrix \- .PP The \fBSbMatrix\fP class is a 4x4 dimensional representation of a matrix\&. .PP \fBSbMatrix\fP is used by many other classes in Coin\&. It provides storage for a 4x4 matrix of single-precision floating point values\&. .SH SYNOPSIS .br .PP .SS "Public Member Functions" .in +1c .ti -1c .RI "\fBSbMatrix\fP (void)" .br .ti -1c .RI "\fBSbMatrix\fP (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)" .br .ti -1c .RI "\fBSbMatrix\fP (const SbMat &matrix)" .br .ti -1c .RI "\fBSbMatrix\fP (const SbMat *matrix)" .br .ti -1c .RI "\fBSbMatrix\fP (const class \fBSbDPMatrix\fP &matrix)" .br .ti -1c .RI "\fB~SbMatrix\fP (void)" .br .ti -1c .RI "void \fBsetValue\fP (const SbMat &m)" .br .ti -1c .RI "void \fBsetValue\fP (const class \fBSbDPMatrix\fP &m)" .br .ti -1c .RI "void \fBsetValue\fP (const float *pMat)" .br .ti -1c .RI "const SbMat & \fBgetValue\fP (void) const " .br .ti -1c .RI "void \fBmakeIdentity\fP (void)" .br .ti -1c .RI "void \fBsetRotate\fP (const \fBSbRotation\fP &q)" .br .ti -1c .RI "\fBSbMatrix\fP \fBinverse\fP (void) const " .br .ti -1c .RI "float \fBdet3\fP (int r1, int r2, int r3, int c1, int c2, int c3) const " .br .ti -1c .RI "float \fBdet3\fP (void) const " .br .ti -1c .RI "float \fBdet4\fP (void) const " .br .ti -1c .RI "SbBool \fBequals\fP (const \fBSbMatrix\fP &m, float tolerance) const " .br .ti -1c .RI "void \fBgetValue\fP (SbMat &m) const " .br .ti -1c .RI "void \fBsetScale\fP (const float s)" .br .ti -1c .RI "void \fBsetScale\fP (const \fBSbVec3f\fP &s)" .br .ti -1c .RI "void \fBsetTranslate\fP (const \fBSbVec3f\fP &t)" .br .ti -1c .RI "void \fBsetTransform\fP (const \fBSbVec3f\fP &t, const \fBSbRotation\fP &r, const \fBSbVec3f\fP &s)" .br .ti -1c .RI "void \fBsetTransform\fP (const \fBSbVec3f\fP &t, const \fBSbRotation\fP &r, const \fBSbVec3f\fP &s, const \fBSbRotation\fP &so)" .br .ti -1c .RI "void \fBsetTransform\fP (const \fBSbVec3f\fP &translation, const \fBSbRotation\fP &rotation, const \fBSbVec3f\fP &scaleFactor, const \fBSbRotation\fP &scaleOrientation, const \fBSbVec3f\fP ¢er)" .br .ti -1c .RI "void \fBgetTransform\fP (\fBSbVec3f\fP &t, \fBSbRotation\fP &r, \fBSbVec3f\fP &s, \fBSbRotation\fP &so) const " .br .ti -1c .RI "void \fBgetTransform\fP (\fBSbVec3f\fP &translation, \fBSbRotation\fP &rotation, \fBSbVec3f\fP &scaleFactor, \fBSbRotation\fP &scaleOrientation, const \fBSbVec3f\fP ¢er) const " .br .ti -1c .RI "SbBool \fBfactor\fP (\fBSbMatrix\fP &r, \fBSbVec3f\fP &s, \fBSbMatrix\fP &u, \fBSbVec3f\fP &t, \fBSbMatrix\fP &proj)" .br .ti -1c .RI "SbBool \fBLUDecomposition\fP (int index[4], float &d)" .br .ti -1c .RI "void \fBLUBackSubstitution\fP (int index[4], float b[4]) const " .br .ti -1c .RI "\fBSbMatrix\fP \fBtranspose\fP (void) const " .br .ti -1c .RI "\fBSbMatrix\fP & \fBmultRight\fP (const \fBSbMatrix\fP &m)" .br .ti -1c .RI "\fBSbMatrix\fP & \fBmultLeft\fP (const \fBSbMatrix\fP &m)" .br .ti -1c .RI "void \fBmultMatrixVec\fP (const \fBSbVec3f\fP &src, \fBSbVec3f\fP &dst) const " .br .ti -1c .RI "void \fBmultVecMatrix\fP (const \fBSbVec3f\fP &src, \fBSbVec3f\fP &dst) const " .br .ti -1c .RI "void \fBmultDirMatrix\fP (const \fBSbVec3f\fP &src, \fBSbVec3f\fP &dst) const " .br .ti -1c .RI "void \fBmultLineMatrix\fP (const \fBSbLine\fP &src, \fBSbLine\fP &dst) const " .br .ti -1c .RI "void \fBmultVecMatrix\fP (const \fBSbVec4f\fP &src, \fBSbVec4f\fP &dst) const " .br .ti -1c .RI "void \fBprint\fP (FILE *fp) const " .br .ti -1c .RI "\fBoperator float *\fP (void)" .br .ti -1c .RI "\fBoperator SbMat &\fP (void)" .br .ti -1c .RI "float * \fBoperator[]\fP (int i)" .br .ti -1c .RI "const float * \fBoperator[]\fP (int i) const " .br .ti -1c .RI "\fBSbMatrix\fP & \fBoperator=\fP (const SbMat &m)" .br .ti -1c .RI "\fBSbMatrix\fP & \fBoperator=\fP (const \fBSbMatrix\fP &m)" .br .ti -1c .RI "\fBSbMatrix\fP & \fBoperator=\fP (const \fBSbRotation\fP &q)" .br .ti -1c .RI "\fBSbMatrix\fP & \fBoperator*=\fP (const \fBSbMatrix\fP &m)" .br .in -1c .SS "Static Public Member Functions" .in +1c .ti -1c .RI "static \fBSbMatrix\fP \fBidentity\fP (void)" .br .in -1c .SS "Friends" .in +1c .ti -1c .RI "\fBSbMatrix\fP \fBoperator*\fP (const \fBSbMatrix\fP &m1, const \fBSbMatrix\fP &m2)" .br .ti -1c .RI "int \fBoperator==\fP (const \fBSbMatrix\fP &m1, const \fBSbMatrix\fP &m2)" .br .ti -1c .RI "int \fBoperator!=\fP (const \fBSbMatrix\fP &m1, const \fBSbMatrix\fP &m2)" .br .in -1c .SH "Detailed Description" .PP The \fBSbMatrix\fP class is a 4x4 dimensional representation of a matrix\&. .PP \fBSbMatrix\fP 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\&. .PP 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 \fBSbMatrix::multRight()\fP method\&. .PP If you have a matrix in row-order from some other source, it can be 'converted' to column-order by transposing it with \fBSbMatrix::transpose()\fP\&. A simple example will help to explain this\&. .PP With row-order matrices, a transformation matrix with position, rotation and scale looks like this: .PP .PP .nf M = T * R * S .fi .PP .PP 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: .PP .PP .nf M = S * R * T .fi .PP .PP 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: .PP .PP .nf M = T * R * S .fi .PP .PP Converting M from a row-order matrix to a column-order matrix is done as follows: .PP .PP .nf 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 .fi .PP .PP All left to be done is to remove the transpose symbols, and the matrices have been converted to column-order matrices: .PP .PP .nf M = S * R * T .fi .PP .PP This was done using the fact that: .PP .PP .nf A^t = (B * C)^t = C^t * B^t .fi .PP .PP Converting from column-order to row-order is done using the same principle\&. .SH "Constructor & Destructor Documentation" .PP .SS "SbMatrix::SbMatrix (void)" The default constructor does nothing\&. The matrix will be uninitialized\&. .SS "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\&. .SS "SbMatrix::SbMatrix (const SbMat &matrixref)" Constructs a matrix instance with the initial elements from the \fImatrix\fP argument\&. .SS "SbMatrix::SbMatrix (const SbMat *matrixptr)" This constructor is courtesy of the Microsoft Visual C++ compiler\&. .SS "SbMatrix::~SbMatrix (void)" Default destructor does nothing\&. .SH "Member Function Documentation" .PP .SS "void SbMatrix::setValue (const SbMat &m)" Copies the elements from \fIm\fP into the matrix\&. .PP \fBSee also:\fP .RS 4 \fBgetValue()\fP\&. .RE .PP .SS "void SbMatrix::setValue (const float *pMat)" Copies the elements from \fIpMat\fP into the matrix\&. .PP \fBSee also:\fP .RS 4 \fBgetValue()\fP\&. .RE .PP .SS "const SbMat & SbMatrix::getValue (void) const" Returns a pointer to the 2 dimensional float array with the matrix elements\&. .PP \fBSee also:\fP .RS 4 \fBsetValue()\fP\&. .RE .PP .SS "void SbMatrix::makeIdentity (void)" Set the matrix to be the identity matrix\&. .PP \fBSee also:\fP .RS 4 \fBidentity()\fP\&. .RE .PP .SS "void SbMatrix::setRotate (const \fBSbRotation\fP &q)" Set matrix to be a rotation matrix with the given rotation\&. .PP \fBSee also:\fP .RS 4 \fBsetTranslate()\fP, \fBsetScale()\fP\&. .RE .PP .SS "\fBSbMatrix\fP SbMatrix::inverse (void) const" Return a new matrix which is the inverse matrix of this\&. .PP The user is responsible for checking that this is a valid operation to execute, by first making sure that the result of \fBSbMatrix::det4()\fP is not equal to zero\&. .SS "float SbMatrix::det3 (intr1, intr2, intr3, intc1, intc2, intc3) const" Returns the determinant of the 3x3 submatrix specified by the row and column indices\&. .SS "float SbMatrix::det3 (void) const" Returns the determinant of the upper left 3x3 submatrix\&. .SS "float SbMatrix::det4 (void) const" Returns the determinant of the matrix\&. .SS "SbBool SbMatrix::equals (const \fBSbMatrix\fP &m, floattolerance) const" Check if the \fIm\fP 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\&. .SS "void SbMatrix::getValue (SbMat &m) const" Return matrix components in the SbMat structure\&. .PP \fBSee also:\fP .RS 4 \fBsetValue()\fP\&. .RE .PP .SS "\fBSbMatrix\fP SbMatrix::identity (void)\fC [static]\fP" Return the identity matrix\&. .PP \fBSee also:\fP .RS 4 \fBmakeIdentity()\fP\&. .RE .PP .SS "void SbMatrix::setScale (const floats)" Set matrix to be a pure scaling matrix\&. Scale factors are specified by \fIs\fP\&. .PP \fBSee also:\fP .RS 4 \fBsetRotate()\fP, \fBsetTranslate()\fP\&. .RE .PP .SS "void SbMatrix::setScale (const \fBSbVec3f\fP &s)" Set matrix to be a pure scaling matrix\&. Scale factors in x, y and z is specified by the \fIs\fP vector\&. .PP \fBSee also:\fP .RS 4 \fBsetRotate()\fP, \fBsetTranslate()\fP\&. .RE .PP .SS "void SbMatrix::setTranslate (const \fBSbVec3f\fP &t)" Make this matrix into a pure translation matrix (no scale or rotation components) with the given vector as the translation\&. .PP \fBSee also:\fP .RS 4 \fBsetRotate()\fP, \fBsetScale()\fP\&. .RE .PP .SS "void SbMatrix::setTransform (const \fBSbVec3f\fP &t, const \fBSbRotation\fP &r, const \fBSbVec3f\fP &s)" Set translation, rotation and scaling all at once\&. The resulting matrix gets calculated like this: .PP .PP .nf M = S * R * T .fi .PP .PP where \fIS\fP, \fIR\fP and \fIT\fP is scaling, rotation and translation matrices\&. .PP \fBSee also:\fP .RS 4 \fBsetTranslate()\fP, \fBsetRotate()\fP, \fBsetScale()\fP and \fBgetTransform()\fP\&. .RE .PP .SS "void SbMatrix::setTransform (const \fBSbVec3f\fP &t, const \fBSbRotation\fP &r, const \fBSbVec3f\fP &s, const \fBSbRotation\fP &so)" Set translation, rotation and scaling all at once with a specified scale orientation\&. The resulting matrix gets calculated like this: .PP .PP .nf M = Ro-¹ * S * Ro * R * T .fi .PP .PP where \fIRo\fP is the scale orientation, and \fIS\fP, \fIR\fP and \fIT\fP is scaling, rotation and translation\&. .PP \fBSee also:\fP .RS 4 \fBsetTranslate()\fP, \fBsetRotate()\fP, \fBsetScale()\fP and \fBgetTransform()\fP\&. .RE .PP .SS "void SbMatrix::setTransform (const \fBSbVec3f\fP &translation, const \fBSbRotation\fP &rotation, const \fBSbVec3f\fP &scaleFactor, const \fBSbRotation\fP &scaleOrientation, const \fBSbVec3f\fP ¢er)" Set translation, rotation and scaling all at once with a specified scale orientation and center point\&. The resulting matrix gets calculated like this: .PP .PP .nf M = -Tc * Ro-¹ * S * Ro * R * T * Tc .fi .PP .PP where \fITc\fP is the center point, \fIRo\fP the scale orientation, \fIS\fP, \fIR\fP and \fIT\fP is scaling, rotation and translation\&. .PP \fBSee also:\fP .RS 4 \fBsetTranslate()\fP, \fBsetRotate()\fP, \fBsetScale()\fP and \fBgetTransform()\fP\&. .RE .PP .SS "void SbMatrix::getTransform (\fBSbVec3f\fP &t, \fBSbRotation\fP &r, \fBSbVec3f\fP &s, \fBSbRotation\fP &so) const" Factor the matrix back into its translation, rotation, scale and scaleorientation components\&. .PP \fBSee also:\fP .RS 4 \fBfactor()\fP .RE .PP .SS "void SbMatrix::getTransform (\fBSbVec3f\fP &translation, \fBSbRotation\fP &rotation, \fBSbVec3f\fP &scaleFactor, \fBSbRotation\fP &scaleOrientation, const \fBSbVec3f\fP ¢er) const" Factor the matrix back into its \fItranslation\fP, \fIrotation\fP, \fIscaleFactor\fP and \fIscaleorientation\fP components\&. Will eliminate the \fIcenter\fP variable from the matrix\&. .PP \fBSee also:\fP .RS 4 \fBfactor()\fP .RE .PP .SS "SbBool SbMatrix::factor (\fBSbMatrix\fP &r, \fBSbVec3f\fP &s, \fBSbMatrix\fP &u, \fBSbVec3f\fP &t, \fBSbMatrix\fP &proj)" This function is not implemented in Coin\&. .PP \fBSee also:\fP .RS 4 \fBgetTransform()\fP .RE .PP .SS "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\&. .PP \fIFALSE\fP 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)\&. .PP 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\&. .PP 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! .PP 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\&. .PP \fBSee also:\fP .RS 4 \fBSbMatrix::LUBackSubstitution\fP .RE .PP .SS "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)\&. .PP The index[] argument is the one returned from \fBSbMatrix::LUDecomposition()\fP, so see that function for an explanation\&. .PP 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\&. .PP BUGS: As is done by Open Inventor, unsolvable x values will not return NaN but 0\&. .SS "\fBSbMatrix\fP SbMatrix::transpose (void) const" Returns the transpose of this matrix\&. .SS "\fBSbMatrix\fP & SbMatrix::multRight (const \fBSbMatrix\fP &m)" Let this matrix be right-multiplied by \fIm\fP\&. Returns reference to self\&. .PP This is the most common multiplication / concatenation operation when using column-order matrices, as \fBSbMatrix\fP instances are, by definition\&. .PP \fBSee also:\fP .RS 4 \fBmultLeft()\fP .RE .PP .SS "\fBSbMatrix\fP & SbMatrix::multLeft (const \fBSbMatrix\fP &m)" Let this matrix be left-multiplied by \fIm\fP\&. Returns reference to self\&. .PP (Be aware that it is more common to use the \fBSbMatrix::multRight()\fP operation, when doing concatenation of transformations, as \fBSbMatrix\fP instances are by definition in column-order, and uses post-multiplication for common geometry operations\&.) .PP \fBSee also:\fP .RS 4 \fBmultRight()\fP .RE .PP .SS "void SbMatrix::multMatrixVec (const \fBSbVec3f\fP &src, \fBSbVec3f\fP &dst) const" Multiply \fIsrc\fP vector with this matrix and return the result in \fIdst\fP\&. Multiplication is done with the vector on the right side of the expression, i\&.e\&. dst = M * src\&. .PP (Be aware that it is more common to use the \fBSbMatrix::multVecMatrix()\fP operation, when doing vector transformations, as \fBSbMatrix\fP instances are by definition in column-order, and uses post-multiplication for common geometry operations\&.) .PP \fBSee also:\fP .RS 4 \fBmultVecMatrix()\fP, \fBmultDirMatrix()\fP and \fBmultLineMatrix()\fP\&. .RE .PP .SS "void SbMatrix::multVecMatrix (const \fBSbVec3f\fP &src, \fBSbVec3f\fP &dst) const" Multiply \fIsrc\fP vector with this matrix and return the result in \fIdst\fP\&. Multiplication is done with the vector on the left side of the expression, i\&.e\&. dst = src * M\&. .PP It is safe to let \fIsrc\fP and \fIdst\fP be the same \fBSbVec3f\fP instance\&. .PP This method can be used (using the current model matrix) to transform a point from an object coordinate systems to the world coordinate system\&. .PP This operation is what you would usually do when transforming vectors, as \fBSbMatrix\fP instances are, by definition, column-order matrices\&. .PP \fBSee also:\fP .RS 4 \fBmultMatrixVec()\fP, \fBmultDirMatrix()\fP and \fBmultLineMatrix()\fP\&. .RE .PP .SS "void SbMatrix::multDirMatrix (const \fBSbVec3f\fP &src, \fBSbVec3f\fP &dst) const" Multiplies \fIsrc\fP by the matrix\&. \fIsrc\fP is assumed to be a direction vector, and the translation components of the matrix are therefore ignored\&. .PP Multiplication is done with the vector on the left side of the expression, i\&.e\&. dst = src * M\&. .PP \fBSee also:\fP .RS 4 \fBmultVecMatrix()\fP, \fBmultMatrixVec()\fP and \fBmultLineMatrix()\fP\&. .RE .PP .SS "void SbMatrix::multLineMatrix (const \fBSbLine\fP &src, \fBSbLine\fP &dst) const" Multiplies line point with the full matrix and multiplies the line direction with the matrix without the translation components\&. .PP \fBSee also:\fP .RS 4 \fBmultVecMatrix()\fP, \fBmultMatrixVec()\fP and \fBmultDirMatrix()\fP\&. .RE .PP .SS "void SbMatrix::multVecMatrix (const \fBSbVec4f\fP &src, \fBSbVec4f\fP &dst) const" This is an overloaded member function, provided for convenience\&. It differs from the above function only in what argument(s) it accepts\&. .SS "void SbMatrix::print (FILE *fp) const" Write out the matrix contents to the given file\&. .SS "SbMatrix::operator float * (void)" Return pointer to the matrix' 4x4 float array\&. .SS "SbMatrix::operator SbMat & (void)" Return pointer to the matrix' 4x4 float array\&. .SS "float * SbMatrix::operator[] (inti)" Returns pointer to the 4 element array representing a matrix row\&. \fIi\fP should be within [0, 3]\&. .PP \fBSee also:\fP .RS 4 \fBgetValue()\fP, \fBsetValue()\fP\&. .RE .PP .SS "const float * SbMatrix::operator[] (inti) const" Returns pointer to the 4 element array representing a matrix row\&. \fIi\fP should be within [0, 3]\&. .PP \fBSee also:\fP .RS 4 \fBgetValue()\fP, \fBsetValue()\fP\&. .RE .PP .SS "\fBSbMatrix\fP & SbMatrix::operator= (const SbMat &m)" Assignment operator\&. Copies the elements from \fIm\fP to the matrix\&. .SS "\fBSbMatrix\fP & SbMatrix::operator= (const \fBSbMatrix\fP &m)" Assignment operator\&. Copies the elements from \fIm\fP to the matrix\&. .SS "\fBSbMatrix\fP & SbMatrix::operator= (const \fBSbRotation\fP &q)" Set matrix to be a rotation matrix with the given rotation\&. .PP \fBSee also:\fP .RS 4 \fBsetRotate()\fP\&. .RE .PP .SS "\fBSbMatrix\fP & SbMatrix::operator*= (const \fBSbMatrix\fP &m)" Right-multiply with the \fIm\fP matrix\&. .PP \fBSee also:\fP .RS 4 \fBmultRight()\fP\&. .RE .PP .SH "Friends And Related Function Documentation" .PP .SS "\fBSbMatrix\fP operator* (const \fBSbMatrix\fP &m1, const \fBSbMatrix\fP &m2)\fC [friend]\fP" Multiplies matrix \fIm1\fP with matrix \fIm2\fP and returns the resultant matrix\&. .SS "int operator== (const \fBSbMatrix\fP &m1, const \fBSbMatrix\fP &m2)\fC [friend]\fP" Compare matrices to see if they are equal\&. For two matrices to be equal, all their individual elements must be equal\&. .PP \fBSee also:\fP .RS 4 \fBequals()\fP\&. .RE .PP .SS "int operator!= (const \fBSbMatrix\fP &m1, const \fBSbMatrix\fP &m2)\fC [friend]\fP" 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\&. .PP \fBSee also:\fP .RS 4 \fBequals()\fP\&. .RE .PP .SH "Author" .PP Generated automatically by Doxygen for Coin from the source code\&.