clFFT.h 8.78 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
/***************************************************************************
 *   Copyright (C) 2012 by Oliver Bock,Heinz-Bernd Eggenstein              *
 *   oliver.bock[AT]aei.mpg.de                                             *
 *   heinz-bernd.eggenstein[AT]aei.mpg.de                                  *
 *                                                                         *
 *   This file is part of libclfft (originally for Einstein@Home)          *
 *   Derived from clFFT,  (C) Apple, see notice below.                     *
 *                                                                         *
 *                                                                         *
 *   libclfft  is distributed in the hope that it will be useful,          *
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See              *
 *   notice below for more details.                                        *
 *                                                                         *
 ***************************************************************************/
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
//
// File:       clFFT.h
//
// Version:    <1.0>
//
// Disclaimer: IMPORTANT:  This Apple software is supplied to you by Apple Inc. ("Apple")
//             in consideration of your agreement to the following terms, and your use,
//             installation, modification or redistribution of this Apple software
//             constitutes acceptance of these terms.  If you do not agree with these
//             terms, please do not use, install, modify or redistribute this Apple
//             software.
//
//             In consideration of your agreement to abide by the following terms, and
//             subject to these terms, Apple grants you a personal, non - exclusive
//             license, under Apple's copyrights in this original Apple software ( the
//             "Apple Software" ), to use, reproduce, modify and redistribute the Apple
//             Software, with or without modifications, in source and / or binary forms;
//             provided that if you redistribute the Apple Software in its entirety and
//             without modifications, you must retain this notice and the following text
//             and disclaimers in all such redistributions of the Apple Software. Neither
//             the name, trademarks, service marks or logos of Apple Inc. may be used to
//             endorse or promote products derived from the Apple Software without specific
//             prior written permission from Apple.  Except as expressly stated in this
//             notice, no other rights or licenses, express or implied, are granted by
//             Apple herein, including but not limited to any patent rights that may be
//             infringed by your derivative works or by other works in which the Apple
//             Software may be incorporated.
//
//             The Apple Software is provided by Apple on an "AS IS" basis.  APPLE MAKES NO
//             WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED
//             WARRANTIES OF NON - INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A
//             PARTICULAR PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND OPERATION
//             ALONE OR IN COMBINATION WITH YOUR PRODUCTS.
//
//             IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR
//             CONSEQUENTIAL DAMAGES ( INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
//             SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
//             INTERRUPTION ) ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION
//             AND / OR DISTRIBUTION OF THE APPLE SOFTWARE, HOWEVER CAUSED AND WHETHER
//             UNDER THEORY OF CONTRACT, TORT ( INCLUDING NEGLIGENCE ), STRICT LIABILITY OR
//             OTHERWISE, EVEN IF APPLE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
// Copyright ( C ) 2008 Apple Inc. All Rights Reserved.
//
////////////////////////////////////////////////////////////////////////////////////////////////////


#ifndef __CLFFT_H
#define __CLFFT_H

66
67
68
69
70
71
72
#include <stdio.h>
#ifdef __APPLE__
    #include <OpenCL/cl.h>
#else
    #include <CL/cl.h>
#endif

