Main Page   Modules   Alphabetical List   Data Structures   Data Fields  

RwMatrix
[Matrix Types]


Data Structures

struct   RwMatrix
struct   RwMatrixTolerance

Enumerations

enum   RwOpCombineType { rwCOMBINEREPLACE = 0, rwCOMBINEPRECONCAT, rwCOMBINEPOSTCONCAT, rwOPCOMBINETYPEFORCEENUMSIZEINT = RWFORCEENUMSIZEINT }

Functions

RwUInt32  RwMatrixStreamGetSize (const RwMatrix *matrix)
const RwMatrix RwMatrixStreamWrite (const RwMatrix *matrix, RwStream *stream)
RwMatrixChunkInfo *  RwMatrixChunkInfoRead (RwStream *stream, RwMatrixChunkInfo *matrixChunkInfo, RwInt32 *bytesRead)
RwMatrix RwMatrixStreamRead (RwStream *stream, RwMatrix *matrix)
void  RwMatrixSetFreeListCreateParams (RwInt32 blockSize, RwInt32 numBlocksToPrealloc)
RwBool  RwEngineGetMatrixTolerances (RwMatrixTolerance *const tolerance)
RwBool  RwEngineSetMatrixTolerances (const RwMatrixTolerance *const tolerance)
RwMatrix RwMatrixOptimize (RwMatrix *matrix, const RwMatrixTolerance *tolerance)
RwMatrix RwMatrixUpdate (RwMatrix *matrix)
RwMatrix RwMatrixMultiply (RwMatrix *dst, const RwMatrix *src1, const RwMatrix *src2)
RwMatrix RwMatrixOrthoNormalize (RwMatrix *dst, const RwMatrix *src)
RwMatrix RwMatrixRotateOneMinusCosineSine (RwMatrix *matrix, const RwV3d *unitAxis, RwReal oneMinusCosine, RwReal sine, RwOpCombineType combineOp)
RwMatrix RwMatrixRotate (RwMatrix *matrix, const RwV3d *axis, RwReal angle, RwOpCombineType combineOp)
RwMatrix RwMatrixInvert (RwMatrix *dst, const RwMatrix *src)
RwMatrix RwMatrixScale (RwMatrix *matrix, const RwV3d *scale, RwOpCombineType combineOp)
RwMatrix RwMatrixTranslate (RwMatrix *matrix, const RwV3d *translation, RwOpCombineType combineOp)
RwMatrix RwMatrixTransform (RwMatrix *matrix, const RwMatrix *transform, RwOpCombineType combineOp)
const RwMatrix RwMatrixQueryRotate (const RwMatrix *matrix, RwV3d *unitAxis, RwReal *angle, RwV3d *center)
RwBool  RwMatrixDestroy (RwMatrix *matrix)
RwMatrix RwMatrixCreate (void)
RwV3d RwMatrixGetRight (RwMatrix *matrix)
RwV3d RwMatrixGetUp (RwMatrix *matrix)
RwV3d RwMatrixGetAt (RwMatrix *matrix)
RwV3d RwMatrixGetPos (RwMatrix *matrix)
void  RwMatrixCopy (RwMatrix *dst, const RwMatrix *src)
void  RwMatrixSetIdentity (RwMatrix *matrix)

Detailed Description

Handling binary matrix representations.

RwMatrix Overview

Requirements

Overview

This object defines a RenderWare Matrix object.

The Matrix is heavily used throughout the API and a full range of functions are provided, including: rotation, multiplication, concatenation, scaling, translation, creation, destruction, stream read/write functions and a number of access functions to access particular vector data within the matrix.

RenderWare uses 4x3, row-major affine matrices.


Enumeration Type Documentation

enum RwOpCombineType
 

enum RwOpCombineType This type represents a combination operator which can be applied to frames and matrices. The operator determines the order in which one object is combined with another

Enumeration values:
rwCOMBINEREPLACE  Replace - all previous transformations are lost
rwCOMBINEPRECONCAT  Pre-concatenation - the given transformation is applied before all others
rwCOMBINEPOSTCONCAT  Post-concatenation - the given transformation is applied after all others

Function Documentation

RwBool RwEngineGetMatrixTolerances RwMatrixTolerance *const    tolerance
 

RwEngineGetMatrixTolerances Returns current tolerances for matrix optimizations with RwMatrixOptimize

Parameters:
tolerance  The destination address to which tolerances are to be written
Returns:
Returns TRUE if successful, FALSE if there is an error
See also:
RwEngineSetMatrixTolerances , RwMatrixOptimize
RwBool RwEngineSetMatrixTolerances const RwMatrixTolerance *const    tolerance
 

