Murl Engine Lua Addon API  Version 1.0 beta
Murl.Math.Matrix

A 4x4 matrix class.


Table members

Enumerations


Component

Enumeration of the components raw data index. The components can be accessed by using the [] operator.

Murl.Math.Matrix.XX
Murl.Math.Matrix.YX
Murl.Math.Matrix.ZX
Murl.Math.Matrix.WX
Murl.Math.Matrix.XY
Murl.Math.Matrix.YY
Murl.Math.Matrix.ZY
Murl.Math.Matrix.WY
Murl.Math.Matrix.XZ
Murl.Math.Matrix.YZ
Murl.Math.Matrix.ZZ
Murl.Math.Matrix.WZ
Murl.Math.Matrix.XW
Murl.Math.Matrix.YW
Murl.Math.Matrix.ZW
Murl.Math.Matrix.WW
Murl.Math.Matrix.NUM_COMPONENTSThe number of components.

ComponentMask

Enumeration of the components' bit masks

Murl.Math.Matrix.MASK_NONENo component
Murl.Math.Matrix.MASK_XXXX component mask
Murl.Math.Matrix.MASK_YXYX component mask
Murl.Math.Matrix.MASK_ZXZX component mask
Murl.Math.Matrix.MASK_WXWX component mask
Murl.Math.Matrix.MASK_XYXY component mask
Murl.Math.Matrix.MASK_YYYY component mask
Murl.Math.Matrix.MASK_ZYZY component mask
Murl.Math.Matrix.MASK_WYWY component mask
Murl.Math.Matrix.MASK_XZXZ component mask
Murl.Math.Matrix.MASK_YZYZ component mask
Murl.Math.Matrix.MASK_ZZZZ component mask
Murl.Math.Matrix.MASK_WZWZ component mask
Murl.Math.Matrix.MASK_XWXW component mask
Murl.Math.Matrix.MASK_YWYW component mask
Murl.Math.Matrix.MASK_ZWZW component mask
Murl.Math.Matrix.MASK_WWWW component mask
Murl.Math.Matrix.MASK_ALLAll components

PredefinedType

Enumeration of the predefined initialization types for constructing a Matrix(PredefinedType type).

Murl.Math.Matrix.UNINITIALIZEDCreate an uninitialized instance.
Murl.Math.Matrix.ZEROInitialize with zero.
Murl.Math.Matrix.IDENTITYInitialize with the identity matrix.

HintFlags

Enumeration of hint flags. Hints are used internally to optimize several operations.

Murl.Math.Matrix.FLAG_TRANSLATIONThe matrix contains translation components.
Murl.Math.Matrix.FLAG_ROTATIONThe matrix contains rotation components.
Murl.Math.Matrix.FLAG_SCALEThe matrix contains scale components.
Murl.Math.Matrix.FLAG_ARBITRARYThe matrix contains arbitrary components.
Murl.Math.Matrix.FLAG_NO_HINTSThe matrix has no component hints.


Functions


Murl.Math.Matrix.new()

The default constructor, creating an identity matrix. Hints are disabled by default.

Murl.Math.Matrix new()

Returns
Murl.Math.Matrix

Murl.Math.Matrix.new(type)

Constructor to create a matrix from a predefined type. Hints are disabled by default.

Murl.Math.Matrix new(Murl.Math.Matrix.PredefinedType type)

Parameters
typeThe predefined type.
Returns
Murl.Math.Matrix

Murl.Math.Matrix.LookAt(center, target, up)

Create a look-at matrix from a given center point, target point and up vector.

Murl.Math.Matrix LookAt(Murl.Math.Vector center, Murl.Math.Vector target, Murl.Math.Vector up)

Parameters
centerThe center point position vector.
targetThe target point position vector.
upThe up direction vector.
Returns
Murl.Math.Matrix The calculated matrix.


Methods


GetHints()

Get the hint flags.

Integer GetHints()

Returns
Integer The bit-mask of hints.

SetHints(mask)

Set the hint flags.

SetHints(Integer mask)

Parameters
maskThe bit-mask of hints to set.

ClearHints(mask)

Clear hint flags.

ClearHints(Integer mask)

Parameters
maskThe bit-mask of hints to clear.

EnableHints(autoDetect)

Enable hints. Enabling hints requires good knowlede of the entire Matrix class e.g. several setter methods do not consider hints.

EnableHints(Boolean autoDetect)

Parameters
autoDetectEvaluate the correct hints if true.

DisableHints()

Disable hints.

DisableHints()


Clear()

Clear all components of the matrix instance. Set the component data array to zero.

Clear()


SetIdentity()

