jDttSP/fftw.h

   1 /* -*- C -*- */
   2 /*
   3  * Copyright (c) 1997-1999, 2003 Massachusetts Institute of Technology
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program; if not, write to the Free Software
  17  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  18  *
  19  */
  20
  21 /* fftw.h -- system-wide definitions */
  22 /* $Id$ */
  23
  24 #ifndef FFTW_H
  25 #define FFTW_H
  26
  27 #include <stdlib.h>
  28 #include <stdio.h>
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif                          /* __cplusplus */
  33
  34 /* Define for using single precision */
  35 /*
  36  * If you can, use configure --enable-float instead of changing this
  37  * flag directly
  38  */
  39 /* #undef FFTW_ENABLE_FLOAT */
  40
  41 /* our real numbers */
  42 #ifdef FFTW_ENABLE_FLOAT
  43 typedef float fftw_real;
  44 #else
  45 typedef double fftw_real;
  46 #endif
  47
  48 /*********************************************
  49  * Complex numbers and operations
  50  *********************************************/
  51 typedef struct {
  52      fftw_real re, im;
  53 } fftw_complex;
  54
  55 #ifndef c_re
  56 #define c_re(c)  ((c).re)
  57 #endif
  58 #ifndef c_im
  59 #define c_im(c)  ((c).im)
  60 #endif
  61
  62 typedef enum {
  63      FFTW_FORWARD = -1, FFTW_BACKWARD = 1
  64 } fftw_direction;
  65
  66 /* backward compatibility with FFTW-1.3 */
  67 typedef fftw_complex FFTW_COMPLEX;
  68 typedef fftw_real FFTW_REAL;
  69
  70 #ifndef FFTW_1_0_COMPATIBILITY
  71 #define FFTW_1_0_COMPATIBILITY 0
  72 #endif
  73
  74 #if FFTW_1_0_COMPATIBILITY
  75 /* backward compatibility with FFTW-1.0 */
  76 #define REAL fftw_real
  77 #define COMPLEX fftw_complex
  78 #endif
  79
  80 /*********************************************
  81  * Success or failure status
  82  *********************************************/
  83
  84 typedef enum {
  85      FFTW_SUCCESS = 0, FFTW_FAILURE = -1
  86 } fftw_status;
  87
  88 /*********************************************
  89  *              Codelets
  90  *********************************************/
  91 typedef void (fftw_notw_codelet)
  92      (const fftw_complex *, fftw_complex *, int, int);
  93 typedef void (fftw_twiddle_codelet)
  94      (fftw_complex *, const fftw_complex *, int,
  95       int, int);
  96 typedef void (fftw_generic_codelet)
  97      (fftw_complex *, const fftw_complex *, int,
  98       int, int, int);
  99 typedef void (fftw_real2hc_codelet)
 100      (const fftw_real *, fftw_real *, fftw_real *,
 101       int, int, int);
 102 typedef void (fftw_hc2real_codelet)
 103      (const fftw_real *, const fftw_real *,
 104       fftw_real *, int, int, int);
 105 typedef void (fftw_hc2hc_codelet)
 106      (fftw_real *, const fftw_complex *,
 107       int, int, int);
 108 typedef void (fftw_rgeneric_codelet)
 109      (fftw_real *, const fftw_complex *, int,
 110       int, int, int);
 111
 112 /*********************************************
 113  *     Configurations
 114  *********************************************/
 115 /*
 116  * A configuration is a database of all known codelets
 117  */
 118
 119 enum fftw_node_type {
 120      FFTW_NOTW, FFTW_TWIDDLE, FFTW_GENERIC, FFTW_RADER,
 121      FFTW_REAL2HC, FFTW_HC2REAL, FFTW_HC2HC, FFTW_RGENERIC
 122 };
 123
 124 /* description of a codelet */
 125 typedef struct {
 126      const char *name;          /* name of the codelet */
 127      void (*codelet) ();        /* pointer to the codelet itself */
 128      int size;                  /* size of the codelet */
 129      fftw_direction dir;        /* direction */
 130      enum fftw_node_type type;  /* TWIDDLE or NO_TWIDDLE */
 131      int signature;             /* unique id */
 132      int ntwiddle;              /* number of twiddle factors */
 133      const int *twiddle_order;  /*
 134                                  * array that determines the order
 135                                  * in which the codelet expects
 136                                  * the twiddle factors
 137                                  */
 138 } fftw_codelet_desc;
 139
 140 /* On Win32, you need to do funny things to access global variables
 141    in shared libraries.  Thanks to Andrew Sterian for this hack. */
 142 #ifdef HAVE_WIN32
 143 #  if defined(BUILD_FFTW_DLL)
 144 #    define DL_IMPORT(type) __declspec(dllexport) type
 145 #  elif defined(USE_FFTW_DLL)
 146 #    define DL_IMPORT(type) __declspec(dllimport) type
 147 #  else
 148 #    define DL_IMPORT(type) type
 149 #  endif
 150 #else
 151 #  define DL_IMPORT(type) type
 152 #endif
 153
 154 extern DL_IMPORT(const char *) fftw_version;
 155
 156 /*****************************
 157  *        Plans
 158  *****************************/
 159 /*
 160  * A plan is a sequence of reductions to compute a FFT of
 161  * a given size.  At each step, the FFT algorithm can:
 162  *
 163  * 1) apply a notw codelet, or
 164  * 2) recurse and apply a twiddle codelet, or
 165  * 3) apply the generic codelet.
 166  */
 167
 168 /* structure that contains twiddle factors */
 169 typedef struct fftw_twiddle_struct {
 170      int n;
 171      const fftw_codelet_desc *cdesc;
 172      fftw_complex *twarray;
 173      struct fftw_twiddle_struct *next;
 174      int refcnt;
 175 } fftw_twiddle;
 176
 177 typedef struct fftw_rader_data_struct {
 178      struct fftw_plan_struct *plan;
 179      fftw_complex *omega;
 180      int g, ginv;
 181      int p, flags, refcount;
 182      struct fftw_rader_data_struct *next;
 183      fftw_codelet_desc *cdesc;
 184 } fftw_rader_data;
 185
 186 typedef void (fftw_rader_codelet)
 187      (fftw_complex *, const fftw_complex *, int,
 188       int, int, fftw_rader_data *);
 189
 190 /* structure that holds all the data needed for a given step */
 191 typedef struct fftw_plan_node_struct {
 192      enum fftw_node_type type;
 193
 194      union {
 195           /* nodes of type FFTW_NOTW */
 196           struct {
 197                int size;
 198                fftw_notw_codelet *codelet;
 199                const fftw_codelet_desc *codelet_desc;
 200           } notw;
 201
 202           /* nodes of type FFTW_TWIDDLE */
 203           struct {
 204                int size;
 205                fftw_twiddle_codelet *codelet;
 206                fftw_twiddle *tw;
 207                struct fftw_plan_node_struct *recurse;
 208                const fftw_codelet_desc *codelet_desc;
 209           } twiddle;
 210
 211           /* nodes of type FFTW_GENERIC */
 212           struct {
 213                int size;
 214                fftw_generic_codelet *codelet;
 215                fftw_twiddle *tw;
 216                struct fftw_plan_node_struct *recurse;
 217           } generic;
 218
 219           /* nodes of type FFTW_RADER */
 220           struct {
 221                int size;
 222                fftw_rader_codelet *codelet;
 223                fftw_rader_data *rader_data;
 224                fftw_twiddle *tw;
 225                struct fftw_plan_node_struct *recurse;
 226           } rader;
 227
 228           /* nodes of type FFTW_REAL2HC */
 229           struct {
 230                int size;
 231                fftw_real2hc_codelet *codelet;
 232                const fftw_codelet_desc *codelet_desc;
 233           } real2hc;
 234
 235           /* nodes of type FFTW_HC2REAL */
 236           struct {
 237                int size;
 238                fftw_hc2real_codelet *codelet;
 239                const fftw_codelet_desc *codelet_desc;
 240           } hc2real;
 241
 242           /* nodes of type FFTW_HC2HC */
 243           struct {
 244                int size;
 245                fftw_direction dir;
 246                fftw_hc2hc_codelet *codelet;
 247                fftw_twiddle *tw;
 248                struct fftw_plan_node_struct *recurse;
 249                const fftw_codelet_desc *codelet_desc;
 250           } hc2hc;
 251
 252           /* nodes of type FFTW_RGENERIC */
 253           struct {
 254                int size;
 255                fftw_direction dir;
 256                fftw_rgeneric_codelet *codelet;
 257                fftw_twiddle *tw;
 258                struct fftw_plan_node_struct *recurse;
 259           } rgeneric;
 260      } nodeu;
 261
 262      int refcnt;
 263 } fftw_plan_node;
 264
 265 typedef enum {
 266      FFTW_NORMAL_RECURSE = 0,
 267      FFTW_VECTOR_RECURSE = 1
 268 } fftw_recurse_kind;
 269
 270 struct fftw_plan_struct {
 271      int n;
 272      int refcnt;
 273      fftw_direction dir;
 274      int flags;
 275      int wisdom_signature;
 276      enum fftw_node_type wisdom_type;
 277      struct fftw_plan_struct *next;
 278      fftw_plan_node *root;
 279      double cost;
 280      fftw_recurse_kind recurse_kind;
 281      int vector_size;
 282 };
 283
 284 typedef struct fftw_plan_struct *fftw_plan;
 285
 286 /* flags for the planner */
 287 #define  FFTW_ESTIMATE (0)
 288 #define  FFTW_MEASURE  (1)
 289
 290 #define FFTW_OUT_OF_PLACE (0)
 291 #define FFTW_IN_PLACE (8)
 292 #define FFTW_USE_WISDOM (16)
 293
 294 #define FFTW_THREADSAFE (128)  /* guarantee plan is read-only so that the
 295                                   same plan can be used in parallel by
 296                                   multiple threads */
 297
 298 #define FFTWND_FORCE_BUFFERED (256)     /* internal flag, forces buffering
 299                                            in fftwnd transforms */
 300
 301 #define FFTW_NO_VECTOR_RECURSE (512)    /* internal flag, prevents use
 302                                            of vector recursion */
 303
 304 extern fftw_plan fftw_create_plan_specific(int n, fftw_direction dir,
 305                                            int flags,
 306                                            fftw_complex *in, int istride,
 307                                          fftw_complex *out, int ostride);
 308 #define FFTW_HAS_PLAN_SPECIFIC
 309 extern fftw_plan fftw_create_plan(int n, fftw_direction dir, int flags);
 310 extern void fftw_print_plan(fftw_plan plan);
 311 extern void fftw_destroy_plan(fftw_plan plan);
 312 extern void fftw(fftw_plan plan, int howmany, fftw_complex *in, int istride,
 313                  int idist, fftw_complex *out, int ostride, int odist);
 314 extern void fftw_one(fftw_plan plan, fftw_complex *in, fftw_complex *out);
 315 extern void fftw_die(const char *s);
 316 extern void *fftw_malloc(size_t n);
 317 extern void fftw_free(void *p);
 318 extern void fftw_check_memory_leaks(void);
 319 extern void fftw_print_max_memory_usage(void);
 320
 321 typedef void *(*fftw_malloc_type_function) (size_t n);
 322 typedef void  (*fftw_free_type_function) (void *p);
 323 typedef void  (*fftw_die_type_function) (const char *errString);
 324 extern DL_IMPORT(fftw_malloc_type_function) fftw_malloc_hook;
 325 extern DL_IMPORT(fftw_free_type_function) fftw_free_hook;
 326 extern DL_IMPORT(fftw_die_type_function) fftw_die_hook;
 327
 328 extern size_t fftw_sizeof_fftw_real(void);
 329
 330 /* Wisdom: */
 331 /*
 332  * define this symbol so that users know we are using a version of FFTW
 333  * with wisdom
 334  */
 335 #define FFTW_HAS_WISDOM
 336 extern void fftw_forget_wisdom(void);
 337 extern void fftw_export_wisdom(void (*emitter) (char c, void *), void *data);
 338 extern fftw_status fftw_import_wisdom(int (*g) (void *), void *data);
 339 extern void fftw_export_wisdom_to_file(FILE *output_file);
 340 extern fftw_status fftw_import_wisdom_from_file(FILE *input_file);
 341 extern char *fftw_export_wisdom_to_string(void);
 342 extern fftw_status fftw_import_wisdom_from_string(const char *input_string);
 343
 344 /*
 345  * define symbol so we know this function is available (it is not in
 346  * older FFTWs)
 347  */
 348 #define FFTW_HAS_FPRINT_PLAN
 349 extern void fftw_fprint_plan(FILE *f, fftw_plan plan);
 350
 351 /*****************************
 352  *    N-dimensional code
 353  *****************************/
 354 typedef struct {
 355      int is_in_place;           /* 1 if for in-place FFTs, 0 otherwise */
 356
 357      int rank;                  /*
 358                                  * the rank (number of dimensions) of the
 359                                  * array to be FFTed
 360                                  */
 361      int *n;                    /*
 362                                  * the dimensions of the array to the
 363                                  * FFTed
 364                                  */
 365      fftw_direction dir;
 366
 367      int *n_before;             /*
 368                                  * n_before[i] = product of n[j] for j < i
 369                                  */
 370      int *n_after;              /* n_after[i] = product of n[j] for j > i */
 371
 372      fftw_plan *plans;          /* 1d fftw plans for each dimension */
 373
 374      int nbuffers, nwork;
 375      fftw_complex *work;        /*
 376                                  * work array big enough to hold
 377                                  * nbuffers+1 of the largest dimension
 378                                  * (has nwork elements)
 379                                  */
 380 } fftwnd_data;
 381
 382 typedef fftwnd_data *fftwnd_plan;
 383
 384 /* Initializing the FFTWND plan: */
 385 extern fftwnd_plan fftw2d_create_plan(int nx, int ny, fftw_direction dir,
 386                                       int flags);
 387 extern fftwnd_plan fftw3d_create_plan(int nx, int ny, int nz,
 388                                       fftw_direction dir, int flags);
 389 extern fftwnd_plan fftwnd_create_plan(int rank, const int *n,
 390                                       fftw_direction dir,
 391                                       int flags);
 392
 393 extern fftwnd_plan fftw2d_create_plan_specific(int nx, int ny,
 394                                                fftw_direction dir,
 395                                                int flags,
 396                                            fftw_complex *in, int istride,
 397                                          fftw_complex *out, int ostride);
 398 extern fftwnd_plan fftw3d_create_plan_specific(int nx, int ny, int nz,
 399                                            fftw_direction dir, int flags,
 400                                            fftw_complex *in, int istride,
 401                                          fftw_complex *out, int ostride);
 402 extern fftwnd_plan fftwnd_create_plan_specific(int rank, const int *n,
 403                                                fftw_direction dir,
 404                                                int flags,
 405                                            fftw_complex *in, int istride,
 406                                          fftw_complex *out, int ostride);
 407
 408 /* Freeing the FFTWND plan: */
 409 extern void fftwnd_destroy_plan(fftwnd_plan plan);
 410
 411 /* Printing the plan: */
 412 extern void fftwnd_fprint_plan(FILE *f, fftwnd_plan p);
 413 extern void fftwnd_print_plan(fftwnd_plan p);
 414 #define FFTWND_HAS_PRINT_PLAN
 415
 416 /* Computing the N-Dimensional FFT */
 417 extern void fftwnd(fftwnd_plan plan, int howmany,
 418                    fftw_complex *in, int istride, int idist,
 419                    fftw_complex *out, int ostride, int odist);
 420 extern void fftwnd_one(fftwnd_plan p, fftw_complex *in, fftw_complex *out);
 421
 422 #ifdef __cplusplus
 423 }                               /* extern "C" */
 424
 425 #endif                          /* __cplusplus */
 426 #endif                          /* FFTW_H */