Merge "Update RenderScript docs to include Support Library APIs" into jb-mr2-ub-dev

1 files changed, 82 insertions, 1 deletions

diff --git a/docs/html/guide/topics/renderscript/compute.jd b/docs/html/guide/topics/renderscript/compute.jd
index 607d16e..14a1682 100644
--- a/docs/html/guide/topics/renderscript/compute.jd
+++ b/docs/html/guide/topics/renderscript/compute.jd
@@ -10,6 +10,11 @@ parent.link=index.html
 
     <ol>
       <li><a href="#writing-an-rs-kernel">Writing a RenderScript Kernel</a></li>
+      <li><a href="#access-rs-apis">Accessing RenderScript Java APIs</a>
+        <ol>
+          <li><a href="#ide-setup">Setting Up Your Development Environment</a></li>
+        </ol>
+      </li>
       <li><a href="#using-rs-from-java">Using RenderScript from Java Code</a></li>
     </ol>
 
@@ -144,9 +149,85 @@ different level of floating point precision:</p>
 beneficial on some architectures due to additional optimizations only available with relaxed
 precision (such as SIMD CPU instructions).</p>
 
+
+<h2 id="access-rs-apis">Accessing RenderScript Java APIs</h2>
+
+<p>When developing an Android application that uses RenderScript, you can access its Java API in
+  one of two ways. The APIs are available in the {@link android.renderscript} package
+  on devices running Android 3.0 (API level 11) and higher. These are the original APIs for
+  RenderScript. The APIs are also available as a Support Library in the
+  {@link android.support.v8.renderscript} package, which allow you to use them on devices running
+  Android 2.2 (API level 8) and higher.</p>
+
+<p>We strongly recommend using the Support Library APIs for accessing RenderScript because they
+  include the latest improvements to the RenderScript compute framework and provide a wider range
+  of device compatibility. Using the RenderScript APIs in the Support Library requires specific
+  setup procedures for your development environment, which is described in the next section.</p>
+
+
+<h3 id="ide-setup">Using the RenderScript Support Library APIs</h3>
+
+<p>In order to use the Support Library RenderScript APIs, you must configure your development
+  environment to be able to access them. The following Android SDK tools are required for using
+  these APIs:</p>
+
+<ul>
+  <li>Android SDK Tools revision 22.2 or higher</li>
+  <li>Android SDK Build-tools revision 18.1.0 or higher</li>
+</ul>
+
+<p>You can check and update the installed version of these tools in the
+  <a href="{@docRoot}tools/help/sdk-manager.html">Android SDK Manager</a>.</p>
+
+<p class="note">
+  <strong>Note:</strong> Use of Support Library RenderScript APIs is not currently supported with
+  Android Studio or Gradle-based builds.
+</p>
+
+<p>To use the Support Library RenderScript APIs in Eclipse:</p>
+
+<ol>
+  <li>Make sure you have the required Android SDK version and Build Tools version installed.</li>
+  <li>Open the {@code project.properties} file in the root folder of your application project.</li>
+  <li>Add the following lines to the file:
+<pre>
+renderscript.target=18
+renderscript.support.mode=true
+sdk.buildtools=18.1.0
+</pre>
+  </li>
+  <li>In your application classes that use RenderScript, add an import for the Support Library
+    classes:
+<pre>
+import android.support.v8.renderscript.*;
+</pre>
+  </li>
+</ol>
+
+<p>The {@code project.properties} settings listed above control specific behavior in the Android
+  build process:</p>
+
+<ul>
+  <li>{@code renderscript.target} - Specifies the bytecode version to be generated. We
+    recommend you set this value the highest available API level and set {@code
+    renderscript.support.mode} to {@code true}. Valid values for this setting are any integer value
+    from 11 to the most recently released API level. If your minimum SDK version specified in your
+    application manifest is set to a higher value, this value is ignored and the target value is set
+    to the minimum SDK version.</li>
+  <li>{@code renderscript.support.mode} - Specifies that the generated bytecode should fall
+    back to a compatible version if the device it is running on does not support the target version.
+    </li>
+  <li>{@code sdk.buildtools} - The version of the Android SDK build tools to use. This value
+    should be set to 18.1.0 or higher. If this option is not specified, the highest installed build
+    tools version is used. You should always set this value to ensure the consistency of builds
+    across development machines with different configurations.</li>
+</ul>
+
+
 <h2 id="using-rs-from-java">Using RenderScript from Java Code</h2>
 
-<p>Using RenderScript from Java code relies on the {@link android.renderscript} APIs. Most
+<p>Using RenderScript from Java code relies on the API classes located in the
+{@link android.renderscript} or the {@link android.support.v8.renderscript} package. Most
 applications follow the same basic usage patterns:</p>
 
 <ol>