Kanzi framework  3.9.1
Java API
Matrix4x4 Class Reference

Matrix with 4x4 elements. More...

Classes

class  FieldOfViewType
 Field of view type of a camera. More...
 

Public Member Functions

 Matrix4x4 (long cPtr, boolean cMemoryOwn)
 
 Matrix4x4 ()
 Default constructor, initializes the matrix to identity matrix.
 
 Matrix4x4 (float x0, float x1, float x2, float x3, float x4, float x5, float x6, float x7, float x8, float x9, float x10, float x11, float x12, float x13, float x14, float x15)
 Constructs the matrix from elements in column-major order.
 
 Matrix4x4 (Vector3 x, Vector3 y, Vector3 z, Vector3 translation)
 Constructs the matrix from four column vectors.
 
 Matrix4x4 (Vector4 x, Vector4 y, Vector4 z, Vector4 translation)
 Constructs the matrix from four column vectors.
 
Matrix4x4 add (Matrix4x4 v)
 Modifies this matrix by adding another matrix. More...
 
synchronized void delete ()
 
boolean equals (Object obj)
 
float get (long index)
 Returns individual matrix element value at index. More...
 
OptionalVector3 getRotationAngle ()
 Calculates Euler rotation angles of the matrix. More...
 
Vector3 getScale ()
 Get scale as a vector.
 
Vector3 getTranslation ()
 Get translation. More...
 
float getTranslationX ()
 Get translation on X axis. More...
 
float getTranslationY ()
 Get translation on Y axis. More...
 
float getTranslationZ ()
 Get translation on Z axis. More...
 
Vector3 getXAxis ()
 Get X axis.
 
Vector3 getYAxis ()
 Get Y axis.
 
Vector3 getZAxis ()
 Get Z axis.
 
Matrix4x4 inverse ()
 Applies an inversion to a matrix. More...
 
Matrix4x4 inverseAffine ()
 Applies an inversion to an affine matrix. More...
 
Matrix4x4 inverseOrthogonal ()
 Applies an inversion to an orthogonal affine matrix. More...
 
Vector3 multiply (Vector3 vector)
 Multiply a 3-component vector with this matrix. More...
 
Vector4 multiply (Vector4 vector)
 Multiply a 4-component vector with this matrix. More...
 
Matrix4x4 multiply (Matrix4x4 m)
 Modifies this matrix by multiplying it with another matrix. More...
 
void scale (Vector3 scale)
 Scales this matrix. More...
 
void scaleUniform (float scale)
 Scales this matrix. More...
 
void set (long index, float v)
 Sets the individual matrix element at index to value. More...
 
void setTranslation (Vector3 translation)
 Set translation. More...
 
void setTranslationX (float translationX)
 Set translation on X axis. More...
 
void setTranslationY (float translationY)
 Set translation on Y axis. More...
 
void setTranslationZ (float translationZ)
 Set translation on Z axis. More...
 
void setXAxis (Vector3 v)
 Set X axis. More...
 
void setYAxis (Vector3 v)
 Set Y axis. More...
 
void setZAxis (Vector3 v)
 Set Z axis. More...
 
Matrix4x4 subtract (Matrix4x4 v)
 Modifies this matrix by subtracting another matrix from this matrix. More...
 
void translate (Vector3 translate)
 Translates this matrix. More...
 
Matrix4x4 transposed ()
 Applies a transpose to a matrix. More...
 

Static Public Member Functions

static Matrix4x4 add (Matrix4x4 lhs, Matrix4x4 rhs)
 Creates a new matrix by adding an existing matrix to another one. More...
 
static Vector4 calculateCameraViewPosition (Matrix4x4 projectionCameraMatrix)
 Calculates a homogeneous camera view position that you can use to calculate the view direction in a shader. More...
 
static Matrix4x4 createFromHomogenousMatrix (Matrix3x3 matrix, float zTranslation)
 Creates a matrix from an existing homogeneous matrix and Z translation. More...
 
static Matrix4x4 createFromHomogenousMatrix (Matrix3x3 matrix)
 Creates a matrix from an existing homogeneous matrix. More...
 
static Matrix4x4 createIdentity ()
 Creates identity matrix. More...
 