RwEngineSetMatrixTolerances Sets current tolerances for matrix optimizations with RwMatrixOptimize

Parameters:
tolerance  The source address from which tolerances are to be read
Returns:
Returns TRUE if successful, FALSE if there is an error
See also:
RwEngineGetMatrixTolerances , RwMatrixOptimize
RwMatrixChunkInfo* RwMatrixChunkInfoRead RwStream   stream,
RwMatrixChunkInfo *    matrixChunkInfo,
RwInt32   bytesRead
 

RwMatrixChunkInfoRead extracts Chunk Info data from a RenderWare stream. The data is converted from its original format and inserted into an RwMatrixChunkInfo structure. A pointer to this structure is returned on success.

Parameters:
stream  A pointer to the RenderWare stream object
matrixChunkInfo  A pointer to the matrixChunkInfo structure to be filled by the data
bytesRead  A pointer to an RwInt32 that will hold the number of bytes read
Returns:
Returns a pointer to the filled structure if successful. Returns NULL if an error occurred.
See also:
RwMatrixStreamRead , RwMatrixStreamWrite , RwStreamOpen , RwStreamClose , RwStreamFindChunk
void RwMatrixCopy RwMatrix   dst,
const RwMatrix   src
 

RwMatrixCopy is used to copy the contents of one matrix to another. Both matrices must exist or have been created using RwMatrixCreate before calling this function.

Note:
This function is used for debug purposes only and, for efficiency, is available as a macro for final release versions of an application.
Parameters:
dst  A pointer to the destination matrix
src  A pointer to the source matrix
Returns:
None.
See also:
RwMatrixCreate , RwMatrixMultiply , RwMatrixInvert , RwMatrixRotate , RwMatrixScale , RwMatrixTranslate , RwMatrixTransform
RwMatrix* RwMatrixCreate void   
 

RwMatrixCreate creates a new transformation matrix initialized to the identity matrix. Note that the matrix must be destroyed when it is no longer required by an application.

Returns:
Returns a pointer to created matrix if successful or NULL if there is an error
See also:
RwMatrixCopy , RwMatrixDestroy
RwBool RwMatrixDestroy RwMatrix   matrix
 

RwMatrixDestroy is used to delete a transformation matrix previously created by the API function RwMatrixCreate matrix.

Parameters:
matrix  A pointer to the matrix that is to be destroyed
Returns:
Returns TRUE
See also:
RwMatrixCreate
RwV3d* RwMatrixGetAt RwMatrix   matrix
 

RwMatrixGetAt is used to retrieve the 'look-at' vector of the specified transformation matrix.

Note:
This function is used for debug purposes only and, for efficiency, is available as a macro for final release versions of an application.
Parameters:
matrix  A pointer to the matrix from which to get the 'look-at' vector
Returns:
Returns a pointer to the 'look-at' vector
See also:
RwMatrixGetRight , RwMatrixGetUp , RwMatrixGetPos , RwMatrixUpdate , RwMatrixOptimize
RwV3d* RwMatrixGetPos RwMatrix   matrix
 

RwMatrixGetPos is used to retrieve the 'position' vector from the specified transformation matrix.

Note:
This function is used for debug purposes only and, for efficiency, is available as a macro for final release versions of an application.
Parameters:
matrix  A pointer to the matrix from which to get the 'position' vector
Returns:
Returns a pointer to the 'position' vector of the matrix
See also:
RwMatrixGetRight , RwMatrixGetUp , RwMatrixGetAt , RwMatrixUpdate , RwMatrixOptimize
RwV3d* RwMatrixGetRight RwMatrix   matrix
 

RwMatrixGetRight is used to retrieve the 'look-right' vector of the specified transformation matrix.

Note:
This function is used for debug purposes only and, for efficiency, is available as a macro for final release versions of an application.
Parameters:
matrix  A pointer to the matrix from which to get 'look-right' vector
Returns:
Returns a pointer to the 'look-right' vector of the matrix
See also:
RwMatrixGetUp , RwMatrixGetAt , RwMatrixGetPos , RwMatrixUpdate , RwMatrixOptimize
RwV3d* RwMatrixGetUp RwMatrix   matrix
 

RwMatrixGetUp is used to retrieve the 'look-up' vector of the specified transformation matrix.

