Package icyllis.arc3d.core

Class Matrix

java.lang.Object
icyllis.arc3d.core.Matrix
All Implemented Interfaces:
Matrixc, Cloneable
Direct Known Subclasses:
Matrix
public non-sealed class Matrix extends Object implements Matrixc, Cloneable
This class represents a 3x3 matrix and a 2D transformation, its components correspond to x, y, and w of a 4x4 matrix, where z is discarded.

This class also computes a type mask to simplify some operations, while Matrix3 and Matrix4 do not have this feature.

The memory layout (order of components) is the same as GLSL's column-major and HLSL's row-major, this is just a difference in naming and writing.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected float
    m11
     
    protected float
    m12
     
    protected float
    m14
     
    protected float
    m21
     
    protected float
    m22
     
    protected float
    m24
     
    protected float
    m41
     
    protected float
    m42
     
    protected float
    m44
     

    Fields inherited from interface icyllis.arc3d.core.Matrixc

    kAffine_Mask, kIdentity_Mask, kPerspective_Mask, kScale_Mask, kTranslate_Mask

  • Constructor Summary

    Constructors
    Constructor
    Description
    Matrix()
    Create a new identity matrix.
    Matrix(float scaleX, float shearY, float persp0, float shearX, float scaleY, float persp1, float transX, float transY, float persp2)
    Create a new matrix from the given elements.
    Matrix(Matrixc m)
    Create a new matrix copied from the given matrix.

  • Method Summary

    Modifier and Type
    Method
    Description
    Matrix
    clone()
     
    float
    determinant()
    Return the determinant of this matrix.
    float
    differentialAreaScale(float px, float py)
    Returns the differential area scale factor for a local point 'p' that will be transformed by 'm' (which may have perspective).
    static boolean
    equals(Matrixc a, Matrixc b)
    Returns whether two matrices' elements are equal, using == operator.
    boolean
    equals(Object o)
    Returns whether this matrix elements are equal to another matrix, using == operator.
    float
    getMaxScale()
    Returns the maximum scaling factor of this matrix by decomposing the scaling and shearing elements.
    Returns -1 if scale factor overflows or this matrix contains perspective.
    float
    getMaxScale(float px, float py)
    Returns the maximum scaling factor of this matrix by decomposing the scaling and shearing elements.
    float
    getMinScale()
    Returns the minimum scaling factor of this matrix by decomposing the scaling and shearing elements.
    Returns -1 if scale factor overflows or this matrix contains perspective.
    float
    getMinScale(float px, float py)
    Returns the minimum scaling factor of this matrix by decomposing the scaling and shearing elements.
    float
    getPerspX()
    Returns factor scaling input x-axis relative to input y-axis.
    float
    getPerspY()
    Returns factor scaling input y-axis relative to input x-axis.
    float
    getScaleX()
    Returns scale factor multiplied by x-axis input, contributing to x-axis output.
    float
    getScaleY()
    Returns scale factor multiplied by y-axis input, contributing to y-axis output.
    float
    getShearX()
    Returns scale factor multiplied by y-axis input, contributing to x-axis output.
    float
    getShearY()
    Returns scale factor multiplied by x-axis input, contributing to y-axis output.
    float
    getTranslateX()
    Returns translation contributing to x-axis output.
    float
    getTranslateY()
    Returns translation contributing to y-axis output.
    int
    getType()
    Returns a bit field describing the transformations the matrix may perform.
    int
    hashCode()
     
    boolean
    hasPerspective()
    Returns whether this matrix contains perspective elements.
    static Matrixc
    identity()
    Returns a read-only identity matrix.
    boolean
    invert()
    Compute the inverse of this matrix.
    boolean
    invert(Matrix dest)
    Compute the inverse of this matrix.
    boolean
    isApproxEqual(Matrix m)
    Returns whether this matrix elements are equivalent to given matrix.
    boolean
    isAxisAligned()
    Returns whether this matrix transforms rect to another rect.
    boolean
    isFinite()
    Returns true if all elements of the matrix are finite.
    boolean
    isIdentity()
    Returns true if this matrix is identity.
    boolean
    isScaleTranslate()
    Returns whether this matrix at most scales and translates.
    boolean
    isSimilarity()
    Returns true if this matrix contains only translation, rotation, reflection, and uniform scale.
    boolean
    isTranslate()
    Returns whether this matrix is identity, or translates.
    float
    localAARadius(float left, float top, float right, float bottom)
    Return the minimum distance needed to move in local (pre-transform) space to ensure that the transformed coordinates are at least 1px away from the original mapped point.
    float
    localAARadius(Rect2fc bounds)
    Return the minimum distance needed to move in local (pre-transform) space to ensure that the transformed coordinates are at least 1px away from the original mapped point.
    float
    m11()
    Same as getScaleX().
    void
    m11(float scaleX)
    Set the scaleX value.
    float
    m12()
    Same as getShearY().
    void
    m12(float shearY)
    Set the shearY value.
    float
    m14()
    Same as getPerspX().
    void
    m14(float persp0)
    Set the persp0 value.
    float
    m21()
    Same as getShearX().
    void
    m21(float shearX)
    Set the shearX value.
    float
    m22()
    Same as getScaleY().
    void
    m22(float scaleY)
    Set the scaleY value.
    float
    m24()
    Same as getPerspY().
    void
    m24(float persp1)
    Set the persp1 value.
    float
    m41()
    Same as getTranslateX().
    void
    m41(float transX)
    Set the transX value.
    float
    m42()
    Same as getTranslateY().
    void
    m42(float transY)
    Set the transY value.
    float
    m44()
    Returns the last element of the matrix, the perspective bias.
    void
    m44(float persp2)
    Set the persp2 value.
    static Matrix
    makeScale(float sx, float sy)
    Creates a new scale-only matrix.
    static Matrix
    makeTranslate(float dx, float dy)
    Creates a new translate-only matrix.
    void
    mapPoints(float[] src, int srcPos, float[] dst, int dstPos, int count)
    Maps src point array of length count to dst point array of equal or greater length.
    void
    mapRect(float left, float top, float right, float bottom, Rect2i dst)
    Map a rectangle points in the X-Y plane to get the maximum bounds.
    boolean
    mapRect(Rect2fc src, Rect2f dst)
    Sets dst to bounds of src corners mapped by this matrix.
    void
    mapRectOut(float left, float top, float right, float bottom, Rect2i dst)
    Map a rectangle points in the X-Y plane to get the maximum bounds.
    void
    normalizePerspective()
    If the last column of the matrix is [0, 0, not_one]^T, we will treat the matrix as if it is in perspective, even though it stills behaves like its affine.
    void
    postConcat(Matrixc rhs)
    Post-multiply this matrix by the given rhs matrix.
    void
    postRotate(float angle)
    Post-rotates this matrix about the Z-axis with the given angle in radians.
    void
    postScale(float sx, float sy)
    Post-multiply scaling to this matrix by scaling the base axes by the given x, y and z factors.
    void
    postShear(float sx, float sy)
    Post-multiplied this matrix by a shearing matrix (sx, sy) about pivot point (0, 0).
    void
    postTranslate(float dx, float dy)
    Post-translates this matrix by given changes.
    void
    preConcat(Matrixc lhs)
    Pre-multiply this matrix by the given lhs matrix.
    void
    preRotate(float angle)
    Rotates this matrix about the Z-axis with the given angle in radians.
    void
    preScale(float sx, float sy)
    Apply scaling to this matrix by scaling the base axes by the given x, y and z factors.
    boolean
    preservesRightAngles()
    Returns true if this matrix contains only translation, rotation, reflection, and scale.
    void
    preShear(float sx, float sy)
    Pre-multiplied this matrix by a shearing matrix (sx, sy) about pivot point (0, 0).
    void
    preTranslate(float dx, float dy)
    Translates this matrix by given changes.
    void
    set(float[] a)
    Set the values in the matrix using a float array that contains the matrix elements in row-major order.
    void
    set(float[] a, int offset)
    Set the values in the matrix using a float array that contains the matrix elements in row-major order.
    void
    set(float scaleX, float shearY, float persp0, float shearX, float scaleY, float persp1, float transX, float transY, float persp2)
    Sets all values from parameters.
    void
    set(long p)
    Set the values in the matrix using an address that contains the matrix elements in row-major order (UNSAFE).
    void
    set(Matrixc m)
    Store the values of the given matrix into this matrix.
    void
    set(ByteBuffer a)
    Set the values in the matrix using a float array that contains the matrix elements in row-major order.
    void
    set(FloatBuffer a)
    Set the values in the matrix using a float array that contains the matrix elements in row-major order.
    void
    setIdentity()
    Reset this matrix to the identity.
    void
    setPerspX(float perspX)
    Set the perspX value.
    void
    setPerspY(float perspY)
    Set the perspY value.
    void
    setRectToRect(Rect2fc src, Rect2fc dst)
    Sets matrix to scale and translate src rect to dst rect.
    void
    setRotate(float angle)
    Set this matrix to rotate by radians about a pivot point at (0, 0).
    void
    setRotate(float angle, float px, float py)
    Set this matrix to rotate by radians about a pivot point at (px, py).
    void
    setScale(float sx, float sy)
    Set this matrix to scale by sx and sy about at pivot point at (0, 0).
    void
    setScale(float sx, float sy, float px, float py)
    Set this matrix to scale by sx and sy, about a pivot point at (px, py).
    void
    setScaleTranslate(float sx, float sy, float tx, float ty)
    Reset this matrix with scale and translate elements.
    void
    setScaleX(float scaleX)
    Set the scaleX value.
    void
    setScaleY(float scaleY)
    Set the scaleY value.
    void
    setShear(float sx, float sy)
    Set this matrix to shear by kx and ky, about a pivot point at (0, 0).
    void
    setShear(float sx, float sy, float px, float py)
    Set this matrix to shear by kx and ky, about a pivot point at (px, py).
    void
    setShearX(float shearX)
    Set the shearX value.
    void
    setShearY(float shearY)
    Set the shearY value.
    void
    setSinCos(float sin, float cos)
    Set this matrix to rotate by sinValue and cosValue, about a pivot point at (0, 0).
    void
    setSinCos(float sin, float cos, float px, float py)
    Set this matrix to rotate by sinValue and cosValue, about a pivot point at (px, py).
    void
    setTranslate(float dx, float dy)
    Set this matrix to be a simple translation matrix.
    void
    setTranslateX(float transX)
    Set the transX value.
    void
    setTranslateY(float transY)
    Set the transY value.
    void
    store(float[] a)
    Store this matrix into the give float array in row-major order.
    void
    store(float[] a, int offset)
    Store this matrix into the give float array in row-major order.
    void
    store(long p)
    Get this matrix data, store them into an address (UNSAFE).
    void
    store(Matrix dst)
    Store this matrix elements to the given matrix.
    void
    store(ByteBuffer a)
    Store this matrix into the give float array in row-major order.
    void
    store(FloatBuffer a)
    Store this matrix into the give float array in row-major order.
    void
    storeAligned(long p)
    Get this matrix data, store them into an address (UNSAFE).
    void
    storeAligned(ByteBuffer a)
    Store this matrix into the give float array in row-major order.
    void
    storeAligned(FloatBuffer a)
    Store this matrix into the give float array in row-major order.
    Matrix4
    toMatrix4()
    Converts this 3x3 matrix to 4x4 matrix, the third row and column are identity.
    void
    toMatrix4(Matrix4 dest)
    Converts this 3x3 matrix to 4x4 matrix, the third row and column are identity.
    String
    toString()
     
    float
    trace()
    Compute the trace of this matrix.

    Methods inherited from class java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait

    Methods inherited from interface icyllis.arc3d.core.Matrixc

    mapPoint, mapPoints, mapPoints, mapPoints, mapPoints, mapRect, mapRect, mapRect, mapRect, mapRectOut, mapRectOut, mapRectOut

  • Field Details

    • m11

      protected float m11

    • m12

      protected float m12

    • m14

      protected float m14

    • m21

      protected float m21

    • m22

      protected float m22

    • m24

      protected float m24

    • m41

      protected float m41

    • m42

      protected float m42

    • m44

      protected float m44

  • Constructor Details

    • Matrix

      public Matrix()
      Create a new identity matrix.

    • Matrix

      public Matrix(@Nonnull Matrixc m)
      Create a new matrix copied from the given matrix.

    • Matrix

      public Matrix(float scaleX, float shearY, float persp0, float shearX, float scaleY, float persp1, float transX, float transY, float persp2)
      Create a new matrix from the given elements. The order matches GLSL's column major.
      Parameters:
      scaleX - the value of m11
      shearY - the value of m12
      persp0 - the value of m14
      shearX - the value of m21
      scaleY - the value of m22
      persp1 - the value of m24
      transX - the value of m41
      transY - the value of m42
      persp2 - the value of m44

  • Method Details

    • identity

      @Nonnull public static Matrixc identity()
      Returns a read-only identity matrix.
      Returns:
      an identity matrix

    • makeTranslate

      @Nonnull public static Matrix makeTranslate(float dx, float dy)
      Creates a new translate-only matrix.
      Returns:
      a translation matrix

    • makeScale

      @Nonnull public static Matrix makeScale(float sx, float sy)
      Creates a new scale-only matrix.
      Returns:
      a scaling matrix

    • m11

      public float m11()
      Same as getScaleX().
      Specified by:
      m11 in interface Matrixc

    • m12

      public float m12()
      Same as getShearY().
      Specified by:
      m12 in interface Matrixc

    • m14

      public float m14()
      Same as getPerspX().
      Specified by:
      m14 in interface Matrixc

    • m21

      public float m21()
      Same as getShearX().
      Specified by:
      m21 in interface Matrixc

    • m22

      public float m22()
      Same as getScaleY().
      Specified by:
      m22 in interface Matrixc

    • m24

      public float m24()
      Same as getPerspY().
      Specified by:
      m24 in interface Matrixc

    • m41

      public float m41()
      Same as getTranslateX().
      Specified by:
      m41 in interface Matrixc

    • m42

      public float m42()
      Same as getTranslateY().
      Specified by:
      m42 in interface Matrixc

    • m44

      public float m44()
      Returns the last element of the matrix, the perspective bias.
      Specified by:
      m44 in interface Matrixc

    • getScaleX

      public float getScaleX()
      Returns scale factor multiplied by x-axis input, contributing to x-axis output. With mapPoints(), scales Point along the x-axis.
      Specified by:
      getScaleX in interface Matrixc
      Returns:
      horizontal scale factor

    • getScaleY

      public float getScaleY()
      Returns scale factor multiplied by y-axis input, contributing to y-axis output. With mapPoints(), scales Point along the y-axis.
      Specified by:
      getScaleY in interface Matrixc
      Returns:
      vertical scale factor

    • getShearY

      public float getShearY()
      Returns scale factor multiplied by x-axis input, contributing to y-axis output. With mapPoints(), shears Point along the y-axis. Shearing both axes can rotate Point.
      Specified by:
      getShearY in interface Matrixc
      Returns:
      vertical shear factor

    • getShearX

      public float getShearX()
      Returns scale factor multiplied by y-axis input, contributing to x-axis output. With mapPoints(), shears Point along the x-axis. Shearing both axes can rotate Point.
      Specified by:
      getShearX in interface Matrixc
      Returns:
      horizontal shear factor

    • getTranslateX

      public float getTranslateX()
      Returns translation contributing to x-axis output. With mapPoints(), moves Point along the x-axis.
      Specified by:
      getTranslateX in interface Matrixc
      Returns:
      horizontal translation factor

    • getTranslateY

      public float getTranslateY()
      Returns translation contributing to y-axis output. With mapPoints(), moves Point along the y-axis.
      Specified by:
      getTranslateY in interface Matrixc
      Returns:
      vertical translation factor

    • getPerspX

      public float getPerspX()
      Returns factor scaling input x-axis relative to input y-axis.
      Specified by:
      getPerspX in interface Matrixc
      Returns:
      input x-axis perspective factor

    • getPerspY

      public float getPerspY()
      Returns factor scaling input y-axis relative to input x-axis.
      Specified by:
      getPerspY in interface Matrixc
      Returns:
      input y-axis perspective factor

    • getType

      public int getType()
      Returns a bit field describing the transformations the matrix may perform. The bit field is computed conservatively, so it may include false positives. For example, when Perspective_Mask is set, all other bits are set.
      Specified by:
      getType in interface Matrixc
      Returns:
      Identity_Mask, or combinations of: Translate_Mask, Scale_Mask, Affine_Mask, Perspective_Mask

    • isIdentity

      public boolean isIdentity()
      Returns true if this matrix is identity.
      Specified by:
      isIdentity in interface Matrixc
      Returns:
      true if this matrix is identity.

    • isScaleTranslate

      public boolean isScaleTranslate()
      Returns whether this matrix at most scales and translates.
      Specified by:
      isScaleTranslate in interface Matrixc
      Returns:
      true if this matrix is scales, translates, or both.

    • isTranslate

      public boolean isTranslate()
      Returns whether this matrix is identity, or translates.
      Specified by:
      isTranslate in interface Matrixc
      Returns:
      true if this matrix is identity, or translates

    • isAxisAligned

      public boolean isAxisAligned()
      Returns whether this matrix transforms rect to another rect. If true, this matrix is identity, or/and scales, or mirrors on axes. In all cases, this matrix is affine and may also have translation.
      Specified by:
      isAxisAligned in interface Matrixc
      Returns:
      true if this matrix transform one rect into another

    • preservesRightAngles

      public boolean preservesRightAngles()
      Returns true if this matrix contains only translation, rotation, reflection, and scale. Scale may differ along rotated axes.
      Returns false if this matrix shearing, perspective, or degenerate forms that collapse to a line or point.

      Preserves right angles, but not requiring that the arms of the angle retain equal lengths.

      Specified by:
      preservesRightAngles in interface Matrixc
      Returns:
      true if this matrix only rotates, scales, translates

    • hasPerspective

      public boolean hasPerspective()
      Returns whether this matrix contains perspective elements.
      Specified by:
      hasPerspective in interface Matrixc
      Returns:
      true if this matrix is in most general form

    • isSimilarity

      public boolean isSimilarity()
      Returns true if this matrix contains only translation, rotation, reflection, and uniform scale. Returns false if this matrix contains different scales, shearing, perspective, or degenerate forms that collapse to a line or point.

      Describes that the matrix makes rendering with and without the matrix are visually alike; a transformed circle remains a circle. Mathematically, this is referred to as similarity of a Euclidean space, or a similarity transformation.

      Preserves right angles, keeping the arms of the angle equal lengths.

      Specified by:
      isSimilarity in interface Matrixc
      Returns:
      true if this matrix only rotates, uniformly scales, translates

    • preConcat

      public void preConcat(@Nonnull Matrixc lhs)
      Pre-multiply this matrix by the given lhs matrix.

      If M is this matrix and L the lhs matrix, then the new matrix will be L * M (row-major). So when transforming a vector v with the new matrix by using v * L * M, the transformation of the left-hand side matrix will be applied first.

      Parameters:
      lhs - the left-hand side matrix to multiply

    • postConcat

      public void postConcat(@Nonnull Matrixc rhs)
      Post-multiply this matrix by the given rhs matrix.

      If M is this matrix and R the rhs matrix, then the new matrix will be M * R (row-major). So when transforming a vector v with the new matrix by using v * M * R, the transformation of this matrix will be applied first.

      Parameters:
      rhs - the right-hand side matrix to multiply

    • setIdentity

      public void setIdentity()
      Reset this matrix to the identity.

    • setScaleTranslate

      public void setScaleTranslate(float sx, float sy, float tx, float ty)
      Reset this matrix with scale and translate elements.
      Parameters:
      sx - horizontal scale factor to store
      sy - vertical scale factor to store
      tx - horizontal translation to store
      ty - vertical translation to store

    • m11

      public void m11(float scaleX)
      Set the scaleX value.

    • m12

      public void m12(float shearY)
      Set the shearY value.

    • m14

      public void m14(float persp0)
      Set the persp0 value.

    • m21

      public void m21(float shearX)
      Set the shearX value.

    • m22

      public void m22(float scaleY)
      Set the scaleY value.

    • m24

      public void m24(float persp1)
      Set the persp1 value.

    • m41

      public void m41(float transX)
      Set the transX value.

    • m42

      public void m42(float transY)
      Set the transY value.

    • m44

      public void m44(float persp2)
      Set the persp2 value.

    • setScaleX

      public void setScaleX(float scaleX)
      Set the scaleX value.

    • setScaleY

      public void setScaleY(float scaleY)
      Set the scaleY value.

    • setShearY

      public void setShearY(float shearY)
      Set the shearY value.

    • setShearX

      public void setShearX(float shearX)
      Set the shearX value.

    • setTranslateX

      public void setTranslateX(float transX)
      Set the transX value.

    • setTranslateY

      public void setTranslateY(float transY)
      Set the transY value.

    • setPerspY

      public void setPerspY(float perspY)
      Set the perspY value.

    • setPerspX

      public void setPerspX(float perspX)
      Set the perspX value.

    • set

      public void set(@Nonnull Matrixc m)
      Store the values of the given matrix into this matrix.
      Parameters:
      m - the matrix to copy from

    • set

      public void set(float scaleX, float shearY, float persp0, float shearX, float scaleY, float persp1, float transX, float transY, float persp2)
      Sets all values from parameters.
      Parameters:
      scaleX - horizontal scale factor to store
      shearY - vertical shear factor to store
      persp0 - input x-axis values perspective factor to store
      shearX - horizontal shear factor to store
      scaleY - vertical scale factor to store
      persp1 - input y-axis values perspective factor to store
      transX - horizontal translation to store
      transY - vertical translation to store
      persp2 - perspective scale factor to store

    • set

      public void set(@Nonnull float[] a)
      Set the values in the matrix using a float array that contains the matrix elements in row-major order.
      Parameters:
      a - the array to copy from

    • set

      public void set(@Nonnull float[] a, int offset)
      Set the values in the matrix using a float array that contains the matrix elements in row-major order.
      Parameters:
      a - the array to copy from
      offset - the element offset

    • set

      public void set(@Nonnull ByteBuffer a)
      Set the values in the matrix using a float array that contains the matrix elements in row-major order.
      Parameters:
      a - the array to copy from

    • set

      public void set(@Nonnull FloatBuffer a)
      Set the values in the matrix using a float array that contains the matrix elements in row-major order.
      Parameters:
      a - the array to copy from

    • set

      public void set(long p)
      Set the values in the matrix using an address that contains the matrix elements in row-major order (UNSAFE).
      Parameters:
      p - the pointer of the array to copy from

    • store

      public void store(@Nonnull Matrix dst)
      Store this matrix elements to the given matrix.
      Specified by:
      store in interface Matrixc
      Parameters:
      dst - the matrix to store

    • store

      public void store(@Nonnull float[] a)
      Store this matrix into the give float array in row-major order.
      Specified by:
      store in interface Matrixc
      Parameters:
      a - the array to store into

    • store

      public void store(@Nonnull float[] a, int offset)
      Store this matrix into the give float array in row-major order.
      Specified by:
      store in interface Matrixc
      Parameters:
      a - the array to store into
      offset - the element offset

    • store

      public void store(@Nonnull ByteBuffer a)
      Store this matrix into the give float array in row-major order.
      Specified by:
      store in interface Matrixc
      Parameters:
      a - the pointer of the array to store

    • storeAligned

      public void storeAligned(@Nonnull ByteBuffer a)
      Store this matrix into the give float array in row-major order. The data matches std140 layout so it is not tightly packed.
      Specified by:
      storeAligned in interface Matrixc
      Parameters:
      a - the pointer of the array to store

    • store

      public void store(@Nonnull FloatBuffer a)
      Store this matrix into the give float array in row-major order.
      Specified by:
      store in interface Matrixc
      Parameters:
      a - the pointer of the array to store

    • storeAligned

      public void storeAligned(@Nonnull FloatBuffer a)
      Store this matrix into the give float array in row-major order. The data matches std140 layout so it is not tightly packed.
      Specified by:
      storeAligned in interface Matrixc
      Parameters:
      a - the pointer of the array to store

    • store

      public void store(long p)
      Get this matrix data, store them into an address (UNSAFE). NOTE: This method does not perform memory security checks.
      Specified by:
      store in interface Matrixc
      Parameters:
      p - the pointer of the array to store

    • storeAligned

      public void storeAligned(long p)
      Get this matrix data, store them into an address (UNSAFE). The data matches std140 layout so it is not tightly packed. NOTE: This method does not perform memory security checks.
      Specified by:
      storeAligned in interface Matrixc
      Parameters:
      p - the pointer of the array to store, must be aligned

    • toMatrix4

      public void toMatrix4(@Nonnull Matrix4 dest)
      Converts this 3x3 matrix to 4x4 matrix, the third row and column are identity. 
      
 [ a b c ]      [ a b 0 c ]
 [ d e f ]  ->  [ d e 0 f ]
 [ g h i ]      [ 0 0 1 0 ]
                [ g h 0 i ]
      Specified by:
      toMatrix4 in interface Matrixc

    • toMatrix4

      @Nonnull public Matrix4 toMatrix4()
      Converts this 3x3 matrix to 4x4 matrix, the third row and column are identity. 
      
 [ a b c ]      [ a b 0 c ]
 [ d e f ]  ->  [ d e 0 f ]
 [ g h i ]      [ 0 0 1 0 ]
                [ g h 0 i ]
      Specified by:
      toMatrix4 in interface Matrixc

    • determinant

      public float determinant()
      Return the determinant of this matrix.
      Returns:
      the determinant

    • trace

      public float trace()
      Compute the trace of this matrix.
      Returns:
      the trace of this matrix

    • invert

      @CheckReturnValue public boolean invert()
      Compute the inverse of this matrix. This matrix will be inverted if this matrix is invertible, otherwise its values will be preserved.
      Returns:
      true if this matrix is invertible.

    • invert

      public boolean invert(@Nullable Matrix dest)
      Compute the inverse of this matrix. The dest matrix will be the inverse of this matrix if this matrix is invertible, otherwise its values will be preserved.
      Specified by:
      invert in interface Matrixc
      Parameters:
      dest - the destination matrix, may be null
      Returns:
      true if this matrix is invertible.

    • preTranslate

      public void preTranslate(float dx, float dy)
      Translates this matrix by given changes. This is equivalent to pre-multiplying by a translation matrix.
      Parameters:
      dx - the x-component of the translation
      dy - the y-component of the translation

    • postTranslate

      public void postTranslate(float dx, float dy)
      Post-translates this matrix by given changes. This is equivalent to post-multiplying by a translation matrix.
      Parameters:
      dx - the x-component of the translation
      dy - the y-component of the translation

    • setTranslate

      public void setTranslate(float dx, float dy)
      Set this matrix to be a simple translation matrix.
      Parameters:
      dx - the x-component of the translation
      dy - the y-component of the translation

    • preScale

      public void preScale(float sx, float sy)
      Apply scaling to this matrix by scaling the base axes by the given x, y and z factors.

      If M is this matrix and S the scaling matrix, then the new matrix will be S * M (row-major). So when transforming a vector v with the new matrix by using v * S * M, the scaling will be applied first.

      Parameters:
      sx - the x-component of the scale
      sy - the y-component of the scale

    • postScale

      public void postScale(float sx, float sy)
      Post-multiply scaling to this matrix by scaling the base axes by the given x, y and z factors.

      If M is this matrix and S the scaling matrix, then the new matrix will be M * S (row-major). So when transforming a vector v with the new matrix by using v * M * S, the scaling will be applied last.

      Parameters:
      sx - the x-component of the scale
      sy - the y-component of the scale

    • setScale

      public void setScale(float sx, float sy)
      Set this matrix to scale by sx and sy about at pivot point at (0, 0).
      Parameters:
      sx - horizontal scale factor
      sy - vertical scale factor

    • setScale

      public void setScale(float sx, float sy, float px, float py)
      Set this matrix to scale by sx and sy, about a pivot point at (px, py). The pivot point is unchanged when mapped with this matrix.
      Parameters:
      sx - horizontal scale factor
      sy - vertical scale factor
      px - pivot on x-axis
      py - pivot on y-axis

    • preRotate

      public void preRotate(float angle)
      Rotates this matrix about the Z-axis with the given angle in radians.

      When used with a right-handed coordinate system, the produced rotation will rotate a vector counter-clockwise around the rotation axis, when viewing along the negative axis direction towards the origin. When used with a left-handed coordinate system, the rotation is clockwise.

      This is equivalent to pre-multiplying by a rotation matrix.

      cosθ sinθ 0
      -sinθ cosθ 0
      0 0 1
      Parameters:
      angle - the rotation angle in radians.

    • postRotate

      public void postRotate(float angle)
      Post-rotates this matrix about the Z-axis with the given angle in radians.

      When used with a right-handed coordinate system, the produced rotation will rotate a vector counter-clockwise around the rotation axis, when viewing along the negative axis direction towards the origin. When used with a left-handed coordinate system, the rotation is clockwise.

      This is equivalent to post-multiplying by a rotation matrix.

      cosθ sinθ 0
      -sinθ cosθ 0
      0 0 1
      Parameters:
      angle - the rotation angle in radians.

    • setRotate

      public void setRotate(float angle)
      Set this matrix to rotate by radians about a pivot point at (0, 0). Positive radians rotates clockwise.
      Parameters:
      angle - angle of axes relative to upright axes

    • setRotate

      public void setRotate(float angle, float px, float py)
      Set this matrix to rotate by radians about a pivot point at (px, py). The pivot point is unchanged when mapped with this matrix.

      Positive radians rotates clockwise.

      Parameters:
      angle - angle of axes relative to upright axes
      px - pivot on x-axis
      py - pivot on y-axis

    • setSinCos

      public void setSinCos(float sin, float cos)
      Set this matrix to rotate by sinValue and cosValue, about a pivot point at (0, 0).
      Parameters:
      sin - rotation vector x-axis component
      cos - rotation vector y-axis component

    • setSinCos

      public void setSinCos(float sin, float cos, float px, float py)
      Set this matrix to rotate by sinValue and cosValue, about a pivot point at (px, py). The pivot point is unchanged when mapped with this matrix.
      Parameters:
      sin - rotation vector x-axis component
      cos - rotation vector y-axis component
      px - pivot on x-axis
      py - pivot on y-axis

    • preShear

      public void preShear(float sx, float sy)
      Pre-multiplied this matrix by a shearing matrix (sx, sy) about pivot point (0, 0).
      Parameters:
      sx - horizontal shear factor
      sy - vertical shear factor

    • postShear

      public void postShear(float sx, float sy)
      Post-multiplied this matrix by a shearing matrix (sx, sy) about pivot point (0, 0).
      Parameters:
      sx - horizontal shear factor
      sy - vertical shear factor

    • setShear

      public void setShear(float sx, float sy)
      Set this matrix to shear by kx and ky, about a pivot point at (0, 0).
      Parameters:
      sx - horizontal shear factor
      sy - vertical shear factor

    • setShear

      public void setShear(float sx, float sy, float px, float py)
      Set this matrix to shear by kx and ky, about a pivot point at (px, py). The pivot point is unchanged when mapped with this matrix.
      Parameters:
      sx - horizontal shear factor
      sy - vertical shear factor
      px - pivot on x-axis
      py - pivot on y-axis

    • mapRect

      public boolean mapRect(@Nonnull Rect2fc src, @Nonnull Rect2f dst)
      Sets dst to bounds of src corners mapped by this matrix. Returns true if mapped corners are dst corners.
      Specified by:
      mapRect in interface Matrixc

    • mapRect

      public void mapRect(float left, float top, float right, float bottom, @Nonnull Rect2i dst)
      Map a rectangle points in the X-Y plane to get the maximum bounds.
      Specified by:
      mapRect in interface Matrixc
      Parameters:
      dst - the round values

    • mapRectOut

      public void mapRectOut(float left, float top, float right, float bottom, @Nonnull Rect2i dst)
      Map a rectangle points in the X-Y plane to get the maximum bounds.
      Specified by:
      mapRectOut in interface Matrixc
      Parameters:
      dst - the round out values

    • mapPoints

      public void mapPoints(float[] src, int srcPos, float[] dst, int dstPos, int count)
      Maps src point array of length count to dst point array of equal or greater length. Points are mapped by multiplying each point by this matrix. Given: 
        | A B C |        | x |
  | D E F |,  pt = | y |
  | G H I |        | 1 |
      where 
        for (i = 0; i invalid input: '<' count; ++i) {
      x = src[srcPos + (i invalid input: '<'invalid input: '<' 1)]
      y = src[srcPos + (i invalid input: '<'invalid input: '<' 1) + 1]
  }
      each dst point is computed as: 
        |A B C| |x|                               Ax+By+C   Dx+Ey+F
  |D E F| |y| = |Ax+By+C Dx+Ey+F Gx+Hy+I| = ------- , -------
  |G H I| |1|                               Gx+Hy+I   Gx+Hy+I

      src and dst may point to the same array.

      Specified by:
      mapPoints in interface Matrixc
      Parameters:
      src - points to transform
      dst - array for mapped points
      count - number of points to transform

    • getMinScale

      public float getMinScale()
      Returns the minimum scaling factor of this matrix by decomposing the scaling and shearing elements.
      Returns -1 if scale factor overflows or this matrix contains perspective.
      Specified by:
      getMinScale in interface Matrixc
      Returns:
      minimum scale factor

    • getMaxScale

      public float getMaxScale()
      Returns the maximum scaling factor of this matrix by decomposing the scaling and shearing elements.
      Returns -1 if scale factor overflows or this matrix contains perspective.
      Specified by:
      getMaxScale in interface Matrixc
      Returns:
      maximum scale factor

    • getMinScale

      public float getMinScale(float px, float py)
      Returns the minimum scaling factor of this matrix by decomposing the scaling and shearing elements. When this matrix has perspective, the scaling factor is specific to the given point p.
      Returns -1 if scale factor overflows.
      Specified by:
      getMinScale in interface Matrixc
      Parameters:
      px - the x-coord of point
      py - the y-coord of point
      Returns:
      minimum scale factor

    • getMaxScale

      public float getMaxScale(float px, float py)
      Returns the maximum scaling factor of this matrix by decomposing the scaling and shearing elements. When this matrix has perspective, the scaling factor is specific to the given point p.
      Returns -1 if scale factor overflows.
      Specified by:
      getMaxScale in interface Matrixc
      Parameters:
      px - the x-coord of point
      py - the y-coord of point
      Returns:
      maximum scale factor

    • differentialAreaScale

      public float differentialAreaScale(float px, float py)
      Returns the differential area scale factor for a local point 'p' that will be transformed by 'm' (which may have perspective). If 'm' does not have perspective, this scale factor is constant regardless of 'p'; when it does have perspective, it is specific to that point.

      This can be crudely thought of as "device pixel area" / "local pixel area" at 'p'.

      Returns positive infinity if the transformed homogeneous point has w invalid input: '<'= 0.

      The return value is equivalent to getMinScale(float, float) times getMaxScale(float, float).

      Specified by:
      differentialAreaScale in interface Matrixc
      Parameters:
      px - the x-coord of point
      py - the y-coord of point

    • localAARadius

      public float localAARadius(Rect2fc bounds)
      Return the minimum distance needed to move in local (pre-transform) space to ensure that the transformed coordinates are at least 1px away from the original mapped point. This minimum distance is specific to the given local 'bounds' since the scale factors change with perspective.

      If the bounds will be clipped by the w=0 plane or otherwise is ill-conditioned, this will return positive infinity.

      Specified by:
      localAARadius in interface Matrixc

    • localAARadius

      public float localAARadius(float left, float top, float right, float bottom)
      Return the minimum distance needed to move in local (pre-transform) space to ensure that the transformed coordinates are at least 1px away from the original mapped point. This minimum distance is specific to the given local 'bounds' since the scale factors change with perspective.

      If the bounds will be clipped by the w=0 plane or otherwise is ill-conditioned, this will return positive infinity.

      Specified by:
      localAARadius in interface Matrixc

    • setRectToRect

      public void setRectToRect(Rect2fc src, Rect2fc dst)
      Sets matrix to scale and translate src rect to dst rect. Returns false if src is empty, and sets matrix to identity. Returns true if dst is empty, and sets matrix to: 
       | 0 0 0 |
 | 0 0 0 |
 | 0 0 1 |
      Parameters:
      src - rect to map from
      dst - rect to map to

    • normalizePerspective

      public void normalizePerspective()
      If the last column of the matrix is [0, 0, not_one]^T, we will treat the matrix as if it is in perspective, even though it stills behaves like its affine. If we divide everything by the not_one value, then it will behave the same, but will be treated as affine, and therefore faster (e.g. clients can forward-difference calculations).

    • isFinite

      public boolean isFinite()
      Returns true if all elements of the matrix are finite. Returns false if any element is infinity, or NaN.
      Specified by:
      isFinite in interface Matrixc
      Returns:
      true if matrix has only finite elements

    • isApproxEqual

      public boolean isApproxEqual(@Nonnull Matrix m)
      Returns whether this matrix elements are equivalent to given matrix.
      Parameters:
      m - the matrix to compare.
      Returns:
      true if this matrix is equivalent to other matrix.

    • equals

      public static boolean equals(@Nonnull Matrixc a, @Nonnull Matrixc b)
      Returns whether two matrices' elements are equal, using == operator. Note -0.0f == 0.0f is true. getType() is ignored.

      Keep consistent with equals(Object).

    • hashCode

      public int hashCode()
      Specified by:
      hashCode in interface Matrixc
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object o)
      Returns whether this matrix elements are equal to another matrix, using == operator. Note -0.0f == 0.0f is true. getType() is ignored.
      Specified by:
      equals in interface Matrixc
      Overrides:
      equals in class Object
      Parameters:
      o - the reference object with which to compare.
      Returns:
      true if this object is the same as the o values.

    • toString

      public String toString()
      Specified by:
      toString in interface Matrixc
      Overrides:
      toString in class Object

    • clone

      @Nonnull public Matrix clone()
      Specified by:
      clone in interface Matrixc
      Overrides:
      clone in class Object
      Returns:
      a copy of this matrix