Cross-Platform Game Programming with gameplay3d/Audio

Overview

Gameplay3d supports 3D audio (using OpenAL, the specification for which can be found here). The basic principles behind using sound in gameplay3d are as follows:

• Your game can have one or more AudioSource(s), which can, if desired, be attached to a Node and positioned in 3D space;
• Non-positional audio, such as music, is achieved by creating and playing an AudioSource which is not attached to a Node; and
• Your game has one AudioListener which receives the sound from the AudioSources. By default, the AudioListener is bound to the active camera of the scene, but can be attached to another camera or positioned manually if desired.

Supported audio formats

Gameplay3d currently supports the following formats:

• .ogg vorbis audio, which is a free and open-source compressed audio format specification; and
• .wav files, whichis a Microsoft and IBM uncompressed audio format.

Using .ogg files is recommended for release versions of your game, as they are compressed and therefore use less memory.

Creating an AudioSource

AudioSources can be created from an audio sample file as follows:

AudioSource* wheelsSound = AudioSource::create("res/explosion.wav");
AudioSource* backgroundMusic = AudioSource::create("res/music.ogg");

AudioSources can also be created and configured from a .audio file - see below for further details.

Positioning the AudioSource

An AudioSource can be bound to a Node in your scene using Node::setAudioSource(). The position of the audio source is automatically updated when the node is transformed.

For example, we could use the following example to position an AudioSource emitting a bird sound:

// Create and configure the AudioSource
AudioSource* audioSource = AudioSource::create("res/birdsound.ogg");
assert(audioSource);
audioSource->setLooped(true);

// Create a new node and set the AudioSource
Node* birdNode = _scene->addNode("bird");
birdNode->setAudioSource(audioSource);
SAFE_RELEASE(audioSource);

// Position the node (high up in the trees), add it to the scene and play the sound
birdNode->setTranslation(10.0f, 100.0f, 30.0f);
_scene->addNode(birdNode);
birdNode->getAudioSource()->play();
SAFE_RELEASE(birdNode);

Playing and controlling the AudioSource

To play an audio source:

audioSource->play();

Other member functions controlling playback are pause(), resume(), stop() and rewind().

We can configure the sound as follows:

audioSource->setLooped(true); // - Play the sound in a loop.

audioSource->setGain(0.5f);   // - Set the gain/volume of the audio source. 1.0 means that the sound is unattenuated.
                              //   Gain larger than one (i.e. amplification) is permitted for source and listener.
                              //   However, the implementation is free to clamp the total gain (effective gain per-source
                              //   multiplied by the listener gain) to one to prevent overflow.

audioSource->setPitch(2.0f);  // - 1.0 equals identity. Each reduction by 50 percent equals a pitch shift of -12
                              //   semitones (one octave reduction). Each doubling equals a pitch shift of 12
                              //   semitones (one octave increase). Zero is not a legal value.

audioSource->setVelocity(1.0f, 0.0f, 15.0f);   // - Velocity is taken into account by the OpenAL driver to synthesize the
                                               //   Doppler effect perceived by the listener for each source, based on the
                                               //   velocity of both source and listener (and the OpenAL Doppler-related
                                               //   parameters).

Positioning the AudioListener manually

The AudioListener can be positioned manually (in this case at the scene's origin) as follows:

AudioListener::getInstance()->setCamera(NULL);
AudioListener::getInstance()->setPosition(0.0f, 0.0f, 0.0f);

The AudioListener can be attached to a specific camera (e.g where multiple viewpoints are onscreen simultaneously) as follows:

AudioListener::getInstance()->setCamera(mainCamera);

.audio files

The following example illustrates how to set all of the AudioSource properties using a .audio file.

Add the following in your .cpp file:

AudioSource* source = AudioSource::create("res/game.audio#fireball");

Add the following in your game.audio file:

audio fireball
{
    path = res/audio/fireball.wav
    looped = false
    gain = 0.7
    pitch = 0.5
    velocity = 0.5 0.0 1.0
}