mi::math::Matrix< T, ROW, COL> Template Class Reference

[Matrix Class]

template< typename T, Size ROW, Size COL>

class mi::math::Matrix< T, ROW, COL>

Description

NxM-dimensional matrix class template of fixed dimensions. This class template provides array-like storage for ROW times COL many values of a (arithmetic) type T. Several functions and arithmetic operators support the work with matrices.

The template parameters have the following requirements:

T: an arithmetic type supporting + - * / == != < > <= >= sqrt().
ROW: a value > 0 of type mi::Size that defines the fixed number of rows in the matrix.
COL: a value > 0 of type mi::Size that defines the fixed number of columns in the matrix.

An instantiation of the matrix class template is a model of the STL container concept. It provides random access to its elements and corresponding random access iterators.

Depending on the dimensions ROW and COL, the mi::math::Matrix class template offers element access through the conventional data members named xx, xy, xz, xw, yx, yy, ..., wx, wy, wz, ww. The first letter denotes the row, the second letter the column. The following example, which, for the sake of illustration, defines a transformation matrix with a factor two scaling transformation:

‎    mi::math::Matrix< mi::Float64, 4, 4> mat( 0.0);
    mat.xx = 2.0;
    mat.yy = 2.0;
    mat.zz = 2.0;
    mat.ww = 1.0;

Memory layout:

Matrices are stored in row-major order, which says that the memory layout of a 4x4 matrix will be sequentially in memory xx, xy, xz, xw, yx, yy, ..., wx, wy, wz, ww.

Note:

The matrix interpretation as a transformation is done by the mi::math::transform_point() and related functions. The convention if vectors are row vectors and multiplied from the left with matrices, or column vectors and multiplied from the right with matrices, determines where the different parameters of a transformation are actually stored in the matrix.
The matrix iterators access the matrix elements, however, the access operator[] accesses row vectors, which follows the interpretation of the matrix as a vector of row vectors in accordance with its underlying row-major memory layout.

See also:

For the free functions and operators available for matrices see Matrix Class.

The underlying POD type mi::math::Matrix_struct.

Public Enumerations

enum Transposed_copy_tag{ TRANSPOSED_COPY_TAG}: Enum type used to tag a special copy constructor that transposes the matrix while copying.

Public Typedefs

typedef Vector< T, ROW> Column_vector: Associated column vector of dimension ROW.
typedef Matrix_struct< T, ROW, COL> Pod_type: POD class corresponding to this matrix.
typedef Vector< T, COL> Row_vector: Associated row vector of dimension COL.
typedef T * const_pointer: Const pointer to element.
typedef T & const_reference: Const reference to element.
typedef Difference difference_type: Difference type, signed.
typedef T * pointer: Mutable pointer to element.
typedef T & reference: Mutable reference to element.
typedef Size size_type: Size type, unsigned.
typedef Matrix_struct< T, ROW, COL> storage_type: Storage class used by this matrix.
typedef T value_type: Element type.

Public Constructors

Matrix(): The default constructor leaves the vector elements uninitialized.
Matrix( const Matrix_struct < T , ROW , COL >& other): Constructor from underlying storage type.
Matrix( T diag): Constructor initializes all matrix elements to zero and the diagonal elements to diag. More...
template< typename Iterator> Matrix( From_iterator_tag, Iterator p): Constructor requires the mi::math::FROM_ITERATOR tag as first argument and initializes the matrix elements with the first ROW times COL elements from the sequence starting at the iterator p. More...
template< typename T2> Matrix( const T2 (&) array[SIZE]): Constructor initializes the matrix elements from an array of dimension ROW times COL. More...
template< typename T2> Matrix( const Matrix < T2 , ROW , COL >& other): Template constructor that allows explicit conversions from other matrices with assignment compatible element value type.
Matrix( Transposed_copy_tag, const Matrix < T , COL , ROW >& other): Constructor that initializes the matrix with the transpose matrix of other.
template< typename T2> Matrix( Transposed_copy_tag, const Matrix < T2 , COL , ROW >& other): Template constructor that initializes the matrix with the transpose matrix of other that allows the explicit conversions from other matrices with assignment compatible element value type.
Matrix( const Row_vector& v0): Dedicated constructor, for ROW==1 only, that initializes matrix from one row vector v0. More...
Matrix( const Row_vector& v0, const Row_vector& v1): Dedicated constructor, for ROW==2 only, that initializes matrix from two row vectors (v0,v1). More...
Matrix( const Row_vector& v0, const Row_vector& v1, const Row_vector& v2): Dedicated constructor, for ROW==3 only, that initializes matrix from three row vectors (v0,v1,v2). More...
Matrix( const Row_vector& v0, const Row_vector& v1, const Row_vector& v2, const Row_vector& v3): Dedicated constructor, for ROW==4 only, that initializes matrix from four row vectors (v0,v1,v2,v3). More...
Matrix( T m0, T m1): 2-element constructor, must be a 1x2 or 2x1 matrix. More...
Matrix( T m0, T m1, T m2): 3-element constructor, must be a 1x3 or 3x1 matrix. More...
Matrix( T m0, T m1, T m2, T m3): 4-element constructor, must be a 1x4, 2x2, or 4x1 matrix. More...
Matrix( T m0, T m1, T m2, T m3, T m4, T m5): 6-element constructor, must be a 2x3 or 3x2 matrix. More...
Matrix( T m0, T m1, T m2, T m3, T m4, T m5, T m6, T m7): 8-element constructor, must be a 2x4 or 4x2 matrix. More...
Matrix( T m0, T m1, T m2, T m3, T m4, T m5, T m6, T m7, T m8): 9-element constructor, must be a 3x3 matrix. More...
Matrix( T m0, T m1, T m2, T m3, T m4, T m5, T m6, T m7, T m8, T m9, T m10, T m11): 12-element constructor, must be a 3x4 or 4x3 matrix. More...
Matrix( T m0, T m1, T m2, T m3, T m4, T m5, T m6, T m7, T m8, T m9, T m10, T m11, T m12, T m13, T m14, T m15): 16-element constructor, must be a 4x4 matrix. More...

Public Member Functions

T* begin(): Returns the pointer to the first matrix element.
const T* begin() const: Returns the pointer to the first matrix element.
T det33() const: Returns the determinant of the upper-left 3x3 sub-matrix. More...
T* end(): Returns the past-the-end pointer. More...
const T* end() const: Returns the past-the-end pointer. More...
T get( Size i) const: Accesses the i-th matrix element, indexed in the order of the row-major memory layout. More...
T get( Size row, Size col) const: Accesses the (row, col)-th matrix element. More...
bool invert(): Inverts this matrix and returns success or failure. More...
void lookat( const Vector < Float32 , 3 >& position, const Vector < Float32 , 3 >& target, const Vector < Float32 , 3 >& up): Sets a transformation matrix based on a given center, a reference point, and a direction. More...
void lookat( const Vector < Float64 , 3 >& position, const Vector < Float64 , 3 >& target, const Vector < Float64 , 3 >& up): Sets a transformation matrix based on a given center, a reference point, and a direction. More...
T& operator()( Size row, Size col): Accesses the (row,col)-th matrix element. More...
const T& operator()( Size row, Size col) const: Accesses the (row, col)-th matrix element. More...
Matrix& operator=( const Matrix& other): Assignment.
Row_vector& operator[]( Size row): Accesses the row-th row vector, 0 <= row < ROW.
const Row_vector& operator[]( Size row) const: Accesses the row-th row vector, 0 <= row < ROW.
void rotate( T xangle, T yangle, T zangle): Adds a relative rotation to the matrix (Euler angles, by component). More...
void rotate( const Vector < Float32 , 3 >& angles): Adds a relative rotation to the matrix (Euler angles, by vector). More...
void rotate( const Vector < Float64 , 3 >& angles): Adds a relative rotation to the matrix (Euler angles, by vector). More...
void set( Size i, T value): Sets the i-th matrix element to value, indexed in the order of the row-major memory layout. More...
void set( Size row, Size col, T value): Sets the i-th matrix element to value, indexed in the order of the row-major memory layout. More...
void set_rotation( T x_angle, T y_angle, T z_angle): Stores an absolute rotation in the upper left 3x3 rotation matrix (Euler angles, by component). More...
void set_rotation( const Vector < Float32 , 3 >& angles): Stores an absolute rotation in the upper left 3x3 rotation matrix (Euler angles, by vector). More...
void set_rotation( const Vector < Float64 , 3 >& angles): Stores an absolute rotation in the upper left 3x3 rotation matrix (Euler angles, by vector). More...
void set_rotation( const Vector < Float32 , 3 >& axis, Float64 angle): Stores an absolute rotation (by axis and angle). More...
void set_rotation( const Vector < Float64 , 3 >& axis, Float64 angle): Stores an absolute rotation (by axis and angle). More...
void set_translation( T dx, T dy, T dz): Stores an absolute translation in the matrix (by component). More...
void set_translation( const Vector < Float32 , 3 >& vector): Stores an absolute translation in the matrix (by vector). More...
void set_translation( const Vector < Float64 , 3 >& vector): Stores an absolute translation in the matrix (by vector). More...
void translate( T x, T y, T z): Adds a relative translation to the matrix (by components). More...
void translate( const Vector < Float32 , 3 >& vector): Adds a relative translation to the matrix (by vector). More...
void translate( const Vector < Float64 , 3 >& vector): Adds a relative translation to the matrix (by vector). More...
void transpose(): Transposes this matrix by exchanging rows and columns. More...

Static Public Member Functions

static Size max_size(): Constant maximum size of the vector.
static Size size(): Constant size of the vector.

Static Public Variables

static const Size COLUMNS = COL: Constant number of columns of the matrix.
static const Size ROWS = ROW: Constant number of rows of the matrix.
static const Size SIZE = ROW*COL: Constant size of the matrix.

Typedefs

typedef Vector< T, ROW> mi::math::Matrix< T, ROW, COL>::Column_vector: Associated column vector of dimension ROW.
typedef Matrix_struct< T, ROW, COL> mi::math::Matrix< T, ROW, COL>::Pod_type: POD class corresponding to this matrix.
typedef Vector< T, COL> mi::math::Matrix< T, ROW, COL>::Row_vector: Associated row vector of dimension COL.
typedef T * mi::math::Matrix< T, ROW, COL>::const_pointer: Const pointer to element.
typedef T & mi::math::Matrix< T, ROW, COL>::const_reference: Const reference to element.
typedef Difference mi::math::Matrix< T, ROW, COL>::difference_type: Difference type, signed.
typedef T * mi::math::Matrix< T, ROW, COL>::pointer: Mutable pointer to element.
typedef T & mi::math::Matrix< T, ROW, COL>::reference: Mutable reference to element.
typedef Size mi::math::Matrix< T, ROW, COL>::size_type: Size type, unsigned.
typedef Matrix_struct< T, ROW, COL> mi::math::Matrix< T, ROW, COL>::storage_type: Storage class used by this matrix.
typedef T mi::math::Matrix< T, ROW, COL>::value_type: Element type.

Enums

enum mi::math::Matrix< T, ROW, COL>::Transposed_copy_tag

Enum type used to tag a special copy constructor that transposes the matrix while copying.

Enumerator:

TRANSPOSED_COPY_TAG: Enum value used to call a special copy constructor that transposes the matrix while copying.

Constructors

mi::math::Matrix< T, ROW, COL>::Matrix() [inline]

The default constructor leaves the vector elements uninitialized.

mi::math::Matrix< T, ROW, COL>::Matrix( const Matrix_struct < T , ROW , COL >& other) [inline]

Constructor from underlying storage type.

mi::math::Matrix< T, ROW, COL>::Matrix( T diag) [inline, explicit]

Constructor initializes all matrix elements to zero and the diagonal elements to diag. Examples are diag==0 to create the null matrix and diag==1 to create the unit matrix.

Parameters

diag: value for diagonal elements.

template< typename Iterator> mi::math::Matrix< T, ROW, COL>::Matrix( From_iterator_tag, Iterator p) [inline]

Constructor requires the mi::math::FROM_ITERATOR tag as first argument and initializes the matrix elements with the first ROW times COL elements from the sequence starting at the iterator p. Iterator must be a model of an input iterator. The value type of Iterator must be assignment compatible with the matrix elements type T.

An example:

‎        std::vector<int> data( 42, 42); // 42 elements of value 42
        mi::math::Matrix< mi::Float64, 4, 4> mat( mi::math::FROM_ITERATOR, data.begin());

template< typename T2> mi::math::Matrix< T, ROW, COL>::Matrix( const T2 (&) array[SIZE]) [inline, explicit]

Constructor initializes the matrix elements from an array of dimension ROW times COL. The value type T2 of the array must be assignment compatible with the matrix elements type T.

An example that initializes a 2x2 unit matrix from an array:

‎        int data[4] = { 1, 0, 0, 1};
        mi::math::Matrix< mi::Float64, 2, 2> mat(data);

template< typename T2> mi::math::Matrix< T, ROW, COL>::Matrix( const Matrix < T2 , ROW , COL >& other) [inline, explicit]

Template constructor that allows explicit conversions from other matrices with assignment compatible element value type.

mi::math::Matrix< T, ROW, COL>::Matrix( Transposed_copy_tag, const Matrix < T , COL , ROW >& other) [inline]

Constructor that initializes the matrix with the transpose matrix of other.

template< typename T2> mi::math::Matrix< T, ROW, COL>::Matrix( Transposed_copy_tag, const Matrix < T2 , COL , ROW >& other) [inline]

Template constructor that initializes the matrix with the transpose matrix of other that allows the explicit conversions from other matrices with assignment compatible element value type.

mi::math::Matrix< T, ROW, COL>::Matrix( const Row_vector& v0) [inline, explicit]

Dedicated constructor, for ROW==1 only, that initializes matrix from one row vector v0.

Precondition:

ROW == 1

mi::math::Matrix< T, ROW, COL>::Matrix( const Row_vector& v0, const Row_vector& v1) [inline]

Dedicated constructor, for ROW==2 only, that initializes matrix from two row vectors (v0,v1).

Precondition:

ROW == 2

mi::math::Matrix< T, ROW, COL>::Matrix( const Row_vector& v0, const Row_vector& v1, const Row_vector& v2) [inline]

Dedicated constructor, for ROW==3 only, that initializes matrix from three row vectors (v0,v1,v2).

Precondition:

ROW == 3

mi::math::Matrix< T, ROW, COL>::Matrix( const Row_vector& v0, const Row_vector& v1, const Row_vector& v2, const Row_vector& v3) [inline]

Dedicated constructor, for ROW==4 only, that initializes matrix from four row vectors (v0,v1,v2,v3).

Precondition:

ROW == 4

mi::math::Matrix< T, ROW, COL>::Matrix( T m0, T m1) [inline]

2-element constructor, must be a 1x2 or 2x1 matrix. The elements are given in row-major order.

mi::math::Matrix< T, ROW, COL>::Matrix( T m0, T m1, T m2) [inline]

3-element constructor, must be a 1x3 or 3x1 matrix. The elements are given in row-major order.

mi::math::Matrix< T, ROW, COL>::Matrix( T m0, T m1, T m2, T m3) [inline]

4-element constructor, must be a 1x4, 2x2, or 4x1 matrix. The elements are given in row-major order.

mi::math::Matrix< T, ROW, COL>::Matrix( T m0, T m1, T m2, T m3, T m4, T m5) [inline]

6-element constructor, must be a 2x3 or 3x2 matrix. The elements are given in row-major order.

mi::math::Matrix< T, ROW, COL>::Matrix( T m0, T m1, T m2, T m3, T m4, T m5, T m6, T m7) [inline]

8-element constructor, must be a 2x4 or 4x2 matrix. The elements are given in row-major order.

mi::math::Matrix< T, ROW, COL>::Matrix( T m0, T m1, T m2, T m3, T m4, T m5, T m6, T m7, T m8) [inline]

9-element constructor, must be a 3x3 matrix. The elements are given in row-major order.

mi::math::Matrix< T, ROW, COL>::Matrix( T m0, T m1, T m2, T m3, T m4, T m5, T m6, T m7, T m8, T m9, T m10, T m11) [inline]

12-element constructor, must be a 3x4 or 4x3 matrix. The elements are given in row-major order.

mi::math::Matrix< T, ROW, COL>::Matrix( T m0, T m1, T m2, T m3, T m4, T m5, T m6, T m7, T m8, T m9, T m10, T m11, T m12, T m13, T m14, T m15) [inline]

16-element constructor, must be a 4x4 matrix. The elements are given in row-major order.

Member Functions

T* mi::math::Matrix< T, ROW, COL>::begin() [inline]: Returns the pointer to the first matrix element.
const T* mi::math::Matrix< T, ROW, COL>::begin() const [inline]: Returns the pointer to the first matrix element.
T mi::math::Matrix< T, ROW, COL>::det33() const [inline]: Returns the determinant of the upper-left 3x3 sub-matrix.

Precondition:

(ROW==3 or ROW==4) and (COL==3 or COL==4)
T* mi::math::Matrix< T, ROW, COL>::end() [inline]: Returns the past-the-end pointer. The range [begin(),end()) forms the range over all ROW times COL many matrix elements.
const T* mi::math::Matrix< T, ROW, COL>::end() const [inline]: Returns the past-the-end pointer. The range [begin(),end()) forms the range over all ROW times COL many matrix elements.
T mi::math::Matrix< T, ROW, COL>::get( Size i) const [inline]: Accesses the i-th matrix element, indexed in the order of the row-major memory layout.

Precondition:

0 <= i < ROW*COL
T mi::math::Matrix< T, ROW, COL>::get( Size row, Size col) const [inline]: Accesses the (row, col)-th matrix element.

Precondition:

0 <= row < ROW and 0 <= col < COL
bool mi::math::Matrix< T, ROW, COL>::invert() [inline]: Inverts this matrix and returns success or failure. The matrix cannot be inverted if it is singular or if it is non-square.
void mi::math::Matrix< T, ROW, COL>::lookat( const Vector < Float32 , 3 >& position, const Vector < Float32 , 3 >& target, const Vector < Float32 , 3 >& up) [inline]: Sets a transformation matrix based on a given center, a reference point, and a direction. The transformation is computed such that position is mapped to the origin, target is mapped to the negative Z-axis, and the up direction is mapped to the positive Y-axis.
void mi::math::Matrix< T, ROW, COL>::lookat( const Vector < Float64 , 3 >& position, const Vector < Float64 , 3 >& target, const Vector < Float64 , 3 >& up) [inline]: Sets a transformation matrix based on a given center, a reference point, and a direction. The transformation is computed such that the origin is mapped to position, the negative Z-axis is mapped to the target direction, and the positive Y-axis is mapped to the up direction.
static Size mi::math::Matrix< T, ROW, COL>::max_size() [inline, static]: Constant maximum size of the vector.
T& mi::math::Matrix< T, ROW, COL>::operator()( Size row, Size col) [inline]: Accesses the (row,col)-th matrix element.

Precondition:

0 <= row < ROW and 0 <= col < COL
const T& mi::math::Matrix< T, ROW, COL>::operator()( Size row, Size col) const [inline]: Accesses the (row, col)-th matrix element.

Precondition:

0 <= row < ROW and 0 <= col < COL
Matrix& mi::math::Matrix< T, ROW, COL>::operator=( const Matrix& other) [inline]: Assignment.
Row_vector& mi::math::Matrix< T, ROW, COL>::operator[]( Size row) [inline]: Accesses the row-th row vector, 0 <= row < ROW.
const Row_vector& mi::math::Matrix< T, ROW, COL>::operator[]( Size row) const [inline]: Accesses the row-th row vector, 0 <= row < ROW.
void mi::math::Matrix< T, ROW, COL>::rotate( T xangle, T yangle, T zangle) [inline]: Adds a relative rotation to the matrix (Euler angles, by component). The rotation is given by XYZ Euler angles (in radians). The elements in the last column of the matrix remain unchanged.
void mi::math::Matrix< T, ROW, COL>::rotate( const Vector < Float32 , 3 >& angles) [inline]: Adds a relative rotation to the matrix (Euler angles, by vector). The rotation is given by XYZ Euler angles (in radians). The elements in the last column of the matrix remain unchanged.
void mi::math::Matrix< T, ROW, COL>::rotate( const Vector < Float64 , 3 >& angles) [inline]: Adds a relative rotation to the matrix (Euler angles, by vector). The rotation is given by XYZ Euler angles (in radians). The elements in the last column of the matrix remain unchanged.
void mi::math::Matrix< T, ROW, COL>::set( Size i, T value) [inline]: Sets the i-th matrix element to value, indexed in the order of the row-major memory layout.

Precondition:

0 <= i < ROW*COL
void mi::math::Matrix< T, ROW, COL>::set( Size row, Size col, T value) [inline]: Sets the i-th matrix element to value, indexed in the order of the row-major memory layout.

Precondition:

0 <= row < ROW and 0 <= col < COL
void mi::math::Matrix< T, ROW, COL>::set_rotation( T x_angle, T y_angle, T z_angle) [inline]: Stores an absolute rotation in the upper left 3x3 rotation matrix (Euler angles, by component). The rotation is given by XYZ Euler angles (in radians). The other matrix elements remain unchanged.
void mi::math::Matrix< T, ROW, COL>::set_rotation( const Vector < Float32 , 3 >& angles) [inline]: Stores an absolute rotation in the upper left 3x3 rotation matrix (Euler angles, by vector). The rotation is given by XYZ Euler angles (in radians). The other matrix elements remain unchanged.
void mi::math::Matrix< T, ROW, COL>::set_rotation( const Vector < Float64 , 3 >& angles) [inline]: Stores an absolute rotation in the upper left 3x3 rotation matrix (Euler angles, by vector). The rotation is given by XYZ Euler angles (in radians). The other matrix elements remain unchanged.
void mi::math::Matrix< T, ROW, COL>::set_rotation( const Vector < Float32 , 3 >& axis, Float64 angle) [inline]: Stores an absolute rotation (by axis and angle). The computed rotation matrix describes a rotation by the given angle (in radians) around the given axis. The other matrix elements are set to 0 and 1, respectively.

Precondition:

axis is normalized
void mi::math::Matrix< T, ROW, COL>::set_rotation( const Vector < Float64 , 3 >& axis, Float64 angle) [inline]: Stores an absolute rotation (by axis and angle). The computed rotation matrix describes a rotation by the given angle (in radians) around the given axis. The other matrix elements are set to 0 and 1, respectively.

Precondition:

axis is normalized
void mi::math::Matrix< T, ROW, COL>::set_translation( T dx, T dy, T dz) [inline]: Stores an absolute translation in the matrix (by component). The other matrix elements remain unchanged.
void mi::math::Matrix< T, ROW, COL>::set_translation( const Vector < Float32 , 3 >& vector) [inline]: Stores an absolute translation in the matrix (by vector). The other matrix elements remain unchanged.
void mi::math::Matrix< T, ROW, COL>::set_translation( const Vector < Float64 , 3 >& vector) [inline]: Stores an absolute translation in the matrix (by vector). The other matrix elements remain unchanged.
static Size mi::math::Matrix< T, ROW, COL>::size() [inline, static]: Constant size of the vector.
void mi::math::Matrix< T, ROW, COL>::translate( T x, T y, T z) [inline]: Adds a relative translation to the matrix (by components). The other matrix elements remain unchanged.
void mi::math::Matrix< T, ROW, COL>::translate( const Vector < Float32 , 3 >& vector) [inline]: Adds a relative translation to the matrix (by vector). The other matrix elements remain unchanged.
void mi::math::Matrix< T, ROW, COL>::translate( const Vector < Float64 , 3 >& vector) [inline]: Adds a relative translation to the matrix (by vector). The other matrix elements remain unchanged.
void mi::math::Matrix< T, ROW, COL>::transpose() [inline]: Transposes this matrix by exchanging rows and columns.

Precondition:

ROW==COL

For transposing non-square matrices see the mi::math::transpose() function.

Variables

const Size mi::math::Matrix< T, ROW, COL>::COLUMNS = COL [static]: Constant number of columns of the matrix.
const Size mi::math::Matrix< T, ROW, COL>::ROWS = ROW [static]: Constant number of rows of the matrix.
const Size mi::math::Matrix< T, ROW, COL>::SIZE = ROW*COL [static]: Constant size of the matrix.

RealityServer® 4.4 Document Center

neuray API Programmer's Manual

mi::math::Matrix< T, ROW, COL> Template Class Reference

[Matrix Class]

Description

Public Enumerations

Public Typedefs

Public Constructors

Public Member Functions

Static Public Member Functions

Static Public Variables

Typedefs

Enums

Enumerator:

Constructors

Parameters

Member Functions

Variables