static OptionalMatrix4x4 createLookAtMatrix (Vector3 position, Vector3 lookAtPoint, Vector3 upVector)
 Creates a lookup transformation matrix, so that it is in a given position looking at the given point. More...
 
static Matrix4x4 createOrthogonalProjection (float left, float right, float bottom, float top, float near, float far)
 Creates projection matrix for orthogonal projection. More...
 
static Matrix4x4 createPerspectiveProjection (float near, float far, Matrix4x4.FieldOfViewType fovType, float fovInDegrees, float aspectRatio)
 Creates a perspective projection matrix for a symmetrical viewing volume. More...
 
static Matrix4x4 createPerspectiveProjection (float near, float far, Vector4 fovInDegrees)
 Creates a perspective projection matrix for a viewing volume. More...
 
static Matrix4x4 createRelativeOrthogonalProjection (float near, float far, Matrix4x4.FieldOfViewType fovType, float orthoSize, float aspectRatio)
 Creates an orthogonal projection matrix for a symmetrical viewing volume. More...
 
static Matrix4x4 createRotation (float angleInRadians, Vector3 rotationAxis)
 Creates a rotation matrix over an arbitrary axis. More...
 
static Matrix4x4 createRotationInDegrees (float angleInDegrees, Vector3 rotationAxis)
 Creates a rotation matrix over an arbitrary axis. More...
 
static Matrix4x4 createScale (Vector3 scale)
 Creates a scaling matrix. More...
 
static Matrix4x4 createSRT (Vector3 scale, Vector3 rotationInRadians, Vector3 translation)
 Create an SRT matrix. More...
 
static Matrix4x4 createSubProjection (Matrix4x4 projection, float relativeOffsetX, float relativeOffsetY, float relativeSizeX, float relativeSizeY)
 Calculate sub-quad projection of an existing projection matrix. More...
 
static Matrix4x4 createTranslation (Vector3 translation)
 Creates translation matrix. More...
 
static Matrix4x4 createTranslation (float x, float y, float z)
 Creates translation matrix. More...
 
static Matrix4x4 createXRotationInDegrees (float angleInDegrees)
 Creates a X rotation matrix. More...
 
static Matrix4x4 createXRotationInRadians (float angleInRadians)
 Creates a X rotation matrix. More...
 
static Matrix4x4 createYRotationInDegrees (float angleInDegrees)
 Creates a Y rotation matrix. More...
 
static Matrix4x4 createYRotationInRadians (float angleInRadians)
 Creates a Y rotation matrix. More...
 
static Matrix4x4 createZRotationInDegrees (float angleInDegrees)
 Creates a Z rotation matrix. More...
 
static Matrix4x4 createZRotationInRadians (float angleInRadians)
 Creates a Z rotation matrix. More...
 
static Matrix3x3 extract3x3 (Matrix4x4 matrix)
 Extracts the 3x3 rotation and scaling part of a matrix.
 
static boolean extractSRT (Matrix4x4 matrix, Vector3 scale, Vector3 rotationInRadians, Vector3 translation)
 Extracts from a matrix the scale, rotation, and translation information. More...
 
static long getCPtr (Matrix4x4 obj)
 
static float getDeterminant (Matrix4x4 matrix)
 Calculates the determinant of a matrix. More...
 
static float getDeterminant3x3 (Matrix4x4 matrix)
 Calculates the determinant of the 3x3 part of a matrix. More...
 
static float getTrace (Matrix4x4 matrix)
 Calculates the trace of a matrix. More...
 
static boolean isTranslationOnly (Matrix4x4 matrix)
 Returns whether a matrix is translation-only. More...
 
static Vector3 matrixMultiplyVectorBy3x3 (Matrix4x4 matrix, Vector3 vector)
 Multiplies a 3D vector with the top 3x3 part of a given matrix. More...
 
static Matrix4x4 multiply (Matrix4x4 lhs, Matrix4x4 rhs)
 Multiplies two matrices and returns the product. More...
 
static Matrix4x4 multiplyAffine (Matrix4x4 left, Matrix4x4 right)
 Multiplies two affine matrices and returns the product. More...
 
