Matrix | Babylon.js API documentation

API
Babylon.js API documentation
    Preparing search index...

    Class Matrix

    Class used to store matrix data (4x4) Note on matrix definitions in Babylon.js for setting values directly rather than using one of the methods available. Matrix size is given by rows x columns. A Vector3 is a 1 X 3 matrix [x, y, z].

    In Babylon.js multiplying a 1 x 3 matrix by a 4 x 4 matrix is done using BABYLON.Vector4.TransformCoordinates(Vector3, Matrix). and extending the passed Vector3 to a Vector4, V = [x, y, z, 1]. Let M be a matrix with elements m(row, column), so that m(2, 3) is the element in row 2 column 3 of M.

    Multiplication is of the form VM and has the resulting Vector4 VM = [xm(0, 0) + ym(1, 0) + zm(2, 0) + m(3, 0), xm(0, 1) + ym(1, 1) + zm(2, 1) + m(3, 1), xm(0, 2) + ym(1, 2) + zm(2, 2) + m(3, 2), xm(0, 3) + ym(1, 3) + zm(2, 3) + m(3, 3)]. On the web you will find many examples that use the opposite convention of MV, in which case to make use of the examples you will need to transpose the matrix.

    Example Playground - Overview Linear Algebra - https://playground.babylonjs.com/#AV9X17 Example Playground - Overview Transformation - https://playground.babylonjs.com/#AV9X17#1 Example Playground - Overview Projection - https://playground.babylonjs.com/#AV9X17#2

    Implements

    Index
    add addAtIndex addInPlace addInPlaceFromFloats addToRef addToSelf addTranslationFromFloats asArray clone copyFrom copyFromFloats copyToArray decompose decomposeToTransformNode determinant divide divideInPlace divideToRef equals equalsToFloats equalsWithEpsilon floor floorToRef fract fractToRef fromArray getClassName getHashCode getRotationMatrix getRotationMatrixToRef getRow getRowToRef getTranslation getTranslationToRef invert invertToRef isIdentity isIdentityAs3x2 markAsUpdated maximizeInPlace maximizeInPlaceFromFloats minimizeInPlace minimizeInPlaceFromFloats multiply multiplyAtIndex multiplyByFloats multiplyByFloatsToRef multiplyInPlace multiplyToArray multiplyToRef negate negateInPlace negateToRef removeRotationAndScaling reset scale scaleAndAddToRef scaleInPlace scaleToRef set setAll setRow setRowFromFloats setTranslation setTranslationFromFloats subtract subtractFromFloats subtractFromFloatsToRef subtractInPlace subtractToRef toArray toggleModelMatrixHandInPlace toggleProjectionMatrixHandInPlace toNormalMatrix toString transpose transposeToRef Compose ComposeToRef DecomposeLerp DecomposeLerpToRef FromArray FromArrayToRef FromFloat32ArrayToRefScaled FromQuaternionToRef FromValues FromValuesToRef FromXYZAxesToRef GetAsMatrix2x2 GetAsMatrix3x3 GetFinalMatrix Identity IdentityToRef Invert Lerp LerpToRef LookAtLH LookAtLHToRef LookAtRH LookAtRHToRef LookDirectionLH LookDirectionLHToRef LookDirectionRH LookDirectionRHToRef ObliqueOffCenterLHToRef ObliqueOffCenterRHToRef OrthoLH OrthoLHToRef OrthoOffCenterLH OrthoOffCenterLHToRef OrthoOffCenterRH OrthoOffCenterRHToRef PerspectiveFovLH PerspectiveFovLHToRef PerspectiveFovReverseLHToRef PerspectiveFovReverseRHToRef PerspectiveFovRH PerspectiveFovRHToRef PerspectiveLH Reflection ReflectionToRef RotationAlignToRef RotationAxis RotationAxisToRef RotationX RotationXToRef RotationY RotationYawPitchRoll RotationYawPitchRollToRef RotationYToRef RotationZ RotationZToRef Scaling ScalingToRef Translation TranslationToRef Transpose TransposeToRef Zero
    dimension: readonly [4, 4]

    Tensor.dimension

    rank: 2

    Tensor.rank

    updateFlag: number = -1

    Gets the update flag of the matrix which is an unique number for the matrix. It will be incremented every time the matrix data change. You can use it to speed the comparison between two versions of the same matrix.

    • Adds the given coordinates to the current instance

      Parameters

      • ...floats: [
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
        ]

        the floats to add

      Returns this

      the current updated instance

    Returns the matrix as a Float32Array or Array Example Playground - https://playground.babylonjs.com/#AV9X17#114

    Returns [
        number,
        number,
        number,
        number,
        number,
        number,
        number,
        number,
        number,
        number,
        number,
        number,
        number,
        number,
        number,
        number,
    ]

    the matrix underlying array.

    • Sets all the matrix values from a float array

      Parameters

      • ...floats: [
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
        ]

        the 16 float values to set

      Returns this

      the current updated matrix

    • Populates the given array from the starting index with the current matrix values

      Parameters

      • array: number[] | Float32Array<ArrayBufferLike>

        defines the target array

      • offset: number = 0

        defines the offset in the target array where to start storing values

      Returns this

      the current matrix

    • Decomposes the current Matrix into a translation, rotation and scaling components Example Playground - https://playground.babylonjs.com/#AV9X17#12

      Parameters

      • Optionalscale: Vector3

        defines the scale vector3 given as a reference to update

      • Optionalrotation: Quaternion

        defines the rotation quaternion given as a reference to update

      • Optionaltranslation: Vector3

        defines the translation vector3 given as a reference to update

      • OptionalpreserveScalingNode: TransformNode

        Use scaling sign coming from this node. Otherwise scaling sign might change.

      • useAbsoluteScaling: boolean = true

        Use scaling sign coming from this absoluteScaling when true or scaling otherwise.

      Returns boolean

      true if operation was successful

    • Returns true if the current Vectoe coordinates equals the given floats

      Parameters

      • ...floats: [
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
        ]

        defines the coordinates to compare against

      Returns boolean

      true if both instances are equal

    • Gets a boolean if two instances are equals (using an epsilon value)

      Parameters

      • other: DeepImmutable<Matrix>

        defines the other instance

      • epsilon: number = 0

        defines the minimal distance to consider equality

      Returns boolean

      true if the given instance coordinates are close to the current ones by a distance of epsilon.

    • Updates the current instance with the maximal coordinate values between its and the given floats.

      Parameters

      • ...floats: [
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
        ]

        defines the floats to compare against

      Returns this

      this current updated instance

    • Updates the current instance with the minmal coordinate values between its and the given floats.

      Parameters

      • ...floats: [
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
        ]

        defines the floats to compare against

      Returns this

      this current updated instance

    • mutiply the specified position in the current Matrix by a value

      Parameters

      • index: number

        the index of the value within the matrix. between 0 and 15.

      • value: number

        the value to be added

      Returns this

      the current updated matrix

    • This method performs a component-by-component multiplication of the current matrix with the array of transmitted numbers. Use multiply or multiplyToRef for matrix multiplication.

      Parameters

      • ...floats: [
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
        ]

        defines the array of numbers to multiply the matrix by

      Returns this

      the current updated matrix

    • Multiples the current matrix by the given floats and stores them in the given ref

      Type Parameters

      Parameters

      • ...args: [
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            T,
        ]

        The floats and ref

      Returns T

      The updated ref

    • Sets the Float32Array "result" from the given index "offset" with the multiplication of the current matrix and the given one

      Parameters

      • other: DeepImmutable<Matrix>

        defines the second operand

      • result: number[] | Float32Array<ArrayBufferLike>

        defines the array where to store the multiplication

      • offset: number

        defines the offset in the target array where to start storing values

      Returns this

      the current matrix

    • Negate the current instance and stores the result in the given instance "result" coordinates

      Type Parameters

      Parameters

      • result: T

        defines the instance object where to store the result

      Returns T

      the result

    • Scale the current matrix values by a factor and add the result to a given matrix

      Type Parameters

      Parameters

      • scale: number

        defines the scale factor

      • result: T

        defines the Matrix to store the result

      Returns T

      result input

    • Multiply the instance coordinates by

      Parameters

      • scale: number

        defines the scaling factor

      Returns this

      the current updated instance

    • Scale the current matrix values by a factor to a given result matrix

      Type Parameters

      Parameters

      • scale: number

        defines the scale factor

      • result: T

        defines the matrix to store the result

      Returns T

      result input

    • Sets the matrix values

      Parameters

      • ...values: [
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
        ]

        the 16 values to set

      Returns this

      the current updated matrix

    • Sets the index-th row of the current matrix with the given 4 x float values Example Playground - https://playground.babylonjs.com/#AV9X17#36

      Parameters

      • index: number

        defines the row index

      • x: number

        defines the x component to set

      • y: number

        defines the y component to set

      • z: number

        defines the z component to set

      • w: number

        defines the w component to set

      Returns this

      the updated current matrix

    • Returns a new instance set with the subtraction of the given floats from the current instance coordinates

      Parameters

      • ...floats: [
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
        ]

        the coordinates to subtract

      Returns Matrix

      the resulting instance

    • Subtracts the given floats from the current instance coordinates and set the given instance "result" with this result Note: Implementation uses array magic so types may be confusing.

      Type Parameters

      Parameters

      • ...args: [
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            number,
            T,
        ]

        the coordinates to subtract with the last element as the result

      Returns T

      the result

    Returns the matrix as a Float32Array or Array

    Returns FloatArray

    Use asArray

    Stores the matrix in a Float32Array or Array Example Playground - https://playground.babylonjs.com/#AV9X17#49

    Parameters

    • array: FloatArray

      The destination array

    • index: number

      The destination index to start ay

    Returns this

    the matrix

    • Creates new matrix from a list of values (16)

      Parameters

      • initialM11: number

        defines 1st value of 1st row

      • initialM12: number

        defines 2nd value of 1st row

      • initialM13: number

        defines 3rd value of 1st row

      • initialM14: number

        defines 4th value of 1st row

      • initialM21: number

        defines 1st value of 2nd row

      • initialM22: number

        defines 2nd value of 2nd row

      • initialM23: number

        defines 3rd value of 2nd row

      • initialM24: number

        defines 4th value of 2nd row

      • initialM31: number

        defines 1st value of 3rd row

      • initialM32: number

        defines 2nd value of 3rd row

      • initialM33: number

        defines 3rd value of 3rd row

      • initialM34: number

        defines 4th value of 3rd row

      • initialM41: number

        defines 1st value of 4th row

      • initialM42: number

        defines 2nd value of 4th row

      • initialM43: number

        defines 3rd value of 4th row

      • initialM44: number

        defines 4th value of 4th row

      Returns Matrix

      the new matrix

    • Stores a list of values (16) inside a given matrix

      Parameters

      • initialM11: number

        defines 1st value of 1st row

      • initialM12: number

        defines 2nd value of 1st row

      • initialM13: number

        defines 3rd value of 1st row

      • initialM14: number

        defines 4th value of 1st row

      • initialM21: number

        defines 1st value of 2nd row

      • initialM22: number

        defines 2nd value of 2nd row

      • initialM23: number

        defines 3rd value of 2nd row

      • initialM24: number

        defines 4th value of 2nd row

      • initialM31: number

        defines 1st value of 3rd row

      • initialM32: number

        defines 2nd value of 3rd row

      • initialM33: number

        defines 3rd value of 3rd row

      • initialM34: number

        defines 4th value of 3rd row

      • initialM41: number

        defines 1st value of 4th row

      • initialM42: number

        defines 2nd value of 4th row

      • initialM43: number

        defines 3rd value of 4th row

      • initialM44: number

        defines 4th value of 4th row

      • result: Matrix

        defines the target matrix

      Returns void

    • Stores a left-handed oblique projection into a given matrix

      Type Parameters

      Parameters

      • left: number

        defines the viewport left coordinate

      • right: number

        defines the viewport right coordinate

      • bottom: number

        defines the viewport bottom coordinate

      • top: number

        defines the viewport top coordinate

      • znear: number

        defines the near clip plane

      • zfar: number

        defines the far clip plane

      • length: number

        Length of the shear

      • angle: number

        Angle (along X/Y Plane) to apply shear

      • distance: number

        Distance from shear point

      • result: T

        defines the target matrix

      • OptionalhalfZRange: boolean

        true to generate NDC coordinates between 0 and 1 instead of -1 and 1 (default: false)

      Returns T

      result input

    • Stores a right-handed oblique projection into a given matrix

      Type Parameters

      Parameters

      • left: number

        defines the viewport left coordinate

      • right: number

        defines the viewport right coordinate

      • bottom: number

        defines the viewport bottom coordinate

      • top: number

        defines the viewport top coordinate

      • znear: number

        defines the near clip plane

      • zfar: number

        defines the far clip plane

      • length: number

        Length of the shear

      • angle: number

        Angle (along X/Y Plane) to apply shear

      • distance: number

        Distance from shear point

      • result: T

        defines the target matrix

      • OptionalhalfZRange: boolean

        true to generate NDC coordinates between 0 and 1 instead of -1 and 1 (default: false)

      Returns T

      result input

    • Create a left-handed orthographic projection matrix Example Playground - https://playground.babylonjs.com/#AV9X17#70

      Parameters

      • width: number

        defines the viewport width

      • height: number

        defines the viewport height

      • znear: number

        defines the near clip plane

      • zfar: number

        defines the far clip plane

      • OptionalhalfZRange: boolean

        true to generate NDC coordinates between 0 and 1 instead of -1 and 1 (default: false)

      Returns Matrix

      a new matrix as a left-handed orthographic projection matrix

    • Store a left-handed orthographic projection to a given matrix Example Playground - https://playground.babylonjs.com/#AV9X17#71

      Type Parameters

      Parameters

      • width: number

        defines the viewport width

      • height: number

        defines the viewport height

      • znear: number

        defines the near clip plane

      • zfar: number

        defines the far clip plane

      • result: T

        defines the target matrix

      • OptionalhalfZRange: boolean

        true to generate NDC coordinates between 0 and 1 instead of -1 and 1 (default: false)

      Returns T

      result input

    • Create a left-handed orthographic projection matrix Example Playground - https://playground.babylonjs.com/#AV9X17#72

      Parameters

      • left: number

        defines the viewport left coordinate

      • right: number

        defines the viewport right coordinate

      • bottom: number

        defines the viewport bottom coordinate

      • top: number

        defines the viewport top coordinate

      • znear: number

        defines the near clip plane

      • zfar: number

        defines the far clip plane

      • OptionalhalfZRange: boolean

        true to generate NDC coordinates between 0 and 1 instead of -1 and 1 (default: false)

      Returns Matrix

      a new matrix as a left-handed orthographic projection matrix

    • Stores a left-handed orthographic projection into a given matrix Example Playground - https://playground.babylonjs.com/#AV9X17#73

      Type Parameters

      Parameters

      • left: number

        defines the viewport left coordinate

      • right: number

        defines the viewport right coordinate

      • bottom: number

        defines the viewport bottom coordinate

      • top: number

        defines the viewport top coordinate

      • znear: number

        defines the near clip plane

      • zfar: number

        defines the far clip plane

      • result: T

        defines the target matrix

      • OptionalhalfZRange: boolean

        true to generate NDC coordinates between 0 and 1 instead of -1 and 1 (default: false)

      Returns T

      result input

    • Creates a right-handed orthographic projection matrix Example Playground - https://playground.babylonjs.com/#AV9X17#76

      Parameters

      • left: number

        defines the viewport left coordinate

      • right: number

        defines the viewport right coordinate

      • bottom: number

        defines the viewport bottom coordinate

      • top: number

        defines the viewport top coordinate

      • znear: number

        defines the near clip plane

      • zfar: number

        defines the far clip plane

      • OptionalhalfZRange: boolean

        true to generate NDC coordinates between 0 and 1 instead of -1 and 1 (default: false)

      Returns Matrix

      a new matrix as a right-handed orthographic projection matrix

    • Stores a right-handed orthographic projection into a given matrix Example Playground - https://playground.babylonjs.com/#AV9X17#77

      Type Parameters

      Parameters

      • left: number

        defines the viewport left coordinate

      • right: number

        defines the viewport right coordinate

      • bottom: number

        defines the viewport bottom coordinate

      • top: number

        defines the viewport top coordinate

      • znear: number

        defines the near clip plane

      • zfar: number

        defines the far clip plane

      • result: T

        defines the target matrix

      • OptionalhalfZRange: boolean

        true to generate NDC coordinates between 0 and 1 instead of -1 and 1 (default: false)

      Returns T

      result input

    • Creates a left-handed perspective projection matrix Example Playground - https://playground.babylonjs.com/#AV9X17#78

      Parameters

      • fov: number

        defines the horizontal field of view

      • aspect: number

        defines the aspect ratio

      • znear: number

        defines the near clip plane

      • zfar: number

        defines the far clip plane. If 0, assume we are in "infinite zfar" mode

      • OptionalhalfZRange: boolean

        true to generate NDC coordinates between 0 and 1 instead of -1 and 1 (default: false)

      • projectionPlaneTilt: number = 0

        optional tilt angle of the projection plane around the X axis (horizontal)

      • reverseDepthBufferMode: boolean = false

        true to indicate that we are in a reverse depth buffer mode (meaning znear and zfar have been inverted when calling the function)

      Returns Matrix

      a new matrix as a left-handed perspective projection matrix

    • Stores a left-handed perspective projection into a given matrix Example Playground - https://playground.babylonjs.com/#AV9X17#81

      Type Parameters

      Parameters

      • fov: number

        defines the horizontal field of view

      • aspect: number

        defines the aspect ratio

      • znear: number

        defines the near clip plane

      • zfar: number

        defines the far clip plane. If 0, assume we are in "infinite zfar" mode

      • result: T

        defines the target matrix

      • isVerticalFovFixed: boolean = true

        defines it the fov is vertically fixed (default) or horizontally

      • OptionalhalfZRange: boolean

        true to generate NDC coordinates between 0 and 1 instead of -1 and 1 (default: false)

      • projectionPlaneTilt: number = 0

        optional tilt angle of the projection plane around the X axis (horizontal)

      • reverseDepthBufferMode: boolean = false

        true to indicate that we are in a reverse depth buffer mode (meaning znear and zfar have been inverted when calling the function)

      Returns T

      result input

    • Stores a left-handed perspective projection into a given matrix with depth reversed Example Playground - https://playground.babylonjs.com/#AV9X17#89

      Type Parameters

      Parameters

      • fov: number

        defines the horizontal field of view

      • aspect: number

        defines the aspect ratio

      • znear: number

        defines the near clip plane

      • zfar: number

        not used as infinity is used as far clip

      • result: T

        defines the target matrix

      • isVerticalFovFixed: boolean = true

        defines it the fov is vertically fixed (default) or horizontally

      • OptionalhalfZRange: boolean

        true to generate NDC coordinates between 0 and 1 instead of -1 and 1 (default: false)

      • projectionPlaneTilt: number = 0

        optional tilt angle of the projection plane around the X axis (horizontal)

      Returns T

      result input

    • Stores a right-handed perspective projection into a given matrix Example Playground - https://playground.babylonjs.com/#AV9X17#90

      Type Parameters

      Parameters

      • fov: number

        defines the horizontal field of view

      • aspect: number

        defines the aspect ratio

      • znear: number

        defines the near clip plane

      • zfar: number

        not used as infinity is used as far clip

      • result: T

        defines the target matrix

      • isVerticalFovFixed: boolean = true

        defines it the fov is vertically fixed (default) or horizontally

      • OptionalhalfZRange: boolean

        true to generate NDC coordinates between 0 and 1 instead of -1 and 1 (default: false)

      • projectionPlaneTilt: number = 0

        optional tilt angle of the projection plane around the X axis (horizontal)

      Returns T

      result input

    • Creates a right-handed perspective projection matrix Example Playground - https://playground.babylonjs.com/#AV9X17#83

      Parameters

      • fov: number

        defines the horizontal field of view

      • aspect: number

        defines the aspect ratio

      • znear: number

        defines the near clip plane

      • zfar: number

        defines the far clip plane. If 0, assume we are in "infinite zfar" mode

      • OptionalhalfZRange: boolean

        true to generate NDC coordinates between 0 and 1 instead of -1 and 1 (default: false)

      • projectionPlaneTilt: number = 0

        optional tilt angle of the projection plane around the X axis (horizontal)

      • reverseDepthBufferMode: boolean = false

        true to indicate that we are in a reverse depth buffer mode (meaning znear and zfar have been inverted when calling the function)

      Returns Matrix

      a new matrix as a right-handed perspective projection matrix

    • Stores a right-handed perspective projection into a given matrix Example Playground - https://playground.babylonjs.com/#AV9X17#84

      Type Parameters

      Parameters

      • fov: number

        defines the horizontal field of view

      • aspect: number

        defines the aspect ratio

      • znear: number

        defines the near clip plane

      • zfar: number

        defines the far clip plane. If 0, assume we are in "infinite zfar" mode

      • result: T

        defines the target matrix

      • isVerticalFovFixed: boolean = true

        defines it the fov is vertically fixed (default) or horizontally

      • OptionalhalfZRange: boolean

        true to generate NDC coordinates between 0 and 1 instead of -1 and 1 (default: false)

      • projectionPlaneTilt: number = 0

        optional tilt angle of the projection plane around the X axis (horizontal)

      • reverseDepthBufferMode: boolean = false

        true to indicate that we are in a reverse depth buffer mode (meaning znear and zfar have been inverted when calling the function)

      Returns T

      result input

    • Creates a left-handed perspective projection matrix Example Playground - https://playground.babylonjs.com/#AV9X17#85

      Parameters

      • width: number

        defines the viewport width

      • height: number

        defines the viewport height

      • znear: number

        defines the near clip plane

      • zfar: number

        defines the far clip plane

      • OptionalhalfZRange: boolean

        true to generate NDC coordinates between 0 and 1 instead of -1 and 1 (default: false)

      • projectionPlaneTilt: number = 0

        optional tilt angle of the projection plane around the X axis (horizontal)

      Returns Matrix

      a new matrix as a left-handed perspective projection matrix

    • Creates a rotation matrix and stores it in a given matrix Example Playground - https://playground.babylonjs.com/#AV9X17#104

      Type Parameters

      Parameters

      • yaw: number

        defines the yaw angle in radians (Y axis)

      • pitch: number

        defines the pitch angle in radians (X axis)

      • roll: number

        defines the roll angle in radians (Z axis)

      • result: T

        defines the target matrix

      Returns T

      result input