home *** CD-ROM | disk | FTP | other *** search
/ Merciful 3 / Merciful_Release_3.bin / software / o / octamed / octamedv6.12.lha / programmers / proplayer.doc < prev    next >
Text File  |  1995-03-27  |  11KB  |  313 lines
  1. INTRODUCTION TO OCTAMED PLAYER ROUTINES
  2. =======================================
  3.  
  4. This drawer contains the material, which is required for using OctaMED
  5. music in your own programs. You are allowed to freely use these routines in
  6. your own non-commercial programs. For commercial products, you will have to
  7. licence the routines. (See the files ReadMe.doc and Licence.doc for the
  8. details.)
  9.  
  10. You have basically two choices - you can either incorporate the player
  11. routine (written in assembler) to your program, or you can use the provided
  12. external player libraries.
  13.  
  14. 1. Embedded player routines (proplayer/pro8player)
  15.  
  16. These are the most often used routines. They are usually the best choice
  17. for embedded game music, module player programs etc. Easy switches are
  18. provided for turning off unnecessary features. As the assembler source is
  19. provided, you can modify the code or add hooks to suit your specific
  20. purpose. The rest of this document contains instructions for the proplayer
  21. routines.
  22.  
  23. 2. Player libraries (medplayer.library/octaplayer.library)
  24.  
  25. These are shared libraries that any application program may call. (Only one
  26. task can be using them at a time, though.) The libraries contain basically
  27. the same functionality as proplayer routines, but no tailoring can be made.
  28. An obvious advantage is that library upgrades are transparent to your
  29. application. The user can simply replace the libraries. See the file
  30. Library.doc for details on using the libraries.
  31.  
  32. Note: medplayer.library and octaplayer.library are located in the LIBS
  33. drawer of OctaMED_Disk_2.
  34.  
  35. Note: If you need a feature that currently does not exist, send us your
  36. exact requirements, and we'll do our best to help you.
  37.  
  38.     Instructions for using "proplayer.a", the stand-alone playroutine.
  39. ===========================================================================
  40.  
  41. "proplayer" is a piece of code which is linked with your program and plays
  42. MED and OctaMED modules.
  43.  
  44. "proplayer" contains the following routines:
  45.     InitPlayer
  46.     RemPlayer
  47.     PlayModule
  48.     ContModule
  49.     StopPlayer
  50.     SetTempo
  51.  
  52. The arguments are passed in registers, and return values are returned in d0.
  53. These routines will trash registers d0-d1 and a0-a1.
  54.  
  55. And now the descriptions of each one:
  56. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  57. InitPlayer -- initialize everything
  58.  
  59. Before you can call the other functions, you must call this function.
  60. It allocates the audio channels, timer, serial port (if MIDI) etc...
  61.  
  62. ARGUMENTS:    none
  63.  
  64. RETURNS:    0 if everything is ok, otherwise something failed.
  65.         If something failed, you can still call the other
  66.         routines - they just don't do anything.
  67.  
  68. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  69. RemPlayer -- return everything back
  70.  
  71. Call this when your program exits. It frees the audio channels, timer,
  72. serial port etc.
  73.  
  74. ARGUMENTS:    none
  75.  
  76. RETURNS:    nothing
  77.  
  78. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  79. PlayModule -- start playing a module
  80.  
  81. When you want to start playing, call this routine.
  82.  
  83. ARGUMENTS:    a0 = pointer to the module. See below for instructions
  84.         how to obtain the pointer.
  85.  
  86. RETURNS:    nothing
  87.  
  88. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  89. StopPlayer -- stop playing
  90.  
  91. ARGUMENTS:    no arguments
  92.  
  93. RETURNS:    nothing
  94.  
  95. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  96. ContModule -- continue playing
  97.  
  98. This routine continues playing the module from the point it was stopped.
  99.  
  100. ARGUMENTS:    a0 = pointer to the module
  101.  
  102. RETURNS:    nothing
  103.  
  104. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  105. SetTempo -- set the playback tempo
  106.  
  107. (This routine has not much use.)
  108.  
  109. ARGUMENTS:    d0 = new tempo (1 - 240)
  110.  
  111. RETURNS:    nothing
  112.  
  113. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  114.  
  115. "proplayer.a" is the source code of the music routine. It contains stuff
  116. that may be unnecessary for your purposes, just taking time and memory.
  117. There are some "switches" at the beginning of the source, that allow you
  118. to turn off features you don't need. They are:
  119.  
  120. MIDI        If only the Amiga audio channels are used, set this to 0.
  121. AUDDEV        For some purposes, you may want to disable the code that
  122.         allocates the audio channels using "audio.device", e.g.
  123.         in a non-multitasking environment. Normally this should
  124.         be 1.
  125. SYNTH        If synth/hybrid sounds are not in use, this can be set to
  126.         zero.
  127. CHECK        This does some checkings to ensure that several values are
  128.         correct (e.g. is the sample in memory, no Amiga effects on
  129.         MIDI-tracks etc..). If you know that the song is correct,
  130.         you can safely turn the checks off.
  131. RELVOL        If you don't need the "relative volume", this can be zero.
  132. IFFMOCT        If the song doesn't contain multi-octave IFF samples
  133.         this can be zero.
  134. HOLD        This turns off the hold/decay features.
  135. PLAYMMD0    If set, the play routine will also handle old MMD0 type
  136.         modules. Useful for player programs.
  137. AURA        Aura output can be enabled by using this flag. (The file
  138.         "aura.a" must exist.)
  139.  
  140.  
  141. There's an additional flag, EASY. If set, the usage of the player routines
  142. is even more simplified, and you enter the module name into an INCBIN
  143. statement. There are two routines (_startmusic, _endmusic) you call
  144. to start and stop the music (the music can be started ONLY ONCE). The
  145. EASY option is suitable for demos etc. where only a single tune is
  146. required.
  147.  
  148. "proplayer.a" also supports multi-modules. It defines a UWORD modnum
  149. (in assembler: _modnum). Set this variable to the number of the song
  150. you want to play before calling PlayModule (0 is the first, 1 is the
  151. second song etc..). For example:
  152.     #include "proplayer.h" /* defines 'modnum' */
  153.     ...
  154.     modnum = 1; /* Play the second module */
  155.     PlayModule(module);
  156.     ...
  157. Assembler:
  158.     xref    _modnum
  159.     xref    _PlayModule
  160.     ...
  161.     move.w    #1,_modnum
  162.     lea    _module,a0
  163.     jsr    _PlayModule(pc)
  164.     ...
  165.  
  166. Timing
  167. ======
  168. If you need vertical blanking timing, you can set VBLANK to 1 and CIAB to 0.
  169. In normal use this is not recommended (because of the 16 % difference in
  170. playing speed with NTSC and PAL Amigas), but if tight synchronization to
  171. vertical blanking (e.g. in most demos/games) is required, VBLANK can be
  172. used.
  173.  
  174. For VBlank timing, the song has to be composed with primary tempo of about
  175. 33. The primary tempo cannot be changed with command F. Only the secondary
  176. tempo control can be used (command 9).
  177.  
  178. Assembling
  179. ==========
  180. "proplayer.a" can be assembled by using HiSoft's Devpac Assembler without
  181. changes. Other assemblers may need some small changes to work correctly
  182. (mostly because the directives they support may be slightly different). If
  183. you're working on a linker environment (e.g. programming in C), you've to
  184. include the resulted "proplayer.o" in your .lnk-file.
  185.  
  186. ===========================================================================
  187.  
  188. And how to get some music?
  189.  
  190. You have two ways to get the music:
  191. 1. Include the module in your final executable.
  192. 2. Save the module as a separate disk file and load it when needed
  193.    (this is probably the best way if you have more than one song, and
  194.     you don't want to use multi-modules).
  195.  
  196. First I cover the first method:
  197. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  198. Including the module in your final executable:
  199.  
  200. There's a utility, Objconv, which loads the module and dumps it into an
  201. object file. Here's an example how to use it:
  202.  
  203. - Assemble 'reloc.a' to 'reloc.o'.
  204. - Save the song as a module
  205. - Use Objconv e.g. objconv medmodule mod.o
  206. - Objconv requests the symbol name, enter "song" (without "'s), for example.
  207. - Now there's a file 'mod.o'. Link this file, and the file 'reloc.o'
  208.   with your program.
  209. - In your program, you define the module:
  210.     #include "proplayer.h"
  211.     ...
  212.     extern struct MMD0 far song;
  213.   You must relocate the module before it's used. Do this only once!
  214.   This is done by
  215.     RelocModule(&song);
  216.   RelocModule expects the argument in stack, so use __stdargs, if you've
  217.   turned registerized parameters on.
  218.  
  219. In assembler, you'd do exactly in the same way, except:
  220.     xref    _song
  221.     xref    _RelocModule
  222.     xref    _PlayModule
  223.  
  224.     ... (assuming all init stuff is here)
  225.  
  226.     lea    _song,a0
  227.     move.l    a0,-(sp)    ;push into stack
  228.     jsr    _RelocModule(pc)
  229.     addq.l    #4,sp        ;reset stack pointer
  230.     lea    _song,a0    ;this is passed in register a0
  231.     jsr    _PlayModule
  232.     ...
  233.  
  234. Note: if you've got an assembler that supports 'incbin' directive or
  235. equivalent, you can use it instead of Objconv. Relocation is required in
  236. any case.
  237.  
  238. And the second method (loading modules from disk):
  239. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  240. File "loadmod.a" contains three routines:
  241.     LoadModule
  242.     UnLoadModule
  243.     RelocModule
  244.  
  245. You usually need only the first two of them. RelocModule is used by
  246. LoadModule.
  247.  
  248. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  249. LoadModule -- loads a module from disk
  250.  
  251. This function loads a module from disk. Note that relocation is done
  252. automatically, so you must not RelocModule() a module obtained by using
  253. this routine.
  254.  
  255. ARGUMENTS:    a0 = pointer to file name
  256.  
  257. RETURNS:    d0 = pointer to the module, if something failed: 0
  258.  
  259. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  260. UnLoadModule -- free the module from memory
  261.  
  262. Frees the module. Remember to StopPlayer() before you unload the module
  263. that is currently playing. Also remember to free all modules you've loaded
  264. before you exit the program.
  265.  
  266. ARGUMENTS:    a0 = pointer to the module (may be 0)
  267.  
  268. RETURNS:    nothing
  269.  
  270. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  271.  
  272. ===========================================================================
  273.  
  274. REMEMBER:    All functions expect the arguments in registers. This is
  275.         automatically (??) handled by you when you program in
  276.         assembler, but it is not automatically handled when
  277.         you're programming in C.
  278.  
  279. If you have SAS/C V5 or later, this is done automatically if you include
  280. "proplayer.h" in all your code modules which call proplayer. If you have a
  281. compiler which doesn't support argument passing in registers, then you have
  282. to write the stub routines in assembler.
  283.  
  284. See also the small example sources.
  285.  
  286. ===========================================================================
  287.  
  288.     pro8player.a
  289.     ~~~~~~~~~~~~
  290.  
  291. "pro8player.a" is the play-routine for OctaMED 5 - 8 channel songs. This
  292. can be used exactly in the same way as "proplayer.a". The functions just
  293. have slightly different names:
  294.     InitPlayer8
  295.     RemPlayer8
  296.     PlayModule8
  297.     ContModule8
  298.     StopPlayer8
  299.     modnum8
  300.  
  301. Note that this player have some restrictions, as opposed to "proplayer.a".
  302. They're listed in OctaMED documents. It also takes quite a lot of processor
  303. time, depending on how many splitted channels there are.
  304.  
  305. You can use the same RelocModule() and (Un)LoadModule() routines with
  306. 5 - 8 channel songs.
  307.  
  308. The eight channel player has a byte flag _hq (assembler)/hq (C), which
  309. controls the HQ mode. Set this to 1 prior to calling PlayModule8 to
  310. activate the HQ mode.
  311.  
  312. ===========================================================================
  313.