static Matrix4x4 normalizeBase (Matrix4x4 matrix)
 Orthonormalizes base vectors of the given matrix. More...
 
static Matrix4x4 orthonormalizeBase (Matrix4x4 matrix)
 Orthonormalizes base vectors of the given matrix. More...
 
static Matrix4x4 subtract (Matrix4x4 lhs, Matrix4x4 rhs)
 Creates a new matrix by subtracting an existing matrix from another one. More...
 

Protected Member Functions

void finalize ()
 

Protected Attributes

transient boolean swigCMemOwn
 

Detailed Description

Matrix with 4x4 elements.

Member Function Documentation

◆ add() [1/2]

Matrix4x4 add ( Matrix4x4  v)

Modifies this matrix by adding another matrix.


Parameters
vAnother matrix.
Returns
This matrix.

◆ add() [2/2]

static Matrix4x4 add ( Matrix4x4  lhs,
Matrix4x4  rhs 
)
static

Creates a new matrix by adding an existing matrix to another one.

Parameters
lhsFirst matrix, left hand side.
rhsSecond matrix, right hand side.
Returns
A new matrix resulting from the addition of the right hand side to the left hand side.

◆ calculateCameraViewPosition()

static Vector4 calculateCameraViewPosition ( Matrix4x4  projectionCameraMatrix)
static

Calculates a homogeneous camera view position that you can use to calculate the view direction in a shader.

For orthogonal projections the w-component of the viewpoint is 0 to indicate that the viewpoint is at infinity.

Parameters
projectionCameraMatrixThe matrix to use for calculating the viewpoint.
Returns
Homogeneous viewpoint.

◆ createFromHomogenousMatrix() [1/2]

static Matrix4x4 createFromHomogenousMatrix ( Matrix3x3  matrix,
float  zTranslation 
)
static

Creates a matrix from an existing homogeneous matrix and Z translation.


Parameters
matrixHomogeneous matrix.
zTranslationX translation.
Returns
Newly constructed matrix.

◆ createFromHomogenousMatrix() [2/2]

static Matrix4x4 createFromHomogenousMatrix ( Matrix3x3  matrix)
static

Creates a matrix from an existing homogeneous matrix.


0.0f is used for the Z translation.

Parameters
matrixHomogeneous matrix.
Returns
Newly constructed matrix.

◆ createIdentity()

static Matrix4x4 createIdentity ( )
static

Creates identity matrix.


Returns
Identity matrix.

◆ createLookAtMatrix()

static OptionalMatrix4x4 createLookAtMatrix ( Vector3  position,
Vector3  lookAtPoint,
Vector3  upVector 
)
static

Creates a lookup transformation matrix, so that it is in a given position looking at the given point.


Parameters
positionThe new translation of the node.
lookAtPointA point where the node is looking at.
upVectorThe new up vector of the node.
Returns
Lookup matrix if position is not the same as lookAtPoint and upVector is not null, nullopt otherwise.

◆ createOrthogonalProjection()

static Matrix4x4 createOrthogonalProjection ( float  left,
float  right,
float  bottom,
float  top,
float  near,
float  far 
)
static

Creates projection matrix for orthogonal projection.


Parameters
leftViewing box left.
rightViewing box right.
bottomViewing box bottom.
topViewing box top.
nearCamera near value.
farCamera far value.
Returns
A newly constructed projection matrix.

◆ createPerspectiveProjection() [1/2]

static Matrix4x4 createPerspectiveProjection ( float  near,
float  far,
Matrix4x4.FieldOfViewType  fovType,
float  fovInDegrees,
float  aspectRatio 
)
static

Creates a perspective projection matrix for a symmetrical viewing volume.


Parameters
nearCamera near value.
farCamera far value.
fovTypeTells whether the fovInDegrees parameter is xfov or yfov.
fovInDegreesField of view in degrees.
aspectRatioThe aspect ratio of the viewport.
Returns
Perspective projection matrix.

◆ createPerspectiveProjection() [2/2]

static Matrix4x4 createPerspectiveProjection ( float  near,
float  far,
Vector4  fovInDegrees 
)
static

Creates a perspective projection matrix for a viewing volume.


