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 17header: 18summary: Allocation Data Access Functions 19description: 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. 32end: 33 34function: rsAllocationCopy1DRange 35version: 14 36ret: void 37arg: rs_allocation dstAlloc, "Allocation to copy cells into." 38arg: uint32_t dstOff, "Offset in the destination of the first cell to be copied into." 39arg: uint32_t dstMip, "Mip level in the destination allocation. 0 if mip mapping is not used." 40arg: uint32_t count, "Number of cells to be copied." 41arg: rs_allocation srcAlloc, "Source allocation." 42arg: uint32_t srcOff, "Offset in the source of the first cell to be copied." 43arg: uint32_t srcMip, "Mip level in the source allocation. 0 if mip mapping is not used." 44summary: Copy consecutive cells between allocations 45description: 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. 60test: none 61end: 62 63function: rsAllocationCopy2DRange 64version: 14 65ret: void 66arg: rs_allocation dstAlloc, "Allocation to copy cells into." 67arg: uint32_t dstXoff, "X offset in the destination of the region to be set." 68arg: uint32_t dstYoff, "Y offset in the destination of the region to be set." 69arg: uint32_t dstMip, "Mip level in the destination allocation. 0 if mip mapping is not used." 70arg: rs_allocation_cubemap_face dstFace, "Cubemap face of the destination allocation. Ignored for allocations that aren't cubemaps." 71arg: uint32_t width, "Width of the incoming region to update." 72arg: uint32_t height, "Height of the incoming region to update." 73arg: rs_allocation srcAlloc, "Source allocation." 74arg: uint32_t srcXoff, "X offset in the source." 75arg: uint32_t srcYoff, "Y offset in the source." 76arg: uint32_t srcMip, "Mip level in the source allocation. 0 if mip mapping is not used." 77arg: rs_allocation_cubemap_face srcFace, "Cubemap face of the source allocation. Ignored for allocations that aren't cubemaps." 78summary: Copy a rectangular region of cells between allocations 79description: 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. 95test: none 96end: 97 98function: rsAllocationVLoadX_#2#1 99version: 22 100w: 2, 3, 4 101t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 102ret: #2#1 103arg: rs_allocation a, "Allocation to get the data from." 104arg: uint32_t x, "X offset in the allocation of the first cell to be copied from." 105summary: Get a vector from an allocation of scalars 106description: 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(). 127test: none 128end: 129 130function: rsAllocationVLoadX_#2#1 131version: 22 132w: 2, 3, 4 133t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 134ret: #2#1 135arg: rs_allocation a 136arg: uint32_t x 137arg: uint32_t y, "Y offset in the allocation of the first cell to be copied from." 138test: none 139end: 140 141function: rsAllocationVLoadX_#2#1 142version: 22 143w: 2, 3, 4 144t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 145ret: #2#1 146arg: rs_allocation a 147arg: uint32_t x 148arg: uint32_t y 149arg: uint32_t z, "Z offset in the allocation of the first cell to be copied from." 150test: none 151end: 152 153function: rsAllocationVStoreX_#2#1 154version: 22 155w: 2, 3, 4 156t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 157ret: void 158arg: rs_allocation a, "Allocation to store the data into." 159arg: #2#1 val, "Value to be stored." 160arg: uint32_t x, "X offset in the allocation of the first cell to be copied into." 161summary: Store a vector into an allocation of scalars 162description: 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(). 182test: none 183end: 184 185function: rsAllocationVStoreX_#2#1 186version: 22 187w: 2, 3, 4 188t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 189ret: void 190arg: rs_allocation a 191arg: #2#1 val 192arg: uint32_t x 193arg: uint32_t y, "Y offset in the allocation of the first cell to be copied into." 194test: none 195end: 196 197function: rsAllocationVStoreX_#2#1 198version: 22 199w: 2, 3, 4 200t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 201ret: void 202arg: rs_allocation a 203arg: #2#1 val 204arg: uint32_t x 205arg: uint32_t y 206arg: uint32_t z, "Z offset in the allocation of the first cell to be copied into." 207test: none 208end: 209 210function: rsGetElementAt 211ret: const void* 212arg: rs_allocation a 213arg: uint32_t x 214summary: Return a cell from an allocation 215description: 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. 225test: none 226end: 227 228function: rsGetElementAt 229ret: const void* 230arg: rs_allocation a 231arg: uint32_t x 232arg: uint32_t y 233test: none 234end: 235 236function: rsGetElementAt 237ret: const void* 238arg: rs_allocation a 239arg: uint32_t x 240arg: uint32_t y 241arg: uint32_t z 242test: none 243end: 244 245function: rsGetElementAt_#2#1 246version: 9 17 247w: 1, 2, 3, 4 248t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 249ret: #2#1 250arg: rs_allocation a 251arg: uint32_t x 252inline: 253 return ((#2#1 *)rsGetElementAt(a, x))[0]; 254test: none 255end: 256 257function: rsGetElementAt_#2#1 258version: 9 17 259w: 1, 2, 3, 4 260t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 261ret: #2#1 262arg: rs_allocation a 263arg: uint32_t x 264arg: uint32_t y 265inline: 266 return ((#2#1 *)rsGetElementAt(a, x, y))[0]; 267test: none 268end: 269 270function: rsGetElementAt_#2#1 271version: 9 17 272w: 1, 2, 3, 4 273t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 274ret: #2#1 275arg: rs_allocation a 276arg: uint32_t x 277arg: uint32_t y 278arg: uint32_t z 279inline: 280 return ((#2#1 *)rsGetElementAt(a, x, y, z))[0]; 281test: none 282end: 283 284function: rsGetElementAt_#2#1 285version: 18 286w: 1, 2, 3, 4 287t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 288ret: #2#1 289arg: rs_allocation a 290arg: uint32_t x 291test: none 292end: 293 294function: rsGetElementAt_#2#1 295version: 18 296w: 1, 2, 3, 4 297t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 298ret: #2#1 299arg: rs_allocation a 300arg: uint32_t x 301arg: uint32_t y 302test: none 303end: 304 305function: rsGetElementAt_#2#1 306version: 18 307w: 1, 2, 3, 4 308t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 309ret: #2#1 310arg: rs_allocation a 311arg: uint32_t x 312arg: uint32_t y 313arg: uint32_t z 314test: none 315end: 316 317function: rsGetElementAt_#2#1 318version: 23 319w: 1, 2, 3, 4 320t: f16 321ret: #2#1 322arg: rs_allocation a 323arg: uint32_t x 324test: none 325end: 326 327function: rsGetElementAt_#2#1 328version: 23 329w: 1, 2, 3, 4 330t: f16 331ret: #2#1 332arg: rs_allocation a 333arg: uint32_t x 334arg: uint32_t y 335test: none 336end: 337 338function: rsGetElementAt_#2#1 339version: 23 340w: 1, 2, 3, 4 341t: f16 342ret: #2#1 343arg: rs_allocation a 344arg: uint32_t x 345arg: uint32_t y 346arg: uint32_t z 347test: none 348end: 349 350function: rsGetElementAtYuv_uchar_U 351version: 18 352ret: uchar 353arg: rs_allocation a 354arg: uint32_t x 355arg: uint32_t y 356summary: Get the U component of an allocation of YUVs 357description: 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(). 365test: none 366end: 367 368function: rsGetElementAtYuv_uchar_V 369version: 18 370ret: uchar 371arg: rs_allocation a 372arg: uint32_t x 373arg: uint32_t y 374summary: Get the V component of an allocation of YUVs 375description: 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(). 383test: none 384end: 385 386function: rsGetElementAtYuv_uchar_Y 387version: 18 388ret: uchar 389arg: rs_allocation a 390arg: uint32_t x 391arg: uint32_t y 392summary: Get the Y component of an allocation of YUVs 393description: 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(). 401test: none 402end: 403 404function: rsSample 405version: 16 406ret: float4 407arg: rs_allocation a, "Allocation to sample from." 408arg: rs_sampler s, "Sampler state." 409arg: float location, "Location to sample from." 410summary: Sample a value from a texture allocation 411description: 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. 418test: none 419end: 420 421function: rsSample 422version: 16 423ret: float4 424arg: rs_allocation a 425arg: rs_sampler s 426arg: float location 427arg: float lod, "Mip level to sample from, for fractional values mip levels will be interpolated if RS_SAMPLER_LINEAR_MIP_LINEAR is used." 428test: none 429end: 430 431function: rsSample 432version: 16 433ret: float4 434arg: rs_allocation a 435arg: rs_sampler s 436arg: float2 location 437test: none 438end: 439 440function: rsSample 441version: 16 442ret: float4 443arg: rs_allocation a 444arg: rs_sampler s 445arg: float2 location 446arg: float lod 447test: none 448end: 449 450function: rsSetElementAt 451version: 18 452ret: void 453arg: rs_allocation a 454arg: void* ptr 455arg: uint32_t x 456summary: Set a cell of an allocation 457description: 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(). 470test: none 471end: 472 473function: rsSetElementAt 474version: 18 475ret: void 476arg: rs_allocation a 477arg: void* ptr 478arg: uint32_t x 479arg: uint32_t y 480test: none 481end: 482 483function: rsSetElementAt_#2#1 484version: 18 485w: 1, 2, 3, 4 486t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 487ret: void 488arg: rs_allocation a 489arg: #2#1 val 490arg: uint32_t x 491test: none 492end: 493 494function: rsSetElementAt_#2#1 495version: 18 496w: 1, 2, 3, 4 497t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 498ret: void 499arg: rs_allocation a 500arg: #2#1 val 501arg: uint32_t x 502arg: uint32_t y 503test: none 504end: 505 506function: rsSetElementAt_#2#1 507version: 18 508w: 1, 2, 3, 4 509t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 510ret: void 511arg: rs_allocation a 512arg: #2#1 val 513arg: uint32_t x 514arg: uint32_t y 515arg: uint32_t z 516test: none 517end: 518 519function: rsSetElementAt_#2#1 520version: 23 521w: 1, 2, 3, 4 522t: f16 523ret: void 524arg: rs_allocation a 525arg: #2#1 val 526arg: uint32_t x 527test: none 528end: 529 530function: rsSetElementAt_#2#1 531version: 23 532w: 1, 2, 3, 4 533t: f16 534ret: void 535arg: rs_allocation a 536arg: #2#1 val 537arg: uint32_t x 538arg: uint32_t y 539test: none 540end: 541 542function: rsSetElementAt_#2#1 543version: 23 544w: 1, 2, 3, 4 545t: f16 546ret: void 547arg: rs_allocation a 548arg: #2#1 val 549arg: uint32_t x 550arg: uint32_t y 551arg: uint32_t z 552test: none 553end: 554