Provided by: libcoin60-doc_3.1.3-2_all

**NAME**

SbMatrix - TheSbMatrixclass is a 4x4 dimensional representation of a matrix.SbMatrixis 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>PublicMemberFunctionsSbMatrix(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)operatorfloat*(void)SbMatrix&operator=(constSbMatrix&m) voidsetValue(const SbMat &m) voidsetValue(const classSbDPMatrix&m) const SbMat &getValue(void) const voidmakeIdentity(void) voidsetRotate(constSbRotation&q)SbMatrixinverse(void) const floatdet3(int r1, int r2, int r3, int c1, int c2, int c3) const floatdet3(void) const floatdet4(void) const SbBoolequals(constSbMatrix&m, float tolerance) constoperatorSbMat&(void) float *operator[](int i) const float *operator[](int i) constSbMatrix&operator=(constSbRotation&q)SbMatrix&operator*=(constSbMatrix&m) voidgetValue(SbMat &m) const voidsetScale(const float s) voidsetScale(constSbVec3f&s) voidsetTranslate(constSbVec3f&t) voidsetTransform(constSbVec3f&t, constSbRotation&r, constSbVec3f&s) voidsetTransform(constSbVec3f&t, constSbRotation&r, constSbVec3f&s, constSbRotation&so) voidsetTransform(constSbVec3f&translation, constSbRotation&rotation, constSbVec3f&scaleFactor, constSbRotation&scaleOrientation, constSbVec3f¢er) voidgetTransform(SbVec3f&t,SbRotation&r,SbVec3f&s,SbRotation&so) const voidgetTransform(SbVec3f&translation,SbRotation&rotation,SbVec3f&scaleFactor,SbRotation&scaleOrientation, constSbVec3f¢er) const SbBoolfactor(SbMatrix&r,SbVec3f&s,SbMatrix&u,SbVec3f&t,SbMatrix&proj) SbBoolLUDecomposition(int index[4], float &d) voidLUBackSubstitution(int index[4], float b[4]) constSbMatrixtranspose(void) constSbMatrix&multRight(constSbMatrix&m)SbMatrix&multLeft(constSbMatrix&m) voidmultMatrixVec(constSbVec3f&src,SbVec3f&dst) const voidmultVecMatrix(constSbVec3f&src,SbVec3f&dst) const voidmultDirMatrix(constSbVec3f&src,SbVec3f&dst) const voidmultLineMatrix(constSbLine&src,SbLine&dst) const voidmultVecMatrix(constSbVec4f&src,SbVec4f&dst) const voidStaticPublicMemberFunctionsstaticSbMatrixidentity(void)FriendsSbMatrixoperator*(constSbMatrix&m1, constSbMatrix&m2) intoperator==(constSbMatrix&m1, constSbMatrix&m2) intoperator!=(constSbMatrix&m1, constSbMatrix&m2)

**Detailed** **Description**

TheSbMatrixclass is a 4x4 dimensional representation of a matrix.SbMatrixis 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 theSbMatrix::multRight()method. If you have a matrix in row-order from some other source, it can be 'converted' to column- order by transposing it withSbMatrix::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)Thedefaultconstructordoesnothing.Thematrixwillbeuninitialized.SbMatrix::SbMatrix(constfloata11,constfloata12,constfloata13,constfloata14,constfloata21,constfloata22,constfloata23,constfloata24,constfloata31,constfloata32,constfloata33,constfloata34,constfloata41,constfloata42,constfloata43,constfloata44)Constructsamatrixinstancewiththegiveninitialelements.SbMatrix::SbMatrix(constSbMat&matrixref)Constructsamatrixinstancewiththeinitialelementsfromthematrixargument.SbMatrix::SbMatrix(constSbMat*matrixptr)ThisconstructoriscourtesyoftheMicrosoftVisualC++compiler.SbMatrix::~SbMatrix(void)Defaultdestructordoesnothing.

**Member** **Function** **Documentation**

