psychlops/extension/standard/fft/fftw3.h

   1 /*
   2  * Copyright (c) 2003, 2007-8 Matteo Frigo
   3  * Copyright (c) 2003, 2007-8 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
  70 /* IMPORTANT: for Windows compilers, you should add a line
  71         #define FFTW_DLL
  72    here and in kernel/ifftw.h if you are compiling/using FFTW as a
  73    DLL, in order to do the proper importing/exporting, or
  74    alternatively compile with -DFFTW_DLL or the equivalent
  75    command-line flag.  This is not necessary under MinGW/Cygwin, where
  76    libtool does the imports/exports automatically. */
  77 #if defined(FFTW_DLL) && (defined(_WIN32) || defined(__WIN32__))
  78    /* annoying Windows syntax for shared-library declarations */
  79 #  if defined(COMPILING_FFTW) /* defined in api.h when compiling FFTW */
  80 #    define FFTW_EXTERN extern __declspec(dllexport)
  81 #  else /* user is calling FFTW; import symbol */
  82 #    define FFTW_EXTERN extern __declspec(dllimport)
  83 #  endif
  84 #else
  85 #  define FFTW_EXTERN extern
  86 #endif
  87
  88 enum fftw_r2r_kind_do_not_use_me {
  89      FFTW_R2HC=0, FFTW_HC2R=1, FFTW_DHT=2,
  90      FFTW_REDFT00=3, FFTW_REDFT01=4, FFTW_REDFT10=5, FFTW_REDFT11=6,
  91      FFTW_RODFT00=7, FFTW_RODFT01=8, FFTW_RODFT10=9, FFTW_RODFT11=10
  92 };
  93
  94 struct fftw_iodim_do_not_use_me {
  95      int n;                     /* dimension size */
  96      int is;                    /* input stride */
  97      int os;                    /* output stride */
  98 };
  99
 100 #include <stddef.h> /* for ptrdiff_t */
 101 struct fftw_iodim64_do_not_use_me {
 102      ptrdiff_t n;                     /* dimension size */
 103      ptrdiff_t is;                      /* input stride */
 104      ptrdiff_t os;                      /* output stride */
 105 };
 106
 107 /*
 108   huge second-order macro that defines prototypes for all API
 109   functions.  We expand this macro for each supported precision
 110
 111   X: name-mangling macro
 112   R: real data type
 113   C: complex data type
 114 */
 115
 116 #define FFTW_DEFINE_API(X, R, C)                                           \
 117                                                                            \
 118 FFTW_DEFINE_COMPLEX(R, C);                                                 \
 119                                                                            \
 120 typedef struct X(plan_s) *X(plan);                                         \
 121                                                                            \
 122 typedef struct fftw_iodim_do_not_use_me X(iodim);                          \
 123 typedef struct fftw_iodim64_do_not_use_me X(iodim64);                      \
 124                                                                            \
 125 typedef enum fftw_r2r_kind_do_not_use_me X(r2r_kind);                      \
 126                                                                            \
 127 FFTW_EXTERN void X(execute)(const X(plan) p);                              \
 128                                                                            \
 129 FFTW_EXTERN X(plan) X(plan_dft)(int rank, const int *n,                    \
 130                     C *in, C *out, int sign, unsigned flags);              \
 131                                                                            \
 132 FFTW_EXTERN X(plan) X(plan_dft_1d)(int n, C *in, C *out, int sign,         \
 133                        unsigned flags);                                    \
 134 FFTW_EXTERN X(plan) X(plan_dft_2d)(int n0, int n1,                         \
 135                        C *in, C *out, int sign, unsigned flags);           \
 136 FFTW_EXTERN X(plan) X(plan_dft_3d)(int n0, int n1, int n2,                 \
 137                        C *in, C *out, int sign, unsigned flags);           \
 138                                                                            \
 139 FFTW_EXTERN X(plan) X(plan_many_dft)(int rank, const int *n,               \
 140                          int howmany,                                      \
 141                          C *in, const int *inembed,                        \
 142                          int istride, int idist,                           \
 143                          C *out, const int *onembed,                       \
 144                          int ostride, int odist,                           \
 145                          int sign, unsigned flags);                        \
 146                                                                            \
 147 FFTW_EXTERN X(plan) X(plan_guru_dft)(int rank, const X(iodim) *dims,       \
 148                          int howmany_rank,                                 \
 149                          const X(iodim) *howmany_dims,                     \
 150                          C *in, C *out,                                    \
 151                          int sign, unsigned flags);                        \
 152 FFTW_EXTERN X(plan) X(plan_guru_split_dft)(int rank, const X(iodim) *dims, \
 153                          int howmany_rank,                                 \
 154                          const X(iodim) *howmany_dims,                     \
 155                          R *ri, R *ii, R *ro, R *io,                       \
 156                          unsigned flags);                                  \
 157                                                                            \
 158 FFTW_EXTERN X(plan) X(plan_guru64_dft)(int rank,                           \
 159                          const X(iodim64) *dims,                           \
 160                          int howmany_rank,                                 \
 161                          const X(iodim64) *howmany_dims,                   \
 162                          C *in, C *out,                                    \
 163                          int sign, unsigned flags);                        \
 164 FFTW_EXTERN X(plan) X(plan_guru64_split_dft)(int rank,                     \
 165                          const X(iodim64) *dims,                           \
 166                          int howmany_rank,                                 \
 167                          const X(iodim64) *howmany_dims,                   \
 168                          R *ri, R *ii, R *ro, R *io,                       \
 169                          unsigned flags);                                  \
 170                                                                            \
 171 FFTW_EXTERN void X(execute_dft)(const X(plan) p, C *in, C *out);           \
 172 FFTW_EXTERN void X(execute_split_dft)(const X(plan) p, R *ri, R *ii,       \
 173                                       R *ro, R *io);                       \
 174                                                                            \
 175 FFTW_EXTERN X(plan) X(plan_many_dft_r2c)(int rank, const int *n,           \
 176                              int howmany,                                  \
 177                              R *in, const int *inembed,                    \
 178                              int istride, int idist,                       \
 179                              C *out, const int *onembed,                   \
 180                              int ostride, int odist,                       \
 181                              unsigned flags);                              \
 182                                                                            \
 183 FFTW_EXTERN X(plan) X(plan_dft_r2c)(int rank, const int *n,                \
 184                         R *in, C *out, unsigned flags);                    \
 185                                                                            \
 186 FFTW_EXTERN X(plan) X(plan_dft_r2c_1d)(int n,R *in,C *out,unsigned flags); \
 187 FFTW_EXTERN X(plan) X(plan_dft_r2c_2d)(int n0, int n1,                     \
 188                            R *in, C *out, unsigned flags);                 \
 189 FFTW_EXTERN X(plan) X(plan_dft_r2c_3d)(int n0, int n1,                     \
 190                            int n2,                                         \
 191                            R *in, C *out, unsigned flags);                 \
 192                                                                            \
 193                                                                            \
 194 FFTW_EXTERN X(plan) X(plan_many_dft_c2r)(int rank, const int *n,           \
 195                              int howmany,                                  \
 196                              C *in, const int *inembed,                    \
 197                              int istride, int idist,                       \
 198                              R *out, const int *onembed,                   \
 199                              int ostride, int odist,                       \
 200                              unsigned flags);                              \
 201                                                                            \
 202 FFTW_EXTERN X(plan) X(plan_dft_c2r)(int rank, const int *n,                \
 203                         C *in, R *out, unsigned flags);                    \
 204                                                                            \
 205 FFTW_EXTERN X(plan) X(plan_dft_c2r_1d)(int n,C *in,R *out,unsigned flags); \
 206 FFTW_EXTERN X(plan) X(plan_dft_c2r_2d)(int n0, int n1,                     \
 207                            C *in, R *out, unsigned flags);                 \
 208 FFTW_EXTERN X(plan) X(plan_dft_c2r_3d)(int n0, int n1,                     \
 209                            int n2,                                         \
 210                            C *in, R *out, unsigned flags);                 \
 211                                                                            \
 212 FFTW_EXTERN X(plan) X(plan_guru_dft_r2c)(int rank, const X(iodim) *dims,   \
 213                              int howmany_rank,                             \
 214                              const X(iodim) *howmany_dims,                 \
 215                              R *in, C *out,                                \
 216                              unsigned flags);                              \
 217 FFTW_EXTERN X(plan) X(plan_guru_dft_c2r)(int rank, const X(iodim) *dims,   \
 218                              int howmany_rank,                             \
 219                              const X(iodim) *howmany_dims,                 \
 220                              C *in, R *out,                                \
 221                              unsigned flags);                              \
 222                                                                            \
 223 FFTW_EXTERN X(plan) X(plan_guru_split_dft_r2c)(                            \
 224                              int rank, const X(iodim) *dims,               \
 225                              int howmany_rank,                             \
 226                              const X(iodim) *howmany_dims,                 \
 227                              R *in, R *ro, R *io,                          \
 228                              unsigned flags);                              \
 229 FFTW_EXTERN X(plan) X(plan_guru_split_dft_c2r)(                            \
 230                              int rank, const X(iodim) *dims,               \
 231                              int howmany_rank,                             \
 232                              const X(iodim) *howmany_dims,                 \
 233                              R *ri, R *ii, R *out,                         \
 234                              unsigned flags);                              \
 235                                                                            \
 236 FFTW_EXTERN X(plan) X(plan_guru64_dft_r2c)(int rank,                       \
 237                              const X(iodim64) *dims,                       \
 238                              int howmany_rank,                             \
 239                              const X(iodim64) *howmany_dims,               \
 240                              R *in, C *out,                                \
 241                              unsigned flags);                              \
 242 FFTW_EXTERN X(plan) X(plan_guru64_dft_c2r)(int rank,                       \
 243                              const X(iodim64) *dims,                       \
 244                              int howmany_rank,                             \
 245                              const X(iodim64) *howmany_dims,               \
 246                              C *in, R *out,                                \
 247                              unsigned flags);                              \
 248                                                                            \
 249 FFTW_EXTERN X(plan) X(plan_guru64_split_dft_r2c)(                          \
 250                              int rank, const X(iodim64) *dims,             \
 251                              int howmany_rank,                             \
 252                              const X(iodim64) *howmany_dims,               \
 253                              R *in, R *ro, R *io,                          \
 254                              unsigned flags);                              \
 255 FFTW_EXTERN X(plan) X(plan_guru64_split_dft_c2r)(                          \
 256                              int rank, const X(iodim64) *dims,             \
 257                              int howmany_rank,                             \
 258                              const X(iodim64) *howmany_dims,               \
 259                              R *ri, R *ii, R *out,                         \
 260                              unsigned flags);                              \
 261                                                                            \
 262 FFTW_EXTERN void X(execute_dft_r2c)(const X(plan) p, R *in, C *out);       \
 263 FFTW_EXTERN void X(execute_dft_c2r)(const X(plan) p, C *in, R *out);       \
 264                                                                            \
 265 FFTW_EXTERN void X(execute_split_dft_r2c)(const X(plan) p,                 \
 266                                           R *in, R *ro, R *io);            \
 267 FFTW_EXTERN void X(execute_split_dft_c2r)(const X(plan) p,                 \
 268                                           R *ri, R *ii, R *out);           \
 269                                                                            \
 270 FFTW_EXTERN X(plan) X(plan_many_r2r)(int rank, const int *n,               \
 271                          int howmany,                                      \
 272                          R *in, const int *inembed,                        \
 273                          int istride, int idist,                           \
 274                          R *out, const int *onembed,                       \
 275                          int ostride, int odist,                           \
 276                          const X(r2r_kind) *kind, unsigned flags);         \
 277                                                                            \
 278 FFTW_EXTERN X(plan) X(plan_r2r)(int rank, const int *n, R *in, R *out,     \
 279                     const X(r2r_kind) *kind, unsigned flags);              \
 280                                                                            \
 281 FFTW_EXTERN X(plan) X(plan_r2r_1d)(int n, R *in, R *out,                   \
 282                        X(r2r_kind) kind, unsigned flags);                  \
 283 FFTW_EXTERN X(plan) X(plan_r2r_2d)(int n0, int n1, R *in, R *out,          \
 284                        X(r2r_kind) kind0, X(r2r_kind) kind1,               \
 285                        unsigned flags);                                    \
 286 FFTW_EXTERN X(plan) X(plan_r2r_3d)(int n0, int n1, int n2,                 \
 287                        R *in, R *out, X(r2r_kind) kind0,                   \
 288                        X(r2r_kind) kind1, X(r2r_kind) kind2,               \
 289                        unsigned flags);                                    \
 290                                                                            \
 291 FFTW_EXTERN X(plan) X(plan_guru_r2r)(int rank, const X(iodim) *dims,       \
 292                          int howmany_rank,                                 \
 293                          const X(iodim) *howmany_dims,                     \
 294                          R *in, R *out,                                    \
 295                          const X(r2r_kind) *kind, unsigned flags);         \
 296                                                                            \
 297 FFTW_EXTERN X(plan) X(plan_guru64_r2r)(int rank, const X(iodim64) *dims,   \
 298                          int howmany_rank,                                 \
 299                          const X(iodim64) *howmany_dims,                   \
 300                          R *in, R *out,                                    \
 301                          const X(r2r_kind) *kind, unsigned flags);         \
 302                                                                            \
 303 FFTW_EXTERN void X(execute_r2r)(const X(plan) p, R *in, R *out);           \
 304                                                                            \
 305 FFTW_EXTERN void X(destroy_plan)(X(plan) p);                               \
 306 FFTW_EXTERN void X(forget_wisdom)(void);                                   \
 307 FFTW_EXTERN void X(cleanup)(void);                                         \
 308                                                                            \
 309 FFTW_EXTERN void X(set_timelimit)(double);                                 \
 310                                                                            \
 311 FFTW_EXTERN void X(plan_with_nthreads)(int nthreads);                      \
 312 FFTW_EXTERN int X(init_threads)(void);                                     \
 313 FFTW_EXTERN void X(cleanup_threads)(void);                                 \
 314                                                                            \
 315 FFTW_EXTERN void X(export_wisdom_to_file)(FILE *output_file);              \
 316 FFTW_EXTERN char *X(export_wisdom_to_string)(void);                        \
 317 FFTW_EXTERN void X(export_wisdom)(void (*write_char)(char c, void *),      \
 318                                   void *data);                             \
 319 FFTW_EXTERN int X(import_system_wisdom)(void);                             \
 320 FFTW_EXTERN int X(import_wisdom_from_file)(FILE *input_file);              \
 321 FFTW_EXTERN int X(import_wisdom_from_string)(const char *input_string);    \
 322 FFTW_EXTERN int X(import_wisdom)(int (*read_char)(void *), void *data);    \
 323                                                                            \
 324 FFTW_EXTERN void X(fprint_plan)(const X(plan) p, FILE *output_file);       \
 325 FFTW_EXTERN void X(print_plan)(const X(plan) p);                           \
 326                                                                            \
 327 FFTW_EXTERN void *X(malloc)(size_t n);                                     \
 328 FFTW_EXTERN void X(free)(void *p);                                         \
 329                                                                            \
 330 FFTW_EXTERN void X(flops)(const X(plan) p,                                 \
 331                           double *add, double *mul, double *fmas);         \
 332 FFTW_EXTERN double X(estimate_cost)(const X(plan) p);                      \
 333                                                                            \
 334 FFTW_EXTERN const char X(version)[];                                       \
 335 FFTW_EXTERN const char X(cc)[];                                            \
 336 FFTW_EXTERN const char X(codelet_optim)[];
 337
 338
 339 /* end of FFTW_DEFINE_API macro */
 340
 341 FFTW_DEFINE_API(FFTW_MANGLE_DOUBLE, double, fftw_complex)
 342 FFTW_DEFINE_API(FFTW_MANGLE_FLOAT, float, fftwf_complex)
 343 FFTW_DEFINE_API(FFTW_MANGLE_LONG_DOUBLE, long double, fftwl_complex)
 344
 345 #define FFTW_FORWARD (-1)
 346 #define FFTW_BACKWARD (+1)
 347
 348 #define FFTW_NO_TIMELIMIT (-1.0)
 349
 350 /* documented flags */
 351 #define FFTW_MEASURE (0U)
 352 #define FFTW_DESTROY_INPUT (1U << 0)
 353 #define FFTW_UNALIGNED (1U << 1)
 354 #define FFTW_CONSERVE_MEMORY (1U << 2)
 355 #define FFTW_EXHAUSTIVE (1U << 3) /* NO_EXHAUSTIVE is default */
 356 #define FFTW_PRESERVE_INPUT (1U << 4) /* cancels FFTW_DESTROY_INPUT */
 357 #define FFTW_PATIENT (1U << 5) /* IMPATIENT is default */
 358 #define FFTW_ESTIMATE (1U << 6)
 359
 360 /* undocumented beyond-guru flags */
 361 #define FFTW_ESTIMATE_PATIENT (1U << 7)
 362 #define FFTW_BELIEVE_PCOST (1U << 8)
 363 #define FFTW_NO_DFT_R2HC (1U << 9)
 364 #define FFTW_NO_NONTHREADED (1U << 10)
 365 #define FFTW_NO_BUFFERING (1U << 11)
 366 #define FFTW_NO_INDIRECT_OP (1U << 12)
 367 #define FFTW_ALLOW_LARGE_GENERIC (1U << 13) /* NO_LARGE_GENERIC is default */
 368 #define FFTW_NO_RANK_SPLITS (1U << 14)
 369 #define FFTW_NO_VRANK_SPLITS (1U << 15)
 370 #define FFTW_NO_VRECURSE (1U << 16)
 371 #define FFTW_NO_SIMD (1U << 17)
 372 #define FFTW_NO_SLOW (1U << 18)
 373 #define FFTW_NO_FIXED_RADIX_LARGE_N (1U << 19)
 374 #define FFTW_ALLOW_PRUNING (1U << 20)
 375 #define FFTW_WISDOM_ONLY (1U << 21)
 376
 377 #ifdef __cplusplus
 378 }  /* extern "C" */
 379 #endif /* __cplusplus */
 380
 381 #endif /* FFTW3_H */