FREQ.EXE:

FREQ.EXE is a program for the ProAudio Spectrum/Studio 16 sound cards.
It samples the input, performs an FFT, and graphs the output.  
INI file and command line options provide the user with the ability to 
select linear/log frequency and amplitude scales as well as sampling rates, 
length of the FFT, and windowing functions.  This program will run on any
8086 compatible computer.  Graphics is done using the Borland .BGI drivers, 
so the file EGAVGA.BGI is required to be in either the same directory as 
the executable or in the directory c:\borlandc\bgi.  

FREQ386.EXE:

FREQ386.EXE is the same as FREQ.EXE, except it has been compiled with full 
optimization and 80386 code enabled, so you will need at least an 80386 
processor to run it.  This program will perform and plot 1024 point FFTs at
a rate of 35 per second on a 486/33 and 512 point FFTs at a rate of 70 per second.  
(On a 486/33 with small memory model, a 1024 point FFT takes 16.5ms.)  
The program allows up to 2048 point FFTs (or higher if you change the source 
slightly).  

FILE LIST:

FREQ.EXE     executable program, described above
FREQ386.EXE  executable program, described above
FREQ.TXT     (you are reading it)
FREQ.INI     initialization file for FREQ.EXE/FREQ386.EXE
EGAVGA.BGI   Borland graphics library file
*.C,*.H      C source for the above programs
FREQ.PRJ     Project file used for Borland C++ (version 3.1)

Of these files, only FREQ.EXE (or FREQ386.EXE) and EGAVGA.BGI are required
to run the program.  FREQ.INI is optional (it is used to set up default
parameters and color scheme).  The other files are the source code, and can
be deleted without affecting program operation.

COMMAND LINE OPTIONS:

-Snumber sets the sampling rate.
-Fnumber sets the length of the FFT.
-Mnumber sets the scale maximum.
-Bnumber sets the logarithmic base level (in tens of dB).
-Tnumber sets the logarithmic top level (in tens of dB).
-Gnumber sets the dB/octave gain factor.
-Rnumber sets the reference frequency for dB/octave gains.
-LA sets a logarithmic scale for the amplitude axis.
-LF sets a logarithmic scale for the frequency axis.
-W0 selects a Hamming window.  (offset sine) <--default
-W1 selects a Hanning window.  (sine)
-W2 selects a Blackman window. (two sines)
-W3[,alpha] selects a Gaussian window.
-W4 selects a Welch window.    (quadratic)
-W5 selects a Parzen window.   (triangular)
-W6 selects a Rectangular window.
-Wfilename saves the windowing function to the specified file.
-? or -H displays this message.

INI File options: 

These options override the program defaults, but are overridden by the 
options specified on the command line.  The red,green,blue values for the
colors must be values between 0 and 63.

Sample rate: 44100          ( same as -Snumber )
FFT length: 1024            ( same as -Fnumber )
Window function: 0          ( same as -Wnumber )
Log freq scale: 0           ( 1 = -LF )
Log amp scale: 1            ( 1 = -LA )
Base db: 7                  ( same as -Bnumber )
Top db: 2                   ( same as -Tnumber )
Max amp: 10                 ( same as -Mnumber )
DB/octave gain: 0           ( same as -Gnumber )
Reference frequency: 1000   ( same as -Rnumber )
Background color: 0,0,20    ( sets the background red,green,blue value )
Clipping warning color: 20,0,0 (sets the background color for when clipping occurs )
Graph color: 30,35,60       ( sets the color for the FFT graph )
Axis label color: 50,20,45  ( sets the color frequency and amplitude labels )
Border color: 40,40,40      ( sets the color for the border and tick marks )
Text color: 55,55,25        ( sets the color for text (other than labels) )
Cursor upper color: 20,20,20 ( sets the color for the upper half of the cursor )
Cursor lower color: 63,63,63 ( sets the color for the lower half of the cursor )

RUNTIME OPTIONS:

While the program is running, the following commands may be used:

E,Q,<ESC> : exit from the program
W : toggle windowing function
X : toggle between logarithmic and linear frequency (x axis) scales
Y : toggle between logarithmic (dB) and linear amplitude (y axis) scales
0 : select 0 db/octave gain
3 : select 3 db/octave gain
6 : select 6 db/octave gain
9 : select 9 db/octave gain
1 : select 12 db/octave gain
<arrows> : increase/decrease the amplitude scale

<space> : freeze display, put up a cursor, and put up a display of frequency,
phase, and amplitude information.  In this mode, the left and right arrows
with move the cursor, <CTRL>-arrows will move in larger steps, <space> will
resume data aquisition, and <ESC>,'Q','E' with exit to DOS.

THE WINDOWING FUNCTION:

