neuray API Programmer's Manual

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.
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...
get( Size i) const
Accesses the i-th matrix element, indexed in the order of the row-major memory layout. More...
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...
Matrixoperator=( const Matrix& other)
Assignment.
Row_vectoroperator[]( Size row)
Accesses the row-th row vector, 0 <= row < ROW.
const Row_vectoroperator[]( 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.