Hello World
As always when introduced to a new framework,your first instinct should be to say “hello” to the world from a RenderScript script. To create a script, simply create a new file in your Android project and call it helloworld.rs. Listing 9–1 shows how we can create a simple function that will output the “Hello, World” string using a simple RenderScript debugging function.
Listing 9–1. “Hello, World” Script
#pragma version(1)
#pragma rs java_package_name(com.apress.proandroid.ch9)
void hello_world() {
rsDebug("Hello, World", 0); // 0 is because we cannot send only a string to the debug output...
}
The first line declares which version of RenderScript your script uses. The second line declares the package name of the Java reflection of this script. As you build your Android project, many things will happen under the hood, and the build tools will create the following three files:
- ScriptC_helloworld.java (in gen/ directory)
- helloworld.d (in gen/ directory)
- helloworld.bc (in res/raw/ directory)
Listing 9–2 shows the content of the auto-generated ScriptC_helloworld.java file. You can find that file in your project's gen directory, which is the same directory R.java is generated. This file is part of the reflected layer of your script and contains the definition of the class that will allow you to invoke functions from your script and communicate with your script in general. In that same directory you will also find helloworld.d, which simply lists the dependencies for the helloworld.bc file (that is, helloworld.bc would have to be generated again if any of the listed dependencies in helloworld.d is modified).
Listing 9–2. ScriptC_helloworld.java
/*
* Copyright (C) 2011 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/*
* This file is auto-generated. DO NOT MODIFY!
* The source RenderScript file: E:wsChapter
9srccomapressproandroidch9helloworld.rs
*/
package com.apress.proandroid.ch9;
import android.renderscript.*;
import android.content.res.Resources;
/**
* @hide
*/
public class ScriptC_helloworld extends ScriptC {
// Constructor
public ScriptC_helloworld(RenderScript rs, Resources resources, int id) {
super(rs, resources, id);
}
private final static int mExportFuncIdx_hello_world = 0;
public void invoke_hello_world() {
invoke(mExportFuncIdx_hello_world);
}
}
Three things stand out in this auto-generated file:
- The package name is the one defined in the script with #pragma
- The public constructor
- The invoke_hello_world function
Parts of this auto-generated file, even though they are important, are not relevant to you. For example, the private mExportFuncIdx_hello_world constant in Listing 9–2 refers to the index of a function in the script, but its actual value is of no importance to you or your application.
To use the script, you will have to create an instance of ScriptC_helloworld in your Java code, which will then allow you to call the script's hello_world function via the reflected invoke_hello_world method, as shown in Listing 9–3.
Listing 9–3. Calling RenderScript Function
public class Chapter9Activity extends Activity {
/** Called when the activity is first created. */
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
HelloWorldRenderScript();
}
private void HelloWorldRenderScript() {
RenderScript rs = RenderScript.create(this); // needs a Context as parameter
// script created using the helloworld bitcode in res/raw/helloworld.bc
ScriptC_helloworld helloworldScript = new ScriptC_helloworld(rs, getResources(), R.raw.helloworld);
// now we can call the script's hello_world function using the reflected method
helloworldScript.invoke_hello_world();
}
}
Executing this code will result in “Hello, World 0 0x0” being displayed in logcat with the tag “RenderScript”.
NOTE: Use DDMS perspective in Eclipse to observe that RenderScript-related threads are now running in the application (with the name RSMessageThread). You can also see the following output in logcat: “RS Launching thread(s), reported CPU count 2” (if your device has 2 cores). As you learn about RenderScript, observe the outputs generated with the tag “RenderScript”.
While the helloworld.bc file is critical as it contains the script bitcode, its actual content is not of great value to you. All you should care about is the fact that the LLVM bitcode is the platform-independent representation of your script. That being said, it is possible to disassemble this file and convert it to human-readable LLVM assembly language using the LLVM disassembler llvm-dis (available as part of the LLVM suite). Listing 9–4 shows the LLVM assembly language version of helloworld.bc.
Listing 9–4. LLVM Assembly Language (helloworld.bc)
; ModuleID = '/home/herve/helloworld.bc'
target datalayout = "e-p:32:32:32-i1:8:8-i8:8:8-i16:16:16-i32:32:32-i64:64:64-f32:32:32-f64:64:64-v64:64:64-v128:128:128-a0:0:64-n32"
target triple = "armv7-none-linux-gnueabi"
@.str = private constant [13 x i8] c"Hello, World 0"
define void @hello_world() nounwind {
tail call void @_Z7rsDebugPKci(i8* getelementptr inbounds ([13 x i8]* @.str, i32 0, i32 0), i32 0) nounwind
ret void
}
declare void @_Z7rsDebugPKci(i8*, i32)
!#pragma = !{!0, !1}
!#rs_export_func = !{!2}
!0 = metadata !{metadata !"version", metadata !"1"}
!1 = metadata !{metadata !"java_package_name", metadata !"com.apress.proandroid.ch9"}
!2 = metadata !{metadata !"hello_world"}
This example did not perform any rendering using RenderScript. In fact, the activity's layout was still defined using XML and the activity content was still set from a layout resource which was inflated when setContentView() was called. Now that you know how to create a basic script, it is time to see how rendering can be performed with RenderScript.