home *** CD-ROM | disk | FTP | other *** search
/ Audio 4.94 - Over 11,000 Files / audio-11000.iso / amiga / utils / atools / atools.doc next >
Text File  |  1988-03-23  |  4KB  |  93 lines
  1.  
  2.  
  3. RELEASE 2 - AUDIO TOOLS - DOCUMENTATION 
  4. --------------------------------------- 
  5.  
  6. The RELEASE.2 directory contains the source and executable program 
  7. for the second release of the audio tools, called audiotools2.c.   
  8. The example program is called rel2.demo.c. 
  9.  
  10. It includes the following functions that are designed to be used by 
  11. the casual user as well as a developer.  A one-line description is 
  12. provided here, with complete documentation for each following later 
  13. in this document. 
  14.  
  15. The functions: 
  16.  
  17.   port = InitAudio()            initialize the audio routines, get a port 
  18.                                 for receiving messages from audio routines 
  19.   channel = GetChannel(type)    request a channel to use. 
  20.   error = FreeChannel(channel)  free a channel that you have been given. 
  21.   FinishAudio(port)             end the use of audio routines and return 
  22.                                 the port you received from audio routines 
  23.  
  24.   error = StopChannel(channel)  temporarily halt a channel you own 
  25.   error = StartChannel(channel) start your channel up again. 
  26.   error = FlushChannel(channel) empty the queue of a channel from any notes 
  27.                                 it is playing or is going to play. 
  28.   error = ResetChannel(channel) reset a channel 
  29.  
  30.   PlayNote( ... parameters ...) queue up a specific note number to be played 
  31.                                 by one of your channels. 
  32.   PlayFreq( ... parameters ...) queue up a specific frequency instead of note. 
  33.  
  34.   IsThatMyChan(channel)         see if your task still owns a particular 
  35.                                 channel (audio system allows stealing of 
  36.                                 channels if they are not locked at a high 
  37.                                 enough priority).   
  38.  
  39.   note = MayGetNote(port, flag) see if a note you marked has begun to play. 
  40.                                 possibly put task to sleep if it has not. 
  41.                                 good for synchronizing graphics and sound. 
  42.  
  43.   SetPV(channel,per,vol)        Set the period and/or volume of a channel 
  44.                                 that is already playing a waveform.  Limited 
  45.                                 use (except for volume, that is; see the 
  46.                                 article text to see why you may not want to 
  47.                                 use this routine to set the period.  In fact, 
  48.                                 I will probably add routines that do volume 
  49.                                 and period separately - routine has to 
  50.                                 be able to read what is now playing to 
  51.                                 be able to modify it properly.) 
  52.  
  53.  
  54. USING THE ROUTINES 
  55. ------------------ 
  56.  
  57. To use the routines, the proper minimal code sequence is: 
  58.  
  59.         1. Declare a pointer to a message port: 
  60.  
  61.                 struct MsgPort *myport; 
  62.  
  63.         2. Declare a LONG integer variable to hold a channel number: 
  64.  
  65.                 LONG channel; 
  66.  
  67.         3. Initialize the audio routines, if successful, the init 
  68.            returns a pointer to a message port: 
  69.  
  70.                 myport = InitAudio(); 
  71.  
  72.         4. Get a channel to use for your output: 
  73.  
  74.                 channel = GetChannel(-1);  
  75.  
  76.            where -1 means "any" available channel, 
  77.            0, 1, 2, or 3 means a specific channel. 
  78.  
  79.            If a value of 0, 1, 2, or 3 is returned, 
  80.            you have that channel to use. 
  81.  
  82.         5. Choose a note or frequency to play, and its duration, 
  83.            the waveform to use, and so on (see detailed 
  84.            descriptions of PlayNote and PlayFreq). 
  85.  
  86.                 error = PlayNote(... parameters ...); 
  87.  
  88.                     or 
  89.  
  90.                 error = PlayFreq(... parameters ...); 
  91.  
  92.  
  93.