Example of a Reduction Kernel
In this example, we use an ImageReductionKernel kernel to find the mean value for each component in an image.
An ImageReductionKernel takes an image, or images, and reduces it down to a value, or values, which describe the
image(s) in some way. For example, we use an ImageReductionKernel here to find the mean value for each component
in an image, but we could also calculate other statistics such as the variance, or the minimum and maximum values,
or perhaps to count the number of non-zero values in the image.
An ImageReductionKernel needs a data structure to reduce into, with some functions defined on it which specify
how the reduction is to be performed. In the example below, we use the "addSample" function to update the
reduction data from the kernel's "process" call, but you could define your own function for the updates inside the
data structure, with any name and signature you like. However, your data structure must implement the "join"
and "finish" functions.
After the reduction kernel has been run, and all its process calls completed, the "join" function will be called in
order to combine results from different parts of the reduction, which might have been performed in parallel. "join"
takes a similar reduction data object to combine with as a parameter. Optionally, it can also take a component index,
which must then be passed in before the reduction data object.
The "finish" function is the final step, and is called on a single thread after all the results have been joined together.
"finish" doesn't have to do anything but, for the moment, it must always be defined. "finish" takes two integer arguments.
The first is the area of the iteration space the kernel was run over, so for an iteration space the same size as the
input image, this would be (image width) x (image height). The second is the number of components the kernel was run over
(for a pixel-wise kernel, this will always be 1). The "finish" function is only called once, so if you need to do something
once for each component, you should loop over the components inside your finish function, as in the example below.
\include reductionKernelExample.rpp