BASED ON THE LATEST VERSION - RELEASE.3 - AUDIOTOOLS BY ROB PECK
   ****************************************************************
    Adaptation for  M2Amiga Modula-2   by Anthony Bryant   9/4/88

AudioTools is a collection of simple-to-use audio routines, that enable the
user to queue up several sounds and have the audio device play them,
sequentially, while your program continues doing what it was doing, without
going directly to the hardware.
 
This provides the capability to synchronize graphics and sound.  Now when you
InitAudio() - initialize the AudioTools - a return value must be saved so that
it can be used later to FinishAudio(), as well as passed with the function
procedure named MayGetNote().   You can identify a note by number, an id, using
PlayNote(), PlayFreq() or PlaySamp(), then tell MayGetNote() whether you want
to get a return immediately, if there is no identified note available to be
gotten, or if you want your task to wait until there is something to be
returned.  Additional procedures simplify operations on individual channels.

The AudioTools module has the appearance of a normal library module consisting
of a symbol file (sym/AudioTools.sym) and an object file (obj/Audiotools.obj)
from which you can IMPORT the following procedures.

The procedures: 

 port:= InitAudio();		initialize the audio routines, get a port
				for receiving messages from audio routines
                                
 chan:= GetChannel(type);	request a channel to use.
  
 error:= FreeChannel(chan);	free a channel that you have been given.
  
 FinishAudio(port);		end the use of audio routines and return
				the port you received from audio routines
                                and free up allocated CHIP RAM.

 error:= StopChannel(chan);	temporarily halt a channel you own.
 error:= StartChannel(chan);    start your channel up again.
 error:= FlushChannel(chan);    empty the queue of a channel from any notes
				it is playing or is going to play.
 error:= ResetChannel(chan);    reset a channel

 error:= IsThatMyChan(chan);    see if your task still owns a particular
                                channel (audio system allows stealing of
                                channels if the are not locked at a high
                                enough priority).
 flag:= CheckIfDone();          check if all notes are finished playing.
                                  
 id:= MayGetNote(port, flag);   see if a note you marked has begun to play.
				possibly put task to sleep if flag = TRUE
				good for synchronizing graphics and sound.

 error:= SetPV(channel,per,vol); set the period and/or volume of a channel
				that is already playing a waveform.

 error:= SetWave(chan,waveArray);  set up waveform, an ARRAY [0..255] OF BYTE,
                                   in CHIP RAM to play on specific channel.
 
  error:= SetSamp(chan,sample,length); copy sample data BYTES to CHIP RAM
                                 to play on specific channel .. unless..
                                 if length = 0 then just free up previous sample
                                 if sample (ADDRESS) = 0 then return new value
                                 in VAR sample - without copying data.
                                    
  PlayNote( ... parameters ...)  queue up a specific note number to be played
				 by one of your channels.
  PlayFreq( ... parameters ...)  queue up a specific frequency instead of note.

  PlaySamp( ... parameters ...)  queue up a sample to play instead of note.
  
  where ( ... parameters ...) = 
       (channel,note/freq/per,volume,duration,priority,messageport,id)
  
(See DEFINITION MODULE (AudioTools.def) for parameter types and specifics)

The error conditions:
 
 InitAudio()    returns a NIL pointer if OpenDevice() or CreatePort() failed.
 
 GetChannel()   normally returns specific channel number 0,1,2 or 3 UNLESS
                returns (notYourChannel) if channel already busy
                returns (badChannelSelected) if unit failed to be assigned
                returns -10  ADIOERR_NOALLOCATION if WaitIO() failed

IsThatMyChan()  normally returns 0 if valid channel you own UNLESS
                returns (badChannelSelected) if chan not 0,1,2 or 3
                returns (notYourChannel) if channel already busy
                
other Channel procedures and also SetPV() procedure 
                returns  same as IsThatMyChan() errors and also
                returns -10  ADIOERR_NOALLOCATION if WaitIO() failed
                        
IF (CheckIfDone() = FALSE) THEN notes not finished playing
IF (CheckIfDOne() = TRUE ) THEN o.k. all finished

SetWave()      normally returns 0 if everything went o.k. UNLESS
               returns same as IsThatMyChan() errors and also
               returns (outOfMemory) if AllocMem() failed
               
SetSamp()      same as SetWave()

(See IMPLEMENTATION MODULE (AudioTools.imp) for the complete source code. )

Using the AudioTools routines:

FROM AudioTools IMPORT

PROGRAM MODULE (AudioDemo.mod) contains the complete source to a simple demo
showing the usage for each of the many commands that make AudioTools easy to
use.  AudioDemo is the executable file.

-------------------------------------------------------------------------------
  The C source for AudioTools was kindly placed into the public domain by 
  
  Rob Peck, thanks Rob!   This M2Amiga Modula-2 adaptation, source, symbol and
  
  object library module files, including demo is also now in the public domain.
  
  Audiotools is being revised, so this adaptation is based on RELEASE.3, the
  
  latest (and greatest) version.  In the fullness of time, it is to be hoped,
  
  AudioTools will become a shared library (loadable from disk), but in the
  
  meantime I will try to keep this M2 directory up-to-date with the latest
  
  Release from Rob.
  
                                  Anthony Bryant   9/4/88
  -----------------------------------------------------------------------------