Scilab [trunk]: scilab/modules/fftw/src/c/fftw3.h Source File

00001 /*
00002  * Copyright (c) 2003, 2006 Matteo Frigo
00003  * Copyright (c) 2003, 2006 Massachusetts Institute of Technology
00004  *
00005  * The following statement of license applies *only* to this header file,
00006  * and *not* to the other files distributed with FFTW or derived therefrom:
00007  * 
00008  * Redistribution and use in source and binary forms, with or without
00009  * modification, are permitted provided that the following conditions
00010  * are met:
00011  *
00012  * 1. Redistributions of source code must retain the above copyright
00013  *    notice, this list of conditions and the following disclaimer.
00014  *
00015  * 2. Redistributions in binary form must reproduce the above copyright
00016  *    notice, this list of conditions and the following disclaimer in the
00017  *    documentation and/or other materials provided with the distribution.
00018  *
00019  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
00020  * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00021  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00022  * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
00023  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00024  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
00025  * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00026  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
00027  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00028  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00029  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00030  */
00031 
00032 /***************************** NOTE TO USERS *********************************
00033  *
00034  *                 THIS IS A HEADER FILE, NOT A MANUAL
00035  *
00036  *    If you want to know how to use FFTW, please read the manual,
00037  *    online at http://www.fftw.org/doc/ and also included with FFTW.
00038  *    For a quick start, see the manual's tutorial section.
00039  *
00040  *   (Reading header files to learn how to use a library is a habit
00041  *    stemming from code lacking a proper manual.  Arguably, it's a
00042  *    *bad* habit in most cases, because header files can contain
00043  *    interfaces that are not part of the public, stable API.)
00044  *
00045  ****************************************************************************/
00046 
00047 /* header file for fftw3 */
00048 /* (The following is the CVS ID for this file, *not* the version
00049    number of FFTW:) */
00050 /* $Id: fftw3.h,v 1.90 2006-01-17 04:03:33 stevenj Exp $ */
00051 
00052 #ifndef FFTW3_H
00053 #define FFTW3_H
00054 
00055 #include <stdio.h>
00056 
00057 #ifdef __cplusplus
00058 extern "C"
00059 {
00060 #endif /* __cplusplus */
00061 
00062 /* If <complex.h> is included, use the C99 complex type.  Otherwise
00063    define a type bit-compatible with C99 complex */
00064 #if !defined(FFTW_NO_Complex) && defined(_Complex_I) && defined(complex) && defined(I)
00065 #  define FFTW_DEFINE_COMPLEX(R, C) typedef R _Complex C
00066 #else
00067 #  define FFTW_DEFINE_COMPLEX(R, C) typedef R C[2]
00068 #endif
00069 
00070 #define FFTW_CONCAT(prefix, name) prefix ## name
00071 #define FFTW_MANGLE_DOUBLE(name) FFTW_CONCAT(fftw_, name)
00072 #define FFTW_MANGLE_FLOAT(name) FFTW_CONCAT(fftwf_, name)
00073 #define FFTW_MANGLE_LONG_DOUBLE(name) FFTW_CONCAT(fftwl_, name)
00074 
00075 /* IMPORTANT: for Windows compilers, you should add a line
00076 */
00077 #define FFTW_DLL
00078 /*
00079    here and in kernel/ifftw.h if you are compiling/using FFTW as a
00080    DLL, in order to do the proper importing/exporting, or
00081    alternatively compile with -DFFTW_DLL or the equivalent
00082    command-line flag.  This is not necessary under MinGW/Cygwin, where
00083    libtool does the imports/exports automatically. */
00084 #if defined(FFTW_DLL) && (defined(_WIN32) || defined(__WIN32__))
00085    /* annoying Windows syntax for shared-library declarations */
00086 #  if defined(COMPILING_FFTW) /* defined in api.h when compiling FFTW */
00087 #    define FFTW_EXTERN extern __declspec(dllexport) 
00088 #  else /* user is calling FFTW; import symbol */
00089 #    define FFTW_EXTERN extern __declspec(dllimport) 
00090 #  endif
00091 #else
00092 #  define FFTW_EXTERN extern
00093 #endif
00094 
00095 enum fftw_r2r_kind_do_not_use_me {
00096      FFTW_R2HC=0, FFTW_HC2R=1, FFTW_DHT=2,
00097      FFTW_REDFT00=3, FFTW_REDFT01=4, FFTW_REDFT10=5, FFTW_REDFT11=6,
00098      FFTW_RODFT00=7, FFTW_RODFT01=8, FFTW_RODFT10=9, FFTW_RODFT11=10
00099 };
00100 
00101 struct fftw_iodim_do_not_use_me {
00102      int n;                     /* dimension size */
00103      int is;                    /* input stride */
00104      int os;                    /* output stride */
00105 };
00106 
00107 /*
00108   huge second-order macro that defines prototypes for all API
00109   functions.  We expand this macro for each supported precision
00110  
00111   X: name-mangling macro
00112   R: real data type
00113   C: complex data type
00114 */
00115 
00116 #define FFTW_DEFINE_API(X, R, C)                                           \
00117                                                                            \
00118 FFTW_DEFINE_COMPLEX(R, C);                                                 \
00119                                                                            \
00120 typedef struct X(plan_s) *X(plan);                                         \
00121                                                                            \
00122 typedef struct fftw_iodim_do_not_use_me X(iodim);                          \
00123                                                                            \
00124 typedef enum fftw_r2r_kind_do_not_use_me X(r2r_kind);                      \
00125                                                                            \
00126 FFTW_EXTERN void X(execute)(const X(plan) p);                              \
00127                                                                            \
00128 FFTW_EXTERN X(plan) X(plan_dft)(int rank, const int *n,                    \
00129                     C *in, C *out, int sign, unsigned flags);              \
00130                                                                            \
00131 FFTW_EXTERN X(plan) X(plan_dft_1d)(int n, C *in, C *out, int sign,         \
00132                        unsigned flags);                                    \
00133 FFTW_EXTERN X(plan) X(plan_dft_2d)(int nx, int ny,                         \
00134                        C *in, C *out, int sign, unsigned flags);           \
00135 FFTW_EXTERN X(plan) X(plan_dft_3d)(int nx, int ny, int nz,                 \
00136                        C *in, C *out, int sign, unsigned flags);           \
00137                                                                            \
00138 FFTW_EXTERN X(plan) X(plan_many_dft)(int rank, const int *n,               \
00139                          int howmany,                                      \
00140                          C *in, const int *inembed,                        \
00141                          int istride, int idist,                           \
00142                          C *out, const int *onembed,                       \
00143                          int ostride, int odist,                           \
00144                          int sign, unsigned flags);                        \
00145                                                                            \
00146 FFTW_EXTERN X(plan) X(plan_guru_dft)(int rank, const X(iodim) *dims,       \
00147                          int howmany_rank,                                 \
00148                          const X(iodim) *howmany_dims,                     \
00149                          C *in, C *out,                                    \
00150                          int sign, unsigned flags);                        \
00151 FFTW_EXTERN X(plan) X(plan_guru_split_dft)(int rank, const X(iodim) *dims, \
00152                          int howmany_rank,                                 \
00153                          const X(iodim) *howmany_dims,                     \
00154                          R *ri, R *ii, R *ro, R *io,                       \
00155                          unsigned flags);                                  \
00156                                                                            \
00157 FFTW_EXTERN void X(execute_dft)(const X(plan) p, C *in, C *out);           \
00158 FFTW_EXTERN void X(execute_split_dft)(const X(plan) p, R *ri, R *ii,       \
00159                                       R *ro, R *io);                       \
00160                                                                            \
00161 FFTW_EXTERN X(plan) X(plan_many_dft_r2c)(int rank, const int *n,           \
00162                              int howmany,                                  \
00163                              R *in, const int *inembed,                    \
00164                              int istride, int idist,                       \
00165                              C *out, const int *onembed,                   \
00166                              int ostride, int odist,                       \
00167                              unsigned flags);                              \
00168                                                                            \
00169 FFTW_EXTERN X(plan) X(plan_dft_r2c)(int rank, const int *n,                \
00170                         R *in, C *out, unsigned flags);                    \
00171                                                                            \
00172 FFTW_EXTERN X(plan) X(plan_dft_r2c_1d)(int n,R *in,C *out,unsigned flags); \
00173 FFTW_EXTERN X(plan) X(plan_dft_r2c_2d)(int nx, int ny,                     \
00174                            R *in, C *out, unsigned flags);                 \
00175 FFTW_EXTERN X(plan) X(plan_dft_r2c_3d)(int nx, int ny,                     \
00176                            int nz,                                         \
00177                            R *in, C *out, unsigned flags);                 \
00178                                                                            \
00179                                                                            \
00180 FFTW_EXTERN X(plan) X(plan_many_dft_c2r)(int rank, const int *n,           \
00181                              int howmany,                                  \
00182                              C *in, const int *inembed,                    \
00183                              int istride, int idist,                       \
00184                              R *out, const int *onembed,                   \
00185                              int ostride, int odist,                       \
00186                              unsigned flags);                              \
00187                                                                            \
00188 FFTW_EXTERN X(plan) X(plan_dft_c2r)(int rank, const int *n,                \
00189                         C *in, R *out, unsigned flags);                    \
00190                                                                            \
00191 FFTW_EXTERN X(plan) X(plan_dft_c2r_1d)(int n,C *in,R *out,unsigned flags); \
00192 FFTW_EXTERN X(plan) X(plan_dft_c2r_2d)(int nx, int ny,                     \
00193                            C *in, R *out, unsigned flags);                 \
00194 FFTW_EXTERN X(plan) X(plan_dft_c2r_3d)(int nx, int ny,                     \
00195                            int nz,                                         \
00196                            C *in, R *out, unsigned flags);                 \
00197                                                                            \
00198 FFTW_EXTERN X(plan) X(plan_guru_dft_r2c)(int rank, const X(iodim) *dims,   \
00199                              int howmany_rank,                             \
00200                              const X(iodim) *howmany_dims,                 \
00201                              R *in, C *out,                                \
00202                              unsigned flags);                              \
00203 FFTW_EXTERN X(plan) X(plan_guru_dft_c2r)(int rank, const X(iodim) *dims,   \
00204                              int howmany_rank,                             \
00205                              const X(iodim) *howmany_dims,                 \
00206                              C *in, R *out,                                \
00207                              unsigned flags);                              \
00208                                                                            \
00209 FFTW_EXTERN X(plan) X(plan_guru_split_dft_r2c)(                            \
00210                              int rank, const X(iodim) *dims,               \
00211                              int howmany_rank,                             \
00212                              const X(iodim) *howmany_dims,                 \
00213                              R *in, R *ro, R *io,                          \
00214                              unsigned flags);                              \
00215 FFTW_EXTERN X(plan) X(plan_guru_split_dft_c2r)(                            \
00216                              int rank, const X(iodim) *dims,               \
00217                              int howmany_rank,                             \
00218                              const X(iodim) *howmany_dims,                 \
00219                              R *ri, R *ii, R *out,                         \
00220                              unsigned flags);                              \
00221                                                                            \
00222 FFTW_EXTERN void X(execute_dft_r2c)(const X(plan) p, R *in, C *out);       \
00223 FFTW_EXTERN void X(execute_dft_c2r)(const X(plan) p, C *in, R *out);       \
00224                                                                            \
00225 FFTW_EXTERN void X(execute_split_dft_r2c)(const X(plan) p,                 \
00226                                           R *in, R *ro, R *io);            \
00227 FFTW_EXTERN void X(execute_split_dft_c2r)(const X(plan) p,                 \
00228                                           R *ri, R *ii, R *out);           \
00229                                                                            \
00230 FFTW_EXTERN X(plan) X(plan_many_r2r)(int rank, const int *n,               \
00231                          int howmany,                                      \
00232                          R *in, const int *inembed,                        \
00233                          int istride, int idist,                           \
00234                          R *out, const int *onembed,                       \
00235                          int ostride, int odist,                           \
00236                          const X(r2r_kind) *kind, unsigned flags);         \
00237                                                                            \
00238 FFTW_EXTERN X(plan) X(plan_r2r)(int rank, const int *n, R *in, R *out,     \
00239                     const X(r2r_kind) *kind, unsigned flags);              \
00240                                                                            \
00241 FFTW_EXTERN X(plan) X(plan_r2r_1d)(int n, R *in, R *out,                   \
00242                        X(r2r_kind) kind, unsigned flags);                  \
00243 FFTW_EXTERN X(plan) X(plan_r2r_2d)(int nx, int ny, R *in, R *out,          \
00244                        X(r2r_kind) kindx, X(r2r_kind) kindy,               \
00245                        unsigned flags);                                    \
00246 FFTW_EXTERN X(plan) X(plan_r2r_3d)(int nx, int ny, int nz,                 \
00247                        R *in, R *out, X(r2r_kind) kindx,                   \
00248                        X(r2r_kind) kindy, X(r2r_kind) kindz,               \
00249                        unsigned flags);                                    \
00250                                                                            \
00251 FFTW_EXTERN X(plan) X(plan_guru_r2r)(int rank, const X(iodim) *dims,       \
00252                          int howmany_rank,                                 \
00253                          const X(iodim) *howmany_dims,                     \
00254                          R *in, R *out,                                    \
00255                          const X(r2r_kind) *kind, unsigned flags);         \
00256 FFTW_EXTERN void X(execute_r2r)(const X(plan) p, R *in, R *out);           \
00257                                                                            \
00258 FFTW_EXTERN void X(destroy_plan)(X(plan) p);                               \
00259 FFTW_EXTERN void X(forget_wisdom)(void);                                   \
00260 FFTW_EXTERN void X(cleanup)(void);                                         \
00261                                                                            \
00262 FFTW_EXTERN void X(set_timelimit)(double);                                 \
00263                                                                            \
00264 FFTW_EXTERN void X(plan_with_nthreads)(int nthreads);                      \
00265 FFTW_EXTERN int X(init_threads)(void);                                     \
00266 FFTW_EXTERN void X(cleanup_threads)(void);                                 \
00267                                                                            \
00268 FFTW_EXTERN void X(export_wisdom_to_file)(FILE *output_file);              \
00269 FFTW_EXTERN char *X(export_wisdom_to_string)(void);                        \
00270 FFTW_EXTERN void X(export_wisdom)(void (*write_char)(char c, void *),      \
00271                                   void *data);                             \
00272 FFTW_EXTERN int X(import_system_wisdom)(void);                             \
00273 FFTW_EXTERN int X(import_wisdom_from_file)(FILE *input_file);              \
00274 FFTW_EXTERN int X(import_wisdom_from_string)(const char *input_string);    \
00275 FFTW_EXTERN int X(import_wisdom)(int (*read_char)(void *), void *data);    \
00276                                                                            \
00277 FFTW_EXTERN void X(fprint_plan)(const X(plan) p, FILE *output_file);       \
00278 FFTW_EXTERN void X(print_plan)(const X(plan) p);                           \
00279                                                                            \
00280 FFTW_EXTERN void *X(malloc)(size_t n);                                     \
00281 FFTW_EXTERN void X(free)(void *p);                                         \
00282                                                                            \
00283 FFTW_EXTERN void X(flops)(const X(plan) p,                                 \
00284                           double *add, double *mul, double *fmas);         \
00285 FFTW_EXTERN double X(estimate_cost)(const X(plan) p);                      \
00286                                                                            \
00287 FFTW_EXTERN const char X(version)[];                                       \
00288 FFTW_EXTERN const char X(cc)[];                                            \
00289 FFTW_EXTERN const char X(codelet_optim)[];
00290 
00291 
00292 /* end of FFTW_DEFINE_API macro */
00293 
00294 FFTW_DEFINE_API(FFTW_MANGLE_DOUBLE, double, fftw_complex)
00295 FFTW_DEFINE_API(FFTW_MANGLE_FLOAT, float, fftwf_complex)
00296 FFTW_DEFINE_API(FFTW_MANGLE_LONG_DOUBLE, long double, fftwl_complex)
00297 
00298 #define FFTW_FORWARD (-1)
00299 #define FFTW_BACKWARD (+1)
00300 
00301 #define FFTW_NO_TIMELIMIT (-1.0)
00302 
00303 /* documented flags */
00304 #define FFTW_MEASURE (0U)
00305 #define FFTW_DESTROY_INPUT (1U << 0)
00306 #define FFTW_UNALIGNED (1U << 1)
00307 #define FFTW_CONSERVE_MEMORY (1U << 2)
00308 #define FFTW_EXHAUSTIVE (1U << 3) /* NO_EXHAUSTIVE is default */
00309 #define FFTW_PRESERVE_INPUT (1U << 4) /* cancels FFTW_DESTROY_INPUT */
00310 #define FFTW_PATIENT (1U << 5) /* IMPATIENT is default */
00311 #define FFTW_ESTIMATE (1U << 6)
00312 
00313 /* undocumented beyond-guru flags */
00314 #define FFTW_ESTIMATE_PATIENT (1U << 7)
00315 #define FFTW_BELIEVE_PCOST (1U << 8)
00316 #define FFTW_NO_DFT_R2HC (1U << 9)
00317 #define FFTW_NO_NONTHREADED (1U << 10)
00318 #define FFTW_NO_BUFFERING (1U << 11)
00319 #define FFTW_NO_INDIRECT_OP (1U << 12)
00320 #define FFTW_ALLOW_LARGE_GENERIC (1U << 13) /* NO_LARGE_GENERIC is default */
00321 #define FFTW_NO_RANK_SPLITS (1U << 14)
00322 #define FFTW_NO_VRANK_SPLITS (1U << 15)
00323 #define FFTW_NO_VRECURSE (1U << 16)
00324 #define FFTW_NO_SIMD (1U << 17)
00325 #define FFTW_NO_SLOW (1U << 18)
00326 #define FFTW_NO_FIXED_RADIX_LARGE_N (1U << 19)
00327 #define FFTW_ALLOW_PRUNING (1U << 20)
00328 
00329 #ifdef __cplusplus
00330 }  /* extern "C" */
00331 #endif /* __cplusplus */
00332 
00333 #endif /* FFTW3_H */