rs_allocation_data.spec revision 20b27d602a4778ed50a83df2147416a35b7c92be
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), 108 an int4 composed 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 111 variant. Similarly, use the x, y variant for two dimensional 112 allocations and x for the mono dimensional allocations. 113 114 For efficiency, this function does not validate the inputs. Trying to 115 wrap the X index, exceeding the size of the allocation, or using indexes 116 incompatible 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 156 allocation. It assumes that the allocation contains scalars. 157 158 The "X" in the name indicates that successive values are stored by 159 increasing the X index. There are currently no functions to store successive 160 values incrementing other dimensions. Use multiple calls to rsSetElementAt() 161 instead. 162 163 For example, when calling rsAllocationVStoreX_int3(a, v, 20, 30), 164 v.x is stored at a[20, 30], v.y at a[21, 30], and v.z at a[22, 30]. 165 166 When storing into a three dimensional allocations, use the x, y, z 167 variant. Similarly, use the x, y variant for two dimensional 168 allocations and x for the mono dimensional allocations. 169 170 For efficiency, this function does not validate the inputs. Trying to 171 wrap the X index, exceeding the size of the allocation, or using indexes 172 incompatible with the dimensionality of the allocation yiels undefined results. 173 174 See also @rsAllocationVLoadX(). 175test: none 176end: 177 178function: rsAllocationVStoreX_#2#1 179version: 22 180w: 2, 3, 4 181t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 182ret: void 183arg: rs_allocation a 184arg: #2#1 val 185arg: uint32_t x 186arg: uint32_t y, "Y offset in the allocation of the first cell to be copied into." 187test: none 188end: 189 190function: rsAllocationVStoreX_#2#1 191version: 22 192w: 2, 3, 4 193t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 194ret: void 195arg: rs_allocation a 196arg: #2#1 val 197arg: uint32_t x 198arg: uint32_t y 199arg: uint32_t z, "Z offset in the allocation of the first cell to be copied into." 200test: none 201end: 202 203function: rsGetElementAt 204ret: const void* 205arg: rs_allocation a 206arg: uint32_t x 207summary: Return a cell from an allocation 208description: 209 This function extracts a single cell from an allocation. 210 211 When retrieving from a three dimensional allocations, use the x, y, z 212 variant. Similarly, use the x, y variant for two dimensional 213 allocations and x for the mono dimensional allocations. 214 215 This function has two styles. One returns the address of the value using a 216 void*, the other returns the actual value, e.g. rsGetElementAt() vs. 217 rsGetElementAt_int4(). For primitive types, always use the latter as it is 218 more efficient. 219test: none 220end: 221 222function: rsGetElementAt 223ret: const void* 224arg: rs_allocation a 225arg: uint32_t x 226arg: uint32_t y 227test: none 228end: 229 230function: rsGetElementAt 231ret: const void* 232arg: rs_allocation a 233arg: uint32_t x 234arg: uint32_t y 235arg: uint32_t z 236test: none 237end: 238 239function: rsGetElementAt_#2#1 240version: 9 17 241w: 1, 2, 3, 4 242t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 243ret: #2#1 244arg: rs_allocation a 245arg: uint32_t x 246inline: 247 return ((#2#1 *)rsGetElementAt(a, x))[0]; 248test: none 249end: 250 251function: rsGetElementAt_#2#1 252version: 9 17 253w: 1, 2, 3, 4 254t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 255ret: #2#1 256arg: rs_allocation a 257arg: uint32_t x 258arg: uint32_t y 259inline: 260 return ((#2#1 *)rsGetElementAt(a, x, y))[0]; 261test: none 262end: 263 264function: rsGetElementAt_#2#1 265version: 9 17 266w: 1, 2, 3, 4 267t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 268ret: #2#1 269arg: rs_allocation a 270arg: uint32_t x 271arg: uint32_t y 272arg: uint32_t z 273inline: 274 return ((#2#1 *)rsGetElementAt(a, x, y, z))[0]; 275test: none 276end: 277 278function: rsGetElementAt_#2#1 279version: 18 280w: 1, 2, 3, 4 281t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 282ret: #2#1 283arg: rs_allocation a 284arg: uint32_t x 285test: none 286end: 287 288function: rsGetElementAt_#2#1 289version: 18 290w: 1, 2, 3, 4 291t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 292ret: #2#1 293arg: rs_allocation a 294arg: uint32_t x 295arg: uint32_t y 296test: none 297end: 298 299function: rsGetElementAt_#2#1 300version: 18 301w: 1, 2, 3, 4 302t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 303ret: #2#1 304arg: rs_allocation a 305arg: uint32_t x 306arg: uint32_t y 307arg: uint32_t z 308test: none 309end: 310 311function: rsGetElementAtYuv_uchar_U 312version: 18 313ret: uchar 314arg: rs_allocation a 315arg: uint32_t x 316arg: uint32_t y 317summary: Get the U component of an allocation of YUVs 318description: 319 Extracts the U component of a single YUV value from a 2D allocation of YUVs. 320 321 Inside an allocation, Y, U, and V components may be stored if different planes 322 and at different resolutions. The x, y coordinates provided here are in the 323 dimensions of the Y plane. 324 325 See @rsGetElementAtYuv_uchar_Y(). 326test: none 327end: 328 329function: rsGetElementAtYuv_uchar_V 330version: 18 331ret: uchar 332arg: rs_allocation a 333arg: uint32_t x 334arg: uint32_t y 335summary: Get the V component of an allocation of YUVs 336description: 337 Extracts the V component of a single YUV value from a 2D allocation of YUVs. 338 339 Inside an allocation, Y, U, and V components may be stored if different planes 340 and at different resolutions. The x, y coordinates provided here are in the 341 dimensions of the Y plane. 342 343 See @rsGetElementAtYuv_uchar_Y(). 344test: none 345end: 346 347function: rsGetElementAtYuv_uchar_Y 348version: 18 349ret: uchar 350arg: rs_allocation a 351arg: uint32_t x 352arg: uint32_t y 353summary: Get the Y component of an allocation of YUVs 354description: 355 Extracts the Y component of a single YUV value from a 2D allocation of YUVs. 356 357 Inside an allocation, Y, U, and V components may be stored if different planes 358 and at different resolutions. The x, y coordinates provided here are in the 359 dimensions of the Y plane. 360 361 See @rsGetElementAtYuv_uchar_U() and @rsGetElementAtYuv_uchar_V(). 362test: none 363end: 364 365function: rsSample 366version: 16 367ret: float4 368arg: rs_allocation a, "Allocation to sample from." 369arg: rs_sampler s, "Sampler state." 370arg: float location, "Location to sample from." 371summary: Sample a value from a texture allocation 372description: 373 Fetches a value from a texture allocation in a way described by the sampler. 374 375 If your allocation is 1D, use the variant with float for location. For 2D, 376 use the float2 variant. 377 378 See <a href='http://developer.android.com/reference/android/renderscript/Sampler.html'>android.renderscript.Sampler</a> for more details. 379test: none 380end: 381 382function: rsSample 383version: 16 384ret: float4 385arg: rs_allocation a 386arg: rs_sampler s 387arg: float location 388arg: float lod, "Mip level to sample from, for fractional values mip levels will be interpolated if RS_SAMPLER_LINEAR_MIP_LINEAR is used." 389test: none 390end: 391 392function: rsSample 393version: 16 394ret: float4 395arg: rs_allocation a 396arg: rs_sampler s 397arg: float2 location 398test: none 399end: 400 401function: rsSample 402version: 16 403ret: float4 404arg: rs_allocation a 405arg: rs_sampler s 406arg: float2 location 407arg: float lod 408test: none 409end: 410 411function: rsSetElementAt 412version: 18 413ret: void 414arg: rs_allocation a 415arg: void* ptr 416arg: uint32_t x 417summary: Set a cell of an allocation 418description: 419 This function stores a value into a single cell of an allocation. 420 421 When storing into a three dimensional allocations, use the x, y, z 422 variant. Similarly, use the x, y variant for two dimensional 423 allocations and x for the mono dimensional allocations. 424 425 This function has two styles. One passes the value to be stored using 426 a void*, the other has the actual value as an argument, e.g. rsSetElementAt() 427 vs. rsSetElementAt_int4(). For primitive types, always use the latter as it is 428 more efficient. 429 430 See also @rsGetElementAt(). 431test: none 432end: 433 434function: rsSetElementAt 435version: 18 436ret: void 437arg: rs_allocation a 438arg: void* ptr 439arg: uint32_t x 440arg: uint32_t y 441test: none 442end: 443 444function: rsSetElementAt_#2#1 445version: 18 446w: 1, 2, 3, 4 447t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 448ret: void 449arg: rs_allocation a 450arg: #2#1 val 451arg: uint32_t x 452test: none 453end: 454 455function: rsSetElementAt_#2#1 456version: 18 457w: 1, 2, 3, 4 458t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 459ret: void 460arg: rs_allocation a 461arg: #2#1 val 462arg: uint32_t x 463arg: uint32_t y 464test: none 465end: 466 467function: rsSetElementAt_#2#1 468version: 18 469w: 1, 2, 3, 4 470t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64 471ret: void 472arg: rs_allocation a 473arg: #2#1 val 474arg: uint32_t x 475arg: uint32_t y 476arg: uint32_t z 477test: none 478end: 479