RenderScript 矩阵函数

概览

这些函数可用于处理 2x2、3x3 和 4x4 阶的方阵。它们对于图形变换特别有用，并且与 OpenGL 兼容。

我们使用从零开始的行和列索引。例如，rs_matrix4x4 的最后一个元素位于 (3, 3)。

RenderScript 使用列优先矩阵和基于列的向量。向量变换是通过对向量进行后乘实现的，例如 (matrix * vector)，这由 rsMatrixMultiply() 提供。

要创建同时执行两个变换的变换矩阵，请将两个源矩阵相乘，并将第一个变换作为右侧参数。例如，要创建先应用变换 s1 再应用 s2 的变换矩阵，请调用 rsMatrixLoadMultiply(&combined, &s2, &s1)。这源自 s2 * (s1 * v)，即 (s2 * s1) * v。

我们有两种风格的函数来创建变换矩阵：rsMatrixLoadTransformation 和 rsMatrixTransformation。前者风格只是将变换矩阵存储在第一个参数中。后者修改现有的变换矩阵，以便新的变换首先发生。例如，如果您对已执行缩放的矩阵调用 rsMatrixTranslate()，则将生成的矩阵应用于向量时，将首先执行平移，然后执行缩放。

摘要

函数
rsExtractFrustumPlanes 计算视锥体平面
rsIsSphereInFrustum 检查球体是否在视锥体平面内
rsMatrixGet 获取一个元素
rsMatrixInverse 原地逆矩阵
rsMatrixInverseTranspose 原地逆矩阵并转置
rsMatrixLoad 加载或复制矩阵
rsMatrixLoadFrustum 加载视锥体投影矩阵
rsMatrixLoadIdentity 加载单位矩阵
rsMatrixLoadMultiply 乘以两个矩阵
rsMatrixLoadOrtho 加载正交投影矩阵
rsMatrixLoadPerspective 加载透视投影矩阵
rsMatrixLoadRotate 加载旋转矩阵
rsMatrixLoadScale 加载缩放矩阵
rsMatrixLoadTranslate 加载平移矩阵
rsMatrixMultiply 矩阵乘以向量或另一个矩阵
rsMatrixRotate 将旋转应用于变换矩阵
rsMatrixScale 将缩放应用于变换矩阵
rsMatrixSet 设置一个元素
rsMatrixTranslate 将平移应用于变换矩阵
rsMatrixTranspose 原地转置矩阵

函数

rsExtractFrustumPlanes ：计算视锥体平面

void rsExtractFrustumPlanes(const rs_matrix4x4* viewProj, float4* left, float4* righ, float4* top, float4* bottom, float4* near, float4* far); 在 API 级别 24 中添加
void rsExtractFrustumPlanes(const rs_matrix4x4* viewProj, float4* left, float4* right, float4* top, float4* bottom, float4* near, float4* far); 从 API 级别 24 及更高版本 中移除
参数
viewProj从中提取平面的矩阵。
left左平面。
right右平面。
top顶平面。
bottom底平面。
near近平面。
far远平面。
righ

从视图投影矩阵计算 6 个视锥体平面

rsIsSphereInFrustum ：检查球体是否在视锥体平面内

bool rsIsSphereInFrustum(float4* sphere, float4* left, float4* right, float4* top, float4* bottom, float4* near, float4* far);
参数
sphere表示球体的 float4。
left左平面。
right右平面。
top顶平面。
bottom底平面。
near近平面。
far远平面。

如果球体在 6 个视锥体平面内，则返回 true。

rsMatrixGet ：获取一个元素

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);
参数
m从中提取元素的矩阵。
col要提取的元素的从零开始的列索引。
row要提取的元素的从零开始的行索引。

返回矩阵的一个元素。

警告：列和行参数的顺序可能与预期不同。

rsMatrixInverse ：原地逆矩阵

bool rsMatrixInverse(rs_matrix4x4* m);
参数
m要逆矩阵的矩阵。

如果矩阵成功逆矩阵，则返回 true。

rsMatrixInverseTranspose ：原地逆矩阵并转置

bool rsMatrixInverseTranspose(rs_matrix4x4* m);
参数
m要修改的矩阵。

矩阵首先被逆矩阵，然后转置。如果矩阵成功逆矩阵，则返回 true。

rsMatrixLoad ：加载或复制矩阵

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);
参数
destination要设置的矩阵。
array用于设置矩阵值的浮点数数组。这些数组应根据矩阵大小分别包含 4、9 或 16 个浮点数。
source源矩阵。

从浮点数数组或另一个矩阵设置矩阵的元素。

如果从数组加载，浮点数应按行优先顺序排列，即 第 0 行，第 0 列 的元素应在前，后跟 第 0 行，第 1 列 的元素，依此类推。

