xm64.h File Reference

Efficient XM module player. More...

Go to the source code of this file.

Data Structures
struct	xm64player_t
	Player of a .XM64 file. More...
struct	xm64player_t.seek

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.

This module implements a player of the .XM64 file format, which is based on the Fast Tracker II .XM module format.

The playback relies on the mixer (mixer.h), as it uses it to perform the actual channel playing and mixing. It will use one mixer channel per each XM channel. You need to initialize the mixer (via mixer_init) before using xm64player_t.

The actual XM player is based on libxm (https://github.com/Artefact2/libxm), a very fast and accurate XM player library that has been adapted for usage in libdragon on N64. The main changes are:

• Usage of the custom XM64 format. This formats is a serialization of the internal libxm context (xm_context_t), and allows us to do some required preprocessing (such as unrolling ping-pong loops which are not supported by the mixer), and to load the whole file with one single memory allocation to avoid heap fragmentation.
• Loading of XM patterns is done on the fly rather than all in advance, to save RAM. Patterns are also recompressed using a RLE derivative which is more efficient and still fast to decompress.
• Waveforms ("samples" in XM) are not preloaded, but they are streamed off disk when necessary, thanks to the mixer API that allows to do it very easily. This saves a lot of RAM.
• The actual sample generation code of libxm is not used, as the playback code is based on the mixer.
• XM64 contains also the precalculated amount of sample buffer memory required for playing back, per each channel. This allows for precise memory allocations even within the mixer.

---

Data Structure Documentation

xm64player_t

struct xm64player_t

Player of a .XM64 file.

This structure holds the state a player of a XM64 module. It can be initialized using xm64player_open, and played with xm64player_play.

See the rest of this module for more functions.

Data Fields
xm_context_t *	ctx	libxm context
waveform_t *	waves	array of all waveforms (one per XM "sample")
int	nwaves	number of waves (XM "samples")
FILE *	fh	open handle of XM64 file
int	first_ch	first channel used in the mixer
bool	playing	playing flag
bool	stop_requested	user requested stop playing
bool	looping	true if the XM is configured to loop
struct xm64player_t.seek	seek	seeking to be performed

xm64player_t.seek

struct xm64player_t.seek

Data Fields
int	patidx
int	row
int	tick

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.