# 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
rsMatrixLoadMultiply Multiply two matrices
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

 void rsExtractFrustumPlanes(const rs_matrix4x4* viewProj, float4* left, float4* righ, float4* top, float4* bottom, float4* near, float4* far); Added in API level 24 void rsExtractFrustumPlanes(const rs_matrix4x4* viewProj, float4* left, float4* right, float4* top, float4* bottom, float4* near, float4* far); Removed from API level 24 and higher
##### Parameters
viewProj Matrix to extract planes from. Left plane. Right plane. Top plane. Bottom plane. Near plane. Far plane.

Computes 6 frustum planes from the view projection matrix

#### rsIsSphereInFrustum: Checks if a sphere is within the frustum planes

 bool rsIsSphereInFrustum(float4* sphere, float4* left, float4* right, float4* top, float4* bottom, float4* near, float4* far);
##### Parameters
sphere float4 representing the sphere. Left plane. Right plane. Top plane. Bottom plane. Near plane. Far plane.

Returns true if the sphere is within the 6 frustum planes.

#### rsMatrixGet: Get one element

 float rsMatrixGet(const rs_matrix2x2* m, uint32_t col, uint32_t row); float rsMatrixGet(const rs_matrix3x3* m, uint32_t col, uint32_t row); float rsMatrixGet(const rs_matrix4x4* m, uint32_t col, uint32_t row);
##### Parameters
m Matrix to extract the element from. Zero-based column of the element to be extracted. 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

 bool rsMatrixInverse(rs_matrix4x4* m);
##### Parameters
m Matrix to invert.

Returns true if the matrix was successfully inverted.

#### rsMatrixInverseTranspose: Inverts and transpose a matrix in place

 bool rsMatrixInverseTranspose(rs_matrix4x4* m);
##### 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

 void rsMatrixLoad(rs_matrix2x2* destination, const float* array); void rsMatrixLoad(rs_matrix2x2* destination, const rs_matrix2x2* source); void rsMatrixLoad(rs_matrix3x3* destination, const float* array); void rsMatrixLoad(rs_matrix3x3* destination, const rs_matrix3x3* source); void rsMatrixLoad(rs_matrix4x4* destination, const float* array); void rsMatrixLoad(rs_matrix4x4* destination, const rs_matrix2x2* source); void rsMatrixLoad(rs_matrix4x4* destination, const rs_matrix3x3* source); void rsMatrixLoad(rs_matrix4x4* destination, const rs_matrix4x4* source);
##### Parameters
destination Matrix to set. Array of values to set the matrix to. These arrays should be 4, 9, or 16 floats long, depending on the matrix size. 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:

 m00 m01 0 0 m10 m11 0 0 0.0 0.0 1 0 0.0 0.0 0 1

#### rsMatrixLoadFrustum: Load a frustum projection matrix

 void rsMatrixLoadFrustum(rs_matrix4x4* m, float left, float right, float bottom, float top, float near, float far);
##### Parameters
m Matrix to set.

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().

##### Parameters
m Matrix to set.

Set the elements of a matrix to the identity matrix.

#### rsMatrixLoadMultiply: Multiply two matrices

 void rsMatrixLoadMultiply(rs_matrix2x2* m, const rs_matrix2x2* lhs, const rs_matrix2x2* rhs); void rsMatrixLoadMultiply(rs_matrix3x3* m, const rs_matrix3x3* lhs, const rs_matrix3x3* rhs); void rsMatrixLoadMultiply(rs_matrix4x4* m, const rs_matrix4x4* lhs, const rs_matrix4x4* rhs);
##### Parameters
m Matrix to set. Left matrix of the product. Right matrix of the product.

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: 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

 void rsMatrixLoadOrtho(rs_matrix4x4* m, float left, float right, float bottom, float top, float near, float far);
##### Parameters
m Matrix to set.

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

 void rsMatrixLoadPerspective(rs_matrix4x4* m, float fovy, float aspect, float near, float far);
##### Parameters
m Matrix to set. Field of view, in degrees along the Y axis. Ratio of x / y. Near clipping plane. 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().

 void rsMatrixLoadRotate(rs_matrix4x4* m, float rot, float x, float y, float z);
