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