Loading...
Searching...
No Matches
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 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.
CLFFTAPI clfftStatus | clfftSetup (const clfftSetupData *setupData)
| Initialize the internal FFT resources.
CLFFTAPI clfftStatus | clfftTeardown ()
| Release all internal resources.
CLFFTAPI clfftStatus | clfftGetVersion (cl_uint *major, cl_uint *minor, cl_uint *patch)
| Query the FFT library for version information.
CLFFTAPI clfftStatus | clfftCreateDefaultPlan (clfftPlanHandle *plHandle, cl_context context, const clfftDim dim, const size_t *clLengths)
| Create a plan object initialized entirely with default values.
CLFFTAPI clfftStatus | clfftCopyPlan (clfftPlanHandle *out_plHandle, cl_context new_context, clfftPlanHandle in_plHandle)
| Create a copy of an existing plan.
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.
CLFFTAPI clfftStatus | clfftDestroyPlan (clfftPlanHandle *plHandle)
| Release the resources of a plan.
CLFFTAPI clfftStatus | clfftGetPlanContext (const clfftPlanHandle plHandle, cl_context *context)
| Retrieve the OpenCL context of a previously created plan.
CLFFTAPI clfftStatus | clfftGetPlanPrecision (const clfftPlanHandle plHandle, clfftPrecision *precision)
| Retrieve the floating point precision of the FFT data.
CLFFTAPI clfftStatus | clfftSetPlanPrecision (clfftPlanHandle plHandle, clfftPrecision precision)
| Set the floating point precision of the FFT data.
CLFFTAPI clfftStatus | clfftGetPlanScale (const clfftPlanHandle plHandle, clfftDirection dir, cl_float *scale)
| Retrieve the scaling factor that is applied to the FFT data.
CLFFTAPI clfftStatus | clfftSetPlanScale (clfftPlanHandle plHandle, clfftDirection dir, cl_float scale)
| Set the scaling factor that is applied to the FFT data.
CLFFTAPI clfftStatus | clfftGetPlanBatchSize (const clfftPlanHandle plHandle, size_t *batchSize)
| Retrieve the number of discrete arrays that the plan can concurrently handle.
CLFFTAPI clfftStatus | clfftSetPlanBatchSize (clfftPlanHandle plHandle, size_t batchSize)
| Set the number of discrete arrays that the plan can concurrently handle.
CLFFTAPI clfftStatus | clfftGetPlanDim (const clfftPlanHandle plHandle, clfftDim *dim, cl_uint *size)
| Retrieve the dimensionality of the data that is transformed.
CLFFTAPI clfftStatus | clfftSetPlanDim (clfftPlanHandle plHandle, const clfftDim dim)
| Set the dimensionality of the data that is transformed.
CLFFTAPI clfftStatus | clfftGetPlanLength (const clfftPlanHandle plHandle, const clfftDim dim, size_t *clLengths)
| Retrieve the length of each dimension of the FFT.
CLFFTAPI clfftStatus | clfftSetPlanLength (clfftPlanHandle plHandle, const clfftDim dim, const size_t *clLengths)
| Set the length of each dimension of the FFT.
CLFFTAPI clfftStatus | clfftGetPlanInStride (const clfftPlanHandle plHandle, const clfftDim dim, size_t *clStrides)
| Retrieve the distance between consecutive elements of input buffers in each dimension.
CLFFTAPI clfftStatus | clfftSetPlanInStride (clfftPlanHandle plHandle, const clfftDim dim, size_t *clStrides)
| Set the distance between consecutive elements of input buffers in each dimension.
CLFFTAPI clfftStatus | clfftGetPlanOutStride (const clfftPlanHandle plHandle, const clfftDim dim, size_t *clStrides)
| Retrieve the distance between consecutive elements of output buffers in each dimension.
CLFFTAPI clfftStatus | clfftSetPlanOutStride (clfftPlanHandle plHandle, const clfftDim dim, size_t *clStrides)
| Set the distance between consecutive elements of output buffers in a dimension.
CLFFTAPI clfftStatus | clfftGetPlanDistance (const clfftPlanHandle plHandle, size_t *iDist, size_t *oDist)
| Retrieve the distance between array objects.
CLFFTAPI clfftStatus | clfftSetPlanDistance (clfftPlanHandle plHandle, size_t iDist, size_t oDist)
| Set the distance between array objects.
CLFFTAPI clfftStatus | clfftGetLayout (const clfftPlanHandle plHandle, clfftLayout *iLayout, clfftLayout *oLayout)
| Retrieve the expected layout of the input and output buffers.
CLFFTAPI clfftStatus | clfftSetLayout (clfftPlanHandle plHandle, clfftLayout iLayout, clfftLayout oLayout)
| Set the expected layout of the input and output buffers.
CLFFTAPI clfftStatus | clfftGetResultLocation (const clfftPlanHandle plHandle, clfftResultLocation *placeness)
| Retrieve whether the input buffers are to be overwritten with results.
CLFFTAPI clfftStatus | clfftSetResultLocation (clfftPlanHandle plHandle, clfftResultLocation placeness)
| Set whether the input buffers are to be overwritten with results.
CLFFTAPI clfftStatus | clfftGetPlanTransposeResult (const clfftPlanHandle plHandle, clfftResultTransposed *transposed)
| Retrieve the final transpose setting of a multi-dimensional FFT.
CLFFTAPI clfftStatus | clfftSetPlanTransposeResult (clfftPlanHandle plHandle, clfftResultTransposed transposed)
| Set the final transpose setting of a multi-dimensional FFT.
CLFFTAPI clfftStatus | clfftGetTmpBufSize (const clfftPlanHandle plHandle, size_t *buffersize)
| Get buffer size (in bytes), which may be needed internally for an intermediate buffer.
CLFFTAPI clfftStatus | clfftSetPlanCallback (clfftPlanHandle plHandle, const char *funcName, const char *funcString, int localMemSize, clfftCallbackType callbackType, cl_mem *userdata, int numUserdataBuffers)
| Register the callback parameters.
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).

