Merge "docs: remove graphics rs docs and restructure existing docs" into jb-dev
diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs
index cc6737ba..94b9773 100644
--- a/docs/html/guide/guide_toc.cs
+++ b/docs/html/guide/guide_toc.cs
@@ -311,26 +311,26 @@
<li><a href="<?cs var:toroot ?>guide/topics/graphics/hardware-accel.html">
<span class="en">Hardware Acceleration</span>
</a></li>
- <li class="nav-section">
- <div class="nav-section-header"><a href="<?cs var:toroot ?>guide/topics/graphics/renderscript/index.html">
- <span class="en">Renderscript</span>
- </a></div>
- <ul>
- <li><a href="<?cs var:toroot ?>guide/topics/graphics/renderscript/graphics.html">
- <span class="en">Graphics</span></a>
- </li>
- <li><a href="<?cs var:toroot ?>guide/topics/graphics/renderscript/compute.html">
- <span class="en">Compute</span></a>
- </li>
- <li><a href="<?cs var:toroot ?>guide/topics/graphics/renderscript/reference.html">
- <span class="en">Runtime API Reference</span></a>
- </li>
- </ul>
- </li>
</ul>
</li><!-- end of graphics and animation-->
-
+ <li class="nav-section">
+ <div class="nav-section-header"><a href="<?cs var:toroot ?>guide/topics/renderscript/index.html">
+ <span class="en">Computation</span>
+ </a></div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>guide/topics/renderscript/compute.html">
+ <span class="en">Renderscript</span></a>
+ </li>
+
+ <li><a href="<?cs var:toroot ?>guide/topics/renderscript/advanced.html">
+ <span class="en">Advanced Renderscript</span></a>
+ </li>
+ <li><a href="<?cs var:toroot ?>guide/topics/renderscript/reference.html">
+ <span class="en">Runtime API Reference</span></a>
+ </li>
+ </ul>
+ </li>
<li class="nav-section">
<div class="nav-section-header"><a href="<?cs var:toroot ?>guide/topics/media/index.html">
<span class="en">Media and Camera</span>
diff --git a/docs/html/guide/topics/graphics/renderscript/compute.jd b/docs/html/guide/topics/graphics/renderscript/compute.jd
deleted file mode 100644
index e827f00..0000000
--- a/docs/html/guide/topics/graphics/renderscript/compute.jd
+++ /dev/null
@@ -1,253 +0,0 @@
-page.title=Compute
-parent.title=Renderscript
-parent.link=index.html
-
-@jd:body
-
-<div id="qv-wrapper">
- <div id="qv">
- <h2>In this document</h2>
-
- <ol>
- <li>
- <a href="#creating">Creating a Compute Renderscript</a>
-
- <ol>
- <li><a href="#creating-renderscript">Creating the Renderscript file</a></li>
-
- <li><a href="#calling">Calling the Renderscript code</a></li>
- </ol>
- </li>
- </ol>
-
- <h2>Related Samples</h2>
-
- <ol>
- <li><a href="{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">Hello
- Compute</a></li>
-
- <li><a href="{@docRoot}resources/samples/RenderScript/Balls/index.html">Balls</a></li>
- </ol>
- </div>
-</div>
-
-<p>Renderscript exposes a set of compute APIs that you can use to do intensive computational
-operations. You can use the compute APIs in the context of a graphics Renderscript such as
-calculating the positions of many objects in a scene. You can also create standalone compute
-Renderscripts such as one that does image processing for a photo editor application.</p>
-
-<p>Compute Renderscripts scale to the amount of
-processing cores available on the device. This is enabled through a function named
-<code>rsForEach()</code> (or the <code>forEach_root()</code> method at the Android framework level).
-that automatically partitions work across available processing cores on the device.
-For now, compute Renderscripts can only take advantage of CPU
-cores, but in the future, they can potentially run on other types of processors such as GPUs and
-DSPs.</p>
-
-<h2 id="creating-renderscript">Creating a Compute Renderscript</h2>
-
-<p>Implementing a compute Renderscript creating a <code>.rs</code> file that contains
-your Renderscript code and calling it at the Android framework level with the
-<code>forEach_root()</code> or at the Renderscript runtime level with the
-<code>rsForEach()</code> function. The following diagram describes how a typical compute
-Renderscript is set up:</p><img src="{@docRoot}images/rs_compute.png">
-
-<p class="img-caption"><strong>Figure 1.</strong> Compute Renderscript overview</p>
-
-<p>The following sections describe how to create a simple compute Renderscript and use it in an
-Android application. This example uses the <a href=
-"{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">HelloCompute Renderscript
-sample</a> that is provided in the SDK as a guide (some code has been modified from its original
-form for simplicity).</p>
-
-<h3 id="creating-renderscript">Creating the Renderscript file</h3>
-
-<p>Your Renderscript code resides in <code>.rs</code> and <code>.rsh</code> files in the
-<code><project_root>/src/</code> directory. This code contains the compute logic
-and declares all necessary variables and pointers.
-Every compute <code>.rs</code> file generally contains the following items:</p>
-
-<ul>
- <li>A pragma declaration (<code>#pragma rs java_package_name(<em>package.name</em>)</code>)
- that declares the package name of the <code>.java</code> reflection of this Renderscript.</li>
-
- <li>A pragma declaration (<code>#pragma version(1)</code>) that declares the version of
- Renderscript that you are using (1 is the only value for now).</li>
-
- <li>A <code>root()</code> function that is the main worker function. The root function is
- called by the <code>rsForEach</code> function, which allows the Renderscript code to be called and
- executed on multiple cores if they are available. The <code>root()</code> function must return
- <code>void</code> and accept the following arguments:
-
- <ul>
- <li>Pointers to memory allocations that are used for the input and output of the compute
- Renderscript. Both of these pointers are required for Android 3.2 (API level 13) platform
- versions or older. Android 4.0 (API level 14) and later requires one or both of these
- allocations.</li>
- </ul>
-
- <p>The following arguments are optional, but both must be supplied if you choose to use
- them:</p>
-
- <ul>
- <li>A pointer for user-defined data that the Renderscript might need to carry out
- computations in addition to the necessary allocations. This can be a pointer to a simple
- primitive or a more complex struct.</li>
-
- <li>The size of the user-defined data.</li>
- </ul>
- </li>
-
- <li>An optional <code>init()</code> function. This allows you to do any initialization
- before the <code>root()</code> function runs, such as initializing variables. This
- function runs once and is called automatically when the Renderscript starts, before anything
- else in your Renderscript.</li>
-
- <li>Any variables, pointers, and structures that you wish to use in your Renderscript code (can
- be declared in <code>.rsh</code> files if desired)</li>
-</ul>
-
-<p>The following code shows how the <a href=
-"{@docRoot}resources/samples/RenderScript/HelloCompute/src/com/example/android/rs/hellocompute/mono.html">
-mono.rs</a> file is implemented:</p>
-<pre>
-#pragma version(1)
-#pragma rs java_package_name(com.example.android.rs.hellocompute)
-
-//multipliers to convert a RGB colors to black and white
-const static float3 gMonoMult = {0.299f, 0.587f, 0.114f};
-
-void root(const uchar4 *v_in, uchar4 *v_out) {
- //unpack a color to a float4
- float4 f4 = rsUnpackColor8888(*v_in);
- //take the dot product of the color and the multiplier
- float3 mono = dot(f4.rgb, gMonoMult);
- //repack the float to a color
- *v_out = rsPackColorTo8888(mono);
-}
-</pre>
-
-<h3 id="calling">Calling the Renderscript code</h3>
-
-<p>You can do Renderscript to Renderscript calls with <code>rsForEach</code> in situations
-such as when a graphics Renderscript needs to do a lot of computational operations. The Renderscript
-<a href="{@docRoot}resources/samples/RenderScript/Balls/index.html">Balls</a> sample shows how
-this is setup. The <a href=
-"resources/samples/RenderScript/Balls/src/com/example/android/rs/balls/balls.html">balls.rs</a>
-graphics Renderscript calls the <a href=
-"resources/samples/RenderScript/Balls/src/com/example/android/rs/balls/balls.html">balls_physics.rs</a>
-compute Renderscript to calculate the location of the balls that are rendered to the screen.</p>
-
-<p>Another way to use a compute Renderscript is to call it from your Android framework code by
-creating a Renderscript object by instantiating the (<code>ScriptC_<em>script_name</em></code>)
-class. This class contains a method, <code>forEach_root()</code>, that lets you invoke
-<code>rsForEach</code>. You give it the same parameters that you would if you were invoking it
-at the Renderscript runtime level. This technique allows your Android application to offload
-intensive mathematical calculations to Renderscript. See the <a href=
-"{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">HelloCompute</a> sample to see
-how a simple Android application can utilize a compute Renderscript.</p>
-
-<p>To call a compute Renderscript at the Android framework level:</p>
-
-<ol>
- <li>Allocate memory that is needed by the compute Renderscript in your Android framework code.
- You need an input and output {@link android.renderscript.Allocation} for Android 3.2 (API level
- 13) platform versions and older. The Android 4.0 (API level 14) platform version requires only
- one or both {@link android.renderscript.Allocation}s.</li>
-
- <li>Create an instance of the <code>ScriptC_<em>script_name</em></code> class.</li>
-
- <li>Call <code>forEach_root()</code>, passing in the allocations, the
- Renderscript, and any optional user-defined data. The output allocation will contain the output
- of the compute Renderscript.</li>
-</ol>
-
-<p>In the following example, taken from the <a href=
-"{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">HelloCompute</a> sample, processes
-a bitmap and outputs a black and white version of it. The
-<code>createScript()</code> method carries out the steps described previously. This method the compute
-Renderscript, <code>mono.rs</code>, passing in memory allocations that store the bitmap to be processed
-as well as the eventual output bitmap. It then displays the processed bitmap onto the screen:</p>
-<pre>
-package com.example.android.rs.hellocompute;
-
-import android.app.Activity;
-import android.os.Bundle;
-import android.graphics.BitmapFactory;
-import android.graphics.Bitmap;
-import android.renderscript.RenderScript;
-import android.renderscript.Allocation;
-import android.widget.ImageView;
-
-public class HelloCompute extends Activity {
- private Bitmap mBitmapIn;
- private Bitmap mBitmapOut;
-
- private RenderScript mRS;
- private Allocation mInAllocation;
- private Allocation mOutAllocation;
- private ScriptC_mono mScript;
-
- @Override
- protected void onCreate(Bundle savedInstanceState) {
- super.onCreate(savedInstanceState);
- setContentView(R.layout.main);
-
- mBitmapIn = loadBitmap(R.drawable.data);
- mBitmapOut = Bitmap.createBitmap(mBitmapIn.getWidth(), mBitmapIn.getHeight(),
- mBitmapIn.getConfig());
-
- ImageView in = (ImageView) findViewById(R.id.displayin);
- in.setImageBitmap(mBitmapIn);
-
- ImageView out = (ImageView) findViewById(R.id.displayout);
- out.setImageBitmap(mBitmapOut);
-
- createScript();
- }
- private void createScript() {
- mRS = RenderScript.create(this);
- mInAllocation = Allocation.createFromBitmap(mRS, mBitmapIn,
- Allocation.MipmapControl.MIPMAP_NONE,
- Allocation.USAGE_SCRIPT);
- mOutAllocation = Allocation.createTyped(mRS, mInAllocation.getType());
- mScript = new ScriptC_mono(mRS, getResources(), R.raw.mono);
- mScript.forEach_root(mInAllocation, mOutAllocation);
- mOutAllocation.copyTo(mBitmapOut);
- }
-
- private Bitmap loadBitmap(int resource) {
- final BitmapFactory.Options options = new BitmapFactory.Options();
- options.inPreferredConfig = Bitmap.Config.ARGB_8888;
- return BitmapFactory.decodeResource(getResources(), resource, options);
- }
-}
-</pre>
-
-<p>To call a compute Renderscript from another Renderscript file:</p>
-<ol>
- <li>Allocate memory that is needed by the compute Renderscript in your Android framework code.
- You need an input and output {@link android.renderscript.Allocation} for Android 3.2 (API level
- 13) platform versions and older. The Android 4.0 (API level 14) platform version requires only
- one or both {@link android.renderscript.Allocation}s.</li>
-
- <li>Call <code>rsForEach()</code>, passing in the allocations and any optional user-defined data.
- The output allocation will contain the output of the compute Renderscript.</li>
-</ol>
-<p>The following example, taken from the <a href=
-"{@docRoot}resources/samples/RenderScript/Balls/src/com/example/android/rs/balls/balls.html">Renderscript
-Balls sample</a>, demonstrates how to do make a script to script call:</p>
-<pre>
-rs_script script;
-rs_allocation in_allocation;
-rs_allocation out_allocation;
-UserData_t data;
-...
-rsForEach(script, in_allocation, out_allocation, &data, sizeof(data));
-</pre>
-
-<p>In this example, assume that the script and memory allocations have already been
-allocated and bound at the Android framework level and that <code>UserData_t</code> is a struct
-declared previously. Passing a pointer to a struct and the size of the struct to <code>rsForEach</code>
-is optional, but useful if your compute Renderscript requires additional information other than
-the necessary memory allocations.</p>
diff --git a/docs/html/guide/topics/graphics/renderscript/index.jd b/docs/html/guide/topics/renderscript/advanced.jd
similarity index 84%
rename from docs/html/guide/topics/graphics/renderscript/index.jd
rename to docs/html/guide/topics/renderscript/advanced.jd
index b2d9f84..58f5e1f 100644
--- a/docs/html/guide/topics/graphics/renderscript/index.jd
+++ b/docs/html/guide/topics/renderscript/advanced.jd
@@ -1,4 +1,7 @@
-page.title=Renderscript
+page.title=Advanced Renderscript
+parent.title=Computation
+parent.link=index.html
+
@jd:body
<div id="qv-wrapper">
@@ -6,7 +9,6 @@
<h2>In this document</h2>
<ol>
- <li><a href="#overview">Renderscript Overview</a></li>
<li><a href="#native">Renderscript Runtime Layer</a></li>
<li><a href="#reflected">Reflected Layer</a>
<ol>
@@ -33,86 +35,22 @@
</div>
</div>
- <p>Renderscript offers a high performance 3D graphics rendering and compute API at the native
- level that you write in C (C99 standard). The main advantages of Renderscript are:</p>
- <ul>
- <li>Portability: Renderscript is designed to run on many types of devices with different
- processor (CPU, GPU, and DSP for instance) architectures. It supports all of these architectures without
- having to target each device, because the code is compiled and cached on the device
- at runtime.</li>
+ <p></p>
- <li>Performance: Renderscript provides similar performance to OpenGL with the NDK and also
- provides a high performance compute API that is not offered by OpenGL.</li>
-
- <li>Usability: Renderscript simplifies development when possible, such as eliminating JNI glue code
- and simplifying mesh setup.</li>
- </ul>
-
- <p>The main disadvantages are:</p>
-
- <ul>
- <li>Development complexity: Renderscript introduces a new set of APIs that you have to learn.
- Renderscript also allocates memory differently compared to OpenGL with the Android framework APIs.
- However, these issues are not hard to understand and Renderscript offers many features that
- make it easier than OpenGL to initialize rendering.</li>
-
- <li>Debugging visibility: Renderscript can potentially execute (planned feature for later releases)
- on processors other than the main CPU (such as the GPU), so if this occurs, debugging becomes more difficult.
- </li>
- </ul>
-
-
- <p>For an example of Renderscript in action, install the Renderscript sample applications that
- are shipped with the SDK in <code><sdk_root>/samples/android-11/RenderScript</code>.
- You can also see a typical use of Renderscript with the 3D carousel view in the Android 3.x
- versions of Google Books and YouTube.</p>
-
- <h2 id="overview">Renderscript Overview</h2>
- <p>The Renderscript runtime operates at the native level and still needs to communicate
-with the Android VM, so the way a Renderscript application is setup is different from a pure VM
-application. An application that uses Renderscript is still a traditional Android application that
-runs in the VM, but you write Renderscript code for the parts of your program that require
-it. Using Renderscript can be as simple as offloading a few math calculations or as complicated as
-rendering an entire 3D game. No matter what you use it for, Renderscript remains platform
-independent, so you do not have to target multiple architectures (for example,
-ARM v5, ARM v7, x86).</p>
-
- <p>The Renderscript system adopts a control and slave architecture where the low-level Renderscript runtime
- code is controlled by the higher level Android system that runs in a virtual machine (VM). The
- Android VM still retains all control of memory management and binds memory that it allocates to
- the Renderscript runtime, so the Renderscript code can access it. The Android framework makes
-asynchronous calls to Renderscript, and the calls are placed in a message queue and processed
-as soon as possible. Figure 1 shows how the Renderscript system is structured.</p>
-
- <img id="figure1" src="{@docRoot}images/rs_overview.png" />
- <p class="img-caption"><strong>Figure 1.</strong> Renderscript system overview</p>
-
- <p>When using Renderscript, there are three layers of APIs that enable communication between the
- Renderscript runtime and Android framework code:</p>
-
- <ul>
- <li>The Renderscript runtime APIs allow you to do the computation or graphics rendering
- that is required by your application.</li>
-
- <li>The reflected layer APIs are a set of classes that are reflected from your Renderscript
-runtime code. It is basically a wrapper around the Renderscript code that allows the Android
-framework to interact with the Renderscript runtime. The Android build tools automatically generate the
-classes for this layer during the build process. These classes eliminate the need to write JNI glue
-code, like with the NDK.</li>
-
- <li>The Android framework APIs, which include the {@link android.renderscript} package, allow you to
- build your application using traditional Android components such as activities and views. When
- using Renderscript, this layer calls the reflected layer to access the Renderscript
- runtime.</li>
- </ul>
-
- <p></p>
+ <p>Because applications that utilize Renderscript still run inside of the Android VM,
+ you have access to all of the framework APIs that you are familiar with, but can
+ utilize Renderscript when appropriate. To facilitate this interaction between
+ the framework and the Renderscript runtime, an intermediate layer of code is also
+ present to facilitate communication and memory management between the two levels of code.
+ This document goes into more detail about these
+ different layers of code as well as how memory is shared between the Android VM and
+ Renderscript runtime.</p>
<h2 id="native">Renderscript Runtime Layer</h2>
<p>Your Renderscript code is compiled and
executed in a compact and well-defined runtime layer. The Renderscript runtime APIs offer support for
-intensive computation and graphics rendering that is portable and automatically scalable to the
+intensive computation that is portable and automatically scalable to the
amount of cores available on a processor.
</p>
<p class="note"><strong>Note:</strong> The standard C functions in the NDK must be
@@ -132,16 +70,14 @@
<ul>
- <li>Graphics rendering functions</li>
-
<li>Memory allocation request features</li>
<li>A large collection of math functions with both scalar and vector typed overloaded versions
of many common routines. Operations such as adding, multiplying, dot product, and cross product
are available as well as atomic arithmetic and comparison functions.</li>
- <li>Conversion routines for primitive data types and vectors, matrix routines, date and time
- routines, and graphics routines.</li>
+ <li>Conversion routines for primitive data types and vectors, matrix routines, and date and time
+ routines</li>
<li>Data types and structures to support the Renderscript system such as Vector types for
defining two-, three-, or four-vectors.</li>
@@ -149,11 +85,7 @@
<li>Logging functions</li>
</ul>
- <p>See the Renderscript runtime API reference for more information on the available functions. The
- Renderscript header files are automatically included for you, except for the Renderscript graphics header file, which
- you can include as follows:</p>
-
-<pre>#include "rs_graphics.rsh"</pre>
+ <p>See the Renderscript runtime API reference for more information on the available functions.
<h2 id="reflected">Reflected Layer</h2>
@@ -428,14 +360,9 @@
specified memory spaces. The following example allocates memory for a custom data type
in both the script and vertex memory spaces:</p>
<pre>
- ScriptField_Point touchPoints = new ScriptField_Point(glRenderer, 2,
+ ScriptField_Point touchPoints = new ScriptField_Point(myRenderscript, 2,
Allocation.USAGE_SCRIPT | Allocation.USAGE_GRAPHICS_VERTEX);
</pre>
-
- <p>If you modify the memory in one memory space and want to push the updates to the rest of
- the memory spaces, call <a href="{@docRoot}reference/renderscript/rs__graphics_8rsh.html">
- <code>rsgAllocationSyncAll()</code></a> in your Renderscript code to
- synchronize the memory.</p>
</li>
<li>A static nested class, <code>Item</code>, allows you to create an instance of the
@@ -665,23 +592,22 @@
<code>intPointer</code>, and a pointer to a struct, <code>touchPoints</code>. It also binds the memory to the
Renderscript:</p>
<pre>
-private RenderScriptGL glRenderer;
+private RenderScript myRenderscript;
private ScriptC_example script;
private Resources resources;
-public void init(RenderScriptGL rs, Resources res) {
- //get the rendering context and resources from the calling method
- glRenderer = rs;
+public void init(RenderScript rs, Resources res) {
+ myRenderscript = rs;
resources = res;
//allocate memory for the struct pointer, calling the constructor
- ScriptField_Point touchPoints = new ScriptField_Point(glRenderer, 2);
+ ScriptField_Point touchPoints = new ScriptField_Point(myRenderscript, 2);
//Create an element manually and allocate memory for the int pointer
- intPointer = Allocation.createSized(glRenderer, Element.I32(glRenderer), 2);
+ intPointer = Allocation.createSized(myRenderscript, Element.I32(myRenderscript), 2);
//create an instance of the Renderscript, pointing it to the bytecode resource
- mScript = new ScriptC_example(glRenderer, resources, R.raw.example);
+ mScript = new ScriptC_example(myRenderscript, resources, R.raw.example);
//bind the struct and int pointers to the Renderscript
mScript.bind_touchPoints(touchPoints);
diff --git a/docs/html/guide/topics/renderscript/compute.jd b/docs/html/guide/topics/renderscript/compute.jd
new file mode 100644
index 0000000..d464c90
--- /dev/null
+++ b/docs/html/guide/topics/renderscript/compute.jd
@@ -0,0 +1,340 @@
+page.title=Renderscript Computation
+parent.title=Computation
+parent.link=index.html
+
+@jd:body
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+
+ <ol>
+ <li><a href="#overview">Renderscript System Overview</a></li>
+ <li>
+ <a href="#creating-renderscript">Creating a Computation Renderscript</a>
+
+ <ol>
+ <li><a href="#creating-rs-file">Creating the Renderscript file</a></li>
+
+ <li><a href="#calling">Calling the Renderscript code</a></li>
+ </ol>
+ </li>
+ </ol>
+
+ <h2>Related Samples</h2>
+
+ <ol>
+ <li><a href="{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">Hello
+ Compute</a></li>
+ </ol>
+ </div>
+</div>
+
+ <p>Renderscript offers a high performance computation API at the native
+level that you write in C (C99 standard). Renderscript gives your apps the ability to run
+operations with automatic parallelization across all available processor cores.
+It also supports different types of processors such as the CPU, GPU or DSP. Renderscript
+is useful for apps that do image processing, mathematical modeling, or any operations
+that require lots of mathematical computation.</p>
+
+<p>In addition, you have access to all of these features without having to write code to
+support different architectures or a different amount of processing cores. You also
+do not need to recompile your application for different processor types, because Renderscript
+code is compiled on the device at runtime.</p>
+
+<p class="note"><strong>Deprecation Notice</strong>: Earlier versions of Renderscript included
+ an experimental graphics engine component. This component
+is now deprecated as of Android 4.1 (most of the APIs in <code>rs_graphics.rsh</code>
+and the corresponding APIs in {@link android.renderscript}).
+If you have apps that render graphics with Renderscript, we highly
+recommend you convert your code to another Android graphics rendering option.</p>
+
+ <h2 id="overview">Renderscript System Overview</h2>
+ <p>The Renderscript runtime operates at the native level and still needs to communicate
+with the Android VM, so the way a Renderscript application is set up is different from a pure VM
+application. An application that uses Renderscript is still a traditional Android application that
+runs in the VM, but you write Renderscript code for the parts of your program that require
+it. No matter what you use it for, Renderscript remains platform
+independent, so you do not have to target multiple architectures (for example,
+ARM v5, ARM v7, x86).</p>
+
+<p>The Renderscript system adopts a control and slave architecture where the low-level Renderscript runtime
+code is controlled by the higher level Android system that runs in a virtual machine (VM). The
+Android VM still retains all control of memory management and binds memory that it allocates to
+the Renderscript runtime, so the Renderscript code can access it. The Android framework makes
+asynchronous calls to Renderscript, and the calls are placed in a message queue and processed
+as soon as possible. Figure 1 shows how the Renderscript system is structured.</p>
+
+ <img id="figure1" src="{@docRoot}images/rs_overview.png" />
+ <p class="img-caption"><strong>Figure 1.</strong> Renderscript system overview</p>
+
+ <p>When using Renderscript, there are three layers of APIs that enable communication between the
+ Renderscript runtime and Android framework code:</p>
+
+ <ul>
+ <li>The Renderscript runtime APIs allow you to do the computation
+ that is required by your application.</li>
+
+ <li>The reflected layer APIs are a set of classes that are reflected from your Renderscript
+runtime code. It is basically a wrapper around the Renderscript code that allows the Android
+framework to interact with the Renderscript runtime. The Android build tools automatically generate the
+classes for this layer during the build process. These classes eliminate the need to write JNI glue
+code, like with the NDK.</li>
+
+ <li>The Android framework layer calls the reflected layer to access the Renderscript
+ runtime.</li>
+ </ul>
+
+<p>Because of the way Renderscript is structured, the main advantages are:</p>
+ <ul>
+ <li>Portability: Renderscript is designed to run on many types of devices with different
+ processor (CPU, GPU, and DSP for instance) architectures. It supports all of these architectures without
+ having to target each device, because the code is compiled and cached on the device
+ at runtime.</li>
+
+ <li>Performance: Renderscript provides a high performance computation API with seamless parallelization
+ across the amount of cores on the device.</li>
+
+ <li>Usability: Renderscript simplifies development when possible, such as eliminating JNI glue code.</li>
+ </ul>
+
+ <p>The main disadvantages are:</p>
+
+ <ul>
+ <li>Development complexity: Renderscript introduces a new set of APIs that you have to learn.</li>
+
+ <li>Debugging visibility: Renderscript can potentially execute (planned feature for later releases)
+ on processors other than the main CPU (such as the GPU), so if this occurs, debugging becomes more difficult.
+ </li>
+ </ul>
+
+<p>For a more detailed explanation of how all of these layers work together, see
+ <a href="{@docRoot}guide/topics/renderscript/advanced.html">Advanced Renderscript</a>.<p>
+
+
+<h2 id="creating-renderscript">Creating a Renderscript</h2>
+
+<p>Renderscripts scale to the amount of
+processing cores available on the device. This is enabled through a function named
+<code>rsForEach()</code> (or the <code>forEach_root()</code> method at the Android framework level).
+that automatically partitions work across available processing cores on the device.
+For now, Renderscript can only take advantage of CPU
+cores, but in the future, they can potentially run on other types of processors such as GPUs and
+DSPs.</p>
+
+<p>Implementing a Renderscript involves creating a <code>.rs</code> file that contains
+your Renderscript code and calling it at the Android framework level with the
+<code>forEach_root()</code> or at the Renderscript runtime level with the
+<code>rsForEach()</code> function. The following diagram describes how a typical
+Renderscript is set up:</p><img src="{@docRoot}images/rs_compute.png">
+
+<p class="img-caption"><strong>Figure 1.</strong> Renderscript overview</p>
+
+<p>The following sections describe how to create a simple Renderscript and use it in an
+Android application. This example uses the <a href=
+"{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">HelloCompute Renderscript
+sample</a> that is provided in the SDK as a guide (some code has been modified from its original
+form for simplicity).</p>
+
+<h3 id="creating-rs-file">Creating the Renderscript file</h3>
+
+<p>Your Renderscript code resides in <code>.rs</code> and <code>.rsh</code> files in the
+<code><project_root>/src/</code> directory. This code contains the computation logic
+and declares all necessary variables and pointers.
+Every <code>.rs</code> file generally contains the following items:</p>
+
+<ul>
+ <li>A pragma declaration (<code>#pragma rs java_package_name(<em>package.name</em>)</code>)
+ that declares the package name of the <code>.java</code> reflection of this Renderscript.</li>
+
+ <li>A pragma declaration (<code>#pragma version(1)</code>) that declares the version of
+ Renderscript that you are using (1 is the only value for now).</li>
+
+ <li><p>A <code>root()</code> function that is the main worker function. The root function is
+ called by the <code>rsForEach</code> function, which allows the Renderscript code to be called and
+ executed on multiple cores if they are available. The <code>root()</code> function must return
+ <code>void</code> and accept the following arguments:</p>
+
+ <ul>
+ <li>Pointers to memory allocations that are used for the input and output of the
+ Renderscript. Both of these pointers are required for Android 3.2 (API level 13) platform
+ versions or older. Android 4.0 (API level 14) and later requires one or both of these
+ allocations.</li>
+ </ul>
+
+ <p>The following arguments are optional, but both must be supplied if you choose to use
+ them:</p>
+
+ <ul>
+ <li>A pointer for user-defined data that the Renderscript might need to carry out
+ computations in addition to the necessary allocations. This can be a pointer to a simple
+ primitive or a more complex struct.</li>
+
+ <li>The size of the user-defined data.</li>
+ </ul>
+ </li>
+
+ <li>An optional <code>init()</code> function. This allows you to do any initialization
+ before the <code>root()</code> function runs, such as initializing variables. This
+ function runs once and is called automatically when the Renderscript starts, before anything
+ else in your Renderscript.</li>
+
+ <li>Any variables, pointers, and structures that you wish to use in your Renderscript code (can
+ be declared in <code>.rsh</code> files if desired)</li>
+</ul>
+
+<p>The following code shows how the <a href=
+"{@docRoot}resources/samples/RenderScript/HelloCompute/src/com/example/android/rs/hellocompute/mono.html">
+mono.rs</a> file is implemented:</p>
+<pre>
+#pragma version(1)
+#pragma rs java_package_name(com.example.android.rs.hellocompute)
+
+//multipliers to convert a RGB colors to black and white
+const static float3 gMonoMult = {0.299f, 0.587f, 0.114f};
+
+void root(const uchar4 *v_in, uchar4 *v_out) {
+ //unpack a color to a float4
+ float4 f4 = rsUnpackColor8888(*v_in);
+ //take the dot product of the color and the multiplier
+ float3 mono = dot(f4.rgb, gMonoMult);
+ //repack the float to a color
+ *v_out = rsPackColorTo8888(mono);
+}
+</pre>
+
+<h3 id="calling">Calling the Renderscript code</h3>
+
+<p>You can call the Renderscript from your Android framework code by
+creating a Renderscript object by instantiating the (<code>ScriptC_<em>script_name</em></code>)
+class. This class contains a method, <code>forEach_root()</code>, that lets you invoke
+<code>rsForEach</code>. You give it the same parameters that you would if you were invoking it
+at the Renderscript runtime level. This technique allows your Android application to offload
+intensive mathematical calculations to Renderscript. See the <a href=
+"{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">HelloCompute</a> sample to see
+how a simple Android application can utilize Renderscript.</p>
+
+<p>To call Renderscript at the Android framework level:</p>
+
+<ol>
+ <li>Allocate memory that is needed by the Renderscript in your Android framework code.
+ You need an input and output {@link android.renderscript.Allocation} for Android 3.2 (API level
+ 13) platform versions and older. The Android 4.0 (API level 14) platform version requires only
+ one or both {@link android.renderscript.Allocation}s.</li>
+
+ <li>Create an instance of the <code>ScriptC_<em>script_name</em></code> class.</li>
+
+ <li>Call <code>forEach_root()</code>, passing in the allocations, the
+ Renderscript, and any optional user-defined data. The output allocation will contain the output
+ of the Renderscript.</li>
+</ol>
+
+<p>The following example, taken from the <a href=
+"{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">HelloCompute</a> sample, processes
+a bitmap and outputs a black and white version of it. The
+<code>createScript()</code> method carries out the steps described previously. This method calls the
+Renderscript, <code>mono.rs</code>, passing in memory allocations that store the bitmap to be processed
+as well as the eventual output bitmap. It then displays the processed bitmap onto the screen:</p>
+<pre>
+package com.example.android.rs.hellocompute;
+
+import android.app.Activity;
+import android.os.Bundle;
+import android.graphics.BitmapFactory;
+import android.graphics.Bitmap;
+import android.renderscript.RenderScript;
+import android.renderscript.Allocation;
+import android.widget.ImageView;
+
+public class HelloCompute extends Activity {
+ private Bitmap mBitmapIn;
+ private Bitmap mBitmapOut;
+
+ private RenderScript mRS;
+ private Allocation mInAllocation;
+ private Allocation mOutAllocation;
+ private ScriptC_mono mScript;
+
+ @Override
+ protected void onCreate(Bundle savedInstanceState) {
+ super.onCreate(savedInstanceState);
+ setContentView(R.layout.main);
+
+ mBitmapIn = loadBitmap(R.drawable.data);
+ mBitmapOut = Bitmap.createBitmap(mBitmapIn.getWidth(), mBitmapIn.getHeight(),
+ mBitmapIn.getConfig());
+
+ ImageView in = (ImageView) findViewById(R.id.displayin);
+ in.setImageBitmap(mBitmapIn);
+
+ ImageView out = (ImageView) findViewById(R.id.displayout);
+ out.setImageBitmap(mBitmapOut);
+
+ createScript();
+ }
+ private void createScript() {
+ mRS = RenderScript.create(this);
+ mInAllocation = Allocation.createFromBitmap(mRS, mBitmapIn,
+ Allocation.MipmapControl.MIPMAP_NONE,
+ Allocation.USAGE_SCRIPT);
+ mOutAllocation = Allocation.createTyped(mRS, mInAllocation.getType());
+ mScript = new ScriptC_mono(mRS, getResources(), R.raw.mono);
+ mScript.forEach_root(mInAllocation, mOutAllocation);
+ mOutAllocation.copyTo(mBitmapOut);
+ }
+
+ private Bitmap loadBitmap(int resource) {
+ final BitmapFactory.Options options = new BitmapFactory.Options();
+ options.inPreferredConfig = Bitmap.Config.ARGB_8888;
+ return BitmapFactory.decodeResource(getResources(), resource, options);
+ }
+}
+</pre>
+
+<p>To call Renderscript from another Renderscript file:</p>
+<ol>
+ <li>Allocate memory that is needed by the Renderscript in your Android framework code.
+ You need an input and output {@link android.renderscript.Allocation} for Android 3.2 (API level
+ 13) platform versions and older. The Android 4.0 (API level 14) platform version requires only
+ one or both {@link android.renderscript.Allocation}s.</li>
+
+ <li>Call <code>rsForEach()</code>, passing in the allocations and any optional user-defined data.
+ The output allocation will contain the output of the Renderscript.</li>
+</ol>
+
+<pre>
+rs_script script;
+rs_allocation in_allocation;
+rs_allocation out_allocation;
+UserData_t data;
+...
+rsForEach(script, in_allocation, out_allocation, &data, sizeof(data));
+</pre>
+</p>
+<p>In this example, assume that the script and memory allocations have already been
+allocated and bound at the Android framework level and that <code>UserData_t</code> is a struct
+declared previously. Passing a pointer to a struct and the size of the struct to <code>rsForEach</code>
+is optional, but useful if your Renderscript requires additional information other than
+the necessary memory allocations.</p>
+
+<h3>Setting floating point precision</h3>
+<p>You can define the floating point precision required by your compute algorithms. This is useful if you
+ require less precision than the IEEE 754-2008 standard (used by default). You can define
+the floating-point precision level of your script with the following pragmas:</p>
+
+<ul>
+ <li><code>#pragma rs_fp_full</code> (default if nothing is specified): For apps that
+ require floating point precision as outlined by the IEEE 754-2008 standard.
+</li>
+ <li><code>#pragma rs_fp_relaxed</code> - For apps that don’t require
+ strict IEEE 754-2008 compliance and can tolerate less precision. This mode enables
+ flush-to-zero for denorms and round-towards-zero.
+</li>
+ <li><code>#pragma rs_fp_imprecise</code> - For apps that don’t have stringent precision requirements. This mode enables
+ everything in <code>rs_fp_relaxed</code> along with the following:
+<ul>
+ <li>Operations resulting in -0.0 can return +0.0 instead.</li>
+ <li>Operations on INF and NAN are undefined.</li>
+</ul>
+</li>
+</ul>
\ No newline at end of file
diff --git a/docs/html/guide/topics/renderscript/index.jd b/docs/html/guide/topics/renderscript/index.jd
new file mode 100644
index 0000000..b6758bc
--- /dev/null
+++ b/docs/html/guide/topics/renderscript/index.jd
@@ -0,0 +1,31 @@
+page.title=Computation
+@jd:body
+
+<p>Renderscript provides a platform-independent computation engine that operates at the native level.
+ Use it to accelerate your apps that require extensive computational horsepower.</p>
+<div class="landing-docs">
+
+ <div>
+ <h3>Blog Articles</h3>
+ <a
+href="http://android-developers.blogspot.com/2012/01/levels-in-renderscript.html">
+ <h4>Levels in Renderscript</h4>
+ <p>For ICS, Renderscript (RS) has been updated with several new features to simplify
+ adding compute acceleration to your application. RS is interesting for compute
+ acceleration when you have large buffers of data on which you need to do significant
+ processing. In this example we will look at applying a levels/saturation operation
+ on a bitmap.</p>
+ </a>
+
+ <a
+href="http://android-developers.blogspot.com/2011/03/renderscript.html">
+ <h4>Renderscript Part 2</h4>
+ <p>In Introducing Renderscript I gave a brief overview of this technology.
+ In this post I’ll look at "compute" in more detail. In Renderscript we use
+ "compute" to mean offloading of data processing from Dalvik code to
+ Renderscript code which may run on the same or different processor(s).</p>
+ </a>
+ </div>
+
+ </div>
+</div>
\ No newline at end of file
diff --git a/docs/html/guide/topics/graphics/renderscript/reference.jd b/docs/html/guide/topics/renderscript/reference.jd
similarity index 91%
rename from docs/html/guide/topics/graphics/renderscript/reference.jd
rename to docs/html/guide/topics/renderscript/reference.jd
index a0a9df2..a9d780a 100644
--- a/docs/html/guide/topics/graphics/renderscript/reference.jd
+++ b/docs/html/guide/topics/renderscript/reference.jd
@@ -1,4 +1,7 @@
page.title=Runtime API Reference
+parent.title=Computation
+parent.link=index.html
+
@jd:body
<script language="JavaScript">