rs_for_each.spec revision 4324eec445c6882dce89a24765482293ed31914e
1be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet# 2be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet# Copyright (C) 2015 The Android Open Source Project 3be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet# 4be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet# Licensed under the Apache License, Version 2.0 (the "License"); 5be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet# you may not use this file except in compliance with the License. 6be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet# You may obtain a copy of the License at 7be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet# 8be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet# http://www.apache.org/licenses/LICENSE-2.0 9be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet# 10be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet# Unless required by applicable law or agreed to in writing, software 11be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet# distributed under the License is distributed on an "AS IS" BASIS, 12be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet# See the License for the specific language governing permissions and 14be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet# limitations under the License. 15be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet# 16be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 17be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletheader: 1820b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletsummary: Kernel Invocation Functions and Types 19be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletdescription: 2020b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet The @rsForEach() function can be used to invoke the root kernel of a script. 2120b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet 2220b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet The other functions are used to get the characteristics of the invocation of 2320b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet an executing kernel, like dimensions and current indexes. These functions take 2420b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet a @rs_kernel_context as argument. 25be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletend: 26be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 27be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillettype: rs_for_each_strategy_t 28be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletenum: rs_for_each_strategy 2920b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletvalue: RS_FOR_EACH_STRATEGY_SERIAL = 0, "Prefer contiguous memory regions." 3020b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletvalue: RS_FOR_EACH_STRATEGY_DONT_CARE = 1, "No prefrences." 3120b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet#TODO explain this better 3220b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletvalue: RS_FOR_EACH_STRATEGY_DST_LINEAR = 2, "Prefer DST." 3320b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletvalue: RS_FOR_EACH_STRATEGY_TILE_SMALL = 3, "Prefer processing small rectangular regions." 3420b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletvalue: RS_FOR_EACH_STRATEGY_TILE_MEDIUM = 4, "Prefer processing medium rectangular regions." 3520b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletvalue: RS_FOR_EACH_STRATEGY_TILE_LARGE = 5, "Prefer processing large rectangular regions." 3620b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletsummary: Suggested cell processing order 37be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletdescription: 3820b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet This type is used to suggest how the invoked kernel should iterate over the cells of the 3920b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet allocations. This is a hint only. Implementations may not follow the suggestion. 40be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 4120b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet This specification can help the caching behavior of the running kernel, e.g. the cache 4220b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet locality when the processing is distributed over multiple cores. 43be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletend: 44be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 45be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillettype: rs_kernel_context 46be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletversion: 23 47be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletsimple: const struct rs_kernel_context_t * 4820b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletsummary: Handle to a kernel invocation context 49be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletdescription: 5020b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet The kernel context contains common characteristics of the allocations being iterated 5120b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet over, like dimensions, and rarely used indexes, like the Array0 index or the current 5220b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet level of detail. 5320b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet 5420b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet A kernel may be executed in parallel over multiple threads. Each thread will have its 5520b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet own context. 5620b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet 574324eec445c6882dce89a24765482293ed31914eJean-Luc Brouillet You can access the context by adding a special parameter named "context" and of type 584324eec445c6882dce89a24765482293ed31914eJean-Luc Brouillet rs_kernel_context to your kernel function. See @rsGetDimX() and @rsGetArray0() for examples. 59be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletend: 60be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 61be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillettype: rs_script_call_t 62be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletstruct: rs_script_call 6320b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletfield: rs_for_each_strategy_t strategy, "Currently ignored. In the future, will be suggested cell iteration strategy." 6420b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletfield: uint32_t xStart, "Starting index in the X dimension." 6520b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletfield: uint32_t xEnd, "Ending index (exclusive) in the X dimension." 6620b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletfield: uint32_t yStart, "Starting index in the Y dimension." 6720b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletfield: uint32_t yEnd, "Ending index (exclusive) in the Y dimension." 6820b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletfield: uint32_t zStart, "Starting index in the Z dimension." 6920b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletfield: uint32_t zEnd, "Ending index (exclusive) in the Z dimension." 7020b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletfield: uint32_t arrayStart, "Starting index in the Array0 dimension." 7120b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletfield: uint32_t arrayEnd, "Ending index (exclusive) in the Array0 dimension." 7257b768bce0a0de33a1b75153e5ab2edd1a9dcca5Jean-Luc Brouilletfield: uint32_t array1Start, "Starting index in the Array1 dimension." 7357b768bce0a0de33a1b75153e5ab2edd1a9dcca5Jean-Luc Brouilletfield: uint32_t array1End, "Ending index (exclusive) in the Array1 dimension." 7457b768bce0a0de33a1b75153e5ab2edd1a9dcca5Jean-Luc Brouilletfield: uint32_t array2Start, "Starting index in the Array2 dimension." 7557b768bce0a0de33a1b75153e5ab2edd1a9dcca5Jean-Luc Brouilletfield: uint32_t array2End, "Ending index (exclusive) in the Array2 dimension." 7657b768bce0a0de33a1b75153e5ab2edd1a9dcca5Jean-Luc Brouilletfield: uint32_t array3Start, "Starting index in the Array3 dimension." 7757b768bce0a0de33a1b75153e5ab2edd1a9dcca5Jean-Luc Brouilletfield: uint32_t array3End, "Ending index (exclusive) in the Array3 dimension." 7820b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletsummary: Cell iteration information 79be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletdescription: 8020b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet This structure is used to provide iteration information to a rsForEach call. 8120b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet It is currently used to restrict processing to a subset of cells. In future 8220b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet versions, it will also be used to provide hint on how to best iterate over 8320b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet the cells. 8420b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet 8520b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet The Start fields are inclusive and the End fields are exclusive. E.g. to iterate 8620b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet over cells 4, 5, 6, and 7 in the X dimension, set xStart to 4 and xEnd to 8. 87be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletend: 88be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 89be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletfunction: rsForEach 90be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletversion: 9 13 91be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletret: void 9220b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletarg: rs_script script, "Script to call." 9320b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletarg: rs_allocation input, "Allocation to source data from." 9420b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletarg: rs_allocation output, "Allocation to write date into." 9520b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletarg: const void* usrData, "User defined data to pass to the script. May be NULL." 9620b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletarg: 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." 9720b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletsummary: Invoke the root kernel of a script 98be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletdescription: 9920b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet Invoke the kernel named "root" of the specified script. Like other kernels, this root() 10020b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet function will be invoked repeatedly over the cells of the specificed allocation, filling 10120b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet the output allocation with the results. 10220b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet 10320b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet When rsForEach is called, the root script is launched immediately. rsForEach returns 10420b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet only when the script has completed and the output allocation is ready to use. 10520b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet 10620b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet The rs_script argument is typically initialized using a global variable set from Java. 10720b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet 10820b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet The kernel can be invoked with just an input allocation or just an output allocation. 10920b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet This can be done by defining an rs_allocation variable and not initializing it. E.g.<code><br/> 11020b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet rs_script gCustomScript;<br/> 11120b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet void specializedProcessing(rs_allocation in) {<br/> 11245c5f4be5d0215a30be1051420e083a49912c5acJean-Luc Brouillet rs_allocation ignoredOut;<br/> 11345c5f4be5d0215a30be1051420e083a49912c5acJean-Luc Brouillet rsForEach(gCustomScript, in, ignoredOut);<br/> 11420b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet }<br/></code> 11520b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet 11620b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet If both input and output allocations are specified, they must have the same dimensions. 117be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillettest: none 118be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletend: 119be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 120be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletfunction: rsForEach 121be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletversion: 9 13 122be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletret: void 123be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletarg: rs_script script 124be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletarg: rs_allocation input 125be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletarg: rs_allocation output 126be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletarg: const void* usrData 127be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillettest: none 128be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletend: 129be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 130be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletfunction: rsForEach 131be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletversion: 14 20 132be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletret: void 133be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletarg: rs_script script 134be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletarg: rs_allocation input 135be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletarg: rs_allocation output 136be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletarg: const void* usrData 1376386ceb3bf25e442513224aaa45691dfe49562d9Jean-Luc Brouilletarg: size_t usrDataLen, "Size of the userData structure. This will be used to perform a shallow copy of the data if necessary." 138be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletarg: const rs_script_call_t* sc 139be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillettest: none 140be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletend: 141be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 142be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletfunction: rsForEach 143be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletversion: 14 20 144be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletret: void 145be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletarg: rs_script script 146be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletarg: rs_allocation input 147be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletarg: rs_allocation output 148be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletarg: const void* usrData 149be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletarg: size_t usrDataLen 150be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillettest: none 151be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletend: 152be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 153be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletfunction: rsForEach 154be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletversion: 14 155be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletret: void 156be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletarg: rs_script script 157be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletarg: rs_allocation input 158be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletarg: rs_allocation output 159be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillettest: none 160be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletend: 161be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 162be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletfunction: rsGetArray0 163be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletversion: 23 164be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletret: uint32_t 1654324eec445c6882dce89a24765482293ed31914eJean-Luc Brouilletarg: rs_kernel_context context 166be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletsummary: Index in the Array0 dimension for the specified context 167be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletdescription: 1686386ceb3bf25e442513224aaa45691dfe49562d9Jean-Luc Brouillet Returns the index in the Array0 dimension of the cell being processed, as specified 1696386ceb3bf25e442513224aaa45691dfe49562d9Jean-Luc Brouillet by the supplied context. 170be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 1716386ceb3bf25e442513224aaa45691dfe49562d9Jean-Luc Brouillet This context is created when a kernel is launched and updated at each iteration. 1726386ceb3bf25e442513224aaa45691dfe49562d9Jean-Luc Brouillet It contains common characteristics of the allocations being iterated over and rarely 1736386ceb3bf25e442513224aaa45691dfe49562d9Jean-Luc Brouillet used indexes, like the Array0 index. 174be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 1754324eec445c6882dce89a24765482293ed31914eJean-Luc Brouillet You can access the context by adding a special parameter named "context" and of 1764324eec445c6882dce89a24765482293ed31914eJean-Luc Brouillet type rs_kernel_context to your kernel function. E.g.<br/> 177be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet <code>short RS_KERNEL myKernel(short value, uint32_t x, rs_kernel_context context) {<br/> 178be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet // The current index in the common x, y, z, w dimensions are accessed by<br/> 179be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet // adding these variables as arguments. For the more rarely used indexes<br/> 180be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet // to the other dimensions, extract them from the context:<br/> 181be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet uint32_t index_a0 = rsGetArray0(context);<br/> 182be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet //...<br/> 183be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet }<br/></code> 184be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 185be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet This function returns 0 if the Array0 dimension is not present. 186be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillettest: none 187be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletend: 188be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 189be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletfunction: rsGetArray1 190be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletversion: 23 191be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletret: uint32_t 1924324eec445c6882dce89a24765482293ed31914eJean-Luc Brouilletarg: rs_kernel_context context 193be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletsummary: Index in the Array1 dimension for the specified context 194be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletdescription: 1956386ceb3bf25e442513224aaa45691dfe49562d9Jean-Luc Brouillet Returns the index in the Array1 dimension of the cell being processed, as specified 1966386ceb3bf25e442513224aaa45691dfe49562d9Jean-Luc Brouillet by the supplied context. See @rsGetArray0() for an explanation of the context. 197be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 198be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet Returns 0 if the Array1 dimension is not present. 199be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillettest: none 200be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletend: 201be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 202be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletfunction: rsGetArray2 203be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletversion: 23 204be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletret: uint32_t 2054324eec445c6882dce89a24765482293ed31914eJean-Luc Brouilletarg: rs_kernel_context context 206be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletsummary: Index in the Array2 dimension for the specified context 207be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletdescription: 208be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet Returns the index in the Array2 dimension of the cell being processed, 209be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet as specified by the supplied context. See @rsGetArray0() for an explanation 210be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet of the context. 211be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 212be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet Returns 0 if the Array2 dimension is not present. 213be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillettest: none 214be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletend: 215be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 216be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletfunction: rsGetArray3 217be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletversion: 23 218be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletret: uint32_t 2194324eec445c6882dce89a24765482293ed31914eJean-Luc Brouilletarg: rs_kernel_context context 220be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletsummary: Index in the Array3 dimension for the specified context 221be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletdescription: 2226386ceb3bf25e442513224aaa45691dfe49562d9Jean-Luc Brouillet Returns the index in the Array3 dimension of the cell being processed, as specified 2236386ceb3bf25e442513224aaa45691dfe49562d9Jean-Luc Brouillet by the supplied context. See @rsGetArray0() for an explanation of the context. 224be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 225be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet Returns 0 if the Array3 dimension is not present. 226be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillettest: none 227be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletend: 228be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 229be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletfunction: rsGetDimArray0 230be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletversion: 23 231be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletret: uint32_t 2324324eec445c6882dce89a24765482293ed31914eJean-Luc Brouilletarg: rs_kernel_context context 233be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletsummary: Size of the Array0 dimension for the specified context 234be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletdescription: 235be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet Returns the size of the Array0 dimension for the specified context. 236be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet See @rsGetDimX() for an explanation of the context. 237be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 238be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet Returns 0 if the Array0 dimension is not present. 239be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet#TODO Add an hyperlink to something that explains Array0/1/2/3 240be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet# for the relevant functions. 241be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillettest: none 242be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletend: 243be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 244be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletfunction: rsGetDimArray1 245be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletversion: 23 246be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletret: uint32_t 2474324eec445c6882dce89a24765482293ed31914eJean-Luc Brouilletarg: rs_kernel_context context 248be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletsummary: Size of the Array1 dimension for the specified context 249be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletdescription: 250be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet Returns the size of the Array1 dimension for the specified context. 251be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet See @rsGetDimX() for an explanation of the context. 252be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 253be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet Returns 0 if the Array1 dimension is not present. 254be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillettest: none 255be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletend: 256be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 257be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletfunction: rsGetDimArray2 258be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletversion: 23 259be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletret: uint32_t 2604324eec445c6882dce89a24765482293ed31914eJean-Luc Brouilletarg: rs_kernel_context context 261be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletsummary: Size of the Array2 dimension for the specified context 262be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletdescription: 263be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet Returns the size of the Array2 dimension for the specified context. 264be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet See @rsGetDimX() for an explanation of the context. 265be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 266be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet Returns 0 if the Array2 dimension is not present. 267be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillettest: none 268be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletend: 269be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 270be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletfunction: rsGetDimArray3 271be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletversion: 23 272be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletret: uint32_t 2734324eec445c6882dce89a24765482293ed31914eJean-Luc Brouilletarg: rs_kernel_context context 274be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletsummary: Size of the Array3 dimension for the specified context 275be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletdescription: 276be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet Returns the size of the Array3 dimension for the specified context. 277be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet See @rsGetDimX() for an explanation of the context. 278be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 279be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet Returns 0 if the Array3 dimension is not present. 280be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillettest: none 281be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletend: 282be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 283be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletfunction: rsGetDimHasFaces 284be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletversion: 23 285be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletret: bool, "Returns true if more than one face is present, false otherwise." 2864324eec445c6882dce89a24765482293ed31914eJean-Luc Brouilletarg: rs_kernel_context context 287be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletsummary: Presence of more than one face for the specified context 288be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletdescription: 2896386ceb3bf25e442513224aaa45691dfe49562d9Jean-Luc Brouillet If the context refers to a cubemap, this function returns true if there's more than 2906386ceb3bf25e442513224aaa45691dfe49562d9Jean-Luc Brouillet one face present. In all other cases, it returns false. See @rsGetDimX() for an 2916386ceb3bf25e442513224aaa45691dfe49562d9Jean-Luc Brouillet explanation of the context. 292be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 293be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet @rsAllocationGetDimFaces() is similar but returns 0 or 1 instead of a bool. 294be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillettest: none 295be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletend: 296be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 297be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletfunction: rsGetDimLod 298be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletversion: 23 299be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletret: uint32_t 3004324eec445c6882dce89a24765482293ed31914eJean-Luc Brouilletarg: rs_kernel_context context 301be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletsummary: Number of levels of detail for the specified context 302be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletdescription: 3036386ceb3bf25e442513224aaa45691dfe49562d9Jean-Luc Brouillet Returns the number of levels of detail for the specified context. This is useful 3046386ceb3bf25e442513224aaa45691dfe49562d9Jean-Luc Brouillet for mipmaps. See @rsGetDimX() for an explanation of the context. 3056386ceb3bf25e442513224aaa45691dfe49562d9Jean-Luc Brouillet 306be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet Returns 0 if Level of Detail is not used. 307be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 308be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet @rsAllocationGetDimLOD() is similar but returns 0 or 1 instead the actual 309be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet number of levels. 310be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillettest: none 311be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletend: 312be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 313be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletfunction: rsGetDimX 314be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletversion: 23 315be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletret: uint32_t 3164324eec445c6882dce89a24765482293ed31914eJean-Luc Brouilletarg: rs_kernel_context context 317be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletsummary: Size of the X dimension for the specified context 318be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletdescription: 319be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet Returns the size of the X dimension for the specified context. 320be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 321be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet This context is created when a kernel is launched. It contains common 322be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet characteristics of the allocations being iterated over by the kernel in 323be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet a very efficient structure. It also contains rarely used indexes. 324be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 3254324eec445c6882dce89a24765482293ed31914eJean-Luc Brouillet You can access it by adding a special parameter named "context" and of 3264324eec445c6882dce89a24765482293ed31914eJean-Luc Brouillet type rs_kernel_context to your kernel function. E.g.<br/> 327be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet <code>int4 RS_KERNEL myKernel(int4 value, rs_kernel_context context) {<br/> 328be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet uint32_t size = rsGetDimX(context); //...<br/></code> 32920b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet 33020b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet To get the dimension of specific allocation, use @rsAllocationGetDimX(). 331be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillettest: none 332be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletend: 333be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 334be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletfunction: rsGetDimY 335be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletversion: 23 336be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletret: uint32_t 3374324eec445c6882dce89a24765482293ed31914eJean-Luc Brouilletarg: rs_kernel_context context 338be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletsummary: Size of the Y dimension for the specified context 339be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletdescription: 340be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet Returns the size of the X dimension for the specified context. 341be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet See @rsGetDimX() for an explanation of the context. 342be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 343be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet Returns 0 if the Y dimension is not present. 34420b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet 34520b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet To get the dimension of specific allocation, use @rsAllocationGetDimY(). 346be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillettest: none 347be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletend: 348be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 349be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletfunction: rsGetDimZ 350be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletversion: 23 351be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletret: uint32_t 3524324eec445c6882dce89a24765482293ed31914eJean-Luc Brouilletarg: rs_kernel_context context 353be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletsummary: Size of the Z dimension for the specified context 354be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletdescription: 355be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet Returns the size of the Z dimension for the specified context. 356be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet See @rsGetDimX() for an explanation of the context. 357be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 358be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet Returns 0 if the Z dimension is not present. 35920b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet 36020b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouillet To get the dimension of specific allocation, use @rsAllocationGetDimZ(). 361be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillettest: none 362be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletend: 363be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 364be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletfunction: rsGetFace 365be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletversion: 23 366be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletret: rs_allocation_cubemap_face 3674324eec445c6882dce89a24765482293ed31914eJean-Luc Brouilletarg: rs_kernel_context context 368be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletsummary: Coordinate of the Face for the specified context 369be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletdescription: 3706386ceb3bf25e442513224aaa45691dfe49562d9Jean-Luc Brouillet Returns the face on which the cell being processed is found, as specified by the 3716386ceb3bf25e442513224aaa45691dfe49562d9Jean-Luc Brouillet supplied context. See @rsGetArray0() for an explanation of the context. 372be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 373be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet Returns RS_ALLOCATION_CUBEMAP_FACE_POSITIVE_X if the face dimension is not 374be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet present. 375be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillettest: none 376be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletend: 377be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 378be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletfunction: rsGetLod 379be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletversion: 23 380be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletret: uint32_t 3814324eec445c6882dce89a24765482293ed31914eJean-Luc Brouilletarg: rs_kernel_context context 38220b27d602a4778ed50a83df2147416a35b7c92beJean-Luc Brouilletsummary: Index in the Levels of Detail dimension for the specified context 383be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletdescription: 3846386ceb3bf25e442513224aaa45691dfe49562d9Jean-Luc Brouillet Returns the index in the Levels of Detail dimension of the cell being processed, 3856386ceb3bf25e442513224aaa45691dfe49562d9Jean-Luc Brouillet as specified by the supplied context. See @rsGetArray0() for an explanation of 3866386ceb3bf25e442513224aaa45691dfe49562d9Jean-Luc Brouillet the context. 387be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet 388be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillet Returns 0 if the Levels of Detail dimension is not present. 389be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouillettest: none 390be2163801c33d6849ae580d42b919b8803d55095Jean-Luc Brouilletend: 391