RenderScript Matrix Functions
Stay organized with collections
Save and categorize content based on your preferences.
Overview
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.
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-major matrices and 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.
Summary
| Functions | |
|---|---|
| rsExtractFrustumPlanes | Compute frustum planes |
| rsIsSphereInFrustum | Checks if a sphere is within the frustum planes |
| rsMatrixGet | Get one element |
| rsMatrixInverse | Inverts a matrix in place |
| rsMatrixInverseTranspose | Inverts and transpose a matrix in place |
| rsMatrixLoad | Load or copy a matrix |
| rsMatrixLoadFrustum | Load a frustum projection matrix |
| rsMatrixLoadIdentity | Load identity matrix |
| rsMatrixLoadMultiply | Multiply two matrices |
| rsMatrixLoadOrtho | Load an orthographic projection matrix |
| rsMatrixLoadPerspective | Load a perspective projection matrix |
| rsMatrixLoadRotate | Load a rotation matrix |
| rsMatrixLoadScale | Load a scaling matrix |
| rsMatrixLoadTranslate | Load a translation matrix |
| rsMatrixMultiply | Multiply a matrix by a vector or another matrix |
| rsMatrixRotate | Apply a rotation to a transformation matrix |
| rsMatrixScale | Apply a scaling to a transformation matrix |
| rsMatrixSet | Set one element |
| rsMatrixTranslate | Apply a translation to a transformation matrix |
| rsMatrixTranspose | Transpose a matrix place |
Functions
rsExtractFrustumPlanes : Compute frustum planes
Parameters
| viewProj | Matrix to extract planes from. |
|---|---|
| left | Left plane. |
| right | Right plane. |
| top | Top plane. |
| bottom | Bottom plane. |
| near | Near plane. |
| far | Far plane. |
| righ |
Computes 6 frustum planes from the view projection matrix
rsIsSphereInFrustum : Checks if a sphere is within the frustum planes
Parameters
| sphere | float4 representing the sphere. |
|---|---|
| left | Left plane. |
| right | Right plane. |
| top | Top plane. |
| bottom | Bottom plane. |
| near | Near plane. |
| far | Far plane. |
Returns true if the sphere is within the 6 frustum planes.
rsMatrixGet : Get one element
Parameters
| m | Matrix to extract the element from. |
|---|---|
| col | Zero-based column of the element to be extracted. |
| row | Zero-based row of the element to extracted. |
Returns one element of a matrix.
Warning: The order of the column and row parameters may be unexpected.
rsMatrixInverse : Inverts a matrix in place
Parameters
| m | Matrix to invert. |
|---|
Returns true if the matrix was successfully inverted.
rsMatrixInverseTranspose : Inverts and transpose a matrix in place
Parameters
| m | Matrix to modify. |
|---|
The matrix is first inverted then transposed. Returns true if the matrix was successfully inverted.
rsMatrixLoad : Load or copy a matrix
Parameters
| destination | Matrix to set. |
|---|---|
| array | Array of values to set the matrix to. These arrays should be 4, 9, or 16 floats long, depending on the matrix size. |
| source | Source matrix. |
Set the elements of a matrix from an array of floats or from another matrix.
If loading from an array, the 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.
If loading from a matrix and the source 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:
rsMatrixLoadFrustum : Load a frustum projection matrix
Parameters
| m | Matrix to set. |
|---|---|
| left | |
| right | |
| bottom | |
| top | |
| near | |
| far |
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().
rsMatrixLoadIdentity : Load identity matrix
Parameters
| m | Matrix to set. |
|---|
Set the elements of a matrix to the identity matrix.
rsMatrixLoadMultiply : Multiply two matrices
Parameters
| m | Matrix to set. |
|---|---|
| lhs | Left matrix of the product. |
| rhs | Right matrix of the product. |
Sets m to the matrix product of lhs * rhs.
To combine two 4x4 transformation 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: Prior to 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.
rsMatrixLoadOrtho : Load an orthographic projection matrix
Parameters
| m | Matrix to set. |
|---|---|
| left | |
| right | |
| bottom | |
| top | |
| near | |
| far |
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 .
rsMatrixLoadPerspective : Load a perspective projection matrix
Parameters
| m | Matrix to set. |
|---|---|
| fovy | Field of view, in degrees along the Y axis. |
| aspect | Ratio of x / y. |
| near | Near clipping plane. |
| far | Far clipping plane. |
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().
rsMatrixLoadRotate : Load a rotation matrix
Parameters
| m | Matrix to set. |
|---|---|
| rot | How much rotation to do, in degrees. |
| x | X component of the vector that is the axis of rotation. |
| y | Y component of the vector that is the axis of rotation. |
| z | Z component of the vector that is the axis of rotation. |
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 https://en.wikipedia.org/wiki/Rotation_matrix .
rsMatrixLoadScale : Load a scaling matrix
Parameters
| m | Matrix to set. |
|---|---|
| x | Multiple to scale the x components by. |
| y | Multiple to scale the y components by. |
| z | Multiple to scale the z components by. |
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().
rsMatrixLoadTranslate : Load a translation matrix
Parameters
| m | Matrix to set. |
|---|---|
| x | Number to add to each x component. |
| y | Number to add to each y component. |
| z | Number to add to each z component. |
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().
rsMatrixMultiply : Multiply a matrix by a vector or another matrix
Parameters
| m | Left matrix of the product and the matrix to be set. |
|---|---|
| rhs | Right matrix of the product. |
| in |
For the matrix by matrix variant, 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.
For the matrix by vector variant, 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).
Starting with API 14, this function takes a const matrix as the first argument.
rsMatrixRotate : Apply a rotation to a transformation matrix
Parameters
| m | Matrix to modify. |
|---|---|
| rot | How much rotation to do, in degrees. |
| x | X component of the vector that is the axis of rotation. |
| y | Y component of the vector that is the axis of rotation. |
| z | Z component of the vector that is the axis of rotation. |
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().
rsMatrixScale : Apply a scaling to a transformation matrix
Parameters
| m | Matrix to modify. |
|---|---|
| x | Multiple to scale the x components by. |
| y | Multiple to scale the y components by. |
| z | Multiple to scale the z components by. |
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().
rsMatrixSet : Set one element
Parameters
| m | Matrix that will be modified. |
|---|---|
| col | Zero-based column of the element to be set. |
| row | Zero-based row of the element to be set. |
| v | Value to set. |
Set an element of a matrix.
Warning: The order of the column and row parameters may be unexpected.
rsMatrixTranslate : Apply a translation to a transformation matrix
Parameters
| m | Matrix to modify. |
|---|---|
| x | Number to add to each x component. |
| y | Number to add to each y component. |
| z | Number to add to each z component. |
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().
rsMatrixTranspose : Transpose a matrix place
Parameters
| m | Matrix to transpose. |
|---|
Transpose the matrix m in place.