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 header: 18 summary: Kernel Invocation Functions and Types 19 description: 20 The @rsForEach() function can be used to invoke the root kernel of a script. 21 22 The other functions are used to get the characteristics of the invocation of 23 an executing kernel, like dimensions and current indexes. These functions take 24 a @rs_kernel_context as argument. 25 end: 26 27 type: rs_for_each_strategy_t 28 enum: rs_for_each_strategy 29 value: RS_FOR_EACH_STRATEGY_SERIAL = 0, "Prefer contiguous memory regions." 30 value: RS_FOR_EACH_STRATEGY_DONT_CARE = 1, "No prefrences." 31 #TODO explain this better 32 value: RS_FOR_EACH_STRATEGY_DST_LINEAR = 2, "Prefer DST." 33 value: RS_FOR_EACH_STRATEGY_TILE_SMALL = 3, "Prefer processing small rectangular regions." 34 value: RS_FOR_EACH_STRATEGY_TILE_MEDIUM = 4, "Prefer processing medium rectangular regions." 35 value: RS_FOR_EACH_STRATEGY_TILE_LARGE = 5, "Prefer processing large rectangular regions." 36 summary: Suggested cell processing order 37 description: 38 This type is used to suggest how the invoked kernel should iterate over the cells of the 39 allocations. This is a hint only. Implementations may not follow the suggestion. 40 41 This specification can help the caching behavior of the running kernel, e.g. the cache 42 locality when the processing is distributed over multiple cores. 43 end: 44 45 type: rs_kernel_context 46 version: 23 47 simple: const struct rs_kernel_context_t * 48 summary: Handle to a kernel invocation context 49 description: 50 The kernel context contains common characteristics of the allocations being iterated 51 over, like dimensions, and rarely used indexes, like the Array0 index or the current 52 level of detail. 53 54 A kernel may be executed in parallel over multiple threads. Each thread will have its 55 own context. 56 57 You can access the context by adding a special parameter named "context" and of type 58 rs_kernel_context to your kernel function. See @rsGetDimX() and @rsGetArray0() for examples. 59 end: 60 61 type: rs_script_call_t 62 struct: rs_script_call 63 field: rs_for_each_strategy_t strategy, "Currently ignored. In the future, will be suggested cell iteration strategy." 64 field: uint32_t xStart, "Starting index in the X dimension." 65 field: uint32_t xEnd, "Ending index (exclusive) in the X dimension." 66 field: uint32_t yStart, "Starting index in the Y dimension." 67 field: uint32_t yEnd, "Ending index (exclusive) in the Y dimension." 68 field: uint32_t zStart, "Starting index in the Z dimension." 69 field: uint32_t zEnd, "Ending index (exclusive) in the Z dimension." 70 field: uint32_t arrayStart, "Starting index in the Array0 dimension." 71 field: uint32_t arrayEnd, "Ending index (exclusive) in the Array0 dimension." 72 field: uint32_t array1Start, "Starting index in the Array1 dimension." 73 field: uint32_t array1End, "Ending index (exclusive) in the Array1 dimension." 74 field: uint32_t array2Start, "Starting index in the Array2 dimension." 75 field: uint32_t array2End, "Ending index (exclusive) in the Array2 dimension." 76 field: uint32_t array3Start, "Starting index in the Array3 dimension." 77 field: uint32_t array3End, "Ending index (exclusive) in the Array3 dimension." 78 summary: Cell iteration information 79 description: 80 This structure is used to provide iteration information to a rsForEach call. 81 It is currently used to restrict processing to a subset of cells. In future 82 versions, it will also be used to provide hint on how to best iterate over 83 the cells. 84 85 The Start fields are inclusive and the End fields are exclusive. E.g. to iterate 86 over cells 4, 5, 6, and 7 in the X dimension, set xStart to 4 and xEnd to 8. 87 end: 88 89 function: rsForEach 90 version: 9 13 91 ret: void 92 arg: rs_script script, "Script to call." 93 arg: rs_allocation input, "Allocation to source data from." 94 arg: rs_allocation output, "Allocation to write date into." 95 arg: const void* usrData, "User defined data to pass to the script. May be NULL." 96 arg: const rs_script_call_t* sc, "Extra control information used to select a sub-region of the allocation to be processed or suggest a walking strategy. May be NULL." 97 summary: Invoke the root kernel of a script 98 description: 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.<code><br/> 110 rs_script gCustomScript;<br/> 111 void specializedProcessing(rs_allocation in) {<br/> 112 rs_allocation ignoredOut;<br/> 113 rsForEach(gCustomScript, in, ignoredOut);<br/> 114 }<br/></code> 115 116 If both input and output allocations are specified, they must have the same dimensions. 117 test: none 118 end: 119 120 function: rsForEach 121 version: 9 13 122 ret: void 123 arg: rs_script script 124 arg: rs_allocation input 125 arg: rs_allocation output 126 arg: const void* usrData 127 test: none 128 end: 129 130 function: rsForEach 131 version: 14 20 132 ret: void 133 arg: rs_script script 134 arg: rs_allocation input 135 arg: rs_allocation output 136 arg: const void* usrData 137 arg: size_t usrDataLen, "Size of the userData structure. This will be used to perform a shallow copy of the data if necessary." 138 arg: const rs_script_call_t* sc 139 test: none 140 end: 141 142 function: rsForEach 143 version: 14 20 144 ret: void 145 arg: rs_script script 146 arg: rs_allocation input 147 arg: rs_allocation output 148 arg: const void* usrData 149 arg: size_t usrDataLen 150 test: none 151 end: 152 153 function: rsForEach 154 version: 14 155 ret: void 156 arg: rs_script script 157 arg: rs_allocation input 158 arg: rs_allocation output 159 test: none 160 end: 161 162 function: rsGetArray0 163 version: 23 164 ret: uint32_t 165 arg: rs_kernel_context context 166 summary: Index in the Array0 dimension for the specified context 167 description: 168 Returns the index in the Array0 dimension of the cell being processed, as specified 169 by the supplied context. 170 171 This context is created when a kernel is launched and updated at each iteration. 172 It contains common characteristics of the allocations being iterated over and rarely 173 used indexes, like the Array0 index. 174 175 You can access the context by adding a special parameter named "context" and of 176 type rs_kernel_context to your kernel function. E.g.<br/> 177 <code>short RS_KERNEL myKernel(short value, uint32_t x, rs_kernel_context context) {<br/> 178 // The current index in the common x, y, z, w dimensions are accessed by<br/> 179 // adding these variables as arguments. For the more rarely used indexes<br/> 180 // to the other dimensions, extract them from the context:<br/> 181 uint32_t index_a0 = rsGetArray0(context);<br/> 182 //...<br/> 183 }<br/></code> 184 185 This function returns 0 if the Array0 dimension is not present. 186 test: none 187 end: 188 189 function: rsGetArray1 190 version: 23 191 ret: uint32_t 192 arg: rs_kernel_context context 193 summary: Index in the Array1 dimension for the specified context 194 description: 195 Returns the index in the Array1 dimension of the cell being processed, as specified 196 by the supplied context. See @rsGetArray0() for an explanation of the context. 197 198 Returns 0 if the Array1 dimension is not present. 199 test: none 200 end: 201 202 function: rsGetArray2 203 version: 23 204 ret: uint32_t 205 arg: rs_kernel_context context 206 summary: Index in the Array2 dimension for the specified context 207 description: 208 Returns the index in the Array2 dimension of the cell being processed, 209 as specified by the supplied context. See @rsGetArray0() for an explanation 210 of the context. 211 212 Returns 0 if the Array2 dimension is not present. 213 test: none 214 end: 215 216 function: rsGetArray3 217 version: 23 218 ret: uint32_t 219 arg: rs_kernel_context context 220 summary: Index in the Array3 dimension for the specified context 221 description: 222 Returns the index in the Array3 dimension of the cell being processed, as specified 223 by the supplied context. See @rsGetArray0() for an explanation of the context. 224 225 Returns 0 if the Array3 dimension is not present. 226 test: none 227 end: 228 229 function: rsGetDimArray0 230 version: 23 231 ret: uint32_t 232 arg: rs_kernel_context context 233 summary: Size of the Array0 dimension for the specified context 234 description: 235 Returns the size of the Array0 dimension for the specified context. 236 See @rsGetDimX() for an explanation of the context. 237 238 Returns 0 if the Array0 dimension is not present. 239 #TODO Add an hyperlink to something that explains Array0/1/2/3 240 # for the relevant functions. 241 test: none 242 end: 243 244 function: rsGetDimArray1 245 version: 23 246 ret: uint32_t 247 arg: rs_kernel_context context 248 summary: Size of the Array1 dimension for the specified context 249 description: 250 Returns the size of the Array1 dimension for the specified context. 251 See @rsGetDimX() for an explanation of the context. 252 253 Returns 0 if the Array1 dimension is not present. 254 test: none 255 end: 256 257 function: rsGetDimArray2 258 version: 23 259 ret: uint32_t 260 arg: rs_kernel_context context 261 summary: Size of the Array2 dimension for the specified context 262 description: 263 Returns the size of the Array2 dimension for the specified context. 264 See @rsGetDimX() for an explanation of the context. 265 266 Returns 0 if the Array2 dimension is not present. 267 test: none 268 end: 269 270 function: rsGetDimArray3 271 version: 23 272 ret: uint32_t 273 arg: rs_kernel_context context 274 summary: Size of the Array3 dimension for the specified context 275 description: 276 Returns the size of the Array3 dimension for the specified context. 277 See @rsGetDimX() for an explanation of the context. 278 279 Returns 0 if the Array3 dimension is not present. 280 test: none 281 end: 282 283 function: rsGetDimHasFaces 284 version: 23 285 ret: bool, "Returns true if more than one face is present, false otherwise." 286 arg: rs_kernel_context context 287 summary: Presence of more than one face for the specified context 288 description: 289 If the context refers to a cubemap, this function returns true if there's more than 290 one face present. In all other cases, it returns false. See @rsGetDimX() for an 291 explanation of the context. 292 293 @rsAllocationGetDimFaces() is similar but returns 0 or 1 instead of a bool. 294 test: none 295 end: 296 297 function: rsGetDimLod 298 version: 23 299 ret: uint32_t 300 arg: rs_kernel_context context 301 summary: Number of levels of detail for the specified context 302 description: 303 Returns the number of levels of detail for the specified context. This is useful 304 for mipmaps. See @rsGetDimX() for an explanation of the context. 305 306 Returns 0 if Level of Detail is not used. 307 308 @rsAllocationGetDimLOD() is similar but returns 0 or 1 instead the actual 309 number of levels. 310 test: none 311 end: 312 313 function: rsGetDimX 314 version: 23 315 ret: uint32_t 316 arg: rs_kernel_context context 317 summary: Size of the X dimension for the specified context 318 description: 319 Returns the size of the X dimension for the specified context. 320 321 This context is created when a kernel is launched. It contains common 322 characteristics of the allocations being iterated over by the kernel in 323 a very efficient structure. It also contains rarely used indexes. 324 325 You can access it by adding a special parameter named "context" and of 326 type rs_kernel_context to your kernel function. E.g.<br/> 327 <code>int4 RS_KERNEL myKernel(int4 value, rs_kernel_context context) {<br/> 328 uint32_t size = rsGetDimX(context); //...<br/></code> 329 330 To get the dimension of specific allocation, use @rsAllocationGetDimX(). 331 test: none 332 end: 333 334 function: rsGetDimY 335 version: 23 336 ret: uint32_t 337 arg: rs_kernel_context context 338 summary: Size of the Y dimension for the specified context 339 description: 340 Returns the size of the X dimension for the specified context. 341 See @rsGetDimX() for an explanation of the context. 342 343 Returns 0 if the Y dimension is not present. 344 345 To get the dimension of specific allocation, use @rsAllocationGetDimY(). 346 test: none 347 end: 348 349 function: rsGetDimZ 350 version: 23 351 ret: uint32_t 352 arg: rs_kernel_context context 353 summary: Size of the Z dimension for the specified context 354 description: 355 Returns the size of the Z dimension for the specified context. 356 See @rsGetDimX() for an explanation of the context. 357 358 Returns 0 if the Z dimension is not present. 359 360 To get the dimension of specific allocation, use @rsAllocationGetDimZ(). 361 test: none 362 end: 363 364 function: rsGetFace 365 version: 23 366 ret: rs_allocation_cubemap_face 367 arg: rs_kernel_context context 368 summary: Coordinate of the Face for the specified context 369 description: 370 Returns the face on which the cell being processed is found, as specified by the 371 supplied context. See @rsGetArray0() for an explanation of the context. 372 373 Returns RS_ALLOCATION_CUBEMAP_FACE_POSITIVE_X if the face dimension is not 374 present. 375 test: none 376 end: 377 378 function: rsGetLod 379 version: 23 380 ret: uint32_t 381 arg: rs_kernel_context context 382 summary: Index in the Levels of Detail dimension for the specified context 383 description: 384 Returns the index in the Levels of Detail dimension of the cell being processed, 385 as specified by the supplied context. See @rsGetArray0() for an explanation of 386 the context. 387 388 Returns 0 if the Levels of Detail dimension is not present. 389 test: none 390 end: 391
