RenderScript Runtime API 参考文档

概览

RenderScript 是一个高性能运行时,提供原生级别的计算操作。 RenderScript 代码会在运行时在设备上编译,以实现平台独立性。

本参考文档介绍了 RenderScript 运行时 API,您可以利用它们在 C99 中编写 RenderScript 代码。系统会自动为您添加 RenderScript 计算头文件。

如需使用 RenderScript,您需要利用此处介绍的 RenderScript 运行时 API 以及适用于 RenderScript 的 Android 框架 API。如需查看有关 Android 框架 API 的文档,请参阅 android.renderscript 软件包参考文档。

如需详细了解如何使用 RenderScript 进行开发以及运行时 API 和 Android 框架 API 如何交互,请参阅 RenderScript 开发者指南RenderScript 示例

数字类型

标量:

RenderScript 支持以下标量数值类型:

8 位 16 位 32 位 64 位
整数: 字符、int8_t 简短、int16_t int32_t long、long long、int64_t
无符号整数: uchar、uint8_t ushort、uint16_t uint、uint32_t ulong、uint64_t
浮点数: 半场 浮点数 double

矢量:

RenderScript 支持长度为 2、3 和 4 的固定大小的矢量。矢量使用通用类型名称后跟 2、3 或 4 来声明。例如,float4int3double2ulong4

如需创建矢量字面量,请使用矢量类型,后跟用大括号括起来的值,例如 (float3){1.0f, 2.0f, 3.0f}

可以使用不同的命名样式访问矢量的条目。

可以在变量名称后面加点“和”来访问单个条目:

  • 即 x、y、z 和 w,
  • 字母 r、g、b 和 a
  • 字母 s 或 S,后跟从零开始的索引。

例如,使用 int4 myVar; 时,以下代码是等效的:
myVar.x == myVar.r == myVar.s0 == myVar.S0
myVar.y == myVar.g == myVar.s1 == myVar.S1
myVar.z == myVar.b == myVar.s2 == myVar.S2
myVar.w == myVar.a == myVar.s3 == myVar.S3

使用由多个字母或索引串联而成的标识符,可以一次访问矢量的多个条目。生成的向量的大小等于指定的条目数。

在上面的示例中,可以使用 myVar.yzmyVar.gbmyVar.s12myVar.S12 访问中间两个条目。

这些条目不必是连续的,也不必按升序排列。只要我们不尝试向其分配条目,条目即可重复。您也不能混用不同的命名样式。

下面列举了一些示例来说明可以或不可以的行为:
float4 v4;
float3 v3;
float2 v2;
v2 = v4.xx; // Valid
v3 = v4.zxw; // Valid
v3 = v4.bba; // Valid
v3 = v4.s032; // Valid
v3.s120 = v4.S233; // Valid
v4.yz = v3.rg; // Valid
v4.yzx = v3.rg; // Invalid: mismatched sizes
v4.yzz = v3; // Invalid: z appears twice in an assignment
v3 = v3.xas0; // Invalid: can't mix xyzw with rgba nor s0...
v3 = v4.s034; // Invalid: the digit can only be 0, 1, 2, or 3

矩阵和四元数:

RenderScript 支持尺寸为 2x2、3x3 和 4x4 的固定大小的浮点数矩阵。 类型分别名为 rs_Matrix2x2rs_Matrix3x3rs_Matrix4x4。如需查看操作列表,请参阅矩阵函数

也可以通过 rs_quaternion 支持四元数。有关操作列表,请参阅 Quaterion 函数

类型
字符 2 两个 8 位有符号整数
字符 3 三个 8 位有符号整数
字符 4 4 个 8 位有符号整数
double2 两个 64 位浮点数
double3 三个 64 位浮点数
double4 四个 64 位浮点数
float2 两个 32 位浮点
float3 三个 32 位浮点数
float4 四个 32 位浮点数
16 位浮点值
half2 两个 16 位浮点数
half3 三个 16 位浮点数
half4 四个 16 位浮点数
int16_t 16 位有符号整数
int2 两个 32 位有符号整数
int3 三个 32 位有符号整数
int32_t 32 位有符号整数
int4 4 个 32 位有符号整数
int64_t 64 位有符号整数
int8_t 8 位有符号整数
long2 两个 64 位有符号整数
long3 三个 64 位有符号整数
long4 4 个 64 位有符号整数
rs_Matrix2x2 32 位浮点数的 2x2 矩阵
rs_Matrix3x3 32 位浮点数的 3x3 矩阵
rs_Matrix4x4 32 位浮点数的 4x4 矩阵
rs_quaternion 四元数
short2 两个 16 位有符号整数
short3 三个 16 位有符号整数
short4 4 个 16 位有符号整数
size_t [尺码 t] 无符号大小类型
ssize_t 签名大小类型
uchar 8 位无符号整数
uchar2 两个 8 位无符号整数
uchar3 三个 8 位无符号整数
uchar4 4 个 8 位无符号整数
uint 32 位无符号整数
uint16_t 16 位无符号整数
uint2 两个 32 位无符号整数
uint3 三个 32 位无符号整数
uint32_t 32 位无符号整数
uint4 4 个 32 位无符号整数
uint64_t 64 位无符号整数
uint8_t 8 位无符号整数
ulong 64 位无符号整数
ulong2 两个 64 位无符号整数
ulong3 三个 64 位无符号整数
ulong4 4 个 64 位无符号整数
ushort 16 位无符号整数
ushort2 两个 16 位无符号整数
ushort3 三个 16 位无符号整数
ushort4 4 个 16 位无符号整数

