From 864090eeaa5241f9fcf17420a3d0123c95052b96 Mon Sep 17 00:00:00 2001 From: Robert Ly Date: Sun, 17 Jun 2012 18:22:17 -0700 Subject: docs: remove graphics rs docs and restructure existing docs Change-Id: I8603c827095143327053e8eba855177ec466a948 --- docs/html/guide/guide_toc.cs | 28 +- .../guide/topics/graphics/renderscript/compute.jd | 253 ------- .../guide/topics/graphics/renderscript/index.jd | 804 --------------------- .../topics/graphics/renderscript/reference.jd | 18 - docs/html/guide/topics/renderscript/advanced.jd | 730 +++++++++++++++++++ docs/html/guide/topics/renderscript/compute.jd | 340 +++++++++ docs/html/guide/topics/renderscript/index.jd | 31 + docs/html/guide/topics/renderscript/reference.jd | 21 + 8 files changed, 1136 insertions(+), 1089 deletions(-) delete mode 100644 docs/html/guide/topics/graphics/renderscript/compute.jd delete mode 100644 docs/html/guide/topics/graphics/renderscript/index.jd delete mode 100644 docs/html/guide/topics/graphics/renderscript/reference.jd create mode 100644 docs/html/guide/topics/renderscript/advanced.jd create mode 100644 docs/html/guide/topics/renderscript/compute.jd create mode 100644 docs/html/guide/topics/renderscript/index.jd create mode 100644 docs/html/guide/topics/renderscript/reference.jd (limited to 'docs/html/guide') diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index fee1f35..8e3fea6 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -311,26 +311,26 @@
  • Hardware Acceleration
    • -
  • -
    - Renderscript + +
    • + +
  • +
    + Computation
    -
    • - - - - +
  • Media and Camera 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 - - - -

    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.

    - -

    Compute Renderscripts scale to the amount of -processing cores available on the device. This is enabled through a function named -rsForEach() (or the forEach_root() 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.

    - -

    Creating a Compute Renderscript

    - -

    Implementing a compute Renderscript creating a .rs file that contains -your Renderscript code and calling it at the Android framework level with the -forEach_root() or at the Renderscript runtime level with the -rsForEach() function. The following diagram describes how a typical compute -Renderscript is set up:

    - -

    Figure 1. Compute Renderscript overview

    - -

    The following sections describe how to create a simple compute Renderscript and use it in an -Android application. This example uses the HelloCompute Renderscript -sample that is provided in the SDK as a guide (some code has been modified from its original -form for simplicity).

    - -

    Creating the Renderscript file

    - -

    Your Renderscript code resides in .rs and .rsh files in the -<project_root>/src/ directory. This code contains the compute logic -and declares all necessary variables and pointers. -Every compute .rs file generally contains the following items:

    - -
      -
    • A pragma declaration (#pragma rs java_package_name(package.name)) - that declares the package name of the .java reflection of this Renderscript.
      • - -
    • A pragma declaration (#pragma version(1)) that declares the version of - Renderscript that you are using (1 is the only value for now).
      • - -
    • A root() function that is the main worker function. The root function is - called by the rsForEach function, which allows the Renderscript code to be called and - executed on multiple cores if they are available. The root() function must return - void and accept the following arguments: - -
        -
      • 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.
        • -
      - -

      The following arguments are optional, but both must be supplied if you choose to use - them:

      - -
        -
      • 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.
        • - -
      • The size of the user-defined data.
        • -
      -
      • - -
    • An optional init() function. This allows you to do any initialization - before the root() function runs, such as initializing variables. This - function runs once and is called automatically when the Renderscript starts, before anything - else in your Renderscript.
      • - -
    • Any variables, pointers, and structures that you wish to use in your Renderscript code (can - be declared in .rsh files if desired)
      • -
    - -

    The following code shows how the -mono.rs file is implemented:

    -
    -#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);
-}
-
    - -

    Calling the Renderscript code

    - -

    You can do Renderscript to Renderscript calls with rsForEach in situations -such as when a graphics Renderscript needs to do a lot of computational operations. The Renderscript -Balls sample shows how -this is setup. The balls.rs -graphics Renderscript calls the balls_physics.rs -compute Renderscript to calculate the location of the balls that are rendered to the screen.

    - -

    Another way to use a compute Renderscript is to call it from your Android framework code by -creating a Renderscript object by instantiating the (ScriptC_script_name) -class. This class contains a method, forEach_root(), that lets you invoke -rsForEach. 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 HelloCompute sample to see -how a simple Android application can utilize a compute Renderscript.

    - -

    To call a compute Renderscript at the Android framework level:

    - -
      -
    1. 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.
      2. - -
    2. Create an instance of the ScriptC_script_name class.
      3. - -
    3. Call forEach_root(), passing in the allocations, the - Renderscript, and any optional user-defined data. The output allocation will contain the output - of the compute Renderscript.
      4. -
    - -

    In the following example, taken from the HelloCompute sample, processes -a bitmap and outputs a black and white version of it. The -createScript() method carries out the steps described previously. This method the compute -Renderscript, mono.rs, 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:

    -
    -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);
-  }
-}
-
    - -

    To call a compute Renderscript from another Renderscript file:

    -
      -
    1. 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.
      2. - -
    2. Call rsForEach(), passing in the allocations and any optional user-defined data. - The output allocation will contain the output of the compute Renderscript.
      3. -
    -

    The following example, taken from the Renderscript -Balls sample, demonstrates how to do make a script to script call:

    -
    -rs_script script;
