Skip to content

Commit b078d94

Browse files
author
Robert Ly
committed
cherrypick from master docs: Renderscript changes Change-Id: Ic84b7d8c5c48e118f337e60c8bb5b8bc68b0da16
Change-Id: I8bd2ba1f0a4f284c52cfd6de817744264d2c50de
1 parent 9575a1a commit b078d94

File tree

10 files changed

+10054
-760
lines changed

10 files changed

+10054
-760
lines changed

‎docs/html/guide/guide_toc.cs‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -271,7 +271,8 @@ localized titles are added in the language order specified below.
271271
</li>
272272
<li class="toggle-list">
273273
<div><a href="<?cs var:toroot ?>guide/topics/renderscript/index.html">
274-
<span class="en">RenderScript</span></a>
274+
<span class="en">Renderscript</span></a>
275+
<span class="new">updated</span>
275276
</div>
276277
<ul>
277278
<li><a href="<?cs var:toroot ?>guide/topics/renderscript/graphics.html">
@@ -361,7 +362,7 @@ localized titles are added in the language order specified below.
361362
</ul>
362363
</li>
363364
<li><a href="<?cs var:toroot?>guide/topics/wireless/wifip2p.html">
364-
<span class="en">WiFi Direct</span></a> <span class="new">new!</span>
365+
<span class="en">Wi-Fi Direct</span></a> <span class="new">new!</span>
365366
</li>
366367
<li class="toggle-list">
367368
<div><a href="<?cs var:toroot?>guide/topics/usb/index.html">

‎docs/html/guide/topics/renderscript/compute.jd‎

Lines changed: 245 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,253 @@
11
page.title=Compute
2-
parent.title=RenderScript
2+
parent.title=Renderscript
33
parent.link=index.html
4+
45
@jd:body
56

6-
<div id="qv-wrapper">
7-
<div id="qv">
7+
<div id="qv-wrapper">
8+
<div id="qv">
9+
<h2>In this document</h2>
10+
11+
<ol>
12+
<li>
13+
<a href="#creating">Creating a Compute Renderscript</a>
14+
15+
<ol>
16+
<li><a href="#creating-renderscript">Creating the Renderscript file</a></li>
817

9-
<h2>Related Samples</h2>
18+
<li><a href="#calling">Calling the Renderscript code</a></li>
19+
</ol>
20+
</li>
21+
</ol>
1022

