| blob | bcc5db929dd55e726ab4fa02609c0ef8355d341e |
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 */
17 // Don't edit this file! It is auto-generated by frameworks/rs/api/generate.sh.
19 /*
20 * rs_for_each.rsh: Kernel Invocation Functions and Types
21 *
22 * The rsForEach() function can be used to invoke the root kernel of a script.
23 *
24 * The other functions are used to get the characteristics of the invocation of
25 * an executing kernel, like dimensions and current indices. These functions take
26 * a rs_kernel_context as argument.
27 */
29 #ifndef RENDERSCRIPT_RS_FOR_EACH_RSH
30 #define RENDERSCRIPT_RS_FOR_EACH_RSH
32 /*
33 * rs_for_each_strategy_t: Suggested cell processing order
34 *
35 * This type is used to suggest how the invoked kernel should iterate over the cells of the
36 * allocations. This is a hint only. Implementations may not follow the suggestion.
37 *
38 * This specification can help the caching behavior of the running kernel, e.g. the cache
39 * locality when the processing is distributed over multiple cores.
40 */
41 typedef enum rs_for_each_strategy {
42 RS_FOR_EACH_STRATEGY_SERIAL = 0, // Prefer contiguous memory regions.
43 RS_FOR_EACH_STRATEGY_DONT_CARE = 1, // No prefrences.
44 RS_FOR_EACH_STRATEGY_DST_LINEAR = 2, // Prefer DST.
45 RS_FOR_EACH_STRATEGY_TILE_SMALL = 3, // Prefer processing small rectangular regions.
46 RS_FOR_EACH_STRATEGY_TILE_MEDIUM = 4, // Prefer processing medium rectangular regions.
47 RS_FOR_EACH_STRATEGY_TILE_LARGE = 5 // Prefer processing large rectangular regions.
48 } rs_for_each_strategy_t;
50 /*
51 * rs_kernel_context: Handle to a kernel invocation context
52 *
53 * The kernel context contains common characteristics of the allocations being iterated
54 * over, like dimensions. It also contains rarely used indices of the currently processed
55 * cell, like the Array0 index or the current level of detail.
56 *
57 * You can access the kernel context by adding a special parameter named "context" of type
58 * rs_kernel_context to your kernel function. See rsGetDimX() and rsGetArray0() for examples.
59 */
60 #if (defined(RS_VERSION) && (RS_VERSION >= 23))
61 typedef const struct rs_kernel_context_t * rs_kernel_context;
62 #endif
64 /*
65 * rs_script_call_t: Cell iteration information
66 *
67 * This structure is used to provide iteration information to a rsForEach call.
68 * It is currently used to restrict processing to a subset of cells. In future
69 * versions, it will also be used to provide hint on how to best iterate over
70 * the cells.
71 *
72 * The Start fields are inclusive and the End fields are exclusive. E.g. to iterate
73 * over cells 4, 5, 6, and 7 in the X dimension, set xStart to 4 and xEnd to 8.
74 */
75 typedef struct rs_script_call {
76 rs_for_each_strategy_t strategy; // Currently ignored. In the future, will be suggested cell iteration strategy.
77 uint32_t xStart; // Starting index in the X dimension.
78 uint32_t xEnd; // Ending index (exclusive) in the X dimension.
79 uint32_t yStart; // Starting index in the Y dimension.
80 uint32_t yEnd; // Ending index (exclusive) in the Y dimension.
81 uint32_t zStart; // Starting index in the Z dimension.
82 uint32_t zEnd; // Ending index (exclusive) in the Z dimension.
83 uint32_t arrayStart; // Starting index in the Array0 dimension.
84 uint32_t arrayEnd; // Ending index (exclusive) in the Array0 dimension.
85 uint32_t array1Start; // Starting index in the Array1 dimension.
86 uint32_t array1End; // Ending index (exclusive) in the Array1 dimension.
87 uint32_t array2Start; // Starting index in the Array2 dimension.
88 uint32_t array2End; // Ending index (exclusive) in the Array2 dimension.
89 uint32_t array3Start; // Starting index in the Array3 dimension.
90 uint32_t array3End; // Ending index (exclusive) in the Array3 dimension.
91 } rs_script_call_t;
93 /*
94 * rs_kernel: Handle to a kernel function
95 *
96 * An opaque type for a function that is defined with the kernel attribute. A value
97 * of this type can be used in a rsForEach call to launch a kernel.
98 */
99 #if (defined(RS_VERSION) && (RS_VERSION >= 24))
100 typedef void* rs_kernel;
101 #endif
103 /*
104 * rsForEach: Launches a kernel
105 *
106 * Runs the kernel over zero or more input allocations. They are passed after the
107 * rs_kernel argument. If the specified kernel returns a value, an output allocation
108 * must be specified as the last argument. All input allocations,
109 * and the output allocation if it exists, must have the same dimensions.
110 *
111 * This is a synchronous function. A call to this function only returns after all
112 * the work has completed for all cells of the input allocations. If the kernel
113 * function returns any value, the call waits until all results have been written
114 * to the output allocation.
115 *
116 * Up to API level 23, the kernel is implicitly specified as the kernel named
117 * "root" in the specified script, and only a single input allocation can be used.
118 * Starting in API level 24, an arbitrary kernel function can be used,
119 * as specified by the kernel argument. The script argument is removed.
120 * The kernel must be defined in the current script. In addition, more than one
121 * input can be used.
122 *
123 * E.g.
124 * float __attribute__((kernel)) square(float a) {
125 * return a * a;
126 * }
127 *
128 * void compute(rs_allocation ain, rs_allocation aout) {
129 * rsForEach(square, ain, aout);
130 * }
131 *
132 *
133 * Parameters:
134 * script: Script to call.
135 * input: Allocation to source data from.
136 * output: Allocation to write date into.
137 * usrData: User defined data to pass to the script. May be NULL.
138 * sc: Extra control information used to select a sub-region of the allocation to be processed or suggest a walking strategy. May be NULL.
139 * usrDataLen: Size of the userData structure. This will be used to perform a shallow copy of the data if necessary.
140 * kernel: Function designator to a function that is defined with the kernel attribute.
141 * ...: Input and output allocations
142 */
143 #if !defined(RS_VERSION) || (RS_VERSION <= 13)
144 extern void __attribute__((overloadable))
145 rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData,
146 const rs_script_call_t* sc);
147 #endif
149 #if !defined(RS_VERSION) || (RS_VERSION <= 13)
150 extern void __attribute__((overloadable))
151 rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData);
152 #endif
154 #if (defined(RS_VERSION) && (RS_VERSION >= 14) && (RS_VERSION <= 20))
155 extern void __attribute__((overloadable))
156 rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData,
157 size_t usrDataLen, const rs_script_call_t* sc);
158 #endif
160 #if (defined(RS_VERSION) && (RS_VERSION >= 14) && (RS_VERSION <= 20))
161 extern void __attribute__((overloadable))
162 rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData,
163 size_t usrDataLen);
164 #endif
166 #if (defined(RS_VERSION) && (RS_VERSION >= 14) && (RS_VERSION <= 23))
167 extern void __attribute__((overloadable))
168 rsForEach(rs_script script, rs_allocation input, rs_allocation output);
169 #endif
171 #if (defined(RS_VERSION) && (RS_VERSION >= 24))
172 extern void
173 rsForEach(rs_kernel kernel, ...);
174 #endif
176 /*
177 * rsForEachWithOptions: Launches a kernel with options
178 *
179 * Launches kernel in a way similar to rsForEach. However, instead of processing
180 * all cells in the input, this function only processes cells in the subspace of
181 * the index space specified in options. With the index space explicitly specified
182 * by options, no input or output allocation is required for a kernel launch using
183 * this API. If allocations are passed in, they must match the number of arguments
184 * and return value expected by the kernel function. The output allocation is
185 * present if and only if the kernel has a non-void return value.
186 *
187 * E.g.,
188 * rs_script_call_t opts = {0};
189 * opts.xStart = 0;
190 * opts.xEnd = dimX;
191 * opts.yStart = 0;
192 * opts.yEnd = dimY / 2;
193 * rsForEachWithOptions(foo, &opts, out, out);
194 *
195 *
196 * Parameters:
197 * kernel: Function designator to a function that is defined with the kernel attribute.
198 * options: Launch options
199 * ...: Input and output allocations
200 */
201 #if (defined(RS_VERSION) && (RS_VERSION >= 24))
202 extern void
203 rsForEachWithOptions(rs_kernel kernel, rs_script_call_t* options, ...);
204 #endif
206 /*
207 * rsGetArray0: Index in the Array0 dimension for the specified kernel context
208 *
209 * Returns the index in the Array0 dimension of the cell being processed, as specified
210 * by the supplied kernel context.
211 *
212 * The kernel context contains common characteristics of the allocations being iterated
213 * over and rarely used indices, like the Array0 index.
214 *
215 * You can access the kernel context by adding a special parameter named "context" of
216 * type rs_kernel_context to your kernel function. E.g.
217 * short RS_KERNEL myKernel(short value, uint32_t x, rs_kernel_context context) {
218 * // The current index in the common x, y, z dimensions are accessed by
219 * // adding these variables as arguments. For the more rarely used indices
220 * // to the other dimensions, extract them from the kernel context:
221 * uint32_t index_a0 = rsGetArray0(context);
222 * //...
223 * }
224 *
225 * This function returns 0 if the Array0 dimension is not present.
226 */
227 #if (defined(RS_VERSION) && (RS_VERSION >= 23))
228 extern uint32_t __attribute__((overloadable))
229 rsGetArray0(rs_kernel_context context);
230 #endif
232 /*
233 * rsGetArray1: Index in the Array1 dimension for the specified kernel context
234 *
235 * Returns the index in the Array1 dimension of the cell being processed, as specified
236 * by the supplied kernel context. See rsGetArray0() for an explanation of the context.
237 *
238 * Returns 0 if the Array1 dimension is not present.
239 */
240 #if (defined(RS_VERSION) && (RS_VERSION >= 23))
241 extern uint32_t __attribute__((overloadable))
242 rsGetArray1(rs_kernel_context context);
243 #endif
245 /*
246 * rsGetArray2: Index in the Array2 dimension for the specified kernel context
247 *
248 * Returns the index in the Array2 dimension of the cell being processed,
249 * as specified by the supplied kernel context. See rsGetArray0() for an explanation
250 * of the context.
251 *
252 * Returns 0 if the Array2 dimension is not present.
253 */
254 #if (defined(RS_VERSION) && (RS_VERSION >= 23))
255 extern uint32_t __attribute__((overloadable))
256 rsGetArray2(rs_kernel_context context);
257 #endif
259 /*
260 * rsGetArray3: Index in the Array3 dimension for the specified kernel context
261 *
262 * Returns the index in the Array3 dimension of the cell being processed, as specified
263 * by the supplied kernel context. See rsGetArray0() for an explanation of the context.
264 *
265 * Returns 0 if the Array3 dimension is not present.
266 */
267 #if (defined(RS_VERSION) && (RS_VERSION >= 23))
268 extern uint32_t __attribute__((overloadable))
269 rsGetArray3(rs_kernel_context context);
270 #endif
272 /*
273 * rsGetDimArray0: Size of the Array0 dimension for the specified kernel context
274 *
275 * Returns the size of the Array0 dimension for the specified kernel context.
276 * See rsGetDimX() for an explanation of the context.
277 *
278 * Returns 0 if the Array0 dimension is not present.
279 */
280 #if (defined(RS_VERSION) && (RS_VERSION >= 23))
281 extern uint32_t __attribute__((overloadable))
282 rsGetDimArray0(rs_kernel_context context);
283 #endif
285 /*
286 * rsGetDimArray1: Size of the Array1 dimension for the specified kernel context
287 *
288 * Returns the size of the Array1 dimension for the specified kernel context.
289 * See rsGetDimX() for an explanation of the context.
290 *
291 * Returns 0 if the Array1 dimension is not present.
292 */
293 #if (defined(RS_VERSION) && (RS_VERSION >= 23))
294 extern uint32_t __attribute__((overloadable))
295 rsGetDimArray1(rs_kernel_context context);
296 #endif
298 /*
299 * rsGetDimArray2: Size of the Array2 dimension for the specified kernel context
300 *
301 * Returns the size of the Array2 dimension for the specified kernel context.
302 * See rsGetDimX() for an explanation of the context.
303 *
304 * Returns 0 if the Array2 dimension is not present.
305 */
306 #if (defined(RS_VERSION) && (RS_VERSION >= 23))
307 extern uint32_t __attribute__((overloadable))
308 rsGetDimArray2(rs_kernel_context context);
309 #endif
311 /*
312 * rsGetDimArray3: Size of the Array3 dimension for the specified kernel context
313 *
314 * Returns the size of the Array3 dimension for the specified kernel context.
315 * See rsGetDimX() for an explanation of the context.
316 *
317 * Returns 0 if the Array3 dimension is not present.
318 */
319 #if (defined(RS_VERSION) && (RS_VERSION >= 23))
320 extern uint32_t __attribute__((overloadable))
321 rsGetDimArray3(rs_kernel_context context);
322 #endif
324 /*
325 * rsGetDimHasFaces: Presence of more than one face for the specified kernel context
326 *
327 * If the kernel is iterating over a cubemap, this function returns true if there's more
328 * than one face present. In all other cases, it returns false. See rsGetDimX() for an
329 * explanation of the context.
330 *
331 * rsAllocationGetDimFaces() is similar but returns 0 or 1 instead of a bool.
332 *
333 * Returns: Returns true if more than one face is present, false otherwise.
334 */
335 #if (defined(RS_VERSION) && (RS_VERSION >= 23))
336 extern bool __attribute__((overloadable))
337 rsGetDimHasFaces(rs_kernel_context context);
338 #endif
340 /*
341 * rsGetDimLod: Number of levels of detail for the specified kernel context
342 *
343 * Returns the number of levels of detail for the specified kernel context. This is useful
344 * for mipmaps. See rsGetDimX() for an explanation of the context.
345 *
346 * Returns 0 if Level of Detail is not used.
347 *
348 * rsAllocationGetDimLOD() is similar but returns 0 or 1 instead the actual
349 * number of levels.
350 */
351 #if (defined(RS_VERSION) && (RS_VERSION >= 23))
352 extern uint32_t __attribute__((overloadable))
353 rsGetDimLod(rs_kernel_context context);
354 #endif
356 /*
357 * rsGetDimX: Size of the X dimension for the specified kernel context
358 *
359 * Returns the size of the X dimension for the specified kernel context.
360 *
361 * The kernel context contains common characteristics of the allocations being iterated
362 * over and rarely used indices, like the Array0 index.
363 *
364 * You can access it by adding a special parameter named "context" of
365 * type rs_kernel_context to your kernel function. E.g.
366 * int4 RS_KERNEL myKernel(int4 value, rs_kernel_context context) {
367 * uint32_t size = rsGetDimX(context); //...
368 *
369 * To get the dimension of specific allocation, use rsAllocationGetDimX().
370 */
371 #if (defined(RS_VERSION) && (RS_VERSION >= 23))
372 extern uint32_t __attribute__((overloadable))
373 rsGetDimX(rs_kernel_context context);
374 #endif
376 /*
377 * rsGetDimY: Size of the Y dimension for the specified kernel context
378 *
379 * Returns the size of the X dimension for the specified kernel context.
380 * See rsGetDimX() for an explanation of the context.
381 *
382 * Returns 0 if the Y dimension is not present.
383 *
384 * To get the dimension of specific allocation, use rsAllocationGetDimY().
385 */
386 #if (defined(RS_VERSION) && (RS_VERSION >= 23))
387 extern uint32_t __attribute__((overloadable))
388 rsGetDimY(rs_kernel_context context);
389 #endif
391 /*
392 * rsGetDimZ: Size of the Z dimension for the specified kernel context
393 *
394 * Returns the size of the Z dimension for the specified kernel context.
395 * See rsGetDimX() for an explanation of the context.
396 *
397 * Returns 0 if the Z dimension is not present.
398 *
399 * To get the dimension of specific allocation, use rsAllocationGetDimZ().
400 */
401 #if (defined(RS_VERSION) && (RS_VERSION >= 23))
402 extern uint32_t __attribute__((overloadable))
403 rsGetDimZ(rs_kernel_context context);
404 #endif
406 /*
407 * rsGetFace: Coordinate of the Face for the specified kernel context
408 *
409 * Returns the face on which the cell being processed is found, as specified by the
410 * supplied kernel context. See rsGetArray0() for an explanation of the context.
411 *
412 * Returns RS_ALLOCATION_CUBEMAP_FACE_POSITIVE_X if the face dimension is not
413 * present.
414 */
415 #if (defined(RS_VERSION) && (RS_VERSION >= 23))
416 extern rs_allocation_cubemap_face __attribute__((overloadable))
417 rsGetFace(rs_kernel_context context);
418 #endif
420 /*
421 * rsGetLod: Index in the Levels of Detail dimension for the specified kernel context
422 *
423 * Returns the index in the Levels of Detail dimension of the cell being processed,
424 * as specified by the supplied kernel context. See rsGetArray0() for an explanation of
425 * the context.
426 *
427 * Returns 0 if the Levels of Detail dimension is not present.
428 */
429 #if (defined(RS_VERSION) && (RS_VERSION >= 23))
430 extern uint32_t __attribute__((overloadable))
431 rsGetLod(rs_kernel_context context);
432 #endif
434 #endif // RENDERSCRIPT_RS_FOR_EACH_RSH