Load the identity matrix to the current instance.

SetIdentity()


SetIdentityRotation()

Load the identity matrix to the upper 3x3 matrix

SetIdentityRotation()


Set(m)

Copy the content of a source matrix to the matrix instance.

Set(Murl.Math.Matrix m)

Parameters
mThe matrix to copy from.

SetTranslationComponent(x, y, z)

Set the translation component to given values.

SetTranslationComponent(Number x, Number y, Number z)

Parameters
xThe X translation component.
yThe Y translation component.
zThe Z translation component.

SetTranslationComponent(v)

Set the translation component to a given vector.

SetTranslationComponent(Murl.Math.Vector v)

Parameters
vThe vector to set the translation component.

SetTranslationComponentX(x)

Set the translation X component.

SetTranslationComponentX(Number x)

Parameters
xThe X translation component.

SetTranslationComponentY(y)

Set the translation Y component.

SetTranslationComponentY(Number y)

Parameters
yThe Y translation component.

SetTranslationComponentZ(z)

Set the translation Z component.

SetTranslationComponentZ(Number z)

Parameters
zThe Z translation component.

GetTranslationComponent()

Get the translation component vector.

Murl.Math.Vector GetTranslationComponent()

Returns
Murl.Math.Vector The translation component vector.

GetTranslationComponentX()

Get the translation component's X value.

Number GetTranslationComponentX()

Returns
Number The X value.

GetTranslationComponentY()

Get the translation component's Y value.

Number GetTranslationComponentY()

Returns
Number The Y value.

GetTranslationComponentZ()

Get the translation component's Z value.

Number GetTranslationComponentZ()

Returns
Number The Z value.

SetScalingComponent(x, y, z)

Set the scaling component using three distinct values. This method only sets the upper 3 diagonal elements of the matrix, so it should only be applied to matrices without rotation.

SetScalingComponent(Number x, Number y, Number z)

Parameters
xThe X scaling factor.
yThe Y scaling factor.
zThe Z scaling factor.

SetScalingComponent(v)

Set the scaling component using a vector. This method only sets the upper 3 diagonal elements of the matrix, so it should only be applied to matrices without rotation.

SetScalingComponent(Murl.Math.Vector v)

Parameters
vThe vector containing X, Y and Z scaling components.

GetScalingComponent()

Get a vector containing the X, Y and Z scaling components of the matrix.

Murl.Math.Vector GetScalingComponent()

Returns
Murl.Math.Vector The scaling components.

GetScalingComponentX()

Get the X scale value of the matrix.

Number GetScalingComponentX()

Returns
Number The X scale value.

GetScalingComponentY()

Get the Y scale value of the matrix.

Number GetScalingComponentY()

Returns
Number The Y scale value.

GetScalingComponentZ()

Get the Z scale value of the matrix.

Number GetScalingComponentZ()

Returns
Number The Z scale value.

SetRotationComponent(angleX, angleY, angleZ)

Set the rotation component by euler angles. The default axis rotation order is IEnums::ROTATION_ORDER_ZYX.

SetRotationComponent(Number angleX, Number angleY, Number angleZ)

Parameters
angleXThe x-axis angle in radiants.
angleYThe y-axis angle in radiants.
angleZThe z-axis angle in radiants.

SetRotationComponent(angle, axis)

Set the rotation component by an angle and vector.

SetRotationComponent(Number angle, Murl.Math.Vector axis)

Parameters
angleThe angle of the rotation in radiants.
axisThe vector of the rotation.

SetRotationComponent(rotationMatrix)

Set the rotation component by a rotation matrix.

SetRotationComponent(Murl.Math.Matrix rotationMatrix)

Parameters
rotationMatrixThe rotation matrix.

SetRotationComponent(q)

Set the rotation component by a quaternion.

SetRotationComponent(Murl.Math.Quaternion q)

Parameters
qThe quaternion.

SetRotationComponent(axisAngle)

Set the rotation component by a vector.

SetRotationComponent(Murl.Math.Vector axisAngle)

Parameters
axisAngleThe vector of the rotation including the angle in w component in radiants.

SetRotationComponentAxisAngle(angle, ax, ay, az)

Set the rotation component by an angle and vector components.

SetRotationComponentAxisAngle(Number angle, Number ax, Number ay, Number az)

Parameters
angleThe angle of the rotation in radiants.
axThe x-component of the rotation vector.
ayThe y-component of the rotation vector.
azThe z-component of the rotation vector.

SetRotationComponentXYZ(angleX, angleY, angleZ, rotationOrder)

Set the rotation component by euler angles with a given rotation order.