Note:
This function is used for debug purposes only and, for efficiency, is available as a macro for final release versions of an application.
Parameters:
matrix  A pointer to the matrix from which to get 'look-up' vector
Returns:
Returns a pointer to the 'look-up' vector of the matrix
See also:
RwMatrixGetRight , RwMatrixGetAt , RwMatrixGetPos , RwMatrixUpdate , RwMatrixOptimize
RwMatrix* RwMatrixInvert RwMatrix   dst,
const RwMatrix   src
 

RwMatrixInvert performs a matrix inversion calculation on the input matrix. Note that the input and output arguments must not point to the same matrix.

Parameters:
dst  A pointer to the matrix where the inverse will be stored
src  A pointer to the matrix that is to be inverted
Returns:
Returns a pointer to the inverted matrix
RwMatrix* RwMatrixMultiply RwMatrix   dst,
const RwMatrix   src1,
const RwMatrix   src2
 

RwMatrixMultiply multiplies two matrices in the order given.

Note:
The matrix used for the result must be different from the input matrices.
Parameters:
dst  A pointer to the matrix that will receive the matrix product
src1  A pointer to the first matrix
src2  A pointer to the second matrix
Returns:
Returns a pointer to the product matrix
See also:
RwMatrixRotate , RwMatrixTranslate , RwMatrixScale , RwMatrixTransform , RwV3dTransformPoints , RwV3dTransformVectors
RwMatrix* RwMatrixOptimize RwMatrix   matrix,
const RwMatrixTolerance   tolerance
 

RwMatrixOptimize informs the library that the application has changed the specified matrix and that the library should take note of the new matrix values.

This is only necessary when the application directly modifies the matrix with RwMatrixGetRight, RwMatrixGetUp, RwMatrixGetAt or RwMatrixGetPos.

This differs from RwMatrixUpdate in that extra work is undertaken to identify special properties of the matrix suitable for subsequent optimizations.

Parameters:
matrix  A pointer to the matrix to update.
tolerance  A pointer to the tolerances for optimizations or NULL if the current global tolerances as returned by RwEngineGetMatrixTolerances are applied
Returns:
Returns a pointer to the optimized matrix
See also:
RwEngineGetMatrixTolerances , RwEngineSetMatrixTolerances , RwMatrixGetAt , RwMatrixGetPos , RwMatrixGetRight , RwMatrixGetUp , RwMatrixUpdate
RwMatrix* RwMatrixOrthoNormalize RwMatrix   dst,
const RwMatrix   src
 

RwMatrixOrthoNormalize extracts the 'rigid-body' transformation component from a matrix.

Whilst RenderWare supports arbitrary 4x3 affine matrices, many applications deal only in 'rigid-body' transformations comprising rotation and translation without scaling or shearing. The 4x3 matrix representing such a transformation has a special form of upper-left 3x3 sub-matrix known as an orthonormal matrix, characterized by its inverse being equal to its transpose. Mathematically, this sub-matrix remains orthonormal following any rigid-body transformation. Numerically, however, after extended matrix composition some scale or shear factors begin to accumulate due to rounding. To prevent the significant build-up of such factors, RwMatrixOrthoNormalize should be periodically applied to ensure the matrix keeps its orthonormal form. The minimal satisfactory frequency of orthonormalization will depend on the nature of the application.

Typically, a frequency of once every 128 frames is adequate.

Parameters:
dst  A pointer to the matrix that will receive orthonormal form
src  A pointer to the matrix to be orthonormalized
Returns:
Returns A pointer to the orthonormalized matrix
See also:
RwMatrixInvert , RwMatrixSetIdentity
const RwMatrix* RwMatrixQueryRotate const RwMatrix   matrix,
RwV3d   unitAxis,
RwReal   angle,
RwV3d   center
 

RwMatrixQueryRotate determines the rotation component from a matrix comprising only rotations and translations. The rotation is returned as a unit vector along the axis of rotation, an angle of rotation and a point on the axis which is the nearest to the origin (hence the line joining this point with the origin is perpendicular to the axis).

The rotation component has two possible descriptions since a rotation about an axis of theta degrees is equivalent to a rotation about an axis pointing in the opposite direction by an angle of 360-theta in the reverse direction. The angle returned by RwMatrixQueryRotate is always between 0 and 180 degrees and the direction of the axis of rotation returned is chosen to ensure the angle is in this range.

