home *** CD-ROM | disk | FTP | other *** search
/ Sound, Music & MIDI Collection 2 / SMMVOL2.bin / MIDI_PAT / MTOOLS.ZIP / PLAYRDEV.EXE / GRASP.DOC < prev    next >
Encoding:
Text File  |  1993-09-14  |  7.8 KB  |  199 lines
  1. ---------------------------------------------------------------------------
  2.  
  3.               GRASP implementation of Play/R interface
  4.  
  5. ---------------------------------------------------------------------------
  6.           Copyright 1992, Kevin Weiner, All rights reserved
  7.  
  8.              Proprietary material - not for distribution
  9. --------------------------------------------------------------------------- 
  10.  
  11. Many of the available Play/D functions have been implemented in GRASP
  12. code in the accompanying files MIDI.TXT (for GRASP 4) or MIDI_MM (for
  13. Multimedia GRASP).  Those functions may be expanded fairly easily to 
  14. implement any features not included (for example, MIDI input).  To add 
  15. MIDI file capability to your GRASP program, simply add the line 
  16. "merge midi" (or "merge midi_mm" for MMGRASP).  Then call the functions 
  17. described below to perform assorted MIDI file operations.  Be sure you
  18. are using the version of the file that matches your copy of GRASP; the
  19. two versions of GRASP have some minor source incompatibilities.
  20.  
  21. The GRASP interface follows the model described in API.DOC.  GRASP
  22. provides an INT command, which allows the int 2F multiplex call to be
  23. made with the appropriate machine register values passed as arguments. 
  24. Unless you are modifying the MIDI.TXT or MIDI_MM.TXT code, however, you 
  25. need not be aware of how things are actually working; just call the 
  26. high-level functions.  You should, however, review API.DOC because it 
  27. contains other important information on the driver, plus distribution 
  28. licensing terms. 
  29.  
  30. Initialization
  31. --------------
  32.  
  33. The function mfinit must always be the first MIDI routine called to
  34. initialize the driver.  When mfinit returns, @0 will be 1 if it was
  35. successful, or 0 otherwise.  Failure generally means that playd.exe has
  36. not been run, so you should report to the user that the MIDI driver
  37. (playd.exe) has not been loaded. 
  38.  
  39. Loading a file
  40. --------------
  41.  
  42. A MIDI song file is loaded into memory with the mfload function:
  43.  
  44.      mfload  <file name>
  45.  
  46. <filename> must be a valid MIDI file name string, or the name of a play
  47. list.  A play list is a simple text file consisting of one MIDI file
  48. name per line.  A play list is distinguished from a MIDI file by
  49. prefixing its name with the "@" character.  When mfload returns, @0 will
  50. contain a load status value.  Possible load status values are listed
  51. below:
  52.  
  53.                0 = File loaded successfully
  54.                1 = File not found
  55.                2 = Not MIDI file format
  56.                3 = Unexpected end of file
  57.                4 = Format not supported
  58.                5 = Track not found
  59.                6 = I/O error reading file
  60.                7 = Not enough memory
  61.                8 = Unsupported time base
  62.                255 = Nothing loaded
  63.  
  64. Playing and pausing
  65. -------------------
  66.  
  67. After a file is loaded, start it with mfplay.  A any point, it may be
  68. stopped with mfpause, and then resumed with mfplay.  When the song is
  69. complete, it will be in a paused state and mfplay will restart it from
  70. the beginning. 
  71.  
  72. Song positioning
  73. ----------------
  74.  
  75. To rewind a song to the beginning at any time during play, use mfrewind. 
  76. This skips to time zero in the file and pauses.  Note that if the song
  77. is already at the beginning, mfrewind will function as a reverse skip to
  78. the previous song if a play list is loaded. 
  79.  
  80. To skip to a specific point in a song, use mfsetpos:
  81.  
  82.      mfsetpos  <pos>
  83.  
  84. If <pos> is a positive number, it is taken to be the song location in
  85. milliseconds to which the player will be positioned.  Note that it may
  86. take up to several seconds to seek to the requested position, depending
  87. upon how far it is from the current position.  Skipping to an earlier
  88. position requires seeking from the beginning. 
  89.  
  90. If <pos> is a negative number, its absolute value specifies the number
  91. of milliseconds to fast forward from the current position. 
  92.  
  93. Positioning in a play list
  94. --------------------------
  95.  
  96. Use mfskip to select a specific song in a play list:
  97.  
  98.      mfskip  <num>
  99.  
  100. <num> is the number of a song in the play list (counting from 1).  If
  101. <num> is beyond the end of the play list, the player will skip to song 1.
  102. If play is in progress, the new song will begin playing immediately after
  103. loading.  If play has been paused, the new song will wait until the next
  104. mfplay to begin.  As noted above, mfrewind will skip to the previous
  105. song in the list if already at the beginning of a song.  As play
  106. progresses and the last song completes, the player will cycle back to
  107. the first song and begin again. 
  108.  
  109. Player status
  110. -------------
  111.  
  112. Use mfstatus to obtain the status of the current song and play list. 
  113. Mfstatus returns @0 with one of the following values:
  114.  
  115.      0  =  Paused
  116.      1  =  Playing
  117.      2  =  Done
  118.  
  119. In addition, three global variables are set:
  120.  
  121.      @etime  =  Elapsed time of current song in milliseconds
  122.      @songcount  =  Total number of songs in play list (0 if no list)
  123.      @cursong  =  Number of the current song in the play list
  124.  
  125. Song volume
  126. -----------
  127.  
  128. The mfvolume adjusts the overall song volume by a specified amount:
  129.  
  130.      mfvolume  <vol>
  131.  
  132. <vol> is a number from -127 to +127, relative to the song's initial
  133. volume.  A value of 0 restores the initial volume.  The volume control
  134. is in terms of MIDI velocity units.  Not all devices or instrument
  135. voices respond to velocity information, so this function may not always
  136. be effective.  Also, if MIDI velocity codes in the file are at maximum,
  137. only negative adjustments can be used. 
  138.  
  139. Sending MIDI messages
  140. ---------------------
  141.  
  142. Individual MIDI messages consisting of one, two, or three bytes may be
  143. sent with the midisend function:
  144.  
  145.      midisend   <status>  <data1>  <data2>
  146.  
  147. All MIDI messages contain at least a status byte.  Some contain one or
  148. two additional data bytes.  One or both of the arguments <data1> and
  149. <data2> may be omitted if not needed for a particular message.  There
  150. are many books available which describe MIDI messages in detail,
  151. however, some simple examples are given here. 
  152.  
  153. MIDI channel messages (such as "note-on") have a two-part status byte. 
  154. The 4 high-order bits determine the type of message, and the 4 low-order
  155. bits indicate the channel.  MIDI channels 1-16 are represented by the
  156. numbers 0 - 15. 
  157.  
  158. For your convenience, the mfinit function defines three of the most
  159. common MIDI messages as global variables:
  160.  
  161.      @note_on  Note-on message  (value 0x90)
  162.      @ctrl_ch  Control change message  (value 0xb0)
  163.      @prog_ch  Program change message  (value 0xc0)
  164.  
  165. To construct a status byte, add one of these message type variables to a
  166. channel number from 0 to 15 (one less than the nominal channel). 
  167.  
  168. A note-on message consists of a status byte, a note number from 0 to
  169. 127, and a velocity value (also 0 - 127).  To play a middle C note (note
  170. number 64) on channel 3 (actually 2), with medium-high velocity (96),
  171. use the following:
  172.  
  173.      midisend  @note_on+2   64   96
  174.  
  175. The "+2" selected channel 3 when constructing the status byte.  A note-on 
  176. message with zero velocity turns off the sounding note.  To turn off the
  177. note played above, use:
  178.  
  179.      midisend  @note_on+2   64   0
  180.  
  181. There are many control change messages available, requiring a table to
  182. use them, but they are also 3-byte messages like note-on.  The program
  183. change message is much simpler, requiring a single data byte to select a
  184. program (meaning a patch, or instrument type) on a particular channel. 
  185. To change to program 10 (actually numbered 9) on channel 1 (actually
  186. numbered 0), use:
  187.  
  188.      midisend  @prog_ch+0  9
  189.  
  190. Absolute time
  191. -------------
  192.  
  193. The mstimer function returns the value of an absolute millisecond timer
  194. in @0 for any additional timing operations you may find necessary.  This
  195. timer runs independently of the player, and represents the number of
  196. milliseconds since playd.exe was loaded. 
  197.  
  198. =========
  199.