RenderScript 内核调用函数和类型

概览

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 指定内核上下文的“详细级别”维度中的索引

类型

rs_for_each_strategy_t :建议的单元格处理顺序

具有以下值的枚举:

RS_FOR_EACH_STRATEGY_SERIAL = 0首选连续的内存区域。
RS_FOR_EACH_STRATEGY_DONT_CARE = 1没有偏好设置。
RS_FOR_EACH_STRATEGY_DST_LINEAR = 2首选 DST。
RS_FOR_EACH_STRATEGY_TILE_SMALL = 3首选处理较小的矩形区域。
RS_FOR_EACH_STRATEGY_TILE_MEDIUM = 4首选处理中等矩形区域。
RS_FOR_EACH_STRATEGY_TILE_LARGE = 5首选处理较大的矩形区域。

此类型用于建议调用的内核应如何迭代分配的单元。这只是提示。实现方式可能未遵循建议。

此规范有助于了解正在运行的内核的缓存行为,例如处理分布在多个核心上时的缓存位置。

rs_kernel :内核函数的句柄

以下类型定义符:void*     在 API 级别 24 中引入

使用内核属性定义的函数的不透明类型。此类型的值可以在 rsForEach 调用中使用以启动内核。

rs_kernel_context :内核调用上下文的句柄

类型定义符:const struct rs_kernel_context_t *     在 API 级别 23 中引入

内核上下文包含迭代分配的分配的共同特征,例如维度。它还包含当前处理的单元格的极少使用索引,例如 Array0 索引或当前详细程度。

您可以通过向内核函数添加一个名为“context”且类型为 rs_kernel_context 的特殊参数来访问内核上下文。有关示例,请参阅 rsGetDimX() 和 rsGetArray0()。

rs_script_call_t :单元格迭代信息

一个包含以下字段的结构:

rs_for_each_strategy_t 策略目前已忽略。以后, 将是建议的单元格迭代策略。
uint32_t xStartX 维度中的起始索引。
uint32_t xEndX 维度中的结束索引(不含边界值)。
uint32_t yStartY 维度中的起始索引。
uint32_t yEndY 维度中的结束索引(不含该索引)。
uint32_t zStartZ 维度中的起始索引。
uint32_t zEndZ 维度中的结束索引(不含该索引)。
uint32_t arrayStartArray0 维度中的起始索引。
uint32_t arrayEndArray0 维度中的结束索引(不含该索引)。
uint32_t array1StartArray1 维度中的起始索引。
uint32_t array1EndArray1 维度中的结束索引(不含该索引)。
uint32_t array2StartArray2 维度中的起始索引。
uint32_t array2EndArray2 维度中的结束索引(不含该索引)。
uint32_t array3StartArray3 维度中的起始索引。
uint32_t 数组 3 结束Array3 维度中的结束索引(不含边界值)。

此结构用于向 rsForEach 调用提供迭代信息。 目前用于将处理范围限制为部分单元格。在未来版本中,它还可用于提供有关如何以最佳方式遍历单元格的提示。

Start 字段和 End 字段均包含在内。例如,如需遍历 X 维度中的单元格 4、5、6 和 7,请将 xStart 设置为 4,将 xEnd 设置为 8。

函数

rsForEach :启动内核

void rsForEach(rs_kernel kernel, ... ...); API 级别 24 中引入
void rsForEach(rs_script record, rs_allocation input, rs_allocation output); API 级别 14 - 23
void rsForEach(rs_script email, rs_allocation input, rs_allocation output, const void* usrData); API 级别 14 及更高级别中移除
void rsForEach(rs_script record, rs_allocation input, rs_allocation output, const void* usrData, const rs_script_call_t* sc); API 级别 14 及更高级别中移除
void rsForEach(rs_script record, rs_allocation input, rs_allocation output, const void* usrData, size_t usrDataLen); API 级别 14 - 20
void rsForEach(rs_script record, rs_allocation input, rs_allocation output, const void* usrData, size_t usrDataLen, const rs_script_call_t* sc); API 级别 14 - 20
参数
脚本要调用的脚本。
输入来源数据的分配。
output写入日期的分配。
usrData要传递给脚本的用户指定数据。可以为 NULL。
sc用于选择要处理的分配子区域或建议步行策略的额外控制信息。可以为 NULL。
usrDataLenuserData 结构的大小。这将用于在必要时执行数据的浅层复制。
内核使用内核属性定义的函数的函数指示符。
输入和输出分配

