1864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lypage.title=Advanced Renderscript 2864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lyparent.title=Computation 3864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lyparent.link=index.html 4864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly 5f197b639ecccc570ee235486f75ba15f87070c28Robert Ly@jd:body 6f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 7f197b639ecccc570ee235486f75ba15f87070c28Robert Ly <div id="qv-wrapper"> 8f197b639ecccc570ee235486f75ba15f87070c28Robert Ly <div id="qv"> 9f197b639ecccc570ee235486f75ba15f87070c28Robert Ly <h2>In this document</h2> 10f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 11f197b639ecccc570ee235486f75ba15f87070c28Robert Ly <ol> 12b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li><a href="#native">Renderscript Runtime Layer</a></li> 13b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li><a href="#reflected">Reflected Layer</a> 14f197b639ecccc570ee235486f75ba15f87070c28Robert Ly <ol> 15b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li><a href="#func">Functions</a></li> 16b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li><a href="#var">Variables</a></li> 17b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li><a href="#pointer">Pointers</a></li> 18b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li><a href="#struct">Structs</a></li> 19f197b639ecccc570ee235486f75ba15f87070c28Robert Ly </ol> 20f197b639ecccc570ee235486f75ba15f87070c28Robert Ly </li> 21f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 22f197b639ecccc570ee235486f75ba15f87070c28Robert Ly <li> 23f197b639ecccc570ee235486f75ba15f87070c28Robert Ly <a href="#mem-allocation">Memory Allocation APIs</a> 24f197b639ecccc570ee235486f75ba15f87070c28Robert Ly </li> 25f197b639ecccc570ee235486f75ba15f87070c28Robert Ly <li> 26b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <a href="#memory">Working with Memory</a> 27f197b639ecccc570ee235486f75ba15f87070c28Robert Ly <ol> 28b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li><a href="#allocating-mem">Allocating and binding memory to the Renderscript</a></li> 29f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 30b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li><a href="#read-write">Reading and writing to memory</a></li> 31f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 32f197b639ecccc570ee235486f75ba15f87070c28Robert Ly </ol> 33f197b639ecccc570ee235486f75ba15f87070c28Robert Ly </li> 34f197b639ecccc570ee235486f75ba15f87070c28Robert Ly </ol> 35f197b639ecccc570ee235486f75ba15f87070c28Robert Ly </div> 36f197b639ecccc570ee235486f75ba15f87070c28Robert Ly </div> 37f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 38864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <p></p> 39f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 40864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <p>Because applications that utilize Renderscript still run inside of the Android VM, 41864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly you have access to all of the framework APIs that you are familiar with, but can 42864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly utilize Renderscript when appropriate. To facilitate this interaction between 43864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly the framework and the Renderscript runtime, an intermediate layer of code is also 44864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly present to facilitate communication and memory management between the two levels of code. 45864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly This document goes into more detail about these 46864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly different layers of code as well as how memory is shared between the Android VM and 47864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly Renderscript runtime.</p> 48f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 49b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <h2 id="native">Renderscript Runtime Layer</h2> 50f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 51b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <p>Your Renderscript code is compiled and 52b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly executed in a compact and well-defined runtime layer. The Renderscript runtime APIs offer support for 53864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lyintensive computation that is portable and automatically scalable to the 54b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyamount of cores available on a processor. 55b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly</p> 56b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p class="note"><strong>Note:</strong> The standard C functions in the NDK must be 57b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly guaranteed to run on a CPU, so Renderscript cannot access these libraries, 58b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly because Renderscript is designed to run on different types of processors.</p> 59f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 60b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p>You define your Renderscript code in <code>.rs</code> 61b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly and <code>.rsh</code> files in the <code>src/</code> directory of your Android project. The code 62b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly is compiled to intermediate bytecode by the 63b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <code>llvm</code> compiler that runs as part of an Android build. When your application 64b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly runs on a device, the bytecode is then compiled (just-in-time) to machine code by another 65b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <code>llvm</code> compiler that resides on the device. The machine code is optimized for the 66b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly device and also cached, so subsequent uses of the Renderscript enabled application does not 67b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly recompile the bytecode.</p> 68f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 69b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <p>Some key features of the Renderscript runtime libraries include:</p> 70f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 71b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <ul> 72f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 73f197b639ecccc570ee235486f75ba15f87070c28Robert Ly <li>Memory allocation request features</li> 74f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 75b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li>A large collection of math functions with both scalar and vector typed overloaded versions 76b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly of many common routines. Operations such as adding, multiplying, dot product, and cross product 77b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly are available as well as atomic arithmetic and comparison functions.</li> 78b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 79864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <li>Conversion routines for primitive data types and vectors, matrix routines, and date and time 80864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly routines</li> 81b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 82b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li>Data types and structures to support the Renderscript system such as Vector types for 83f197b639ecccc570ee235486f75ba15f87070c28Robert Ly defining two-, three-, or four-vectors.</li> 84b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 85b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li>Logging functions</li> 86f197b639ecccc570ee235486f75ba15f87070c28Robert Ly </ul> 87f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 88864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly <p>See the Renderscript runtime API reference for more information on the available functions. 89b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 90b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <h2 id="reflected">Reflected Layer</h2> 91f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 92f197b639ecccc570ee235486f75ba15f87070c28Robert Ly <p>The reflected layer is a set of classes that the Android build tools generate to allow access 93b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly to the Renderscript runtime from the Android framework. This layer also provides methods 94b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyand constructors that allow you to allocate and work with memory for pointers that are defined in 95b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyyour Renderscript code. The following list describes the major 96f197b639ecccc570ee235486f75ba15f87070c28Robert Ly components that are reflected:</p> 97f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 98f197b639ecccc570ee235486f75ba15f87070c28Robert Ly <ul> 99f197b639ecccc570ee235486f75ba15f87070c28Robert Ly <li>Every <code>.rs</code> file that you create is generated into a class named 100b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <code>project_root/gen/package/name/ScriptC_<em>renderscript_filename</em></code> of 101b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lytype {@link android.renderscript.ScriptC}. This file is the <code>.java</code> version of your 102b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<code>.rs</code> file, which you can call from the Android framework. This class contains the 103b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyfollowing items reflected from the <code>.rs</code> file: 104f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 105f197b639ecccc570ee235486f75ba15f87070c28Robert Ly <ul> 106b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li>Non-static functions</li> 107b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 108b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li>Non-static, global Renderscript variables. Accessor methods are generated for each 109b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly variable, so you can read and write the Renderscript variables from the Android 110b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly framework. If a global variable is initialized at the Renderscript runtime layer, those 111b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyvalues are used to initialize the corresponding values in the Android framework layer. If global 112b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyvariables are marked as <code>const</code>, then a <code>set</code> method is not 113b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lygenerated.</p></li> 114b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 115b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li>Global pointers</li> 116f197b639ecccc570ee235486f75ba15f87070c28Robert Ly </ul> 117f197b639ecccc570ee235486f75ba15f87070c28Robert Ly </li> 118f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 119f197b639ecccc570ee235486f75ba15f87070c28Robert Ly <li>A <code>struct</code> is reflected into its own class named 120b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 121b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <code>project_root/gen/package/name/ScriptField_struct_name</em></code>, which extends {@link 122f197b639ecccc570ee235486f75ba15f87070c28Robert Ly android.renderscript.Script.FieldBase}. This class represents an array of the 123f197b639ecccc570ee235486f75ba15f87070c28Robert Ly <code>struct</code>, which allows you to allocate memory for one or more instances of this 124f197b639ecccc570ee235486f75ba15f87070c28Robert Ly <code>struct</code>.</li> 125f197b639ecccc570ee235486f75ba15f87070c28Robert Ly </ul> 126f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 127f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 128b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<h3 id="func">Functions</h3> 129b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p>Functions are reflected into the script class itself, located in 130b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<code>project_root/gen/package/name/ScriptC_renderscript_filename</code>. For 131b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyexample, if you declare the following function in your Renderscript code:</p> 132f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 133b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<pre> 134b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyvoid touch(float x, float y, float pressure, int id) { 135b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly if (id >= 10) { 136b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly return; 137b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly } 138f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 139b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly touchPos[id].x = x; 140b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly touchPos[id].y = y; 141b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly touchPressure[id] = pressure; 142b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly} 143b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly</pre> 144f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 145b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p>then the following code is generated:</p> 146f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 147b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<pre> 148b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lypublic void invoke_touch(float x, float y, float pressure, int id) { 149b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly FieldPacker touch_fp = new FieldPacker(16); 150b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly touch_fp.addF32(x); 151b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly touch_fp.addF32(y); 152b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly touch_fp.addF32(pressure); 153b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly touch_fp.addI32(id); 154b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly invoke(mExportFuncIdx_touch, touch_fp); 155b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly} 156b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly</pre> 157b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p> 158b078d942911d5e1cf9533f7fe3e156c579ba396eRobert LyFunctions cannot have a return value, because the Renderscript system is designed to be 159b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyasynchronous. When your Android framework code calls into Renderscript, the call is queued and is 160b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyexecuted when possible. This restriction allows the Renderscript system to function without constant 161b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyinterruption and increases efficiency. If functions were allowed to have return values, the call 162b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lywould block until the value was returned.</p> 163f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 164b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p> 165b078d942911d5e1cf9533f7fe3e156c579ba396eRobert LyIf you want the Renderscript code to send a value back to the Android framework, use the 166f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly<a href="{@docRoot}reference/renderscript/rs__core_8rsh.html"><code>rsSendToClient()</code></a> 167f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Lyfunction. 168b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly</p> 169f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 170b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<h3 id="var">Variables</h3> 171f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 172b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <p>Variables of supported types are reflected into the script class itself, located in 173b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<code>project_root/gen/package/name/ScriptC_renderscript_filename</code>. A set of accessor 174b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lymethods are generated for each variable. For example, if you declare the following variable in 175b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyyour Renderscript code:</p> 176b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <pre>uint32_t unsignedInteger = 1;</pre> 177f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 178b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <p>then the following code is generated:</p> 179f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 180b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<pre> 181b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyprivate long mExportVar_unsignedInteger; 182b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lypublic void set_unsignedInteger(long v){ 183b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly mExportVar_unsignedInteger = v; 184b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly setVar(mExportVarIdx_unsignedInteger, v); 185b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly} 186f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 187b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lypublic long get_unsignedInteger(){ 188b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly return mExportVar_unsignedInteger; 189b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly} 190b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly </pre> 191f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 192b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 193b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <h3 id="struct">Structs</h3> 194b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <p>Structs are reflected into their own classes, located in 195b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <code><project_root>/gen/com/example/renderscript/ScriptField_struct_name</code>. This 196b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly class represents an array of the <code>struct</code> and allows you to allocate memory for a 197b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly specified number of <code>struct</code>s. For example, if you declare the following struct:</p> 198f197b639ecccc570ee235486f75ba15f87070c28Robert Ly<pre> 199b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lytypedef struct Point { 200f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly float2 position; 201f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly float size; 202b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly} Point_t; 203f197b639ecccc570ee235486f75ba15f87070c28Robert Ly</pre> 204f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 205b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p>then the following code is generated in <code>ScriptField_Point.java</code>: 206b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<pre> 207b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lypackage com.example.android.rs.hellocompute; 208f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 209f197b639ecccc570ee235486f75ba15f87070c28Robert Lyimport android.renderscript.*; 210f197b639ecccc570ee235486f75ba15f87070c28Robert Lyimport android.content.res.Resources; 211f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 212b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly /** 213b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly * @hide 214b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly */ 215f197b639ecccc570ee235486f75ba15f87070c28Robert Lypublic class ScriptField_Point extends android.renderscript.Script.FieldBase { 216b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 217f197b639ecccc570ee235486f75ba15f87070c28Robert Ly static public class Item { 218b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly public static final int sizeof = 12; 219f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 220b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly Float2 position; 221b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly float size; 222f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 223f197b639ecccc570ee235486f75ba15f87070c28Robert Ly Item() { 224b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly position = new Float2(); 225f197b639ecccc570ee235486f75ba15f87070c28Robert Ly } 226f197b639ecccc570ee235486f75ba15f87070c28Robert Ly } 227f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 228f197b639ecccc570ee235486f75ba15f87070c28Robert Ly private Item mItemArray[]; 229f197b639ecccc570ee235486f75ba15f87070c28Robert Ly private FieldPacker mIOBuffer; 230f197b639ecccc570ee235486f75ba15f87070c28Robert Ly public static Element createElement(RenderScript rs) { 231f197b639ecccc570ee235486f75ba15f87070c28Robert Ly Element.Builder eb = new Element.Builder(rs); 232b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly eb.add(Element.F32_2(rs), "position"); 233b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly eb.add(Element.F32(rs), "size"); 234f197b639ecccc570ee235486f75ba15f87070c28Robert Ly return eb.create(); 235f197b639ecccc570ee235486f75ba15f87070c28Robert Ly } 236f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 237f197b639ecccc570ee235486f75ba15f87070c28Robert Ly public ScriptField_Point(RenderScript rs, int count) { 238f197b639ecccc570ee235486f75ba15f87070c28Robert Ly mItemArray = null; 239f197b639ecccc570ee235486f75ba15f87070c28Robert Ly mIOBuffer = null; 240f197b639ecccc570ee235486f75ba15f87070c28Robert Ly mElement = createElement(rs); 241f197b639ecccc570ee235486f75ba15f87070c28Robert Ly init(rs, count); 242f197b639ecccc570ee235486f75ba15f87070c28Robert Ly } 243f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 244f197b639ecccc570ee235486f75ba15f87070c28Robert Ly public ScriptField_Point(RenderScript rs, int count, int usages) { 245f197b639ecccc570ee235486f75ba15f87070c28Robert Ly mItemArray = null; 246f197b639ecccc570ee235486f75ba15f87070c28Robert Ly mIOBuffer = null; 247f197b639ecccc570ee235486f75ba15f87070c28Robert Ly mElement = createElement(rs); 248f197b639ecccc570ee235486f75ba15f87070c28Robert Ly init(rs, count, usages); 249f197b639ecccc570ee235486f75ba15f87070c28Robert Ly } 250f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 251f197b639ecccc570ee235486f75ba15f87070c28Robert Ly private void copyToArray(Item i, int index) { 252b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly if (mIOBuffer == null) mIOBuffer = new FieldPacker(Item.sizeof * getType().getX()/* count 253b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly */); 254f197b639ecccc570ee235486f75ba15f87070c28Robert Ly mIOBuffer.reset(index * Item.sizeof); 255b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly mIOBuffer.addF32(i.position); 256b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly mIOBuffer.addF32(i.size); 257f197b639ecccc570ee235486f75ba15f87070c28Robert Ly } 258f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 259f197b639ecccc570ee235486f75ba15f87070c28Robert Ly public void set(Item i, int index, boolean copyNow) { 260f197b639ecccc570ee235486f75ba15f87070c28Robert Ly if (mItemArray == null) mItemArray = new Item[getType().getX() /* count */]; 261f197b639ecccc570ee235486f75ba15f87070c28Robert Ly mItemArray[index] = i; 262f197b639ecccc570ee235486f75ba15f87070c28Robert Ly if (copyNow) { 263f197b639ecccc570ee235486f75ba15f87070c28Robert Ly copyToArray(i, index); 264f197b639ecccc570ee235486f75ba15f87070c28Robert Ly mAllocation.setFromFieldPacker(index, mIOBuffer); 265f197b639ecccc570ee235486f75ba15f87070c28Robert Ly } 266f197b639ecccc570ee235486f75ba15f87070c28Robert Ly } 267f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 268f197b639ecccc570ee235486f75ba15f87070c28Robert Ly public Item get(int index) { 269f197b639ecccc570ee235486f75ba15f87070c28Robert Ly if (mItemArray == null) return null; 270f197b639ecccc570ee235486f75ba15f87070c28Robert Ly return mItemArray[index]; 271f197b639ecccc570ee235486f75ba15f87070c28Robert Ly } 272f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 273b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly public void set_position(int index, Float2 v, boolean copyNow) { 274b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly if (mIOBuffer == null) mIOBuffer = new FieldPacker(Item.sizeof * getType().getX()/* count */); 275f197b639ecccc570ee235486f75ba15f87070c28Robert Ly if (mItemArray == null) mItemArray = new Item[getType().getX() /* count */]; 276f197b639ecccc570ee235486f75ba15f87070c28Robert Ly if (mItemArray[index] == null) mItemArray[index] = new Item(); 277b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly mItemArray[index].position = v; 278b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly if (copyNow) { 279f197b639ecccc570ee235486f75ba15f87070c28Robert Ly mIOBuffer.reset(index * Item.sizeof); 280f197b639ecccc570ee235486f75ba15f87070c28Robert Ly mIOBuffer.addF32(v); 281f197b639ecccc570ee235486f75ba15f87070c28Robert Ly FieldPacker fp = new FieldPacker(8); 282f197b639ecccc570ee235486f75ba15f87070c28Robert Ly fp.addF32(v); 283f197b639ecccc570ee235486f75ba15f87070c28Robert Ly mAllocation.setFromFieldPacker(index, 0, fp); 284f197b639ecccc570ee235486f75ba15f87070c28Robert Ly } 285b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly } 286f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 287b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly public void set_size(int index, float v, boolean copyNow) { 288b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly if (mIOBuffer == null) mIOBuffer = new FieldPacker(Item.sizeof * getType().getX()/* count */); 289b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly if (mItemArray == null) mItemArray = new Item[getType().getX() /* count */]; 290b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly if (mItemArray[index] == null) mItemArray[index] = new Item(); 291b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly mItemArray[index].size = v; 292b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly if (copyNow) { 293b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly mIOBuffer.reset(index * Item.sizeof + 8); 294b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly mIOBuffer.addF32(v); 295b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly FieldPacker fp = new FieldPacker(4); 296b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly fp.addF32(v); 297b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly mAllocation.setFromFieldPacker(index, 1, fp); 298b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly } 299f197b639ecccc570ee235486f75ba15f87070c28Robert Ly } 300f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 301b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly public Float2 get_position(int index) { 302f197b639ecccc570ee235486f75ba15f87070c28Robert Ly if (mItemArray == null) return null; 303b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly return mItemArray[index].position; 304b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly } 305b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 306b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly public float get_size(int index) { 307b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly if (mItemArray == null) return 0; 308b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly return mItemArray[index].size; 309f197b639ecccc570ee235486f75ba15f87070c28Robert Ly } 310f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 311f197b639ecccc570ee235486f75ba15f87070c28Robert Ly public void copyAll() { 312f197b639ecccc570ee235486f75ba15f87070c28Robert Ly for (int ct = 0; ct < mItemArray.length; ct++) copyToArray(mItemArray[ct], ct); 313f197b639ecccc570ee235486f75ba15f87070c28Robert Ly mAllocation.setFromFieldPacker(0, mIOBuffer); 314f197b639ecccc570ee235486f75ba15f87070c28Robert Ly } 315f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 316f197b639ecccc570ee235486f75ba15f87070c28Robert Ly public void resize(int newSize) { 317f197b639ecccc570ee235486f75ba15f87070c28Robert Ly if (mItemArray != null) { 318f197b639ecccc570ee235486f75ba15f87070c28Robert Ly int oldSize = mItemArray.length; 319f197b639ecccc570ee235486f75ba15f87070c28Robert Ly int copySize = Math.min(oldSize, newSize); 320f197b639ecccc570ee235486f75ba15f87070c28Robert Ly if (newSize == oldSize) return; 321f197b639ecccc570ee235486f75ba15f87070c28Robert Ly Item ni[] = new Item[newSize]; 322f197b639ecccc570ee235486f75ba15f87070c28Robert Ly System.arraycopy(mItemArray, 0, ni, 0, copySize); 323f197b639ecccc570ee235486f75ba15f87070c28Robert Ly mItemArray = ni; 324f197b639ecccc570ee235486f75ba15f87070c28Robert Ly } 325f197b639ecccc570ee235486f75ba15f87070c28Robert Ly mAllocation.resize(newSize); 326f197b639ecccc570ee235486f75ba15f87070c28Robert Ly if (mIOBuffer != null) mIOBuffer = new FieldPacker(Item.sizeof * getType().getX()/* count */); 327f197b639ecccc570ee235486f75ba15f87070c28Robert Ly } 328b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly} 329b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly</pre> 330b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 331b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p>The generated code is provided to you as a convenience to allocate memory for structs requested 332b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyby the Renderscript runtime and to interact with <code>struct</code>s 333b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyin memory. Each <code>struct</code>'s class defines the following methods and constructors:</p> 334b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 335b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <ul> 336b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li>Overloaded constructors that allow you to allocate memory. The 337b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <code>ScriptField_<em>struct_name</em>(RenderScript rs, int count)</code> constructor allows 338b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly you to define the number of structures that you want to allocate memory for with the 339b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <code>count</code> parameter. The <code>ScriptField_<em>struct_name</em>(RenderScript rs, int 340b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly count, int usages)</code> constructor defines an extra parameter, <code>usages</code>, that 341b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly lets you specify the memory space of this memory allocation. There are four memory space 342b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly possibilities: 343b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 344b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <ul> 345b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li>{@link android.renderscript.Allocation#USAGE_SCRIPT}: Allocates in the script memory 346b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly space. This is the default memory space if you do not specify a memory space.</li> 347b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 348b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li>{@link android.renderscript.Allocation#USAGE_GRAPHICS_TEXTURE}: Allocates in the 349b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly texture memory space of the GPU.</li> 350b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 351b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li>{@link android.renderscript.Allocation#USAGE_GRAPHICS_VERTEX}: Allocates in the vertex 352b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly memory space of the GPU.</li> 353b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 354b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li>{@link android.renderscript.Allocation#USAGE_GRAPHICS_CONSTANTS}: Allocates in the 355b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly constants memory space of the GPU that is used by the various program objects.</li> 356b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly </ul> 357f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 358b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <p>You can specify multiple memory spaces by using the bitwise <code>OR</code> operator. Doing so 359b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly notifies the Renderscript runtime that you intend on accessing the data in the 360b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly specified memory spaces. The following example allocates memory for a custom data type 361b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly in both the script and vertex memory spaces:</p> 362b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <pre> 363864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly ScriptField_Point touchPoints = new ScriptField_Point(myRenderscript, 2, 364b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly Allocation.USAGE_SCRIPT | Allocation.USAGE_GRAPHICS_VERTEX); 365b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly </pre> 366b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly </li> 367b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 368b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li>A static nested class, <code>Item</code>, allows you to create an instance of the 369b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <code>struct</code>, in the form of an object. This nested class is useful if it makes more sense to work 370b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly with the <code>struct</code> in your Android code. When you are done manipulating the object, 371b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly you can push the object to the allocated memory by calling <code>set(Item i, int index, 372b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly boolean copyNow)</code> and setting the <code>Item</code> to the desired position in 373b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lythe array. The Renderscript runtime automatically has access to the newly written memory. 374b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 375b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li>Accessor methods to get and set the values of each field in a struct. Each of these 376b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly accessor methods have an <code>index</code> parameter to specify the <code>struct</code> in 377b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly the array that you want to read or write to. Each setter method also has a 378b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<code>copyNow</code> parameter that specifies whether or not to immediately sync this memory 379b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyto the Renderscript runtime. To sync any memory that has not been synced, call 380b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <code>copyAll()</code>.</li> 381b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 382b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li>The <code>createElement()</code> method creates a description of the struct in memory. This 383b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly description is used to allocate memory consisting of one or many elements.</li> 384b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 385b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li><code>resize()</code> works much like a <code>realloc()</code> in C, allowing you to 386b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyexpand previously allocated memory, maintaining the current values that were previously 387b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lycreated.</li> 388b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 389b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <li><code>copyAll()</code> synchronizes memory that was set on the framework level to the 390b078d942911d5e1cf9533f7fe3e156c579ba396eRobert LyRenderscript runtime. When you call a set accessor method on a member, there is an optional 391b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<code>copyNow</code> boolean parameter that you can specify. Specifying 392b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <code>true</code> synchronizes the memory when you call the method. If you specify false, 393b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly you can call <code>copyAll()</code> once, and it synchronizes memory for all the 394b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyproperties that are not yet synchronized.</li> 395b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly </ul> 396b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 397f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly <h3 id="pointer">Pointers</h3> 398f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly <p>Pointers are reflected into the script class itself, located in 399f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly<code>project_root/gen/package/name/ScriptC_renderscript_filename</code>. You 400f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Lycan declare pointers to a <code>struct</code> or any of the supported Renderscript types, but a 401f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly<code>struct</code> cannot contain pointers or nested arrays. For example, if you declare the 402f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Lyfollowing pointers to a <code>struct</code> and <code>int32_t</code></p> 403f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly 404f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly<pre> 405f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Lytypedef struct Point { 406f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly float2 position; 407f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly float size; 408f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly} Point_t; 409f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly 410f11ffc1178645762b74f945b6c5ee068dc6000d3Robert LyPoint_t *touchPoints; 411f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Lyint32_t *intPointer; 412f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly</pre> 413f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly <p>then the following code is generated in:</p> 414f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly 415f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly<pre> 416f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Lyprivate ScriptField_Point mExportVar_touchPoints; 417f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Lypublic void bind_touchPoints(ScriptField_Point v) { 418f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly mExportVar_touchPoints = v; 419f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly if (v == null) bindAllocation(null, mExportVarIdx_touchPoints); 420f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly else bindAllocation(v.getAllocation(), mExportVarIdx_touchPoints); 421f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly} 422f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly 423f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Lypublic ScriptField_Point get_touchPoints() { 424f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly return mExportVar_touchPoints; 425f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly} 426f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly 427f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Lyprivate Allocation mExportVar_intPointer; 428f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Lypublic void bind_intPointer(Allocation v) { 429f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly mExportVar_intPointer = v; 430f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly if (v == null) bindAllocation(null, mExportVarIdx_intPointer); 431f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly else bindAllocation(v, mExportVarIdx_intPointer); 432f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly} 433f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly 434f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Lypublic Allocation get_intPointer() { 435f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly return mExportVar_intPointer; 436f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly} 437f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly </pre> 438f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly 439f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly<p>A <code>get</code> method and a special method named <code>bind_<em>pointer_name</em></code> 440f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly(instead of a <code>set()</code> method) is generated. This method allows you to bind the memory 441f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Lythat is allocated in the Android VM to the Renderscript runtime (you cannot allocate 442f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Lymemory in your <code>.rs</code> file). For more information, see <a href="#memory">Working 443f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Lywith Allocated Memory</a>. 444f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly</p> 445f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly 446f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly 447b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <h2 id="mem-allocation">Memory Allocation APIs</h2> 448b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 449b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <p>Applications that use Renderscript still run in the Android VM. The actual Renderscript code, however, runs natively and 450b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly needs access to the memory allocated in the Android VM. To accomplish this, you must 451b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly attach the memory that is allocated in the VM to the Renderscript runtime. This 452b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyprocess, called binding, allows the Renderscript runtime to seamlessly work with memory that it 453b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyrequests but cannot explicitly allocate. The end result is essentially the same as if you had 454b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lycalled <code>malloc</code> in C. The added benefit is that the Android VM can carry out garbage collection as well as 455b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyshare memory with the Renderscript runtime layer. Binding is only necessary for dynamically allocated memory. Statically 456b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyallocated memory is automatically created for your Renderscript code at compile time. See <a href="#figure1">Figure 1</a> 457b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyfor more information on how memory allocation occurs. 458b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly</p> 459b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 460b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <p>To support this memory allocation system, there are a set of APIs that allow the Android VM to 461b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyallocate memory and offer similar functionality to a <code>malloc</code> call. These classes 462b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyessentially describe how memory should be allocated and also carry out the allocation. To better 463b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyunderstand how these classes work, it is useful to think of them in relation to a simple 464b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<code>malloc</code> call that can look like this: </p> 465b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 466b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <pre>array = (int *)malloc(sizeof(int)*10);</pre> 467b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 468b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <p>The <code>malloc</code> call can be broken up into two parts: the size of the memory being allocated (<code>sizeof(int)</code>), 469b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly along with how many units of that memory should be allocated (10). The Android framework provides classes for these two parts as 470b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly well as a class to represent <code>malloc</code> itself.</p> 471b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 472b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <p>The {@link android.renderscript.Element} class represents the (<code>sizeof(int)</code>) portion 473b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly of the <code>malloc</code> call and encapsulates one cell of a memory allocation, such as a single 474b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly float value or a struct. The {@link android.renderscript.Type} class encapsulates the {@link android.renderscript.Element} 475b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly and the amount of elements to allocate (10 in our example). You can think of a {@link android.renderscript.Type} as 476b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly an array of {@link android.renderscript.Element}s. The {@link android.renderscript.Allocation} class does the actual 477b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly memory allocation based on a given {@link android.renderscript.Type} and represents the actual allocated memory.</p> 478b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 479b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <p>In most situations, you do not need to call these memory allocation APIs directly. The reflected layer 480b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly classes generate code to use these APIs automatically and all you need to do to allocate memory is call a 481b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly constructor that is declared in one of the reflected layer classes and then bind 482b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly the resulting memory {@link android.renderscript.Allocation} to the Renderscript. 483b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly There are some situations where you would want to use these classes directly to allocate memory on your 484b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly own, such as loading a bitmap from a resource or when you want to allocate memory for pointers to 485b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly primitive types. You can see how to do this in the 486b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <a href="#allocating-mem">Allocating and binding memory to the Renderscript</a> section. 487b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly The following table describes the three memory management classes in more detail:</p> 488b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 489b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <table id="mem-mgmt-table"> 490b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <tr> 491b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <th>Android Object Type</th> 492b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 493b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <th>Description</th> 494b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly </tr> 495b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 496b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <tr> 497b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <td>{@link android.renderscript.Element}</td> 498b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 499b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <td> 500b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <p>An element describes one cell of a memory allocation and can have two forms: basic or 501b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly complex.</p> 502b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 503b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <p>A basic element contains a single component of data of any valid Renderscript data type. 504b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly Examples of basic element data types include a single <code>float</code> value, a <code>float4</code> vector, or a 505b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly single RGB-565 color.</p> 506b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 507b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <p>Complex elements contain a list of basic elements and are created from 508b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <code>struct</code>s that you declare in your Renderscript code. For instance an allocation 509b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly can contain multiple <code>struct</code>s arranged in order in memory. Each struct is considered as its 510b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly own element, rather than each data type within that struct.</p> 511b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly </td> 512b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly </tr> 513b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 514b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <tr> 515b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <td>{@link android.renderscript.Type}</td> 516b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 517b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <td> 518b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <p>A type is a memory allocation template and consists of an element and one or more 519b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly dimensions. It describes the layout of the memory (basically an array of {@link 520b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly android.renderscript.Element}s) but does not allocate the memory for the data that it 521b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly describes.</p> 522b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 523b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <p>A type consists of five dimensions: X, Y, Z, LOD (level of detail), and Faces (of a cube 524b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly map). You can assign the X,Y,Z dimensions to any positive integer value within the 525b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly constraints of available memory. A single dimension allocation has an X dimension of 526b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly greater than zero while the Y and Z dimensions are zero to indicate not present. For 527b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly example, an allocation of x=10, y=1 is considered two dimensional and x=10, y=0 is 528b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly considered one dimensional. The LOD and Faces dimensions are booleans to indicate present 529b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly or not present.</p> 530b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly </td> 531b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly </tr> 532b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 533b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <tr> 534b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <td>{@link android.renderscript.Allocation}</td> 535b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 536b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <td> 537b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <p>An allocation provides the memory for applications based on a description of the memory 538b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly that is represented by a {@link android.renderscript.Type}. Allocated memory can exist in 539b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly many memory spaces concurrently. If memory is modified in one space, you must explicitly 540b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly synchronize the memory, so that it is updated in all the other spaces in which it exists. 541b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly </p> 542b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 543b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <p>Allocation data is uploaded in one of two primary ways: type checked and type unchecked. 544b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly For simple arrays there are <code>copyFrom()</code> functions that take an array from the 545b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly Android system and copy it to the native layer memory store. The unchecked variants allow 546b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly the Android system to copy over arrays of structures because it does not support 547b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly structures. For example, if there is an allocation that is an array of n floats, the data 548b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly contained in a float[n] array or a <code>byte[n*4]</code> array can be copied.</p> 549b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly </td> 550b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly </tr> 551b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly </table> 552b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 553b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <h2 id="memory">Working with Memory</h2> 554b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 555b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p>Non-static, global variables that you declare in your Renderscript are allocated memory at compile time. 556b078d942911d5e1cf9533f7fe3e156c579ba396eRobert LyYou can work with these variables directly in your Renderscript code without having to allocate 557b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lymemory for them at the Android framework level. The Android framework layer also has access to these variables 558b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lywith the provided accessor methods that are generated in the reflected layer classes. If these variables are 559b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyinitialized at the Renderscript runtime layer, those values are used to initialize the corresponding 560b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyvalues in the Android framework layer. If global variables are marked as const, then a <code>set</code> method is 561b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lynot generated.</p> 562b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 563b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 564b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p class="note"><strong>Note:</strong> If you are using certain Renderscript structures that contain pointers, such as 565b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<code>rs_program_fragment</code> and <code>rs_allocation</code>, you have to obtain an object of the 566b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lycorresponding Android framework class first and then call the <code>set</code> method for that 567b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lystructure to bind the memory to the Renderscript runtime. You cannot directly manipulate these structures 568af1667509775dc3f3d811ff15b2a28446ab3038fRobert Lyat the Renderscript runtime layer. This restriction is not applicable to user-defined structures 569af1667509775dc3f3d811ff15b2a28446ab3038fRobert Lythat contain pointers, because they cannot be exported to a reflected layer class 570af1667509775dc3f3d811ff15b2a28446ab3038fRobert Lyin the first place. A compiler error is generated if you try to declare a non-static, global 571af1667509775dc3f3d811ff15b2a28446ab3038fRobert Lystruct that contains a pointer. 572b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly</p> 573b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 574b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p>Renderscript also has support for pointers, but you must explicitly allocate the memory in your 575b078d942911d5e1cf9533f7fe3e156c579ba396eRobert LyAndroid framework code. When you declare a global pointer in your <code>.rs</code> file, you 576b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyallocate memory through the appropriate reflected layer class and bind that memory to the native 577b078d942911d5e1cf9533f7fe3e156c579ba396eRobert LyRenderscript layer. You can interact with this memory from the Android framework layer as well as 578b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lythe Renderscript layer, which offers you the flexibility to modify variables in the most 579b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyappropriate layer.</p> 580b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 581b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 582b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 583b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <h3 id="allocating-mem">Allocating and binding dynamic memory to the Renderscript</h3> 584b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 585b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <p>To allocate dynamic memory, you need to call the constructor of a 586b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly {@link android.renderscript.Script.FieldBase} class, which is the most common way. An alternative is to create an 587b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly {@link android.renderscript.Allocation} manually, which is required for things such as primitive type pointers. You should 588b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly use a {@link android.renderscript.Script.FieldBase} class constructor whenever available for simplicity. 589b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly After obtaining a memory allocation, call the reflected <code>bind</code> method of the pointer to bind the allocated memory to the 590b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly Renderscript runtime.</p> 591b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <p>The example below allocates memory for both a primitive type pointer, 592b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <code>intPointer</code>, and a pointer to a struct, <code>touchPoints</code>. It also binds the memory to the 593b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly Renderscript:</p> 594b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <pre> 595864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lyprivate RenderScript myRenderscript; 596b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyprivate ScriptC_example script; 597b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyprivate Resources resources; 598b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 599864090eeaa5241f9fcf17420a3d0123c95052b96Robert Lypublic void init(RenderScript rs, Resources res) { 600864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly myRenderscript = rs; 601b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly resources = res; 602b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 603b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly //allocate memory for the struct pointer, calling the constructor 604864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly ScriptField_Point touchPoints = new ScriptField_Point(myRenderscript, 2); 605b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 606b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly //Create an element manually and allocate memory for the int pointer 607864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly intPointer = Allocation.createSized(myRenderscript, Element.I32(myRenderscript), 2); 608b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 609b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly //create an instance of the Renderscript, pointing it to the bytecode resource 610864090eeaa5241f9fcf17420a3d0123c95052b96Robert Ly mScript = new ScriptC_example(myRenderscript, resources, R.raw.example); 611b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 612b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly //bind the struct and int pointers to the Renderscript 613b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly mScript.bind_touchPoints(touchPoints); 614b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly script.bind_intPointer(intPointer); 615b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 616b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly ... 617f197b639ecccc570ee235486f75ba15f87070c28Robert Ly} 618f197b639ecccc570ee235486f75ba15f87070c28Robert Ly</pre> 619f197b639ecccc570ee235486f75ba15f87070c28Robert Ly 620b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <h3>Reading and writing to memory</h3> 621b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <p>You can read and write to statically and dynamically allocated memory both at the Renderscript runtime 622b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly and Android framework layer.</p> 623b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 624b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p>Statically allocated memory comes with a one-way communication restriction 625b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyat the Renderscript runtime level. When Renderscript code changes the value of a variable, it is not 626b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lycommunicated back to the Android framework layer for efficiency purposes. The last value 627b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lythat is set from the Android framework is always returned during a call to a <code>get</code> 628b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lymethod. However, when Android framework code modifies a variable, that change can be communicated to 629b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lythe Renderscript runtime automatically or synchronized at a later time. If you need to send data 630f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Lyfrom the Renderscript runtime to the Android framework layer, you can use the 631f11ffc1178645762b74f945b6c5ee068dc6000d3Robert Ly<a href="{@docRoot}reference/renderscript/rs__core_8rsh.html"><code>rsSendToClient()</code></a> function 632b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyto overcome this limitation. 633b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly</p> 634b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p>When working with dynamically allocated memory, any changes at the Renderscript runtime layer are propagated 635b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyback to the Android framework layer if you modified the memory allocation using its associated pointer. 636b078d942911d5e1cf9533f7fe3e156c579ba396eRobert LyModifying an object at the Android framework layer immediately propagates that change back to the Renderscript 637b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyruntime layer.</p> 638b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 639b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <h4>Reading and writing to global variables</h4> 640b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 641b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <p>Reading and writing to global variables is a straightforward process. You can use the accessor methods 642b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly at the Android framework level or set them directly in the Renderscript code. Keep in mind that any 643b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly changes that you make in your Renderscript code are not propagated back to the Android framework layer.</p> 644b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 645b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly <p>For example, given the following struct declared in a file named <code>rsfile.rs</code>:</p> 646b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<pre> 647b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lytypedef struct Point { 648b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly int x; 649b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly int y; 650b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly} Point_t; 651b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 652b078d942911d5e1cf9533f7fe3e156c579ba396eRobert LyPoint_t point; 653b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 654b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly</pre> 655b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p>You can assign values to the struct like this directly in <code>rsfile.rs</code>. These values are not 656b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lypropagated back to the Android framework level:</p> 657b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<pre> 658b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lypoint.x = 1; 659b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lypoint.y = 1; 660b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly</pre> 661b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 662b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p>You can assign values to the struct at the Android framework layer like this. These values are 663b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lypropagated back to the Renderscript runtime level:</p> 664b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<pre> 665b078d942911d5e1cf9533f7fe3e156c579ba396eRobert LyScriptC_rsfile mScript; 666b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 667b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly... 668b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 669b078d942911d5e1cf9533f7fe3e156c579ba396eRobert LyItem i = new ScriptField_Point.Item(); 670b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyi.x = 1; 671b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyi.y = 1; 672b078d942911d5e1cf9533f7fe3e156c579ba396eRobert LymScript.set_point(i); 673b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly</pre> 674b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 675b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p>You can read the values in your Renderscript code like this:</p> 676b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 677b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<pre> 678b078d942911d5e1cf9533f7fe3e156c579ba396eRobert LyrsDebug("Printing out a Point", point.x, point.y); 679b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly</pre> 680b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 681b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p>You can read the values in the Android framework layer with the following code. Keep in mind that this 682b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lycode only returns a value if one was set at the Android framework level. You will get a null pointer 683b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyexception if you only set the value at the Renderscript runtime level:</p> 684b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 685b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<pre> 686b078d942911d5e1cf9533f7fe3e156c579ba396eRobert LyLog.i("TAGNAME", "Printing out a Point: " + mScript.get_point().x + " " + mScript.get_point().y); 687b078d942911d5e1cf9533f7fe3e156c579ba396eRobert LySystem.out.println(point.get_x() + " " + point.get_y()); 688b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly</pre> 689b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 690b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<h4>Reading and writing global pointers</h4> 691b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 692b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p>Assuming that memory has been allocated in the Android framework level and bound to the Renderscript runtime, 693b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyyou can read and write memory from the Android framework level by using the <code>get</code> and <code>set</code> methods for that pointer. 694b078d942911d5e1cf9533f7fe3e156c579ba396eRobert LyIn the Renderscript runtime layer, you can read and write to memory with pointers as normal and the changes are propagated 695b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyback to the Android framework layer, unlike with statically allocated memory.</p> 696b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 697b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p>For example, given the following pointer to a <code>struct</code> in a file named <code>rsfile.rs</code>:</p> 698b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<pre> 699b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lytypedef struct Point { 700b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly int x; 701b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly int y; 702b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly} Point_t; 703b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 704b078d942911d5e1cf9533f7fe3e156c579ba396eRobert LyPoint_t *point; 705b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly</pre> 706b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 707b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p>Assuming you already allocated memory at the Android framework layer, you can access values in 708b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lythe <code>struct</code> as normal. Any changes you make to the struct via its pointer variable 709b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyare automatically available to the Android framework layer:</p> 710b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 711b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<pre> 712b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lypoint[index].x = 1; 713b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lypoint[index].y = 1; 714b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly</pre> 715b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 716b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p>You can read and write values to the pointer at the Android framework layer as well: 717b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<pre> 718b078d942911d5e1cf9533f7fe3e156c579ba396eRobert LyScriptField_Point p = new ScriptField_Point(mRS, 1); 719b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly Item i = new ScriptField_Point.Item(); 720b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly i.x=100; 721b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly i.y = 100; 722b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly p.set(i, 0, true); 723b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly mScript.bind_point(p); 724b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 725b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly points.get_x(0); //read x and y from index 0 726b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly points.get_x(0); 727b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly</pre> 728b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly 729b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Ly<p>Once memory is already bound, you do not have to rebind the memory to the Renderscript 730b078d942911d5e1cf9533f7fe3e156c579ba396eRobert Lyruntime every time you make a change to a value.</p> 731