This is the documentation file for GusDelay version 1.0.
Copyright (c) 1994 by David MacMahon - All rights reserved

TABLE OF CONTENTS
=================

0. LEGAL STUFF
1. INTRODUCTION
   A) Features
   B) Requirements
   C) Guide to the manual
2. QUICK START INSTRUCTIONS
   A) Starting GusDelay
   B) Getting on-line help
   C) Creating an echo
   D) Creating reverberation
   E) Creating surround sound
   F) Recording to disk
3. COMMAND LINE REFERENCE
   A) On-line help
   B) Initial configuration file
   C) Disk-only mode
   D) Input selection
   E) Output file
   F) Sampling rate
   G) Stereo mode
   H) Look-up table file
   I) Extra wait factor
   J) Examples
4. RUNTIME COMMAND REFERENCE
   A) On-line help
   B) Activating, deactivating, and selecting voices
   C) Changing the volume of the current voice
   D) Changing the delay of the current voice
   E) Changing the pan position (balance) of the current voice
   F) Displaying voice information
   G) Configuration files
   H) Look-up tables
   I) Recording to disk
   J) Quitting GusDelay
5. THEORY OF OPERATION
   A) Data Flow - Buffers, Buffers, and Buffers
   B) Signal Flow - Channels, Tracks, and Voices
6. FILE FORMATS
   A) Look-up table (LUT) files
   B) Configuration files
   C) Sound files
7. FUTURE ENHANCEMENTS
A1. CONTACTING THE AUTHOR
A2. TROUBLESHOOTING

==============
0. LEGAL STUFF
==============
Version 1.0 of GusDelay is shareware.  It is NOT free.  The copy of GusDelay 
which you received is an unregistered copy.  You may use this unregistered 
copy for 15 days to evaluate GusDelay.  If you continue to use the program 
after the 15 day evaluation period you are required to register the program. 
See the file REGISTER.TXT for registration instructions.  The shareware 
concept is designed to let you "try before you buy".  This copy, although 
unregistered, is fully functional.  Your support of GusDelay (by registering 
it) will help ensure my continued support of GusDelay (by improving it).

This program, GUSDELAY.EXE, may be freely distributed provided that this 
documentation accompanies the program, no fee is charged for the program
(except for a NOMINAL media charge not to exceed US$5), and it is not 
distributed as part of any commercial offering without prior written consent 
of the author, David MacMahon.

TRADEMARKS - GusDelay is a trademark of David MacMahon.
             Advanced Gravis, UltraSound, and USS 8 are trademarks 
             of Advanced Gravis Computer Technology Limited.  
             QEMM is a trademark of Quarterdeck Office Systems.
             386MAX is a trademark of Qualitas Inc.


===============
1. INTRODUCTION
===============
GusDelay is a program that transforms your Gravis UltraSound into an 
extremely powerful yet easy to use digital delay system (DDS).  It has 
features found only on professional DDSs that cost far more than the Gravis  
UltraSound itself.

Features
--------
Here is a brief list of some of GusDelay's features:

*** Up to 14 individually controllable output taps - GusDelay can use this 
    ability to create regenerative effects that are not degenerative.  
    Single tap delay units must feed the output back into the input in order 
    to create regenerative effects (such as multiple echoes or reverb).  
    Each time the signal goes through the system it is degraded in quality.  
    After several iterations the signal can be quite distorted.  With 
    multiple taps, regenerative effects can be simulated without feeding the 
    output back into the input thereby eliminating the degenerative side 
    effects.

*** Sampling frequencies up to 44.1 kHz in both mono and stereo - GusDelay 
    supports the entire sampling frequency range of the Gravis UltraSound.  
        
*** Jitter free and dropout free recording - GusDelay uses a technique for 
    recording that produces higher quality recordings than other recording 
    programs for the Gravis UltraSound including USS 8 and Playfile.

*** Real-time surround sound capabilities - GusDelay can produce real-time 
    output that can be decoded by surround sound systems to produce true, 
    on-the-fly surround sound effects.

*** Supports text based configuration files for plug-and-play usability 
    and easy customization - GusDelay is highly configurable through the use 
    of ASCII based configuration files.  This makes it easy for GusDelay 
    users to save their favorite "presets" for quick recall, exchange their 
    favorite settings with other users,  write simple programs to generate 
    the settings for a mathematically calculated effect, and so on.

*** Command line arguments - GusDelay takes many of its parameters from the 
    command line.  This enhances GusDelay's flexibility by allowing it to be 
    started unattended from within batch files.

*** On-line help - GusDelay offers on-line help for the command line 
    arguments as well as runtime operation.  This on-line quick reference 
    information makes GusDelay easier to use.

Requirements
------------
In order for GusDelay to work, there are two configuration requirements that 
must be met.  The most important of which is that the UltraSound absolutely 
MUST be set up to use two different DMA channels.  Due to the intensive 
throughput of the program, the use of two different 16-bit DMA channels is 
HIGHLY recommended.  The other requirement is that GusDelay must NOT be run 
if a protected mode memory manager is loaded.  The protected mode memory 
manager virtualizes the PC's hardware which slows down access to the DMA 
controller.  This causes problems because GusDelay is very DMA intensive.  
Future versions of GusDelay will coexist with these memory managers.  The 
memory requirements for GusDelay are quite minimal so this should not cause 
too much of a problem.  GusDelay should work on a computer with as little as 
512 KB of memory and with the standard GUS's 256 KB of on-board RAM.  
Currently GusDelay does not take advantage of GUS memory beyond 256 KB.  

GusDelay checks for both of these requirements when it starts.  If either 
one is not met GusDelay will print an appropriate message and exit.

Guide to the manual
-------------------
Here is a list of the remaining chapters of the manual.  A brief description 
of each chapter is also given.

QUICK START INSTRUCTIONS - This chapter is for those who want to jump in 
right away.  It describes the steps necessary to use some of GusDelay's 
basic functionality.  It also explains how to use the on-line help.  It
briefly mentions how to solve some of the problems that may be encountered.

COMMAND LINE REFERENCE - This chapter presents the various command line 
arguments and how to use them.  Essentially, it is a more detailed version 
of GusDelay's command line help.

RUNTIME COMMAND REFERENCE - This chapter covers the commands used to 
interact with GusDelay during runtime.  It not only covers them in more 
detail than GusDelay's runtime help, it also talks about the effects that 
the various commands have on each other.  This chapter is very important for 
anyone who will use GusDelay interactively (which includes almost everyone).

THEORY OF OPERATION - This chapter explains the technical details of 
GusDelay.  Reading and understanding this chapter is not required in order 
to use GusDelay, but those wishing to exploit the full power of GusDelay 
should be familiar with the contents of this chapter.  Warning: This chapter 
gets quite technical at times and may not be suitable for all viewers.

FILE FORMATS - This chapter outlines the file formats used by GusDelay. 
These files are used to store user-definable look-up tables, user-definable 
configurations (presets), and recorded data (sound).

FUTURE ENHANCEMENTS - This chapter lists features that could be added to 
future versions of GusDelay.  These features show areas where GusDelay 
could be enhanced.

CONTACTING THE AUTHOR - This appendix provides information about contacting 
the author of GusDelay.

TROUBLESHOOTING - This appendix provides pointers for troubleshooting when 
GusDelay does not operate as expected.  Look here if GusDelay doesn't seem 
to be functioning properly.  If you have a "slower" system (by today's 
standards) you may want to read this section first.

===========================
2. QUICK START INSTRUCTIONS
===========================
This chapter tells you how to get GusDelay up and running.  It introduces 
you to some of GusDelay's basic functionality, including on-line help.  It 
also touches upon some of GusDelay's more advanced features.  Along the way, 
various problems that may be encountered are discussed and solutions to them
are offered.

