xm64.c File Reference

Efficient XM module player. More...

Functions
void	xm64player_open (xm64player_t *player, const char *fn)
	Open a XM64 module file and prepare for playback.
int	xm64player_num_channels (xm64player_t *player)
	Get the number of channels in the XM64 file.
void	xm64player_set_loop (xm64player_t *player, bool loop)
	Configure a XM64 file for looping.
void	xm64player_play (xm64player_t *player, int first_ch)
	Start playing the XM64 module.
void	xm64player_stop (xm64player_t *player)
	Stop XM playback.
void	xm64player_tell (xm64player_t *player, int *patidx, int *row, float *secs)
	Read the current position of the XM module.
void	xm64player_seek (xm64player_t *player, int patidx, int row, int tick)
	Seek to a specific position of the XM module.
void	xm64player_set_vol (xm64player_t *player, float volume)
	Change the volume of the player.
void	xm64player_set_effect_callback (xm64player_t *player, void(*cb)(void *, uint8_t, uint8_t, uint8_t), void *ctx)
	Set a custom effect callback to allow music synchronization.
void	xm64player_close (xm64player_t *player)
	Close and deallocate the XM64 player.

Detailed Description

Efficient XM module player.

Function Documentation

xm64player_open()

void xm64player_open	(	xm64player_t *	player,
		const char *	fn
	)

Open a XM64 module file and prepare for playback.

This function requires the mixer to have been already initialized (via mixer_init).

Parameters

player	Pointer to the xm64player_t player structure to use
fn	Filename of the XM64 (with filesystem prefix). Currently, only files on DFS ("rom:/") are supported.

xm64player_num_channels()

int xm64player_num_channels

(

xm64player_t *

player

)

Get the number of channels in the XM64 file.

Notice that the player needs to use one mixer channel per each XM64 channel.

xm64player_set_loop()

void xm64player_set_loop	(	xm64player_t *	player,
		bool	loop
	)

Configure a XM64 file for looping.

By default, XM64 files will be played in loop. Use this function to disable looping.

Parameters

[in]	player	XM64 player
[in]	loop	true to enable looping, false to disable looping.

xm64player_play()

void xm64player_play	(	xm64player_t *	player,
		int	first_ch
	)

Start playing the XM64 module.

Notice that the player needs to use one mixer channel per each XM64 channel.

Parameters

player	XM64 player
first_ch	Index of the first mixer channel to use for playback.

xm64player_stop()

void xm64player_stop

(

xm64player_t *

player

)

Stop XM playback.

The XM module will keep the current position. Use xmplayer_play to continue playback.

xm64player_tell()

void xm64player_tell	(	xm64player_t *	player,
		int *	patidx,
		int *	row,
		float *	secs
	)

Read the current position of the XM module.

The function returns the current position expressed as pattern/row (internal XM position), and also expressed as number of seconds. You can pass NULL to information that you are not interested in receiving.

Parameters

	player	XM64 player
[out]	patidx	Index of the XM pattern
[out]	row	Row within the pattern
[out]	secs	Total number of seconds

xm64player_seek()

void xm64player_seek	(	xm64player_t *	player,
		int	patidx,
		int	row,
		int	tick
	)

Seek to a specific position of the XM module.

Seeking in XM module is "broken by design". What this function does is to move the playback cursor to the specified position, but it doesn't take into effect what samples / effects should be active at the seeking point.

Parameters

player	XM64 player
patidx	Index of the XM pattern to seek to
row	Row within the pattern to seek to
tick	Tick within the row to seek to

xm64player_set_vol()

void xm64player_set_vol	(	xm64player_t *	player,
		float	volume
	)

Change the volume of the player.

This allows to tune the volume of playback. The default volume is 1.0; smaller values will lower the volume, higher values will amplificate (but may clip).

xm64player_set_effect_callback()

void xm64player_set_effect_callback	(	xm64player_t *	player,
		void(*)(void *, uint8_t, uint8_t, uint8_t)	cb,
		void *	ctx
	)

Set a custom effect callback to allow music synchronization.

This function configures a callback that will be called whenever the player finds an unknown / unsupported effect in any channel. These unknown effects can be used to add custom "sync cues" in the music score, and synchronize graphic effects or gameplay logic to them.

There are many unused effect letters in XM format. For instance, a good choice can be effect Xxx which is used as modplug hack for MIDI support, but is unimplemented by standard XM players like this one.

The callback will be called passing as arguments a custom context, the channel number, and the effect code and the effect parameter. The effect code is the code in extended hex format (A-F are 10-15 as in normal hex, but then G-Z are 16-35), while the effect parameter is one free byte that can be inserted in the music score.