1/* 2 * Copyright (C) 2015 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 indexes. 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, and rarely used indexes, like the Array0 index or the current 55 * level of detail. 56 * 57 * A kernel may be executed in parallel over multiple threads. Each thread will have its 58 * own context. 59 * 60 * You can access the context by adding a special parameter named "context" and of type 61 * rs_kernel_context to your kernel function. See rsGetDimX() and rsGetArray0() for examples. 62 */ 63#if (defined(RS_VERSION) && (RS_VERSION >= 23)) 64typedef const struct rs_kernel_context_t * rs_kernel_context; 65#endif 66 67/* 68 * rs_script_call_t: Cell iteration information 69 * 70 * This structure is used to provide iteration information to a rsForEach call. 71 * It is currently used to restrict processing to a subset of cells. In future 72 * versions, it will also be used to provide hint on how to best iterate over 73 * the cells. 74 * 75 * The Start fields are inclusive and the End fields are exclusive. E.g. to iterate 76 * over cells 4, 5, 6, and 7 in the X dimension, set xStart to 4 and xEnd to 8. 77 */ 78typedef struct rs_script_call { 79 rs_for_each_strategy_t strategy; // Currently ignored. In the future, will be suggested cell iteration strategy. 80 uint32_t xStart; // Starting index in the X dimension. 81 uint32_t xEnd; // Ending index (exclusive) in the X dimension. 82 uint32_t yStart; // Starting index in the Y dimension. 83 uint32_t yEnd; // Ending index (exclusive) in the Y dimension. 84 uint32_t zStart; // Starting index in the Z dimension. 85 uint32_t zEnd; // Ending index (exclusive) in the Z dimension. 86 uint32_t arrayStart; // Starting index in the Array0 dimension. 87 uint32_t arrayEnd; // Ending index (exclusive) in the Array0 dimension. 88 uint32_t array1Start; // Starting index in the Array1 dimension. 89 uint32_t array1End; // Ending index (exclusive) in the Array1 dimension. 90 uint32_t array2Start; // Starting index in the Array2 dimension. 91 uint32_t array2End; // Ending index (exclusive) in the Array2 dimension. 92 uint32_t array3Start; // Starting index in the Array3 dimension. 93 uint32_t array3End; // Ending index (exclusive) in the Array3 dimension. 94} rs_script_call_t; 95 96/* 97 * rsForEach: Invoke the root kernel of a script 98 * 99 * Invoke the kernel named "root" of the specified script. Like other kernels, this root() 100 * function will be invoked repeatedly over the cells of the specificed allocation, filling 101 * the output allocation with the results. 102 * 103 * When rsForEach is called, the root script is launched immediately. rsForEach returns 104 * only when the script has completed and the output allocation is ready to use. 105 * 106 * The rs_script argument is typically initialized using a global variable set from Java. 107 * 108 * The kernel can be invoked with just an input allocation or just an output allocation. 109 * This can be done by defining an rs_allocation variable and not initializing it. E.g. 110 * rs_script gCustomScript; 111 * void specializedProcessing(rs_allocation in) { 112 * rs_allocation ignoredOut; 113 * rsForEach(gCustomScript, in, ignoredOut); 114 * } 115 * 116 * If both input and output allocations are specified, they must have the same dimensions. 117 * 118 * Parameters: 119 * script: Script to call. 120 * input: Allocation to source data from. 121 * output: Allocation to write date into. 122 * usrData: User defined data to pass to the script. May be NULL. 123 * sc: Extra control information used to select a sub-region of the allocation to be processed or suggest a walking strategy. May be NULL. 124 * usrDataLen: Size of the userData structure. This will be used to perform a shallow copy of the data if necessary. 125 */ 126#if !defined(RS_VERSION) || (RS_VERSION <= 13) 127extern void __attribute__((overloadable)) 128 rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData, 129 const rs_script_call_t* sc); 130#endif 131 132#if !defined(RS_VERSION) || (RS_VERSION <= 13) 133extern void __attribute__((overloadable)) 134 rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData); 135#endif 136 137#if (defined(RS_VERSION) && (RS_VERSION >= 14) && (RS_VERSION <= 20)) 138extern void __attribute__((overloadable)) 139 rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData, 140 size_t usrDataLen, const rs_script_call_t* sc); 141#endif 142 143#if (defined(RS_VERSION) && (RS_VERSION >= 14) && (RS_VERSION <= 20)) 144extern void __attribute__((overloadable)) 145 rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData, 146 size_t usrDataLen); 147#endif 148 149#if (defined(RS_VERSION) && (RS_VERSION >= 14)) 150extern void __attribute__((overloadable)) 151 rsForEach(rs_script script, rs_allocation input, rs_allocation output); 152#endif 153 154/* 155 * rsGetArray0: Index in the Array0 dimension for the specified context 156 * 157 * Returns the index in the Array0 dimension of the cell being processed, as specified 158 * by the supplied context. 159 * 160 * This context is created when a kernel is launched and updated at each iteration. 161 * It contains common characteristics of the allocations being iterated over and rarely 162 * used indexes, like the Array0 index. 163 * 164 * You can access the context by adding a special parameter named "context" and of 165 * type rs_kernel_context to your kernel function. E.g. 166 * short RS_KERNEL myKernel(short value, uint32_t x, rs_kernel_context context) { 167 * // The current index in the common x, y, z, w dimensions are accessed by 168 * // adding these variables as arguments. For the more rarely used indexes 169 * // to the other dimensions, extract them from the context: 170 * uint32_t index_a0 = rsGetArray0(context); 171 * //... 172 * } 173 * 174 * This function returns 0 if the Array0 dimension is not present. 175 */ 176#if (defined(RS_VERSION) && (RS_VERSION >= 23)) 177extern uint32_t __attribute__((overloadable)) 178 rsGetArray0(rs_kernel_context context); 179#endif 180 181/* 182 * rsGetArray1: Index in the Array1 dimension for the specified context 183 * 184 * Returns the index in the Array1 dimension of the cell being processed, as specified 185 * by the supplied context. See rsGetArray0() for an explanation of the context. 186 * 187 * Returns 0 if the Array1 dimension is not present. 188 */ 189#if (defined(RS_VERSION) && (RS_VERSION >= 23)) 190extern uint32_t __attribute__((overloadable)) 191 rsGetArray1(rs_kernel_context context); 192#endif 193 194/* 195 * rsGetArray2: Index in the Array2 dimension for the specified context 196 * 197 * Returns the index in the Array2 dimension of the cell being processed, 198 * as specified by the supplied context. See rsGetArray0() for an explanation 199 * of the context. 200 * 201 * Returns 0 if the Array2 dimension is not present. 202 */ 203#if (defined(RS_VERSION) && (RS_VERSION >= 23)) 204extern uint32_t __attribute__((overloadable)) 205 rsGetArray2(rs_kernel_context context); 206#endif 207 208/* 209 * rsGetArray3: Index in the Array3 dimension for the specified context 210 * 211 * Returns the index in the Array3 dimension of the cell being processed, as specified 212 * by the supplied context. See rsGetArray0() for an explanation of the context. 213 * 214 * Returns 0 if the Array3 dimension is not present. 215 */ 216#if (defined(RS_VERSION) && (RS_VERSION >= 23)) 217extern uint32_t __attribute__((overloadable)) 218 rsGetArray3(rs_kernel_context context); 219#endif 220 221/* 222 * rsGetDimArray0: Size of the Array0 dimension for the specified context 223 * 224 * Returns the size of the Array0 dimension for the specified context. 225 * See rsGetDimX() for an explanation of the context. 226 * 227 * Returns 0 if the Array0 dimension is not present. 228 */ 229#if (defined(RS_VERSION) && (RS_VERSION >= 23)) 230extern uint32_t __attribute__((overloadable)) 231 rsGetDimArray0(rs_kernel_context context); 232#endif 233 234/* 235 * rsGetDimArray1: Size of the Array1 dimension for the specified context 236 * 237 * Returns the size of the Array1 dimension for the specified context. 238 * See rsGetDimX() for an explanation of the context. 239 * 240 * Returns 0 if the Array1 dimension is not present. 241 */ 242#if (defined(RS_VERSION) && (RS_VERSION >= 23)) 243extern uint32_t __attribute__((overloadable)) 244 rsGetDimArray1(rs_kernel_context context); 245#endif 246 247/* 248 * rsGetDimArray2: Size of the Array2 dimension for the specified context 249 * 250 * Returns the size of the Array2 dimension for the specified context. 251 * See rsGetDimX() for an explanation of the context. 252 * 253 * Returns 0 if the Array2 dimension is not present. 254 */ 255#if (defined(RS_VERSION) && (RS_VERSION >= 23)) 256extern uint32_t __attribute__((overloadable)) 257 rsGetDimArray2(rs_kernel_context context); 258#endif 259 260/* 261 * rsGetDimArray3: Size of the Array3 dimension for the specified context 262 * 263 * Returns the size of the Array3 dimension for the specified context. 264 * See rsGetDimX() for an explanation of the context. 265 * 266 * Returns 0 if the Array3 dimension is not present. 267 */ 268#if (defined(RS_VERSION) && (RS_VERSION >= 23)) 269extern uint32_t __attribute__((overloadable)) 270 rsGetDimArray3(rs_kernel_context context); 271#endif 272 273/* 274 * rsGetDimHasFaces: Presence of more than one face for the specified context 275 * 276 * If the context refers to a cubemap, this function returns true if there's more than 277 * one face present. In all other cases, it returns false. See rsGetDimX() for an 278 * explanation of the context. 279 * 280 * rsAllocationGetDimFaces() is similar but returns 0 or 1 instead of a bool. 281 * 282 * Returns: Returns true if more than one face is present, false otherwise. 283 */ 284#if (defined(RS_VERSION) && (RS_VERSION >= 23)) 285extern bool __attribute__((overloadable)) 286 rsGetDimHasFaces(rs_kernel_context context); 287#endif 288 289/* 290 * rsGetDimLod: Number of levels of detail for the specified context 291 * 292 * Returns the number of levels of detail for the specified context. This is useful 293 * for mipmaps. See rsGetDimX() for an explanation of the context. 294 * 295 * Returns 0 if Level of Detail is not used. 296 * 297 * rsAllocationGetDimLOD() is similar but returns 0 or 1 instead the actual 298 * number of levels. 299 */ 300#if (defined(RS_VERSION) && (RS_VERSION >= 23)) 301extern uint32_t __attribute__((overloadable)) 302 rsGetDimLod(rs_kernel_context context); 303#endif 304 305/* 306 * rsGetDimX: Size of the X dimension for the specified context 307 * 308 * Returns the size of the X dimension for the specified context. 309 * 310 * This context is created when a kernel is launched. It contains common 311 * characteristics of the allocations being iterated over by the kernel in 312 * a very efficient structure. It also contains rarely used indexes. 313 * 314 * You can access it by adding a special parameter named "context" and of 315 * type rs_kernel_context to your kernel function. E.g. 316 * int4 RS_KERNEL myKernel(int4 value, rs_kernel_context context) { 317 * uint32_t size = rsGetDimX(context); //... 318 * 319 * To get the dimension of specific allocation, use rsAllocationGetDimX(). 320 */ 321#if (defined(RS_VERSION) && (RS_VERSION >= 23)) 322extern uint32_t __attribute__((overloadable)) 323 rsGetDimX(rs_kernel_context context); 324#endif 325 326/* 327 * rsGetDimY: Size of the Y dimension for the specified context 328 * 329 * Returns the size of the X dimension for the specified context. 330 * See rsGetDimX() for an explanation of the context. 331 * 332 * Returns 0 if the Y dimension is not present. 333 * 334 * To get the dimension of specific allocation, use rsAllocationGetDimY(). 335 */ 336#if (defined(RS_VERSION) && (RS_VERSION >= 23)) 337extern uint32_t __attribute__((overloadable)) 338 rsGetDimY(rs_kernel_context context); 339#endif 340 341/* 342 * rsGetDimZ: Size of the Z dimension for the specified context 343 * 344 * Returns the size of the Z dimension for the specified context. 345 * See rsGetDimX() for an explanation of the context. 346 * 347 * Returns 0 if the Z dimension is not present. 348 * 349 * To get the dimension of specific allocation, use rsAllocationGetDimZ(). 350 */ 351#if (defined(RS_VERSION) && (RS_VERSION >= 23)) 352extern uint32_t __attribute__((overloadable)) 353 rsGetDimZ(rs_kernel_context context); 354#endif 355 356/* 357 * rsGetFace: Coordinate of the Face for the specified context 358 * 359 * Returns the face on which the cell being processed is found, as specified by the 360 * supplied context. See rsGetArray0() for an explanation of the context. 361 * 362 * Returns RS_ALLOCATION_CUBEMAP_FACE_POSITIVE_X if the face dimension is not 363 * present. 364 */ 365#if (defined(RS_VERSION) && (RS_VERSION >= 23)) 366extern rs_allocation_cubemap_face __attribute__((overloadable)) 367 rsGetFace(rs_kernel_context context); 368#endif 369 370/* 371 * rsGetLod: Index in the Levels of Detail dimension for the specified context 372 * 373 * Returns the index in the Levels of Detail dimension of the cell being processed, 374 * as specified by the supplied context. See rsGetArray0() for an explanation of 375 * the context. 376 * 377 * Returns 0 if the Levels of Detail dimension is not present. 378 */ 379#if (defined(RS_VERSION) && (RS_VERSION >= 23)) 380extern uint32_t __attribute__((overloadable)) 381 rsGetLod(rs_kernel_context context); 382#endif 383 384#endif // RENDERSCRIPT_RS_FOR_EACH_RSH 385