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 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. :)