概览
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_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 调用提供迭代信息。 目前用于将处理范围限制为部分单元格。在未来版本中，它还可用于提供有关如何以最佳方式遍历单元格的提示。
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。 |
| 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 维度中的索引
| 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。