-rs_allocation in_allocation;
-rs_allocation out_allocation;
-UserData_t data;
-...
-rsForEach(script, in_allocation, out_allocation, &data, sizeof(data));
-
    - -

    In this example, assume that the script and memory allocations have already been -allocated and bound at the Android framework level and that UserData_t is a struct -declared previously. Passing a pointer to a struct and the size of the struct to rsForEach -is optional, but useful if your compute Renderscript requires additional information other than -the necessary memory allocations.

    diff --git a/docs/html/guide/topics/graphics/renderscript/index.jd b/docs/html/guide/topics/graphics/renderscript/index.jd deleted file mode 100644 index b2d9f84..0000000 --- a/docs/html/guide/topics/graphics/renderscript/index.jd +++ /dev/null @@ -1,804 +0,0 @@ -page.title=Renderscript -@jd:body - - - -

    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:

    -
      -
    • 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.
      • - -
    • Performance: Renderscript provides similar performance to OpenGL with the NDK and also - provides a high performance compute API that is not offered by OpenGL.
      • - -
    • Usability: Renderscript simplifies development when possible, such as eliminating JNI glue code - and simplifying mesh setup.
      • -
    - -

    The main disadvantages are:

    - -
      -
    • 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.
      • - -
    • 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. -
      • -
    - - -

    For an example of Renderscript in action, install the Renderscript sample applications that - are shipped with the SDK in <sdk_root>/samples/android-11/RenderScript. - 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.

    - -

    Renderscript Overview

    -

    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).

    - -

    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.

    - - -

    Figure 1. Renderscript system overview

    - -

    When using Renderscript, there are three layers of APIs that enable communication between the - Renderscript runtime and Android framework code:

    - -
      -
    • The Renderscript runtime APIs allow you to do the computation or graphics rendering - that is required by your application.
      • - -
    • 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.
      • - -
    • 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.
      • -
    - -

    - -

    Renderscript Runtime Layer

    - -

    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 -amount of cores available on a processor. -

    -

    Note: The standard C functions in the NDK must be - guaranteed to run on a CPU, so Renderscript cannot access these libraries, - because Renderscript is designed to run on different types of processors.

    - -

    You define your Renderscript code in .rs - and .rsh files in the src/ directory of your Android project. The code - is compiled to intermediate bytecode by the - llvm compiler that runs as part of an Android build. When your application - runs on a device, the bytecode is then compiled (just-in-time) to machine code by another - llvm compiler that resides on the device. The machine code is optimized for the - device and also cached, so subsequent uses of the Renderscript enabled application does not - recompile the bytecode.

    - -

    Some key features of the Renderscript runtime libraries include:

    - -
      - -
    • Graphics rendering functions
      • - -
    • Memory allocation request features
      • - -
    • 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.
      • - -
    • Conversion routines for primitive data types and vectors, matrix routines, date and time - routines, and graphics routines.
      • - -
    • Data types and structures to support the Renderscript system such as Vector types for - defining two-, three-, or four-vectors.
      • - -
    • Logging functions
      • -
    - -

    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:

    - -
    #include "rs_graphics.rsh"
    - -

    Reflected Layer

    - -

    The reflected layer is a set of classes that the Android build tools generate to allow access - to the Renderscript runtime from the Android framework. This layer also provides methods -and constructors that allow you to allocate and work with memory for pointers that are defined in -your Renderscript code. The following list describes the major - components that are reflected:

    - -
      -
    • Every .rs file that you create is generated into a class named - project_root/gen/package/name/ScriptC_renderscript_filename of -type {@link android.renderscript.ScriptC}. This file is the .java version of your -.rs file, which you can call from the Android framework. This class contains the -following items reflected from the .rs file: - -
        -
      • Non-static functions
        • - -
      • Non-static, global Renderscript variables. Accessor methods are generated for each - variable, so you can read and write the Renderscript variables from the Android - framework. If a global variable is initialized at the Renderscript runtime layer, those -values are used to initialize the corresponding values in the Android framework layer. If global -variables are marked as const, then a set method is not -generated.

        • - -
      • Global pointers
        • -
      -
      • - -
    • A struct is reflected into its own class named - - project_root/gen/package/name/ScriptField_struct_name, which extends {@link - android.renderscript.Script.FieldBase}. This class represents an array of the - struct, which allows you to allocate memory for one or more instances of this - struct.
      • -
    - - -

    Functions

    -

    Functions are reflected into the script class itself, located in -project_root/gen/package/name/ScriptC_renderscript_filename. For -example, if you declare the following function in your Renderscript code:

    - -
    -void touch(float x, float y, float pressure, int id) {
-    if (id >= 10) {
-        return;
-    }
-
-    touchPos[id].x = x;
-    touchPos[id].y = y;
-    touchPressure[id] = pressure;
-}
-
    - -

    then the following code is generated:

    - -
    -public void invoke_touch(float x, float y, float pressure, int id) {
-    FieldPacker touch_fp = new FieldPacker(16);
-    touch_fp.addF32(x);
-    touch_fp.addF32(y);
-    touch_fp.addF32(pressure);
-    touch_fp.addI32(id);
-    invoke(mExportFuncIdx_touch, touch_fp);
-}
-
    -

    -Functions cannot have a return value, because the Renderscript system is designed to be -asynchronous. When your Android framework code calls into Renderscript, the call is queued and is -executed when possible. This restriction allows the Renderscript system to function without constant -interruption and increases efficiency. If functions were allowed to have return values, the call -would block until the value was returned.

    - -

    -If you want the Renderscript code to send a value back to the Android framework, use the -rsSendToClient() -function. -

    - -

    Variables

    - -

    Variables of supported types are reflected into the script class itself, located in -project_root/gen/package/name/ScriptC_renderscript_filename. A set of accessor -methods are generated for each variable. For example, if you declare the following variable in -your Renderscript code:

    - 
    uint32_t unsignedInteger = 1;
    - -

    then the following code is generated:

    - -
    -private long mExportVar_unsignedInteger;
-public void set_unsignedInteger(long v){
-    mExportVar_unsignedInteger = v;
-    setVar(mExportVarIdx_unsignedInteger, v);
-}
-
-public long get_unsignedInteger(){
-    return mExportVar_unsignedInteger;
-}
-
    - - -

    Structs

    -

    Structs are reflected into their own classes, located in - <project_root>/gen/com/example/renderscript/ScriptField_struct_name. This - class represents an array of the struct and allows you to allocate memory for a - specified number of structs. For example, if you declare the following struct:

    -
    -typedef struct Point {
-    float2 position;
-    float size;
-} Point_t;
-
    - -

    then the following code is generated in ScriptField_Point.java: -

    -package com.example.android.rs.hellocompute;
