Mercurial > hg > sv-dependency-builds

comparison src/fftw-3.3.8/api/fftw3.h @ 167:bd3cc4d1df30

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add FFTW 3.3.8 source, and a Linux build
author Chris Cannam <cannam@all-day-breakfast.com>
date Tue, 19 Nov 2019 14:52:55 +0000
parents
children
comparison
equal deleted inserted replaced
166:cbd6d7e562c7 167:bd3cc4d1df30
1 /*
2 * Copyright (c) 2003, 2007-14 Matteo Frigo
3 * Copyright (c) 2003, 2007-14 Massachusetts Institute of Technology
4 *
5 * The following statement of license applies *only* to this header file,
6 * and *not* to the other files distributed with FFTW or derived therefrom:
7 *
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
10 * are met:
11 *
12 * 1. Redistributions of source code must retain the above copyright
13 * notice, this list of conditions and the following disclaimer.
14 *
15 * 2. Redistributions in binary form must reproduce the above copyright
16 * notice, this list of conditions and the following disclaimer in the
17 * documentation and/or other materials provided with the distribution.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
20 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
21 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
23 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
25 * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
27 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
28 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
29 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 */
31
32 /***************************** NOTE TO USERS *********************************
33 *
34 * THIS IS A HEADER FILE, NOT A MANUAL
35 *
36 * If you want to know how to use FFTW, please read the manual,
37 * online at http://www.fftw.org/doc/ and also included with FFTW.
38 * For a quick start, see the manual's tutorial section.
39 *
40 * (Reading header files to learn how to use a library is a habit
41 * stemming from code lacking a proper manual. Arguably, it's a
42 * *bad* habit in most cases, because header files can contain
43 * interfaces that are not part of the public, stable API.)
44 *
45 ****************************************************************************/
46
47 #ifndef FFTW3_H
48 #define FFTW3_H
49
50 #include <stdio.h>
51
52 #ifdef __cplusplus
53 extern "C"
54 {
55 #endif /* __cplusplus */
56
57 /* If <complex.h> is included, use the C99 complex type. Otherwise
58 define a type bit-compatible with C99 complex */
59 #if !defined(FFTW_NO_Complex) && defined(_Complex_I) && defined(complex) && defined(I)
60 # define FFTW_DEFINE_COMPLEX(R, C) typedef R _Complex C
61 #else
62 # define FFTW_DEFINE_COMPLEX(R, C) typedef R C[2]
63 #endif
64
65 #define FFTW_CONCAT(prefix, name) prefix ## name
66 #define FFTW_MANGLE_DOUBLE(name) FFTW_CONCAT(fftw_, name)
67 #define FFTW_MANGLE_FLOAT(name) FFTW_CONCAT(fftwf_, name)
68 #define FFTW_MANGLE_LONG_DOUBLE(name) FFTW_CONCAT(fftwl_, name)
69 #define FFTW_MANGLE_QUAD(name) FFTW_CONCAT(fftwq_, name)
70
71 /* IMPORTANT: for Windows compilers, you should add a line
72 #define FFTW_DLL
73 here and in kernel/ifftw.h if you are compiling/using FFTW as a
74 DLL, in order to do the proper importing/exporting, or
75 alternatively compile with -DFFTW_DLL or the equivalent
76 command-line flag. This is not necessary under MinGW/Cygwin, where
77 libtool does the imports/exports automatically. */
78 #if defined(FFTW_DLL) && (defined(_WIN32) || defined(__WIN32__))
79 /* annoying Windows syntax for shared-library declarations */
80 # if defined(COMPILING_FFTW) /* defined in api.h when compiling FFTW */
81 # define FFTW_EXTERN extern __declspec(dllexport)
82 # else /* user is calling FFTW; import symbol */
83 # define FFTW_EXTERN extern __declspec(dllimport)
84 # endif
85 #else
86 # define FFTW_EXTERN extern
87 #endif
88
89 /* specify calling convention (Windows only) */
90 #if defined(_WIN32) || defined(__WIN32__)
91 # define FFTW_CDECL __cdecl
92 #else
93 # define FFTW_CDECL
94 #endif
95
96 enum fftw_r2r_kind_do_not_use_me {
97 FFTW_R2HC=0, FFTW_HC2R=1, FFTW_DHT=2,
98 FFTW_REDFT00=3, FFTW_REDFT01=4, FFTW_REDFT10=5, FFTW_REDFT11=6,
99 FFTW_RODFT00=7, FFTW_RODFT01=8, FFTW_RODFT10=9, FFTW_RODFT11=10
100 };
101
102 struct fftw_iodim_do_not_use_me {
103 int n; /* dimension size */
104 int is; /* input stride */
105 int os; /* output stride */
106 };
107
108 #include <stddef.h> /* for ptrdiff_t */
109 struct fftw_iodim64_do_not_use_me {
110 ptrdiff_t n; /* dimension size */
111 ptrdiff_t is; /* input stride */
112 ptrdiff_t os; /* output stride */
113 };
114
115 typedef void (FFTW_CDECL *fftw_write_char_func_do_not_use_me)(char c, void *);
116 typedef int (FFTW_CDECL *fftw_read_char_func_do_not_use_me)(void *);
117
118 /*
119 huge second-order macro that defines prototypes for all API
120 functions. We expand this macro for each supported precision
121
122 X: name-mangling macro
123 R: real data type
124 C: complex data type
125 */
126
127 #define FFTW_DEFINE_API(X, R, C) \
128 \
129 FFTW_DEFINE_COMPLEX(R, C); \
130 \
131 typedef struct X(plan_s) *X(plan); \
132 \
133 typedef struct fftw_iodim_do_not_use_me X(iodim); \
134 typedef struct fftw_iodim64_do_not_use_me X(iodim64); \
135 \
136 typedef enum fftw_r2r_kind_do_not_use_me X(r2r_kind); \
137 \
138 typedef fftw_write_char_func_do_not_use_me X(write_char_func); \
139 typedef fftw_read_char_func_do_not_use_me X(read_char_func); \
140 \
141 FFTW_EXTERN void \
142 FFTW_CDECL X(execute)(const X(plan) p); \
143 \
144 FFTW_EXTERN X(plan) \
145 FFTW_CDECL X(plan_dft)(int rank, const int *n, \
146 C *in, C *out, int sign, unsigned flags); \
147 \
148 FFTW_EXTERN X(plan) \
149 FFTW_CDECL X(plan_dft_1d)(int n, C *in, C *out, int sign, \
150 unsigned flags); \
151 FFTW_EXTERN X(plan) \
152 FFTW_CDECL X(plan_dft_2d)(int n0, int n1, \
153 C *in, C *out, int sign, unsigned flags); \
154 FFTW_EXTERN X(plan) \
155 FFTW_CDECL X(plan_dft_3d)(int n0, int n1, int n2, \
156 C *in, C *out, int sign, unsigned flags); \
157 \
158 FFTW_EXTERN X(plan) \
159 FFTW_CDECL X(plan_many_dft)(int rank, const int *n, \
160 int howmany, \
161 C *in, const int *inembed, \
162 int istride, int idist, \
163 C *out, const int *onembed, \
164 int ostride, int odist, \
165 int sign, unsigned flags); \
166 \
167 FFTW_EXTERN X(plan) \
168 FFTW_CDECL X(plan_guru_dft)(int rank, const X(iodim) *dims, \
169 int howmany_rank, \
170 const X(iodim) *howmany_dims, \
171 C *in, C *out, \
172 int sign, unsigned flags); \
173 FFTW_EXTERN X(plan) \
174 FFTW_CDECL X(plan_guru_split_dft)(int rank, const X(iodim) *dims, \
175 int howmany_rank, \
176 const X(iodim) *howmany_dims, \
177 R *ri, R *ii, R *ro, R *io, \
178 unsigned flags); \
179 \
180 FFTW_EXTERN X(plan) \
181 FFTW_CDECL X(plan_guru64_dft)(int rank, \
182 const X(iodim64) *dims, \
183 int howmany_rank, \
184 const X(iodim64) *howmany_dims, \
185 C *in, C *out, \
186 int sign, unsigned flags); \
187 FFTW_EXTERN X(plan) \
188 FFTW_CDECL X(plan_guru64_split_dft)(int rank, \
189 const X(iodim64) *dims, \
190 int howmany_rank, \
191 const X(iodim64) *howmany_dims, \
192 R *ri, R *ii, R *ro, R *io, \
193 unsigned flags); \
194 \
195 FFTW_EXTERN void \
196 FFTW_CDECL X(execute_dft)(const X(plan) p, C *in, C *out); \
197 \
198 FFTW_EXTERN void \
199 FFTW_CDECL X(execute_split_dft)(const X(plan) p, R *ri, R *ii, \
200 R *ro, R *io); \
201 \
202 FFTW_EXTERN X(plan) \
203 FFTW_CDECL X(plan_many_dft_r2c)(int rank, const int *n, \
204 int howmany, \
205 R *in, const int *inembed, \
206 int istride, int idist, \
207 C *out, const int *onembed, \
208 int ostride, int odist, \
209 unsigned flags); \
210 \
211 FFTW_EXTERN X(plan) \
212 FFTW_CDECL X(plan_dft_r2c)(int rank, const int *n, \
213 R *in, C *out, unsigned flags); \
214 \
215 FFTW_EXTERN X(plan) \
216 FFTW_CDECL X(plan_dft_r2c_1d)(int n,R *in,C *out,unsigned flags); \
217 \
218 FFTW_EXTERN X(plan) \
219 FFTW_CDECL X(plan_dft_r2c_2d)(int n0, int n1, \
220 R *in, C *out, unsigned flags); \
221 \
222 FFTW_EXTERN X(plan) \
223 FFTW_CDECL X(plan_dft_r2c_3d)(int n0, int n1, \
224 int n2, \
225 R *in, C *out, unsigned flags); \
226 \
227 FFTW_EXTERN X(plan) \
228 FFTW_CDECL X(plan_many_dft_c2r)(int rank, const int *n, \
229 int howmany, \
230 C *in, const int *inembed, \
231 int istride, int idist, \
232 R *out, const int *onembed, \
233 int ostride, int odist, \
234 unsigned flags); \
235 \
236 FFTW_EXTERN X(plan) \
237 FFTW_CDECL X(plan_dft_c2r)(int rank, const int *n, \
238 C *in, R *out, unsigned flags); \
239 \
240 FFTW_EXTERN X(plan) \
241 FFTW_CDECL X(plan_dft_c2r_1d)(int n,C *in,R *out,unsigned flags); \
242 \
243 FFTW_EXTERN X(plan) \
244 FFTW_CDECL X(plan_dft_c2r_2d)(int n0, int n1, \
245 C *in, R *out, unsigned flags); \
246 \
247 FFTW_EXTERN X(plan) \
248 FFTW_CDECL X(plan_dft_c2r_3d)(int n0, int n1, \
249 int n2, \
250 C *in, R *out, unsigned flags); \
251 \
252 FFTW_EXTERN X(plan) \
253 FFTW_CDECL X(plan_guru_dft_r2c)(int rank, const X(iodim) *dims, \
254 int howmany_rank, \
255 const X(iodim) *howmany_dims, \
256 R *in, C *out, \
257 unsigned flags); \
258 \
259 FFTW_EXTERN X(plan) \
260 FFTW_CDECL X(plan_guru_dft_c2r)(int rank, const X(iodim) *dims, \
261 int howmany_rank, \
262 const X(iodim) *howmany_dims, \
263 C *in, R *out, \
264 unsigned flags); \
265 \
266 FFTW_EXTERN X(plan) \
267 FFTW_CDECL X(plan_guru_split_dft_r2c)(int rank, const X(iodim) *dims, \
268 int howmany_rank, \
269 const X(iodim) *howmany_dims, \
270 R *in, R *ro, R *io, \
271 unsigned flags); \
272 \
273 FFTW_EXTERN X(plan) \
274 FFTW_CDECL X(plan_guru_split_dft_c2r)(int rank, const X(iodim) *dims, \
275 int howmany_rank, \
276 const X(iodim) *howmany_dims, \
277 R *ri, R *ii, R *out, \
278 unsigned flags); \
279 \
280 FFTW_EXTERN X(plan) \
281 FFTW_CDECL X(plan_guru64_dft_r2c)(int rank, \
282 const X(iodim64) *dims, \
283 int howmany_rank, \
284 const X(iodim64) *howmany_dims, \
285 R *in, C *out, \
286 unsigned flags); \
287 \
288 FFTW_EXTERN X(plan) \
289 FFTW_CDECL X(plan_guru64_dft_c2r)(int rank, \
290 const X(iodim64) *dims, \
291 int howmany_rank, \
292 const X(iodim64) *howmany_dims, \
293 C *in, R *out, \
294 unsigned flags); \
295 \
296 FFTW_EXTERN X(plan) \
297 FFTW_CDECL X(plan_guru64_split_dft_r2c)(int rank, const X(iodim64) *dims, \
298 int howmany_rank, \
299 const X(iodim64) *howmany_dims, \
300 R *in, R *ro, R *io, \
301 unsigned flags); \
302 FFTW_EXTERN X(plan) \
303 FFTW_CDECL X(plan_guru64_split_dft_c2r)(int rank, const X(iodim64) *dims, \
304 int howmany_rank, \
305 const X(iodim64) *howmany_dims, \
306 R *ri, R *ii, R *out, \
307 unsigned flags); \
308 \
309 FFTW_EXTERN void \
310 FFTW_CDECL X(execute_dft_r2c)(const X(plan) p, R *in, C *out); \
311 \
312 FFTW_EXTERN void \
313 FFTW_CDECL X(execute_dft_c2r)(const X(plan) p, C *in, R *out); \
314 \
315 FFTW_EXTERN void \
316 FFTW_CDECL X(execute_split_dft_r2c)(const X(plan) p, \
317 R *in, R *ro, R *io); \
318 \
319 FFTW_EXTERN void \
320 FFTW_CDECL X(execute_split_dft_c2r)(const X(plan) p, \
321 R *ri, R *ii, R *out); \
322 \
323 FFTW_EXTERN X(plan) \
324 FFTW_CDECL X(plan_many_r2r)(int rank, const int *n, \
325 int howmany, \
326 R *in, const int *inembed, \
327 int istride, int idist, \
328 R *out, const int *onembed, \
329 int ostride, int odist, \
330 const X(r2r_kind) *kind, unsigned flags); \
331 \
332 FFTW_EXTERN X(plan) \
333 FFTW_CDECL X(plan_r2r)(int rank, const int *n, R *in, R *out, \
334 const X(r2r_kind) *kind, unsigned flags); \
335 \
336 FFTW_EXTERN X(plan) \
337 FFTW_CDECL X(plan_r2r_1d)(int n, R *in, R *out, \
338 X(r2r_kind) kind, unsigned flags); \
339 \
340 FFTW_EXTERN X(plan) \
341 FFTW_CDECL X(plan_r2r_2d)(int n0, int n1, R *in, R *out, \
342 X(r2r_kind) kind0, X(r2r_kind) kind1, \
343 unsigned flags); \
344 \
345 FFTW_EXTERN X(plan) \
346 FFTW_CDECL X(plan_r2r_3d)(int n0, int n1, int n2, \
347 R *in, R *out, X(r2r_kind) kind0, \
348 X(r2r_kind) kind1, X(r2r_kind) kind2, \
349 unsigned flags); \
350 \
351 FFTW_EXTERN X(plan) \
352 FFTW_CDECL X(plan_guru_r2r)(int rank, const X(iodim) *dims, \
353 int howmany_rank, \
354 const X(iodim) *howmany_dims, \
355 R *in, R *out, \
356 const X(r2r_kind) *kind, unsigned flags); \
357 \
358 FFTW_EXTERN X(plan) \
359 FFTW_CDECL X(plan_guru64_r2r)(int rank, const X(iodim64) *dims, \
360 int howmany_rank, \
361 const X(iodim64) *howmany_dims, \
362 R *in, R *out, \
363 const X(r2r_kind) *kind, unsigned flags); \
364 \
365 FFTW_EXTERN void \
366 FFTW_CDECL X(execute_r2r)(const X(plan) p, R *in, R *out); \
367 \
368 FFTW_EXTERN void \
369 FFTW_CDECL X(destroy_plan)(X(plan) p); \
370 \
371 FFTW_EXTERN void \
372 FFTW_CDECL X(forget_wisdom)(void); \
373 FFTW_EXTERN void \
374 FFTW_CDECL X(cleanup)(void); \
375 \
376 FFTW_EXTERN void \
377 FFTW_CDECL X(set_timelimit)(double t); \
378 \
379 FFTW_EXTERN void \
380 FFTW_CDECL X(plan_with_nthreads)(int nthreads); \
381 \
382 FFTW_EXTERN int \
383 FFTW_CDECL X(init_threads)(void); \
384 \
385 FFTW_EXTERN void \
386 FFTW_CDECL X(cleanup_threads)(void); \
387 \
388 FFTW_EXTERN void \
389 FFTW_CDECL X(make_planner_thread_safe)(void); \
390 \
391 FFTW_EXTERN int \
392 FFTW_CDECL X(export_wisdom_to_filename)(const char *filename); \
393 \
394 FFTW_EXTERN void \
395 FFTW_CDECL X(export_wisdom_to_file)(FILE *output_file); \
396 \
397 FFTW_EXTERN char * \
398 FFTW_CDECL X(export_wisdom_to_string)(void); \
399 \
400 FFTW_EXTERN void \
401 FFTW_CDECL X(export_wisdom)(X(write_char_func) write_char, \
402 void *data); \
403 FFTW_EXTERN int \
404 FFTW_CDECL X(import_system_wisdom)(void); \
405 \
406 FFTW_EXTERN int \
407 FFTW_CDECL X(import_wisdom_from_filename)(const char *filename); \
408 \
409 FFTW_EXTERN int \
410 FFTW_CDECL X(import_wisdom_from_file)(FILE *input_file); \
411 \
412 FFTW_EXTERN int \
413 FFTW_CDECL X(import_wisdom_from_string)(const char *input_string); \
414 \
415 FFTW_EXTERN int \
416 FFTW_CDECL X(import_wisdom)(X(read_char_func) read_char, void *data); \
417 \
418 FFTW_EXTERN void \
419 FFTW_CDECL X(fprint_plan)(const X(plan) p, FILE *output_file); \
420 \
421 FFTW_EXTERN void \
422 FFTW_CDECL X(print_plan)(const X(plan) p); \
423 \
424 FFTW_EXTERN char * \
425 FFTW_CDECL X(sprint_plan)(const X(plan) p); \
426 \
427 FFTW_EXTERN void * \
428 FFTW_CDECL X(malloc)(size_t n); \
429 \
430 FFTW_EXTERN R * \
431 FFTW_CDECL X(alloc_real)(size_t n); \
432 FFTW_EXTERN C * \
433 FFTW_CDECL X(alloc_complex)(size_t n); \
434 \
435 FFTW_EXTERN void \
436 FFTW_CDECL X(free)(void *p); \
437 \
438 FFTW_EXTERN void \
439 FFTW_CDECL X(flops)(const X(plan) p, \
440 double *add, double *mul, double *fmas); \
441 FFTW_EXTERN double \
442 FFTW_CDECL X(estimate_cost)(const X(plan) p); \
443 \
444 FFTW_EXTERN double \
445 FFTW_CDECL X(cost)(const X(plan) p); \
446 \
447 FFTW_EXTERN int \
448 FFTW_CDECL X(alignment_of)(R *p); \
449 \
450 FFTW_EXTERN const char X(version)[]; \
451 FFTW_EXTERN const char X(cc)[]; \
452 FFTW_EXTERN const char X(codelet_optim)[];
453
454
455 /* end of FFTW_DEFINE_API macro */
456
457 FFTW_DEFINE_API(FFTW_MANGLE_DOUBLE, double, fftw_complex)
458 FFTW_DEFINE_API(FFTW_MANGLE_FLOAT, float, fftwf_complex)
459 FFTW_DEFINE_API(FFTW_MANGLE_LONG_DOUBLE, long double, fftwl_complex)
460
461 /* __float128 (quad precision) is a gcc extension on i386, x86_64, and ia64
462 for gcc >= 4.6 (compiled in FFTW with --enable-quad-precision) */
463 #if (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)) \
464 && !(defined(__ICC) || defined(__INTEL_COMPILER) || defined(__CUDACC__) || defined(__PGI)) \
465 && (defined(__i386__) || defined(__x86_64__) || defined(__ia64__))
466 # if !defined(FFTW_NO_Complex) && defined(_Complex_I) && defined(complex) && defined(I)
467 /* note: __float128 is a typedef, which is not supported with the _Complex
468 keyword in gcc, so instead we use this ugly __attribute__ version.
469 However, we can't simply pass the __attribute__ version to
470 FFTW_DEFINE_API because the __attribute__ confuses gcc in pointer
471 types. Hence redefining FFTW_DEFINE_COMPLEX. Ugh. */
472 # undef FFTW_DEFINE_COMPLEX
473 # define FFTW_DEFINE_COMPLEX(R, C) typedef _Complex float __attribute__((mode(TC))) C
474 # endif
475 FFTW_DEFINE_API(FFTW_MANGLE_QUAD, __float128, fftwq_complex)
476 #endif
477
478 #define FFTW_FORWARD (-1)
479 #define FFTW_BACKWARD (+1)
480
481 #define FFTW_NO_TIMELIMIT (-1.0)
482
483 /* documented flags */
484 #define FFTW_MEASURE (0U)
485 #define FFTW_DESTROY_INPUT (1U << 0)
486 #define FFTW_UNALIGNED (1U << 1)
487 #define FFTW_CONSERVE_MEMORY (1U << 2)
488 #define FFTW_EXHAUSTIVE (1U << 3) /* NO_EXHAUSTIVE is default */
489 #define FFTW_PRESERVE_INPUT (1U << 4) /* cancels FFTW_DESTROY_INPUT */
490 #define FFTW_PATIENT (1U << 5) /* IMPATIENT is default */
491 #define FFTW_ESTIMATE (1U << 6)
492 #define FFTW_WISDOM_ONLY (1U << 21)
493
494 /* undocumented beyond-guru flags */
495 #define FFTW_ESTIMATE_PATIENT (1U << 7)
496 #define FFTW_BELIEVE_PCOST (1U << 8)
497 #define FFTW_NO_DFT_R2HC (1U << 9)
498 #define FFTW_NO_NONTHREADED (1U << 10)
499 #define FFTW_NO_BUFFERING (1U << 11)
500 #define FFTW_NO_INDIRECT_OP (1U << 12)
501 #define FFTW_ALLOW_LARGE_GENERIC (1U << 13) /* NO_LARGE_GENERIC is default */
502 #define FFTW_NO_RANK_SPLITS (1U << 14)
503 #define FFTW_NO_VRANK_SPLITS (1U << 15)
504 #define FFTW_NO_VRECURSE (1U << 16)
505 #define FFTW_NO_SIMD (1U << 17)
506 #define FFTW_NO_SLOW (1U << 18)
507 #define FFTW_NO_FIXED_RADIX_LARGE_N (1U << 19)
508 #define FFTW_ALLOW_PRUNING (1U << 20)
509
510 #ifdef __cplusplus
511 } /* extern "C" */
512 #endif /* __cplusplus */
513
514 #endif /* FFTW3_H */