clFFT.h File Reference

Go to the source code of this file.

Classes
struct	clfftSetupData
	Data structure that can be passed to clfftSetup() to control the behavior of the FFT runtime. More...

Macros
#define	CLFFTAPI
#define	CLFFT_DUMP_PROGRAMS   0x1

Typedefs
typedef size_t	clfftPlanHandle
	An abstract handle to the object that represents the state of the FFT(s)

Enumerations
enum	clfftStatus_ { ,   CLFFT_BUGCHECK = 4*1024,   CLFFT_NOTIMPLEMENTED,   CLFFT_TRANSPOSED_NOTIMPLEMENTED,   CLFFT_FILE_NOT_FOUND,   CLFFT_FILE_CREATE_FAILURE,   CLFFT_VERSION_MISMATCH,   CLFFT_INVALID_PLAN,   CLFFT_DEVICE_NO_DOUBLE,   CLFFT_DEVICE_MISMATCH }
	clfft error codes definition(incorporating OpenCL error definitions) More...
enum	clfftDim {   CLFFT_1D = 1,   CLFFT_2D,   CLFFT_3D,   ENDDIMENSION }
	The dimension of the input and output buffers that is fed into all FFT transforms. More...
enum	clfftLayout {   CLFFT_COMPLEX_INTERLEAVED = 1,   CLFFT_COMPLEX_PLANAR,   CLFFT_HERMITIAN_INTERLEAVED,   CLFFT_HERMITIAN_PLANAR,   CLFFT_REAL,   ENDLAYOUT }
	Specify the expected layouts of the buffers. More...
enum	clfftPrecision {   CLFFT_SINGLE = 1,   CLFFT_DOUBLE,   CLFFT_SINGLE_FAST,   CLFFT_DOUBLE_FAST,   ENDPRECISION }
	Specify the expected precision of each FFT. More...
enum	clfftDirection {   CLFFT_FORWARD = -1,   CLFFT_BACKWARD = 1,   CLFFT_MINUS = -1,   CLFFT_PLUS = 1,   ENDDIRECTION }
	Specify the expected direction of each FFT, time or the frequency domains. More...
enum	clfftResultLocation {   CLFFT_INPLACE = 1,   CLFFT_OUTOFPLACE,   ENDPLACE }
	Specify wheter the input buffers are overwritten with results. More...
enum	clfftResultTransposed {   CLFFT_NOTRANSPOSE = 1,   CLFFT_TRANSPOSED,   ENDTRANSPOSED }
	Determines whether the result is returned in original order. It is valid only for dimensions greater than 1. More...
enum	clfftCallbackType {   PRECALLBACK,   POSTCALLBACK }
	Type of Callback function. More...

Functions
__inline clfftStatus	clfftInitSetupData (clfftSetupData *setupData)
	Initialize a clfftSetupData struct for the client. More...
CLFFTAPI clfftStatus	clfftSetup (const clfftSetupData *setupData)
	Initialize the internal FFT resources. More...
CLFFTAPI clfftStatus	clfftTeardown ()
	Release all internal resources. More...
CLFFTAPI clfftStatus	clfftGetVersion (cl_uint *major, cl_uint *minor, cl_uint *patch)
	Query the FFT library for version information. More...
CLFFTAPI clfftStatus	clfftCreateDefaultPlan (clfftPlanHandle *plHandle, cl_context context, const clfftDim dim, const size_t *clLengths)
	Create a plan object initialized entirely with default values. More...
CLFFTAPI clfftStatus	clfftCopyPlan (clfftPlanHandle *out_plHandle, cl_context new_context, clfftPlanHandle in_plHandle)
	Create a copy of an existing plan. More...
CLFFTAPI clfftStatus	clfftBakePlan (clfftPlanHandle plHandle, cl_uint numQueues, cl_command_queue *commQueueFFT, void(CL_CALLBACK *pfn_notify)(clfftPlanHandle plHandle, void *user_data), void *user_data)
	Prepare the plan for execution. More...
CLFFTAPI clfftStatus	clfftDestroyPlan (clfftPlanHandle *plHandle)
	Release the resources of a plan. More...
CLFFTAPI clfftStatus	clfftGetPlanContext (const clfftPlanHandle plHandle, cl_context *context)
	Retrieve the OpenCL context of a previously created plan. More...
CLFFTAPI clfftStatus	clfftGetPlanPrecision (const clfftPlanHandle plHandle, clfftPrecision *precision)
	Retrieve the floating point precision of the FFT data. More...
CLFFTAPI clfftStatus	clfftSetPlanPrecision (clfftPlanHandle plHandle, clfftPrecision precision)
	Set the floating point precision of the FFT data. More...
