OpenAL Driver

TGorillaOpenALManager implements the Gorilla3D audio manager on top of OpenAL Soft. It is the open source alternative to FMOD: positional audio, distance models, sound cones, Doppler and the EFX effect extension — without a commercial dependency, and it is the only driver available on Linux.

Table of Contents

Units

Unit Content
Gorilla.Audio.OpenAL TGorillaOpenALManager, sounds, channels, effects
Gorilla.Audio.OpenAL.Loader Loading WAV, OGG and MP3 into audio buffers
Gorilla.Audio.OpenAL.API Low level OpenAL and EFX bindings
Gorilla.Audio.MP3.API MP3 decoding through libmpg123
Gorilla.Audio.OGG.API OGG Vorbis decoding through libogg / libvorbis

Setting up the Manager

uses
  Gorilla.Audio.Manager, Gorilla.Audio.OpenAL;

var LAudio : TGorillaOpenALManager;
begin
  LAudio := TGorillaOpenALManager.Create(Self);
  LAudio.Parent := GorillaViewport1;

  if not LAudio.InitializeOpenAL() then
    raise Exception.Create('No OpenAL device available');
end;

Initialized tells you whether device and context are up. ShutdownOpenAL() releases everything again — it is called on destruction anyway.

Property Description
Sounds Collection of TGorillaOpenALSoundItem (the OpenAL buffers)
Channels Collection of TGorillaOpenALChannelItem (the OpenAL sources)
Effects Collection of TGorillaOpenALEffectItem (EFX effect slots)
ListenerPosition Position of the listener
ListenerVelocity Listener velocity, drives the Doppler effect
ListenerOrientation Six-component vector: forward and up
DopplerFactor Multiplier of the Doppler effect, default 1.0
Initialized True once device and context exist (read-only)

Sounds

A TGorillaOpenALSoundItem is an OpenAL buffer plus the source settings applied when it is played:

Property Description
FileName Audio file to load
Loaded True once the buffer holds data (read-only)
Format TStreamFormat — mono/stereo, sample rate, bit depth (read-only)
Streaming Streams from disk instead of loading the file completely
Position, Velocity 3D placement of the sound
Volume, Pitch, Looping Basic playback settings
DistanceModel dmInverse, dmLinear or dmExponent
ReferenceDistance Distance up to which no attenuation happens
MaxDistance Distance the attenuation stops at
RolloffFactor How quickly the sound fades with distance
ConeInnerAngle, ConeOuterAngle, ConeOuterGain Directional sound cone
PlaybackPosition, PlaybackLength Position and length in ms (read-only)
var LSound : TGorillaOpenALSoundItem;
begin
  LSound := LAudio.Sounds.Add();
  LSound.DisplayName := 'torch';
  LSound.FileName    := 'sounds/torch.wav';
  LSound.Looping     := true;
  LSound.Position    := Point3D(4, 1, -2);
  LSound.ReferenceDistance := 2;
  LSound.MaxDistance       := 30;
  LSound.LoadBuffer();

  // or load everything configured at design time in one go
  LAudio.LoadAllSounds();
end;

Lookup helpers: Sounds.FindByName(), Sounds.FindByFileName(), GetSoundItemByFilename(). LoadBufferFromStream() fills a buffer from a stream, UnloadBuffer() releases it.

Channels

In this driver a channel is a named group of sounds that are played, paused and positioned together — the OpenAL counterpart to an FMOD channel group.

var LChannel : TGorillaOpenALChannelItem;
begin
  LChannel := LAudio.Channels.Add();
  LChannel.Name   := 'SFX';
  LChannel.Volume := 0.4;

  LAudio.AddSoundToChannel('SFX', 'torch');
  LAudio.AddSoundToChannel('SFX', 'footstep');

  LAudio.PlayChannel('SFX');
  LAudio.PauseChannel('SFX');
  LAudio.ResumeChannel('SFX');
  LAudio.StopChannel('SFX');

  if LAudio.GetChannelState('SFX') = psPlaying then
    ...;
