clFFT 2.0
 
Loading...
Searching...
No Matches
clFFT.h
Go to the documentation of this file.
1/* ************************************************************************
2 * Copyright 2013-2015 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 cannot use namespaces for strict C compliance, so we prefix our public accessible names
62 * with the string clfft
63 */
64
65/* All functions return pre-defined error codes, and do 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 /* The last value of the enum, and marks the length of clfftStatus. */
134};
135typedef enum clfftStatus_ clfftStatus;
136
138typedef enum clfftDim_
139{
145
156
167
169typedef enum clfftDirection_
170{
177
179typedef enum clfftResultLocation_
180{
183 ENDPLACE
185
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};
214typedef struct clfftSetupData_ clfftSetupData;
215
218typedef enum clfftCallbackType_
219{
223
225typedef size_t clfftPlanHandle;
226
227#ifdef __cplusplus
228extern "C" {
229#endif
235 __inline clfftStatus clfftInitSetupData( clfftSetupData* setupData )
236 {
237 setupData->major = clfftVersionMajor;
238 setupData->minor = clfftVersionMinor;
239 setupData->patch = clfftVersionPatch;
240 setupData->debugFlags = 0;
241
242 return CLFFT_SUCCESS;
243 }
244
251 CLFFTAPI clfftStatus clfftSetup( const clfftSetupData* setupData );
252
257 CLFFTAPI clfftStatus clfftTeardown( );
258
266 CLFFTAPI clfftStatus clfftGetVersion( cl_uint* major, cl_uint* minor, cl_uint* patch );
267
277 CLFFTAPI clfftStatus clfftCreateDefaultPlan( clfftPlanHandle* plHandle, cl_context context, const clfftDim dim,
278 const size_t* clLengths );
279
288 CLFFTAPI clfftStatus clfftCopyPlan( clfftPlanHandle* out_plHandle, cl_context new_context, clfftPlanHandle in_plHandle );
289
314 CLFFTAPI clfftStatus clfftBakePlan( clfftPlanHandle plHandle, cl_uint numQueues, cl_command_queue* commQueueFFT,
315 void (CL_CALLBACK *pfn_notify)(clfftPlanHandle plHandle, void *user_data), void* user_data );
316
323 CLFFTAPI clfftStatus clfftDestroyPlan( clfftPlanHandle* plHandle );
324
332 CLFFTAPI clfftStatus clfftGetPlanContext( const clfftPlanHandle plHandle, cl_context* context );
333
341 CLFFTAPI clfftStatus clfftGetPlanPrecision( const clfftPlanHandle plHandle, clfftPrecision* precision );
342
350
359 CLFFTAPI clfftStatus clfftGetPlanScale( const clfftPlanHandle plHandle, clfftDirection dir, cl_float* scale );
360
369 CLFFTAPI clfftStatus clfftSetPlanScale( clfftPlanHandle plHandle, clfftDirection dir, cl_float scale );
370
378 CLFFTAPI clfftStatus clfftGetPlanBatchSize( const clfftPlanHandle plHandle, size_t* batchSize );
379
387 CLFFTAPI clfftStatus clfftSetPlanBatchSize( clfftPlanHandle plHandle, size_t batchSize );
388
397 CLFFTAPI clfftStatus clfftGetPlanDim( const clfftPlanHandle plHandle, clfftDim* dim, cl_uint* size );
398
405 CLFFTAPI clfftStatus clfftSetPlanDim( clfftPlanHandle plHandle, const clfftDim dim );
406
415 CLFFTAPI clfftStatus clfftGetPlanLength( const clfftPlanHandle plHandle, const clfftDim dim, size_t* clLengths );
416
424 CLFFTAPI clfftStatus clfftSetPlanLength( clfftPlanHandle plHandle, const clfftDim dim, const size_t* clLengths );
425
433 CLFFTAPI clfftStatus clfftGetPlanInStride( const clfftPlanHandle plHandle, const clfftDim dim, size_t* clStrides );
434
444 CLFFTAPI clfftStatus clfftSetPlanInStride( clfftPlanHandle plHandle, const clfftDim dim, size_t* clStrides );
445
453 CLFFTAPI clfftStatus clfftGetPlanOutStride( const clfftPlanHandle plHandle, const clfftDim dim, size_t* clStrides );
454
464 CLFFTAPI clfftStatus clfftSetPlanOutStride( clfftPlanHandle plHandle, const clfftDim dim, size_t* clStrides );
465
475 CLFFTAPI clfftStatus clfftGetPlanDistance( const clfftPlanHandle plHandle, size_t* iDist, size_t* oDist );
476
486 CLFFTAPI clfftStatus clfftSetPlanDistance( clfftPlanHandle plHandle, size_t iDist, size_t oDist );
487
495 CLFFTAPI clfftStatus clfftGetLayout( const clfftPlanHandle plHandle, clfftLayout* iLayout, clfftLayout* oLayout );
496
504 CLFFTAPI clfftStatus clfftSetLayout( clfftPlanHandle plHandle, clfftLayout iLayout, clfftLayout oLayout );
505
513 CLFFTAPI clfftStatus clfftGetResultLocation( const clfftPlanHandle plHandle, clfftResultLocation* placeness );
514
523
532
541
542
550 CLFFTAPI clfftStatus clfftGetTmpBufSize( const clfftPlanHandle plHandle, size_t* buffersize );
551
565 CLFFTAPI clfftStatus clfftSetPlanCallback(clfftPlanHandle plHandle, const char* funcName, const char* funcString,
566 int localMemSize, clfftCallbackType callbackType, cl_mem *userdata, int numUserdataBuffers);
567
568
592 clfftPlanHandle plHandle,
593 clfftDirection dir,
594 cl_uint numQueuesAndEvents,
595 cl_command_queue* commQueues,
596 cl_uint numWaitEvents,
597 const cl_event* waitEvents,
598 cl_event* outEvents,
599 cl_mem* inputBuffers,
600 cl_mem* outputBuffers,
601 cl_mem tmpBuffer
602 );
603
604#ifdef __cplusplus
605}
606#endif
607
608#endif
clfftDirection
Specify the expected direction of each FFT, time or the frequency domains.
Definition clFFT.h:170
@ ENDDIRECTION
Definition clFFT.h:175
@ CLFFT_FORWARD
Definition clFFT.h:171
@ CLFFT_BACKWARD
Definition clFFT.h:172
@ CLFFT_PLUS
Definition clFFT.h:174
@ CLFFT_MINUS
Definition clFFT.h:173
CLFFTAPI clfftStatus clfftGetPlanContext(const clfftPlanHandle plHandle, cl_context *context)
Retrieve the OpenCL context of a previously created plan.
clfftPrecision
Specify the expected precision of each FFT.
Definition clFFT.h:160
@ CLFFT_DOUBLE
Definition clFFT.h:162
@ CLFFT_DOUBLE_FAST
Definition clFFT.h:164
@ CLFFT_SINGLE
Definition clFFT.h:161
@ ENDPRECISION
Definition clFFT.h:165
@ CLFFT_SINGLE_FAST
Definition clFFT.h:163
__inline clfftStatus clfftInitSetupData(clfftSetupData *setupData)
Initialize a clfftSetupData struct for the client.
Definition clFFT.h:235
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 clfftSetPlanLength(clfftPlanHandle plHandle, const clfftDim dim, const size_t *clLengths)
Set the length of each dimension of the FFT.
CLFFTAPI clfftStatus clfftGetPlanOutStride(const clfftPlanHandle plHandle, const clfftDim dim, size_t *clStrides)
Retrieve the distance between consecutive elements of output buffers in each dimension.
clfftCallbackType
Type of Callback function.
Definition clFFT.h:219
@ POSTCALLBACK
Definition clFFT.h:221
@ PRECALLBACK
Definition clFFT.h:220
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 clfftSetup(const clfftSetupData *setupData)
Initialize the internal FFT resources.
CLFFTAPI clfftStatus clfftGetResultLocation(const clfftPlanHandle plHandle, clfftResultLocation *placeness)
Retrieve whether the input buffers are to be overwritten with results.
CLFFTAPI clfftStatus clfftCopyPlan(clfftPlanHandle *out_plHandle, cl_context new_context, clfftPlanHandle in_plHandle)
Create a copy of an existing plan.
CLFFTAPI clfftStatus clfftSetResultLocation(clfftPlanHandle plHandle, clfftResultLocation placeness)
Set whether the input buffers are to be overwritten with results.
CLFFTAPI clfftStatus clfftSetLayout(clfftPlanHandle plHandle, clfftLayout iLayout, clfftLayout oLayout)
Set the expected layout of the input and output buffers.
CLFFTAPI clfftStatus clfftSetPlanBatchSize(clfftPlanHandle plHandle, size_t batchSize)
Set the number of discrete arrays that the plan can concurrently handle.
clfftStatus_
clfft error codes definition(incorporating OpenCL error definitions)
Definition clFFT.h:75
@ CLFFT_DEVICE_MISMATCH
Definition clFFT.h:132
@ CLFFT_VERSION_MISMATCH
Definition clFFT.h:129
@ CLFFT_BUGCHECK
Definition clFFT.h:124
@ CLFFT_DEVICE_NO_DOUBLE
Definition clFFT.h:131
@ CLFFT_INVALID_PLAN
Definition clFFT.h:130
@ CLFFT_FILE_CREATE_FAILURE
Definition clFFT.h:128
@ CLFFT_NOTIMPLEMENTED
Definition clFFT.h:125
@ CLFFT_FILE_NOT_FOUND
Definition clFFT.h:127
@ CLFFT_TRANSPOSED_NOTIMPLEMENTED
Definition clFFT.h:126
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 clfftGetPlanDistance(const clfftPlanHandle plHandle, size_t *iDist, size_t *oDist)
Retrieve the distance between array objects.
CLFFTAPI clfftStatus clfftGetPlanTransposeResult(const clfftPlanHandle plHandle, clfftResultTransposed *transposed)
Retrieve the final transpose setting of a multi-dimensional FFT.
clfftLayout
Specify the expected layouts of the buffers.
Definition clFFT.h:148
@ ENDLAYOUT
Definition clFFT.h:154
@ CLFFT_COMPLEX_INTERLEAVED
Definition clFFT.h:149
@ CLFFT_HERMITIAN_PLANAR
Definition clFFT.h:152
@ CLFFT_REAL
Definition clFFT.h:153
@ CLFFT_COMPLEX_PLANAR
Definition clFFT.h:150
@ CLFFT_HERMITIAN_INTERLEAVED
Definition clFFT.h:151
CLFFTAPI clfftStatus clfftSetPlanTransposeResult(clfftPlanHandle plHandle, clfftResultTransposed transposed)
Set the final transpose setting of a multi-dimensional FFT.
CLFFTAPI clfftStatus clfftGetPlanLength(const clfftPlanHandle plHandle, const clfftDim dim, size_t *clLengths)
Retrieve the length of each dimension of the FFT.
CLFFTAPI clfftStatus clfftGetPlanPrecision(const clfftPlanHandle plHandle, clfftPrecision *precision)
Retrieve the floating point precision of the FFT data.
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 clfftTeardown()
Release all internal resources.
CLFFTAPI clfftStatus clfftDestroyPlan(clfftPlanHandle *plHandle)
Release the resources of a plan.
clfftResultTransposed
Determines whether the result is returned in original order. It is valid only for dimensions greater ...
Definition clFFT.h:188
@ CLFFT_TRANSPOSED
Definition clFFT.h:190
@ ENDTRANSPOSED
Definition clFFT.h:191
@ CLFFT_NOTRANSPOSE
Definition clFFT.h:189
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)
CLFFTAPI clfftStatus clfftSetPlanPrecision(clfftPlanHandle plHandle, clfftPrecision precision)
Set the floating point precision of the FFT data.
CLFFTAPI clfftStatus clfftSetPlanDim(clfftPlanHandle plHandle, const clfftDim dim)
Set the dimensionality of the data that is transformed.
clfftDim
The dimension of the input and output buffers that is fed into all FFT transforms.
Definition clFFT.h:139
@ CLFFT_2D
Definition clFFT.h:141
@ CLFFT_3D
Definition clFFT.h:142
@ CLFFT_1D
Definition clFFT.h:140
@ ENDDIMENSION
Definition clFFT.h:143
CLFFTAPI clfftStatus clfftSetPlanOutStride(clfftPlanHandle plHandle, const clfftDim dim, size_t *clStrides)
Set the distance between consecutive elements of output buffers in a dimension.
#define CLFFTAPI
Definition clFFT.h:58
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 clfftSetPlanScale(clfftPlanHandle plHandle, clfftDirection dir, cl_float scale)
Set the scaling factor that is applied to the FFT data.
clfftResultLocation
Specify wheter the input buffers are overwritten with results.
Definition clFFT.h:180
@ ENDPLACE
Definition clFFT.h:183
@ CLFFT_OUTOFPLACE
Definition clFFT.h:182
@ CLFFT_INPLACE
Definition clFFT.h:181
CLFFTAPI clfftStatus clfftGetPlanDim(const clfftPlanHandle plHandle, clfftDim *dim, cl_uint *size)
Retrieve the dimensionality of the data that is transformed.
CLFFTAPI clfftStatus clfftGetLayout(const clfftPlanHandle plHandle, clfftLayout *iLayout, clfftLayout *oLayout)
Retrieve the expected layout of the input and output buffers.
CLFFTAPI clfftStatus clfftGetPlanBatchSize(const clfftPlanHandle plHandle, size_t *batchSize)
Retrieve the number of discrete arrays that the plan can concurrently handle.
CLFFTAPI clfftStatus clfftGetPlanScale(const clfftPlanHandle plHandle, clfftDirection dir, cl_float *scale)
Retrieve the scaling factor that is applied to the FFT data.
CLFFTAPI clfftStatus clfftSetPlanDistance(clfftPlanHandle plHandle, size_t iDist, size_t oDist)
Set the distance between array objects.
size_t clfftPlanHandle
An abstract handle to the object that represents the state of the FFT(s)
Definition clFFT.h:225
Data structure that can be passed to clfftSetup() to control the behavior of the FFT runtime.
Definition clFFT.h:203
cl_uint major
Definition clFFT.h:204
cl_uint patch
Definition clFFT.h:206
cl_ulong debugFlags
Definition clFFT.h:209
cl_uint minor
Definition clFFT.h:205