From 6518f486a5b9cdcb48df3ca09732b51b6df249bf Mon Sep 17 00:00:00 2001
From: Robert Ly The Renderscript system offers high performance 3D rendering and mathematical computations at
+ The Renderscript system offers high performance 3D rendering and mathematical computation at
the native level. The Renderscript APIs are intended for developers who are comfortable with
developing in C (C99 standard) and want to maximize performance in their applications. The
Renderscript system improves performance by running as native code on the device, but it also
@@ -46,47 +54,46 @@ parent.link=index.html
intermediate code. The disadvantage of the Renderscript system is that it adds complexity to the development and
- debugging processes and is not a substitute for the Android system APIs. It is a portable native
- language with pointers and explicit resource management. The target use is for performance
- critical code where the existing Android APIs are not sufficient. If what you are rendering or
- computing is very simple and does not require much processing power, you should still use the
- Android APIs for ease of development. Debugging visibility can be limited, because the
+ debugging processes. Debugging visibility can be limited, because the
Renderscript system can execute on processors other than the main CPU (such as the GPU), so if
- this occurs, debugging becomes more difficult. Remember the tradeoffs between development and
- debugging complexity versus performance when deciding to use Renderscript.Related Samples
+
+
-
For an example of Renderscript in action, see the 3D carousel view in the Android 3.0 versions
of Google Books and YouTube or install the Renderscript sample applications that are shipped with
- the SDK in <sdk_root>/platforms/android-3.0/samples
.
<sdk_root>/samples/android-11/Renderscript
.
The Renderscript system adopts a control and slave architecture where the low-level native code is controlled by the higher level Android system that runs in the virtual machine (VM). When - you use the Renderscript system, there are three layers of APIs that exist:
+ you use the Renderscript system, there are three layers that exist:.rs
files
- that you write to compute mathematical operations, render graphics, or both. This layer does
- the intensive computation or graphics rendering and returns the result back to the Android VM
- through the reflected layer..rs
files compute mathematical operations, render graphics,
+ or both. This layer does the intensive computation or graphics rendering and returns the result
+ back to the Android VM through the reflected layer.To fully understand how the Renderscript system works, you must understand how the reflected layer is generated and how it interacts with the native Renderscript layer and Android system layer. The reflected layer provides the entry points into the native code, enabling the Android - system code to give high level commands like, "rotate the view" or "filter the bitmap." It - delegates all the heavy lifting to the native layer. To accomplish this, you need to create logic + system to give high level commands like, "rotate the view" or "filter the bitmap" to the + native layer, which does the heavy lifting. To accomplish this, you need to create logic to hook together all of these layers so that they can correctly communicate.
At the root of everything is your Renderscript, which is the actual C code that you write and @@ -94,11 +101,10 @@ parent.link=index.html and graphics. A compute Renderscript does not do any graphics rendering while a graphics Renderscript does.
-When you create a Renderscript .rs
file, an equivalent, reflective layer class,
- {@link android.renderscript.ScriptC}, is generated by the build tools and exposes the native
- functions to the Android system. This class is named
- ScriptC_renderscript_filename
. The following list describes the major
- components of your native Renderscript code that is reflected:
When you create Renderscript .rs
files, equivalent, reflected classes
+ are generated by the build tools and expose the native functions and data types and structures
+ to the Android system. The following list describes the major components of your native Renderscript
+ code that is reflected:
.rs
file) are reflected into
@@ -108,12 +114,12 @@ parent.link=index.html
ScriptC_renderscript_filename
.
Accessor methods are generated, so the Android system layer can access the values.
- The get()
method comes with a one-way communication restriction.
- The Android system layer always caches the last value that is set and returns that during a call to get.
- If the native Renderscript code has changed the value, the change does propagate back to the Android system layer
- for efficiency. If the global variables are initialized in the native Renderscript code, those values are used
- to initialize the Android system versions. If global variables are marked as const
,
- then a set()
method is not generated.
+ The get
method comes with a one-way communication restriction.
+ The Android system layer always caches the last value that is set and returns that during a call to a get method.
+ If the native Renderscript code changes the value, the change does not propagate back to the Android system layer.
+ If the global variables are initialized in the native Renderscript code, those values are used
+ to initialize the corresponding values in the Android system. If global variables are marked as const
,
+ then a set
method is not generated.
The Android system also has a corresponding Renderscript context object, {@link +
The Android framework API also has a corresponding Renderscript context object, {@link android.renderscript.RenderScript} (for a compute Renderscript) or {@link android.renderscript.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, {@link - android.renderscript.RSSurfaceView}, which gets passed into its constructor. When all three of - the layers are connected, the Renderscript system can compute or render graphics.
+ android.renderscript.RSSurfaceView}, which gets passed into its constructor.The Renderscript headers are located in the include
and
clang-include
directories in the
- <sdk_root>/platforms/android-3.0/renderscript
directory of the Android SDK.
+ <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:
These classes are not generated by the reflection process, and are actually part of the - Android system APIs, but they are mainly used by the reflective layer classes to handle memory - allocation and management for your Renderscript. You normally do not need to be call these classes - directly.
+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.
@@ -195,7 +198,7 @@ parent.link=index.html
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 reflective layer classes:
+The following classes are mainly used by the reflected layer classes:
An {@link android.renderscript.Element} is the most basic element of a memory type. An
element represents one cell of a memory allocation. An element can have two forms: Basic or
- Complex. They are typically created from C structures that are used within Renderscript
- code and cannot contain pointers or nested arrays. The other common source of elements is
- bitmap formats.
+ Complex. They are typically created from C structures in your Renderscript
+ code during the reflection process. Elements cannot contain pointers or nested arrays.
+ The other common source of elements is bitmap formats.
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 @@ -253,12 +256,11 @@ parent.link=index.html | rs_allocation |
- An {@link android.renderscript.Allocation} provides the memory for applications. An {@link
+ An {@link android.renderscript.Allocation} provides the memory for applications. An {@link android.renderscript.Allocation} allocates memory based on a description of the memory that - is represented by a {@link android.renderscript.Type}. The {@link - android.renderscript.Type} describes an array of {@link android.renderscript.Element}s that + is represented by a {@link android.renderscript.Type}. The type describes an array of elements that represent the memory to be allocated. Allocations are the primary way data moves into and - out of scripts. + out of scripts. Memory is user-synchronized and it's possible for allocations to exist in multiple memory spaces concurrently. For example, if you make a call to the graphics card to load a @@ -270,9 +272,9 @@ parent.link=index.html Allocation data is uploaded in one of two primary ways: type checked and type unchecked.
For simple arrays there are |
@@ -331,7 +333,7 @@ parent.link=index.html
state is taken from the bind points as set in the {@link android.renderscript.RenderScriptGL}
bind methods in the control environment (VM environment).
- rs_program_vertex |
- The Renderscript vertex program, also known as a vertex shader, describes the stage in the
+ The Renderscript vertex program, also known as a vertex shader, describes the stage in the graphics pipeline responsible for manipulating geometric data in a user-defined way. The - object is constructed by providing Renderscript with the following data: + object is constructed by providing Renderscript with the following data:
Once the program is created, bind it to the graphics context. It is then used for all + Once the program is created, bind it to the {@link android.renderscript.RenderScriptGL} + graphics context by calling + {@link android.renderscript.RenderScriptGL#bindProgramVertex bindProgramVertex()}. It is then used for all subsequent draw calls until you bind a new program. If the program has constant inputs, the user needs to bind an allocation containing those inputs. The allocation’s type must match the one provided during creation. The Renderscript library then does all the necessary @@ -391,7 +395,7 @@ parent.link=index.html | rs_program_fragment | -The Renderscript fragment program, also known as the fragment shader, is responsible for + | The Renderscript fragment program, also known as the fragment shader, is responsible for manipulating pixel data in a user-defined way. It’s constructed from a GLSL shader string containing the program body, textures inputs, and a Type object describing the constants used by the program. Like the vertex programs, when an allocation with constant input values is @@ -401,7 +405,7 @@ parent.link=index.html rsgAllocationSyncAll so it could send the new values to hardware. Communication between the vertex and fragment programs is handled internally in the GLSL code. For example, if the fragment program is expecting a varying input called varTex0, the GLSL code inside the - program vertex must provide it. + program vertex must provide it. To bind shader constructs to the this Program, declare a struct containing the necessary shader constants in your native Renderscript code. This struct is generated into a reflected class that you can use as a constant input element during the Program's creation. It is an easy way to create an instance of this struct as an allocation. @@ -416,7 +420,7 @@ parent.link=index.html | rs_program_store | The Renderscript ProgramStore contains a set of parameters that control how the graphics - hardware writes to the framebuffer. It could be used to enable/disable depth writes and + hardware writes to the framebuffer. It could be used to enable and disable depth writes and testing, setup various blending modes for effects like transparency and define write masks for color components. |