frameworks/rs/scriptc/rs_matrix.rsh File Reference

Functions
_RS_RUNTIME void	rsMatrixSet (rs_matrix4x4 *m, uint32_t col, uint32_t row, float v)
_RS_RUNTIME void	rsMatrixSet (rs_matrix3x3 *m, uint32_t col, uint32_t row, float v)
_RS_RUNTIME void	rsMatrixSet (rs_matrix2x2 *m, uint32_t col, uint32_t row, float v)
_RS_RUNTIME float	rsMatrixGet (const rs_matrix4x4 *m, uint32_t col, uint32_t row)
_RS_RUNTIME float	rsMatrixGet (const rs_matrix3x3 *m, uint32_t col, uint32_t row)
_RS_RUNTIME float	rsMatrixGet (const rs_matrix2x2 *m, uint32_t col, uint32_t row)
void	rsMatrixLoadIdentity (rs_matrix4x4 *m)
void	rsMatrixLoadIdentity (rs_matrix3x3 *m)
void	rsMatrixLoadIdentity (rs_matrix2x2 *m)
void	rsMatrixLoad (rs_matrix4x4 *m, const float *v)
void	rsMatrixLoad (rs_matrix3x3 *m, const float *v)
void	rsMatrixLoad (rs_matrix2x2 *m, const float *v)
void	rsMatrixLoad (rs_matrix4x4 *m, const rs_matrix4x4 *v)
void	rsMatrixLoad (rs_matrix4x4 *m, const rs_matrix3x3 *v)
void	rsMatrixLoad (rs_matrix4x4 *m, const rs_matrix2x2 *v)
void	rsMatrixLoad (rs_matrix3x3 *m, const rs_matrix3x3 *v)
void	rsMatrixLoad (rs_matrix2x2 *m, const rs_matrix2x2 *v)
void	rsMatrixLoadRotate (rs_matrix4x4 *m, float rot, float x, float y, float z)
void	rsMatrixLoadScale (rs_matrix4x4 *m, float x, float y, float z)
void	rsMatrixLoadTranslate (rs_matrix4x4 *m, float x, float y, float z)
void	rsMatrixLoadMultiply (rs_matrix4x4 *m, const rs_matrix4x4 *lhs, const rs_matrix4x4 *rhs)
void	rsMatrixLoadMultiply (rs_matrix3x3 *m, const rs_matrix3x3 *lhs, const rs_matrix3x3 *rhs)
void	rsMatrixLoadMultiply (rs_matrix2x2 *m, const rs_matrix2x2 *lhs, const rs_matrix2x2 *rhs)
void	rsMatrixMultiply (rs_matrix4x4 *m, const rs_matrix4x4 *rhs)
void	rsMatrixMultiply (rs_matrix3x3 *m, const rs_matrix3x3 *rhs)
void	rsMatrixMultiply (rs_matrix2x2 *m, const rs_matrix2x2 *rhs)
void	rsMatrixRotate (rs_matrix4x4 *m, float rot, float x, float y, float z)
void	rsMatrixScale (rs_matrix4x4 *m, float x, float y, float z)
void	rsMatrixTranslate (rs_matrix4x4 *m, float x, float y, float z)
void	rsMatrixLoadOrtho (rs_matrix4x4 *m, float left, float right, float bottom, float top, float near, float far)
void	rsMatrixLoadFrustum (rs_matrix4x4 *m, float left, float right, float bottom, float top, float near, float far)
void	rsMatrixLoadPerspective (rs_matrix4x4 *m, float fovy, float aspect, float near, float far)
_RS_RUNTIME float4	rsMatrixMultiply (rs_matrix4x4 *m, float4 in)
_RS_RUNTIME float3	rsMatrixMultiply (rs_matrix3x3 *m, float3 in)
_RS_RUNTIME float2	rsMatrixMultiply (rs_matrix2x2 *m, float2 in)
bool	rsMatrixInverse (rs_matrix4x4 *m)
bool	rsMatrixInverseTranspose (rs_matrix4x4 *m)
void	rsMatrixTranspose (rs_matrix4x4 *m)
void	rsMatrixTranspose (rs_matrix3x3 *m)
void	rsMatrixTranspose (rs_matrix2x2 *m)

---

Detailed Description

Matrix functions.

These functions let you manipulate square matrices of rank 2x2, 3x3, and 4x4. They are particularly useful for graphical transformations and are compatible with OpenGL.

