sbmatrix(3)

NAME

SbMatrix

SYNOPSIS

#include <Inventor/SbLinear.h>

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 newcomers to the API.

Another way to think of column-order matrices is that they use postorder 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.
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)
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)

Constructor & Destructor Documentation

SbMatrix::SbMatrix (void): The default constructor does nothing. The matrix will be uninitialized.; Referenced by identity().
SbMatrix::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)
Constructs a matrix instance with the given initial elements.; References setValue().
SbMatrix::SbMatrix (const SbMat & matrixref): Constructs a matrix instance with the initial elements from the matrix argument.; References setValue().
SbMatrix::SbMatrix (const SbMat * matrixptr): This constructor is courtesy of the Microsoft Visual C++ compiler.; References setValue().
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.; References setValue().
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.; References matrix, and setValue().
void SbMatrix::setValue (const SbMat & m): Copies the elements from m into the matrix.; See also:
getValue().; Referenced by operator=(), and SbMatrix().
const SbMat & SbMatrix::getValue (void) const: Returns a pointer to the 2 dimensional float array with the matrix
elements.; See also:
setValue().; Referenced by SbViewVolume::getAlignRotation().
void SbMatrix::makeIdentity (void): Set the matrix to be the identity matrix.; See also:
identity().; Referenced by SoGetMatrixAction::beginTraversal(),
SoResetTransform::callback(), SbXfBox3f::extendBy(),
SoVRMLTextureTransform::pick(), SoTexture2Transform::pick(),
SoBumpMapTransform::pick(), SbProjector::SbProjector(),
SbXfBox3f::SbXfBox3f(), setScale(), and setTranslate().
void SbMatrix::setRotate (const SbRotation & q): Set matrix to be a rotation matrix with the given rotation.; See also:
setTranslate(), setScale().; References SbRotation::getValue().; Referenced by SbRotation::multVec(), operator=(), and setTransform().
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.; References identity(), matrix, and SoDebugError::postWarning().; Referenced by SoDragger::appendRotation(),
SoTexture2Transform::callback(), SoVRMLTextureTransform::GLRender(),
SbProjector::setWorkingSpace(), and SbPlane::transform().
float SbMatrix::det3 (int r1, int r2, int r3, int c1, int c2, int c3) const: Returns the determinant of the 3x3 submatrix specified by the row and
column indices.; References SoDebugError::post().; Referenced by SbXfBox3f::getVolume().
float SbMatrix::det3 (void) const: Returns the determinant of the upper left 3x3 submatrix.; Referenced by det4().
float SbMatrix::det4 (void) const: Returns the determinant of the matrix.; References det3().
SbBool SbMatrix::equals (const SbMatrix & m, float tolerance) 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.; References matrix, and SoDebugError::postWarning().
SbMatrix::operator SbMat & (void): Return pointer to the matrix' 4x4 float array.
float * SbMatrix::operator[] (int i): Returns pointer to the 4 element array representing a matrix row. i
should be within [0, 3].; See also:
getValue(), setValue().; References SoDebugError::post().
const float * SbMatrix::operator[] (int i) const: Returns pointer to the 4 element array representing a matrix row. i
should be within [0, 3].; See also:
getValue(), setValue().; References SoDebugError::postWarning().
SbMatrix & SbMatrix::operator= (const SbRotation & q): Set matrix to be a rotation matrix with the given rotation.; See also:
setRotate().; References setRotate().
SbMatrix & SbMatrix::operator*= (const SbMatrix & m): Right-multiply with the m matrix.; See also:
multRight().; References 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().; References SbMatrix().; Referenced by SoGetBoundingBoxAction::checkResetAfter(),
SoGetBoundingBoxAction::checkResetBefore(),
SoCamera::getBalanceAdjustment(), SoGeoLocation::getPrimitiveCount(),
SoMatrixTransform::initClass(), SbXfBox3f::intersect(), inverse(),
SbDPMatrix::inverse(), SoTransformerDragger::isColinear(),
SoVRMLTransform::notify(), SoVRMLBillboard::notify(), setTransform(),
and SoTransformVec3f::SoTransformVec3f().
void SbMatrix::setScale (const float s): Set matrix to be a pure scaling matrix. Scale factors are specified by s.; See also:
setRotate(), setTranslate().; References makeIdentity().; Referenced by SoScale::callback(), SoUnits::getMatrix(), and
setTransform().
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().; References makeIdentity().
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().; References makeIdentity().; Referenced by SoTranslation::callback(),
SbProjector::findVanishingDistance(), SoSurroundScale::getMatrix(),
getTransform(), setTransform(), and
SoCenterballDragger::valueChangedCB().
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().; References SbRotation::identity(), identity(), multRight(),
setRotate(), setScale(), and setTranslate().; Referenced by SoTexture3Transform::callback(),
SoClipPlaneManip::fieldSensorCB(), SoTransform::getBoundingBox(), and
SoVRMLTransform::notify().
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().; References SbRotation::identity(), identity(), SbRotation::inverse(),
multRight(), setRotate(), setScale(), and setTranslate().
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().; References SbRotation::identity(), identity(), SbRotation::inverse(),
multRight(), setRotate(), setScale(), and setTranslate().
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(); Referenced by SoVRMLTransform::combineRight(),
SoTransform::combineRight(), SoClipPlaneManip::fieldSensorCB(),
getTransform(), and SoTabPlaneDragger::reallyAdjustScaleTabSize().
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(); References getTransform(), multLeft(), multRight(), and setTranslate().
SbBool SbMatrix::factor (SbMatrix & r, SbVec3f & s, SbMatrix & u, SbVec3f &: t, SbMatrix & proj)
This function is not implemented in Coin.; See also:
getTransform(); Referenced by LUDecomposition().
SbBool SbMatrix::LUDecomposition (int index[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; References factor().
void SbMatrix::LUBackSubstitution (int index[4], float b[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.; Referenced by SbPlane::transform().
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(); References matrix.; Referenced by SoDragger::appendRotation(),
SoTexture2Transform::callback(), SoGetBoundingBoxAction::extendBy(),
SbXfBox3f::extendBy(), SoUnits::getMatrix(),
SoSurroundScale::getMatrix(), getTransform(),
SoVRMLTextureTransform::GLRender(), operator*=(),
SoVRMLTextureTransform::pick(), SoTexture2Transform::pick(),
SoBumpMapTransform::pick(), SoGetBoundingBoxAction::setCenter(),
setTransform(), SbXfBox3f::transform(),
SoDragger::transformMatrixLocalToWorld(),
SoDragger::transformMatrixWorldToLocal(), and
SoCenterballDragger::valueChangedCB().
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 postmultiplication for common geometry operations.); See also:
multRight(); References matrix.; Referenced by SoDragger::appendRotation(), SoTranslation::callback(),
SoTexture2Transform::callback(), SoMatrixTransform::callback(),
SoUnits::getMatrix(), SoSurroundScale::getMatrix(), getTransform(),
SoVRMLTextureTransform::GLRender(),
SoTabPlaneDragger::reallyAdjustScaleTabSize(),
SoDragger::transformMatrixLocalToWorld(), and
SoCenterballDragger::valueChangedCB().
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().; Referenced by SbXfBox3f::extendBy(), SbXfBox3f::getCenter(),
SoPickedPoint::getObjectPoint(),
SoPickedPoint::getObjectTextureCoords(), SoShape::getScreenSize(),
SoAntiSquish::getUnsquishingMatrix(), SoVRMLTouchSensor::handleEvent(), SbXfBox3f::intersect(), SbSphereProjector::isPointInFront(),
SbCylinderProjector::isPointInFront(), multLineMatrix(),
SbRotation::multVec(), SoVRMLBillboard::notify(), SbBox3i32::outside(), SbBox3f::outside(), SbPlaneProjector::project(),
SbLineProjector::project(),
SoTabPlaneDragger::reallyAdjustScaleTabSize(),
SoGetBoundingBoxAction::setCenter(), SbPlane::transform(),
SbBox3i32::transform(), SbBox3f::transform(), and
SbProjector::verifyProjection().
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().; Referenced by SoPickedPoint::getObjectNormal(),
SoVRMLTouchSensor::handleEvent(), SbSphereProjector::isPointInFront(), SbCylinderProjector::isPointInFront(), multLineMatrix(),
SoVRMLBillboard::notify(), SbSphereSheetProjector::setupPlane(),
SbPlaneProjector::setupPlane(), SbCylinderSheetProjector::setupPlane(), SbSphereSectionProjector::setupTolerance(),
SbCylinderSectionProjector::setupTolerance(), and SbPlane::transform().
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().; References SbLine::getDirection(), SbLine::getPosition(),
multDirMatrix(), multVecMatrix(), and SbLine::setValue().; Referenced by SbProjector::getWorkingLine(),
SbPlaneProjector::project(), and SbLineProjector::project().
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.; Referenced by SbXfBox3f::print().

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.

docs.sk

comprehensive documentation repository

Most Viewed