Starting GusDelay
-----------------
GusDelay can be started by simply typing "GusDelay" (no quotes) at the DOS 
prompt when it is in the current directory.  This starts GusDelay using its 
default values.  The defaults for GusDelay are to use line in, to sample at 
11025 Hz, and to operate in mono mode.  To start GusDelay with values other 
than these, you must use command line arguments.  The chapter entitled
"Command Line Reference" provides full details on all of the command line 
arguments which GusDelay will accept.  The examples in this chapter assume 
that GusDelay has been started with the default values.

Once GusDelay starts, you will see the following:
   
     GusDelay - Version 1.0
     Copyright (c) 1994 by David MacMahon - All rights reserved.
     Unregistered version for evaluation only.

     Press '?' for help.
     Now using LUT pair 0.
     Positive volume uses LUT 0 - Linear map, positive polarity
     Negative volume uses LUT 1 - Linear map, negative polarity

The first three lines contain version, copyright, and registration 
information.  The next three lines of text provide information regarding the 
current look-up tables (LUTs) that are being used.  GusDelay uses two LUTs 
at any given time, but it is possible to have more than one LUT pair in 
memory.  For more information on LUTs, see the chapters entitled "Theory of 
Operation" and "File Formats".

The other piece of information that is displayed is in the upper right hand 
corner of the screen.  This is a four digit hexadecimal number that provides 
information regarding the performance of the system.  The smaller this 
number is, the better GusDelay is performing.  Note that this number will 
never go below 0010 (for playback DMA channels less than 4) or 0020 (for 
playback DMA channels greater than 4).  It is quite common for this number 
to fluctuate slightly, but it should not vary widely.  When using high 
sampling rates on slower systems, this number may grow rapidly until the 
program spontaneously terminates.  This problem is much more likely to 
happen in stereo mode.  If this occurs, it simply means that your system is 
not able to provide the throughput necessary to maintain that sample rate.  
The number displayed in the corner is actually the number of samples that 
are currently being downloaded to the GUS.  This is referred to as the 
"download size".  See the chapter entitled "Theory of Operation" for more 
details.  For reference, my 25 MHz 386 system with a 32 KB cache running in 
stereo with a sample rate of 44100 Hz has a download size that fluctuates 
right around 00E0.  Another 25 MHz 386 system, without a cache, cannot keep 
up at that rate.

Getting on-line help
--------------------
GusDelay has two forms of on-line help.  The first form is command line 
help.  If you start GusDelay by typing "GusDelay -?", you will see a brief 
summary of GusDelay's command line arguments.  The chapter entitled "Command 
Line Reference" describes each argument in detail.  The second form of 
on-line help is runtime help.  If you type a question mark while GusDelay is 
running, you will see a brief summary of all of the valid commands that can 
be used to control various aspects of GusDelay's operation.  The chapter 
entitled "Runtime Command Reference" explains what each command does.

Creating an echo
----------------
When GusDelay is started with the default values, none of the voices are 
active.  In order to create any effect, you must first activate at least one 
voice.  To activate a voice, press the '<Insert>' key.  The first inactive 
voice will be activated with default values and you will see a line of text 
similar to this:

     Voice  0: Pan = 15  Volume [0] = +0     Delay = 2756

This means that voice 0 is active, its pan position is 15 (all the way to 
the right), its current volume is +0, and its delay is 2756.  The default 
value of the delay is equal to one quarter of a second (250 mS).  See the 
chapter entitled "Theory of Operation" for details about the minimum 
allowable delay.  A voice has two volumes associated with it, a muted volume 
(indicated by "[0]" following the word "Volume") and a normal volume 
(indicated by "[1]" following the word "Volume").  When a voice is first 
activated, its muted volume is its current volume.  By default, a voices 
muted volume is 0 and its normal volume is 3600.  Pressing 'm' switches from 
the muted volume to the normal volume and displays a line of text similar to 
this:

     Voice  0: Pan = 15  Volume [1] = +3600  Delay = 2756

At this point you will hear (on the right channel) one echo of the input (on 
the left channel).

Creating reverberation
----------------------
Reverberation, more commonly referred to as reverb, is an effect created by 
multiple echoes with very short delay times.  GusDelay can use two different 
methods (or a combination of them) to create reverb.  The first method is 
the same one used by conventional single tap delay units.  It creates 
multiple echoes by mixing the output of the delay unit with the input to the 
delay unit.  This method works, but it has three limitations.  The first 
limitation is that if the feedback occurs in the analog domain (as with 
GusDelay) then the signal degrades slightly every time it passes through 
the system.  After a few iterations, it can become quite distorted.  The 
second limitation to this system is that every echo has a delay time that is 
an integral multiple of the shortest delay time.  The third drawback is that 
the nature of the decay of the echoes is very regular; each echo's amplitude 
is a certain percentage of the previous echo's amplitude.  Because of these   
last two limitations, the regeneration method does not accurately model 
real-world reverb and leads to an effect that can sound artificial.  The 
second method of creating reverb uses multiple voices to generate multiple 
echoes.  This method does not result in signal degradation because there is 
no regeneration taking place in either the analog or the digital domain.  
The multiple voice method allows each echo's delay time and amplitude to be 
controlled independently from those of the other echoes.  These benefits 
come at a slight cost of convenience.  Setting up multiple voices to 
generate reverb is more involved than setting up one voice for regeneration.  
The use of configuration files, however, means that this work only needs to 
be done once.

