SBSPSS/tools/mod/Calls.txt

713 lines
18 KiB
Plaintext
Raw Normal View History

2000-09-18 16:26:56 +02:00
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