home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 591b.lha / OctaMED_v1.0b / Programmers / MODPlayer / modplayer.doc / modplayer.doc
Text File  |  1991-04-30  |  9KB  |  245 lines
  1. ****** Instructions for using "modplayer.a", the stand-alone playroutine
  2. ****** of MED V3.10/OctaMED V1.00
  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.     StopPlayer
  12.     SetTempo
  13.  
  14. (As you can see, some of the less important functions of V2.10 are removed.
  15. they are still available on medplayer.library.)
  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. StopPlayer -- stop playing
  50.  
  51. ARGUMENTS:    no arguments
  52.  
  53. RETURNS:    nothing
  54. --------------------------------------------------------------------------
  55. SetTempo -- set the playback tempo
  56.  
  57. ARGUMENTS:    d0 = new tempo (1 - 240)
  58.  
  59. RETURNS:    nothing
  60. --------------------------------------------------------------------------
  61.  
  62. "modplayer.a" is the source code of the music routine. It contains stuff
  63. that may be unnecessary for your purposes, that just takes time and memory.
  64. There are some "switches" at the beginning of the source, that allow you
  65. to turn off features you don't need. They are:
  66.  
  67. MIDI        If the song(s) use(s) only the Amiga audio channels, set
  68.         this to 0.
  69. AUDDEV        For some purposes, you may want to disable the code that
  70.         allocates the audio channels using "audio.device", e.g.
  71.         in a non-multitasking environment. Normally this should
  72.         be 1.
  73. SYNTH        If the song(s) doesn't use synth/hybrid sounds, then this
  74.         can be set to zero.
  75. CHECK        This does some checkings to ensure that several values are
  76.         correct (e.g. is the sample in memory, no Amiga effects on
  77.         MIDI-tracks etc..). If you know that the song is correct,
  78.         you can safely turn the checks off.
  79. RELVOL        If you don't need the "relative volume", this can be zero.
  80. IFF53        If the song doesn't contain IFF 3- or 5-octave samples,
  81.         this can be zero.
  82.  
  83. Timing
  84. ======
  85. If you need vertical blanking timing, you can set VBLANK to 1 and CIAB to 0.
  86. In normal use this is not recommended (because of the 16 % difference in
  87. playing speed with NTSC and PAL Amigas).
  88.  
  89. Assembling
  90. ==========
  91. Now you must assemble this file. The "modplayer.a" is directly compatible
  92. with A68k V2.61 (or later...) and HiSoft Devpac 2. Other assemblers may need
  93. some small work to assemble it correctly. The A68k V2.61 is available e.g.
  94. on Fred Fish disk 314.
  95.  
  96. The result is an object file. Link this file with your program (add the name
  97. of the .o-file to the .lnk-file)
  98.  
  99. Now you have the player, but there's still something missing...guess??...
  100. that's right: the music.
  101.  
  102. You have two ways to get the music:
  103. 1. Include the module in your final executable.
  104. 2. Save the module as a separate disk file and load it when needed
  105.    (this is probably the best way if you have more than one song).
  106.  
  107. First I cover the first method:
  108. --------------------------------------------------------------------------
  109. Including the module in your final executable:
  110.  
  111. There are two ways to do this:
  112. 1. Save the module as an object file which you can directly link with your
  113.    program.
  114. 2. In some assemblers it is possible to include binary files into the code.
  115.    There's a special source "easyplayer.a" for Devpac 2 (see below...)
  116.  
  117. Again I cover the first method first:
  118.  
  119. You must load MED and then load the song you want to include. Now select
  120. "Save song". You should see the save format requester. There are two
  121. gadgets which save object files: "Obj 1" and "Obj 2". Another problem,
  122. which one to select??
  123.  
  124. Well, the reason why there are two gadgets is that Lattice's Blink 5.04,
  125. which I use, handles the chip bits of the object files in a different way
  126. to the description in AmigaDOS manual.
  127. While the the "AmigaDOS-manual" way would be
  128.         000003EA    40001234,
  129.         hunk_data   |   hunk size
  130.                    chip
  131.  
  132. Blink uses a format like this:
  133.         400003EA    00001234
  134.         | hunk_data     hunk size
  135.      chip
  136.  
  137. The "Obj 1" gadget saves the file in Blink format, "Obj 2" saves it in
  138. the "AmigaDOS manual-format".
  139.  
  140. I suggest that you first try "Obj 1". If you get an error message when
  141. linking, then select "Obj 2".
  142.  
  143. Now you know how to save the object file. The object file has exactly
  144. one symbol defined: the module (struct MMD0). The name of the symbol
  145. depends on the file name (so you can have more than one song). If the
  146. file name you entered was "song", the object file would be "song.o" and
  147. the module would be defined as "_song" (in C just plain "song").
  148.  
  149. In C, you would define it this way:
  150.  
  151.     extern struct MMD0 far song; /* remember to include "modplayer.h" */
  152.  
  153. and to start playing, you'd call (assuming you've already called InitPlayer):
  154.  
  155.     PlayModule(&song);
  156.  
  157. With assembler, it would look like this:
  158.  
  159.     xref    _PlayModule
  160.     xref    _song
  161.     ....
  162.     lea    _song,a0
  163.     jsr    _PlayModule(pc)
  164.  
  165. Then the another way...
  166.  
  167. When you have included the module (not an object file!!) as a binary
  168. module, it must be relocated before it can be used. The easiest way to
  169. do this is to use _RelocModule, which is in "loadmod.a". After it's
  170. relocated, send the pointer of the module to PlayModule (NOTE: Remember
  171. to xdef the _RelocModule-function or strip the function from loadmod.a).
  172. By the way, never relocate the same module twice. It is 100 % guaranteed
  173. that it won't work then.
  174.  
  175. And the second method (loading modules from disk):
  176. --------------------------------------------------------------------------
  177. File "loadmod.a" contains three routines:
  178.     LoadModule
  179.     UnLoadModule
  180.     RelocModule (see above)
  181.  
  182. You need only the first two of them. RelocModule is used by LoadModule.
  183.  
  184. --------------------------------------------------------------------------
  185. LoadModule -- load module from disk
  186.  
  187. Loads and relocates module.
  188.  
  189. ARGUMENTS:    a0 = pointer to the file name
  190.  
  191. RETURNS:    d0 = pointer to the module, if something failed: 0
  192. --------------------------------------------------------------------------
  193. UnLoadModule -- free the module from memory
  194.  
  195. Frees the module. Remember to StopPlayer() before you unload the module
  196. that is currently playing. Also remember to free all modules you've loaded
  197. before you exit the program.
  198.  
  199. ARGUMENTS:    a0 = pointer to the module (may be 0)
  200.  
  201. RETURNS:    nothing, nothing and nothing
  202. --------------------------------------------------------------------------
  203.  
  204. Just call LoadModule to load the module and send the returned pointer to
  205. PlayModule. Easy??
  206.  
  207. ==========================================================================
  208.  
  209. REMEMBER:    All functions expect the arguments in registers. This is
  210.         automatically (??) handled by you when you program in
  211.         assembler, but it is not automatically handled when you
  212.         program in C.
  213.  
  214. If you have Lattice/SAS C V5.xx, this is done automatically if you include
  215. "modplayer.h" in all your code modules which call modplayer. If you
  216. have a compiler which doesn't support argument passing in registers,
  217. then you have to write the stub routines in assembler.
  218.  
  219. That was it. See also the small example sources.
  220.  
  221. ==========================================================================
  222.     easyplayer.a -- easy-to-use player for demos etc.
  223.  
  224. This is a player designed for playing a single song. It works on Devpac 2
  225. (not on A68k, because it doesn't have INCBIN-command). To use it, insert
  226. it into your code (or assemble separately and link). The name of the module
  227. must be written into the INCBIN-statement. At the beginning of the program,
  228. call _startmusic, when you're ready to finish, call _endmusic. That's all.
  229.  
  230. ==========================================================================
  231. ==========================================================================
  232.     mod8player.a -- the playroutine for 8-channel OctaMED songs
  233. ==========================================================================
  234. ==========================================================================
  235.  
  236. This is the player for 8-channel songs (ONLY for 8-channel songs). Using
  237. it is similar to using modplayer.a. The functions have a bit different
  238. names:
  239.     InitPlayer8
  240.     RemPlayer8
  241.     PlayModule8
  242.     StopPlayer8
  243.  
  244. The modules can be obtained exactly in the same way as above.
  245.