Parameters
nearCamera near value.
farCamera far value.
fovInDegreesField of view in degrees, specified in order left, right, up, down. Angles to the right of center and upwards of center are positive.
Returns
Perspective projection matrix.

◆ createRelativeOrthogonalProjection()

static Matrix4x4 createRelativeOrthogonalProjection ( float  near,
float  far,
Matrix4x4.FieldOfViewType  fovType,
float  orthoSize,
float  aspectRatio 
)
static

Creates an orthogonal projection matrix for a symmetrical viewing volume.


Parameters
nearCamera near value.
farCamera far value.
fovTypeTells whether the orthoSize parameter is the width or height of the viewing box.
orthoSizeSpecifies the size of the viewing box (either width of height).
aspectRatioSpecifies the aspect ratio of the viewing box.
Returns
Orthogonal projection matrix.
See also
Matrix4x4::createOrthogonalProjection

◆ createRotation()

static Matrix4x4 createRotation ( float  angleInRadians,
Vector3  rotationAxis 
)
static

Creates a rotation matrix over an arbitrary axis.


Similar to the matrix used by glRotatef.
The rotation axis needs not be normalized.

Parameters
angleInRadiansRotation angle in radians.
rotationAxisArbitrary rotation axis.
Returns
Rotation matrix.

◆ createRotationInDegrees()

static Matrix4x4 createRotationInDegrees ( float  angleInDegrees,
Vector3  rotationAxis 
)
static

Creates a rotation matrix over an arbitrary axis.


Similar to the matrix used by glRotatef.
The rotation axis needs not be normalized.

Parameters
angleInDegreesRotation angle in degrees.
rotationAxisArbitrary rotation axis.
Returns
Rotation matrix.

◆ createScale()

static Matrix4x4 createScale ( Vector3  scale)
static

Creates a scaling matrix.


Parameters
scaleScaling vector.
Returns
Scaled matrix.

◆ createSRT()

static Matrix4x4 createSRT ( Vector3  scale,
Vector3  rotationInRadians,
Vector3  translation 
)
static

Create an SRT matrix.


Parameters
scaleScales by axises.
rotationInRadiansRotation component in radians.
translationTranslation component.
Returns
Newly constructed matrix.

◆ createSubProjection()

static Matrix4x4 createSubProjection ( Matrix4x4  projection,
float  relativeOffsetX,
float  relativeOffsetY,
float  relativeSizeX,
float  relativeSizeY 
)
static

Calculate sub-quad projection of an existing projection matrix.



This is a specific solution for an axis-aligned case.

Old projection matrix =
[P00 0 P02 P03]
[ 0 P11 P12 P13]
[ 0 0 P22 P23]
[ 0 0 -1 0]

Traslated and scaled: (x, y) |–> (Ox, Oy) + (Sx * x, Sy * y)
[Sx P00, 0, Ox P22 + Sx P02, Ox P23]
[ 0, Sy P11, Oy P22 + Sy P12, Oy P23]
[ 0, 0, P22, P23]
[ 0, 0, -1, 0]

Parameters
projectionProjection matrix.
relativeOffsetXX offset of sub-quad as portion of the size of the projection area.
relativeOffsetYY offset of sub-quad as portion of the size of the projection area.
relativeSizeXProjection area X size in regard to sub-quad area size.
relativeSizeYProjection area Y size in regard to sub-quad area size.
Returns
Modified projection matrix.

◆ createTranslation() [1/2]

static Matrix4x4 createTranslation ( Vector3  translation)
static

Creates translation matrix.


Parameters
translationTranslation vector.
Returns
Translation matrix.

◆ createTranslation() [2/2]

static Matrix4x4 createTranslation ( float  x,
float  y,
float  z 
)
static

Creates translation matrix.


Parameters
xX component of the Translation vector.
yY component of the Translation vector.
zZ component of the Translation vector.
Returns
Translation matrix.

◆ createXRotationInDegrees()

static Matrix4x4 createXRotationInDegrees ( float  angleInDegrees)
static

Creates a X rotation matrix.


Parameters
angleInDegreesRotation angle in degrees.
Returns
X Rotation matrix.

◆ createXRotationInRadians()

static Matrix4x4 createXRotationInRadians ( float  angleInRadians)
static

Creates a X rotation matrix.


