The Tor Browser / file comparison
comparison: media/kiss_fft/README
media/kiss_fft/README
- branch
- TOR_BUG_9701
- changeset 8
- 97036ab72558
equal
deleted
inserted
replaced
| -1:000000000000 | 0:d4d5b8f61b86 |
|---|---|
| 1 KISS FFT - A mixed-radix Fast Fourier Transform based up on the principle, | |
| 2 "Keep It Simple, Stupid." | |
| 3 | |
| 4 There are many great fft libraries already around. Kiss FFT is not trying | |
| 5 to be better than any of them. It only attempts to be a reasonably efficient, | |
| 6 moderately useful FFT that can use fixed or floating data types and can be | |
| 7 incorporated into someone's C program in a few minutes with trivial licensing. | |
| 8 | |
| 9 USAGE: | |
| 10 | |
| 11 The basic usage for 1-d complex FFT is: | |
| 12 | |
| 13 #include "kiss_fft.h" | |
| 14 | |
| 15 kiss_fft_cfg cfg = kiss_fft_alloc( nfft ,is_inverse_fft ,0,0 ); | |
| 16 | |
| 17 while ... | |
| 18 | |
| 19 ... // put kth sample in cx_in[k].r and cx_in[k].i | |
| 20 | |
| 21 kiss_fft( cfg , cx_in , cx_out ); | |
| 22 | |
| 23 ... // transformed. DC is in cx_out[0].r and cx_out[0].i | |
| 24 | |
| 25 free(cfg); | |
| 26 | |
| 27 Note: frequency-domain data is stored from dc up to 2pi. | |
| 28 so cx_out[0] is the dc bin of the FFT | |
| 29 and cx_out[nfft/2] is the Nyquist bin (if exists) | |
| 30 | |
| 31 Declarations are in "kiss_fft.h", along with a brief description of the | |
| 32 functions you'll need to use. | |
| 33 | |
| 34 Code definitions for 1d complex FFTs are in kiss_fft.c. | |
| 35 | |
| 36 You can do other cool stuff with the extras you'll find in tools/ | |
| 37 | |
| 38 * multi-dimensional FFTs | |
| 39 * real-optimized FFTs (returns the positive half-spectrum: (nfft/2+1) complex frequency bins) | |
| 40 * fast convolution FIR filtering (not available for fixed point) | |
| 41 * spectrum image creation | |
| 42 | |
| 43 The core fft and most tools/ code can be compiled to use float, double, | |
| 44 Q15 short or Q31 samples. The default is float. | |
| 45 | |
| 46 | |
| 47 BACKGROUND: | |
| 48 | |
| 49 I started coding this because I couldn't find a fixed point FFT that didn't | |
| 50 use assembly code. I started with floating point numbers so I could get the | |
| 51 theory straight before working on fixed point issues. In the end, I had a | |
| 52 little bit of code that could be recompiled easily to do ffts with short, float | |
| 53 or double (other types should be easy too). | |
| 54 | |
| 55 Once I got my FFT working, I was curious about the speed compared to | |
| 56 a well respected and highly optimized fft library. I don't want to criticize | |
| 57 this great library, so let's call it FFT_BRANDX. | |
| 58 During this process, I learned: | |
| 59 | |
| 60 1. FFT_BRANDX has more than 100K lines of code. The core of kiss_fft is about 500 lines (cpx 1-d). | |
| 61 2. It took me an embarrassingly long time to get FFT_BRANDX working. | |
| 62 3. A simple program using FFT_BRANDX is 522KB. A similar program using kiss_fft is 18KB (without optimizing for size). | |
| 63 4. FFT_BRANDX is roughly twice as fast as KISS FFT in default mode. | |
| 64 | |
| 65 It is wonderful that free, highly optimized libraries like FFT_BRANDX exist. | |
| 66 But such libraries carry a huge burden of complexity necessary to extract every | |
| 67 last bit of performance. | |
| 68 | |
| 69 Sometimes simpler is better, even if it's not better. | |
| 70 | |
| 71 FREQUENTLY ASKED QUESTIONS: | |
| 72 Q: Can I use kissfft in a project with a ___ license? | |
| 73 A: Yes. See LICENSE below. | |
| 74 | |
| 75 Q: Why don't I get the output I expect? | |
| 76 A: The two most common causes of this are | |
| 77 1) scaling : is there a constant multiplier between what you got and what you want? | |
| 78 2) mixed build environment -- all code must be compiled with same preprocessor | |
| 79 definitions for FIXED_POINT and kiss_fft_scalar | |
| 80 | |
| 81 Q: Will you write/debug my code for me? | |
| 82 A: Probably not unless you pay me. I am happy to answer pointed and topical questions, but | |
| 83 I may refer you to a book, a forum, or some other resource. | |
| 84 | |
| 85 | |
| 86 PERFORMANCE: | |
| 87 (on Athlon XP 2100+, with gcc 2.96, float data type) | |
| 88 | |
| 89 Kiss performed 10000 1024-pt cpx ffts in .63 s of cpu time. | |
| 90 For comparison, it took md5sum twice as long to process the same amount of data. | |
| 91 | |
| 92 Transforming 5 minutes of CD quality audio takes less than a second (nfft=1024). | |
| 93 | |
| 94 DO NOT: | |
| 95 ... use Kiss if you need the Fastest Fourier Transform in the World | |
| 96 ... ask me to add features that will bloat the code | |
| 97 | |
| 98 UNDER THE HOOD: | |
| 99 | |
| 100 Kiss FFT uses a time decimation, mixed-radix, out-of-place FFT. If you give it an input buffer | |
| 101 and output buffer that are the same, a temporary buffer will be created to hold the data. | |
| 102 | |
| 103 No static data is used. The core routines of kiss_fft are thread-safe (but not all of the tools directory). | |
| 104 | |
| 105 No scaling is done for the floating point version (for speed). | |
| 106 Scaling is done both ways for the fixed-point version (for overflow prevention). | |
| 107 | |
| 108 Optimized butterflies are used for factors 2,3,4, and 5. | |
| 109 | |
| 110 The real (i.e. not complex) optimization code only works for even length ffts. It does two half-length | |
| 111 FFTs in parallel (packed into real&imag), and then combines them via twiddling. The result is | |
| 112 nfft/2+1 complex frequency bins from DC to Nyquist. If you don't know what this means, search the web. | |
| 113 | |
| 114 The fast convolution filtering uses the overlap-scrap method, slightly | |
| 115 modified to put the scrap at the tail. | |
| 116 | |
| 117 LICENSE: | |
| 118 Revised BSD License, see COPYING for verbiage. | |
| 119 Basically, "free to use&change, give credit where due, no guarantees" | |
| 120 Note this license is compatible with GPL at one end of the spectrum and closed, commercial software at | |
| 121 the other end. See http://www.fsf.org/licensing/licenses | |
| 122 | |
| 123 A commercial license is available which removes the requirement for attribution. Contact me for details. | |
| 124 | |
| 125 | |
| 126 TODO: | |
| 127 *) Add real optimization for odd length FFTs | |
| 128 *) Document/revisit the input/output fft scaling | |
| 129 *) Make doc describing the overlap (tail) scrap fast convolution filtering in kiss_fastfir.c | |
| 130 *) Test all the ./tools/ code with fixed point (kiss_fastfir.c doesn't work, maybe others) | |
| 131 | |
| 132 AUTHOR: | |
| 133 Mark Borgerding | |
| 134 Mark@Borgerding.net |
