clFFT  2.0
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 will be fed into all FFT transforms. More...
 
enum  clfftLayout {
  CLFFT_COMPLEX_INTERLEAVED = 1,
  CLFFT_COMPLEX_PLANAR,
  CLFFT_HERMITIAN_INTERLEAVED,
  CLFFT_HERMITIAN_PLANAR,
  CLFFT_REAL,
  ENDLAYOUT
}
 These are the expected layouts of the buffers. More...
 
enum  clfftPrecision {
  CLFFT_SINGLE = 1,
  CLFFT_DOUBLE,
  CLFFT_SINGLE_FAST,
  CLFFT_DOUBLE_FAST,
  ENDPRECISION
}
 This is the expected precision of each FFT. More...
 
enum  clfftDirection {
  CLFFT_FORWARD = -1,
  CLFFT_BACKWARD = 1,
  CLFFT_MINUS = -1,
  CLFFT_PLUS = 1,
  ENDDIRECTION
}
 What is the expected direction of each FFT, time or the frequency domains. More...
 
enum  clfftResultLocation {
  CLFFT_INPLACE = 1,
  CLFFT_OUTOFPLACE,
  ENDPLACE
}
 Are the input buffers overwritten with the results. More...
 
enum  clfftResultTransposed {
  CLFFT_NOTRANSPOSE = 1,
  CLFFT_TRANSPOSED,
  ENDTRANSPOSED
}
 This determines whether the result is returned in original order. It is valid only for dimensions greater than 1. More...
 

Functions

__inline clfftStatus clfftInitSetupData (clfftSetupData *setupData)
 Initialize an clfftSetupData struct for the client. More...
 
CLFFTAPI clfftStatus clfftSetup (const clfftSetupData *setupData)
 Initialize 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 should be applied to the FFT data. More...
 
CLFFTAPI clfftStatus clfftSetPlanScale (clfftPlanHandle plHandle, clfftDirection dir, cl_float scale)
 Set the scaling factor that should be applied to the FFT data. More...
 
CLFFTAPI clfftStatus clfftGetPlanBatchSize (const clfftPlanHandle plHandle, size_t *batchSize)
 Retrieve the number of discrete arrays that this plan can handle concurrently. More...
 
CLFFTAPI clfftStatus clfftSetPlanBatchSize (clfftPlanHandle plHandle, size_t batchSize)
 Set the number of discrete arrays that this plan can handle concurrently. More...
 
CLFFTAPI clfftStatus clfftGetPlanDim (const clfftPlanHandle plHandle, clfftDim *dim, cl_uint *size)
 Retrieve the dimensionality of FFT's to be transformed in the plan. More...
 
CLFFTAPI clfftStatus clfftSetPlanDim (clfftPlanHandle plHandle, const clfftDim dim)
 Set the dimensionality of FFT's to be transformed by the plan. 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 for input buffers in a dimension. More...
 
CLFFTAPI clfftStatus clfftSetPlanInStride (clfftPlanHandle plHandle, const clfftDim dim, size_t *clStrides)
 Set the distance between consecutive elements for input buffers in a dimension. More...
 
CLFFTAPI clfftStatus clfftGetPlanOutStride (const clfftPlanHandle plHandle, const clfftDim dim, size_t *clStrides)
 Retrieve the distance between consecutive elements for output buffers in a dimension. More...
 
CLFFTAPI clfftStatus clfftSetPlanOutStride (clfftPlanHandle plHandle, const clfftDim dim, size_t *clStrides)
 Set the distance between consecutive elements for 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 going to be overwritten with results. More...
 
CLFFTAPI clfftStatus clfftSetResultLocation (clfftPlanHandle plHandle, clfftResultLocation placeness)
 Set whether the input buffers are going to be overwritten with results. More...
 
CLFFTAPI clfftStatus clfftGetPlanTransposeResult (const clfftPlanHandle plHandle, clfftResultTransposed *transposed)
 Retrieve the final transpose setting of a muti-dimensional FFT. More...
 
CLFFTAPI clfftStatus clfftSetPlanTransposeResult (clfftPlanHandle plHandle, clfftResultTransposed transposed)
 Set the final transpose setting of a muti-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 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 of the public interfaces and types that are meant to be used by clFFT clients This is the one 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 of making exporting APIs from a DLL simpler. All files within this DLL are compiled with the CLFFT_EXPORTS symbol defined on the command line. This symbol should not be defined on any project that uses this DLL. This way any other project whose source files include this file see clfft functions as being imported from a DLL, whereas this DLL sees symbols defined with this macro as being exported.

