home *** CD-ROM | disk | FTP | other *** search
/ Black Box 4 / BlackBox.cdr / progc / kslib.arj / MUSIC.DOC < prev    next >
Encoding:
Text File  |  1991-07-18  |  3.0 KB  |  84 lines
  1. Documentation for music routines
  2. --------------------------------
  3. Source file(s)    : music.c
  4. Include file(s)    : music.h
  5. Library            : tools.lib
  6.  
  7. The music routines enable sound to be played through the normal PC speaker.
  8. The first routine emulates the standard BASIC "play" command, with single
  9. note output, while the other two routines enable 3-voice polyphonic music
  10. to be played from a file in a special format.
  11.  
  12. ===============================================================================
  13.  
  14. Function        void play(char *s)
  15. Prototype in    music.h
  16.  
  17.     Plays notes from the character string s. S should contain a sequence of
  18.     commands, optionally followed by a single digit argument, as follows :
  19.  
  20.     Command        Argument    Function
  21.     A-G            1-9            Play the note, set the length for this note only
  22.                             if the argument is present.
  23.     T            0-9            Set the tempo from 0 (fastest) to 9 (slowest).
  24.     L            1-9            Set the default note length from 1 (full note) to
  25.                             9 (1/256th note).
  26.     O            1-9            Set the octave from 0 (lowest) to 9 (highest).
  27.     @            filename    Continue getting commands from the specified file.
  28.                             Unless this is the last command in the string, the
  29.                             argument should be terminated by another '@'. The
  30.                             file can contain multiple lines, and can contain
  31.                             another '@' command. '@'s can be nested until you
  32.                             run out of memory.
  33.  
  34. Returns            Nothing
  35.  
  36. -------------------------------------------------------------------------------
  37.  
  38. Function        void tri(short tune)
  39. Prototype in    music.h
  40.  
  41.     Takes an array of 'short', and plays it. Each element in the array must
  42.     be at least 16 bits long. The highest 3 bits represent the Command, and
  43.     the lowest 13 bits represent the Value. The commands are as follows :
  44.  
  45.     000        End-Of-Tune
  46.     001        Delay for Value, then play Voices 1,2 & 3
  47.     010        Change Tempo to Value
  48.     011        Ignore this Value
  49.     100        Set Pitch for Voice 1
  50.     101        Set Pitch for Voice 2
  51.     110        Set Pitch for Voice 3
  52.     111        Set Pitch for Voice 3
  53.  
  54.     Note that this is only my best guess at how this thing really works.
  55.     Take it with a pinch of salt.
  56.  
  57. Returns            Nothing
  58.  
  59. -------------------------------------------------------------------------------
  60.  
  61. Function        char *mplay(char *name)
  62. Prototype in    music.h
  63.  
  64.     This function uses tri() to play a tune stored in a file. The file has a
  65.     default extension of ".POL", and should contain a series of integers
  66.     seperated by blanks or newlines. Each of the integers should be in the
  67.     format specified for tri().
  68.  
  69. Returns            pointer to the name of the file played.
  70.  
  71. ===============================================================================
  72.  
  73. General notes :
  74. ---------------
  75.  
  76. mplay() was written by Mike Talvola, of Agoura Hills CA, and placed in the
  77. public domain. I used it here virtually unchanged.
  78.  
  79. tri() was written by A. Bogatyrev, of Moscow, and placed in the public domain.
  80. Again, I used it here virtually unchanged.
  81.  
  82. play() was written by myself, and is placed in the public domain, although I
  83. retain full copyrights.
  84.