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