NDS: ARM9 Initialization/Main Functions

Macros
#define	MMCB_DELETESAMPLE   0x1D
	Command ID to free a sample. See mmSetCustomSoundBankHandler().
#define	MMCB_DELETESONG   0x1C
	Command ID to free a song. See mmSetCustomSoundBankHandler().
#define	MMCB_SAMPREQUEST   0x1B
	Command ID to load a sample. See mmSetCustomSoundBankHandler().
#define	MMCB_SONGREQUEST   0x1A
	Command ID to load a song. See mmSetCustomSoundBankHandler().

Functions
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_ds_system *system)
	Initializes Maxmod with the settings specified.
bool	mmInitDefault (const char *soundbank_file)
	Initialize Maxmod with default settings.
bool	mmInitDefaultMem (mm_addr soundbank)
	Initialize Maxmod with default settings.
mm_word	mmLoad (mm_word module_ID)
	Loads a module into memory for playback.
mm_word	mmLoadEffect (mm_word sample_ID)
	Loads a sound effect into memory for playback.
void	mmLockChannels (mm_word bitmask)
	Lock audio channels to prevent Maxmod from using them.
void	mmSelectMode (mm_mode_enum mode)
	Switches the audio mode for Maxmod DS.
void	mmSetCustomSoundBankHandler (mm_callback p_loader)
	Install a custom routine to interface with the soundbank data.
void	mmSetEventHandler (mm_callback handler)
	Install handler to receive song events.
void	mmSoundBankInFiles (const char *filename)
	Setup the standard interface for a soundbank that is loaded in the file system.
void	mmSoundBankInMemory (mm_addr address)
	Enable the standard interface for a soundbank that is loaded into memory.
mm_word	mmUnload (mm_word module_ID)
	Unloads and frees memory space occupied by a module.
mm_word	mmUnloadEffect (mm_word sample_ID)
	Unloads a sound effect and frees the memory if the reference count becomes zero.
void	mmUnlockChannels (mm_word bitmask)
	Unlocks audio channels to allow Maxmod to use them.

Detailed Description

Function Documentation

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_ds_system *

system

)

Initializes Maxmod with the settings specified.

Initialize system. Call once at startup.

For DS projects, you must also setup a soundbank interface with one of the mmSoundBank* functions.

Example:

void maxmodInit(void)
{
    mm_ds_system sys;
 
    // Number of modules in your soundbank (defined in output header)
    sys.mod_count = MSL_NSONGS;
 
    // Number of samples in your soundbank (defined in output header)
    sys.samp_count= MSL_NSAMPS;
 
    // Memory bank, allocate BANKSIZE (or NSONGS+NSAMPS) words
    sys.mem_bank = malloc(MSL_BANKSIZE * 4);
 
    // Select FIFO channel
    sys.fifo_channel = FIFO_MAXMOD;
 
    // Initialize maxmod
    mmInit(&sys);
 
    mmSoundBankInMemory((mm_addr)my_soundbank);
 
    // or
    //
    //mmSoundBankInFiles("my_soundbank.msl");
}

Parameters

system

Maxmod setup configuration.

Returns

It returns true on success, false on error.

mmInitDefault()

bool mmInitDefault

(

const char *

soundbank_file

)

Initialize Maxmod with default settings.

For DS, this function also sets up the internal soundbank interface to use the file specified.

Parameters

soundbank_file

Filename of soundbank. A soundbank file can be created with the Maxmod Utility.

Returns

It returns true on success, false on error.

mmInitDefaultMem()

bool mmInitDefaultMem

(

mm_addr

soundbank

)

Initialize Maxmod with default settings.

This function also sets up the internal soundbank interface to use the file that is located somewhere in memory.

Use this when you have the entire soundbank loaded into memory.

Parameters

soundbank

Address of soundbank data.

Returns

It returns true on success, false on error.

mmLoad()

mm_word mmLoad

(

mm_word

module_ID

)

Loads a module into memory for playback.

Must be used before starting to play a module with mmStart(). If the sound bank is in the filesystem, this function will load the required data from the sound bank and save it in RAM.

It loads all module information and the samples required by it. If any of the samples can't be loaded, all information is freed before returning.

