dreamworkAPI
Ctrl K
GitHub
classDocs / VMatrix

VMatrix

classsharedmenusource
Object → VMatrix

A 4x4 transformation matrix object ( rotation, scale and translation ) in Source engine layout.

Operators:

  • matrix * matrix - matrix product, a * b transforms by b first, then by a.
  • matrix * vec3 - transforms the point ( with translation ), returns a new Vector3.
  • matrix + matrix, matrix - matrix - component-wise.

There is no division operator, use getInverse explicitly, it can fail for singular matrices.

Constructor

VMatrix(...: number?): VMatrix

Fields

NameTypeDescription
m11numberRow 1, column 1 ( forward X ).
m12numberRow 1, column 2 ( left X ).
m13numberRow 1, column 3 ( up X ).
m14numberRow 1, column 4 ( translation X ).
m21numberRow 2, column 1 ( forward Y ).
m22numberRow 2, column 2 ( left Y ).
m23numberRow 2, column 3 ( up Y ).
m24numberRow 2, column 4 ( translation Y ).
m31numberRow 3, column 1 ( forward Z ).
m32numberRow 3, column 2 ( left Z ).
m33numberRow 3, column 3 ( up Z ).
m34numberRow 3, column 4 ( translation Z ).
m41numberRow 4, column 1, 0 for affine transforms.
m42numberRow 4, column 2, 0 for affine transforms.
m43numberRow 4, column 3, 0 for affine transforms.
m44numberRow 4, column 4, 1 for affine transforms.

Operators

OperatorOperandResult
add VMatrix VMatrix
sub VMatrix VMatrix
mul Vector3 Vector3
mul VMatrix VMatrix

Static functions

cloneCreates a new independent copy of the matrix.
copyCreates a new independent copy of the matrix.
fromAngle3Creates a new rotation matrix from the angle and the optional translation.
fromQuaternionCreates a new rotation matrix from the quaternion and the optional translation.
invertInverts the matrix ( full 4x4 inverse ).
invertTRInverts the matrix, assuming it only contains rotation and translation ( no scale ).
setUnpackedSets all 16 values of the matrix ( row by row ).
transformPointTransforms the point by the matrix ( rotation, scale and translation ), same as matrix * vec3.
transposeTransposes the matrix ( swaps rows and columns ).
unpackReturns all 16 values of the matrix ( row by row ).
unpackAnglesReturns the unpacked Euler angles ( pitch, yaw, roll ) of the matrix in degrees.

#VMatrix.clone

sharedmenunodiscardsource
function VMatrix.clone(self: VMatrix): VMatrix

Creates a new independent copy of the matrix.

Parameters
NameTypeDescription
selfVMatrixThe matrix.
Returns
TypeNameDescription
VMatrixcopyThe new matrix.

#VMatrix.copy

sharedmenunodiscardsource
function VMatrix.copy(self: VMatrix): VMatrix

Creates a new independent copy of the matrix.

Parameters
NameTypeDescription
selfVMatrixThe matrix.
Returns
TypeNameDescription
VMatrixcopyThe new matrix.

#VMatrix.fromAngle3

sharedmenunodiscardsource
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.

Parameters
NameTypeDescription
angleAngle3The angle.
translationoptionalVector3The translation, defaults to ( 0, 0, 0 ).
Returns
TypeNameDescription
VMatrixmatrixThe new matrix.

#VMatrix.fromQuaternion

sharedmenunodiscardsource
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.

Parameters
NameTypeDescription
quaternionQuaternionThe quaternion.
translationoptionalVector3The translation, defaults to ( 0, 0, 0 ).
Returns
TypeNameDescription
VMatrixmatrixThe new matrix.

#VMatrix.invert

sharedmenusource
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.

Parameters
NameTypeDescription
selfVMatrixThe matrix.
Returns
TypeNameDescription
booleansuccesstrue if the matrix was inverted, false if the matrix is singular.

#VMatrix.invertTR

sharedmenusource
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.

Parameters
NameTypeDescription
selfVMatrixThe matrix.
Returns
TypeNameDescription
VMatrixmatrixThe same matrix, inverted.

#VMatrix.setUnpacked

sharedmenusource
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 ).