CLFFTAPI clfftStatus	clfftGetPlanScale (const clfftPlanHandle plHandle, clfftDirection dir, cl_float *scale)
	Retrieve the scaling factor that is applied to the FFT data. More...
CLFFTAPI clfftStatus	clfftSetPlanScale (clfftPlanHandle plHandle, clfftDirection dir, cl_float scale)
	Set the scaling factor that is applied to the FFT data. More...
CLFFTAPI clfftStatus	clfftGetPlanBatchSize (const clfftPlanHandle plHandle, size_t *batchSize)
	Retrieve the number of discrete arrays that the plan can concurrently handle. More...
CLFFTAPI clfftStatus	clfftSetPlanBatchSize (clfftPlanHandle plHandle, size_t batchSize)
	Set the number of discrete arrays that the plan can concurrently handle. More...
CLFFTAPI clfftStatus	clfftGetPlanDim (const clfftPlanHandle plHandle, clfftDim *dim, cl_uint *size)
	Retrieve the dimensionality of the data that is transformed. More...
CLFFTAPI clfftStatus	clfftSetPlanDim (clfftPlanHandle plHandle, const clfftDim dim)
	Set the dimensionality of the data that is transformed. More...
CLFFTAPI clfftStatus	clfftGetPlanLength (const clfftPlanHandle plHandle, const clfftDim dim, size_t *clLengths)
	Retrieve the length of each dimension of the FFT. More...
CLFFTAPI clfftStatus	clfftSetPlanLength (clfftPlanHandle plHandle, const clfftDim dim, const size_t *clLengths)
	Set the length of each dimension of the FFT. More...
CLFFTAPI clfftStatus	clfftGetPlanInStride (const clfftPlanHandle plHandle, const clfftDim dim, size_t *clStrides)
	Retrieve the distance between consecutive elements of input buffers in each dimension. More...
CLFFTAPI clfftStatus	clfftSetPlanInStride (clfftPlanHandle plHandle, const clfftDim dim, size_t *clStrides)
	Set the distance between consecutive elements of input buffers in each dimension. More...
CLFFTAPI clfftStatus	clfftGetPlanOutStride (const clfftPlanHandle plHandle, const clfftDim dim, size_t *clStrides)
	Retrieve the distance between consecutive elements of output buffers in each dimension. More...
CLFFTAPI clfftStatus	clfftSetPlanOutStride (clfftPlanHandle plHandle, const clfftDim dim, size_t *clStrides)
	Set the distance between consecutive elements of output buffers in a dimension. More...
CLFFTAPI clfftStatus	clfftGetPlanDistance (const clfftPlanHandle plHandle, size_t *iDist, size_t *oDist)
	Retrieve the distance between array objects. More...
CLFFTAPI clfftStatus	clfftSetPlanDistance (clfftPlanHandle plHandle, size_t iDist, size_t oDist)
	Set the distance between array objects. More...
CLFFTAPI clfftStatus	clfftGetLayout (const clfftPlanHandle plHandle, clfftLayout *iLayout, clfftLayout *oLayout)
	Retrieve the expected layout of the input and output buffers. More...
CLFFTAPI clfftStatus	clfftSetLayout (clfftPlanHandle plHandle, clfftLayout iLayout, clfftLayout oLayout)
	Set the expected layout of the input and output buffers. More...
CLFFTAPI clfftStatus	clfftGetResultLocation (const clfftPlanHandle plHandle, clfftResultLocation *placeness)
	Retrieve whether the input buffers are to be overwritten with results. More...
CLFFTAPI clfftStatus	clfftSetResultLocation (clfftPlanHandle plHandle, clfftResultLocation placeness)
	Set whether the input buffers are to be overwritten with results. More...
CLFFTAPI clfftStatus	clfftGetPlanTransposeResult (const clfftPlanHandle plHandle, clfftResultTransposed *transposed)
	Retrieve the final transpose setting of a multi-dimensional FFT. More...
CLFFTAPI clfftStatus	clfftSetPlanTransposeResult (clfftPlanHandle plHandle, clfftResultTransposed transposed)
	Set the final transpose setting of a multi-dimensional FFT. More...
CLFFTAPI clfftStatus	clfftGetTmpBufSize (const clfftPlanHandle plHandle, size_t *buffersize)
	Get buffer size (in bytes), which may be needed internally for an intermediate buffer. More...
CLFFTAPI clfftStatus	clfftSetPlanCallback (clfftPlanHandle plHandle, const char *funcName, const char *funcString, int localMemSize, clfftCallbackType callbackType, cl_mem *userdata, int numUserdataBuffers)
	Register the callback parameters. More...