To create multiple echoes using regeneration, move the pan position of a 
voice towards the left.  Continuing the example started in the previous 
section, change the pan position of Voice 0 from 15 to 7 by pressing '<' 8 
times.  This will result in multiple echoes that decay away after several 
iterations.  To increase the decay time of the echo, increase the voice's 
volume by pressing 'Ctrl-<Up Arrow>' twice.  This will make the voice's 
volume be +3800.  This will increase the number of echoes that can be heard 
before they fade out.  Be careful, though, setting a voice's volume too high 
will result in the echoes getting successively louder until all you have is 
very loud noise.  Shortening the delay (by repeatedly pressing 'Ctrl-<Left 
Arrow>') will create a reverb effect.  You must also be careful when doing 
this.  GusDelay will let you shorten the delay to the "absolute minimum 
delay" which is either 32 or 64 depending on the width of the playback DMA 
channel.  This absolute minimum delay value is (usually) quite shorter than 
the minimum delay that is actually realizable.  GusDelay calculates a "safe 
minimum delay" value based on the throughput provided by your system at the 
current sampling rate.  If you shorten the delay below this safe minimum 
delay value, GusDelay will print an asterisk ('*') after the current delay 
value.  The method by which GusDelay calculates the safe minimum delay 
value is very conservative.  The actual safe minimum delay value is 
somewhere between the calculated value and the absolute minimum delay value. 
If you set the delay to be barely to short, the output will be choppy.  If 
you set the delay extremely too short the output will, in effect, "wrap 
around" and sound like an extremely long delay.

To create multiple echoes using multiple voices, you first need to activate 
several voices and set their delays to different values.  Make sure that the 
voices are panned all the way to the right (Pan = 15) or you will be using a 
combination of the two methods.  Pressing '>' moves a voice's pan position 
to the right.  Pressing '<Insert>' activates a new voice and makes it the 
current voice.  The current voice is the voice that is affected by the 
commands you type.  To select the current voice, press '<Page Up>' or 
'<Page Down>'.  The current voice is always the last displayed voice on the 
screen.  Pressing '<Space>' will display the settings of all active voices 
and then display the settings of the current voice.  After you are done 
using GusDelay, press '<Esc>', 'q', or 'Q' to exit.  There will be a slight 
pause before GusDelay exits, especially at lower sample rates.  This is 
normal.

Creating surround sound
-----------------------
Because GusDelay uses look-up tables (LUTs), it is able to implement a form 
of "negative volume".  Negative volume is the same as positive volume except 
that the output is the negated (or inverted).  Surround sound decoders 
generate the back (or rear) channel by subtracting the left and right 
channels (B = L - R).  They generate the front signal by adding the left and 
right channels (F = L + R).  Surround sound is can be created by generating 
the normal signal on the left channel, and the negated (or inverted) signal 
on the right.  This results in the back channel being the same as adding the 
left and right channels (B = L - (-R) = L + R).  Due to limitations in the 
GUS's mixer prior to rev 3.7, surround sound in GusDelay is somewhat limited 
in functionality.  It works best in stereo mode because signals going to 
both channels will regenerate.  In mono mode, the signals going to the left 
channel will regenerate, but signals going to the right channel will not.  
You could compensate for this by setting up multiple voices on the right 
channel and only one voice on the left channel (see the previous section 
about creating reverberation).

The method for creating surround sound using stereo mode is given here.  
First, start GusDelay in stereo mode ("GusDelay -s").  Activate a voice pair 
by pressing '<Insert>'.  Switch the voices from their muted volume to their 
normal volume by pressing 'm'.  At this point there is no surround sound 
effect.  The echoes will be heard on the left, front, and right channels.  
Press 'p' to change the relative polarities of the two voices.  At this 
point you should hear the echoes alternating between the front and back 
channels as well as being present on the left and right channels.  The 
echoes alternate in this manner because the right channel inverts the echo 
every time it passes through the system.  On even iterations, the polarity 
of the echo on the right channel is the same as the polarity of the original 
sound.  Even iteration echoes are heard on the front channel.  On odd 
iterations, the polarity of the echo on the right channel is opposite the 
polarity of the original sound.  Odd iteration echoes are heard on the back 
channel.  Pressing 'p' cycles through all the possible relative polarities 
of the two voices (i.e. +L +R, +L -R, -L -R, -L +R, and finally back to 
+L +R).  Pressing 'P' cycles through in the opposite direction.  In mono 
mode, pressing 'p' or 'P' simply toggles the polarity of the current voice.

Recording to disk
-----------------
GusDelay is able to record the input signal to disk, but not the output 
signal.  If no regeneration is occurring, the recording will not contain any 
echoes at all.  GusDelay saves the recorded data to disk in a raw, unsigned 
format similar to the .SND files used by Playfile and USS 8.  There are 
plenty of tools available to convert this file format into others.  To start 
recording, press 'd'.  Once recording has begun, pressing 'd' pauses or 
resumes recording.  The name of the output file defaults to "GUSDELAY.SND".  
Using the "-o" switch on the command line can override this.  For example, 
"GusDelay -o Terrapin.snd" would cause GusDelay to record to the file 
"Terrapin.snd" (assuming that 'd' is pressed before quitting GusDelay).

When GusDelay records to disk, it greatly increases the bandwidth required 
of the bus.  It is possible that at high sample rates the system may not be 
able to keep up.  When this occurs, the number in the upper right corner 
(the download size) will increase (rapidly) until the program spontaneously 
terminates.  This simply means that your system is not able to provide the 
throughput necessary for real-time delaying AND simultaneous recording to 
disk at the sample rate you have selected.  If you wish to make recordings 
at this high sample rate, you can use the "-d" switch on the command line.  
This switch specifies that GusDelay is only going to be used for recording 
to disk.  When operating in this "disk-only" mode, the delay functionality 
of the program is unavailable.  For example, my 25 MHz 386 system is unable 
to record in stereo with a sampling rate of 44100 Hz while it is 
simultaneously providing delay functionality.  If I want to record at this 
rate, I type "GusDelay -s -r 44100 -d" to start the program without the 
delay functionality enabled.  This allows me to record at this rate.

GusDelay uses a unique (as far as I know) method of recording.  It is 
capable of producing jitter free and dropout free recordings that are devoid 
of "clicks".  At lower sampling rates, the difference in recording quality 
between GusDelay and Playfile is not so noticeable, but at higher sampling 
rates the difference is very noticeable.

=========================
3. COMMAND LINE REFERENCE
=========================
When GusDelay is started without any command line arguments, it uses default
values for many of its operating parameters.  This chapter lists the 
parameters which can be changed by specifying various arguments on the 
command line.  GusDelay's default behavior and modified behavior is given 
for each argument.  The text uses a dash ("-") as a prefix character for the 
arguments.  GusDelay will accept either a dash or a forward slash ("/").  
Multiple command line arguments can be given on the command line.  In 
certain combinations, however, one or more of the given arguments may not 
have any effect.

On-line help
------------
On-line help regarding the command line arguments themselves can be obtained 
by specifying "-h" or "-?" on the command line.  If either of these 
arguments is given, GusDelay ignores any other arguments and displays a help 
screen before returning to the DOS prompt.

Initial configuration file
--------------------------
Configuration files are used to store preset values for voice attributes 
such as volume, pan position, and delay.  This makes it possible to quickly 
setup GusDelay for preset effects.  Because the configuration files are 
ASCII text files, it is easy to create your own and exchange them with other 
GusDelay users via e-mail or other forms of communication.  GusDelay is also 
capable of writing configuration files.  See the chapter entitled "Runtime 
Reference" for more details.  To have GusDelay load a configuration file 
during startup, add "-c <filename>" to the command line.  This will cause 
GusDelay to use the settings specified in "<filename>" as the initial 
configuration.  For example, "GusDelay -c carnegie.gd" will start GusDelay 
using the settings specified in "carnegie.gd" (which may provide 
reverberation similar to Carnegie Hall).  If the "-c" argument is not given, 
GusDelay starts with the following voice attributes: 

     1) All voices deactivated.
     2) All voices use muted volume when first activated.
     3) The muted volume of all voices is 0.
     4) The normal volume of all voices is 3600
     5) The pan position of all voices in mono and the right (odd numbered) 
        voices in stereo is 15.  Left (even numbered) voices in stereo have 
        a default pan position of 0.
     6) The delay of all voices is one quarter of a second (250 mS).

Disk-only mode
--------------
When using GusDelay to record to disk at high sample rates, it is possible 
that slower systems may not be able to provide enough throughput to maintain 
real-time delay AND the simultaneous writing to disk.  The "-d" argument 
disables GusDelay's real-time delay feature.  When the delay feature is 
disabled, GusDelay is in "disk-only mode".  In this mode, the only thing 
that GusDelay can do is record to disk.  Obviously, GusDelay's default 
behavior in the absence of this argument is to provide real-time delay.

Input selection
---------------
GusDelay can sample the line level inputs, the microphone inputs, or both.  
The default behavior is to sample the line level inputs.  To make GusDelay 
sample the microphone inputs, add the "-m" argument to the command line.  If 
just the "-m" argument is given, GusDelay disables the line level inputs.  
To sample both the line level and microphone inputs, you must specify both 
the "-m" and the "-l" arguments.  The "-l" switch enables the line level 
inputs.  You can specify just the "-l" argument to enable only the line 
level inputs.  Since this is the default behavior, however, it is redundant 
and unnecessary.

Output file
-----------
When recording to disk, GusDelay will create a file called "GUSDELAY.SND".  
If this file exists, it will be overwritten.  To record to an output file 
other than "GUSDELAY.SND", add "-o <filename>" to the command line.  This 
will make GusDelay record to an output file named "<filename>".  For 
example, "GusDelay -o stairway.snd" will cause GusDelay to use 
"stairway.snd" as the output file.
   
Sampling rate
-------------
GusDelay's default sampling rate is 11025 Hz.  To start GusDelay using a 
different sampling rate, use the "-r <#>" argument.  This starts GusDelay 
with a sampling frequency of <#> Hz.  For example,  "GusDelay -r 44100" 
starts GusDelay with a sampling rate of 44100 Hz.  Because the GUS only 
supports a limited number of distinct sampling rates, unsupported sampling 
rates will be adjusted to one of the supported rates.  GusDelay will print a 
message to this effect if it happens.  
   
