Classes | Public Types | Public Member Functions | Public Attributes

gmtl::Matrix< DATA_TYPE, ROWS, COLS > Class Template Reference
[Abstract Data Types: Matrix, Vec, Quat, Coord, Sphere, Plane]

State tracked NxM dimensional Matrix (ordered in memory by Column). More...

#include <Matrix.h>

Collaboration diagram for gmtl::Matrix< DATA_TYPE, ROWS, COLS >:
Collaboration graph
[legend]

List of all members.

Classes

class  ConstRowAccessor
 Helper class for Matrix op[] const. More...
class  RowAccessor
 Helper class for Matrix op[]. More...

Public Types

enum  Params { Rows = ROWS, Cols = COLS }
enum  XformState {
  IDENTITY = 1, TRANS = 2, ORTHOGONAL = 4, AFFINE = 16,
  NON_UNISCALE = 32, FULL = 64, XFORM_ERROR = 128
}
 

describes the xforms that this matrix has been through.

More...
typedef DATA_TYPE DataType
 use this to declare single value types of the same type as this matrix.

Public Member Functions

 Matrix ()
 Default Constructor (Identity constructor).
 Matrix (const Matrix< DATA_TYPE, ROWS, COLS > &matrix)
 copy constructor
void set (DATA_TYPE v00, DATA_TYPE v01, DATA_TYPE v10, DATA_TYPE v11)
 element wise setter for 2x2.
void set (DATA_TYPE v00, DATA_TYPE v01, DATA_TYPE v02, DATA_TYPE v10, DATA_TYPE v11, DATA_TYPE v12)
 element wise setter for 2x3.
void set (DATA_TYPE v00, DATA_TYPE v01, DATA_TYPE v02, DATA_TYPE v10, DATA_TYPE v11, DATA_TYPE v12, DATA_TYPE v20, DATA_TYPE v21, DATA_TYPE v22)
 element wise setter for 3x3.
void set (DATA_TYPE v00, DATA_TYPE v01, DATA_TYPE v02, DATA_TYPE v03, DATA_TYPE v10, DATA_TYPE v11, DATA_TYPE v12, DATA_TYPE v13, DATA_TYPE v20, DATA_TYPE v21, DATA_TYPE v22, DATA_TYPE v23)
 element wise setter for 3x4.
void set (DATA_TYPE v00, DATA_TYPE v01, DATA_TYPE v02, DATA_TYPE v03, DATA_TYPE v10, DATA_TYPE v11, DATA_TYPE v12, DATA_TYPE v13, DATA_TYPE v20, DATA_TYPE v21, DATA_TYPE v22, DATA_TYPE v23, DATA_TYPE v30, DATA_TYPE v31, DATA_TYPE v32, DATA_TYPE v33)
 element wise setter for 4x4.
void set (const DATA_TYPE *data)
 comma operator
void setTranspose (const DATA_TYPE *data)
 set the matrix to the transpose of the given data.
DATA_TYPE & operator() (const unsigned row, const unsigned column)
 access [row, col] in the matrix WARNING: If you set data in the matrix (using this interface), you are required to set mState appropriately, failure to do so will result in incorrect calculations by other functions in GMTL.
const DATA_TYPE & operator() (const unsigned row, const unsigned column) const
 access [row, col] in the matrix (const version)
RowAccessor operator[] (const unsigned row)
 bracket operator WARNING: If you set data in the matrix (using this interface), you are required to set mState appropriately, failure to do so will result in incorrect calculations by other functions in GMTL.
ConstRowAccessor operator[] (const unsigned row) const
 bracket operator (const version)
const DATA_TYPE * getData () const
 Gets a DATA_TYPE pointer to the matrix data.
bool isError ()
void setError ()
void setState (int state)

Public Attributes

DATA_TYPE mData [COLS *ROWS]
 Column major.
int mState
 describes what xforms are in this matrix

Detailed Description

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
class gmtl::Matrix< DATA_TYPE, ROWS, COLS >

State tracked NxM dimensional Matrix (ordered in memory by Column).

Memory mapping:

gmtl::Matrix stores its elements in column major order. That is, it stores each column end-to-end in memory.

Typically, for 3D transform matrices, the 3x3 rotation is in the first three columns, while the translation is in the last column.

This memory alignment is chosen for compatibility with the OpenGL graphics API and others, which take matrices in this specific column major ordering described above.

See the interfaces for operator[r][c] and operator(r,c) for how to iterate over columns and rows for a GMTL Matrix.

NOTES on Matrix memory layout and [][] accessors:

State Tracking:

The idea of a state-tracked matrix is that if we track the information as it is stored into the matrix, then other operations could make more optimal descisions based on the known state. A good example is in matrix invertion, a reletively costly operation for matrices. However, if we know the matrix state is (i.e.) ORTHOGONAL, then inversion becomes a simple transpose operation. There are also optimizations with multiplication, as well as other.

One side effect of this state tracking is that EVERY MATRIC FUNCTION NEEDS TO TRACK STATE. This means that anyone writing custom methods, or extentions to gmtl, will need to pay close attention to matrix state.

To facilitate state tracking in extensions, we've provided the function gmtl::combineMatrixStates() to help in determining state based on two combined matrices.

See also:
Matrix44f
Matrix44d

Definition at line 107 of file Matrix.h.


Member Typedef Documentation

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
typedef DATA_TYPE gmtl::Matrix< DATA_TYPE, ROWS, COLS >::DataType

use this to declare single value types of the same type as this matrix.

Definition at line 121 of file Matrix.h.


Member Enumeration Documentation

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
enum gmtl::Matrix::Params
Enumerator:
Rows 
Cols 

Definition at line 122 of file Matrix.h.

   {
      Rows = ROWS, Cols = COLS
   };

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
enum gmtl::Matrix::XformState

describes the xforms that this matrix has been through.

Enumerator:
IDENTITY 
TRANS 
ORTHOGONAL 
AFFINE 
NON_UNISCALE 
FULL 
XFORM_ERROR 

Definition at line 181 of file Matrix.h.

   {
      // identity matrix.
      IDENTITY = 1,

      // only translation, can simply negate that column
      TRANS = 2,

      // able to tranpose to get the inverse.  only rotation component is set
      ORTHOGONAL = 4,

      // orthogonal, and normalized axes.
      //ORTHONORMAL = 8,

      // leaves the homogeneous coordinate unchanged - that is, in which the last column is (0,0,0,s).
      // can include rotation, uniform scale, and translation, but no shearing or nonuniform scaling
      // This can optionally be combined with the NON_UNISCALE state to indicate there is also non-uniform scale
      AFFINE = 16,

      // AFFINE matrix with non-uniform scale, a matrix cannot
      // have this state without also having AFFINE (must be or'd together).
      NON_UNISCALE = 32,

      // fully set matrix containing more information than the above, or state is unknown,
      // or unclassifiable in terms of the above.
      FULL = 64,

      // error bit
      XFORM_ERROR = 128
   };


Constructor & Destructor Documentation

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
gmtl::Matrix< DATA_TYPE, ROWS, COLS >::Matrix (  )  [inline]

Default Constructor (Identity constructor).

Todo:
mp
Todo:
mp
Todo:
Set initial state to IDENTITY and test other stuff

Definition at line 213 of file Matrix.h.

   {
      for (unsigned int r = 0; r < ROWS; ++r)
      {
         for (unsigned int c = 0; c < COLS; ++c)
         {   this->operator()( r, c ) = (DATA_TYPE)0.0; }
      }

      for (unsigned int x = 0; x < Math::Min( COLS, ROWS ); ++x)
      {  this->operator()( x, x ) = (DATA_TYPE)1.0; }

      mState = IDENTITY;
   }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
gmtl::Matrix< DATA_TYPE, ROWS, COLS >::Matrix ( const Matrix< DATA_TYPE, ROWS, COLS > &  matrix  )  [inline]

copy constructor

Definition at line 231 of file Matrix.h.

   {
      this->set( matrix.getData() );
      mState = matrix.mState;
   }


Member Function Documentation

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
const DATA_TYPE* gmtl::Matrix< DATA_TYPE, ROWS, COLS >::getData (  )  const [inline]

Gets a DATA_TYPE pointer to the matrix data.

Returns:
Returns a pointer to the head of the matrix data.

Definition at line 461 of file Matrix.h.

{ return (DATA_TYPE*)mData; }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
bool gmtl::Matrix< DATA_TYPE, ROWS, COLS >::isError (  )  [inline]

Definition at line 463 of file Matrix.h.

   {
      return mState & XFORM_ERROR;
   }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
const DATA_TYPE& gmtl::Matrix< DATA_TYPE, ROWS, COLS >::operator() ( const unsigned  row,
const unsigned  column 
) const [inline]

access [row, col] in the matrix (const version)

Definition at line 424 of file Matrix.h.

   {
      gmtlASSERT( (row < ROWS) && (column < COLS) );
      return mData[column*ROWS + row];
   }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
DATA_TYPE& gmtl::Matrix< DATA_TYPE, ROWS, COLS >::operator() ( const unsigned  row,
const unsigned  column 
) [inline]

access [row, col] in the matrix WARNING: If you set data in the matrix (using this interface), you are required to set mState appropriately, failure to do so will result in incorrect calculations by other functions in GMTL.

