GBA: Initialization/Main Functions

Macros
#define	MM_SIZEOF_ACTCH   28
	Size of act channel (bytes)
#define	MM_SIZEOF_MIXCH   24
	Size of mix channel (bytes)
#define	MM_SIZEOF_MODCH   40
	Size of mod channel (bytes)

Enumerations
enum	mm_mixlen_enum { MM_MIXLEN_8KHZ }
	Precalculated mix buffer lengths (in bytes) More...

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

Detailed Description

Enumeration Type Documentation

mm_mixlen_enum

enum mm_mixlen_enum

Precalculated mix buffer lengths (in bytes)

Enumerator
MM_MIXLEN_8KHZ	(8121 hz) (10512 hz) (13379 hz) (15768 hz) (18157 hz) (21024 hz) (26758 hz) (31536 hz)

Function Documentation

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.

mmInit()

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

Parameters

setup

Maxmod setup configuration.

Example:

// Mixing buffer (globals should go in IWRAM)
// Mixing buffer SHOULD be in IWRAM, otherwise the CPU load will
// _drastially_ increase.
u8 myMixingBuffer[ MM_MIXLEN_16KHZ ] __attribute((aligned(4)));
 
void maxmodInit( void )
{
    irqSet( IRQ_VBLANK, mmVBlank );
 
    u8* myData;
    mm_gba_system mySystem;
 
    // Allocate data for channel buffers & wave buffer (malloc'd data goes
    // to EWRAM).
    // Use the SIZEOF definitions to calculate how many bytes to reserve
    myData = (u8*)malloc( 8 * (MM_SIZEOF_MODCH
                               +MM_SIZEOF_ACTCH
                               +MM_SIZEOF_MIXCH)
                               +MM_MIXLEN_16KHZ );
 
    // setup system info
    // 16KHz software mixing rate, select from mm_mixmode
    mySystem.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.
    mySystem.mod_channel_count = 8;
    mySystem.mix_channel_count = 8;
 
    // Assign memory blocks to pointers
    mySystem.module_channels   = (mm_addr)(myData+0);
    mySystem.active_channels   = (mm_addr)(myData+(8*MM_SIZEOF_MODCH));
    mySystem.mixing_channels   = (mm_addr)(myData+(8*(MM_SIZEOF_MODCH
                                                      +MM_SIZEOF_ACTCH)));
    mySystem.mixing_memory     = (mm_addr)myMixingBuffer;
    mySystem.wave_memory       = (mm_addr)(myData+(8*(MM_SIZEOF_MODCH
                                                      +MM_SIZEOF_ACTCH
                                                      +MM_SIZEOF_MIXCH)));
    // Pass soundbank address
    mySystem.soundbank         = (mm_addr)soundbank;
 
    // Initialize Maxmod
    mmInit( &mySystem );
}

mmInitDefault()

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

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.

Parameters

handler

Function pointer to event handler.

mmSetVBlankHandler()

void mmSetVBlankHandler

(

void *

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
}