Allegro Sound Setup Utility
by David Calvin

------------
Introduction
------------

This program is a simple interface to setting up a sound.cfg file for use
with Allegro.  It will allow you to autodetect your soundcard or set it up
manually.  It also provides a test system to make sure the settings you have
chosen are working properly.

-----
Files
-----

setup.exe       Main Program File
setup.txt       You're reading it now
setup.dat       Datafile containing test sounds
sound.cfg       Created by setup.exe to save settings

------------
Installation
------------

If you are a user of an Allegro based program, installation is simple.
Copy setup.exe and setup.dat into the directory of the program you are using 
and you're all set.

If you are a programmer of an Allegro based program, the follow steps will
be used to modify setup to work with your program.

1) In setup.cc, change the PROGRAM_NAME #define to the name of your program.
2) Run make.
3) Copy the resulting .exe and the setup.dat to the location of your program.

If you wish to modify setup to work with additional soundcards, try the
following:

1) In setup.h, modify the NUM_DIGI_CARDS and NUM_MIDI_CARDS constants to 
	reflect the new amount of cards supported.
2) In setup.h, modify the data structures holding the names and specs of
	the digi and midi cards to account for the new ones.
3) As long as the new cards work the same way as the old ones, recompile
	and you should be all set.  NOTE: This has never been tested,
	additional hacking might be necessary.

-----
Usage
-----

The simplest case of usage is this:

1) Run setup.exe
2) Select Autodetect
3) Test to make sure the settings work
4) Save and exit

Setup will automatically read the settings in sound.cfg at startup.  If you
wish to avoid this, either delete sound.cfg, or run "setup -nodetect".

=============================================
============ Sound configuration ============
=============================================

When Allegro initialises the sound routines it reads information about your 
hardware from a file called sound.cfg. If this doesn't exist it will 
autodetect (ie. guess :-) You can write your sound.cfg by hand with a text 
editor, or you can use David Calvin's setup program.

Normally setup.exe and sound.cfg will go in the same directory as the 
Allegro program they are controlling. This is fine for the end user, but it 
can be a pain for a programmer using Allegro because you may have several 
programs in different directories and want to use a single sound.cfg for all 
of them. If this is the case you can set the environment variable 'ALLEGRO' 
to the directory containing your sound.cfg, and Allegro will look there if 
there is no sound.cfg in the current directory.

Apart from comments, which begin with a '#' character and continue to the 
end of the line, sound.cfg can contain any of the statements:

digi_card = x
   Sets the driver to use for playing samples, where x is one of the values:
      0 = none            1 = SB (autodetect breed)
      2 = SB 1.0          3 = SB 1.5 
      4 = SB 2.0          5 = SB Pro
      6 = SB16

midi_card = x
   Sets the driver to use for MIDI music, where x is one of the values:
      0 = none            1 = Adlib (autodetect OPL version)
      2 = OPL2            3 = Dual OPL2 (SB Pro-1)
      4 = OPL3            5 = SB MIDI interface
      6 = MPU-401

flip_pan = x
   Toggling this between 0 and 1 reverses the left/right panning of samples, 
   which might be needed because some SB cards (including mine :-) get the 
   stereo image the wrong way round.

sb_port = x
   Sets the port address of the SB (this is usually 220).

sb_dma = x
   Sets the DMA channel for the SB (this is usually 1).

sb_irq = x
   Sets the IRQ for the SB (this is usually 7).

sb_freq = x
   Sets the sample frequency, which defaults to 16129. Possible values are:
      11906 - works with any SB
      16129 - works with any SB
      22727 - on SB 2.0 and above
      45454 - only on SB 2.0 or SB16 (not the stereo SB Pro driver)

fm_port = x
   Sets the port address of the OPL synth (this is usually 388).

mpu_port = x
   Sets the port address of the MPU-401 MIDI interface (this is usually 330).

If you are using the SB MIDI output or MPU-401 drivers with an external 
synthesiser that is not General MIDI compatible, you can also use sound.cfg 
to specify a patch mapping table for converting GM patch numbers into 
whatever bank and program change messages will select the appropriate sound 
on your synth. This is a real piece of self-indulgence. I have a Yamaha 
TG500, which has some great sounds but no GM patch set, and I just had to 
make it work somehow... If you want to use the patch mapping table, add a 
series of lines to sound.cfg, following the format:

   p<x>  <b0>  <b1>  <prog>   <pitch>

where x is the GM program change number (1-128), b0 and b1 are the two bank 
change messages to send to your synth (on controllers #0 and #32), prog is 
the program change to send to your synth, and pitch is the number of 
semitones to shift everything played with that sound. Setting the bank 
change numbers to -1 will prevent them from being sent.

For example, the line:

   p36      0        34       9        12

specifies that whenever GM program 36 (which happens to be a fretless bass) 
is selected, Allegro should send a bank change message #0 with a parameter 
of 0, a bank change message #32 with a parameter of 34, a program change 
with a parameter of 9, and then should shift everything up by an octave.


-------
Credits
-------

Written by David Calvin
You may contact me at "calvid@rpi.edu" to report bugs or make comments or
whatever.  Unless the bug is severe, I probably won't have time to try to
fix it, but I'd like to hear about them anyway.  Most users spend an average
of five seconds in a setup program, it doesn't need to be all that
wonderful. :)

Thanks to the following people:

Shawn Hargreaves, author of the incredible Allegro game library.  Not only
did he write this amazing library, but he gladly answered all my annoying
questions while I was writing this program.  Thanks Shawn!  If Setup did not
come with Allegro, you can find it at
"ftp://x2ftp.oulu.fi/pub/msdos/programming/djgpp2/".

DJ Delorie, author of the outstanding DJGPP compiler.  Without his work, none
of this would have been possible.  DJGPP can be found at
"http://www.delorie.com/djgpp/".

-----
Legal
-----

This program is freeware.  You MAY distribute it anywhere, anyhow, anytime.
You MAY also modify, hack, alter, disassemble, reassemble, rip apart and
otherwise molest the source code.  I don't care what you do with it, as
long as I am given credit somewhere.  If it is used in a commercial product,
some kind of monetary contribution would be nice.

----
Bugs
----

Yes, of course there are some, but they aren't that serious.

Setup will override values in sound.cfg if they do not work.  However, this
isn't really a bug, it is a feature. :)
