1page.title=RenderScript Kernel Launch Functions and Types 2 3@jd:body 4 5<div class='renderscript'> 6<h2>Overview</h2> 7<p> The <a href='rs_for_each.html#android_rs:rsForEach'>rsForEach</a>() and <a href='rs_for_each.html#android_rs:rsForEachWithOptions'>rsForEachWithOptions</a>() functions are used to launch foreach kernels. 8</p> 9 10<p> The other functions are used to get the characteristics of the invocation of 11an executing kernel, like dimensions and current indices. These functions take 12a <a href='rs_for_each.html#android_rs:rs_kernel_context'>rs_kernel_context</a> as argument. 13</p> 14<h2>Summary</h2> 15<table class='jd-sumtable'><tbody> 16 <tr><th colspan='2'>Types</th></tr> 17 <tr class='alt-color api apilevel-1'> 18 <td class='jd-linkcol'> 19 <a href='rs_for_each.html#android_rs:rs_for_each_strategy_t'>rs_for_each_strategy_t</a> 20 </td> 21 <td class='jd-descrcol' width='100%'> 22 Suggested cell processing order 23 </td> 24 </tr> 25 <tr class='alt-color api apilevel-1'> 26 <td class='jd-linkcol'> 27 <a href='rs_for_each.html#android_rs:rs_kernel'>rs_kernel</a> 28 </td> 29 <td class='jd-descrcol' width='100%'> 30 Handle to a kernel function 31 </td> 32 </tr> 33 <tr class='alt-color api apilevel-1'> 34 <td class='jd-linkcol'> 35 <a href='rs_for_each.html#android_rs:rs_kernel_context'>rs_kernel_context</a> 36 </td> 37 <td class='jd-descrcol' width='100%'> 38 Handle to a kernel invocation context 39 </td> 40 </tr> 41 <tr class='alt-color api apilevel-1'> 42 <td class='jd-linkcol'> 43 <a href='rs_for_each.html#android_rs:rs_script_call_t'>rs_script_call_t</a> 44 </td> 45 <td class='jd-descrcol' width='100%'> 46 Cell iteration information 47 </td> 48 </tr> 49</tbody></table> 50<table class='jd-sumtable'><tbody> 51 <tr><th colspan='2'>Functions</th></tr> 52 <tr class='alt-color api apilevel-1'> 53 <td class='jd-linkcol'> 54 <a href='rs_for_each.html#android_rs:rsForEach'>rsForEach</a> 55 </td> 56 <td class='jd-descrcol' width='100%'> 57 Launches a kernel 58 </td> 59 </tr> 60 <tr class='alt-color api apilevel-1'> 61 <td class='jd-linkcol'> 62 <a href='rs_for_each.html#android_rs:rsForEachWithOptions'>rsForEachWithOptions</a> 63 </td> 64 <td class='jd-descrcol' width='100%'> 65 Launches a kernel with options 66 </td> 67 </tr> 68 <tr class='alt-color api apilevel-1'> 69 <td class='jd-linkcol'> 70 <a href='rs_for_each.html#android_rs:rsGetArray0'>rsGetArray0</a> 71 </td> 72 <td class='jd-descrcol' width='100%'> 73 Index in the Array0 dimension for the specified kernel context 74 </td> 75 </tr> 76 <tr class='alt-color api apilevel-1'> 77 <td class='jd-linkcol'> 78 <a href='rs_for_each.html#android_rs:rsGetArray1'>rsGetArray1</a> 79 </td> 80 <td class='jd-descrcol' width='100%'> 81 Index in the Array1 dimension for the specified kernel context 82 </td> 83 </tr> 84 <tr class='alt-color api apilevel-1'> 85 <td class='jd-linkcol'> 86 <a href='rs_for_each.html#android_rs:rsGetArray2'>rsGetArray2</a> 87 </td> 88 <td class='jd-descrcol' width='100%'> 89 Index in the Array2 dimension for the specified kernel context 90 </td> 91 </tr> 92 <tr class='alt-color api apilevel-1'> 93 <td class='jd-linkcol'> 94 <a href='rs_for_each.html#android_rs:rsGetArray3'>rsGetArray3</a> 95 </td> 96 <td class='jd-descrcol' width='100%'> 97 Index in the Array3 dimension for the specified kernel context 98 </td> 99 </tr> 100 <tr class='alt-color api apilevel-1'> 101 <td class='jd-linkcol'> 102 <a href='rs_for_each.html#android_rs:rsGetDimArray0'>rsGetDimArray0</a> 103 </td> 104 <td class='jd-descrcol' width='100%'> 105 Size of the Array0 dimension for the specified kernel context 106 </td> 107 </tr> 108 <tr class='alt-color api apilevel-1'> 109 <td class='jd-linkcol'> 110 <a href='rs_for_each.html#android_rs:rsGetDimArray1'>rsGetDimArray1</a> 111 </td> 112 <td class='jd-descrcol' width='100%'> 113 Size of the Array1 dimension for the specified kernel context 114 </td> 115 </tr> 116 <tr class='alt-color api apilevel-1'> 117 <td class='jd-linkcol'> 118 <a href='rs_for_each.html#android_rs:rsGetDimArray2'>rsGetDimArray2</a> 119 </td> 120 <td class='jd-descrcol' width='100%'> 121 Size of the Array2 dimension for the specified kernel context 122 </td> 123 </tr> 124 <tr class='alt-color api apilevel-1'> 125 <td class='jd-linkcol'> 126 <a href='rs_for_each.html#android_rs:rsGetDimArray3'>rsGetDimArray3</a> 127 </td> 128 <td class='jd-descrcol' width='100%'> 129 Size of the Array3 dimension for the specified kernel context 130 </td> 131 </tr> 132 <tr class='alt-color api apilevel-1'> 133 <td class='jd-linkcol'> 134 <a href='rs_for_each.html#android_rs:rsGetDimHasFaces'>rsGetDimHasFaces</a> 135 </td> 136 <td class='jd-descrcol' width='100%'> 137 Presence of more than one face for the specified kernel context 138 </td> 139 </tr> 140 <tr class='alt-color api apilevel-1'> 141 <td class='jd-linkcol'> 142 <a href='rs_for_each.html#android_rs:rsGetDimLod'>rsGetDimLod</a> 143 </td> 144 <td class='jd-descrcol' width='100%'> 145 Number of levels of detail for the specified kernel context 146 </td> 147 </tr> 148 <tr class='alt-color api apilevel-1'> 149 <td class='jd-linkcol'> 150 <a href='rs_for_each.html#android_rs:rsGetDimX'>rsGetDimX</a> 151 </td> 152 <td class='jd-descrcol' width='100%'> 153 Size of the X dimension for the specified kernel context 154 </td> 155 </tr> 156 <tr class='alt-color api apilevel-1'> 157 <td class='jd-linkcol'> 158 <a href='rs_for_each.html#android_rs:rsGetDimY'>rsGetDimY</a> 159 </td> 160 <td class='jd-descrcol' width='100%'> 161 Size of the Y dimension for the specified kernel context 162 </td> 163 </tr> 164 <tr class='alt-color api apilevel-1'> 165 <td class='jd-linkcol'> 166 <a href='rs_for_each.html#android_rs:rsGetDimZ'>rsGetDimZ</a> 167 </td> 168 <td class='jd-descrcol' width='100%'> 169 Size of the Z dimension for the specified kernel context 170 </td> 171 </tr> 172 <tr class='alt-color api apilevel-1'> 173 <td class='jd-linkcol'> 174 <a href='rs_for_each.html#android_rs:rsGetFace'>rsGetFace</a> 175 </td> 176 <td class='jd-descrcol' width='100%'> 177 Coordinate of the Face for the specified kernel context 178 </td> 179 </tr> 180 <tr class='alt-color api apilevel-1'> 181 <td class='jd-linkcol'> 182 <a href='rs_for_each.html#android_rs:rsGetLod'>rsGetLod</a> 183 </td> 184 <td class='jd-descrcol' width='100%'> 185 Index in the Levels of Detail dimension for the specified kernel context 186 </td> 187 </tr> 188</tbody></table> 189<h2>Types</h2> 190<a name='android_rs:rs_for_each_strategy_t'></a> 191<div class='jd-details'> 192 <h4 class='jd-details-title'> 193 <span class='sympad'>rs_for_each_strategy_t</span> 194 <span class='normal'>: Suggested cell processing order</span> 195 </h4> 196 <div class='jd-details-descr'> 197<p>An enum with the following values: 198</p> 199 <table class='jd-tagtable'><tbody> 200 <tr><th>RS_FOR_EACH_STRATEGY_SERIAL = 0</th><td>Prefer contiguous memory regions.</td></tr> 201 <tr><th>RS_FOR_EACH_STRATEGY_DONT_CARE = 1</th><td>No prefrences.</td></tr> 202 <tr><th>RS_FOR_EACH_STRATEGY_DST_LINEAR = 2</th><td>Prefer DST.</td></tr> 203 <tr><th>RS_FOR_EACH_STRATEGY_TILE_SMALL = 3</th><td>Prefer processing small rectangular regions.</td></tr> 204 <tr><th>RS_FOR_EACH_STRATEGY_TILE_MEDIUM = 4</th><td>Prefer processing medium rectangular regions.</td></tr> 205 <tr><th>RS_FOR_EACH_STRATEGY_TILE_LARGE = 5</th><td>Prefer processing large rectangular regions.</td></tr> 206 </tbody></table><br/> 207<p> This type is used to suggest how the invoked kernel should iterate over the cells of the 208allocations. This is a hint only. Implementations may not follow the suggestion. 209</p> 210 211<p> This specification can help the caching behavior of the running kernel, e.g. the cache 212locality when the processing is distributed over multiple cores. 213</p> 214 </div> 215</div> 216 217<a name='android_rs:rs_kernel'></a> 218<div class='jd-details'> 219 <h4 class='jd-details-title'> 220 <span class='sympad'>rs_kernel</span> 221 <span class='normal'>: Handle to a kernel function</span> 222 </h4> 223 <div class='jd-details-descr'> 224<p>A typedef of: void* Added in <a href='http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels'>API level 24</a> 225</p> 226<p> An opaque type for a function that is defined with the kernel attribute. A value 227 of this type can be used in a <a href='rs_for_each.html#android_rs:rsForEach'>rsForEach</a> call to launch a kernel. 228</p> 229 </div> 230</div> 231 232<a name='android_rs:rs_kernel_context'></a> 233<div class='jd-details'> 234 <h4 class='jd-details-title'> 235 <span class='sympad'>rs_kernel_context</span> 236 <span class='normal'>: Handle to a kernel invocation context</span> 237 </h4> 238 <div class='jd-details-descr'> 239<p>A typedef of: const struct rs_kernel_context_t * Added in <a href='http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels'>API level 23</a> 240</p> 241<p> The kernel context contains common characteristics of the allocations being iterated 242over, like dimensions. It also contains rarely used indices of the currently processed 243cell, like the Array0 index or the current level of detail. 244</p> 245 246<p> You can access the kernel context by adding a special parameter named "context" of type 247rs_kernel_context to your kernel function. See <a href='rs_for_each.html#android_rs:rsGetDimX'>rsGetDimX</a>() and <a href='rs_for_each.html#android_rs:rsGetArray0'>rsGetArray0</a>() for examples. 248</p> 249 </div> 250</div> 251 252<a name='android_rs:rs_script_call_t'></a> 253<div class='jd-details'> 254 <h4 class='jd-details-title'> 255 <span class='sympad'>rs_script_call_t</span> 256 <span class='normal'>: Cell iteration information</span> 257 </h4> 258 <div class='jd-details-descr'> 259<p>A structure with the following fields: </p> 260 <table class='jd-tagtable'><tbody> 261 <tr><th>rs_for_each_strategy_t strategy</th><td>Currently ignored. In the future, will be suggested cell iteration strategy.</td></tr> 262 <tr><th>uint32_t xStart</th><td>Starting index in the X dimension.</td></tr> 263 <tr><th>uint32_t xEnd</th><td>Ending index (exclusive) in the X dimension.</td></tr> 264 <tr><th>uint32_t yStart</th><td>Starting index in the Y dimension.</td></tr> 265 <tr><th>uint32_t yEnd</th><td>Ending index (exclusive) in the Y dimension.</td></tr> 266 <tr><th>uint32_t zStart</th><td>Starting index in the Z dimension.</td></tr> 267 <tr><th>uint32_t zEnd</th><td>Ending index (exclusive) in the Z dimension.</td></tr> 268 <tr><th>uint32_t arrayStart</th><td>Starting index in the Array0 dimension.</td></tr> 269 <tr><th>uint32_t arrayEnd</th><td>Ending index (exclusive) in the Array0 dimension.</td></tr> 270 <tr><th>uint32_t array1Start</th><td>Starting index in the Array1 dimension.</td></tr> 271 <tr><th>uint32_t array1End</th><td>Ending index (exclusive) in the Array1 dimension.</td></tr> 272 <tr><th>uint32_t array2Start</th><td>Starting index in the Array2 dimension.</td></tr> 273 <tr><th>uint32_t array2End</th><td>Ending index (exclusive) in the Array2 dimension.</td></tr> 274 <tr><th>uint32_t array3Start</th><td>Starting index in the Array3 dimension.</td></tr> 275 <tr><th>uint32_t array3End</th><td>Ending index (exclusive) in the Array3 dimension.</td></tr> 276 </tbody></table><br/> 277<p> This structure is used to provide iteration information to a rsForEach call. 278It is currently used to restrict processing to a subset of cells. In future 279versions, it will also be used to provide hint on how to best iterate over 280the cells. 281</p> 282 283<p> The Start fields are inclusive and the End fields are exclusive. For example, to iterate 284over cells 4, 5, 6, and 7 in the X dimension, set xStart to 4 and xEnd to 8. 285</p> 286 </div> 287</div> 288 289<h2>Functions</h2> 290<a name='android_rs:rsForEach'></a> 291<div class='jd-details'> 292 <h4 class='jd-details-title'> 293 <span class='sympad'>rsForEach</span> 294 <span class='normal'>: Launches a kernel</span> 295 </h4> 296 <div class='jd-details-descr'> 297 <table class='jd-tagtable'><tbody> 298 <tr> 299 <td>void rsForEach(<a href='rs_for_each.html#android_rs:rs_kernel'>rs_kernel</a> kernel, ... ...); 300</td> 301 <td> Added in <a href='http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels'>API level 24</a> 302 </td> 303 </tr> 304 <tr> 305 <td>void rsForEach(<a href='rs_object_types.html#android_rs:rs_script'>rs_script</a> script, <a href='rs_object_types.html#android_rs:rs_allocation'>rs_allocation</a> input, <a href='rs_object_types.html#android_rs:rs_allocation'>rs_allocation</a> output); 306</td> 307 <td> <a href='http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels'>API level 14 - 23</a> 308 </td> 309 </tr> 310 <tr> 311 <td>void rsForEach(<a href='rs_object_types.html#android_rs:rs_script'>rs_script</a> script, <a href='rs_object_types.html#android_rs:rs_allocation'>rs_allocation</a> input, <a href='rs_object_types.html#android_rs:rs_allocation'>rs_allocation</a> output, const void* usrData); 312</td> 313 <td> Removed from <a href='http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels'>API level 14 and higher</a> 314 </td> 315 </tr> 316 <tr> 317 <td>void rsForEach(<a href='rs_object_types.html#android_rs:rs_script'>rs_script</a> script, <a href='rs_object_types.html#android_rs:rs_allocation'>rs_allocation</a> input, <a href='rs_object_types.html#android_rs:rs_allocation'>rs_allocation</a> output, const void* usrData, const <a href='rs_for_each.html#android_rs:rs_script_call_t'>rs_script_call_t</a>* sc); 318</td> 319 <td> Removed from <a href='http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels'>API level 14 and higher</a> 320 </td> 321 </tr> 322 <tr> 323 <td>void rsForEach(<a href='rs_object_types.html#android_rs:rs_script'>rs_script</a> script, <a href='rs_object_types.html#android_rs:rs_allocation'>rs_allocation</a> input, <a href='rs_object_types.html#android_rs:rs_allocation'>rs_allocation</a> output, const void* usrData, <a href='rs_value_types.html#android_rs:size_t'>size_t</a> usrDataLen); 324</td> 325 <td> <a href='http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels'>API level 14 - 20</a> 326 </td> 327 </tr> 328 <tr> 329 <td>void rsForEach(<a href='rs_object_types.html#android_rs:rs_script'>rs_script</a> script, <a href='rs_object_types.html#android_rs:rs_allocation'>rs_allocation</a> input, <a href='rs_object_types.html#android_rs:rs_allocation'>rs_allocation</a> output, const void* usrData, <a href='rs_value_types.html#android_rs:size_t'>size_t</a> usrDataLen, const <a href='rs_for_each.html#android_rs:rs_script_call_t'>rs_script_call_t</a>* sc); 330</td> 331 <td> <a href='http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels'>API level 14 - 20</a> 332 </td> 333 </tr> 334 </tbody></table> 335 </div> 336 <div class='jd-tagdata'> <h5 class='jd-tagtitle'>Parameters</h5> 337 <table class='jd-tagtable'><tbody> 338 <tr><th>script</th><td>Script to call.</td></tr> 339 <tr><th>input</th><td>Allocation to source data from.</td></tr> 340 <tr><th>output</th><td>Allocation to write data into.</td></tr> 341 <tr><th>usrData</th><td>User defined data to pass to the script. May be NULL.</td></tr> 342 <tr><th>sc</th><td>Extra control information used to select a sub-region of the allocation to be processed or suggest a walking strategy. May be NULL.</td></tr> 343 <tr><th>usrDataLen</th><td>Size of the userData structure. This will be used to perform a shallow copy of the data if necessary.</td></tr> 344 <tr><th>kernel</th><td>Function designator of the kernel function to call, which must be defined with the kernel attribute.</td></tr> 345 <tr><th>...</th><td>Input and output allocations</td></tr> 346 </tbody></table> 347 </div> 348 <div class='jd-tagdata jd-tagdescr'> 349<p> Runs the kernel over zero or more input allocations. They are passed after the 350<a href='rs_for_each.html#android_rs:rs_kernel'>rs_kernel</a> argument. If the specified kernel returns a value, an output allocation 351must be specified as the last argument. All input allocations, 352and the output allocation if it exists, must have the same dimensions. 353</p> 354 355<p> This is a synchronous function. A call to this function only returns after all 356the work has completed. If the kernel 357function returns any value, the call waits until all results have been written 358to the output allocation. 359</p> 360 361<p> Up to API level 23, the kernel is implicitly specified as the kernel named 362"root" in the specified script, and only a single input allocation can be used. 363Starting in API level 24, an arbitrary kernel function can be used, 364as specified by the kernel argument. 365The kernel must be defined in the current script. In addition, more than one 366input can be used. 367</p> 368 369<p> For example,<code><br/> 370float __attribute__((kernel)) square(float a) {<br/> 371 return a * a;<br/> 372}<br/> 373<br/> 374void compute(rs_allocation ain, rs_allocation aout) {<br/> 375 rsForEach(square, ain, aout);<br/> 376}<br/> 377<br/></code> 378</p> 379 </div> 380</div> 381 382<a name='android_rs:rsForEachWithOptions'></a> 383<div class='jd-details'> 384 <h4 class='jd-details-title'> 385 <span class='sympad'>rsForEachWithOptions</span> 386 <span class='normal'>: Launches a kernel with options</span> 387 </h4> 388 <div class='jd-details-descr'> 389 <table class='jd-tagtable'><tbody> 390 <tr> 391 <td>void rsForEachWithOptions(<a href='rs_for_each.html#android_rs:rs_kernel'>rs_kernel</a> kernel, <a href='rs_for_each.html#android_rs:rs_script_call_t'>rs_script_call_t</a>* options, ... ...); 392</td> 393 <td> Added in <a href='http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels'>API level 24</a> 394 </td> 395 </tr> 396 </tbody></table> 397 </div> 398 <div class='jd-tagdata'> <h5 class='jd-tagtitle'>Parameters</h5> 399 <table class='jd-tagtable'><tbody> 400 <tr><th>kernel</th><td>Function designator to a function that is defined with the kernel attribute.</td></tr> 401 <tr><th>options</th><td>Launch options</td></tr> 402 <tr><th>...</th><td>Input and output allocations</td></tr> 403 </tbody></table> 404 </div> 405 <div class='jd-tagdata jd-tagdescr'> 406<p> Launches kernel in a way similar to <a href='rs_for_each.html#android_rs:rsForEach'>rsForEach</a>. However, instead of processing 407all cells in the input, this function only processes cells in the subspace of 408the index space specified in options. With the index space explicitly specified 409by options, no input or output allocation is required for a kernel launch using 410this API. If allocations are passed in, they must match the number of arguments 411and return value expected by the kernel function. The output allocation is 412present if and only if the kernel has a non-void return value. 413</p> 414 415<p> For example,<code><br/> 416 rs_script_call_t opts = {0};<br/> 417 opts.xStart = 0;<br/> 418 opts.xEnd = dimX;<br/> 419 opts.yStart = 0;<br/> 420 opts.yEnd = dimY / 2;<br/> 421 rsForEachWithOptions(foo, &opts, out, out);<br/> 422</code> 423</p> 424 </div> 425</div> 426 427<a name='android_rs:rsGetArray0'></a> 428<div class='jd-details'> 429 <h4 class='jd-details-title'> 430 <span class='sympad'>rsGetArray0</span> 431 <span class='normal'>: Index in the Array0 dimension for the specified kernel context</span> 432 </h4> 433 <div class='jd-details-descr'> 434 <table class='jd-tagtable'><tbody> 435 <tr> 436 <td><a href='rs_value_types.html#android_rs:uint32_t'>uint32_t</a> rsGetArray0(<a href='rs_for_each.html#android_rs:rs_kernel_context'>rs_kernel_context</a> context); 437</td> 438 <td> Added in <a href='http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels'>API level 23</a> 439 </td> 440 </tr> 441 </tbody></table> 442 </div> 443 <div class='jd-tagdata jd-tagdescr'> 444<p> Returns the index in the Array0 dimension of the cell being processed, as specified 445by the supplied kernel context. 446</p> 447 448<p> The kernel context contains common characteristics of the allocations being iterated 449over and rarely used indices, like the Array0 index. 450</p> 451 452<p> You can access the kernel context by adding a special parameter named "context" of 453type rs_kernel_context to your kernel function. For example,<br/> 454<code>short RS_KERNEL myKernel(short value, uint32_t x, rs_kernel_context context) {<br/> 455 // The current index in the common x, y, z dimensions are accessed by<br/> 456 // adding these variables as arguments. For the more rarely used indices<br/> 457 // to the other dimensions, extract them from the kernel context:<br/> 458 uint32_t index_a0 = rsGetArray0(context);<br/> 459 //...<br/> 460}<br/></code> 461</p> 462 463<p> This function returns 0 if the Array0 dimension is not present. 464</p> 465 </div> 466</div> 467 468<a name='android_rs:rsGetArray1'></a> 469<div class='jd-details'> 470 <h4 class='jd-details-title'> 471 <span class='sympad'>rsGetArray1</span> 472 <span class='normal'>: Index in the Array1 dimension for the specified kernel context</span> 473 </h4> 474 <div class='jd-details-descr'> 475 <table class='jd-tagtable'><tbody> 476 <tr> 477 <td><a href='rs_value_types.html#android_rs:uint32_t'>uint32_t</a> rsGetArray1(<a href='rs_for_each.html#android_rs:rs_kernel_context'>rs_kernel_context</a> context); 478</td> 479 <td> Added in <a href='http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels'>API level 23</a> 480 </td> 481 </tr> 482 </tbody></table> 483 </div> 484 <div class='jd-tagdata jd-tagdescr'> 485<p> Returns the index in the Array1 dimension of the cell being processed, as specified 486by the supplied kernel context. See <a href='rs_for_each.html#android_rs:rsGetArray0'>rsGetArray0</a>() for an explanation of the context. 487</p> 488 489<p> Returns 0 if the Array1 dimension is not present. 490</p> 491 </div> 492</div> 493 494<a name='android_rs:rsGetArray2'></a> 495<div class='jd-details'> 496 <h4 class='jd-details-title'> 497 <span class='sympad'>rsGetArray2</span> 498 <span class='normal'>: Index in the Array2 dimension for the specified kernel context</span> 499 </h4> 500 <div class='jd-details-descr'> 501 <table class='jd-tagtable'><tbody> 502 <tr> 503 <td><a href='rs_value_types.html#android_rs:uint32_t'>uint32_t</a> rsGetArray2(<a href='rs_for_each.html#android_rs:rs_kernel_context'>rs_kernel_context</a> context); 504</td> 505 <td> Added in <a href='http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels'>API level 23</a> 506 </td> 507 </tr> 508 </tbody></table> 509 </div> 510 <div class='jd-tagdata jd-tagdescr'> 511<p> Returns the index in the Array2 dimension of the cell being processed, 512as specified by the supplied kernel context. See <a href='rs_for_each.html#android_rs:rsGetArray0'>rsGetArray0</a>() for an explanation 513of the context. 514</p> 515 516<p> Returns 0 if the Array2 dimension is not present. 517</p> 518 </div> 519</div> 520 521<a name='android_rs:rsGetArray3'></a> 522<div class='jd-details'> 523 <h4 class='jd-details-title'> 524 <span class='sympad'>rsGetArray3</span> 525 <span class='normal'>: Index in the Array3 dimension for the specified kernel context</span> 526 </h4> 527 <div class='jd-details-descr'> 528 <table class='jd-tagtable'><tbody> 529 <tr> 530 <td><a href='rs_value_types.html#android_rs:uint32_t'>uint32_t</a> rsGetArray3(<a href='rs_for_each.html#android_rs:rs_kernel_context'>rs_kernel_context</a> context); 531</td> 532 <td> Added in <a href='http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels'>API level 23</a> 533 </td> 534 </tr> 535 </tbody></table> 536 </div> 537 <div class='jd-tagdata jd-tagdescr'> 538<p> Returns the index in the Array3 dimension of the cell being processed, as specified 539by the supplied kernel context. See <a href='rs_for_each.html#android_rs:rsGetArray0'>rsGetArray0</a>() for an explanation of the context. 540</p> 541 542<p> Returns 0 if the Array3 dimension is not present. 543</p> 544 </div> 545</div> 546 547<a name='android_rs:rsGetDimArray0'></a> 548<div class='jd-details'> 549 <h4 class='jd-details-title'> 550 <span class='sympad'>rsGetDimArray0</span> 551 <span class='normal'>: Size of the Array0 dimension for the specified kernel context</span> 552 </h4> 553 <div class='jd-details-descr'> 554 <table class='jd-tagtable'><tbody> 555 <tr> 556 <td><a href='rs_value_types.html#android_rs:uint32_t'>uint32_t</a> rsGetDimArray0(<a href='rs_for_each.html#android_rs:rs_kernel_context'>rs_kernel_context</a> context); 557</td> 558 <td> Added in <a href='http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels'>API level 23</a> 559 </td> 560 </tr> 561 </tbody></table> 562 </div> 563 <div class='jd-tagdata jd-tagdescr'> 564<p> Returns the size of the Array0 dimension for the specified kernel context. 565See <a href='rs_for_each.html#android_rs:rsGetDimX'>rsGetDimX</a>() for an explanation of the context. 566</p> 567 568<p> Returns 0 if the Array0 dimension is not present. 569</p> 570 </div> 571</div> 572 573<a name='android_rs:rsGetDimArray1'></a> 574<div class='jd-details'> 575 <h4 class='jd-details-title'> 576 <span class='sympad'>rsGetDimArray1</span> 577 <span class='normal'>: Size of the Array1 dimension for the specified kernel context</span> 578 </h4> 579 <div class='jd-details-descr'> 580 <table class='jd-tagtable'><tbody> 581 <tr> 582 <td><a href='rs_value_types.html#android_rs:uint32_t'>uint32_t</a> rsGetDimArray1(<a href='rs_for_each.html#android_rs:rs_kernel_context'>rs_kernel_context</a> context); 583</td> 584 <td> Added in <a href='http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels'>API level 23</a> 585 </td> 586 </tr> 587 </tbody></table> 588 </div> 589 <div class='jd-tagdata jd-tagdescr'> 590<p> Returns the size of the Array1 dimension for the specified kernel context. 591See <a href='rs_for_each.html#android_rs:rsGetDimX'>rsGetDimX</a>() for an explanation of the context. 592</p> 593 594<p> Returns 0 if the Array1 dimension is not present. 595</p> 596 </div> 597</div> 598 599<a name='android_rs:rsGetDimArray2'></a> 600<div class='jd-details'> 601 <h4 class='jd-details-title'> 602 <span class='sympad'>rsGetDimArray2</span> 603 <span class='normal'>: Size of the Array2 dimension for the specified kernel context</span> 604 </h4> 605 <div class='jd-details-descr'> 606 <table class='jd-tagtable'><tbody> 607 <tr> 608 <td><a href='rs_value_types.html#android_rs:uint32_t'>uint32_t</a> rsGetDimArray2(<a href='rs_for_each.html#android_rs:rs_kernel_context'>rs_kernel_context</a> context); 609</td> 610 <td> Added in <a href='http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels'>API level 23</a> 611 </td> 612 </tr> 613 </tbody></table> 614 </div> 615 <div class='jd-tagdata jd-tagdescr'> 616<p> Returns the size of the Array2 dimension for the specified kernel context. 617See <a href='rs_for_each.html#android_rs:rsGetDimX'>rsGetDimX</a>() for an explanation of the context. 618</p> 619 620<p> Returns 0 if the Array2 dimension is not present. 621</p> 622 </div> 623</div> 624 625<a name='android_rs:rsGetDimArray3'></a> 626<div class='jd-details'> 627 <h4 class='jd-details-title'> 628 <span class='sympad'>rsGetDimArray3</span> 629 <span class='normal'>: Size of the Array3 dimension for the specified kernel context</span> 630 </h4> 631 <div class='jd-details-descr'> 632 <table class='jd-tagtable'><tbody> 633 <tr> 634 <td><a href='rs_value_types.html#android_rs:uint32_t'>uint32_t</a> rsGetDimArray3(<a href='rs_for_each.html#android_rs:rs_kernel_context'>rs_kernel_context</a> context); 635</td> 636 <td> Added in <a href='http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels'>API level 23</a> 637 </td> 638 </tr> 639 </tbody></table> 640 </div> 641 <div class='jd-tagdata jd-tagdescr'> 642<p> Returns the size of the Array3 dimension for the specified kernel context. 643See <a href='rs_for_each.html#android_rs:rsGetDimX'>rsGetDimX</a>() for an explanation of the context. 644</p> 645 646<p> Returns 0 if the Array3 dimension is not present. 647</p> 648 </div> 649</div> 650 651<a name='android_rs:rsGetDimHasFaces'></a> 652<div class='jd-details'> 653 <h4 class='jd-details-title'> 654 <span class='sympad'>rsGetDimHasFaces</span> 655 <span class='normal'>: Presence of more than one face for the specified kernel context</span> 656 </h4> 657 <div class='jd-details-descr'> 658 <table class='jd-tagtable'><tbody> 659 <tr> 660 <td>bool rsGetDimHasFaces(<a href='rs_for_each.html#android_rs:rs_kernel_context'>rs_kernel_context</a> context); 661</td> 662 <td> Added in <a href='http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels'>API level 23</a> 663 </td> 664 </tr> 665 </tbody></table> 666 </div> 667 <div class='jd-tagdata'> <h5 class='jd-tagtitle'>Returns</h5> 668 <table class='jd-tagtable'><tbody> 669 <tr><td>Returns true if more than one face is present, false otherwise.</td></tr> 670 </tbody></table> 671 </div> 672 <div class='jd-tagdata jd-tagdescr'> 673<p> If the kernel is iterating over a cubemap, this function returns true if there's more 674than one face present. In all other cases, it returns false. See <a href='rs_for_each.html#android_rs:rsGetDimX'>rsGetDimX</a>() for an 675explanation of the context. 676</p> 677 678<p> <a href='rs_object_info.html#android_rs:rsAllocationGetDimFaces'>rsAllocationGetDimFaces</a>() is similar but returns 0 or 1 instead of a bool. 679</p> 680 </div> 681</div> 682 683<a name='android_rs:rsGetDimLod'></a> 684<div class='jd-details'> 685 <h4 class='jd-details-title'> 686 <span class='sympad'>rsGetDimLod</span> 687 <span class='normal'>: Number of levels of detail for the specified kernel context</span> 688 </h4> 689 <div class='jd-details-descr'> 690 <table class='jd-tagtable'><tbody> 691 <tr> 692 <td><a href='rs_value_types.html#android_rs:uint32_t'>uint32_t</a> rsGetDimLod(<a href='rs_for_each.html#android_rs:rs_kernel_context'>rs_kernel_context</a> context); 693</td> 694 <td> Added in <a href='http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels'>API level 23</a> 695 </td> 696 </tr> 697 </tbody></table> 698 </div> 699 <div class='jd-tagdata jd-tagdescr'> 700<p> Returns the number of levels of detail for the specified kernel context. This is useful 701for mipmaps. See <a href='rs_for_each.html#android_rs:rsGetDimX'>rsGetDimX</a>() for an explanation of the context. 702</p> 703 704<p> Returns 0 if Level of Detail is not used. 705</p> 706 707<p> <a href='rs_object_info.html#android_rs:rsAllocationGetDimLOD'>rsAllocationGetDimLOD</a>() is similar but returns 0 or 1 instead the actual 708number of levels. 709</p> 710 </div> 711</div> 712 713<a name='android_rs:rsGetDimX'></a> 714<div class='jd-details'> 715 <h4 class='jd-details-title'> 716 <span class='sympad'>rsGetDimX</span> 717 <span class='normal'>: Size of the X dimension for the specified kernel context</span> 718 </h4> 719 <div class='jd-details-descr'> 720 <table class='jd-tagtable'><tbody> 721 <tr> 722 <td><a href='rs_value_types.html#android_rs:uint32_t'>uint32_t</a> rsGetDimX(<a href='rs_for_each.html#android_rs:rs_kernel_context'>rs_kernel_context</a> context); 723</td> 724 <td> Added in <a href='http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels'>API level 23</a> 725 </td> 726 </tr> 727 </tbody></table> 728 </div> 729 <div class='jd-tagdata jd-tagdescr'> 730<p> Returns the size of the X dimension for the specified kernel context. 731</p> 732 733<p> The kernel context contains common characteristics of the allocations being iterated 734over and rarely used indices, like the Array0 index. 735</p> 736 737<p> You can access it by adding a special parameter named "context" of 738type rs_kernel_context to your kernel function. For example,<br/> 739<code>int4 RS_KERNEL myKernel(int4 value, rs_kernel_context context) {<br/> 740 uint32_t size = rsGetDimX(context); //...<br/></code> 741</p> 742 743<p> To get the dimension of specific allocation, use <a href='rs_object_info.html#android_rs:rsAllocationGetDimX'>rsAllocationGetDimX</a>(). 744</p> 745 </div> 746</div> 747 748<a name='android_rs:rsGetDimY'></a> 749<div class='jd-details'> 750 <h4 class='jd-details-title'> 751 <span class='sympad'>rsGetDimY</span> 752 <span class='normal'>: Size of the Y dimension for the specified kernel context</span> 753 </h4> 754 <div class='jd-details-descr'> 755 <table class='jd-tagtable'><tbody> 756 <tr> 757 <td><a href='rs_value_types.html#android_rs:uint32_t'>uint32_t</a> rsGetDimY(<a href='rs_for_each.html#android_rs:rs_kernel_context'>rs_kernel_context</a> context); 758</td> 759 <td> Added in <a href='http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels'>API level 23</a> 760 </td> 761 </tr> 762 </tbody></table> 763 </div> 764 <div class='jd-tagdata jd-tagdescr'> 765<p> Returns the size of the X dimension for the specified kernel context. 766See <a href='rs_for_each.html#android_rs:rsGetDimX'>rsGetDimX</a>() for an explanation of the context. 767</p> 768 769<p> Returns 0 if the Y dimension is not present. 770</p> 771 772<p> To get the dimension of specific allocation, use <a href='rs_object_info.html#android_rs:rsAllocationGetDimY'>rsAllocationGetDimY</a>(). 773</p> 774 </div> 775</div> 776 777<a name='android_rs:rsGetDimZ'></a> 778<div class='jd-details'> 779 <h4 class='jd-details-title'> 780 <span class='sympad'>rsGetDimZ</span> 781 <span class='normal'>: Size of the Z dimension for the specified kernel context</span> 782 </h4> 783 <div class='jd-details-descr'> 784 <table class='jd-tagtable'><tbody> 785 <tr> 786 <td><a href='rs_value_types.html#android_rs:uint32_t'>uint32_t</a> rsGetDimZ(<a href='rs_for_each.html#android_rs:rs_kernel_context'>rs_kernel_context</a> context); 787</td> 788 <td> Added in <a href='http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels'>API level 23</a> 789 </td> 790 </tr> 791 </tbody></table> 792 </div> 793 <div class='jd-tagdata jd-tagdescr'> 794<p> Returns the size of the Z dimension for the specified kernel context. 795See <a href='rs_for_each.html#android_rs:rsGetDimX'>rsGetDimX</a>() for an explanation of the context. 796</p> 797 798<p> Returns 0 if the Z dimension is not present. 799</p> 800 801<p> To get the dimension of specific allocation, use <a href='rs_object_info.html#android_rs:rsAllocationGetDimZ'>rsAllocationGetDimZ</a>(). 802</p> 803 </div> 804</div> 805 806<a name='android_rs:rsGetFace'></a> 807<div class='jd-details'> 808 <h4 class='jd-details-title'> 809 <span class='sympad'>rsGetFace</span> 810 <span class='normal'>: Coordinate of the Face for the specified kernel context</span> 811 </h4> 812 <div class='jd-details-descr'> 813 <table class='jd-tagtable'><tbody> 814 <tr> 815 <td><a href='rs_object_types.html#android_rs:rs_allocation_cubemap_face'>rs_allocation_cubemap_face</a> rsGetFace(<a href='rs_for_each.html#android_rs:rs_kernel_context'>rs_kernel_context</a> context); 816</td> 817 <td> Added in <a href='http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels'>API level 23</a> 818 </td> 819 </tr> 820 </tbody></table> 821 </div> 822 <div class='jd-tagdata jd-tagdescr'> 823<p> Returns the face on which the cell being processed is found, as specified by the 824supplied kernel context. See <a href='rs_for_each.html#android_rs:rsGetArray0'>rsGetArray0</a>() for an explanation of the context. 825</p> 826 827<p> Returns RS_ALLOCATION_CUBEMAP_FACE_POSITIVE_X if the face dimension is not 828present. 829</p> 830 </div> 831</div> 832 833<a name='android_rs:rsGetLod'></a> 834<div class='jd-details'> 835 <h4 class='jd-details-title'> 836 <span class='sympad'>rsGetLod</span> 837 <span class='normal'>: Index in the Levels of Detail dimension for the specified kernel context</span> 838 </h4> 839 <div class='jd-details-descr'> 840 <table class='jd-tagtable'><tbody> 841 <tr> 842 <td><a href='rs_value_types.html#android_rs:uint32_t'>uint32_t</a> rsGetLod(<a href='rs_for_each.html#android_rs:rs_kernel_context'>rs_kernel_context</a> context); 843</td> 844 <td> Added in <a href='http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels'>API level 23</a> 845 </td> 846 </tr> 847 </tbody></table> 848 </div> 849 <div class='jd-tagdata jd-tagdescr'> 850<p> Returns the index in the Levels of Detail dimension of the cell being processed, 851as specified by the supplied kernel context. See <a href='rs_for_each.html#android_rs:rsGetArray0'>rsGetArray0</a>() for an explanation of 852the context. 853</p> 854 855<p> Returns 0 if the Levels of Detail dimension is not present. 856</p> 857 </div> 858</div> 859 860</div> 861