17.2 Sampled Sound Playback

17.2.1 Representing Sound

The Audio Library supports playback of both uncompressed and ADPCM compressed, 16-bit audio. (Currently, the sample format support includes only mono ADPCM compression format.) An audio waveform is represented with the Sound object via the ALSound structure. The ALSound structure contains entries for the envelope, pan, and volume along with a pointer to the ALWaveTable structure (which contains the audio).

Collections of sounds can be stored in an ALBankFile structure. The format of this structure is described in Chapter 19 "Audio File Formats" The tools available to create Bank Files for inclusion in the ROM are described in Chapter 18 "Audio Tools".

Note: Currently, the only supported sample formats are single-channel, ADPCM compressed and 16-bit uncompressed.

17.2.2 Playing Sound

The Sound Player is the mechanism by which the Audio Library plays back individual sounds, such as isolated sound effects. It is responsible for allocating the resources needed to play a sound and for controlling the performance of the sound data for the application.

There are certain steps you must take for your game to play a sound. At a minimum, you must:

1. Create and initialize the basic resources described in the section "Generating Audio Output".
   
   
2. Instantiate the Sound Player with alSndpNew(). The Sound Player created also signs in as a client to the Synthesis Driver.
   
   
3. Load the sound bank's .ctl file into RAM, and initialize it with a call to alBnkfNew.
   
   
4. Allocate a sound with a call to alSndpAllocate()
   
   
5. Set the Sound Player's target sound to reference your sound with alSndpSetSound()
   
   
6. Play the sound with alSndpPlay().
   
   
7. Stop the sound when you are finished with alSndpStop(). Note that if the sound is not looped, the sound player will take care of stopping the sound when it is finished playing. However, you can stop the sound at any time during playback with this call.
   
   

When the sound is no longer needed, the resources in the Sound Player can be freed with a call to alSndpDeallocate(). If the Sound Player itself is no longer required, it can be removed from the Synthesis Driver callback list with alSndpDelete().

The Sound Player can play both looped and unlooped sounds. When playing a sound, the Sound Player steps through the Envelope states Attack, Decay, and Release. Envelope parameters are defined in the ALSound structure. The duration of the sound is determined by the sum of the Attack time, Decay time, and Release time, or the length of the wavetable (whichever is shorter), scaled by the pitch.

For looped sounds, the duration is always determined by the Envelope parameters and the pitch. If the Envelope Decay time is set to -1, the sound will continue playing (that is, it will never enter the Release phase) until it is stopped by the application with a call to alSndpStop(). Envelope times are scaled by the playback pitch so that regardless of pitch, finite-length sounds play to completion. For example, by default, a sound played an octave lower plays for twice as long as it does at unity pitch. Loop points for sounds are embedded in the ALWaveTable structure. (Loop points will be automatically extracted from the .aiff file when using the file conversion tools provided such as vadpcm_enc.)

Various parameters that affect the playback of a sound can be set before and during playback. When a sound is allocated to a Sound Player, an ID is returned that uniquely identifies that sound. Parameters for a particular sound are set by first setting the target sound with a call to alSndpSetSound(), and then making a subsequent call to set a parameter for the target sound. Available calls are described in Table 17-1 below.

Note: Each sound allocated to a Sound Player has a unique ID and private parameter values and play state. To play the same sound simultaneously, possibly with different parameter settings, it must be allocated multiple times to the Sound Player.

A summary of Sound Player functions is given below. Details can be found in the reference (man) pages.