GBA: Initialization/Main Functions

Enumerations
enum	mm_mixlen_enum {   MM_MIXLEN_8KHZ = 544 ,   MM_MIXLEN_10KHZ = 704 ,   MM_MIXLEN_13KHZ = 896 ,   MM_MIXLEN_16KHZ = 1056 ,   MM_MIXLEN_18KHZ = 1216 ,   MM_MIXLEN_21KHZ = 1408 ,   MM_MIXLEN_27KHZ = 1792 ,   MM_MIXLEN_31KHZ = 2112 }
	Precalculated mix buffer lengths (in bytes) More...

Functions
bool	mmEnd (void)
	Deinitializes Maxmod.
void	mmFrame (void) __attribute((long_call))
	This is the main routine-function that processes music and updates the sound output.
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	mmInit (mm_gba_system *setup)
	Initializes Maxmod with the settings specified.
bool	mmInitDefault (mm_addr soundbank, mm_word number_of_channels)
	Initialize Maxmod with default settings.
void	mmSetEventHandler (mm_callback handler)
	Install handler to receive song events.
void	mmSetVBlankHandler (mm_voidfunc function)
	Installs a custom handler to be processed after the sound DMA is reset.
void	mmVBlank (void)
	This function must be linked directly to the VBlank IRQ.

Detailed Description

Enumeration Type Documentation

mm_mixlen_enum

enum mm_mixlen_enum

Precalculated mix buffer lengths (in bytes)

Enumerator
MM_MIXLEN_8KHZ	(8121 hz)
MM_MIXLEN_10KHZ	(10512 hz)
MM_MIXLEN_13KHZ	(13379 hz)
MM_MIXLEN_16KHZ	(15768 hz)
MM_MIXLEN_18KHZ	(18157 hz)
MM_MIXLEN_21KHZ	(21024 hz)
MM_MIXLEN_27KHZ	(26758 hz)
MM_MIXLEN_31KHZ	(31536 hz)

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

(

void

)

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

For GBA, this function must be called every frame. If a call is missed, garbage will be heard in the output and module processing will be delayed.

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.

mmInit()

bool mmInit

(

mm_gba_system *

setup

)

Initializes Maxmod with the settings specified.

Initialize system. Call once at startup.

For GBA projects, irqInit() should be called before this function.

Example:

// Mixing buffer (globals are usually placed in IWRAM by your toolchain).
// If it isn't placed in IWRAM the CPU load will _drastially_ increase due
// to the slower memory accesses.
u8 myMixingBuffer[MM_MIXLEN_16KHZ] __attribute__((aligned(4)));
 
void maxmodInit(void)
{
    irqInit();
    irqSet(IRQ_VBLANK, mmVBlank);
    irqEnable(IRQ_VBLANK);
 
    // Allocate data for channel buffers & wave buffer (memory returned by
    // malloc is in EWRAM). Use the SIZEOF definitions to calculate how many
    // bytes to reserve
    u8 *myData = malloc((8 * (MM_SIZEOF_MODCH + MM_SIZEOF_ACTCH + MM_SIZEOF_MIXCH))
                        + MM_MIXLEN_16KHZ);
 
    // Setup system information
    mm_gba_system mySystem =
    {
        // 16 KHz software mixing rate, select from the mm_mixmode enum
        .mixing_mode       = MM_MIX_16KHZ;
 
        // Number of module/mixing channels. Higher numbers offer better
        // polyphony at the expense of more memory and/or CPU usage.
        // The maximum number of channels supported is 32.
        .mod_channel_count = 8; // Max number of channels for modules only
        .mix_channel_count = 8; // Max number of channels for modules and effects
 
        // Assign memory blocks to pointers
        .module_channels = (mm_addr)(myData + 0);
        .active_channels = (mm_addr)(myData + (8 * MM_SIZEOF_MODCH));
        .mixing_channels = (mm_addr)(myData + (8 * (MM_SIZEOF_MODCH + MM_SIZEOF_ACTCH)));
 
        .mixing_memory   = (mm_addr)myMixingBuffer;
        .wave_memory     = (mm_addr)(myData + (8 * (MM_SIZEOF_MODCH + MM_SIZEOF_ACTCH
                                                    + MM_SIZEOF_MIXCH)));
 
        // Soundbank address in ROM/RAM
        .soundbank         = (mm_addr)soundbank;
    };
 
    // Initialize Maxmod
    mmInit(&mySystem);
}

Parameters

setup

Maxmod setup configuration.

Returns

It returns true on success, false on error.

mmInitDefault()

bool mmInitDefault	(	mm_addr	soundbank,
		mm_word	number_of_channels
	)

Initialize Maxmod with default settings.

For GBA, this function uses these default settings (and allocates memory): 16KHz mixing rate, channel buffers in EWRAM, wave buffer in EWRAM, and mixing buffer in IWRAM. It also links the VBlank interrupt to mmVBlank with the libgba interrupt handler.

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 32.

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).

Note for GBA projects: 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.

mmSetVBlankHandler()

void mmSetVBlankHandler

(

mm_voidfunc

function

)

Installs a custom handler to be processed after the sound DMA is reset.

If you need to have a function linked to the VBlank interrupt, use this function (the actual VBlank interrupt must be linked directly to mmVBlank).

Parameters

function

Pointer to your VBlank handler.

mmVBlank()

void mmVBlank

(

void

)

This function must be linked directly to the VBlank IRQ.

During this function, the sound DMA is reset. The timing is extremely critical, so make sure that it is not interrupted, otherwise garbage may be heard in the output.

If you need another function to execute after this process is finished, use mmVBlankReturn() to install your handler.

Example setup with libgba system:

void setup_interrupts(void)
{
    irqInit();
    irqSet(IRQ_VBLANK, mmVBlank);
    irqEnable(IRQ_VBLANK);
 
    mmVBlankReturn(myVBlankHandler); // This is optional
}