Parameters
angleInRadiansRotation angle in radians.
Returns
X Rotation matrix.

◆ createYRotationInDegrees()

static Matrix4x4 createYRotationInDegrees ( float  angleInDegrees)
static

Creates a Y rotation matrix.


Parameters
angleInDegreesRotation angle in degrees.
Returns
Y Rotation matrix.

◆ createYRotationInRadians()

static Matrix4x4 createYRotationInRadians ( float  angleInRadians)
static

Creates a Y rotation matrix.


Parameters
angleInRadiansRotation angle in radians.
Returns
Y Rotation matrix.

◆ createZRotationInDegrees()

static Matrix4x4 createZRotationInDegrees ( float  angleInDegrees)
static

Creates a Z rotation matrix.


Parameters
angleInDegreesRotation angle in degrees.
Returns
Z Rotation matrix.

◆ createZRotationInRadians()

static Matrix4x4 createZRotationInRadians ( float  angleInRadians)
static

Creates a Z rotation matrix.


Parameters
angleInRadiansRotation angle in radians.
Returns
Z Rotation matrix.

◆ extractSRT()

static boolean extractSRT ( Matrix4x4  matrix,
Vector3  scale,
Vector3  rotationInRadians,
Vector3  translation 
)
static

Extracts from a matrix the scale, rotation, and translation information.


Parameters
matrixInput matrix.
scaleScale vector.
rotationInRadiansRotation vector, rotation angle in radians.
translationTranslation vector.

◆ get()

float get ( long  index)

Returns individual matrix element value at index.


Returns
The matrix element value at index.

◆ getDeterminant()

static float getDeterminant ( Matrix4x4  matrix)
static

Calculates the determinant of a matrix.


Parameters
matrixThe matrix for which you want to return the determinant.
Returns
Determinant of the matrix.

◆ getDeterminant3x3()

static float getDeterminant3x3 ( Matrix4x4  matrix)
static

Calculates the determinant of the 3x3 part of a matrix.


Parameters
matrixThe matrix for which you want to return the determinant.
Returns
Determinant of the matrix.

◆ getRotationAngle()

OptionalVector3 getRotationAngle ( )

Calculates Euler rotation angles of the matrix.


Kanzi Engine represents Euler angles as Tait-Bryan angles where the rotations are applied in the order x, y and z.

Returns
Euler angles in radians, or nullopt if the matrix is not decomposable.

◆ getTrace()

static float getTrace ( Matrix4x4  matrix)
static

Calculates the trace of a matrix.


Returns
Trace of the matrix.

◆ getTranslation()

Vector3 getTranslation ( )

Get translation.


Returns
Translation vector.

◆ getTranslationX()

float getTranslationX ( )

Get translation on X axis.


Returns
Translation X component.

◆ getTranslationY()

float getTranslationY ( )

Get translation on Y axis.


Returns
Translation Y component.

◆ getTranslationZ()

float getTranslationZ ( )

Get translation on Z axis.


Returns
Translation Z component.

◆ inverse()

Matrix4x4 inverse ( )

Applies an inversion to a matrix.

Returns
Inverted matrix if the input matrix is invertible, null otherwise.

◆ inverseAffine()

Matrix4x4 inverseAffine ( )

Applies an inversion to an affine matrix.

Returns
Inverted matrix if the input matrix is invertible, null otherwise.

◆ inverseOrthogonal()

Matrix4x4 inverseOrthogonal ( )

Applies an inversion to an orthogonal affine matrix.

Returns
Inverted matrix if the input matrix is invertible, null otherwise.

◆ isTranslationOnly()

static boolean isTranslationOnly ( Matrix4x4  matrix)
static

Returns whether a matrix is translation-only.


Parameters
matrixInput matrix.
Returns
If the input matrix is translation-only, true, otherwise false.

◆ matrixMultiplyVectorBy3x3()

static Vector3 matrixMultiplyVectorBy3x3 ( Matrix4x4  matrix,
Vector3  vector 
)
static

Multiplies a 3D vector with the top 3x3 part of a given matrix.


Parameters
matrixThe matrix that you want to multiply with a 3D vector.
vectorThe 3D vector that you want to multiply with a matrix.
Returns
The result of the multiplication.