end;

Further channel operations: RemoveSoundFromChannel(), ClearChannelSounds(), ChannelHasSound(), GetChannelSoundCount(), StopAllChannels() and ClearAllChannels(). Channel states are psInitial, psPlaying, psPaused and psStopped.

Playing single sounds works as well and returns the channel the sound landed in:

LChannel := LAudio.PlaySound('torch');
LChannel := LAudio.PlaySoundItem(LSound);

Effects

The EFX extension is exposed through effect slots. Each slot has a type and can be applied to a channel:

Effect type
etNone No effect
etReverb Room reverb
etChorus Chorus
etEcho Echo / delay
etDistortion Distortion
etFlanger Flanger
etCompressor Compressor
var LEffect : TGorillaOpenALEffectItem;
begin
  LEffect := LAudio.Effects.Add();
  LEffect.Name       := 'CaveReverb';
  LEffect.EffectType := etReverb;
  LEffect.Enabled    := true;

  LAudio.ApplyEffectToChannel('SFX', 'CaveReverb');
end;

EFX requires an OpenAL implementation that supports it. OpenAL Soft does; some vendor drivers do not.

The Listener

LAudio.SetListenerWorldPosition(Camera1.AbsolutePosition.Point);
LAudio.ListenerOrientation := TVector6D.Create(
  LForward.X, LForward.Y, LForward.Z,
  LUp.X,      LUp.Y,      LUp.Z);
LAudio.ListenerVelocity := LPlayerVelocity;
LAudio.DopplerFactor    := 1.0;

TVector6D packs the two vectors OpenAL expects: the first three components are the forward ("at") vector, the last three the up vector. TVector6D.Default returns the standard orientation.

Unlike FMOD there is no automatic listener target — update the listener from your camera every frame.

Distance Models

Model Behaviour
dmInverse Inverse distance attenuation — the physically plausible default
dmLinear Linear falloff between reference and maximum distance, reaches true silence
dmExponent Exponential falloff, useful for a dramatic close-up effect

The model works together with ReferenceDistance, MaxDistance and RolloffFactor. A common mistake is leaving ReferenceDistance at its default while working in a scene scaled in centimetres — the sound is then attenuated long before it should be.

Supported Formats

Format Decoder
WAV (PCM) Built in
OGG Vorbis ogg / vorbis / vorbisfile libraries
MP3 libmpg123

LoadAudioFile() in Gorilla.Audio.OpenAL.Loader picks the decoder by file extension, so LoadSoundItemFromFile() handles all three transparently.

The Update Loop

procedure TForm1.GorillaViewport1Render(Sender : TObject; ...);
begin
  LAudio.Update();
end;

Update() refills streaming buffers and retires finished sources. Without it, streamed sounds stop after their first buffer.

Libraries and Deployment

The OpenAL binaries ship with Gorilla3D under <installation>\lib\OpenAL\.

File Purpose
openal32.dll (Windows), libopenal.so / .dylib The OpenAL implementation
oalinst.exe OpenAL Soft installer, for systems without a system-wide OpenAL
libmpg123-0.dll MP3 decoding
ogg.dll, vorbis.dll, vorbisfile.dll, vorbisenc.dll OGG Vorbis decoding

Deploy the libraries next to your executable, or run oalinst.exe once during installation. On Linux, OpenAL is usually available through the distribution package manager (libopenal1).

Upstream sources:

Best Practices

  • Check the result of InitializeOpenAL() — a missing device is a normal case, not an exception
  • Use channels as buses, and mix through the channel volume
  • Enable Streaming for music and long ambiences, leave it off for short effects
  • Tune ReferenceDistance / MaxDistance to the scale of your scene
  • Update the listener from the camera every frame, including its orientation
  • Set ListenerVelocity only when you actually want Doppler, otherwise it produces surprising pitch shifts

See Also

API Reference

Related Topics