libOGC  1.0
 All Data Structures Files Functions Variables Typedefs Macros Modules Pages
Functions
Voice functions

Functions

s32 ASND_AddVoice (s32 voice, void *snd, s32 size_snd)
 Adds a PCM voice to play from the second buffer. More...
 
s32 ASND_ChangePitchVoice (s32 voice, s32 pitch)
 Changes the voice pitch in real-time. More...
 
s32 ASND_ChangeVolumeVoice (s32 voice, s32 volume_l, s32 volume_r)
 Changes the voice volume in real-time. More...
 
s32 ASND_GetFirstUnusedVoice ()
 Returns the first unused voice. More...
 
u32 ASND_GetTickCounterVoice (s32 voice)
 Returns the voice tick counter. More...
 
u32 ASND_GetTimerVoice (s32 voice)
 Returns the voice playback time. More...
 
s32 ASND_PauseVoice (s32 voice, s32 pause)
 Pauses the selected voice. More...
 
s32 ASND_SetInfiniteVoice (s32 voice, s32 format, s32 pitch, s32 delay, void *snd, s32 size_snd, s32 volume_l, s32 volume_r)
 Sets a PCM voice to play infinitely. More...
 
s32 ASND_SetVoice (s32 voice, s32 format, s32 pitch, s32 delay, void *snd, s32 size_snd, s32 volume_l, s32 volume_r, ASNDVoiceCallback callback)
 Sets a PCM voice to play. More...
 
s32 ASND_StatusVoice (s32 voice)
 Returns the status of the selected voice. More...
 
s32 ASND_StopVoice (s32 voice)
 Stops the selected voice. More...
 
s32 ASND_TestPointer (s32 voice, void *pointer)
 Tests if pointer is in use by voice as a buffer. More...
 
s32 ASND_TestVoiceBufferReady (s32 voice)
 Tests to determine if the voice is ready to receive a new buffer sample with ASND_AddVoice(). More...
 

Detailed Description

Function Documentation

s32 ASND_AddVoice ( s32  voice,
void *  snd,
s32  size_snd 
)

Adds a PCM voice to play from the second buffer.

Note
This function requires a call to ASND_SetVoice() and its subsequent return value to be a status other than SND_UNUSED prior to calling this one.
Parameters
[in]voiceVoice slot to attach this buffer to; value must be 0 to (MAX_SND_VOICES-1).
[in]sndBuffer containing the samples; it must be aligned and padded to 32 bytes AND have the same sample format as the first buffer.
[in]size_sndSize of the buffer samples, in bytes.
Returns
SND_OK or SND_INVALID; it may also return SND_BUSY if the second buffer is not empty and the voice cannot be added.
s32 ASND_ChangePitchVoice ( s32  voice,
s32  pitch 
)

Changes the voice pitch in real-time.

This function can be used to create audio effects such as Doppler effect emulation.

Parameters
[in]voiceVoice to change the pitch of, from 0 to (MAX_SND_VOICES-1).
Returns
SND_OK or SND_INVALID.
s32 ASND_ChangeVolumeVoice ( s32  voice,
s32  volume_l,
s32  volume_r 
)

Changes the voice volume in real-time.

This function can be used to create audio effects like distance attenuation.

Parameters
[in]voiceVoice to change the volume of, from 0 to (MAX_SND_VOICES-1).
[in]volume_lVoice volume to set the left channel to, from 0 to 255.
[in]volume_rVoice volume to set the right channel to, from 0 to 255.
Returns
SND_OK or SND_INVALID.
s32 ASND_GetFirstUnusedVoice ( )

Returns the first unused voice.

Note
Voice 0 is the last possible voice that can be returned. The idea is that this voice is reserved for a MOD/OGG/MP3/etc. player. With this in mind, you can use this function to determine that the rest of the voices are working if the return value is < 1.
Returns
SND_INVALID or the first free voice from 0 to (MAX_SND_VOICES-1).
u32 ASND_GetTickCounterVoice ( s32  voice)

Returns the voice tick counter.

This value represents the number of ticks since this voice started to play, sans delay time. It uses the same resolution as the internal sound buffer. For example, if the lib is initialized with INIT_RATE_48000, a return value of 24000 is equal to 0.5 seconds. This value can be used, for example, to synchronize audio and video.

