1/*
2 * Copyright (C) 2016 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// Don't edit this file!  It is auto-generated by frameworks/rs/api/generate.sh.
18
19/*
20 * rs_object_info.rsh: Object Characteristics Functions
21 *
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
24 * script.
25 *
26 * Allocations:
27 *
28 * Allocations are the primary method used to pass data to and from RenderScript kernels.
29 *
30 * They are a structured collection of cells that can be used to store bitmaps, textures,
31 * arbitrary data points, etc.
32 *
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).
35 *
36 * See the android.renderscript.Allocation for details on to create Allocations.
37 *
38 * Elements:
39 *
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.
45 *
46 * The functions below let you query the characteristics of the type specificiation.
47 *
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.
51 *
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.
55 *
56 * Elements can also have a kind, which is semantic information used to interpret pixel
57 * data.  See rs_data_kind.
58 *
59 * When creating Allocations of common elements, you can simply use one of the many predefined
60 * Elements like F32_2.
61 *
62 * To create complex Elements, use the Element.Builder Java class.
63 *
64 * Samplers:
65 *
66 * Samplers objects define how Allocations can be read as structure within a kernel.
67 * See android.renderscript.S.
68 */
69
70#ifndef RENDERSCRIPT_RS_OBJECT_INFO_RSH
71#define RENDERSCRIPT_RS_OBJECT_INFO_RSH
72
73/*
74 * rsAllocationGetDimFaces: Presence of more than one face
75 *
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.
78 *
79 * Use rsGetDimHasFaces() to get the dimension of a currently running kernel.
80 *
81 * Returns: Returns 1 if more than one face is present, 0 otherwise.
82 */
83extern uint32_t __attribute__((overloadable))
84    rsAllocationGetDimFaces(rs_allocation a);
85
86/*
87 * rsAllocationGetDimLOD: Presence of levels of detail
88 *
89 * Query an Allocation for the presence of more than one Level Of Detail.  This is useful
90 * for mipmaps.
91 *
92 * Use rsGetDimLod() to get the dimension of a currently running kernel.
93 *
94 * Returns: Returns 1 if more than one LOD is present, 0 otherwise.
95 */
96extern uint32_t __attribute__((overloadable))
97    rsAllocationGetDimLOD(rs_allocation a);
98
99/*
100 * rsAllocationGetDimX: Size of the X dimension
101 *
102 * Returns the size of the X dimension of the Allocation.
103 *
104 * Use rsGetDimX() to get the dimension of a currently running kernel.
105 *
106 * Returns: X dimension of the Allocation.
107 */
108extern uint32_t __attribute__((overloadable))
109    rsAllocationGetDimX(rs_allocation a);
110
111/*
112 * rsAllocationGetDimY: Size of the Y dimension
113 *
114 * Returns the size of the Y dimension of the Allocation.  If the Allocation has less
115 * than two dimensions, returns 0.
116 *
117 * Use rsGetDimY() to get the dimension of a currently running kernel.
118 *
119 * Returns: Y dimension of the Allocation.
120 */
121extern uint32_t __attribute__((overloadable))
122    rsAllocationGetDimY(rs_allocation a);
123
124/*
125 * rsAllocationGetDimZ: Size of the Z dimension
126 *
127 * Returns the size of the Z dimension of the Allocation.  If the Allocation has less
128 * than three dimensions, returns 0.
129 *
130 * Use rsGetDimZ() to get the dimension of a currently running kernel.
131 *
132 * Returns: Z dimension of the Allocation.
133 */
134extern uint32_t __attribute__((overloadable))
135    rsAllocationGetDimZ(rs_allocation a);
136
137/*
138 * rsAllocationGetElement: Get the object that describes the cell of an Allocation
139 *
140 * Get the Element object describing the type, kind, and other characteristics of a cell
141 * of an Allocation.  See the rsElement* functions below.
142 *
143 * Parameters:
144 *   a: Allocation to get data from.
145 *
146 * Returns: Element describing Allocation layout.
147 */
148extern rs_element __attribute__((overloadable))
149    rsAllocationGetElement(rs_allocation a);
150
151/*
152 * rsClearObject: Release an object
153 *
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.
156 *
157 * After calling this function, *dst will be set to an empty handle.  See rsIsObject().
158 */
159extern void __attribute__((overloadable))
160    rsClearObject(rs_element* dst);
161
162extern void __attribute__((overloadable))
163    rsClearObject(rs_type* dst);
164
165extern void __attribute__((overloadable))
166    rsClearObject(rs_allocation* dst);
167
168extern void __attribute__((overloadable))
169    rsClearObject(rs_sampler* dst);
170
171extern void __attribute__((overloadable))
172    rsClearObject(rs_script* dst);
173
174/*
175 * rsIsObject: Check for an empty handle
176 *
177 * Returns true if the handle contains a non-null reference.
178 *
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.
181 *
182 * This function can be used to check the Element returned by rsElementGetSubElement()
183 * or see if rsClearObject() has been called on a handle.
184 */
185extern bool __attribute__((overloadable))
186    rsIsObject(rs_element v);
187
188extern bool __attribute__((overloadable))
189    rsIsObject(rs_type v);
190
191extern bool __attribute__((overloadable))
192    rsIsObject(rs_allocation v);
193
194extern bool __attribute__((overloadable))
195    rsIsObject(rs_sampler v);
196
197extern bool __attribute__((overloadable))
198    rsIsObject(rs_script v);
199
200/*
201 * rsElementGetBytesSize: Size of an Element
202 *
203 * Returns the size in bytes that an instantiation of this Element will occupy.
204 */
205#if (defined(RS_VERSION) && (RS_VERSION >= 16))
206extern uint32_t __attribute__((overloadable))
207    rsElementGetBytesSize(rs_element e);
208#endif
209
210/*
211 * rsElementGetDataKind: Kind of an Element
212 *
213 * Returns the Element's data kind.  This is used to interpret pixel data.
214 *
215 * See rs_data_kind.
216 */
217#if (defined(RS_VERSION) && (RS_VERSION >= 16))
218extern rs_data_kind __attribute__((overloadable))
219    rsElementGetDataKind(rs_element e);
220#endif
221
222/*
223 * rsElementGetDataType: Data type of an Element
224 *
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).
228 * See rs_data_type.
229 *
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.
232 *
233 * If the Element describes a structure, RS_TYPE_NONE is returned.  Use the rsElementGetSub*
234 * functions to explore this complex Element.
235 */
236#if (defined(RS_VERSION) && (RS_VERSION >= 16))
237extern rs_data_type __attribute__((overloadable))
238    rsElementGetDataType(rs_element e);
239#endif
240
241/*
242 * rsElementGetSubElement: Sub-element of a complex Element
243 *
244 * For Elements that represents a structure, this function returns the sub-element at the
245 * specified index.
246 *
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.
249 *
250 * Parameters:
251 *   e: Element to query.
252 *   index: Index of the sub-element to return.
253 *
254 * Returns: Sub-element at the given index.
255 */
256#if (defined(RS_VERSION) && (RS_VERSION >= 16))
257extern rs_element __attribute__((overloadable))
258    rsElementGetSubElement(rs_element e, uint32_t index);
259#endif
260
261/*
262 * rsElementGetSubElementArraySize: Array size of a sub-element of a complex Element
263 *
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.
267 *
268 * Parameters:
269 *   e: Element to query.
270 *   index: Index of the sub-element.
271 *
272 * Returns: Array size of the sub-element.
273 */
274#if (defined(RS_VERSION) && (RS_VERSION >= 16))
275extern uint32_t __attribute__((overloadable))
276    rsElementGetSubElementArraySize(rs_element e, uint32_t index);
277#endif
278
279/*
280 * rsElementGetSubElementCount: Number of sub-elements
281 *
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.
285 *
286 * Parameters:
287 *   e: Element to get data from.
288 *
289 * Returns: Number of sub-elements.
290 */
291#if (defined(RS_VERSION) && (RS_VERSION >= 16))
292extern uint32_t __attribute__((overloadable))
293    rsElementGetSubElementCount(rs_element e);
294#endif
295
296/*
297 * rsElementGetSubElementName: Name of a sub-element
298 *
299 * For complex Elements, this function returns the name of the sub-element at the
300 * specified index.
301 *
302 * Parameters:
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.
307 *
308 * Returns: Number of characters copied, excluding the null terminator.
309 */
310#if (defined(RS_VERSION) && (RS_VERSION >= 16))
311extern uint32_t __attribute__((overloadable))
312    rsElementGetSubElementName(rs_element e, uint32_t index, char* name, uint32_t nameLength);
313#endif
314
315/*
316 * rsElementGetSubElementNameLength: Length of the name of a sub-element
317 *
318 * For complex Elements, this function returns the length of the name of the sub-element
319 * at the specified index.
320 *
321 * Parameters:
322 *   e: Element to get data from.
323 *   index: Index of the sub-element.
324 *
325 * Returns: Length of the sub-element name including the null terminator.
326 */
327#if (defined(RS_VERSION) && (RS_VERSION >= 16))
328extern uint32_t __attribute__((overloadable))
329    rsElementGetSubElementNameLength(rs_element e, uint32_t index);
330#endif
331
332/*
333 * rsElementGetSubElementOffsetBytes: Offset of the instantiated sub-element
334 *
335 * This function returns the relative position of the instantiation of the specified
336 * sub-element within the instantiation of the Element.
337 *
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.
340 *
341 * Parameters:
342 *   e: Element to get data from.
343 *   index: Index of the sub-element.
344 *
345 * Returns: Offset in bytes.
346 */
347#if (defined(RS_VERSION) && (RS_VERSION >= 16))
348extern uint32_t __attribute__((overloadable))
349    rsElementGetSubElementOffsetBytes(rs_element e, uint32_t index);
350#endif
351
352/*
353 * rsElementGetVectorSize: Vector size of the Element
354 *
355 * Returns the Element's vector size.  If the Element does not represent a vector,
356 * 1 is returned.
357 *
358 * Parameters:
359 *   e: Element to get data from.
360 *
361 * Returns: Length of the element vector.
362 */
363#if (defined(RS_VERSION) && (RS_VERSION >= 16))
364extern uint32_t __attribute__((overloadable))
365    rsElementGetVectorSize(rs_element e);
366#endif
367
368/*
369 * rsGetAllocation: Return the Allocation for a given pointer
370 *
371 * DEPRECATED.  Do not use.
372 *
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.
375 */
376extern 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.")
379#endif
380))
381    rsGetAllocation(const void* p);
382
383/*
384 * rsSamplerGetAnisotropy: Anisotropy of the Sampler
385 *
386 * Get the Sampler's anisotropy.
387 *
388 * See android.renderscript.S.
389 */
390#if (defined(RS_VERSION) && (RS_VERSION >= 16))
391extern float __attribute__((overloadable))
392    rsSamplerGetAnisotropy(rs_sampler s);
393#endif
394
395/*
396 * rsSamplerGetMagnification: Sampler magnification value
397 *
398 * Get the Sampler's magnification value.
399 *
400 * See android.renderscript.S.
401 */
402#if (defined(RS_VERSION) && (RS_VERSION >= 16))
403extern rs_sampler_value __attribute__((overloadable))
404    rsSamplerGetMagnification(rs_sampler s);
405#endif
406
407/*
408 * rsSamplerGetMinification: Sampler minification value
409 *
410 * Get the Sampler's minification value.
411 *
412 * See android.renderscript.S.
413 */
414#if (defined(RS_VERSION) && (RS_VERSION >= 16))
415extern rs_sampler_value __attribute__((overloadable))
416    rsSamplerGetMinification(rs_sampler s);
417#endif
418
419/*
420 * rsSamplerGetWrapS: Sampler wrap S value
421 *
422 * Get the Sampler's wrap S value.
423 *
424 * See android.renderscript.S.
425 */
426#if (defined(RS_VERSION) && (RS_VERSION >= 16))
427extern rs_sampler_value __attribute__((overloadable))
428    rsSamplerGetWrapS(rs_sampler s);
429#endif
430
431/*
432 * rsSamplerGetWrapT: Sampler wrap T value
433 *
434 * Get the sampler's wrap T value.
435 *
436 * See android.renderscript.S.
437 */
438#if (defined(RS_VERSION) && (RS_VERSION >= 16))
439extern rs_sampler_value __attribute__((overloadable))
440    rsSamplerGetWrapT(rs_sampler s);
441#endif
442
443/*
444 * rsSetObject: For internal use.
445 *
446 */
447extern void __attribute__((overloadable))
448    rsSetObject(rs_element* dst, rs_element src);
449
450extern void __attribute__((overloadable))
451    rsSetObject(rs_type* dst, rs_type src);
452
453extern void __attribute__((overloadable))
454    rsSetObject(rs_allocation* dst, rs_allocation src);
455
456extern void __attribute__((overloadable))
457    rsSetObject(rs_sampler* dst, rs_sampler src);
458
459extern void __attribute__((overloadable))
460    rsSetObject(rs_script* dst, rs_script src);
461
462#endif // RENDERSCRIPT_RS_OBJECT_INFO_RSH
463