XGM2 sound driver. More...

Functions
void	XGM2_loadDriver (bool waitReady)
	Load the XGM2 sound driver.
void	XGM2_unloadDriver (void)
	Unload the XGM2 sound driver.
bool	XGM2_isPlaying (void)
	Returns play music state.
void	XGM2_load (const u8 *song)
	Load the specified XGM2 music blob (prepare for play, useful for multi tracks XGM2 music)
void	XGM2_load_FAR (const u8 *song, const u32 len)
	Same as XGM2_load(..) except it supports access through bank switch.
void	XGM2_playTrack (const u16 track)
	Start playing the specified track (need to call XGM2_load(..) first)
void	XGM2_play (const u8 *song)
	Start playing the specified XGM2 music blob (fast play for single track XGM2 music)
void	XGM2_play_FAR (const u8 *song, const u32 len)
	Same as XGM2_play(..) except it supports music accessible through bank switch.
void	XGM2_stop (void)
	Stop playing music (cannot be resumed).
void	XGM2_pause (void)
	Pause playing music, music can be resumed by calling XGM2_resume(). Note that due to the nature of the music chip (FM synthesis), resume play operation will never be perfect and some notes will miss until next key-on event occurs.
void	XGM2_resume (void)
	Resume playing music after pausing with XGM2_stop(). Note that due to the nature of the music chip (FM synthesis), resume play operation will never be perfect and some notes will miss until next key-on event occurs.
u8	XGM2_isPlayingPCM (const u16 channel_mask)
	Return play status of specified PCM channel.
void	XGM2_playPCM (const u8 *sample, const u32 len, const SoundPCMChannel channel)
	Play a PCM sample on specified channel (XGM2 music player driver). The method automatically select the channel to use.
void	XGM2_playPCMEx (const u8 *sample, const u32 len, const SoundPCMChannel channel, const u8 priority, const bool halfRate, const bool loop)
	Play a PCM sample on specified channel (XGM2 music player driver). If a sample was currently playing on this channel then priority of the newer sample should be are compared then it's stopped and the new sample is played instead. Note that music may use the first PCM channel so it's better to use channel 2 to 4 for SFX.
void	XGM2_stopPCM (const SoundPCMChannel channel)
	Stop play PCM on specified channel (XGM2 music player driver). No effect if no sample was currently playing on this channel.
bool	XGM2_isProcessingFade (void)
void	XGM2_fadeIn (const u16 numFrame)
	Process music volume "fade-in" effect, must be called right after a "start play" or "resume" command. Gradually increase FM and PSG volume starting from 0 up to the current volume levels.
void	XGM2_fadeOut (const u16 numFrame)
	Process music volume "fade-out" effect. Gradually decrease FM and PSG volume starting from current levels down to 0.
void	XGM2_fadeOutAndStop (const u16 numFrame)
	Process music volume "fade-out" effect and stop. Gradually decrease FM and PSG volume starting from current levels down to 0, then issue a 'stop play' command.
void	XGM2_fadeOutAndPause (const u16 numFrame)
	Process music volume "fade-out" effect and pause. Gradually decrease FM and PSG volume starting from current levels down to 0, then issue a 'stop play' command.
void	XGM2_fadeTo (const u16 fmVolume, const u16 psgVolume, const u16 numFrame)
	Process a specific music volume "fade" effect. Gradually change FM and PSG volume starting from current levels to the specified ones.
void	XGM2_setLoopNumber (const s8 value)
	Set the loop number for music with loop command. Default value is -1 for pseudo unfinite (255) loops plays. A value of 0 means single play without any loop, 1 = single play + 1 loop...
u32	XGM2_getElapsed (void)
	Return the elapsed play time since the last XGM2_play(..) call. The returned value is in music frame which can be 50/60 per second depending the base music play rate (NTSC/PAL).
u16	XGM2_getMusicTempo (void)
	Get the current music tempo (in tick per second). Default value is 60 or 50 depending the system is NTSC or PAL. This method is meaningful only if you use the automatic music sync mode (see XGM2_setManualSync() method) which is the default mode. Note that using specific tempo (not 60 or 50) will affect performance of DMA contention and external command parsing so it's recommended to stand with default one.
void	XGM2_setMusicTempo (const u16 value)
	Set the music tempo (in tick per second). Default value is 60 or 50 depending the system is NTSC or PAL. This method is meaningful only if you use the automatic music sync mode (see XGM2_setManualSync() method) which is the default mode. Note that using specific tempo (not 60 or 50) can completely distord FM instruments sound and affect performance of DMA contention and external command parsing so it's recommended to stand with default one.
void	XGM2_setFMVolume (const u16 value)
	Set the volume level for the FM music part.
void	XGM2_setPSGVolume (const u16 value)
	Set the volume level for the PSG music part.
bool	XGM2_isPAL (const u8 *xgm2)
	Returns TRUE if specified xgm2 use PAL timing.
