fftw.h Source File

00001 /* -*- C -*- */
00002 /*
00003  * Copyright (c) 1997-1999 Massachusetts Institute of Technology
00004  *
00005  * This program is free software; you can redistribute it and/or modify
00006  * it under the terms of the GNU General Public License as published by
00007  * the Free Software Foundation; either version 2 of the License, or
00008  * (at your option) any later version.
00009  *
00010  * This program is distributed in the hope that it will be useful,
00011  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00012  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00013  * GNU General Public License for more details.
00014  *
00015  * You should have received a copy of the GNU General Public License
00016  * along with this program; if not, write to the Free Software
00017  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
00018  *
00019  */
00020 
00021 /* fftw.h -- system-wide definitions */
00022 /* $Id: fftw.h.in,v 1.53 1999/07/24 20:01:23 stevenj Exp $ */
00023 
00024 #ifndef FFTW_H
00025 #define FFTW_H
00026 #define FFTW_ENABLE_FLOAT
00027 
00028 #include <stdlib.h>
00029 #include <stdio.h>
00030 
00031 #ifdef __cplusplus
00032 extern "C" {
00033 #endif                          /* __cplusplus */
00034 
00035 /* Define for using single precision */
00036 /*
00037  * If you can, use configure --enable-float instead of changing this
00038  * flag directly 
00039  */
00040 /* #undef FFTW_ENABLE_FLOAT */
00041 
00042 /* our real numbers */
00043 #ifdef FFTW_ENABLE_FLOAT
00044 typedef float fftw_real;
00045 #else
00046 typedef double fftw_real;
00047 #endif
00048 
00049 /*********************************************
00050  * Complex numbers and operations 
00051  *********************************************/
00052 typedef struct {
00053      fftw_real re, im;
00054 } fftw_complex;
00055 
00056 #define c_re(c)  ((c).re)
00057 #define c_im(c)  ((c).im)
00058 
00059 typedef enum {
00060      FFTW_FORWARD = -1, FFTW_BACKWARD = 1
00061 } fftw_direction;
00062 
00063 /* backward compatibility with FFTW-1.3 */
00064 typedef fftw_complex FFTW_COMPLEX;
00065 typedef fftw_real FFTW_REAL;
00066 
00067 #ifndef FFTW_1_0_COMPATIBILITY
00068 #define FFTW_1_0_COMPATIBILITY 0
00069 #endif
00070 
00071 #if FFTW_1_0_COMPATIBILITY
00072 /* backward compatibility with FFTW-1.0 */
00073 #define REAL fftw_real
00074 #define COMPLEX fftw_complex
00075 #endif
00076 
00077 /*********************************************
00078  * Success or failure status
00079  *********************************************/
00080 
00081 typedef enum {
00082      FFTW_SUCCESS = 0, FFTW_FAILURE = -1
00083 } fftw_status;
00084 
00085 /*********************************************
00086  *              Codelets
00087  *********************************************/
00088 typedef void (fftw_notw_codelet) 
00089      (const fftw_complex *, fftw_complex *, int, int);
00090 typedef void (fftw_twiddle_codelet)
00091      (fftw_complex *, const fftw_complex *, int,
00092       int, int);
00093 typedef void (fftw_generic_codelet) 
00094      (fftw_complex *, const fftw_complex *, int,
00095       int, int, int);
00096 typedef void (fftw_real2hc_codelet)
00097      (const fftw_real *, fftw_real *, fftw_real *,
00098       int, int, int);
00099 typedef void (fftw_hc2real_codelet)
00100      (const fftw_real *, const fftw_real *,
00101       fftw_real *, int, int, int);
00102 typedef void (fftw_hc2hc_codelet)
00103      (fftw_real *, const fftw_complex *,
00104       int, int, int);
00105 typedef void (fftw_rgeneric_codelet)
00106      (fftw_real *, const fftw_complex *, int,
00107       int, int, int);
00108 
00109 /*********************************************
00110  *     Configurations
00111  *********************************************/
00112 /*
00113  * A configuration is a database of all known codelets
00114  */
00115 
00116 enum fftw_node_type {
00117      FFTW_NOTW, FFTW_TWIDDLE, FFTW_GENERIC, FFTW_RADER,
00118      FFTW_REAL2HC, FFTW_HC2REAL, FFTW_HC2HC, FFTW_RGENERIC
00119 };
00120 
00121 /* description of a codelet */
00122 typedef struct {
00123      const char *name;          /* name of the codelet */
00124      void (*codelet) ();        /* pointer to the codelet itself */
00125      int size;                  /* size of the codelet */
00126      fftw_direction dir;        /* direction */
00127      enum fftw_node_type type;  /* TWIDDLE or NO_TWIDDLE */
00128      int signature;             /* unique id */
00129      int ntwiddle;              /* number of twiddle factors */
00130      const int *twiddle_order;  /* 
00131                                  * array that determines the order 
00132                                  * in which the codelet expects
00133                                  * the twiddle factors
00134                                  */
00135 } fftw_codelet_desc;
00136 
00137 /* On Win32, you need to do funny things to access global variables
00138    in shared libraries.  Thanks to Andrew Sterian for this hack. */
00139 #ifdef HAVE_WIN32
00140 #  if defined(BUILD_FFTW_DLL)
00141 #    define DL_IMPORT(type) __declspec(dllexport) type
00142 #  elif defined(USE_FFTW_DLL)
00143 #    define DL_IMPORT(type) __declspec(dllimport) type
00144 #  else
00145 #    define DL_IMPORT(type) type
00146 #  endif
00147 #else
00148 #  define DL_IMPORT(type) type
00149 #endif
00150 
00151 extern DL_IMPORT(const char *) fftw_version;
00152 
00153 /*****************************
00154  *        Plans
00155  *****************************/
00156 /*
00157  * A plan is a sequence of reductions to compute a FFT of
00158  * a given size.  At each step, the FFT algorithm can:
00159  *
00160  * 1) apply a notw codelet, or
00161  * 2) recurse and apply a twiddle codelet, or
00162  * 3) apply the generic codelet.
00163  */
00164 
00165 /* structure that contains twiddle factors */
00166 typedef struct fftw_twiddle_struct {
00167      int n;
00168      const fftw_codelet_desc *cdesc;
00169      fftw_complex *twarray;
00170      struct fftw_twiddle_struct *next;
00171      int refcnt;
00172 } fftw_twiddle;
00173 
00174 typedef struct fftw_rader_data_struct {
00175      struct fftw_plan_struct *plan;
00176      fftw_complex *omega;
00177      int g, ginv;
00178      int p, flags, refcount;
00179      struct fftw_rader_data_struct *next;
00180      fftw_codelet_desc *cdesc;
00181 } fftw_rader_data;
00182 
00183 typedef void (fftw_rader_codelet) 
00184      (fftw_complex *, const fftw_complex *, int,
00185       int, int, fftw_rader_data *);
00186 
00187 /* structure that holds all the data needed for a given step */
00188 typedef struct fftw_plan_node_struct {
00189      enum fftw_node_type type;
00190 
00191      union {
00192           /* nodes of type FFTW_NOTW */
00193           struct {
00194                int size;
00195                fftw_notw_codelet *codelet;
00196                const fftw_codelet_desc *codelet_desc;
00197           } notw;
00198 
00199           /* nodes of type FFTW_TWIDDLE */
00200           struct {
00201                int size;
00202                fftw_twiddle_codelet *codelet;
00203                fftw_twiddle *tw;
00204                struct fftw_plan_node_struct *recurse;
00205                const fftw_codelet_desc *codelet_desc;
00206           } twiddle;
00207 
00208           /* nodes of type FFTW_GENERIC */
00209           struct {
00210                int size;
00211                fftw_generic_codelet *codelet;
00212                fftw_twiddle *tw;
00213                struct fftw_plan_node_struct *recurse;
00214           } generic;
00215 
00216           /* nodes of type FFTW_RADER */
00217           struct {
00218                int size;
00219                fftw_rader_codelet *codelet;
00220                fftw_rader_data *rader_data;
00221                fftw_twiddle *tw;
00222                struct fftw_plan_node_struct *recurse;
00223           } rader;
00224 
00225           /* nodes of type FFTW_REAL2HC */
00226           struct {
00227                int size;
00228                fftw_real2hc_codelet *codelet;
00229                const fftw_codelet_desc *codelet_desc;
00230           } real2hc;
00231 
00232           /* nodes of type FFTW_HC2REAL */
00233           struct {
00234                int size;
00235                fftw_hc2real_codelet *codelet;
00236                const fftw_codelet_desc *codelet_desc;
00237           } hc2real;
00238 
00239           /* nodes of type FFTW_HC2HC */
00240           struct {
00241                int size;
00242                fftw_direction dir;
00243                fftw_hc2hc_codelet *codelet;
00244                fftw_twiddle *tw;
00245                struct fftw_plan_node_struct *recurse;
00246                const fftw_codelet_desc *codelet_desc;
00247           } hc2hc;
00248 
00249           /* nodes of type FFTW_RGENERIC */
00250           struct {
00251                int size;
00252                fftw_direction dir;
00253                fftw_rgeneric_codelet *codelet;
00254                fftw_twiddle *tw;
00255                struct fftw_plan_node_struct *recurse;
00256           } rgeneric;
00257      } nodeu;
00258 
00259      int refcnt;
00260 } fftw_plan_node;
00261 
00262 typedef enum {
00263      FFTW_NORMAL_RECURSE = 0,
00264      FFTW_VECTOR_RECURSE = 1
00265 } fftw_recurse_kind;
00266 
00267 struct fftw_plan_struct {
00268      int n;
00269      int refcnt;
00270      fftw_direction dir;
00271      int flags;
00272      int wisdom_signature;
00273      enum fftw_node_type wisdom_type;
00274      struct fftw_plan_struct *next;
00275      fftw_plan_node *root;
00276      double cost;
00277      fftw_recurse_kind recurse_kind;
00278      int vector_size;
00279 };
00280 
00281 typedef struct fftw_plan_struct *fftw_plan;
00282 
00283 /* flags for the planner */
00284 #define  FFTW_ESTIMATE (0)
00285 #define  FFTW_MEASURE  (1)
00286 
00287 #define FFTW_OUT_OF_PLACE (0)
00288 #define FFTW_IN_PLACE (8)
00289 #define FFTW_USE_WISDOM (16)
00290 
00291 #define FFTW_THREADSAFE (128)  /* guarantee plan is read-only so that the
00292                                   same plan can be used in parallel by
00293                                   multiple threads */
00294 
00295 #define FFTWND_FORCE_BUFFERED (256)     /* internal flag, forces buffering
00296                                            in fftwnd transforms */
00297 
00298 #define FFTW_NO_VECTOR_RECURSE (512)    /* internal flag, prevents use
00299                                            of vector recursion */
00300 
00301 extern fftw_plan fftw_create_plan_specific(int n, fftw_direction dir,
00302                                            int flags,
00303                                            fftw_complex *in, int istride,
00304                                          fftw_complex *out, int ostride);
00305 #define FFTW_HAS_PLAN_SPECIFIC
00306 extern fftw_plan fftw_create_plan(int n, fftw_direction dir, int flags);
00307 extern void fftw_print_plan(fftw_plan plan);
00308 extern void fftw_destroy_plan(fftw_plan plan);
00309 extern void fftw(fftw_plan plan, int howmany, fftw_complex *in, int istride,
00310                  int idist, fftw_complex *out, int ostride, int odist);
00311 extern void fftw_one(fftw_plan plan, fftw_complex *in, fftw_complex *out);
00312 extern void fftw_die(const char *s);
00313 extern void *fftw_malloc(size_t n);
00314 extern void fftw_free(void *p);
00315 extern void fftw_check_memory_leaks(void);
00316 extern void fftw_print_max_memory_usage(void);
00317 
00318 typedef void *(*fftw_malloc_type_function) (size_t n);
00319 typedef void  (*fftw_free_type_function) (void *p);
00320 typedef void  (*fftw_die_type_function) (const char *errString);
00321 extern DL_IMPORT(fftw_malloc_type_function) fftw_malloc_hook;
00322 extern DL_IMPORT(fftw_free_type_function) fftw_free_hook;
00323 extern DL_IMPORT(fftw_die_type_function) fftw_die_hook;
00324 
00325 extern size_t fftw_sizeof_fftw_real(void);
00326 
00327 /* Wisdom: */
00328 /*
00329  * define this symbol so that users know we are using a version of FFTW
00330  * with wisdom
00331  */
00332 #define FFTW_HAS_WISDOM
00333 extern void fftw_forget_wisdom(void);
00334 extern void fftw_export_wisdom(void (*emitter) (char c, void *), void *data);
00335 extern fftw_status fftw_import_wisdom(int (*g) (void *), void *data);
00336 extern void fftw_export_wisdom_to_file(FILE *output_file);
00337 extern fftw_status fftw_import_wisdom_from_file(FILE *input_file);
00338 extern char *fftw_export_wisdom_to_string(void);
00339 extern fftw_status fftw_import_wisdom_from_string(const char *input_string);
00340 
00341 /*
00342  * define symbol so we know this function is available (it is not in
00343  * older FFTWs)
00344  */
00345 #define FFTW_HAS_FPRINT_PLAN
00346 extern void fftw_fprint_plan(FILE *f, fftw_plan plan);
00347 
00348 /*****************************
00349  *    N-dimensional code
00350  *****************************/
00351 typedef struct {
00352      int is_in_place;           /* 1 if for in-place FFTs, 0 otherwise */
00353 
00354      int rank;                  /* 
00355                                  * the rank (number of dimensions) of the
00356                                  * array to be FFTed 
00357                                  */
00358      int *n;                    /*
00359                                  * the dimensions of the array to the
00360                                  * FFTed 
00361                                  */
00362      fftw_direction dir;
00363 
00364      int *n_before;             /*
00365                                  * n_before[i] = product of n[j] for j < i 
00366                                  */
00367      int *n_after;              /* n_after[i] = product of n[j] for j > i */
00368 
00369      fftw_plan *plans;          /* 1d fftw plans for each dimension */
00370 
00371      int nbuffers, nwork;
00372      fftw_complex *work;        /* 
00373                                  * work array big enough to hold
00374                                  * nbuffers+1 of the largest dimension 
00375                                  * (has nwork elements)
00376                                  */
00377 } fftwnd_data;
00378 
00379 typedef fftwnd_data *fftwnd_plan;
00380 
00381 /* Initializing the FFTWND plan: */
00382 extern fftwnd_plan fftw2d_create_plan(int nx, int ny, fftw_direction dir,
00383                                       int flags);
00384 extern fftwnd_plan fftw3d_create_plan(int nx, int ny, int nz,
00385                                       fftw_direction dir, int flags);
00386 extern fftwnd_plan fftwnd_create_plan(int rank, const int *n,
00387                                       fftw_direction dir,
00388                                       int flags);
00389 
00390 extern fftwnd_plan fftw2d_create_plan_specific(int nx, int ny,
00391                                                fftw_direction dir,
00392                                                int flags,
00393                                            fftw_complex *in, int istride,
00394                                          fftw_complex *out, int ostride);
00395 extern fftwnd_plan fftw3d_create_plan_specific(int nx, int ny, int nz,
00396                                            fftw_direction dir, int flags,
00397                                            fftw_complex *in, int istride,
00398                                          fftw_complex *out, int ostride);
00399 extern fftwnd_plan fftwnd_create_plan_specific(int rank, const int *n,
00400                                                fftw_direction dir,
00401                                                int flags,
00402                                            fftw_complex *in, int istride,
00403                                          fftw_complex *out, int ostride);
00404 
00405 /* Freeing the FFTWND plan: */
00406 extern void fftwnd_destroy_plan(fftwnd_plan plan);
00407 
00408 /* Printing the plan: */
00409 extern void fftwnd_fprint_plan(FILE *f, fftwnd_plan p);
00410 extern void fftwnd_print_plan(fftwnd_plan p);
00411 #define FFTWND_HAS_PRINT_PLAN
00412 
00413 /* Computing the N-Dimensional FFT */
00414 extern void fftwnd(fftwnd_plan plan, int howmany,
00415                    fftw_complex *in, int istride, int idist,
00416                    fftw_complex *out, int ostride, int odist);
00417 extern void fftwnd_one(fftwnd_plan p, fftw_complex *in, fftw_complex *out);
00418 
00419 #ifdef __cplusplus
00420 }                               /* extern "C" */
00421 
00422 #endif                          /* __cplusplus */
00423 #endif                          /* FFTW_H */