CLFFTAPI clfftStatus	clfftEnqueueTransform (clfftPlanHandle plHandle, clfftDirection dir, cl_uint numQueuesAndEvents, cl_command_queue *commQueues, cl_uint numWaitEvents, const cl_event *waitEvents, cl_event *outEvents, cl_mem *inputBuffers, cl_mem *outputBuffers, cl_mem tmpBuffer)
	Enqueue an FFT transform operation, and return immediately (non-blocking) More...

Detailed Description

clFFT.h defines all the public interfaces and types that are used by clFFT clients This is the only public header file that should be consumed by clFFT clients. It is written to adhere to native "C" interfaces to make clFFT library as portable as possible; it should be callable from C, C++, .NET and Fortran, either with the proper linking or using wrapper classes.

Macro Definition Documentation

#define CLFFT_DUMP_PROGRAMS   0x1

BitMasks to be used with clfftSetupData.debugFlags

#define CLFFTAPI

This preprocessor definition is the standard way to export APIs from a DLL simpler. All files within this DLL are compiled with the CLFFT_EXPORTS symbol defined on the command line. This symbol must not be defined on any project that uses this DLL. This ensures source files of any other project that include this file see clfft functions as being imported from a DLL, whereas the DLL sees symbols defined with this macro as being exported.

Enumeration Type Documentation

enum clfftCallbackType

Type of Callback function.

Enumerator
PRECALLBACK	Callback function is invoked only once for every point of input at the beginning of FFT transform.
POSTCALLBACK	Callback function is invoked only once for every point of output at the end of FFT transform.

enum clfftDim

The dimension of the input and output buffers that is fed into all FFT transforms.

Enumerator
CLFFT_1D	1 Dimensional FFT transform (default).
CLFFT_2D	2 Dimensional FFT transform.
CLFFT_3D	3 Dimensional FFT transform.
ENDDIMENSION	The last value of the enum, and marks the length of clfftDim.

enum clfftDirection

Specify the expected direction of each FFT, time or the frequency domains.

Enumerator
CLFFT_FORWARD	FFT transform from time to frequency domain.
CLFFT_BACKWARD	FFT transform from frequency to time domain.
CLFFT_MINUS	Alias for the forward transform.
CLFFT_PLUS	Alias for the backward transform.
ENDDIRECTION	The last value of the enum, and marks the length of clfftDirection.

enum clfftLayout

Specify the expected layouts of the buffers.

Enumerator
CLFFT_COMPLEX_INTERLEAVED	An array of complex numbers, with real and imaginary components together (default).
CLFFT_COMPLEX_PLANAR	Separate arrays of real components and imaginary components.
CLFFT_HERMITIAN_INTERLEAVED	Compressed form of complex numbers; complex-conjugates are not stored, real and imaginary components are stored in the same array.
CLFFT_HERMITIAN_PLANAR	Compressed form of complex numbers; complex-conjugates are not stored, real and imaginary components are stored in separate arrays.
CLFFT_REAL	An array of real numbers, with no corresponding imaginary components.
ENDLAYOUT	The last value of the enum, and marks the length of clfftLayout.

enum clfftPrecision

Specify the expected precision of each FFT.

Enumerator
CLFFT_SINGLE	An array of complex numbers, with real and imaginary components saved as floats (default).
CLFFT_DOUBLE	An array of complex numbers, with real and imaginary components saved as doubles.
CLFFT_SINGLE_FAST	Faster implementation preferred.
CLFFT_DOUBLE_FAST	Faster implementation preferred.
ENDPRECISION	The last value of the enum, and marks the length of clfftPrecision.

enum clfftResultLocation

Specify wheter the input buffers are overwritten with results.

Enumerator
CLFFT_INPLACE	Input and output buffers are the same (default).
CLFFT_OUTOFPLACE	Input and output buffers are separate.
ENDPLACE	The last value of the enum, and marks the length of clfftPlaceness.

enum clfftResultTransposed

Determines whether the result is returned in original order. It is valid only for dimensions greater than 1.

Enumerator
CLFFT_NOTRANSPOSE	The result is returned in the original order (default)
CLFFT_TRANSPOSED	The result is transposed where transpose kernel is supported (possibly faster)
ENDTRANSPOSED	The last value of the enum, and marks the length of clfftResultTransposed

enum clfftStatus_

clfft error codes definition(incorporating OpenCL error definitions)

