home *** CD-ROM | disk | FTP | other *** search
/ PC Loisirs 18 / cd.iso / sharewar / mikm202 / docs / mdriver.doc < prev    next >
Encoding:
Text File  |  1995-09-18  |  10.7 KB  |  396 lines
  1. ┌──────────────────────────────┐
  2. │MDRIVER.C Module Documentation│
  3. └──────────────────────────────┘
  4.  
  5. Date last modified: April 05, 1995
  6.                             
  7. If you want to use any of the routines of this module, include "mdriver.h" 
  8. and link every soundcard driver you want to use with your program.
  9.  
  10. Available soundcard drivers:
  11.  
  12. Gus:
  13.  
  14.     DRVGUS\GUSDEV.LIB
  15.  
  16. Soundblaster & compatibles:         
  17.  
  18.     DRVSB\SBDEV.LIB
  19.  
  20. if you want to use this, you'll also have to add VIRTCHAN\VIRTCHAN.LIB, 
  21. MDMA.C and MEMS.C to your project.
  22.  
  23. No sound:
  24.                       
  25.     DRVNOSND\NOSNDDEV.LIB
  26.  
  27. ════════════════════════════════════════════════════════════════════════════════
  28.  
  29. General information:
  30.  
  31. As far as the other modules are concerned, the driver module is a set of 
  32. _universal_ routines for producing sound. The other modules don't have to 
  33. worry about how to drive a particular soundcard, they just 'ask' the driver 
  34. module to reserve so many voices, to mix at a certain rate and to play a 
  35. voice every once in a while. The driver module will adjust the requested 
  36. mixing mode and frequency if the actual soundcard doesn't support it.
  37.  
  38. When we take a closer look at the driver module we see that it's just a set 
  39. of 'glue' functions that redirect the driver function calls to the actual 
  40. selected soundcard driver:    
  41.  
  42.  
  43.         ┌───────────────┬────────────────────────┐
  44.         │DRIVER BLACKBOX│                        │
  45.         ├───────────────┘                        │
  46.         │                                        │
  47.      sb     │┌──────────┐                            │
  48.    hardware─┼┤sb driver ├══╗ <- selected driver      │
  49.         │└──────────┘  ║                         │
  50.         │              ║                         │
  51.      gus    │┌──────────┐  ║                         │
  52.    hardware─┼┤gus driver├──║                         │
  53.         │└──────────┘  ║ ┌─────────────────────┐ │
  54.         │              ╚═┤DRIVER GLUE FUNCTIONS├─┼<>─ interface to
  55.      pas    │┌──────────┐  │ └─────────────────────┘ │    other modules
  56.    hardware─┼┤pas driver├──┤                         │
  57.         │└──────────┘  │  - common driver        │
  58.         │              │    routines             │
  59.      other  │┌──────────┐  │                         │
  60.    hardware─┼┤etc..     ├──┘  - common driver        │
  61.         │└──────────┘       variables            │
  62.         │                                        │
  63.         └────────────────────────────────────────┘
  64.  
  65. To prevent having to link _all_ lowlevel soundcard drivers to the player 
  66. (when you only want to use the gus-driver), the first thing the main module 
  67. has to do before using the driver module is to 'register' all drivers it 
  68. might need. This way only the registered drivers will get linked to the 
  69. executable, thus reducing the size of it. So registering a driver to the 
  70. driver module is a way of saying 'lookee here, another driver you can choose
  71. from'.
  72.  
  73. ════════════════════════════════════════════════════════════════════════════════
  74.  
  75. MDRIVER public variables:
  76.  
  77. DRIVER *md_driver       // pointer to the currently used driver
  78.             // this variable is set after a call to MD_Init()
  79.  
  80. UWORD  md_device        // device-number
  81. UWORD  md_mixfreq       // current mixing frequency
  82. UWORD  md_dmabufsize    // dma buffer size (for sb)
  83. UWORD  md_mode          // output mode
  84. UBYTE  md_numchn        // number of channels to use
  85. UBYTE  md_bpm           // current bpm rate
  86.  
  87. ════════════════════════════════════════════════════════════════════════════════
  88.  
  89. void MD_InfoDriver(void)
  90. ========================
  91.  
  92. Input parms:
  93.  
  94.     -
  95.  
  96.  
  97. Returns:
  98.  
  99.     -
  100.  
  101.  
  102. Description:
  103.  
  104. This function produces a list of all registered drivers to stdout. Use it 
  105. _after_ you've registered all drivers using ML_RegisterDriver().
  106.  
  107. ════════════════════════════════════════════════════════════════════════════════
  108.  
  109. void MD_RegisterDriver(DRIVER *drv)
  110. ===================================
  111.  
  112. Input parms:
  113.  
  114.     drv     pointer to a DRIVER structure
  115.  
  116.  
  117. Returns:
  118.  
  119.     -
  120.  
  121.  
  122. Description:
  123.  
  124. Before you can use any of the other device-routines you first have to 
  125. register the drivers you want to use. This way only the registered drivers 
  126. are linked to the resulting program, so if you only want to support a single 
  127. soundcard your program won't be so big.
  128.  
  129.  
  130. Example:
  131.  
  132.     [at the top of the program:]
  133.  
  134.     extern DRIVER gusdriver,sbdriver;
  135.  
  136.     [ at the start of the main program: ]
  137.  
  138.     {
  139.         ...
  140.  
  141.         MD_RegisterDriver(&gusdriver);
  142.         MD_RegisterDriver(&sbdriver);
  143.  
  144.         MD_InfoDriver();
  145.         ...
  146.         ...
  147.  
  148.     }
  149.  
  150. ════════════════════════════════════════════════════════════════════════════════
  151.  
  152. BOOL MD_Init(void)
  153. ==================
  154.  
  155. Input parms:
  156.  
  157.     -
  158.  
  159. Returns:
  160.  
  161.     True if soundcard init succeeded, FALSE otherwise.
  162.  
  163. Description:
  164.  
  165. Before calling this routine you have to initialize some variables:
  166.  
  167.     md_mixfreq:     What mixing frequency do you want to use (Hz)
  168.  
  169.     md_dmabufsize:  How big the soundcard dma-buffer should be (in bytes)
  170.  
  171.     md_mode:        Flags what output mode to use.. Use the bitwise OR (|)
  172.             to combine flags:
  173.             
  174.             DMODE_16BITS : 16 bits output
  175.             DMODE_STEREO : stereo output
  176.  
  177.     md_device:      The number of the driver you want to use. Use 0 to
  178.             use the first soundcard it detects.
  179.  
  180. MD_Init will call the initialisation routine of the specified driver. When 
  181. the soundcard doesn't support any of selected mixing modes or mixing 
  182. frequency it will adjust the md_mode & md_mixfreq to values that _are_ 
  183. supported. For example, if you have a SB-pro and you try to init it with the 
  184. DMODE_16BITS flag set, it removes this flag after the MD_Init() call.
  185.  
  186. !!! It is ILLEGAL to change the variables md_mixfreq,md_dmabufsize, md_mode & 
  187. md_device AFTER you've called MD_Init()!!!
  188.  
  189. ════════════════════════════════════════════════════════════════════════════════
  190.  
  191. **** The following routines may only be called if MD_Init succeeded ****
  192.  
  193. ════════════════════════════════════════════════════════════════════════════════
  194.  
  195. void MD_Exit(void)
  196. ==================
  197.  
  198. Input parms:
  199.  
  200.     -
  201.  
  202. Returns:
  203.  
  204.     -
  205.  
  206. Description:
  207.  
  208. De-initialises the soundcard after you're done with it.
  209.  
  210. ════════════════════════════════════════════════════════════════════════════════
  211.  
  212. WORD MD_SampleLoad(FILE *fp,ULONG size,ULONG reppos,ULONG repend,UWORD flags)
  213. =============================================================================
  214.  
  215. Input parms:
  216.  
  217.     fp      filepointer to raw sample data
  218.     size    size of the sample (in samples!)
  219.     reppos  repeat start offset
  220.     repend  repeat end offset
  221.     flags   flags which indicate the format of the sample
  222.  
  223. Returns:
  224.  
  225.     A handle which identifies the sample, or -1 incase of an error
  226.  
  227. Description:
  228.  
  229. Loads a raw sample from file to the soundcard. It returns a number (handle)
  230. which identifies the sample (you need the handle if you want to play the sample).
  231.  
  232. ════════════════════════════════════════════════════════════════════════════════
  233.  
  234. void MD_SampleUnLoad(WORD handle)
  235. =================================
  236.  
  237. Input parms:
  238.  
  239.     handle  the handle that identifies the sample to be unloaded.
  240.  
  241. Returns:
  242.  
  243.     -
  244.  
  245. Description:
  246.  
  247. Frees the sample which was previously loaded using MP_SampleLoad().
  248.  
  249. ════════════════════════════════════════════════════════════════════════════════
  250.  
  251. void MD_PlayStart(void)
  252. =======================
  253.  
  254. Input parms:
  255.  
  256.     -
  257.  
  258. Returns:
  259.  
  260.     -
  261.  
  262. Description:
  263.  
  264. Starts the mixing process of the soundcard (after calling this routine you 
  265. can use the MD_Voice* routines to make noise). Before calling this routine 
  266. you have to set the variable 'md_numchn' so it knows how many channels it has 
  267. to mix. This routine also installs a BPM interrupt which takes care of 
  268. updating the voice parameters every tick. The speed at which the interrupt 
  269. occurs can be controlled by adjusting the variable md_bpm, where a value of 
  270. 125 (default) will make the interrupt go at 50Hz, and 250 will make the 
  271. interrupt go at 100Hz.
  272.  
  273. ════════════════════════════════════════════════════════════════════════════════
  274.  
  275. void MD_PlayStop(void)
  276. ======================
  277.  
  278. Input parms:
  279.  
  280.     -
  281.  
  282. Returns:
  283.  
  284.     -
  285.  
  286. Description:
  287.  
  288. Stops soundcard output & stops the BPM interrupt.
  289.  
  290. ════════════════════════════════════════════════════════════════════════════════
  291.  
  292. void MD_RegisterTickHandler(void (*tickhandler)(void))
  293. ======================================================
  294.  
  295. Input parms:
  296.  
  297.     tickhandler     pointer to a routine that should be called every
  298.             bpm interrupt.
  299.  
  300. Returns:
  301.  
  302.     -
  303.  
  304. Description:
  305.  
  306. Installs a custom BPM handler which you could use to update a song. Take a 
  307. look at MIKMOD.C to see how this could be done.
  308.  
  309. ════════════════════════════════════════════════════════════════════════════════
  310.  
  311. void MD_VoiceSetVolume(UBYTE voice,UBYTE vol)
  312. =============================================
  313.  
  314. Input parms:
  315.  
  316.     voice   which voice to change the volume for.
  317.     vol     new volume setting for this voice (0-64)
  318.  
  319. Returns:
  320.  
  321.     -
  322.  
  323. Description:
  324.  
  325. Sets the volume of a single voice. Note that it doesn't change the volume 
  326. immediately but at the next BPM tick (this is true for all MD_Voice* 
  327. routines).
  328.  
  329. ════════════════════════════════════════════════════════════════════════════════
  330.  
  331. void MD_VoiceSetFrequency(UBYTE voice,ULONG frq)
  332. ================================================
  333.  
  334. Input parms:
  335.  
  336.     voice   which voice to change the frequency.
  337.     frq     new playback frequency this voice.
  338.  
  339. Returns:
  340.  
  341.     -
  342.  
  343. Description:
  344.  
  345. Sets the playback frequency of a single voice.
  346.  
  347. ════════════════════════════════════════════════════════════════════════════════
  348.  
  349. void MD_VoiceSetPanning(UBYTE voice,UBYTE pan)
  350. ==============================================
  351.  
  352. Input parms:
  353.  
  354.     voice   which voice to change the panning position.
  355.     pan     new panpos for this voice.
  356.  
  357. Returns:
  358.  
  359.     -
  360.  
  361. Description:
  362.  
  363. Changes the panning position (=balance) for this voice. 0 is all left, 255 is 
  364. all right.
  365.  
  366. ════════════════════════════════════════════════════════════════════════════════
  367.  
  368. void MD_VoicePlay(UBYTE voice,
  369.           WORD handle,
  370.           ULONG start,ULONG size,
  371.           ULONG reppos,ULONG repend,
  372.           UWORD flags)
  373. ============================================
  374.  
  375. Input parms:
  376.  
  377.     voice   which voice to start playing a new sample on
  378.     handle  the handle that identifies the sample
  379.     start   the starting offset (in samples!)
  380.     size    the size of the sample (in samples!)
  381.     reppos  repeat start position offset.
  382.     repend  repeat end position offset.
  383.     flags   identifies the type of sample, and if it has to loop.
  384.  
  385. Returns:
  386.  
  387.     -
  388.  
  389. Description:
  390.  
  391. Starts playing a new sample on the specified channel, using the requested 
  392. start,size and loop parameters (using the current volume, frequency and 
  393. panning parameters of a voice).
  394.  
  395. ════════════════════════════════════════════════════════════════════════════════
  396.