Headless: Initialization/Main Functions

Functions
bool	mmEnd (void)
	Deinitializes Maxmod.
void	mmFrame (mm_addr buffer, mm_word total_samples)
	This is the main routine-function that processes music and updates the sound output.
mm_callback	mmGetEventHandler (void)
	Returns the event handler previously installed by the user.
mm_word	mmGetModuleCount (void)
	Returns the number of modules available in the soundbank.
mm_word	mmGetSampleCount (void)
	Returns the number of samples available in the soundbank.
bool	mmInitDefault (mm_addr soundbank, mm_word number_of_channels, mm_word sample_rate)
	Initialize Maxmod with default settings.
void	mmSetEventHandler (mm_callback handler)
	Install handler to receive song events.

Detailed Description

Function Documentation

mmEnd()

bool mmEnd

(

void

)

Deinitializes Maxmod.

If Maxmod was initialized with mmInitDefault(), it also frees the memory allocated by it.

If Maxmod was initialized with mmInit(), the user is responsible for freeing the memory passed to it when Maxmod was initialized.

Returns

It returns true on success, false on error.

mmFrame()

void mmFrame	(	mm_addr	buffer,
		mm_word	total_samples
	)

This is the main routine-function that processes music and updates the sound output.

This function must be called whenever the user wants Maxmod to generate new samples and write them to a buffer.

The output format is currently hardcoded to 8-bit signed samples. The output is stereo, and left and right channels are interleaved (L, R, L, R ...).

Parameters

buffer	Destination buffer. The size must be total_samples * 2.
total_samples	The number of samples to save to the buffer. In total, it saves total_samples * 2 because the output is stereo.

mmGetEventHandler()

mm_callback mmGetEventHandler

(

void

)

Returns the event handler previously installed by the user.

Returns

Function pointer to the event handler currently installed.

mmGetModuleCount()

mm_word mmGetModuleCount

(

void

)

Returns the number of modules available in the soundbank.

Returns

The number of modules.

mmGetSampleCount()

mm_word mmGetSampleCount

(

void

)

Returns the number of samples available in the soundbank.

Note

This number includes the samples used by all the songs in the soundbank, not just the sound effects in WAV format.

Returns

The number of samples.

mmInitDefault()

bool mmInitDefault	(	mm_addr	soundbank,
		mm_word	number_of_channels,
		mm_word	sample_rate
	)

Initialize Maxmod with default settings.

Parameters

soundbank	Memory address of soundbank (in ROM). A soundbank file can be created with the Maxmod Utility.
number_of_channels	Number of module/mixing channels to allocate. Must be greater or equal to the channel count in your modules. The maximum value allowed is 256.
sample_rate	The sample rate to be used by Maxmod. Any value is allowed.

Returns

It returns true on success, false on error.

mmSetEventHandler()

void mmSetEventHandler

(

mm_callback

handler

)

Install handler to receive song events.

Use this function to receive song events. Song events occur in two situations. One is by special pattern data in a module (which is triggered by SFx/EFx commands). The other occurs when a module finishes playback (in MM_PLAY_ONCE mode).

During the song event, Maxmod is in the middle of module processing. Avoid using any Maxmod related functions during your song event handler since they may cause problems in this situation.

Check the song events tutorial in the documentation for more information.

Parameters

handler

Function pointer to event handler.