Parameters
NameTypeDescription
selfany
m11any
m12any
m13any
m14any
m21any
m22any
m23any
m24any
m31any
m32any
m33any
m34any
m41any
m42any
m43any
m44any
Returns
TypeNameDescription
VMatrixmatrixThe same matrix.

#VMatrix.transformPoint

sharedmenunodiscardsource
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 ).

Parameters
NameTypeDescription
selfVMatrixThe matrix.
vectorVector3The point.
Returns
TypeNameDescription
Vector3vec3The new transformed point.

#VMatrix.transpose

sharedmenusource
function VMatrix.transpose(self: VMatrix): VMatrix

Transposes the matrix ( swaps rows and columns ).

For pure rotation matrices the transpose is the inverse.

Parameters
NameTypeDescription
selfVMatrixThe matrix.
Returns
TypeNameDescription
VMatrixmatrixThe same matrix, transposed.

#VMatrix.unpack

sharedmenunodiscardsource
function VMatrix.unpack(self: any): number

Returns all 16 values of the matrix ( row by row ).

Parameters
NameTypeDescription
selfany
Returns
TypeNameDescription
numberm11, 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

sharedmenunodiscardsource
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.

Parameters
NameTypeDescription
selfVMatrixThe matrix.
Returns
TypeNameDescription
numberpitchThe pitch in degrees.
numberyawThe yaw in degrees.
numberrollThe roll in degrees.

Methods

getAnglesReturns the rotation of the matrix as an angle.
getDeterminantCalculates the determinant of the matrix.
getFieldReturns the value of the matrix at the given row and column.
getForwardReturns the forward direction of the matrix ( first column ).
getInverseReturns the inverse of the matrix ( full 4x4 inverse ).
getInverseTRReturns the inverse of the matrix, assuming it only contains rotation and translation ( no scale ).
getLeftReturns the left direction of the matrix ( second column ).
getRightReturns the right direction of the matrix ( negated second column ).
getScaleReturns the scale of the matrix ( lengths of the forward, left and up columns ).
getTranslationReturns the translation of the matrix ( fourth column ).
getTransposedReturns a transposed copy of the matrix.
getUpReturns the up direction of the matrix ( third column ).
identitySets the matrix to identity ( no rotation, no translation, scale 1 ).
isIdentityChecks if the matrix is exactly identity.
isNearChecks if the matrix is equal to the given matrix with the given tolerance.
isRotationMatrixChecks if the matrix is a rotation matrix ( forward, left and up columns are normalized and perpendicular ).
isZeroChecks if all values of the matrix are exactly zero.
lerpInterpolates the matrix to the target matrix.
mulMultiplies the matrix by another matrix ( self = self * matrix ).
premulMultiplies another matrix by the matrix ( self = matrix * self ).
rotateRotates the matrix by the given angle in local space ( self = self * R ).
scaleScales the matrix by the given vector in local space ( self = self * S ).
scaleTranslationScales the translation of the matrix by the given number.
setCopies the values of another matrix into this matrix.
setAnglesSets the rotation of the matrix from the angle, translation and the fourth row stay unchanged.
setFieldSets the value of the matrix at the given row and column.
setForwardSets the forward direction of the matrix ( first column ).
setLeftSets the left direction of the matrix ( second column ).
setRightSets the right direction of the matrix ( stored negated in the second column ).
setScaleSets the scale of the matrix while preserving the rotation and translation.
setTranslationSets the translation of the matrix ( fourth column ), rotation and scale stay unchanged.
setUpSets the up direction of the matrix ( third column ).
toQuaternionReturns the rotation of the matrix as a quaternion, scale and translation are ignored.
transformDirectionTransforms the direction by the matrix ( rotation and scale, without translation ).
translateTranslates the matrix by the given vector in local space ( self = self * T ).
zeroSets all values of the matrix to zero.

#VMatrix:getAngles

sharedmenunodiscardsource
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].

Returns
TypeNameDescription
Angle3ang3The new angle.

#VMatrix:getDeterminant

sharedmenunodiscardsource
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.

Returns
TypeNameDescription
numberdeterminantThe determinant.

#VMatrix:getField

sharedmenunodiscardsource
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 ).

Parameters
NameTypeDescription
rowintegerThe row, from 1 to 4.
columnintegerThe column, from 1 to 4.
Returns
TypeNameDescription
numbervalueThe value.

#VMatrix:getForward