对象类型

以下类型用于操控 RenderScript 对象,例如分配、采样器、元素和脚本。其中大多数对象都是使用 Java RenderScript API 创建的。

类型
rs_allocation 分配句柄
rs_allocation_cubemap_face 用于选择立方体贴图面的枚举
rs_allocation_usage_type 用于指定如何使用分配的位字段
rs_data_Kind 元素数据种类
rs_data_type 元素基本数据类型
rs_element 元素句柄
rs_sampler 采样器句柄
rs_sampler_value 采样器封装 T 值
rs_script 脚本句柄
rs_type 类型句柄
rs_yuv_format YUV 格式

转换函数

以下函数可以从数值矢量类型转换为另一种类型,或者从一种颜色表示转换为另一种颜色表示。

函数
转换 转换数值矢量
rsPackColorTo8888 基于浮点数创建 uchar4 RGBA
rsUnpackColor8888 从 uchar4 创建 float4 RGBA
rsYuvToRGBA 将 YUV 值转换为 RGBA

数学常量和函数

以下数学函数可应用于标量和矢量。应用于向量时,返回的值是应用于每个输入条目的函数的向量。

例如:
float3 a, b;
// The following call sets
// a.x to sin(b.x),
// a.y to sin(b.y), and
// a.z to sin(b.z).
a = sin(b);

有关 distance() 和 length() 等可将输入解释为 n 维空间中单个向量的函数,请参阅矢量数学函数

对 32 位浮点数进行数学运算的精度受 pragmas rs_fp_relaxed 和 rs_fp_full 的影响。在 rs_fp_relaxed 下,次正常值可能会被刷新为 0,并可能会舍入到零。相比之下,rs_fp_full 需要正确处理次正规值,即小于 1.17549435e-38f。rs_fp_rull 还需要舍入到最接近并且等于偶数。

通过使用常见数学函数的变体,可以实现不同的精度/速度权衡。名称以

  • native_:可能包含精确度较低的自定义硬件实现。此外,次正规值可能会被刷新到零,可以使用向零舍入,并且可能无法正确处理 NaN 和无穷大输入。
  • double_:可以使用 16 位浮点数执行内部计算。此外,次正常值可能会清零,也可以使用向零舍入。

