3D Rendering and Computation with Renderscript

The Android framework API also has a corresponding Renderscript context object, RenderScript (for a compute Renderscript) or RenderScriptGL (for a graphics Renderscript). This context object allows you to bind to the reflected Renderscript class, so that the Renderscript context knows what its corresponding native Renderscript is. If you have a graphics Renderscript context, you can also specify a variety of Programs (stages in the graphics pipeline) to tweek how your graphics are rendered. A graphics Renderscript context also needs a surface to render on, RSSurfaceView, which gets passed into its constructor.

API overview

Renderscript code is compiled and executed in a compact and well defined runtime, which has access to a limited amount of functions. Renderscript cannot use the NDK or standard C functions, because these functions are assumed to be running on a standard CPU. The Renderscript runtime chooses the best processor to execute the code, which may not be the CPU, so it cannot guarantee support for standard C libraries. What Renderscript does offer is an API that supports intensive computation with an extensive collection of math APIs. The following sections group the APIs into three distinct categories.

Native Renderscript APIs

The Renderscript headers are located in the include and clang-include directories in the <sdk_root>/platforms/android-11/renderscript directory of the Android SDK. The headers are automatically included for you, except for the graphics specific header, which you can define as follows:

#include "rs_graphics.rsh"

Some key features of the native Renderscript libraries include:

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

Reflected layer APIs

These classes are mainly used by the reflected classes that are generated from your native Renderscript code. They allocate and manage memory for your Renderscript on the Android system side. You normally do not need to call these classes directly.

Because of the constraints of the Renderscript native layer, you cannot do any dynamic memory allocation in your Renderscript .rs file. The native Renderscript layer can request memory from the Android system layer, which allocates memory for you and does reference counting to figure out when to free the memory. A memory allocation is taken care of by the Allocation class and memory is requested in your Renderscript code with the the rs_allocation type. All references to Renderscript objects are counted, so when your Renderscript native code or system code no longer references a particular Allocation, it destroys itself. Alternatively, you can call destroy() from the Android system level, which decreases the reference to the Allocation. If no references exist after the decrease, the Allocation destroys itself. The Android system object, which at this point is just an empty shell, is eventually garbage collected.

The following classes are mainly used by the reflected layer classes:

Graphics API

Renderscript provides a number of graphics APIs for hardware-accelerated 3D rendering. The Renderscript graphics APIs include a stateful context, RenderScriptGL that contains the current rendering state. The primary state consists of the objects that are attached to the rendering context, which are the graphics Renderscript and the four program types. The main working function of the graphics Renderscript is the code that is defined in the root() function. The root() function is called each time the surface goes through a frame refresh. The four program types mirror a traditional graphical rendering pipeline and are:

• Vertex
• Fragment
• Store
• Raster

Graphical scripts have more properties beyond a basic computational script, and they call the 'rsg'-prefixed functions defined in the rs_graphics.rsh header file. A graphics Renderscript can also set four pragmas that control the default bindings to the RenderScriptGL context when the script is executing:

• stateVertex
• stateFragment
• stateRaster
• stateStore

The possible values are parent or default for each pragma. Using default says that when a script is executed, the bindings to the graphical context are the system defaults. Using parent says that the state should be the same as it is in the calling script. If this is a root script, the parent state is taken from the bind points as set in the RenderScriptGL bind methods in the control environment (VM environment).

For example, you can define this at the top of your native graphics Renderscript code:

#pragma stateVertex(parent)
#pragma stateStore(parent)

The following table describes the major graphics specific APIs that are available to you:

Developing a Renderscript application

The basic workflow of developing a Renderscript application is:

1. Analyze your application's requirements and figure out what you want to develop with Renderscript. To take full advantage of the Renderscript system, you want to use it when the computation or graphics performance you're getting with the traditional framework APIs is insufficient.
2. Design the interface of your Renderscript code and implement it using the native Renderscript APIs that are included in the Android SDK in <sdk_root>/platforms/android-11/renderscript.
3. Create an Android project as you would normally, in Eclipse or with the android tool.
4. Place your Renderscript files in src folder of the Android project so that the build tools can generate the reflected layer classes.
5. Create your application, calling the Renderscript through the reflected class layer when you need to.
6. Build, install, and run your application as you would normally.

To see how a simple Renderscript application is put together, see the Renderscript samples and The Hello Graphics Application section of the documentation.

The Hello Graphics Application

This small application demonstrates the structure of a simple Renderscript application. You can model your Renderscript application after the basic structure of this application. You can find the complete source in the SDK in the <android-sdk>/samples/android-11/HelloWorldRS directory. The application uses Renderscript to draw the string, "Hello World!" to the screen and redraws the text whenever the user touches the screen at the location of the touch. This application is only a demonstration and you should not use the Renderscript system to do something this trivial. The application contains the following source files:

• HelloWorld: The main Activity for the application. This class is present to provide Activity lifecycle management. It mainly delegates work to HelloWorldView, which is the Renderscript surface that the sample actually draws on.
• HelloWorldView: The Renderscript surface that the graphics render on. If you are using Renderscript for graphics rendering, you must have a surface to render on. If you are using it for computatational operations only, then you do not need this.
• HelloWorldRS: The class that calls the native Renderscript code through high level entry points that are generated by the Android build tools.
• helloworld.rs: The Renderscript native code that draws the text on the screen.