如果从矩阵加载且源矩阵小于目标矩阵，则目标矩阵的其余部分将填充单位矩阵的元素。例如，将 rs_matrix2x2 加载到 rs_matrix4x4 中将得到

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

rsMatrixLoadFrustum ：加载视锥体投影矩阵

void rsMatrixLoadFrustum(rs_matrix4x4* m, float left, float right, float bottom, float top, float near, float far);
参数
m要设置的矩阵。
left
right
bottom
top
near
far

构建视锥体投影矩阵，转换由六个裁剪平面 left, right, bottom, top, near, far 标识的框。

要将此投影应用于向量，请使用 rsMatrixMultiply() 将向量乘以创建的矩阵。

rsMatrixLoadIdentity ：加载单位矩阵

void rsMatrixLoadIdentity(rs_matrix2x2* m);
void rsMatrixLoadIdentity(rs_matrix3x3* m);
void rsMatrixLoadIdentity(rs_matrix4x4* m);
参数
m要设置的矩阵。

将矩阵的元素设置为单位矩阵。

rsMatrixLoadMultiply ：乘以两个矩阵

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);
参数
m要设置的矩阵。
lhs乘积的左侧矩阵。
rhs乘积的右侧矩阵。

将 m 设置为 lhs * rhs 的矩阵乘积。

要组合两个 4x4 变换矩阵，请将第二个变换矩阵乘以第一个变换矩阵。例如，要创建先应用变换 s1 再应用 s2 的变换矩阵，请调用 rsMatrixLoadMultiply(&combined, &s2, &s1)。

警告：在版本 21 之前，不支持将结果存储回右侧矩阵，这将导致未定义行为。请改用 rsMatrixMultiply。例如，不要执行 rsMatrixLoadMultiply (&m2r, &m2r, &m2l)，请使用 rsMatrixMultiply (&m2r, &m2l)。rsMatrixLoadMultiply (&m2l, &m2r, &m2l) 按预期工作。

rsMatrixLoadOrtho ：加载正交投影矩阵

void rsMatrixLoadOrtho(rs_matrix4x4* m, float left, float right, float bottom, float top, float near, float far);
参数
m要设置的矩阵。
left
right
bottom
top
near
far

构建正交投影矩阵，将由六个裁剪平面 left, right, bottom, top, near, far 标识的框转换成一个单位立方体，其中一个角位于 (-1, -1, -1)，对角位于 (1, 1, 1)。

要将此投影应用于向量，请使用 rsMatrixMultiply() 将向量乘以创建的矩阵。

请参阅 https://en.wikipedia.org/wiki/Orthographic_projection 。

rsMatrixLoadPerspective ：加载透视投影矩阵

void rsMatrixLoadPerspective(rs_matrix4x4* m, float fovy, float aspect, float near, float far);
参数
m要设置的矩阵。
fovy视野，沿 Y 轴的角度（以度为单位）。
aspectx / y 的比率。
nearNear clipping plane.
farFar clipping plane.

构建透视投影矩阵，假设视野对称。

要将此投影应用于向量，请使用 rsMatrixMultiply() 将向量乘以创建的矩阵。

rsMatrixLoadRotate ：加载旋转矩阵

void rsMatrixLoadRotate(rs_matrix4x4* m, float rot, float x, float y, float z);
参数
m要设置的矩阵。
rot旋转量，以度为单位。
x作为旋转轴的向量的 X 分量。
y作为旋转轴的向量的 Y 分量。
z作为旋转轴的向量的 Z 分量。

此函数创建旋转矩阵。旋转轴是向量 (x, y, z)。

要旋转向量，请使用 rsMatrixMultiply() 将向量乘以创建的矩阵。

请参阅 https://en.wikipedia.org/wiki/Rotation_matrix 。

rsMatrixLoadScale ：加载缩放矩阵

void rsMatrixLoadScale(rs_matrix4x4* m, float x, float y, float z);
参数
m要设置的矩阵。
x用于缩放 X 分量的乘数。
y用于缩放 Y 分量的乘数。
z用于缩放 Z 分量的乘数。

此函数创建缩放矩阵，其中向量的每个分量都乘以一个数字。此数字可以为负数。

要缩放向量，请使用 rsMatrixMultiply() 将向量乘以创建的矩阵。

rsMatrixLoadTranslate ：加载平移矩阵

void rsMatrixLoadTranslate(rs_matrix4x4* m, float x, float y, float z);
参数
m要设置的矩阵。
x要添加到每个 X 分量的数字。
y要添加到每个 Y 分量的数字。
z要添加到每个 Z 分量的数字。

此函数创建平移矩阵，其中一个数字被添加到向量的每个元素。

要平移向量，请使用 rsMatrixMultiply() 将向量乘以创建的矩阵。

