renderscript/include/rs_object_info.rsh

/*
 * Copyright (C) 2015 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.
 */

// Don't edit this file!  It is auto-generated by frameworks/rs/api/generate.sh.

/*
 * rs_object_info.rsh: Object Characteristics Functions
 *
 * The functions below can be used to query the characteristics of an allocation,
 * element, or sampler object.  These objects are created from Java.
 *
 * The term "element" is used a bit ambiguously in RenderScript, as both
 * the type of an item of an allocation and the instantiation of that type:
 * - rs_element is a handle to a type specification, and
 * - In functions like rsGetElementAt(), "element" means the instantiation
 *     of the type, i.e. an item of an allocation.
 *
 * The functions below let you query the characteristics of the type specificiation.
 *
 * To create complex elements, use the Element.Builder Java class.
 * For common elements, in Java you can simply use one of the many predefined elements
 * like F32_2.  You can't create elements from a script.
 *
 * An element can be a simple data type as found in C/C++, a handle type,
 * a structure, or a fixed size vector (of size 2, 3, or 4) of sub-elements.
 *
 * Elements can also have a kind, which is semantic information used mostly to
 * interpret pixel data.
 */

#ifndef RENDERSCRIPT_RS_OBJECT_INFO_RSH
#define RENDERSCRIPT_RS_OBJECT_INFO_RSH

/*
 * rsAllocationGetDimFaces: Presence of more than one face
 *
 * 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.
 *
 * Returns: Returns 1 if more than one face is present, 0 otherwise.
 */
extern uint32_t __attribute__((overloadable))
    rsAllocationGetDimFaces(rs_allocation a);

/*
 * rsAllocationGetDimLOD: Presence of levels of detail
 *
 * 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.
 *
 * Returns: Returns 1 if more than one LOD is present, 0 otherwise.
 */
extern uint32_t __attribute__((overloadable))
    rsAllocationGetDimLOD(rs_allocation a);

/*
 * rsAllocationGetDimX: Size of the X dimension
 *
 * Returns the size of the X dimension of the allocation.
 *
 * Use rsGetDimX() to get the dimension of a currently running kernel.
 *
 * Returns: The X dimension of the allocation.
 */
extern uint32_t __attribute__((overloadable))
    rsAllocationGetDimX(rs_allocation a);

/*
 * rsAllocationGetDimY: Size of the Y dimension
 *
 * 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.
 *
 * Returns: The Y dimension of the allocation.
 */
extern uint32_t __attribute__((overloadable))
    rsAllocationGetDimY(rs_allocation a);

/*
 * rsAllocationGetDimZ: Size of the Z dimension
 *
 * 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.
 *
 * Returns: The Z dimension of the allocation.
 */
extern uint32_t __attribute__((overloadable))
    rsAllocationGetDimZ(rs_allocation a);

/*
 * Get the element object describing the allocation's layout
 *
 * Parameters:
 *   a: allocation to get data from
 *
 * Returns: element describing allocation layout
 */
extern rs_element __attribute__((overloadable))
    rsAllocationGetElement(rs_allocation a);

/*
 * rsClearObject: Release an object
 *
 * 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().
 */
extern void __attribute__((overloadable))
    rsClearObject(rs_element* dst);

extern void __attribute__((overloadable))
    rsClearObject(rs_type* dst);

extern void __attribute__((overloadable))
    rsClearObject(rs_allocation* dst);

extern void __attribute__((overloadable))
    rsClearObject(rs_sampler* dst);

extern void __attribute__((overloadable))
    rsClearObject(rs_script* dst);

/*
 * rsIsObject: Check for an empty handle
 *
 * 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.
 */
extern bool __attribute__((overloadable))
    rsIsObject(rs_element v);

extern bool __attribute__((overloadable))
    rsIsObject(rs_type v);

extern bool __attribute__((overloadable))
    rsIsObject(rs_allocation v);

extern bool __attribute__((overloadable))
    rsIsObject(rs_sampler v);

extern bool __attribute__((overloadable))
    rsIsObject(rs_script v);