SbMatrix&SbMatrix::operator=(constSbMat&m)Assignmentoperator.Copiestheelementsfrommtothematrix.SbMatrix::operatorfloat*(void)Returnpointertothematrix'4x4floatarray.SbMatrix&SbMatrix::operator=(constSbMatrix&m)Assignmentoperator.Copiestheelementsfrommtothematrix.voidSbMatrix::setValue(constSbMat&m)Copiestheelementsfrommintothematrix.Seealso:getValue().constSbMat&SbMatrix::getValue(void)constReturnsapointertothe2dimensionalfloatarraywiththematrixelements.Seealso:setValue().voidSbMatrix::makeIdentity(void)Setthematrixtobetheidentitymatrix.Seealso:identity().voidSbMatrix::setRotate(constSbRotation&q)Setmatrixtobearotationmatrixwiththegivenrotation.Seealso:setTranslate(),setScale().SbMatrixSbMatrix::inverse(void)constReturnanewmatrixwhichistheinversematrixofthis.The user is responsible for checking that this is a valid operation to execute, by first making sure that the result ofSbMatrix::det4()is not equal to zero.floatSbMatrix::det3(intr1,intr2,intr3,intc1,intc2,intc3)constReturnsthedeterminantofthe3x3submatrixspecifiedbytherowandcolumnindices.floatSbMatrix::det3(void)constReturnsthedeterminantoftheupperleft3x3submatrix.floatSbMatrix::det4(void)constReturnsthedeterminantofthematrix.SbBoolSbMatrix::equals(constSbMatrix&m,floattolerance)constCheckifthemmatrixisequaltothisone,withinthegiventolerancevalue.Thetolerancevalueisappliedinthecomparisononacomponentbycomponentbasis.SbMatrix::operatorSbMat&(void)Returnpointertothematrix'4x4floatarray.float*SbMatrix::operator[](inti)Returnspointertothe4elementarrayrepresentingamatrixrow.ishouldbewithin[0,3].Seealso:getValue(),setValue().constfloat*SbMatrix::operator[](inti)constReturnspointertothe4elementarrayrepresentingamatrixrow.ishouldbewithin[0,3].Seealso:getValue(),setValue().SbMatrix&SbMatrix::operator=(constSbRotation&q)Setmatrixtobearotationmatrixwiththegivenrotation.Seealso:setRotate().SbMatrix&SbMatrix::operator*=(constSbMatrix&m)Right-multiplywiththemmatrix.Seealso:multRight().voidSbMatrix::getValue(SbMat&m)constReturnmatrixcomponentsintheSbMatstructure.Seealso:setValue().SbMatrixSbMatrix::identity(void)[static]Returntheidentitymatrix.Seealso:makeIdentity().voidSbMatrix::setScale(constfloats)Setmatrixtobeapurescalingmatrix.Scalefactorsarespecifiedbys.Seealso:setRotate(),setTranslate().voidSbMatrix::setScale(constSbVec3f&s)Setmatrixtobeapurescalingmatrix.Scalefactorsinx,yandzisspecifiedbythesvector.Seealso:setRotate(),setTranslate().voidSbMatrix::setTranslate(constSbVec3f&t)Makethismatrixintoapuretranslationmatrix(noscaleorrotationcomponents)withthegivenvectorasthetranslation.Seealso:setRotate(),setScale().voidSbMatrix::setTransform(constSbVec3f&t,constSbRotation&r,constSbVec3f&s)Settranslation,rotationandscalingallatonce.Theresultingmatrixgetscalculatedlikethis:M = S * R * T whereS,RandTis scaling, rotation and translation matrices.Seealso:setTranslate(),setRotate(),setScale()andgetTransform().voidSbMatrix::setTransform(constSbVec3f&t,constSbRotation&r,constSbVec3f&s,constSbRotation&so)Settranslation,rotationandscalingallatoncewithaspecifiedscaleorientation.Theresultingmatrixgetscalculatedlikethis:M = Ro-¹ * S * Ro * R * T whereRois the scale orientation, andS,RandTis scaling, rotation and translation.Seealso:setTranslate(),setRotate(),setScale()andgetTransform().voidSbMatrix::setTransform(constSbVec3f&translation,constSbRotation&rotation,constSbVec3f&scaleFactor,constSbRotation&scaleOrientation,constSbVec3f¢er)Settranslation,rotationandscalingallatoncewithaspecifiedscaleorientationandcenterpoint.Theresultingmatrixgetscalculatedlikethis:M = -Tc * Ro-¹ * S * Ro * R * T * Tc whereTcis the center point,Rothe scale orientation,S,RandTis scaling, rotation and translation.Seealso:setTranslate(),setRotate(),setScale()andgetTransform().voidSbMatrix::getTransform(SbVec3f&t,SbRotation&r,SbVec3f&s,SbRotation&so)constFactorthematrixbackintoitstranslation,rotation,scaleandscaleorientationcomponents.Seealso:factor()voidSbMatrix::getTransform(SbVec3f&translation,SbRotation&rotation,SbVec3f&scaleFactor,SbRotation&scaleOrientation,constSbVec3f¢er)constFactorthematrixbackintoitstranslation,rotation,scaleFactorandscaleorientationcomponents.Willeliminatethecentervariablefromthematrix.Seealso:factor()SbBoolSbMatrix::factor(SbMatrix&r,SbVec3f&s,SbMatrix&u,SbVec3f&t,SbMatrix&proj)ThisfunctionisnotimplementedinCoin.Seealso:getTransform()SbBoolSbMatrix::LUDecomposition(intindex[4],float&d)ThisfunctionproducesapermutedLUdecompositionofthematrix.Itusesthecommonsingle-row-pivotingstrategy.FALSEis 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.Seealso:SbMatrix::LUBackSubstitutionvoidSbMatrix::LUBackSubstitution(intindex[4],floatb[4])constThisfunctiondoesasolveonthe'Ax=b'system,giventhatthematrixisLU-decomposedinadvance.First,aforwardsubstitutionisdoneonthelowersystem(Ly=b),andthenabackwardssubstitutionisdoneontheuppertriangularsystem(Ux=y).The index[] argument is the one returned fromSbMatrix::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.SbMatrixSbMatrix::transpose(void)constReturnsthetransposeofthismatrix.SbMatrix&SbMatrix::multRight(constSbMatrix&m)Letthismatrixberight-multipliedbym.Returnsreferencetoself.This is the most common multiplication / concatenation operation when using column-order matrices, asSbMatrixinstances are, by definition.Seealso:multLeft()SbMatrix&SbMatrix::multLeft(constSbMatrix&m)Letthismatrixbeleft-multipliedbym.Returnsreferencetoself.(Be aware that it is more common to use theSbMatrix::multRight()operation, when doing concatenation of transformations, asSbMatrixinstances are by definition in column-order, and uses post-multiplication for common geometry operations.)Seealso:multRight()voidSbMatrix::multMatrixVec(constSbVec3f&src,SbVec3f&dst)constMultiplysrcvectorwiththismatrixandreturntheresultindst.Multiplicationisdonewiththevectorontherightsideoftheexpression,i.e.dst=M*src.(Be aware that it is more common to use theSbMatrix::multVecMatrix()operation, when doing vector transformations, asSbMatrixinstances are by definition in column-order, and uses post-multiplication for common geometry operations.)Seealso:multVecMatrix(),multDirMatrix()andmultLineMatrix().voidSbMatrix::multVecMatrix(constSbVec3f&src,SbVec3f&dst)constMultiplysrcvectorwiththismatrixandreturntheresultindst.Multiplicationisdonewiththevectorontheleftsideoftheexpression,i.e.dst=src*M.It is safe to letsrcanddstbe the sameSbVec3finstance. 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, asSbMatrixinstances are, by definition, column-order matrices.Seealso:multMatrixVec(),multDirMatrix()andmultLineMatrix().voidSbMatrix::multDirMatrix(constSbVec3f&src,SbVec3f&dst)constMultipliessrcbythematrix.srcisassumedtobeadirectionvector,andthetranslationcomponentsofthematrixarethereforeignored.Multiplication is done with the vector on the left side of the expression, i.e. dst = src * M.Seealso:multVecMatrix(),multMatrixVec()andmultLineMatrix().voidSbMatrix::multLineMatrix(constSbLine&src,SbLine&dst)constMultiplieslinepointwiththefullmatrixandmultipliesthelinedirectionwiththematrixwithoutthetranslationcomponents.Seealso:multVecMatrix(),multMatrixVec()andmultDirMatrix().voidSbMatrix::multVecMatrix(constSbVec4f&src,SbVec4f&dst)constThisisanoverloadedmemberfunction,providedforconvenience.Itdiffersfromtheabovefunctiononlyinwhatargument(s)itaccepts.voidSbMatrix::print(FILE*fp)constWriteoutthematrixcontentstothegivenfile.

**Friends** **And** **Related** **Function** **Documentation**

SbMatrixoperator*(constSbMatrix&m1,constSbMatrix&m2)[friend]Multipliesmatrixm1withmatrixm2andreturnstheresultantmatrix.intoperator==(constSbMatrix&m1,constSbMatrix&m2)[friend]Comparematricestoseeiftheyareequal.Fortwomatricestobeequal,alltheirindividualelementsmustbeequal.Seealso:equals().intoperator!=(constSbMatrix&m1,constSbMatrix&m2)[friend]Comparematricestoseeiftheyarenotequal.Fortwomatricestonotbeequal,itisenoughthatatleastoneoftheirelementsareunequal.Seealso:equals().

**Author**

Generated automatically by Doxygen for Coin from the source code.