u16	XGM2_getCPULoad (const bool mean)
	Returns an estimation of the Z80 CPU load (XGM2 driver).
u16	XGM2_getDMAWaitTime (const bool mean)
	Returns an estimation of the Z80 CPU time spent in waiting for DMA completion (see Z80_setBusProtection(bool) method).
u16	XGM2_getDebugFrameCounter (void)
	Returns the internal frame counter (v-int process number). Debug function to verify the driver is working optimally.
u16	XGM2_getDebugPCMRate (void)
	Returns the real PCM playback rate (XGM2 driver). Debug function to verify the driver is working optimally.
u8	XGM2_getDebugMissedFrames (void)
	Returns the number of missed frames since last startPlay command. Debug function to verify the driver is working optimally.
u8	XGM2_getDebugProcessDuration (const u16 ind)
	Returns the ending process time in number of sample for the specified v-int process (v-int process number). Debug function to verify the driver is working optimally.

Detailed Description

XGM2 sound driver.

Author:: Stephane Dallongeville

Date:: 04/2023

This unit provides methods to use the XGM2 (eXtended Genesis Music) sound driver.
It takes VGM (or XGM2) file as input to play music.
It supports 3 PCM channels at either 13.3 Khz or 6.65 Khz and envelop control for both FM and PSG.
It allows to play SFX through PCM with 16 level of priority.
The driver supports renforced protection against DMA contention.

Function Documentation

void XGM2_fadeIn ( const u16 numFrame )

Process music volume "fade-in" effect, must be called right after a "start play" or "resume" command.
Gradually increase FM and PSG volume starting from 0 up to the current volume levels.

Parameters:

numFrame Duration of music fade-in effect in number of frame.

void XGM2_fadeOut ( const u16 numFrame )

Process music volume "fade-out" effect.
Gradually decrease FM and PSG volume starting from current levels down to 0.

Parameters:

numFrame Duration of music fade-out effect in number of frame.

void XGM2_fadeOutAndPause ( const u16 numFrame )

Process music volume "fade-out" effect and pause.
Gradually decrease FM and PSG volume starting from current levels down to 0, then issue a 'stop play' command.

Parameters:

numFrame Duration of music fade-out effect in number of frame.

void XGM2_fadeOutAndStop ( const u16 numFrame )

Process music volume "fade-out" effect and stop.
Gradually decrease FM and PSG volume starting from current levels down to 0, then issue a 'stop play' command.

Parameters:

numFrame Duration of music fade-out effect in number of frame.

void XGM2_fadeTo	(	const u16	fmVolume,
		const u16	psgVolume,
		const u16	numFrame
	)

Process a specific music volume "fade" effect.
Gradually change FM and PSG volume starting from current levels to the specified ones.

Parameters:

fmVolume	FM volume to reach at the end of fade effect.
psgVolume	PSG volume to reach at the end of fade effect.
numFrame	Duration of music fade effect in number of frame.

u16 XGM2_getCPULoad ( const bool mean )

Returns an estimation of the Z80 CPU load (XGM2 driver).

Parameters:

mean	if set to TRUE then return a mean load computed on the last 8 frames otherwise return instant last frame load

u16 XGM2_getDMAWaitTime ( const bool mean )

Returns an estimation of the Z80 CPU time spent in waiting for DMA completion (see Z80_setBusProtection(bool) method).

Parameters:

mean	if set to TRUE then return a mean wait computed on the last 8 frames otherwise return instant last frame DMA wait

u32 XGM2_getElapsed ( void )

Return the elapsed play time since the last XGM2_play(..) call.
The returned value is in music frame which can be 50/60 per second depending the base music play rate (NTSC/PAL).

See also:: XGM2_play(..); XGM2_playTrack(..); XGM2_setMusicTempo(..)

u16 XGM2_getMusicTempo ( void )

Get the current music tempo (in tick per second).
Default value is 60 or 50 depending the system is NTSC or PAL.
This method is meaningful only if you use the automatic music sync mode (see XGM2_setManualSync() method) which is the default mode.
Note that using specific tempo (not 60 or 50) will affect performance of DMA contention and external command parsing so it's recommended to stand with default one.

See also:: XGM2_setMusicTempo

u8 XGM2_isPlayingPCM ( const u16 channel_mask )

Return play status of specified PCM channel.

Parameters:

channel_mask Channel(s) we want to retrieve play state.
SOUND_PCM_CH1_MSK = channel 1
SOUND_PCM_CH2_MSK = channel 2
SOUND_PCM_CH3_MSK = channel 3

You can combine mask to retrieve state of severals channels at once:
isPlayingPCM(SOUND_PCM_CH1_MSK | SOUND_PCM_CH2_MSK)
will actually return play state for channel 1 and channel 2.

Returns:: Return the channel mask of current playing channel(s).
For instance it returns (SOUND_PCM_CH1_MSK | SOUND_PCM_CH3_MSK) if channels 1 and 3 are currently playing.

See also:: XGM2_playPCM; XGM2_stopPCM