SetRotationComponentXYZ(Number angleX, Number angleY, Number angleZ, Murl.IEnums.RotationOrder rotationOrder)

Parameters
angleXThe x-axis angle in radiants.
angleYThe y-axis angle in radiants.
angleZThe z-axis angle in radiants.
rotationOrderThe axis rotation order.

SetRotationComponentXYZ(angles, rotationOrder)

Set the rotation component by euler angles with a given rotation order.

SetRotationComponentXYZ(Murl.Math.Vector angles, Murl.IEnums.RotationOrder rotationOrder)

Parameters
anglesA vector containing the X, Y and Z angles in radiants.
rotationOrderThe axis rotation order.

SetRotationComponentX(angleX)

Set the rotation component of the transformation matrix to only rotate around the X axis. This method directly overwrites the upper 3x3 matrix of the internal transformation by calculating and applying a rotation around the unit X axis. The angle value must be given in radians. A positive value result in a clockwise rotation.

SetRotationComponentX(Number angleX)

Parameters
angleXThe x-axis angle in radiants.

SetRotationComponentY(angleY)

Set the rotation component of the transformation matrix to only rotate around the Y axis. This method directly overwrites the upper 3x3 matrix of the internal transformation by calculating and applying a rotation around the unit Y axis. The angle value must be given in radians. A positive value result in a clockwise rotation.

SetRotationComponentY(Number angleY)

Parameters
angleYThe y-axis angle in radiants.

SetRotationComponentZ(angleZ)

Set the rotation component of the transformation matrix to only rotate around the Z axis. This method directly overwrites the upper 3x3 matrix of the internal transformation by calculating and applying a rotation around the unit Z axis. The angle value must be given in radians. A positive value result in a clockwise rotation.

SetRotationComponentZ(Number angleZ)

Parameters
angleZThe z-axis angle in radiants.

GetEulerRotation()

Get the euler rotation angles. Extract the euer rotation angles based on https://d3cw3dd2w32x2b.cloudfront.net/wp-content/uploads/2012/07/euler-angles.pdf

Murl.Math.Vector GetEulerRotation()

Returns
Murl.Math.Vector The euler rotation angles in radiants. The vector members x, y and z corresponds to the axis angles.

GetRotationAndScalingComponent()

Extract the rotation and scaling component of the matrix.

Murl.Math.Matrix GetRotationAndScalingComponent()

Returns
Murl.Math.Matrix A matrix containing only scaling and rotation.

GetColumnVector(columnIndex)

Get the vector of a specified column.

Murl.Math.Vector GetColumnVector(Integer columnIndex)

Parameters
columnIndexThe column index in range [0 .. 3].
Returns
Murl.Math.Vector The vector of the colum at the specified index.

SetColumnVector(columnIndex, vec)

Set a specified column by a vector. Hints are not considered.

SetColumnVector(Integer columnIndex, Murl.Math.Vector vec)

Parameters
columnIndexThe column index in range [0 .. 3].
vecThe vector to set the colum at the specified index.

GetRowVector(rowIndex)

Get the vector of a specified row.

Murl.Math.Vector GetRowVector(Integer rowIndex)

Parameters
rowIndexThe row index in range [0 .. 3].
Returns
Murl.Math.Vector The vector of the row at the specified index.

SetRowVector(rowIndex, vec)

Set a specified row by a vector. Hints are not considered.

SetRowVector(Integer rowIndex, Murl.Math.Vector vec)

Parameters
rowIndexThe row index in range [0 .. 3].
vecThe vector to set the row at the specified index.

MultiplySelf(m)

In-place matrix-matrix multiplication.

MultiplySelf(Murl.Math.Matrix m)

Parameters
mThe matrix to multiply.

MultiplySelfReverse(m)

In-place reverse matrix-matrix multiplication.

MultiplySelfReverse(Murl.Math.Matrix m)

Parameters
mThe matrix to multiply.

TransposeSelf()

In-place transpose of the matrix.

TransposeSelf()


InvertSelf()

In-place inversion of the matrix.

InvertSelf()


Transform(v)

Transform (multiply) a vector by the matrix.

Murl.Math.Vector Transform(Murl.Math.Vector v)

Parameters
vThe vector to mulitply.
Returns
Murl.Math.Vector The multiplied vector.

Rotate(v)

Rotate a vector by the matrix.

Murl.Math.Vector Rotate(Murl.Math.Vector v)

Parameters
vThe vector to rotate.
Returns
Murl.Math.Vector The rotated vector.

Translate(v)

Translate a vector by the matrix (add the translation component).

Murl.Math.Vector Translate(Murl.Math.Vector v)

