Peter_vdL

Renderscript, part II

by Peter_vdL Motorola 03-13-2011 04:03 PM - edited 03-22-2011 09:18 AM

In a recent blog post, I described Renderscript - the new high performance 3D graphics API for Android.  To refresh your memory, Renderscript is

  • a new API, published with the Honeycomb API release
  • made up of a "computing" API, and a "rendering" API
  • intended for programmers who want to coax the last ounce of performance from their hardware
  • accessed using a C-based scripting language

The earlier post showed how to compile and run the sample Renderscript code included with the Honeycomb SDK. This blog post reviews the source files for one of the Renderscript samples, and explains how a Renderscript app is composed.

 

When analyzing something new, it's usual to start with the simplest example and proceed from there.  In the case of Renderscript, the simplest example is the "Hello World" code, provided as one of several sample apps.  No one would actually use Renderscript in real life to put a string on the screen, but it's a great way to look at the files needed for a minimal example.  

 

Renderscript source code

After you import the sample code into Eclipse (described in the earlier blog post), you will see four source files. 

Screen shot 2011-03-13 at 2.05.19 PM.png

     Figure 1: Four source files make up the Hello World Renderscript example.

 

You keep your Renderscript scripts in the src folder of the project.  A Renderscript file looks like C code, although with some special pragmas and names.  Look at helloworld.rs first -- this is the actual Renderscript script for the example.  Here's that .rs file, stripped of pragmas and most comments:

#include "rs_graphics.rsh"

int gTouchX;
int gTouchY;

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

int root(int launchID) {
rsgClearColor(0.0f, 0.0f, 0.0f, 0.0f); // set background black
rsgFontColor(1.0f, 1.0f, 1.0f, 1.0f); // set font white
rsgDrawText("Hello World!", gTouchX, gTouchY);
return 20;
}

If you're comfortable with C, you'll be immediately comfortable with the syntax and appearance of Renderscript.  [You'll probably also notice that the rsgClearColor() call should be as below, for example.  I'm not sure what it means to set the alpha value of the background to anything other than fully opaque.  Possibly it means nothing, if the alpha channel is ignored for backgrounds.  (But if it is ignored, why is it a parameter?) ]

rsgClearColor(0.0f, 0.0f, 0.0f, 1.0f);  // set background opaque black

 

The init() function is for one time set-up.  It 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 runtime.

 

The root() routine is the equivalent of main().  Root() is called for each frame refresh for the surface it is being rendered to.  The return value, 20 here, tells Renderscript runtime approximately how many milleseconds should elapse between redraws.  So the frame rate here is about 50 fps.

 

#include header files

The "#include" brings in the header file for the Renderscript graphics.   You can find that rs_graphics.rsh file in your SDK, in the folder platforms/android-11/renderscript/include, along with 5 other .rsh ("Renderscript header") files.  In an unexplained break with C convention, these other five files are included automatically when needed.  The 6 .rsh files together provide the namespace for typedefs and the functions that you can call in your Renderscript scripts.

 

If you want to try modifying this script, there's an rsRand() function you can use, in rs_math.rsh.  You could use that to pick random values for the font color.  Or animate the text on the screen by moving a small amount in each frame.

 

Screen shot 2011-03-12 at 5.07.01 PM.png

                      Figure 2: Review the six rs_*.rsh files in the SDK to see the names in the Renderscript API.

 

As its name suggests, rs_graphics.rsh contains the declarations of about 30 graphics-oriented routines in the native Renderscript libraries.   These are operations like rsgClearColor() to set a rendering surface to a specific color, and rsgDrawMesh() to draw a mesh of geometry.

 

The other 5 .rsh files contain declarations of math and utility functions.  The math functions are overloaded so they work on both scalars and vectors.  There is a clang-include directory containing a score or so C header files, also relating to math and other supporting features to use in your scripts.

 

Compute Scripts and Graphics Scripts

It is perfectly possible to use Renderscript for intensive number-crunching that is unrelated to graphics (e.g. weather modeling).  You do this by using the math library, and never calling any rendering routines.    There are thus two kinds of Renderscripts:

  • a compute Renderscript only does number-crunching and no rendering 
  • a graphics Renderscript does graphics rendering plus any calculations needed to support it.

For both kinds of script, the basic model is to do all your memory allocation in Java, and then hand all the data to Renderscript for crunching and rendering.  You don't do any memory allocation in Renderscript.  This limitation allows Renderscript to allocate processing units freely, on CPU cores or the GPU, as available.  This ensures that maximum resources are brought to bear on CPU-bound programs, and you get the highest possible performance from your hardware.  

 

The "silicon fungibility" (capability for mutual substitution) brings with it two restrictions.  GPUs don't have the same hardware support for debugging that CPUs have.  So you can't set breakpoints and debug your scripts using the debugger.  Second, Renderscript cannot call any C libraries or code, because these functions assume they running on a CPU, not a GPU.  For the same reason, you cannot run Renderscript programs in the emulator.

 

How your Renderscript source interfaces to Android/Java

Renderscript programs start off with an Android project created in Eclipse.  The Android code manages the Activity lifecycle. 

 

When you build a project containing Renderscript, the build system automatically generates some Java "glue" code that makes the Renderscript objects visible to your Android Java code, and vice versa.  The generated code provides get/set routines, allowing Java to see and use Renderscript variables like gTouchX and gTouchY in the sample. The generated code can be seen in your project's gen directory, but you probably never need to look at it.

 

