1 # 2 # Copyright (C) 2015 The Android Open Source Project 3 # 4 # Licensed under the Apache License, Version 2.0 (the "License"); 5 # you may not use this file except in compliance with the License. 6 # You may obtain a copy of the License at 7 # 8 # http://www.apache.org/licenses/LICENSE-2.0 9 # 10 # Unless required by applicable law or agreed to in writing, software 11 # distributed under the License is distributed on an "AS IS" BASIS, 12 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 # See the License for the specific language governing permissions and 14 # limitations under the License. 15 # 16 17 header: 18 summary: Allocation Data Access Functions 19 description: 20 The functions below can be used to get and set the cells that comprise 21 an allocation. 22 <ul> 23 <li>Individual cells are accessed using the rsGetElementAt* and 24 @rsSetElementAt functions.</li> 25 <li>Multiple cells can be copied using the rsAllocationCopy* and 26 rsAllocationV* functions.</li> 27 <li>For getting values through a sampler, use @rsSample.</li> 28 </ul> 29 The @rsGetElementAt and rsSetElement* functions are somewhat misnamed. 30 They don't get or set elements, which are akin to data types; they get 31 or set cells. Think of them as rsGetCellAt and and rsSetCellAt. 32 end: 33 34 function: rsAllocationCopy1DRange 35 version: 14 36 ret: void 37 arg: rs_allocation dstAlloc, "Allocation to copy cells into." 38 arg: uint32_t dstOff, "Offset in the destination of the first cell to be copied into." 39 arg: uint32_t dstMip, "Mip level in the destination allocation. 0 if mip mapping is not used." 40 arg: uint32_t count, "Number of cells to be copied." 41 arg: rs_allocation srcAlloc, "Source allocation." 42 arg: uint32_t srcOff, "Offset in the source of the first cell to be copied." 43 arg: uint32_t srcMip, "Mip level in the source allocation. 0 if mip mapping is not used." 44 summary: Copy consecutive cells between allocations 45 description: 46 Copies the specified number of cells from one allocation to another. 47 48 The two allocations must be different. Using this function to copy whithin 49 the same allocation yields undefined results. 50 51 The function does not validate whether the offset plus count exceeds the size 52 of either allocation. Be careful! 53 54 This function should only be called between 1D allocations. Calling it 55 on other allocations is undefined. 56 57 This function should not be called from inside a kernel, or from any function 58 that may be called directly or indirectly from a kernel. Doing so would cause a 59 runtime error. 60 test: none 61 end: 62 63 function: rsAllocationCopy2DRange 64 version: 14 65 ret: void 66 arg: rs_allocation dstAlloc, "Allocation to copy cells into." 67 arg: uint32_t dstXoff, "X offset in the destination of the region to be set." 68 arg: uint32_t dstYoff, "Y offset in the destination of the region to be set." 69 arg: uint32_t dstMip, "Mip level in the destination allocation. 0 if mip mapping is not used." 70 arg: rs_allocation_cubemap_face dstFace, "Cubemap face of the destination allocation. Ignored for allocations that aren't cubemaps." 71 arg: uint32_t width, "Width of the incoming region to update." 72 arg: uint32_t height, "Height of the incoming region to update." 73 arg: rs_allocation srcAlloc, "Source allocation." 74 arg: uint32_t srcXoff, "X offset in the source." 75 arg: uint32_t srcYoff, "Y offset in the source." 76 arg: uint32_t srcMip, "Mip level in the source allocation. 0 if mip mapping is not used." 77 arg: rs_allocation_cubemap_face srcFace, "Cubemap face of the source allocation. Ignored for allocations that aren't cubemaps." 78 summary: Copy a rectangular region of cells between allocations 79 description: 80 Copies a rectangular region of cells from one allocation to another. 81 (width * heigth) cells are copied. 82 83 The two allocations must be different. Using this function to copy whithin 84 the same allocation yields undefined results. 85 86 The function does not validate whether the the source or destination region 87 exceeds the size of its respective allocation. Be careful! 88 89 This function should only be called between 2D allocations. Calling it 90 on other allocations is undefined. 91 92 This function should not be called from inside a kernel, or from any function 93 that may be called directly or indirectly from a kernel. Doing so would cause a 94 runtime error. 95 test: none 96 end: 97 98 function: rsAllocationVLoadX_#2#1 99 version: 22 100 w: 2, 3, 4 101 t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 102 ret: #2#1 103 arg: rs_allocation a, "Allocation to get the data from." 104 arg: uint32_t x, "X offset in the allocation of the first cell to be copied from." 105 summary: Get a vector from an allocation of scalars 106 description: 107 This function returns a vector composed of successive cells of the allocation. 108 It assumes that the allocation contains scalars. 109 110 The "X" in the name indicates that successive values are extracted by 111 increasing the X index. There are currently no functions to get successive 112 values incrementing other dimensions. Use multiple calls to rsGetElementAt() 113 instead. 114 115 For example, when calling rsAllocationVLoadX_int4(a, 20, 30), an int4 composed 116 of a[20, 30], a[21, 30], a[22, 30], and a[23, 30] is returned. 117 118 When retrieving from a three dimensional allocations, use the x, y, z variant. 119 Similarly, use the x, y variant for two dimensional allocations and x for the 120 mono dimensional allocations. 121 122 For efficiency, this function does not validate the inputs. Trying to wrap 123 the X index, exceeding the size of the allocation, or using indices incompatible 124 with the dimensionality of the allocation yields undefined results. 125 126 See also @rsAllocationVStoreX(). 127 test: none 128 end: 129 130 function: rsAllocationVLoadX_#2#1 131 version: 22 132 w: 2, 3, 4 133 t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 134 ret: #2#1 135 arg: rs_allocation a 136 arg: uint32_t x 137 arg: uint32_t y, "Y offset in the allocation of the first cell to be copied from." 138 test: none 139 end: 140 141 function: rsAllocationVLoadX_#2#1 142 version: 22 143 w: 2, 3, 4 144 t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 145 ret: #2#1 146 arg: rs_allocation a 147 arg: uint32_t x 148 arg: uint32_t y 149 arg: uint32_t z, "Z offset in the allocation of the first cell to be copied from." 150 test: none 151 end: 152 153 function: rsAllocationVStoreX_#2#1 154 version: 22 155 w: 2, 3, 4 156 t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 157 ret: void 158 arg: rs_allocation a, "Allocation to store the data into." 159 arg: #2#1 val, "Value to be stored." 160 arg: uint32_t x, "X offset in the allocation of the first cell to be copied into." 161 summary: Store a vector into an allocation of scalars 162 description: 163 This function stores the entries of a vector into successive cells of an allocation. 164 It assumes that the allocation contains scalars. 165 166 The "X" in the name indicates that successive values are stored by increasing 167 the X index. There are currently no functions to store successive values 168 incrementing other dimensions. Use multiple calls to rsSetElementAt() instead. 169 170 For example, when calling rsAllocationVStoreX_int3(a, v, 20, 30), v.x is stored 171 at a[20, 30], v.y at a[21, 30], and v.z at a[22, 30]. 172 173 When storing into a three dimensional allocations, use the x, y, z variant. 174 Similarly, use the x, y variant for two dimensional allocations and x for the 175 mono dimensional allocations. 176 177 For efficiency, this function does not validate the inputs. Trying to wrap the 178 X index, exceeding the size of the allocation, or using indices incompatible 179 with the dimensionality of the allocation yiels undefined results. 180 181 See also @rsAllocationVLoadX(). 182 test: none 183 end: 184 185 function: rsAllocationVStoreX_#2#1 186 version: 22 187 w: 2, 3, 4 188 t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 189 ret: void 190 arg: rs_allocation a 191 arg: #2#1 val 192 arg: uint32_t x 193 arg: uint32_t y, "Y offset in the allocation of the first cell to be copied into." 194 test: none 195 end: 196 197 function: rsAllocationVStoreX_#2#1 198 version: 22 199 w: 2, 3, 4 200 t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 201 ret: void 202 arg: rs_allocation a 203 arg: #2#1 val 204 arg: uint32_t x 205 arg: uint32_t y 206 arg: uint32_t z, "Z offset in the allocation of the first cell to be copied into." 207 test: none 208 end: 209 210 function: rsGetElementAt 211 ret: const void* 212 arg: rs_allocation a 213 arg: uint32_t x 214 summary: Return a cell from an allocation 215 description: 216 This function extracts a single cell from an allocation. 217 218 When retrieving from a three dimensional allocations, use the x, y, z variant. 219 Similarly, use the x, y variant for two dimensional allocations and x for the 220 mono dimensional allocations. 221 222 This function has two styles. One returns the address of the value using a void*, 223 the other returns the actual value, e.g. rsGetElementAt() vs. rsGetElementAt_int4(). 224 For primitive types, always use the latter as it is more efficient. 225 test: none 226 end: 227 228 function: rsGetElementAt 229 ret: const void* 230 arg: rs_allocation a 231 arg: uint32_t x 232 arg: uint32_t y 233 test: none 234 end: 235 236 function: rsGetElementAt 237 ret: const void* 238 arg: rs_allocation a 239 arg: uint32_t x 240 arg: uint32_t y 241 arg: uint32_t z 242 test: none 243 end: 244 245 function: rsGetElementAt_#2#1 246 version: 9 17 247 w: 1, 2, 3, 4 248 t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 249 ret: #2#1 250 arg: rs_allocation a 251 arg: uint32_t x 252 inline: 253 return ((#2#1 *)rsGetElementAt(a, x))[0]; 254 test: none 255 end: 256 257 function: rsGetElementAt_#2#1 258 version: 9 17 259 w: 1, 2, 3, 4 260 t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 261 ret: #2#1 262 arg: rs_allocation a 263 arg: uint32_t x 264 arg: uint32_t y 265 inline: 266 return ((#2#1 *)rsGetElementAt(a, x, y))[0]; 267 test: none 268 end: 269 270 function: rsGetElementAt_#2#1 271 version: 9 17 272 w: 1, 2, 3, 4 273 t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 274 ret: #2#1 275 arg: rs_allocation a 276 arg: uint32_t x 277 arg: uint32_t y 278 arg: uint32_t z 279 inline: 280 return ((#2#1 *)rsGetElementAt(a, x, y, z))[0]; 281 test: none 282 end: 283 284 function: rsGetElementAt_#2#1 285 version: 18 286 w: 1, 2, 3, 4 287 t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 288 ret: #2#1 289 arg: rs_allocation a 290 arg: uint32_t x 291 test: none 292 end: 293 294 function: rsGetElementAt_#2#1 295 version: 18 296 w: 1, 2, 3, 4 297 t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 298 ret: #2#1 299 arg: rs_allocation a 300 arg: uint32_t x 301 arg: uint32_t y 302 test: none 303 end: 304 305 function: rsGetElementAt_#2#1 306 version: 18 307 w: 1, 2, 3, 4 308 t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 309 ret: #2#1 310 arg: rs_allocation a 311 arg: uint32_t x 312 arg: uint32_t y 313 arg: uint32_t z 314 test: none 315 end: 316 317 function: rsGetElementAt_#2#1 318 version: 23 319 w: 1, 2, 3, 4 320 t: f16 321 ret: #2#1 322 arg: rs_allocation a 323 arg: uint32_t x 324 test: none 325 end: 326 327 function: rsGetElementAt_#2#1 328 version: 23 329 w: 1, 2, 3, 4 330 t: f16 331 ret: #2#1 332 arg: rs_allocation a 333 arg: uint32_t x 334 arg: uint32_t y 335 test: none 336 end: 337 338 function: rsGetElementAt_#2#1 339 version: 23 340 w: 1, 2, 3, 4 341 t: f16 342 ret: #2#1 343 arg: rs_allocation a 344 arg: uint32_t x 345 arg: uint32_t y 346 arg: uint32_t z 347 test: none 348 end: 349 350 function: rsGetElementAtYuv_uchar_U 351 version: 18 352 ret: uchar 353 arg: rs_allocation a 354 arg: uint32_t x 355 arg: uint32_t y 356 summary: Get the U component of an allocation of YUVs 357 description: 358 Extracts the U component of a single YUV value from a 2D allocation of YUVs. 359 360 Inside an allocation, Y, U, and V components may be stored if different planes 361 and at different resolutions. The x, y coordinates provided here are in the 362 dimensions of the Y plane. 363 364 See @rsGetElementAtYuv_uchar_Y(). 365 test: none 366 end: 367 368 function: rsGetElementAtYuv_uchar_V 369 version: 18 370 ret: uchar 371 arg: rs_allocation a 372 arg: uint32_t x 373 arg: uint32_t y 374 summary: Get the V component of an allocation of YUVs 375 description: 376 Extracts the V component of a single YUV value from a 2D allocation of YUVs. 377 378 Inside an allocation, Y, U, and V components may be stored if different planes 379 and at different resolutions. The x, y coordinates provided here are in the 380 dimensions of the Y plane. 381 382 See @rsGetElementAtYuv_uchar_Y(). 383 test: none 384 end: 385 386 function: rsGetElementAtYuv_uchar_Y 387 version: 18 388 ret: uchar 389 arg: rs_allocation a 390 arg: uint32_t x 391 arg: uint32_t y 392 summary: Get the Y component of an allocation of YUVs 393 description: 394 Extracts the Y component of a single YUV value from a 2D allocation of YUVs. 395 396 Inside an allocation, Y, U, and V components may be stored if different planes 397 and at different resolutions. The x, y coordinates provided here are in the 398 dimensions of the Y plane. 399 400 See @rsGetElementAtYuv_uchar_U() and @rsGetElementAtYuv_uchar_V(). 401 test: none 402 end: 403 404 function: rsSample 405 version: 16 406 ret: float4 407 arg: rs_allocation a, "Allocation to sample from." 408 arg: rs_sampler s, "Sampler state." 409 arg: float location, "Location to sample from." 410 summary: Sample a value from a texture allocation 411 description: 412 Fetches a value from a texture allocation in a way described by the sampler. 413 414 If your allocation is 1D, use the variant with float for location. For 2D, 415 use the float2 variant. 416 417 See <a href='http://developer.android.com/reference/android/renderscript/Sampler.html'>android.renderscript.Sampler</a> for more details. 418 test: none 419 end: 420 421 function: rsSample 422 version: 16 423 ret: float4 424 arg: rs_allocation a 425 arg: rs_sampler s 426 arg: float location 427 arg: float lod, "Mip level to sample from, for fractional values mip levels will be interpolated if RS_SAMPLER_LINEAR_MIP_LINEAR is used." 428 test: none 429 end: 430 431 function: rsSample 432 version: 16 433 ret: float4 434 arg: rs_allocation a 435 arg: rs_sampler s 436 arg: float2 location 437 test: none 438 end: 439 440 function: rsSample 441 version: 16 442 ret: float4 443 arg: rs_allocation a 444 arg: rs_sampler s 445 arg: float2 location 446 arg: float lod 447 test: none 448 end: 449 450 function: rsSetElementAt 451 version: 18 452 ret: void 453 arg: rs_allocation a 454 arg: void* ptr 455 arg: uint32_t x 456 summary: Set a cell of an allocation 457 description: 458 This function stores a value into a single cell of an allocation. 459 460 When storing into a three dimensional allocations, use the x, y, z variant. 461 Similarly, use the x, y variant for two dimensional allocations and x for 462 the mono dimensional allocations. 463 464 This function has two styles. One passes the value to be stored using a void*, 465 the other has the actual value as an argument, e.g. rsSetElementAt() vs. 466 rsSetElementAt_int4(). For primitive types, always use the latter as it is 467 more efficient. 468 469 See also @rsGetElementAt(). 470 test: none 471 end: 472 473 function: rsSetElementAt 474 version: 18 475 ret: void 476 arg: rs_allocation a 477 arg: void* ptr 478 arg: uint32_t x 479 arg: uint32_t y 480 test: none 481 end: 482 483 function: rsSetElementAt_#2#1 484 version: 18 485 w: 1, 2, 3, 4 486 t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 487 ret: void 488 arg: rs_allocation a 489 arg: #2#1 val 490 arg: uint32_t x 491 test: none 492 end: 493 494 function: rsSetElementAt_#2#1 495 version: 18 496 w: 1, 2, 3, 4 497 t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 498 ret: void 499 arg: rs_allocation a 500 arg: #2#1 val 501 arg: uint32_t x 502 arg: uint32_t y 503 test: none 504 end: 505 506 function: rsSetElementAt_#2#1 507 version: 18 508 w: 1, 2, 3, 4 509 t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 510 ret: void 511 arg: rs_allocation a 512 arg: #2#1 val 513 arg: uint32_t x 514 arg: uint32_t y 515 arg: uint32_t z 516 test: none 517 end: 518 519 function: rsSetElementAt_#2#1 520 version: 23 521 w: 1, 2, 3, 4 522 t: f16 523 ret: void 524 arg: rs_allocation a 525 arg: #2#1 val 526 arg: uint32_t x 527 test: none 528 end: 529 530 function: rsSetElementAt_#2#1 531 version: 23 532 w: 1, 2, 3, 4 533 t: f16 534 ret: void 535 arg: rs_allocation a 536 arg: #2#1 val 537 arg: uint32_t x 538 arg: uint32_t y 539 test: none 540 end: 541 542 function: rsSetElementAt_#2#1 543 version: 23 544 w: 1, 2, 3, 4 545 t: f16 546 ret: void 547 arg: rs_allocation a 548 arg: #2#1 val 549 arg: uint32_t x 550 arg: uint32_t y 551 arg: uint32_t z 552 test: none 553 end: 554