This enumeration is a superset of the OpenCL error codes. For example, CL_OUT_OF_HOST_MEMORY, which is defined in cl.h is aliased as CLFFT_OUT_OF_HOST_MEMORY. The set of basic OpenCL error codes is extended to add extra values specific to the clfft package.

Enumerator
CLFFT_BUGCHECK	Bugcheck.
CLFFT_NOTIMPLEMENTED	Functionality is not implemented yet.
CLFFT_TRANSPOSED_NOTIMPLEMENTED	Transposed functionality is not implemented for this transformation.
CLFFT_FILE_NOT_FOUND	Tried to open an existing file on the host system, but failed.
CLFFT_FILE_CREATE_FAILURE	Tried to create a file on the host system, but failed.
CLFFT_VERSION_MISMATCH	Version conflict between client and library.
CLFFT_INVALID_PLAN	Requested plan could not be found.
CLFFT_DEVICE_NO_DOUBLE	Double precision not supported on this device.
CLFFT_DEVICE_MISMATCH	Attempt to run on a device using a plan baked for a different device.

Function Documentation

CLFFTAPI clfftStatus clfftBakePlan	(	clfftPlanHandle	plHandle,
		cl_uint	numQueues,
		cl_command_queue *	commQueueFFT,
		void(CL_CALLBACK *pfn_notify)(clfftPlanHandle plHandle, void *user_data)	,
		void *	user_data
	)

Prepare the plan for execution.

After all plan parameters are set, the client has the option of 'baking' the plan, which informs the runtime that no more change to the parameters of the plan is expected, and the OpenCL kernels can be compiled. This optional function allows the client application to perform the OpenCL kernel compilation when the application is initialized instead of during the first execution. At this point, the clfft runtime applies all implimented optimizations, including running kernel experiments on the devices in the plan context.

This function takes a long time to execute. If a plan is not baked before being executed, the first call to clfftEnqueueTransform takes a long time to execute.

If any significant parameter of a plan is changed after the plan is baked (by a subsequent call to any one of the functions that has the prefix "clfftSetPlan"), it is not considered an error. Instead, the plan reverts back to the unbaked state, discarding the benefits of the baking operation.

Parameters

[in]	plHandle	Handle to a previously created plan
[in]	numQueues	Number of command queues in commQueueFFT; 0 is a valid value, in which case the client does not want the runtime to run load experiments and only pre-calculate state information
[in]	commQueueFFT	An array of cl_command_queues created by the client; the command queues must be a proper subset of the devices included in the plan context
[in]	pfn_notify	A function pointer to a notification routine. The notification routine is a callback function that an application can register and is called when the program executable is built (successfully or unsuccessfully). Currently, this parameter MUST be NULL or nullptr.
[in]	user_data	Passed as an argument when pfn_notify is called. Currently, this parameter MUST be NULL or nullptr.

Returns

Enum describing error condition; superset of OpenCL error codes

CLFFTAPI clfftStatus clfftCopyPlan	(	clfftPlanHandle *	out_plHandle,
		cl_context	new_context,
		clfftPlanHandle	in_plHandle
	)

Create a copy of an existing plan.

This API allows a client to create a new plan based upon an existing plan. This function can be used to quickly create plans that are similar, but may differ slightly.

Parameters

[out]	out_plHandle	Handle to the newly created plan that is based on in_plHandle
[in]	new_context	Client is responsible for providing a new context for the new plan
[in]	in_plHandle	Handle to a previously created plan that is to be copied

Returns

Enum describing error condition; superset of OpenCL error codes

CLFFTAPI clfftStatus clfftCreateDefaultPlan	(	clfftPlanHandle *	plHandle,
		cl_context	context,
		const clfftDim	dim,
		const size_t *	clLengths
	)

Create a plan object initialized entirely with default values.

A plan is a repository of state for calculating FFT's. Allows the runtime to pre-calculate kernels, programs and buffers and associate them with buffers of specified dimensions.

Parameters

[out]	plHandle	Handle to the newly created plan
[in]	context	Client is responsible for providing an OpenCL context for the plan
[in]	dim	Dimensionality of the FFT transform; describes how many elements are in the array
[in]	clLengths	An array of length of size 'dim'; each array value describes the length of each dimension

Returns

Enum describing error condition; superset of OpenCL error codes

CLFFTAPI clfftStatus clfftDestroyPlan

(

clfftPlanHandle *

plHandle

)

Release the resources of a plan.

A plan may include resources, such as kernels, programs, and buffers that consume memory. When a plan is no more needed, the client must release the plan.

Parameters

[in,out]

plHandle

Handle to a previously created plan

Returns

Enum describing error condition; superset of OpenCL error codes

