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_EXPORTS )
51  #define CLFFTAPI __declspec( dllexport )
52  #else
53  #define CLFFTAPI __declspec( dllimport )
54  #endif
55 #else
56  #define CLFFTAPI
57 #endif
58 
59 /* In general, you can not use namespaces for strict C compliance, so we prefix our public accessible names
60  * with the string clfft
61  */
62 
63 /* All functions will return pre-defined error codes, and will NOT throw exceptions to the caller
64  */
65 
73 {
74  CLFFT_INVALID_GLOBAL_WORK_SIZE = CL_INVALID_GLOBAL_WORK_SIZE,
75  CLFFT_INVALID_MIP_LEVEL = CL_INVALID_MIP_LEVEL,
76  CLFFT_INVALID_BUFFER_SIZE = CL_INVALID_BUFFER_SIZE,
77  CLFFT_INVALID_GL_OBJECT = CL_INVALID_GL_OBJECT,
78  CLFFT_INVALID_OPERATION = CL_INVALID_OPERATION,
79  CLFFT_INVALID_EVENT = CL_INVALID_EVENT,
80  CLFFT_INVALID_EVENT_WAIT_LIST = CL_INVALID_EVENT_WAIT_LIST,
81  CLFFT_INVALID_GLOBAL_OFFSET = CL_INVALID_GLOBAL_OFFSET,
82  CLFFT_INVALID_WORK_ITEM_SIZE = CL_INVALID_WORK_ITEM_SIZE,
83  CLFFT_INVALID_WORK_GROUP_SIZE = CL_INVALID_WORK_GROUP_SIZE,
84  CLFFT_INVALID_WORK_DIMENSION = CL_INVALID_WORK_DIMENSION,
85  CLFFT_INVALID_KERNEL_ARGS = CL_INVALID_KERNEL_ARGS,
86  CLFFT_INVALID_ARG_SIZE = CL_INVALID_ARG_SIZE,
87  CLFFT_INVALID_ARG_VALUE = CL_INVALID_ARG_VALUE,
88  CLFFT_INVALID_ARG_INDEX = CL_INVALID_ARG_INDEX,
89  CLFFT_INVALID_KERNEL = CL_INVALID_KERNEL,
90  CLFFT_INVALID_KERNEL_DEFINITION = CL_INVALID_KERNEL_DEFINITION,
91  CLFFT_INVALID_KERNEL_NAME = CL_INVALID_KERNEL_NAME,
92  CLFFT_INVALID_PROGRAM_EXECUTABLE = CL_INVALID_PROGRAM_EXECUTABLE,
93  CLFFT_INVALID_PROGRAM = CL_INVALID_PROGRAM,
94  CLFFT_INVALID_BUILD_OPTIONS = CL_INVALID_BUILD_OPTIONS,
95  CLFFT_INVALID_BINARY = CL_INVALID_BINARY,
96  CLFFT_INVALID_SAMPLER = CL_INVALID_SAMPLER,
97  CLFFT_INVALID_IMAGE_SIZE = CL_INVALID_IMAGE_SIZE,
98  CLFFT_INVALID_IMAGE_FORMAT_DESCRIPTOR = CL_INVALID_IMAGE_FORMAT_DESCRIPTOR,
99  CLFFT_INVALID_MEM_OBJECT = CL_INVALID_MEM_OBJECT,
100  CLFFT_INVALID_HOST_PTR = CL_INVALID_HOST_PTR,
101  CLFFT_INVALID_COMMAND_QUEUE = CL_INVALID_COMMAND_QUEUE,
102  CLFFT_INVALID_QUEUE_PROPERTIES = CL_INVALID_QUEUE_PROPERTIES,
103  CLFFT_INVALID_CONTEXT = CL_INVALID_CONTEXT,
104  CLFFT_INVALID_DEVICE = CL_INVALID_DEVICE,
105  CLFFT_INVALID_PLATFORM = CL_INVALID_PLATFORM,
106  CLFFT_INVALID_DEVICE_TYPE = CL_INVALID_DEVICE_TYPE,
107  CLFFT_INVALID_VALUE = CL_INVALID_VALUE,
108  CLFFT_MAP_FAILURE = CL_MAP_FAILURE,
109  CLFFT_BUILD_PROGRAM_FAILURE = CL_BUILD_PROGRAM_FAILURE,
110  CLFFT_IMAGE_FORMAT_NOT_SUPPORTED = CL_IMAGE_FORMAT_NOT_SUPPORTED,
111  CLFFT_IMAGE_FORMAT_MISMATCH = CL_IMAGE_FORMAT_MISMATCH,
112  CLFFT_MEM_COPY_OVERLAP = CL_MEM_COPY_OVERLAP,
113  CLFFT_PROFILING_INFO_NOT_AVAILABLE = CL_PROFILING_INFO_NOT_AVAILABLE,
114  CLFFT_OUT_OF_HOST_MEMORY = CL_OUT_OF_HOST_MEMORY,
115  CLFFT_OUT_OF_RESOURCES = CL_OUT_OF_RESOURCES,
116  CLFFT_MEM_OBJECT_ALLOCATION_FAILURE = CL_MEM_OBJECT_ALLOCATION_FAILURE,
117  CLFFT_COMPILER_NOT_AVAILABLE = CL_COMPILER_NOT_AVAILABLE,
118  CLFFT_DEVICE_NOT_AVAILABLE = CL_DEVICE_NOT_AVAILABLE,
119  CLFFT_DEVICE_NOT_FOUND = CL_DEVICE_NOT_FOUND,
120  CLFFT_SUCCESS = CL_SUCCESS,
121  //-------------------------- Extended status codes for clfft ----------------------------------------
122  CLFFT_BUGCHECK = 4*1024,
131  CLFFT_ENDSTATUS /* This value will always be last, and marks the length of clfftStatus. */
132 };
133 typedef enum clfftStatus_ clfftStatus;
134 
136 typedef enum clfftDim_
137 {
138  CLFFT_1D = 1,
142 } clfftDim;
143 
145 typedef enum clfftLayout_
146 {
153 } clfftLayout;
154 
157 typedef enum clfftPrecision_
158 {
165 
167 typedef enum clfftDirection_
168 {
171  CLFFT_MINUS = -1,
175 
177 typedef enum clfftResultLocation_
178 {
183 
186 typedef enum clfftResultTransposed_ {
191 
193 #define CLFFT_DUMP_PROGRAMS 0x1
194 
201 {
202  cl_uint major;
203  cl_uint minor;
204  cl_uint patch;
207  cl_ulong debugFlags;
211 };
212 typedef struct clfftSetupData_ clfftSetupData;
213 
215 typedef size_t clfftPlanHandle;
216 
217 #ifdef __cplusplus
218 extern "C" {
219 #endif
220 
225  __inline clfftStatus clfftInitSetupData( clfftSetupData* setupData )
226  {
227  setupData->major = clfftVersionMajor;
228  setupData->minor = clfftVersionMinor;
229  setupData->patch = clfftVersionPatch;
230  setupData->debugFlags = 0;
231 
232  return CLFFT_SUCCESS;
233  }
234 
241  CLFFTAPI clfftStatus clfftSetup( const clfftSetupData* setupData );
242 
247  CLFFTAPI clfftStatus clfftTeardown( );
248 
256  CLFFTAPI clfftStatus clfftGetVersion( cl_uint* major, cl_uint* minor, cl_uint* patch );
257 
267  CLFFTAPI clfftStatus clfftCreateDefaultPlan( clfftPlanHandle* plHandle, cl_context context, const clfftDim dim,
268  const size_t* clLengths );
269 
278  CLFFTAPI clfftStatus clfftCopyPlan( clfftPlanHandle* out_plHandle, cl_context new_context, clfftPlanHandle in_plHandle );
279 
304  CLFFTAPI clfftStatus clfftBakePlan( clfftPlanHandle plHandle, cl_uint numQueues, cl_command_queue* commQueueFFT,
305  void (CL_CALLBACK *pfn_notify)(clfftPlanHandle plHandle, void *user_data), void* user_data );
306 
313  CLFFTAPI clfftStatus clfftDestroyPlan( clfftPlanHandle* plHandle );
314 
322  CLFFTAPI clfftStatus clfftGetPlanContext( const clfftPlanHandle plHandle, cl_context* context );
323 
331  CLFFTAPI clfftStatus clfftGetPlanPrecision( const clfftPlanHandle plHandle, clfftPrecision* precision );
332 
339  CLFFTAPI clfftStatus clfftSetPlanPrecision( clfftPlanHandle plHandle, clfftPrecision precision );
340 
349  CLFFTAPI clfftStatus clfftGetPlanScale( const clfftPlanHandle plHandle, clfftDirection dir, cl_float* scale );
350 
359  CLFFTAPI clfftStatus clfftSetPlanScale( clfftPlanHandle plHandle, clfftDirection dir, cl_float scale );
360 
368  CLFFTAPI clfftStatus clfftGetPlanBatchSize( const clfftPlanHandle plHandle, size_t* batchSize );
369 
377  CLFFTAPI clfftStatus clfftSetPlanBatchSize( clfftPlanHandle plHandle, size_t batchSize );
378 
387  CLFFTAPI clfftStatus clfftGetPlanDim( const clfftPlanHandle plHandle, clfftDim* dim, cl_uint* size );
388 
395  CLFFTAPI clfftStatus clfftSetPlanDim( clfftPlanHandle plHandle, const clfftDim dim );
396 
405  CLFFTAPI clfftStatus clfftGetPlanLength( const clfftPlanHandle plHandle, const clfftDim dim, size_t* clLengths );
406 
414  CLFFTAPI clfftStatus clfftSetPlanLength( clfftPlanHandle plHandle, const clfftDim dim, const size_t* clLengths );
415 
423  CLFFTAPI clfftStatus clfftGetPlanInStride( const clfftPlanHandle plHandle, const clfftDim dim, size_t* clStrides );
424 
434  CLFFTAPI clfftStatus clfftSetPlanInStride( clfftPlanHandle plHandle, const clfftDim dim, size_t* clStrides );
435 
443  CLFFTAPI clfftStatus clfftGetPlanOutStride( const clfftPlanHandle plHandle, const clfftDim dim, size_t* clStrides );
444 
454  CLFFTAPI clfftStatus clfftSetPlanOutStride( clfftPlanHandle plHandle, const clfftDim dim, size_t* clStrides );
455 
465  CLFFTAPI clfftStatus clfftGetPlanDistance( const clfftPlanHandle plHandle, size_t* iDist, size_t* oDist );
466 
476  CLFFTAPI clfftStatus clfftSetPlanDistance( clfftPlanHandle plHandle, size_t iDist, size_t oDist );
477 
485  CLFFTAPI clfftStatus clfftGetLayout( const clfftPlanHandle plHandle, clfftLayout* iLayout, clfftLayout* oLayout );
486 
494  CLFFTAPI clfftStatus clfftSetLayout( clfftPlanHandle plHandle, clfftLayout iLayout, clfftLayout oLayout );
495 
503  CLFFTAPI clfftStatus clfftGetResultLocation( const clfftPlanHandle plHandle, clfftResultLocation* placeness );
504 
512  CLFFTAPI clfftStatus clfftSetResultLocation( clfftPlanHandle plHandle, clfftResultLocation placeness );
513 
521  CLFFTAPI clfftStatus clfftGetPlanTransposeResult( const clfftPlanHandle plHandle, clfftResultTransposed * transposed );
522 
531 
532 
540  CLFFTAPI clfftStatus clfftGetTmpBufSize( const clfftPlanHandle plHandle, size_t* buffersize );
541 
564  CLFFTAPI clfftStatus clfftEnqueueTransform(
565  clfftPlanHandle plHandle,
566  clfftDirection dir,
567  cl_uint numQueuesAndEvents,
568  cl_command_queue* commQueues,
569  cl_uint numWaitEvents,
570  const cl_event* waitEvents,
571  cl_event* outEvents,
572  cl_mem* inputBuffers,
573  cl_mem* outputBuffers,
574  cl_mem tmpBuffer
575  );
576 
577 #ifdef __cplusplus
578 }
579 #endif
580 
581 #endif
Definition: clFFT.h:138
clfftResultTransposed
This determines whether the result is returned in original order. It is valid only for dimensions gre...
Definition: clFFT.h:186
clfftDirection
What is the expected direction of each FFT, time or the frequency domains.
Definition: clFFT.h:167
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:72
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:147
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:56
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:141
Definition: clFFT.h:123
Definition: clFFT.h:163
cl_uint major
Definition: clFFT.h:202
Definition: clFFT.h:160
Data structure that can be passed to clfftSetup() to control the behavior of the FFT runtime...
Definition: clFFT.h:200
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:126
Definition: clFFT.h:170
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:125
cl_uint patch
Definition: clFFT.h:204
Definition: clFFT.h:151
Definition: clFFT.h:139
CLFFTAPI clfftStatus clfftSetPlanPrecision(clfftPlanHandle plHandle, clfftPrecision precision)
Set the floating point precision of the FFT data.
Definition: clFFT.h:150
Definition: clFFT.h:127
Definition: clFFT.h:130
Definition: clFFT.h:124
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:171
Definition: clFFT.h:173
Definition: clFFT.h:161
CLFFTAPI clfftStatus clfftCopyPlan(clfftPlanHandle *out_plHandle, cl_context new_context, clfftPlanHandle in_plHandle)
Create a copy of an existing plan.
Definition: clFFT.h:172
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:203
Definition: clFFT.h:149
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:225
CLFFTAPI clfftStatus clfftGetVersion(cl_uint *major, cl_uint *minor, cl_uint *patch)
Query the FFT library for version information.
Definition: clFFT.h:169
CLFFTAPI clfftStatus clfftSetPlanLength(clfftPlanHandle plHandle, const clfftDim dim, const size_t *clLengths)
Set the length of each dimension of the FFT.
Definition: clFFT.h:188
Definition: clFFT.h:179
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:159
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:152
size_t clfftPlanHandle
An abstract handle to the object that represents the state of the FFT(s)
Definition: clFFT.h:215
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:145
Definition: clFFT.h:148
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:187
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:128
clfftResultLocation
Are the input buffers overwritten with the results.
Definition: clFFT.h:177
Definition: clFFT.h:122
cl_ulong debugFlags
Definition: clFFT.h:207
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:181
Definition: clFFT.h:162
Definition: clFFT.h:180
Definition: clFFT.h:140
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:157
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:129
Definition: clFFT.h:189
clfftDim
The dimension of the input and output buffers that will be fed into all FFT transforms.
Definition: clFFT.h:136