sharedmenunodiscardsource
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.

Returns
TypeNameDescription
Vector3forward_dirThe new vector.

#VMatrix:getInverse

sharedmenunodiscardsource
function VMatrix:getInverse(): VMatrix | nil

Returns the inverse of the matrix ( full 4x4 inverse ).

Same as VMatrix:GetInverse in Garry's Mod.

Returns
TypeNameDescription
VMatrix | nilinverted_matrixThe new matrix, or nil if the matrix is singular.

#VMatrix:getInverseTR

sharedmenunodiscardsource
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.

Returns
TypeNameDescription
VMatrixinverted_matrixThe new matrix.

#VMatrix:getLeft

sharedmenunodiscardsource
function VMatrix:getLeft(): Vector3

Returns the left direction of the matrix ( second column ).

Returns
TypeNameDescription
Vector3left_dirThe new vector.

#VMatrix:getRight

sharedmenunodiscardsource
function VMatrix:getRight(): Vector3

Returns the right direction of the matrix ( negated second column ).

Same as VMatrix:GetRight in Garry's Mod.

Returns
TypeNameDescription
Vector3right_dirThe new vector.

#VMatrix:getScale

sharedmenunodiscardsource
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 ).

Returns
TypeNameDescription
Vector3scaleThe new vector.

#VMatrix:getTranslation

sharedmenunodiscardsource
function VMatrix:getTranslation(): Vector3

Returns the translation of the matrix ( fourth column ).

Same as VMatrix:GetTranslation in Garry's Mod.

Returns
TypeNameDescription
Vector3translationThe new vector.

#VMatrix:getTransposed

sharedmenunodiscardsource
function VMatrix:getTransposed(): VMatrix

Returns a transposed copy of the matrix.

Returns
TypeNameDescription
VMatrixtransposed_matrixThe new matrix.

#VMatrix:getUp

sharedmenunodiscardsource
function VMatrix:getUp(): Vector3

Returns the up direction of the matrix ( third column ).

Same as VMatrix:GetUp in Garry's Mod.

Returns
TypeNameDescription
Vector3up_dirThe new vector.

#VMatrix:identity

sharedmenusource
function VMatrix:identity(): VMatrix

Sets the matrix to identity ( no rotation, no translation, scale 1 ).

Returns
TypeNameDescription
VMatrixmatrixThe same matrix.

#VMatrix:isIdentity

sharedmenunodiscardsource
function VMatrix:isIdentity(): boolean

Checks if the matrix is exactly identity.

Returns
TypeNameDescription
booleanis_identitytrue if the matrix is identity, false otherwise.

#VMatrix:isNear

sharedmenunodiscardsource
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.

Parameters
NameTypeDescription
matrixVMatrixThe matrix to check.
tolerancenumberThe maximum allowed difference per value.
Returns
TypeNameDescription
booleanis_neartrue if the matrices are equal within the tolerance, otherwise false.

#VMatrix:isRotationMatrix

sharedmenunodiscardsource
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.

Parameters
NameTypeDescription
toleranceoptionalnumberThe tolerance, defaults to 1e-3.
Returns
TypeNameDescription
booleanis_rotation_matrixtrue if the matrix is a rotation matrix, false otherwise.

#VMatrix:isZero

sharedmenunodiscardsource
function VMatrix:isZero(): boolean

Checks if all values of the matrix are exactly zero.

Returns
TypeNameDescription
booleanis_zerotrue if the matrix is zero, false otherwise.

#VMatrix:lerp

sharedmenusource
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.

Parameters
NameTypeDescription
tnumberThe interpolation factor for translation, scale and the fourth row, 0 keeps the matrix, 1 sets it to the target.
targetVMatrixThe target matrix.
t_angleoptionalnumberThe interpolation factor for rotation, defaults to t.
Returns
TypeNameDescription
VMatrixmatrixThe same matrix, interpolated.

#VMatrix:mul

sharedmenusource
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.

Parameters
NameTypeDescription
matrixVMatrixThe other matrix.
Returns
TypeNameDescription
VMatrixmatrixThe same matrix, with the product.

#VMatrix:premul

sharedmenusource
function VMatrix:premul(matrix: VMatrix): VMatrix

Multiplies another matrix by the matrix ( self = matrix * self ).

matrix is applied after the current transform.