通过零个或多个输入分配运行内核。它们在 rs_kernel 参数之后传递。如果指定的内核返回值,则必须将输出分配指定为最后一个参数。所有输入分配以及输出分配(如果存在)都必须具有相同的维度。

这是一个同步函数。只有在输入分配的所有单元的所有工作完成后,对此函数的调用才会返回。如果内核函数返回任何值,则调用会等到所有结果都已写入输出分配。

在 API 级别 23 及之前的版本中,内核会在指定脚本中隐式指定为名为“root”的内核,并且只能使用一个输入分配。 从 API 级别 24 开始,可以使用内核参数指定的任意内核函数。该脚本参数会被移除。 必须在当前脚本中定义内核。此外,可以使用多个输入源。

例如:
float __attribute__((kernel)) square(float a) {
  return a * a;
}

void compute(rs_allocation ain, rs_allocation aout) {
  rsForEach(square, ain, aout);
}

rsForEachInternal :(内部 API)在当前脚本中启动内核(包含槽号)

void rsForEachInternal(int slot, rs_script_call_t* options, int hasOutput, int numInputs, rs_allocation* allocs); API 级别 24 中引入
参数
空档
选项
hasOutput指示内核是否生成输出
输入数量输入分配数量
分配输入和输出分配

用于启动内核的内部 API。

rsForEachWithOptions :启动包含选项的内核

void rsForEachWithOptions(rs_kernel kernel, rs_script_call_t* options, ... ...); API 级别 24 中引入
参数
内核使用内核属性定义的函数的函数指示符。
选项启动选项
输入和输出分配

以类似于 rsForEach 的方式启动内核。但是,此函数不会处理输入中的所有单元,而是仅处理选项中指定的索引空间的子空间中的单元。通过选项明确指定索引空间后,使用此 API 启动内核时无需分配输入或输出。如果传入分配,它们必须与内核函数预期的参数数量和返回值相匹配。当且仅当内核具有非空返回值时,才会存在输出分配。

例如:
rs_script_call_t opts = {0};
opts.xStart = 0;
opts.xEnd = dimX;
opts.yStart = 0;
opts.yEnd = dimY / 2;
rsForEachWithOptions(foo, &opts, out, out);

rsGetArray0 :指定内核上下文的 Array0 维度中的索引

uint32_t rsGetArray0(rs_kernel_context context); API 级别 23 中引入

返回正在处理的单元的 Array0 维度中的索引(由提供的内核上下文指定)。

内核上下文包含正在迭代的分配和很少使用的索引的共同特征,例如 Array0 索引。

您可以通过向内核函数添加一个名为“context”且类型为 rs_kernel_context 的特殊参数来访问内核上下文。例如:
short RS_KERNEL myKernel(short value, uint32_t x, rs_kernel_context context) {
  // The current index in the common x, y, z dimensions are accessed by
  // adding these variables as arguments. For the more rarely used indices
  // to the other dimensions, extract them from the kernel context:
  uint32_t index_a0 = rsGetArray0(context);
  //...
}

如果 Array0 维度不存在,此函数会返回 0。

rsGetArray1 :指定内核上下文的 Array1 维度中的索引

uint32_t rsGetArray1(rs_kernel_context context); API 级别 23 中引入

返回正在处理的单元的 Array1 维度中的索引(由提供的内核上下文指定)。请参阅 rsGetArray0(),了解上下文的说明。

如果 Array1 维度不存在,则返回 0。

rsGetArray2 :指定内核上下文的 Array2 维度中的索引

uint32_t rsGetArray2(rs_kernel_context context); API 级别 23 中引入

返回正在处理的单元的 Array2 维度中的索引(由提供的内核上下文指定)。请参阅 rsGetArray0(),了解上下文的说明。

如果 Array2 维度不存在,则返回 0。

rsGetArray3 :指定内核上下文的 Array3 维度中的索引

uint32_t rsGetArray3(rs_kernel_context context); API 级别 23 中引入

返回正在处理的单元的 Array3 维度中的索引(由提供的内核上下文指定)。请参阅 rsGetArray0(),了解上下文的说明。

如果 Array3 维度不存在,则返回 0。

rsGetDimArray0 :指定内核上下文的 Array0 维度的大小