Note
This function does not return error codes.
Parameters
[in]voiceVoice to retrieve the counter value from, from 0 to (MAX_SND_VOICES-1).
Returns
Number of ticks since this voice started playing.
u32 ASND_GetTimerVoice ( s32  voice)

Returns the voice playback time.

This value represents the time, in milliseconds, since this voice started playing, sans delay time. This value can be used, for example, to synchronize audio and video.

Note
This function does not return error codes.
Parameters
[in]voiceVoice to retrieve the time value from, from 0 to (MAX_SND_VOICES-1).
Returns
Amount of time since this voice has started playing.
s32 ASND_PauseVoice ( s32  voice,
s32  pause 
)

Pauses the selected voice.

Parameters
[in]voiceVoice to pause, from 0 to (MAX_SND_VOICES-1).
Returns
SND_OK or SND_INVALID.
s32 ASND_SetInfiniteVoice ( s32  voice,
s32  format,
s32  pitch,
s32  delay,
void *  snd,
s32  size_snd,
s32  volume_l,
s32  volume_r 
)

Sets a PCM voice to play infinitely.

Note
See ASND_SetVoice() for a detailed description, as it is largely identical.
s32 ASND_SetVoice ( s32  voice,
s32  format,
s32  pitch,
s32  delay,
void *  snd,
s32  size_snd,
s32  volume_l,
s32  volume_r,
ASNDVoiceCallback  callback 
)

Sets a PCM voice to play.

This function stops one previous voice. Use ASND_StatusVoice() to test the status condition.

Note
The voices are played in 16-bit stereo, regardless of the source format.

callback is used to implement a double buffer. When the second buffer is empty, the callback function is called with the voice number as an argument. You can use void callback (s32 voice) to call ASND_AddVoice() and add one voice to the second buffer. When the callback is non-NULL the, the voice never stops and returns SND_WAITING if successful on timeout condition.
Parameters
[in]voiceVoice slot to use for this sound; valid values are 0 to (MAX_SND_VOICES-1).
[in]formatVoice format to use for this sound.
[in]pitchFrequency to use, in Hz.
[in]delayDelay to wait before playing this voice; value is in milliseconds.
[in]sndBuffer containing samples to play back; the buffer must be aligned and padded to 32 bytes!
[in]size_sndSize of the buffer samples, in bytes.
[in]volume_lVoice volume of the left channel; value can be 0 - 255 inclusive.
[in]volume_rVoice volume of the right channel; value can be 0 - 255 inclusive.
[in]callbackOptional callback function to use; set to NULL for no callback. See the note above for details.
Returns
SND_OK or SND_INVALID.
s32 ASND_StatusVoice ( s32  voice)

Returns the status of the selected voice.

Parameters
[in]voiceVoice slot to get the status from, from 0 to (MAX_SND_VOICES-1).
Returns
SND_INVALID if invalid, else a value from SND_IsActiveVoice additional return values.
s32 ASND_StopVoice ( s32  voice)

Stops the selected voice.

If the voice is used in song mode, you need to assign the samples with ASND_SetSongSampleVoice() again. In this case, use ANS_PauseSongVoice() to stop the voice without loss of samples.

Parameters
[in]voiceVoice to stop, from 0 to (MAX_SND_VOICES-1).
Returns
SND_OK or SND_INVALID.
s32 ASND_TestPointer ( s32  voice,
void *  pointer 
)

Tests if pointer is in use by voice as a buffer.

Parameters
[in]voiceVoice to test, from 0 to (MAX_SND_VOICES-1).
[in]pointerAddress to test. This must be the same pointer sent to ASND_AddVoice() or ASND_SetVoice().
Returns
SND_INVALID if invalid
0 if the pointer is unused
1 if the pointer used as a buffer.
s32 ASND_TestVoiceBufferReady ( s32  voice)

Tests to determine if the voice is ready to receive a new buffer sample with ASND_AddVoice().

You can use this function to block a reader when double buffering is used. It works similarly to ASND_TestPointer() without needing to pass a pointer.

Parameters
[in]voiceVoice to test, from 0 to (MAX_SND_VOICES-1).
Returns
SND_INVALID
0 if voice is NOT ready to receive a new voice.
1 if voice is ready to receive a new voice with ASND_AddVoice().