A few general notes:

• We use a zero-based index for rows and columns. E.g. the last element of a rs_matrix4x4 is found at (3, 3).

• RenderScript uses column-based vectors. Transforming a vector is done by postmultiplying the vector, e.g. (matrix * vector), as provided by rsMatrixMultiply.

• To create a transformation matrix that performs two transformations at once, multiply the two source matrices, with the first transformation as the right argument. E.g. to create a transformation matrix that applies the transformation s1 followed by s2, call rsMatrixLoadMultiply(&combined, &s2, &s1). This derives from s2 * (s1 * v), which is (s2 * s1) * v.

• We have two style of functions to create transformation matrices: rsMatrixLoadTransformation and rsMatrixTransformation. The former style simply stores the transformation matrix in the first argument. The latter modifies a pre-existing transformation matrix so that the new transformation happens first. E.g. if you call rsMatrixTranslate on a matrix that already does a scaling, the resulting matrix when applied to a vector will first do the translation then the scaling.

Definition in file rs_matrix.rsh.

---

Function Documentation

_RS_RUNTIME float rsMatrixGet	(	const rs_matrix4x4 *	m,
		uint32_t	col,
		uint32_t	row
	)

Returns one element of a matrix.

Parameters:

m	The matrix to extract the element from.
col	The zero-based column of the element to be extracted.
row	The zero-based row of the element to extracted.

Warning:

The order of the column and row parameters may be unexpected.

Returns:

float