常量
M_1_PI 1 / pi,以 32 位浮点数表示
M_2_PI 2 / pi(32 位浮点数)
M_2_SQRTPI 2 / sqrt(pi),作为 32 位浮点数
M_E e,以 32 位浮点数表示
M_LN10 log_e(10),采用 32 位浮点数
M_LN2 log_e(2),采用 32 位浮点数
M_LOG10E log_10(e),作为 32 位浮点数
M_LOG2E log_2(e),格式为 32 位浮点
M_PI pi,以 32 位浮点数表示
M_PI_2 pi / 2,作为 32 位浮点数
M_PI_4 pi / 4,以 32 位浮点数表示
M_SQRT1_2 1 / sqrt(2),作为 32 位浮点数
M_SQRT2 sqrt(2) 作为 32 位浮点数
函数
abs 整数的绝对值
acos 反余弦
acosh 反双曲余弦
acospi 反余弦除以圆周率
asin 反正弦
Asinh 反双曲正弦
asinpi 反正弦除以圆周率
atan 反正切
atan2 比率的反正切
atan2pi 比率的反正切值除以圆周率
atanh 反双曲正切
atanpi 反正切值除以圆周率
cbrt 立方根
ceil 不小于某个值的最小整数
夹扣 将值限制在某个范围内
clz 前导 0 位的数量
文案签名 将一个数字的符号复制到另一个
cos 余弦
cosh 连字符余弦
cospi 数值的余弦值与 pi 的乘积
将弧度转换为角度
erf 数学误差函数
erfc 数学互补误差函数
exp e 取值为数字
exp10 10 取整
exp2 2 变为数字
expm1 e 增加为减 1 的数字
Fab 浮点数的绝对值
fdim 两个值之间的正差
floor 不大于值的最小整数
fma 相乘和相加
fmax 最多两个浮点数
fmin 最少 2 个浮点数
fmod
分数 正小数部分
frexp 二元尾数和指数
half_recip 按照 16 位精度计算的倒数
half_rsqrt 按 16 位精度计算的平方根的倒数
half_sqrt 计算到 16 位精度的平方根
hypot 斜边
ilogb 以二基数为底的指数
ldexp 根据尾数和指数创建浮点数
lgamma 伽玛函数的自然对数
log 自然对数
log10 以 10 为底的对数
log1p 数值加 1 的自然对数
log2 以 2 为底的对数
logb 以二基数为底的指数
疯狂 相乘和相加
max 上限
min 下限
合辑 混合两个值
modf 积分分量和小数分量
nan 不是数字
nan_half 不是数字
native_acos 近似反余弦
native_acosh 近似双曲余弦
native_acospi 近似反余弦值除以圆周率
native_asin 近似反正弦
native_asinh 近似双曲正弦
native_asinpi 近似反正弦除以 pi
native_atan 近似反正切
native_atan2 比率的近似反正切
native_atan2pi 比率的近似反正切值,除以 pi
native_atanh 近似双曲正切
native_atanpi 近似反正切值/圆周率
native_cbrt 近似立方根
native_cos 近似余弦
native_cosh 近似双曲余弦
native_cospi 数值的近似余弦值乘以圆周率
native_divide 近似除法
native_exp 将 e 近似计算为数字
native_exp10 将近似 10 取为数字
native_exp2 将近似 2 取为数值
native_expm1 e 近似值,取数值减 1
native_hypot 近似斜边
native_log 近似自然对数
native_log10 近似以 10 为底的对数
native_log1p 数值加 1 的近似自然对数
native_log2 近似以 2 为底的对数
native_powr 近似正底数为指数幂
native_recip 近似倒数
native_rootn 近似 n 次方根
native_rsqrt 平方根的近似倒数
native_sin 近似正弦
native_sincos 近似正弦和余弦
native_sinh 近似双曲正弦
native_sinpi 数值的近似正弦与圆周率的乘积
native_sqrt 近似平方根
native_tan 近似正切
native_tanh 近似双曲正切
native_tanpi 数值的近似正切值与圆周率的乘积
nextafter 下一个浮点数
pow 基数为指数的幂
pown 基数为整数指数的基数
powr 以正数为底数为指数的数值
弧度 将角度转换为弧度
余数 除法余数
remquo 除法的余数和商
rint 四舍五入到偶数
rootn n 次方根
round 向远离 0 方向舍入
rsRand 伪随机数
rsqrt 平方根的倒数
签名 值的符号
sin 正弦
sincos 正弦和余弦
sinh 双曲正弦
sinpi 数值的正弦与圆周率的乘积
sqrt 平方根
step 如果小于某个值,则为 0,否则为 0
tan 正切
Tanh 双曲正切
Tanpi 数值乘以 pi 的正切值
tgamma 伽玛函数
trunc 截断浮点数

矢量数学函数

这些函数将输入参数解释为 N 维空间中向量的表示。

对 32 位浮点数进行数学运算的精度受 pragmas rs_fp_relaxed 和 rs_fp_full 的影响。如需了解详情,请参阅数学常量和函数

通过使用常见数学函数的变体,可以实现不同的精度/速度权衡。名称以

  • native_:可能包含精确度较低的自定义硬件实现。此外,次正规值可能会被刷新到零,可以使用向零舍入,并且可能无法正确处理 NaN 和无穷大输入。
  • fast_:可以使用 16 位浮点数执行内部计算。此外,次正常值可能会清零,也可以使用向零舍入。

函数
叉号 两个向量的叉积
距离 两点之间的距离
两个向量的点积
Fast_distance 两点之间的大致距离
Fast_length 矢量的大致长度
Fast_normalize 近似归一化向量
长度 矢量的长度
native_distance 两点之间的大致距离
native_length 矢量的大致长度
native_normalize 对向量进行近似归一化
归一化 归一化向量

矩阵函数

这些函数可让您操控 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 转置矩阵地点

四元数函数

以下函数用于操控四元数。

