home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / fish / audio / utils / med_424 / programmers / modplayer / modplayer.doc < prev    next >
Text File  |  1990-12-30  |  8KB  |  231 lines
  1. ****** Instructions for using "modplayer", the stand-alone playroutine
  2. ****** of MED V2.10
  3.  
  4. "modplayer" is a piece of code (about 3 - 5 KBytes, depending on your needs)
  5. which is linked with your program and plays modules made with MED.
  6.  
  7. "modplayer" contains the following routines:
  8.     InitPlayer
  9.     RemPlayer
  10.     PlayModule
  11.     ContModule
  12.     StopPlayer
  13.     DimOffPlayer (optional)
  14.     SetTempo
  15.     ResetMIDI (optional, too)
  16.  
  17. The arguments are passed in registers, and return values are returned in d0.
  18.  
  19. And now the descriptions of each one:
  20. --------------------------------------------------------------------------
  21. InitPlayer -- initialize everything
  22.  
  23. Before you can call the other functions, you must call this function.
  24. It allocates the audio channels, timer, serial port (if MIDI) etc...
  25.  
  26. ARGUMENTS:    none
  27.  
  28. RETURNS:        0 if everything is ok, otherwise something failed.
  29.         If something failed, you can still call the other
  30.         routines - they just don't do anything.
  31. --------------------------------------------------------------------------
  32. RemPlayer -- return everything back
  33.  
  34. Call this when your program exits. It frees the audio channels etc. etc.
  35.  
  36. ARGUMENTS:    none
  37.  
  38. RETURNS:        nothing
  39. --------------------------------------------------------------------------
  40. PlayModule -- start playing a module
  41.  
  42. When you want to start playing call this.
  43.  
  44. ARGUMENTS:    a0 = pointer to the module. Where to get that pointer?
  45.         Don't panic, it's explained later....
  46.  
  47. RETURNS:        nothing
  48. --------------------------------------------------------------------------
  49. ContModule -- continue playing after stop from the point it was stopped
  50.  
  51. As is.
  52.  
  53. ARGUMENTS:    a0 = ptr to the module
  54.  
  55. RETURNS:        exactly nothing
  56. --------------------------------------------------------------------------
  57. StopPlayer -- stop playing
  58.  
  59. ARGUMENTS:    no arguments
  60.  
  61. RETURNS:        nothing
  62. --------------------------------------------------------------------------
  63. DimOffPlayer -- fade out and stop player
  64.  
  65. Returns immediately and starts fading the sound.
  66.  
  67. ARGUMENTS:    d0 = how many lines do you want the fade to take??
  68.  
  69. RETURNS:        nothing
  70. --------------------------------------------------------------------------
  71. SetTempo -- set the playback tempo
  72.  
  73. ARGUMENTS:    d0 = new tempo (1 - 240)
  74.  
  75. RETURNS:        nothing
  76. --------------------------------------------------------------------------
  77. ResetMIDI -- reset pitchbenders/modulation wheels/presets
  78.  
  79. ARGUMENTS:    nothing
  80.  
  81. RETURNS:        nothing
  82. --------------------------------------------------------------------------
  83.  
  84. "modplayer.a" is the source code of the music routine. It contains all
  85. theses routines. You may have noticed that you may not need all these
  86. routines. At the beginning of the source are two "switches":
  87.  
  88. DIM    EQU    1
  89. MIDI    EQU    1
  90.  
  91. If you don't need DimOffPlayer, the first line should read:
  92.  
  93. DIM    EQU    0
  94.  
  95. If you don't need MIDI output, the second line should be:
  96.  
  97. MIDI    EQU    0
  98.  
  99. With these switches you can make the player shorter, a bit faster and
  100. avoid allocating resources that are not needed (like serial port).
  101.  
  102. Now you must assemble this file. It works well with A68k-assembler,
  103. which is MetaComco-compatible, so any MetaComco-compatible should work.
  104. If you don't have A68k, you can get it from Fish #186, at least (although
  105. there are probably newer version(s) available now). It shouldn't be too
  106. difficult to convert it to non-MetaComco-assemblers too.
  107.  
  108. The result is an object file. Link this file with your program.
  109.  
  110. Now you have the player, but there's still something missing...guess??...
  111. that's right: the music.
  112.  
  113. You have two ways to get the music:
  114. 1. Include the module in your final executable.
  115. 2. Save the module as a separate disk file and load it when needed
  116.    (this is probably the best way if you have more than one song).
  117.  
  118. First I cover the first method:
  119. --------------------------------------------------------------------------
  120. Including the module in your final executable:
  121.  
  122. There are two ways to do this:
  123. 1. Save the module as an object file which you can directly link with your
  124.    program.
  125. 2. In some assemblers it is possible to include binary files into the code.
  126.    While I have not tried it (I haven't got such an assembler, maybe I
  127.    should buy), it should work.
  128.  
  129. Again I cover the first method first:
  130.  
  131. You must load MED V2.10 and load the song you want to include. Now select
  132. "Save song". You should see the save format requester. There are two
  133. gadgets which save object files: "Obj 1" and "Obj 2". Another problem,
  134. which one to select??
  135.  
  136. Well, the reason why there are two gadgets is that Lattice's Blink 5.04,
  137. which I use, handles the chip bits of the object files in a nonstandard
  138. way. While the the standard way would be
  139.         000003EA    40001234,
  140.         hunk_data   |   hunk size
  141.                    chip
  142.  
  143. Lattice uses a format like this:
  144.         400003EA    00001234
  145.         | hunk_data     hunk size
  146.      chip
  147.  
  148. The "Obj 1" gadget saves the file in Blink format, "Obj 2" saves it in
  149. the standard format (described in AmigaDOS manual).
  150.  
  151. I suggest that you first try "Obj 1". If you get an error message when
  152. linking, then select "Obj 2".
  153.  
  154. Now you know how to save the object file. The object file has exactly
  155. one symbol defined: the module (struct MMD0). The name of the symbol
  156. depends on the file name (so you can have more than one song). If the
  157. file name you entered was "song", the object file would be "song.o" and
  158. the module would be defined as "_song" (in C just plain "song").
  159.  
  160. In C, you would define it this way:
  161.  
  162.     extern struct MMD0 far song; /* remember to include "med.h" */
  163.  
  164. and to start playing, you'd call:
  165.  
  166.     PlayModule(&song);
  167.  
  168. With assembler, it would look like this:
  169.  
  170.     xref    _PlayModule
  171.     xref    _song
  172.     ....
  173.     lea    _song,a0
  174.     jsr    _PlayModule(pc)
  175.  
  176. Then the another way...
  177.  
  178. When you have included the module (not an object file!!) as a binary
  179. module, it must be relocated before it can be used. The easiest way to
  180. do this is to use _RelocModule, which is in "loadmod.a". After it's
  181. relocated, send the pointer of the module to PlayModule (NOTE: Remember
  182. to xdef the _RelocModule-function or strip the function).
  183. By the way, never relocate the same module twice. It is 100 % guaranteed
  184. that it won't work then.
  185.  
  186. And the second method:
  187. --------------------------------------------------------------------------
  188. File "loadmod.a" contains three routines:
  189.     LoadModule
  190.     UnLoadModule
  191.     RelocModule (see above)
  192.  
  193. You need only the first two of them. RelocModule is used by LoadModule.
  194.  
  195. --------------------------------------------------------------------------
  196. LoadModule -- load module from disk
  197.  
  198. Loads and relocates module.
  199.  
  200. ARGUMENTS:    a0 = pointer to the file name
  201.  
  202. RETURNS:        d0 = pointer to the module, if something failed: 0
  203. --------------------------------------------------------------------------
  204. UnLoadModule -- free the module from memory
  205.  
  206. Frees the module. Remember to StopPlayer() before you unload the module
  207. that is currently playing. Also remember to free all modules you've loaded
  208. before you exit the program.
  209.  
  210. ARGUMENTS:    a0 = pointer to the module
  211.  
  212. RETURNS:        nothing, nothing and nothing
  213. --------------------------------------------------------------------------
  214.  
  215. Just call LoadModule to load the module and send the returned pointer to
  216. PlayModule. Easy??
  217.  
  218. ==========================================================================
  219.  
  220. REMEMBER:    All functions expect the arguments in registers. This is
  221.         automatically (??) handled by you when you program in
  222.         assembler, but it is not automatically handled when you
  223.         program in C.
  224.  
  225. If you have Lattice C V5.04, this is done automatically if you include
  226. "modplayer.h" in all your code modules which call modplayer. If you
  227. have a compiler which doesn't support argument passing in registers,
  228. then you have to write the stub routines in assembler.
  229.  
  230. That was it. See also the small example sources.
  231.