Stereo mode
-----------
To use GusDelay in stereo mode, add the "-s" argument to the command line.  
GusDelay's runs in mono mode by default.  Most people probably will prefer 
to use mono mode most of the time.  This is because the mixer on Ultrasounds 
prior to rev 3.7 had the not-so-wonderful "feature" of ALWAYS mixing the 
input into the output and the output into the input.  Having things set up 
this way results in the unavoidable regeneration of delayed signals, at 
least in stereo.  In mono, things are a little bit better.  The GUS samples 
only the left channel when sampling in mono.  By placing the output on the 
right channel, the inadvertent feedback can not only be avoided, but 
actually controlled.  As a voice gradually gets panned left, its 
regeneration gradually increases.  This is actually quite desirable because 
it means that the regeneration of each voice can be individually 
controlled!  In mono mode this "feature" of the GUS is truly a feature.  In 
stereo, however, this feature loses its appeal.  I have not had the 
opportunity to test GusDelay on a GUS that has the modified mixer so I 
don't know how it will perform.  My understanding is that the newer cards 
can put the mixers in "transparent mode" which provides the same 
functionality as the older GUSes.  Given this compatibility, GusDelay should 
work the same on these newer cards.  Future versions of GusDelay will 
support the "full mixer" found on newer cards.

Look-up table file
------------------
GusDelay uses look-up tables (LUTs) to map a single input sample stream into 
two output sample streams.  While only two LUTs are used at any given time, 
it is possible to have more than two LUTs in memory.  Look-up tables, like 
configurations, are stored in ASCII text files.  Unlike configuration files 
which can contain only one configuration, LUT files can contain many 
different LUTs.  To use GusDelay with a LUT file, add "-t <filename>" to the 
command line.  This will cause GusDelay to use "<filename>" as a LUT file.  
For example, "GusDelay -t metalfx.lut" will start GusDelay and load the LUTs 
in "metalfx.lut" into memory.  If the -t argument is not present on the 
command line, GusDelay uses its two internal LUTs.  Default LUT 0 maps 0 to 
0, 1 to 1, 2 to 2, etc.  This results in the output sample stream being the 
same as the input sample stream.  Default LUT 1 maps 0 to 255, 1 to 254, 2 
to 253, etc.  This results in an output stream that is the inverse of the 
input stream.  This is a large part of how GusDelay implements "negative" 
volume.

Extra wait factor
-----------------
GusDelay is designed to utilize as much bus bandwidth as possible.  The 
"extra wait factor" argument can be used to force GusDelay to run with less
than optimal efficiency.  This is primarily used in cases where GusDelay 
does not react well at maximum efficiency with a particular system.  To use 
an extra wait factor, add "-w <#>" to the command line, where <#> is a 
number between 0 and 8.  The default value of the extra wait factor is 0.  
See appendix 2, "Troubleshooting", for more details.

Examples
--------
This section lists a few possible combinations of command line switches and
explains how they affects GusDelay's operation.

 Command Line:                            What it does:

 GusDelay -m -r 44100                     Starts GusDelay sampling the
                                          microphone input in mono at a 
                                          rate of 44100 Hz.

 GusDelay -c myroom.gd -t distort1.lut    Starts GusDelay sampling the line
                                          level input in mono at a rate of 
                                          11025 Hz.  The voices are 
                                          initially configured as specified 
                                          in the file "myroom.gd".  The 
                                          look-up tables that will be used 
                                          are stored in the file named
                                          "distort1.lut".

 GusDelay -d -s -r 44100 -o quality.snd   Starts GusDelay in disk-only mode.
                                          The line level inputs will be 
                                          sampled in stereo at a rate of 
                                          44100 Hz.  The output file will be 
                                          named "quality.snd".

============================
4. RUNTIME COMMAND REFERENCE
============================
During the operation, or runtime, of GusDelay many aspects of the program 
can be modified by issuing various keystroke commands.  This enables you to 
dynamically "tweak" GusDelay until you get an effect you like.  At that 
point, you can write the configuration to a file for future use.  If you get 
a configuration file from someone and you feel that certain properties of 
the configuration are not quite right for your GUS (e.g. too much or not 
enough regeneration), you can use the commands described in this chapter to 
manually trim the configuration to your liking.  This chapter covers all of 
GusDelay's runtime commands.  For ease of learning, the commands are listed 
in functional groups.

Many of the commands deal with voice manipulation.  In mono mode, all the 
voices are used independently.  In stereo mode, however, voices are used in 
pairs.  In mono mode, voice commands generally affect the current voice 
only.  In stereo mode, voice commands generally affect both voices in the 
current voice pair.  Throughout this chapter, the commands are primarily 
described in the context of mono mode.  Unless otherwise noted, a command's  
effect on the current voice in mono mode is similar to the command's effect 
on the current voice pair in stereo.

On-line help
------------
On-line help concerning the runtime operation of GusDelay can be obtained by 
pressing '?' while the program is running.  This will clear the screen and 
print a list of all the valid commands (keystrokes) and a brief explanation 
of what each one does.  In disk-only mode, the list is much shorter than in 
normal operation because many commands affect the delay portion of the 
program.  These commands are unavailable in disk-only mode.

Activating, deactivating, and selecting voices
----------------------------------------------
GusDelay uses up to 14 voices of the GF1 chip to create its output.  Voices
that are in use are called "active voices".  Voices that are not in use are 
called "inactive voices".  In stereo, voices are used in pairs so you can 
have up to 7 pairs of active voices.  One of the active voices is considered 
to be the "current voice".  The current voice is the voice whose parameters 
will be changed when a voice altering command is given.  It is possible to 
select which voice is the current one.  Here are the keystrokes to activate 
voices, deactivate voices, and select the current voice from all active 
voices.

      Insert - Activates the first inactive voice and makes it the current 
               voice
      Delete - Deactivates the last activated voice.  If this voice happens 
               to be the current voice, then the next-to-last activated 
               voice will become the new current voice
     Page Up - Cycles the current voice through all active voices in 
               ascending order
   Page Down - Cycles the current voice through all active voices in 
               descending order

Changing the volume of the current voice
----------------------------------------
Voices in GusDelay have two volumes associated with them: a muted volume and 
a normal volume.  Only one of a voice's two volume levels can be in effect 
at any given time.  Both of these values can range from -4095 to +4095.  The 
sign of the selected volume determines which of two output streams will be 
used.  Positive volumes use the output stream associated with the even 
numbered LUT in the current LUT pair.  Negative volumes use the output 
stream associated with the odd numbered LUT of the current LUT pair.  The 
absolute value of the selected volume is the actual volume used.  Note that 
the volume scales are NOT linear.  If regeneration is occurring, setting the 
volume too high can result in a positive feedback situation that will sound 
like (surprise!) feedback.  Adjusting the volume to just below this 
threshold creates some interesting effects.  Here are the keystrokes for 
changing the volume of the current voice:
          
          Up Arrow - Increases the volume of the current voice by 10
        Down Arrow - Decreases the volume of the current voice by 10
     Ctrl Up Arrow - Increases the volume of the current voice by 100 
   Ctrl Down Arrow - Decreases the volume of the current voice by 100 
          'm', 'M' - Toggles between the current voice's muted and normal 
                     volume
           Alt-'M' - Sets every voice to its muted volume
          'p', 'P' - In mono mode, toggles the polarity (sign) of the 
                     current voice's volume
   (lowercase) 'p' - In stereo mode, cycles through all the possible 
                     combinations of volume polarity of the current voice 
                     pair in the following order, +L/+R, +L/-R, -L-R, -L/+R
   (uppercase) 'P' - In stereo mode, cycles through all the possible 
                     combinations of volume polarity of the current voice 
                     pair in the following order, +L/+R, -L/+R, -L-R, +L/-R
   
