Cross-Platform Game Programming with gameplay3d/Audio
Overview
editGameplay3d 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 aNode
and positioned in 3D space; - Non-positional audio, such as music, is achieved by creating and playing an
AudioSource
which is not attached to aNode
; and - Your game has one
AudioListener
which receives the sound from theAudioSources
. By default, theAudioListener
is bound to the active camera of the scene, but can be attached to another camera or positioned manually if desired.
Supported audio formats
editGameplay3d 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
editAudioSources
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
editAn 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
editTo 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
editThe 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
editThe 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
}