1/*
2 * Copyright (C) 2011-2012 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 target="_parent" 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 target="_parent" href=
36  * "http://developer.android.com/guide/topics/renderscript/index.html">Renderscript
37  * developer guide</a> and the <a target="_parent" href=
38  * "http://developer.android.com/resources/samples/RenderScript/index.html">
39  * Renderscript samples</a>.
40  */
41
42/** @file rs_core.rsh
43 *  \brief todo-jsams
44 *
45 *  todo-jsams
46 *
47 */
48
49#ifndef __RS_CORE_RSH__
50#define __RS_CORE_RSH__
51
52#define _RS_RUNTIME extern
53
54#include "rs_types.rsh"
55#include "rs_allocation.rsh"
56#include "rs_atomic.rsh"
57#include "rs_cl.rsh"
58#include "rs_debug.rsh"
59#include "rs_element.rsh"
60#include "rs_math.rsh"
61#include "rs_matrix.rsh"
62#include "rs_object.rsh"
63#include "rs_quaternion.rsh"
64#include "rs_sampler.rsh"
65#include "rs_time.rsh"
66
67/**
68 * Send a message back to the client.  Will not block and returns true
69 * if the message was sendable and false if the fifo was full.
70 * A message ID is required.  Data payload is optional.
71 */
72extern bool __attribute__((overloadable))
73    rsSendToClient(int cmdID);
74/**
75 * \overload
76 */
77extern bool __attribute__((overloadable))
78    rsSendToClient(int cmdID, const void *data, uint len);
79/**
80 * Send a message back to the client, blocking until the message is queued.
81 * A message ID is required.  Data payload is optional.
82 */
83extern void __attribute__((overloadable))
84    rsSendToClientBlocking(int cmdID);
85/**
86 * \overload
87 */
88extern void __attribute__((overloadable))
89    rsSendToClientBlocking(int cmdID, const void *data, uint len);
90
91
92/**
93 * Launch order hint for rsForEach calls.  This provides a hint to the system to
94 * determine in which order the root function of the target is called with each
95 * cell of the allocation.
96 *
97 * This is a hint and implementations may not obey the order.
98 */
99enum rs_for_each_strategy {
100    RS_FOR_EACH_STRATEGY_SERIAL,
101    RS_FOR_EACH_STRATEGY_DONT_CARE,
102    RS_FOR_EACH_STRATEGY_DST_LINEAR,
103    RS_FOR_EACH_STRATEGY_TILE_SMALL,
104    RS_FOR_EACH_STRATEGY_TILE_MEDIUM,
105    RS_FOR_EACH_STRATEGY_TILE_LARGE
106};
107
108
109/**
110 * Structure to provide extra information to a rsForEach call.  Primarly used to
111 * restrict the call to a subset of cells in the allocation.
112 */
113typedef struct rs_script_call {
114    enum rs_for_each_strategy strategy;
115    uint32_t xStart;
116    uint32_t xEnd;
117    uint32_t yStart;
118    uint32_t yEnd;
119    uint32_t zStart;
120    uint32_t zEnd;
121    uint32_t arrayStart;
122    uint32_t arrayEnd;
123} rs_script_call_t;
124
125/**
126 * Make a script to script call to launch work. One of the input or output is
127 * required to be a valid object. The input and output must be of the same
128 * dimensions.
129 * API 10-13
130 *
131 * @param script The target script to call
132 * @param input The allocation to source data from
133 * @param output the allocation to write date into
134 * @param usrData The user definied params to pass to the root script.  May be
135 *                NULL.
136 * @param sc Extra control infomation used to select a sub-region of the
137 *           allocation to be processed or suggest a walking strategy.  May be
138 *           NULL.
139 *
140 *  */
141#if !defined(RS_VERSION) || (RS_VERSION < 14)
142extern void __attribute__((overloadable))
143    rsForEach(rs_script script, rs_allocation input,
144              rs_allocation output, const void * usrData,
145              const rs_script_call_t *sc);
146/**
147 * \overload
148 */
149extern void __attribute__((overloadable))
150    rsForEach(rs_script script, rs_allocation input,
151              rs_allocation output, const void * usrData);
152#else
153
154/**
155 * Make a script to script call to launch work. One of the input or output is
156 * required to be a valid object. The input and output must be of the same
157 * dimensions.
158 * API 14+
159 *
160 * @param script The target script to call
161 * @param input The allocation to source data from
162 * @param output the allocation to write date into
163 * @param usrData The user definied params to pass to the root script.  May be
164 *                NULL.
165 * @param usrDataLen The size of the userData structure.  This will be used to
166 *                   perform a shallow copy of the data if necessary.
167 * @param sc Extra control infomation used to select a sub-region of the
168 *           allocation to be processed or suggest a walking strategy.  May be
169 *           NULL.
170 *
171 */
172extern void __attribute__((overloadable))
173    rsForEach(rs_script script, rs_allocation input, rs_allocation output,
174              const void * usrData, size_t usrDataLen, const rs_script_call_t *);
175/**
176 * \overload
177 */
178extern void __attribute__((overloadable))
179    rsForEach(rs_script script, rs_allocation input, rs_allocation output,
180              const void * usrData, size_t usrDataLen);
181/**
182 * \overload
183 */
184extern void __attribute__((overloadable))
185    rsForEach(rs_script script, rs_allocation input, rs_allocation output);
186#endif
187
188
189
190#undef _RS_RUNTIME
191
192#endif
193