CLFFTAPI clfftStatus clfftEnqueueTransform	(	clfftPlanHandle	plHandle,
		clfftDirection	dir,
		cl_uint	numQueuesAndEvents,
		cl_command_queue *	commQueues,
		cl_uint	numWaitEvents,
		const cl_event *	waitEvents,
		cl_event *	outEvents,
		cl_mem *	inputBuffers,
		cl_mem *	outputBuffers,
		cl_mem	tmpBuffer
	)

Enqueue an FFT transform operation, and return immediately (non-blocking)

This transform API function computes the FFT transform. It is non-blocking as it only enqueues the OpenCL kernels for execution. The synchronization step must be managed by the user.

Parameters

[in]	plHandle	Handle to a previously created plan
[in]	dir	Forward or backward transform
[in]	numQueuesAndEvents	Number of command queues in commQueues; number of expected events to be returned in outEvents
[in]	commQueues	An array of cl_command_queues created by the client; the command queues must be a proper subset of the devices included in the OpenCL context associated with the plan
[in]	numWaitEvents	Specify the number of elements in the eventWaitList array
[in]	waitEvents	Events for which the transform waits to complete before executing on the device
[out]	outEvents	The runtime fills this array with events corresponding one to one with the input command queues passed in commQueues. This parameter can have the value NULL or nullptr. When the value is NULL, the client is not interested in receiving notifications when transforms are finished, otherwise, (if not NULL) the client is responsible for allocating this array with at least as many elements as specified in numQueuesAndEvents.
[in]	inputBuffers	An array of cl_mem objects that contain data for processing by the FFT runtime. If the transform is in-place, the FFT results overwrite the input buffers
[out]	outputBuffers	An array of cl_mem objects that store the results of out-of-place transforms. If the transform is in-place, this parameter may be NULL or nullptr and is completely ignored
[in]	tmpBuffer	A cl_mem object that is reserved as a temporary buffer for FFT processing. If clTmpBuffers is NULL or nullptr, and the library needs temporary storage, an internal temporary buffer is created on the fly managed by the library.

Returns

Enum describing error condition; superset of OpenCL error codes

CLFFTAPI clfftStatus clfftGetLayout	(	const clfftPlanHandle	plHandle,
		clfftLayout *	iLayout,
		clfftLayout *	oLayout
	)

Retrieve the expected layout of the input and output buffers.

Input and output buffers can be filled with either Hermitian, complex, or real numbers. Complex numbers are stored in various layouts; this function retrieves the layouts used by input and output

Parameters

[in]	plHandle	Handle to a previously created plan
[out]	iLayout	Indicates how the input buffers are laid out in memory
[out]	oLayout	Indicates how the output buffers are laid out in memory

CLFFTAPI clfftStatus clfftGetPlanBatchSize	(	const clfftPlanHandle	plHandle,
		size_t *	batchSize
	)

Retrieve the number of discrete arrays that the plan can concurrently handle.

The user must pass a reference to a cl_uint variable, which is set to the number of discrete arrays (1D or 2D) that is batched together for the plan

Parameters

[in]	plHandle	Handle to a previously created plan
[out]	batchSize	Number of discrete FFTs performed

Returns

Enum describing error condition; superset of OpenCL error codes

CLFFTAPI clfftStatus clfftGetPlanContext	(	const clfftPlanHandle	plHandle,
		cl_context *	context
	)

Retrieve the OpenCL context of a previously created plan.

The user must pass a reference to a cl_context variable, which is modified to point to a context set in the specified plan.

Parameters

[in]	plHandle	Handle to a previously created plan
[out]	context	Reference to the user allocated cl_context, which points to context set in the plan

Returns

Enum describing error condition; superset of OpenCL error codes

CLFFTAPI clfftStatus clfftGetPlanDim	(	const clfftPlanHandle	plHandle,
		clfftDim *	dim,
		cl_uint *	size
	)

Retrieve the dimensionality of the data that is transformed.

Queries a plan object and retrieves the value of the dimensionality that the plan is set for. A size is returned to help the client allocate sufficient storage to hold the dimensions in a further call to clfftGetPlanLength

Parameters

[in]	plHandle	Handle to a previously created plan
[out]	dim	The dimensionality of the FFT to be transformed
[out]	size	Value to allocate an array to hold the FFT dimensions.

Returns

Enum describing error condition; superset of OpenCL error codes

CLFFTAPI clfftStatus clfftGetPlanDistance	(	const clfftPlanHandle	plHandle,
		size_t *	iDist,
		size_t *	oDist
	)

Retrieve the distance between array objects.