uint32_t rsGetDimArray0(rs_kernel_context context); API 级别 23 中引入

返回指定内核上下文的 Array0 维度的大小。 请参阅 rsGetDimX(),了解上下文的说明。

如果 Array0 维度不存在,则返回 0。

rsGetDimArray1 :指定内核上下文的 Array1 维度的大小

uint32_t rsGetDimArray1(rs_kernel_context context); API 级别 23 中引入

返回指定内核上下文的 Array1 维度的大小。 请参阅 rsGetDimX(),了解上下文的说明。

如果 Array1 维度不存在,则返回 0。

rsGetDimArray2 :指定内核上下文的 Array2 维度的大小

uint32_t rsGetDimArray2(rs_kernel_context context); API 级别 23 中引入

返回指定内核上下文的 Array2 维度的大小。 请参阅 rsGetDimX(),了解上下文的说明。

如果 Array2 维度不存在,则返回 0。

rsGetDimArray3 :指定内核上下文的 Array3 维度的大小

uint32_t rsGetDimArray3(rs_kernel_context context); API 级别 23 中引入

返回指定内核上下文的 Array3 维度的大小。 请参阅 rsGetDimX(),了解上下文的说明。

如果 Array3 维度不存在,则返回 0。

rsGetDimHasFaces :对于指定的内核上下文,出现了多个人脸

bool rsGetDimHasFaces(rs_kernel_context context); API 级别 23 中引入
开球回攻次数
如果存在多个人脸,则返回 true,否则返回 false。

如果内核在迭代立方体贴图,如果存在多个人脸,此函数会返回 true。在所有其他情况下,它都会返回 false。请参阅 rsGetDimX(),了解上下文的说明。

rsAllocationGetDimFaces() 与此类似,但会返回 0 或 1,而不是布尔值。

rsGetDimLod :指定内核上下文的详细程度数量

uint32_t rsGetDimLod(rs_kernel_context context); API 级别 23 中引入

返回指定内核上下文的详细级别数。这对于 mipmap 非常有用。请参阅 rsGetDimX(),了解上下文的说明。

如果未使用详细级别,则返回 0。

rsAllocationGetDimLOD() 与此类似,但返回 0 或 1,而不是实际关卡数。

rsGetDimX :指定内核上下文的 X 维度大小

uint32_t rsGetDimX(rs_kernel_context context); API 级别 23 中引入

返回指定内核上下文的 X 维度的大小。

内核上下文包含正在迭代的分配和很少使用的索引的共同特征,例如 Array0 索引。

您可以通过将名为“context”且类型为 rs_kernel_context 的特殊参数添加到内核函数中来访问它。例如:
int4 RS_KERNEL myKernel(int4 value, rs_kernel_context context) {
  uint32_t size = rsGetDimX(context); //...

要获取特定分配的维度,请使用 rsAllocationGetDimX()。

rsGetDimY :指定内核上下文的 Y 维度大小

uint32_t rsGetDimY(rs_kernel_context context); API 级别 23 中引入

返回指定内核上下文的 X 维度的大小。请参阅 rsGetDimX(),了解上下文的说明。

如果 Y 维度不存在,则返回 0。

要获取特定分配的维度,请使用 rsAllocationGetDimY()。

rsGetDimZ :指定内核上下文的 Z 维度大小

uint32_t rsGetDimZ(rs_kernel_context context); API 级别 23 中引入

返回指定内核上下文的 Z 维度大小。 请参阅 rsGetDimX(),了解上下文的说明。

如果 Z 维度不存在,则返回 0。

要获取特定分配的维度,请使用 rsAllocationGetDimZ()。

rsGetFace :指定内核上下文的人脸坐标

rs_allocation_cubemap_face rsGetFace(rs_kernel_context context); API 级别 23 中引入

返回正在处理的单元格的人脸(根据提供的内核上下文指定)。请参阅 rsGetArray0(),了解上下文的说明。

如果不存在人脸尺寸,则返回 RS_ALLOCATION_CUBEMAP_FACE_POSITIVE_X。

rsGetLod :指定内核上下文的“详细级别”维度中的索引

uint32_t rsGetLod(rs_kernel_context context); API 级别 23 中引入

返回正在处理的单元的“详细级别”维度中的索引(由提供的内核上下文指定)。有关上下文的说明,请参阅 rsGetArray0()。

如果不存在“详细级别”维度,则返回 0。