-
-import android.renderscript.*;
-import android.content.res.Resources;
-
-  /**
-  * @hide
-  */
-public class ScriptField_Point extends android.renderscript.Script.FieldBase {
-
-    static public class Item {
-        public static final int sizeof = 12;
-
-        Float2 position;
-        float size;
-
-        Item() {
-            position = new Float2();
-        }
-    }
-
-    private Item mItemArray[];
-    private FieldPacker mIOBuffer;
-    public static Element createElement(RenderScript rs) {
-        Element.Builder eb = new Element.Builder(rs);
-        eb.add(Element.F32_2(rs), "position");
-        eb.add(Element.F32(rs), "size");
-        return eb.create();
-    }
-
-    public  ScriptField_Point(RenderScript rs, int count) {
-        mItemArray = null;
-        mIOBuffer = null;
-        mElement = createElement(rs);
-        init(rs, count);
-    }
-
-    public  ScriptField_Point(RenderScript rs, int count, int usages) {
-        mItemArray = null;
-        mIOBuffer = null;
-        mElement = createElement(rs);
-        init(rs, count, usages);
-    }
-
-    private void copyToArray(Item i, int index) {
-        if (mIOBuffer == null) mIOBuffer = new FieldPacker(Item.sizeof * getType().getX()/* count
-        */);
-        mIOBuffer.reset(index * Item.sizeof);
-        mIOBuffer.addF32(i.position);
-        mIOBuffer.addF32(i.size);
-    }
-
-    public void set(Item i, int index, boolean copyNow) {
-        if (mItemArray == null) mItemArray = new Item[getType().getX() /* count */];
-        mItemArray[index] = i;
-        if (copyNow)  {
-            copyToArray(i, index);
-            mAllocation.setFromFieldPacker(index, mIOBuffer);
-        }
-    }
-
-    public Item get(int index) {
-        if (mItemArray == null) return null;
-        return mItemArray[index];
-    }
-
-    public void set_position(int index, Float2 v, boolean copyNow) {
-        if (mIOBuffer == null) mIOBuffer = new FieldPacker(Item.sizeof * getType().getX()/* count */);
-        if (mItemArray == null) mItemArray = new Item[getType().getX() /* count */];
-        if (mItemArray[index] == null) mItemArray[index] = new Item();
-        mItemArray[index].position = v;
-        if (copyNow) {
-            mIOBuffer.reset(index * Item.sizeof);
-            mIOBuffer.addF32(v);
-            FieldPacker fp = new FieldPacker(8);
-            fp.addF32(v);
-            mAllocation.setFromFieldPacker(index, 0, fp);
-        }
-    }
-
-    public void set_size(int index, float v, boolean copyNow) {
-        if (mIOBuffer == null) mIOBuffer = new FieldPacker(Item.sizeof * getType().getX()/* count */);
-        if (mItemArray == null) mItemArray = new Item[getType().getX() /* count */];
-        if (mItemArray[index] == null) mItemArray[index] = new Item();
-        mItemArray[index].size = v;
-        if (copyNow)  {
-            mIOBuffer.reset(index * Item.sizeof + 8);
-            mIOBuffer.addF32(v);
-            FieldPacker fp = new FieldPacker(4);
-            fp.addF32(v);
-            mAllocation.setFromFieldPacker(index, 1, fp);
-        }
-    }
-
-    public Float2 get_position(int index) {
-        if (mItemArray == null) return null;
-        return mItemArray[index].position;
-    }
-
-    public float get_size(int index) {
-        if (mItemArray == null) return 0;
-        return mItemArray[index].size;
-    }
-
-    public void copyAll() {
-        for (int ct = 0; ct < mItemArray.length; ct++) copyToArray(mItemArray[ct], ct);
-        mAllocation.setFromFieldPacker(0, mIOBuffer);
-    }
-
-    public void resize(int newSize) {
-        if (mItemArray != null)  {
-            int oldSize = mItemArray.length;
-            int copySize = Math.min(oldSize, newSize);
-            if (newSize == oldSize) return;
-            Item ni[] = new Item[newSize];
-            System.arraycopy(mItemArray, 0, ni, 0, copySize);
-            mItemArray = ni;
-        }
-        mAllocation.resize(newSize);
-        if (mIOBuffer != null) mIOBuffer = new FieldPacker(Item.sizeof * getType().getX()/* count */);
-    }
-}
-
    - -

    The generated code is provided to you as a convenience to allocate memory for structs requested -by the Renderscript runtime and to interact with structs -in memory. Each struct's class defines the following methods and constructors:

    - -
      -
    • Overloaded constructors that allow you to allocate memory. The - ScriptField_struct_name(RenderScript rs, int count) constructor allows - you to define the number of structures that you want to allocate memory for with the - count parameter. The ScriptField_struct_name(RenderScript rs, int - count, int usages) constructor defines an extra parameter, usages, that - lets you specify the memory space of this memory allocation. There are four memory space - possibilities: - -
        -
      • {@link android.renderscript.Allocation#USAGE_SCRIPT}: Allocates in the script memory - space. This is the default memory space if you do not specify a memory space.
        • - -
      • {@link android.renderscript.Allocation#USAGE_GRAPHICS_TEXTURE}: Allocates in the - texture memory space of the GPU.
        • - -
      • {@link android.renderscript.Allocation#USAGE_GRAPHICS_VERTEX}: Allocates in the vertex - memory space of the GPU.
        • - -
      • {@link android.renderscript.Allocation#USAGE_GRAPHICS_CONSTANTS}: Allocates in the - constants memory space of the GPU that is used by the various program objects.
        • -
      - -

      You can specify multiple memory spaces by using the bitwise OR operator. Doing so - notifies the Renderscript runtime that you intend on accessing the data in the - specified memory spaces. The following example allocates memory for a custom data type - in both the script and vertex memory spaces:

      - 
      -        ScriptField_Point touchPoints = new ScriptField_Point(glRenderer, 2,
-        Allocation.USAGE_SCRIPT | Allocation.USAGE_GRAPHICS_VERTEX);
-
      - -

      If you modify the memory in one memory space and want to push the updates to the rest of - the memory spaces, call - rsgAllocationSyncAll() in your Renderscript code to - synchronize the memory.

      -
      • - -
    • A static nested class, Item, allows you to create an instance of the - struct, in the form of an object. This nested class is useful if it makes more sense to work - with the struct in your Android code. When you are done manipulating the object, - you can push the object to the allocated memory by calling set(Item i, int index, - boolean copyNow) and setting the Item to the desired position in -the array. The Renderscript runtime automatically has access to the newly written memory. - -
    • Accessor methods to get and set the values of each field in a struct. Each of these - accessor methods have an index parameter to specify the struct in - the array that you want to read or write to. Each setter method also has a -copyNow parameter that specifies whether or not to immediately sync this memory -to the Renderscript runtime. To sync any memory that has not been synced, call - copyAll().
      • - -
    • The createElement() method creates a description of the struct in memory. This - description is used to allocate memory consisting of one or many elements.
      • - -
    • resize() works much like a realloc() in C, allowing you to -expand previously allocated memory, maintaining the current values that were previously -created.
      • - -
    • copyAll() synchronizes memory that was set on the framework level to the -Renderscript runtime. When you call a set accessor method on a member, there is an optional -copyNow boolean parameter that you can specify. Specifying - true synchronizes the memory when you call the method. If you specify false, - you can call copyAll() once, and it synchronizes memory for all the -properties that are not yet synchronized.
      • -
    - -

    Pointers

    -

    Pointers are reflected into the script class itself, located in -project_root/gen/package/name/ScriptC_renderscript_filename. You -can declare pointers to a struct or any of the supported Renderscript types, but a -struct cannot contain pointers or nested arrays. For example, if you declare the -following pointers to a struct and int32_t

    - -
    -typedef struct Point {
-    float2 position;
-    float size;
-} Point_t;
-
-Point_t *touchPoints;
-int32_t *intPointer;
-
    -

    then the following code is generated in:

    - -
    -private ScriptField_Point mExportVar_touchPoints;
-public void bind_touchPoints(ScriptField_Point v) {
-    mExportVar_touchPoints = v;
-    if (v == null) bindAllocation(null, mExportVarIdx_touchPoints);
-    else bindAllocation(v.getAllocation(), mExportVarIdx_touchPoints);
-}
-
-public ScriptField_Point get_touchPoints() {
-    return mExportVar_touchPoints;
-}
-
-private Allocation mExportVar_intPointer;
-public void bind_intPointer(Allocation v) {
-    mExportVar_intPointer = v;
-    if (v == null) bindAllocation(null, mExportVarIdx_intPointer);
-    else bindAllocation(v, mExportVarIdx_intPointer);
-}
-
-public Allocation get_intPointer() {
-    return mExportVar_intPointer;
-}
-
    - -

    A get method and a special method named bind_pointer_name -(instead of a set() method) is generated. This method allows you to bind the memory -that is allocated in the Android VM to the Renderscript runtime (you cannot allocate -memory in your .rs file). For more information, see Working -with Allocated Memory. -

    - - -

    Memory Allocation APIs

    - -

    Applications that use Renderscript still run in the Android VM. The actual Renderscript code, however, runs natively and - needs access to the memory allocated in the Android VM. To accomplish this, you must - attach the memory that is allocated in the VM to the Renderscript runtime. This -process, called binding, allows the Renderscript runtime to seamlessly work with memory that it -requests but cannot explicitly allocate. The end result is essentially the same as if you had -called malloc in C. The added benefit is that the Android VM can carry out garbage collection as well as -share memory with the Renderscript runtime layer. Binding is only necessary for dynamically allocated memory. Statically -allocated memory is automatically created for your Renderscript code at compile time. See Figure 1 -for more information on how memory allocation occurs. -

    - -

    To support this memory allocation system, there are a set of APIs that allow the Android VM to -allocate memory and offer similar functionality to a malloc call. These classes -essentially describe how memory should be allocated and also carry out the allocation. To better -understand how these classes work, it is useful to think of them in relation to a simple -malloc call that can look like this:

    - - 
    array = (int *)malloc(sizeof(int)*10);
    - -

    The malloc call can be broken up into two parts: the size of the memory being allocated (sizeof(int)), - along with how many units of that memory should be allocated (10). The Android framework provides classes for these two parts as - well as a class to represent malloc itself.

    - -

    The {@link android.renderscript.Element} class represents the (sizeof(int)) portion - of the malloc call and encapsulates one cell of a memory allocation, such as a single - float value or a struct. The {@link android.renderscript.Type} class encapsulates the {@link android.renderscript.Element} - and the amount of elements to allocate (10 in our example). You can think of a {@link android.renderscript.Type} as - an array of {@link android.renderscript.Element}s. The {@link android.renderscript.Allocation} class does the actual - memory allocation based on a given {@link android.renderscript.Type} and represents the actual allocated memory.

    - -

    In most situations, you do not need to call these memory allocation APIs directly. The reflected layer - classes generate code to use these APIs automatically and all you need to do to allocate memory is call a - constructor that is declared in one of the reflected layer classes and then bind - the resulting memory {@link android.renderscript.Allocation} to the Renderscript. - There are some situations where you would want to use these classes directly to allocate memory on your - own, such as loading a bitmap from a resource or when you want to allocate memory for pointers to - primitive types. You can see how to do this in the - Allocating and binding memory to the Renderscript section. - The following table describes the three memory management classes in more detail:

    - - - - - - - - - - - - - - - - - - - - - - - - - -
    Android Object TypeDescription
    {@link android.renderscript.Element} -

    An element describes one cell of a memory allocation and can have two forms: basic or - complex.

    - -

    A basic element contains a single component of data of any valid Renderscript data type. - Examples of basic element data types include a single float value, a float4 vector, or a - single RGB-565 color.

    - -

    Complex elements contain a list of basic elements and are created from - structs that you declare in your Renderscript code. For instance an allocation - can contain multiple structs arranged in order in memory. Each struct is considered as its - own element, rather than each data type within that struct.

    -
    {@link android.renderscript.Type} -

    A type is a memory allocation template and consists of an element and one or more - dimensions. It describes the layout of the memory (basically an array of {@link - android.renderscript.Element}s) but does not allocate the memory for the data that it - describes.

    - -

    A type consists of five dimensions: X, Y, Z, LOD (level of detail), and Faces (of a cube - map). You can assign the X,Y,Z dimensions to any positive integer value within the - constraints of available memory. A single dimension allocation has an X dimension of - greater than zero while the Y and Z dimensions are zero to indicate not present. For - example, an allocation of x=10, y=1 is considered two dimensional and x=10, y=0 is - considered one dimensional. The LOD and Faces dimensions are booleans to indicate present - or not present.

    -
    {@link android.renderscript.Allocation} -

    An allocation provides the memory for applications based on a description of the memory - that is represented by a {@link android.renderscript.Type}. Allocated memory can exist in - many memory spaces concurrently. If memory is modified in one space, you must explicitly - synchronize the memory, so that it is updated in all the other spaces in which it exists. -

    - -

    Allocation data is uploaded in one of two primary ways: type checked and type unchecked. - For simple arrays there are copyFrom() functions that take an array from the - Android system and copy it to the native layer memory store. The unchecked variants allow - the Android system to copy over arrays of structures because it does not support - structures. For example, if there is an allocation that is an array of n floats, the data - contained in a float[n] array or a byte[n*4] array can be copied.

    -
    - -

    Working with Memory

    - -

    Non-static, global variables that you declare in your Renderscript are allocated memory at compile time. -You can work with these variables directly in your Renderscript code without having to allocate -memory for them at the Android framework level. The Android framework layer also has access to these variables -with the provided accessor methods that are generated in the reflected layer classes. If these variables are -initialized at the Renderscript runtime layer, those values are used to initialize the corresponding -values in the Android framework layer. If global variables are marked as const, then a set method is -not generated.

    - - -

    Note: If you are using certain Renderscript structures that contain pointers, such as -rs_program_fragment and rs_allocation, you have to obtain an object of the -corresponding Android framework class first and then call the set method for that -structure to bind the memory to the Renderscript runtime. You cannot directly manipulate these structures -at the Renderscript runtime layer. This restriction is not applicable to user-defined structures -that contain pointers, because they cannot be exported to a reflected layer class -in the first place. A compiler error is generated if you try to declare a non-static, global -struct that contains a pointer. -

    - -

    Renderscript also has support for pointers, but you must explicitly allocate the memory in your -Android framework code. When you declare a global pointer in your .rs file, you -allocate memory through the appropriate reflected layer class and bind that memory to the native -Renderscript layer. You can interact with this memory from the Android framework layer as well as -the Renderscript layer, which offers you the flexibility to modify variables in the most -appropriate layer.

    - - - -

    Allocating and binding dynamic memory to the Renderscript

    - -

    To allocate dynamic memory, you need to call the constructor of a - {@link android.renderscript.Script.FieldBase} class, which is the most common way. An alternative is to create an - {@link android.renderscript.Allocation} manually, which is required for things such as primitive type pointers. You should - use a {@link android.renderscript.Script.FieldBase} class constructor whenever available for simplicity. - After obtaining a memory allocation, call the reflected bind method of the pointer to bind the allocated memory to the - Renderscript runtime.

    -

    The example below allocates memory for both a primitive type pointer, - intPointer, and a pointer to a struct, touchPoints. It also binds the memory to the - Renderscript:

    - 
    -private RenderScriptGL glRenderer;
-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;
-    resources = res;
-
-    //allocate memory for the struct pointer, calling the constructor
-    ScriptField_Point touchPoints = new ScriptField_Point(glRenderer, 2);
-
-    //Create an element manually and allocate memory for the int pointer
-    intPointer = Allocation.createSized(glRenderer, Element.I32(glRenderer), 2);
-
-    //create an instance of the Renderscript, pointing it to the bytecode resource
-    mScript = new ScriptC_example(glRenderer, resources, R.raw.example);
-
-    //bind the struct and int pointers to the Renderscript
-    mScript.bind_touchPoints(touchPoints);
-    script.bind_intPointer(intPointer);
-
-   ...
-}
-
    - -

    Reading and writing to memory

    -

    You can read and write to statically and dynamically allocated memory both at the Renderscript runtime - and Android framework layer.

    - -

    Statically allocated memory comes with a one-way communication restriction -at the Renderscript runtime level. When Renderscript code changes the value of a variable, it is not -communicated back to the Android framework layer for efficiency purposes. The last value -that is set from the Android framework is always returned during a call to a get -method. However, when Android framework code modifies a variable, that change can be communicated to -the Renderscript runtime automatically or synchronized at a later time. If you need to send data -from the Renderscript runtime to the Android framework layer, you can use the -rsSendToClient() function -to overcome this limitation. -

    -

    When working with dynamically allocated memory, any changes at the Renderscript runtime layer are propagated -back to the Android framework layer if you modified the memory allocation using its associated pointer. -Modifying an object at the Android framework layer immediately propagates that change back to the Renderscript -runtime layer.

    - -

    Reading and writing to global variables

    - -

    Reading and writing to global variables is a straightforward process. You can use the accessor methods - at the Android framework level or set them directly in the Renderscript code. Keep in mind that any - changes that you make in your Renderscript code are not propagated back to the Android framework layer.

    - -

    For example, given the following struct declared in a file named rsfile.rs:

    -
    -typedef struct Point {
-    int x;
-    int y;
-} Point_t;
-
-Point_t point;
-
-
    -

    You can assign values to the struct like this directly in rsfile.rs. These values are not -propagated back to the Android framework level:

    -
    -point.x = 1;
-point.y = 1;
-
    - -

    You can assign values to the struct at the Android framework layer like this. These values are -propagated back to the Renderscript runtime level:

    -
    -ScriptC_rsfile mScript;
-
-...
-
-Item i = new ScriptField_Point.Item();
-i.x = 1;
-i.y = 1;
-mScript.set_point(i);
-
    - -

    You can read the values in your Renderscript code like this:

    - -
    -rsDebug("Printing out a Point", point.x, point.y);
-
    - -

    You can read the values in the Android framework layer with the following code. Keep in mind that this -code only returns a value if one was set at the Android framework level. You will get a null pointer -exception if you only set the value at the Renderscript runtime level:

    - -
    -Log.i("TAGNAME", "Printing out a Point: " + mScript.get_point().x + " " + mScript.get_point().y);
-System.out.println(point.get_x() + " " + point.get_y());
-
    - -

    Reading and writing global pointers

    - -

    Assuming that memory has been allocated in the Android framework level and bound to the Renderscript runtime, -you can read and write memory from the Android framework level by using the get and set methods for that pointer. -In the Renderscript runtime layer, you can read and write to memory with pointers as normal and the changes are propagated -back to the Android framework layer, unlike with statically allocated memory.

    - -

    For example, given the following pointer to a struct in a file named rsfile.rs:

    -
    -typedef struct Point {
-    int x;
-    int y;
-} Point_t;
-
-Point_t *point;
-
    - -

    Assuming you already allocated memory at the Android framework layer, you can access values in -the struct as normal. Any changes you make to the struct via its pointer variable -are automatically available to the Android framework layer:

    - -
    -point[index].x = 1;
-point[index].y = 1;
-
    - -

    You can read and write values to the pointer at the Android framework layer as well: -

    -ScriptField_Point p = new ScriptField_Point(mRS, 1);
-    Item i = new ScriptField_Point.Item();
-    i.x=100;
-    i.y = 100;
-    p.set(i, 0, true);
-    mScript.bind_point(p);
-
-    points.get_x(0);            //read x and y from index 0
-    points.get_x(0);
-
    - -

    Once memory is already bound, you do not have to rebind the memory to the Renderscript -runtime every time you make a change to a value.

    diff --git a/docs/html/guide/topics/graphics/renderscript/reference.jd b/docs/html/guide/topics/graphics/renderscript/reference.jd deleted file mode 100644 index a0a9df2..0000000 --- a/docs/html/guide/topics/graphics/renderscript/reference.jd +++ /dev/null @@ -1,18 +0,0 @@ -page.title=Runtime API Reference -@jd:body - - - - - diff --git a/docs/html/guide/topics/renderscript/advanced.jd b/docs/html/guide/topics/renderscript/advanced.jd new file mode 100644 index 0000000..58f5e1f --- /dev/null +++ b/docs/html/guide/topics/renderscript/advanced.jd @@ -0,0 +1,730 @@ +page.title=Advanced Renderscript +parent.title=Computation +parent.link=index.html + +@jd:body + + + +

    + +

    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.

    + +

    Renderscript Runtime Layer

    + +

    Your Renderscript code is compiled and + executed in a compact and well-defined runtime layer. The Renderscript runtime APIs offer support for +intensive computation that is portable and automatically scalable to the +amount of cores available on a processor. +

    +

    Note: The standard C functions in the NDK must be + guaranteed to run on a CPU, so Renderscript cannot access these libraries, + because Renderscript is designed to run on different types of processors.

    + +

    You define your Renderscript code in .rs + and .rsh files in the src/ directory of your Android project. The code + is compiled to intermediate bytecode by the + llvm compiler that runs as part of an Android build. When your application + runs on a device, the bytecode is then compiled (just-in-time) to machine code by another + llvm compiler that resides on the device. The machine code is optimized for the + device and also cached, so subsequent uses of the Renderscript enabled application does not + recompile the bytecode.

    + +

    Some key features of the Renderscript runtime libraries include:

    + +
      + +
    • Memory allocation request features
      • + +
    • 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.
      • + +
    • Conversion routines for primitive data types and vectors, matrix routines, and date and time + routines
      • + +
    • Data types and structures to support the Renderscript system such as Vector types for + defining two-, three-, or four-vectors.
      • + +
    • Logging functions
      • +
    + +

    See the Renderscript runtime API reference for more information on the available functions. + +

    Reflected Layer

    + +

    The reflected layer is a set of classes that the Android build tools generate to allow access + to the Renderscript runtime from the Android framework. This layer also provides methods +and constructors that allow you to allocate and work with memory for pointers that are defined in +your Renderscript code. The following list describes the major + components that are reflected:

    + +
      +
    • Every .rs file that you create is generated into a class named + project_root/gen/package/name/ScriptC_renderscript_filename of +type {@link android.renderscript.ScriptC}. This file is the .java version of your +.rs file, which you can call from the Android framework. This class contains the +following items reflected from the .rs file: + +
        +
      • Non-static functions
        • + +
      • Non-static, global Renderscript variables. Accessor methods are generated for each + variable, so you can read and write the Renderscript variables from the Android + framework. If a global variable is initialized at the Renderscript runtime layer, those +values are used to initialize the corresponding values in the Android framework layer. If global +variables are marked as const, then a set method is not +generated.

        • + +
      • Global pointers
        • +
      +
      • + +
    • A struct is reflected into its own class named + + project_root/gen/package/name/ScriptField_struct_name, which extends {@link + android.renderscript.Script.FieldBase}. This class represents an array of the + struct, which allows you to allocate memory for one or more instances of this + struct.
      • +
    + + +

    Functions

    +

    Functions are reflected into the script class itself, located in +project_root/gen/package/name/ScriptC_renderscript_filename. For +example, if you declare the following function in your Renderscript code:

    + +
    +void touch(float x, float y, float pressure, int id) {
+    if (id >= 10) {
+        return;
+    }
+
+    touchPos[id].x = x;
+    touchPos[id].y = y;
+    touchPressure[id] = pressure;
+}
+
    + +

    then the following code is generated:

    + +
    +public void invoke_touch(float x, float y, float pressure, int id) {
+    FieldPacker touch_fp = new FieldPacker(16);
+    touch_fp.addF32(x);
+    touch_fp.addF32(y);
+    touch_fp.addF32(pressure);
+    touch_fp.addI32(id);
+    invoke(mExportFuncIdx_touch, touch_fp);
+}
+
    +

    +Functions cannot have a return value, because the Renderscript system is designed to be +asynchronous. When your Android framework code calls into Renderscript, the call is queued and is +executed when possible. This restriction allows the Renderscript system to function without constant +interruption and increases efficiency. If functions were allowed to have return values, the call +would block until the value was returned.

    + +

    +If you want the Renderscript code to send a value back to the Android framework, use the +rsSendToClient() +function. +

    + +

    Variables

    + +

    Variables of supported types are reflected into the script class itself, located in +project_root/gen/package/name/ScriptC_renderscript_filename. A set of accessor +methods are generated for each variable. For example, if you declare the following variable in +your Renderscript code:

    + 
    uint32_t unsignedInteger = 1;
    + +

    then the following code is generated:

    + +
    +private long mExportVar_unsignedInteger;
+public void set_unsignedInteger(long v){
+    mExportVar_unsignedInteger = v;
+    setVar(mExportVarIdx_unsignedInteger, v);
+}
+
+public long get_unsignedInteger(){
+    return mExportVar_unsignedInteger;
+}
+
    + + +

    Structs

    +

    Structs are reflected into their own classes, located in + <project_root>/gen/com/example/renderscript/ScriptField_struct_name. This + class represents an array of the struct and allows you to allocate memory for a + specified number of structs. For example, if you declare the following struct:

    +
    +typedef struct Point {
+    float2 position;
+    float size;
+} Point_t;
+
    + +

    then the following code is generated in ScriptField_Point.java: +

    +package com.example.android.rs.hellocompute;
+
+import android.renderscript.*;
+import android.content.res.Resources;
+
+  /**
+  * @hide
+  */
+public class ScriptField_Point extends android.renderscript.Script.FieldBase {
+
+    static public class Item {
+        public static final int sizeof = 12;
+
+        Float2 position;
+        float size;
+
+        Item() {
+            position = new Float2();
+        }
+    }
+
+    private Item mItemArray[];
+    private FieldPacker mIOBuffer;
+    public static Element createElement(RenderScript rs) {
+        Element.Builder eb = new Element.Builder(rs);
+        eb.add(Element.F32_2(rs), "position");
+        eb.add(Element.F32(rs), "size");
+        return eb.create();
+    }
+
+    public  ScriptField_Point(RenderScript rs, int count) {
+        mItemArray = null;
+        mIOBuffer = null;
+        mElement = createElement(rs);
+        init(rs, count);
+    }
+
+    public  ScriptField_Point(RenderScript rs, int count, int usages) {
+        mItemArray = null;
+        mIOBuffer = null;
+        mElement = createElement(rs);
+        init(rs, count, usages);
+    }
+
+    private void copyToArray(Item i, int index) {
+        if (mIOBuffer == null) mIOBuffer = new FieldPacker(Item.sizeof * getType().getX()/* count
+        */);
+        mIOBuffer.reset(index * Item.sizeof);
+        mIOBuffer.addF32(i.position);
+        mIOBuffer.addF32(i.size);
+    }
+
+    public void set(Item i, int index, boolean copyNow) {
+        if (mItemArray == null) mItemArray = new Item[getType().getX() /* count */];
+        mItemArray[index] = i;
+        if (copyNow)  {
+            copyToArray(i, index);
+            mAllocation.setFromFieldPacker(index, mIOBuffer);
+        }
+    }
+
+    public Item get(int index) {
+        if (mItemArray == null) return null;
+        return mItemArray[index];
+    }
+
+    public void set_position(int index, Float2 v, boolean copyNow) {
+        if (mIOBuffer == null) mIOBuffer = new FieldPacker(Item.sizeof * getType().getX()/* count */);
+        if (mItemArray == null) mItemArray = new Item[getType().getX() /* count */];
+        if (mItemArray[index] == null) mItemArray[index] = new Item();
+        mItemArray[index].position = v;
+        if (copyNow) {
+            mIOBuffer.reset(index * Item.sizeof);
+            mIOBuffer.addF32(v);
+            FieldPacker fp = new FieldPacker(8);
+            fp.addF32(v);
+            mAllocation.setFromFieldPacker(index, 0, fp);
+        }
+    }
+
+    public void set_size(int index, float v, boolean copyNow) {
+        if (mIOBuffer == null) mIOBuffer = new FieldPacker(Item.sizeof * getType().getX()/* count */);
+        if (mItemArray == null) mItemArray = new Item[getType().getX() /* count */];
+        if (mItemArray[index] == null) mItemArray[index] = new Item();
+        mItemArray[index].size = v;
+        if (copyNow)  {
+            mIOBuffer.reset(index * Item.sizeof + 8);
+            mIOBuffer.addF32(v);
+            FieldPacker fp = new FieldPacker(4);
+            fp.addF32(v);
+            mAllocation.setFromFieldPacker(index, 1, fp);
+        }
+    }
+
+    public Float2 get_position(int index) {
+        if (mItemArray == null) return null;
+        return mItemArray[index].position;
+    }
+
+    public float get_size(int index) {
+        if (mItemArray == null) return 0;
+        return mItemArray[index].size;
+    }
+
+    public void copyAll() {
+        for (int ct = 0; ct < mItemArray.length; ct++) copyToArray(mItemArray[ct], ct);
+        mAllocation.setFromFieldPacker(0, mIOBuffer);
+    }
+
+    public void resize(int newSize) {
+        if (mItemArray != null)  {
+            int oldSize = mItemArray.length;
+            int copySize = Math.min(oldSize, newSize);
+            if (newSize == oldSize) return;
+            Item ni[] = new Item[newSize];
+            System.arraycopy(mItemArray, 0, ni, 0, copySize);
+            mItemArray = ni;
+        }
+        mAllocation.resize(newSize);
+        if (mIOBuffer != null) mIOBuffer = new FieldPacker(Item.sizeof * getType().getX()/* count */);
+    }
+}
+
    + +

    The generated code is provided to you as a convenience to allocate memory for structs requested +by the Renderscript runtime and to interact with structs +in memory. Each struct's class defines the following methods and constructors:

    + +
      +
    • Overloaded constructors that allow you to allocate memory. The + ScriptField_struct_name(RenderScript rs, int count) constructor allows + you to define the number of structures that you want to allocate memory for with the + count parameter. The ScriptField_struct_name(RenderScript rs, int + count, int usages) constructor defines an extra parameter, usages, that + lets you specify the memory space of this memory allocation. There are four memory space + possibilities: + +
        +
      • {@link android.renderscript.Allocation#USAGE_SCRIPT}: Allocates in the script memory + space. This is the default memory space if you do not specify a memory space.
        • + +
      • {@link android.renderscript.Allocation#USAGE_GRAPHICS_TEXTURE}: Allocates in the + texture memory space of the GPU.
        • + +
      • {@link android.renderscript.Allocation#USAGE_GRAPHICS_VERTEX}: Allocates in the vertex + memory space of the GPU.
        • + +
      • {@link android.renderscript.Allocation#USAGE_GRAPHICS_CONSTANTS}: Allocates in the + constants memory space of the GPU that is used by the various program objects.
        • +
      + +

      You can specify multiple memory spaces by using the bitwise OR operator. Doing so + notifies the Renderscript runtime that you intend on accessing the data in the + specified memory spaces. The following example allocates memory for a custom data type + in both the script and vertex memory spaces:

      + 
      +        ScriptField_Point touchPoints = new ScriptField_Point(myRenderscript, 2,
+        Allocation.USAGE_SCRIPT | Allocation.USAGE_GRAPHICS_VERTEX);
+
      +
      • + +
    • A static nested class, Item, allows you to create an instance of the + struct, in the form of an object. This nested class is useful if it makes more sense to work + with the struct in your Android code. When you are done manipulating the object, + you can push the object to the allocated memory by calling set(Item i, int index, + boolean copyNow) and setting the Item to the desired position in +the array. The Renderscript runtime automatically has access to the newly written memory. + +
    • Accessor methods to get and set the values of each field in a struct. Each of these + accessor methods have an index parameter to specify the struct in + the array that you want to read or write to. Each setter method also has a +copyNow parameter that specifies whether or not to immediately sync this memory +to the Renderscript runtime. To sync any memory that has not been synced, call + copyAll().
      • + +
    • The createElement() method creates a description of the struct in memory. This + description is used to allocate memory consisting of one or many elements.
      • + +
    • resize() works much like a realloc() in C, allowing you to +expand previously allocated memory, maintaining the current values that were previously +created.
      • + +
    • copyAll() synchronizes memory that was set on the framework level to the +Renderscript runtime. When you call a set accessor method on a member, there is an optional +copyNow boolean parameter that you can specify. Specifying + true synchronizes the memory when you call the method. If you specify false, + you can call copyAll() once, and it synchronizes memory for all the +properties that are not yet synchronized.
      • +
    + +

    Pointers

    +

    Pointers are reflected into the script class itself, located in +project_root/gen/package/name/ScriptC_renderscript_filename. You +can declare pointers to a struct or any of the supported Renderscript types, but a +struct cannot contain pointers or nested arrays. For example, if you declare the +following pointers to a struct and int32_t

    + +
    +typedef struct Point {
+    float2 position;
+    float size;
+} Point_t;
+
+Point_t *touchPoints;
+int32_t *intPointer;
+
    +

    then the following code is generated in:

    + +
    +private ScriptField_Point mExportVar_touchPoints;
+public void bind_touchPoints(ScriptField_Point v) {
+    mExportVar_touchPoints = v;
+    if (v == null) bindAllocation(null, mExportVarIdx_touchPoints);
+    else bindAllocation(v.getAllocation(), mExportVarIdx_touchPoints);
+}
+
+public ScriptField_Point get_touchPoints() {
+    return mExportVar_touchPoints;
+}
+
+private Allocation mExportVar_intPointer;
+public void bind_intPointer(Allocation v) {
+    mExportVar_intPointer = v;
+    if (v == null) bindAllocation(null, mExportVarIdx_intPointer);
+    else bindAllocation(v, mExportVarIdx_intPointer);
+}
+
+public Allocation get_intPointer() {
+    return mExportVar_intPointer;
+}
+
    + +

    A get method and a special method named bind_pointer_name +(instead of a set() method) is generated. This method allows you to bind the memory +that is allocated in the Android VM to the Renderscript runtime (you cannot allocate +memory in your .rs file). For more information, see Working +with Allocated Memory. +

    + + +

    Memory Allocation APIs

    + +

    Applications that use Renderscript still run in the Android VM. The actual Renderscript code, however, runs natively and + needs access to the memory allocated in the Android VM. To accomplish this, you must + attach the memory that is allocated in the VM to the Renderscript runtime. This +process, called binding, allows the Renderscript runtime to seamlessly work with memory that it +requests but cannot explicitly allocate. The end result is essentially the same as if you had +called malloc in C. The added benefit is that the Android VM can carry out garbage collection as well as +share memory with the Renderscript runtime layer. Binding is only necessary for dynamically allocated memory. Statically +allocated memory is automatically created for your Renderscript code at compile time. See Figure 1 +for more information on how memory allocation occurs. +

    + +

    To support this memory allocation system, there are a set of APIs that allow the Android VM to +allocate memory and offer similar functionality to a malloc call. These classes +essentially describe how memory should be allocated and also carry out the allocation. To better +understand how these classes work, it is useful to think of them in relation to a simple +malloc call that can look like this:

    + + 
    array = (int *)malloc(sizeof(int)*10);
    + +

    The malloc call can be broken up into two parts: the size of the memory being allocated (sizeof(int)), + along with how many units of that memory should be allocated (10). The Android framework provides classes for these two parts as + well as a class to represent malloc itself.

    + +

    The {@link android.renderscript.Element} class represents the (sizeof(int)) portion + of the malloc call and encapsulates one cell of a memory allocation, such as a single + float value or a struct. The {@link android.renderscript.Type} class encapsulates the {@link android.renderscript.Element} + and the amount of elements to allocate (10 in our example). You can think of a {@link android.renderscript.Type} as + an array of {@link android.renderscript.Element}s. The {@link android.renderscript.Allocation} class does the actual + memory allocation based on a given {@link android.renderscript.Type} and represents the actual allocated memory.

    + +

    In most situations, you do not need to call these memory allocation APIs directly. The reflected layer + classes generate code to use these APIs automatically and all you need to do to allocate memory is call a + constructor that is declared in one of the reflected layer classes and then bind + the resulting memory {@link android.renderscript.Allocation} to the Renderscript. + There are some situations where you would want to use these classes directly to allocate memory on your + own, such as loading a bitmap from a resource or when you want to allocate memory for pointers to + primitive types. You can see how to do this in the + Allocating and binding memory to the Renderscript section. + The following table describes the three memory management classes in more detail:

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    Android Object TypeDescription
    {@link android.renderscript.Element} +

    An element describes one cell of a memory allocation and can have two forms: basic or + complex.

    + +

    A basic element contains a single component of data of any valid Renderscript data type. + Examples of basic element data types include a single float value, a float4 vector, or a + single RGB-565 color.

    + +

    Complex elements contain a list of basic elements and are created from + structs that you declare in your Renderscript code. For instance an allocation + can contain multiple structs arranged in order in memory. Each struct is considered as its + own element, rather than each data type within that struct.

    +
    {@link android.renderscript.Type} +

    A type is a memory allocation template and consists of an element and one or more + dimensions. It describes the layout of the memory (basically an array of {@link + android.renderscript.Element}s) but does not allocate the memory for the data that it + describes.

    + +

    A type consists of five dimensions: X, Y, Z, LOD (level of detail), and Faces (of a cube + map). You can assign the X,Y,Z dimensions to any positive integer value within the + constraints of available memory. A single dimension allocation has an X dimension of + greater than zero while the Y and Z dimensions are zero to indicate not present. For + example, an allocation of x=10, y=1 is considered two dimensional and x=10, y=0 is + considered one dimensional. The LOD and Faces dimensions are booleans to indicate present + or not present.

    +
    {@link android.renderscript.Allocation} +

    An allocation provides the memory for applications based on a description of the memory + that is represented by a {@link android.renderscript.Type}. Allocated memory can exist in + many memory spaces concurrently. If memory is modified in one space, you must explicitly + synchronize the memory, so that it is updated in all the other spaces in which it exists. +

    + +

    Allocation data is uploaded in one of two primary ways: type checked and type unchecked. + For simple arrays there are copyFrom() functions that take an array from the + Android system and copy it to the native layer memory store. The unchecked variants allow + the Android system to copy over arrays of structures because it does not support + structures. For example, if there is an allocation that is an array of n floats, the data + contained in a float[n] array or a byte[n*4] array can be copied.

    +
    + +

    Working with Memory

    + +

    Non-static, global variables that you declare in your Renderscript are allocated memory at compile time. +You can work with these variables directly in your Renderscript code without having to allocate +memory for them at the Android framework level. The Android framework layer also has access to these variables +with the provided accessor methods that are generated in the reflected layer classes. If these variables are +initialized at the Renderscript runtime layer, those values are used to initialize the corresponding +values in the Android framework layer. If global variables are marked as const, then a set method is +not generated.

    + + +

    Note: If you are using certain Renderscript structures that contain pointers, such as +rs_program_fragment and rs_allocation, you have to obtain an object of the +corresponding Android framework class first and then call the set method for that +structure to bind the memory to the Renderscript runtime. You cannot directly manipulate these structures +at the Renderscript runtime layer. This restriction is not applicable to user-defined structures +that contain pointers, because they cannot be exported to a reflected layer class +in the first place. A compiler error is generated if you try to declare a non-static, global +struct that contains a pointer. +

    + +

    Renderscript also has support for pointers, but you must explicitly allocate the memory in your +Android framework code. When you declare a global pointer in your .rs file, you +allocate memory through the appropriate reflected layer class and bind that memory to the native +Renderscript layer. You can interact with this memory from the Android framework layer as well as +the Renderscript layer, which offers you the flexibility to modify variables in the most +appropriate layer.

    + + + +

    Allocating and binding dynamic memory to the Renderscript

    + +

    To allocate dynamic memory, you need to call the constructor of a + {@link android.renderscript.Script.FieldBase} class, which is the most common way. An alternative is to create an + {@link android.renderscript.Allocation} manually, which is required for things such as primitive type pointers. You should + use a {@link android.renderscript.Script.FieldBase} class constructor whenever available for simplicity. + After obtaining a memory allocation, call the reflected bind method of the pointer to bind the allocated memory to the + Renderscript runtime.

    +

    The example below allocates memory for both a primitive type pointer, + intPointer, and a pointer to a struct, touchPoints. It also binds the memory to the + Renderscript:

    + 
    +private RenderScript myRenderscript;
+private ScriptC_example script;
+private Resources resources;
+
+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(myRenderscript, 2);
+
+    //Create an element manually and allocate memory for the int pointer
+    intPointer = Allocation.createSized(myRenderscript, Element.I32(myRenderscript), 2);
+
+    //create an instance of the Renderscript, pointing it to the bytecode resource
+    mScript = new ScriptC_example(myRenderscript, resources, R.raw.example);
+
+    //bind the struct and int pointers to the Renderscript
+    mScript.bind_touchPoints(touchPoints);
+    script.bind_intPointer(intPointer);
+
+   ...
+}
+
    + +

    Reading and writing to memory

    +

    You can read and write to statically and dynamically allocated memory both at the Renderscript runtime + and Android framework layer.

    + +

    Statically allocated memory comes with a one-way communication restriction +at the Renderscript runtime level. When Renderscript code changes the value of a variable, it is not +communicated back to the Android framework layer for efficiency purposes. The last value +that is set from the Android framework is always returned during a call to a get +method. However, when Android framework code modifies a variable, that change can be communicated to +the Renderscript runtime automatically or synchronized at a later time. If you need to send data +from the Renderscript runtime to the Android framework layer, you can use the +rsSendToClient() function +to overcome this limitation. +

    +

    When working with dynamically allocated memory, any changes at the Renderscript runtime layer are propagated +back to the Android framework layer if you modified the memory allocation using its associated pointer. +Modifying an object at the Android framework layer immediately propagates that change back to the Renderscript +runtime layer.

    + +

    Reading and writing to global variables

    + +

    Reading and writing to global variables is a straightforward process. You can use the accessor methods + at the Android framework level or set them directly in the Renderscript code. Keep in mind that any + changes that you make in your Renderscript code are not propagated back to the Android framework layer.

    + +

    For example, given the following struct declared in a file named rsfile.rs:

    +
    +typedef struct Point {
+    int x;
+    int y;
+} Point_t;
+
+Point_t point;
+
+
    +

    You can assign values to the struct like this directly in rsfile.rs. These values are not +propagated back to the Android framework level:

    +
    +point.x = 1;
+point.y = 1;
+
    + +

    You can assign values to the struct at the Android framework layer like this. These values are +propagated back to the Renderscript runtime level:

    +
    +ScriptC_rsfile mScript;
+
+...
+
+Item i = new ScriptField_Point.Item();
+i.x = 1;
+i.y = 1;
+mScript.set_point(i);
+
    + +

    You can read the values in your Renderscript code like this:

    + +
    +rsDebug("Printing out a Point", point.x, point.y);
+
    + +

    You can read the values in the Android framework layer with the following code. Keep in mind that this +code only returns a value if one was set at the Android framework level. You will get a null pointer +exception if you only set the value at the Renderscript runtime level:

    + +
    +Log.i("TAGNAME", "Printing out a Point: " + mScript.get_point().x + " " + mScript.get_point().y);
+System.out.println(point.get_x() + " " + point.get_y());
+
    + +

    Reading and writing global pointers

    + +

    Assuming that memory has been allocated in the Android framework level and bound to the Renderscript runtime, +you can read and write memory from the Android framework level by using the get and set methods for that pointer. +In the Renderscript runtime layer, you can read and write to memory with pointers as normal and the changes are propagated +back to the Android framework layer, unlike with statically allocated memory.

    + +

    For example, given the following pointer to a struct in a file named rsfile.rs:

    +
    +typedef struct Point {
+    int x;
+    int y;
+} Point_t;
+
+Point_t *point;
+
    + +

    Assuming you already allocated memory at the Android framework layer, you can access values in +the struct as normal. Any changes you make to the struct via its pointer variable +are automatically available to the Android framework layer:

    + +
    +point[index].x = 1;
+point[index].y = 1;
+
    + +

    You can read and write values to the pointer at the Android framework layer as well: +

    +ScriptField_Point p = new ScriptField_Point(mRS, 1);
+    Item i = new ScriptField_Point.Item();
+    i.x=100;
+    i.y = 100;
+    p.set(i, 0, true);
+    mScript.bind_point(p);
+
+    points.get_x(0);            //read x and y from index 0
+    points.get_x(0);
+
    + +

    Once memory is already bound, you do not have to rebind the memory to the Renderscript +runtime every time you make a change to a value.

    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 + + + +

    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.

    + +

    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.

    + +

    Deprecation Notice: 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 rs_graphics.rsh +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.

    + +

    Renderscript System Overview

    +

    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).

    + +

    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.

    + + +

    Figure 1. Renderscript system overview

    + +

    When using Renderscript, there are three layers of APIs that enable communication between the + Renderscript runtime and Android framework code:

    + +
      +
    • The Renderscript runtime APIs allow you to do the computation + that is required by your application.
      • + +
    • 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.
      • + +
    • The Android framework layer calls the reflected layer to access the Renderscript + runtime.
      • +
    + +

    Because of the way Renderscript is structured, the main advantages are:

    +
      +
    • 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.
      • + +
    • Performance: Renderscript provides a high performance computation API with seamless parallelization + across the amount of cores on the device.
      • + +
    • Usability: Renderscript simplifies development when possible, such as eliminating JNI glue code.
      • +
    + +

    The main disadvantages are:

    + +
      +
    • Development complexity: Renderscript introduces a new set of APIs that you have to learn.
      • + +
    • 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. +
      • +
    + +

    For a more detailed explanation of how all of these layers work together, see + Advanced Renderscript.

    + + +

    Creating a Renderscript

    + +

    Renderscripts scale to the amount of +processing cores available on the device. This is enabled through a function named +rsForEach() (or the forEach_root() 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.

    + +

    Implementing a Renderscript involves creating a .rs file that contains +your Renderscript code and calling it at the Android framework level with the +forEach_root() or at the Renderscript runtime level with the +rsForEach() function. The following diagram describes how a typical +Renderscript is set up:

    + +

    Figure 1. Renderscript overview

    + +

    The following sections describe how to create a simple Renderscript and use it in an +Android application. This example uses the HelloCompute Renderscript +sample that is provided in the SDK as a guide (some code has been modified from its original +form for simplicity).

    + +

    Creating the Renderscript file

    + +

    Your Renderscript code resides in .rs and .rsh files in the +<project_root>/src/ directory. This code contains the computation logic +and declares all necessary variables and pointers. +Every .rs file generally contains the following items:

    + +
      +
    • A pragma declaration (#pragma rs java_package_name(package.name)) + that declares the package name of the .java reflection of this Renderscript.
      • + +
    • A pragma declaration (#pragma version(1)) that declares the version of + Renderscript that you are using (1 is the only value for now).
      • + +

    • A root() function that is the main worker function. The root function is + called by the rsForEach function, which allows the Renderscript code to be called and + executed on multiple cores if they are available. The root() function must return + void and accept the following arguments:

      + +
        +
      • 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.
        • +
      + +

      The following arguments are optional, but both must be supplied if you choose to use + them:

      + +
        +
      • 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.
        • + +
      • The size of the user-defined data.
        • +
      +
      • + +
    • An optional init() function. This allows you to do any initialization + before the root() function runs, such as initializing variables. This + function runs once and is called automatically when the Renderscript starts, before anything + else in your Renderscript.
      • + +
    • Any variables, pointers, and structures that you wish to use in your Renderscript code (can + be declared in .rsh files if desired)
      • +
    + +

    The following code shows how the +mono.rs file is implemented:

    +
    +#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);
+}
+
    + +

    Calling the Renderscript code

    + +

    You can call the Renderscript from your Android framework code by +creating a Renderscript object by instantiating the (ScriptC_script_name) +class. This class contains a method, forEach_root(), that lets you invoke +rsForEach. 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 HelloCompute sample to see +how a simple Android application can utilize Renderscript.

    + +

    To call Renderscript at the Android framework level:

    + +
      +
    1. 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.
      2. + +
    2. Create an instance of the ScriptC_script_name class.
      3. + +
    3. Call forEach_root(), passing in the allocations, the + Renderscript, and any optional user-defined data. The output allocation will contain the output + of the Renderscript.
      4. +
    + +

    The following example, taken from the HelloCompute sample, processes +a bitmap and outputs a black and white version of it. The +createScript() method carries out the steps described previously. This method calls the +Renderscript, mono.rs, 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:

    +
    +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);
+  }
+}
+
    + +

    To call Renderscript from another Renderscript file:

    +
      +
    1. 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.
      2. + +
    2. Call rsForEach(), passing in the allocations and any optional user-defined data. + The output allocation will contain the output of the Renderscript.
      3. +
    + +
    +rs_script script;
+rs_allocation in_allocation;
+rs_allocation out_allocation;
+UserData_t data;
+...
+rsForEach(script, in_allocation, out_allocation, &data, sizeof(data));
+
    +

    +

    In this example, assume that the script and memory allocations have already been +allocated and bound at the Android framework level and that UserData_t is a struct +declared previously. Passing a pointer to a struct and the size of the struct to rsForEach +is optional, but useful if your Renderscript requires additional information other than +the necessary memory allocations.

    + +

    Setting floating point precision

    +

    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:

    + +
      +
    • #pragma rs_fp_full (default if nothing is specified): For apps that + require floating point precision as outlined by the IEEE 754-2008 standard. +
      • +
    • #pragma rs_fp_relaxed - 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. +
      • +
    • #pragma rs_fp_imprecise - For apps that don’t have stringent precision requirements. This mode enables + everything in rs_fp_relaxed along with the following: +
        +
      • Operations resulting in -0.0 can return +0.0 instead.
        • +
      • Operations on INF and NAN are undefined.
        • +
      +
      • +
    \ 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 + +

    Renderscript provides a platform-independent computation engine that operates at the native level. + Use it to accelerate your apps that require extensive computational horsepower.

    +
    + +
    +

    Blog Articles

    + +

    Levels in Renderscript

    +

    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.

    +     + + +

    Renderscript Part 2

    +

    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).

    +     +
    + +
    +
    \ No newline at end of file diff --git a/docs/html/guide/topics/renderscript/reference.jd b/docs/html/guide/topics/renderscript/reference.jd new file mode 100644 index 0000000..a9d780a --- /dev/null +++ b/docs/html/guide/topics/renderscript/reference.jd @@ -0,0 +1,21 @@ +page.title=Runtime API Reference +parent.title=Computation +parent.link=index.html + +@jd:body + + + + + -- cgit v1.1