Package icyllis.arc3d.core.effects

# Class ColorMatrix

java.lang.Object
icyllis.arc3d.core.effects.ColorMatrix

public class ColorMatrix extends Object
This class represents a 5x4 affine matrix that transforms 4-component colors. The memory layout (order of components) is the same as GLSL's column-major. Interpret first 16 elements as mat4 m and last 4 elements as vec4 v, then `newColor = m * color + v;`

The matrix can be passed as single array, and is treated as follows:

      [ a, b, c, d,
        e, f, g, h,
        i, j, k, l,
        m, n, o, p,
        q, r, s, t ]

When applied to a color `[R, G, B, A]`, the resulting color is computed as:

       R’ = a*R + e*G + i*B + m*A + q;
       G’ = b*R + f*G + j*B + n*A + r;
       B’ = c*R + g*G + k*B + o*A + s;
       A’ = d*R + h*G + l*B + p*A + t;

That resulting color `[R’, G’, B’, A’]` then has each channel clamped to the `0.0` to `1.0` range.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ColorMatrix()`
  Create an identity matrix.
  `ColorMatrix(float... src)`
  Create a matrix from an array of elements in row-major.
  `ColorMatrix(ColorMatrix src)`
  Create a matrix copied from an existing matrix.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `float[]`
  `elements()`
  `boolean`
  `equals(Object o)`
  `int`
  `hashCode()`
  `void`
  `postConcat(float[] rhs)`
  `void`
  `postConcat(ColorMatrix rhs)`
  Post-multiply this matrix by the given `rhs` matrix.
  `void`
  `preConcat(float[] lhs)`
  `void`
  `preConcat(ColorMatrix lhs)`
  Pre-multiply this matrix by the given `lhs` matrix.
  `void`
  `set(float[] src)`
  Set the values in the matrix using a float array that contains the matrix elements in row-major order.
  `void`
  `set(float[] src, int offset)`
  Set the values in the matrix using a float array that contains the matrix elements in row-major order.
  `void`
  `set(ColorMatrix src)`
  Store the values of the given matrix into this matrix.
  `void`
  `set(ByteBuffer src)`
  Set the values in the matrix using a float array that contains the matrix elements in row-major order.
  `void`
  `set(FloatBuffer src)`
  Set the values in the matrix using a float array that contains the matrix elements in row-major order.
  `void`
  `setConcat(float[] lhs, float[] rhs)`
  `void`
  `setConcat(ColorMatrix lhs, ColorMatrix rhs)`
  Set this matrix to the concatenation of the two specified matrices, such that the resulting matrix has the same effect as applying `lhs` first and then applying `rhs`.
  `void`
  `setIdentity()`
  Reset this matrix to the identity.
  `void`
  `setRotateB(float angle)`
  Set the rotation around the blue color axis by the specified radians.
  `void`
  `setRotateG(float angle)`
  Set the rotation around the green color axis by the specified radians.
  `void`
  `setRotateR(float angle)`
  Set the rotation around the red color axis by the specified radians.
  `void`
  `setSaturation(float sat)`
  Set the matrix to affect the saturation of colors.
  `void`
  `setScale(float scaleR, float scaleG, float scaleB, float scaleA)`
  Set this matrix to scale by the specified values.
  `void`
  `setTranslate(float transR, float transG, float transB, float transA)`
  `void`
  `store(float[] dst)`
  Store this matrix into the give float array in row-major order.
  `void`
  `store(float[] dst, int offset)`
  Store this matrix into the give float array in row-major order.
  `void`
  `store(ColorMatrix dst)`
  Store this matrix elements to the given matrix.
  `void`
  `store(ByteBuffer dst)`
  Store this matrix into the give float array in row-major order.
  `void`
  `store(FloatBuffer dst)`
  Store this matrix into the give float array in row-major order.

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### ColorMatrix

    public ColorMatrix()
    Create an identity matrix.

  - ### ColorMatrix

    public ColorMatrix(@Size(20L) float... src)
    Create a matrix from an array of elements in row-major.
    Parameters:
      `src` - the array to create from
    See Also:
      - `set(float[])`

  - ### ColorMatrix

    public ColorMatrix(@Nonnull ColorMatrix src)
    Create a matrix copied from an existing matrix.
    Parameters:
      `src` - the matrix to create from

- ## Method Details

  - ### setIdentity

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

  - ### set

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

  - ### set

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

  - ### set

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

  - ### set

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

  - ### set

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

  - ### store

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

  - ### store

    public void store(@Size(20L) float[] dst)
    Store this matrix into the give float array in row-major order.
    Parameters:
      `dst` - the array to store into

  - ### store

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

  - ### store

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

  - ### store

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

  - ### setScale

    public void setScale(float scaleR, float scaleG, float scaleB, float scaleA)
    Set this matrix to scale by the specified values.

  - ### setRotateR

    public void setRotateR(float angle)
    Set the rotation around the red color axis by the specified radians.
    Parameters:
      `angle` - the rotation angle in radians

  - ### setRotateG

    public void setRotateG(float angle)
    Set the rotation around the green color axis by the specified radians.
    Parameters:
      `angle` - the rotation angle in radians

  - ### setRotateB

    public void setRotateB(float angle)
    Set the rotation around the blue color axis by the specified radians.
    Parameters:
      `angle` - the rotation angle in radians

  - ### setTranslate

    public void setTranslate(float transR, float transG, float transB, float transA)

  - ### preConcat

    public void preConcat(@Size(20L) float[] lhs)

  - ### preConcat

    public void preConcat(@Nonnull ColorMatrix 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(@Size(20L) float[] rhs)

  - ### postConcat

    public void postConcat(@Nonnull ColorMatrix 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

  - ### setConcat

    public void setConcat(@Size(20L) float[] lhs, @Size(20L) float[] rhs)

  - ### setConcat

    public void setConcat(@Nonnull ColorMatrix lhs, @Nonnull ColorMatrix rhs)
    Set this matrix to the concatenation of the two specified matrices, such that the resulting matrix has the same effect as applying `lhs` first and then applying `rhs`.

    It is legal for either `lhs` or `rhs` to be the same matrix as `this`.

  - ### setSaturation

    public void setSaturation(float sat)
    Set the matrix to affect the saturation of colors.
    Parameters:
      `sat` - A value of 0 maps the color to gray-scale. 1 is identity.

  - ### elements

    public float[] elements()
    Returns:
      the backing array

  - ### hashCode

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

  - ### equals

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