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.
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:
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.
|alSndpNew||Creates a new Sound Player.|
|alSndpDelete||Removes a Sound Player from the Synthesis Driver's client list.|
|alSndpAllocate||Allocate a sound to a sound player.|
|alSndpDeallocate||Deallocate a sound from the sound player.|
|alSndpSetSound||Sets the Sound Player's current sound.|
|alSndpGetSound||Returns the Sound Player's current sound.|
|alSndpPlay||Plays the Sound Player's current sound.|
|alSndpPlayAt||Plays a sound at some specified time in the future.|
|alSndpStop||Stops the current sound from playing.|
|alSndpGetState||Gets the current state (stopped or playing) of the current sound.|
|alSndpSetPitch||Sets the pitch for the current sound.|
|alSndpSetVol||Sets the playback volume of the current sound.|
|alSndpSetPan||Sets the pan position of the current sound.|
|alSndpSetPriority||Sets the sounds priority value.|
|alSndpSetFXMix||Sets the wet/dry mix of the current sound.|