AAS Instructions

APEX AUDIO SYSTEM
Instruction Manual

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.

:: AAS_Timer1InterruptHandler

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.

:: AAS_FastTimer1InterruptHandler

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.

:: AAS_DoWork

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.

:: AAS_DoDMA3

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.

:: AAS_ShowLogo

PROTOTYPE void AAS_ShowLogo();

FUNCTION Displays the AAS splash screen.

PARAMETERS None

RETURNS Nothing

NOTES
It is entirely optional for projects to use this splash-screen on startup from v1.12 onwards, now that this is an open-source project. This is a change from the v1.11 release back in 2008 and earlier. Although the creator does still appreciate attribution. Please read about licensing here.

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_ShowLogo();
FUNCTION	Displays the AAS splash screen.
PARAMETERS	None
RETURNS	Nothing
NOTES	It is entirely optional for projects to use this splash-screen on startup from v1.12 onwards, now that this is an open-source project. This is a change from the v1.11 release back in 2008 and earlier. Although the creator does still appreciate attribution. Please read about licensing here.