Note:
Only matrices known to be composed solely of rotations and translations, i.e. OrthoNormal or rigid-body transformations, should be queried with this function. The results from querying matrices incorporating transforms such as scaling are unlikely to be useful.
Parameters:
matrix  A pointer to the matrix to be investigated
unitAxis  A pointer to the vector which will receive the unit direction vector along axis of rotation
angle  A pointer to the RwReal that will receive the angle of rotation in degrees
center  A pointer to the vector that will receive the center of the line of rotation
Returns:
Returns A pointer to the queried matrix
See also:
RwMatrixRotate , RwMatrixRotateOneMinusCosineSine
RwMatrix* RwMatrixRotate RwMatrix   matrix,
const RwV3d   axis,
RwReal    angle,
RwOpCombineType    combineOp
 

RwMatrixRotate builds a rotation matrix from the given axis and angle of rotation and applies it to the specified matrix. The combine operation may be pre-concatenation, post-concatenation or replacement.

Parameters:
matrix  A pointer to the matrix to which to apply the rotation
axis  A pointer to the vector that specifies the axis of rotation
angle  An angle of rotation in degrees
combineOp  A combination operator that specifies how the rotation is applied
Returns:
Returns a pointer to the updated matrix.
See also:
RwMatrixTranslate , RwMatrixScale , RwMatrixTransform , RwMatrixRotateOneMinusCosineSine
RwMatrix* RwMatrixRotateOneMinusCosineSine RwMatrix   matrix,
const RwV3d   unitAxis,
RwReal    oneMinusCosine,
RwReal    sine,
RwOpCombineType    combineOp
 

RwMatrixRotateOneMinusCosineSine builds a rotation matrix from the given axis and applies it to the specified matrix. The angle of rotation is supplied by giving values for 1-cos(theta) and sin(theta) where theta is the angle of rotation. This function should be used in preference to RwMatrixRotate, where possible, as it is substantially faster. The combine operation may be pre-concatenation, post-concatenation or replacement.

Parameters:
matrix  A pointer to the matrix to which to apply the rotation
unitAxis  A pointer to a unit vector describing the axis of rotation
oneMinusCosine  The value of 1-cos(theta), where theta is the angle of rotation
sine  The value of sin(theta)
combineOp  A combination operator that specifies how rotation is applied
Returns:
Returns a pointer to the updated matrix.
See also:
RwMatrixRotate , RwMatrixTranslate , RwMatrixScale , RwMatrixTransform
RwMatrix* RwMatrixScale RwMatrix   matrix,
const RwV3d   scale,
RwOpCombineType    combineOp
 

RwMatrixScale builds a scaling matrix from the given scale factors and applies it to the specified matrix in place. The combine operation may be pre-concatenation, post-concatenation or replacement.

Parameters:
matrix  A pointer to the matrix to apply scaling to
scale  A pointer to the vector specifying the scale factors
combineOp  A combine operator specifiying how the scaling is to be applied:
  • rwCOMBINEREPLACE Replacement
  • rwCOMBINEPRECONCAT Pre-concatenation
  • rwCOMBINEPOSTCONCAT Post-concatenation
Returns:
Returns a pointer to the updated matrix.
See also:
RwMatrixRotate , RwMatrixTranslate , RwMatrixTransform , RwV3dTransformPoints , RwV3dTransformVectors
void RwMatrixSetFreeListCreateParams RwInt32    blockSize,
RwInt32    numBlocksToPrealloc
 

RwMatrixSetFreeListCreateParams allows the developer to specify how many RwMatrix s to preallocate space for. Call before RwEngineInit.

Parameters:
blockSize  number of entries per freelist block.
numBlocksToPrealloc  number of blocks to allocate on RwFreeListCreateAndPreallocateSpace.
See also:
RwFreeList
void RwMatrixSetIdentity RwMatrix   matrix
 

RwMatrixSetIdentity is used to convert the specified matrix to the identity matrix.

Note:
This function is used for debug purposes only and, for efficiency, is available as a macro for final release versions of an application.
Parameters:
matrix  A pointer to the matrix to reset to the identity matrix.
Returns:
None
See also:
RwMatrixCreate
RwUInt32 RwMatrixStreamGetSize const RwMatrix   matrix
 

RwMatrixStreamGetSize determines the size in bytes of the binary representation of the given matrix. This is used in the binary chunk header to indicate the size of the chunk.

Parameters:
matrix  A pointer to a matrix for the size that is required
Returns:
Returns the chunk size of the matrix in bytes or zero if there an error
See also:
RwMatrixStreamRead , RwMatrixStreamWrite
RwMatrix* RwMatrixStreamRead RwStream   stream,
RwMatrix   matrix
 

RwMatrixStreamRead reads a matrix from a binary stream. If the matrix argument is NULL then a new matrix is created, otherwise the specified one is over-written.

