[Image]  APEX AUDIO SYSTEM
Instruction Manual
intro | getting started | conv2aas | example | faq
api : index | general | sfx | mod | misc | mixer


:: AAS_MixAudio
PROTOTYPE void AAS_MixAudio( AAS_s8* mix_buffer, struct AAS_Channel chans[], int iterations );
FUNCTION Mixes multiple sounds into a single mixing buffer. This function is in IWRAM and so it must be called using AAS_INIT_BRANCH and AAS_BRANCH() as described in "AAS_Mixer.h". This function should not normally be directly called.
PARAMETERS
Name Valid values Meaning
mix_buffer Any writeable word-aligned address at least iterations*16 bytes in size Specifies the address of the mixing buffer you wish to use
chans Any writeable word-aligned address pointing to valid channel data The start address of an array of 8 AAS_Channel structures
iterations 1-127 The number of 16 byte chunks you wish the function to write to mix_buffer
RETURNS Nothing
NOTES

This function (and the others in this section of the documentation) should only be used if you've got a strong reason for needing to access the mixing routine directly. Because of this, it isn't included in the usual "AAS.h" header file - you'll need to include "AAS_Mixer.h" instead, which is in the "aas/" folder of either the release or the ‹root›/build file when building from source. A good understanding of the GBA's sound hardware is required to use this routine directly.

The AAS_Channel structure is defined in the header file as follows:

struct AAS_Channel
{
	AAS_u8 effective_volume;
	AAS_BOOL active;
	AAS_u8 volume;
	AAS_u8 pos_fraction;
	AAS_u16 frequency;
	AAS_u16 delta;
	const AAS_s8* pos;
	const AAS_s8* end;
	AAS_u32 loop_length;
};

The meaning of these elements is shown below:

Name Valid values Meaning
effective_volume 0-255 (see below) Specifies the volume of this channel. Channels with an effective_volume of zero will not be processed. This should usually be set to (active?volume:0) before calling AAS_MixAudio. Zero will be written here by the mixer when a non-looping sample finishes.
active AAS_TRUE or AAS_FALSE AAS_MixAudio does not read this value but it does write AAS_FALSE here when a non-looping sample finishes. (See effective_volume.)
volume 0-255 Not directly used by AAS_MixAudio. (See effective_volume.)
pos_fraction Any The fractional component of the sample position. This value should be reset to zero when a sample is started, but other than that it should only be changed by AAS_MixAudio.
frequency 1-65535 Not directly used by AAS_MixAudio. (See delta.)
delta 1-4095 Specifies how much to add on to the sample position per byte in 2.10 fixed point format. Usually set to ((frequency<<10)/mixing_frequency) before calling AAS_MixAudio.
pos Any valid address The address of the current sample position. The fractional component is stored in pos_fraction.
end Any valid address The address of the end of the sample.
loop_length Any The number of bytes from the end of the sample back to the loop restart point. Zero indicates that the sample should not loop.

AAS_MixAudio expects to be passed a pointer to an array of 8 AAS_Channels - this is referred to as a channel set. An array containing 16 AAS_Channels is provided and is called AAS_channels[]. This can effectively be used as two seperate arrays of 8 AAS_Channels by calling using either &AAS_channels[0] or &AAS_channels[8] as a parameter. This allows a total of 16 channels - 8 per Direct Sound output. (The maximum number of channels per set is specified using the AAS_MixAudio_SetMaxChans_x functions - the default is 4.)

Also note that the total volume (i.e. the sum of the effective_volumes for all the channels in the set) must not exceed 256 (except if AAS_MIXAUDIO_MODE_BOOST is used (see AAS_MixAudio_SetMode), in which case the total must not exceed 128). If it does, the sound output will be distorted. This means that, despite 255 (127 with AAS_MIXAUDIO_MODE_BOOST) being a valid volume for a channel as indicated above, it is only safe to set a volume this high if the total effective_volume of the remaining channels in the channel set is 0 or 1. This means that if you intend to use all 8 channels in the set then you should generally use volumes in the range 0-32 (0-16 with AAS_MIXAUDIO_MODE_BOOST).

