public class

Matrix

extends Object
java.lang.Object
   ↳ android.graphics.Matrix

Class Overview

The Matrix class holds a 3x3 matrix for transforming coordinates. Matrix does not have a constructor, so it must be explicitly initialized using either reset() - to construct an identity matrix, or one of the set..() functions (e.g. setTranslate, setRotate, etc.).

Summary

Nested Classes
enum Matrix.ScaleToFit Controlls how the src rect should align into the dst rect for setRectToRect(). 
Constants
int MPERSP_0
int MPERSP_1
int MPERSP_2
int MSCALE_X
int MSCALE_Y
int MSKEW_X
int MSKEW_Y
int MTRANS_X
int MTRANS_Y
Public Constructors
Matrix()
Create an identity matrix
Matrix(Matrix src)
Create a matrix that is a (deep) copy of src
Public Methods
boolean equals(Object obj)
Returns true iff obj is a Matrix and its values equal our values.
void getValues(float[] values)
Copy 9 values from the matrix into the array.
boolean invert(Matrix inverse)
If this matrix can be inverted, return true and if inverse is not null, set inverse to be the inverse of this matrix.
boolean isIdentity()
Returns true if the matrix is identity.
void mapPoints(float[] dst, float[] src)
Apply this matrix to the array of 2D points specified by src, and write the transformed points into the array of points specified by dst.
void mapPoints(float[] dst, int dstIndex, float[] src, int srcIndex, int pointCount)
Apply this matrix to the array of 2D points specified by src, and write the transformed points into the array of points specified by dst.
void mapPoints(float[] pts)
Apply this matrix to the array of 2D points, and write the transformed points back into the array
float mapRadius(float radius)
Return the mean radius of a circle after it has been mapped by this matrix.
boolean mapRect(RectF rect)
Apply this matrix to the rectangle, and write the transformed rectangle back into it.
boolean mapRect(RectF dst, RectF src)
Apply this matrix to the src rectangle, and write the transformed rectangle into dst.
void mapVectors(float[] dst, float[] src)
Apply this matrix to the array of 2D vectors specified by src, and write the transformed vectors into the array of vectors specified by dst.
void mapVectors(float[] vecs)
Apply this matrix to the array of 2D vectors, and write the transformed vectors back into the array.
void mapVectors(float[] dst, int dstIndex, float[] src, int srcIndex, int vectorCount)
Apply this matrix to the array of 2D vectors specified by src, and write the transformed vectors into the array of vectors specified by dst.
boolean postConcat(Matrix other)
Postconcats the matrix with the specified matrix.
boolean postRotate(float degrees, float px, float py)
Postconcats the matrix with the specified rotation.
boolean postRotate(float degrees)
Postconcats the matrix with the specified rotation.
boolean postScale(float sx, float sy, float px, float py)
Postconcats the matrix with the specified scale.
boolean postScale(float sx, float sy)
Postconcats the matrix with the specified scale.
boolean postSkew(float kx, float ky)
Postconcats the matrix with the specified skew.
boolean postSkew(float kx, float ky, float px, float py)
Postconcats the matrix with the specified skew.
boolean postTranslate(float dx, float dy)
Postconcats the matrix with the specified translation.
boolean preConcat(Matrix other)
Preconcats the matrix with the specified matrix.
boolean preRotate(float degrees)
Preconcats the matrix with the specified rotation.
boolean preRotate(float degrees, float px, float py)
Preconcats the matrix with the specified rotation.
boolean preScale(float sx, float sy, float px, float py)
Preconcats the matrix with the specified scale.
boolean preScale(float sx, float sy)
Preconcats the matrix with the specified scale.
boolean preSkew(float kx, float ky, float px, float py)
Preconcats the matrix with the specified skew.
boolean preSkew(float kx, float ky)
Preconcats the matrix with the specified skew.
boolean preTranslate(float dx, float dy)
Preconcats the matrix with the specified translation.
boolean rectStaysRect()
Returns true if will map a rectangle to another rectangle.
void reset()
Set the matrix to identity
void set(Matrix src)
(deep) copy the src matrix into this matrix.
boolean setConcat(Matrix a, Matrix b)
Set the matrix to the concatenation of the two specified matrices, returning true if the the result can be represented.
boolean setPolyToPoly(float[] src, int srcIndex, float[] dst, int dstIndex, int pointCount)
Set the matrix such that the specified src points would map to the specified dst points.
boolean setRectToRect(RectF src, RectF dst, Matrix.ScaleToFit stf)
Set the matrix to the scale and translate values that map the source rectangle to the destination rectangle, returning true if the the result can be represented.
void setRotate(float degrees)
Set the matrix to rotate about (0,0) by the specified number of degrees.
void setRotate(float degrees, float px, float py)
Set the matrix to rotate by the specified number of degrees, with a pivot point at (px, py).
void setScale(float sx, float sy)
Set the matrix to scale by sx and sy.
void setScale(float sx, float sy, float px, float py)
Set the matrix to scale by sx and sy, with a pivot point at (px, py).
void setSinCos(float sinValue, float cosValue, float px, float py)
Set the matrix to rotate by the specified sine and cosine values, with a pivot point at (px, py).
void setSinCos(float sinValue, float cosValue)
Set the matrix to rotate by the specified sine and cosine values.
void setSkew(float kx, float ky, float px, float py)
Set the matrix to skew by sx and sy, with a pivot point at (px, py).
void setSkew(float kx, float ky)
Set the matrix to skew by sx and sy.
void setTranslate(float dx, float dy)
Set the matrix to translate by (dx, dy).
void setValues(float[] values)
Copy 9 values from the array into the matrix.
String toShortString()
String toString()
Returns a string containing a concise, human-readable description of this object.
Protected Methods
void finalize()
Is called before the object's memory is being reclaimed by the VM.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int MPERSP_0

