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


:: AAS_SFX_Play
PROTOTYPE int AAS_SFX_Play( int channel, int sample_volume, int sample_frequency, const AAS_s8* sample_start, const AAS_s8* sample_end, const AAS_s8* sample_restart );
FUNCTION Starts playing the specified sample.
PARAMETERS
Name Valid values Meaning
channel Depends on how AAS has been configured - see AAS_SetConfig Specifies the channel you wish to use
sample_volume 0-64 Specifies the volume you wish to play the sample at
sample_frequency 1-65535 Specifies the frequency you wish to play the sample at
sample_start AAS_DATA_SFX_START_???, where ??? is the name of the sample you wish to play (see your project's AAS_Data.h file for a complete list of all available samples) Specifies the start address of the sample you wish to play
sample_end AAS_DATA_SFX_END_???, where ??? is the name of the sample you wish to play (see your project's AAS_Data.h file for a complete list of all available samples) Specifies the end address if the sample you wish to play
sample_restart AAS_NULL or any address between AAS_DATA_SFX_START_??? (inclusive) and AAS_DATA_SFX_END_??? (exclusive), where ??? is the name of the sample you wish to play (see your project's AAS_Data.h file for a complete list of all available samples) Specifies the address the sample will loop to when it gets to the end. NULL indicates that the sample should not loop.
RETURNS
AAS_OK : Function executed correctly.
AAS_ERROR_INVALID_SAMPLE_ADDRESS : The sample_start, sample_end or sample_restart addresses specified are not valid.
AAS_ERROR_VOLUME_OUT_OF_RANGE : The volume specified is not in the range 0-64.
AAS_ERROR_FREQUENCY_OUT_OF_RANGE : The frequency specified is not in the range 1-65535.
AAS_ERROR_CHANNEL_NOT_AVAILABLE : The channel you specified is not available to play a sample - see AAS_SetConfig.
AAS_ERROR_CALL_SET_CONFIG_FIRST : AAS_SetConfig has not been successfully called yet. It must be successfully called at least once before calling this function.
NOTES

Sample frequency is capped at 4 times the mixing rate specified when calling AAS_SetConfig.

:: AAS_SFX_ChannelExists
PROTOTYPE AAS_BOOL AAS_SFX_ChannelExists( int channel );
FUNCTION Returns AAS_TRUE only if AAS_SFX_Play will succeed for this channel, otherwise returns AAS_FALSE.
PARAMETERS
Name Valid values Meaning
channel Depends on how AAS has been configured - see AAS_SetConfig Specifies the channel you wish to test
RETURNS
AAS_FALSE : This channel is not currently a valid sound effect channel.
AAS_TRUE : This channel is currently a valid sound effect channel.
NOTES

Whether a channel is available or not depends on how many channels were specified when calling AAS_SetConfig and also on whether or not a MOD is currently playing. See AAS_SetConfig for more information.

:: AAS_SFX_IsActive
PROTOTYPE AAS_BOOL AAS_SFX_IsActive( int channel );
FUNCTION Returns AAS_TRUE if channel is valid and active, AAS_FALSE otherwise.
PARAMETERS
Name Valid values Meaning
channel Depends on how AAS has been configured - see AAS_SetConfig Specifies the channel you wish to test
RETURNS
AAS_FALSE : This is an invalid channel for sound effects, or it is valid but currently in use.
AAS_TRUE : This is a valid sound effect channel and it currently has a sound effect playing.
NOTES

Whether or not a channel is valid depends on how many channels were specified when calling AAS_SetConfig and also on whether or not a MOD is currently playing. See AAS_SetConfig for more information. Provided the channel specified is valid, this function will return AAS_TRUE if there is another sound effect playing on this channel, and AAS_FALSE if there is not. It will always return AAS_FALSE if the channel is invalid.

:: AAS_SFX_EndLoop
PROTOTYPE int AAS_SFX_EndLoop( int channel );
FUNCTION If a looping sample was playing in this channel, it will not loop again at end of the current iteration.
PARAMETERS
Name Valid values Meaning
channel Depends on how AAS has been configured - see AAS_SetConfig Specifies the channel you wish to change
RETURNS
AAS_OK : The function suceeded.
AAS_ERROR_CHANNEL_NOT_AVAILABLE : The channel specified is invalid.
AAS_ERROR_CALL_SET_CONFIG_FIRST : AAS_SetConfig should be successfully called at least once before calling this function.
NOTES

None

:: AAS_SFX_SetFrequency
PROTOTYPE int AAS_SFX_SetFrequency( int channel, int sample_frequency );
FUNCTION Changes the frequency of the sample playing in the specified channel.
PARAMETERS
Name Valid values Meaning
channel Depends on how AAS has been configured - see AAS_SetConfig Specifies the channel you wish to change
sample_frequency 1-65535 Specifies the new frequency you wish to play the sample at
RETURNS
AAS_OK : The function suceeded.
AAS_ERROR_FREQUENCY_OUT_OF_RANGE : The frequency specified in not in the range 1-65535.
AAS_ERROR_CHANNEL_NOT_AVAILABLE : The channel specified is invalid.
AAS_ERROR_CALL_SET_CONFIG_FIRST : AAS_SetConfig should be successfully called at least once before calling this function.
NOTES

Sample frequency is capped at four times the mixing rate specified when calling AAS_SetConfig. If no sample is playing in the specified channel then this function has no effect.

:: AAS_SFX_SetVolume
PROTOTYPE int AAS_SFX_SetVolume( int channel, int sample_volume );
FUNCTION Changes the volume of the sample playing in the specified channel.
PARAMETERS
Name Valid values Meaning
channel Depends on how AAS has been configured - see AAS_SetConfig Specifies the channel you wish to change
sample_volume 0-64 Specifies the new volume you wish to play the sample at
RETURNS
AAS_OK : The function suceeded.
AAS_ERROR_VOLUME_OUT_OF_RANGE : The frequency specified in not in the range 0-64.
AAS_ERROR_CHANNEL_NOT_AVAILABLE : The channel specified is invalid.
AAS_ERROR_CALL_SET_CONFIG_FIRST : AAS_SetConfig should be successfully called at least once before calling this function.
NOTES

If no sample is playing in the specified channel then this function has no effect.

:: AAS_SFX_Stop
PROTOTYPE int AAS_SFX_Stop( int channel );
FUNCTION Stops the sample currently playing in the specified channel.
PARAMETERS
Name Valid values Meaning
channel Depends on how AAS has been configured - see AAS_SetConfig Specifies the channel you wish to stop
RETURNS
AAS_OK : The function suceeded.
AAS_ERROR_CHANNEL_NOT_AVAILABLE : The channel specified is invalid.
AAS_ERROR_CALL_SET_CONFIG_FIRST : AAS_SetConfig should be successfully called at least once before calling this function.
NOTES

If no sample is playing in the specified channel then this function has no effect.

:: AAS_SFX_Resume
PROTOTYPE int AAS_SFX_Resume( int channel );
FUNCTION Resumes a channel that has been previously stopped.
PARAMETERS
Name Valid values Meaning
channel Depends on how AAS has been configured - see AAS_SetConfig Specifies the channel you wish to resume
RETURNS
AAS_OK : The function suceeded.
AAS_ERROR_CHANNEL_NOT_AVAILABLE : The channel specified is invalid.
AAS_ERROR_CALL_SET_CONFIG_FIRST : AAS_SetConfig should be successfully called at least once before calling this function.
AAS_ERROR_CHANNEL_ACTIVE : The channel is already active so it cannot be resumed.
AAS_ERROR_CHANNEL_UNRESUMEABLE : This channel has either never been used or is inactive because the sample finished.
NOTES

None

:: AAS_SFX_GetNumChannels
PROTOTYPE int AAS_SFX_GetNumChannels();
FUNCTION Returns the number of SFX channels that are currently available.
PARAMETERS None
RETURNS
0-16 : The number of SFX channels that are currently available.
NOTES

None