A few other things worth noting about this routine:

  • It doesn't increment pos if a channel's effective_volume is 0. You'll need to increment it yourself if you want this to happen.
  • Do not call AAS_MixAudio if there are no active channels in the set. Use a seperate routine to write out zeroes to the buffer or use a pre-calculated buffer full of zeroes instead.
  • The dynamic mixing rate feature is also handled by a different routine so you cannot use this feature if you are accessing AAS_MixAudio directly without implimenting your own code to change the mixing rate.
  • All sample data should be 8-bit signed and clipped to the range -127 to 127. (Rather than the usual range of -128 to 127.) If this extra bit of clipping is not done then the sound may occasionally distort. Conv2AAS does this automatically, but if you're using a different program to import your sample data (not recommended) then you will need to preprocess the data to avoid this problem.
  • The mixer does not sanity check the input parameters. The result of passing illegal parameters is undefined.
  • AAS_MixAudio uses DMA 3, which may cause problems if it is called via an interrupt whilst another bit of code is halfway through initialising a DMA 3 transfer. AAS_DoDMA3 should be used to prevent this problem. This routine works by writing all the values required to start a DMA transfer with a single stmia instruction. You can do this in your own code as an alternative to calling AAS_DoDMA3.
  • You will need to set up your own sound handling routines and interrupts around the mixer to get it work usefully. This is normally handled by AAS but this is not possible when AAS_MixAudio is directly accessed. It should not be used in conjunction with any of the standard AAS commands with the exception of AAS_ShowLogo and AAS_DoDMA3.
  • Also bare in mind that the API for this routine is more likely to change in future versions of AAS than those for the other routines. [Last changed in v1.11]

:: AAS_MixAudio_NoChange
PROTOTYPE void AAS_MixAudio_NoChange( AAS_s8* mix_buffer, struct AAS_Channel chans[], int iterations );
FUNCTION Mixes multiple sounds into a single mixing buffer. This function should only be called if there are no changes to chans[] since a previous call to AAS_MixAudio. Do not call twice in a row. This function is in IWRAM and so it must be called using AAS_INIT_BRANCH and AAS_BRANCH() as described in "AAS_Mixer.h". This function should not normally be directly called - see AAS_MixAudio.
PARAMETERS See AAS_MixAudio.
RETURNS Nothing
NOTES

This function works in the same way as AAS_MixAudio, except that it is slightly faster but should only be called if there are no changes to chans[] since a previous call to AAS_MixAudio. It should also not be called twice in a row.

:: AAS_MixAudio_SetMode
PROTOTYPE void AAS_MixAudio_SetMode( int mode );
FUNCTION Enable/disable volume boost and (optional) clipping. This function should only be called if you can be 100% sure that AAS_MixAudio and AAS_MixAudio_NoChange won't interrupt it. This function should not normally be directly called - see AAS_MixAudio.
PARAMETERS
Name Valid values Meaning
mode AAS_MIXAUDIO_MODE_NORMAL
AAS_MIXAUDIO_MODE_BOOST
AAS_MIXAUDIO_MODE_BOOSTANDCLIP 		Specifies whether the volume should be boosted and (optionally) clipped
RETURNS Nothing
NOTES

The three mixing modes work as follows:

  • AAS_MIXAUDIO_MODE_NORMAL. No volume boosting. The total volume of the channel set must be <= 256. This is the default setting.
  • AAS_MIXAUDIO_MODE_BOOST. All volumes are doubled. The output is not clipped so the total volume of the channel set must be <= 128 otherwise severe distortion will occur.
  • AAS_MIXAUDIO_MODE_BOOSTANDCLIP. All volumes are doubled. The output is clipped so the total volume of the channel set must be <= 256.

:: AAS_MixAudio_SetMaxChans_2
PROTOTYPE void AAS_MixAudio_SetMaxChans_2();
FUNCTION Sets the maximum number of channels in the set to 2. This function should only be called if you can be 100% sure that AAS_MixAudio and AAS_MixAudio_NoChange won't interrupt it. This function should not normally be directly called - see AAS_MixAudio.
PARAMETERS None
RETURNS Nothing
NOTES

For best performance, the maximum number of channels in the set should be set to the lowest number that is >= the actual number of channels in the set.

:: AAS_MixAudio_SetMaxChans_4
PROTOTYPE void AAS_MixAudio_SetMaxChans_4();
FUNCTION Sets the maximum number of channels in the set to 4 (the default). This function should only be called if you can be 100% sure that AAS_MixAudio and AAS_MixAudio_NoChange won't interrupt it. This function should not normally be directly called - see AAS_MixAudio.
PARAMETERS None
RETURNS Nothing
NOTES

For best performance, the maximum number of channels in the set should be set to the lowest number that is >= the actual number of channels in the set.

:: AAS_MixAudio_SetMaxChans_8
PROTOTYPE void AAS_MixAudio_SetMaxChans_8();
FUNCTION Sets the maximum number of channels in the set to 8. This function should only be called if you can be 100% sure that AAS_MixAudio and AAS_MixAudio_NoChange won't interrupt it. This function should not normally be directly called - see AAS_MixAudio.
PARAMETERS None
RETURNS Nothing
NOTES

For best performance, the maximum number of channels in the set should be set to the lowest number that is >= the actual number of channels in the set.