Since: API Level 1

Constant Value: 6 (0x00000006)

public static final int MPERSP_1

Since: API Level 1

Constant Value: 7 (0x00000007)

public static final int MPERSP_2

Since: API Level 1

Constant Value: 8 (0x00000008)

public static final int MSCALE_X

Since: API Level 1

Constant Value: 0 (0x00000000)

public static final int MSCALE_Y

Since: API Level 1

Constant Value: 4 (0x00000004)

public static final int MSKEW_X

Since: API Level 1

Constant Value: 1 (0x00000001)

public static final int MSKEW_Y

Since: API Level 1

Constant Value: 3 (0x00000003)

public static final int MTRANS_X

Since: API Level 1

Constant Value: 2 (0x00000002)

public static final int MTRANS_Y

Since: API Level 1

Constant Value: 5 (0x00000005)

Public Constructors

public Matrix ()

Since: API Level 1

Create an identity matrix

public Matrix (Matrix src)

Since: API Level 1

Create a matrix that is a (deep) copy of src

Parameters
src The matrix to copy into this matrix

Public Methods

public boolean equals (Object obj)

Since: API Level 1

Returns true iff obj is a Matrix and its values equal our values.

Parameters
obj the object to compare this instance with.
Returns
  • true if the specified object is equal to this Object; false otherwise.

public void getValues (float[] values)

Since: API Level 1

Copy 9 values from the matrix into the array.

public boolean invert (Matrix inverse)

Since: API Level 1

If this matrix can be inverted, return true and if inverse is not null, set inverse to be the inverse of this matrix. If this matrix cannot be inverted, ignore inverse and return false.

public boolean isIdentity ()

Since: API Level 1

Returns true if the matrix is identity. This maybe faster than testing if (getType() == 0)

public void mapPoints (float[] dst, float[] src)

Since: API Level 1

Apply this matrix to the array of 2D points specified by src, and write the transformed points into the array of points specified by dst. The two arrays represent their "points" as pairs of floats [x, y].

Parameters
dst The array of dst points (x,y pairs)
src The array of src points (x,y pairs)

public void mapPoints (float[] dst, int dstIndex, float[] src, int srcIndex, int pointCount)

Since: API Level 1

Apply this matrix to the array of 2D points specified by src, and write the transformed points into the array of points specified by dst. The two arrays represent their "points" as pairs of floats [x, y].

Parameters
dst The array of dst points (x,y pairs)
dstIndex The index of the first [x,y] pair of dst floats
src The array of src points (x,y pairs)
srcIndex The index of the first [x,y] pair of src floats
pointCount The number of points (x,y pairs) to transform

public void mapPoints (float[] pts)

Since: API Level 1

Apply this matrix to the array of 2D points, and write the transformed points back into the array

Parameters
pts The array [x0, y0, x1, y1, ...] of points to transform.

public float mapRadius (float radius)

Since: API Level 1

Return the mean radius of a circle after it has been mapped by this matrix. NOTE: in perspective this value assumes the circle has its center at the origin.