Several different windowing functions are available.  The windowing function
is a function that is multiplied by the input data to reduce the effects of
the discontinuity at the ends of the data set.  A rectangular window is 
actually no window: all data is passed through.  A Parzen (triangular) window 
uses a trianglar weighting: the end points are multiplied by 0, the
middle point by 1, with a linear ramp from 0 to 1 and back to 0 again.
A Welch Window uses a quadratic weighting: the end points are multiplied by
0, the middle points by 1, with a [concave down] quadratic function from 0,
up to 1, and back down to 0 again. To see the shapes of the various windows, 
used the -Wfilename option, and plot the data in the output file.

The best way to see the effects of windows is to use a logarithmic amplitude
scale, and input a sine wave (an audio test CD works great for this).  If 
you don't have any good sine wave sources, whistling into a mic works fairly
well.

KNOWN PROBLEMS: (let me know if you find others)

1) The program does not work if the 'device=mvsound.sys' line in config.sys 
contains the switch "u" (this switch allows initialization of the card, but 
then the driver is unloaded from memory (not a TSR)).  Removing this switch 
solves the problem.  My config.sys contains the following line:
   devicehigh=c:\pastudio\mvsound.sys d:5 q:7 s:1,220,1,5 j:1 t:1 v:0

2) The actual sample rates must be integer divisions of the timer frequency,
1.19318 MHz.  This means actual sampling rates are:
   91.78kHz, 85.23kHz, 79.55kHz, 74.57kHz, 70.19kHz, 66.29kHz, 62.80kHz,
   59.66kHz, ... , 45.89kHz, 44.19kHz, 42.61kHz, etc.
The displayed sample rates will not reflect actual values unless the command
line option specifies a rate that is an integral division of 1.19318 MHz.

THE SOURCE:

To compile the source you will also need the PAS SDK (SDK-V3.ZIP or 
PASSDK30.ZIP) that can be found via ftp on ProAudio archive sites such as
/ftp.uwp.edu:pub/msdos/proaudio.  It can also be found on Media Vision's 
bulletin board (files DISK1.ZIP and DISK2.ZIP), and on Compuserve in the 
Media Vision forum (SDK-V3.ZIP).

You will also need Borland C++ since the program uses the Borland .BGI
graphics facilities, but this should be easy to convert to the Microsoft C
(or other) graphics facilities.

WHAT'S NEW IN VERSION TWO:

1) The FFT routine has been changed to process purely real data, which can be
done in about half of the time it takes to process complex data.  This makes 
the FFT routine a little messy, but it is worth the mess!

2) The screen updating routine was changed a bit, and now runs faster
than before.  The main change was setting the mode and color once when the 
program starts, instead of every time a line was drawn.  This works
because I am interesting in drawing one color only, and nothing else is 
trying to output to the display while the program is running.

3) Changed the square root code to use a Newton-Raphson method.

4) Filled in the gaps in plots (such as log frequency scale).

5) A version is included which runs on only 386+ machines with COPROCESSORS.
This program is even faster than the other version because it was written
in 386/387 assembly code.

6) Removed Bartlett window function (it is essentially the same as the Parzen
window function).

7) Added cursor/amplitude display during paused display.

WHAT'S NEW IN VERSION THREE:

1) Skipped the assembly language version (it is too difficult to keep up with
the changes in two versions of the program).  The version optimized for the 
386 runs as fast as the eye can see, anyway, so there was not much gain it
going real time.

2) Added checking so that lines do not go beyond the limits of the display.

3) Added options for 0,3,6,9,12 dB/octave gains so that higher harmonics can
be made more visible (6dB/octave gain will make harmonics whose amplitudes 
drop as 1/frequency to have the same amplitude; 12dB/octave will make 
harmonics whose amplitudes drop as 1/frequency^2 to have the same amplitude.)

4) Added a bunch of run-time options for modifying the display.

5) Added more information in the header display

6) Added an INI file for setting defaults, so that you don't have to specify
all of your favorite options on the command line.

7) Allow modification of display colors (through the FREQ.INI file).

8) Background flashes a warning color when saturation of the input occurs.
(This flashing can be disabled by setting the background color and the
clipping warning color to the same values in the INI file.)

TIME COMPARISONS:

The following times are the amount of time required for one program loop,
which includes windowing the data, performing the FFT, and plotting the data.
All measurements were made on a 486/33 with zero input, and as such represent 
the minimum amount of time for one loop.  The time increases as the amount
of plotting increases (i.e. when the input amplitude increases).  Prev.ver.
refers to the first version of the program that I posted.

                  Linear Amp    Log Amp
Prev.ver. w/286:    122.8ms      98.7ms
Prev.ver. w/386:     70.7ms      59.2ms
FREQ w/ 286 code:    71.8ms      62.6ms
FREQ w/ 386 code:    32.6ms      27.5ms
FREQ387              19.1ms      19.0ms


If you have any questions or bug reports, you can contact me at:

Internet:    phillipv@engin.umich.edu

Compuserve:  71214,2302

Philip VanBaren
1845 Lake Lila Dr.  Apt. C3
Ann Arbor, MI  48105