Changing the delay of the current voice
---------------------------------------
The absolute minimum delay that a voice can have is 32 (for an 8-bit 
playback DMA channel) or 64 (for a 16-bit playback DMA channel).  GusDelay  
calculates a safe minimum delay by doubling the size of the largest playback 
DMA transfer.  This value is typically larger than the realizable minimum 
delay value.  The maximum delay a voice can have is equal to the size of 
one GUS memory buffer minus the absolute minimum delay.  The size of the 
GUS memory buffer is approximately equal to (256K / n), where n is 2 for 
mono mode or 4 for stereo mode.  

Theoretically, two voices with opposite volumes but the same delay value and 
pan position should exactly cancel each other.  In GusDelay, however, the 
procedure for setting a voice's delay to a particular value is not very 
precise.  If two such voices are independently set to the same delay, it is 
unlikely that the two voices will exactly cancel each other.  To circumvent 
this, GusDelay is able to set the delay of two voices simultaneously.  This 
way, even if the voices are not set to the exact delay requested, both 
voices will be off by the same amount and will exactly cancel each other 
(assuming they have the same pan position and opposite volume).  This is 
referred to as "binding" the voices' delays.  When binding delays, one voice 
is the "master" and the other voice is the "slave".  When a master's and 
slave's delays are bound, the delays of both voices are set to the delay of 
the master voice.  Only certain master/slave combinations are allowed.  In 
mono mode, even numbered voices are bound to the next higher voice, 
regardless of which one is the master.  In stereo mode, even numbered voice 
pairs (voice pairs whose left voice is divisible by 4) are bound to the next 
higher voice pair regardless of which pair is the master.  Because GusDelay 
only supports 14 voices, voice pair (12, 13) can not be bound.  The current 
voice (or, in stereo, voice pair) is the master voice.  For example, in mono 
mode, if voice 5 is the current voice and 'b' (the "bind voice delays" 
command) is pressed, the delays of voice 4 and voice 5 will be set to the 
current delay of voice 5.

Here are the keystrokes for changing the delay of the current voice and, in 
the case of the "bind voice delays" command, the delay of its corresponding 
slave voice.
     
                '+' - Increases the delay of the current voice by 10
                '-' - Decreases the delay of the current voice by 10
                '*' - Increases the delay of the current voice by 100
                '/' - Decreases the delay of the current voice by 100
        Right Arrow - Increases the delay of the current voice by 50
         Left Arrow - Decreases the delay of the current voice by 50
   Ctrl Right Arrow - Increases the delay of the current voice by 500
    Ctrl Left Arrow - Decreases the delay of the current voice by 500
            '0'-'9' - Sets the last digit of the current voice's delay
           'b', 'B' - Bind voice delays (see above)

Note: If the delay of a voice is adjusted to below the safe minimum delay 
then an asterisk ('*') will be printed after the voice's current delay.

Changing the pan position (balance) of the current voice
--------------------------------------------------------
The pan position of a voice can range from 0 (all the way to the left) to 15 
(all the way to the right).  In mono mode, voices start with a pan position 
of 15 by default.  See the "Stereo mode" section of the "Command Line 
Reference" chapter for the reason behind this.  In stereo mode, voice pairs, 
by default, start with the even numbered (left) voice at pan position 0 and 
the odd numbered (right) voice at pan position 15.  Changing the pan 
position of the current (stereo) voice pair will affect the separation.  
After 7 changes away from the initial pan positions, both voices will be 
just about dead center (no separation).  After 15 changes away from the 
initial pan positions, the left voice will be all the way to the right and 
the right voice will be all the way to the left.

   '>' - Increases the value of the pan position of the current voice by 1.
         In stereo, this increases (by 1) the pan position of the left voice
         of the current voice pair and decreases (by 1) the pan position of
         the right voice.  This has the effect of decreasing the separation
         (unless the voices have "crossed", in which case the separation is
         increased.)  In mono, this decreases the regeneration of the current
         voice.
   '<' - Decreases the value of the pan position of the current voice by 1.
         In stereo, this decreases (by 1) the pan position of the left voice
         of the current voice pair and increases (by 1) the pan position of
         the right voice.  This has the effect of increasing the separation
         (unless the voices have "crossed", in which case the separation is
         decreased.)  In mono, this increases the regeneration of the current
         voice.

Displaying voice information
----------------------------
Information about the parameters of all active voices can be obtained at any 
time by pressing the space bar.  This will list all the active voices and 
their parameters.  The information about the current voice is printed on a 
line following this list.
   
Configuration files
-------------------
GusDelay can read and write configuration files on the fly.  This allows you 
to quickly change from one effect to another.  It also allows you to save 
newly created effects to disk for later use.  Whenever a configuration file 
command is given (read or write), GusDelay prompts you for the file name to 
use.  Here are the keys used to read and write configuration files from 
within GusDelay:

   (lowercase) 'c' - Read configuration to file (after prompting for name)
   (uppercase) 'C' - Write configuration to file (after prompting for name)

Look-up tables
--------------
As mentioned in the "Look-up table file" section of the "Command Line 
Reference" chapter, GusDelay only uses two look-up tables (LUTs) at any 
given time.  There can be more than one pair of LUTs in memory, but only one 
pair can be used at any time.  Pressing 'l' (or 'L') causes the next LUT 
pair to be used.  If the last LUT pair is in use, pressing 'l' selects the 
first LUT pair.
   
Recording to disk
-----------------
When GusDelay first starts, recording to disk is off.  Pressing 'd' (or 'D') 
will start recording to disk.  From that point on, the 'd' (or 'D') key acts 
as a pause/resume button, toggling the recording off and on.  Note that 
GusDelay can only record the inputs of the GUS.  It can not directly record 
the outputs.  GusDelay will record the data in a file called "GUSDELAY.SND" 
unless "-o <filename>" was given on the command line.  In that case, the 
data will be recorded in a file named "<filename>". If the program 
unexpectedly terminates while recording to disk, see the "Disk-only mode" 
section of the "Command Line Reference" chapter.
   
Quitting GusDelay
-----------------
To quit GusDelay, press '<Esc>', 'q', or 'Q'.  There will be a slight pause 
before GusDelay actually terminates.  If you are using a low sampling rate, 
this pause will be somewhat longer.

======================
5. THEORY OF OPERATION
======================
GusDelay takes advantage of the fact that the Gravis UltraSound is able to 
use two separate DMA channels for recording and playback.  Because of this, 
it makes heavy use of memory buffers.  To a great degree, GusDelay also 
relies on the architecture of the UltraSound itself.  For these reasons it 
makes sense to talk about GusDelay in two different contexts.  The first 
context is data flow.  The term "data flow" refers to the movement of data 
along the path from input to output.  The second context is signal flow.  
The term "signal flow" refers to the movement of signals along the path from 
input to output.  Although these two terms seem superficially synonymous, 
they are in fact quite different.  The data flow context is physical in 
nature.  Signal flow is more of an abstract or logical context.  One can 
think of signal flow as *what* the program actually does while data flow can 
be thought of as *how* the program actually does it.

Data Flow - Buffers, Buffers, and Buffers
-----------------------------------------
During the execution of GusDelay, data is constantly moving from the input 
to the output through various stages of processing.  The input of data 
occurs at a constant rate that is directly dependent on the sampling 
frequency.  Because the CPU can not be dedicated solely to the handling of 
these data, each stage of processing has an associated set of buffers to 
collect the data until the CPU is ready to process that stage.  Here is a 
block diagram of the buffer sets used in GusDelay:

               +-----+    +----------+    +-----+   
               |     |    | Record   |    |     |    +--------+