rsMatrixMultiply ：矩阵乘以向量或另一个矩阵

float2 rsMatrixMultiply(const rs_matrix2x2* m, float2 in); 在 API 级别 14 中添加
float2 rsMatrixMultiply(rs_matrix2x2* m, float2 in); 从 API 级别 14 及更高版本 中移除
float3 rsMatrixMultiply(const rs_matrix3x3* m, float2 in); 在 API 级别 14 中添加
float3 rsMatrixMultiply(const rs_matrix3x3* m, float3 in); 在 API 级别 14 中添加
float3 rsMatrixMultiply(rs_matrix3x3* m, float2 in); 从 API 级别 14 及更高版本 中移除
float3 rsMatrixMultiply(rs_matrix3x3* m, float3 in); 从 API 级别 14 及更高版本 中移除
float4 rsMatrixMultiply(const rs_matrix4x4* m, float2 in); 在 API 级别 14 中添加
float4 rsMatrixMultiply(const rs_matrix4x4* m, float3 in); 在 API 级别 14 中添加
float4 rsMatrixMultiply(const rs_matrix4x4* m, float4 in); 在 API 级别 14 中添加
float4 rsMatrixMultiply(rs_matrix4x4* m, float2 in); 从 API 级别 14 及更高版本 中移除
float4 rsMatrixMultiply(rs_matrix4x4* m, float3 in); 从 API 级别 14 及更高版本 中移除
float4 rsMatrixMultiply(rs_matrix4x4* m, float4 in); 从 API 级别 14 及更高版本 中移除
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);
参数
m乘积的左侧矩阵，也是要设置的矩阵。
rhs乘积的右侧矩阵。
in

对于矩阵乘以矩阵的变体，将 m 设置为矩阵乘积 m * rhs。

使用此函数组合两个 4x4 变换矩阵时，生成的矩阵将对应于先执行 rhs 变换，然后执行原始 m 变换。

对于矩阵乘以向量的变体，返回向量与矩阵的后乘结果，即 m * in。

将 float3 乘以 rs_matrix4x4 时，向量会用 (1) 扩展。

将 float2 乘以 rs_matrix4x4 时，向量会用 (0, 1) 扩展。

将 float2 乘以 rs_matrix3x3 时，向量会用 (0) 扩展。

从 API 级别 14 开始，此函数将 const 矩阵作为第一个参数。

rsMatrixRotate ：将旋转应用于变换矩阵

void rsMatrixRotate(rs_matrix4x4* m, float rot, float x, float y, float z);
参数
m要修改的矩阵。
rot旋转量，以度为单位。
x作为旋转轴的向量的 X 分量。
y作为旋转轴的向量的 Y 分量。
z作为旋转轴的向量的 Z 分量。

将矩阵 m 乘以旋转矩阵。

此函数修改变换矩阵，以便先执行旋转。旋转轴是向量 (x, y, z)。

要将此组合变换应用于向量，请使用 rsMatrixMultiply() 将向量乘以创建的矩阵。

rsMatrixScale ：将缩放应用于变换矩阵

void rsMatrixScale(rs_matrix4x4* m, float x, float y, float z);
参数
m要修改的矩阵。
x用于缩放 X 分量的乘数。
y用于缩放 Y 分量的乘数。
z用于缩放 Z 分量的乘数。

将矩阵 m 乘以缩放矩阵。

此函数修改变换矩阵，以便先执行缩放。缩放时，向量的每个分量都乘以一个数字。此数字可以为负数。

要将此组合变换应用于向量，请使用 rsMatrixMultiply() 将向量乘以创建的矩阵。

rsMatrixSet ：设置一个元素

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);
参数
m将被修改的矩阵。
col要设置的元素的从零开始的列索引。
row要设置的元素的从零开始的行索引。
v要设置的值。

设置矩阵的一个元素。

警告：列和行参数的顺序可能与预期不同。

rsMatrixTranslate ：将平移应用于变换矩阵

void rsMatrixTranslate(rs_matrix4x4* m, float x, float y, float z);
参数
m要修改的矩阵。
x要添加到每个 X 分量的数字。
y要添加到每个 Y 分量的数字。
z要添加到每个 Z 分量的数字。

将矩阵 m 乘以平移矩阵。

此函数修改变换矩阵，以便先执行平移。平移时，一个数字被添加到向量的每个分量。

要将此组合变换应用于向量，请使用 rsMatrixMultiply() 将向量乘以创建的矩阵。

rsMatrixTranspose ：原地转置矩阵

void rsMatrixTranspose(rs_matrix2x2* m);
void rsMatrixTranspose(rs_matrix3x3* m);
void rsMatrixTranspose(rs_matrix4x4* m);
参数
m要转置的矩阵。

原地转置矩阵 m。