The prohibition on calling C, mentioned above, rules out calls to malloc, calloc, and other C-based dynamic memory management (except allocation on the stack presumably, if you can do it without calling alloca()).  Your scripts will request memory by using the rs_allocation type, defined in the rs_types.rsh header file.  This will call back into the generated Java "glue" code, and get the memory using the class android.renderscript.Allocation.  All dynamic memory management is done within Java and Android.

 

Other Source Files

There are three other files in the hello world source folder.  They are quite brief, so I'll just list their purpose here, and invite you to review the source code at your leisure.

 

  1. HelloWorld.java -- this is very close to the "hello world" template that Eclipse gives you.  The only significant addition is the instantiation of a HelloWorldView object in onCreate(), which is then set as the content view
  2. HelloWorldRS.java -- this file is the renderer.  Rendering is the last step in the graphics pipeline, turning the 3D model into a 2D raster representation on the screen.  The code reads in the helloworld.rs Renderscript (accessing it as a project resource), and binds it to a Renderscript GL object.  That causes the init() and root() methods of the script to be called, and away we go.
  3. HelloWorldView.java -- this file creates a surface (a memory buffer that can be drawn on), and passes it to the init() routine of HelloWorldRS.  As the only View in the Activity, this class gets onTouchEvents. It passes the X,Y coordinates to HelloWorldRS.java, which in turn calls the "glue" code to pass them to your script.

Other References

There aren't a lot of Renderscript articles at the time of writing (March 13, 2011).   After you've read this post, and want more details, here are the two references I used:

 

 http://developer.android.com/guide/topics/graphics/renderscript.html

 

 http://developer.android.com/reference/android/renderscript/package-summary.html

 

If you have any suggestions for improving or extending this blog post, to make it a more useful or complete introduction to Renderscript, please post them as a comment below.  I will update the article (or post a new one) to include the best suggestions.  Cheers,

 

Peter van der Linden

Android Technology Evangelist

 

 

Comments
by Anoop(anon) on 03-16-2011 02:03 AM

Is it possible to test renderscript in Emulator? Android 3.0 devices are not yet available in India.

by Peter_vdL Motorola on 03-22-2011 09:15 AM

Hi Anoop -- Renderscript is very dependent on hardware.   As a result, it falls in the same category as e.g. sensors - it only works on real hardware.

 

Peter

by Alexander Emeliyanov(anon) on 05-03-2011 01:14 AM

Hi, Peter

 

One thing that boggles me about Renderscript is how to generate A3D format that would store my meshes? I saw some early introduction articles, where it was shown the Android droids converted from Collada to A3D. I tried to dig that one, but failed miserably. I can't find an easy way to store my models in A3D format. Maybe you could give me a hint?

 

Kind regards,

Alex

by goodsunil(anon) on 06-15-2011 05:28 AM

can you tell me if renderscript samples are expected to run in emulator of Android SDK. i tried but does not work. provide so solution if u know.

by Peter_vdL Motorola on 06-18-2011 05:03 PM

Hi Sunil,

Renderscript is very dependent on hardware.   As a result, it falls in the same category as e.g. sensors, or bluetooth - it only works on real hardware.

 

Peter



by Arun Akilendraa(anon) on 01-24-2012 11:01 PM

Hi,

 

 I am new to renderscript concept...i am tryin to replicate Fruit Ninja blade effect using renderscript...can anyone help me on this??

by Peter_vdL Motorola on 01-25-2012 01:50 PM

If it were me, Arun, I would definitely start with something much simpler, and work my way up to more fancy effects.  

by Tyler Durden(anon) on 03-09-2012 01:20 AM

Dear Peter,

 

I would like to my custom view instead of bitmap in Renderscript Carousel, Is it possible?

Post a Comment
Be sure to enter a unique name. You can't reuse a name that's already in use.
Be sure to enter a unique email address. You can't reuse an email address that's already in use.
reCAPTCHA challenge image
Type the characters you see in the picture above.Type the words you hear.
About MOTODEV Blog
The MOTODEV blog keeps you updated on mobile app development news from MOTODEV and the Android developer community.

Subscribe to our RSS feed Subscribe via RSS

Follow Us:
Fan MOTODEV on Facebook Join the MOTODEV LinkedIn Group MOTODEV on YouTube

motodev profile

motodev Do u have questions about the Google+ Hangout happening right now? Go to Google Moderator and ask a way: moto.ly/askl2cloud 7 days ago · reply · retweet · favorite

motodev profile

motodev Use Schema Builder to build out your data model. Find out more at our Google+ Hangout now: moto.ly/l2cloud #l2cloud 7 days ago · reply · retweet · favorite

motodev profile

motodev It's not too late to join our Google+ Hangout: Migrating your Legacy Systems to the Cloud & Mobile: moto.ly/l2cloud #l2cloud 7 days ago · reply · retweet · favorite

Our Blog & Comment Policy
Opinions expressed here and in any corresponding comments are the personal opinions of the original authors, not of Motorola. The content is provided for informational purposes only and is not meant to be an endorsement or representation by Motorola or any other party.

Remember, when you comment, please stay on topic and avoid spam, profanity, and anything else that violates our user guidelines. All comments require approval by Motorola and can be rejected for any reason.

For customer support issues with your Motorola phone go to the Motorola customer support website.