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