_RS_RUNTIME float rsMatrixGet	(	const rs_matrix3x3 *	m,
		uint32_t	col,
		uint32_t	row
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

_RS_RUNTIME float rsMatrixGet	(	const rs_matrix2x2 *	m,
		uint32_t	col,
		uint32_t	row
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool rsMatrixInverse

(

rs_matrix4x4 *

m

)

Inverts a matrix in place.

Returns true if the matrix was successfully inversed.

Parameters:

m	The matrix to invert.

bool rsMatrixInverseTranspose

(

rs_matrix4x4 *

m

)

Inverts and transpose a matrix in place.

The matrix is first inverted then transposed. Returns true if the matrix was successfully inverted.

Parameters:

m	The matrix to modify.

void rsMatrixLoad	(	rs_matrix4x4 *	m,
		const float *	v
	)

Set the elements of a matrix from an array of floats.

The array of floats should be in row-major order, i.e. the element a row 0, column 0 should be first, followed by the element at row 0, column 1, etc.

Parameters:

m	The matrix to set.
v	The array of values to set the matrix to. These arrays should be 4, 9, or 16 floats long, depending on the matrix size.

void rsMatrixLoad	(	rs_matrix3x3 *	m,
		const float *	v
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void rsMatrixLoad	(	rs_matrix2x2 *	m,
		const float *	v
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void rsMatrixLoad	(	rs_matrix4x4 *	m,
		const rs_matrix4x4 *	v
	)

Set the elements of a matrix from another matrix.

If the source matrix is smaller than the destination, the rest of the destination is filled with elements of the identity matrix. E.g. loading a rs_matrix2x2 into a rs_matrix4x4 will give:

m00	m01	0.0	0.0
m10	m11	0.0	0.0
0.0	0.0	1.0	0.0
0.0	0.0	0.0	1.0

Parameters:

m	The matrix to set.
v	The source matrix.

void rsMatrixLoad	(	rs_matrix4x4 *	m,
		const rs_matrix3x3 *	v
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void rsMatrixLoad	(	rs_matrix4x4 *	m,
		const rs_matrix2x2 *	v
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void rsMatrixLoad	(	rs_matrix3x3 *	m,
		const rs_matrix3x3 *	v
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void rsMatrixLoad	(	rs_matrix2x2 *	m,
		const rs_matrix2x2 *	v
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void rsMatrixLoadFrustum	(	rs_matrix4x4 *	m,
		float	left,
		float	right,
		float	bottom,
		float	top,
		float	near,
		float	far
	)

Load a frustum projection matrix.

Constructs a frustum projection matrix, transforming the box identified by the six clipping planes left, right, bottom, top, near, far.

To apply this projection to a vector, multiply the vector by the created matrix using rsMatrixMultiply.

See https://www.opengl.org/documentation/specs/version2.0/glspec20.pdf

Parameters:

m	The matrix to set.
left
right
bottom
top
near
far

void rsMatrixLoadIdentity

(

rs_matrix4x4 *

m

)

Set the elements of a matrix to the identity matrix.

Parameters:

m	The matrix to set.

void rsMatrixLoadIdentity

(

rs_matrix3x3 *

m

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void rsMatrixLoadIdentity

(

rs_matrix2x2 *

m

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void rsMatrixLoadMultiply	(	rs_matrix4x4 *	m,
		const rs_matrix4x4 *	lhs,
		const rs_matrix4x4 *	rhs
	)

Multiply two matrices.

Sets m to the matrix product of lhs * rhs.

To combine two 4x4 transformaton matrices, multiply the second transformation matrix by the first transformation matrix. E.g. to create a transformation matrix that applies the transformation s1 followed by s2, call rsMatrixLoadMultiply(&combined, &s2, &s1).

Warning:

As of version 21, storing the result back into right matrix is not supported and will result in undefined behavior. Use rsMatrixMulitply instead. E.g. instead of doing rsMatrixLoadMultiply (&m2r, &m2r, &m2l), use rsMatrixMultiply (&m2r, &m2l). rsMatrixLoadMultiply (&m2l, &m2r, &m2l) works as expected.

Parameters:

m	The matrix to set.
lhs	The left matrix of the product.
rhs	The right matrix of the product.

void rsMatrixLoadMultiply	(	rs_matrix3x3 *	m,
		const rs_matrix3x3 *	lhs,
		const rs_matrix3x3 *	rhs
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void rsMatrixLoadMultiply	(	rs_matrix2x2 *	m,
		const rs_matrix2x2 *	lhs,
		const rs_matrix2x2 *	rhs
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void rsMatrixLoadOrtho	(	rs_matrix4x4 *	m,
		float	left,
		float	right,
		float	bottom,
		float	top,
		float	near,
		float	far
	)

Load an orthographic projection matrix.

Constructs an orthographic projection matrix, transforming the box identified by the six clipping planes left, right, bottom, top, near, far into a unit cube with a corner at (-1, -1, -1) and the opposite at (1, 1, 1).

To apply this projection to a vector, multiply the vector by the created matrix using rsMatrixMultiply.

See https://en.wikipedia.org/wiki/Orthographic_projection and https://www.opengl.org/documentation/specs/version2.0/glspec20.pdf

Parameters:

m	The matrix to set.
left
right
bottom
top
near
far

void rsMatrixLoadPerspective	(	rs_matrix4x4 *	m,
		float	fovy,
		float	aspect,
		float	near,
		float	far
	)

Load a perspective projection matrix.

Constructs a perspective projection matrix, assuming a symmetrical field of view.

To apply this projection to a vector, multiply the vector by the created matrix using rsMatrixMultiply.

See https://www.opengl.org/documentation/specs/version2.0/glspec20.pdf

Parameters:

m	The matrix to set.
fovy	Field of view, in degrees along the Y axis.
aspect	Ratio of x / y.
near	The near clipping plane.
far	The far clipping plane.

void rsMatrixLoadRotate	(	rs_matrix4x4 *	m,
		float	rot,
		float	x,
		float	y,
		float	z
	)

Load a rotation matrix.

This function creates a rotation matrix. The axis of rotation is the (x, y, z) vector.

To rotate a vector, multiply the vector by the created matrix using rsMatrixMultiply.

See http://en.wikipedia.org/wiki/Rotation_matrix .

Parameters:

m	The matrix to set.
rot	How much rotation to do, in degrees.
x	The x component of the vector that is the axis of rotation.
y	The y component of the vector that is the axis of rotation.
z	The z component of the vector that is the axis of rotation.

void rsMatrixLoadScale	(	rs_matrix4x4 *	m,
		float	x,
		float	y,
		float	z
	)

Load a scale matrix.

This function creates a scaling matrix, where each component of a vector is multiplied by a number. This number can be negative.

To scale a vector, multiply the vector by the created matrix using rsMatrixMultiply.

Parameters:

m	The matrix to set.
x	The multiple to scale the x components by.
y	The multiple to scale the y components by.
z	The multiple to scale the z components by.

void rsMatrixLoadTranslate	(	rs_matrix4x4 *	m,
		float	x,
		float	y,
		float	z
	)

Load a translation matrix.

This function creates a translation matrix, where a number is added to each element of a vector.

To translate a vector, multiply the vector by the created matrix using rsMatrixMultiply.

Parameters:

m	The matrix to set.
x	The number to add to each x component.
y	The number to add to each y component.
z	The number to add to each z component.

void rsMatrixMultiply	(	rs_matrix4x4 *	m,
		const rs_matrix4x4 *	rhs
	)

Multiply a matrix into another one.

Sets m to the matrix product m * rhs.

When combining two 4x4 transformation matrices using this function, the resulting matrix will correspond to performing the rhs transformation first followed by the original m transformation.

Parameters:

m	The left matrix of the product and the matrix to be set.
rhs	The right matrix of the product.

void rsMatrixMultiply	(	rs_matrix3x3 *	m,
		const rs_matrix3x3 *	rhs
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void rsMatrixMultiply	(	rs_matrix2x2 *	m,
		const rs_matrix2x2 *	rhs
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

_RS_RUNTIME float4 rsMatrixMultiply	(	rs_matrix4x4 *	m,
		float4	in
	)

Multiply a vector by a matrix.

Returns the post-multiplication of the vector by the matrix, ie. m * in.

When multiplying a float3 to a rs_matrix4x4, the vector is expanded with (1).

When multiplying a float2 to a rs_matrix4x4, the vector is expanded with (0, 1).

When multiplying a float2 to a rs_matrix3x3, the vector is expanded with (0).

This function is available in API version 10-13. Starting with API 14, the function takes a const matrix as the first argument.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

_RS_RUNTIME float3 rsMatrixMultiply	(	rs_matrix3x3 *	m,
		float3	in
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

_RS_RUNTIME float2 rsMatrixMultiply	(	rs_matrix2x2 *	m,
		float2	in
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void rsMatrixRotate	(	rs_matrix4x4 *	m,
		float	rot,
		float	x,
		float	y,
		float	z
	)

Multiply the matrix m with a rotation matrix.

This function modifies a transformation matrix to first do a rotation. The axis of rotation is the (x, y, z) vector.

To apply this combined transformation to a vector, multiply the vector by the created matrix using rsMatrixMultiply.

Parameters:

m	The matrix to modify.
rot	How much rotation to do, in degrees.
x	The x component of the vector that is the axis of rotation.
y	The y component of the vector that is the axis of rotation.
z	The z component of the vector that is the axis of rotation.

void rsMatrixScale	(	rs_matrix4x4 *	m,
		float	x,
		float	y,
		float	z
	)

Multiply the matrix m with a scaling matrix.

This function modifies a transformation matrix to first do a scaling. When scaling, each component of a vector is multiplied by a number. This number can be negative.

To apply this combined transformation to a vector, multiply the vector by the created matrix using rsMatrixMultiply.

Parameters:

m	The matrix to modify.
x	The multiple to scale the x components by.
y	The multiple to scale the y components by.
z	The multiple to scale the z components by.

_RS_RUNTIME void rsMatrixSet	(	rs_matrix4x4 *	m,
		uint32_t	col,
		uint32_t	row,
		float	v
	)

Set an element of a matrix.

Parameters:

m	The matrix that will be modified.
col	The zero-based column of the element to be set.
row	The zero-based row of the element to be set.
v	The value to set.

Warning:

The order of the column and row parameters may be unexpected.

Returns:

void

_RS_RUNTIME void rsMatrixSet	(	rs_matrix3x3 *	m,
		uint32_t	col,
		uint32_t	row,
		float	v
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

_RS_RUNTIME void rsMatrixSet	(	rs_matrix2x2 *	m,
		uint32_t	col,
		uint32_t	row,
		float	v
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void rsMatrixTranslate	(	rs_matrix4x4 *	m,
		float	x,
		float	y,
		float	z
	)

Multiply the matrix m with a translation matrix.

This function modifies a transformation matrix to first do a translation. When translating, a number is added to each component of a vector.

To apply this combined transformation to a vector, multiply the vector by the created matrix using rsMatrixMultiply.

Parameters:

m	The matrix to modify.
x	The number to add to each x component.
y	The number to add to each y component.
z	The number to add to each z component.

void rsMatrixTranspose

(

rs_matrix4x4 *

m

)

Transpose the matrix m in place.

Parameters:

m	The matrix to transpose.

void rsMatrixTranspose

(

rs_matrix3x3 *

m

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void rsMatrixTranspose

(

rs_matrix2x2 *

m

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.