Pitch is the distance between each discrete array object in an FFT array. This is only used for 'array' dimensions in clfftDim; see clfftSetPlanDimension (units are in terms of clfftPrecision)

Parameters

[in]	plHandle	Handle to a previously created plan
[out]	iDist	The distance between the beginning elements of the discrete array objects in input buffer. For contiguous arrays in memory, iDist=(strideX*strideY*strideZ)
[out]	oDist	The distance between the beginning elements of the discrete array objects in output buffer. For contiguous arrays in memory, oDist=(strideX*strideY*strideZ)

CLFFTAPI clfftStatus clfftGetPlanInStride	(	const clfftPlanHandle	plHandle,
		const clfftDim	dim,
		size_t *	clStrides
	)

Retrieve the distance between consecutive elements of input buffers in each dimension.

Depending on how the dimension is set in the plan (for 2D or 3D FFT), strideY or strideZ can be safely ignored

Parameters

[in]	plHandle	Handle to a previously created plan
[in]	dim	The dimension of the stride parameters; provides the number of elements in the array
[out]	clStrides	An array of strides, of size 'dim'.

CLFFTAPI clfftStatus clfftGetPlanLength	(	const clfftPlanHandle	plHandle,
		const clfftDim	dim,
		size_t *	clLengths
	)

Retrieve the length of each dimension of the FFT.

The user must pass a reference to a size_t array, which is set to the length of each discrete dimension of the FFT

Parameters

[in]	plHandle	Handle to a previously created plan
[in]	dim	Dimension of the FFT; describes how many elements are in the clLengths array
[out]	clLengths	An array of length of size 'dim'; each array value describes the length of each dimension

Returns

Enum describing error condition; superset of OpenCL error codes

CLFFTAPI clfftStatus clfftGetPlanOutStride	(	const clfftPlanHandle	plHandle,
		const clfftDim	dim,
		size_t *	clStrides
	)

Retrieve the distance between consecutive elements of output buffers in each dimension.

Depending on how the dimension is set in the plan (for 2D or 3D FFT), strideY or strideZ can be safely ignored

Parameters

[in]	plHandle	Handle to a previously created plan
[in]	dim	The dimension of the stride parameters; provides the number of elements in the clStrides array
[out]	clStrides	An array of strides, of size 'dim'.

CLFFTAPI clfftStatus clfftGetPlanPrecision	(	const clfftPlanHandle	plHandle,
		clfftPrecision *	precision
	)

Retrieve the floating point precision of the FFT data.

The user must pass a reference to a clfftPrecision variable, which is set to the precision of the FFT complex data in the plan.

Parameters

[in]	plHandle	Handle to a previously created plan
[out]	precision	Reference to the user clfftPrecision enum

Returns

Enum describing error condition; superset of OpenCL error codes

CLFFTAPI clfftStatus clfftGetPlanScale	(	const clfftPlanHandle	plHandle,
		clfftDirection	dir,
		cl_float *	scale
	)

Retrieve the scaling factor that is applied to the FFT data.

The user must pass a reference to a cl_float variable, which is set to the floating point scaling factor that is multiplied across the FFT data.

Parameters

[in]	plHandle	Handle to a previously created plan
[in]	dir	Direction of the applied scaling factor
[out]	scale	Reference to the user cl_float variable

Returns

Enum describing error condition; superset of OpenCL error codes

CLFFTAPI clfftStatus clfftGetPlanTransposeResult	(	const clfftPlanHandle	plHandle,
		clfftResultTransposed *	transposed
	)

Retrieve the final transpose setting of a multi-dimensional FFT.

A multi-dimensional FFT transposes the data several times during calculation. If the client does not care about the final transpose, to put data back in proper dimension, the final transpose can be skipped to improve speed

Parameters

[in]	plHandle	Handle to a previously created plan
[out]	transposed	Specifies whether the final transpose can be skipped

CLFFTAPI clfftStatus clfftGetResultLocation	(	const clfftPlanHandle	plHandle,
		clfftResultLocation *	placeness
	)

Retrieve whether the input buffers are to be overwritten with results.

If the setting performs an in-place transform, the input buffers are overwritten with the results of the transform. If the setting performs an out-of-place transforms, the library looks for separate output buffers on the Enqueue call.

Parameters

[in]	plHandle	Handle to a previously created plan
[out]	placeness	Informs the library to either overwrite the input buffers with results or to write them in separate output buffers

CLFFTAPI clfftStatus clfftGetTmpBufSize	(	const clfftPlanHandle	plHandle,
		size_t *	buffersize
	)