Enumeration Type Documentation

enum clfftDim

The dimension of the input and output buffers that will be 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 

This value will always be last, and marks the length of clfftDim.

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

Enumerator
CLFFT_FORWARD 

FFT transform from the time to the frequency domain.

CLFFT_BACKWARD 

FFT transform from the frequency to the time domain.

CLFFT_MINUS 

Alias for the forward transform.

CLFFT_PLUS 

Alias for the backward transform.

ENDDIRECTION 

This value will always be last, and marks the length of clfftDirection.

These are 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 

Arrays of real componets and arrays of imaginary components that have been seperated out.

CLFFT_HERMITIAN_INTERLEAVED 

Compressed form of complex numbers; complex-conjugates not stored, real and imaginary components in same array.

CLFFT_HERMITIAN_PLANAR 

Compressed form of complex numbers; complex-conjugates not stored, real and imaginary components in separate arrays.

CLFFT_REAL 

An array of real numbers, with no corresponding imaginary components.

ENDLAYOUT 

This value will always be last, and marks the length of clfftLayout.

This is the expected precision of each FFT.

Enumerator
CLFFT_SINGLE 

An array of complex numbers, with real and imaginary components as floats (default).

CLFFT_DOUBLE 

An array of complex numbers, with real and imaginary components as doubles.

CLFFT_SINGLE_FAST 

Faster implementation preferred.

CLFFT_DOUBLE_FAST 

Faster implementation preferred.

ENDPRECISION 

This value will always be last, and marks the length of clfftPrecision.

Are the input buffers overwritten with the results.

Enumerator
CLFFT_INPLACE 

The input and output buffers are the same (default).

CLFFT_OUTOFPLACE 

Seperate input and output buffers.

ENDPLACE 

This value will always be last, and marks the length of clfftPlaceness.

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

Enumerator
CLFFT_NOTRANSPOSE 

The results are returned in the original preserved order (default)

CLFFT_TRANSPOSED 

The result is transposed where transpose kernel is supported (possibly faster)

ENDTRANSPOSED 

This value will always be last, and marks the length of clfftResultTransposed

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 tells the runtime that no more changes to the plan's parameters are expected, and the OpenCL kernels should be compiled. This optional function allows the client application to perform this function when the application is being initialized instead of on the first execution. At this point, the clfft runtime will apply all implimented optimizations, possibly including running kernel experiments on the devices in the plan context.

Users should assume that this function will take a long time to execute. If a plan is not baked before being executed, users should assume that the first call to clfftEnqueueTransform will take a long time to execute.

If any significant parameter of a plan is changed after the plan is baked (by a subsequent call to one of the clfftSetPlan____ functions), that will not be considered an error. Instead, the plan will revert back to the unbaked state, discarding the benefits of the baking operation.

Parameters
[in]plHandleHandle to a plan previously created
[in]numQueuesNumber of command queues in commQueueFFT; 0 is a valid value, in which case client does not want the runtime to run load experiments and only pre-calculate state information
[in]commQueueFFTAn 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_notifyA function pointer to a notification routine. The notification routine is a callback function that an application can register and which will be called when the program executable has been built (successfully or unsuccessfully). Currently, this parameter MUST be NULL or nullptr.
[in]user_dataPassed 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 is a convenience function provided for quickly creating plans that are similar, but may differ slightly.

Parameters
[out]out_plHandleHandle to the newly created plan that is based on in_plHandle
[in]new_contextClient is responsible for providing a new context for the new plan
[in]in_plHandleHandle to a plan to be copied, previously created
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]plHandleHandle to the newly created plan
[in]contextClient is responsible for providing an OpenCL context for the plan
[in]dimThe dimensionality of the FFT transform; describes how many elements are in the array
[in]clLengthsAn array of lengths, of size 'dim'. Each value describes the length of additional dimensions
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 kernels, programs and buffers associated with it that consume memory. When a plan is not needed anymore, the client should release the plan.

Parameters
[in,out]plHandleHandle to a plan previously created
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 is the function that actually computes the FFT transfrom. It is non-blocking as it only enqueues the OpenCL kernels for execution. The synchronization step has to be managed by the user.

