home *** CD-ROM | disk | FTP | other *** search
/ Sound, Music & MIDI Collection 2 / SMMVOL2.bin / MIDI_PAT / MTOOLS.ZIP / PLAYRDEV.EXE / MLIB_PAS.DOC < prev    next >
Encoding:
Text File  |  1992-11-07  |  7.4 KB  |  249 lines
  1. -----------------------------------------------------------------------------
  2.  
  3.            MLIB.PAS - Pascal 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.  
  12. The unit mlib.pas implements most of the Play/R API functions.  Simply
  13. include mlib in your program's uses clause.  See API.DOC for further
  14. information on the API functions, which in most cases have a one-to-one
  15. correspondence with the Pascal versions.  API.DOC also includes other
  16. important information on the driver, plus distribution licensing terms.
  17.  
  18.  
  19.  
  20. ----------------------- Global variables defined ---------------------------
  21.  
  22.   MidiDriverLoaded: boolean;    {true if driver is loaded, else false}
  23.  
  24.   MID: integer;                 {Default device id number}
  25.  
  26.  
  27. ----------------------------- Initialization -------------------------------
  28.  
  29.   The mlib unit automatically tests for the presence of the driver
  30.   and does other initialization.  It defines the global variables
  31.   MidiDriverLoaded and MID.
  32.  
  33.  
  34. ------------------------ MIDI file functions -------------------------------
  35.  
  36. procedure mfPause;
  37.  
  38.      Pauses MIDI file play.
  39.  
  40.  
  41. procedure mfContinue;
  42.  
  43.      Continues play after pausing.
  44.  
  45.  
  46. procedure mfPopup;
  47.  
  48.      Causes pop up window to appear.  (Play/R)
  49.  
  50.  
  51. procedure mfRewind;
  52.  
  53.      Rewind to beginning of song and pause.
  54.  
  55.  
  56. function mfPlay(name: string): integer;
  57.  
  58.      Load specified song and start play.
  59.      Return value = load status:
  60.                          0 = File loaded successfully
  61.                          1 = File not found
  62.                          2 = Not MIDI file format
  63.                          3 = Unexpected end of file
  64.                          4 = Format not supported
  65.                          5 = Track not found
  66.                          6 = I/O error reading file
  67.                          7 = Not enough memory 
  68.                          8 = Unsupported time base
  69.                          255 = Nothing loaded
  70.  
  71.  
  72. procedure mfSongStat(var playing, done: boolean; var position: longint;
  73.                      var songcount, cursong: byte);
  74.  
  75.      Gets song status:
  76.         playing   = true if play in progress, false if paused
  77.         done      = true if at end of song, else false
  78.         position  = song position in milliseconds
  79.         songcount = size of play list, 0 if none
  80.         cursong   = current song number in play list
  81.  
  82.  
  83. procedure mfFileStat(var stat: byte; var name: string);
  84.  
  85.      Gets file load status (see mfPlay) and current file name.
  86.  
  87.  
  88. function mfLoad(name: string): integer;
  89.  
  90.     Load file but do not begin play.
  91.     Return value = load status (see mfPlay).
  92.  
  93.  
  94. procedure mfQuiet;
  95.  
  96.     Stops all sounding notes.
  97.  
  98.  
  99. procedure mfPopEnable(stat: boolean);
  100.  
  101.     Enable (stat=true) or disable (stat=false) user initiated pop up.
  102.     (Play/R only)
  103.  
  104.  
  105. procedure mfVolume(adjust: integer);
  106.  
  107.     Adjust song volume +/- 128 velocity units from initial value.
  108.  
  109.  
  110. procedure mfTimeMode(mode: integer);
  111.  
  112.     Set timer stepping mode (1-3).  See "Timing Considerations" in the
  113.     file API.DOC for further info.
  114.  
  115.  
  116. procedure mfGetChan(datatype: integer; var chan: channels);
  117.  
  118.     Get channel attributes.  Returns an array of 16 channel (channels
  119.     type is defined as an array of bytes) attributes, their meaning
  120.     depending on the value of datatype:
  121.  
  122.         "datatype"              "chan" array contents
  123.       --------------   --------------------------------------------
  124.        0 (chan_map)     Output channel map - values from 0 to 15
  125.  
  126.        1 (chan_ena)     Channel enable flag - 1=enable, 0=disable
  127.  
  128.        2 (chan_xpos)    Channel transpose - 8-bit 2's comp (if greater
  129.                         than 127, subtract 256 to get signed value;
  130.                         when setting, use lo() to get low order byte of
  131.                         signed integer).
  132.  
  133.        Note: chan_map, chan_ena, and chan_xpos are predefined constants.
  134.  
  135.  
  136. procedure mfSetChan(datatype: integer; chan: channels);
  137.  
  138.     Set channel attributes according to the specified array
  139.     (chan) and attribute type (datatype).  See mfGetChan.
  140.  
  141.  
  142. procedure mfSetPos(time: longint);
  143.  
  144.     Set song position to specified time in milliseconds.  If time is
  145.     negative, skip forward abs(time) milliseconds.
  146.  
  147.  
  148. procedure mfSkipSong(n: byte);
  149.  
  150.     Skip to song n in play list.  If beyond end of list, skip to 1.
  151.  
  152.  
  153. procedure mfLoopMode(n: byte);
  154.  
  155.     Set song looping mode:   0 = no looping
  156.                              1 = loop current song
  157.                              2 = loop play list (startup default)
  158.  
  159.  
  160. ---------------------- General MIDI functions ----------------------------
  161.  
  162. function midiDevName(dev: integer; var devname: string;
  163.                      var devdesc: string): integer;
  164.  
  165.     Gets 3-letter device designation and 20-character description
  166.     for specified device number (starting at 1).  Returns non-zero
  167.     if device exists, else 0 if no more devices.
  168.  
  169.  
  170. procedure midiReset(dev: integer);
  171.  
  172.     Resets device to UART status.
  173.  
  174.  
  175. procedure midiPutBuffer(dev: integer; bufptr: pointer; len: word);
  176.  
  177.     Writes a buffer pointed to by bufptr of len bytes to device dev.
  178.     May be used while MIDI file play is in progress (although play will
  179.     be suspended until all the data is sent).
  180.  
  181.  
  182. procedure midiPutBuffer1(dev: integer; bufptr: pointer; len: word);
  183.  
  184.     Same as midiPutBuffer, but uses direct calls to the output driver.
  185.     This is more efficient for shorter messages, but MIDI file play must
  186.     be stopped first using mfPause.
  187.  
  188.  
  189. procedure midiGetBuffer(dev: integer; bufptr: pointer; max: word;
  190.                         var recv: word);
  191.  
  192.     Returns up to max bytes to buffer pointed to by bufptr from device
  193.     dev.  Function return value is number of bytes actually transferred.
  194.  
  195.  
  196. procedure midiPutByte(dev, data: integer);
  197.  
  198.     Write a single MIDI data byte.  MIDI file play should be suspended
  199.     while using this routine.
  200.  
  201.  
  202. function midiInputReady(dev: integer): boolean;
  203.  
  204.     Test for input data waiting.  Function returns true if data waiting,
  205.     else false.
  206.  
  207.  
  208. procedure midiGetByte(dev: integer; var data: integer);
  209.  
  210.     Read a single MIDI byte.  Returns -1 if no data arrives
  211.     within 200 ms.  Use with midiInputReady for best results.
  212.  
  213.  
  214. procedure midiClearInput(dev: integer);
  215.  
  216.     Clear all unread data from device.
  217.  
  218. procedure midiGetMessage(dev: integer; var msg: messages;
  219.                          var chan, data1, data2: byte);
  220.  
  221.     Get a full MIDI message from specified device, returning message
  222.     class (enumerated type "messages" - see MIDI.INC), channel, and two
  223.     data bytes (one or both may be unused).
  224.  
  225.  
  226. procedurel midiResend(dev: integer);
  227.  
  228.     Resend data just read by midiGetMessage;
  229.  
  230. procedure midiPutMessage(dev: integer; msg: messages;
  231.                          chan, data1, data2: byte);
  232.  
  233.     Send a full MIDI message using specified device, message type (see
  234.     MIDI.INC), channel (0-based), and up to two data bytes.
  235.  
  236.  
  237. ---------------------------- Misc. functions ----------------------------
  238.  
  239. function msTimer: longint;
  240.  
  241.     Return reference time in milliseconds.
  242.  
  243.  
  244. procedure midiRemove;
  245.  
  246.     Removes driver from memory if possible to do so.
  247.  
  248. =========
  249.