APEX AUDIO SYSTEM Instruction Manual

intro | getting started | conv2aas | example | faq api : index | general | sfx | mod | misc | mixer

PROTOTYPE	int AAS_SetConfig( int config_mix, int config_chans, int config_spatial, int config_dynamic );
FUNCTION	Sets the effective mixing rate, number of channels, volume boost, mono/stereo output and switches dynamic mixing on or off. Must be called before using any other AAS functions.
PARAMETERS	Name Valid values Meaning config_mix AAS_CONFIG_MIX_32KHZ AAS_CONFIG_MIX_28KHZ AAS_CONFIG_MIX_24KHZ AAS_CONFIG_MIX_20KHZ AAS_CONFIG_MIX_16KHZ AAS_CONFIG_MIX_12KHZ AAS_CONFIG_MIX_8KHZ Specifies the effective mixing rate config_chans AAS_CONFIG_CHANS_16 AAS_CONFIG_CHANS_8 AAS_CONFIG_CHANS_4 AAS_CONFIG_CHANS_16_LOUD AAS_CONFIG_CHANS_8_LOUD AAS_CONFIG_CHANS_4_LOUD Specifies the maximum number of channels and whether the output should be volume boosted and clipped config_spatial AAS_CONFIG_SPATIAL_STEREO AAS_CONFIG_SPATIAL_MONO Specifies mono/stereo output config_dynamic AAS_CONFIG_DYNAMIC_OFF AAS_CONFIG_DYNAMIC_ON Specifies dynamic mixing on/off (see NOTES)
RETURNS	AAS_OK : Function executed correctly. AAS_ERROR_INVALID_CONFIG : Invalid configuration requested.
NOTES	This function should be called at least once before calling any other AAS functions. It can also be used to change the audio settings, although doing so will stop any sounds that are currently playing. The recommended configuration is 24KHz AAS_CONFIG_CHANS_8 mono with dynamic mixing disabled. The AAS_CONFIG_CHANS_x_LOUD modes increase the volume of the output but take ~10% more CPU time and can cause the sound to distort in some cases. They are not recommended for use with the 4 channel modes but are strongly encouraged when using 16 channels. Dynamic mixing automatically adjusts the mixing rate depending on the frequency of the sounds being played, up to a maximum of the mixing rate you specified. Disabling it will cause AAS to always use the mixing rate you chose. Dynamic mixing is still somewhat experimental, but it often yields a significant performance boost for only a very small drop in quality. If stereo mode is used the SFX channels are arranged as follows: SFX Channel 0 : Left SFX Channel 1 : Right SFX Channel 2 : Right SFX Channel 3 : Left SFX Channel 4 : Left SFX Channel 5 : Right SFX Channel 6 : Right SFX Channel 7 : Left SFX Channel 8 : Left SFX Channel 9 : Right SFX Channel 10 : Right SFX Channel 11 : Left SFX Channel 12 : Left SFX Channel 13 : Right SFX Channel 14 : Right SFX Channel 15 : Left In mono mode, all sounds come out both speakers. The number of channels you can access is limited by the number that are already being used to play a MOD. So, if you're playing a 3 channel MOD in AAS_CONFIG_CHANS_4 mode then only the first channel (channel 0) will be available for playing sound effects. If AAS_CONFIG_CHANS_8 were used in the same situation then the first 5 channels (channels 0-4) would be available.

PROTOTYPE	void AAS_Timer1InterruptHandler();
FUNCTION	Either this or AAS_FastTimer1InterruptHandler must be quickly called when a Timer 1 interrupt occurs.
PARAMETERS	None
RETURNS	Nothing
NOTES	The Timer 1 interrupt occurs roughly 50 times per second and this routine must be called by the user's interrupt handler each time the appropriate interrupt occurs. For more information about this please read the getting started section and, for example interrupt handling code, please read the example section. This routine also mixes the next batch of audio so it can take a long time to return. This may cause problems if you have other CPU-intensive interrupts in your code. In these cases, AAS_FastTimer1InterruptHandler, AAS_DoWork and the special "__AAS_MultipleInterrupts" mode in the crt0.s file used in AASExample2 should be used instead of the normal interrupt handling modes.

PROTOTYPE	void AAS_FastTimer1InterruptHandler();
FUNCTION	Either this or AAS_Timer1InterruptHandler must be quickly called when a Timer 1 interrupt occurs. AAS_DoWork must also be called 50 times per second if AAS_FastTimer1InterruptHandler is used.
PARAMETERS	None
RETURNS	Nothing
NOTES	This function also requires a seperate (less time-sensitive) call to AAS_DoWork at least 50 times a second. This function is called automatically if the special "AAS_MultipleInterrupts" mode in the custom crt0.s file included with the SDK is used. The Timer 1 interrupt occurs roughly 50 times per second and this routine must be called by the user's interrupt handler each time the appropriate interrupt occurs. For more information about this please read the getting started section and, for example interrupt handling code, please read the example section. This routine starts the next piece of audio playing, but does not mix the batch of audio that will be played after that. This means that this routine returns very quickly but a seperate call to AAS_DoWork is also required within the next 50th of a second. The ideal place to call AAS_DoWork is during VBlank. To prevent AAS_FastTimer1InterruptHandler() being halted by another interrupt, the special "__AAS_MultipleInterrupts" mode in the crt0.s file used in AASExample2 should also be used. Alternatively, if your code does not use other CPU-intensive interrupts then you can use a normal interrupt handler and AAS_Timer1InterruptHandler. In this case there is no need for a seperate call to AAS_DoWork. An example of this method of handling interrupts is shown in AASExample.

PROTOTYPE	void AAS_DoWork();
FUNCTION	Mixes the next batch of audio. Should only be used in conjunction with AAS_FastTimer1InterruptHandler.
PARAMETERS	None
RETURNS	Nothing
NOTES	This function should be called at least 50 times a second (during VBlank, for example) if you're using AAS_FastTimer1InterruptHandler. If you're using AAS_Timer1InterruptHandler instead then AAS_DoWork should not be called at all. Should only be used in conjunction with AAS_FastTimer1InterruptHandler and the special "__AAS_MultipleInterrupts" mode in the crt0.s file used in AASExample2. Alternatively, AAS_Timer1InterruptHandler can be used with the standard interrupt handlers but this will not work correctly if there are other CPU-intensive interrupts in your code.

PROTOTYPE	void AAS_DoDMA3( void* source, void* dest, AAS_u32 flags_and_length );
FUNCTION	Allows DMA3 to be used safely.
PARAMETERS	Name Valid values Meaning source Depends on flags_and_length Specifies source address dest Depends on flags_and_length Specifies dest address flags_and_length See GBA docs See GBA docs
RETURNS	Nothing
NOTES	The mixer uses DMA3 internally, which means it is no longer safe to use DMA3 in your code in the usual way since the mixer might interrupt it halfway through and corrupt the parameters. To fix this you should either use AAS_DoDMA3 or the stmia assembler instruction to write all parameters with a single instruction.

PROTOTYPE	void AAS_ShowLogo();
FUNCTION	Displays the AAS splash screen.
PARAMETERS	None
RETURNS	Nothing
NOTES	Non commercial projects must display this splash screen on startup. It is optional on commercial projects. Please read about licensing here.