Package icyllis.arc3d.core

# Interface Matrixc

All Known Implementing Classes:
  `Matrix`, `Matrix`

public sealed interface Matrixc permits Matrix
Interface to a read-only view of a 3x3 matrix for 2D transformation. This does not mean that the matrix is immutable, it only implies that a method should not change the state of the matrix.

`Matrix const &matrix`

See Also:
  - `Matrix`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `kAffine_Mask`
  TypeMask
  `static final int`
  `kIdentity_Mask`
  TypeMask
  `static final int`
  `kPerspective_Mask`
  TypeMask
  `static final int`
  `kScale_Mask`
  TypeMask
  `static final int`
  `kTranslate_Mask`
  TypeMask

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Matrix`
  `clone()`
  `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).
  `boolean`
  `equals(Object o)`
  `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.
  `boolean`
  `invert(Matrix dest)`
  Compute the inverse of this 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()`.
  `float`
  `m12()`
  Same as `getShearY()`.
  `float`
  `m14()`
  Same as `getPerspX()`.
  `float`
  `m21()`
  Same as `getShearX()`.
  `float`
  `m22()`
  Same as `getScaleY()`.
  `float`
  `m24()`
  Same as `getPerspY()`.
  `float`
  `m41()`
  Same as `getTranslateX()`.
  `float`
  `m42()`
  Same as `getTranslateY()`.
  `float`
  `m44()`
  Returns the last element of the matrix, the perspective bias.
  `default void`
  `mapPoint(float[] p)`
  `default void`
  `mapPoints(float[] pts)`
  `default void`
  `mapPoints(float[] src, float[] dst, int count)`
  `default void`
  `mapPoints(float[] pts, int count)`
  `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.
  `default void`
  `mapPoints(float[] pts, int pos, int count)`
  `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.
  `default boolean`
  `mapRect(Rect2f rect)`
  Sets rect to bounds of rect corners mapped by this matrix.
  `boolean`
  `mapRect(Rect2fc src, Rect2f dst)`
  Sets dst to bounds of src corners mapped by this matrix.
  `default void`
  `mapRect(Rect2fc r, Rect2i out)`
  Map a rectangle points in the X-Y plane to get the maximum bounds.
  `default void`
  `mapRect(Rect2i r)`
  Map a rectangle points in the X-Y plane to get the maximum bounds.
  `default void`
  `mapRect(Rect2ic r, Rect2i out)`
  Map a rectangle points in the X-Y plane to get the maximum bounds.
  `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.
  `default void`
  `mapRectOut(Rect2fc r, Rect2i dst)`
  Map a rectangle points in the X-Y plane to get the maximum bounds.
  `default void`
  `mapRectOut(Rect2i r)`
  Map a rectangle points in the X-Y plane to get the maximum bounds.
  `default void`
  `mapRectOut(Rect2ic r, Rect2i dst)`
  Map a rectangle points in the X-Y plane to get the maximum bounds.
  `boolean`
  `preservesRightAngles()`
  Returns true if this matrix contains only translation, rotation, reflection, and scale.
  `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()`

- ## Field Details

  - ### kIdentity_Mask

    static final int kIdentity_Mask
    TypeMask

    Enum of bit fields for mask returned by `getType()`. Used to identify the complexity of Matrix, for optimizations.

    See Also:
      - Constant Field Values

  - ### kTranslate_Mask

    static final int kTranslate_Mask
    TypeMask

    Enum of bit fields for mask returned by `getType()`. Used to identify the complexity of Matrix, for optimizations.

    See Also:
      - Constant Field Values

  - ### kScale_Mask

    static final int kScale_Mask
    TypeMask

    Enum of bit fields for mask returned by `getType()`. Used to identify the complexity of Matrix, for optimizations.

    See Also:
      - Constant Field Values

  - ### kAffine_Mask

    static final int kAffine_Mask
    TypeMask

    Enum of bit fields for mask returned by `getType()`. Used to identify the complexity of Matrix, for optimizations.

    See Also:
      - Constant Field Values

  - ### kPerspective_Mask

    static final int kPerspective_Mask
    TypeMask

    Enum of bit fields for mask returned by `getType()`. Used to identify the complexity of Matrix, for optimizations.

    See Also:
      - Constant Field Values

- ## Method Details

  - ### getType

    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.
    Returns:
      Identity_Mask, or combinations of: Translate_Mask, Scale_Mask, Affine_Mask, Perspective_Mask

  - ### isIdentity

    boolean isIdentity()
    Returns true if this matrix is identity.
    Returns:
      `true` if this matrix is identity.

  - ### isScaleTranslate

    boolean isScaleTranslate()
    Returns whether this matrix at most scales and translates.
    Returns:
      `true` if this matrix is scales, translates, or both.

  - ### isTranslate

    boolean isTranslate()
    Returns whether this matrix is identity, or translates.
    Returns:
      `true` if this matrix is identity, or translates

  - ### isAxisAligned

    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.
    Returns:
      true if this matrix transform one rect into another

  - ### preservesRightAngles

    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.

    Returns:
      true if this matrix only rotates, scales, translates

  - ### hasPerspective

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

  - ### isSimilarity

    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.

    Returns:
      true if this matrix only rotates, uniformly scales, translates

  - ### m11

    float m11()
    Same as `getScaleX()`.

  - ### m12

    float m12()
    Same as `getShearY()`.

  - ### m14

    float m14()
    Same as `getPerspX()`.

  - ### m21

    float m21()
    Same as `getShearX()`.

  - ### m22

    float m22()
    Same as `getScaleY()`.

  - ### m24

    float m24()
    Same as `getPerspY()`.

  - ### m41

    float m41()
    Same as `getTranslateX()`.

  - ### m42

    float m42()
    Same as `getTranslateY()`.

  - ### m44

    float m44()
    Returns the last element of the matrix, the perspective bias.

  - ### getScaleX

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

  - ### getScaleY

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

  - ### getShearY

    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.
    Returns:
      vertical shear factor

  - ### getShearX

    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.
    Returns:
      horizontal shear factor

  - ### getTranslateX

    float getTranslateX()
    Returns translation contributing to x-axis output. With mapPoints(), moves Point along the x-axis.
    Returns:
      horizontal translation factor

  - ### getTranslateY

    float getTranslateY()
    Returns translation contributing to y-axis output. With mapPoints(), moves Point along the y-axis.
    Returns:
      vertical translation factor

  - ### getPerspX

    float getPerspX()
    Returns factor scaling input x-axis relative to input y-axis.
    Returns:
      input x-axis perspective factor

  - ### getPerspY

    float getPerspY()
    Returns factor scaling input y-axis relative to input x-axis.
    Returns:
      input y-axis perspective factor

  - ### store

    void store(@Nonnull Matrix dst)
    Store this matrix elements to the given matrix.
    Parameters:
      `dst` - the matrix to store

  - ### store

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

  - ### store

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

  - ### store

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

  - ### storeAligned

    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.
    Parameters:
      `a` - the pointer of the array to store

  - ### store

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

  - ### storeAligned

    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.
    Parameters:
      `a` - the pointer of the array to store

  - ### store

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

  - ### storeAligned

    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.
    Parameters:
      `p` - the pointer of the array to store, must be aligned

  - ### toMatrix4

    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 ]

  - ### toMatrix4

    @Nonnull 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 ]

  - ### invert

    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.
    Parameters:
      `dest` - the destination matrix, may be null
    Returns:
      `true` if this matrix is invertible.

  - ### mapRect

    default boolean mapRect(@Nonnull Rect2f rect)
    Sets rect to bounds of rect corners mapped by this matrix. Returns true if mapped corners are dst corners.

  - ### mapRect

    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.

  - ### mapRect

    default void mapRect(@Nonnull Rect2i r)
    Map a rectangle points in the X-Y plane to get the maximum bounds.

  - ### mapRect

    default void mapRect(@Nonnull Rect2fc r, @Nonnull Rect2i out)
    Map a rectangle points in the X-Y plane to get the maximum bounds.
    Parameters:
      `out` - the round values

  - ### mapRect

    default void mapRect(@Nonnull Rect2ic r, @Nonnull Rect2i out)
    Map a rectangle points in the X-Y plane to get the maximum bounds.
    Parameters:
      `out` - the round values

  - ### mapRect

    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.
    Parameters:
      `dst` - the round values

  - ### mapRectOut

    default void mapRectOut(@Nonnull Rect2i r)
    Map a rectangle points in the X-Y plane to get the maximum bounds.

  - ### mapRectOut

    default void mapRectOut(@Nonnull Rect2ic r, @Nonnull Rect2i dst)
    Map a rectangle points in the X-Y plane to get the maximum bounds.
    Parameters:
      `dst` - the round out values

  - ### mapRectOut

    default void mapRectOut(@Nonnull Rect2fc r, @Nonnull Rect2i dst)
    Map a rectangle points in the X-Y plane to get the maximum bounds.
    Parameters:
      `dst` - the round out values

  - ### mapRectOut

    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.
    Parameters:
      `dst` - the round out values

  - ### mapPoint

    default void mapPoint(float[] p)
    See Also:
      - `mapPoints(float[], int, float[], int, int)`

  - ### mapPoints

    default void mapPoints(float[] pts)
    See Also:
      - `mapPoints(float[], int, float[], int, int)`

  - ### mapPoints

    default void mapPoints(float[] pts, int count)
    See Also:
      - `mapPoints(float[], int, float[], int, int)`

  - ### mapPoints

    default void mapPoints(float[] pts, int pos, int count)
    See Also:
      - `mapPoints(float[], int, float[], int, int)`

  - ### mapPoints

    default void mapPoints(float[] src, float[] dst, int count)
    See Also:
      - `mapPoints(float[], int, float[], int, int)`

  - ### mapPoints

    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.

    Parameters:
      `src` - points to transform
      `dst` - array for mapped points
      `count` - number of points to transform

  - ### getMinScale

    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.
    Returns:
      minimum scale factor

  - ### getMaxScale

    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.
    Returns:
      maximum scale factor

  - ### getMinScale

    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.
    Parameters:
      `px` - the x-coord of point
      `py` - the y-coord of point
    Returns:
      minimum scale factor

  - ### getMaxScale

    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.
    Parameters:
      `px` - the x-coord of point
      `py` - the y-coord of point
    Returns:
      maximum scale factor

  - ### differentialAreaScale

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

    Parameters:
      `px` - the x-coord of point
      `py` - the y-coord of point

  - ### localAARadius

    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.

  - ### localAARadius

    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.

  - ### isFinite

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

  - ### hashCode

    int hashCode()
    Overrides:
      `hashCode` in class `Object`

  - ### equals

    boolean equals(Object o)
    Overrides:
      `equals` in class `Object`

  - ### toString

    String toString()
    Overrides:
      `toString` in class `Object`

  - ### clone

    @Nonnull Matrix clone()