GBA: Sound Effects

Functions
mm_sfxhand	mmEffect (mm_word sample_ID)
	Plays a sound effect with default settings.
mm_bool	mmEffectActive (mm_sfxhand handle)
	Indicates if a sound effect is active or not.
mm_word	mmEffectCancel (mm_sfxhand handle)
	Stops a sound effect. The handle will be invalidated.
void	mmEffectCancelAll ()
	Stop all sound effects and reset the effect system.
mm_sfxhand	mmEffectEx (mm_sound_effect *sound)
	Plays a sound effect with custom settings.
void	mmEffectPanning (mm_sfxhand handle, mm_byte panning)
	Changes the panning of a sound effect.
void	mmEffectRate (mm_sfxhand handle, mm_word rate)
	Changes the playback rate for a sound effect.
void	mmEffectRelease (mm_sfxhand handle)
	Marks a sound effect as unimportant.
void	mmEffectScaleRate (mm_sfxhand handle, mm_word factor)
	Scales the rate of the sound effect by a certain factor.
void	mmEffectVolume (mm_sfxhand handle, mm_word volume)
	Changes the volume of a sound effect.
void	mmSetEffectsVolume (mm_word volume)
	Set master volume scale for effect playback.

Detailed Description

Function Documentation

mmEffect()

mm_sfxhand mmEffect

(

mm_word

sample_ID

)

Plays a sound effect with default settings.

Default settings are: Volume=Max, Panning=Center, Rate=Center (specified in sample).

The value returned from this function is a handle and can be used to modify the sound effect while it's actively playing.

Parameters

sample_ID

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

Returns

Sound effect handle. This value can be used to modify parameters of the sound effect while it is playing.

mmEffectActive()

mm_bool mmEffectActive

(

mm_sfxhand

handle

)

Indicates if a sound effect is active or not.

Parameters

handle

Sound effect handle received from mmEffect() or mmEffectEx().

Returns

Non-zero if the sound effect is active, zero if it isn't.

mmEffectCancel()

mm_word mmEffectCancel

(

mm_sfxhand

handle

)

Stops a sound effect. The handle will be invalidated.

Parameters

handle

Sound effect handle received from mmEffect() or mmEffectEx().

Returns

Non-zero if the sound was found and stopped, zero on error.

mmEffectEx()

mm_sfxhand mmEffectEx

(

mm_sound_effect *

sound

)

Plays a sound effect with custom settings.

Parameters

sound

Structure containing information about the sound to be played.

Returns

Sound effect handle that may be used to modify the sound later.

mmEffectPanning()

void mmEffectPanning	(	mm_sfxhand	handle,
		mm_byte	panning
	)

Changes the panning of a sound effect.

Parameters

handle	Sound effect handle received from mmEffect() or mmEffectEx().
panning	New panning level. Ranges from 0 (left) to 255 (right).

mmEffectRate()

void mmEffectRate	(	mm_sfxhand	handle,
		mm_word	rate
	)

Changes the playback rate for a sound effect.

The actual playback rate depends on this value and the base frequency of the sample. This parameter is a 6.10 fixed point value, passing 1024 will return the sound to its original pitch, 2048 will raise the pitch by one octave, and 512 will lower the pitch by an octave. To calculate a value from semitones: Rate = 1024 * 2^(Semitones/12). (please don't try to do that with integer maths)

Parameters

handle	Sound effect handle received from mmEffect() or mmEffectEx().
rate	New playback rate.

mmEffectRelease()

void mmEffectRelease

(

mm_sfxhand

handle

)

Marks a sound effect as unimportant.

This enables the sound effect to be interrupted by music/other sound effects if the need arises. The handle will be invalidated.

Parameters

handle

Sound effect handle received from mmEffect() or mmEffectEx().

mmEffectScaleRate()

void mmEffectScaleRate	(	mm_sfxhand	handle,
		mm_word	factor
	)

Scales the rate of the sound effect by a certain factor.

Parameters

handle	Sound effect handle received from mmEffect() or mmEffectEx().
factor	6.10 fixed point factor.

mmEffectVolume()

void mmEffectVolume	(	mm_sfxhand	handle,
		mm_word	volume
	)

Changes the volume of a sound effect.

TODO: Does volume go from 0 to 65535?

Parameters

handle	Sound effect handle received from mmEffect() or mmEffectEx().
volume	New volume level. Ranges from 0 (silent) to 255 (normal).

mmSetEffectsVolume()

void mmSetEffectsVolume

(

mm_word

volume

)

Set master volume scale for effect playback.

Parameters

volume

Master volume. 0->1024 representing 0%->100% volume