MODPlay API Manual
==================

MODPlay is a library of functions written in fully portable ANSI-C 
which allows you to play standard Amiga Pro/Soundtracker music 
(commonly known as MOD) files and to mix them with sound effects of 
your choice. The library currently works on the PC/Windows, Sega 
Dreamcast and Gamepark GP32. It is intended to by easy to use, portable
 and reasonably fast.

The MODPlay library is (c)2002,2003 by Christian Nowak <chnowak@web.de>.

For C Programmers
=================

To use the library with plain C, #include the file "gpmodplay.h" and 
link your executable with libmodplay.a.



void MODPlay_Init ( MODPlay * );

Initializes the MODPlay structure with standard values. Every instance 
of the MODPlay structure needs to be initialized this way.



int MODPlay_Load ( MODPlay*, char * fname );

Loads a MOD file from the smartmedia card. Returns a value smaller than
 0 on error. Note that you can load a MOD even if the given MODPlay 
structure is already associated with a MOD and is being played. If the 
Load fails, the old MOD won't be deleted from memory. Before using this
 function, you must have called GpFatInit().



int MODPlay_SetMOD ( MODPlay*, u8* );

Can be used as an alternative to MODPlay_Load if you want to embed the 
MOD into your program code. Pass a pointer to the beginning of the MOD 
file in memory as the second parameter.



int MODPlay_Start ( MODPlay* );

Starts playing the MOD. Returns a value smaller than 0 on error.



int MODPlay_Stop ( MODPlay* );

Stops playback. Returns a value smaller than 0 on error.



int MODPlay_Pause ( MODPlay*, BOOL );

Pauses/continues playback, depending on the value of the boolean 
parameter.



void MODPlay_Unload ( MODPlay* );

Deletes the MOD from memory (unless it has been 'loaded' using 
MODPlay_SetMOD). You can call this function any time.



void MODPlay_SetStereo ( MODPlay*, BOOL );

If the second parameter is TRUE, playback switches to stereo (standard 
setting), otherwise it switches to mono. You can call this function 
any time.



int MODPlay_SetPlayFreq ( MODPlay*, int );

Set the playback frequency to 11025, 22050 or 44100Hz (standard 
setting). You can call this function any time.



int MODPlay_AllocSFXChannels ( MODPlay*, int );

Allocates the specified number of channels for effects. Please note 
that the total number of channels (music + effects channels) must not 
exceed 32. The function returns a value smaller than 0 on error.



int MODPlay_TriggerNote ( MODPlay*, int channel, u8 instnum, u16 freq, u8 vol );

Triggers a note in the specified effects channel. channel=0 specifies 
the first allocated SFX channel, so the music playback won't be 
affected. freq specifies standard Amiga frequency values and vol ranges
 from 0 to 64 (full volume). If you set all bits of any parameter 
 except channel, this parameter will be ignored. If instnum is not 
equal to 0xff, the sample will be retriggered. The function returns a 
value smaller than 0 on error.


The volume of music as well as SFX playback can be adjusted between 0 and 64.
To do that, store the desired volume in the musicvolume or sfxvolume variables
of the MOD structure in the MODPlay structure.


For C++ Programmers
===================

-- Coming soon ;) --



That's it for now. Have fun!

/chris
-- 
Christian Nowak <chnowak@web.de>
http://chn.roarvgm.com/
