VMatrix
A 4x4 transformation matrix object ( rotation, scale and translation ) in Source engine layout.
Operators:
matrix * matrix- matrix product,a * btransforms bybfirst, then bya.matrix * vec3- transforms the point ( with translation ), returns a newVector3.matrix + matrix,matrix - matrix- component-wise.
There is no division operator, use getInverse explicitly, it can fail for singular matrices.
Constructor
VMatrix(...: number?): VMatrixFields
| Name | Type | Description |
|---|---|---|
m11 | number | Row 1, column 1 ( forward X ). |
m12 | number | Row 1, column 2 ( left X ). |
m13 | number | Row 1, column 3 ( up X ). |
m14 | number | Row 1, column 4 ( translation X ). |
m21 | number | Row 2, column 1 ( forward Y ). |
m22 | number | Row 2, column 2 ( left Y ). |
m23 | number | Row 2, column 3 ( up Y ). |
m24 | number | Row 2, column 4 ( translation Y ). |
m31 | number | Row 3, column 1 ( forward Z ). |
m32 | number | Row 3, column 2 ( left Z ). |
m33 | number | Row 3, column 3 ( up Z ). |
m34 | number | Row 3, column 4 ( translation Z ). |
m41 | number | Row 4, column 1, 0 for affine transforms. |
m42 | number | Row 4, column 2, 0 for affine transforms. |
m43 | number | Row 4, column 3, 0 for affine transforms. |
m44 | number | Row 4, column 4, 1 for affine transforms. |
Operators
Static functions
clone | Creates a new independent copy of the matrix. |
copy | Creates a new independent copy of the matrix. |
fromAngle3 | Creates a new rotation matrix from the angle and the optional translation. |
fromQuaternion | Creates a new rotation matrix from the quaternion and the optional translation. |
invert | Inverts the matrix ( full 4x4 inverse ). |
invertTR | Inverts the matrix, assuming it only contains rotation and translation ( no scale ). |
setUnpacked | Sets all 16 values of the matrix ( row by row ). |
transformPoint | Transforms the point by the matrix ( rotation, scale and translation ), same as matrix * vec3. |
transpose | Transposes the matrix ( swaps rows and columns ). |
unpack | Returns all 16 values of the matrix ( row by row ). |
unpackAngles | Returns the unpacked Euler angles ( pitch, yaw, roll ) of the matrix in degrees. |
#VMatrix.clone
function VMatrix.clone(self: VMatrix): VMatrix
Creates a new independent copy of the matrix.
| Name | Type | Description |
|---|---|---|
self | VMatrix | The matrix. |
| Type | Name | Description |
|---|---|---|
VMatrix | copy | The new matrix. |
#VMatrix.copy
function VMatrix.copy(self: VMatrix): VMatrix
Creates a new independent copy of the matrix.
| Name | Type | Description |
|---|---|---|
self | VMatrix | The matrix. |
| Type | Name | Description |
|---|---|---|
VMatrix | copy | The new matrix. |
#VMatrix.fromAngle3
function VMatrix.fromAngle3(angle: Angle3, translation?: Vector3): VMatrix
Creates a new rotation matrix from the angle and the optional translation.
Same as AngleMatrix in Source engine.
| Name | Type | Description |
|---|---|---|
angle | Angle3 | The angle. |
translationoptional | Vector3 | The translation, defaults to ( 0, 0, 0 ). |
| Type | Name | Description |
|---|---|---|
VMatrix | matrix | The new matrix. |
#VMatrix.fromQuaternion
function VMatrix.fromQuaternion(quaternion: Quaternion, translation?: Vector3): VMatrix
Creates a new rotation matrix from the quaternion and the optional translation.
Same as QuaternionMatrix in Source engine, works with non-unit quaternions.
| Name | Type | Description |
|---|---|---|
quaternion | Quaternion | The quaternion. |
translationoptional | Vector3 | The translation, defaults to ( 0, 0, 0 ). |
| Type | Name | Description |
|---|---|---|
VMatrix | matrix | The new matrix. |
#VMatrix.invert
function VMatrix.invert(self: VMatrix): boolean
Inverts the matrix ( full 4x4 inverse ).
Same as VMatrix:Invert in Garry's Mod, the matrix stays unchanged if it can't be inverted.
Use invertTR for rotation + translation matrices, it is faster and always succeeds.
| Name | Type | Description |
|---|---|---|
self | VMatrix | The matrix. |
| Type | Name | Description |
|---|---|---|
boolean | success | true if the matrix was inverted, false if the matrix is singular. |
#VMatrix.invertTR
function VMatrix.invertTR(self: VMatrix): VMatrix
Inverts the matrix, assuming it only contains rotation and translation ( no scale ).
Same as VMatrix:InvertTR in Garry's Mod, much faster than invert, but the result is wrong for scaled or skewed matrices. The fourth row is reset to 0 0 0 1.
| Name | Type | Description |
|---|---|---|
self | VMatrix | The matrix. |
| Type | Name | Description |
|---|---|---|
VMatrix | matrix | The same matrix, inverted. |
#VMatrix.setUnpacked
function VMatrix.setUnpacked(self: any, m11: any, m12: any, m13: any, m14: any, m21: any, m22: any, m23: any, m24: any, m31: any, m32: any, m33: any, m34: any, m41: any, m42: any, m43: any, m44: any): VMatrix
Sets all 16 values of the matrix ( row by row ).
| Name | Type | Description |
|---|---|---|
self | any | |
m11 | any | |
m12 | any | |
m13 | any | |
m14 | any | |
m21 | any | |
m22 | any | |
m23 | any | |
m24 | any | |
m31 | any | |
m32 | any | |
m33 | any | |
m34 | any | |
m41 | any | |
m42 | any | |
m43 | any | |
m44 | any |
| Type | Name | Description |
|---|---|---|
VMatrix | matrix | The same matrix. |
#VMatrix.transformPoint
function VMatrix.transformPoint(self: VMatrix, vector: Vector3): Vector3
Transforms the point by the matrix ( rotation, scale and translation ), same as matrix * vec3.
The fourth row is ignored ( no perspective divide ).
| Type | Name | Description |
|---|---|---|
Vector3 | vec3 | The new transformed point. |
#VMatrix.transpose
function VMatrix.transpose(self: VMatrix): VMatrix
Transposes the matrix ( swaps rows and columns ).
For pure rotation matrices the transpose is the inverse.
| Name | Type | Description |
|---|---|---|
self | VMatrix | The matrix. |
| Type | Name | Description |
|---|---|---|
VMatrix | matrix | The same matrix, transposed. |
#VMatrix.unpack
function VMatrix.unpack(self: any): number
Returns all 16 values of the matrix ( row by row ).
| Name | Type | Description |
|---|---|---|
self | any |
| Type | Name | Description |
|---|---|---|
number | m11, number m12, number m13, number m14, number m21, number m22, number m23, number m24, number m31, number m32, number m33, number m34, number m41, number m42, number m43, number m44 |
#VMatrix.unpackAngles
function VMatrix.unpackAngles(self: VMatrix): number, number, number
Returns the unpacked Euler angles ( pitch, yaw, roll ) of the matrix in degrees.
Same as MatrixAngles in Source engine, allocation free alternative to getAngles.
Assumes the matrix has no scale, at pitch ±90 ( gimbal lock ) roll is always 0.
| Name | Type | Description |
|---|---|---|
self | VMatrix | The matrix. |
| Type | Name | Description |
|---|---|---|
number | pitch | The pitch in degrees. |
number | yaw | The yaw in degrees. |
number | roll | The roll in degrees. |
Methods
getAngles | Returns the rotation of the matrix as an angle. |
getDeterminant | Calculates the determinant of the matrix. |
getField | Returns the value of the matrix at the given row and column. |
getForward | Returns the forward direction of the matrix ( first column ). |
getInverse | Returns the inverse of the matrix ( full 4x4 inverse ). |
getInverseTR | Returns the inverse of the matrix, assuming it only contains rotation and translation ( no scale ). |
getLeft | Returns the left direction of the matrix ( second column ). |
getRight | Returns the right direction of the matrix ( negated second column ). |
getScale | Returns the scale of the matrix ( lengths of the forward, left and up columns ). |
getTranslation | Returns the translation of the matrix ( fourth column ). |
getTransposed | Returns a transposed copy of the matrix. |
getUp | Returns the up direction of the matrix ( third column ). |
identity | Sets the matrix to identity ( no rotation, no translation, scale 1 ). |
isIdentity | Checks if the matrix is exactly identity. |
isNear | Checks if the matrix is equal to the given matrix with the given tolerance. |
isRotationMatrix | Checks if the matrix is a rotation matrix ( forward, left and up columns are normalized and perpendicular ). |
isZero | Checks if all values of the matrix are exactly zero. |
lerp | Interpolates the matrix to the target matrix. |
mul | Multiplies the matrix by another matrix ( self = self * matrix ). |
premul | Multiplies another matrix by the matrix ( self = matrix * self ). |
rotate | Rotates the matrix by the given angle in local space ( self = self * R ). |
scale | Scales the matrix by the given vector in local space ( self = self * S ). |
scaleTranslation | Scales the translation of the matrix by the given number. |
set | Copies the values of another matrix into this matrix. |
setAngles | Sets the rotation of the matrix from the angle, translation and the fourth row stay unchanged. |
setField | Sets the value of the matrix at the given row and column. |
setForward | Sets the forward direction of the matrix ( first column ). |
setLeft | Sets the left direction of the matrix ( second column ). |
setRight | Sets the right direction of the matrix ( stored negated in the second column ). |
setScale | Sets the scale of the matrix while preserving the rotation and translation. |
setTranslation | Sets the translation of the matrix ( fourth column ), rotation and scale stay unchanged. |
setUp | Sets the up direction of the matrix ( third column ). |
toQuaternion | Returns the rotation of the matrix as a quaternion, scale and translation are ignored. |
transformDirection | Transforms the direction by the matrix ( rotation and scale, without translation ). |
translate | Translates the matrix by the given vector in local space ( self = self * T ). |
zero | Sets all values of the matrix to zero. |
#VMatrix:getAngles
function VMatrix:getAngles(): Angle3
Returns the rotation of the matrix as an angle.
Same as VMatrix:GetAngles in Garry's Mod, values are in range [-180, 180].
| Type | Name | Description |
|---|---|---|
Angle3 | ang3 | The new angle. |
#VMatrix:getDeterminant
function VMatrix:getDeterminant(): number
Calculates the determinant of the matrix.
1 for rotation matrices, 0 for singular ( non-invertible ) matrices, negative if the matrix mirrors.
| Type | Name | Description |
|---|---|---|
number | determinant | The determinant. |
#VMatrix:getField
function VMatrix:getField(row: integer, column: integer): number
Returns the value of the matrix at the given row and column.
Same as VMatrix:GetField in Garry's Mod, out of range indices are clamped to [1, 4].
Slower than accessing the fields directly ( matrix.m23 ).
| Name | Type | Description |
|---|---|---|
row | integer | The row, from 1 to 4. |
column | integer | The column, from 1 to 4. |
| Type | Name | Description |
|---|---|---|
number | value | The value. |
#VMatrix:getForward
function VMatrix:getForward(): Vector3
Returns the forward direction of the matrix ( first column ).
Same as VMatrix:GetForward in Garry's Mod, not normalized if the matrix has scale.
| Type | Name | Description |
|---|---|---|
Vector3 | forward_dir | The new vector. |
#VMatrix:getInverse
function VMatrix:getInverse(): VMatrix | nil
Returns the inverse of the matrix ( full 4x4 inverse ).
Same as VMatrix:GetInverse in Garry's Mod.
| Type | Name | Description |
|---|---|---|
VMatrix | nil | inverted_matrix | The new matrix, or nil if the matrix is singular. |
#VMatrix:getInverseTR
function VMatrix:getInverseTR(): VMatrix
Returns the inverse of the matrix, assuming it only contains rotation and translation ( no scale ).
Same as VMatrix:GetInverseTR in Garry's Mod.
| Type | Name | Description |
|---|---|---|
VMatrix | inverted_matrix | The new matrix. |
#VMatrix:getLeft
function VMatrix:getLeft(): Vector3
Returns the left direction of the matrix ( second column ).
| Type | Name | Description |
|---|---|---|
Vector3 | left_dir | The new vector. |
#VMatrix:getRight
function VMatrix:getRight(): Vector3
Returns the right direction of the matrix ( negated second column ).
Same as VMatrix:GetRight in Garry's Mod.
| Type | Name | Description |
|---|---|---|
Vector3 | right_dir | The new vector. |
#VMatrix:getScale
function VMatrix:getScale(): Vector3
Returns the scale of the matrix ( lengths of the forward, left and up columns ).
Always positive, mirroring is not detected ( check getDeterminant for that ).
| Type | Name | Description |
|---|---|---|
Vector3 | scale | The new vector. |
#VMatrix:getTranslation
function VMatrix:getTranslation(): Vector3
Returns the translation of the matrix ( fourth column ).
Same as VMatrix:GetTranslation in Garry's Mod.
| Type | Name | Description |
|---|---|---|
Vector3 | translation | The new vector. |
#VMatrix:getTransposed
function VMatrix:getTransposed(): VMatrix
Returns a transposed copy of the matrix.
| Type | Name | Description |
|---|---|---|
VMatrix | transposed_matrix | The new matrix. |
#VMatrix:getUp
function VMatrix:getUp(): Vector3
Returns the up direction of the matrix ( third column ).
Same as VMatrix:GetUp in Garry's Mod.
| Type | Name | Description |
|---|---|---|
Vector3 | up_dir | The new vector. |
#VMatrix:identity
function VMatrix:identity(): VMatrix
Sets the matrix to identity ( no rotation, no translation, scale 1 ).
| Type | Name | Description |
|---|---|---|
VMatrix | matrix | The same matrix. |
#VMatrix:isIdentity
function VMatrix:isIdentity(): boolean
Checks if the matrix is exactly identity.
| Type | Name | Description |
|---|---|---|
boolean | is_identity | true if the matrix is identity, false otherwise. |
#VMatrix:isNear
function VMatrix:isNear(matrix: VMatrix, tolerance: number): boolean
Checks if the matrix is equal to the given matrix with the given tolerance.
Each of the 16 values is compared separately.
| Name | Type | Description |
|---|---|---|
matrix | VMatrix | The matrix to check. |
tolerance | number | The maximum allowed difference per value. |
| Type | Name | Description |
|---|---|---|
boolean | is_near | true if the matrices are equal within the tolerance, otherwise false. |
#VMatrix:isRotationMatrix
function VMatrix:isRotationMatrix(tolerance?: number): boolean
Checks if the matrix is a rotation matrix ( forward, left and up columns are normalized and perpendicular ).
Same as VMatrix:IsRotationMatrix in Garry's Mod, translation is ignored.
| Name | Type | Description |
|---|---|---|
toleranceoptional | number | The tolerance, defaults to 1e-3. |
| Type | Name | Description |
|---|---|---|
boolean | is_rotation_matrix | true if the matrix is a rotation matrix, false otherwise. |
#VMatrix:isZero
function VMatrix:isZero(): boolean
Checks if all values of the matrix are exactly zero.
| Type | Name | Description |
|---|---|---|
boolean | is_zero | true if the matrix is zero, false otherwise. |
#VMatrix:lerp
function VMatrix:lerp(t: number, target: VMatrix, t_angle?: number): VMatrix
Interpolates the matrix to the target matrix.
Rotation is interpolated with quaternion slerp ( shortest path ), scale, translation and the fourth row linearly.
| Name | Type | Description |
|---|---|---|
t | number | The interpolation factor for translation, scale and the fourth row, 0 keeps the matrix, 1 sets it to the target. |
target | VMatrix | The target matrix. |
t_angleoptional | number | The interpolation factor for rotation, defaults to t. |
| Type | Name | Description |
|---|---|---|
VMatrix | matrix | The same matrix, interpolated. |
#VMatrix:mul
function VMatrix:mul(matrix: VMatrix): VMatrix
Multiplies the matrix by another matrix ( self = self * matrix ).
Same as VMatrix:Mul in Garry's Mod, matrix is applied before the current transform.
| Name | Type | Description |
|---|---|---|
matrix | VMatrix | The other matrix. |
| Type | Name | Description |
|---|---|---|
VMatrix | matrix | The same matrix, with the product. |
#VMatrix:premul
function VMatrix:premul(matrix: VMatrix): VMatrix
Multiplies another matrix by the matrix ( self = matrix * self ).
matrix is applied after the current transform.
| Name | Type | Description |
|---|---|---|
matrix | VMatrix | The other matrix. |
| Type | Name | Description |
|---|---|---|
VMatrix | matrix | The same matrix, with the product. |
#VMatrix:rotate
function VMatrix:rotate(angle: Angle3): VMatrix
Rotates the matrix by the given angle in local space ( self = self * R ).
Same as VMatrix:Rotate in Garry's Mod, translation stays unchanged.
| Name | Type | Description |
|---|---|---|
angle | Angle3 | The angle. |
| Type | Name | Description |
|---|---|---|
VMatrix | matrix | The same matrix, rotated. |
#VMatrix:scale
function VMatrix:scale(vector: Vector3): VMatrix
Scales the matrix by the given vector in local space ( self = self * S ).
Same as VMatrix:Scale in Garry's Mod, multiplies the forward, left and up columns, translation stays unchanged.
| Name | Type | Description |
|---|---|---|
vector | Vector3 | The scale per axis. |
| Type | Name | Description |
|---|---|---|
VMatrix | matrix | The same matrix, scaled. |
#VMatrix:scaleTranslation
function VMatrix:scaleTranslation(scale: number): VMatrix
Scales the translation of the matrix by the given number.
Same as VMatrix:ScaleTranslation in Garry's Mod.
| Name | Type | Description |
|---|---|---|
scale | number | The scale factor. |
| Type | Name | Description |
|---|---|---|
VMatrix | matrix | The same matrix. |
#VMatrix:set
function VMatrix:set(matrix: VMatrix): VMatrix
Copies the values of another matrix into this matrix.
| Name | Type | Description |
|---|---|---|
matrix | VMatrix | The matrix to copy from. |
| Type | Name | Description |
|---|---|---|
VMatrix | matrix | The same matrix. |
#VMatrix:setAngles
function VMatrix:setAngles(angle: Angle3): VMatrix
Sets the rotation of the matrix from the angle, translation and the fourth row stay unchanged.
Same as VMatrix:SetAngles in Garry's Mod, any existing scale is lost.
| Name | Type | Description |
|---|---|---|
angle | Angle3 | The angle. |
| Type | Name | Description |
|---|---|---|
VMatrix | matrix | The same matrix. |
#VMatrix:setField
function VMatrix:setField(row: integer, column: integer, value: number): VMatrix
Sets the value of the matrix at the given row and column.
Same as VMatrix:SetField in Garry's Mod, out of range indices are clamped to [1, 4].
| Name | Type | Description |
|---|---|---|
row | integer | The row, from 1 to 4. |
column | integer | The column, from 1 to 4. |
value | number | The value. |
| Type | Name | Description |
|---|---|---|
VMatrix | matrix | The same matrix. |
#VMatrix:setForward
function VMatrix:setForward(vector: Vector3): VMatrix
Sets the forward direction of the matrix ( first column ).
Same as VMatrix:SetForward in Garry's Mod.
| Name | Type | Description |
|---|---|---|
vector | Vector3 | The forward direction. |
| Type | Name | Description |
|---|---|---|
VMatrix | matrix | The same matrix. |
#VMatrix:setLeft
function VMatrix:setLeft(vector: Vector3): VMatrix
Sets the left direction of the matrix ( second column ).
| Name | Type | Description |
|---|---|---|
vector | Vector3 | The left direction. |
| Type | Name | Description |
|---|---|---|
VMatrix | matrix | The same matrix. |
#VMatrix:setRight
function VMatrix:setRight(vector: Vector3): VMatrix
Sets the right direction of the matrix ( stored negated in the second column ).
Same as VMatrix:SetRight in Garry's Mod.
| Name | Type | Description |
|---|---|---|
vector | Vector3 | The right direction. |
| Type | Name | Description |
|---|---|---|
VMatrix | matrix | The same matrix. |
#VMatrix:setScale
function VMatrix:setScale(vector: Vector3): VMatrix
Sets the scale of the matrix while preserving the rotation and translation.
Columns with zero length stay zero, since their direction is unknown.
| Name | Type | Description |
|---|---|---|
vector | Vector3 | The new scale per axis. |
| Type | Name | Description |
|---|---|---|
VMatrix | matrix | The same matrix. |
#VMatrix:setTranslation
function VMatrix:setTranslation(vector: Vector3): VMatrix
Sets the translation of the matrix ( fourth column ), rotation and scale stay unchanged.
Same as VMatrix:SetTranslation in Garry's Mod.
| Name | Type | Description |
|---|---|---|
vector | Vector3 | The translation. |
| Type | Name | Description |
|---|---|---|
VMatrix | matrix | The same matrix. |
#VMatrix:setUp
function VMatrix:setUp(vector: Vector3): VMatrix
Sets the up direction of the matrix ( third column ).
Same as VMatrix:SetUp in Garry's Mod.
| Name | Type | Description |
|---|---|---|
vector | Vector3 | The up direction. |
| Type | Name | Description |
|---|---|---|
VMatrix | matrix | The same matrix. |
#VMatrix:toQuaternion
function VMatrix:toQuaternion(): Quaternion
Returns the rotation of the matrix as a quaternion, scale and translation are ignored.
| Type | Name | Description |
|---|---|---|
Quaternion | quat | The new unit quaternion. |
#VMatrix:transformDirection
function VMatrix:transformDirection(vector: Vector3): Vector3
Transforms the direction by the matrix ( rotation and scale, without translation ).
The result is not normalized if the matrix has scale.
| Name | Type | Description |
|---|---|---|
vector | Vector3 | The direction. |
| Type | Name | Description |
|---|---|---|
Vector3 | vec3 | The new transformed direction. |
#VMatrix:translate
function VMatrix:translate(vector: Vector3): VMatrix
Translates the matrix by the given vector in local space ( self = self * T ).
Same as VMatrix:Translate in Garry's Mod, the offset is rotated and scaled by the matrix, use setTranslation to move in world space.
| Name | Type | Description |
|---|---|---|
vector | Vector3 | The local offset. |
| Type | Name | Description |
|---|---|---|
VMatrix | matrix | The same matrix, translated. |
#VMatrix:zero
function VMatrix:zero(): VMatrix
Sets all values of the matrix to zero.
| Type | Name | Description |
|---|---|---|
VMatrix | matrix | The same matrix. |