public boolean mapRect (RectF rect)

Since: API Level 1

Apply this matrix to the rectangle, and write the transformed rectangle back into it. This is accomplished by transforming the 4 corners of rect, and then setting it to the bounds of those points

Parameters
rect The rectangle to transform.
Returns
  • the result of calling rectStaysRect()

public boolean mapRect (RectF dst, RectF src)

Since: API Level 1

Apply this matrix to the src rectangle, and write the transformed rectangle into dst. This is accomplished by transforming the 4 corners of src, and then setting dst to the bounds of those points.

Parameters
dst Where the transformed rectangle is written.
src The original rectangle to be transformed.
Returns
  • the result of calling rectStaysRect()

public void mapVectors (float[] dst, float[] src)

Since: API Level 1

Apply this matrix to the array of 2D vectors specified by src, and write the transformed vectors into the array of vectors specified by dst. The two arrays represent their "vectors" as pairs of floats [x, y].

Parameters
dst The array of dst vectors (x,y pairs)
src The array of src vectors (x,y pairs)

public void mapVectors (float[] vecs)

Since: API Level 1

Apply this matrix to the array of 2D vectors, and write the transformed vectors back into the array.

Parameters
vecs The array [x0, y0, x1, y1, ...] of vectors to transform.

public void mapVectors (float[] dst, int dstIndex, float[] src, int srcIndex, int vectorCount)

Since: API Level 1

Apply this matrix to the array of 2D vectors specified by src, and write the transformed vectors into the array of vectors specified by dst. The two arrays represent their "vectors" as pairs of floats [x, y].

Parameters
dst The array of dst vectors (x,y pairs)
dstIndex The index of the first [x,y] pair of dst floats
src The array of src vectors (x,y pairs)
srcIndex The index of the first [x,y] pair of src floats
vectorCount The number of vectors (x,y pairs) to transform

public boolean postConcat (Matrix other)

Since: API Level 1

Postconcats the matrix with the specified matrix. M' = other * M

public boolean postRotate (float degrees, float px, float py)

Since: API Level 1

Postconcats the matrix with the specified rotation. M' = R(degrees, px, py) * M

public boolean postRotate (float degrees)

Since: API Level 1

Postconcats the matrix with the specified rotation. M' = R(degrees) * M

public boolean postScale (float sx, float sy, float px, float py)

Since: API Level 1

Postconcats the matrix with the specified scale. M' = S(sx, sy, px, py) * M

public boolean postScale (float sx, float sy)

Since: API Level 1

Postconcats the matrix with the specified scale. M' = S(sx, sy) * M

public boolean postSkew (float kx, float ky)

Since: API Level 1

Postconcats the matrix with the specified skew. M' = K(kx, ky) * M

public boolean postSkew (float kx, float ky, float px, float py)

Since: API Level 1

Postconcats the matrix with the specified skew. M' = K(kx, ky, px, py) * M

public boolean postTranslate (float dx, float dy)

Since: API Level 1

Postconcats the matrix with the specified translation. M' = T(dx, dy) * M

public boolean preConcat (Matrix other)

Since: API Level 1

Preconcats the matrix with the specified matrix. M' = M * other

public boolean preRotate (float degrees)

Since: API Level 1

Preconcats the matrix with the specified rotation. M' = M * R(degrees)

public boolean preRotate (float degrees, float px, float py)

Since: API Level 1

Preconcats the matrix with the specified rotation. M' = M * R(degrees, px, py)

public boolean preScale (float sx, float sy, float px, float py)

Since: API Level 1

Preconcats the matrix with the specified scale. M' = M * S(sx, sy, px, py)

public boolean preScale (float sx, float sy)

Since: API Level 1

Preconcats the matrix with the specified scale. M' = M * S(sx, sy)

public boolean preSkew (float kx, float ky, float px, float py)

Since: API Level 1

Preconcats the matrix with the specified skew. M' = M * K(kx, ky, px, py)

public boolean preSkew (float kx, float ky)

Since: API Level 1

Preconcats the matrix with the specified skew. M' = M * K(kx, ky)

public boolean preTranslate (float dx, float dy)

Since: API Level 1

Preconcats the matrix with the specified translation. M' = M * T(dx, dy)

public boolean rectStaysRect ()

Since: API Level 1

Returns true if will map a rectangle to another rectangle. This can be true if the matrix is identity, scale-only, or rotates a multiple of 90 degrees.

public void reset ()

Since: API Level 1

