home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / fish / audio / utils / med_424 / programmers / medplayerlibrary / medplayerlib.doc < prev    next >
Text File  |  1990-12-30  |  10KB  |  319 lines
  1. Instructions for using "medplayer.library" V1.00, by Teijo Kinnunen.
  2. --------------------------------------------------------------------
  3.  
  4. "medplayer.library" is a shared library, which can be used to load
  5. and play MED modules. You can call its functions from any language
  6. which supports library calls (C, Assembler, Basic...)
  7.  
  8. There's one advantage of using "medplayer.library" instead of linking
  9. with modplayer: If "medplayer.library" is upgraded, then the user has
  10. only change the library and there's no need to make modifications for
  11. the program itself.
  12.  
  13. First you must install "medplayer.library" to your LIBS: drawer.
  14. Click the "Inst"-gadget to do that (provided that you've booted with
  15. Workbench 1.3 or later). You can also load it with ARP's "loadlib"
  16. command. AmigaBasic-programmers should also copy "medplayer.bmap" to
  17. LIBS: or the current directory of AmigaBasic.
  18.  
  19. How to use the library?
  20. =======================
  21.  
  22. AmigaBasic: Study the example program...
  23.  
  24. C: If you have the Lattice C 5.04, then include "libproto.h", which
  25.    contains the #pragma's for calling the library. If you have some
  26.    other compiler, assemble "medplrlib_stub.a", which contains the
  27.    stub routines for calling the library (like amiga.lib).
  28.  
  29. Assembler: Just load the registers and call like any other library function.
  30.  
  31. Other languages: Since these are the only languages I know, I can't
  32.    help with other languages. Most other languages (Modula-2, other Basics
  33.    etc..) have probably some way of calling Amiga library functions. See
  34.    the manual of the compiler/interpreter.
  35.  
  36. Included are also few examples of using the library in C and Basic.
  37.  
  38. Here's the complete list of the functions of "medplayer.library" (in
  39. RKM autodoc-style):
  40.  
  41. ---------------------------------------------------------------------------
  42. ---------------------------------------------------------------------------
  43.  
  44. GetPlayer
  45.  
  46. NAME
  47.     GetPlayer -- get and initialize the player routine
  48.  
  49. SYNOPSIS
  50.     error = GetPlayer(midi)
  51.     D0                D0
  52.  
  53. FUNCTION
  54.     This routine allocates the audio channels and CIAA timer A
  55.     and prepares the interrupt. If "midi" is nonzero, serial
  56.     port is allocated and initialized. You should call this
  57.     routine when your programs starts up.
  58.  
  59. INPUTS
  60.     midi = 0 no midi, 1 set up midi. When you use a song that
  61.            has only Amiga samples, there's no reason to allocate
  62.            the serial port. Then set midi to 0. Use only values
  63.            0 or 1 here. Other values reserved for future expansion.
  64.  
  65. RESULT
  66.     If everything is OK, GetPlayer() returns zero. If initialization
  67.     failed or somebody else is currently using the library, then
  68.     GetPlayer() returns nonzero value.
  69.     NOTE: Even if GetPlayer() returned an error, you can still call
  70.           the library functions without making harm. They just won't
  71.           work (except LoadModule(), UnLoadModule() and GetCurrent-
  72.           Module(), which always work).
  73.  
  74. SEE ALSO
  75.     FreePlayer
  76.  
  77. ---------------------------------------------------------------------------
  78. ---------------------------------------------------------------------------
  79.  
  80. FreePlayer
  81.  
  82. NAME
  83.     FreePlayer -- free the resources allocated by GetPlayer()
  84.  
  85. SYNOPSIS
  86.     FreePlayer()
  87.  
  88. FUNCTION
  89.     This routine frees all resources allocated by GetPlayer().
  90.     Remember always call this routine before your program
  91.     exits. It doesn't harm to call this if GetPlayer() failed.
  92.     If you don't call this function during exit, audio channels,
  93.     timer etc. will remain allocated until reboot.
  94.  
  95. SEE ALSO
  96.     GetPlayer
  97.  
  98. ---------------------------------------------------------------------------
  99. ---------------------------------------------------------------------------
  100.  
  101. PlayModule
  102.  
  103. NAME
  104.     PlayModule -- play module from the beginning
  105.  
  106. SYNOPSIS
  107.     PlayModule(module)
  108.                A0
  109.  
  110. FUNCTION
  111.     This routine starts to play the module from the beginning.
  112.     The module can be obtained by calling LoadModule() or it can
  113.     be part of your program (when saved as an object file and
  114.     linked with it or included with some assemblers "binary
  115.     include" option).
  116.  
  117. INPUTS
  118.     module = pointer to module. If zero, then play the current
  119.              module (module which was played last).
  120.  
  121. SEE ALSO
  122.     ContModule, StopPlayer, DimOffPlayer
  123.  
  124. ---------------------------------------------------------------------------
  125. ---------------------------------------------------------------------------
  126.  
  127. ContModule
  128.  
  129. NAME
  130.     ContModule -- continue playing the module from where it stopped
  131.  
  132. SYNOPSIS
  133.     ContModule(module)
  134.                A0
  135.  
  136. FUNCTION
  137.     ContModule() functions just like PlayModule() except if you
  138.     have stopped playing with StopPlayer(), the playing will
  139.     continue where it stopped. When you play the module first
  140.     time, you should use PlayModule(), because ContModule() doesn't
  141.     initialize the filter.
  142.  
  143. INPUTS
  144.     module = pointer to module. If zero, use the current module.
  145.  
  146. SEE ALSO
  147.     PlayModule, StopPlayer, DimOffPlayer
  148.  
  149. ---------------------------------------------------------------------------
  150. ---------------------------------------------------------------------------
  151.  
  152. StopPlayer
  153.  
  154. NAME
  155.     StopPlayer -- stops playing immediately
  156.  
  157. SYNOPSIS
  158.     StopPlayer()
  159.  
  160. FUNCTION
  161.     Stop.
  162.  
  163. SEE ALSO
  164.     PlayModule, ContModule, DimOffPlayer
  165.  
  166. ---------------------------------------------------------------------------
  167. ---------------------------------------------------------------------------
  168.  
  169. DimOffPlayer
  170.  
  171. NAME
  172.     DimOffPlayer -- fade out the volume and stop playing
  173.  
  174. SYNOPSIS
  175.     DimOffPlayer(dimlength)
  176.  
  177. FUNCTION
  178.     Fades out the volume and stops the playing. The routine
  179.     returns immediately after you've called it. Then the
  180.     sound will start fading. If you want to know when the
  181.     player has stopped, you can examine the playstate-field
  182.     of the current module.
  183.  
  184. INPUTS
  185.     dimlength = how slowly should the sound fade, in lines
  186.                 e.g. DimOffPlayer(60) fades the sound in 60
  187.              lines
  188.  
  189. SEE ALSO
  190.     PlayModule, ContModule, StopPlayer
  191.  
  192. ---------------------------------------------------------------------------
  193. ---------------------------------------------------------------------------
  194.  
  195. SetTempo
  196.  
  197. NAME
  198.     SetTempo -- modify the playing speed
  199.  
  200. SYNOPSIS
  201.     SetTempo(tempo)
  202.              D0
  203.  
  204. FUNCTION
  205.     If you want to modify the playback speed, you can call this one.
  206.     This number should be 1 - 240. Note that tempos 1 - 10 are
  207.     recognized as SoundTracker tempos.
  208.  
  209. INPUTS
  210.     tempo = new tempo
  211.  
  212. ---------------------------------------------------------------------------
  213. ---------------------------------------------------------------------------
  214.  
  215. LoadModule
  216.  
  217. NAME
  218.     LoadModule -- load a MED module from disk and relocate it
  219.  
  220. SYNOPSIS
  221.     module = LoadModule(name)
  222.     D0                  A0
  223.  
  224. FUNCTION
  225.     When you want to load a module from disk, call this function.
  226.     The function loads only MED modules (MMD0). It doesn't load
  227.     Tracker-modules, MED songs or object files. Only MMD0s
  228.     (MMD0 is the identification word at the beginning of the file).
  229.     Because the module contains many pointers, they must be
  230.     relocated. This function relocates the module automatically.
  231.     If you link songs saved as object files, they will be relocated
  232.     by the AmigaDOS. Only if you include the module as a binary file,
  233.     then YOU must relocate it. This is an easy thing to do. You can
  234.     use the "RelocModule" function from "loadmod.a".
  235.  
  236. INPUTS
  237.     name = pointer to file name (null-terminated)
  238.  
  239. RESULT
  240.     module = pointer to module. If failed to load for some reason
  241.              (disk error, out of memory, not a module), zero will
  242.           be returned.
  243.  
  244. SEE ALSO
  245.     UnLoadModule
  246.  
  247. ---------------------------------------------------------------------------
  248. ---------------------------------------------------------------------------
  249.  
  250. UnLoadModule
  251.  
  252. NAME
  253.     UnLoadModule -- frees the module from memory
  254.  
  255. SYNOPSIS
  256.     UnLoadModule(module)
  257.                  A0
  258. FUNCTION
  259.     When you don't need the module anymore, you MUST free the
  260.     memory it has used. Use this routine for it. Remember to
  261.     stop the player before unloading the module it is playing.
  262.  
  263.     NOTE: unload only those modules which are loaded with
  264.     LoadModule(). If you attempt to free module which is a part
  265.     of the program, you will cause guru 81000009/81000005.
  266.  
  267. INPUTS
  268.     module = pointer to module. If zero, nothing happens.
  269.  
  270. SEE ALSO
  271.     LoadModule
  272.  
  273. ---------------------------------------------------------------------------
  274. ---------------------------------------------------------------------------
  275.  
  276. GetCurrentModule
  277.  
  278. NAME
  279.     GetCurrentModule -- returns the address of module currently playing
  280.  
  281. SYNOPSIS
  282.     module = GetCurrentModule()
  283.     D0
  284.  
  285. FUNCTION
  286.     Simply returns the pointer of the module, which is currently
  287.     playing (or if player is stopped, which was played last). This
  288.     works also if some other task is currently playing. In this case,
  289.     because of multitasking, you should have no use for the value
  290.     (the module can be already unloaded). You may ask what use this
  291.     function has. Well, I'm not sure, but because this function
  292.     takes only 2 machine language instructions (8 bytes of memory)
  293.     there's not much harm of it.
  294.  
  295. RESULT
  296.     module = pointer to current module
  297.  
  298. ---------------------------------------------------------------------------
  299. ---------------------------------------------------------------------------
  300.  
  301. ResetMIDI
  302.  
  303. NAME
  304.     ResetMIDI -- reset all pitchbenders and modulation wheels and
  305.                  ask player to resend the preset values
  306.  
  307. SYNOPSIS
  308.     ResetMIDI()
  309.  
  310. FUNCTION
  311.     This function resets pitchbenders and modulation wheels on all
  312.     MIDI channels. It also asks the player to send again the
  313.     preset change requests for all instruments, so that the presets
  314.     will be correct if the user has changed them. It performs the
  315.     same function as MED's Ctrl-Space.
  316.  
  317. ---------------------------------------------------------------------------
  318. ---------------------------------------------------------------------------
  319.