@database "easyFFT" @index INDEXNODE @node "MAIN" "MAIN" @next "Introduction" @toc "MAIN" @{b}easyFFT.doc@{ub} Documentation for easyFFT V2.0 Last Revised: July 15th, 1997 Copyright © 1996, 1997 Alexander Marx. All Rights Reserved. @{b}Contents:@{ub} @{" Introduction " link "Introduction"} @{" Disclaimer " link "Disclaimer"} @{" Copyright " link "Copyright"} @{" Requirements " link "Requirements"} @{" Installation " link "Installation"} @{" Notes " link "Notes"} @{" History " link "History"} @{" Author " link "Author"} @{b}Appendix@{ub} @{" Autodocs " link "Autodocs"} @endnode @node Introduction "Introduction" @next Disclaimer @toc "MAIN" @{b}Introduction@{ub} Long time ago I built an A/D-Converter and as I was very busy in constructing my own hifi-loudspeakers I was in the need of a software which could calculate the frequency spectrum out of a measured signal. So, as I couldn't find an appropriate piece of software for my little Amiga, I decided to write my own... ...and here it is now - transformed into a shared library. It is a kept very simple and is written in plain C, it is *not* thought for realtime applications, 'cause it's tooooooo slooooow - at least on my A500 :/ - but it works. It was written on an A500/020/882 using SAS/C V6.57; BTW, be warned ... as I've no MMU there may be lots of enforcer hits. (10-Jul-97) @endnode @node Disclaimer "Disclaimer" @next Copyright @toc "MAIN" @{b}Disclaimer@{ub} THERE IS NO WARRANTY FOR THE SOFTWARE TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHERE OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. I HERBY REJECT ANY LIABILITY OR RESPONSIBILTITY FOR THESE OR ANY OTHER CONSEQUENCES FROM THE USE OF >easyFFT< WHATSOEVER. THIS INCLUDES, BUT IS NOT LIMITED TO, DAMAGE TO YOUR EQUIPMENT, TO YOUR DATA, PERSONAL INJURIES, FINANCIAL LOSS OR ANY OTHER KINDS OF SIDE EFFECTS. >easyFFT< IS PROVIDED AS-IS. THIS MEANS I DO NOT GUARANTEE THAT >easyFFT< IS FIT FOR ANY SPECIFIC PURPOSE AND I DO NOT GUARANTEE ANY BUG FIXES, UPDATES OR HELP DURING ERROR RECOVERY. @endnode @node Copyright "Copyright" @next Requirements @toc "MAIN" @{b}Copyright & Distribution@{ub} @{i}easyFFT.library - Version 2.0@{ui} Copyright © 1996, 1997 Alexander Marx All Rights Reserved. "easyFFT" is freeware, copyrighted software. This copyright applies to all files in the easyFFT distribution. Permission is granted to distribute this software as long as the archive stays intact. Files in the archive can be modified but *must not* be released in any shape or form. This software is *not* public domain so no authorization is given to reverse engineer the code, modify it and release it. Commercial distribution of easyFFT.library and/or its relative files is *not* allowed without written permission from the author. @endnode @node Requirements "Requirements" @next Installation @toc "MAIN" @{b}Requirements@{ub} Hmm, - an AMIGA would be good, - a few kBytes of free mem, - the mathieeedoubbas.library and the mathieeedoutrans.library for the easyFFT_000.library version; - and of course at least a 020+fpu for the easyFFT_020+fpu.library version; @endnode @node Installation "Installation" @next Notes @toc "MAIN" @{b}Installation@{ub} It's pretty simple, just put the library you want (easyFFT_000.library or the 020+FPU version) in the LIBS: directory and rename it to easyFFT.library; then copy the header files in the appropriate directories. Ready. _ @endnode @node Notes "Notes" @next History @toc "MAIN" @{b}Notes@{ub} * Sampling-rate: Speed of your A/D-Converter; rated at samples/second * Sampling-theorem: Says, that you may only sample a signal which highest frequency (don't forget the harmonics) must be less or equal to sampling-rate/2. Thats logical, 'cause you need at least 2 measured points to reconstruct a sine-wave. So you must use a low pass filter at sampling-rate/2 (or lower) in order to get correct results. * FFT: Fast Fourier Transformation, is an arithmetical algorithm which can be used (or abused?) to do spectrum analysis. (for more info on FFT see: A.V.Oppenheim and R.W.Schaffer, @{i}Digital Sound Processing@{ui}, Prentice-Hall, Englewood Cliffs, NJ, 1975) * FFT resolution: Resolution of the calculated frequency spectrum. Depends on the number of samples and the sampling-rate. e.g.: NRs = 1024 samples taken; at Sr = 44.1kHz sampling rate; FFTres = Sr/NRs = 44.1kHz/1024 = 43.066Hz @endnode @node History "History" @next Author @toc "MAIN" @{b}History@{ub} V1.0 "!§^#&@" - a little bit to buggy to actually release it to the public V1.1 (June 21st, 1997, 1st public release) - initial release V2.0 (July 15th, 1997, 2nd public release) - several minor bug fixes - added a synthesizer mode - and added assembler include files @endnode @node Author "Author" @next Autodocs @toc "MAIN" @{b}Author@{ub} Send bugreports, comments, questions, donations, gifts or whatever to: Alexander Marx Leiblfing 81 A-6410 Pettnau AUSTRIA <--- in the middle of Europe, near the Alps, *no* kangaroos!!! You can reach me also via electronic mail: mady@pettnau.netwing.at @endnode @node Autodocs "Autodocs" @next new @toc "MAIN" @{b}Autodocs@{ub} @{i}easyFFT.library/@{ui} @{" eFFTnew() " link "new"} ... initialize a new handle @{" eFFTcalc() " link "calc"} ... do the actual calculation @{" eFFTfree() " link "free"} ... free the handle @{" eFFTsetdat() " link "setd"} ... set attributes @{" eFFTgetdat() " link "getd"} ... get attributes @endnode @node new "easyFFT.library/eFFTnew()" @next calc @toc "Autodocs" @{b}easyFFT.library/eFFTnew@{ub} @{b}NAME@{ub} eFFTnew -- Create a new handle @{b}SYNOPSIS@{ub} handle = eFFTnew(num); D0 -30(A6) D0 APTR eFFTnew(ULONG); @{b}FUNCTION@{ub} Creates a new handle. @{b}INPUTS@{ub} num - the number of entries in the data array; (New in V2.0: You can now change num to *any* other value you want at a later moment, using eFFTsetdat. However, you must not set this parameter to zero!) @{b}NOTE@{ub} All calls to eFFTnew should have matching calls to eFFTfree! IMPORTANT! Make sure the value of max is 2^n (e.g. max=2^8=256); In every other case the value will be decreased to 2^(n-1); (e.g. max=250; 2^8=256; 2^7=128; -> max=2^7=128) The reason for this is, because of the used algorithm. Sorry... @{b}RESULTS@{ub} APTR - Pointer to a handle. NULL if failed. @{b}BUGS@{ub} None known. @endnode @node calc "easyFFT.library/eFFTcalc()" @next free @toc "Autodocs" @{b}easyFFT.library/eFFTcalc@{ub} @{b}NAME@{ub} eFFTcalc -- start calculation @{b}SYNOPSIS@{ub} eFFTcalc(handle); -36(A6) A0 void eFFTcalc(APTR); @{b}FUNCTION@{ub} This function does the actual calulations (analizing/synthesizing) @{b}INPUTS@{ub} handle - pointer to handle as returned by eFFTnew @{b}NOTE@{ub} This handle must be properly initialized using eFFTsetdat, because this function does not very much error checking, so be careful! @{b}RESULTS@{ub} The calculated data is now stored in private memory; to get that data you have to use eFFTgetdat. @{b}BUGS@{ub} None known. @endnode @node free "easyFFT.library/eFFTfree()" @next setd @toc "Autodocs" @{b}easyFFT.library/eFFTfree@{ub} @{b}NAME@{ub} eFFTfree -- Conclude access to a handle @{b}SYNOPSIS@{ub} eFFTfree(handle); -42(A6) A0 void eFFTfree(APTR); @{b}FUNCTION@{ub} Frees the memory taken by a handle. @{b}INPUTS@{ub} handle - pointer to handle as returned by eFFTnew @{b}NOTE@{ub} This function handles a NULL pointer correctly; so if you pass a handle that equals NULL it frees nothing. @{b}RESULTS@{ub} None @{b}BUGS@{ub} None known. @endnode @node setd "easyFFT.library/eFFTsetdat()" @next getd @toc "Autodocs" @{b}easyFFT.library/eFFTsetdat@{ub} @{b}NAME@{ub} eFFTsetdat -- Set attribute for a handle @{b}SYNOPSIS@{ub} success = eFFTsetdat(handle, tag, data); D0 -48(A6) A0 D0 D1 BOOL eFFTsetdat(APTR, ULONG, ULONG); @{b}FUNCTION@{ub} This function sets an attribute for a previously allocated handle. @{b}INPUTS@{ub} handle - pointer to handle as returned by eFFTnew @{u}Supported Tags:@{uu} eFFT_NUM: data specifies a new value for the length of your data array. New in V2.0 and later is, that you can set that value now higher than the one set using eFFTnew; the internal arrays will then be freed and new ones will be allocated; so the pointers you get from eFFTgetdat will change! However, if there was not enough mem to allocate the new arrays the old ones will be restored; so you still have to call eFFTfree if you want to free everything! In case that not enough mem was available you will get FALSE as return code from eFFTsetdat. And of course the value of num is restricted to 2^n! (see eFFTnew for further details on that restriction) eFFT_SIG: set a new pointer to your signal array (=previously called data array), on which you want to do spectrum analizing. eFFT_SYN: If data equals TRUE, then the library will switch to the new synthesizer mode else it will fall back to analizer mode. (default: analizer mode) eFFT_ASP: data should contain a pointer to your array of amplitudes; eFFT_NUM and eFFT_SRATE *must* be set correctly *before* you set this parameter; else the library will not accept your parameter and returns a FALSE! eFFT_PSP: data should contain a pointer to your array of phasedisplacements; the values of that array should be in the range of +PI..-PI; If you set this tag, eFFT_DOPD is automatically set to TRUE, because the library thinks that you want to include the phasedisplacements into the synthesizing process! eFFT_NUM and eFFT_SRATE *must* be set correctly *before* you set this parameter; else the library will not accept your parameter and returns a FALSE! eFFT_TRASH: data should contain TRUE or FALSE wether you allow the library to use (trash) your signal data array or not; (default: FALSE) This parameter is only effective in analizer mode, because library does never use your amp.- or phase.-arrays if you are in synthesizer mode. eFFT_SRATE: data should contain the sampling rate (in Hz; Smpls/Sec) This value is now only optional in analizer mode! In synthesizer mode you *must set* this tag *before* you can set eFFT_AMP and/or eFFT_PHA eFFT_DOPD: If data equals TRUE, then the library will calculate/use the frequency spectrum including the phasedisplacements; (default: FALSE, however if you set eFFT_PHA it will change to TRUE!) In analizer mode it tells the library to calculate the phasedisplacements and in synthesizer mode it tells the library to use the phasedisplacements additionally to the given amplitudes to create the signal. In every case if set to TRUE it slows down the whole thing, because of the additional calculations. @{b}NOTE@{ub} Keep in mind that this function may change only one tag at once. If you set eFFT_TRASH to TRUE the library may use (trash) your signal data array, the reason for this is - speed! Because then the library doesn't have to copy your signal data array every time you call eFFTcalc. However, your signal data array may contain other values afterwards. So, if you need the old values later set eFFT_TRASH to FALSE. Keep also in mind, that you can not do analizing and synthesizing in parallel with just one handle - the reason for this is that several internal arrays and variables will interfere with each other, sorry. If you need to do it in parallel, just allocate a second handle with eFFTnew. @{b}RESULTS@{ub} success - TRUE if everything worked else FALSE. (If you receive a FALSE, check your data array; maybe you gave the library a NULL pointer. :( ) @{b}BUGS@{ub} None known. @endnode @node getd "easyFFT.library/eFFTgetdat()" @toc "Autodocs" @{b}easyFFT.library/eFFTgetdat@{ub} @{b}NAME@{ub} eFFTgetdat -- Get attribute from a handle @{b}SYNOPSIS@{ub} data = eFFTgetdat(handle, tag); D0 -54(A6) A0 D0 APTR eFFTgetdat(APTR, ULONG); @{b}FUNCTION@{ub} This function gets an attribute from a handle. @{b}INPUTS@{ub} handle - pointer to handle as returned by eFFTnew @{u}Supported Tags:@{uu} eFFT_NUM: returns a pointer to the length of your data array. However, keep in mind that this value may differ from the one you thought you set, because of the 2^n restriction. (see eFFTnew or eFFTsetdat) eFFT_SIG: returns a pointer to your signal data array. eFFT_TRASH: returns TRUE or FALSE, wether you allowed the library to use (trash) your data array or not. eFFT_SRATE: returns a pointer to your sampling rate. eFFT_DOPD: returns TRUE or FALSE, wether the library shall calc the phasedisplacements or not eFFT_RESOL: returns pointer to the calculated FFT resolution; this value is only available if you have set the eFFT_SRATE before. eFFT_ASP: returns a pointer to the calculated frequency spectrum. (= the array of amplitudes) eFFT_PSP: returna apointer to the calculated frequency spectrum. (= the array of phasedisplacments) eFFT_SYN: returns a pointer to the synthesized signal. @{b}NOTE@{ub} None @{b}RESULTS@{ub} (see above) @{b}BUGS@{ub} None known. @endnode