diff --git a/tools/mod/Calls.txt b/tools/mod/Calls.txt new file mode 100644 index 000000000..3796f629a --- /dev/null +++ b/tools/mod/Calls.txt @@ -0,0 +1,712 @@ +07-12-98/JAP +XMPlayer (Extended MOD) for PlayStation. (c)1998 SCEE +Written by Jason Page + +Calls: + +---------------------------------------------------------------------------- +void XM_OnceOffInit(machine type); + + Description: + Init player to NTSC/PAL + Requires: + XM_NTSC To play at 60fps + XM_PAL To play at 50fsp + Returns: + Nothing + +---------------------------------------------------------------------------- +int XM_VABInit(VHData,VBData); + + Description: + Initialise the VAB data files + Requires: + VHData Address of VAB Header + VBData Address of VAB Body + (Hopefully BOTH VB and VH files can be + deleted from main memory after this call) + Returns: + VAB_ID. 0-7 + -1 if transfer not complete + (no free ID's or out of SPU RAM) +---------------------------------------------------------------------------- +void InitXMData(XMData,XM_ID,PanType); + + Description: + Initialise the XM data + Requires: + XMData Address of .XM Data file + XM_ID ID(0-7) so any song/SFX know what XM file to + use. + PanType XM_UseXMPanning + XM_UseS3MPanning + (Allows S3M files (converted to .XM) to play + correctly) + Returns: + Nothing. + +---------------------------------------------------------------------------- +int XM_Init (VabID,XM_ID,FirstChannel,Loop,PlayMask,SongType,SFXPatternNum); + + Description: + Play a Song or SFX + Init's user channel volumes to 0 + Requres: + VabID ID returned from XM_VABInit + XM_ID So we know what XM file to use.(0-7) + FirstChannel 1) First channel to playback on (setting + this to 5, with a 4 channel song, would + use SPU channels 5,6,7,8) + 2) -1 will force SFX to use the predefined + channels from the XM_SetSFXRange call. + Loop XM_Loop or XM_NoLoop(for once off music) + PlayMask Set each bit to all data to be played. + -1 will play everything. + 3 will play the first 2 channels + 5 will play channels 0 and 3 only + This allows for multi or single channel SFX + 0 = PAUSE TUNE (So it wont start straight away) + Use XM_PlayStart to start tune. + SongType XM_Music or XM_SFX + SFXPatternNum 1) Pattern to use as a SFX. + SFX will play the single pattern and then + stop. Using this, with the PlayMask and + FirstChannel allows multi or single channel + SFX to play on any channel- quite powerful. + 2) Offset in Songs pattern play list. + Set this to play from any point through + the song. + Returns: + Song_ID 0-23. Used later for panning/volume/pausing... + +---------------------------------------------------------------------------- +void XM_PlayStart(Song_ID,int Playmask); + + Description: + Set flag to allow processing of tune. + Requires: + Song_ID Value passed on XM_Init + PlayMask BitMask for channels on or off. + -1 Play all channels of tune. + 3 Play channels 0 and 1 etc..etc... + Returns: + Nothing. + +---------------------------------------------------------------------------- +void XM_PlayStop(Song_ID); + + Description: + Set flag to stop processing of tune. + Silence any playing channels for tune. + Requires: + Song_ID Value passed on XM_Init + Returns: + Nothing. + +---------------------------------------------------------------------------- +void XM_SetSongPos(Song_ID,SongPos); + + Description: + Jumps directley to SongPos in the XM file's + playlist. + Requires: + Song_ID Value passed on XM_Init + SongPos Positiong through song to jump to + Returns: + Nothing + +---------------------------------------------------------------------------- +void XM_Update(); + + Description: + Updates XM Player (up to 24 songs/SFX) + Must be called at 50 or 60fps + (Depending on XM_OnceOffInit) + Requires: + Nothing. + Returns: + Nothing. + +---------------------------------------------------------------------------- + +void XM_Update2(Speed); + + Description: + Updates XM Player (up to 24 songs/SFX) + Must be called n times per frame + Keeps better time than XM_Update() + (Depending on XM_OnceOffInit) + Requires: + Speed (amount of times routine is called per frame..) + Returns: + Nothing. + +---------------------------------------------------------------------------- + +void XM_Pause(Song_ID); + + Description: + Pause song/SFX + Silence any playing channels + Requires: + Song_ID Value passed on XM_Init + Returns: + Nothing + +---------------------------------------------------------------------------- +void XM_Restart(Song_ID); + + Description: + Restart (UnPause) song/SFX + Continue any playing channels + (Continues any previously keyed on notes) + Requires: + Song_ID Value passed on XM_Init + Returns: + Nothing + +---------------------------------------------------------------------------- +void XM_PauseAll(void); + + Description: + Pause all playing songs/SFX + Silence any playing channels + Requires: + Nothing + Returns: + Nothing + +---------------------------------------------------------------------------- +void XM_RestartAll(void); + + Description: + Restart (UnPause) all paused songs/SFX + Continue any playing channels + (Continues any previously keyed on notes) + Requires: + Nothing + Returns: + Nothing + +---------------------------------------------------------------------------- +void XM_Exit(); + + Description: + Stops all tunes. + Free SPU RAM + + Requires: + Nothing + Returns: + Nothing + +---------------------------------------------------------------------------- +void XM_SetChVolume(Song_ID,Channel,Volume); + + Description: + Allow user input to modify individual channel + volumes. + Requires: + Song_ID Value passed on XM_Init + Channel (0-24) Channel to modify/set. + Volume (0-64) This value is subtracted from the + channels current volume. + 0 Normal Channel volume. + 32 Current channel volume - 32 + 64 Current channel volume - 64 (silent) + Returns: + Nothing + +---------------------------------------------------------------------------- +int XM_GetChVolume(Song_ID,Channel); + + Description: + Get user volume setting for current channel. + Requires: + Song_ID Value passed on XM_Init + Channel (0-24) Channel to get info from. + Returns: + ChannelVolume (0-64) Current user volume for channel. + +---------------------------------------------------------------------------- +XM_Feedback Fdbk; +XM_Feedback *FB; +FB=&Fdbk; +XM_GetFeedback(Song_ID,FB); + + Description: + Get song info. + Requires: + Song_ID Value passed on XM_Init + FB Pointer to the XM_Feedback structure. + Returns: + Fdbk.Status Current Playing status (stopped,playing,paused..) + Fdbk.SongPos Current Song position through playlist. + Fdbk.PatternPos Current postion through current pattern + Fdbk.SongBPM Current BPM for song + Fdbk.SongSpeed Current Speed for song + Fdbk.SongLength Number of patterns in song + Fdbk.SongLoop Flag if song is to loop at end or finish. + Fdbk.Volume Master volume (0-128) + Fdbk.Panning Master panning (-127 > +127) + Fdbk.ActiveVoices Amount of keyed on voices + Fdbk.PlayNext Current User requested song jump (-1 if none) + Fdbk.CurrentStart Position tune last jumped to if user jumps + +---------------------------------------------------------------------------- +void XM_PlayNext(Song_ID,SongPosition); + + Description: + Sets position in songs pattern list to + jump to, when playing reaches the end + of a pattern. + Reqires: + Song_ID Value passed on XM_Init + SongPosition Position through song list to jump to + or -1 to cancel request + Returns: + Nothing + +---------------------------------------------------------------------------- +void XM_CPlayNext(Song_ID,SongPosition); + + Description: + Sets position in songs pattern list to + jump to, when playing reaches the end + of a pattern. ONLY does this if a 0xcff + has been put in the pattern data. + (set 0xcfe to cancel command) + Reqires: + Song_ID Value passed on XM_Init + SongPosition Position through song list to jump to + or -1 to cancel request + Returns: + Nothing + +---------------------------------------------------------------------------- + +void XM_CloseVAB(VabID); + + Description: + Clears SPU RAM of all samples used in VAB. + Requires: + VAB ID + Returns: + Nothing + +---------------------------------------------------------------------------- +void XM_SetMasterVol(int Song_ID,u_char Vol); + + Description: + Set Song/SFX master volume. + Requires: + SongID Value passed on XM_Init + Volume 0-128 + + Returns: + Nothing + +---------------------------------------------------------------------------- +void XM_SetMasterPan(int Song_ID,u_char Pan); + + Description: + Set Song/SFX master volume. + Requires: + SongID Value passed on XM_Init + Pan -127 > + 127 (0 = middle, -ve left +ve right) + + Returns: + Nothing + +---------------------------------------------------------------------------- +int XM_SendVAGToSRAM(u_char *addr,int size); + + Description: + Sends a single VAG to SPU RAM. + Uses the same malloc table, and so on. + Allows the user to play single VAG samples + without having to use the XM Player. + + Requires: + addr Address of VAG + size Size of VAG + + Returns: + SPU Address Address of sample in SPU RAM. + -1 if Transfer failed. +---------------------------------------------------------------------------- +void XM_FreeVAG(int addr); + + Description: + Free's sample from SPU RAM + Used for clearing samples if user has called + XM_SendVAGToSRAM. + + Requires: + addr Address of VAG (returned from XM_SendVAGToSRAM) + + Returns: + Nothing + +---------------------------------------------------------------------------- +void XM_DoFullUpdate(int Song); + + Description: + Forces update of Song data. + Does not use any BPM or Speed rescrictions. + Use this call if you are setting up your + own interrupt or timer. + Your interrupt will have to calculate the + BPM/Speed and then call this function when + necessary. + You will need to get the BPM and Speed values + from the Feedback structure after each call + to this, and use them for your calculations. + + Requires: + Song Song number 0-23 to update. + + Returns: + Nothing + +---------------------------------------------------------------------------- +XM_HeaderInfo Info; +XM_HeaderInfo *Inf; +Inf=&Info; + +XM_GetHeaderInfo(XM_ID,Inf); + + Description: + Get XM file info. + Use if setting up your own interrupt to call + XM_DoFullUpdate. + + Requires: + XM_ID Value returned from InitXMData + Inf Pointer to XM_HeaderInfo structure + + Returns: + Inf.BPM XM File Initial BPM setting + Inf.Speed XM File Initial Speed setting + +---------------------------------------------------------------------------- +int XM_SetSFXRange(start,length); + + Description: + Sets table for using SFX. + This table (along with setting -1 in the first + channel of the XM_Init call) will force SFX + to use specified channels. + This means that the user doesn't have to + specify what channel a SFX will be played on, + so makes it easier to setup and call SFX. + 1) XM_SetSFXRange(0,10) + 2) XM_Init(with -1 in FirstChannel) + SFX will then be played on channels 0-0xf. + Any finished patterns will free up channels. + + Requires: + start First channel to use as SFX + length Amount of channels to use as SFX + + Returns: + 0 All OK + -1 Error (too many channels?) + +---------------------------------------------------------------------------- +void XM_ClearSFXRange(void); + + Description: + Clears any values set up by XM_SetSFXRange + + Requires: + Nothing + + Returns: + Nothing + +---------------------------------------------------------------------------- +void XM_Quit(SongID); + + Description: + Stops song/SFX. Free ID + Requires: + Song_ID ID of song/SFX you want to quit. + + Returns: + Nothing. + +---------------------------------------------------------------------------- +int XM_GetSampleAddress(VabID,Sample); + + Description: + Returns the SPU address of sample n in a VAB + + Requires: + VabID ID of VAB file you want to use + Sample Sample number in VAB ID (as in XM file) + Returns: + SPU Address + +---------------------------------------------------------------------------- +void XM_PlaySample(Address,Channel,VolL,VolR,Pitch); + + Description: + Basic routine to play a sample in SPU RAM + Requires: + Address SPU Address of sample (see XM_GetSampleAddress) + Channel 0-23 + VolL Left volume (-0x3fff > + 0x3fff) + VolR Right volume (-0x3fff > + 0x3fff) + Pitch 0x1000 = 44khz sample, 0x800 = 22khz... + Returns: + Nothing + +---------------------------------------------------------------------------- +void XM_StopSample(Channel); + + Description: + Key off a sample on a channel + Requires: + Channel Channel to key off (0-23) + Returns: + Nothing + +---------------------------------------------------------------------------- +int XM_GetFreeVAB(void); + + Description: + Returns a free VAB slot. + Use this if using your own SPU allocation. + Requires: + Nothing + Returns: + VAB slot 0-7 + -1 no free slots + +---------------------------------------------------------------------------- +void XM_SetVAGAddress(VabID,slot,addr); + + Description: + Store SPU address of sample in XMPlayer data + Use this if using your own SPU allocation. + Requires: + VabID Returned from XM_GetFreeVAB + slot 0-127. Position in XMPlayer data to store addr + (normally the same value as the position of + the sample in the original XM file) + addr Address of VAG in SPU RAM + Returns: + Nothing + +---------------------------------------------------------------------------- +XM_VABInfo VInfo; +XM_VABInfo *VInf; +VInf=&VInfo; + +int XM_GetVABSampleInfo(VInfo,Header,Body,slot); + + Description: + Gets a VAG start address and size from a VAB + file. + Use this, XM_SetVAGAddress and XM_GetFreeVAB + to use your own SPU memory management code. + Requires: + VInfo Pointer to XM_VABInfo structure. + Header Address of VH + Body Address of VB + slot Sample within VAB to retrieve data from + (0 = first, 1=second.....) + + Returns: + 0 Data Stored OK. + VInfo.Address Address of VAG + VInfo.Size Size of VAG + + -1 No VAG data (slot is greater than number of + VAG's) + +---------------------------------------------------------------------------- +void XM_CloseVAB2(VabID); + + Description: + Shuts down VAB + Same as XM_CloseVAB, but only use if you are + using your own SPU memory management code. + (See XM_GetVABSampleInfo,XM_SetVAGAddress and + XM_GetFreeVAB) + Requires: + VAB ID + Returns: + Nothing + +---------------------------------------------------------------------------- +int XM_GetSongSize(void) + + Description: + Returns the size of the "Song" structure. + This is needed for the user to do memory + allocation. + + Requires: + Nothing. + Returns: + Song structure size + +---------------------------------------------------------------------------- +void XM_SetSongAddress(u_char *Address) + + Description: + Sets the address of the song structure that + the user has allocated, using the size from + XM_GetSongSize(). The more times the user + allocates song structures, and calls this + function, the more Song ID's will become + available (max 24) + + Requires: + Address of allocated song structure. + + Returns: + Nothing. + +---------------------------------------------------------------------------- +void XM_FreeSongID(void) + + Description: + Free's the last song ID. Call this after + freeing the song structure memory. This + call also means that the user has one less + song ID available. + + Requires: + Nothing. + Returns: + Nothing. + +---------------------------------------------------------------------------- +void XM_FreeAllSongIDs(void) + + Description: + Free's ALL song ID's. Call this after freeing + memory used by all song structure mallocs. + This is the same as XM_FreeSongID, but + clears ALL song ID's. + + Requires: + Nothing. + Returns: + Nothing. + +---------------------------------------------------------------------------- +int XM_GetFileHeaderSize(void) + + Description: + Returns the size of the "Header" structure. + This is needed for the user to do memory + allocation. + + Requires: + Nothing. + Returns: + Header structure size + +---------------------------------------------------------------------------- +void XM_SetFileHeaderAddress(u_char *Address) + + Description: + Sets the address of the header structure that + the user has allocated, using the size from + XM_GetFileHeaderSize(). The more times the user + allocates header structures, and calls this + function, the more Header ID's will become + available (max 8). + This is known as XM_ID in the above calls. + + Requires: + Address of allocated header structure. + + Returns: + Nothing. + +---------------------------------------------------------------------------- +void XM_FreeFileHeaderID(void) + + Description: + Free's the last header ID. Call this after + freeing the header structure memory. This + call also means that the user has one less + header ID available. + + Requires: + Nothing. + Returns: + Nothing. + +---------------------------------------------------------------------------- +void XM_FreeAllHeaderIDs(void) + + Description: + Free's ALL header ID's. Call this after freeing + memory used by all header structure mallocs. + This is the same as XM_FreeHeaderID, but + clears ALL header ID's. + + Requires: + Nothing. + Returns: + Nothing. + +---------------------------------------------------------------------------- +void XM_SetSpeed(int Song_ID,u_short Speed); + + Description: + Sets the song speed. + Note - this can get overridden by xm data + + Requires: + Song_ID ID of song to modify speed + Speed New speed + + Returns: + Nothing. + +---------------------------------------------------------------------------- +void XM_SetBPM(int Song_ID,u_short BPM); + + Description: + Sets the song BPM. + Note - this can get overridden by xm data + + Requires: + Song_ID ID of song to modify BPM + BPM New BPM + + Returns: + Nothing. + +---------------------------------------------------------------------------- +void XM_SetMono(void); + + Description: + Sets mono output (Left and Right volumes are + averaged, and the result sent to both + left and right outputs) + Requires: + Nothing. + Returns: + Nothing. + +---------------------------------------------------------------------------- +void XM_SetStereo(void); + + Description: + Sets stereo output + Requires: + Nothing. + Returns: + Nothing. + +---------------------------------------------------------------------------- + +End-Of-File