Parameters
vThe vector to translate.
Returns
Murl.Math.Vector The translated vector.

Multiply(m)

Multiply a matrix by the matrix.

Murl.Math.Matrix Multiply(Murl.Math.Matrix m)

Parameters
mThe matrix to mulitply.
Returns
Murl.Math.Matrix The multiplied matrix.

Multiply(v)

Multiply a vector by the matrix.

Murl.Math.Vector Multiply(Murl.Math.Vector v)

Parameters
vThe vector to mulitply.
Returns
Murl.Math.Vector The multiplied vector.

Transpose()

Get the transposed matrix.

Murl.Math.Matrix Transpose()

Returns
Murl.Math.Matrix The transposed matrix.

InvertTransRot()

Fast inversion of a rotation/translation matrix. This method can be used to quickly invert a given matrix that is only made up from rotation and translation operations. If the matrix also contains any scaling operations, use InvertTransRotScl() instead. For general 4x4 matrices, use Invert().

Murl.Math.Matrix InvertTransRot()

Returns
Murl.Math.Matrix The inverted rotation/translation matrix.

InvertTransRotScl()

Fast inversion of a rotation/translation/scaling matrix. This method can be used to quickly invert a given matrix that is only made up from rotation, translation and scaling operations. If only rotation and translation is present, use InvertTransRot(). For general 4x4 matrices, use Invert() instead.

Murl.Math.Matrix InvertTransRotScl()

Returns
Murl.Math.Matrix The inverted rotation/translation/scaling matrix.

Invert()

Matrix inversion. This method can be used to calculate the inverse of a general 4x4 matrix. In case the matrix is only made up from rotation and translation operations, it is possible to use InvertTransRot() instead. If it also contains additional scaling operations, InvertTransRotScl() can be used; both alternative methods show better overall performance.

Murl.Math.Matrix Invert()

Returns
Murl.Math.Matrix The inverted matrix.

Solve(v)

Solve the matrix by a vector.

Murl.Math.Vector Solve(Murl.Math.Vector v)

Parameters
vThe vector to solve.
Returns
Murl.Math.Vector The solved vector.

SetElementAt(row, col, value)

Set a component element. Hints are not considered.

SetElementAt(Integer row, Integer col, Number value)

Parameters
rowThe row in range [0 .. 3].
colThe column in range [0 .. 3].
valueThe value to set.

GetElementAt(row, col)

Get a writeable reference to a component element.

Number GetElementAt(Integer row, Integer col)

Parameters
rowThe row in range [0 .. 3].
colThe column in range [0 .. 3].
Returns
Number The value at the given position.

SetElement(element, value)

Set a component element. Hints are not considered.

SetElement(Murl.Math.Matrix.Component element, Number value)

Parameters
elementThe element
valueThe value to set.

GetElement(element)

Get a writeable reference to a component element.

Number GetElement(Murl.Math.Matrix.Component element)

Parameters
elementThe element's component.
Returns
Number The value at the given position.

SetXX(value)

Set the XX component. Hints are not considered.

SetXX(Number value)

Parameters
valueThe XX component value to set.

SetXY(value)

Set the XY component. Hints are not considered.

SetXY(Number value)

Parameters
valueThe XY component value to set.

SetXZ(value)

Set the XZ component. Hints are not considered.

SetXZ(Number value)

Parameters
valueThe XZ component value to set.

SetXW(value)

Set the XW component. Hints are not considered.

SetXW(Number value)

Parameters
valueThe XW component value to set.

SetYX(value)

Set the YX component. Hints are not considered.

SetYX(Number value)

Parameters
valueThe YX component value to set.

SetYY(value)

Set the YY component. Hints are not considered.

SetYY(Number value)

Parameters
valueThe YY component value to set.

SetYZ(value)

Set the YZ component. Hints are not considered.

SetYZ(Number value)

Parameters
valueThe YZ component value to set.

SetYW(value)

Set the YW component. Hints are not considered.

SetYW(Number value)

Parameters
valueThe YW component value to set.

SetZX(value)

Set the ZX component. Hints are not considered.

SetZX(Number value)

Parameters
valueThe ZX component value to set.

SetZY(value)

Set the ZY component. Hints are not considered.

SetZY(Number value)

Parameters
valueThe ZY component value to set.

SetZZ(value)

Set the ZZ component. Hints are not considered.

SetZZ(Number value)

Parameters
valueThe ZZ component value to set.

SetZW(value)

Set the ZW component. Hints are not considered.

SetZW(Number value)

Parameters
valueThe ZW component value to set.

SetWX(value)

Set the WX component. Hints are not considered.

SetWX(Number value)