Parameters

module_ID

Index of module to be loaded. Values are defined in the soundbank header output. (prefixed with "MOD_")

Returns

It returns 0 on success and a non-zero value on error.

mmLoadEffect()

mm_word mmLoadEffect

(

mm_word

sample_ID

)

Loads a sound effect into memory for playback.

May be played with mmEffect()/mmEffectEx() afterwards. If the sound bank is in the filesystem, this function will load the required data from the sound bank and save it in RAM.

Parameters

sample_ID

Index of sample to be loaded. Values are defined in the soundbank header output (prefixed with "SFX_)

Returns

It returns 0 on success and a non-zero value on error.

mmLockChannels()

void mmLockChannels

(

mm_word

bitmask

)

Lock audio channels to prevent Maxmod from using them.

This is for when you need to operate on the DS hardware channels directly. Note that if you use this function while music or sound effects are playing, any active notes that are using the channels to be locked will be cut.

Parameters

bitmask

Selection of channels to lock. Bit0 = Channel0, Bit1 = Channel1 ... Bit15 = Channel15

mmSelectMode()

void mmSelectMode

(

mm_mode_enum

mode

)

Switches the audio mode for Maxmod DS.

Hardware mixing offers 16-channel audio with minimal CPU load.

Interpolated mixing extends the capability of the hardware channels by adding linear interpolation in software.

Extended mixing increases the channel count to 30 with software mixing.

Parameters

mode	New audio mode. Pass MM_MODE_A for complete hardware mixing, MM_MODE_B for interpolated mixing, or MM_MODE_C for extended mixing.

mmSetCustomSoundBankHandler()

void mmSetCustomSoundBankHandler

(

mm_callback

p_loader

)

Install a custom routine to interface with the soundbank data.

The callback will be responsible for handling requests from Maxmod to access data in the soundbank. It will receive the following values in the "msg" value:

• MMCB_SONGREQUEST and MMCB_SAMPREQUEST: "param" contains a song/sample ID that you need to load to RAM. The callback needs to return a pointer to the address of the data in RAM. The callback can return zero if it failed to load the data.
• MMCB_DELETESONG and MMCB_DELETESAMPLE: "param" contains the address to the data in RAM, and the callback is expected to free it if required. The callback needs to return zero.

Parameters

p_loader

Function pointer to soundbank request handler.

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

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

Parameters

handler

Function pointer to event handler.

mmSoundBankInFiles()

void mmSoundBankInFiles

(

const char *

filename

)

Setup the standard interface for a soundbank that is loaded in the file system.

This function should be called after mmInit and before any Load or Unload operations. This function is called by mmInitDefault.

Parameters

filename

Filename of your soundbank binary.

mmSoundBankInMemory()

void mmSoundBankInMemory

(

mm_addr

address

)

Enable the standard interface for a soundbank that is loaded into memory.

This function should be called after mmInit and before any Load or Unload functions. This function is called by mmInitDefaultMem.

Parameters

address

Memory address of soundbank file.

mmUnload()

mm_word mmUnload

(

mm_word

module_ID

)

Unloads and frees memory space occupied by a module.

Caution: Ensure that the module to be unloaded isn't playing!

Parameters

module_ID

Index of module to be unloaded from memory.

Returns

It returns 0 on success and a non-zero value on error.

mmUnloadEffect()

mm_word mmUnloadEffect

(

mm_word

sample_ID

)

Unloads a sound effect and frees the memory if the reference count becomes zero.

Parameters

sample_ID

Index of sample to be unloaded.

Returns

It returns 0 on success and a non-zero value on error.

mmUnlockChannels()

void mmUnlockChannels

(

mm_word

bitmask

)

Unlocks audio channels to allow Maxmod to use them.

This function can be used to restore channel usage to Maxmod when you are finished using certain channels.

Note that in the "Interpolated Audio" mode, channels can not be unlocked. To unlock channels in the interpolated mode you must reset the audio system. To reset the audio system, use mmSelectMode.

Parameters

bitmask

Selection of channels to unlock. Bit0 = Channel0, Bit1 = Channel1, Bit2 = Channel2 ... Bit15 = Channel15