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:
  - `Matrix3`
  - `Matrix4`

- ## 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