RenderScript Runtime API Reference

Overview

RenderScript is a high-performance runtime that provides compute operations at the native level.
RenderScript code is compiled on devices at runtime to allow platform-independence as well.

This reference documentation describes the RenderScript runtime APIs, which you can utilize
to write RenderScript code in C99. The RenderScript compute header files are automatically
included for you.

To use RenderScript, you need to utilize the RenderScript runtime APIs documented here as well
as the Android framework APIs for RenderScript. For documentation on the Android framework
APIs, see the android.renderscript package reference.

Multiple entries of a vector can be accessed at once by using an identifier that is
the concatenation of multiple letters or indices. The resulting vector has a size
equal to the number of entries named.

With the example above, the middle two entries can be accessed using
myVar.yz, myVar.gb, myVar.s12, and myVar.S12.

The entries don't have to be contiguous or in increasing order. Entries can even be
repeated, as long as we're not trying to assign to it. You also can't mix the naming
styles.

The precision of the mathematical operations on 32 bit floats is affected by the pragmas
rs_fp_relaxed and rs_fp_full. Under rs_fp_relaxed, subnormal values may be flushed to zero and
rounding may be done towards zero. In comparison, rs_fp_full requires correct handling of
subnormal values, i.e. smaller than 1.17549435e-38f. rs_fp_rull also requires round to nearest
with ties to even.

Different precision/speed tradeoffs can be achieved by using variants of the common math
functions. Functions with a name starting with

native_: May have custom hardware implementations with weaker precision. Additionally,
subnormal values may be flushed to zero, rounding towards zero may be used, and NaN and
infinity input may not be handled correctly.

half_: May perform internal computations using 16 bit floats. Additionally, subnormal
values may be flushed to zero, and rounding towards zero may be used.

Different precision/speed tradeoffs can be achieved by using variants of the common math
functions. Functions with a name starting with

native_: May have custom hardware implementations with weaker precision. Additionally,
subnormal values may be flushed to zero, rounding towards zero may be used, and NaN and
infinity input may not be handled correctly.

fast_: May perform internal computations using 16 bit floats. Additionally, subnormal
values may be flushed to zero, and rounding towards zero may be used.

To create a transformation matrix that performs two transformations at once,
multiply the two source matrices, with the first transformation as the right
argument. E.g. to create a transformation matrix that applies the
transformation s1 followed by s2, call rsMatrixLoadMultiply(&combined, &s2, &s1).
This derives from s2 * (s1 * v), which is (s2 * s1) * v.

We have two style of functions to create transformation matrices:
rsMatrixLoadTransformation and rsMatrixTransformation. The former
style simply stores the transformation matrix in the first argument. The latter
modifies a pre-existing transformation matrix so that the new transformation
happens first. E.g. if you call rsMatrixTranslate() on a matrix that already
does a scaling, the resulting matrix when applied to a vector will first do the
translation then the scaling.

Atomic Update Functions

To update values shared between multiple threads, use the functions below.
They ensure that the values are atomically updated, i.e. that the memory
reads, the updates, and the memory writes are done in the right order.

These functions are slower than their non-atomic equivalents, so use
them only when synchronization is needed.

Note that in RenderScript, your code is likely to be running in separate
threads even though you did not explicitly create them. The RenderScript
runtime will very often split the execution of one kernel across multiple
threads. Updating globals should be done with atomic functions. If possible,
modify your algorithm to avoid them altogether.

Allocation Creation Functions

The functions below can be used to create Allocations from a Script.

These functions can be called directly or indirectly from an invokable
function. If some control-flow path can result in a call to these functions
from a RenderScript kernel function, a compiler error will be generated.