◆ multiply() [1/4]

Vector3 multiply ( Vector3  vector)

Multiply a 3-component vector with this matrix.


Parameters
vectorA Vector3.
Returns
Result of the multiplication.

◆ multiply() [2/4]

Vector4 multiply ( Vector4  vector)

Multiply a 4-component vector with this matrix.


Parameters
vectorA Vector4.
Returns
Result of the multiplication.

◆ multiply() [3/4]

Matrix4x4 multiply ( Matrix4x4  m)

Modifies this matrix by multiplying it with another matrix.


Parameters
mAnother matrix.
Returns
This matrix.

◆ multiply() [4/4]

static Matrix4x4 multiply ( Matrix4x4  lhs,
Matrix4x4  rhs 
)
static

Multiplies two matrices and returns the product.

Parameters
lhsFirst matrix, left hand side.
rhsSecond matrix, right hand side.
Returns
The result matrix.

◆ multiplyAffine()

static Matrix4x4 multiplyAffine ( Matrix4x4  left,
Matrix4x4  right 
)
static

Multiplies two affine matrices and returns the product.


Parameters
leftLeft hand side matrix.
rightRight hand side matrix.
Returns
The result matrix.

◆ normalizeBase()

static Matrix4x4 normalizeBase ( Matrix4x4  matrix)
static

Orthonormalizes base vectors of the given matrix.

The result is in out_matrix.
The orthonormalization is done using the Gram-Schmidt process. Z axis is kept still, then Y is handled, then X.
This function can be used to prevent value drift.

Parameters
matrixInput matrix.
Returns
The orthonormalized matrix.

◆ orthonormalizeBase()

static Matrix4x4 orthonormalizeBase ( Matrix4x4  matrix)
static

Orthonormalizes base vectors of the given matrix.

The result is in out_matrix.
The orthonormalization is done using the Gram-Schmidt process. Z axis is kept still, then Y is handled, then X.
You can use this function to prevent value drift.

Parameters
matrixInput matrix.
Returns
The orthonormalized matrix.

◆ scale()

void scale ( Vector3  scale)

Scales this matrix.


Parameters
scaleScaling vector.

◆ scaleUniform()

void scaleUniform ( float  scale)

Scales this matrix.


Parameters
scaleUniform scaling value.

◆ set()

void set ( long  index,
float  v 
)

Sets the individual matrix element at index to value.


Parameters
indexMatrix element index to set.

◆ setTranslation()

void setTranslation ( Vector3  translation)

Set translation.


Parameters
translationTranslation vector.

◆ setTranslationX()

void setTranslationX ( float  translationX)

Set translation on X axis.


Parameters
translationXTranslation X component.

◆ setTranslationY()

void setTranslationY ( float  translationY)

Set translation on Y axis.


Parameters
translationYTranslation Y component.

◆ setTranslationZ()

void setTranslationZ ( float  translationZ)

Set translation on Z axis.


Parameters
translationZTranslation Y component.

◆ setXAxis()

void setXAxis ( Vector3  v)

Set X axis.


Parameters
vX axis vector.

◆ setYAxis()

void setYAxis ( Vector3  v)

Set Y axis.


Parameters
vY axis vector.

◆ setZAxis()

void setZAxis ( Vector3  v)

Set Z axis.


Parameters
vZ axis vector.

◆ subtract() [1/2]

Matrix4x4 subtract ( Matrix4x4  v)

Modifies this matrix by subtracting another matrix from this matrix.


Parameters
vAnother matrix.
Returns
This matrix.

◆ subtract() [2/2]

static Matrix4x4 subtract ( Matrix4x4  lhs,
Matrix4x4  rhs 
)
static

Creates a new matrix by subtracting an existing matrix from another one.

Parameters
lhsFirst matrix, left hand side.
rhsSecond matrix, right hand side.
Returns
A new matrix resulting from the subtraction of the right hand side from the left hand side.

◆ translate()

void translate ( Vector3  translate)

Translates this matrix.


Parameters
translateTranslation vector.

◆ transposed()

Matrix4x4 transposed ( )

Applies a transpose to a matrix.


Returns
Newly constructed transpose matrix.