## 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

## CLFFT_DUMP_PROGRAMS

#define CLFFT_DUMP_PROGRAMS 0x1

BitMasks to be used with clfftSetupData.debugFlags

## CLFFTAPI

#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

## clfftCallbackType

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.

## clfftDim

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.

## clfftDirection

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.

## clfftLayout

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.

## clfftPrecision

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.

## clfftResultLocation

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.

## clfftResultTransposed

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

## clfftStatus_

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

## clfftBakePlan()

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

## clfftCopyPlan()

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

## clfftCreateDefaultPlan()

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

## clfftDestroyPlan()

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

## clfftEnqueueTransform()

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

## clfftGetLayout()

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

## clfftGetPlanBatchSize()

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

## clfftGetPlanContext()

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

## clfftGetPlanDim()

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

## clfftGetPlanDistance()

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)

## clfftGetPlanInStride()

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'.

## clfftGetPlanLength()

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

## clfftGetPlanOutStride()

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'.

## clfftGetPlanPrecision()

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

## clfftGetPlanScale()

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

## clfftGetPlanTransposeResult()

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

## clfftGetResultLocation()

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

## clfftGetTmpBufSize()

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

## clfftGetVersion()

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

## clfftInitSetupData()

__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

## clfftSetLayout()

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

## clfftSetPlanBatchSize()

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

## clfftSetPlanCallback()

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

## clfftSetPlanDim()

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

## clfftSetPlanDistance()

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)

## clfftSetPlanInStride()

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.

## clfftSetPlanLength()

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

## clfftSetPlanOutStride()

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

## clfftSetPlanPrecision()

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

## clfftSetPlanScale()

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

## clfftSetPlanTransposeResult()

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

## clfftSetResultLocation()

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

## clfftSetup()

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

## clfftTeardown()

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