| # | |
| # Copyright (C) 2014 The Android Open Source Project | |
| # | |
| # Licensed under the Apache License, Version 2.0 (the "License"); | |
| # you may not use this file except in compliance with the License. | |
| # You may obtain a copy of the License at | |
| # | |
| # http://www.apache.org/licenses/LICENSE-2.0 | |
| # | |
| # Unless required by applicable law or agreed to in writing, software | |
| # distributed under the License is distributed on an "AS IS" BASIS, | |
| # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
| # See the License for the specific language governing permissions and | |
| # limitations under the License. | |
| # | |
| header: | |
| summary: Object Characteristics Functions | |
| description: | |
| The functions below can be used to query the characteristics of an Allocation, Element, | |
| or Sampler object. These objects are created from Java. You can't create them from a | |
| script. | |
| <h5>Allocations:</h5> | |
| Allocations are the primary method used to pass data to and from RenderScript kernels. | |
| They are a structured collection of cells that can be used to store bitmaps, textures, | |
| arbitrary data points, etc. | |
| This collection of cells may have many dimensions (X, Y, Z, Array0, Array1, Array2, Array3), | |
| faces (for cubemaps), and level of details (for mipmapping). | |
| See the <a href='http://developer.android.com/reference/android/renderscript/Allocation.html'>android.renderscript.Allocation</a> for details on to create Allocations. | |
| <h5>Elements:</h5> | |
| The term "element" is used a bit ambiguously in RenderScript, as both type information | |
| for the cells of an Allocation and the instantiation of that type. For example:<ul> | |
| <li>@rs_element is a handle to a type specification, and</li> | |
| <li>In functions like @rsGetElementAt(), "element" means the instantiation of the type, | |
| i.e. a cell of an Allocation.</li></ul> | |
| The functions below let you query the characteristics of the type specificiation. | |
| An Element can specify a simple data types as found in C, e.g. an integer, float, or | |
| boolean. It can also specify a handle to a RenderScript object. See @rs_data_type for | |
| a list of basic types. | |
| Elements can specify fixed size vector (of size 2, 3, or 4) versions of the basic types. | |
| Elements can be grouped together into complex Elements, creating the equivalent of | |
| C structure definitions. | |
| Elements can also have a kind, which is semantic information used to interpret pixel | |
| data. See @rs_data_kind. | |
| When creating Allocations of common elements, you can simply use one of the many predefined | |
| Elements like <a href='http://developer.android.com/reference/android/renderscript/Element.html#F32_2(android.renderscript.RenderScript)'>F32_2</a>. | |
| To create complex Elements, use the <a href='http://developer.android.com/reference/android/renderscript/Element.Builder.html'>Element.Builder</a> Java class. | |
| <h5>Samplers:</h5> | |
| Samplers objects define how Allocations can be read as structure within a kernel. | |
| See <a href='http://developer.android.com/reference/android/renderscript/Sampler.html'>android.renderscript.S</a>. | |
| end: | |
| function: rsAllocationGetDimFaces | |
| ret: uint32_t, "Returns 1 if more than one face is present, 0 otherwise." | |
| arg: rs_allocation a | |
| summary: Presence of more than one face | |
| description: | |
| If the Allocation is a cubemap, this function returns 1 if there's more than one face | |
| present. In all other cases, it returns 0. | |
| Use @rsGetDimHasFaces() to get the dimension of a currently running kernel. | |
| test: none | |
| end: | |
| function: rsAllocationGetDimLOD | |
| ret: uint32_t, "Returns 1 if more than one LOD is present, 0 otherwise." | |
| arg: rs_allocation a | |
| summary: Presence of levels of detail | |
| description: | |
| Query an Allocation for the presence of more than one Level Of Detail. This is useful | |
| for mipmaps. | |
| Use @rsGetDimLod() to get the dimension of a currently running kernel. | |
| test: none | |
| end: | |
| function: rsAllocationGetDimX | |
| ret: uint32_t, "X dimension of the Allocation." | |
| arg: rs_allocation a | |
| summary: Size of the X dimension | |
| description: | |
| Returns the size of the X dimension of the Allocation. | |
| Use @rsGetDimX() to get the dimension of a currently running kernel. | |
| test: none | |
| end: | |
| function: rsAllocationGetDimY | |
| ret: uint32_t, "Y dimension of the Allocation." | |
| arg: rs_allocation a | |
| summary: Size of the Y dimension | |
| description: | |
| Returns the size of the Y dimension of the Allocation. If the Allocation has less | |
| than two dimensions, returns 0. | |
| Use @rsGetDimY() to get the dimension of a currently running kernel. | |
| test: none | |
| end: | |
| function: rsAllocationGetDimZ | |
| ret: uint32_t, "Z dimension of the Allocation." | |
| arg: rs_allocation a | |
| summary: Size of the Z dimension | |
| description: | |
| Returns the size of the Z dimension of the Allocation. If the Allocation has less | |
| than three dimensions, returns 0. | |
| Use @rsGetDimZ() to get the dimension of a currently running kernel. | |
| test: none | |
| end: | |
| function: rsAllocationGetElement | |
| ret: rs_element, "Element describing Allocation layout." | |
| arg: rs_allocation a, "Allocation to get data from." | |
| summary: Get the object that describes the cell of an Allocation | |
| description: | |
| Get the Element object describing the type, kind, and other characteristics of a cell | |
| of an Allocation. See the rsElement* functions below. | |
| test: none | |
| end: | |
| function: rsClearObject | |
| t: rs_element, rs_type, rs_allocation, rs_sampler, rs_script | |
| ret: void | |
| arg: #1* dst | |
| summary: Release an object | |
| description: | |
| Tells the run time that this handle will no longer be used to access the the related | |
| object. If this was the last handle to that object, resource recovery may happen. | |
| After calling this function, *dst will be set to an empty handle. See @rsIsObject(). | |
| test: none | |
| end: | |
| function: rsIsObject | |
| t: rs_element, rs_type, rs_allocation, rs_sampler, rs_script | |
| ret: bool | |
| arg: #1 v | |
| summary: Check for an empty handle | |
| description: | |
| Returns true if the handle contains a non-null reference. | |
| This function does not validate that the internal pointer used in the handle | |
| points to an actual valid object; it only checks for null. | |
| This function can be used to check the Element returned by @rsElementGetSubElement() | |
| or see if @rsClearObject() has been called on a handle. | |
| test: none | |
| end: | |
| function: rsElementGetBytesSize | |
| version: 16 | |
| ret: uint32_t | |
| arg: rs_element e | |
| summary: Size of an Element | |
| description: | |
| Returns the size in bytes that an instantiation of this Element will occupy. | |
| test: none | |
| end: | |
| function: rsElementGetDataKind | |
| version: 16 | |
| ret: rs_data_kind | |
| arg: rs_element e | |
| summary: Kind of an Element | |
| description: | |
| Returns the Element's data kind. This is used to interpret pixel data. | |
| See @rs_data_kind. | |
| test: none | |
| end: | |
| function: rsElementGetDataType | |
| version: 16 | |
| ret: rs_data_type | |
| arg: rs_element e | |
| summary: Data type of an Element | |
| description: | |
| Returns the Element's base data type. This can be a type similar to C/C++ (e.g. | |
| RS_TYPE_UNSIGNED_8), a handle (e.g. RS_TYPE_ALLOCATION and RS_TYPE_ELEMENT), or a | |
| more complex numerical type (e.g. RS_TYPE_UNSIGNED_5_6_5 and RS_TYPE_MATRIX_4X4). | |
| See @rs_data_type. | |
| If the Element describes a vector, this function returns the data type of one of its items. | |
| Use @rsElementGetVectorSize to get the size of the vector. | |
| If the Element describes a structure, RS_TYPE_NONE is returned. Use the rsElementGetSub* | |
| functions to explore this complex Element. | |
| test: none | |
| end: | |
| function: rsElementGetSubElement | |
| version: 16 | |
| ret: rs_element, "Sub-element at the given index." | |
| arg: rs_element e, "Element to query." | |
| arg: uint32_t index, "Index of the sub-element to return." | |
| summary: Sub-element of a complex Element | |
| description: | |
| For Elements that represents a structure, this function returns the sub-element at the | |
| specified index. | |
| If the Element is not a structure or the index is greater or equal to the number of | |
| sub-elements, an invalid handle is returned. | |
| test: none | |
| end: | |
| function: rsElementGetSubElementArraySize | |
| version: 16 | |
| ret: uint32_t, "Array size of the sub-element." | |
| arg: rs_element e, "Element to query." | |
| arg: uint32_t index, "Index of the sub-element." | |
| summary: Array size of a sub-element of a complex Element | |
| description: | |
| For complex Elements, sub-elements can be statically sized arrays. This function | |
| returns the array size of the sub-element at the index. This sub-element repetition | |
| is different than fixed size vectors. | |
| test: none | |
| end: | |
| function: rsElementGetSubElementCount | |
| version: 16 | |
| ret: uint32_t, "Number of sub-elements." | |
| arg: rs_element e, "Element to get data from." | |
| summary: Number of sub-elements | |
| description: | |
| Elements can be simple, such as an int or a float, or a structure with multiple | |
| sub-elements. This function returns zero for simple Elements and the number of | |
| sub-elements for complex Elements. | |
| test: none | |
| end: | |
| function: rsElementGetSubElementName | |
| version: 16 | |
| ret: uint32_t, "Number of characters copied, excluding the null terminator." | |
| arg: rs_element e, "Element to get data from." | |
| arg: uint32_t index, "Index of the sub-element." | |
| arg: char* name, "Address of the array to store the name into." | |
| arg: uint32_t nameLength, "Length of the provided name array." | |
| summary: Name of a sub-element | |
| description: | |
| For complex Elements, this function returns the name of the sub-element at the | |
| specified index. | |
| test: none | |
| end: | |
| function: rsElementGetSubElementNameLength | |
| version: 16 | |
| ret: uint32_t, "Length of the sub-element name including the null terminator." | |
| arg: rs_element e, "Element to get data from." | |
| arg: uint32_t index, "Index of the sub-element." | |
| summary: Length of the name of a sub-element | |
| description: | |
| For complex Elements, this function returns the length of the name of the sub-element | |
| at the specified index. | |
| test: none | |
| end: | |
| function: rsElementGetSubElementOffsetBytes | |
| version: 16 | |
| ret: uint32_t, "Offset in bytes." | |
| arg: rs_element e, "Element to get data from." | |
| arg: uint32_t index, "Index of the sub-element." | |
| summary: Offset of the instantiated sub-element | |
| description: | |
| This function returns the relative position of the instantiation of the specified | |
| sub-element within the instantiation of the Element. | |
| For example, if the Element describes a 32 bit float followed by a 32 bit integer, | |
| the offset return for the first will be 0 and the second 4. | |
| test: none | |
| end: | |
| function: rsElementGetVectorSize | |
| version: 16 | |
| ret: uint32_t, "Length of the element vector." | |
| arg: rs_element e, "Element to get data from." | |
| summary: Vector size of the Element | |
| description: | |
| Returns the Element's vector size. If the Element does not represent a vector, | |
| 1 is returned. | |
| test: none | |
| end: | |
| function: rsGetAllocation | |
| ret: rs_allocation | |
| arg: const void* p | |
| deprecated: This function is deprecated and will be removed from the SDK in a future release. | |
| summary: Return the Allocation for a given pointer | |
| description: | |
| Returns the Allocation for a given pointer. The pointer should point within a valid | |
| allocation. The results are undefined if the pointer is not from a valid Allocation. | |
| test: none | |
| end: | |
| function: rsSamplerGetAnisotropy | |
| version: 16 | |
| ret: float | |
| arg: rs_sampler s | |
| summary: Anisotropy of the Sampler | |
| description: | |
| Get the Sampler's anisotropy. | |
| See <a href='http://developer.android.com/reference/android/renderscript/Sampler.html'>android.renderscript.S</a>. | |
| test: none | |
| end: | |
| function: rsSamplerGetMagnification | |
| version: 16 | |
| ret: rs_sampler_value | |
| arg: rs_sampler s | |
| summary: Sampler magnification value | |
| description: | |
| Get the Sampler's magnification value. | |
| See <a href='http://developer.android.com/reference/android/renderscript/Sampler.html'>android.renderscript.S</a>. | |
| test: none | |
| end: | |
| function: rsSamplerGetMinification | |
| version: 16 | |
| ret: rs_sampler_value | |
| arg: rs_sampler s | |
| summary: Sampler minification value | |
| description: | |
| Get the Sampler's minification value. | |
| See <a href='http://developer.android.com/reference/android/renderscript/Sampler.html'>android.renderscript.S</a>. | |
| test: none | |
| end: | |
| function: rsSamplerGetWrapS | |
| version: 16 | |
| ret: rs_sampler_value | |
| arg: rs_sampler s | |
| summary: Sampler wrap S value | |
| description: | |
| Get the Sampler's wrap S value. | |
| See <a href='http://developer.android.com/reference/android/renderscript/Sampler.html'>android.renderscript.S</a>. | |
| test: none | |
| end: | |
| function: rsSamplerGetWrapT | |
| version: 16 | |
| ret: rs_sampler_value | |
| arg: rs_sampler s | |
| summary: Sampler wrap T value | |
| description: | |
| Get the sampler's wrap T value. | |
| See <a href='http://developer.android.com/reference/android/renderscript/Sampler.html'>android.renderscript.S</a>. | |
| test: none | |
| end: | |
| function: rsSetObject | |
| t: rs_element, rs_type, rs_allocation, rs_sampler, rs_script | |
| ret: void | |
| arg: #1* dst | |
| arg: #1 src | |
| hidden: | |
| summary: For internal use. | |
| description: | |
| test: none | |
| end: |