Parameters
valueThe WX component value to set.

SetWY(value)

Set the WY component. Hints are not considered.

SetWY(Number value)

Parameters
valueThe WY component value to set.

SetWZ(value)

Set the WZ component. Hints are not considered.

SetWZ(Number value)

Parameters
valueThe WZ component value to set.

SetWW(value)

Set the WW component. Hints are not considered.

SetWW(Number value)

Parameters
valueThe WW component value to set.

GetXX()

Get the XX component.

Number GetXX()

Returns
Number The XX component value.

GetXY()

Get the XY component.

Number GetXY()

Returns
Number The XY component value.

GetXZ()

Get the XZ component.

Number GetXZ()

Returns
Number The XZ component value.

GetXW()

Get the XW component.

Number GetXW()

Returns
Number The XW component value.

GetYX()

Get the YX component.

Number GetYX()

Returns
Number The YX component value.

GetYY()

Get the YY component.

Number GetYY()

Returns
Number The YY component value.

GetYZ()

Get the YZ component.

Number GetYZ()

Returns
Number The YZ component value.

GetYW()

Get the YW component.

Number GetYW()

Returns
Number The YW component value.

GetZX()

Get the ZX component.

Number GetZX()

Returns
Number The ZX component value.

GetZY()

Get the ZY component.

Number GetZY()

Returns
Number The ZY component value.

GetZZ()

Get the ZZ component.

Number GetZZ()

Returns
Number The ZZ component value.

GetZW()

Get the ZW component.

Number GetZW()

Returns
Number The ZW component value.

GetWX()

Get the WX component.

Number GetWX()

Returns
Number The WX component value.

GetWY()

Get the WY component.

Number GetWY()

Returns
Number The WY component value.

GetWZ()

Get the WZ component.

Number GetWZ()

Returns
Number The WZ component value.

GetWW()

Get the WW component.

Number GetWW()

Returns
Number The WW component value.

IsEqual(m)

Check if the matrix is equal to a given matrix. Compares all values within the default epsilon range Limits::Epsilon().

Boolean IsEqual(Murl.Math.Matrix m)

Parameters
mThe matrix to compare.
Returns
Boolean true if all components are exactly the same.

IsEqual(m, epsilon)

Check if the matrix is equal to a given matrix. Compares all values within a given epsilon range.

Boolean IsEqual(Murl.Math.Matrix m, Number epsilon)

Parameters
mThe matrix to compare.
epsilonThe epsilon to compare.
Returns
Boolean true if equal.

IsIdentity()

Check if the matrix is equal to the identity matrix. Performs a test without an epsilon range.

Boolean IsIdentity()

Returns
Boolean true if equal.

IsIdentity(epsilon)

Check if the matrix is equal to the identity matrix. Compares all values within a given epsilon range.

Boolean IsIdentity(Number epsilon)

Parameters
epsilonThe epsilon to compare.
Returns
Boolean true if equal.

ToString()

Get the string representation of the object.

String ToString()

Returns
String The string representation of the object.

GetCount()

Get the number of elements in the object.

Integer GetCount()

Returns
Integer The number of elements in the object.


Metamethods


The length operator

The length operator is denoted by the unary prefix operator #.

Returns
GetCount()

The tostring operator

Converts the object content to a string in a reasonable format.

Returns
ToString()

The array subscript operator.

Get a writeable reference to a component element.

Parameters
indexThe component index, see enum Component.
Returns
Number = Murl.Math.Matrix [Integer index]
Assign
Murl.Math.Matrix [Integer index] = Number

The multiplication operator.

Matrix-matrix multiplication operator.

Returns
Murl.Math.Matrix = Murl.Math.Matrix * Murl.Math.Matrix

The multiplication operator.

Matrix-vector multiplication operator.

Returns
Murl.Math.Vector = Murl.Math.Matrix * Murl.Math.Vector

The equal to operator.

Equal to comparison operator. Performs a test without an epsilon range, which can be used for detecting changes i.e. DoubleBuffer<Matrix> class. To compare within an epsilon range use Matrix::IsEqual().

Returns
Boolean = Murl.Math.Matrix == Murl.Math.Matrix


Instance Members


mXX

Returns
Number

mYX

Returns
Number

mZX

Returns
Number

mWX

Returns
Number

mXY

Returns
Number

mYY

Returns
Number

mZY

Returns
Number

mWY

Returns
Number

mXZ

Returns
Number

mYZ

Returns
Number

mZZ

Returns
Number

mWZ

Returns
Number

mXW

Returns
Number

mYW

Returns
Number

mZW

Returns
Number

mWW

Returns
Number