rs_allocation.rsh revision 8d0f59ef07388a32ed694efe8aa63c24a67cfd7b 
1/*
2 * Copyright (C) 2011 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/*! \mainpage notitle
18 *
19 * Renderscript is a high-performance runtime that provides graphics rendering and
20 * compute operations at the native level. Renderscript code is compiled on devices
21 * at runtime to allow platform-independence as well.
22 * This reference documentation describes the Renderscript runtime APIs, which you
23 * can utilize to write Renderscript code in C99. The Renderscript header
24 * files are automatically included for you, except for the rs_graphics.rsh header. If
25 * you are doing graphics rendering, include the graphics header file like this:
26 *
27 * <code>#include "rs_graphics.rsh"</code>
28 *
29 * To use Renderscript, you need to utilize the Renderscript runtime APIs documented here
30 * as well as the Android framework APIs for Renderscript.
31 * For documentation on the Android framework APIs, see the <a href=
32 * "http://developer.android.com/reference/android/renderscript/package-summary.html">
33 * android.renderscript</a> package reference.
34 * For more information on how to develop with Renderscript and how the runtime and
35 * Android framework APIs interact, see the <a href=
36 * "http://developer.android.com/guide/topics/renderscript/index.html">Renderscript
37 * developer guide</a> and the <a href=
38 * "http://developer.android.com/resources/samples/RenderScript/index.html">
39 * Renderscript samples</a>.
40 */
41
42/** @file rs_allocation.rsh
43 *  \brief Allocation routines
44 *
45 *
46 */
47
48#ifndef __RS_ALLOCATION_RSH__
49#define __RS_ALLOCATION_RSH__
50
51/**
52 * Returns the Allocation for a given pointer.  The pointer should point within
53 * a valid allocation.  The results are undefined if the pointer is not from a
54 * valid allocation.
55 */
56extern rs_allocation __attribute__((overloadable))
57    rsGetAllocation(const void *);
58
59/**
60 * Query the dimension of an allocation.
61 *
62 * @return uint32_t The X dimension of the allocation.
63 */
64extern uint32_t __attribute__((overloadable))
65    rsAllocationGetDimX(rs_allocation);
66
67/**
68 * Query the dimension of an allocation.
69 *
70 * @return uint32_t The Y dimension of the allocation.
71 */
72extern uint32_t __attribute__((overloadable))
73    rsAllocationGetDimY(rs_allocation);
74
75/**
76 * Query the dimension of an allocation.
77 *
78 * @return uint32_t The Z dimension of the allocation.
79 */
80extern uint32_t __attribute__((overloadable))
81    rsAllocationGetDimZ(rs_allocation);
82
83/**
84 * Query an allocation for the presence of more than one LOD.
85 *
86 * @return uint32_t Returns 1 if more than one LOD is present, 0 otherwise.
87 */
88extern uint32_t __attribute__((overloadable))
89    rsAllocationGetDimLOD(rs_allocation);
90
91/**
92 * Query an allocation for the presence of more than one face.
93 *
94 * @return uint32_t Returns 1 if more than one face is present, 0 otherwise.
95 */
96extern uint32_t __attribute__((overloadable))
97    rsAllocationGetDimFaces(rs_allocation);
98
99#if (defined(RS_VERSION) && (RS_VERSION >= 14))
100
101/**
102 * Copy part of an allocation from another allocation.
103 *
104 * @param dstAlloc Allocation to copy data into.
105 * @param dstOff The offset of the first element to be copied in
106 *               the destination allocation.
107 * @param dstMip Mip level in the destination allocation.
108 * @param count The number of elements to be copied.
109 * @param srcAlloc The source data allocation.
110 * @param srcOff The offset of the first element in data to be
111 *               copied in the source allocation.
112 * @param srcMip Mip level in the source allocation.
113 */
114extern void __attribute__((overloadable))
115    rsAllocationCopy1DRange(rs_allocation dstAlloc,
116                            uint32_t dstOff, uint32_t dstMip,
117                            uint32_t count,
118                            rs_allocation srcAlloc,
119                            uint32_t srcOff, uint32_t srcMip);
120
121/**
122 * Copy a rectangular region into the allocation from another
123 * allocation.
124 *
125 * @param dstAlloc allocation to copy data into.
126 * @param dstXoff X offset of the region to update in the
127 *                destination allocation.
128 * @param dstYoff Y offset of the region to update in the
129 *                destination allocation.
130 * @param dstMip Mip level in the destination allocation.
131 * @param dstFace Cubemap face of the destination allocation,
132 *                ignored for allocations that aren't cubemaps.
133 * @param width Width of the incoming region to update.
134 * @param height Height of the incoming region to update.
135 * @param srcAlloc The source data allocation.
136 * @param srcXoff X offset in data of the source allocation.
137 * @param srcYoff Y offset in data of the source allocation.
138 * @param srcMip Mip level in the source allocation.
139 * @param srcFace Cubemap face of the source allocation,
140 *                ignored for allocations that aren't cubemaps.
141 */
142extern void __attribute__((overloadable))
143    rsAllocationCopy2DRange(rs_allocation dstAlloc,
144                            uint32_t dstXoff, uint32_t dstYoff,
145                            uint32_t dstMip,
146                            rs_allocation_cubemap_face dstFace,
147                            uint32_t width, uint32_t height,
148                            rs_allocation srcAlloc,
149                            uint32_t srcXoff, uint32_t srcYoff,
150                            uint32_t srcMip,
151                            rs_allocation_cubemap_face srcFace);
152
153#endif //defined(RS_VERSION) && (RS_VERSION >= 14)
154
155/**
156 * Extract a single element from an allocation.
157 */
158extern const void * __attribute__((overloadable))
159    rsGetElementAt(rs_allocation, uint32_t x);
160/**
161 * \overload
162 */
163extern const void * __attribute__((overloadable))
164    rsGetElementAt(rs_allocation, uint32_t x, uint32_t y);
165/**
166 * \overload
167 */
168extern const void * __attribute__((overloadable))
169    rsGetElementAt(rs_allocation, uint32_t x, uint32_t y, uint32_t z);
170
171/**
172 * @param a allocation to get data from
173 * @return element describing allocation layout
174 */
175extern rs_element __attribute__((overloadable))
176    rsAllocationGetElement(rs_allocation a);
177
178/**
179 * @param m mesh to get data from
180 * @return number of allocations in the mesh that contain vertex
181 *         data
182 */
183extern uint32_t __attribute__((overloadable))
184    rsMeshGetVertexAllocationCount(rs_mesh m);
185
186/**
187 * @param m mesh to get data from
188 * @return number of primitive groups in the mesh. This would
189 *         include simple primitives as well as allocations
190 *         containing index data
191 */
192extern uint32_t __attribute__((overloadable))
193    rsMeshGetPrimitiveCount(rs_mesh m);
194
195/**
196 * @param m mesh to get data from
197 * @param index index of the vertex allocation
198 * @return allocation containing vertex data
199 */
200extern rs_allocation __attribute__((overloadable))
201    rsMeshGetVertexAllocation(rs_mesh m, uint32_t index);
202
203/**
204 * @param m mesh to get data from
205 * @param index index of the index allocation
206 * @return allocation containing index data
207 */
208extern rs_allocation __attribute__((overloadable))
209    rsMeshGetIndexAllocation(rs_mesh m, uint32_t index);
210
211/**
212 * @param m mesh to get data from
213 * @param index index of the primitive
214 * @return primitive describing how the mesh is rendered
215 */
216extern rs_primitive __attribute__((overloadable))
217    rsMeshGetPrimitive(rs_mesh m, uint32_t index);
218
219/**
220 * @param e element to get data from
221 * @return number of sub-elements in this element
222 */
223extern uint32_t __attribute__((overloadable))
224    rsElementGetSubElementCount(rs_element e);
225
226/**
227 * @param e element to get data from
228 * @param index index of the sub-element to return
229 * @return sub-element in this element at given index
230 */
231extern rs_element __attribute__((overloadable))
232    rsElementGetSubElement(rs_element, uint32_t index);
233
234/**
235 * @param e element to get data from
236 * @param index index of the sub-element to return
237 * @return length of the sub-element name
238 */
239extern uint32_t __attribute__((overloadable))
240    rsElementGetSubElementNameLength(rs_element e, uint32_t index);
241
242/**
243 * @param e element to get data from
244 * @param index index of the sub-element
245 * @param name array to store the name into
246 * @param nameLength length of the provided name array
247 * @return number of characters written
248 */
249extern uint32_t __attribute__((overloadable))
250    rsElementGetSubElementName(rs_element e, uint32_t index, char *name, uint32_t nameLength);
251
252/**
253 * @param e element to get data from
254 * @param index index of the sub-element
255 * @return array size of sub-element in this element at given
256 *         index
257 */
258extern uint32_t __attribute__((overloadable))
259    rsElementGetSubElementArraySize(rs_element e, uint32_t index);
260
261/**
262 * @param e element to get data from
263 * @param index index of the sub-element
264 * @return offset in bytes of sub-element in this element at
265 *         given index
266 */
267extern uint32_t __attribute__((overloadable))
268    rsElementGetSubElementOffsetBytes(rs_element e, uint32_t index);
269
270/**
271 * @param e element to get data from
272 * @return total size of the element in bytes
273 */
274extern uint32_t __attribute__((overloadable))
275    rsElementGetSizeBytes(rs_element e);
276
277/**
278 * @param e element to get data from
279 * @return element's data type
280 */
281extern rs_data_type __attribute__((overloadable))
282    rsElementGetDataType(rs_element e);
283
284/**
285 * @param e element to get data from
286 * @return element's data size
287 */
288extern rs_data_kind __attribute__((overloadable))
289    rsElementGetDataKind(rs_element e);
290
291#endif
292
293