You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
627 lines
20 KiB
627 lines
20 KiB
4 months ago
|
<?xml version="1.0" encoding="utf-8" ?>
|
||
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
|
|
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
|
||
|
|
<title>llvm-rs-cc: Compiler for Renderscript language</title>
|
||
|
|
<style type="text/css">
|
||
|
|
|
||
|
|
/*
|
||
|
|
:Author: David Goodger (goodger@python.org)
|
||
|
|
:Id: $Id: html4css1.css 5951 2009-05-18 18:03:10Z milde $
|
||
|
|
:Copyright: This stylesheet has been placed in the public domain.
|
||
|
|
|
||
|
|
Default cascading style sheet for the HTML output of Docutils.
|
||
|
|
|
||
|
|
See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
|
||
|
|
customize this style sheet.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/* used to remove borders from tables and images */
|
||
|
|
.borderless, table.borderless td, table.borderless th {
|
||
|
|
border: 0 }
|
||
|
|
|
||
|
|
table.borderless td, table.borderless th {
|
||
|
|
/* Override padding for "table.docutils td" with "! important".
|
||
|
|
The right padding separates the table cells. */
|
||
|
|
padding: 0 0.5em 0 0 ! important }
|
||
|
|
|
||
|
|
.first {
|
||
|
|
/* Override more specific margin styles with "! important". */
|
||
|
|
margin-top: 0 ! important }
|
||
|
|
|
||
|
|
.last, .with-subtitle {
|
||
|
|
margin-bottom: 0 ! important }
|
||
|
|
|
||
|
|
.hidden {
|
||
|
|
display: none }
|
||
|
|
|
||
|
|
a.toc-backref {
|
||
|
|
text-decoration: none ;
|
||
|
|
color: black }
|
||
|
|
|
||
|
|
blockquote.epigraph {
|
||
|
|
margin: 2em 5em ; }
|
||
|
|
|
||
|
|
dl.docutils dd {
|
||
|
|
margin-bottom: 0.5em }
|
||
|
|
|
||
|
|
/* Uncomment (and remove this text!) to get bold-faced definition list terms
|
||
|
|
dl.docutils dt {
|
||
|
|
font-weight: bold }
|
||
|
|
*/
|
||
|
|
|
||
|
|
div.abstract {
|
||
|
|
margin: 2em 5em }
|
||
|
|
|
||
|
|
div.abstract p.topic-title {
|
||
|
|
font-weight: bold ;
|
||
|
|
text-align: center }
|
||
|
|
|
||
|
|
div.admonition, div.attention, div.caution, div.danger, div.error,
|
||
|
|
div.hint, div.important, div.note, div.tip, div.warning {
|
||
|
|
margin: 2em ;
|
||
|
|
border: medium outset ;
|
||
|
|
padding: 1em }
|
||
|
|
|
||
|
|
div.admonition p.admonition-title, div.hint p.admonition-title,
|
||
|
|
div.important p.admonition-title, div.note p.admonition-title,
|
||
|
|
div.tip p.admonition-title {
|
||
|
|
font-weight: bold ;
|
||
|
|
font-family: sans-serif }
|
||
|
|
|
||
|
|
div.attention p.admonition-title, div.caution p.admonition-title,
|
||
|
|
div.danger p.admonition-title, div.error p.admonition-title,
|
||
|
|
div.warning p.admonition-title {
|
||
|
|
color: red ;
|
||
|
|
font-weight: bold ;
|
||
|
|
font-family: sans-serif }
|
||
|
|
|
||
|
|
/* Uncomment (and remove this text!) to get reduced vertical space in
|
||
|
|
compound paragraphs.
|
||
|
|
div.compound .compound-first, div.compound .compound-middle {
|
||
|
|
margin-bottom: 0.5em }
|
||
|
|
|
||
|
|
div.compound .compound-last, div.compound .compound-middle {
|
||
|
|
margin-top: 0.5em }
|
||
|
|
*/
|
||
|
|
|
||
|
|
div.dedication {
|
||
|
|
margin: 2em 5em ;
|
||
|
|
text-align: center ;
|
||
|
|
font-style: italic }
|
||
|
|
|
||
|
|
div.dedication p.topic-title {
|
||
|
|
font-weight: bold ;
|
||
|
|
font-style: normal }
|
||
|
|
|
||
|
|
div.figure {
|
||
|
|
margin-left: 2em ;
|
||
|
|
margin-right: 2em }
|
||
|
|
|
||
|
|
div.footer, div.header {
|
||
|
|
clear: both;
|
||
|
|
font-size: smaller }
|
||
|
|
|
||
|
|
div.line-block {
|
||
|
|
display: block ;
|
||
|
|
margin-top: 1em ;
|
||
|
|
margin-bottom: 1em }
|
||
|
|
|
||
|
|
div.line-block div.line-block {
|
||
|
|
margin-top: 0 ;
|
||
|
|
margin-bottom: 0 ;
|
||
|
|
margin-left: 1.5em }
|
||
|
|
|
||
|
|
div.sidebar {
|
||
|
|
margin: 0 0 0.5em 1em ;
|
||
|
|
border: medium outset ;
|
||
|
|
padding: 1em ;
|
||
|
|
background-color: #ffffee ;
|
||
|
|
width: 40% ;
|
||
|
|
float: right ;
|
||
|
|
clear: right }
|
||
|
|
|
||
|
|
div.sidebar p.rubric {
|
||
|
|
font-family: sans-serif ;
|
||
|
|
font-size: medium }
|
||
|
|
|
||
|
|
div.system-messages {
|
||
|
|
margin: 5em }
|
||
|
|
|
||
|
|
div.system-messages h1 {
|
||
|
|
color: red }
|
||
|
|
|
||
|
|
div.system-message {
|
||
|
|
border: medium outset ;
|
||
|
|
padding: 1em }
|
||
|
|
|
||
|
|
div.system-message p.system-message-title {
|
||
|
|
color: red ;
|
||
|
|
font-weight: bold }
|
||
|
|
|
||
|
|
div.topic {
|
||
|
|
margin: 2em }
|
||
|
|
|
||
|
|
h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
|
||
|
|
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
|
||
|
|
margin-top: 0.4em }
|
||
|
|
|
||
|
|
h1.title {
|
||
|
|
text-align: center }
|
||
|
|
|
||
|
|
h2.subtitle {
|
||
|
|
text-align: center }
|
||
|
|
|
||
|
|
hr.docutils {
|
||
|
|
width: 75% }
|
||
|
|
|
||
|
|
img.align-left, .figure.align-left{
|
||
|
|
clear: left ;
|
||
|
|
float: left ;
|
||
|
|
margin-right: 1em }
|
||
|
|
|
||
|
|
img.align-right, .figure.align-right {
|
||
|
|
clear: right ;
|
||
|
|
float: right ;
|
||
|
|
margin-left: 1em }
|
||
|
|
|
||
|
|
.align-left {
|
||
|
|
text-align: left }
|
||
|
|
|
||
|
|
.align-center {
|
||
|
|
clear: both ;
|
||
|
|
text-align: center }
|
||
|
|
|
||
|
|
.align-right {
|
||
|
|
text-align: right }
|
||
|
|
|
||
|
|
/* reset inner alignment in figures */
|
||
|
|
div.align-right {
|
||
|
|
text-align: left }
|
||
|
|
|
||
|
|
/* div.align-center * { */
|
||
|
|
/* text-align: left } */
|
||
|
|
|
||
|
|
ol.simple, ul.simple {
|
||
|
|
margin-bottom: 1em }
|
||
|
|
|
||
|
|
ol.arabic {
|
||
|
|
list-style: decimal }
|
||
|
|
|
||
|
|
ol.loweralpha {
|
||
|
|
list-style: lower-alpha }
|
||
|
|
|
||
|
|
ol.upperalpha {
|
||
|
|
list-style: upper-alpha }
|
||
|
|
|
||
|
|
ol.lowerroman {
|
||
|
|
list-style: lower-roman }
|
||
|
|
|
||
|
|
ol.upperroman {
|
||
|
|
list-style: upper-roman }
|
||
|
|
|
||
|
|
p.attribution {
|
||
|
|
text-align: right ;
|
||
|
|
margin-left: 50% }
|
||
|
|
|
||
|
|
p.caption {
|
||
|
|
font-style: italic }
|
||
|
|
|
||
|
|
p.credits {
|
||
|
|
font-style: italic ;
|
||
|
|
font-size: smaller }
|
||
|
|
|
||
|
|
p.label {
|
||
|
|
white-space: nowrap }
|
||
|
|
|
||
|
|
p.rubric {
|
||
|
|
font-weight: bold ;
|
||
|
|
font-size: larger ;
|
||
|
|
color: maroon ;
|
||
|
|
text-align: center }
|
||
|
|
|
||
|
|
p.sidebar-title {
|
||
|
|
font-family: sans-serif ;
|
||
|
|
font-weight: bold ;
|
||
|
|
font-size: larger }
|
||
|
|
|
||
|
|
p.sidebar-subtitle {
|
||
|
|
font-family: sans-serif ;
|
||
|
|
font-weight: bold }
|
||
|
|
|
||
|
|
p.topic-title {
|
||
|
|
font-weight: bold }
|
||
|
|
|
||
|
|
pre.address {
|
||
|
|
margin-bottom: 0 ;
|
||
|
|
margin-top: 0 ;
|
||
|
|
font: inherit }
|
||
|
|
|
||
|
|
pre.literal-block, pre.doctest-block {
|
||
|
|
margin-left: 2em ;
|
||
|
|
margin-right: 2em }
|
||
|
|
|
||
|
|
span.classifier {
|
||
|
|
font-family: sans-serif ;
|
||
|
|
font-style: oblique }
|
||
|
|
|
||
|
|
span.classifier-delimiter {
|
||
|
|
font-family: sans-serif ;
|
||
|
|
font-weight: bold }
|
||
|
|
|
||
|
|
span.interpreted {
|
||
|
|
font-family: sans-serif }
|
||
|
|
|
||
|
|
span.option {
|
||
|
|
white-space: nowrap }
|
||
|
|
|
||
|
|
span.pre {
|
||
|
|
white-space: pre }
|
||
|
|
|
||
|
|
span.problematic {
|
||
|
|
color: red }
|
||
|
|
|
||
|
|
span.section-subtitle {
|
||
|
|
/* font-size relative to parent (h1..h6 element) */
|
||
|
|
font-size: 80% }
|
||
|
|
|
||
|
|
table.citation {
|
||
|
|
border-left: solid 1px gray;
|
||
|
|
margin-left: 1px }
|
||
|
|
|
||
|
|
table.docinfo {
|
||
|
|
margin: 2em 4em }
|
||
|
|
|
||
|
|
table.docutils {
|
||
|
|
margin-top: 0.5em ;
|
||
|
|
margin-bottom: 0.5em }
|
||
|
|
|
||
|
|
table.footnote {
|
||
|
|
border-left: solid 1px black;
|
||
|
|
margin-left: 1px }
|
||
|
|
|
||
|
|
table.docutils td, table.docutils th,
|
||
|
|
table.docinfo td, table.docinfo th {
|
||
|
|
padding-left: 0.5em ;
|
||
|
|
padding-right: 0.5em ;
|
||
|
|
vertical-align: top }
|
||
|
|
|
||
|
|
table.docutils th.field-name, table.docinfo th.docinfo-name {
|
||
|
|
font-weight: bold ;
|
||
|
|
text-align: left ;
|
||
|
|
white-space: nowrap ;
|
||
|
|
padding-left: 0 }
|
||
|
|
|
||
|
|
h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
|
||
|
|
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
|
||
|
|
font-size: 100% }
|
||
|
|
|
||
|
|
ul.auto-toc {
|
||
|
|
list-style-type: none }
|
||
|
|
|
||
|
|
</style>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<div class="document" id="llvm-rs-cc-compiler-for-renderscript-language">
|
||
|
|
<h1 class="title">llvm-rs-cc: Compiler for Renderscript language</h1>
|
||
|
|
|
||
|
|
<div class="section" id="introduction">
|
||
|
|
<h1>Introduction</h1>
|
||
|
|
<p>llvm-rs-cc compiles a program in the Renderscript language to generate the
|
||
|
|
following files:</p>
|
||
|
|
<ul class="simple">
|
||
|
|
<li>Bitcode file. Note that the bitcode here denotes the LLVM (Low-Level
|
||
|
|
Virtual Machine) bitcode representation, which will be consumed on
|
||
|
|
an Android device by libbcc (in
|
||
|
|
platform/frameworks/compile/libbcc.git) to generate device-specific
|
||
|
|
executables.</li>
|
||
|
|
<li>Reflected APIs for Java. As a result, Android's Java developers can
|
||
|
|
invoke those APIs from their code.</li>
|
||
|
|
</ul>
|
||
|
|
<p>Note that although Renderscript is C99-like, we enhance it with several
|
||
|
|
distinct, effective features for Android programming. We will use
|
||
|
|
some examples to illustrate these features.</p>
|
||
|
|
<p>llvm-rs-cc is run on the host and performs many aggressive optimizations.
|
||
|
|
As a result, libbcc on the device can be lightweight and focus on
|
||
|
|
machine-dependent code generation for some input bitcode.</p>
|
||
|
|
<p>llvm-rs-cc is a driver on top of libslang. The architecture of
|
||
|
|
libslang and libbcc is depicted in the following figure:</p>
|
||
|
|
<pre class="literal-block">
|
||
|
|
libslang libbcc
|
||
|
|
| \ |
|
||
|
|
| \ |
|
||
|
|
clang llvm
|
||
|
|
</pre>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="usage">
|
||
|
|
<h1>Usage</h1>
|
||
|
|
<ul>
|
||
|
|
<li><p class="first"><em>-o $(PRIVATE_RS_OUTPUT_DIR)/res/raw</em></p>
|
||
|
|
<p>This option specifies the directory for outputting a .bc file.</p>
|
||
|
|
</li>
|
||
|
|
<li><p class="first"><em>-p $(PRIVATE_RS_OUTPUT_DIR)/src</em></p>
|
||
|
|
<p>The option <em>-p</em> denotes the directory for outputting the reflected Java files.</p>
|
||
|
|
</li>
|
||
|
|
<li><p class="first"><em>-d $(PRIVATE_RS_OUTPUT_DIR)</em></p>
|
||
|
|
<p>This option <em>-d</em> sets the directory for writing dependence information.</p>
|
||
|
|
</li>
|
||
|
|
<li><p class="first"><em>-MD</em></p>
|
||
|
|
<p>Note that <em>-MD</em> will tell llvm-rs-cc to output dependence information.</p>
|
||
|
|
</li>
|
||
|
|
<li><p class="first"><em>-a $(EXTRA_TARGETS)</em></p>
|
||
|
|
<p>Specifies additional target dependencies.</p>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="example-command">
|
||
|
|
<h1>Example Command</h1>
|
||
|
|
<p>First:</p>
|
||
|
|
<pre class="literal-block">
|
||
|
|
$ cd <Android_Root_Directory>
|
||
|
|
</pre>
|
||
|
|
<p>Using frameworks/base/tests/RenderScriptTests/Fountain as a simple app in both
|
||
|
|
Java and Renderscript, we can find the following command line in the build
|
||
|
|
log:</p>
|
||
|
|
<pre class="literal-block">
|
||
|
|
$ out/host/linux-x86/bin/llvm-rs-cc \
|
||
|
|
-o out/target/common/obj/APPS/Fountain_intermediates/src/renderscript/res/raw \
|
||
|
|
-p out/target/common/obj/APPS/Fountain_intermediates/src/renderscript/src \
|
||
|
|
-d out/target/common/obj/APPS/Fountain_intermediates/src/renderscript \
|
||
|
|
-a out/target/common/obj/APPS/Fountain_intermediates/src/RenderScript.stamp \
|
||
|
|
-MD \
|
||
|
|
-I frameworks/base/libs/rs/script_api/include \
|
||
|
|
-I external/clang/lib/Headers \
|
||
|
|
frameworks/base/libs/rs/java/Fountain/src/com/android/fountain/fountain.rscript
|
||
|
|
</pre>
|
||
|
|
<p>This command will generate:</p>
|
||
|
|
<ul class="simple">
|
||
|
|
<li><strong>fountain.bc</strong></li>
|
||
|
|
<li><strong>ScriptC_fountain.java</strong></li>
|
||
|
|
<li><strong>ScriptField_Point.java</strong></li>
|
||
|
|
</ul>
|
||
|
|
<p>The <strong>Script*.java</strong> files above will be documented below.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="example-program-fountain-rs">
|
||
|
|
<h1>Example Program: fountain.rscript</h1>
|
||
|
|
<p>fountain.rscript is in the Renderscript language, which is based on the standard
|
||
|
|
C99. However, llvm-rs-cc goes beyond "clang -std=c99" and provides the
|
||
|
|
following important features:</p>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="pragma">
|
||
|
|
<h1>1. Pragma</h1>
|
||
|
|
<ul>
|
||
|
|
<li><p class="first"><em>#pragma rs java_package_name([PACKAGE_NAME])</em></p>
|
||
|
|
<p>The ScriptC_[SCRIPT_NAME].java has to be packaged so that Java
|
||
|
|
developers can invoke those APIs.</p>
|
||
|
|
<p>To do that, a Renderscript programmer should specify the package name, so
|
||
|
|
that llvm-rs-cc knows the package expression and hence the directory
|
||
|
|
for outputting ScriptC_[SCRIPT_NAME].java.</p>
|
||
|
|
<p>In fountain.rscript, we have:</p>
|
||
|
|
<pre class="literal-block">
|
||
|
|
#pragma rs java_package_name(com.android.fountain)
|
||
|
|
</pre>
|
||
|
|
<p>In ScriptC_fountain.java, we have:</p>
|
||
|
|
<pre class="literal-block">
|
||
|
|
package com.android.fountain
|
||
|
|
</pre>
|
||
|
|
<p>Note that the ScriptC_fountain.java will be generated inside
|
||
|
|
./com/android/fountain/.</p>
|
||
|
|
</li>
|
||
|
|
<li><p class="first">#pragma version(1)</p>
|
||
|
|
<p>This pragma is for evolving the language. Currently we are at
|
||
|
|
version 1 of the language.</p>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="basic-reflection-export-variables-and-functions">
|
||
|
|
<h1>2. Basic Reflection: Export Variables and Functions</h1>
|
||
|
|
<p>llvm-rs-cc automatically exports the "externalizable and defined" functions and
|
||
|
|
variables to Android's Java side. That is, scripts are accessible from
|
||
|
|
Java.</p>
|
||
|
|
<p>For instance, for:</p>
|
||
|
|
<pre class="literal-block">
|
||
|
|
int foo = 0;
|
||
|
|
</pre>
|
||
|
|
<p>In ScriptC_fountain.java, llvm-rs-cc will reflect the following methods:</p>
|
||
|
|
<pre class="literal-block">
|
||
|
|
void set_foo(int v)...
|
||
|
|
|
||
|
|
int get_foo()...
|
||
|
|
</pre>
|
||
|
|
<p>This access takes the form of generated classes which provide access
|
||
|
|
to the functions and global variables within a script. In summary,
|
||
|
|
global variables and functions within a script that are not declared
|
||
|
|
static will generate get, set, or invoke methods. This provides a way
|
||
|
|
to set the data within a script and call its functions.</p>
|
||
|
|
<p>Take the addParticles function in fountain.rscript as an example:</p>
|
||
|
|
<pre class="literal-block">
|
||
|
|
void addParticles(int rate, float x, float y, int index, bool newColor) {
|
||
|
|
...
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
<p>llvm-rs-cc will genearte ScriptC_fountain.java as follows:</p>
|
||
|
|
<pre class="literal-block">
|
||
|
|
void invoke_addParticles(int rate, float x, float y,
|
||
|
|
int index, bool newColor) {
|
||
|
|
...
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="export-user-defined-structs">
|
||
|
|
<h1>3. Export User-Defined Structs</h1>
|
||
|
|
<p>In fountain.rscript, we have:</p>
|
||
|
|
<pre class="literal-block">
|
||
|
|
typedef struct __attribute__((packed, aligned(4))) Point {
|
||
|
|
float2 delta;
|
||
|
|
float2 position;
|
||
|
|
uchar4 color;
|
||
|
|
} Point_t;
|
||
|
|
|
||
|
|
Point_t *point;
|
||
|
|
</pre>
|
||
|
|
<p>llvm-rs-cc generates one ScriptField*.java file for each user-defined
|
||
|
|
struct. In this case, llvm-rs-cc will reflect two files,
|
||
|
|
ScriptC_fountain.java and ScriptField_Point.java.</p>
|
||
|
|
<p>Note that when the type of an exportable variable is a structure, Renderscript
|
||
|
|
developers should avoid using anonymous structs. This is because llvm-rs-cc
|
||
|
|
uses the struct name to identify the file, instead of the typedef name.</p>
|
||
|
|
<p>For the generated Java files, using ScriptC_fountain.java as an
|
||
|
|
example we also have:</p>
|
||
|
|
<pre class="literal-block">
|
||
|
|
void bind_point(ScriptField_Point v)
|
||
|
|
</pre>
|
||
|
|
<p>This binds your object with the allocated memory.</p>
|
||
|
|
<p>You can bind the struct(e.g., Point), using the setter and getter
|
||
|
|
methods in ScriptField_Point.java.</p>
|
||
|
|
<p>After binding, you can access the object with this method:</p>
|
||
|
|
<pre class="literal-block">
|
||
|
|
ScriptField_Point get_point()
|
||
|
|
</pre>
|
||
|
|
<p>In ScriptField_Point_s.java:</p>
|
||
|
|
<pre class="literal-block">
|
||
|
|
...
|
||
|
|
// Copying the Item, which is the object that stores every
|
||
|
|
// fields of struct, to the *index*\-th entry of byte array.
|
||
|
|
//
|
||
|
|
// In general, this method would not be invoked directly
|
||
|
|
// but is used to implement the setter.
|
||
|
|
void copyToArray(Item i, int index)
|
||
|
|
|
||
|
|
// The setter of Item array,
|
||
|
|
// index: the index of the Item array
|
||
|
|
// copyNow: If true, it will be copied to the *index*\-th entry
|
||
|
|
// of byte array.
|
||
|
|
void set(Item i, int index, boolean copyNow)
|
||
|
|
|
||
|
|
// The getter of Item array, which gets the *index*-th element
|
||
|
|
// of byte array.
|
||
|
|
Item get(int index)
|
||
|
|
|
||
|
|
set_delta(int index, Float2 v, boolean copyNow)
|
||
|
|
|
||
|
|
// The following is the individual setters and getters of
|
||
|
|
// each field of a struct.
|
||
|
|
public void set_delta(int index, Float2 v, boolean copyNow)
|
||
|
|
public void set_position(int index, Float2 v, boolean copyNow)
|
||
|
|
public void set_color(int index, Short4 v, boolean copyNow)
|
||
|
|
public Float2 get_delta(int index)
|
||
|
|
public Float2 get_position(int index)
|
||
|
|
public Short4 get_color(int index)
|
||
|
|
|
||
|
|
// Copying all Item array to byte array (i.e., memory allocation).
|
||
|
|
void copyAll()
|
||
|
|
...
|
||
|
|
</pre>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="summary-of-the-java-reflection-above">
|
||
|
|
<h1>4. Summary of the Java Reflection above</h1>
|
||
|
|
<p>This section summarizes the high-level design of Renderscript's reflection.</p>
|
||
|
|
<ul>
|
||
|
|
<li><p class="first">In terms of a script's global functions, they can be called from Java.
|
||
|
|
These calls operate asynchronously and no assumptions should be made
|
||
|
|
on whether a function called will have actually completed operation. If it
|
||
|
|
is necessary to wait for a function to complete, the Java application
|
||
|
|
may call the runtime finish() method, which will wait for all the script
|
||
|
|
threads to complete pending operations. A few special functions can also
|
||
|
|
exist:</p>
|
||
|
|
<ul>
|
||
|
|
<li><p class="first">The function <strong>init</strong> (if present) will be called once after the script
|
||
|
|
is loaded. This is useful to initialize data or anything else the
|
||
|
|
script may need before it can be used. The init function may not depend
|
||
|
|
on globals initialized from Java as it will be called before these
|
||
|
|
can be initialized. The function signature for init must be:</p>
|
||
|
|
<pre class="literal-block">
|
||
|
|
void init(void);
|
||
|
|
</pre>
|
||
|
|
</li>
|
||
|
|
<li><p class="first">The function <strong>root</strong> is a special function for graphics. This function
|
||
|
|
will be called when a script must redraw its contents. No
|
||
|
|
assumptions should be made as to when this function will be
|
||
|
|
called. It will only be called if the script is bound as a graphics root.
|
||
|
|
Calls to this function will be synchronized with data updates and
|
||
|
|
other invocations from Java. Thus the script will not change due
|
||
|
|
to external influence in the middle of running <strong>root</strong>. The return value
|
||
|
|
indicates to the runtime when the function should be called again to
|
||
|
|
redraw in the future. A return value of 0 indicates that no
|
||
|
|
redraw is necessary until something changes on the Java side. Any
|
||
|
|
positive integer indicates a time in milliseconds that the runtime should
|
||
|
|
wait before calling root again to render another frame. The function
|
||
|
|
signature for a graphics root functions is as follows:</p>
|
||
|
|
<pre class="literal-block">
|
||
|
|
int root(void);
|
||
|
|
</pre>
|
||
|
|
</li>
|
||
|
|
<li><p class="first">It is also possible to create a purely compute-based <strong>root</strong> function.
|
||
|
|
Such a function has the following signature:</p>
|
||
|
|
<pre class="literal-block">
|
||
|
|
void root(const T1 *in, T2 *out, const T3 *usrData, uint32_t x, uint32_t y);
|
||
|
|
</pre>
|
||
|
|
<p>T1, T2, and T3 represent any supported Renderscript type. Any parameters
|
||
|
|
above can be omitted, although at least one of in/out must be present.
|
||
|
|
If both in and out are present, root must only be invoked with types of
|
||
|
|
the same exact dimensionality (i.e. matching X and Y values for dimension).
|
||
|
|
This root function is accessible through the Renderscript language
|
||
|
|
construct <strong>forEach</strong>. We also reflect a Java version to access this
|
||
|
|
function as <strong>forEach_root</strong> (for API levels of 14+). An example of this
|
||
|
|
can be seen in the Android SDK sample for HelloCompute.</p>
|
||
|
|
</li>
|
||
|
|
<li><p class="first">The function <strong>.rs.dtor</strong> is a function that is sometimes generated by
|
||
|
|
llvm-rs-cc. This function cleans up any global variable that contains
|
||
|
|
(or is) a reference counted Renderscript object type (such as an
|
||
|
|
rs_allocation, rs_font, or rs_script). This function will be invoked
|
||
|
|
implicitly by the Renderscript runtime during script teardown.</p>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
<li><p class="first">In terms of a script's global data, global variables can be written
|
||
|
|
from Java. The Java instance will cache the value or object set and
|
||
|
|
provide return methods to retrieve this value. If a script updates
|
||
|
|
the value, this update will not propagate back to the Java class.
|
||
|
|
Initializers, if present, will also initialize the cached Java value.
|
||
|
|
This provides a convenient way to declare constants within a script and
|
||
|
|
make them accessible to the Java runtime. If the script declares a
|
||
|
|
variable const, only the get methods will be generated.</p>
|
||
|
|
<p>Globals within a script are considered local to the script. They
|
||
|
|
cannot be accessed by other scripts and are in effect always 'static'
|
||
|
|
in the traditional C sense. Static here is used to control if
|
||
|
|
accessors are generated. Static continues to mean <em>not
|
||
|
|
externally visible</em> and thus prevents the generation of
|
||
|
|
accessors. Globals are persistent across invocations of a script and
|
||
|
|
thus may be used to hold data from run to run.</p>
|
||
|
|
<p>Globals of two types may be reflected into the Java class. The first
|
||
|
|
type is basic non-pointer types. Types defined in rs_types.rsh may also be
|
||
|
|
used. For the non-pointer class, get and set methods are generated for
|
||
|
|
Java. Globals of single pointer types behave differently. These may
|
||
|
|
use more complex types. Simple structures composed of the types in
|
||
|
|
rs_types.rsh may also be used. These globals generate bind points in
|
||
|
|
Java. If the type is a structure they also generate an appropriate
|
||
|
|
<strong>Field</strong> class that is used to pack and unpack the contents of the
|
||
|
|
structure. Binding an allocation in Java effectively sets the
|
||
|
|
pointer in the script. Bind points marked const indicate to the
|
||
|
|
runtime that the script will not modify the contents of an allocation.
|
||
|
|
This may allow the runtime to make more effective use of threads.</p>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="vector-types">
|
||
|
|
<h1>5. Vector Types</h1>
|
||
|
|
<p>Vector types such as float2, float4, and uint4 are included to support
|
||
|
|
vector processing in environments where the processors provide vector
|
||
|
|
instructions.</p>
|
||
|
|
<p>On non-vector systems the same code will continue to run but without
|
||
|
|
the performance advantage. Function overloading is also supported.
|
||
|
|
This allows the runtime to support vector version of the basic math
|
||
|
|
routines without the need for special naming. For instance,</p>
|
||
|
|
<ul class="simple">
|
||
|
|
<li><em>float sin(float);</em></li>
|
||
|
|
<li><em>float2 sin(float2);</em></li>
|
||
|
|
<li><em>float3 sin(float3);</em></li>
|
||
|
|
<li><em>float4 sin(float4);</em></li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|