Get buffer size (in bytes), which may be needed internally for an intermediate buffer.

Very large FFT transforms may need multiple passes, and the operation needs a temporary buffer to hold intermediate results. This function is only valid after the plan is baked, otherwise, an invalid operation error is returned. If the returned buffersize is 0, the runtime needs no temporary buffer.

Parameters

[in]	plHandle	Handle to a previously created plan
[out]	buffersize	Size in bytes for intermediate buffer

CLFFTAPI clfftStatus clfftGetVersion	(	cl_uint *	major,
		cl_uint *	minor,
		cl_uint *	patch
	)

Query the FFT library for version information.

Returns the major, minor and patch version numbers associated with the FFT library

Parameters

[out]	major	Major functionality change
[out]	minor	Minor functionality change
[out]	patch	Bug fixes, documentation changes, no new features introduced

Returns

Enum describing error condition; superset of OpenCL error codes

__inline clfftStatus clfftInitSetupData

(

clfftSetupData *

setupData

)

Initialize a clfftSetupData struct for the client.

clfftSetupData is passed to clfftSetup to control behavior of the FFT runtime.

Parameters

[out]

setupData

Data structure is cleared and initialized with version information and default values

Returns

Enum describes the error condition; superset of OpenCL error codes

CLFFTAPI clfftStatus clfftSetLayout	(	clfftPlanHandle	plHandle,
		clfftLayout	iLayout,
		clfftLayout	oLayout
	)

Set the expected layout of the input and output buffers.

Input and output buffers can be filled with either Hermitian, complex, or real numbers. Complex numbers can be stored in various layouts; this function informs the library what layouts to use for input and output

Parameters

[in]	plHandle	Handle to a previously created plan
[in]	iLayout	Indicates how the input buffers are laid out in memory
[in]	oLayout	Indicates how the output buffers are laid out in memory

CLFFTAPI clfftStatus clfftSetPlanBatchSize	(	clfftPlanHandle	plHandle,
		size_t	batchSize
	)

Set the number of discrete arrays that the plan can concurrently handle.

Sets the plan property which sets the number of discrete arrays (1D or 2D) that is batched together for the plan

Parameters

[in]	plHandle	Handle to a previously created plan
[in]	batchSize	Number of discrete FFTs performed

Returns

Enum describing error condition; superset of OpenCL error codes

CLFFTAPI clfftStatus clfftSetPlanCallback	(	clfftPlanHandle	plHandle,
		const char *	funcName,
		const char *	funcString,
		int	localMemSize,
		clfftCallbackType	callbackType,
		cl_mem *	userdata,
		int	numUserdataBuffers
	)

Register the callback parameters.

Client can provide a callback function to do custom processing while reading input data and/or writing output data. The callback function is provided as a string. clFFT library incorporates the callback function string into the main FFT kernel. This function is used by client to set the necessary parameters for callback

Parameters

[in]	plHandle	Handle to a previously created plan
[in]	funcName	Callback function name
[in]	funcString	Callback function in string form
[in]	localMemSize	Optional - Size (bytes) of the local memory used by callback function; pass 0 if no local memory is used
[in]	callbackType	Type of callback - Pre-Callback or Post-Callback
[in]	userdata	Supplementary data if any used by callback function
[in]	numUserdataBuffers	Number of userdata buffers

CLFFTAPI clfftStatus clfftSetPlanDim	(	clfftPlanHandle	plHandle,
		const clfftDim	dim
	)

Set the dimensionality of the data that is transformed.

Set the dimensionality of the data that is transformed by the plan

Parameters

[in]	plHandle	Handle to a previously created plan
[in]	dim	The dimensionality of the FFT to be transformed

Returns

Enum describing error condition; superset of OpenCL error codes

CLFFTAPI clfftStatus clfftSetPlanDistance	(	clfftPlanHandle	plHandle,
		size_t	iDist,
		size_t	oDist
	)

Set the distance between array objects.

Pitch is the distance between each discrete array object in an FFT array. This is only used for 'array' dimensions in clfftDim; see clfftSetPlanDimension (units are in terms of clfftPrecision)

Parameters

[in]	plHandle	Handle to a previously created plan
[out]	iDist	The distance between the beginning elements of the discrete array objects in input buffer. For contiguous arrays in memory, iDist=(strideX*strideY*strideZ)
[out]	oDist	The distance between the beginning elements of the discrete array objects in output buffer. For contiguous arrays in memory, oDist=(strideX*strideY*strideZ)

CLFFTAPI clfftStatus clfftSetPlanInStride	(	clfftPlanHandle	plHandle,
		const clfftDim	dim,
		size_t *	clStrides
	)