/*
 * rsElementGetBytesSize: Return the size of an element
 *
 * Returns the size in bytes that an instantiation of this element will occupy.
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern uint32_t __attribute__((overloadable))
    rsElementGetBytesSize(rs_element e);
#endif

/*
 * rsElementGetDataKind: Return the kind of an element
 *
 * Returns the element's data kind.  This is used to interpret pixel data.
 *
 * See rs_data_kind.
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern rs_data_kind __attribute__((overloadable))
    rsElementGetDataKind(rs_element e);
#endif

/*
 * rsElementGetDataType: Return the data type of an element
 *
 * 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).
 *
 * If the element describes a vector, this function returns the data type of one of its items.
 *
 * If the element describes a structure, RS_TYPE_NONE is returned.
 *
 * See rs_data_type.
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern rs_data_type __attribute__((overloadable))
    rsElementGetDataType(rs_element e);
#endif

/*
 * rsElementGetSubElement: Return a sub element of a complex element
 *
 * For the element 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.
 *
 * Parameters:
 *   e: Element to query
 *   index: Index of the sub-element to return
 *
 * Returns: Sub-element at the given index
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern rs_element __attribute__((overloadable))
    rsElementGetSubElement(rs_element e, uint32_t index);
#endif

/*
 * rsElementGetSubElementArraySize: Return the array size of a sub element of a complex element
 *
 * For complex elements, some sub-elements could be statically
 * sized arrays. This function returns the array size of the
 * sub-element at the index.
 *
 * Parameters:
 *   e: Element to query
 *   index: Index of the sub-element
 *
 * Returns: Array size of the sub-element at the given index
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern uint32_t __attribute__((overloadable))
    rsElementGetSubElementArraySize(rs_element e, uint32_t index);
#endif

/*
 * rsElementGetSubElementCount: Return the number of sub-elements
 *
 * Elements could be simple, such as an int or a float, or a
 * structure with multiple sub-elements, such as a collection of
 * floats, float2, float4.  This function returns zero for simple
 * elements or the number of sub-elements otherwise.
 *
 * Parameters:
 *   e: Element to get data from
 *
 * Returns: Number of sub-elements in this element
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern uint32_t __attribute__((overloadable))
    rsElementGetSubElementCount(rs_element e);
#endif

/*
 * rsElementGetSubElementName: Return the name of a sub-element
 *
 * For complex elements, this function returns the name of the sub-element
 * at the specified index.
 *
 * Parameters:
 *   e: Element to get data from
 *   index: Index of the sub-element
 *   name: Array to store the name into
 *   nameLength: Length of the provided name array
 *
 * Returns: Number of characters actually written, excluding the null terminator
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern uint32_t __attribute__((overloadable))
    rsElementGetSubElementName(rs_element e, uint32_t index, char* name, uint32_t nameLength);
#endif

/*
 * rsElementGetSubElementNameLength: Return the length of the name of a sub-element
 *
 * For complex elements, this function will return the length of
 * sub-element name at index
 *
 * Parameters:
 *   e: Element to get data from
 *   index: Index of the sub-element to return
 *
 * Returns: Length of the sub-element name including the null terminator (size of buffer needed to write the name)
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern uint32_t __attribute__((overloadable))
    rsElementGetSubElementNameLength(rs_element e, uint32_t index);
#endif

/*
 * This function specifies the location of a sub-element within
 * the element
 *
 * Parameters:
 *   e: Element to get data from
 *   index: Index of the sub-element
 *
 * Returns: Offset in bytes of sub-element in this element at given index
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern uint32_t __attribute__((overloadable))
    rsElementGetSubElementOffsetBytes(rs_element e, uint32_t index);
#endif

/*
 * Returns the element's vector size
 *
 * Parameters:
 *   e: Element to get data from
 *
 * Returns: Length of the element vector (for float2, float3, etc.)
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern uint32_t __attribute__((overloadable))
    rsElementGetVectorSize(rs_element e);
#endif

/*
 * rsGetAllocation: Returns the Allocation for a given pointer
 *
 * DEPRECATED.  Do not use.
 *
 * 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.
 */
extern rs_allocation __attribute__((overloadable))
    rsGetAllocation(const void* p);

/*
 *  Get sampler anisotropy
 *
 * Parameters:
 *   s: sampler to query
 *
 * Returns: anisotropy
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern float __attribute__((overloadable))
    rsSamplerGetAnisotropy(rs_sampler s);
#endif

/*
 * Get sampler magnification value
 *
 * Parameters:
 *   s: sampler to query
 *
 * Returns: magnification value
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern rs_sampler_value __attribute__((overloadable))
    rsSamplerGetMagnification(rs_sampler s);
#endif

/*
 * Get sampler minification value
 *
 * Parameters:
 *   s: sampler to query
 *
 * Returns: minification value
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern rs_sampler_value __attribute__((overloadable))
    rsSamplerGetMinification(rs_sampler s);
#endif

/*
 * Get sampler wrap S value
 *
 * Parameters:
 *   s: sampler to query
 *
 * Returns: wrap S value
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern rs_sampler_value __attribute__((overloadable))
    rsSamplerGetWrapS(rs_sampler s);
#endif

/*
 * Get sampler wrap T value
 *
 * Parameters:
 *   s: sampler to query
 *
 * Returns: wrap T value
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern rs_sampler_value __attribute__((overloadable))
    rsSamplerGetWrapT(rs_sampler s);
#endif

/*
 * rsSetObject: For internal use.
 *
 */
extern void __attribute__((overloadable))
    rsSetObject(rs_element* dst, rs_element src);

extern void __attribute__((overloadable))
    rsSetObject(rs_type* dst, rs_type src);

extern void __attribute__((overloadable))
    rsSetObject(rs_allocation* dst, rs_allocation src);

extern void __attribute__((overloadable))
    rsSetObject(rs_sampler* dst, rs_sampler src);

extern void __attribute__((overloadable))
    rsSetObject(rs_script* dst, rs_script src);

#endif // RENDERSCRIPT_RS_OBJECT_INFO_RSH