README.html
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/" /> 7 <title>llvm-rs-cc: Compiler for Renderscript language</title> 8 <style type="text/css"> 9 10 /* 11 :Author: David Goodger (goodger (a] 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> 307 <div class="document" id="llvm-rs-cc-compiler-for-renderscript-language"> 308 <h1 class="title">llvm-rs-cc: Compiler for Renderscript language</h1> 309 310 <div class="section" id="introduction"> 311 <h1>Introduction</h1> 312 <p>llvm-rs-cc compiles a program in the Renderscript language to generate the 313 following files:</p> 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> 323 <p>Note that although Renderscript is C99-like, we enhance it with several 324 distinct, effective features for Android programming. We will use 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 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> 348 <p>This option <em>-d</em> sets the directory for writing dependence information.</p> 349 </li> 350 <li><p class="first"><em>-MD</em></p> 351 <p>Note that <em>-MD</em> will tell llvm-rs-cc to output dependence information.</p> 352 </li> 353 <li><p class="first"><em>-a $(EXTRA_TARGETS)</em></p> 354 <p>Specifies additional target dependencies.</p> 355 </li> 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> 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 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/script_api/include \ 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> 388 <p>fountain.rs is in the Renderscript language, which is based on the standard 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> 398 <p>To do that, a Renderscript programmer should specify the package name, so 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> 405 <p>In ScriptC_fountain.java, we have:</p> 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> 420 <p>llvm-rs-cc automatically exports the "externalizable and defined" functions and 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> 427 <p>In ScriptC_fountain.java, llvm-rs-cc will reflect the following methods:</p> 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 437 to set the data within a script and call its functions.</p> 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 465 struct. In this case, llvm-rs-cc will reflect two files, 466 ScriptC_fountain.java and ScriptField_Point.java.</p> 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> 470 <p>For the generated Java files, using ScriptC_fountain.java as an 471 example we also have:</p> 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 477 methods in ScriptField_Point.java.</p> 478 <p>After binding, you can access the object with this method:</p> 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> 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> 521 <ul> 522 <li><p class="first">In terms of a script's global functions, they can be called from Java. 523 These calls operate asynchronously and no assumptions should be made 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 531 is loaded. This is useful to initialize data or anything else the 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 541 assumptions should be made as to when this function will be 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 544 other invocations from Java. Thus the script will not change due 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 547 redraw in the future. A return value of 0 indicates that no 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> 576 </ul> 577 </li> 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 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. 582 Initializers, if present, will also initialize the cached Java value. 583 This provides a convenient way to declare constants within a script and 584 make them accessible to the Java runtime. If the script declares a 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' 588 in the traditional C sense. Static here is used to control if 589 accessors are generated. Static continues to mean <em>not 590 externally visible</em> and thus prevents the generation of 591 accessors. Globals are persistent across invocations of a script and 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 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 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 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 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> 620 <li><em>float3 sin(float3);</em></li> 621 <li><em>float4 sin(float4);</em></li> 622 </ul> 623 </div> 624 </div> 625 </body> 626 </html> 627
README.rst
1 ============================================== 2 llvm-rs-cc: Compiler for Renderscript language 3 ============================================== 4 5 6 Introduction 7 ------------ 8 9 llvm-rs-cc compiles a program in the Renderscript language to generate the 10 following files: 11 12 * Bitcode file. Note that the bitcode here denotes the LLVM (Low-Level 13 Virtual Machine) bitcode representation, which will be consumed on 14 an Android device by libbcc (in 15 platform/frameworks/compile/libbcc.git) to generate device-specific 16 executables. 17 18 * Reflected APIs for Java. As a result, Android's Java developers can 19 invoke those APIs from their code. 20 21 Note that although Renderscript is C99-like, we enhance it with several 22 distinct, effective features for Android programming. We will use 23 some examples to illustrate these features. 24 25 llvm-rs-cc is run on the host and performs many aggressive optimizations. 26 As a result, libbcc on the device can be lightweight and focus on 27 machine-dependent code generation for some input bitcode. 28 29 llvm-rs-cc is a driver on top of libslang. The architecture of 30 libslang and libbcc is depicted in the following figure:: 31 32 libslang libbcc 33 | \ | 34 | \ | 35 clang llvm 36 37 38 Usage 39 ----- 40 41 * *-o $(PRIVATE_RS_OUTPUT_DIR)/res/raw* 42 43 This option specifies the directory for outputting a .bc file. 44 45 * *-p $(PRIVATE_RS_OUTPUT_DIR)/src* 46 47 The option *-p* denotes the directory for outputting the reflected Java files. 48 49 * *-d $(PRIVATE_RS_OUTPUT_DIR)* 50 51 This option *-d* sets the directory for writing dependence information. 52 53 * *-MD* 54 55 Note that *-MD* will tell llvm-rs-cc to output dependence information. 56 57 * *-a $(EXTRA_TARGETS)* 58 59 Specifies additional target dependencies. 60 61 Example Command 62 --------------- 63 64 First:: 65 66 $ cd <Android_Root_Directory> 67 68 Using frameworks/base/tests/RenderScriptTests/Fountain as a simple app in both 69 Java and Renderscript, we can find the following command line in the build 70 log:: 71 72 $ out/host/linux-x86/bin/llvm-rs-cc \ 73 -o out/target/common/obj/APPS/Fountain_intermediates/src/renderscript/res/raw \ 74 -p out/target/common/obj/APPS/Fountain_intermediates/src/renderscript/src \ 75 -d out/target/common/obj/APPS/Fountain_intermediates/src/renderscript \ 76 -a out/target/common/obj/APPS/Fountain_intermediates/src/RenderScript.stamp \ 77 -MD \ 78 -I frameworks/base/libs/rs/script_api/include \ 79 -I external/clang/lib/Headers \ 80 frameworks/base/libs/rs/java/Fountain/src/com/android/fountain/fountain.rs 81 82 This command will generate: 83 84 * **fountain.bc** 85 86 * **ScriptC_fountain.java** 87 88 * **ScriptField_Point.java** 89 90 The **Script\*.java** files above will be documented below. 91 92 93 Example Program: fountain.rs 94 ---------------------------- 95 96 fountain.rs is in the Renderscript language, which is based on the standard 97 C99. However, llvm-rs-cc goes beyond "clang -std=c99" and provides the 98 following important features: 99 100 1. Pragma 101 --------- 102 103 * *#pragma rs java_package_name([PACKAGE_NAME])* 104 105 The ScriptC_[SCRIPT_NAME].java has to be packaged so that Java 106 developers can invoke those APIs. 107 108 To do that, a Renderscript programmer should specify the package name, so 109 that llvm-rs-cc knows the package expression and hence the directory 110 for outputting ScriptC_[SCRIPT_NAME].java. 111 112 In fountain.rs, we have:: 113 114 #pragma rs java_package_name(com.android.fountain) 115 116 In ScriptC_fountain.java, we have:: 117 118 package com.android.fountain 119 120 Note that the ScriptC_fountain.java will be generated inside 121 ./com/android/fountain/. 122 123 * #pragma version(1) 124 125 This pragma is for evolving the language. Currently we are at 126 version 1 of the language. 127 128 129 2. Basic Reflection: Export Variables and Functions 130 --------------------------------------------------- 131 132 llvm-rs-cc automatically exports the "externalizable and defined" functions and 133 variables to Android's Java side. That is, scripts are accessible from 134 Java. 135 136 For instance, for:: 137 138 int foo = 0; 139 140 In ScriptC_fountain.java, llvm-rs-cc will reflect the following methods:: 141 142 void set_foo(int v)... 143 144 int get_foo()... 145 146 This access takes the form of generated classes which provide access 147 to the functions and global variables within a script. In summary, 148 global variables and functions within a script that are not declared 149 static will generate get, set, or invoke methods. This provides a way 150 to set the data within a script and call its functions. 151 152 Take the addParticles function in fountain.rs as an example:: 153 154 void addParticles(int rate, float x, float y, int index, bool newColor) { 155 ... 156 } 157 158 llvm-rs-cc will genearte ScriptC_fountain.java as follows:: 159 160 void invoke_addParticles(int rate, float x, float y, 161 int index, bool newColor) { 162 ... 163 } 164 165 166 3. Export User-Defined Structs 167 ------------------------------ 168 169 In fountain.rs, we have:: 170 171 typedef struct __attribute__((packed, aligned(4))) Point { 172 float2 delta; 173 float2 position; 174 uchar4 color; 175 } Point_t; 176 177 Point_t *point; 178 179 llvm-rs-cc generates one ScriptField*.java file for each user-defined 180 struct. In this case, llvm-rs-cc will reflect two files, 181 ScriptC_fountain.java and ScriptField_Point.java. 182 183 Note that when the type of an exportable variable is a structure, Renderscript 184 developers should avoid using anonymous structs. This is because llvm-rs-cc 185 uses the struct name to identify the file, instead of the typedef name. 186 187 For the generated Java files, using ScriptC_fountain.java as an 188 example we also have:: 189 190 void bind_point(ScriptField_Point v) 191 192 This binds your object with the allocated memory. 193 194 You can bind the struct(e.g., Point), using the setter and getter 195 methods in ScriptField_Point.java. 196 197 After binding, you can access the object with this method:: 198 199 ScriptField_Point get_point() 200 201 In ScriptField_Point_s.java:: 202 203 ... 204 // Copying the Item, which is the object that stores every 205 // fields of struct, to the *index*\-th entry of byte array. 206 // 207 // In general, this method would not be invoked directly 208 // but is used to implement the setter. 209 void copyToArray(Item i, int index) 210 211 // The setter of Item array, 212 // index: the index of the Item array 213 // copyNow: If true, it will be copied to the *index*\-th entry 214 // of byte array. 215 void set(Item i, int index, boolean copyNow) 216 217 // The getter of Item array, which gets the *index*-th element 218 // of byte array. 219 Item get(int index) 220 221 set_delta(int index, Float2 v, boolean copyNow) 222 223 // The following is the individual setters and getters of 224 // each field of a struct. 225 public void set_delta(int index, Float2 v, boolean copyNow) 226 public void set_position(int index, Float2 v, boolean copyNow) 227 public void set_color(int index, Short4 v, boolean copyNow) 228 public Float2 get_delta(int index) 229 public Float2 get_position(int index) 230 public Short4 get_color(int index) 231 232 // Copying all Item array to byte array (i.e., memory allocation). 233 void copyAll() 234 ... 235 236 237 4. Summary of the Java Reflection above 238 --------------------------------------- 239 240 This section summarizes the high-level design of Renderscript's reflection. 241 242 * In terms of a script's global functions, they can be called from Java. 243 These calls operate asynchronously and no assumptions should be made 244 on whether a function called will have actually completed operation. If it 245 is necessary to wait for a function to complete, the Java application 246 may call the runtime finish() method, which will wait for all the script 247 threads to complete pending operations. A few special functions can also 248 exist: 249 250 * The function **init** (if present) will be called once after the script 251 is loaded. This is useful to initialize data or anything else the 252 script may need before it can be used. The init function may not depend 253 on globals initialized from Java as it will be called before these 254 can be initialized. The function signature for init must be:: 255 256 void init(void); 257 258 * The function **root** is a special function for graphics. This function 259 will be called when a script must redraw its contents. No 260 assumptions should be made as to when this function will be 261 called. It will only be called if the script is bound as a graphics root. 262 Calls to this function will be synchronized with data updates and 263 other invocations from Java. Thus the script will not change due 264 to external influence in the middle of running **root**. The return value 265 indicates to the runtime when the function should be called again to 266 redraw in the future. A return value of 0 indicates that no 267 redraw is necessary until something changes on the Java side. Any 268 positive integer indicates a time in milliseconds that the runtime should 269 wait before calling root again to render another frame. The function 270 signature for a graphics root functions is as follows:: 271 272 int root(void); 273 274 * It is also possible to create a purely compute-based **root** function. 275 Such a function has the following signature:: 276 277 void root(const T1 *in, T2 *out, const T3 *usrData, uint32_t x, uint32_t y); 278 279 T1, T2, and T3 represent any supported Renderscript type. Any parameters 280 above can be omitted, although at least one of in/out must be present. 281 If both in and out are present, root must only be invoked with types of 282 the same exact dimensionality (i.e. matching X and Y values for dimension). 283 This root function is accessible through the Renderscript language 284 construct **forEach**. We also reflect a Java version to access this 285 function as **forEach_root** (for API levels of 14+). An example of this 286 can be seen in the Android SDK sample for HelloCompute. 287 288 * The function **.rs.dtor** is a function that is sometimes generated by 289 llvm-rs-cc. This function cleans up any global variable that contains 290 (or is) a reference counted Renderscript object type (such as an 291 rs_allocation, rs_font, or rs_script). This function will be invoked 292 implicitly by the Renderscript runtime during script teardown. 293 294 * In terms of a script's global data, global variables can be written 295 from Java. The Java instance will cache the value or object set and 296 provide return methods to retrieve this value. If a script updates 297 the value, this update will not propagate back to the Java class. 298 Initializers, if present, will also initialize the cached Java value. 299 This provides a convenient way to declare constants within a script and 300 make them accessible to the Java runtime. If the script declares a 301 variable const, only the get methods will be generated. 302 303 Globals within a script are considered local to the script. They 304 cannot be accessed by other scripts and are in effect always 'static' 305 in the traditional C sense. Static here is used to control if 306 accessors are generated. Static continues to mean *not 307 externally visible* and thus prevents the generation of 308 accessors. Globals are persistent across invocations of a script and 309 thus may be used to hold data from run to run. 310 311 Globals of two types may be reflected into the Java class. The first 312 type is basic non-pointer types. Types defined in rs_types.rsh may also be 313 used. For the non-pointer class, get and set methods are generated for 314 Java. Globals of single pointer types behave differently. These may 315 use more complex types. Simple structures composed of the types in 316 rs_types.rsh may also be used. These globals generate bind points in 317 Java. If the type is a structure they also generate an appropriate 318 **Field** class that is used to pack and unpack the contents of the 319 structure. Binding an allocation in Java effectively sets the 320 pointer in the script. Bind points marked const indicate to the 321 runtime that the script will not modify the contents of an allocation. 322 This may allow the runtime to make more effective use of threads. 323 324 325 5. Vector Types 326 --------------- 327 328 Vector types such as float2, float4, and uint4 are included to support 329 vector processing in environments where the processors provide vector 330 instructions. 331 332 On non-vector systems the same code will continue to run but without 333 the performance advantage. Function overloading is also supported. 334 This allows the runtime to support vector version of the basic math 335 routines without the need for special naming. For instance, 336 337 * *float sin(float);* 338 339 * *float2 sin(float2);* 340 341 * *float3 sin(float3);* 342 343 * *float4 sin(float4);* 344