• The <project_root>/gen directory contains the reflected layer classes that are generated by the Android build tools. You will notice a ScriptC_helloworld class, which is the reflective version of the Renderscript and contains the entry points into the helloworld.rs native code. This file does not appear until you run a build.

Each file has its own distinct use. The following files comprise the main parts of the sample and demonstrate in detail how the sample works:

helloworld.rs

The native Renderscript code is contained in the helloworld.rs file. Every .rs file must contain two pragmas that define the version of Renderscript that it is using (1 is the only version for now), and the package name that the reflected classes should be generated with. For example:

#pragma version(1)

#pragma rs java_package_name(com.my.package.name)

An .rs file can also declare two special functions:

• init(): This function is called once for each instance of this Renderscript file that is loaded on the device, before the script is accessed in any other way by the Renderscript system. The init() is ideal for doing one time setup after the machine code is loaded such as initializing complex constant tables. The init() function for the helloworld.rs script sets the initial location of the text that is rendered to the screen:

  void init(){
      gTouchX = 50.0f;
      gTouchY = 50.0f;
  }
  

• root(): This function is the default worker function for this Renderscript file. For graphics Renderscript applications, like this one, the Renderscript system expects this function to render the frame that is going to be displayed. It is called every time the frame refreshes. The root() function for the helloworld.rs script sets the background color of the frame, the color of the text, and then draws the text where the user last touched the screen:

  int root(int launchID) {
      // Clear the background color
      rsgClearColor(0.0f, 0.0f, 0.0f, 0.0f);
      // Tell the runtime what the font color should be
      rsgFontColor(1.0f, 1.0f, 1.0f, 1.0f);
      // Introduce ourselves to the world by drawing a greeting
      // at the position that the user touched on the screen
      rsgDrawText("Hello World!", gTouchX, gTouchY);
            
      // Return value tells RS roughly how often to redraw
      // in this case 20 ms
      return 20;
  }
  

  The return value, 20, is the desired frame refresh rate in milliseconds. The real screen refresh rate depends on the hardware, computation, and rendering complexity that the root() function has to execute. A value of 0 tells the screen to render only once and to only render again when a change has been made to one of the properties that are being modified by the Renderscript code.

  Besides the init() and root() functions, you can define the other native functions, structs, data types, and any other logic for your Renderscript. You can even define separate header files as .rsh files.

ScriptC_helloworld

This class is generated by the Android build tools and is the reflected version of the helloworld.rs Renderscript. It provides a a high level entry point into the helloworld.rs native code by defining the corresponding methods that you can call from the traditional framework APIs.

helloworld.bc bytecode

This file is the intermediate, platform-independent bytecode that gets compiled on the device when the Renderscript application runs. It is generated by the Android build tools and is packaged with the .apk file and subsequently compiled on the device at runtime. This file is located in the <project_root>/res/raw/ directory and is named rs_filename.bc. You need to bind these files to your Renderscript context before call any Renderscript code from your Android application. You can reference them in your code with R.id.rs_filename.

HelloWorldView class

This class represents the Surface View that the Renderscript graphics are drawn on. It does some administrative tasks in the ensureRenderScript() method that sets up the Renderscript system. This method creates a RenderScriptGL object, which represents the context of the Renderscript and creates a default surface to draw on (you can set the surface properties such as alpha and bit depth in the RenderScriptGL.SurfaceConfig class ). When a RenderScriptGL is instantiated, this class calls the HelloRS class and creates the instance of the actual Renderscript graphics renderer.

// Renderscipt context
private RenderScriptGL mRS;
// Script that does the rendering
private HelloWorldRS mRender;

    private void ensureRenderScript() {
        if (mRS == null) {
            // Initialize Renderscript with desired surface characteristics.
            // In this case, just use the defaults
            RenderScriptGL.SurfaceConfig sc = new RenderScriptGL.SurfaceConfig();
            mRS = createRenderScriptGL(sc);

            // Create an instance of the Renderscript that does the rendering
            mRender = new HelloWorldRS();
            mRender.init(mRS, getResources());
        }
    }

This class also handles the important lifecycle events and relays touch events to the Renderscript renderer. When a user touches the screen, it calls the renderer, HelloWorldRS and asks it to draw the text on the screen at the new location.

public boolean onTouchEvent(MotionEvent ev) {
    // Pass touch events from the system to the rendering script
    if (ev.getAction() == MotionEvent.ACTION_DOWN) {
        mRender.onActionDown((int)ev.getX(), (int)ev.getY());
        return true;
    }
    return false;
}

HelloWorldRS

This class represents the Renderscript renderer for the HelloWorldView Surface View. It interacts with the native Renderscript code that is defined in helloworld.rs through the interfaces exposed by ScriptC_helloworld. To be able to call the native code, it creates an instance of the Renderscript reflected class, ScriptC_helloworld. The reflected Renderscript object binds the Renderscript bytecode (R.raw.helloworld) and the Renderscript context, RenderScriptGL, so the context knows to use the right Renderscript to render its surface.

private Resources mRes;
private RenderScriptGL mRS;
private ScriptC_helloworld mScript;

private void initRS() {
    mScript = new ScriptC_helloworld(mRS, mRes, R.raw.helloworld);
    mRS.bindRootScript(mScript);
}