1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/libs/kissfft/README	Sat Feb 01 19:58:19 2014 +0200
     1.3 @@ -0,0 +1,134 @@
     1.4 +KISS FFT - A mixed-radix Fast Fourier Transform based up on the principle, 
     1.5 +"Keep It Simple, Stupid."
     1.6 +
     1.7 +    There are many great fft libraries already around.  Kiss FFT is not trying
     1.8 +to be better than any of them.  It only attempts to be a reasonably efficient, 
     1.9 +moderately useful FFT that can use fixed or floating data types and can be 
    1.10 +incorporated into someone's C program in a few minutes with trivial licensing.
    1.11 +
    1.12 +USAGE:
    1.13 +
    1.14 +    The basic usage for 1-d complex FFT is:
    1.15 +
    1.16 +        #include "kiss_fft.h"
    1.17 +
    1.18 +        kiss_fft_cfg cfg = kiss_fft_alloc( nfft ,is_inverse_fft ,0,0 );
    1.19 +
    1.20 +        while ...
    1.21 +        
    1.22 +            ... // put kth sample in cx_in[k].r and cx_in[k].i
    1.23 +            
    1.24 +            kiss_fft( cfg , cx_in , cx_out );
    1.25 +            
    1.26 +            ... // transformed. DC is in cx_out[0].r and cx_out[0].i 
    1.27 +            
    1.28 +        free(cfg);
    1.29 +
    1.30 +    Note: frequency-domain data is stored from dc up to 2pi.
    1.31 +    so cx_out[0] is the dc bin of the FFT
    1.32 +    and cx_out[nfft/2] is the Nyquist bin (if exists)
    1.33 +
    1.34 +    Declarations are in "kiss_fft.h", along with a brief description of the 
    1.35 +functions you'll need to use. 
    1.36 +
    1.37 +Code definitions for 1d complex FFTs are in kiss_fft.c.
    1.38 +
    1.39 +You can do other cool stuff with the extras you'll find in tools/
    1.40 +
    1.41 +    * multi-dimensional FFTs 
    1.42 +    * real-optimized FFTs  (returns the positive half-spectrum: (nfft/2+1) complex frequency bins)
    1.43 +    * fast convolution FIR filtering (not available for fixed point)
    1.44 +    * spectrum image creation
    1.45 +
    1.46 +The core fft and most tools/ code can be compiled to use float, double,
    1.47 + Q15 short or Q31 samples. The default is float.
    1.48 +
    1.49 +
    1.50 +BACKGROUND:
    1.51 +
    1.52 +    I started coding this because I couldn't find a fixed point FFT that didn't 
    1.53 +use assembly code.  I started with floating point numbers so I could get the 
    1.54 +theory straight before working on fixed point issues.  In the end, I had a 
    1.55 +little bit of code that could be recompiled easily to do ffts with short, float
    1.56 +or double (other types should be easy too).  
    1.57 +
    1.58 +    Once I got my FFT working, I was curious about the speed compared to
    1.59 +a well respected and highly optimized fft library.  I don't want to criticize 
    1.60 +this great library, so let's call it FFT_BRANDX.
    1.61 +During this process, I learned:
    1.62 +
    1.63 +    1. FFT_BRANDX has more than 100K lines of code. The core of kiss_fft is about 500 lines (cpx 1-d).
    1.64 +    2. It took me an embarrassingly long time to get FFT_BRANDX working.
    1.65 +    3. A simple program using FFT_BRANDX is 522KB. A similar program using kiss_fft is 18KB (without optimizing for size).
    1.66 +    4. FFT_BRANDX is roughly twice as fast as KISS FFT in default mode.
    1.67 +
    1.68 +    It is wonderful that free, highly optimized libraries like FFT_BRANDX exist.
    1.69 +But such libraries carry a huge burden of complexity necessary to extract every 
    1.70 +last bit of performance.
    1.71 +
    1.72 +    Sometimes simpler is better, even if it's not better.
    1.73 +
    1.74 +FREQUENTLY ASKED QUESTIONS:
    1.75 +	Q: Can I use kissfft in a project with a ___ license?
    1.76 +	A: Yes.  See LICENSE below.
    1.77 +
    1.78 +	Q: Why don't I get the output I expect?
    1.79 +	A: The two most common causes of this are 
    1.80 +		1) scaling : is there a constant multiplier between what you got and what you want?
    1.81 +		2) mixed build environment -- all code must be compiled with same preprocessor 
    1.82 +		definitions for FIXED_POINT and kiss_fft_scalar
    1.83 +
    1.84 +	Q: Will you write/debug my code for me?
    1.85 +	A: Probably not unless you pay me.  I am happy to answer pointed and topical questions, but 
    1.86 +	I may refer you to a book, a forum, or some other resource.
    1.87 +
    1.88 +
    1.89 +PERFORMANCE:
    1.90 +    (on Athlon XP 2100+, with gcc 2.96, float data type)
    1.91 +
    1.92 +    Kiss performed 10000 1024-pt cpx ffts in .63 s of cpu time.
    1.93 +    For comparison, it took md5sum twice as long to process the same amount of data.
    1.94 +
    1.95 +    Transforming 5 minutes of CD quality audio takes less than a second (nfft=1024). 
    1.96 +
    1.97 +DO NOT:
    1.98 +    ... use Kiss if you need the Fastest Fourier Transform in the World
    1.99 +    ... ask me to add features that will bloat the code
   1.100 +
   1.101 +UNDER THE HOOD:
   1.102 +
   1.103 +    Kiss FFT uses a time decimation, mixed-radix, out-of-place FFT. If you give it an input buffer  
   1.104 +    and output buffer that are the same, a temporary buffer will be created to hold the data.
   1.105 +
   1.106 +    No static data is used.  The core routines of kiss_fft are thread-safe (but not all of the tools directory).
   1.107 +
   1.108 +    No scaling is done for the floating point version (for speed).  
   1.109 +    Scaling is done both ways for the fixed-point version (for overflow prevention).
   1.110 +
   1.111 +    Optimized butterflies are used for factors 2,3,4, and 5. 
   1.112 +
   1.113 +    The real (i.e. not complex) optimization code only works for even length ffts.  It does two half-length
   1.114 +    FFTs in parallel (packed into real&imag), and then combines them via twiddling.  The result is 
   1.115 +    nfft/2+1 complex frequency bins from DC to Nyquist.  If you don't know what this means, search the web.
   1.116 +
   1.117 +    The fast convolution filtering uses the overlap-scrap method, slightly 
   1.118 +    modified to put the scrap at the tail.
   1.119 +
   1.120 +LICENSE:
   1.121 +    Revised BSD License, see COPYING for verbiage. 
   1.122 +    Basically, "free to use&change, give credit where due, no guarantees"
   1.123 +    Note this license is compatible with GPL at one end of the spectrum and closed, commercial software at 
   1.124 +    the other end.  See http://www.fsf.org/licensing/licenses
   1.125 +
   1.126 +    A commercial license is available which removes the requirement for attribution.  Contact me for details.
   1.127 +
   1.128 +  
   1.129 +TODO:
   1.130 +    *) Add real optimization for odd length FFTs 
   1.131 +    *) Document/revisit the input/output fft scaling
   1.132 +    *) Make doc describing the overlap (tail) scrap fast convolution filtering in kiss_fastfir.c
   1.133 +    *) Test all the ./tools/ code with fixed point (kiss_fastfir.c doesn't work, maybe others)
   1.134 +
   1.135 +AUTHOR:
   1.136 +    Mark Borgerding
   1.137 +    Mark@Borgerding.net