Shih-wei Liao | 19cc697 | 2011-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 Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 7 | <title>llvm-rs-cc: Compiler for Renderscript language</title> |
Shih-wei Liao | 19cc697 | 2011-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 | |
| 15 | Default cascading style sheet for the HTML output of Docutils. |
| 16 | |
| 17 | See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to |
| 18 | customize 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 | |
| 25 | table.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 | |
| 40 | a.toc-backref { |
| 41 | text-decoration: none ; |
| 42 | color: black } |
| 43 | |
| 44 | blockquote.epigraph { |
| 45 | margin: 2em 5em ; } |
| 46 | |
| 47 | dl.docutils dd { |
| 48 | margin-bottom: 0.5em } |
| 49 | |
| 50 | /* Uncomment (and remove this text!) to get bold-faced definition list terms |
| 51 | dl.docutils dt { |
| 52 | font-weight: bold } |
| 53 | */ |
| 54 | |
| 55 | div.abstract { |
| 56 | margin: 2em 5em } |
| 57 | |
| 58 | div.abstract p.topic-title { |
| 59 | font-weight: bold ; |
| 60 | text-align: center } |
| 61 | |
| 62 | div.admonition, div.attention, div.caution, div.danger, div.error, |
| 63 | div.hint, div.important, div.note, div.tip, div.warning { |
| 64 | margin: 2em ; |
| 65 | border: medium outset ; |
| 66 | padding: 1em } |
| 67 | |
| 68 | div.admonition p.admonition-title, div.hint p.admonition-title, |
| 69 | div.important p.admonition-title, div.note p.admonition-title, |
| 70 | div.tip p.admonition-title { |
| 71 | font-weight: bold ; |
| 72 | font-family: sans-serif } |
| 73 | |
| 74 | div.attention p.admonition-title, div.caution p.admonition-title, |
| 75 | div.danger p.admonition-title, div.error p.admonition-title, |
| 76 | div.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. |
| 83 | div.compound .compound-first, div.compound .compound-middle { |
| 84 | margin-bottom: 0.5em } |
| 85 | |
| 86 | div.compound .compound-last, div.compound .compound-middle { |
| 87 | margin-top: 0.5em } |
| 88 | */ |
| 89 | |
| 90 | div.dedication { |
| 91 | margin: 2em 5em ; |
| 92 | text-align: center ; |
| 93 | font-style: italic } |
| 94 | |
| 95 | div.dedication p.topic-title { |
| 96 | font-weight: bold ; |
| 97 | font-style: normal } |
| 98 | |
| 99 | div.figure { |
| 100 | margin-left: 2em ; |
| 101 | margin-right: 2em } |
| 102 | |
| 103 | div.footer, div.header { |
| 104 | clear: both; |
| 105 | font-size: smaller } |
| 106 | |
| 107 | div.line-block { |
| 108 | display: block ; |
| 109 | margin-top: 1em ; |
| 110 | margin-bottom: 1em } |
| 111 | |
| 112 | div.line-block div.line-block { |
| 113 | margin-top: 0 ; |
| 114 | margin-bottom: 0 ; |
| 115 | margin-left: 1.5em } |
| 116 | |
| 117 | div.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 | |
| 126 | div.sidebar p.rubric { |
| 127 | font-family: sans-serif ; |
| 128 | font-size: medium } |
| 129 | |
| 130 | div.system-messages { |
| 131 | margin: 5em } |
| 132 | |
| 133 | div.system-messages h1 { |
| 134 | color: red } |
| 135 | |
| 136 | div.system-message { |
| 137 | border: medium outset ; |
| 138 | padding: 1em } |
| 139 | |
| 140 | div.system-message p.system-message-title { |
| 141 | color: red ; |
| 142 | font-weight: bold } |
| 143 | |
| 144 | div.topic { |
| 145 | margin: 2em } |
| 146 | |
| 147 | h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, |
| 148 | h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { |
| 149 | margin-top: 0.4em } |
| 150 | |
| 151 | h1.title { |
| 152 | text-align: center } |
| 153 | |
| 154 | h2.subtitle { |
| 155 | text-align: center } |
| 156 | |
| 157 | hr.docutils { |
| 158 | width: 75% } |
| 159 | |
| 160 | img.align-left, .figure.align-left{ |
| 161 | clear: left ; |
| 162 | float: left ; |
| 163 | margin-right: 1em } |
| 164 | |
| 165 | img.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 */ |
| 181 | div.align-right { |
| 182 | text-align: left } |
| 183 | |
| 184 | /* div.align-center * { */ |
| 185 | /* text-align: left } */ |
| 186 | |
| 187 | ol.simple, ul.simple { |
| 188 | margin-bottom: 1em } |
| 189 | |
| 190 | ol.arabic { |
| 191 | list-style: decimal } |
| 192 | |
| 193 | ol.loweralpha { |
| 194 | list-style: lower-alpha } |
| 195 | |
| 196 | ol.upperalpha { |
| 197 | list-style: upper-alpha } |
| 198 | |
| 199 | ol.lowerroman { |
| 200 | list-style: lower-roman } |
| 201 | |
| 202 | ol.upperroman { |
| 203 | list-style: upper-roman } |
| 204 | |
| 205 | p.attribution { |
| 206 | text-align: right ; |
| 207 | margin-left: 50% } |
| 208 | |
| 209 | p.caption { |
| 210 | font-style: italic } |
| 211 | |
| 212 | p.credits { |
| 213 | font-style: italic ; |
| 214 | font-size: smaller } |
| 215 | |
| 216 | p.label { |
| 217 | white-space: nowrap } |
| 218 | |
| 219 | p.rubric { |
| 220 | font-weight: bold ; |
| 221 | font-size: larger ; |
| 222 | color: maroon ; |
| 223 | text-align: center } |
| 224 | |
| 225 | p.sidebar-title { |
| 226 | font-family: sans-serif ; |
| 227 | font-weight: bold ; |
| 228 | font-size: larger } |
| 229 | |
| 230 | p.sidebar-subtitle { |
| 231 | font-family: sans-serif ; |
| 232 | font-weight: bold } |
| 233 | |
| 234 | p.topic-title { |
| 235 | font-weight: bold } |
| 236 | |
| 237 | pre.address { |
| 238 | margin-bottom: 0 ; |
| 239 | margin-top: 0 ; |
| 240 | font: inherit } |
| 241 | |
| 242 | pre.literal-block, pre.doctest-block { |
| 243 | margin-left: 2em ; |
| 244 | margin-right: 2em } |
| 245 | |
| 246 | span.classifier { |
| 247 | font-family: sans-serif ; |
| 248 | font-style: oblique } |
| 249 | |
| 250 | span.classifier-delimiter { |
| 251 | font-family: sans-serif ; |
| 252 | font-weight: bold } |
| 253 | |
| 254 | span.interpreted { |
| 255 | font-family: sans-serif } |
| 256 | |
| 257 | span.option { |
| 258 | white-space: nowrap } |
| 259 | |
| 260 | span.pre { |
| 261 | white-space: pre } |
| 262 | |
| 263 | span.problematic { |
| 264 | color: red } |
| 265 | |
| 266 | span.section-subtitle { |
| 267 | /* font-size relative to parent (h1..h6 element) */ |
| 268 | font-size: 80% } |
| 269 | |
| 270 | table.citation { |
| 271 | border-left: solid 1px gray; |
| 272 | margin-left: 1px } |
| 273 | |
| 274 | table.docinfo { |
| 275 | margin: 2em 4em } |
| 276 | |
| 277 | table.docutils { |
| 278 | margin-top: 0.5em ; |
| 279 | margin-bottom: 0.5em } |
| 280 | |
| 281 | table.footnote { |
| 282 | border-left: solid 1px black; |
| 283 | margin-left: 1px } |
| 284 | |
| 285 | table.docutils td, table.docutils th, |
| 286 | table.docinfo td, table.docinfo th { |
| 287 | padding-left: 0.5em ; |
| 288 | padding-right: 0.5em ; |
| 289 | vertical-align: top } |
| 290 | |
| 291 | table.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 | |
| 297 | h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, |
| 298 | h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { |
| 299 | font-size: 100% } |
| 300 | |
| 301 | ul.auto-toc { |
| 302 | list-style-type: none } |
| 303 | |
| 304 | </style> |
| 305 | </head> |
| 306 | <body> |
Stephen Hines | 1868714 | 2011-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 Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 309 | |
| 310 | <div class="section" id="introduction"> |
| 311 | <h1>Introduction</h1> |
Stephen Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 312 | <p>llvm-rs-cc compiles a program in the Renderscript language to generate the |
| 313 | following files:</p> |
Shih-wei Liao | 19cc697 | 2011-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 |
| 316 | Virtual Machine) bitcode representation, which will be consumed on |
| 317 | an Android device by libbcc (in |
| 318 | platform/frameworks/compile/libbcc.git) to generate device-specific |
| 319 | executables.</li> |
| 320 | <li>Reflected APIs for Java. As a result, Android's Java developers can |
| 321 | invoke those APIs from their code.</li> |
| 322 | </ul> |
Stephen Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 323 | <p>Note that although Renderscript is C99-like, we enhance it with several |
Shih-wei Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 324 | distinct, effective features for Android programming. We will use |
Stephen Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 325 | some examples to illustrate these features.</p> |
| 326 | <p>llvm-rs-cc is run on the host and performs many aggressive optimizations. |
| 327 | As a result, libbcc on the device can be lightweight and focus on |
| 328 | machine-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 Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 330 | libslang and libbcc is depicted in the following figure:</p> |
| 331 | <pre class="literal-block"> |
| 332 | libslang 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 Hines | 1868714 | 2011-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 Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 349 | </li> |
| 350 | <li><p class="first"><em>-MD</em></p> |
Stephen Hines | 1868714 | 2011-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 Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 352 | </li> |
Stephen Hines | 1868714 | 2011-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 Liao | 29c3673 | 2011-01-20 05:48:20 -0800 | [diff] [blame] | 355 | </li> |
Shih-wei Liao | 19cc697 | 2011-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 <Android_Root_Directory> |
| 363 | </pre> |
Stephen Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 364 | <p>Using frameworks/base/tests/RenderScriptTests/Fountain as a simple app in both |
| 365 | Java and Renderscript, we can find the following command line in the build |
Shih-wei Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 366 | log:</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 Hines | 1868714 | 2011-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 Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 389 | C99. However, llvm-rs-cc goes beyond "clang -std=c99" and provides the |
| 390 | following 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 |
| 397 | developers can invoke those APIs.</p> |
Stephen Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 398 | <p>To do that, a Renderscript programmer should specify the package name, so |
Shih-wei Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 399 | that llvm-rs-cc knows the package expression and hence the directory |
| 400 | for 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 Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 405 | <p>In ScriptC_fountain.java, we have:</p> |
Shih-wei Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 406 | <pre class="literal-block"> |
| 407 | package 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 |
| 414 | version 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 Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 420 | <p>llvm-rs-cc automatically exports the "externalizable and defined" functions and |
Shih-wei Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 421 | variables to Android's Java side. That is, scripts are accessible from |
| 422 | Java.</p> |
| 423 | <p>For instance, for:</p> |
| 424 | <pre class="literal-block"> |
| 425 | int foo = 0; |
| 426 | </pre> |
Stephen Hines | 1868714 | 2011-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 Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 428 | <pre class="literal-block"> |
| 429 | void set_foo(int v)... |
| 430 | |
| 431 | int get_foo()... |
| 432 | </pre> |
| 433 | <p>This access takes the form of generated classes which provide access |
| 434 | to the functions and global variables within a script. In summary, |
| 435 | global variables and functions within a script that are not declared |
| 436 | static will generate get, set, or invoke methods. This provides a way |
Stephen Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 437 | to set the data within a script and call its functions.</p> |
Shih-wei Liao | 19cc697 | 2011-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"> |
| 440 | void 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"> |
| 446 | void 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"> |
| 456 | typedef struct __attribute__((packed, aligned(4))) Point { |
| 457 | float2 delta; |
| 458 | float2 position; |
| 459 | uchar4 color; |
| 460 | } Point_t; |
| 461 | |
| 462 | Point_t *point; |
| 463 | </pre> |
| 464 | <p>llvm-rs-cc generates one ScriptField*.java file for each user-defined |
Stephen Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 465 | struct. In this case, llvm-rs-cc will reflect two files, |
Shih-wei Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 466 | ScriptC_fountain.java and ScriptField_Point.java.</p> |
Stephen Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 467 | <p>Note that when the type of an exportable variable is a structure, Renderscript |
| 468 | developers should avoid using anonymous structs. This is because llvm-rs-cc |
| 469 | uses the struct name to identify the file, instead of the typedef name.</p> |
Shih-wei Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 470 | <p>For the generated Java files, using ScriptC_fountain.java as an |
Stephen Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 471 | example we also have:</p> |
Shih-wei Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 472 | <pre class="literal-block"> |
| 473 | void 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 Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 477 | methods in ScriptField_Point.java.</p> |
| 478 | <p>After binding, you can access the object with this method:</p> |
Shih-wei Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 479 | <pre class="literal-block"> |
| 480 | ScriptField_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. |
| 490 | void 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. |
| 496 | void set(Item i, int index, boolean copyNow) |
| 497 | |
| 498 | // The getter of Item array, which gets the *index*-th element |
| 499 | // of byte array. |
| 500 | Item get(int index) |
| 501 | |
| 502 | set_delta(int index, Float2 v, boolean copyNow) |
| 503 | |
| 504 | // The following is the individual setters and getters of |
| 505 | // each field of a struct. |
| 506 | public void set_delta(int index, Float2 v, boolean copyNow) |
| 507 | public void set_position(int index, Float2 v, boolean copyNow) |
| 508 | public void set_color(int index, Short4 v, boolean copyNow) |
| 509 | public Float2 get_delta(int index) |
| 510 | public Float2 get_position(int index) |
| 511 | public Short4 get_color(int index) |
| 512 | |
| 513 | // Copying all Item array to byte array (i.e., memory allocation). |
| 514 | void copyAll() |
| 515 | ... |
| 516 | </pre> |
| 517 | </div> |
Stephen Hines | 1868714 | 2011-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 Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 521 | <ul> |
Stephen Hines | 1868714 | 2011-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 Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 523 | These calls operate asynchronously and no assumptions should be made |
Stephen Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 524 | on whether a function called will have actually completed operation. If it |
| 525 | is necessary to wait for a function to complete, the Java application |
| 526 | may call the runtime finish() method, which will wait for all the script |
| 527 | threads to complete pending operations. A few special functions can also |
| 528 | exist:</p> |
| 529 | <ul> |
| 530 | <li><p class="first">The function <strong>init</strong> (if present) will be called once after the script |
Shih-wei Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 531 | is loaded. This is useful to initialize data or anything else the |
Stephen Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 532 | script may need before it can be used. The init function may not depend |
| 533 | on globals initialized from Java as it will be called before these |
| 534 | can be initialized. The function signature for init must be:</p> |
| 535 | <pre class="literal-block"> |
| 536 | void init(void); |
| 537 | </pre> |
| 538 | </li> |
| 539 | <li><p class="first">The function <strong>root</strong> is a special function for graphics. This function |
| 540 | will be called when a script must redraw its contents. No |
Shih-wei Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 541 | assumptions should be made as to when this function will be |
Stephen Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 542 | called. It will only be called if the script is bound as a graphics root. |
| 543 | Calls to this function will be synchronized with data updates and |
Shih-wei Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 544 | other invocations from Java. Thus the script will not change due |
Stephen Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 545 | to external influence in the middle of running <strong>root</strong>. The return value |
| 546 | indicates to the runtime when the function should be called again to |
Shih-wei Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 547 | redraw in the future. A return value of 0 indicates that no |
Stephen Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 548 | redraw is necessary until something changes on the Java side. Any |
| 549 | positive integer indicates a time in milliseconds that the runtime should |
| 550 | wait before calling root again to render another frame. The function |
| 551 | signature for a graphics root functions is as follows:</p> |
| 552 | <pre class="literal-block"> |
| 553 | int 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. |
| 557 | Such a function has the following signature:</p> |
| 558 | <pre class="literal-block"> |
| 559 | void 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 |
| 562 | above can be omitted, although at least one of in/out must be present. |
| 563 | If both in and out are present, root must only be invoked with types of |
| 564 | the same exact dimensionality (i.e. matching X and Y values for dimension). |
| 565 | This root function is accessible through the Renderscript language |
| 566 | construct <strong>forEach</strong>. We also reflect a Java version to access this |
| 567 | function as <strong>forEach_root</strong> (for API levels of 14+). An example of this |
| 568 | can 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 |
| 571 | llvm-rs-cc. This function cleans up any global variable that contains |
| 572 | (or is) a reference counted Renderscript object type (such as an |
| 573 | rs_allocation, rs_font, or rs_script). This function will be invoked |
| 574 | implicitly by the Renderscript runtime during script teardown.</p> |
| 575 | </li> |
Shih-wei Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 576 | </ul> |
| 577 | </li> |
Stephen Hines | 1868714 | 2011-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 |
| 579 | from Java. The Java instance will cache the value or object set and |
Shih-wei Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 580 | provide return methods to retrieve this value. If a script updates |
| 581 | the value, this update will not propagate back to the Java class. |
Stephen Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 582 | Initializers, if present, will also initialize the cached Java value. |
Shih-wei Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 583 | This provides a convenient way to declare constants within a script and |
Stephen Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 584 | make them accessible to the Java runtime. If the script declares a |
Shih-wei Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 585 | variable const, only the get methods will be generated.</p> |
| 586 | <p>Globals within a script are considered local to the script. They |
| 587 | cannot be accessed by other scripts and are in effect always 'static' |
Stephen Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 588 | in the traditional C sense. Static here is used to control if |
| 589 | accessors are generated. Static continues to mean <em>not |
Shih-wei Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 590 | externally visible</em> and thus prevents the generation of |
Stephen Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 591 | accessors. Globals are persistent across invocations of a script and |
Shih-wei Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 592 | thus 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 Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 594 | type is basic non-pointer types. Types defined in rs_types.rsh may also be |
| 595 | used. For the non-pointer class, get and set methods are generated for |
Shih-wei Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 596 | Java. Globals of single pointer types behave differently. These may |
| 597 | use more complex types. Simple structures composed of the types in |
| 598 | rs_types.rsh may also be used. These globals generate bind points in |
Stephen Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 599 | Java. 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 |
| 601 | structure. Binding an allocation in Java effectively sets the |
Shih-wei Liao | 19cc697 | 2011-01-20 04:34:38 -0800 | [diff] [blame] | 602 | pointer in the script. Bind points marked const indicate to the |
| 603 | runtime that the script will not modify the contents of an allocation. |
| 604 | This 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 |
| 611 | vector processing in environments where the processors provide vector |
| 612 | instructions.</p> |
| 613 | <p>On non-vector systems the same code will continue to run but without |
| 614 | the performance advantage. Function overloading is also supported. |
| 615 | This allows the runtime to support vector version of the basic math |
| 616 | routines 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 Hines | 1868714 | 2011-09-02 19:07:14 -0700 | [diff] [blame] | 620 | <li><em>float3 sin(float3);</em></li> |
Shih-wei Liao | 19cc697 | 2011-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> |