函数
rsQuaternionAdd 将两个四元数相加
rsQuaternionConjugate 共合四元数
rsQuaternionDot 两个四元数的点积
rsQuaternionGetMatrixUnit 从四元数获取旋转矩阵
rsQuaternionLoadRotate 创建旋转四元数
rsQuaternionLoadRotateUnit 表示围绕任意单位向量旋转的四元数
rsQuaternionMultiply 将四元数与标量或其他四元数相乘
rsQuaternionNormalize 将四元数归一化
rsQuaternionSet 创建四元数
rsQuaternionSlerp 两个四元数之间的球面线性插值

原子更新函数

如需更新多个线程之间共享的值,请使用以下函数。它们可确保值以原子方式更新,即以正确的顺序执行内存读取、更新和内存写入。

这些函数比其非原子函数慢,因此请仅在需要同步时使用。

请注意,在 RenderScript 中,即使您没有明确创建代码,代码也可能会在单独的线程中运行。RenderScript 运行时通常会将一个内核的执行拆分到多个线程中。更新全局变量应使用原子函数完成。如果可能,请修改算法,完全避免采用这些错误。

函数
rsAtomicAdd 线程安全添加
rsAtomicAnd 线程安全按位和
rsAtomicCas 线程安全比较和设置
rsAtomicDec 线程安全递减
rsAtomicInc 线程安全增量
rsAtomicMax 线程安全最大值
rsAtomicMin 线程安全最小值
rsAtomicOr 线程安全按位或
rsAtomicSub 线程安全减法
rsAtomicXor 线程安全按位独占或

时间函数和类型

以下函数可用于告知当前时钟时间和当前系统时间。建议不要在内核中调用这些函数。

类型
rs_time_t 自 1970 年 1 月 1 日以来的秒数
rs_tm 日期和时间结构
函数
rsGetDt 自上次通话以来经过的时间
rsLocaltime 转换为当地时间
rsTime 自 1970 年 1 月 1 日以来的秒数
rsUptimeMillis 系统正常运行时间(以毫秒为单位)
rsUptimeNanos 系统正常运行时间(以纳秒为单位)

分配创建函数

以下函数可用于从脚本创建 Allocation。

这些函数可以通过可调用函数直接或间接调用。如果某些控制流路径可能导致从 RenderScript 内核函数调用这些函数,则会生成编译器错误。

函数
rsCreateAllocation 创建给定类型的 rs_allocation 对象。
rsCreateElement 创建指定数据类型的 rs_element 对象
rsCreatePixelElement 创建具有指定数据类型和数据类型的 rs_element 对象
rsCreateType 使用指定的元素和形状属性创建 rs_type 对象
rsCreateVectorElement 创建具有指定数据类型和矢量宽度的 rs_element 对象

分配数据访问函数

以下函数可用于获取和设置构成分配的单元。

  • 您可以使用 rsGetElementAt* 和 rsSetElementAt 函数访问各个单元格。
  • 您可以使用 rsAllocationCopy* 和 rsAllocationV* 函数复制多个单元格。
  • 要通过采样器获取值,请使用 rsSample
rsGetElementAt 和 rsSetElement* 函数的名称有些错误。 它们不会获取或设置类似于数据类型的元素,而是会获取或设置单元格。可以将它们视为 rsGetCellAt 和 rsSetCellAt。

函数
rsAllocationCopy1DRange 在分配之间复制连续单元格
rsAllocationCopy2DRange 在分配之间复制单元格的矩形区域
rsAllocationVLoadX 从标量分配中获取矢量
rsAllocationVStoreX 将向量存储到标量分配中
rsGetElementAt 从分配返回单元格
rsGetElementAtYuv_uchar_U 获取 YUV 分配的 U 分量
rsGetElementAtYuv_uchar_V 获取 YUV 分配的 V 分量
rsGetElementAtYuv_uchar_Y 获取 YUV 分配的 Y 分量
rsSample 对纹理分配中的值进行采样
rsSetElementAt 设置分配中的单元格

对象特性函数

以下函数可用于查询 Allocation、Element 或 Sampler 对象的特性。这些对象是通过 Java 创建的。而无法通过脚本创建。

分配:

分配是用于将数据传递到 RenderScript 内核以及从 RenderScript 内核传递数据的主要方法。

它们是可用于存储位图、纹理、任意数据点等的结构化单元格集合。

该单元格集合可能具有多个维度(X、Y、Z、Array0、Array1、Array2、Array3)、面(对于立方体贴图)和细节级别(对于 mipmapping)。

如需详细了解如何创建 Allocation,请参阅 android.renderscript.Allocation

