                     SOUND.C - SB DRIVER FUNCTIONS V1.1
                     ==================================

The SOUND.C file includes a set of simple routines for generating audio 
output through a basic SB card, which of course should include all SB
compatible cards.  The routines are designed to use the low-speed DMA
output feature of the SB card.  The routines will automatically create
the necessary buffers, and will create a continuous stream of output
assuming that the Fillbuffer function is called periodically.  The
rate at which Fillbuffer must be called is dependent on the number of
buffers, the size of each buffer, and the playback frequency.

These functions have been designed to work with the 16-bit Borland 'C'
compiler.  Some modification is required to support 32-bit applications.

A header file 'SOUND.H' has been included for use in other modules, and
provides the necessary function prototypes.

The routines are easy to use.  Detailed descriptions on the function calls   
are listed below.


LIMITATIONS
-----------

The SB Driver routines have several limitations.  Most of these limitations
should be easy to eliminate.

1) The routines can support any IRQ from 0 to 7.  If any other IRQ is needed,
   changes are required.  This should be changed to allow support for all
   SB cards.

2) The routines can support any DMA channel from 0 to 3.  If any other DMA
   channel is needed, changes are required.  This may need to be changed to
   support all SB cards.

3) The routines only support the low-speed DMA output function of the SB
   card, which limits the maximum playback to approximately 22KHz.

4) The routines only support 8-bit mono audio output.  

5) The routines require that the 'BLASTER' environment variable be configured.
   This can be accomplished by using "SET BLASTER = A220 I7 D1" from the 
   command line.  The 'A' value is the base address of the card, the 'I' value
   is the configured interrupt line, and the 'D' value is the configured DMA
   channel.


GENERAL OVERVIEW
----------------

On start-up of the system, a single call should be made to OpenSB.  
This routine will reset the SB, setup the interrupts and prepare the 
structures for sound output.  This routine should not be called again 
until after the CloseSB function is called.

On system shut-down, a single call should be made to CloseSB.  This routine
will reset the SB, disable the interrupts and free the structures that were
created.

Once in the main loop, the Fillbuffer routine must be called periodically.
The frequency at which this function must be called depends on the number
of buffers, the size of each buffer and the playback frequency.  This 
routine will fill the next buffer in the queue with data and set a flag
to let the interrupt vector know there is data to be processed.  If the
system is currently not playing audio, it will also send the current buffer 
out to 'prime the interrupt pump'.

The Fillbuffer routine is currently designed to call the Pokey_process 
function.  This function call can be replaced by any other function which
will make the SB Driver routines generic.


DETAILED FUNCTION DESCRIPTIONS
------------------------------

OpenSB (unsigned int playback_freq, unsigned int num_bufs, 
        unsigned int buffer_size)
----------------------------------------------------------

This function resets and initializes the SB, initializes and enables the
interrupts, and creates and initializes all local global structures. 
This function takes three parameters: the playback frequency, the number
of playback buffers to be used and the size of each playback buffer.

The playback frequency can be any unsigned integer from 1-65535, though
the maximum limit is currently set by the SB low-speed DMA audio routines
(approx. 22KHz).  

The number of buffers can be any value from 1 to 8.  For best results, use
2-4 buffers. 

The buffer size can be any value from 1 to 65535.  The actual size needed
will depend on the playback frequency.  Typically, between 500 and 1500
samples is sufficient.

If the call to OpenSB was unsuccessful, the function will return a value
of 0.  Otherwise, the return value will be non-zero.


CloseSB (void)
--------------

This function disables all interrupts, frees all buffers and stops all
SB audio output.  This function should be called before the program 
exits.  This function has no input or output parameters.


Fillbuffer (void)
-----------------

This function fills the next buffer in the audio queue if it is empty.  If
there the system is not currently sending audio output, this function will
automatically transmit the current buffer to the SB to 'prime the interrupt
pump.'  This function has no input or output parameters.

This function is currently designed to call the Pokey_process function to
fill the current buffer.  This call could be replaced by any function to
make the SB driver routines generic.  


License Information and Copyright Notice
========================================

PokeySound is Copyright(c) 1996 by Ron Fries

This library is free software; you can redistribute it and/or modify it under 
the terms of version 2 of the GNU Library General Public License as published 
by the Free Software Foundation.

This library is distributed in the hope that it will be useful, but WITHOUT 
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 
FOR A PARTICULAR PURPOSE.  See the GNU Library General Public License for more 
details.

To obtain a copy of the GNU Library General Public License, write to the Free 
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Any permitted reproduction of these routines, in whole or in part, must bear 
this legend.  