bool XGM2_isProcessingFade ( void )

Returns:: TRUE if currently processing a volume fade effect, FALSE otherwise.

void XGM2_load ( const u8 * song )

Load the specified XGM2 music blob (prepare for play, useful for multi tracks XGM2 music)

Parameters:

song	XGM2 music blob address

See also:: XGM2_playTrack; XGM2_stop; XGM2_load_FAR

void XGM2_load_FAR	(	const u8 *	song,
		const u32	len
	)

Same as XGM2_load(..) except it supports access through bank switch.

Parameters:

song	XGM2 music blob address
len	XGM2 music blob size (in byte)

See also:: XGM2_playTrack; XGM2_stop; XGM2_load

void XGM2_loadDriver ( bool waitReady )

Load the XGM2 sound driver.

Don't use this method directly, use Z80_loadDriver(..) instead.

void XGM2_pause ( void )

Pause playing music, music can be resumed by calling XGM2_resume().
Note that due to the nature of the music chip (FM synthesis), resume play operation will never be perfect and some notes will miss until next key-on event occurs.

See also:: XGM2_resume; XGM2_stop

void XGM2_play ( const u8 * song )

Start playing the specified XGM2 music blob (fast play for single track XGM2 music)

Parameters:

song	XGM2 track address.

See also:: XGM2_stop; XGM2_play_FAR; XGM2_load

void XGM2_play_FAR	(	const u8 *	song,
		const u32	len
	)

Same as XGM2_play(..) except it supports music accessible through bank switch.

Parameters:

song	XGM2 track address.
len	XGM2 track size (in byte)

See also:: XGM2_stop; XGM2_play; XGM2_load_FAR

void XGM2_playPCM	(	const u8 *	sample,
		const u32	len,
		const SoundPCMChannel	channel
	)

Play a PCM sample on specified channel (XGM2 music player driver).
The method automatically select the channel to use.

Parameters:

sample	Sample address, should be 256 bytes boundary aligned (SGDK automatically align WAV resource as needed)
len	Size of sample in bytes, should be a multiple of 256 (SGDK automatically adjust WAV resource size as needed)
channel	Channel to use to play sample. SOUND_PCM_CH_AUTO = auto selection from current channel usage SOUND_PCM_CH1 = channel 1 (usually used by music) SOUND_PCM_CH2 = channel 2 SOUND_PCM_CH3 = channel 3

See also:: XGM2_playPCMEx; XGM2_stopPCM; XGM2_isPlayingPCM

void XGM2_playPCMEx	(	const u8 *	sample,
		const u32	len,
		const SoundPCMChannel	channel,
		const u8	priority,
		const bool	halfRate,
		const bool	loop
	)

Play a PCM sample on specified channel (XGM2 music player driver).
If a sample was currently playing on this channel then priority of the newer sample should be are compared then it's stopped and the new sample is played instead.
Note that music may use the first PCM channel so it's better to use channel 2 to 4 for SFX.

Parameters:

sample	Sample address, should be 256 bytes boundary aligned (SGDK automatically align WAV resource as needed)
len	Size of sample in bytes, should be a multiple of 256 (SGDK automatically adjust WAV resource size as needed)
channel	Channel to use to play sample. SOUND_PCM_CH_AUTO = auto selection from current channel usage SOUND_PCM_CH1 = channel 1 (usually used by music) SOUND_PCM_CH2 = channel 2 SOUND_PCM_CH3 = channel 3
priority	Value should go from 0 to 15 where 0 is lowest priority and 15 the highest one. If the channel was already playing the priority is used to determine if the new SFX should replace the current one (new priority >= old priority).
halfRate	Set to TRUE to play the sample at half rate (6.65 Khz) instead of default 13.3 Khz
loop	Set to TRUE to enable looping sample play

See also:: XGM2_playPCM; XGM2_stopPCM; XGM2_isPlayingPCM

void XGM2_playTrack ( const u16 track )

Start playing the specified track (need to call XGM2_load(..) first)

Parameters:

track track index (for multi track XGM2 music blob)

See also:: XGM2_load; XGM2_load_FAR; XGM2_stop

void XGM2_resume ( void )

Resume playing music after pausing with XGM2_stop().
Note that due to the nature of the music chip (FM synthesis), resume play operation will never be perfect and some notes will miss until next key-on event occurs.

See also:: XGM2_pause; XGM2_stop

void XGM2_setFMVolume ( const u16 value )

Set the volume level for the FM music part.

Parameters:

value volume level (0 to 100)

See also:: XGM2_setPSGVolume

void XGM2_setMusicTempo ( const u16 value )

Set the music tempo (in tick per second).
Default value is 60 or 50 depending the system is NTSC or PAL. This method is meaningful only if you use the automatic music sync mode (see XGM2_setManualSync() method) which is the default mode.
Note that using specific tempo (not 60 or 50) can completely distord FM instruments sound and affect performance of DMA contention and external command parsing so it's recommended to stand with default one.