Analog In  ~~~>|     |===>| Buffers  |--->|     |    |  Disk  |
               | GUS |    +----------+    | CPU |--->| Buffer |-=-> To Disk
Analog Out <~~~|     |<===| Download |<---|     |    +--------+
               |     |    | Buffers  |    |     |
               +-----+    +----------+    +-----+

~~~> denotes an analog data path
===> denotes a DMA based digital data path
---> denotes a non-DMA based digital data path
-=-> denotes a digital data path that may or may not be DMA based

                                 Figure 1.

This diagram shows that data move from the GUS to the record buffers via 
DMA.  The CPU is responsible for transferring this data from the record 
buffers to the download and disk buffers in a timely fashion.  Data in the 
download buffers are moved, via DMA, to more buffers (not shown) on the GUS.  
Data in the disk buffer are written to disk.  In addition to what is 
depicted, the CPU is in charge of initiating the DMA transfers, handling the 
writing of data to disk, taking care of the user interface, and maintaining 
DOS (i.e. handling interrupts).  It is clear from this diagram that the CPU 
moves data from buffer to buffer, but the actual timing and implementation 
of these movements are not shown.

The two data movements performed by the CPU are record buffer to disk buffer 
and record buffer to download buffer.  The movement of data from the record 
buffer to the disk buffer is simply a copy.  The movement of data from the 
record buffer to the download buffer is more complex.  There is some 
processing done on the data as they are copied from the record buffer to the 
download buffer.  This processing involves using the input samples as 
indexes into a look-up table.  The entries in the look-up table are used as 
output samples.  In stereo mode there is a little more processing because 
the input samples are interleaved, but the output samples are not.

The timing of these data movements is interrupt driven.  After some samples 
have been transferred to the record buffers, the data movement routine is 
invoked.  This routine does the following things:
        
        1. Copies the new samples to the disk buffer
        2. Processes the new input samples, placing the resulting 
           output samples into the download buffers.
        3. Starts the download of the first download buffer

The completion of the download triggers an interrupt.  The interrupt handler 
function calls a routine in GusDelay that starts the download of the next 
download buffer.  If all download buffers have been downloaded and there are 
enough new samples to start another round of downloads, the data movement 
routine is called.  If there are not enough new samples at this time, one of 
the GUS's timers is started to trigger an interrupt when there will be 
enough new samples for another round of downloads.  The number of bytes in a 
download is called the "download size".  Due to the dynamic nature of the 
timing of these routines, not all download sizes are equal.

