Added in API level 1

ColorMatrix


public class ColorMatrix
extends Object

java.lang.Object
   ↳ android.graphics.ColorMatrix


4x5 matrix for transforming the color and alpha components of a Bitmap. 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 + b*G + c*B + d*A + e;
   G’ = f*R + g*G + h*B + i*A + j;
   B’ = k*R + l*G + m*B + n*A + o;
   A’ = p*R + q*G + r*B + s*A + t;

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

The sample ColorMatrix below inverts incoming colors by scaling each channel by -1, and then shifting the result up by 255 to remain in the standard color space.

   [ -1, 0, 0, 0, 255,
     0, -1, 0, 0, 255,
     0, 0, -1, 0, 255,
     0, 0, 0, 1, 0 ]

Summary

Public constructors

ColorMatrix()

Create a new colormatrix initialized to identity (as if reset() had been called).

ColorMatrix(float[] src)

Create a new colormatrix initialized with the specified array of values.

ColorMatrix(ColorMatrix src)

Create a new colormatrix initialized with the specified colormatrix.

Public methods

boolean equals(Object obj)

Indicates whether some other object is "equal to" this one.

final float[] getArray()

Return the array of floats representing this colormatrix.

void postConcat(ColorMatrix postmatrix)

Concat this colormatrix with the specified postmatrix.

void preConcat(ColorMatrix prematrix)

Concat this colormatrix with the specified prematrix.

void reset()

Set this colormatrix to identity:

 [ 1 0 0 0 0   - red vector
   0 1 0 0 0   - green vector
   0 0 1 0 0   - blue vector
   0 0 0 1 0 ] - alpha vector
 

void set(float[] src)

Assign the array of floats into this matrix, copying all of its values.

void set(ColorMatrix src)

Assign the src colormatrix into this matrix, copying all of its values.

void setConcat(ColorMatrix matA, ColorMatrix matB)

Set this colormatrix to the concatenation of the two specified colormatrices, such that the resulting colormatrix has the same effect as applying matB and then applying matA.

void setRGB2YUV()

Set the matrix to convert RGB to YUV

void setRotate(int axis, float degrees)

Set the rotation on a color axis by the specified values.

void setSaturation(float sat)

Set the matrix to affect the saturation of colors.

void setScale(float rScale, float gScale, float bScale, float aScale)

Set this colormatrix to scale by the specified values.

void setYUV2RGB()

Set the matrix to convert from YUV to RGB

Inherited methods

Public constructors

ColorMatrix

Added in API level 1
public ColorMatrix ()

Create a new colormatrix initialized to identity (as if reset() had been called).

ColorMatrix

Added in API level 1
public ColorMatrix (float[] src)

Create a new colormatrix initialized with the specified array of values.

Parameters
src float

ColorMatrix

Added in API level 1
public ColorMatrix (ColorMatrix src)

Create a new colormatrix initialized with the specified colormatrix.

Parameters
src ColorMatrix

Public methods

equals

Added in API level 1
public boolean equals (Object obj)

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

  • It is reflexive: for any non-null reference value x, x.equals(x) should return true.
  • It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
  • It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
  • For any non-null reference value x, x.equals(null) should return false.

An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

Parameters
obj Object: the reference object with which to compare.

Returns
boolean true if this object is the same as the obj argument; false otherwise.

getArray

Added in API level 1
public final float[] getArray ()

Return the array of floats representing this colormatrix.

Returns
float[]

postConcat

Added in API level 1
public void postConcat (ColorMatrix postmatrix)

Concat this colormatrix with the specified postmatrix.

This is logically the same as calling setConcat(postmatrix, this);

Parameters
postmatrix ColorMatrix

preConcat

Added in API level 1
public void preConcat (ColorMatrix prematrix)

Concat this colormatrix with the specified prematrix.

This is logically the same as calling setConcat(this, prematrix);

Parameters
prematrix ColorMatrix

reset

Added in API level 1
public void reset ()

Set this colormatrix to identity:

 [ 1 0 0 0 0   - red vector
   0 1 0 0 0   - green vector
   0 0 1 0 0   - blue vector
   0 0 0 1 0 ] - alpha vector
 

set

Added in API level 1
public void set (float[] src)

Assign the array of floats into this matrix, copying all of its values.

Parameters
src float

set

Added in API level 1
public void set (ColorMatrix src)

Assign the src colormatrix into this matrix, copying all of its values.

Parameters
src ColorMatrix

setConcat

Added in API level 1
public void setConcat (ColorMatrix matA, 
                ColorMatrix matB)

Set this colormatrix to the concatenation of the two specified colormatrices, such that the resulting colormatrix has the same effect as applying matB and then applying matA.

It is legal for either matA or matB to be the same colormatrix as this.

Parameters
matA ColorMatrix

matB ColorMatrix

setRGB2YUV

Added in API level 1
public void setRGB2YUV ()

Set the matrix to convert RGB to YUV

setRotate

Added in API level 1
public void setRotate (int axis, 
                float degrees)

Set the rotation on a color axis by the specified values.

axis=0 correspond to a rotation around the RED color axis=1 correspond to a rotation around the GREEN color axis=2 correspond to a rotation around the BLUE color

Parameters
axis int

degrees float

setSaturation

Added in API level 1
public void setSaturation (float sat)

Set the matrix to affect the saturation of colors.

Parameters
sat float: A value of 0 maps the color to gray-scale. 1 is identity.

setScale

Added in API level 1
public void setScale (float rScale, 
                float gScale, 
                float bScale, 
                float aScale)

Set this colormatrix to scale by the specified values.

Parameters
rScale float

gScale float

bScale float

aScale float

setYUV2RGB

Added in API level 1
public void setYUV2RGB ()

Set the matrix to convert from YUV to RGB