概览
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 ：内核函数句柄
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 xStart | X 维度中的起始索引。 |
| uint32_t xEnd | X 维度中的结束索引（不含边界值）。 |
| uint32_t yStart | Y 维度中的起始索引。 |
| uint32_t yEnd | Y 维度中的结束索引（不含边界值）。 |
| uint32_t zStart | Z 维度中的起始索引。 |
| uint32_t zEnd | Z 维度中的结束索引（不含边界值）。 |
| uint32_t arrayStart | Array0 维度中的起始索引。 |
| uint32_t arrayEnd | Array0 维度中的结束索引（不含边界值）。 |
| uint32_t array1Start | Array1 维度中的起始索引。 |
| uint32_t array1End | Array1 维度中的结束索引（不含边界值）。 |
| uint32_t array2Start | Array2 维度中的起始索引。 |
| uint32_t array2End | Array2 维度中的结束索引（不含边界值）。 |
| uint32_t array3Start | Array3 维度中的起始索引。 |
| uint32_t 数组 3 结束 | Array3 维度中的结束索引（不含边界值）。 |
此结构用于向 rsForEach 调用提供迭代信息。 目前用于将处理限制为部分单元格。在未来版本中，它还将用于提供有关如何以最佳方式迭代单元格的提示。
开始字段包含，而结束字段不包含。例如，如需在 X 维度中遍历单元格 4、5、6 和 7，请将 xStart 设置为 4，并将 xEnd 设置为 8。
函数
rsForEach ：启动内核
| void rsForEach(rs_kernel kernel, ... ...); | 在 API 级别 24 中引入 |
| void rsForEach(rs_script tag, rs_allocation input, rs_allocation output); | API 级别 14 - 23 |
| void rsForEach(rs_script tag, 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 tag, 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。 |
| usrDataLen | userData 结构的大小。这将用于在必要时执行数据的浅副本。 |
| 内核 | 使用内核属性定义的函数的函数指示符。 |
| … | 输入和输出分配 |
在零个或零个以上的输入分配上运行内核。它们在 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 维度中的索引
返回正在处理的单元格的 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 维度中的索引
返回正在处理的单元格的 Array1 维度中的索引（由提供的内核上下文指定）。请参阅 rsGetArray0()，了解上下文的说明。
如果 Array1 维度不存在，则返回 0。
rsGetArray2 ：指定内核上下文的 Array2 维度中的索引
返回正在处理的单元格的 Array2 维度中的索引（由提供的内核上下文指定）。请参阅 rsGetArray0()，了解上下文的说明。
如果 Array2 维度不存在，则返回 0。
rsGetArray3 ：指定内核上下文的 Array3 维度中的索引
返回正在处理的单元格的 Array3 维度中的索引（由提供的内核上下文指定）。请参阅 rsGetArray0()，了解上下文的说明。
如果 Array3 维度不存在，则返回 0。
rsGetDimArray0 ：指定内核上下文的 Array0 维度的大小
返回指定内核上下文的 Array0 维度的大小。请参阅 rsGetDimX()，了解相关上下文的说明。
如果 Array0 维度不存在，则返回 0。
rsGetDimArray1 ：指定内核上下文的 Array1 维度的大小
返回指定内核上下文的 Array1 维度的大小。请参阅 rsGetDimX()，了解相关上下文的说明。
如果 Array1 维度不存在，则返回 0。
rsGetDimArray2 ：指定内核上下文的 Array2 维度的大小
| uint32_t rsGetDimArray2(rs_kernel_context context); | 在 API 级别 23 中引入 |
返回指定内核上下文的 Array2 维度的大小。请参阅 rsGetDimX()，了解相关上下文的说明。
如果 Array2 维度不存在，则返回 0。
rsGetDimArray3 ：指定内核上下文的 Array3 维度的大小
返回指定内核上下文的 Array3 维度的大小。 请参阅 rsGetDimX()，了解相关上下文的说明。
如果 Array3 维度不存在，则返回 0。
rsGetDimHasFaces ：存在指定的内核上下文的多个人脸
| bool rsGetDimHasFaces(rs_kernel_context context); | 在 API 级别 23 中引入 |
返回
| 如果存在多个人脸，则返回 true，否则返回 false。 |
如果内核在迭代立方体贴图，如果存在多个人脸，此函数会返回 true。在所有其他情况下，返回 false。请参阅 rsGetDimX()，了解上下文的说明。
rsAllocationGetDimFaces() 与此类似，但返回 0 或 1，而不是 bool。
rsGetDimLod ：指定内核上下文的详细级别数量
返回指定内核上下文的详细级别数。这对于 mipmap 非常有用。请参阅 rsGetDimX()，了解相关上下文的说明。
如果未使用详细级别，则返回 0。
rsAllocationGetDimLOD() 与此类似，但返回的是 0 或 1，而不是实际的层数。
rsGetDimX ：指定内核上下文的 X 维度的大小
返回指定内核上下文的 X 维度的大小。
内核上下文包含迭代和极少使用的索引的共同特征，例如 Array0 索引。
您可以通过将名为“context”且类型为 rs_kernel_context 的特殊参数添加到内核函数中来访问它。例如：
int4 RS_KERNEL myKernel(int4 value, rs_kernel_context context) {
uint32_t size = rsGetDimX(context); //...
要获取特定分配的维度，请使用 rsAllocationGetDimX()。
rsGetDimY ：指定内核上下文的 Y 维度的大小
返回指定内核上下文的 X 维度的大小。 请参阅 rsGetDimX()，了解相关上下文的说明。
如果 Y 维度不存在，则返回 0。
要获取特定分配的维度，请使用 rsAllocationGetDimY()。
rsGetDimZ ：指定内核上下文的 Z 维度大小
返回指定内核上下文的 Z 维度大小。 请参阅 rsGetDimX()，了解相关上下文的说明。
如果 Z 维度不存在，则返回 0。
要获取特定分配的维度，请使用 rsAllocationGetDimZ()。
rsGetFace ：指定内核上下文的 Face 坐标
| rs_allocation_cubemap_face rsGetFace(rs_kernel_context context); | 在 API 级别 23 中引入 |
返回正在处理的单元格的人脸（根据提供的内核上下文指定）。请参阅 rsGetArray0()，了解上下文的说明。
如果人脸尺寸不存在，则返回 RS_ALLOCATION_CUBEMAP_FACE_POSITIVE_X。
rsGetLod ：指定内核上下文的“详细级别”维度中的索引
返回正在处理的单元格的“详细级别”维度中的索引（由提供的内核上下文指定）。有关上下文的说明，请参阅 rsGetArray0()。
如果不存在“详细级别”维度，则返回 0。