Parameters
[in]plHandleHandle to a plan previously created
[in]dirForwards or backwards transform
[in]numQueuesAndEventsNumber of command queues in commQueues; number of expected events to be returned in outEvents
[in]commQueuesAn 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]numWaitEventsSpecify the number of elements in the eventWaitList array
[in]waitEventsEvents that this transform should wait to complete before executing on the device
[out]outEventsThe runtime fills this array with events corresponding 1 to 1 with the input command queues passed in commQueues. This parameter can be NULL or nullptr, in which case 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]inputBuffersAn array of cl_mem objects that contain data for processing by the FFT runtime. If the transform is in place, the FFT results will overwrite the input buffers
[out]outputBuffersAn array of cl_mem objects that will store the results of out of place transforms. If the transform is in place, this parameter may be NULL or nullptr. It is completely ignored
[in]tmpBufferA cl_mem object that is reserved as a temporary buffer for FFT processing. If clTmpBuffers is NULL or nullptr, and the runtime needs temporary storage, an internal temporary buffer will be created on the fly managed by the runtime.
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.

Output buffers can be filled with either hermitian or complex numbers. Complex numbers can be stored in various layouts; this informs the FFT engine what layout to produce on output

Parameters
[in]plHandleHandle to a plan previously created
[out]iLayoutIndicates how the input buffers are laid out in memory
[out]oLayoutIndicates 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 this plan can handle concurrently.

User should pass a reference to an cl_uint variable, which will be set to the number of discrete arrays (1D or 2D) that will be batched together for this plan

Parameters
[in]plHandleHandle to a plan previously created
[out]batchSizeHow many discrete number of FFT's are to be 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.

User should pass a reference to an cl_context variable, which will be changed to point to a context set in the specified plan.

Parameters
[in]plHandleHandle to a plan previously created
[out]contextReference to user allocated cl_context, which will point to context set in 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 FFT's to be transformed in the plan.

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

Parameters
[in]plHandleHandle to a plan previously created
[out]dimThe dimensionality of the FFT's to be transformed
[out]sizeValue used 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]plHandleHandle to a plan previously created
[out]iDistThe distance between the beginning elements of the discrete array objects in memory on input. For contiguous arrays in memory, iDist=(strideX*strideY*strideZ)
[out]oDistThe distance between the beginning elements of the discrete array objects in memory on output. 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 for input buffers in a dimension.

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

Parameters
[in]plHandleHandle to a plan previously created
[in]dimThe dimension of the stride parameters; describes how many elements are in the array
[out]clStridesAn 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.

User should pass a reference to a size_t array, which will be set to the length of each discrete dimension of the FFT

Parameters
[in]plHandleHandle to a plan previously created
[in]dimThe dimension of the length parameters; describes how many elements are in the array
[out]clLengthsAn array of lengths, 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 for output buffers in a dimension.

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

Parameters
[in]plHandleHandle to a plan previously created
[in]dimThe dimension of the stride parameters; describes how many elements are in the array
[out]clStridesAn array of strides, of size 'dim'.
CLFFTAPI clfftStatus clfftGetPlanPrecision ( const clfftPlanHandle  plHandle,
clfftPrecision precision 
)

Retrieve the floating point precision of the FFT data.

User should pass a reference to an clfftPrecision variable, which will be set to the precision of the FFT complex data in the plan.

Parameters
[in]plHandleHandle to a plan previously created
[out]precisionReference to 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 should be applied to the FFT data.

User should pass a reference to an cl_float variable, which will be set to the floating point scaling factor that will be multiplied across the FFT data.

Parameters
[in]plHandleHandle to a plan previously created
[in]dirWhich direction does the scaling factor apply to
[out]scaleReference to 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 muti-dimensional FFT.

A multi-dimensional FFT typically 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 for possible speed improvements

Parameters
[in]plHandleHandle to a plan previously created
[out]transposedParameter specifies whether the final transpose can be skipped
CLFFTAPI clfftStatus clfftGetResultLocation ( const clfftPlanHandle  plHandle,
clfftResultLocation placeness 
)

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

If the setting is to do an in-place transform, the input buffers are overwritten with the results of the transform. If the setting is for out-of-place transforms, the engine knows to look for separate output buffers on the Enqueue call.

Parameters
[in]plHandleHandle to a plan previously created
[out]placenessTells the FFT engine to clobber the input buffers or to expect output buffers for results
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 would need 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 buffersize returns as 0, the runtime needs no temporary buffer.

Parameters
[in]plHandleHandle to a plan previously created
[out]buffersizeSize in bytes for intermediate buffer
CLFFTAPI clfftStatus clfftGetVersion ( cl_uint *  major,
cl_uint *  minor,
cl_uint *  patch 
)

Query the FFT library for version information.

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

Parameters
[out]majorMajor functionality change
[out]minorMinor functionality change
[out]patchBug fixes, documentation changes, no new features introduced
Returns
Enum describing error condition; superset of OpenCL error codes
__inline clfftStatus clfftInitSetupData ( clfftSetupData *  setupData)