元素:

术语“元素”在 RenderScript 中有些不明确,既用作 Allocation 单元格的类型信息,又是该类型的实例化。例如:

  • rs_element 是类型规范的句柄,
  • rsGetElementAt() 等函数中,“元素”表示类型的实例化,即 Allocation 的单元格。

您可以利用以下函数查询类型规范的特性。

一个元素可以指定 C 语言中的简单数据类型,例如整数、浮点数或布尔值。还可以指定 RenderScript 对象的句柄。如需查看基本类型的列表,请参阅 rs_data_type

元素可以指定基本类型的固定大小矢量(大小为 2、3 或 4)。您可以将元素归为一组复杂的 Element,从而创建等效的 C 结构定义。

元素还可以有一个种类,这是用于解释像素数据的语义信息。请参阅 rs_data_Kind

创建公共元素的 Allocation 时,只需使用众多预定义 Element 中的一个,如 F32_2

要创建复杂元素,请使用 Element.Builder Java 类。

采样器:

采样器对象定义了如何将 Allocation 作为内核中的结构进行读取。请参阅 android.renderscript.S

函数
rsAllocationGetDimFaces 出现多个面孔
rsAllocationGetDimLOD 呈现详细程度
rsAllocationGetDimX X 维度的尺寸
rsAllocationGetDimY Y 维度的尺寸
rsAllocationGetDimZ Z 维度尺寸
rsAllocationGetElement 获取描述 Allocation 的单元的对象
rsClearObject 释放对象
rsElementGetBytesSize 元素的大小
rsElementGetDataKind 元素的种类
rsElementGetDataType 元素的数据类型
rsElementGetSubElement 复杂元素的子元素
rsElementGetSubElementArraySize 复杂元素子元素的数组大小
rsElementGetSubElementCount 子元素的数量
rsElementGetSubElementName 子元素的名称
rsElementGetSubElementNameLength 子元素的名称长度
rsElementGetSubElementOffsetBytes 实例化的子元素的偏移量
rsElementGetVectorSize 元素的矢量大小
rsIsObject 检查是否存在空句柄
rsSamplerGetAnisotropy 采样器的各向异性
rsSamplerGetMagnification 采样器放大值
rsSamplerGetMinification 采样器缩减值
rsSamplerGetWrapS 采样器封装 S 值
rsSamplerGetWrapT 采样器封装 T 值

内核调用函数和类型

rsForEach() 函数可用于调用脚本的根内核。

其他函数用于获取正在执行的内核的调用的特性,例如维度和当前索引。这些函数将 rs_kernel_context 作为参数。

类型
rs_for_each_strategy_t 建议的单元格处理顺序
rs_kernel 内核函数句柄
rs_kernel_context 内核调用上下文的句柄
rs_script_call_t 单元格迭代信息
函数
rsForEach 启动内核
rsForEachInternal (内部 API)在当前脚本中启动内核(带有槽位编号)
rsForEachWithOptions 启动带有选项的内核
rsGetArray0 指定内核上下文的 Array0 维度中的索引
rsGetArray1 指定内核上下文的 Array1 维度中的索引
rsGetArray2 指定内核上下文的 Array2 维度中的索引
rsGetArray3 指定内核上下文的 Array3 维度中的索引
rsGetDimArray0 指定内核上下文的 Array0 维度的大小
rsGetDimArray1 指定内核上下文的 Array1 维度的大小
rsGetDimArray2 指定内核上下文的 Array2 维度的大小
rsGetDimArray3 指定内核上下文的 Array3 维度的大小
rsGetDimHasFaces 指定的内核上下文出现了多个人脸
rsGetDimLod 指定内核上下文的详细级别数
rsGetDimX 指定内核上下文的 X 维度大小
rsGetDimY 指定内核上下文的 Y 维度大小
rsGetDimZ 指定内核上下文的 Z 维度大小
rsGetFace 指定内核上下文的人脸坐标
rsGetLod 指定内核上下文的“详细级别”维度中的索引

输入/输出函数

这些函数用于:

  • 将信息发送到 Java 客户端,以及
  • 发送已处理的分配或接收下一个要处理的分配。

函数
rsAllocationIoReceive 从队列中接收新内容
rsAllocationIoSend 将新内容发送到队列
rsSendToClient 向客户端发送消息,非阻塞
rsSendToClientBlocking 向客户端发送消息,阻止

调试函数

以下函数应在应用开发期间使用。不应在送货应用中使用。

函数
rsDebug 记录消息和值

图形函数和类型

在 API 级别 23 中移除了 RenderScript 的图形子系统。