GBA: Module Playback

Functions
mm_bool	mmActive (void)
	Used to determine if a module is playing.
mm_word	mmGetPosition (void)
	Get current pattern order being played.
mm_word	mmGetPositionRow (void)
	Get current row being played.
mm_word	mmGetPositionTick (void)
	Get current number of elapsed ticks in the row being played.
void	mmPause (void)
	Pauses playback of the active module.
void	mmPlayMAS (uintptr_t address, mm_word mode, mm_word layer)
	Play individual MAS file from RAM.
void	mmPlayModule (uintptr_t address, mm_word mode, mm_word layer)
	Play individual MAS file from RAM.
static void	mmPosition (mm_word position)
	Set playback position.
void	mmResume (void)
	Resume module playback.
void	mmSetModulePitch (mm_word pitch)
	Change the master pitch scale for module playback.
void	mmSetModuleTempo (mm_word tempo)
	Change the master tempo for module playback.
void	mmSetModuleVolume (mm_word volume)
	Use this function to change the master volume scale for module playback.
static void	mmSetPosition (mm_word position)
	Set the current sequence [aka order-list] position for the active module.
void	mmSetPositionEx (mm_word position, mm_word row)
	Set the current playback position.
void	mmStart (mm_word module_ID, mm_pmode mode)
	Begins playback of a module.
void	mmStop (void)
	Stops playback of the active module.

Detailed Description

Function Documentation

mmActive()

mm_bool mmActive

(

void

)

Used to determine if a module is playing.

Returns

Nonzero if a module is currently playing.

mmGetPosition()

mm_word mmGetPosition

(

void

)

Get current pattern order being played.

Returns

The current pattern.

mmGetPositionRow()

mm_word mmGetPositionRow

(

void

)

Get current row being played.

Returns

The current row.

mmGetPositionTick()

mm_word mmGetPositionTick

(

void

)

Get current number of elapsed ticks in the row being played.

Returns

Number of elapsed ticks.

mmPause()

void mmPause

(

void

)

Pauses playback of the active module.

Resume with mmResume().

mmPlayMAS()

void mmPlayMAS	(	uintptr_t	address,
		mm_word	mode,
		mm_word	layer
	)

Play individual MAS file from RAM.

A soundbank is a MSL file that contains one or more MAS files. Each MAS file can contain a sample or a module. This function allows you to play samples or modules without the need for a soundbank.

Normally, Maxmod plays MAS files from the sound bank provided to mmInit(). This function lets you play MAS files outside of that soundbank.

Warning

You need to initialize Maxmod with a valid soundbank, or with mmInitNoSoundbank() if you don't plan on using any soundbank at all.

Parameters

address	Address of the MAS file.
mode	Playback mode: MM_PLAY_ONCE or MM_PLAY_LOOP.
layer	MM_MAIN (main module layer) or MM_JINGLE (sub/jingle layer).

mmPlayModule()

void mmPlayModule	(	uintptr_t	address,
		mm_word	mode,
		mm_word	layer
	)

Play individual MAS file from RAM.

Deprecated:

This function expects the user to pass a pointer to the MAS file skipping the MAS file prefix, which isn't very intuitive. Use mmPlayMAS() instead.

Warning

You need to initialize Maxmod with mmInit() and provide it a valid soundbank even if you plan to use mmPlayModule() to play everything. You can initialize mmInit() passing 0 as the number of modules and sound effects.

Parameters

address	Address of the MAS file, skipping the first few bytes of the prefix. Add sizeof(mm_mas_prefix) to the pointer to your MAS file.
mode	Playback mode: MM_PLAY_ONCE or MM_PLAY_LOOP.
layer	MM_MAIN (main module layer) or MM_JINGLE (sub/jingle layer).

mmPosition()

static void mmPosition ( mm_word  position )

inlinestatic

Set playback position.

Deprecated:

Alias of mmSetPosition().

Parameters

position

New position in module sequence.

mmResume()

void mmResume

(

void

)

Resume module playback.

Pause with mmPause().

mmSetModulePitch()

void mmSetModulePitch

(

mm_word

pitch

)

Change the master pitch scale for module playback.

Specifying 1024 will play the module at its normal pitch. Minimum/Maximum range of the pitch change is +-1 octave.

Range = 0x200 -> 0x800 = 0.5 -> 2.0

Parameters

pitch

New pitch scale. Value = 1024 * 2^(semitones/12)

mmSetModuleTempo()

void mmSetModuleTempo

(

mm_word

tempo

)

Change the master tempo for module playback.

Specifying 1024 will play the module at its normal speed. Minimum and maximum values are 50% (512) and 200% (2048). Note that increasing the tempo will also increase the module processing load.

It uses a fixed point (Q10) value representing tempo.

Range = 0x200 -> 0x800 = 0.5 -> 2.0

Parameters

tempo

New tempo value. Tempo = (speed_percentage * 1024) / 100.

mmSetModuleVolume()

void mmSetModuleVolume

(

mm_word

volume

)

Use this function to change the master volume scale for module playback.

Parameters

volume

New volume level. Ranges from 0 (silent) to 1024 (normal).

mmSetPosition()

static void mmSetPosition ( mm_word  position )

inlinestatic

Set the current sequence [aka order-list] position for the active module.

Parameters

position

New position in module sequence.

mmSetPositionEx()

void mmSetPositionEx	(	mm_word	position,
		mm_word	row
	)

Set the current playback position.

It sets the sequence [aka order-list] position for the active module and the row inside the pattern.

Parameters

position	New position in module sequence.
row	New row in the destination pattern

mmStart()

void mmStart	(	mm_word	module_ID,
		mm_pmode	mode
	)

Begins playback of a module.

For GBA, the module data is read directly from the cartridge space, so no loading is needed.

Parameters

module_ID	Index of module to be played. Values are defined in the soundbank header output. (prefixed with "MOD_")
mode	Mode of playback. Can be MM_PLAY_LOOP (play and loop until stopped manually) or MM_PLAY_ONCE (play until end).

mmStop()

void mmStop

(

void

)

Stops playback of the active module.

Start again (from the beginning) with mmStart().

Any channels used by the active module will be freed.