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