Adding Sound and Video - Marmalade SDK Mobile Game Development Essentials - page 196

The s3eSound API allows us to set several different callback functions on a
per channel basis and we use the functions s3eSoundChannelRegister and
s3eSoundChannelUnRegister to enable and disable them as follows:
// To set up a sound channel callback
s3eSoundChannelRegister(lChannel, lCallbackType, (s3eCallback)
CallbackFunction, lpUserData);
// To disable a sound channel callback
s3eSoundChannelUnRegister(lChannel, lCallbackType);
As with all other Marmalade callbacks, we specify the code for the callback function
by passing in a pointer to the function itself, and we can also register a block of
user data that will be passed into this function when it is triggered. There are four
different callback types called S3E_CHANNEL_END_SAMPLE , S3E_CHANNEL_STOP_
AUDIO , S3E_CHANNEL_GEN_AUDIO , and S3E_CHANNEL_GEN_AUDIO_STEREO . We will
only take a look at the first two of them here, as the latter two are concerned with
generating custom audio streams and are beyond the scope of this topic. For an
example of how to use these callback types, take a look at the source code for the
SoundEngine module, which we'll be covering in the next section.
First let's look at the S3E_CHANNEL_END_SAMPLE callback, which allows us to loop
sounds and join different sounds together as a sequence. The registered callback
function is passed a pointer to an s3eSoundEndSampleInfo structure as its first
parameter. The structure indicates which sound channel has ended by using its m_
Channel member.
If we want to start a completely new sound playing on this channel, we can set the
m_NewData member of the s3eSoundEndSampleInfo structure to the start address of
the new sample data, and the m_NumSamples member to the number of samples in
the new waveform.
The structure also contains a member called m_RepsRemaining , which allows us to
change the number of repetitions of the sample data we want on this sound channel.
Note, though, that this callback will still be triggered every time the end of the
sample data has been reached.
If we wish the channel to continue playing sample data, be it the original data or
a new sample specified using the m_NewData and m_NumSamples members of the
s3eSoundEndSampleInfo structure, we must return a non-zero value from the
callback function. If zero is returned, the sound channel will stop playing.