If you are unsure about how to set mState, set it to FULL and you will be sure to get the correct result at the cost of some performance.

Definition at line 417 of file Matrix.h.

   {
      gmtlASSERT( (row < ROWS) && (column < COLS) );
      return mData[column*ROWS + row];
   }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
RowAccessor gmtl::Matrix< DATA_TYPE, ROWS, COLS >::operator[] ( const unsigned  row  )  [inline]

bracket operator WARNING: If you set data in the matrix (using this interface), you are required to set mState appropriately, failure to do so will result in incorrect calculations by other functions in GMTL.

If you are unsure about how to set mState, set it to FULL and you will be sure to get the correct result at the cost of some performance.

Definition at line 438 of file Matrix.h.

   {
      return RowAccessor(this, row);
   }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
ConstRowAccessor gmtl::Matrix< DATA_TYPE, ROWS, COLS >::operator[] ( const unsigned  row  )  const [inline]

bracket operator (const version)

Definition at line 444 of file Matrix.h.

   {
      return ConstRowAccessor( this, row );
   }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
void gmtl::Matrix< DATA_TYPE, ROWS, COLS >::set ( DATA_TYPE  v00,
DATA_TYPE  v01,
DATA_TYPE  v10,
DATA_TYPE  v11 
) [inline]

element wise setter for 2x2.

Note:
variable names specify the row,column number to put the data into
Todo:
needs mp!!

Definition at line 241 of file Matrix.h.

   {
      GMTL_STATIC_ASSERT( (ROWS == 2 && COLS == 2), Set_called_when_Matrix_not_of_size_2_2 );
      mData[0] = v00;
      mData[1] = v10;
      mData[2] = v01;
      mData[3] = v11;
      mState = FULL;
   }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
void gmtl::Matrix< DATA_TYPE, ROWS, COLS >::set ( DATA_TYPE  v00,
DATA_TYPE  v01,
DATA_TYPE  v02,
DATA_TYPE  v03,
DATA_TYPE  v10,
DATA_TYPE  v11,
DATA_TYPE  v12,
DATA_TYPE  v13,
DATA_TYPE  v20,
DATA_TYPE  v21,
DATA_TYPE  v22,
DATA_TYPE  v23 
) [inline]

element wise setter for 3x4.

Todo:
needs mp!! currently no way for a 4x3, ....

Definition at line 293 of file Matrix.h.

   {
      GMTL_STATIC_ASSERT( (ROWS == 3 && COLS == 4), Set_called_when_Matrix_not_of_size_3_4 );
      mData[0] = v00;
      mData[1] = v10;
      mData[2] = v20;
      mData[3] = v01;
      mData[4] = v11;
      mData[5] = v21;
      mData[6] = v02;
      mData[7] = v12;
      mData[8] = v22;

      // right row
      mData[9]  = v03;
      mData[10] = v13;
      mData[11] = v23;
      mState = FULL;
   }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
void gmtl::Matrix< DATA_TYPE, ROWS, COLS >::set ( DATA_TYPE  v00,
DATA_TYPE  v01,
DATA_TYPE  v02,
DATA_TYPE  v10,
DATA_TYPE  v11,
DATA_TYPE  v12 
) [inline]

element wise setter for 2x3.

Todo:
needs mp!!

Definition at line 255 of file Matrix.h.

   {
      GMTL_STATIC_ASSERT( (ROWS == 2 && COLS == 3), Set_called_when_Matrix_not_of_size_2_3 );
      mData[0] = v00;
      mData[1] = v10;
      mData[2] = v01;
      mData[3] = v11;
      mData[4] = v02;
      mData[5] = v12;
      mState = FULL;
   }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
void gmtl::Matrix< DATA_TYPE, ROWS, COLS >::set ( DATA_TYPE  v00,
DATA_TYPE  v01,
DATA_TYPE  v02,
DATA_TYPE  v03,
DATA_TYPE  v10,
DATA_TYPE  v11,
DATA_TYPE  v12,
DATA_TYPE  v13,
DATA_TYPE  v20,
DATA_TYPE  v21,
DATA_TYPE  v22,
DATA_TYPE  v23,
DATA_TYPE  v30,
DATA_TYPE  v31,
DATA_TYPE  v32,
DATA_TYPE  v33 
) [inline]

element wise setter for 4x4.

Todo:
needs mp!! currently no way for a 4x3, ....

