home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 15 / CD_ASCQ_15_070894.iso / vrac / mikmod43.zip / README.DOC < prev    next >
Text File  |  1994-04-30  |  17KB  |  654 lines
  1. MIKMOD v0.43
  2. ============
  3.  
  4.  
  5. Or how to make a modplayer using the GUS v2.10 LowLevel Toolkit and BC 3.1
  6. Programmed by MikMak of Unicorn Design a.k.a. Jean-Paul Mikkers.
  7.  
  8. This is SOURCEWARE/PUBLIC DOMAIN so you may use my routines as long as you
  9. mention my name :)
  10.  
  11.  
  12.  
  13. Contents:
  14.  
  15.       Chapter 1         -     Introduction
  16.  
  17.       Chapter 2         -     "Your interface.. I hate it, I HATE IT!"
  18.  
  19.       Chapter 3         -     How to compile MIKMOD
  20.  
  21.       Chapter 4         -     MODLOAD.C functions
  22.  
  23.       Chapter 5         -     MODPLAY.C functions
  24.  
  25.       Chapter 6         -     How to use
  26.  
  27.       Chapter 7         -     History
  28.  
  29.       Chapter 8         -     Future
  30.  
  31.       Chapter 9         -     Greetings
  32.  
  33.       Chapter 10        -     How to contact me
  34.  
  35.       Chapter 11        -     Legal stuff
  36.  
  37.  
  38.  
  39.  
  40. =======================
  41. Chapter 1: Introduction
  42. =======================
  43.  
  44.  
  45.  
  46. What it does:
  47. -------------
  48.  
  49. Pretty obvious. It loads a module (protracker,startracker,fasttracker 4-8
  50. channels) and plays it through your GUS.
  51.  
  52.  
  53.  
  54. What's so good about it ?
  55. -------------------------
  56.  
  57. Errrm.. It uses the GUS SDK toolkit.. and err.. well.. the sourcecode is
  58. included. (In 'C' ofcourse). Anditsawholelottapublicdomain.
  59.  
  60. The program is divided into three main parts: The module loader, the module
  61. player and the GUS interface. The module loader and player are soundcard
  62. independent so they could be used for other soundcards than GUS. (Actually 
  63. they were until I got my GUS)
  64.  
  65. This version is sort of a in between release.. I'm still working on version
  66. 0.50 but I don't have a lot of time ( I'm graduating, you know ). So this
  67. is _not_ a major update.. I only fixed some bugs and added a few features.
  68.  
  69.  
  70. Version 0.50 will have the following features added:
  71.  
  72.  
  73.       - Soundblaster, covox and speaker support + full sources <sic>
  74.  
  75.       - Improved gus routines
  76.  
  77.       - MTM loader
  78.  
  79.  
  80. If you have written a program that uses mikmod or that is based upon
  81. mikmod, I would like to receive a copy of it (if it's not too much trou-
  82. ble). Just send your program uuencoded to my email address (You don't have
  83. to send me your sources if you don't want to).
  84.  
  85. See chapter 10 for my E-mail and snail-mail address.
  86.  
  87.  
  88. ===================================================
  89. Chapter 2: "Your interface.. I hate it, I HATE IT!"
  90. ===================================================
  91.  
  92. "That's not my job.. my job is eating this donut.." (Ice-T, Copkiller)
  93.  
  94. This chapter is meant for anyone who uses MikMod and thinks that it has a
  95. crappy user-interface.. well.. I agree, but I never meant to make a full-
  96. scale, all-formats-supporting modplayer with graphical analysers, VU-bars,
  97. shelling capabilities and lots of other neato stuff. That's something _you_
  98. have to make. ( Or check out Extended MikMod (XMM) by Rao a.k.a. Paul
  99. Fisher)
  100.  
  101. But to make life just a bit easier I included some nice routines for scan-
  102. ning the commandline and wildcard filename handling. (Heh.. I'm a nice guy
  103. :)
  104.  
  105.  
  106.  
  107.  
  108. ================================
  109. Chapter 3: How to compile MIKMOD
  110. ================================
  111.  
  112.  
  113.  
  114. Using borlandc 3.1 IDE:
  115. -----------------------
  116.  
  117.    -  Get the GUS SDK v2.10
  118.  
  119.    -  Start the borlandc IDE and open the project file MIKMOD.PRJ
  120.  
  121.    -  Change the library directory c:\gusdk210\libs to point to your
  122.       corresponding gusdk210 libs directory (Menu Options-Directories).
  123.  
  124.    -  Change the include directory c:\gusdk210\incs to point to your 
  125.       corresponding gusdk210 incs directory (Menu Options-Directories).
  126.  
  127.    -  Then make or run it.
  128.  
  129.  
  130.  
  131.  
  132. Using MAKE:
  133. -----------
  134.  
  135.    -  Get the GUS SDK v2.10
  136.  
  137.    -  Edit LIBPATH and INCLUDEPATH in the file MIKMOD.MAK to point to your
  138.       corresponding directories.
  139.  
  140.    -  Execute MAKE -fMIKMOD.MAK
  141.  
  142.  
  143.  
  144.  
  145. ==============================
  146. Chapter 4: MODLOAD.C functions
  147. ==============================
  148.  
  149.  
  150. void ML_Load15(int yesno)
  151. -------------------------
  152.  
  153. With this function you can enable (yesno=1) or disable (yesno=0) the
  154. loading of 15-instrument modules. It's disabled by default, because there's
  155. no way to accurately detect that a file is a 15-instrument module.
  156.  
  157. returns:    nothing
  158.  
  159.  
  160.  
  161. MODFILE *ML_Open(char filename[],FILE *fp)
  162. ------------------------------------------
  163.  
  164. Opens a module and initializes a MODFILE structure that contains all infor-
  165. mation. A module can be opened by filename or by filepointer ( If you
  166. supply a filepointer, it's up to you to close the file when the module has
  167. been read ). Note that when this routine returns, only the module header
  168. has been read, the patterns and samples are not yet loaded (use ML_Load).
  169. Take a look at MODLOAD.H for more info about the MODFILE structure.
  170.  
  171.  
  172. returns:    MODFILE *       Pointer to an initialized MODFILE structure
  173.             or
  174.             NULL            When an error occurred
  175.  
  176.  
  177.  
  178.  
  179. int ML_Load(MODFILE *mf)
  180. ------------------------
  181.  
  182. Loads the patterns and samples of a module using the user-supplied call-
  183. backroutines. After this function returns it's safe for you to close the
  184. fileptr to the module, or in case you supplied a filename to ML_Open it
  185. will be closed for you.
  186.  
  187.  
  188. returns:    0     on error
  189.             or
  190.             1     everything okay
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197. void ML_Free(MODFILE *mf)
  198. -------------------------
  199.  
  200. Use this routine to free memory used by the module. Only use this routine
  201. when ML_Open succeeded.
  202.  
  203.  
  204. returns:    nothing.
  205.  
  206.  
  207.  
  208.  
  209.  
  210.  
  211. void ML_RegisterLoader(int (*Loader)(FILE *fp,SAMPLEINFO *smp))
  212. ---------------------------------------------------------------
  213.  
  214. Registers the callback routine for loading a module-sample. The callback
  215. routine has to load smp->length bytes from the file 'fp'. It then has to
  216. return a unique handle number that identifies the sample that was loaded.
  217. In case of an error (for example out of memory error) it has to return -1.
  218.  
  219. The loader routine has to be registered BEFORE you try to ML_Load() a
  220. module.
  221.  
  222.  
  223. returns:    nothing.
  224.  
  225.  
  226.  
  227.  
  228.  
  229. void ML_RegisterUnLoader(void (*UnLoader)(int handle,SAMPLEINFO *smp))
  230. ----------------------------------------------------------------------
  231.  
  232. Registers the callback routine for unloading a module-sample. The call-
  233. back routine has to free the memory taken up by the sample that is identi-
  234. fied by 'handle'.
  235.  
  236. The unloader routine has to be registered BEFORE you try to ML_Free() a
  237. module.
  238.  
  239.  
  240. returns:    nothing.
  241.  
  242.  
  243.  
  244.  
  245. const char *ML_Error(void)
  246. --------------------------
  247.  
  248. Returns a string that explains what error occurred. Use it to explain what
  249. went wrong.
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256. ============================
  257. Chapter 5: MODPLAY functions
  258. ============================
  259.  
  260.  
  261. void MP_NextPosition(void)
  262. --------------------------
  263.  
  264. Skips to next song position. Note that the result may not be completely
  265. correct if the module contains patternbreaks.
  266.  
  267. returns:    nothing.
  268.  
  269.  
  270.  
  271. void MP_PrevPosition(void)
  272. --------------------------
  273.  
  274. Jumps to the previous song position.
  275.  
  276. returns:    nothing.
  277.  
  278.  
  279.  
  280. void MP_MainVol(UBYTE volume)
  281. -----------------------------
  282.  
  283. Sets mainvolume to a value between 0-100%. Your player routine has acces to
  284. the main volume via the global variable 'mp_mainvol'. Remember that _your_
  285. player routine has to take care of combining this value with the voices
  286. volumes to compute the resulting volume settings for each channel.
  287.  
  288. returns:    nothing
  289.  
  290.  
  291. void MP_ExtSpd(int yesno)
  292. -------------------------
  293.  
  294. Use this function to enable (yesno=1) or disable (yesno=0) protracker
  295. extended speed. Extended speed is enabled by default.
  296.  
  297. return:     nothing
  298.  
  299.  
  300.  
  301. void MP_RegisterPlayer(void (*Player)(int voice,AUDTMP *aud,MODFILE *mf))
  302. -------------------------------------------------------------------------
  303.  
  304. Registers the callback routine for playing the samples when a module is
  305. being played. Take a look at MIKMOD.C to see how one could implement this
  306. routine (GusPlay()).
  307.  
  308. The player routine has to be registered BEFORE you try to call MP_Handle-
  309. Tick().
  310.  
  311.  
  312. returns:    nothing
  313.  
  314.  
  315.  
  316.  
  317. void MP_Init(MODFILE *m)
  318. ------------------------
  319.  
  320. Initializes the MODPLAY routines to start playing this modfile the next
  321. time MP_HandleTick() is called. This routine has to be called BEFORE you
  322. try to call MP_HandleTick().
  323.  
  324.  
  325. returns:    nothing
  326.  
  327.  
  328.  
  329.  
  330. void MP_HandleTick(void)
  331. ------------------------
  332.  
  333. This routine has to be called 50 (or (bpm*50)/125 ) times a second to play
  334. a module. Every time this routine has been called, it will in turn call the
  335. user supplied player routine to do the actual playing of the samples (See
  336. MP_RegisterPlayer()).
  337.  
  338. returns:    nothing
  339.  
  340.  
  341.  
  342.  
  343.  
  344. =========================================
  345. Chapter 6: How to use (for ANY soundcard)
  346. =========================================
  347.  
  348.  
  349.   1.  Initialize soundcard hardware, dma, interrupts etc. (this is the hard
  350.       part)
  351.  
  352.   2.  Register your sample load and unload routines using ML_RegisterLoa-
  353.       der() and ML_RegisterUnLoader()
  354.  
  355.   3.  Register your sample play routine using MP_RegisterPlayer()
  356.  
  357.   4.  Open the modfile using ML_Open()
  358.  
  359.   5.  If nothing went wrong, load the patterns and samples using ML_Load()
  360.       (Between step 4 and 5 you could display the module name or sample na-
  361.       mes... display some info)
  362.  
  363.   6.  Call MP_Init() to tell the player to play the module the next time
  364.       you call MP_HandleTick()
  365.  
  366.   7.  Call MP_HandleTick() 50 times a second.. or set up an interrupt to do
  367.       this for you... and presto.. MUSIC!
  368.  
  369.   8.  Stop calling MP_HandleTick() and disable soundcard output.
  370.  
  371.   9.  Call ML_Free() to free memory
  372.  
  373.  10.  Goto 4 (music forever ;)
  374.  
  375.  
  376.  
  377.  
  378.  
  379. ==================
  380. Chapter 7: History
  381. ==================
  382.  
  383.  
  384. Version 0.43:
  385. -------------
  386.  
  387.    -  Fixed a bug that caused the first sample not to be unloaded
  388.  
  389.    -  Added a check to see if the loop end point exceeds the sample size
  390.       (some modfiles seem to have this problem)
  391.  
  392.    -  Added wildcard filename matching to the modplayer
  393.  
  394.    -  Added the M!K! module id.
  395.  
  396.    -  Removed the check for the number of bytes loaded from a sample,
  397.       because a lot of modules don't have the last sample complete, so mik-
  398.       mod would refuse to play them.
  399.  
  400.    -  Changed the loader so it can load 15-instrument modules
  401.  
  402.    -  Extended protracker speeds can be disabled
  403.  
  404.    -  Improved commandline parsing
  405.  
  406.    -  Added master volume
  407.  
  408.    -  Added functions to skip to the next or previous song position
  409.  
  410. Version 0.42:
  411. -------------
  412.  
  413.    -  Removed more ultraclicks by adding volumeramping when stopping a
  414.       voice. Actually this idea was suggested to me by Forte Tech Support..
  415.       thanks!
  416.  
  417.    -  When an arpeggio effect stopped, the period would 'hang' at the last
  418.       arpeggio note, while it should return to the 'base' period.. To fix
  419.       this problem I changed the arpeggio code to not affect tmpperiod but
  420.       period itself. (This bug was kinda hard to find because it's an
  421.       outdated effect)
  422.  
  423.    -  Have to limit patbrk values to max. 64.
  424.  
  425.    -  Rearranged the GusPlay() callback routine to use a more sensible
  426.       order of setting the frequency and volume of a voice.
  427.  
  428.  
  429. Version 0.41:
  430. -------------
  431.  
  432.    -  When comparing to my amiga, I noticed that some effects on mikmod
  433.       were too fast. I discovered that effects like toneslide, vibrato,
  434.       volumeslide etc aren't updated the first tick of a row. FIXED.
  435.  
  436.    -  Have to reset wantedperiod for each note..
  437.  
  438.  
  439. Version 0.4:
  440. ------------
  441.  
  442.    -  Totally rewritten the modload routines.. Created a type 'MODFILE'
  443.       that holds all info of a modfile, so now you can load more than one
  444.       module.
  445.  
  446.    -  New docs.
  447.  
  448.    -  Using handle-numbers instead of sample numbers to load samples..
  449.       (neccessary when loading more than one module at a time )
  450.  
  451.    -  Have to limit volume range for effect C
  452.  
  453.    -  Fixed effect '3' (toneslide) (this caused wierd slides on modules
  454.       like scramble.mod)
  455.  
  456.    -  Switched to a 3-byte-per-note format when converting patterns.. same
  457.       format that GUSMOD uses.
  458.  
  459.    -  When a patternbreak has just occurred, all patternbreak command's
  460.       have to be ignored for the next row. ( This bug made mikmod skip a
  461.       pattern in the module 'condom-corruption' )
  462.  
  463.  
  464.  
  465. Version 0.3: (unreleased)
  466. ------------
  467.  
  468.    -  Added 2 octaves to period tables.
  469.  
  470.    -  Removed ASM bits from MODLOAD.C
  471.  
  472.    -  Implemented the remaining effect commands. (Phew!)
  473.  
  474.    -  The sample start bug of the SDK 2.01 has been removed in the 2.10
  475.       SDK. So now this program can be compiled without modifying the SDK
  476.       itself.
  477.  
  478.    -  The pattern break effect data is in BCD !. This screwed up modules
  479.       like garbage_collection (by Peter Salomonson).
  480.  
  481.  
  482.  
  483. Version 0.2:
  484. ------------
  485.  
  486. MODLOAD.C:
  487.  
  488.    -  I have to check ALL song positions (128 positions ) for patterns...
  489.       This bug caused edited modules to load incorrectly. FIXED.
  490.  
  491.  
  492. MODPLAY.C:
  493.  
  494.    -  The old version didn't allow sample loops smaller than 64 bytes. (
  495.       that was a leftover from my soundblaster player.. ) FIXED.
  496.  
  497.  
  498. MIKMOD.C:
  499.  
  500.    -  UltraClicks removed (most of them). Ultraclicks are caused by the
  501.       fact that a GUS plays beyond the last byte of a sample. (actually, it 
  502.       interpolates between the last byte of a sample and the next byte that
  503.       doesn't belong to that sample). I fixed this by allocating one more
  504.       byte when loading a sample and zeroing that extra byte.
  505.  
  506.    -  Added fast volume ramping when starting a sample...
  507.  
  508.    -  #@$%@^$!!#$@! Fixed the extended speed.. I really should be more
  509.       careful.
  510.  
  511.  
  512.  
  513. Version 0.1
  514. -----------
  515.  
  516. First public release.
  517.  
  518.  
  519.  
  520.  
  521.  
  522. ==================
  523. Chapter 8:  Future
  524. ==================
  525.  
  526.    -  Using expanded memory for storing patterns
  527.  
  528.    -  Some kind of collection of separate drivers that can be used for the
  529.       soundcard you need. The drivers should be dynamically loadable, but
  530.       I'm still trying to find a way how to write those in 'C'.. in assem-
  531.       bly it's much easier. These kind of drivers would allow programmers
  532.       to add soundsupport for _any_ soundcard. If anyone has got any ideas
  533.       on implementing those drivers in 'C' , please mail.
  534.  
  535.    -  669, STM, P16 support ?
  536.  
  537.    -  Maybe a C++ implementation of these routines.
  538.  
  539.    -  A pascal version of mikmod.. naah.. just kidding :)
  540.  
  541.    -  Any function you want me to add.
  542.  
  543.  
  544.  
  545.  
  546. =====================
  547. Chapter 9:  Greetings
  548. =====================
  549.  
  550.  
  551. Thanks to:
  552.  
  553. Bzarre, Sinox, Big Ed, Pernel (for the drams), Master of Disaster, Plim,
  554. The Joker, Cat, Outbit, Skyhigh, MaNaR, Forte Tech Support (Mike), Jean-
  555. Stephane Perri, Irmin Ziegelmeier, Mark Connor, Patrik Wallstr|m, Stuart
  556. Carnie, Prime a.k.a Stefan Danes, Hyperion, everybody at Stack, Paul v.d.
  557. Ven, JVeck, Rao, Mike Tedder, Saari Anssi, Alexander Kerkhove, Jaap van
  558. Hengstum, Martin Flack, Dick Verweij (C00L Demo Dude!), Tomi Suominen,
  559. Craig Peeper, Mikko Rauhala, Gavin Scarman, The Frenchman, Wildcat, Robert
  560. Sanders, Ronny Hanssen
  561.  
  562. Thanks for your support and bugreports!
  563.  
  564.  
  565. =============================
  566. Chapter 10: How to contact me
  567. =============================
  568.  
  569.  
  570. I can be reached at:
  571.  
  572.  
  573. E-mail:
  574.  
  575. *****************************
  576. *                           *
  577. *  mikmak@stack.urc.tue.nl  *
  578. *                           *
  579. *****************************
  580.  
  581.  
  582. Snail-mail:
  583.  
  584. *****************************
  585. *                           *
  586. *     Jean-Paul Mikkers     *
  587. *     Godartstraat 16       *
  588. *     5932 AX               *
  589. *     Tegelen               *
  590. *     The Netherlands       *
  591. *                           *
  592. *****************************
  593.  
  594.  
  595.  
  596. Some reasons why you might want to contact me:
  597.  
  598.  
  599.    -  You have a programming job you want me to work on.
  600.  
  601.    -  You found a bug.
  602.  
  603.    -  You want soundblaster support.
  604.  
  605.    -  To let me know if MikMod compiles on your compiler.. (BC 4.0, Watcom,
  606.       Microsoft-C)
  607.  
  608.    -  To send me your fabulous programs.
  609.  
  610.    -  To request a new function for the next version of MikMod.
  611.  
  612.    -  To give me some percentage of the multi-million dollar profit you got
  613.       out of MikMod.
  614.  
  615.    -  To wish me merry x-mas.
  616.  
  617.    -  You want to donate your complete collection of Star Trek - the next
  618.       generation or Star Trek - Deep Space 9 videos.
  619.  
  620.    -  You're Cindy Crawford..
  621.  
  622.    -  To startup another PD project for the ultrasound (Midi ? - Patches ?)
  623.  
  624.    -  To flame.. no wait.. just send those to /dev/nul okay?
  625.  
  626. etcetera
  627.  
  628.  
  629.  
  630.  
  631. ========================
  632. Chapter 11:  LEGAL STUFF
  633. ========================
  634.  
  635.  
  636. This software is PUBLIC DOMAIN.
  637.  
  638. Disclaimer:
  639.  
  640. The author (that's me) specifically disclaims all warranties, expressed or
  641. implied, including but not limited to implied warranties of merchantability
  642. and fitness for a particular purpose with respect to defects in the
  643. software and documentation.
  644.  
  645. In no event shall the author be liable for any loss of profit or damage,
  646. including but not limited to special, incidental, or consequential damages.
  647.  
  648. The GUS Lowlevel toolkit v2.10 is copyright (C) 1992,1993 by FORTE and
  649. advanced GRAVIS.
  650.  
  651. All product names, trademarks and registered trademarks contained in this
  652. document are the property of their respective holders.
  653.  
  654.