RexxMMD.library V1.1 - An ARexx Function Library    Coded in   MC680x0 Assembly   by   Gard Kay     Copyright Notice THIS PIECE OF SOFTWARE IS COPYRIGHT © 1993 BY GARD KAY AND "DEAD ELKS - SERIOUS". YOU MAY, HOWEVER, REDISTRIBUTE THIS PROGRAM FREELY PROVIDED THAT NO FEE WHATSOEVER IS CHARGED FOR IT EXCEPT BBS DOWNLOAD CREDITS, THE PROGRAM IS SUPPLIED WITH THE DOCUMENTATION AND ALL ORIGINALLY SUPPLIED FILES, AND THAT IT IS NOT INCLUDED IN ANY COMMERCIAL PACKAGE WITHOUT THE AUTHOR'S PRIOR WRITTEN CONSENT. IT IS ILLEGAL TO MODIFY THIS PROGRAM IN ANY WAY, EXCEPT RE-ARCHIVING WITH AN ARCHIVER THAT RECONSTRUCTS THE FILES EXACTLY AS THEY WERE PRIOR ARCHIVING. PERMISSION IS HEREBY GRANTED TO MR. BJØRN A. LYNNE TO REDISTRIBUTE THIS PACKAGE AS HE SEES FIT, AS A PART OF HIS AM/FM DISK-MAGAZINE. Disclaimer UNDER NO CIRCUMSTANCES DO THE COPYRIGHT HOLDERS CLAIM LIABILITY TO YOU FOR ANYTHING, RESULTING FROM USE OR MISUSE, CAUSED, DIRECTLY OR INDIRECTLY, BY THIS PROGRAM. ALL RIGHTS RESERVED. Know that every effort has been made to make this program bug-free. (But one never knows.) What You Get This archive should contain: Docs/RexxMMD.doc The file you are reading. Libs/medplayer.library A library by Teijo Kinnunen. Libs/octaplayer.library A library by Teijo Kinnunen. Libs/rexxmmd.library The ARexx interface library. Program Description RexxMMD.library is an ARexx function library containing interface functions for Teijo Kinnunen's medplayer.library and octaplayer.library. This interface enables you to load and play (presently) MMD0 and MMD1 4-8 channel modules in no-time. To add the library to the ARexx function library list, type "RXLIB rexxmmd.library 0 -30 1" and . Requirements This program requires a standard A500 with KickStart V1.3 (or higher). It also requires medplayer.library and octaplayer.library. How to Contact the Author If you find any bugs, do not hesitate to write to me at this address: Gard Kay Fauchaldsgate 20 2800 GJOEVIK Norway Acknowledgements Medplayer.library is copyright © 1991 by Teijo Kinnunen and RBF Software. Octaplayer.library is copyright © 1991 by Teijo Kinnunen and RBF Software. RexxMMD.library History V1.0: First release. V1.1: Renamed to (from "MMDxLib") "RexxMMD". Modified some potentially dangerous code. Bugfix: Due to a missing byte, the PlayModule8() was reported "not present" in the library. This is now fixed. RexxMMD.library Future o XPK support. o Functions to identify a loaded module (MMD0, MMD1, # of channels, etc). Coming soon from Dead Elks - Entertainment Elkanoid MineSweeper Professional III    FUNCTION DESCRIPTIONS    Warning: Do not access any functions from this library directly from the CLI. I think the medplayer.library performs certain safety-checks in your task structure, and if it finds any inconcistencies from call to call it refuses to work. Conclusions derived from said fact give witness to the practicality of loading and playing a module from within one task, and stopping and unloading it from within another. :-) (You won't be able to stop it.) Only use these functions from within the same program without interruptions in the program-flow (such as syntax errors). (This makes for some interesting debugging. :-) ) ------------------------------------------------------------------------------ NAME ContModule() SYNOPSIS ContModule(Module) DESCRIPTION Continues a module previously stopped by StopPlayer(). INPUTS Module - An ARexx pointer ("xxxxxxxx"x) to the module (as returned by LoadModule()). BUGS None known. SEE ALSO LoadModule() StopPlayer() ------------------------------------------------------------------------------ NAME FreePlayer() SYNOPSIS FreePlayer() DESCRIPTION Frees the system-resources allocated by GetPlayer(). BUGS None known. SEE ALSO GetPlayer() ------------------------------------------------------------------------------ NAME GetCurrentModule() SYNOPSIS Module = GetCurrentModule() DESCRIPTION Gets ahold of the address of the module currently playing. RESULT Module - ARexx pointer to the module or "00000000"x if no module is currently playing. BUGS None known. SEE ALSO ------------------------------------------------------------------------------ NAME GetPlayer(MIDI) SYNOPSIS Success = GetPlayer(MIDI) DESCRIPTION Allocates the system-resources neccessary for playing OctaMEd modules. This function _must_ have been called before any attempt is made at playing modules. INPUTS MIDI - Optional. If anything else than FALSE (0), the player will be set up for MIDI playing. RESULT Success - TRUE (1) if the system-resources could be allocated, FALSE if not. The latter being the case, you should not make _any_ attempt at playing anything. (Something will probably already be playing.) BUGS None known. SEE ALSO FreePlayer() ------------------------------------------------------------------------------ NAME LoadModule() SYNOPSIS Module = LoadModule(ModName) DESCRIPTION Loads a module into memory and relocates it. INPUTS ModName - Filename (w/path) of the module to load. RESULT Module - ARexx pointer to the module or "00000000"x if it could not be loaded for some reason. BUGS Err... Well... There is one bug, but I reckon this bug exists in the medplayer.library. Sometimes (for God knows what reason) this function gurus. This only happens when the module is found and enough memory exists to contain it (I think). SEE ALSO UnLoadModule() ------------------------------------------------------------------------------ NAME PlayModule() SYNOPSIS PlayModule(Module) DESCRIPTION Plays the given module from the start. If you are about to play a multi- module, set the module number by using SetModnum() before calling this function. INPUTS Module - ARexx pointer to the module. BUGS None known. SEE ALSO SetModnum() StopPlayer() ------------------------------------------------------------------------------ NAME ResetMIDI() SYNOPSIS ResetMIDI() DESCRIPTION Resets all pitchbenders and modulation wheels and requests that the preset values be re-sent. BUGS None known. SEE ALSO GetPlayer() ------------------------------------------------------------------------------ NAME SetModnum() SYNOPSIS SetModnum(ModNum) DESCRIPTION Sets which module to play (for multi-modules). INPUTS ModNum - Number (from 0 and up) denoting which module to play. BUGS None known. SEE ALSO PlayModule() ------------------------------------------------------------------------------ NAME StopPlayer() SYNOPSIS StopPlayer() DESCRIPTION Stops all playing immediately. BUGS None known. SEE ALSO ContModule() ------------------------------------------------------------------------------ NAME UnLoadModule() SYNOPSIS UnLoadModule(Module) DESCRIPTION Removes a module from memory. This function is probably not safe to use while playing. :-) INPUTS Module - ARexx pointer to the module to be unloaded. BUGS None known. SEE ALSO LoadModule. ------------------------------------------------------------------------------ A more or less identical set of octaplayer.library interface functions also exist in this library. The functions are named: ContModule8() FreePlayer8() GetPlayer8() LoadModule8() PlayModule8() SetModnum8() StopPlayer8() UnLoadModule8() All functions accept the same arguments (and return the same results) as their medplayer.library equivalents, except GetPlayer8() which takes no arguments. (MIDI playing is not possible with 5-8 channel modules.) In case someone wonders how to proceed when loading and playing a module, here's an example: /* PlayMod */ PlayMod: if ~getplayer() then do say "Could not allocate the needed resources." return(10) end /* GetPlayer() _must_ return 1 if playing is to proceed normally */ Module = loadmodule("DH0:TestMod") if Module = "00000000"x then do freeplayer() say "Could not load module." return(10) end /* Ofcourse, the module must also have loaded successfully */ playmodule(Module) /* Start playing */ pull Dummy /* Delay until the user presses return */ stopplayer() /* Stop playing */ unloadmodule(Module) /* Free the memory for the module */ freeplayer() /* Release the audio resources from our grasp 8) */ return(0) /* Exit */