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:

  • 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:

    • 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:

    • 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:

    • 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:

    • 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:

  • 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

      default void mapPoints(float[] pts)
      See Also:

    • mapPoints

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

    • mapPoints

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

    • mapPoints

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

    • 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()