rs_object_info.rsh revision 2a85b6b9d6f9cb8f1b20d573c1c5ceafe901b011
1/* 2 * Copyright (C) 2016 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// Don't edit this file! It is auto-generated by frameworks/rs/api/generate.sh. 18 19/* 20 * rs_object_info.rsh: Object Characteristics Functions 21 * 22 * The functions below can be used to query the characteristics of an Allocation, Element, 23 * or Sampler object. These objects are created from Java. You can't create them from a 24 * script. 25 * 26 * Allocations: 27 * 28 * Allocations are the primary method used to pass data to and from RenderScript kernels. 29 * 30 * They are a structured collection of cells that can be used to store bitmaps, textures, 31 * arbitrary data points, etc. 32 * 33 * This collection of cells may have many dimensions (X, Y, Z, Array0, Array1, Array2, Array3), 34 * faces (for cubemaps), and level of details (for mipmapping). 35 * 36 * See the android.renderscript.Allocation for details on to create Allocations. 37 * 38 * Elements: 39 * 40 * The term "element" is used a bit ambiguously in RenderScript, as both type information 41 * for the cells of an Allocation and the instantiation of that type. For example: 42 * - rs_element is a handle to a type specification, and 43 * - In functions like rsGetElementAt(), "element" means the instantiation of the type, 44 * i.e. a cell of an Allocation. 45 * 46 * The functions below let you query the characteristics of the type specificiation. 47 * 48 * An Element can specify a simple data types as found in C, e.g. an integer, float, or 49 * boolean. It can also specify a handle to a RenderScript object. See rs_data_type for 50 * a list of basic types. 51 * 52 * Elements can specify fixed size vector (of size 2, 3, or 4) versions of the basic types. 53 * Elements can be grouped together into complex Elements, creating the equivalent of 54 * C structure definitions. 55 * 56 * Elements can also have a kind, which is semantic information used to interpret pixel 57 * data. See rs_data_kind. 58 * 59 * When creating Allocations of common elements, you can simply use one of the many predefined 60 * Elements like F32_2. 61 * 62 * To create complex Elements, use the Element.Builder Java class. 63 * 64 * Samplers: 65 * 66 * Samplers objects define how Allocations can be read as structure within a kernel. 67 * See android.renderscript.S. 68 */ 69 70#ifndef RENDERSCRIPT_RS_OBJECT_INFO_RSH 71#define RENDERSCRIPT_RS_OBJECT_INFO_RSH 72 73/* 74 * rsAllocationGetDimFaces: Presence of more than one face 75 * 76 * If the Allocation is a cubemap, this function returns 1 if there's more than one face 77 * present. In all other cases, it returns 0. 78 * 79 * Use rsGetDimHasFaces() to get the dimension of a currently running kernel. 80 * 81 * Returns: Returns 1 if more than one face is present, 0 otherwise. 82 */ 83extern uint32_t __attribute__((overloadable)) 84 rsAllocationGetDimFaces(rs_allocation a); 85 86/* 87 * rsAllocationGetDimLOD: Presence of levels of detail 88 * 89 * Query an Allocation for the presence of more than one Level Of Detail. This is useful 90 * for mipmaps. 91 * 92 * Use rsGetDimLod() to get the dimension of a currently running kernel. 93 * 94 * Returns: Returns 1 if more than one LOD is present, 0 otherwise. 95 */ 96extern uint32_t __attribute__((overloadable)) 97 rsAllocationGetDimLOD(rs_allocation a); 98 99/* 100 * rsAllocationGetDimX: Size of the X dimension 101 * 102 * Returns the size of the X dimension of the Allocation. 103 * 104 * Use rsGetDimX() to get the dimension of a currently running kernel. 105 * 106 * Returns: X dimension of the Allocation. 107 */ 108extern uint32_t __attribute__((overloadable)) 109 rsAllocationGetDimX(rs_allocation a); 110 111/* 112 * rsAllocationGetDimY: Size of the Y dimension 113 * 114 * Returns the size of the Y dimension of the Allocation. If the Allocation has less 115 * than two dimensions, returns 0. 116 * 117 * Use rsGetDimY() to get the dimension of a currently running kernel. 118 * 119 * Returns: Y dimension of the Allocation. 120 */ 121extern uint32_t __attribute__((overloadable)) 122 rsAllocationGetDimY(rs_allocation a); 123 124/* 125 * rsAllocationGetDimZ: Size of the Z dimension 126 * 127 * Returns the size of the Z dimension of the Allocation. If the Allocation has less 128 * than three dimensions, returns 0. 129 * 130 * Use rsGetDimZ() to get the dimension of a currently running kernel. 131 * 132 * Returns: Z dimension of the Allocation. 133 */ 134extern uint32_t __attribute__((overloadable)) 135 rsAllocationGetDimZ(rs_allocation a); 136 137/* 138 * rsAllocationGetElement: Get the object that describes the cell of an Allocation 139 * 140 * Get the Element object describing the type, kind, and other characteristics of a cell 141 * of an Allocation. See the rsElement* functions below. 142 * 143 * Parameters: 144 * a: Allocation to get data from. 145 * 146 * Returns: Element describing Allocation layout. 147 */ 148extern rs_element __attribute__((overloadable)) 149 rsAllocationGetElement(rs_allocation a); 150 151/* 152 * rsClearObject: Release an object 153 * 154 * Tells the run time that this handle will no longer be used to access the the related 155 * object. If this was the last handle to that object, resource recovery may happen. 156 * 157 * After calling this function, *dst will be set to an empty handle. See rsIsObject(). 158 */ 159extern void __attribute__((overloadable)) 160 rsClearObject(rs_element* dst); 161 162extern void __attribute__((overloadable)) 163 rsClearObject(rs_type* dst); 164 165extern void __attribute__((overloadable)) 166 rsClearObject(rs_allocation* dst); 167 168extern void __attribute__((overloadable)) 169 rsClearObject(rs_sampler* dst); 170 171extern void __attribute__((overloadable)) 172 rsClearObject(rs_script* dst); 173 174/* 175 * rsIsObject: Check for an empty handle 176 * 177 * Returns true if the handle contains a non-null reference. 178 * 179 * This function does not validate that the internal pointer used in the handle 180 * points to an actual valid object; it only checks for null. 181 * 182 * This function can be used to check the Element returned by rsElementGetSubElement() 183 * or see if rsClearObject() has been called on a handle. 184 */ 185extern bool __attribute__((overloadable)) 186 rsIsObject(rs_element v); 187 188extern bool __attribute__((overloadable)) 189 rsIsObject(rs_type v); 190 191extern bool __attribute__((overloadable)) 192 rsIsObject(rs_allocation v); 193 194extern bool __attribute__((overloadable)) 195 rsIsObject(rs_sampler v); 196 197extern bool __attribute__((overloadable)) 198 rsIsObject(rs_script v); 199 200/* 201 * rsElementGetBytesSize: Size of an Element 202 * 203 * Returns the size in bytes that an instantiation of this Element will occupy. 204 */ 205#if (defined(RS_VERSION) && (RS_VERSION >= 16)) 206extern uint32_t __attribute__((overloadable)) 207 rsElementGetBytesSize(rs_element e); 208#endif 209 210/* 211 * rsElementGetDataKind: Kind of an Element 212 * 213 * Returns the Element's data kind. This is used to interpret pixel data. 214 * 215 * See rs_data_kind. 216 */ 217#if (defined(RS_VERSION) && (RS_VERSION >= 16)) 218extern rs_data_kind __attribute__((overloadable)) 219 rsElementGetDataKind(rs_element e); 220#endif 221 222/* 223 * rsElementGetDataType: Data type of an Element 224 * 225 * Returns the Element's base data type. This can be a type similar to C/C++ (e.g. 226 * RS_TYPE_UNSIGNED_8), a handle (e.g. RS_TYPE_ALLOCATION and RS_TYPE_ELEMENT), or a 227 * more complex numerical type (e.g. RS_TYPE_UNSIGNED_5_6_5 and RS_TYPE_MATRIX_4X4). 228 * See rs_data_type. 229 * 230 * If the Element describes a vector, this function returns the data type of one of its items. 231 * Use rsElementGetVectorSize to get the size of the vector. 232 * 233 * If the Element describes a structure, RS_TYPE_NONE is returned. Use the rsElementGetSub* 234 * functions to explore this complex Element. 235 */ 236#if (defined(RS_VERSION) && (RS_VERSION >= 16)) 237extern rs_data_type __attribute__((overloadable)) 238 rsElementGetDataType(rs_element e); 239#endif 240 241/* 242 * rsElementGetSubElement: Sub-element of a complex Element 243 * 244 * For Elements that represents a structure, this function returns the sub-element at the 245 * specified index. 246 * 247 * If the Element is not a structure or the index is greater or equal to the number of 248 * sub-elements, an invalid handle is returned. 249 * 250 * Parameters: 251 * e: Element to query. 252 * index: Index of the sub-element to return. 253 * 254 * Returns: Sub-element at the given index. 255 */ 256#if (defined(RS_VERSION) && (RS_VERSION >= 16)) 257extern rs_element __attribute__((overloadable)) 258 rsElementGetSubElement(rs_element e, uint32_t index); 259#endif 260 261/* 262 * rsElementGetSubElementArraySize: Array size of a sub-element of a complex Element 263 * 264 * For complex Elements, sub-elements can be statically sized arrays. This function 265 * returns the array size of the sub-element at the index. This sub-element repetition 266 * is different than fixed size vectors. 267 * 268 * Parameters: 269 * e: Element to query. 270 * index: Index of the sub-element. 271 * 272 * Returns: Array size of the sub-element. 273 */ 274#if (defined(RS_VERSION) && (RS_VERSION >= 16)) 275extern uint32_t __attribute__((overloadable)) 276 rsElementGetSubElementArraySize(rs_element e, uint32_t index); 277#endif 278 279/* 280 * rsElementGetSubElementCount: Number of sub-elements 281 * 282 * Elements can be simple, such as an int or a float, or a structure with multiple 283 * sub-elements. This function returns zero for simple Elements and the number of 284 * sub-elements for complex Elements. 285 * 286 * Parameters: 287 * e: Element to get data from. 288 * 289 * Returns: Number of sub-elements. 290 */ 291#if (defined(RS_VERSION) && (RS_VERSION >= 16)) 292extern uint32_t __attribute__((overloadable)) 293 rsElementGetSubElementCount(rs_element e); 294#endif 295 296/* 297 * rsElementGetSubElementName: Name of a sub-element 298 * 299 * For complex Elements, this function returns the name of the sub-element at the 300 * specified index. 301 * 302 * Parameters: 303 * e: Element to get data from. 304 * index: Index of the sub-element. 305 * name: Address of the array to store the name into. 306 * nameLength: Length of the provided name array. 307 * 308 * Returns: Number of characters copied, excluding the null terminator. 309 */ 310#if (defined(RS_VERSION) && (RS_VERSION >= 16)) 311extern uint32_t __attribute__((overloadable)) 312 rsElementGetSubElementName(rs_element e, uint32_t index, char* name, uint32_t nameLength); 313#endif 314 315/* 316 * rsElementGetSubElementNameLength: Length of the name of a sub-element 317 * 318 * For complex Elements, this function returns the length of the name of the sub-element 319 * at the specified index. 320 * 321 * Parameters: 322 * e: Element to get data from. 323 * index: Index of the sub-element. 324 * 325 * Returns: Length of the sub-element name including the null terminator. 326 */ 327#if (defined(RS_VERSION) && (RS_VERSION >= 16)) 328extern uint32_t __attribute__((overloadable)) 329 rsElementGetSubElementNameLength(rs_element e, uint32_t index); 330#endif 331 332/* 333 * rsElementGetSubElementOffsetBytes: Offset of the instantiated sub-element 334 * 335 * This function returns the relative position of the instantiation of the specified 336 * sub-element within the instantiation of the Element. 337 * 338 * For example, if the Element describes a 32 bit float followed by a 32 bit integer, 339 * the offset return for the first will be 0 and the second 4. 340 * 341 * Parameters: 342 * e: Element to get data from. 343 * index: Index of the sub-element. 344 * 345 * Returns: Offset in bytes. 346 */ 347#if (defined(RS_VERSION) && (RS_VERSION >= 16)) 348extern uint32_t __attribute__((overloadable)) 349 rsElementGetSubElementOffsetBytes(rs_element e, uint32_t index); 350#endif 351 352/* 353 * rsElementGetVectorSize: Vector size of the Element 354 * 355 * Returns the Element's vector size. If the Element does not represent a vector, 356 * 1 is returned. 357 * 358 * Parameters: 359 * e: Element to get data from. 360 * 361 * Returns: Length of the element vector. 362 */ 363#if (defined(RS_VERSION) && (RS_VERSION >= 16)) 364extern uint32_t __attribute__((overloadable)) 365 rsElementGetVectorSize(rs_element e); 366#endif 367 368/* 369 * rsGetAllocation: Return the Allocation for a given pointer 370 * 371 * DEPRECATED. Do not use. 372 * 373 * Returns the Allocation for a given pointer. The pointer should point within a valid 374 * allocation. The results are undefined if the pointer is not from a valid Allocation. 375 */ 376extern rs_allocation __attribute__((overloadable 377#if (defined(RS_VERSION) && (RS_VERSION >= 22)) 378, deprecated("This function is deprecated and will be removed from the SDK in a future release.") 379#endif 380)) 381 rsGetAllocation(const void* p); 382 383/* 384 * rsSamplerGetAnisotropy: Anisotropy of the Sampler 385 * 386 * Get the Sampler's anisotropy. 387 * 388 * See android.renderscript.S. 389 */ 390#if (defined(RS_VERSION) && (RS_VERSION >= 16)) 391extern float __attribute__((overloadable)) 392 rsSamplerGetAnisotropy(rs_sampler s); 393#endif 394 395/* 396 * rsSamplerGetMagnification: Sampler magnification value 397 * 398 * Get the Sampler's magnification value. 399 * 400 * See android.renderscript.S. 401 */ 402#if (defined(RS_VERSION) && (RS_VERSION >= 16)) 403extern rs_sampler_value __attribute__((overloadable)) 404 rsSamplerGetMagnification(rs_sampler s); 405#endif 406 407/* 408 * rsSamplerGetMinification: Sampler minification value 409 * 410 * Get the Sampler's minification value. 411 * 412 * See android.renderscript.S. 413 */ 414#if (defined(RS_VERSION) && (RS_VERSION >= 16)) 415extern rs_sampler_value __attribute__((overloadable)) 416 rsSamplerGetMinification(rs_sampler s); 417#endif 418 419/* 420 * rsSamplerGetWrapS: Sampler wrap S value 421 * 422 * Get the Sampler's wrap S value. 423 * 424 * See android.renderscript.S. 425 */ 426#if (defined(RS_VERSION) && (RS_VERSION >= 16)) 427extern rs_sampler_value __attribute__((overloadable)) 428 rsSamplerGetWrapS(rs_sampler s); 429#endif 430 431/* 432 * rsSamplerGetWrapT: Sampler wrap T value 433 * 434 * Get the sampler's wrap T value. 435 * 436 * See android.renderscript.S. 437 */ 438#if (defined(RS_VERSION) && (RS_VERSION >= 16)) 439extern rs_sampler_value __attribute__((overloadable)) 440 rsSamplerGetWrapT(rs_sampler s); 441#endif 442 443/* 444 * rsSetObject: For internal use. 445 * 446 */ 447extern void __attribute__((overloadable)) 448 rsSetObject(rs_element* dst, rs_element src); 449 450extern void __attribute__((overloadable)) 451 rsSetObject(rs_type* dst, rs_type src); 452 453extern void __attribute__((overloadable)) 454 rsSetObject(rs_allocation* dst, rs_allocation src); 455 456extern void __attribute__((overloadable)) 457 rsSetObject(rs_sampler* dst, rs_sampler src); 458 459extern void __attribute__((overloadable)) 460 rsSetObject(rs_script* dst, rs_script src); 461 462#endif // RENDERSCRIPT_RS_OBJECT_INFO_RSH 463