ClFourierTransform Class Reference

#include <ImFusion/CL/ClFourierTransform.h>

OpenCL-based Fast Fourier Transform using the ClFFT library. More...

Inheritance diagram for ClFourierTransform:

Detailed Description

OpenCL-based Fast Fourier Transform using the ClFFT library.

Based on the examples at https://github.com/clMathLibraries/clFFT/tree/master/src/examples and https://dournac.org/info/fft_gpu.

Example use:

// Assume as given.
SharedImage* img = ...;
 
// Check if the image can be transformed.
if (!ClFourierTransform::checkIfDataValid(img->img()) return;
 
ClFourierTransform fft;
 
// Set up a transformation plan using the Image descriptor. Here, no padding is added.
if (!fft.setup(img->img()) return;
 
// OPTIONALLY: Set up another plan for back transform with prefiltering on-the-fly.
// EITHER use the precallback feature and provide function string and userdata according to the following prototype.
const char* funcName = "vectorMultiply";
const char* callbackString = "float2 vectorMultiply(__global void* inputRe, \n"
    "               __global void* inputIm, \n"
    "               uint inoffset, \n"
    "               __global void* userdata) \n"
    "{\n"
    "  float mult = *((__global float*)userdata + inoffset);\n"
    "  float real = *((__global float*)inputRe  + inoffset);\n"
    "  float imag = *((__global float*)inputIm  + inoffset);\n"
    "  return (float2)(real*mult, imag*mult); }\n";
ClImage* userdata = new ClImage(ClImage::BUFFER, ClImage::READ_ONLY, Image(Image::FLOAT, datasize, 1), data, 0, 0, m_env);
if (!fft.setupFilteredRoundTransform(funcName, callbackString, userdata)) return;
 
// OR pass a ClKernel object with all arguments set except for the first and second (reserved for real and imaginary buffer).
ClKernel* kernel = program->createKernel( kernelName );
kernel->setArgument(2, ...);
if (!fft.setupFilteredRoundTransform(kernel)) return;
 
// Input data is purely real valued and of type float. Transform into desired direction (here: forward).
// Set direction to zero if the round-transform workflow should be followed.
if (!fft.transform(img->mem()->data()), 0, -1) return; // or: fft.transform(*img->mem(), 0, -1) ...
 
// Fetch real valued output.
if (void* result = fft.output(ClFourierTransform::OUTPUT_REAL))
// or (including cropping if required for image dimensions): MemImage* result = fft.output(OUTPUT_REAL, true);
   // do further processing...

Public Types
enum	OutputType { OUTPUT_REAL , OUTPUT_IMAG , OUTPUT_POWER_SPECTRUM , OUTPUT_TYPES }
	Specifies output type.

Public Member Functions
	ClFourierTransform (ClEnvironment *env=0)
	Creates a ClEnvironment singleton if not specified.
	~ClFourierTransform () override
	Releases all buffers. Eventually calls clfftTeardown().
bool	setup (const Image *descIn, const int dim=4, const double paddingPercentage=0.0, size_t *strides=nullptr, const int dist=0, const int prec=1) override
	Specify settings for a single transformation, do the setup.
bool	transform (const MemImage &imgInReal, MemImage *imgInImag, int direction=0)
	Convenience method that performs the transform with MemImage instances of arbitrary datatype.
Public Member Functions inherited from FFT
void	computeDescPadded (int dim, double paddingPercentage)
	Compute the padded image for an FFT of dimension dim. The image type will be FLOAT.
const Image *	descPadded () const
	Get the padded image descriptor. This is a nullpointer if no m_descIn has been set before.
const Image *	descIn () const
	Fetch the descriptor of the image that the FFT will be computed on. This is a nullpointer if setup() has not been called.

Static Public Member Functions
static bool	checkIfDataValid (const Image *desc, int ftDim=4)
	Static method to check for valid image dimension prior to computation.

Protected Member Functions
bool	transform (const float *dataInReal, float *dataInImag, int direction=0)
	Creates the (optionally padded) buffers from input and performs the actual transform(s).
bool	createClBuffers (const float *dataInReal, float *dataInImag)
	Creates CL buffers from input data.
const float *	createPaddedMemBuffer (const float *dataIn) const
	Centrally embeds the given data in the padded 'volume' and pads the sides accordingly.
ClImage *	computePowerSpectrum (const ClImage &bufferReal, const ClImage &bufferImag) const
	Compute power spectrum from given real and imaginary buffers.
float *	computePowerSpectrum () const
bool	setupFilteredRoundTransform (const char *funcName=0, const char *callbackString=0, ClImage *userDataBuffer=0)
	Sets up a new plan for the back transform for a combined forward and backward transform with an optional filtering step applied inbetween.
bool	setupFilteredRoundTransform (ClKernel *clKernel)
	Alternatively, a precreated clKernel instance can be passed.
bool	output (ClMemory &result, bool real) const
	Fetch the output, either as CL buffer or downloaded into memory.
float *	output (OutputType type) const
MemImage *	output (OutputType type, bool cropPadding) const
	Convenience method that optionally crops the output image to match the original image size.

Additional Inherited Members
Protected Attributes inherited from FFT
Image *	m_descIn
	Descriptor of input image, owned.
Image *	m_descPadded
	Descriptor of padded image, owned.
unsigned int	m_largestValidPrimeRank
	A specific FFT implementation can only deal with images whose dimensions are a multiple of small primes.

Member Function Documentation

setup()

bool setup ( const Image * descIn, const int dim = 4, const double paddingPercentage = 0.0, size_t * strides = nullptr, const int dist = 0, const int prec = 1 )

overridevirtual

Specify settings for a single transformation, do the setup.

The layout used for input and output buffers is CLFFT_COMPLEX_PLANAR, i.e. a block representing real values followed by a block representing imaginary values.

Parameters

dim	Dimension of transform. By default according to the input image dimension. 1=1D, 2=2D, 3=3D. If e.g. a row-wise transform of a 2D image is desired, select dim=1. Distance and batchsize are deduced accordingly. Custom strides and distance are not yet supported.
paddingPercentage	The total padded size will be larger than the original size by at least this many percents.
prec	Floating point precision, single by default. 1=single, 2=double, 3=fast single, 4=fast double

Implements FFT.

setupFilteredRoundTransform() [1/2]

bool setupFilteredRoundTransform	(	const char *	funcName = 0,
		const char *	callbackString = 0,
		ClImage *	userDataBuffer = 0 )

Sets up a new plan for the back transform for a combined forward and backward transform with an optional filtering step applied inbetween.

\warn Always call setup() before calling this method! The parameters follow the naming convention of clfftSetPlanCallback(). This method leverages the baking of a custom kernel into the back transform plan. If one or two of the string arguments are NULL, no callback will be invoked. Then, the output should exactly match the input. This is useful for testing consistency. For more information, refer to the documentation (http://clmathlibraries.github.io/clFFT/index.html#Callbacks) or this tutorial (http://developer.amd.com/community/blog/2015/10/06/clfft-pre-callback-a-faster-way-to-pre-process-data/)

Parameters

funcName	Callback function name
callbackString	Callback function in string form
userDataBuffer	Has to be of type ClImage::BUFFER if not NULL. If NULL, the 'userdata' argument must not be used in the precallback body, yet it has to be declared in the argument list.

setupFilteredRoundTransform() [2/2]

bool setupFilteredRoundTransform

(

ClKernel *

clKernel

)

Alternatively, a precreated clKernel instance can be passed.

It performs custom computation on the transformed data, i.e. in Fourier space.

Note

The first two arguments in the kernel have to be placeholders (of type 'global float*') for the real and imaginary CL buffers. They will be set accordingly in the transform() step. The starting index for setting further custom arguments to the kernel has to be 2.

Parameters

clKernel

Non-NULL and valid CL kernel instance. Otherwise the back transform is still set up but no filtering task performed.

transform() [1/2]

bool transform	(	const MemImage &	imgInReal,
		MemImage *	imgInImag,
		int	direction = 0 )

Convenience method that performs the transform with MemImage instances of arbitrary datatype.

Creates temporary float image if required.

Note

Remember to pass a reference to the real image, otherwise the function above will be called.

output() [1/2]

bool output	(	ClMemory &	result,
		bool	real ) const

Fetch the output, either as CL buffer or downloaded into memory.

Note

A ClMemory instance is passed instead of an ClImage because it has a copy assignment operator.

The output image might have a drastically different appearance depending on whether it is processed using MemImage::prepare() or not.

output() [2/2]

MemImage * output	(	OutputType	type,
		bool	cropPadding ) const

Convenience method that optionally crops the output image to match the original image size.

Returns

MemImage instance holding the transformed data.

checkIfDataValid()

static bool checkIfDataValid ( const Image * desc, int ftDim = 4 )

static

Static method to check for valid image dimension prior to computation.

Note

Only images with dimensions that are a product of powers of 2, 3, 5 and 7 are supported.

Parameters

desc	Image descriptor of input imagesets.
ftDim	Desired dimension of transform. Set to image dimension by default. Must not be larger than image dimension.

transform() [2/2]

bool transform ( const float * dataInReal, float * dataInImag, int direction = 0 )

protected

Creates the (optionally padded) buffers from input and performs the actual transform(s).

Parameters

direction	-1=forward, 1=backward. 0=forward + applying callback/ClKernel + backward Input has to be float*.
dataInReal	If NULL, a buffer filled with zeros is created.
dataInImag	If NULL, a buffer filled with zeros is created.

computePowerSpectrum()

ClImage * computePowerSpectrum ( const ClImage & bufferReal, const ClImage & bufferImag ) const

protected

Compute power spectrum from given real and imaginary buffers.

Note

Only implemented on CPU.

---

The documentation for this class was generated from the following file:

• ImFusion/CL/ClFourierTransform.h