arch/dos/allg_snd/sound/readme.txt

   1      ______   ___    ___
   2     /\  _  \ /\_ \  /\_ \
   3     \ \ \L\ \\//\ \ \//\ \      __     __   _ __   ___
   4      \ \  __ \ \ \ \  \ \ \   /'__`\ /'_ `\/\`'__\/ __`\
   5       \ \ \/\ \ \_\ \_ \_\ \_/\  __//\ \L\ \ \ \//\ \L\ \
   6        \ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/
   7         \/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/
   8                                        /\____/
   9                                        \_/__/     Version 3.0
  10
  11
  12                 A game programming library
  13
  14                By Shawn Hargreaves, 1994/97
  15
  16
  17
  18 #include <std_disclaimer.h>
  19
  20    "I do not accept responsibility for any effects, adverse or otherwise,
  21     that this code may have on you, your computer, your sanity, your dog,
  22     and anything else that you can think of. Use it at your own risk."
  23
  24
  25
  26 ======================================
  27 ============ Introduction ============
  28 ======================================
  29
  30    Allegro is a library of functions for use in computer games, written for
  31    the djgpp compiler in a mixture of C and assembly language. This is
  32    version 3.0: see the NEWS file for a list of differences from the
  33    previous release.
  34
  35    According to the Oxford Companion to Music, Allegro is the Italian for
  36    "quick, lively, bright". Once upon a time it was also an acronym for
  37    "Atari Low Level Game Routines", but it is a long time since I did any
  38    programming on the Atari, and the name is pretty much the only thing left
  39    of the original Atari code.
  40
  41
  42
  43 ==================================
  44 ============ Features ============
  45 ==================================
  46
  47    Supports VGA mode 13h, mode-X (twenty two tweaked VGA resolutions plus
  48    unchained 640x400 Xtended mode), and SVGA modes with 8, 15, 16, 24, and
  49    32 bit color depths. Uses VESA 2.0 linear framebuffers if they are
  50    available, and also contains register level drivers for ATI, Cirrus,
  51    Paradise, S3, Trident, Tseng, and Video-7 cards.
  52
  53    Drawing functions including putpixel, getpixel, lines, rectangles, flat
  54    shaded, gouraud shaded, and texture mapped polygons, circles, floodfill,
  55    bezier splines, patterned fills, masked, run length encoded, and compiled
  56    sprites, blitting, bitmap scaling and rotation, translucency/lighting,
  57    and text output with proportional fonts. Supports clipping, and can draw
  58    directly to the screen or to memory bitmaps of any size.
  59
  60    Hardware scrolling, mode-X split screens, and palette manipulation.
  61
  62    FLI/FLC animation player.
  63
  64    Plays background MIDI music and up to 32 simultaneous sound effects.
  65    Samples can be looped (forwards, backwards, or bidirectionally), and the
  66    volume, pan, pitch, etc, can be adjusted while they are playing. The MIDI
  67    player responds to note on, note off, main volume, pan, pitch bend, and
  68    program change messages, using the General MIDI patch set and drum
  69    mappings. Currently supports Adlib, SB, SB Pro, SB16, AWE32, MPU-401, and
  70    software wavetable MIDI.
  71
  72    Easy access to the mouse, keyboard, joystick, and high resolution timer
  73    interrupts, including a vertical retrace interrupt simulator.
  74
  75    Routines for reading and writing LZSS compressed files.
  76
  77    Multi-object data files and a grabber utility.
  78
  79    Math functions including fixed point arithmetic, lookup table trig, and
  80    3d vector/matrix manipulation.
  81
  82    GUI dialog manager and file selector.
  83
  84
  85
  86 ===================================
  87 ============ Copyright ============
  88 ===================================
  89
  90    Allegro is swap-ware. You may use, modify, redistribute, and generally
  91    hack it about in any way you like, but if you do you must send me
  92    something in exchange. This could be a complimentary copy of a game, an
  93    addition or improvement to Allegro, a bug report, some money (this is
  94    particularly encouraged if you use Allegro in a commercial product), or
  95    just a copy of your autoexec.bat if you don't have anything better. If
  96    you redistribute parts of Allegro or make a game using it, it would be
  97    nice if you mentioned me somewhere in the credits, but if you just want
  98    to pinch a few routines that is OK too. I'll trust you not to rip me off.
  99
 100
 101
 102 ============================================
 103 ============ Supported hardware ============
 104 ============================================
 105
 106    The bare minimum you need to use Allegro is a 386 with a VGA graphics
 107    card, but a 486 is strongly recommended. To get into SVGA modes you will
 108    need a compatible SVGA card, which means either one of the cards that is
 109    supported directly, or a card with a working VESA driver. If you have a
 110    VESA 2.0 implementation such as UniVBE (which you can get from the
 111    Display Doctor link on http://www.scitechsoft.com/), you are fine just
 112    using that. If you don't, beware. For one thing, everything will be much
 113    slower if Allegro can't use the sexy VBE 2.0 features. For another, I
 114    could go on all day telling horror stories about the buggy and generally
 115    just pathetic VESA implementations that I've come across. If you are
 116    having trouble with the SVGA modes, try getting a copy of UniVBE and see
 117    if that clears things up (it probably will: SciTech usually get these
 118    things right).
 119
 120    On the sound front, Allegro supports sample playback on the SB (mono),
 121    the SB Pro (stereo), and the SB16. It has MIDI drivers for the OPL2 FM
 122    synth (Adlib and SB cards), the OPL3 (Adlib Gold, SB Pro-II and above),
 123    the pair of OPL2 chips found in the SB Pro-I, the AWE32 EMU8000 chip, the
 124    raw SB MIDI output, and the MPU-401 interface, plus it can emulate a
 125    wavetable MIDI synth in software, running on top of any of the supported
 126    digital soundcards. If you feel like coming up with drivers for any other
 127    hardware, they would be much appreciated.
 128
 129    You may notice that this release contains some code for building a Linux
 130    version, but don't bother trying this: it won't work! A _lot_ more work
 131    is needed before Allegro will be usable under Linux.
 132
 133    There is also the first part of a VBE/AF driver in this package. VBE/AF
 134    is an extension to the VBE 2.0 API which provides a standard way of
 135    accessing hardware accelerator features. My driver implements all the
 136    basic mode set and bank switch functions, so it works as well as the
 137    regular VESA drivers, but it doesn't yet support any accelerated drawing
 138    operations. This is because SciTech have, so far, only implemented VBE/AF
 139    on the ATI Mach64 chipset, and I don't have access to a Mach64. I'll
 140    finish the driver as soon as they implement VBE/AF on the Matrox Mystique.
 141
 142
 143
 144 ============================================
 145 ============ Installing Allegro ============
 146 ============================================
 147
 148    To conserve space I decided to make this a source-only distribution, so
 149    you will have to compile Allegro before you can use it. To do this you
 150    should:
 151
 152    - Go to wherever you want to put your copy of Allegro (your main djgpp
 153      directory would be fine, but you can put it somewhere else if you
 154      prefer), and unzip everything. Allegro contains several subdirectories,
 155      so you must specify the -d flag to pkunzip.
 156
 157    - If you are using PGCC, uncomment the definition of PGCC at the top of
 158      the makefile, or set the environment variable "PGCC=1".
 159
 160    - Type "cd allegro", followed by "make". Then go do something
 161      interesting while everything compiles. If all goes according to plan
 162      you will end up with a bunch of test programs, some tools like the
 163      grabber, and the library itself, liballeg.a.
 164
 165      If you have any trouble with the build, look at faq.txt for the
 166      solutions to some of the more common problems.
 167
 168    - If you want to use the sound routines or a non-US keyboard layout, it
 169      is a good idea to set up an allegro.cfg file: see below.
 170
 171    - If you want to read the Allegro documentation with the Info viewer
 172      or the Rhide online help system, edit the file djgpp\info\dir, and in
 173      the menu section add the lines:
 174
 175          * Allegro: (allegro.inf).
 176                  The Allegro game programming library
 177
 178    - If you want to create the HTML documentation as one large allegro.html
 179      file rather than splitting it into sections, edit docs\allegro._tx,
 180      remove the @multiplefiles statement from line 8, and run make again.
 181
 182    To use Allegro in your programs you should:
 183
 184    - Put the following line at the beginning of all C or C++ files that use
 185      Allegro:
 186
 187          #include <allegro.h>
 188
 189    - If you compile from the command line or with a makefile, add '-lalleg'
 190      to the end of the gcc command, eg:
 191
 192          gcc foo.c -o foo.exe -lalleg
 193
 194    - If you are using Rhide, go to the Options/Libraries menu, type 'alleg'
 195      into the first empty space, and make sure the box next to it is checked.
 196
 197    See allegro.txt for details of how to use the Allegro functions, and how
 198    to build a debug version of the library.
 199
 200
 201
 202 =======================================
 203 ============ Configuration ============
 204 =======================================
 205
 206 When Allegro initialises the keyboard and sound routines it reads
 207 information about your hardware from a file called allegro.cfg or sound.cfg.
 208 If this file doesn't exist it will autodetect (ie. guess :-) You can write
 209 your config file by hand with a text editor, or you can use the setup
 210 utility program.
 211
 212 Normally setup.exe and allegro.cfg will go in the same directory as the
 213 Allegro program they are controlling. This is fine for the end user, but it
 214 can be a pain for a programmer using Allegro because you may have several
 215 programs in different directories and want to use a single allegro.cfg for
 216 all of them. If this is the case you can set the environment variable
 217 ALLEGRO to the directory containing your allegro.cfg, and Allegro will look
 218 there if there is no allegro.cfg in the current directory.
 219
 220 The mapping tables used to store different keyboard layouts are stored in a
 221 file called keyboard.dat. This must either be located in the same directory
 222 as your Allegro program, or in the directory pointed to by the ALLEGRO
 223 environment variable. If you want to support different international
 224 keyboard layouts, you must distribute a copy of keyboard.dat along with your
 225 program.
 226
 227 See allegro.txt for details of the config file format.
 228
 229
 230
 231 ================================================
 232 ============ Notes for the musician ============
 233 ================================================
 234
 235 The OPL2 synth chip can provide either nine voice polyphony or six voices
 236 plus five drum channels. How to make music sound good on the OPL2 is left as
 237 an exercise for the reader :-) On an SB Pro or above you will have eighteen
 238 voices, or fifteen plus drums. Allegro decides whether to use drum mode
 239 individually for each MIDI file you play, based on whether it contains any
 240 drum sounds or not. If you have an orchestral piece with just the odd cymbal
 241 crash, you might be better removing the drums altogether as that will let
 242 Allegro use the non-drum mode and give you an extra three notes polyphony.
 243
 244 When Allegro is playing a MIDI file in looped mode, it jumps back to the
 245 start of the file when it reaches the end of the piece. To control the exact
 246 loop point, you may need to insert a dummy marker event such as a controller
 247 message on an unused channel.
 248
 249 All the OPL chips have very limited stereo capabilities. On an OPL2,
 250 everything is of course played in mono. On the SB Pro-I, sounds can only be
 251 panned hard left or right. With the OPL3 chip in the SB Pro-II and above,
 252 they can be panned left, right, or centre. I could use two voices per note
 253 to provide more flexible panning, but that would reduce the available
 254 polyphony and I don't want to do that. So don't try to move sounds around
 255 the stereo image with streams of pan controller messages, because they will
 256 jerk horribly. It is also worth thinking out the panning of each channel so
 257 that the music will sound ok on both SB Pro-I and OPL3 cards. If you want a
 258 sound panned left or right, use a pan value less than 48 or greater than 80.
 259 If you want it centred, use a pan value between 48 and 80, but put it
 260 slightly to one side of the exactly central 64 to control which speaker will
 261 be used if the central panning isn't possible.
 262
 263 The DIGMID wavetable driver uses standard GUS format .pat files, and you
 264 will need a collection of such instruments before you can use it. This can
 265 either be in the standard GUS format (a set of .pat files and a default.cfg
 266 index), or a patches.dat file as produced by the pat2dat utility. You can
 267 also use pat2dat to convert AWE32 SoundFont banks into the patches.dat
 268 format, and if you list some MIDI files on the command line it will filter
 269 the sample set to only include the instruments that are actually used by
 270 those tunes, so it can be useful for getting rid of unused instruments when
 271 you are preparing to distribute a game. See the Allegro website for some
 272 links to suitable sample sets.
 273
 274 The DIGMID driver normally only loads the patches needed for each song when
 275 the tune is first played. This reduces the memory usage, but can result in a
 276 longish delay the first time you play each MIDI file. If you prefer to load
 277 the entire patch set in one go, call the load_midi_patches() function.
 278
 279 The CPU sample mixing code can support between 1 and 32 voices, going up in
 280 powers of two (ie. either 1, 2, 4, 8, 16, or 32 channels). By default it
 281 provides 8 digital voices, or 8 digital plus 24 MIDI voices (a total of 32)
 282 if the DIGMID driver is in use. But the more voices, the lower the output
 283 volume and quality, so you may wish to change this by calling the
 284 reserve_voices() function or setting the digi_voices and midi_voices
 285 parameters in allegro.cfg.
 286
 287
 288
 289 ======================================
 290 ============ Contact info ============
 291 ======================================
 292
 293    WWW:                 http://www.talula.demon.co.uk/allegro/
 294
 295    Mailing list:        allegro@canvaslink.com. To add or remove yourself,
 296                         write to listserv@canvaslink.com with the text
 297                         "subscribe allegro yourname" or "unsubscribe
 298                         allegro" in the body of your message.
 299
 300    Usenet:              Try the djgpp newsgroup, comp.os.msdos.djgpp
 301
 302    IRC:                 #allegro channel on EFnet
 303
 304    My email:            shawn@talula.demon.co.uk
 305
 306    Snail mail:          Shawn Hargreaves,
 307                         1 Salisbury Road,
 308                         Market Drayton,
 309                         Shropshire,
 310                         England, TF9 1AJ.
 311
 312    Telephone:           UK 01630 654346
 313
 314    On Foot:             Coming down Shrewsbury Road from the town centre,
 315                         turn off down Salisbury Road and it is the first
 316                         house on the left.
 317
 318    If all else fails:   52 deg 54' N
 319                         2 deg 29' W
 320
 321    The latest version of Allegro can always be found on the Allegro
 322    homepage, http://www.talula.demon.co.uk/allegro/.
 323