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

The s3eSound API
If you want to add spot sound effects to your game, such as laser bolts and
explosions, the s3eSound API is what you need to use. This API allows multiple
sound samples to be played simultaneously at different volumes and pitch by
mixing them together into a single output.
To make use of the s3eSound API, simply include the file s3eSound.h in your
source code.
The API expects all sound effects to be supplied as uncompressed 16-bit signed
PCM. File formats such as WAV are not supported by the API, so you must write
your own code to load and extract the sample data from such files.
As you read through this section you may start to think that there's an awful lot to do
in order to play some sound effects. While this may appear to be the case, s3eSound
is actually a very low-level API and provides enough flexibility to allow you to code
your own complex sound routines.
Later in this chapter we will be covering the SoundEngine module, which comes
with Marmalade to provide a wrapper for the s3eSound API. The SoundEngine
module takes care of most of the hard work involved in using the s3eSound API for
us and also includes the ability to load WAV files directly from a GROUP file.
Starting sound playback
In order to play a sound sample using s3eSound, the first thing we have to do is
allocate a free sound channel. The s3eSound API provides a limited number of
channels (we'll see later how to determine exactly how many are available) that
allow us to specify a sound sample, volume, and playback rate. The sound data
for all currently active channels is then mixed together in the inner workings of
s3eSound into a single waveform and this is what is played through the device's
sound hardware. To allocate a free channel, we make the following function call:
int32 lChannel = s3eSoundGetFreeChannel();
This will return the ID number of a free channel, or -1 if no channel is available.
Most of the time it is unlikely that a free channel will not be available, but if we are
playing a lot of sound effects we might want to consider tagging each of our sound
effects with a priority value and maintaining a list of currently active sounds. When
we run out of channels, we can check the list of sounds and reclaim the channel
being used by the lowest priority sound effect, assuming that it is at a lower priority
than the sound we wish to start of course!