clFFT  2.0
clFFT.h
Go to the documentation of this file.
1 /* ************************************************************************
2  * Copyright 2013 Advanced Micro Devices, Inc.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  * ************************************************************************/
16 
17 
26 #pragma once
27 #if !defined( CLFFT_H )
28 #define CLFFT_H
29 
30 #if defined(__APPLE__) || defined(__MACOSX)
31  #include <OpenCL/cl.h>
32 #else
33  #include <CL/cl.h>
34 #endif
35 
36 #include "clFFT.version.h"
37 
45 #if defined( _WIN32 )
46  #if !defined( __cplusplus )
47  #define inline __inline
48  #endif
49 
50  #if defined( CLFFT_STATIC )
51  #define CLFFTAPI
52  #elif defined( CLFFT_EXPORTS )
53  #define CLFFTAPI __declspec( dllexport )
54  #else
55  #define CLFFTAPI __declspec( dllimport )
56  #endif
57 #else
58  #define CLFFTAPI
59 #endif
60 
61 /* In general, you can not use namespaces for strict C compliance, so we prefix our public accessible names
62  * with the string clfft
63  */
64 
65 /* All functions will return pre-defined error codes, and will NOT throw exceptions to the caller
66  */
67 
75 {
76  CLFFT_INVALID_GLOBAL_WORK_SIZE = CL_INVALID_GLOBAL_WORK_SIZE,
77  CLFFT_INVALID_MIP_LEVEL = CL_INVALID_MIP_LEVEL,
78  CLFFT_INVALID_BUFFER_SIZE = CL_INVALID_BUFFER_SIZE,
79  CLFFT_INVALID_GL_OBJECT = CL_INVALID_GL_OBJECT,
80  CLFFT_INVALID_OPERATION = CL_INVALID_OPERATION,
81  CLFFT_INVALID_EVENT = CL_INVALID_EVENT,
82  CLFFT_INVALID_EVENT_WAIT_LIST = CL_INVALID_EVENT_WAIT_LIST,
83  CLFFT_INVALID_GLOBAL_OFFSET = CL_INVALID_GLOBAL_OFFSET,
84  CLFFT_INVALID_WORK_ITEM_SIZE = CL_INVALID_WORK_ITEM_SIZE,
85  CLFFT_INVALID_WORK_GROUP_SIZE = CL_INVALID_WORK_GROUP_SIZE,
86  CLFFT_INVALID_WORK_DIMENSION = CL_INVALID_WORK_DIMENSION,
87  CLFFT_INVALID_KERNEL_ARGS = CL_INVALID_KERNEL_ARGS,
88  CLFFT_INVALID_ARG_SIZE = CL_INVALID_ARG_SIZE,
89  CLFFT_INVALID_ARG_VALUE = CL_INVALID_ARG_VALUE,
90  CLFFT_INVALID_ARG_INDEX = CL_INVALID_ARG_INDEX,
91  CLFFT_INVALID_KERNEL = CL_INVALID_KERNEL,
92  CLFFT_INVALID_KERNEL_DEFINITION = CL_INVALID_KERNEL_DEFINITION,
93  CLFFT_INVALID_KERNEL_NAME = CL_INVALID_KERNEL_NAME,
94  CLFFT_INVALID_PROGRAM_EXECUTABLE = CL_INVALID_PROGRAM_EXECUTABLE,
95  CLFFT_INVALID_PROGRAM = CL_INVALID_PROGRAM,
96  CLFFT_INVALID_BUILD_OPTIONS = CL_INVALID_BUILD_OPTIONS,
97  CLFFT_INVALID_BINARY = CL_INVALID_BINARY,
98  CLFFT_INVALID_SAMPLER = CL_INVALID_SAMPLER,
99  CLFFT_INVALID_IMAGE_SIZE = CL_INVALID_IMAGE_SIZE,
100  CLFFT_INVALID_IMAGE_FORMAT_DESCRIPTOR = CL_INVALID_IMAGE_FORMAT_DESCRIPTOR,
101  CLFFT_INVALID_MEM_OBJECT = CL_INVALID_MEM_OBJECT,
102  CLFFT_INVALID_HOST_PTR = CL_INVALID_HOST_PTR,
103  CLFFT_INVALID_COMMAND_QUEUE = CL_INVALID_COMMAND_QUEUE,
104  CLFFT_INVALID_QUEUE_PROPERTIES = CL_INVALID_QUEUE_PROPERTIES,
105  CLFFT_INVALID_CONTEXT = CL_INVALID_CONTEXT,
106  CLFFT_INVALID_DEVICE = CL_INVALID_DEVICE,
107  CLFFT_INVALID_PLATFORM = CL_INVALID_PLATFORM,
108  CLFFT_INVALID_DEVICE_TYPE = CL_INVALID_DEVICE_TYPE,
109  CLFFT_INVALID_VALUE = CL_INVALID_VALUE,
110  CLFFT_MAP_FAILURE = CL_MAP_FAILURE,
111  CLFFT_BUILD_PROGRAM_FAILURE = CL_BUILD_PROGRAM_FAILURE,
112  CLFFT_IMAGE_FORMAT_NOT_SUPPORTED = CL_IMAGE_FORMAT_NOT_SUPPORTED,
113  CLFFT_IMAGE_FORMAT_MISMATCH = CL_IMAGE_FORMAT_MISMATCH,
114  CLFFT_MEM_COPY_OVERLAP = CL_MEM_COPY_OVERLAP,
115  CLFFT_PROFILING_INFO_NOT_AVAILABLE = CL_PROFILING_INFO_NOT_AVAILABLE,
116  CLFFT_OUT_OF_HOST_MEMORY = CL_OUT_OF_HOST_MEMORY,
117  CLFFT_OUT_OF_RESOURCES = CL_OUT_OF_RESOURCES,
118  CLFFT_MEM_OBJECT_ALLOCATION_FAILURE = CL_MEM_OBJECT_ALLOCATION_FAILURE,
119  CLFFT_COMPILER_NOT_AVAILABLE = CL_COMPILER_NOT_AVAILABLE,
120  CLFFT_DEVICE_NOT_AVAILABLE = CL_DEVICE_NOT_AVAILABLE,
121  CLFFT_DEVICE_NOT_FOUND = CL_DEVICE_NOT_FOUND,
122  CLFFT_SUCCESS = CL_SUCCESS,
123  //-------------------------- Extended status codes for clfft ----------------------------------------
124  CLFFT_BUGCHECK = 4*1024,
133  CLFFT_ENDSTATUS /* This value will always be last, and marks the length of clfftStatus. */
134 };
135 typedef enum clfftStatus_ clfftStatus;
136 
138 typedef enum clfftDim_
139 {
140  CLFFT_1D = 1,
144 } clfftDim;
145 
147 typedef enum clfftLayout_
148 {
155 } clfftLayout;
156 
159 typedef enum clfftPrecision_
160 {
167 
169 typedef enum clfftDirection_
170 {
173  CLFFT_MINUS = -1,
177 
179 typedef enum clfftResultLocation_
180 {
185 
188 typedef enum clfftResultTransposed_ {
193 
195 #define CLFFT_DUMP_PROGRAMS 0x1
196 
203 {
204  cl_uint major;
205  cl_uint minor;
206  cl_uint patch;
209  cl_ulong debugFlags;
213 };
214 typedef struct clfftSetupData_ clfftSetupData;
215 
217 typedef size_t clfftPlanHandle;
218 
219 #ifdef __cplusplus
220 extern "C" {
221 #endif
222 
227  __inline clfftStatus clfftInitSetupData( clfftSetupData* setupData )
228  {
229  setupData->major = clfftVersionMajor;
230  setupData->minor = clfftVersionMinor;
231  setupData->patch = clfftVersionPatch;
232  setupData->debugFlags = 0;
233 
234  return CLFFT_SUCCESS;
235  }
236 
243  CLFFTAPI clfftStatus clfftSetup( const clfftSetupData* setupData );
244 
249  CLFFTAPI clfftStatus clfftTeardown( );
250 
258  CLFFTAPI clfftStatus clfftGetVersion( cl_uint* major, cl_uint* minor, cl_uint* patch );
259 
269  CLFFTAPI clfftStatus clfftCreateDefaultPlan( clfftPlanHandle* plHandle, cl_context context, const clfftDim dim,
270  const size_t* clLengths );
271 
280  CLFFTAPI clfftStatus clfftCopyPlan( clfftPlanHandle* out_plHandle, cl_context new_context, clfftPlanHandle in_plHandle );
281 
306  CLFFTAPI clfftStatus clfftBakePlan( clfftPlanHandle plHandle, cl_uint numQueues, cl_command_queue* commQueueFFT,
307  void (CL_CALLBACK *pfn_notify)(clfftPlanHandle plHandle, void *user_data), void* user_data );
308 
315  CLFFTAPI clfftStatus clfftDestroyPlan( clfftPlanHandle* plHandle );
316 
324  CLFFTAPI clfftStatus clfftGetPlanContext( const clfftPlanHandle plHandle, cl_context* context );
325 
333  CLFFTAPI clfftStatus clfftGetPlanPrecision( const clfftPlanHandle plHandle, clfftPrecision* precision );
334 
341  CLFFTAPI clfftStatus clfftSetPlanPrecision( clfftPlanHandle plHandle, clfftPrecision precision );
342 
351  CLFFTAPI clfftStatus clfftGetPlanScale( const clfftPlanHandle plHandle, clfftDirection dir, cl_float* scale );
352 
361  CLFFTAPI clfftStatus clfftSetPlanScale( clfftPlanHandle plHandle, clfftDirection dir, cl_float scale );
362 
370  CLFFTAPI clfftStatus clfftGetPlanBatchSize( const clfftPlanHandle plHandle, size_t* batchSize );
371 
379  CLFFTAPI clfftStatus clfftSetPlanBatchSize( clfftPlanHandle plHandle, size_t batchSize );
380 
389  CLFFTAPI clfftStatus clfftGetPlanDim( const clfftPlanHandle plHandle, clfftDim* dim, cl_uint* size );
390 
397  CLFFTAPI clfftStatus clfftSetPlanDim( clfftPlanHandle plHandle, const clfftDim dim );
398 
407  CLFFTAPI clfftStatus clfftGetPlanLength( const clfftPlanHandle plHandle, const clfftDim dim, size_t* clLengths );
408 
416  CLFFTAPI clfftStatus clfftSetPlanLength( clfftPlanHandle plHandle, const clfftDim dim, const size_t* clLengths );
417 
425  CLFFTAPI clfftStatus clfftGetPlanInStride( const clfftPlanHandle plHandle, const clfftDim dim, size_t* clStrides );
426 
436  CLFFTAPI clfftStatus clfftSetPlanInStride( clfftPlanHandle plHandle, const clfftDim dim, size_t* clStrides );
437 
445  CLFFTAPI clfftStatus clfftGetPlanOutStride( const clfftPlanHandle plHandle, const clfftDim dim, size_t* clStrides );
446 
456  CLFFTAPI clfftStatus clfftSetPlanOutStride( clfftPlanHandle plHandle, const clfftDim dim, size_t* clStrides );
457 
467  CLFFTAPI clfftStatus clfftGetPlanDistance( const clfftPlanHandle plHandle, size_t* iDist, size_t* oDist );
468 
478  CLFFTAPI clfftStatus clfftSetPlanDistance( clfftPlanHandle plHandle, size_t iDist, size_t oDist );
479 
487  CLFFTAPI clfftStatus clfftGetLayout( const clfftPlanHandle plHandle, clfftLayout* iLayout, clfftLayout* oLayout );
488 
496  CLFFTAPI clfftStatus clfftSetLayout( clfftPlanHandle plHandle, clfftLayout iLayout, clfftLayout oLayout );
497 
505  CLFFTAPI clfftStatus clfftGetResultLocation( const clfftPlanHandle plHandle, clfftResultLocation* placeness );
506 
514  CLFFTAPI clfftStatus clfftSetResultLocation( clfftPlanHandle plHandle, clfftResultLocation placeness );
515 
523  CLFFTAPI clfftStatus clfftGetPlanTransposeResult( const clfftPlanHandle plHandle, clfftResultTransposed * transposed );
524 
533 
534 
542  CLFFTAPI clfftStatus clfftGetTmpBufSize( const clfftPlanHandle plHandle, size_t* buffersize );
543 
566  CLFFTAPI clfftStatus clfftEnqueueTransform(
567  clfftPlanHandle plHandle,
568  clfftDirection dir,
569  cl_uint numQueuesAndEvents,
570  cl_command_queue* commQueues,
571  cl_uint numWaitEvents,
572  const cl_event* waitEvents,
573  cl_event* outEvents,
574  cl_mem* inputBuffers,
575  cl_mem* outputBuffers,
576  cl_mem tmpBuffer
577  );
578 
579 #ifdef __cplusplus
580 }
581 #endif
582 
583 #endif
Definition: clFFT.h:140
clfftResultTransposed
This determines whether the result is returned in original order. It is valid only for dimensions gre...
Definition: clFFT.h:188
clfftDirection
What is the expected direction of each FFT, time or the frequency domains.
Definition: clFFT.h:169
CLFFTAPI clfftStatus clfftGetPlanContext(const clfftPlanHandle plHandle, cl_context *context)
Retrieve the OpenCL context of a previously created plan.
clfftStatus_
clfft error codes definition, incorporating OpenCL error definitions
Definition: clFFT.h:74
CLFFTAPI clfftStatus clfftGetPlanPrecision(const clfftPlanHandle plHandle, clfftPrecision *precision)
Retrieve the floating point precision of the FFT data.
CLFFTAPI clfftStatus clfftGetLayout(const clfftPlanHandle plHandle, clfftLayout *iLayout, clfftLayout *oLayout)
Retrieve the expected layout of the input and output buffers.
CLFFTAPI clfftStatus clfftDestroyPlan(clfftPlanHandle *plHandle)
Release the resources of a plan.
CLFFTAPI clfftStatus clfftGetPlanDistance(const clfftPlanHandle plHandle, size_t *iDist, size_t *oDist)
Retrieve the distance between Array objects.
Definition: clFFT.h:149
CLFFTAPI clfftStatus clfftGetPlanLength(const clfftPlanHandle plHandle, const clfftDim dim, size_t *clLengths)
Retrieve the length of each dimension of the FFT.
#define CLFFTAPI
Definition: clFFT.h:58
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.
Definition: clFFT.h:143
Definition: clFFT.h:125
Definition: clFFT.h:165
cl_uint major
Definition: clFFT.h:204
Definition: clFFT.h:162
Data structure that can be passed to clfftSetup() to control the behavior of the FFT runtime...
Definition: clFFT.h:202
CLFFTAPI clfftStatus clfftSetPlanDistance(clfftPlanHandle plHandle, size_t iDist, size_t oDist)
Set the distance between Array objects.
CLFFTAPI clfftStatus clfftSetResultLocation(clfftPlanHandle plHandle, clfftResultLocation placeness)
Set whether the input buffers are going to be overwritten with results.
CLFFTAPI clfftStatus clfftSetPlanScale(clfftPlanHandle plHandle, clfftDirection dir, cl_float scale)
Set the scaling factor that should be applied to the FFT data.
Definition: clFFT.h:128
Definition: clFFT.h:172
CLFFTAPI clfftStatus clfftSetLayout(clfftPlanHandle plHandle, clfftLayout iLayout, clfftLayout oLayout)
Set the expected layout of the input and output buffers.
CLFFTAPI clfftStatus clfftTeardown()
Release all internal resources.
Definition: clFFT.h:127
cl_uint patch
Definition: clFFT.h:206
Definition: clFFT.h:153
Definition: clFFT.h:141
CLFFTAPI clfftStatus clfftSetPlanPrecision(clfftPlanHandle plHandle, clfftPrecision precision)
Set the floating point precision of the FFT data.
Definition: clFFT.h:152
Definition: clFFT.h:129
Definition: clFFT.h:132
Definition: clFFT.h:126
CLFFTAPI clfftStatus clfftSetPlanOutStride(clfftPlanHandle plHandle, const clfftDim dim, size_t *clStrides)
Set the distance between consecutive elements for output buffers in a dimension.
Definition: clFFT.h:173
Definition: clFFT.h:175
Definition: clFFT.h:163
CLFFTAPI clfftStatus clfftCopyPlan(clfftPlanHandle *out_plHandle, cl_context new_context, clfftPlanHandle in_plHandle)
Create a copy of an existing plan.
Definition: clFFT.h:174
CLFFTAPI clfftStatus clfftCreateDefaultPlan(clfftPlanHandle *plHandle, cl_context context, const clfftDim dim, const size_t *clLengths)
Create a plan object initialized entirely with default values.
cl_uint minor
Definition: clFFT.h:205
Definition: clFFT.h:151
CLFFTAPI clfftStatus clfftGetPlanBatchSize(const clfftPlanHandle plHandle, size_t *batchSize)
Retrieve the number of discrete arrays that this plan can handle concurrently.
CLFFTAPI clfftStatus clfftSetPlanTransposeResult(clfftPlanHandle plHandle, clfftResultTransposed transposed)
Set the final transpose setting of a muti-dimensional FFT.
CLFFTAPI clfftStatus clfftSetPlanBatchSize(clfftPlanHandle plHandle, size_t batchSize)
Set the number of discrete arrays that this plan can handle concurrently.
__inline clfftStatus clfftInitSetupData(clfftSetupData *setupData)
Initialize an clfftSetupData struct for the client.
Definition: clFFT.h:227
CLFFTAPI clfftStatus clfftGetVersion(cl_uint *major, cl_uint *minor, cl_uint *patch)
Query the FFT library for version information.
Definition: clFFT.h:171
CLFFTAPI clfftStatus clfftSetPlanLength(clfftPlanHandle plHandle, const clfftDim dim, const size_t *clLengths)
Set the length of each dimension of the FFT.
Definition: clFFT.h:190
Definition: clFFT.h:181
CLFFTAPI clfftStatus clfftGetTmpBufSize(const clfftPlanHandle plHandle, size_t *buffersize)
Get buffer size (in bytes), which may be needed internally for an intermediate buffer.
Definition: clFFT.h:161
CLFFTAPI clfftStatus clfftSetup(const clfftSetupData *setupData)
Initialize internal FFT resources.
CLFFTAPI clfftStatus clfftGetPlanTransposeResult(const clfftPlanHandle plHandle, clfftResultTransposed *transposed)
Retrieve the final transpose setting of a muti-dimensional FFT.
CLFFTAPI clfftStatus clfftSetPlanDim(clfftPlanHandle plHandle, const clfftDim dim)
Set the dimensionality of FFT's to be transformed by the plan.
Definition: clFFT.h:154
size_t clfftPlanHandle
An abstract handle to the object that represents the state of the FFT(s)
Definition: clFFT.h:217
CLFFTAPI clfftStatus clfftGetResultLocation(const clfftPlanHandle plHandle, clfftResultLocation *placeness)
Retrieve whether the input buffers are going to be overwritten with results.
clfftLayout
These are the expected layouts of the buffers.
Definition: clFFT.h:147
Definition: clFFT.h:150
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)
Definition: clFFT.h:189
CLFFTAPI clfftStatus clfftGetPlanInStride(const clfftPlanHandle plHandle, const clfftDim dim, size_t *clStrides)
Retrieve the distance between consecutive elements for input buffers in a dimension.
Definition: clFFT.h:130
clfftResultLocation
Are the input buffers overwritten with the results.
Definition: clFFT.h:179
Definition: clFFT.h:124
cl_ulong debugFlags
Definition: clFFT.h:209
CLFFTAPI clfftStatus clfftGetPlanOutStride(const clfftPlanHandle plHandle, const clfftDim dim, size_t *clStrides)
Retrieve the distance between consecutive elements for output buffers in a dimension.
CLFFTAPI clfftStatus clfftSetPlanInStride(clfftPlanHandle plHandle, const clfftDim dim, size_t *clStrides)
Set the distance between consecutive elements for input buffers in a dimension.
Definition: clFFT.h:183
Definition: clFFT.h:164
Definition: clFFT.h:182
Definition: clFFT.h:142
CLFFTAPI clfftStatus clfftGetPlanScale(const clfftPlanHandle plHandle, clfftDirection dir, cl_float *scale)
Retrieve the scaling factor that should be applied to the FFT data.
clfftPrecision
This is the expected precision of each FFT.
Definition: clFFT.h:159
CLFFTAPI clfftStatus clfftGetPlanDim(const clfftPlanHandle plHandle, clfftDim *dim, cl_uint *size)
Retrieve the dimensionality of FFT's to be transformed in the plan.
Definition: clFFT.h:131
Definition: clFFT.h:191
clfftDim
The dimension of the input and output buffers that will be fed into all FFT transforms.
Definition: clFFT.h:138