73
74
#ifdef __cplusplus
extern "C" {
75
76
#endif

77
// XForm type
Oliver Bock's avatar
Oliver Bock committed
78
typedef enum
79
{
Oliver Bock's avatar
Oliver Bock committed
80
81
    clFFT_Forward   =   -1,
    clFFT_Inverse   =    1
Oliver Bock's avatar
Oliver Bock committed
82

83
84
85
86
87
}clFFT_Direction;

// XForm dimension
typedef enum
{
Oliver Bock's avatar
Oliver Bock committed
88
89
90
    clFFT_1D    = 0,
    clFFT_2D    = 1,
    clFFT_3D    = 3
Oliver Bock's avatar
Oliver Bock committed
91

92
93
94
95
96
}clFFT_Dimension;

// XForm Data type
typedef enum
{
Oliver Bock's avatar
Oliver Bock committed
97
98
    clFFT_SplitComplexFormat       = 0,
    clFFT_InterleavedComplexFormat = 1
99
100
}clFFT_DataFormat;

101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
// enum for twiddle factor method selection (essentially different methods to evaluate 
// sin(x) and cos(x) on a grid x_k= 2*pi*k/N for some N, k=0..N-1 )
//
// clFFT_native_trig    : the original method, using native_sin, native_cos
//                      : NOTE: precision is hardware dependent, see OpenCL 1.1 spec
// clFFT_sincosfunc     : alternative method using sincos function (slow in most 
//                      : implementations, accuracy as defined in OpenCL 1.1 spec
// clFFT_BigLUT         : alternative version using Lookup tables stored as part of the 
//                      : plan. The LUTs size grow with O(sqrt(N)) , where N is the 
//                      : total size of the transform (over all dimensions). This should 
//                      : be the most accurate option and have much better performance than 
//                      : with option clFFT_sincosfunc
// clFFT_TaylorLUT      : alternative method using a constant size Look-Up-Table and Taylor
//                      : series approx of sin,cos 
// clFFT_RFU{n}         : reserved for future use, so that clFFT_TwiddleFactorMethod may use
//                      : the lower 3 bits of the flags argument to clFFT_CreatePlanAdv. 
//                      : All options are mutually exclusive. 
     

120
121
122
123
124
typedef enum 
{
  clFFT_native_trig       = 0,
  clFFT_sincosfunc        = 1,
  clFFT_BigLUT            = 2,
125
126
127
128
129
  clFFT_TaylorLUT         = 3,
  clFFT_RFU4              = 4,
  clFFT_RFU5              = 5,   
  clFFT_RFU6              = 6,  
  clFFT_RFU7              = 7    
130
131
} clFFT_TwiddleFactorMethod;

132
133
typedef struct
{
Oliver Bock's avatar
Oliver Bock committed
134
135
136
    unsigned int x;
    unsigned int y;
    unsigned int z;
Oliver Bock's avatar
Oliver Bock committed
137
138
}clFFT_Dim3;

139
140
typedef struct
{
Oliver Bock's avatar
Oliver Bock committed
141
142
    float *real;
    float *imag;
143
144
145
146
} clFFT_SplitComplex;

typedef struct
{
Oliver Bock's avatar
Oliver Bock committed
147
148
    float real;
    float imag;
149
150
}clFFT_Complex;

Oliver Bock's avatar
Oliver Bock committed
151
typedef void* clFFT_Plan;
152
153
154

clFFT_Plan clFFT_CreatePlan( cl_context context, clFFT_Dim3 n, clFFT_Dimension dim, clFFT_DataFormat dataFormat, cl_int *error_code );

155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
/**
 *  Extended plan constructor, allows to specify plan options in the flags parameter.  
 *  Currently only values of the enumeration clFFT_TwiddleFactorMethod are supported to 
 *  choose the method for twiddle factor computations. 
 *
 *  Param:
 *        context   : cl_context to use
 *        n         : transform lengths in (up to) 3 dimensions
 *        dim       : dimension of the transform
 *        dataFormat: see  clFFT_DataFormat type
 *        flags     : plan generation options. Use OR to specify more than one option 
 *                    (currently only the mutually exclusive enumeration values of 
 *                    clFFT_TwiddleFactorMethod are supported) 
 *        error_code: pointer to error code, in case of error
 *
 *  Returns:
 *        freshly allocated clFFT_Plan object holding the plan for the specified transform.
 *        Can be reused for several FFT plan executions. 
 *        The caller is responsible to deallocate this object after use.   
 */

176
177
clFFT_Plan clFFT_CreatePlanAdv( cl_context context, clFFT_Dim3 n, clFFT_Dimension dim, clFFT_DataFormat dataFormat, unsigned long flags, cl_int *error_code );

178
179
void clFFT_DestroyPlan( clFFT_Plan plan );

Oliver Bock's avatar
Oliver Bock committed
180
cl_int clFFT_ExecuteInterleaved( cl_command_queue queue, clFFT_Plan plan, cl_int batchSize, clFFT_Direction dir,
Oliver Bock's avatar
Oliver Bock committed
181
182
                                 cl_mem data_in, cl_mem data_out,
                                 cl_int num_events, cl_event *event_list, cl_event *event );
183

Oliver Bock's avatar
Oliver Bock committed
184
cl_int clFFT_ExecutePlannar( cl_command_queue queue, clFFT_Plan plan, cl_int batchSize, clFFT_Direction dir,
Oliver Bock's avatar
Oliver Bock committed
185
186
                             cl_mem data_in_real, cl_mem data_in_imag, cl_mem data_out_real, cl_mem data_out_imag,
                             cl_int num_events, cl_event *event_list, cl_event *event );
187

Oliver Bock's avatar
Oliver Bock committed
188
cl_int clFFT_1DTwistInterleaved(clFFT_Plan Plan, cl_command_queue queue, cl_mem array,
Oliver Bock's avatar
Oliver Bock committed
189
                                size_t numRows, size_t numCols, size_t startRow, size_t rowsToProcess, clFFT_Direction dir);
190

Oliver Bock's avatar
Oliver Bock committed
191
192

cl_int clFFT_1DTwistPlannar(clFFT_Plan Plan, cl_command_queue queue, cl_mem array_real, cl_mem array_imag,
Oliver Bock's avatar
Oliver Bock committed
193
                            size_t numRows, size_t numCols, size_t startRow, size_t rowsToProcess, clFFT_Direction dir);
Oliver Bock's avatar
Oliver Bock committed
194
195

void clFFT_DumpPlan( clFFT_Plan plan, FILE *file);
196
197
198
199
200

#ifdef __cplusplus
}
#endif

Oliver Bock's avatar
Oliver Bock committed
201
#endif