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
- Setting up the Manager
- Sounds
- Channels
- Effects
- The Listener
- Distance Models
- Supported Formats
- The Update Loop
- Libraries and Deployment
- Best Practices
- See Also
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:
- OpenAL Soft: https://openal-soft.org/
- libmpg123: https://www.mpg123.de/
- libogg / libvorbis: https://xiph.org/downloads/
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
Streamingfor music and long ambiences, leave it off for short effects - Tune
ReferenceDistance/MaxDistanceto the scale of your scene - Update the listener from the camera every frame, including its orientation
- Set
ListenerVelocityonly when you actually want Doppler, otherwise it produces surprising pitch shifts
See Also
API Reference
- Gorilla.Audio.OpenAL — Full class reference
- Gorilla.Audio.Manager — Base classes
Related Topics
- Audio Manager — The backend independent API
- FMOD Driver — The commercial alternative
- Audio Playlist — Playlist on top of this driver
- Speech-to-Text — Uses the OpenAL capture device for recording