Set the distance between consecutive elements of input buffers in each dimension.

Set the plan properties which is the distance between elements in all dimensions of the input buffer (units are in terms of clfftPrecision)

Parameters

[in]	plHandle	Handle to a previously created plan
[in]	dim	The dimension of the stride parameters; provides the number of elements in the clStrides array
[in]	clStrides	An array of strides of size 'dim'. Usually, strideX=1 so that successive elements in the first dimension are stored contiguously. Typically, strideY=LenX and strideZ=LenX*LenY with the successive elements in the second and third dimensions stored in packed format. See Strides and Distances for details.

CLFFTAPI clfftStatus clfftSetPlanLength	(	clfftPlanHandle	plHandle,
		const clfftDim	dim,
		const size_t *	clLengths
	)

Set the length of each dimension of the FFT.

Sets the plan property which is the length of each discrete dimension of the FFT

Parameters

[in]	plHandle	Handle to a previously created plan
[in]	dim	The dimension of the FFT; describes how many elements are in the clLengths array
[in]	clLengths	An array of length of size 'dim'; each array value describes the length of each dimension

Returns

Enum describing error condition; superset of OpenCL error codes

CLFFTAPI clfftStatus clfftSetPlanOutStride	(	clfftPlanHandle	plHandle,
		const clfftDim	dim,
		size_t *	clStrides
	)

Set the distance between consecutive elements of output buffers in a dimension.

Sets the plan properties which is the distance between elements in all dimensions of the output buffer (units are in terms of clfftPrecision)

Parameters

[in]	plHandle	Handle to a previously created plan
[in]	dim	The dimension of the stride parameters; provides the number of elements in the clStrides array
[in]	clStrides	An array of strides of size 'dim'. Usually, strideX=1 so that successive elements in the first dimension are stored contiguously. Typically, strideY=LenX and strideZ=LenX*LenY cause the successive elements in the second and third dimensions be stored in packed format.

See also

clfftSetPlanInStride

CLFFTAPI clfftStatus clfftSetPlanPrecision	(	clfftPlanHandle	plHandle,
		clfftPrecision	precision
	)

Set the floating point precision of the FFT data.

Sets the floating point precision of the FFT complex data in the plan.

Parameters

[in]	plHandle	Handle to a previously created plan
[in]	precision	Reference to the user clfftPrecision enum

Returns

Enum describing error condition; superset of OpenCL error codes

CLFFTAPI clfftStatus clfftSetPlanScale	(	clfftPlanHandle	plHandle,
		clfftDirection	dir,
		cl_float	scale
	)

Set the scaling factor that is applied to the FFT data.

Sets the floating point scaling factor that is multiplied across the FFT data.

Parameters

[in]	plHandle	Handle to a previously created plan
[in]	dir	Direction of the applied scaling factor
[in]	scale	Reference to the user cl_float variable

Returns

Enum describing error condition; superset of OpenCL error codes

CLFFTAPI clfftStatus clfftSetPlanTransposeResult	(	clfftPlanHandle	plHandle,
		clfftResultTransposed	transposed
	)

Set the final transpose setting of a multi-dimensional FFT.

A multi-dimensional FFT transposes the data several times during calculation. If the client does not care about the final transpose, to put data back in proper dimension, the final transpose can be skipped to improve speed

Parameters

[in]	plHandle	Handle to a previously created plan
[in]	transposed	Specifies whether the final transpose can be skipped

CLFFTAPI clfftStatus clfftSetResultLocation	(	clfftPlanHandle	plHandle,
		clfftResultLocation	placeness
	)

Set whether the input buffers are to be overwritten with results.

If the setting performs an in-place transform, the input buffers are overwritten with the results of the transform. If the setting performs an out-of-place transforms, the library looks for separate output buffers on the Enqueue call.

Parameters

[in]	plHandle	Handle to a previously created plan
[in]	placeness	Informs the library to either overwrite the input buffers with results or to write them in separate output buffers

CLFFTAPI clfftStatus clfftSetup

(

const clfftSetupData *

setupData

)

Initialize the internal FFT resources.

The internal resources include FFT implementation caches kernels, programs, and buffers.

Parameters

[in]

setupData

Data structure that is passed into the setup routine to control FFT generation behavior and debug functionality

Returns

Enum describing error condition; superset of OpenCL error codes

CLFFTAPI clfftStatus clfftTeardown

(

)

Release all internal resources.

Called when client is done with the FFT library, allowing the library to destroy all resources it has cached

Returns

Enum describing error condition; superset of OpenCL error codes