home *** CD-ROM | disk | FTP | other *** search
/ Merciful 3 / Merciful_Release_3.bin / software / o / octamed / octamedv6.12.lha / programmers / library.doc < prev    next >
Text File  |  1995-03-25  |  12KB  |  397 lines
  1. ***************************************************************************
  2.  
  3. Instructions for using "medplayer.library" and "octaplayer.library" V6.0.
  4.  
  5. ***************************************************************************
  6.  
  7.  
  8.         medplayer.library
  9.         ~~~~~~~~~~~~~~~~~
  10.  
  11. "medplayer.library" is a shared library, which can be used to load and play
  12. MED/OctaMED 4-channel modules You can call its functions from any language
  13. which supports library calls (C, Assembler, Basic...)
  14.  
  15. "medplayer.library" supports only 4-channel MED songs. For OctaMED 5 - 8
  16. channel songs octaplayer.library must be used.
  17.  
  18. There's a header file 'libproto.h' that contains the prototypes and
  19. #pragmas for use with SAS/C.
  20.  
  21. Here's the complete list of the functions in "medplayer.library" (in RKM
  22. autodoc-style):
  23.  
  24. ---------------------------------------------------------------------------
  25. ---------------------------------------------------------------------------
  26.  
  27. GetPlayer
  28.  
  29. NAME
  30.     GetPlayer -- get and initialize the player routine
  31.  
  32. SYNOPSIS
  33.     error = GetPlayer(midi)
  34.     D0                D0
  35.  
  36. FUNCTION
  37.     This routine allocates the audio channels and CIAB timer A/B
  38.     and prepares the interrupt. If "midi" is nonzero, serial
  39.     port is allocated and initialized. You should call this
  40.     routine when your programs starts up.
  41.  
  42. INPUTS
  43.     midi =  0 no midi, 1 set up midi. When you use a song that
  44.         has only Amiga samples, there's no reason to allocate
  45.         the serial port. Then set midi to 0.
  46.  
  47. RESULT
  48.     If everything is OK, GetPlayer() returns zero. If initialization
  49.     failed or somebody else is currently using the library, then
  50.     GetPlayer() returns nonzero value.
  51.     NOTE: Even if GetPlayer() returned an error, you can still call
  52.           the library functions without making harm. They just won't
  53.           work (except LoadModule(), UnLoadModule(), RelocModule()
  54.           and GetCurrentModule(), which always work).
  55.  
  56. SEE ALSO
  57.     FreePlayer
  58.  
  59. ---------------------------------------------------------------------------
  60. ---------------------------------------------------------------------------
  61.  
  62. FreePlayer
  63.  
  64. NAME
  65.     FreePlayer -- free the resources allocated by GetPlayer()
  66.  
  67. SYNOPSIS
  68.     FreePlayer()
  69.  
  70. FUNCTION
  71.     This routine frees all resources allocated by GetPlayer().
  72.     Remember always call this routine before your program
  73.     exits. It doesn't harm to call this if GetPlayer() failed.
  74.     If you don't call this function during exit, audio channels,
  75.     timer etc. will remain allocated until reboot.
  76.  
  77. SEE ALSO
  78.     GetPlayer
  79.  
  80. ---------------------------------------------------------------------------
  81. ---------------------------------------------------------------------------
  82.  
  83. PlayModule
  84.  
  85. NAME
  86.     PlayModule -- play module from the beginning
  87.  
  88. SYNOPSIS
  89.     PlayModule(module)
  90.                A0
  91.  
  92. FUNCTION
  93.     This routine starts to play the module from the beginning.
  94.     The module can be obtained by calling LoadModule() or it can
  95.     be incorporated directly into your program. The module has to
  96.     be relocated before calling PlayModule()!
  97.  
  98. INPUTS
  99.     module = pointer to the module.
  100.  
  101. SEE ALSO
  102.     ContModule, StopPlayer
  103.  
  104. ---------------------------------------------------------------------------
  105. ---------------------------------------------------------------------------
  106.  
  107. ContModule
  108.  
  109. NAME
  110.     ContModule -- continue playing the module from where it stopped
  111.  
  112. SYNOPSIS
  113.     ContModule(module)
  114.                A0
  115.  
  116. FUNCTION
  117.     ContModule() functions just like PlayModule() except if you
  118.     have stopped playing with StopPlayer(), the playing will
  119.     continue where it stopped. When you play the module first
  120.     time, you should use PlayModule().
  121.  
  122. INPUTS
  123.     module = pointer to module.
  124.  
  125. SEE ALSO
  126.     PlayModule, StopPlayer
  127.  
  128. ---------------------------------------------------------------------------
  129. ---------------------------------------------------------------------------
  130.  
  131. StopPlayer
  132.  
  133. NAME
  134.     StopPlayer -- stops playing immediately
  135.  
  136. SYNOPSIS
  137.     StopPlayer()
  138.  
  139. FUNCTION
  140.     Stop.
  141.  
  142. SEE ALSO
  143.     PlayModule, ContModule
  144.  
  145. ---------------------------------------------------------------------------
  146. ---------------------------------------------------------------------------
  147.  
  148. DimOffPlayer
  149.  
  150. NOTE
  151.     This is an obsolete function! It was removed in V2 of the library,
  152.     and it now just does StopPlayer()!
  153.  
  154. ---------------------------------------------------------------------------
  155. ---------------------------------------------------------------------------
  156.  
  157. SetTempo
  158.  
  159. NAME
  160.     SetTempo -- modify the playing speed
  161.  
  162. SYNOPSIS
  163.     SetTempo(tempo)
  164.              D0
  165.  
  166. FUNCTION
  167.     If you want to modify the playback speed, you can call this one.
  168.     This number should be 1 - 240. Note that tempos 1 - 10 are
  169.     recognized as SoundTracker tempos. This function probably has not
  170.     much use.
  171.  
  172. INPUTS
  173.     tempo = new tempo
  174.  
  175. ---------------------------------------------------------------------------
  176. ---------------------------------------------------------------------------
  177.  
  178. LoadModule
  179.  
  180. NAME
  181.     LoadModule -- load a MED module from disk and relocate it
  182.  
  183. SYNOPSIS
  184.     module = LoadModule(name)
  185.     D0                  A0
  186.  
  187. FUNCTION
  188.     When you want to load a module from disk, call this function.
  189.     The function loads only MED modules (MMD0/MMD1/MMD2). This
  190.     function relocates the module automatically.
  191.  
  192.     If you want to be sure that a specific module type is supported,
  193.     you will have to use the minimum version number when opening the
  194.     library. Here are the version numbers:
  195.  
  196.     MMD0    all versions
  197.     MMD1    version 3 + above
  198.     MMD2    version 5 + above
  199.  
  200.     However, supporting the module type does not mean that the player
  201.     can fully play the module with all detail. For example, multiple
  202.     command pages are not supported until version 6, and earlier
  203.     versions just recognize the first page.
  204.  
  205. INPUTS
  206.     name = pointer to file name (null-terminated)
  207.  
  208. RESULT
  209.     module = pointer to module. If failed to load for some reason
  210.              (disk error, out of memory, not a module), zero will
  211.           be returned.
  212.  
  213. SEE ALSO
  214.     UnLoadModule
  215.  
  216. NOTE
  217.     If you include the module as a binary file converted with Objconv
  218.     instead of loading from disk, YOU must relocate it. This is an easy
  219.     thing to do. Just call RelocModule().
  220.  
  221. ---------------------------------------------------------------------------
  222. ---------------------------------------------------------------------------
  223.  
  224. UnLoadModule
  225.  
  226. NAME
  227.     UnLoadModule -- frees the module from memory
  228.  
  229. SYNOPSIS
  230.     UnLoadModule(module)
  231.                  A0
  232. FUNCTION
  233.     When you don't need the module anymore, you MUST free the
  234.     memory it has used. Use this routine for it. Remember to
  235.     stop the player before unloading the module it is playing.
  236.  
  237.     NOTE: unload only those modules which are loaded with
  238.     LoadModule(). If you attempt to free module which is a part
  239.     of the program, you will get a guru (81000009/81000005).
  240.  
  241. INPUTS
  242.     module = pointer to module. If zero, nothing happens.
  243.  
  244. SEE ALSO
  245.     LoadModule
  246.  
  247. ---------------------------------------------------------------------------
  248. ---------------------------------------------------------------------------
  249.  
  250. GetCurrentModule
  251.  
  252. NAME
  253.     GetCurrentModule -- returns the address of module currently playing
  254.  
  255. SYNOPSIS
  256.     module = GetCurrentModule()
  257.     D0
  258.  
  259. FUNCTION
  260.     Simply returns the pointer of the module, which is currently
  261.     playing (or if player is stopped, which was played last). This
  262.     works also if some other task is currently playing. In this case,
  263.     because of multitasking, you should have no use for the value
  264.     (the module can be already unloaded). You may ask what use this
  265.     function has. Well, I'm not sure, but because this function
  266.     takes only 2 machine language instructions (8 bytes of memory)
  267.     there's not much harm of it.
  268.  
  269. RESULT
  270.     module = pointer to current module
  271.  
  272. ---------------------------------------------------------------------------
  273. ---------------------------------------------------------------------------
  274.  
  275. ResetMIDI
  276.  
  277. NAME
  278.     ResetMIDI -- reset all pitchbenders and modulation wheels and
  279.                  ask player to resend the preset values
  280.  
  281. SYNOPSIS
  282.     ResetMIDI()
  283.  
  284. FUNCTION
  285.     This function resets pitchbenders and modulation wheels on all
  286.     MIDI channels. It also asks the player to send again the
  287.     preset change requests for all instruments, so that the presets
  288.     will be correct if the user has changed them. It performs the
  289.     same function as Ctrl-Space in OctaMED.
  290.  
  291. ---------------------------------------------------------------------------
  292. ---------------------------------------------------------------------------
  293. Note: The following functions are only available in medplayer.library V2
  294. or later, be sure that you're really using V2 of the library
  295. e.g.  MEDPlayerBase = OpenLibrary("medplayer.library",2);
  296. ---------------------------------------------------------------------------
  297. ---------------------------------------------------------------------------
  298.  
  299. SetModnum
  300.  
  301. NAME
  302.     SetModnum -- select the number of the song (in multi-module)
  303.  
  304. SYNOPSIS
  305.     SetModnum(modnum)
  306.           D0
  307.  
  308. FUNCTION
  309.     Use this function to set the number of song you want to play.
  310.     Call this before PlayModule(). 0 is the first song, 1 is the
  311.     second, and so on. If the module is not a multi-module, this
  312.     function has no effect.
  313.  
  314. ---------------------------------------------------------------------------
  315. ---------------------------------------------------------------------------
  316.  
  317. RelocModule
  318.  
  319. NAME
  320.     RelocModule -- relocate module
  321.  
  322. SYNOPSIS
  323.     RelocModule(module)
  324.             A0
  325.  
  326. FUNCTION
  327.     This function relocates the module. It should be used if you've
  328.     incorporated the module with Objconv program before using the
  329.     module. Note that LoadModule() automatically relocs everything.
  330.  
  331. ---------------------------------------------------------------------------
  332. ***************************************************************************
  333.  
  334.         octaplayer.library
  335.         ~~~~~~~~~~~~~~~~~~
  336.  
  337. This  library  is  made  for  playing OctaMED 5 - 8 channel songs ONLY.  It
  338. doesn't  support  MIDI  or 4-channel songs.  The functions in it work quite
  339. similarly as medplayer.library's functions.  See the medplayer.library docs
  340. above   for   explanation   of   the   functions,   as   the  functions  in
  341. octaplayer.library work in the same way.
  342.  
  343. The functions are:
  344.  
  345.     GetPlayer8()        (midi switch ignored)
  346.     FreePlayer8()
  347.     PlayModule8(module)
  348.     ContModule8(module)
  349.     StopPlayer8()
  350.     LoadModule8(filename)
  351.     UnLoadModule8(module)
  352.     SetModnum8(modnum)
  353.     RelocModule8(module)
  354.  
  355. As you can see, every function has '8' in its name, and some functions that
  356. are in medplayer.library don't exist. There's also an additional function
  357. that exists only in octaplayer.library (V6 and above):
  358.  
  359. ---------------------------------------------------------------------------
  360.  
  361. SetHQ
  362.  
  363. NAME
  364.     SetHQ - set high quality mode        (V6)
  365.  
  366. SYNOPSIS
  367.     SetHQ(hq)
  368.           D0
  369.  
  370. FUNCTION
  371.     When you allocate the player with GetPlayer8(), the HQ mode is set
  372.     off by default. This function switches the HQ mode on or off.
  373.     (D0: nonzero = on, zero = off).
  374.  
  375.     Note: The player should be stopped when calling this.
  376.  
  377.     Also note: No check is made whether the computer is fast enough to
  378.     handle HQ properly.
  379.  
  380. ---------------------------------------------------------------------------
  381.  
  382. ***************************************************************************
  383. Note:
  384. ~~~~~
  385. Version 3 of both medplayer.library and octaplayer.library handle the new
  386. MMD1 module type correctly. No changes are required to programs calling
  387. these libraries. If you absolutely want MMD1 support, be sure to request
  388. V3 of the libraries.
  389.  
  390. (e.g. OpenLibrary("medplayer.library",3); )
  391.  
  392. As well, if you want MMD2 support, be sure to ask version 5 or later.
  393.  
  394. The libraries keep track of the current user by comparing the task
  395. address. Therefore, you should call all routines within a single task.
  396. ***************************************************************************
  397.