This data-movement-and-download process is repeated until the program 
terminates.  The time it takes for a new sample to propagate from the GUS's 
ADC to the GUS's RAM determines the actual minimum delay that can be 
realized.  This time is dependent on the download size (i.e. the larger the 
download size, the longer samples have been in the PC's memory).  
Theoretically, the minimum realizable delay is approximately equal to twice 
the time represented by the download size.  In practice, however, the 
minimum realizable delay is somewhat higher than this.  I don't know if 
this is due to a problem in the theory or the implementation, but future 
versions of GusDelay will address this issue.  GusDelay keeps track of the 
largest download size and sets the safe minimum delay equal to twice this 
value.  This is a very conservative approach, but this value is intended to 
be only a guideline.

Signal Flow - Channels, Tracks, and Voices
------------------------------------------
Now that the flow of data through the system is understood, the flow of 
signals through the system can be discussed.  Throughout this section the 
terms channel, track, and voice are used with specific meaning.  Because the 
meanings used in this text differ slightly from their conventional meanings, 
their definitions are given here.

Channel - A channel refers to a single audio signal.  Anything that is 
          mono has only one channel.  Anything that is stereo has two 
          channels.  A channel signal can exist in digital or analog form 
          (or both).

Track -   A track is similar to a channel in that it refers to a single 
          audio signal, but a track signal differs from a channel signal 
          because a track signal can only exist in digital form.  Channel 
          signals are mapped into track signals.  A single channel can have 
          more than one mapping and, therefore, more than one associated 
          track.  GusDelay uses two tracks per channel.

Voice -   A voice is logical element of the GF1 chip that plays a track 
          signal and directs it to the output channels.  GusDelay supports 
          up to 14 voices.

Understanding the relationships between channels, tracks, and voices is a 
prerequisite for understanding the flow of signals in GusDelay.  The 
following diagram illustrates the signal flow of GusDelay operating in
stereo mode.  Mono mode is similar in operation, but has only one channel 
and two tracks.
                                                             Download
                                                             Buffers
                                                           +---------+   
                                                     /---->| Track 0 |=====\
Audio                                                |     +---------+     |
 In       +-------+        +-----+    +---------+    |/--->| Track 1 |====\|
~~~~~+~~~>| Mixer |~~~~~~~>| ADC |===>| Record  |----+     +---------+     |
     |    +-------+        +-----+    | Buffers |    |\--->| Track 2 |====\|
     |       /|\                      +---------+    |     +---------+     |
     |        |                                      \---->| Track 3 |====\|
     |        +~~~~~~~~+                                   +---------+     |
     |                 |                                                   |
     +~~~~~~~~+        |                                   +---------+     | 
              |        |                             /-----| Track 0 |<===/|
             \|/       |              +---------+    |     +---------+     |
          +-------+    |   +-----+    |         |    |/----| Track 1 |<===/|
<~~~~~~~~~| Mixer |<~~~+~~~| DAC |<---|   GF1   |<---+     +---------+     |
Audio     +-------+        +-----+    |         |    |\----| Track 2 |<===/|
 Out                                  +---------+    |     +---------+     |
                                                     \-----| Track 3 |<====/
~~~> denotes an analog stereo signal path                  +---------+
===> denotes a DMA based digital signal path                   GUS
---> denotes a non-DMA based digital signal path             Buffers

                                 Figure 2.

The output of the ADC is transferred via DMA to the record buffers.  These 
data consist of interleaved samples of two audio channels (left and right). 
Using the mechanism described in the preceding section, the interleaved 
samples of these two channel signals are processed using two different 
mappings (look-up tables) to produce four track signals.  The samples of the 
four track signals are placed in the download buffers.  The relationship 
between the channel signals and the track signals is summarized in this 
table:

                       Track    Channel   Mapping
                       --------------------------
                         0         L         0
                         1         R         0
                         2         L         1
                         3         R         1

                                Table 1.

After the samples of the track signals are in the download buffers they are 
downloaded to the corresponding buffers in the GUS's RAM.  These GUS buffers 
are much larger than the download buffers.  Once the track signals are in 
the GUS's RAM, voices of the GF1 chip can be used to transform these track 
signals back into channel signals. 

In order to use a voice for playing the track signals into channel signals,
the voice's number, volume, pan position, and delay must be specified.  
Since a voice can play samples from only one track at a time, the track used 
by a voice must also be known.

GusDelay determines the voice's track based on the the voice's volume and, 
in stereo, the voice's number itself.  The GF1 allows a voice's volume to be 
any value between 0 and 4095, inclusive.  GusDelay allows a voice's volume 
to be any value between -4095 and 4095.  The sign of a voice's volume 
determines which mapping it will use and the absolute value of its volume is 
the actual volume that is given to the GF1.  Voices with positive volume use 
mapping 0, voices with negative volume use mapping 1.  Using the sign of the 
voice's volume to determine the mapping allows GusDelay to actually simulate 
negative gain (inversion) provided that the mapping is set up properly.  
GusDelay's default mapping provides this functionality.  In mono mode, 
mapping 0 implies track 0 and mapping 1 implies track 1.  In stereo mode, 
however, an additional piece of information is needed to determine which 
track will be used by a voice.  GusDelay uses the LSB of the voice's number 
to determine which input channel to use.  Even numbered voices use the left 
input channel and odd numbered voices use the right input channel.  For 
example, voice 2 with a volume of 3400 will use track 0 while voice 5 with a 
volume of -3500 will use track 3.  

The output channels of a voice are determined by the voice's pan position.
The output of each voice can be panned to any one of 16 pan positions 
ranging from full left to full right.  This allows one voice to output on 
either or both channels.   The input channel used by a voice is not 
necessarily the same as the output channel.  It is possible for a voice to 
play the left input channel mostly on the right output channel and vice 
versa.  Due to the limited nature of the mixer on the GUS prior to rev 3.7, 
there is no way, in stereo mode, to prevent the output from mixing back into 
the input (unless you have bypassed the GUS's mixer altogether). This means 
that, in stereo mode, the output of a voice always regenerates. In mono 
mode, since the GUS samples the left channel only, adjusting the voice's pan 
position all the way to the right prevents any feedback to the input stages.
By varying a voice's pan position, it's regeneration can be controlled.  
With rev 3.7 (and later) of the GUS, this problem/feature does not exist, 
but this version of GusDelay is not written to take advantage of the new 
features of the newer cards.

The location of the voice in the track signal GUS buffer is determined by 
the voice's delay value.  The delay value of a voice is the number of 
samples by which the voice lags the present.  The delay value can be used to 
calculate the voice's offset within the GUS buffer.  When the delay value of 
a voice is changed, the voice's position must be changed to reflect the new 
delay.  The method by which GusDelay does this is not very precise.  If two 
voices are set up with the same delay, it is unlikely that they will 
actually be positioned at the same offset within their respective track 
buffers.  For this reason, the concept of "voice binding" was added to 
GusDelay.  Voice binding takes one voice's delay and forces that voice and a 
second voice to be positioned at exactly the same offset based on the delay 
of the first voice.  If the default mappings are in effect, binding two 
voices with the same pan position, same delay, and opposite volumes will 
cause them to exactly cancel each other.

A thorough understanding of the concepts that were presented in this chapter 
is not required to use GusDelay.  Knowing how GusDelay works, however, makes 
it easier to create custom look up tables (LUTs) and configuration (presets) 
files.  The ability to customize these aspects of GusDelay greatly enhances 
its versatility and usefulness.

===============
6. FILE FORMATS
===============
GusDelay uses three different file types: look-up table (LUT) files, 
configuration files, and sound files.  This chapter explains the formats of 
these file types.  LUT files and configuration files are ASCII text files 
that allow the user to customize GusDelay.  Sound files are binary files 
that contain data recorded by GusDelay.  GusDelay comes with a sample LUT 
file and a sample configuration file.  They are both usable, but they are 
intended to be more instructional than useful.

LUT files and configuration files have some similarities beyond the fact 
that they are both ASCII text files.  They are both composed of "tokens".  
Tokens are groups of non-white space characters delimited by white space 
characters.  This means that these files are not very sensitive to line 
spacing and can be quite free-form.  Both file types also have the same 
"comment characters".  Comment characters cause all remaining characters on 
that line to be ignored.  There are three comment characters: ';' 
(semicolon), '#'(number sign), and '"' (double quote).  The ';' and '#' 
characters are comment characters in the traditional sense.  Everything 
after them is ignored (until the end of the line).  The '"' character is a 
little different.  Characters after it (until the end of the line) are not 
parsed as tokens, but they are echoed to the screen.  This is useful for 
embedding such things as the file creator's name, reminder messages to the 
user, etc.  

Look-up table (LUT) files
-------------------------
The first three tokens of a LUT file are all integers.  They indicate the 
number of LUTs that GusDelay should create in memory, the number of entries 
per LUT, and the number of bytes per entry.  Currently, the number of 
entries per LUT and the number of bytes per entry MUST be set to 256 and 1,
respectively.  After parsing these three tokens, GusDelay will create as 
many LUTs as specified by the first token.  These LUTs are initially set up 
to be identical to the default LUTs.  Even numbered LUTs, by default, have a 
1:1 mapping (i.e. 0 maps to 0, 1 maps to 1, 2 maps to 2, etc.).  Odd 
numbered LUTs, by default, have a 1:-1 mapping (i.e. 0 maps to 255, 1 maps 
to 254, 2 maps to 253, etc.).  The remainder of the LUT file is composed of 
LUT entry records or LUT name records.

A LUT entry record consists of three tokens, all integers.  The first token 
in a LUT entry record is the number of the LUT which this entry modifies.  
The second token is the number of the LUT entry to modify.  The third token 
is the new value for this entry.  LUT entry records are only required for LUT entries that 
differ from the default entries.  For example, the tokens "2 37 53 3 214 98" 
would cause GusDelay to set entry 37 of LUT 2 to 53 and entry 214 of LUT 3 
to 98.

A LUT name record consists of two or more tokens.  The first token in a LUT 
name record is the number of the LUT that is being named.  The first 
character of the second token is non-numeric.  This fact is important 
because it is how GusDelay differentiates between a LUT entry record and a 
LUT name record.  The second token and the remainder of the text on that 
line of the LUT file make up the name of the LUT specified by the first 
token.  For example, if "2 37 53 2 Random mapping" appeared as one complete 
line of a LUT file, GusDelay would set entry 37 of LUT 2 to 53 and would set 
the name of LUT 2 to "Random mapping".  The name of a LUT is displayed when 
the LUT is activated.

GusDelay comes with a sample LUT file called GUSDELAY.LUT.  This file 
specifies 4 LUTs, but only modifies LUTs 2 and 3.  This means that LUTs 0 
and 1 will contain only the default values.  Also note that GUSDELAY.LUT 
only modifies half of the entries in LUTs 2 and 3.  LUT 2 is a positive 
rectifier.  This causes all negative input voltages to become positive
output voltages (ignoring the fact that the output is AC coupled).  It 
should be noted that the look-ups map unsigned values into unsigned values.  
As it turns out, 0 produces the highest (most positive) output voltage and 
255 produces the lowest (most negative) output voltage.  
   
Configuration files
-------------------
Configuration files are composed of voice selection records and voice 
attribute records.  Both types of records contain two tokens.  Voice 
selection records are used to select which voice's attributes will be 
affected by subsequent voice attribute records.  Voice attribute records 
affect various attributes of the voice selected by the most recent voice 
selection record.  

The first token of a voice selection record is a single character token, 
either a "v" or a "V".  The following token, an integer, specifies the 
number of the voice that will be affected by subsequent voice attribute 
records.  When a new voice selection record is encountered, the previously 
selected voice will not be further affected unless it is selected again with 
another voice selection record.  Voice selection records also imply that the 
selected voice (and all other voices with smaller voice numbers) will be an 
active voice after the configuration file is processed.

The structure of a voice attribute record is virtually identical to the 
structure of a voice selection record.  The first token is a single 
character specifying which attribute of the currently selected voice will be 
given a new value.  The second token, an integer, is the value given to that 
attribute.  There are four attributes of a voice that can be changed: muted 
volume, normal volume, delay, and pan position.  There are, however, six 
different types of voice attribute records which are summarized in the 
following table:

        First token     Meaning of the value of the second token
        -----------     ----------------------------------------
                'm'     Sets the muted volume of the current voice
                'M'     Sets the muted volume of the current voice AND 
                        specifies that the current voice will use this
                        volume after the configuration file is processed.
                'n'     Sets the normal volume of the current voice
                'N'     Sets the normal volume of the current voice AND 
                        specifies that the current voice will use this
                        volume after the configuration file is processed.
         'd' or 'D'     Sets the delay (in samples) of the current voice.
         'p' or 'P'     Sets the pan position of the current voice.

Unless 'N' is explicitly used for a voice (and not followed by an 'M'), its 
volume after the configuration file is processed will be its normal volume.

Currently, GusDelay configuration files do not specify global options such 
as sampling rate, stereo or mono mode, etc.  For any given configuration 
file, appropriate values for these options must be given on the command line 
or the effect obtained will not be the one intended.  Future versions of 
GusDelay will address this issue.  If certain attributes of a voice are not 
specified in the configuration file, those attributes will take on their 
default values.  These default values were listed in the "Initial 
configuration file" section of the chapter entitled "Command Line 
Reference".

GusDelay comes with a sample configuration file, GUSDELAY.CFG, that uses 
three voices to create reverb/echo.  Two of the voices are configured for no  
regeneration while the third voice is set to regenerate.  This produces a 
rather pleasing effect.  It should be noted that by having only one voice 
regenerate, the reverb "pattern" is effectively regenerated as a whole.  In 
other words, even though voices 0 and 1 don't regenerate, they will still 
provide one and only one echo for each and every regeneration of voice 2.

Sound files
-----------
The sound files created by GusDelay are simply raw samples.  These samples 
are 8-bit unsigned integers.  Stereo sound files interleave the samples of 
left and right channels.  For any corresponding pair of samples, the left 
channel's sample comes first.  This is the same format used by the .SND 
files of Playfile and USS 8.  There are a number of utilities that can be 
used to convert this file format into other formats.  GusDelay can create 
stereo recordings at any of the sample rates supported by the GUS.

======================
7. FUTURE ENHANCEMENTS
======================
Even though the current version of GusDelay has quite a bit of 
functionality, there are more features I would like to add.  Some of these 
offer new functionality while others offer increased ease of use.  The next 
release of GusDelay will most likely be 1.1.  It will offer an enhanced 
feature set (i.e. bug fixes) as well as some additional functionality.  I 
can't list what bugs will be fixed because as far as I know, there are no 
bugs, only misunderstood "features".  I am relying on you to tell me which 
"features" need to be better behaved.  Likewise, I can't list what 
functionality will be added.  It depends on how urgently "features" need to 
be improved.  As with any software project, improving existing features and 
adding new functionality need to be carefully balanced.  Registered users 
will have a great deal of influence on the future of GusDelay (and will be 
automatically registered for all future versions).  That said, here is a 
list of functionality that I would like to eventually incorporate into 
GusDelay:

 - Graphical user interface (probably TurboVision)
 - Create .WAV (and other formats) files instead of just raw data files
 - Support for more than 256K of GUS DRAM
 - Flanger effect - This will fluctuate a voice's playback frequency above
   and below the recording frequency
 - Chorus effect - This will fluctuate a voice pair's volume.
 - Adjustable maximum delay
 - Ability to change loop mode - Allow voices to loop bidirectionally.  
   This, in combination with the adjustable maximum delay, can create some 
   bizarre effects
 - More flexible configuration files
 - Better coexistence with protected mode memory managers
 - Support for the improved mixers on newer GUSes
 - Support for the 16-bit daughter card and GUS MAX
 - Make GusDelay MIDI aware.  There must be MIDI-aware delay modules and 
   there is no reason that GusDelay could not offer this functionality.
 - Other enhancements mentioned in the text
 - Your excellent idea here - I am always willing to consider new ideas

The flanger and chorus effects are my personal favorites.

=========================
A1. CONTACTING THE AUTHOR
=========================
I can be reached via e-mail at davidm@marcam.com.  I am very interested in
your feedback, both good and bad, and will try to respond to all of it.  I
also read the "GUS SDK Digest", the "Ultrasound Daily Digest", the "GUS 
Musicians' Digest", and the USENET news group comp.sys.ibm.pc.soundcard.

===================
A2. TROUBLESHOOTING
===================
I have put much effort into ensuring that GusDelay will run well on as many 
different computers in as many different configurations as possible.  This 
does not mean that it will run well on every computer.  The two biggest 
causes of problems that I have seen are running GusDelay with a protected 
mode memory manager and running GusDelay on "slower" computers.  Here is a 
list of symptoms and likely solutions for them.

SYMPTOM 1: GusDelay complains that my DMA channels are the same.

SOLUTION 1: GusDelay requires that the UltraSound be configured to use two 
different DMA channels.  Consult the documentation that came with the 
UltraSound for instructions on how to do this.

SYMPTOM 2: GusDelay complains that Virtual DMA Services (VDS) are detected.

SOLUTION 2: If GusDelay detects VDS it assumes that a protected mode memory 
manager is installed.  This version of GusDelay is not compatible with such 
memory managers and will refuse to run.  To use GusDelay, you must boot your 
PC without a protected mode memory manager.  See the DOS documentation and 
the memory manager documentation for instructions on disabling your memory 
manager.  Common memory managers that fall into this category are EMM386, 
QEMM, and 386MAX.

SYMPTOM 3: GusDelay hangs the PC after starting - even Ctrl-Alt-Delete won't
reboot - but numbers in the upper right corner seems to be fluctuating.

SYMPTOM 4: GusDelay starts OK, but after a short while it produces a "Stack 
overflow" error and the system is halted.

SOLUTIONS 3 & 4: I have seen these problems on slower computers and I'm 
pretty sure it's due to the interrupt latency time being too long, 
relatively speaking, compared to the actual interrupt service time.  By 
using the "-w <#>" option (see the "Extra wait factor" section of "Command 
Line Reference" chapter), you can force GusDelay to increase the number of 
samples transferred per interrupt and therefore give the PC more time 
between interrupts to "catch its breath".  A method does exist for 
calculating the optimal value for "<#>", but it is beyond the scope of this 
document.  The easiest way to determine the best value is by experimenting 
with different values.  Start with "-w 1" and work your way up by steps of 
one until you find a value that works.  In other words, if "-w 1" doesn't 
work, try "-w 2" and then "-w 3" until it works.  If you get up to "-w 8" 
and it still doesn't work, please let me know the details of your system and 
its configuration.  I will do what I can to help you.

SYMPTOM 5: GusDelay works, but the number in the upper right corner 
increases until GusDelay spontaneously terminates.  The higher the sample 
rate, the faster the number increases.  This is especially bad in stereo 
mode.

SOLUTION 5: If this occurs, your system is unable to provide the throughput 
required for steady state operation at the current sample rate.  Use a lower 
sample rate.

SYMPTOM 6: GusDelay works, but as soon as I start recording to disk the 
number in the upper right corner increases until GusDelay spontaneously 
terminates.  The higher the sample rate, the faster the number increases.  
This is especially bad in stereo mode.

SOLUTION 6: If this occurs, your system is unable to provide the throughput 
required for steady state operation at the current sample rate while 
recording to disk.  Use the "-d" option (see the "Disk-only mode" section of 
the "Command Line Reference" chapter) to record to disk at the current 
sample rate.  This will disable the real-time delay functionality of 
GusDelay.

SYMPTOM 7: GusDelay works and when recording to disk the number in the 
upper right corner is stable (with slight fluctuations), but the recordings 
end up with slight clicks in them.

SOLUTION 7: GusDelay uses a special technique to produce click-free 
recordings, but sometimes when recording AND providing real-time delay there 
are still clicks in the recording.  Use the "-d" option.  This will disable 
the real-time delay functionality of GusDelay.

SYMPTOM 8: GusDelay seems to work OK, but the delayed signals sound very 
distorted or choppy.

SOLUTION 8: This is the primary symptom of running GusDelay with a protected 
mode memory manager loaded.  GusDelay tries to detect when such a memory 
manager is installed.  Usually the detection works (and GusDelay exits), but 
you will notice this symptom if the detection fails. For good results, you 
MUST run GusDelay without ANY protected mode memory manager whatsoever.  
GusDelay does not use much memory so there is little point in using a memory 
manager anyway.  If this happens to you please let me know so I can improve 
the detection routine.

SYMPTOM 9: GusDelay doesn't work and nothing listed here has helped.

SOLUTION 9: Let me know the details of your system and its configuration.  I 
will do what I can to help you get GusDelay working.

Enjoy!
Dave