Note:
Prior to this function call a binary matrix chunk must be found in the stream using the RwStreamFindChunk API function.
The sequence to locate and read a matrix from a binary stream connected to a disk file is as follows:
    RwStream *stream;
    RwMatrix *matrix;
  
    stream = RwStreamOpen(rwSTREAMFILENAME, rwSTREAMREAD, "mybinary.xxx");
    if( stream )
    {
        if( RwStreamFindChunk(stream, rwID_MATRIX, NULL, NULL) )
        {
            matrix = RwMatrixStreamRead(stream, NULL);
        }
  
        RwStreamClose(stream, NULL);
    }

The second parameter is useful if you have a matrix allocated on the stack so you could also do:

    RwStream *stream;
    RwMatrix matrix;
   
    stream = RwStreamOpen(rwSTREAMFILENAME, rwSTREAMREAD, "mybinary.xxx");
    if( stream )
    {
        if( RwStreamFindChunk(stream, rwID_MATRIX, NULL, NULL) )
        {
            RwMatrixStreamRead(stream, &matrix);
        }
   
        RwStreamClose(stream, NULL);
    }
Parameters:
stream  A pointer to the stream from which the matrix will be read
matrix  A pointer to a matrix which will receive the data from the stream. If one is not provided by the application (NULL is passed), then one will be created
Returns:
Returns pointer to the matrix if successful or NULL if there is an error.
See also:
RwMatrixStreamWrite , RwMatrixStreamGetSize , RwStreamOpen , RwStreamClose , RwStreamFindChunk
const RwMatrix* RwMatrixStreamWrite const RwMatrix   matrix,
RwStream   stream
 

RwMatrixStreamWrite writes the specified matrix to a binary stream.

Note:
The stream will have been opened prior to this function call.
Parameters:
matrix  A pointer to the matrix to be written
stream  A pointer to the stream
Returns:
Returns a pointer to the matrix if successful or NULL if there is an error
See also:
RwMatrixStreamRead , RwMatrixStreamGetSize , RwStreamOpen , RwStreamClose
RwMatrix* RwMatrixTransform RwMatrix   matrix,
const RwMatrix   transform,
RwOpCombineType    combineOp
 

RwMatrixTransform calculates the result of applying a general transformation matrix to the given matrix. The combine operation may be pre-concatenation, post-concatenation or replacement.

The two input matrices must not be the same.

Parameters:
matrix  A pointer to the matrix to which to apply the transformation
transform  A pointer to the matrix which specifies the transformation
combineOp  A combination operator specifying how the transformation is to be applied
  • rwCOMBINEREPLACE Replacement
  • rwCOMBINEPRECONCAT Pre-concatenation
  • rwCOMBINEPOSTCONCAT Post-concatenation.
Returns:
Returns a pointer to the updated matrix.
See also:
RwMatrixRotate , RwMatrixTranslate , RwMatrixScale , RwV3dTransformPoints , RwV3dTransformVectors
RwMatrix* RwMatrixTranslate RwMatrix   matrix,
const RwV3d   translation,
RwOpCombineType    combineOp
 

RwMatrixTranslate builds a translation matrix from the given vector and applies it to the specified matrix. The combine operation may be pre-concatenation, post-concatenation or replacement.

Parameters:
matrix  A pointer to the matrix to which to apply the translation
translation  A pointer to the vector that specifies the components of the translation
combineOp  A combination operator that specifies how the translation is to be applied
  • rwCOMBINEREPLACE Replacement
  • rwCOMBINEPRECONCAT Pre-concatenation
  • rwCOMBINEPOSTCONCAT Post-concatenation
Returns:
Returns a pointer to the updated matrix.
See also:
RwMatrixRotate , RwMatrixScale , RwMatrixTransform , RwV3dTransformPoints , RwV3dTransformVectors
RwMatrix* RwMatrixUpdate RwMatrix   matrix
 

RwMatrixUpdate informs the library that the application has changed the specified matrix and that the library should take note of the new matrix values. This is only necessary when the application directly modifies the matrix with RwMatrixGetRight, RwMatrixGetUp, RwMatrixGetAt or RwMatrixGetPos.

Parameters:
matrix  A pointer to the matrix to update
Returns:
Returns a pointer to the specified matrix or NULL if there is an error.
See also:
RwMatrixGetRight , RwMatrixGetUp , RwMatrixGetAt , RwMatrixGetPos , RwMatrixOptimize

Criterion Software © 1993-2003 Criterion Software Limited. All rights reserved. Built Tue Apr 22 12:46:13 2003. Send Feedback
Converted from CHM to HTML with chm2web Pro 2.85 (unicode)