2 * Copyright (C) 2016 The Android Open Source Project
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 // Don't edit this file! It is auto-generated by frameworks/rs/api/generate.sh.
20 * rs_object_info.rsh: Object Characteristics Functions
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
28 * Allocations are the primary method used to pass data to and from RenderScript kernels.
30 * They are a structured collection of cells that can be used to store bitmaps, textures,
31 * arbitrary data points, etc.
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).
36 * See the android.renderscript.Allocation for details on to create Allocations.
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.
46 * The functions below let you query the characteristics of the type specificiation.
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.
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.
56 * Elements can also have a kind, which is semantic information used to interpret pixel
57 * data. See rs_data_kind.
59 * When creating Allocations of common elements, you can simply use one of the many predefined
60 * Elements like F32_2.
62 * To create complex Elements, use the Element.Builder Java class.
66 * Samplers objects define how Allocations can be read as structure within a kernel.
67 * See android.renderscript.S.
70 #ifndef RENDERSCRIPT_RS_OBJECT_INFO_RSH
71 #define RENDERSCRIPT_RS_OBJECT_INFO_RSH
74 * rsAllocationGetDimFaces: Presence of more than one face
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.
79 * Use rsGetDimHasFaces() to get the dimension of a currently running kernel.
81 * Returns: Returns 1 if more than one face is present, 0 otherwise.
83 extern uint32_t __attribute__((overloadable))
84 rsAllocationGetDimFaces(rs_allocation a);
87 * rsAllocationGetDimLOD: Presence of levels of detail
89 * Query an Allocation for the presence of more than one Level Of Detail. This is useful
92 * Use rsGetDimLod() to get the dimension of a currently running kernel.
94 * Returns: Returns 1 if more than one LOD is present, 0 otherwise.
96 extern uint32_t __attribute__((overloadable))
97 rsAllocationGetDimLOD(rs_allocation a);
100 * rsAllocationGetDimX: Size of the X dimension
102 * Returns the size of the X dimension of the Allocation.
104 * Use rsGetDimX() to get the dimension of a currently running kernel.
106 * Returns: X dimension of the Allocation.
108 extern uint32_t __attribute__((overloadable))
109 rsAllocationGetDimX(rs_allocation a);
112 * rsAllocationGetDimY: Size of the Y dimension
114 * Returns the size of the Y dimension of the Allocation. If the Allocation has less
115 * than two dimensions, returns 0.
117 * Use rsGetDimY() to get the dimension of a currently running kernel.
119 * Returns: Y dimension of the Allocation.
121 extern uint32_t __attribute__((overloadable))
122 rsAllocationGetDimY(rs_allocation a);
125 * rsAllocationGetDimZ: Size of the Z dimension
127 * Returns the size of the Z dimension of the Allocation. If the Allocation has less
128 * than three dimensions, returns 0.
130 * Use rsGetDimZ() to get the dimension of a currently running kernel.
132 * Returns: Z dimension of the Allocation.
134 extern uint32_t __attribute__((overloadable))
135 rsAllocationGetDimZ(rs_allocation a);
138 * rsAllocationGetElement: Get the object that describes the cell of an Allocation
140 * Get the Element object describing the type, kind, and other characteristics of a cell
141 * of an Allocation. See the rsElement* functions below.
144 * a: Allocation to get data from.
146 * Returns: Element describing Allocation layout.
148 extern rs_element __attribute__((overloadable))
149 rsAllocationGetElement(rs_allocation a);
152 * rsClearObject: Release an object
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.
157 * After calling this function, *dst will be set to an empty handle. See rsIsObject().
159 extern void __attribute__((overloadable))
160 rsClearObject(rs_element* dst);
162 extern void __attribute__((overloadable))
163 rsClearObject(rs_type* dst);
165 extern void __attribute__((overloadable))
166 rsClearObject(rs_allocation* dst);
168 extern void __attribute__((overloadable))
169 rsClearObject(rs_sampler* dst);
171 extern void __attribute__((overloadable))
172 rsClearObject(rs_script* dst);
175 * rsIsObject: Check for an empty handle
177 * Returns true if the handle contains a non-null reference.
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.
182 * This function can be used to check the Element returned by rsElementGetSubElement()
183 * or see if rsClearObject() has been called on a handle.
185 extern bool __attribute__((overloadable))
186 rsIsObject(rs_element v);
188 extern bool __attribute__((overloadable))
189 rsIsObject(rs_type v);
191 extern bool __attribute__((overloadable))
192 rsIsObject(rs_allocation v);
194 extern bool __attribute__((overloadable))
195 rsIsObject(rs_sampler v);
197 extern bool __attribute__((overloadable))
198 rsIsObject(rs_script v);
201 * rsElementGetBytesSize: Size of an Element
203 * Returns the size in bytes that an instantiation of this Element will occupy.
205 #if (defined(RS_VERSION) && (RS_VERSION >= 16))
206 extern uint32_t __attribute__((overloadable))
207 rsElementGetBytesSize(rs_element e);
211 * rsElementGetDataKind: Kind of an Element
213 * Returns the Element's data kind. This is used to interpret pixel data.
217 #if (defined(RS_VERSION) && (RS_VERSION >= 16))
218 extern rs_data_kind __attribute__((overloadable))
219 rsElementGetDataKind(rs_element e);
223 * rsElementGetDataType: Data type of an Element
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).
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.
233 * If the Element describes a structure, RS_TYPE_NONE is returned. Use the rsElementGetSub*
234 * functions to explore this complex Element.
236 #if (defined(RS_VERSION) && (RS_VERSION >= 16))
237 extern rs_data_type __attribute__((overloadable))
238 rsElementGetDataType(rs_element e);
242 * rsElementGetSubElement: Sub-element of a complex Element
244 * For Elements that represents a structure, this function returns the sub-element at the
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.
251 * e: Element to query.
252 * index: Index of the sub-element to return.
254 * Returns: Sub-element at the given index.
256 #if (defined(RS_VERSION) && (RS_VERSION >= 16))
257 extern rs_element __attribute__((overloadable))
258 rsElementGetSubElement(rs_element e, uint32_t index);
262 * rsElementGetSubElementArraySize: Array size of a sub-element of a complex Element
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.
269 * e: Element to query.
270 * index: Index of the sub-element.
272 * Returns: Array size of the sub-element.
274 #if (defined(RS_VERSION) && (RS_VERSION >= 16))
275 extern uint32_t __attribute__((overloadable))
276 rsElementGetSubElementArraySize(rs_element e, uint32_t index);
280 * rsElementGetSubElementCount: Number of sub-elements
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.
287 * e: Element to get data from.
289 * Returns: Number of sub-elements.
291 #if (defined(RS_VERSION) && (RS_VERSION >= 16))
292 extern uint32_t __attribute__((overloadable))
293 rsElementGetSubElementCount(rs_element e);
297 * rsElementGetSubElementName: Name of a sub-element
299 * For complex Elements, this function returns the name of the sub-element at the
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.
308 * Returns: Number of characters copied, excluding the null terminator.
310 #if (defined(RS_VERSION) && (RS_VERSION >= 16))
311 extern uint32_t __attribute__((overloadable))
312 rsElementGetSubElementName(rs_element e, uint32_t index, char* name, uint32_t nameLength);
316 * rsElementGetSubElementNameLength: Length of the name of a sub-element
318 * For complex Elements, this function returns the length of the name of the sub-element
319 * at the specified index.
322 * e: Element to get data from.
323 * index: Index of the sub-element.
325 * Returns: Length of the sub-element name including the null terminator.
327 #if (defined(RS_VERSION) && (RS_VERSION >= 16))
328 extern uint32_t __attribute__((overloadable))
329 rsElementGetSubElementNameLength(rs_element e, uint32_t index);
333 * rsElementGetSubElementOffsetBytes: Offset of the instantiated sub-element
335 * This function returns the relative position of the instantiation of the specified
336 * sub-element within the instantiation of the Element.
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.
342 * e: Element to get data from.
343 * index: Index of the sub-element.
345 * Returns: Offset in bytes.
347 #if (defined(RS_VERSION) && (RS_VERSION >= 16))
348 extern uint32_t __attribute__((overloadable))
349 rsElementGetSubElementOffsetBytes(rs_element e, uint32_t index);
353 * rsElementGetVectorSize: Vector size of the Element
355 * Returns the Element's vector size. If the Element does not represent a vector,
359 * e: Element to get data from.
361 * Returns: Length of the element vector.
363 #if (defined(RS_VERSION) && (RS_VERSION >= 16))
364 extern uint32_t __attribute__((overloadable))
365 rsElementGetVectorSize(rs_element e);
369 * rsGetAllocation: Return the Allocation for a given pointer
371 * DEPRECATED. Do not use.
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.
376 extern 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.")
381 rsGetAllocation(const void* p);
384 * rsSamplerGetAnisotropy: Anisotropy of the Sampler
386 * Get the Sampler's anisotropy.
388 * See android.renderscript.S.
390 #if (defined(RS_VERSION) && (RS_VERSION >= 16))
391 extern float __attribute__((overloadable))
392 rsSamplerGetAnisotropy(rs_sampler s);
396 * rsSamplerGetMagnification: Sampler magnification value
398 * Get the Sampler's magnification value.
400 * See android.renderscript.S.
402 #if (defined(RS_VERSION) && (RS_VERSION >= 16))
403 extern rs_sampler_value __attribute__((overloadable))
404 rsSamplerGetMagnification(rs_sampler s);
408 * rsSamplerGetMinification: Sampler minification value
410 * Get the Sampler's minification value.
412 * See android.renderscript.S.
414 #if (defined(RS_VERSION) && (RS_VERSION >= 16))
415 extern rs_sampler_value __attribute__((overloadable))
416 rsSamplerGetMinification(rs_sampler s);
420 * rsSamplerGetWrapS: Sampler wrap S value
422 * Get the Sampler's wrap S value.
424 * See android.renderscript.S.
426 #if (defined(RS_VERSION) && (RS_VERSION >= 16))
427 extern rs_sampler_value __attribute__((overloadable))
428 rsSamplerGetWrapS(rs_sampler s);
432 * rsSamplerGetWrapT: Sampler wrap T value
434 * Get the sampler's wrap T value.
436 * See android.renderscript.S.
438 #if (defined(RS_VERSION) && (RS_VERSION >= 16))
439 extern rs_sampler_value __attribute__((overloadable))
440 rsSamplerGetWrapT(rs_sampler s);
444 * rsSetObject: For internal use.
447 extern void __attribute__((overloadable))
448 rsSetObject(rs_element* dst, rs_element src);
450 extern void __attribute__((overloadable))
451 rsSetObject(rs_type* dst, rs_type src);
453 extern void __attribute__((overloadable))
454 rsSetObject(rs_allocation* dst, rs_allocation src);
456 extern void __attribute__((overloadable))
457 rsSetObject(rs_sampler* dst, rs_sampler src);
459 extern void __attribute__((overloadable))
460 rsSetObject(rs_script* dst, rs_script src);
462 #endif // RENDERSCRIPT_RS_OBJECT_INFO_RSH