11-
<ol>
12-
<li><a href="{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">Hello
13-
Compute</a></li>
14-
<li><a href="{@docRoot}resources/samples/RenderScript/Balls/index.html">Balls</a></li>
15-
</ol>
16-
</div>
23+
<h2>Related Samples</h2>
24+
25+
<ol>
26+
<li><a href="{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">Hello
27+
Compute</a></li>
28+
29+
<li><a href="{@docRoot}resources/samples/RenderScript/Balls/index.html">Balls</a></li>
30+
</ol>
1731
</div>
32+
</div>
33+
34+
<p>Renderscript exposes a set of compute APIs that you can use to do intensive computational
35+
operations. You can use the compute APIs in the context of a graphics Renderscript such as
36+
calculating the positions of many objects in a scene. You can also create standalone compute
37+
Renderscripts such as one that does image processing for a photo editor application.</p>
38+
39+
<p>Compute Renderscripts scale to the amount of
40+
processing cores available on the device. This is enabled through a function named
41+
<code>rsForEach()</code> (or the <code>forEach_root()</code> method at the Android framework level).
42+
that automatically partitions work across available processing cores on the device.
43+
For now, compute Renderscripts can only take advantage of CPU
44+
cores, but in the future, they can potentially run on other types of processors such as GPUs and
45+
DSPs.</p>
46+
47+
<h2 id="creating-renderscript">Creating a Compute Renderscript</h2>
48+
49+
<p>Implementing a compute Renderscript creating a <code>.rs</code> file that contains
50+
your Renderscript code and calling it at the Android framework level with the
51+
<code>forEach_root()</code> or at the Renderscript runtime level with the
52+
<code>rsForEach()</code> function. The following diagram describes how a typical compute
53+
Renderscript is set up:</p><img src="{@docRoot}images/rs_compute.png">
54+
55+
<p class="img-caption"><strong>Figure 1.</strong> Compute Renderscript overview</p>
56+
57+
<p>The following sections describe how to create a simple compute Renderscript and use it in an
58+
Android application. This example uses the <a href=
59+
"{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">HelloCompute Renderscript
60+
sample</a> that is provided in the SDK as a guide (some code has been modified from its original
61+
form for simplicity).</p>
62+
63+
<h3 id="creating-renderscript">Creating the Renderscript file</h3>
64+
65+
<p>Your Renderscript code resides in <code>.rs</code> and <code>.rsh</code> files in the
66+
<code>&lt;project_root&gt;/src/</code> directory. This code contains the compute logic
67+
and declares all necessary variables and pointers.
68+
Every compute <code>.rs</code> file generally contains the following items:</p>
69+
70+
<ul>
71+
<li>A pragma declaration (<code>#pragma rs java_package_name(<em>package.name</em>)</code>)
72+
that declares the package name of the <code>.java</code> reflection of this Renderscript.</li>
73+
74+
<li>A pragma declaration (<code>#pragma version(1)</code>) that declares the version of
75+
Renderscript that you are using (1 is the only value for now).</li>
76+
77+
<li>A <code>root()</code> function that is the main worker function. The root function is
78+
called by the <code>rsForEach</code> function, which allows the Renderscript code to be called and
79+
executed on multiple cores if they are available. The <code>root()</code> function must return
80+
<code>void</code> and accept the following arguments:
81+
82+
<ul>
83+
<li>Pointers to memory allocations that are used for the input and output of the compute
84+
Renderscript. Both of these pointers are required for Android 3.2 (API level 13) platform
85+
versions or older. Android 4.0 (API level 14) and later requires one or both of these
86+
allocations.</li>
87+
</ul>
88+
89+
<p>The following arguments are optional, but both must be supplied if you choose to use
90+
them:</p>
91+
92+
<ul>
93+
<li>A pointer for user-defined data that the Renderscript might need to carry out
94+
computations in addition to the necessary allocations. This can be a pointer to a simple
95+
primitive or a more complex struct.</li>
96+
97+
<li>The size of the user-defined data.</li>
98+
</ul>
99+
</li>
100+
101+
<li>An optional <code>init()</code> function. This allows you to do any initialization
102+
before the <code>root()</code> function runs, such as initializing variables. This
103+
function runs once and is called automatically when the Renderscript starts, before anything
104+
else in your Renderscript.</li>
105+
106+
<li>Any variables, pointers, and structures that you wish to use in your Renderscript code (can
107+
be declared in <code>.rsh</code> files if desired)</li>
108+
</ul>
109+
110+
<p>The following code shows how the <a href=
111+
"{@docRoot}resources/samples/RenderScript/HelloCompute/src/com/example/android/rs/hellocompute/mono.html">
112+
mono.rs</a> file is implemented:</p>
113+
<pre>
114+
#pragma version(1)
115+
#pragma rs java_package_name(com.example.android.rs.hellocompute)
116+
117+
//multipliers to convert a RGB colors to black and white
118+
const static float3 gMonoMult = {0.299f, 0.587f, 0.114f};
119+
120+
void root(const uchar4 *v_in, uchar4 *v_out) {
121+
//unpack a color to a float4
122+
float4 f4 = rsUnpackColor8888(*v_in);
123+
//take the dot product of the color and the multiplier
124+
float3 mono = dot(f4.rgb, gMonoMult);
125+
//repack the float to a color
126+
*v_out = rsPackColorTo8888(mono);
127+
}
128+
</pre>
129+
130+
<h3 id="calling">Calling the Renderscript code</h3>
131+
132+
<p>You can do Renderscript to Renderscript calls with <code>rsForEach</code> in situations
133+
such as when a graphics Renderscript needs to do a lot of computational operations. The Renderscript
134+
<a href="{@docRoot}resources/samples/RenderScript/Balls/index.html">Balls</a> sample shows how
135+
this is setup. The <a href=
136+
"resources/samples/RenderScript/Balls/src/com/example/android/rs/balls/balls.html">balls.rs</a>
137+
graphics Renderscript calls the <a href=
138+
"resources/samples/RenderScript/Balls/src/com/example/android/rs/balls/balls.html">balls_physics.rs</a>
139+
compute Renderscript to calculate the location of the balls that are rendered to the screen.</p>
140+
141+
<p>Another way to use a compute Renderscript is to call it from your Android framework code by
142+
creating a Renderscript object by instantiating the (<code>ScriptC_<em>script_name</em></code>)
143+
class. This class contains a method, <code>forEach_root()</code>, that lets you invoke
144+
<code>rsForEach</code>. You give it the same parameters that you would if you were invoking it
145+
at the Renderscript runtime level. This technique allows your Android application to offload
146+
intensive mathematical calculations to Renderscript. See the <a href=
147+
"{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">HelloCompute</a> sample to see
148+
how a simple Android application can utilize a compute Renderscript.</p>
149+
150+
<p>To call a compute Renderscript at the Android framework level:</p>
151+
152+
<ol>
153+
<li>Allocate memory that is needed by the compute Renderscript in your Android framework code.
154+
You need an input and output {@link android.renderscript.Allocation} for Android 3.2 (API level
155+
13) platform versions and older. The Android 4.0 (API level 14) platform version requires only
156+
one or both {@link android.renderscript.Allocation}s.</li>
157+
158+
<li>Create an instance of the <code>ScriptC_<em>script_name</em></code> class.</li>
159+
160+
<li>Call <code>forEach_root()</code>, passing in the allocations, the
161+
Renderscript, and any optional user-defined data. The output allocation will contain the output
162+
of the compute Renderscript.</li>
163+
</ol>
164+
165+
<p>In the following example, taken from the <a href=
166+
"{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">HelloCompute</a> sample, processes
167+
a bitmap and outputs a black and white version of it. The
168+
<code>createScript()</code> method carries out the steps described previously. This method the compute
169+
Renderscript, <code>mono.rs</code>, passing in memory allocations that store the bitmap to be processed
170+
as well as the eventual output bitmap. It then displays the processed bitmap onto the screen:</p>
171+
<pre>
172+
package com.example.android.rs.hellocompute;
173+
174+
import android.app.Activity;
175+
import android.os.Bundle;
176+
import android.graphics.BitmapFactory;
177+
import android.graphics.Bitmap;
178+
import android.renderscript.RenderScript;
179+
import android.renderscript.Allocation;
180+
import android.widget.ImageView;
181+
182+
public class HelloCompute extends Activity {
183+
private Bitmap mBitmapIn;
184+
private Bitmap mBitmapOut;
185+
186+
private RenderScript mRS;
187+
private Allocation mInAllocation;
188+
private Allocation mOutAllocation;
189+
private ScriptC_mono mScript;
190+
191+
&#064;Override
192+
protected void onCreate(Bundle savedInstanceState) {
193+
super.onCreate(savedInstanceState);
194+
setContentView(R.layout.main);
195+
196+
mBitmapIn = loadBitmap(R.drawable.data);
197+
mBitmapOut = Bitmap.createBitmap(mBitmapIn.getWidth(), mBitmapIn.getHeight(),
198+
mBitmapIn.getConfig());
199+
200+
ImageView in = (ImageView) findViewById(R.id.displayin);
201+
in.setImageBitmap(mBitmapIn);
202+
203+
ImageView out = (ImageView) findViewById(R.id.displayout);
204+
out.setImageBitmap(mBitmapOut);
205+
206+
createScript();
207+
}
208+
private void createScript() {
209+
mRS = RenderScript.create(this);
210+
mInAllocation = Allocation.createFromBitmap(mRS, mBitmapIn,
211+
Allocation.MipmapControl.MIPMAP_NONE,
212+
Allocation.USAGE_SCRIPT);
213+
mOutAllocation = Allocation.createTyped(mRS, mInAllocation.getType());
214+
mScript = new ScriptC_mono(mRS, getResources(), R.raw.mono);
215+
mScript.forEach_root(mInAllocation, mOutAllocation);
216+
mOutAllocation.copyTo(mBitmapOut);
217+
}
218+
219+
private Bitmap loadBitmap(int resource) {
220+
final BitmapFactory.Options options = new BitmapFactory.Options();
221+
options.inPreferredConfig = Bitmap.Config.ARGB_8888;
222+
return BitmapFactory.decodeResource(getResources(), resource, options);
223+
}
224+
}
225+
</pre>
226+
227+
<p>To call a compute Renderscript from another Renderscript file:</p>
228+
<ol>
229+
<li>Allocate memory that is needed by the compute Renderscript in your Android framework code.
230+
You need an input and output {@link android.renderscript.Allocation} for Android 3.2 (API level
231+
13) platform versions and older. The Android 4.0 (API level 14) platform version requires only
232+
one or both {@link android.renderscript.Allocation}s.</li>
233+
234+
<li>Call <code>rsForEach()</code>, passing in the allocations and any optional user-defined data.
235+
The output allocation will contain the output of the compute Renderscript.</li>
236+
</ol>
237+
<p>The following example, taken from the <a href=
238+
"{@docRoot}resources/samples/RenderScript/Balls/src/com/example/android/rs/balls/balls.html">Renderscript
239+
Balls sample</a>, demonstrates how to do make a script to script call:</p>
240+
<pre>
241+
rs_script script;
242+
rs_allocation in_allocation;
243+
rs_allocation out_allocation;
244+
UserData_t data;
245+
...
246+
rsForEach(script, in_allocation, out_allocation, &amp;data, sizeof(data));
247+
</pre>
18248

19-
<p>RenderScript exposes a set of compute APIs that you can use to do intensive computational operations.
20-
You can use the compute APIs in the context of a graphics RenderScript such as calculating the
21-
transformation of many geometric objects in a scene. You can also create a standalone compute RenderScript that does not
22-
draw anything to the screen such as bitmap image processing for a photo editor application.
23-
The RenderScript compute APIs are mainly defined in the <code>rs_cl.rsh</code> header</p>
24-
25-
<p>Compute RenderScripts are simpler to setup and implement as there is no graphics rendering involved.
26-
You can offload computational aspects of your application to RenderScript by creating a native RenderScript
27-
file (.rs) and using the generated reflected layer class to call functions in the <code>.rs</code> file.
28-
29-
<p>See the <a href="{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">HelloCompute</a>
30-
sample in the Android SDK for more
31-
information on how to create a simple compute RenderScript.</p>
32-
<p>
33-
See the <a href="{@docRoot}resources/samples/RenderScript/Balls/index.html">Balls</a>
34-
sample in the Android SDK for more
35-
information on how to create a compute RenderScript that is used in a graphics RenderScript.
36-
The compute RenderScript is contained in
37-
<a href="{@docRoot}resources/samples/RenderScript/Balls/src/com/example/android/rs/balls/ball_physics.html">balls_physics.rs</a>.
38-
</p>
249+
<p>In this example, assume that the script and memory allocations have already been
250+
allocated and bound at the Android framework level and that <code>UserData_t</code> is a struct
251+
declared previously. Passing a pointer to a struct and the size of the struct to <code>rsForEach</code>
252+
is optional, but useful if your compute Renderscript requires additional information other than
253+
the necessary memory allocations.</p>

0 commit comments

Comments
 (0)