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_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 */ 28 29#ifndef RENDERSCRIPT_RS_FOR_EACH_RSH 30#define RENDERSCRIPT_RS_FOR_EACH_RSH 31 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 */ 41typedef 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; 49 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)) 61typedef const struct rs_kernel_context_t * rs_kernel_context; 62#endif 63 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 */ 75typedef 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; 92 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)) 100typedef void* rs_kernel; 101#endif 102 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) 144extern 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 148 149#if !defined(RS_VERSION) || (RS_VERSION <= 13) 150extern void __attribute__((overloadable)) 151 rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData); 152#endif 153 154#if (defined(RS_VERSION) && (RS_VERSION >= 14) && (RS_VERSION <= 20)) 155extern 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 159 160#if (defined(RS_VERSION) && (RS_VERSION >= 14) && (RS_VERSION <= 20)) 161extern void __attribute__((overloadable)) 162 rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData, 163 size_t usrDataLen); 164#endif 165 166#if (defined(RS_VERSION) && (RS_VERSION >= 14) && (RS_VERSION <= 23)) 167extern void __attribute__((overloadable)) 168 rsForEach(rs_script script, rs_allocation input, rs_allocation output); 169#endif 170 171#if (defined(RS_VERSION) && (RS_VERSION >= 24)) 172extern void 173 rsForEach(rs_kernel kernel, ...); 174#endif 175 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)) 202extern void 203 rsForEachWithOptions(rs_kernel kernel, rs_script_call_t* options, ...); 204#endif 205 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)) 228extern uint32_t __attribute__((overloadable)) 229 rsGetArray0(rs_kernel_context context); 230#endif 231 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)) 241extern uint32_t __attribute__((overloadable)) 242 rsGetArray1(rs_kernel_context context); 243#endif 244 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)) 255extern uint32_t __attribute__((overloadable)) 256 rsGetArray2(rs_kernel_context context); 257#endif 258 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)) 268extern uint32_t __attribute__((overloadable)) 269 rsGetArray3(rs_kernel_context context); 270#endif 271 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)) 281extern uint32_t __attribute__((overloadable)) 282 rsGetDimArray0(rs_kernel_context context); 283#endif 284 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)) 294extern uint32_t __attribute__((overloadable)) 295 rsGetDimArray1(rs_kernel_context context); 296#endif 297 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)) 307extern uint32_t __attribute__((overloadable)) 308 rsGetDimArray2(rs_kernel_context context); 309#endif 310 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)) 320extern uint32_t __attribute__((overloadable)) 321 rsGetDimArray3(rs_kernel_context context); 322#endif 323 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)) 336extern bool __attribute__((overloadable)) 337 rsGetDimHasFaces(rs_kernel_context context); 338#endif 339 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)) 352extern uint32_t __attribute__((overloadable)) 353 rsGetDimLod(rs_kernel_context context); 354#endif 355 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)) 372extern uint32_t __attribute__((overloadable)) 373 rsGetDimX(rs_kernel_context context); 374#endif 375 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)) 387extern uint32_t __attribute__((overloadable)) 388 rsGetDimY(rs_kernel_context context); 389#endif 390 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)) 402extern uint32_t __attribute__((overloadable)) 403 rsGetDimZ(rs_kernel_context context); 404#endif 405 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)) 416extern rs_allocation_cubemap_face __attribute__((overloadable)) 417 rsGetFace(rs_kernel_context context); 418#endif 419 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)) 430extern uint32_t __attribute__((overloadable)) 431 rsGetLod(rs_kernel_context context); 432#endif 433 434#endif // RENDERSCRIPT_RS_FOR_EACH_RSH 435