frameworks/rs/scriptc/rs_matrix.rsh File Reference

- Overview
- Globals
- Structs

Functions
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.