##### Parameters
m Matrix to set. How much rotation to do, in degrees. X component of the vector that is the axis of rotation. Y component of the vector that is the axis of rotation. 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 .

 void rsMatrixLoadScale(rs_matrix4x4* m, float x, float y, float z);
##### Parameters
m Matrix to set. Multiple to scale the x components by. Multiple to scale the y components by. 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().

 void rsMatrixLoadTranslate(rs_matrix4x4* m, float x, float y, float z);
##### Parameters
m Matrix to set. Number to add to each x component. Number to add to each y component. 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

 float2 rsMatrixMultiply(const rs_matrix2x2* m, float2 in); Added in API level 14 float2 rsMatrixMultiply(rs_matrix2x2* m, float2 in); Removed from API level 14 and higher float3 rsMatrixMultiply(const rs_matrix3x3* m, float2 in); Added in API level 14 float3 rsMatrixMultiply(const rs_matrix3x3* m, float3 in); Added in API level 14 float3 rsMatrixMultiply(rs_matrix3x3* m, float2 in); Removed from API level 14 and higher float3 rsMatrixMultiply(rs_matrix3x3* m, float3 in); Removed from API level 14 and higher float4 rsMatrixMultiply(const rs_matrix4x4* m, float2 in); Added in API level 14 float4 rsMatrixMultiply(const rs_matrix4x4* m, float3 in); Added in API level 14 float4 rsMatrixMultiply(const rs_matrix4x4* m, float4 in); Added in API level 14 float4 rsMatrixMultiply(rs_matrix4x4* m, float2 in); Removed from API level 14 and higher float4 rsMatrixMultiply(rs_matrix4x4* m, float3 in); Removed from API level 14 and higher float4 rsMatrixMultiply(rs_matrix4x4* m, float4 in); Removed from API level 14 and higher void rsMatrixMultiply(rs_matrix2x2* m, const rs_matrix2x2* rhs); void rsMatrixMultiply(rs_matrix3x3* m, const rs_matrix3x3* rhs); void rsMatrixMultiply(rs_matrix4x4* m, const rs_matrix4x4* rhs);
##### Parameters
m Left matrix of the product and the matrix to be set. Right matrix of the product.

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

 void rsMatrixRotate(rs_matrix4x4* m, float rot, float x, float y, float z);
##### Parameters
m Matrix to modify. How much rotation to do, in degrees. X component of the vector that is the axis of rotation. Y component of the vector that is the axis of rotation. 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

 void rsMatrixScale(rs_matrix4x4* m, float x, float y, float z);
##### Parameters
m Matrix to modify. Multiple to scale the x components by. Multiple to scale the y components by. 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

 void rsMatrixSet(rs_matrix2x2* m, uint32_t col, uint32_t row, float v); void rsMatrixSet(rs_matrix3x3* m, uint32_t col, uint32_t row, float v); void rsMatrixSet(rs_matrix4x4* m, uint32_t col, uint32_t row, float v);
##### Parameters
m Matrix that will be modified. Zero-based column of the element to be set. Zero-based row of the element to be set. 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

 void rsMatrixTranslate(rs_matrix4x4* m, float x, float y, float z);
##### Parameters
m Matrix to modify. Number to add to each x component. Number to add to each y component. 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

 void rsMatrixTranspose(rs_matrix2x2* m); void rsMatrixTranspose(rs_matrix3x3* m); void rsMatrixTranspose(rs_matrix4x4* m);
##### Parameters
m Matrix to transpose.

Transpose the matrix m in place.

[{ "type": "thumb-down", "id": "missingTheInformationINeed", "label":"Missing the information I need" },{ "type": "thumb-down", "id": "tooComplicatedTooManySteps", "label":"Too complicated / too many steps" },{ "type": "thumb-down", "id": "outOfDate", "label":"Out of date" },{ "type": "thumb-down", "id": "samplesCodeIssue", "label":"Samples / code issue" },{ "type": "thumb-down", "id": "otherDown", "label":"Other" }]
[{ "type": "thumb-up", "id": "easyToUnderstand", "label":"Easy to understand" },{ "type": "thumb-up", "id": "solvedMyProblem", "label":"Solved my problem" },{ "type": "thumb-up", "id": "otherUp", "label":"Other" }]