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