Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / frameworks / compile / slang / refs/tags/fp2-sibon-17.07.6 / . / README.html
blob: 4ace7c659a5c975f414e5e46510103feaa70b90d [file] [log] [blame]
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]1<?xml version="1.0" encoding="utf-8" ?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]7<title>llvm-rs-cc: Compiler for Renderscript language</title>
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]8<style type="text/css">
9
10/*
11:Author: David Goodger (goodger@python.org)
12:Id: $Id: html4css1.css 5951 2009-05-18 18:03:10Z milde $
13:Copyright: This stylesheet has been placed in the public domain.
14
15Default cascading style sheet for the HTML output of Docutils.
16
17See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
18customize this style sheet.
19*/
20
21/* used to remove borders from tables and images */
22.borderless, table.borderless td, table.borderless th {
23 border: 0 }
24
25table.borderless td, table.borderless th {
26 /* Override padding for "table.docutils td" with "! important".
27 The right padding separates the table cells. */
28 padding: 0 0.5em 0 0 ! important }
29
30.first {
31 /* Override more specific margin styles with "! important". */
32 margin-top: 0 ! important }
33
34.last, .with-subtitle {
35 margin-bottom: 0 ! important }
36
37.hidden {
38 display: none }
39
40a.toc-backref {
41 text-decoration: none ;
42 color: black }
43
44blockquote.epigraph {
45 margin: 2em 5em ; }
46
47dl.docutils dd {
48 margin-bottom: 0.5em }
49
50/* Uncomment (and remove this text!) to get bold-faced definition list terms
51dl.docutils dt {
52 font-weight: bold }
53*/
54
55div.abstract {
56 margin: 2em 5em }
57
58div.abstract p.topic-title {
59 font-weight: bold ;
60 text-align: center }
61
62div.admonition, div.attention, div.caution, div.danger, div.error,
63div.hint, div.important, div.note, div.tip, div.warning {
64 margin: 2em ;
65 border: medium outset ;
66 padding: 1em }
67
68div.admonition p.admonition-title, div.hint p.admonition-title,
69div.important p.admonition-title, div.note p.admonition-title,
70div.tip p.admonition-title {
71 font-weight: bold ;
72 font-family: sans-serif }
73
74div.attention p.admonition-title, div.caution p.admonition-title,
75div.danger p.admonition-title, div.error p.admonition-title,
76div.warning p.admonition-title {
77 color: red ;
78 font-weight: bold ;
79 font-family: sans-serif }
80
81/* Uncomment (and remove this text!) to get reduced vertical space in
82 compound paragraphs.
83div.compound .compound-first, div.compound .compound-middle {
84 margin-bottom: 0.5em }
85
86div.compound .compound-last, div.compound .compound-middle {
87 margin-top: 0.5em }
88*/
89
90div.dedication {
91 margin: 2em 5em ;
92 text-align: center ;
93 font-style: italic }
94
95div.dedication p.topic-title {
96 font-weight: bold ;
97 font-style: normal }
98
99div.figure {
100 margin-left: 2em ;
101 margin-right: 2em }
102
103div.footer, div.header {
104 clear: both;
105 font-size: smaller }
106
107div.line-block {
108 display: block ;
109 margin-top: 1em ;
110 margin-bottom: 1em }
111
112div.line-block div.line-block {
113 margin-top: 0 ;
114 margin-bottom: 0 ;
115 margin-left: 1.5em }
116
117div.sidebar {
118 margin: 0 0 0.5em 1em ;
119 border: medium outset ;
120 padding: 1em ;
121 background-color: #ffffee ;
122 width: 40% ;
123 float: right ;
124 clear: right }
125
126div.sidebar p.rubric {
127 font-family: sans-serif ;
128 font-size: medium }
129
130div.system-messages {
131 margin: 5em }
132
133div.system-messages h1 {
134 color: red }
135
136div.system-message {
137 border: medium outset ;
138 padding: 1em }
139
140div.system-message p.system-message-title {
141 color: red ;
142 font-weight: bold }
143
144div.topic {
145 margin: 2em }
146
147h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
148h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
149 margin-top: 0.4em }
150
151h1.title {
152 text-align: center }
153
154h2.subtitle {
155 text-align: center }
156
157hr.docutils {
158 width: 75% }
159
160img.align-left, .figure.align-left{
161 clear: left ;
162 float: left ;
163 margin-right: 1em }
164
165img.align-right, .figure.align-right {
166 clear: right ;
167 float: right ;
168 margin-left: 1em }
169
170.align-left {
171 text-align: left }
172
173.align-center {
174 clear: both ;
175 text-align: center }
176
177.align-right {
178 text-align: right }
179
180/* reset inner alignment in figures */
181div.align-right {
182 text-align: left }
183
184/* div.align-center * { */
185/* text-align: left } */
186
187ol.simple, ul.simple {
188 margin-bottom: 1em }
189
190ol.arabic {
191 list-style: decimal }
192
193ol.loweralpha {
194 list-style: lower-alpha }
195
196ol.upperalpha {
197 list-style: upper-alpha }
198
199ol.lowerroman {
200 list-style: lower-roman }
201
202ol.upperroman {
203 list-style: upper-roman }
204
205p.attribution {
206 text-align: right ;
207 margin-left: 50% }
208
209p.caption {
210 font-style: italic }
211
212p.credits {
213 font-style: italic ;
214 font-size: smaller }
215
216p.label {
217 white-space: nowrap }
218
219p.rubric {
220 font-weight: bold ;
221 font-size: larger ;
222 color: maroon ;
223 text-align: center }
224
225p.sidebar-title {
226 font-family: sans-serif ;
227 font-weight: bold ;
228 font-size: larger }
229
230p.sidebar-subtitle {
231 font-family: sans-serif ;
232 font-weight: bold }
233
234p.topic-title {
235 font-weight: bold }
236
237pre.address {
238 margin-bottom: 0 ;
239 margin-top: 0 ;
240 font: inherit }
241
242pre.literal-block, pre.doctest-block {
243 margin-left: 2em ;
244 margin-right: 2em }
245
246span.classifier {
247 font-family: sans-serif ;
248 font-style: oblique }
249
250span.classifier-delimiter {
251 font-family: sans-serif ;
252 font-weight: bold }
253
254span.interpreted {
255 font-family: sans-serif }
256
257span.option {
258 white-space: nowrap }
259
260span.pre {
261 white-space: pre }
262
263span.problematic {
264 color: red }
265
266span.section-subtitle {
267 /* font-size relative to parent (h1..h6 element) */
268 font-size: 80% }
269
270table.citation {
271 border-left: solid 1px gray;
272 margin-left: 1px }
273
274table.docinfo {
275 margin: 2em 4em }
276
277table.docutils {
278 margin-top: 0.5em ;
279 margin-bottom: 0.5em }
280
281table.footnote {
282 border-left: solid 1px black;
283 margin-left: 1px }
284
285table.docutils td, table.docutils th,
286table.docinfo td, table.docinfo th {
287 padding-left: 0.5em ;
288 padding-right: 0.5em ;
289 vertical-align: top }
290
291table.docutils th.field-name, table.docinfo th.docinfo-name {
292 font-weight: bold ;
293 text-align: left ;
294 white-space: nowrap ;
295 padding-left: 0 }
296
297h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
298h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
299 font-size: 100% }
300
301ul.auto-toc {
302 list-style-type: none }
303
304</style>
305</head>
306<body>
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]307<div class="document" id="llvm-rs-cc-compiler-for-renderscript-language">
308<h1 class="title">llvm-rs-cc: Compiler for Renderscript language</h1>
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]309
310<div class="section" id="introduction">
311<h1>Introduction</h1>
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]312<p>llvm-rs-cc compiles a program in the Renderscript language to generate the
313following files:</p>
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]314<ul class="simple">
315<li>Bitcode file. Note that the bitcode here denotes the LLVM (Low-Level
316Virtual Machine) bitcode representation, which will be consumed on
317an Android device by libbcc (in
318platform/frameworks/compile/libbcc.git) to generate device-specific
319executables.</li>
320<li>Reflected APIs for Java. As a result, Android's Java developers can
321invoke those APIs from their code.</li>
322</ul>
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]323<p>Note that although Renderscript is C99-like, we enhance it with several
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]324distinct, effective features for Android programming. We will use
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]325some examples to illustrate these features.</p>
326<p>llvm-rs-cc is run on the host and performs many aggressive optimizations.
327As a result, libbcc on the device can be lightweight and focus on
328machine-dependent code generation for some input bitcode.</p>
329<p>llvm-rs-cc is a driver on top of libslang. The architecture of
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]330libslang and libbcc is depicted in the following figure:</p>
331<pre class="literal-block">
332libslang libbcc
333 | \ |
334 | \ |
335 clang llvm
336</pre>
337</div>
338<div class="section" id="usage">
339<h1>Usage</h1>
340<ul>
341<li><p class="first"><em>-o $(PRIVATE_RS_OUTPUT_DIR)/res/raw</em></p>
342<p>This option specifies the directory for outputting a .bc file.</p>
343</li>
344<li><p class="first"><em>-p $(PRIVATE_RS_OUTPUT_DIR)/src</em></p>
345<p>The option <em>-p</em> denotes the directory for outputting the reflected Java files.</p>
346</li>
347<li><p class="first"><em>-d $(PRIVATE_RS_OUTPUT_DIR)</em></p>
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]348<p>This option <em>-d</em> sets the directory for writing dependence information.</p>
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]349</li>
350<li><p class="first"><em>-MD</em></p>
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]351<p>Note that <em>-MD</em> will tell llvm-rs-cc to output dependence information.</p>
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]352</li>
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]353<li><p class="first"><em>-a $(EXTRA_TARGETS)</em></p>
354<p>Specifies additional target dependencies.</p>
Shih-wei Liao29c36732011-01-20 05:48:20 -0800[diff] [blame]355</li>
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]356</ul>
357</div>
358<div class="section" id="example-command">
359<h1>Example Command</h1>
360<p>First:</p>
361<pre class="literal-block">
362$ cd &lt;Android_Root_Directory&gt;
363</pre>
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]364<p>Using frameworks/base/tests/RenderScriptTests/Fountain as a simple app in both
365Java and Renderscript, we can find the following command line in the build
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]366log:</p>
367<pre class="literal-block">
368$ out/host/linux-x86/bin/llvm-rs-cc \
369 -o out/target/common/obj/APPS/Fountain_intermediates/src/renderscript/res/raw \
370 -p out/target/common/obj/APPS/Fountain_intermediates/src/renderscript/src \
371 -d out/target/common/obj/APPS/Fountain_intermediates/src/renderscript \
372 -a out/target/common/obj/APPS/Fountain_intermediates/src/RenderScript.stamp \
373 -MD \
374 -I frameworks/base/libs/rs/scriptc \
375 -I external/clang/lib/Headers \
376 frameworks/base/libs/rs/java/Fountain/src/com/android/fountain/fountain.rs
377</pre>
378<p>This command will generate:</p>
379<ul class="simple">
380<li><strong>fountain.bc</strong></li>
381<li><strong>ScriptC_fountain.java</strong></li>
382<li><strong>ScriptField_Point.java</strong></li>
383</ul>
384<p>The <strong>Script*.java</strong> files above will be documented below.</p>
385</div>
386<div class="section" id="example-program-fountain-rs">
387<h1>Example Program: fountain.rs</h1>
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]388<p>fountain.rs is in the Renderscript language, which is based on the standard
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]389C99. However, llvm-rs-cc goes beyond &quot;clang -std=c99&quot; and provides the
390following important features:</p>
391</div>
392<div class="section" id="pragma">
393<h1>1. Pragma</h1>
394<ul>
395<li><p class="first"><em>#pragma rs java_package_name([PACKAGE_NAME])</em></p>
396<p>The ScriptC_[SCRIPT_NAME].java has to be packaged so that Java
397developers can invoke those APIs.</p>
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]398<p>To do that, a Renderscript programmer should specify the package name, so
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]399that llvm-rs-cc knows the package expression and hence the directory
400for outputting ScriptC_[SCRIPT_NAME].java.</p>
401<p>In fountain.rs, we have:</p>
402<pre class="literal-block">
403#pragma rs java_package_name(com.android.fountain)
404</pre>
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]405<p>In ScriptC_fountain.java, we have:</p>
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]406<pre class="literal-block">
407package com.android.fountain
408</pre>
409<p>Note that the ScriptC_fountain.java will be generated inside
410./com/android/fountain/.</p>
411</li>
412<li><p class="first">#pragma version(1)</p>
413<p>This pragma is for evolving the language. Currently we are at
414version 1 of the language.</p>
415</li>
416</ul>
417</div>
418<div class="section" id="basic-reflection-export-variables-and-functions">
419<h1>2. Basic Reflection: Export Variables and Functions</h1>
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]420<p>llvm-rs-cc automatically exports the &quot;externalizable and defined&quot; functions and
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]421variables to Android's Java side. That is, scripts are accessible from
422Java.</p>
423<p>For instance, for:</p>
424<pre class="literal-block">
425int foo = 0;
426</pre>
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]427<p>In ScriptC_fountain.java, llvm-rs-cc will reflect the following methods:</p>
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]428<pre class="literal-block">
429void set_foo(int v)...
430
431int get_foo()...
432</pre>
433<p>This access takes the form of generated classes which provide access
434to the functions and global variables within a script. In summary,
435global variables and functions within a script that are not declared
436static will generate get, set, or invoke methods. This provides a way
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]437to set the data within a script and call its functions.</p>
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]438<p>Take the addParticles function in fountain.rs as an example:</p>
439<pre class="literal-block">
440void addParticles(int rate, float x, float y, int index, bool newColor) {
441 ...
442}
443</pre>
444<p>llvm-rs-cc will genearte ScriptC_fountain.java as follows:</p>
445<pre class="literal-block">
446void invoke_addParticles(int rate, float x, float y,
447 int index, bool newColor) {
448 ...
449}
450</pre>
451</div>
452<div class="section" id="export-user-defined-structs">
453<h1>3. Export User-Defined Structs</h1>
454<p>In fountain.rs, we have:</p>
455<pre class="literal-block">
456typedef struct __attribute__((packed, aligned(4))) Point {
457 float2 delta;
458 float2 position;
459 uchar4 color;
460} Point_t;
461
462Point_t *point;
463</pre>
464<p>llvm-rs-cc generates one ScriptField*.java file for each user-defined
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]465struct. In this case, llvm-rs-cc will reflect two files,
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]466ScriptC_fountain.java and ScriptField_Point.java.</p>
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]467<p>Note that when the type of an exportable variable is a structure, Renderscript
468developers should avoid using anonymous structs. This is because llvm-rs-cc
469uses the struct name to identify the file, instead of the typedef name.</p>
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]470<p>For the generated Java files, using ScriptC_fountain.java as an
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]471example we also have:</p>
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]472<pre class="literal-block">
473void bind_point(ScriptField_Point v)
474</pre>
475<p>This binds your object with the allocated memory.</p>
476<p>You can bind the struct(e.g., Point), using the setter and getter
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]477methods in ScriptField_Point.java.</p>
478<p>After binding, you can access the object with this method:</p>
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]479<pre class="literal-block">
480ScriptField_Point get_point()
481</pre>
482<p>In ScriptField_Point_s.java:</p>
483<pre class="literal-block">
484...
485// Copying the Item, which is the object that stores every
486// fields of struct, to the *index*\-th entry of byte array.
487//
488// In general, this method would not be invoked directly
489// but is used to implement the setter.
490void copyToArray(Item i, int index)
491
492// The setter of Item array,
493// index: the index of the Item array
494// copyNow: If true, it will be copied to the *index*\-th entry
495// of byte array.
496void set(Item i, int index, boolean copyNow)
497
498// The getter of Item array, which gets the *index*-th element
499// of byte array.
500Item get(int index)
501
502set_delta(int index, Float2 v, boolean copyNow)
503
504// The following is the individual setters and getters of
505// each field of a struct.
506public void set_delta(int index, Float2 v, boolean copyNow)
507public void set_position(int index, Float2 v, boolean copyNow)
508public void set_color(int index, Short4 v, boolean copyNow)
509public Float2 get_delta(int index)
510public Float2 get_position(int index)
511public Short4 get_color(int index)
512
513// Copying all Item array to byte array (i.e., memory allocation).
514void copyAll()
515...
516</pre>
517</div>
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]518<div class="section" id="summary-of-the-java-reflection-above">
519<h1>4. Summary of the Java Reflection above</h1>
520<p>This section summarizes the high-level design of Renderscript's reflection.</p>
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]521<ul>
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]522<li><p class="first">In terms of a script's global functions, they can be called from Java.
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]523These calls operate asynchronously and no assumptions should be made
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]524on whether a function called will have actually completed operation. If it
525is necessary to wait for a function to complete, the Java application
526may call the runtime finish() method, which will wait for all the script
527threads to complete pending operations. A few special functions can also
528exist:</p>
529<ul>
530<li><p class="first">The function <strong>init</strong> (if present) will be called once after the script
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]531is loaded. This is useful to initialize data or anything else the
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]532script may need before it can be used. The init function may not depend
533on globals initialized from Java as it will be called before these
534can be initialized. The function signature for init must be:</p>
535<pre class="literal-block">
536void init(void);
537</pre>
538</li>
539<li><p class="first">The function <strong>root</strong> is a special function for graphics. This function
540will be called when a script must redraw its contents. No
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]541assumptions should be made as to when this function will be
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]542called. It will only be called if the script is bound as a graphics root.
543Calls to this function will be synchronized with data updates and
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]544other invocations from Java. Thus the script will not change due
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]545to external influence in the middle of running <strong>root</strong>. The return value
546indicates to the runtime when the function should be called again to
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]547redraw in the future. A return value of 0 indicates that no
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]548redraw is necessary until something changes on the Java side. Any
549positive integer indicates a time in milliseconds that the runtime should
550wait before calling root again to render another frame. The function
551signature for a graphics root functions is as follows:</p>
552<pre class="literal-block">
553int root(void);
554</pre>
555</li>
556<li><p class="first">It is also possible to create a purely compute-based <strong>root</strong> function.
557Such a function has the following signature:</p>
558<pre class="literal-block">
559void root(const T1 *in, T2 *out, const T3 *usrData, uint32_t x, uint32_t y);
560</pre>
561<p>T1, T2, and T3 represent any supported Renderscript type. Any parameters
562above can be omitted, although at least one of in/out must be present.
563If both in and out are present, root must only be invoked with types of
564the same exact dimensionality (i.e. matching X and Y values for dimension).
565This root function is accessible through the Renderscript language
566construct <strong>forEach</strong>. We also reflect a Java version to access this
567function as <strong>forEach_root</strong> (for API levels of 14+). An example of this
568can be seen in the Android SDK sample for HelloCompute.</p>
569</li>
570<li><p class="first">The function <strong>.rs.dtor</strong> is a function that is sometimes generated by
571llvm-rs-cc. This function cleans up any global variable that contains
572(or is) a reference counted Renderscript object type (such as an
573rs_allocation, rs_font, or rs_script). This function will be invoked
574implicitly by the Renderscript runtime during script teardown.</p>
575</li>
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]576</ul>
577</li>
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]578<li><p class="first">In terms of a script's global data, global variables can be written
579from Java. The Java instance will cache the value or object set and
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]580provide return methods to retrieve this value. If a script updates
581the value, this update will not propagate back to the Java class.
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]582Initializers, if present, will also initialize the cached Java value.
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]583This provides a convenient way to declare constants within a script and
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]584make them accessible to the Java runtime. If the script declares a
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]585variable const, only the get methods will be generated.</p>
586<p>Globals within a script are considered local to the script. They
587cannot be accessed by other scripts and are in effect always 'static'
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]588in the traditional C sense. Static here is used to control if
589accessors are generated. Static continues to mean <em>not
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]590externally visible</em> and thus prevents the generation of
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]591accessors. Globals are persistent across invocations of a script and
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]592thus may be used to hold data from run to run.</p>
593<p>Globals of two types may be reflected into the Java class. The first
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]594type is basic non-pointer types. Types defined in rs_types.rsh may also be
595used. For the non-pointer class, get and set methods are generated for
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]596Java. Globals of single pointer types behave differently. These may
597use more complex types. Simple structures composed of the types in
598rs_types.rsh may also be used. These globals generate bind points in
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]599Java. If the type is a structure they also generate an appropriate
600<strong>Field</strong> class that is used to pack and unpack the contents of the
601structure. Binding an allocation in Java effectively sets the
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]602pointer in the script. Bind points marked const indicate to the
603runtime that the script will not modify the contents of an allocation.
604This may allow the runtime to make more effective use of threads.</p>
605</li>
606</ul>
607</div>
608<div class="section" id="vector-types">
609<h1>5. Vector Types</h1>
610<p>Vector types such as float2, float4, and uint4 are included to support
611vector processing in environments where the processors provide vector
612instructions.</p>
613<p>On non-vector systems the same code will continue to run but without
614the performance advantage. Function overloading is also supported.
615This allows the runtime to support vector version of the basic math
616routines without the need for special naming. For instance,</p>
617<ul class="simple">
618<li><em>float sin(float);</em></li>
619<li><em>float2 sin(float2);</em></li>
Stephen Hines18687142011-09-02 19:07:14 -0700[diff] [blame]620<li><em>float3 sin(float3);</em></li>
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800[diff] [blame]621<li><em>float4 sin(float4);</em></li>
622</ul>
623</div>
624</div>
625</body>
626</html>