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