Developers
Overview
The rsForEach() function can be used to invoke the root kernel of a script.
Summary
| Types | |
|---|---|
| rs_for_each_strategy_t | Suggested cell processing order |
| rs_script_call_t | Cell iteration information |
| Functions | |
|---|---|
| rsForEach | Invoke the root kernel of a script |
Types
rs_for_each_strategy_t : Suggested cell processing order
An enum with the following values:
| RS_FOR_EACH_STRATEGY_SERIAL = 0 | Prefer contiguous memory regions. |
|---|---|
| RS_FOR_EACH_STRATEGY_DONT_CARE = 1 | No prefrences. |
| RS_FOR_EACH_STRATEGY_DST_LINEAR = 2 | Prefer DST. |
| RS_FOR_EACH_STRATEGY_TILE_SMALL = 3 | Prefer processing small rectangular regions. |
| RS_FOR_EACH_STRATEGY_TILE_MEDIUM = 4 | Prefer processing medium rectangular regions. |
| RS_FOR_EACH_STRATEGY_TILE_LARGE = 5 | Prefer processing large rectangular regions. |
This type is used to suggest how the invoked kernel should iterate over the cells of the allocations. This is a hint only. Implementations may not follow the suggestion.
This specification can help the caching behavior of the running kernel, e.g. the cache locality when the processing is distributed over multiple cores.
rs_script_call_t : Cell iteration information
A structure with the following fields:
| rs_for_each_strategy_t strategy | Currently ignored. In the future, will be suggested cell iteration strategy. |
|---|---|
| uint32_t xStart | Starting index in the X dimension. |
| uint32_t xEnd | Ending index (exclusive) in the X dimension. |
| uint32_t yStart | Starting index in the Y dimension. |
| uint32_t yEnd | Ending index (exclusive) in the Y dimension. |
| uint32_t zStart | Starting index in the Z dimension. |
| uint32_t zEnd | Ending index (exclusive) in the Z dimension. |
| uint32_t arrayStart | Starting index in the Array0 dimension. |
| uint32_t arrayEnd | Ending index (exclusive) in the Array0 dimension. |
| uint32_t array1Start | Starting index in the Array1 dimension. |
| uint32_t array1End | Ending index (exclusive) in the Array1 dimension. |
| uint32_t array2Start | Starting index in the Array2 dimension. |
| uint32_t array2End | Ending index (exclusive) in the Array2 dimension. |
| uint32_t array3Start | Starting index in the Array3 dimension. |
| uint32_t array3End | Ending index (exclusive) in the Array3 dimension. |
This structure is used to provide iteration information to a rsForEach call. It is currently used to restrict processing to a subset of cells. In future versions, it will also be used to provide hint on how to best iterate over the cells.
The Start fields are inclusive and the End fields are exclusive. E.g. to iterate over cells 4, 5, 6, and 7 in the X dimension, set xStart to 4 and xEnd to 8.
Functions
rsForEach : Invoke the root kernel of a script
| void rsForEach(rs_script script, rs_allocation input, rs_allocation output); | Added in API level 14 |
| void rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData); | Removed from API level 14 |
| void rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData, const rs_script_call_t* sc); | Removed from API level 14 |
| void rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData, size_t usrDataLen); | API level 14 - 20 |
| void rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData, size_t usrDataLen, const rs_script_call_t* sc); | API level 14 - 20 |
Parameters
| script | Script to call. |
|---|---|
| input | Allocation to source data from. |
| output | Allocation to write date into. |
| usrData | User defined data to pass to the script. May be NULL. |
| sc | Extra control information used to select a sub-region of the allocation to be processed or suggest a walking strategy. May be NULL. |
| usrDataLen | Size of the userData structure. This will be used to perform a shallow copy of the data if necessary. |
Invoke the kernel named "root" of the specified script. Like other kernels, this root() function will be invoked repeatedly over the cells of the specificed allocation, filling the output allocation with the results.
When rsForEach is called, the root script is launched immediately. rsForEach returns only when the script has completed and the output allocation is ready to use.
The rs_script argument is typically initialized using a global variable set from Java.
The kernel can be invoked with just an input allocation or just an output allocation.
This can be done by defining an rs_allocation variable and not initializing it. E.g.
rs_script gCustomScript;
void specializedProcessing(rs_allocation in) {
rs_allocation ignoredOut;
rsForEach(gCustomScript, in, ignoredOut);
}
If both input and output allocations are specified, they must have the same dimensions.