Parameters
NameTypeDescription
matrixVMatrixThe other matrix.
Returns
TypeNameDescription
VMatrixmatrixThe same matrix, with the product.

#VMatrix:rotate

sharedmenusource
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.

Parameters
NameTypeDescription
angleAngle3The angle.
Returns
TypeNameDescription
VMatrixmatrixThe same matrix, rotated.

#VMatrix:scale

sharedmenusource
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.

Parameters
NameTypeDescription
vectorVector3The scale per axis.
Returns
TypeNameDescription
VMatrixmatrixThe same matrix, scaled.

#VMatrix:scaleTranslation

sharedmenusource
function VMatrix:scaleTranslation(scale: number): VMatrix

Scales the translation of the matrix by the given number.

Same as VMatrix:ScaleTranslation in Garry's Mod.

Parameters
NameTypeDescription
scalenumberThe scale factor.
Returns
TypeNameDescription
VMatrixmatrixThe same matrix.

#VMatrix:set

sharedmenusource
function VMatrix:set(matrix: VMatrix): VMatrix

Copies the values of another matrix into this matrix.

Parameters
NameTypeDescription
matrixVMatrixThe matrix to copy from.
Returns
TypeNameDescription
VMatrixmatrixThe same matrix.

#VMatrix:setAngles

sharedmenusource
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.

Parameters
NameTypeDescription
angleAngle3The angle.
Returns
TypeNameDescription
VMatrixmatrixThe same matrix.

#VMatrix:setField

sharedmenusource
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].

Parameters
NameTypeDescription
rowintegerThe row, from 1 to 4.
columnintegerThe column, from 1 to 4.
valuenumberThe value.
Returns
TypeNameDescription
VMatrixmatrixThe same matrix.

#VMatrix:setForward

sharedmenusource
function VMatrix:setForward(vector: Vector3): VMatrix

Sets the forward direction of the matrix ( first column ).

Same as VMatrix:SetForward in Garry's Mod.

Parameters
NameTypeDescription
vectorVector3The forward direction.
Returns
TypeNameDescription
VMatrixmatrixThe same matrix.

#VMatrix:setLeft

sharedmenusource
function VMatrix:setLeft(vector: Vector3): VMatrix

Sets the left direction of the matrix ( second column ).

Parameters
NameTypeDescription
vectorVector3The left direction.
Returns
TypeNameDescription
VMatrixmatrixThe same matrix.

#VMatrix:setRight

sharedmenusource
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.

Parameters
NameTypeDescription
vectorVector3The right direction.
Returns
TypeNameDescription
VMatrixmatrixThe same matrix.

#VMatrix:setScale

sharedmenusource
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.

Parameters
NameTypeDescription
vectorVector3The new scale per axis.
Returns
TypeNameDescription
VMatrixmatrixThe same matrix.

#VMatrix:setTranslation

sharedmenusource
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.

Parameters
NameTypeDescription
vectorVector3The translation.
Returns
TypeNameDescription
VMatrixmatrixThe same matrix.

#VMatrix:setUp

sharedmenusource
function VMatrix:setUp(vector: Vector3): VMatrix

Sets the up direction of the matrix ( third column ).

Same as VMatrix:SetUp in Garry's Mod.

Parameters
NameTypeDescription
vectorVector3The up direction.
Returns
TypeNameDescription
VMatrixmatrixThe same matrix.

#VMatrix:toQuaternion

sharedmenunodiscardsource
function VMatrix:toQuaternion(): Quaternion

Returns the rotation of the matrix as a quaternion, scale and translation are ignored.

Returns
TypeNameDescription
QuaternionquatThe new unit quaternion.

#VMatrix:transformDirection

sharedmenunodiscardsource
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.

Parameters
NameTypeDescription
vectorVector3The direction.
Returns
TypeNameDescription
Vector3vec3The new transformed direction.

#VMatrix:translate

sharedmenusource
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.

Parameters
NameTypeDescription
vectorVector3The local offset.
Returns
TypeNameDescription
VMatrixmatrixThe same matrix, translated.

#VMatrix:zero

sharedmenusource
function VMatrix:zero(): VMatrix

Sets all values of the matrix to zero.

Returns
TypeNameDescription
VMatrixmatrixThe same matrix.
Generated from the dreamwork meta branch.