1864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lypage.title=Renderscript Computation 2864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lyparent.title=Computation 319aad293c0dba4ed9a47939c487fecdd5318ef08Scott Mainparent.link=index.html 4b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 5f197b639ecccc570ee235486f75ba15f87070c28Robert Ly@jd:body 6f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 7b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<div id="qv-wrapper"> 8b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <div id="qv"> 9b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <h2>In this document</h2> 10b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 11b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <ol> 12864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <li><a href="#overview">Renderscript System Overview</a></li> 13b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li> 14864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <a href="#creating-renderscript">Creating a Computation Renderscript</a> 15b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 16b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <ol> 17864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <li><a href="#creating-rs-file">Creating the Renderscript file</a></li> 18f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 19b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li><a href="#calling">Calling the Renderscript code</a></li> 20b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly </ol> 21b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly </li> 22b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly </ol> 23f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 24b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <h2>Related Samples</h2> 25b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 26b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <ol> 27b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li><a href="{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">Hello 28b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly Compute</a></li> 29b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly </ol> 30f197b639ecccc570ee235486f75ba15f87070c28Robert Ly </div> 31b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly</div> 32b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 33864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <p>Renderscript offers a high performance computation API at the native 34864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lylevel that you write in C (C99 standard). Renderscript gives your apps the ability to run 35864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lyoperations with automatic parallelization across all available processor cores. 36864090eeaa5241f9fcf17420a3d0123c95052b96Robert LyIt also supports different types of processors such as the CPU, GPU or DSP. Renderscript 37864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lyis useful for apps that do image processing, mathematical modeling, or any operations 38864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lythat require lots of mathematical computation.</p> 39864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly 40864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly<p>In addition, you have access to all of these features without having to write code to 41864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lysupport different architectures or a different amount of processing cores. You also 42864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lydo not need to recompile your application for different processor types, because Renderscript 43864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lycode is compiled on the device at runtime.</p> 44864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly 45864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly<p class="note"><strong>Deprecation Notice</strong>: Earlier versions of Renderscript included 46864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly an experimental graphics engine component. This component 47864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lyis now deprecated as of Android 4.1 (most of the APIs in <code>rs_graphics.rsh</code> 48864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lyand the corresponding APIs in {@link android.renderscript}). 49864090eeaa5241f9fcf17420a3d0123c95052b96Robert LyIf you have apps that render graphics with Renderscript, we highly 50864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lyrecommend you convert your code to another Android graphics rendering option.</p> 51864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly 52864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <h2 id="overview">Renderscript System Overview</h2> 53864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <p>The Renderscript runtime operates at the native level and still needs to communicate 54864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lywith the Android VM, so the way a Renderscript application is set up is different from a pure VM 55864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lyapplication. An application that uses Renderscript is still a traditional Android application that 56864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lyruns in the VM, but you write Renderscript code for the parts of your program that require 57864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lyit. No matter what you use it for, Renderscript remains platform 58864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lyindependent, so you do not have to target multiple architectures (for example, 59864090eeaa5241f9fcf17420a3d0123c95052b96Robert LyARM v5, ARM v7, x86).</p> 60864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly 61864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly<p>The Renderscript system adopts a control and slave architecture where the low-level Renderscript runtime 62864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lycode is controlled by the higher level Android system that runs in a virtual machine (VM). The 63864090eeaa5241f9fcf17420a3d0123c95052b96Robert LyAndroid VM still retains all control of memory management and binds memory that it allocates to 64864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lythe Renderscript runtime, so the Renderscript code can access it. The Android framework makes 65864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lyasynchronous calls to Renderscript, and the calls are placed in a message queue and processed 66864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lyas soon as possible. Figure 1 shows how the Renderscript system is structured.</p> 67864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly 68864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <img id="figure1" src="{@docRoot}images/rs_overview.png" /> 69864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <p class="img-caption"><strong>Figure 1.</strong> Renderscript system overview</p> 70864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly 71864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <p>When using Renderscript, there are three layers of APIs that enable communication between the 72864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly Renderscript runtime and Android framework code:</p> 73864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly 74864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <ul> 75864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <li>The Renderscript runtime APIs allow you to do the computation 76864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly that is required by your application.</li> 77864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly 78864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <li>The reflected layer APIs are a set of classes that are reflected from your Renderscript 79864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lyruntime code. It is basically a wrapper around the Renderscript code that allows the Android 80864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lyframework to interact with the Renderscript runtime. The Android build tools automatically generate the 81864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lyclasses for this layer during the build process. These classes eliminate the need to write JNI glue 82864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lycode, like with the NDK.</li> 83864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly 84864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <li>The Android framework layer calls the reflected layer to access the Renderscript 85864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly runtime.</li> 86864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly </ul> 87864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly 88864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly<p>Because of the way Renderscript is structured, the main advantages are:</p> 89864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <ul> 90864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <li>Portability: Renderscript is designed to run on many types of devices with different 91864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly processor (CPU, GPU, and DSP for instance) architectures. It supports all of these architectures without 92864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly having to target each device, because the code is compiled and cached on the device 93864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly at runtime.</li> 94864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly 95864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <li>Performance: Renderscript provides a high performance computation API with seamless parallelization 96864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly across the amount of cores on the device.</li> 97864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly 98864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <li>Usability: Renderscript simplifies development when possible, such as eliminating JNI glue code.</li> 99864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly </ul> 100864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly 101864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <p>The main disadvantages are:</p> 102864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly 103864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <ul> 104864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <li>Development complexity: Renderscript introduces a new set of APIs that you have to learn.</li> 105864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly 106864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <li>Debugging visibility: Renderscript can potentially execute (planned feature for later releases) 107864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly on processors other than the main CPU (such as the GPU), so if this occurs, debugging becomes more difficult. 108864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly </li> 109864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly </ul> 110864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly 111864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly<p>For a more detailed explanation of how all of these layers work together, see 112864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <a href="{@docRoot}guide/topics/renderscript/advanced.html">Advanced Renderscript</a>.<p> 113864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly 114864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly 115864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly<h2 id="creating-renderscript">Creating a Renderscript</h2> 116864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly 117864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly<p>Renderscripts scale to the amount of 118b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyprocessing cores available on the device. This is enabled through a function named 119b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<code>rsForEach()</code> (or the <code>forEach_root()</code> method at the Android framework level). 120b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lythat automatically partitions work across available processing cores on the device. 121864090eeaa5241f9fcf17420a3d0123c95052b96Robert LyFor now, Renderscript can only take advantage of CPU 122b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lycores, but in the future, they can potentially run on other types of processors such as GPUs and 123b078d942911d5e1cf9533f7fe3e156c579ba396eRobert LyDSPs.</p> 124b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 125864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly<p>Implementing a Renderscript involves creating a <code>.rs</code> file that contains 126b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyyour Renderscript code and calling it at the Android framework level with the 127b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<code>forEach_root()</code> or at the Renderscript runtime level with the 128864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly<code>rsForEach()</code> function. The following diagram describes how a typical 129b078d942911d5e1cf9533f7fe3e156c579ba396eRobert LyRenderscript is set up:</p><img src="{@docRoot}images/rs_compute.png"> 130b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 131864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly<p class="img-caption"><strong>Figure 1.</strong> Renderscript overview</p> 132b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 133864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly<p>The following sections describe how to create a simple Renderscript and use it in an 134b078d942911d5e1cf9533f7fe3e156c579ba396eRobert LyAndroid application. This example uses the <a href= 135b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly"{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">HelloCompute Renderscript 136b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lysample</a> that is provided in the SDK as a guide (some code has been modified from its original 137b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyform for simplicity).</p> 138b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 139864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly<h3 id="creating-rs-file">Creating the Renderscript file</h3> 140b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 141b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p>Your Renderscript code resides in <code>.rs</code> and <code>.rsh</code> files in the 142864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly<code><project_root>/src/</code> directory. This code contains the computation logic 143b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyand declares all necessary variables and pointers. 144864090eeaa5241f9fcf17420a3d0123c95052b96Robert LyEvery <code>.rs</code> file generally contains the following items:</p> 145b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 146b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<ul> 147b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li>A pragma declaration (<code>#pragma rs java_package_name(<em>package.name</em>)</code>) 148b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly that declares the package name of the <code>.java</code> reflection of this Renderscript.</li> 149b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 150b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li>A pragma declaration (<code>#pragma version(1)</code>) that declares the version of 151b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly Renderscript that you are using (1 is the only value for now).</li> 152b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 153864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <li><p>A <code>root()</code> function that is the main worker function. The root function is 154b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly called by the <code>rsForEach</code> function, which allows the Renderscript code to be called and 155b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly executed on multiple cores if they are available. The <code>root()</code> function must return 156864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <code>void</code> and accept the following arguments:</p> 157b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 158b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <ul> 159864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <li>Pointers to memory allocations that are used for the input and output of the 160b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly Renderscript. Both of these pointers are required for Android 3.2 (API level 13) platform 161b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly versions or older. Android 4.0 (API level 14) and later requires one or both of these 162b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly allocations.</li> 163b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly </ul> 164b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 165b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <p>The following arguments are optional, but both must be supplied if you choose to use 166b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly them:</p> 167b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 168b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <ul> 169b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li>A pointer for user-defined data that the Renderscript might need to carry out 170b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly computations in addition to the necessary allocations. This can be a pointer to a simple 171b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly primitive or a more complex struct.</li> 172b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 173b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li>The size of the user-defined data.</li> 174b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly </ul> 175b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly </li> 176b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 177b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li>An optional <code>init()</code> function. This allows you to do any initialization 178b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly before the <code>root()</code> function runs, such as initializing variables. This 179b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly function runs once and is called automatically when the Renderscript starts, before anything 180b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly else in your Renderscript.</li> 181b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 182b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li>Any variables, pointers, and structures that you wish to use in your Renderscript code (can 183b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly be declared in <code>.rsh</code> files if desired)</li> 184b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly</ul> 185b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 186b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p>The following code shows how the <a href= 187b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly"{@docRoot}resources/samples/RenderScript/HelloCompute/src/com/example/android/rs/hellocompute/mono.html"> 188b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lymono.rs</a> file is implemented:</p> 189b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<pre> 190b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly#pragma version(1) 191b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly#pragma rs java_package_name(com.example.android.rs.hellocompute) 192b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 193b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly//multipliers to convert a RGB colors to black and white 194b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyconst static float3 gMonoMult = {0.299f, 0.587f, 0.114f}; 195b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 196b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyvoid root(const uchar4 *v_in, uchar4 *v_out) { 197b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly //unpack a color to a float4 198b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly float4 f4 = rsUnpackColor8888(*v_in); 199b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly //take the dot product of the color and the multiplier 200b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly float3 mono = dot(f4.rgb, gMonoMult); 201b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly //repack the float to a color 202b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly *v_out = rsPackColorTo8888(mono); 203b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly} 204b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly</pre> 205b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 206b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<h3 id="calling">Calling the Renderscript code</h3> 207b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 208864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly<p>You can call the Renderscript from your Android framework code by 209b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lycreating a Renderscript object by instantiating the (<code>ScriptC_<em>script_name</em></code>) 210b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyclass. This class contains a method, <code>forEach_root()</code>, that lets you invoke 211b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<code>rsForEach</code>. You give it the same parameters that you would if you were invoking it 212b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyat the Renderscript runtime level. This technique allows your Android application to offload 213b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyintensive mathematical calculations to Renderscript. See the <a href= 214b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly"{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">HelloCompute</a> sample to see 215864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lyhow a simple Android application can utilize Renderscript.</p> 216b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 217864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly<p>To call Renderscript at the Android framework level:</p> 218b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 219b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<ol> 220864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <li>Allocate memory that is needed by the Renderscript in your Android framework code. 221b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly You need an input and output {@link android.renderscript.Allocation} for Android 3.2 (API level 222b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 13) platform versions and older. The Android 4.0 (API level 14) platform version requires only 223b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly one or both {@link android.renderscript.Allocation}s.</li> 224b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 225b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li>Create an instance of the <code>ScriptC_<em>script_name</em></code> class.</li> 226b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 227b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li>Call <code>forEach_root()</code>, passing in the allocations, the 228b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly Renderscript, and any optional user-defined data. The output allocation will contain the output 229864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly of the Renderscript.</li> 230b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly</ol> 231b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 232864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly<p>The following example, taken from the <a href= 233b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly"{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">HelloCompute</a> sample, processes 234b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lya bitmap and outputs a black and white version of it. The 235864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly<code>createScript()</code> method carries out the steps described previously. This method calls the 236b078d942911d5e1cf9533f7fe3e156c579ba396eRobert LyRenderscript, <code>mono.rs</code>, passing in memory allocations that store the bitmap to be processed 237b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyas well as the eventual output bitmap. It then displays the processed bitmap onto the screen:</p> 238b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<pre> 239b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lypackage com.example.android.rs.hellocompute; 240b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 241b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyimport android.app.Activity; 242b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyimport android.os.Bundle; 243b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyimport android.graphics.BitmapFactory; 244b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyimport android.graphics.Bitmap; 245b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyimport android.renderscript.RenderScript; 246b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyimport android.renderscript.Allocation; 247b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyimport android.widget.ImageView; 248b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 249b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lypublic class HelloCompute extends Activity { 250b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly private Bitmap mBitmapIn; 251b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly private Bitmap mBitmapOut; 252b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 253b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly private RenderScript mRS; 254b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly private Allocation mInAllocation; 255b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly private Allocation mOutAllocation; 256b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly private ScriptC_mono mScript; 257b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 258b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly @Override 259b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly protected void onCreate(Bundle savedInstanceState) { 260b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly super.onCreate(savedInstanceState); 261b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly setContentView(R.layout.main); 262b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 263b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly mBitmapIn = loadBitmap(R.drawable.data); 264b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly mBitmapOut = Bitmap.createBitmap(mBitmapIn.getWidth(), mBitmapIn.getHeight(), 265b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly mBitmapIn.getConfig()); 266b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 267b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly ImageView in = (ImageView) findViewById(R.id.displayin); 268b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly in.setImageBitmap(mBitmapIn); 269b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 270b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly ImageView out = (ImageView) findViewById(R.id.displayout); 271b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly out.setImageBitmap(mBitmapOut); 272b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 273b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly createScript(); 274b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly } 275b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly private void createScript() { 276b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly mRS = RenderScript.create(this); 277b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly mInAllocation = Allocation.createFromBitmap(mRS, mBitmapIn, 278b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly Allocation.MipmapControl.MIPMAP_NONE, 279b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly Allocation.USAGE_SCRIPT); 280b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly mOutAllocation = Allocation.createTyped(mRS, mInAllocation.getType()); 281b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly mScript = new ScriptC_mono(mRS, getResources(), R.raw.mono); 282b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly mScript.forEach_root(mInAllocation, mOutAllocation); 283b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly mOutAllocation.copyTo(mBitmapOut); 284b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly } 285b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 286b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly private Bitmap loadBitmap(int resource) { 287b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly final BitmapFactory.Options options = new BitmapFactory.Options(); 288b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly options.inPreferredConfig = Bitmap.Config.ARGB_8888; 289b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly return BitmapFactory.decodeResource(getResources(), resource, options); 290b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly } 291b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly} 292b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly</pre> 293b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 294864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly<p>To call Renderscript from another Renderscript file:</p> 295b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<ol> 296864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <li>Allocate memory that is needed by the Renderscript in your Android framework code. 297b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly You need an input and output {@link android.renderscript.Allocation} for Android 3.2 (API level 298b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 13) platform versions and older. The Android 4.0 (API level 14) platform version requires only 299b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly one or both {@link android.renderscript.Allocation}s.</li> 300b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 301b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li>Call <code>rsForEach()</code>, passing in the allocations and any optional user-defined data. 302864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly The output allocation will contain the output of the Renderscript.</li> 303b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly</ol> 304864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly 305b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<pre> 306b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyrs_script script; 307b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyrs_allocation in_allocation; 308b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyrs_allocation out_allocation; 309b078d942911d5e1cf9533f7fe3e156c579ba396eRobert LyUserData_t data; 310b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly... 311b078d942911d5e1cf9533f7fe3e156c579ba396eRobert LyrsForEach(script, in_allocation, out_allocation, &data, sizeof(data)); 312b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly</pre> 313864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly</p> 314b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p>In this example, assume that the script and memory allocations have already been 315b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyallocated and bound at the Android framework level and that <code>UserData_t</code> is a struct 316b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lydeclared previously. Passing a pointer to a struct and the size of the struct to <code>rsForEach</code> 317864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lyis optional, but useful if your Renderscript requires additional information other than 318b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lythe necessary memory allocations.</p> 319864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly 320864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly<h3>Setting floating point precision</h3> 321864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly<p>You can define the floating point precision required by your compute algorithms. This is useful if you 322864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly require less precision than the IEEE 754-2008 standard (used by default). You can define 323864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lythe floating-point precision level of your script with the following pragmas:</p> 324864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly 325864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly<ul> 326864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <li><code>#pragma rs_fp_full</code> (default if nothing is specified): For apps that 327864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly require floating point precision as outlined by the IEEE 754-2008 standard. 328864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly</li> 329864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <li><code>#pragma rs_fp_relaxed</code> - For apps that don’t require 330864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly strict IEEE 754-2008 compliance and can tolerate less precision. This mode enables 331864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly flush-to-zero for denorms and round-towards-zero. 332864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly</li> 333864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <li><code>#pragma rs_fp_imprecise</code> - For apps that don’t have stringent precision requirements. This mode enables 334864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly everything in <code>rs_fp_relaxed</code> along with the following: 335864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly<ul> 336864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <li>Operations resulting in -0.0 can return +0.0 instead.</li> 337864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <li>Operations on INF and NAN are undefined.</li> 338864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly</ul> 339864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly</li> 340864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly</ul>