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 来声明。例如，float4、int3、double2、ulong4。

如需创建矢量字面量，请使用矢量类型，后跟用大括号括起来的值，例如 (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.yz、myVar.gb、myVar.s12 和 myVar.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_Matrix2x2、rs_Matrix3x3 和 rs_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 的图形子系统。