Set the matrix to identity

public void set (Matrix src)

Since: API Level 1

(deep) copy the src matrix into this matrix. If src is null, reset this matrix to the identity matrix.

public boolean setConcat (Matrix a, Matrix b)

Since: API Level 1

Set the matrix to the concatenation of the two specified matrices, returning true if the the result can be represented. Either of the two matrices may also be the target matrix. this = a * b

public boolean setPolyToPoly (float[] src, int srcIndex, float[] dst, int dstIndex, int pointCount)

Since: API Level 1

Set the matrix such that the specified src points would map to the specified dst points. The "points" are represented as an array of floats, order [x0, y0, x1, y1, ...], where each "point" is 2 float values.

Parameters
src The array of src [x,y] pairs (points)
srcIndex Index of the first pair of src values
dst The array of dst [x,y] pairs (points)
dstIndex Index of the first pair of dst values
pointCount The number of pairs/points to be used. Must be [0..4]
Returns
  • true if the matrix was set to the specified transformation

public boolean setRectToRect (RectF src, RectF dst, Matrix.ScaleToFit stf)

Since: API Level 1

Set the matrix to the scale and translate values that map the source rectangle to the destination rectangle, returning true if the the result can be represented.

Parameters
src the source rectangle to map from.
dst the destination rectangle to map to.
stf the ScaleToFit option
Returns
  • true if the matrix can be represented by the rectangle mapping.

public void setRotate (float degrees)

Since: API Level 1

Set the matrix to rotate about (0,0) by the specified number of degrees.

public void setRotate (float degrees, float px, float py)

Since: API Level 1

Set the matrix to rotate by the specified number of degrees, with a pivot point at (px, py). The pivot point is the coordinate that should remain unchanged by the specified transformation.

public void setScale (float sx, float sy)

Since: API Level 1

Set the matrix to scale by sx and sy.

public void setScale (float sx, float sy, float px, float py)

Since: API Level 1

Set the matrix to scale by sx and sy, with a pivot point at (px, py). The pivot point is the coordinate that should remain unchanged by the specified transformation.

public void setSinCos (float sinValue, float cosValue, float px, float py)

Since: API Level 1

Set the matrix to rotate by the specified sine and cosine values, with a pivot point at (px, py). The pivot point is the coordinate that should remain unchanged by the specified transformation.

public void setSinCos (float sinValue, float cosValue)

Since: API Level 1

Set the matrix to rotate by the specified sine and cosine values.

public void setSkew (float kx, float ky, float px, float py)

Since: API Level 1

Set the matrix to skew by sx and sy, with a pivot point at (px, py). The pivot point is the coordinate that should remain unchanged by the specified transformation.

public void setSkew (float kx, float ky)

Since: API Level 1

Set the matrix to skew by sx and sy.

public void setTranslate (float dx, float dy)

Since: API Level 1

Set the matrix to translate by (dx, dy).

public void setValues (float[] values)

Since: API Level 1

Copy 9 values from the array into the matrix. Depending on the implementation of Matrix, these may be transformed into 16.16 integers in the Matrix, such that a subsequent call to getValues() will not yield exactly the same values.

public String toShortString ()

Since: API Level 1

public String toString ()

Since: API Level 1

Returns a string containing a concise, human-readable description of this object. Subclasses are encouraged to override this method and provide an implementation that takes into account the object's type and data. The default implementation simply concatenates the class name, the '@' sign and a hexadecimal representation of the object's hashCode(), that is, it is equivalent to the following expression: 

 getClass().getName() + '@' + Integer.toHexString(hashCode())

Returns
  • a printable representation of this object.

Protected Methods

protected void finalize ()

Since: API Level 1

Is called before the object's memory is being reclaimed by the VM. This can only happen once the VM has detected, during a run of the garbage collector, that the object is no longer reachable by any thread of the running application.

The method can be used to free system resources or perform other cleanup before the object is garbage collected. The default implementation of the method is empty, which is also expected by the VM, but subclasses can override finalize() as required. Uncaught exceptions which are thrown during the execution of this method cause it to terminate immediately but are otherwise ignored.

Note that the VM does guarantee that finalize() is called at most once for any object, but it doesn't guarantee when (if at all) finalize() will be called. For example, object B's finalize() can delay the execution of object A's finalize() method and therefore it can delay the reclamation of A's memory. To be safe, use a ReferenceQueue, because it provides more control over the way the VM deals with references during garbage collection.

Throws
Throwable