Initialize an clfftSetupData struct for the client.

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

Parameters
[out]setupDataData structure is cleared, initialized with version information and default values
Returns
Enum describing 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.

Output buffers can be filled with either hermitian or complex numbers. Complex numbers can be stored in various layouts; this informs the FFT engine what layout to produce on output

Parameters
[in]plHandleHandle to a plan previously created
[in]iLayoutIndicates how the input buffers are laid out in memory
[in]oLayoutIndicates how the output buffers are laid out in memory
CLFFTAPI clfftStatus clfftSetPlanBatchSize ( clfftPlanHandle  plHandle,
size_t  batchSize 
)

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

Set the plan property which will be set to the number of discrete arrays (1D or 2D) that will be batched together for this plan

Parameters
[in]plHandleHandle to a plan previously created
[in]batchSizeHow many discrete number of FFT's are to be performed
Returns
Enum describing error condition; superset of OpenCL error codes
CLFFTAPI clfftStatus clfftSetPlanDim ( clfftPlanHandle  plHandle,
const clfftDim  dim 
)

Set the dimensionality of FFT's to be transformed by the plan.

Set the dimensionality of FFT's to be transformed by the plan

Parameters
[in]plHandleHandle to a plan previously created
[in]dimThe dimensionality of the FFT's 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]plHandleHandle to a plan previously created
[out]iDistThe distance between the beginning elements of the discrete array objects in memory on input. For contiguous arrays in memory, iDist=(strideX*strideY*strideZ)
[out]oDistThe distance between the beginning elements of the discrete array objects in memory on output. 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 for input buffers in a dimension.

Set the plan properties which will be the distance between elements in a given dimension (units are in terms of clfftPrecision)

Parameters
[in]plHandleHandle to a plan previously created
[in]dimThe dimension of the stride parameters; describes how many elements are in the array
[in]clStridesAn array of strides, of size 'dim'. Usually strideX=1 so that successive elements in the first dimension are stored contiguously. Typically strideY=LenX, strideZ=LenX*LenY such that successive elements in the second and third dimensions are 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.

Set the plan property which will be the length of each discrete dimension of the FFT

Parameters
[in]plHandleHandle to a plan previously created
[in]dimThe dimension of the length parameters; describes how many elements are in the array
[in]clLengthsAn array of lengths, of size 'dim'. Each value describes the length of additional dimensions
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 for output buffers in a dimension.

Set the plan properties which will be the distance between elements in a given dimension (units are in terms of clfftPrecision)

Parameters
[in]plHandleHandle to a plan previously created
[in]dimThe dimension of the stride parameters; describes how many elements are in the array
[in]clStridesAn array of strides, of size 'dim'. Usually strideX=1 so that successive elements in the first dimension are stored contiguously. Typically strideY=LenX, strideZ=LenX*LenY such that successive elements in the second and third dimensions are stored in packed format.
See also
clfftSetPlanInStride
CLFFTAPI clfftStatus clfftSetPlanPrecision ( clfftPlanHandle  plHandle,
clfftPrecision  precision 
)

Set the floating point precision of the FFT data.

Set the plan property which will be the precision of the FFT complex data in the plan.

Parameters
[in]plHandleHandle to a plan previously created
[in]precisionReference to 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 should be applied to the FFT data.

Set the plan property which will be the floating point scaling factor that will be multiplied across the FFT data.

Parameters
[in]plHandleHandle to a plan previously created
[in]dirWhich direction does the scaling factor apply to
[in]scaleReference to 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 muti-dimensional FFT.

A multi-dimensional FFT typically 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 for possible speed improvements

Parameters
[in]plHandleHandle to a plan previously created
[in]transposedParameter specifies whether the final transpose can be skipped
CLFFTAPI clfftStatus clfftSetResultLocation ( clfftPlanHandle  plHandle,
clfftResultLocation  placeness 
)

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

If the setting is to do an in-place transform, the input buffers are overwritten with the results of the transform. If the setting is for out-of-place transforms, the engine knows to look for separate output buffers on the Enqueue call.

Parameters
[in]plHandleHandle to a plan previously created
[in]placenessTells the FFT engine to clobber the input buffers or to expect output buffers for results
CLFFTAPI clfftStatus clfftSetup ( const clfftSetupData *  setupData)

Initialize internal FFT resources.

AMD's FFT implementation caches kernels, programs and buffers for its internal use.

Parameters
[in]setupDataData structure that can be 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.

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

Returns
Enum describing error condition; superset of OpenCL error codes