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