AudioResources
Generated from engine/audio/audio_resources.h at aceb130. The text under each declaration is the header's own comment, word for word. About the reference says how these pages are made.
Audience: game code.
#include "engine/audio/audio_resources.h" · namespace labrador
class AudioResources
Section titled “class AudioResources”The sound banks, cached by name, and the sound groups whose volumes they mix in. The audio counterpart to RenderResources, and separate from it because the module table (ARCHITECTURE.md) has render and audio depending on core and math alone - neither knows the other exists, so nothing that only draws has to compile the audio stack to do it.
SoundBankHandle
Section titled “SoundBankHandle”SoundGroupHandle
Section titled “SoundGroupHandle”using SoundGroupHandle = labrador::SoundGroupHandle;AudioResources
Section titled “AudioResources”resolve_sound_bank
Section titled “resolve_sound_bank”SoundBankHandle resolve_sound_bank(const std::string& sound_bank_name) const;Load-time. Throws std::out_of_range naming the bank if nothing loaded it. Same bargain as RenderResources: resolve a name once, keep the handle, and never search by name again.
sound_bank
Section titled “sound_bank”SoundBank* sound_bank(const std::string& sound_bank_name) const;Const and non-mutating, like every other registry getter: throws std::out_of_range naming the bank if it is absent or released. The returned pointer is borrowed until this table is destroyed or add_sound_bank replaces or empties that name's slot. Keep a handle, not this pointer, across such a change and read the slot again.
add_sound_bank
Section titled “add_sound_bank”void add_sound_bank(const std::string& sound_bank_name,Takes ownership. Re-adding a name destroys its previous bank and refills the same slot; a null bank empties it. Existing handles keep naming that slot, and sound_bank throws while it is empty. Pointers returned before replacement or emptying must no longer be used. If adding a new name throws, it remains absent and can be retried; previously registered banks and their pointers/handles are unchanged.
Also lends the bank this object's group volumes, which is what lets its set_wave_group and set_effect_group accept a group. The bank and the volumes are both owned here, and the banks are destroyed first, so no bank outlives the volumes it was lent.
Banks are not device resources, so a device loss leaves them alone. A bank holds only handles: the voices and the wave bank behind them belong to the AudioDevice, which frees them when it is destroyed. Replacing or emptying a name therefore neither stops nor frees the previous bank's voices, and a looping effect it was playing keeps sounding with no handle left to stop it until the device is destroyed or, on XAudio2, reset after a device loss. Stop a bank's effects before replacing it.
SOUND GROUPS. A group is a volume a game sets once for many sounds - the music slider and the effects slider of a settings screen. A bank is told at load which of its waves and effects belong to which group (SoundBank::set_wave_group, set_effect_group), and from then on every level it sends to the device is the level the caller asked for times its group's volume. A sound in no group is at full group volume, so a game that never adds a group hears exactly what it asked for.
What a group is for, which sounds are in it and what its volume is are the game's; so are fades, ducking and authored levels, which a game builds from these calls and set_effect_volume (T1). A group spans banks, which is why it lives here rather than in one of them.
add_sound_group
Section titled “add_sound_group”SoundGroupHandle add_sound_group(const std::string& group_name);Load-time. Starts at volume 1. Throws std::invalid_argument naming the group if one of that name was already added. If storing a new group throws, its name remains absent and can be retried; existing groups and their volumes are unchanged.
resolve_sound_group
Section titled “resolve_sound_group”SoundGroupHandle resolve_sound_group(const std::string& group_name) const;Load-time. Throws std::out_of_range naming the group if none of that name was added.
set_group_volume
Section titled “set_group_volume”void set_group_volume(SoundGroupHandle group, float volume);Clamped to [0,1]. Throws std::invalid_argument for a NaN volume, before the handle is checked, and std::out_of_range through an unresolved handle.
A one-shot already playing keeps the level it was launched with, and one launched after this call takes the new level. A retained effect in the group, across every bank this holds, takes it now if it is playing or paused - a paused one plays at it when resumed - and a stopped one takes it at its next play_effect. Each of those pushes is one call to the device, made here and never per frame.
group_volume
Section titled “group_volume”float group_volume(SoundGroupHandle group) const;Throws std::out_of_range through an unresolved handle.
Related types
Section titled “Related types”Named in the public declarations above: Handle, SoundBank.
In the samples and tests
Section titled “In the samples and tests”The files that include this header directly. A file can also reach it through another header.
samples/audio/smoke_test.cpp,sound_board_tests.cpptests/assets/resource_loader_tests.cpp,wave_asset_tests.cpptests/audio/audio_resources_failure_tests.cpp,audio_resources_tests.cpptests/audio/null/memory_bank_tests.cpp,null_tests.cpptests/audio/webaudio/webaudio_tests.cpp
Explained in
Section titled “Explained in”Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.