RenderScript Kernel Invocation Functions and Types

Runs the kernel over zero or more input allocations. They are passed after the rs_kernel argument. If the specified kernel returns a value, an output allocation must be specified as the last argument. All input allocations, and the output allocation if it exists, must have the same dimensions.

This is a synchronous function. A call to this function only returns after all the work has completed for all cells of the input allocations. If the kernel function returns any value, the call waits until all results have been written to the output allocation.

Up to API level 23, the kernel is implicitly specified as the kernel named "root" in the specified script, and only a single input allocation can be used. Starting in API level 24, an arbitrary kernel function can be used, as specified by the kernel argument. The script argument is removed. The kernel must be defined in the current script. In addition, more than one input can be used.

E.g.
float __attribute__((kernel)) square(float a) {
  return a * a;
}

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



Internal API to launch a kernel.

Launches kernel in a way similar to rsForEach. However, instead of processing all cells in the input, this function only processes cells in the subspace of the index space specified in options. With the index space explicitly specified by options, no input or output allocation is required for a kernel launch using this API. If allocations are passed in, they must match the number of arguments and return value expected by the kernel function. The output allocation is present if and only if the kernel has a non-void return value.

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


Returns the index in the Array0 dimension of the cell being processed, as specified by the supplied kernel context.

The kernel context contains common characteristics of the allocations being iterated over and rarely used indices, like the Array0 index.

You can access the kernel context by adding a special parameter named "context" of type rs_kernel_context to your kernel function. E.g.
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);
  //...
}


This function returns 0 if the Array0 dimension is not present.

Returns the index in the Array1 dimension of the cell being processed, as specified by the supplied kernel context. See rsGetArray0() for an explanation of the context.

Returns 0 if the Array1 dimension is not present.

Returns the index in the Array2 dimension of the cell being processed, as specified by the supplied kernel context. See rsGetArray0() for an explanation of the context.

Returns 0 if the Array2 dimension is not present.

Returns the index in the Array3 dimension of the cell being processed, as specified by the supplied kernel context. See rsGetArray0() for an explanation of the context.

Returns 0 if the Array3 dimension is not present.

Returns the size of the Array0 dimension for the specified kernel context. See rsGetDimX() for an explanation of the context.

Returns 0 if the Array0 dimension is not present.

Returns the size of the Array1 dimension for the specified kernel context. See rsGetDimX() for an explanation of the context.

Returns 0 if the Array1 dimension is not present.

Returns the size of the Array2 dimension for the specified kernel context. See rsGetDimX() for an explanation of the context.

Returns 0 if the Array2 dimension is not present.

Returns the size of the Array3 dimension for the specified kernel context. See rsGetDimX() for an explanation of the context.

Returns 0 if the Array3 dimension is not present.

If the kernel is iterating over a cubemap, this function returns true if there's more than one face present. In all other cases, it returns false. See rsGetDimX() for an explanation of the context.

rsAllocationGetDimFaces() is similar but returns 0 or 1 instead of a bool.

Returns the number of levels of detail for the specified kernel context. This is useful for mipmaps. See rsGetDimX() for an explanation of the context.

Returns 0 if Level of Detail is not used.

rsAllocationGetDimLOD() is similar but returns 0 or 1 instead the actual number of levels.

Returns the size of the X dimension for the specified kernel context.

The kernel context contains common characteristics of the allocations being iterated over and rarely used indices, like the Array0 index.

You can access it by adding a special parameter named "context" of type rs_kernel_context to your kernel function. E.g.
int4 RS_KERNEL myKernel(int4 value, rs_kernel_context context) {
  uint32_t size = rsGetDimX(context); //...


To get the dimension of specific allocation, use rsAllocationGetDimX().

Returns the size of the X dimension for the specified kernel context. See rsGetDimX() for an explanation of the context.

Returns 0 if the Y dimension is not present.

To get the dimension of specific allocation, use rsAllocationGetDimY().

Returns the size of the Z dimension for the specified kernel context. See rsGetDimX() for an explanation of the context.

Returns 0 if the Z dimension is not present.

To get the dimension of specific allocation, use rsAllocationGetDimZ().

Returns the face on which the cell being processed is found, as specified by the supplied kernel context. See rsGetArray0() for an explanation of the context.

Returns RS_ALLOCATION_CUBEMAP_FACE_POSITIVE_X if the face dimension is not present.

Returns the index in the Levels of Detail dimension of the cell being processed, as specified by the supplied kernel context. See rsGetArray0() for an explanation of the context.

Returns 0 if the Levels of Detail dimension is not present.