Definition at line 318 of file Matrix.h.

   {
      GMTL_STATIC_ASSERT( (ROWS == 4 && COLS == 4), Set_called_when_Matrix_not_of_size_4_4 );
      mData[0]  = v00;
      mData[1]  = v10;
      mData[2]  = v20;
      mData[4]  = v01;
      mData[5]  = v11;
      mData[6]  = v21;
      mData[8]  = v02;
      mData[9]  = v12;
      mData[10] = v22;

      // right row
      mData[12] = v03;
      mData[13] = v13;
      mData[14] = v23;

      // bottom row
      mData[3]  = v30;
      mData[7]  = v31;
      mData[11] = v32;
      mData[15] = v33;
      mState = FULL;
   }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
void gmtl::Matrix< DATA_TYPE, ROWS, COLS >::set ( const DATA_TYPE *  data  )  [inline]

comma operator

Todo:
implement this!

set the matrix to the given data. This function is useful to copy matrix data from another math library.

"Example (to a matrix using an external math library):"

    pfMatrix other_matrix;
    other_matrix.setRot( 90, 1, 0, 0 );

    gmtl::Matrix44f mat;
    mat.set( other_matrix.getFloatPtr() );

WARNING: this isn't really safe, size and datatype are not enforced by the compiler.

Precondition:
data is in the native format of the gmtl::Matrix class, if not, then you might be able to use the setTranspose function.
i.e. in a 4x4 data[0-3] is the 1st column, data[4-7] is 2nd, etc...

Todo:
mp

Definition at line 370 of file Matrix.h.

   {
      for (unsigned int x = 0; x < ROWS * COLS; ++x)
         mData[x] = data[x];
      mState = FULL;
   }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
void gmtl::Matrix< DATA_TYPE, ROWS, COLS >::set ( DATA_TYPE  v00,
DATA_TYPE  v01,
DATA_TYPE  v02,
DATA_TYPE  v10,
DATA_TYPE  v11,
DATA_TYPE  v12,
DATA_TYPE  v20,
DATA_TYPE  v21,
DATA_TYPE  v22 
) [inline]

element wise setter for 3x3.

Todo:
needs mp!!

Definition at line 271 of file Matrix.h.

   {
      GMTL_STATIC_ASSERT( (ROWS == 3 && COLS == 3), Set_called_when_Matrix_not_of_size_3_3 );
      mData[0] = v00;
      mData[1] = v10;
      mData[2] = v20;

      mData[3] = v01;
      mData[4] = v11;
      mData[5] = v21;

      mData[6] = v02;
      mData[7] = v12;
      mData[8] = v22;
      mState = FULL;
   }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
void gmtl::Matrix< DATA_TYPE, ROWS, COLS >::setError (  )  [inline]

Definition at line 467 of file Matrix.h.

   {
      mState |= XFORM_ERROR;
   }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
void gmtl::Matrix< DATA_TYPE, ROWS, COLS >::setState ( int  state  )  [inline]

Definition at line 472 of file Matrix.h.

   { mState = state; }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
void gmtl::Matrix< DATA_TYPE, ROWS, COLS >::setTranspose ( const DATA_TYPE *  data  )  [inline]

set the matrix to the transpose of the given data.

normally set() takes raw matrix data in column by column order, this function allows you to pass in row by row data.

Normally you'll use this function if you want to use a float array to init the matrix (see code example).

"Example (to set a [15 -4 20] translation using float array):"

    float data[] = { 1, 0, 0, 15,
                     0, 1, 0, -4,
                     0, 0, 1, 20,
                     0, 0, 0, 1   };
    gmtl::Matrix44f mat;
    mat.setTranspose( data );

WARNING: this isn't really safe, size and datatype are not enforced by the compiler.

Precondition:
ptr is in the transpose of the native format of the Matrix class
i.e. in a 4x4 data[0-3] is the 1st row, data[4-7] is 2nd, etc...

Todo:
metaprog

Definition at line 400 of file Matrix.h.

   {
      for (unsigned int r = 0; r < ROWS; ++r)
      for (unsigned int c = 0; c < COLS; ++c)
         this->operator()( r, c ) = data[(r * COLS) + c];
      mState = FULL;
   }


Member Data Documentation

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
DATA_TYPE gmtl::Matrix< DATA_TYPE, ROWS, COLS >::mData[COLS *ROWS]

Column major.

In other words {Column1, Column2, Column3, Column4} in memory access element mData[column][row] WARNING: If you set data in the matrix (using this interface), you are required to set mState appropriately, failure to do so will result in incorrect calculations by other functions in GMTL. If you are unsure about how to set mState, set it to FULL and you will be sure to get the correct result at the cost of some performance.

Definition at line 485 of file Matrix.h.

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
int gmtl::Matrix< DATA_TYPE, ROWS, COLS >::mState

describes what xforms are in this matrix

Definition at line 488 of file Matrix.h.


The documentation for this class was generated from the following file: