neuray API Programmer's Manual

Matrix Class

[Math API]

Description

A NxM-dimensional matrix class template of fixed dimensions with supporting functions.

Include File:

#include <mi/math/matrix.h>

Modules

 
Storage class for matrix templates with support for xx, xy, xz, etc., members for appropriate dimensions. More...

Classes

class 
NxM-dimensional matrix class template of fixed dimensions. More...

Functions

template< typename T, Size, Size>bool  mi::math::operator!=( const Matrix < T , ROW , COL >& lhs, const Matrix < T , ROW , COL >& rhs)
Returns true if lhs is elementwise not equal to rhs.
template< typename T, Size, Size, Size, Size> Matrix < T , ROW1 , COL2 > mi::math::operator*( const Matrix < T , ROW1 , COL1 >& lhs, const Matrix < T , ROW2 , COL2 >& rhs)
Performs matrix multiplication, lhs times rhs, and returns the new result. More...
template< typename T, Size, Size, Size> Vector < T , ROW > mi::math::operator*( const Matrix < T , ROW , COL >& mat, const Vector < T , DIM >& vec)
Multiplies the (column) vector vec from the right with the matrix mat and returns the resulting vector. More...
template< Size, typename T, Size, Size> Vector < T , COL > mi::math::operator*( const Vector < T , DIM >& vec, const Matrix < T , ROW , COL >& mat)
Multiplies the (row) vector vec from the left with the matrix mat and returns the resulting vector. More...
template< typename T, Size, Size> Matrix < T , ROW , COL > mi::math::operator*( const Matrix < T , ROW , COL >& mat, T factor)
Multiplies the matrix mat elementwise with the scalar factor and returns the new result.
template< typename T, Size, Size> Matrix < T , ROW , COL > mi::math::operator*( T factor, const Matrix < T , ROW , COL >& mat)
Multiplies the matrix mat elementwise with the scalar factor and returns the new result.
template< typename T, Size, Size> Matrix < T , ROW , COL >& mi::math::operator*=( Matrix < T , ROW , COL >& lhs, const Matrix < T , COL , COL >& rhs)
Performs matrix multiplication, lhs times rhs, assigns it to lhs, and returns the modified lhs. More...
template< typename T, Size, Size> Matrix < T , ROW , COL >& mi::math::operator*=( Matrix < T , ROW , COL >& mat, T factor)
Multiplies the matrix mat elementwise with the scalar factor and returns the modified matrix mat.
template< typename T, Size, Size> Matrix < T , ROW , COL > mi::math::operator+( const Matrix < T , ROW , COL >& lhs, const Matrix < T , ROW , COL >& rhs)
Adds lhs and rhs elementwise and returns the new result.
template< typename T, Size, Size> Matrix < T , ROW , COL >& mi::math::operator+=( Matrix < T , ROW , COL >& lhs, const Matrix < T , ROW , COL >& rhs)
Adds rhs elementwise to lhs and returns the modified lhs.
template< typename T, Size, Size> Matrix < T , ROW , COL > mi::math::operator-( const Matrix < T , ROW , COL >& lhs, const Matrix < T , ROW , COL >& rhs)
Subtracts rhs elementwise from lhs and returns the new result.
template< typename T, Size, Size> Matrix < T , ROW , COL > mi::math::operator-( const Matrix < T , ROW , COL >& mat)
Negates the matrix mat elementwise and returns the new result.
template< typename T, Size, Size> Matrix < T , ROW , COL >& mi::math::operator-=( Matrix < T , ROW , COL >& lhs, const Matrix < T , ROW , COL >& rhs)
Subtracts rhs elementwise from lhs and returns the modified lhs.
template< typename T, Size, Size>bool  mi::math::operator<( const Matrix < T , ROW , COL >& lhs, const Matrix < T , ROW , COL >& rhs)
Returns true if lhs is lexicographically less than rhs. More...
template< typename T, Size, Size>bool  mi::math::operator<=( const Matrix < T , ROW , COL >& lhs, const Matrix < T , ROW , COL >& rhs)
Returns true if lhs is lexicographically less than or equal to rhs. More...
template< typename T, Size, Size>bool  mi::math::operator==( const Matrix < T , ROW , COL >& lhs, const Matrix < T , ROW , COL >& rhs)
Returns true if lhs is elementwise equal to rhs.
template< typename T, Size, Size>bool  mi::math::operator>( const Matrix < T , ROW , COL >& lhs, const Matrix < T , ROW , COL >& rhs)
Returns true if lhs is lexicographically greater than rhs. More...
template< typename T, Size, Size>bool  mi::math::operator>=( const Matrix < T , ROW , COL >& lhs, const Matrix < T , ROW , COL >& rhs)
Returns true if lhs is lexicographically greater than or equal to rhs. More...
template< Size, Size, typename T, Size, Size> Matrix < T , NEW_ROW , NEW_COL > mi::math::sub_matrix( const Matrix < T , ROW , COL >& mat)
Returns the upper-left sub-matrix of size NEW_ROW times NEW_COL. More...
template< typename T, typename U> Vector < U , 3 > mi::math::transform_normal( const Matrix < T , 4 , 4 >& mat, const Vector < U , 3 >& normal)
Returns a transformed 3D normal vector by applying the 3x3 transposed linear sub-transformation in the inverse of the 4x4 matrix mat on the 3D normal vector normal. More...
template< typename T, typename U> Vector < U , 3 > mi::math::transform_normal_inv( const Matrix < T , 3 , 3 >& inv_mat, const Vector < U , 3 >& normal)
Returns an inverse transformed 3D normal vector by applying the 3x3 transposed linear transformation in the matrix inv_mat on the 3D normal vector normal. More...
template< typename T, typename U> Vector < U , 3 > mi::math::transform_normal_inv( const Matrix < T , 4 , 4 >& inv_mat, const Vector < U , 3 >& normal)
Returns an inverse transformed 3D normal vector by applying the 3x3 transposed linear sub-transformation in the 4x4 matrix inv_mat on the 3D normal vector normal. More...
template< typename T, typename U>mi::math::transform_point( const Matrix < T , 4 , 4 >& mat, const U& point)
Returns a transformed 1D point by applying the full transformation in the 4x4 matrix mat on the 1D point point, which includes the translation. More...
template< typename T, typename U> Vector < U , 2 > mi::math::transform_point( const Matrix < T , 4 , 4 >& mat, const Vector < U , 2 >& point)
Returns a transformed 2D point by applying the full transformation in the 4x4 matrix mat on the 2D point point, which includes the translation. More...
template< typename T, typename U> Vector < U , 3 > mi::math::transform_point( const Matrix < T , 4 , 3 >& mat, const Vector < U , 3 >& point)
Returns a transformed 3D point by applying the full transformation in the 4x3 matrix mat on the 3D point point, which includes the translation. More...
template< typename T, typename U> Vector < U , 3 > mi::math::transform_point( const Matrix < T , 4 , 4 >& mat, const Vector < U , 3 >& point)
Returns a transformed 3D point by applying the full transformation in the 4x4 matrix mat on the 3D point point, which includes the translation. More...
template< typename T, typename U> Vector < U , 4 > mi::math::transform_point( const Matrix < T , 4 , 4 >& mat, const Vector < U , 4 >& point)
Returns a transformed 4D point by applying the full transformation in the 4x4 matrix mat on the 4D point point, which includes the translation. More...
template< typename T, typename U>mi::math::transform_vector( const Matrix < T , 4 , 4 >& mat, const U& vector)
Returns a transformed 1D vector by applying the 1x1 linear sub-transformation in the 4x4 matrix mat on the 1D vector vector, which excludes the translation. More...
template< typename T, typename U> Vector < U , 2 > mi::math::transform_vector( const Matrix < T , 4 , 4 >& mat, const Vector < U , 2 >& vector)
Returns a transformed 2D vector by applying the 2x2 linear sub-transformation in the 4x4 matrix mat on the 2D vector vector, which excludes the translation. More...
template< typename T, typename U> Vector < U , 3 > mi::math::transform_vector( const Matrix < T , 3 , 3 >& mat, const Vector < U , 3 >& vector)
Returns a transformed 3D vector by applying the 3x3 matrix mat transformation on the 3D vector vector. More...
template< typename T, typename U> Vector < U , 3 > mi::math::transform_vector( const Matrix < T , 4 , 3 >& mat, const Vector < U , 3 >& vector)
Returns a transformed 3D vector by applying the 3x3 linear sub-transformation in the 4x3 matrix mat on the 3D vector vector, which excludes the translation. More...
template< typename T, typename U> Vector < U , 3 > mi::math::transform_vector( const Matrix < T , 4 , 4 >& mat, const Vector < U , 3 >& vector)
Returns a transformed 3D vector by applying the 3x3 linear sub-transformation in the 4x4 matrix mat on the 3D vector vector, which excludes the translation. More...
template< typename T, Size, Size> Matrix < T , COL , ROW > mi::math::transpose( const Matrix < T , ROW , COL >& mat)
Returns the transpose of the matrix mat by exchanging rows and columns.

Functions

template< typename T, Size, Size>

bool mi::math::operator!=( const Matrix < T , ROW , COL >& lhs, const Matrix < T , ROW , COL >& rhs) [inline]

Returns true if lhs is elementwise not equal to rhs.

template< typename T, Size, Size, Size, Size>

Matrix < T , ROW1 , COL2 > mi::math::operator*( const Matrix < T , ROW1 , COL1 >& lhs, const Matrix < T , ROW2 , COL2 >& rhs) [inline]

Performs matrix multiplication, lhs times rhs, and returns the new result. The matrices can be of different sizes, but the number of columns of lhs must be equal to the number of rows of rhs. The result matrix has then the size (number of rows of lhs) times (number of columns of rhs).

template< typename T, Size, Size, Size>

Vector < T , ROW > mi::math::operator*( const Matrix < T , ROW , COL >& mat, const Vector < T , DIM >& vec) [inline]

Multiplies the (column) vector vec from the right with the matrix mat and returns the resulting vector. The result vector has the same dimension as the number of rows in the matrix mat.

Precondition:

The vector vec must have the same dimension as the number of columns in the matrix mat.

template< Size, typename T, Size, Size>

Vector < T , COL > mi::math::operator*( const Vector < T , DIM >& vec, const Matrix < T , ROW , COL >& mat) [inline]

Multiplies the (row) vector vec from the left with the matrix mat and returns the resulting vector. The result vector has the same dimension as the number of columns in the matrix mat.

Precondition:

The vector vec must have the same dimension as the number of rows in the matrix mat.

template< typename T, Size, Size>

Matrix < T , ROW , COL > mi::math::operator*( const Matrix < T , ROW , COL >& mat, T factor) [inline]

Multiplies the matrix mat elementwise with the scalar factor and returns the new result.

template< typename T, Size, Size>

Matrix < T , ROW , COL > mi::math::operator*( T factor, const Matrix < T , ROW , COL >& mat) [inline]

Multiplies the matrix mat elementwise with the scalar factor and returns the new result.

template< typename T, Size, Size>

Matrix < T , ROW , COL >& mi::math::operator*=( Matrix < T , ROW , COL >& lhs, const Matrix < T , COL , COL >& rhs) [inline]

Performs matrix multiplication, lhs times rhs, assigns it to lhs, and returns the modified lhs. The matrix lhs must be of size ROW times COL, and the matrix rhs must be of size COL times COL. For mixed size matrix multiplications, see the mi::math::operator*() on matrices.

template< typename T, Size, Size>

Matrix < T , ROW , COL >& mi::math::operator*=( Matrix < T , ROW , COL >& mat, T factor) [inline]

Multiplies the matrix mat elementwise with the scalar factor and returns the modified matrix mat.

template< typename T, Size, Size>

Matrix < T , ROW , COL > mi::math::operator+( const Matrix < T , ROW , COL >& lhs, const Matrix < T , ROW , COL >& rhs) [inline]

Adds lhs and rhs elementwise and returns the new result.

template< typename T, Size, Size>

Matrix < T , ROW , COL >& mi::math::operator+=( Matrix < T , ROW , COL >& lhs, const Matrix < T , ROW , COL >& rhs) [inline]

Adds rhs elementwise to lhs and returns the modified lhs.

template< typename T, Size, Size>

Matrix < T , ROW , COL > mi::math::operator-( const Matrix < T , ROW , COL >& lhs, const Matrix < T , ROW , COL >& rhs) [inline]

Subtracts rhs elementwise from lhs and returns the new result.

template< typename T, Size, Size>

Matrix < T , ROW , COL > mi::math::operator-( const Matrix < T , ROW , COL >& mat) [inline]

Negates the matrix mat elementwise and returns the new result.

template< typename T, Size, Size>

Matrix < T , ROW , COL >& mi::math::operator-=( Matrix < T , ROW , COL >& lhs, const Matrix < T , ROW , COL >& rhs) [inline]

Subtracts rhs elementwise from lhs and returns the modified lhs.

template< typename T, Size, Size>

bool mi::math::operator<( const Matrix < T , ROW , COL >& lhs, const Matrix < T , ROW , COL >& rhs) [inline]

Returns true if lhs is lexicographically less than rhs.

See also:

mi_def_lexicographic_order

template< typename T, Size, Size>

bool mi::math::operator<=( const Matrix < T , ROW , COL >& lhs, const Matrix < T , ROW , COL >& rhs) [inline]

Returns true if lhs is lexicographically less than or equal to rhs.

See also:

mi_def_lexicographic_order

template< typename T, Size, Size>

bool mi::math::operator==( const Matrix < T , ROW , COL >& lhs, const Matrix < T , ROW , COL >& rhs) [inline]

Returns true if lhs is elementwise equal to rhs.

template< typename T, Size, Size>

bool mi::math::operator>( const Matrix < T , ROW , COL >& lhs, const Matrix < T , ROW , COL >& rhs) [inline]

Returns true if lhs is lexicographically greater than rhs.

See also:

mi_def_lexicographic_order

template< typename T, Size, Size>

bool mi::math::operator>=( const Matrix < T , ROW , COL >& lhs, const Matrix < T , ROW , COL >& rhs) [inline]

Returns true if lhs is lexicographically greater than or equal to rhs.

See also:

mi_def_lexicographic_order

template< Size, Size, typename T, Size, Size>

Matrix < T , NEW_ROW , NEW_COL > mi::math::sub_matrix( const Matrix < T , ROW , COL >& mat) [inline]

Returns the upper-left sub-matrix of size NEW_ROW times NEW_COL.

Precondition:

NEW_ROW <= ROW and NEW_COL <= COL.

template< typename T, typename U>

Vector < U , 3 > mi::math::transform_normal( const Matrix < T , 4 , 4 >& mat, const Vector < U , 3 >& normal) [inline]

Returns a transformed 3D normal vector by applying the 3x3 transposed linear sub-transformation in the inverse of the 4x4 matrix mat on the 3D normal vector normal. Note that in general, a normal vector is transformed by the transposed inverse matrix (compared to a point transformation) and the inverse is often costly to compute. So, if you wish to compute the inverse once and keep it to transform several normal vectors, you can use the mi::math::transform_normal_inv() function, which accepts the inverse matrix as argument.

If the linear sub-matrix cannot be inverted, this function returns the unchanged normal.

The normal vector normal is considered to be a row vector, which is multiplied from the left with the transposed upper-left 3x3 sub-matrix of the inverse of mat.

Parameters

mat
4x4 transformation matrix
normal
normal vector to transform

template< typename T, typename U>

Vector < U , 3 > mi::math::transform_normal_inv( const Matrix < T , 3 , 3 >& inv_mat, const Vector < U , 3 >& normal) [inline]

Returns an inverse transformed 3D normal vector by applying the 3x3 transposed linear transformation in the matrix inv_mat on the 3D normal vector normal. Note that in general, a normal vector is transformed by the transposed inverse matrix (compared to a point transformation). The inverse is often costly to compute, why one typically keeps the inverse stored and this function operates then on the inverse matrix to properly transform normal vectors. If you need to transform only one normal, you can also consider the mi::math::transform_normal() function, which includes the inverse computation.

The normal vector normal is considered to be a row vector, which is multiplied from the left with the transposed upper-left 3x3 sub-matrix of inv_mat.

Parameters

inv_mat
inverse 4x4 transformation matrix
normal
normal vector to transform

template< typename T, typename U>

Vector < U , 3 > mi::math::transform_normal_inv( const Matrix < T , 4 , 4 >& inv_mat, const Vector < U , 3 >& normal) [inline]

Returns an inverse transformed 3D normal vector by applying the 3x3 transposed linear sub-transformation in the 4x4 matrix inv_mat on the 3D normal vector normal. Note that in general, a normal vector is transformed by the transposed inverse matrix (compared to a point transformation). The inverse is often costly to compute, why one typically keeps the inverse stored and this function operates then on the inverse matrix to properly transform normal vectors. If you need to transform only one normal, you can also consider the mi::math::transform_normal() function, which includes the inverse computation.

The normal vector normal is considered to be a row vector, which is multiplied from the left with the transposed upper-left 3x3 sub-matrix of inv_mat.

Parameters

inv_mat
inverse 4x4 transformation matrix
normal
normal vector to transform

template< typename T, typename U>

U mi::math::transform_point( const Matrix < T , 4 , 4 >& mat, const U& point) [inline]

Returns a transformed 1D point by applying the full transformation in the 4x4 matrix mat on the 1D point point, which includes the translation. The point point is considered to be a row vector, which is multiplied from the left with the matrix mat.

Parameters

mat
4x4 transformation matrix
point
point to transform

template< typename T, typename U>

Vector < U , 2 > mi::math::transform_point( const Matrix < T , 4 , 4 >& mat, const Vector < U , 2 >& point) [inline]

Returns a transformed 2D point by applying the full transformation in the 4x4 matrix mat on the 2D point point, which includes the translation. The point point is considered to be a row vector, which is multiplied from the left with the matrix mat.

Parameters

mat
4x4 transformation matrix
point
point to transform

template< typename T, typename U>

Vector < U , 3 > mi::math::transform_point( const Matrix < T , 4 , 3 >& mat, const Vector < U , 3 >& point) [inline]

Returns a transformed 3D point by applying the full transformation in the 4x3 matrix mat on the 3D point point, which includes the translation. The point point is considered to be a row vector, which is multiplied from the left with the matrix mat.

Parameters

mat
4x3 transformation matrix
point
point to transform

template< typename T, typename U>

Vector < U , 3 > mi::math::transform_point( const Matrix < T , 4 , 4 >& mat, const Vector < U , 3 >& point) [inline]

Returns a transformed 3D point by applying the full transformation in the 4x4 matrix mat on the 3D point point, which includes the translation. The point point is considered to be a row vector, which is multiplied from the left with the matrix mat.

Parameters

mat
4x4 transformation matrix
point
point to transform

template< typename T, typename U>

Vector < U , 4 > mi::math::transform_point( const Matrix < T , 4 , 4 >& mat, const Vector < U , 4 >& point) [inline]

Returns a transformed 4D point by applying the full transformation in the 4x4 matrix mat on the 4D point point, which includes the translation. The point point is considered to be a row vector, which is multiplied from the left with the matrix mat.

Parameters

mat
4x4 transformation matrix
point
point to transform

template< typename T, typename U>

U mi::math::transform_vector( const Matrix < T , 4 , 4 >& mat, const U& vector) [inline]

Returns a transformed 1D vector by applying the 1x1 linear sub-transformation in the 4x4 matrix mat on the 1D vector vector, which excludes the translation. The vector vector is considered to be a row vector, which is multiplied from the left with the matrix mat.

Parameters

mat
4x4 transformation matrix
vector
vector to transform

template< typename T, typename U>

Vector < U , 2 > mi::math::transform_vector( const Matrix < T , 4 , 4 >& mat, const Vector < U , 2 >& vector) [inline]

Returns a transformed 2D vector by applying the 2x2 linear sub-transformation in the 4x4 matrix mat on the 2D vector vector, which excludes the translation. The vector vector is considered to be a row vector, which is multiplied from the left with the matrix mat.

Parameters

mat
4x4 transformation matrix
vector
vector to transform

template< typename T, typename U>

Vector < U , 3 > mi::math::transform_vector( const Matrix < T , 3 , 3 >& mat, const Vector < U , 3 >& vector) [inline]

Returns a transformed 3D vector by applying the 3x3 matrix mat transformation on the 3D vector vector. The vector vector is considered to be a row vector, which is multiplied from the left with the matrix mat.

Parameters

mat
3x3 transformation matrix
vector
vector to transform

template< typename T, typename U>

Vector < U , 3 > mi::math::transform_vector( const Matrix < T , 4 , 3 >& mat, const Vector < U , 3 >& vector) [inline]

Returns a transformed 3D vector by applying the 3x3 linear sub-transformation in the 4x3 matrix mat on the 3D vector vector, which excludes the translation. The vector vector is considered to be a row vector, which is multiplied from the left with the matrix mat.

Parameters

mat
4x3 transformation matrix
vector
vector to transform

template< typename T, typename U>

Vector < U , 3 > mi::math::transform_vector( const Matrix < T , 4 , 4 >& mat, const Vector < U , 3 >& vector) [inline]

Returns a transformed 3D vector by applying the 3x3 linear sub-transformation in the 4x4 matrix mat on the 3D vector vector, which excludes the translation. The vector vector is considered to be a row vector, which is multiplied from the left with the matrix mat.

Parameters

mat
4x4 transformation matrix
vector
vector to transform

template< typename T, Size, Size>

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

Returns the transpose of the matrix mat by exchanging rows and columns.