Owns the miniaudio engine and provides the playback API. More...

#include <AudioEngine.h>

Collaboration diagram for Engine::Core::AudioEngine:

Classes
struct	PendingPlay
	Deferred playback request awaiting its clip's async payload. More...
struct	PlayingFlow
	Active flow graph playback instance. More...
struct	PlayingSound
	Active miniaudio sound instance owned by the audio engine. More...
struct	SpatializedSound
	Active spatialized sound referencing a Steam Audio backend source. More...

Public Member Functions
	AudioEngine (const AudioClipStore *audioClips=nullptr)
	Construct an uninitialized audio engine.
	~AudioEngine ()
	Shut down the audio engine on destruction.
	AudioEngine (const AudioEngine &)=delete
	AudioEngine owns native audio resources and cannot be copied.
AudioEngine &	operator= (const AudioEngine &)=delete
	AudioEngine owns native audio resources and cannot be copy-assigned.
bool	init ()
	Initialize the miniaudio engine with AudioConfig settings.
bool	setPlaybackDevice (std::optional< uint32_t > deviceIndex)
	Rebuilds the audio backend using a playback device from getPlaybackDevices().
std::vector< AudioDeviceInfo >	getPlaybackDevices () const
	Enumerates playback devices currently reported by miniaudio.
const std::string &	getPlaybackDeviceName () const
	Returns the active playback device name, or an empty string when audio is disabled.
void	cleanup ()
	Shut down the audio engine and free all resources.
void	onAudioLoaded (Assets::Audio *asset, const std::filesystem::path &path)
	Called by AudioAssetPipeline when an asset finishes loading. Starts any deferred playback requests that were waiting on this clip.
AudioHandle	play (Assets::AudioClipHandle clip, float volume=1.0f, bool loop=false)
	Play a loaded audio clip by its stable asset handle.
void	setFlowStore (Assets::AudioFlowStore *store)
	Set the flow registry used to resolve flow playback.
AudioHandle	playFlow (Assets::AudioFlowHandle flow, float volume=1.0f, bool loop=false)
	Play an audio flow (reactive node graph) non-spatialized.
void	setFlowParam (AudioHandle handle, Assets::FlowSettingHandle setting, float value)
	Change a reactive flow setting on a playing flow instance.
AudioHandle	playSpatialized (Assets::AudioClipHandle clip, const glm::vec3 &worldPosition, float volume=1.0f, bool loop=false)
	Play an audio clip spatialized at a world position by stable handle.
void	updateSpatializedSource (AudioHandle handle, const glm::vec3 &worldPosition)
	Move a playing spatialized source to a new world position.
void	setListener (const glm::vec3 &worldPosition, const glm::quat &worldOrientation)
	Update the HRTF listener pose from the headset.
void	stop (AudioHandle handle)
	Stop a playing sound.
void	stopAll ()
	Stop all currently playing sounds.
void	setMasterVolume (float volume)
	Set the master volume.
float	getMasterVolume () const
bool	isPlaying (AudioHandle handle) const
	Check if a sound is currently playing.
bool	isInitialized () const
	Check if the audio engine initialized successfully.
void	renderSpatialized (float *pFramesOut, std::uint64_t frameCount)
	Accumulate the Steam Audio binaural mix into the engine output. Called from the audio thread via the miniaudio engine onProcess hook.

Private Member Functions
bool	init (std::optional< uint32_t > deviceIndex)
void	shutdownBackend ()
AudioHandle	startPlayback (Assets::Audio *asset, const std::string &assetPath, float volume, bool loop, const std::optional< glm::vec3 > &worldPosition, AudioHandle handle)
	Starts playback of a decoded audio payload.
void	drainPendingForPath (const std::filesystem::path &path, Assets::Audio *asset)
	Starts pending (deferred) playback requests whose clip payload just landed.
void	purgeStalePending ()
	Drops deferred playback requests whose clip failed to load or expired.
void	cleanupFinishedSounds ()

Private Attributes
const AudioClipStore *	audioClips_ = nullptr
Assets::AudioFlowStore *	flowStore_ = nullptr
ma_context *	context_ = nullptr
ma_engine *	engine_ = nullptr
bool	initialized_ = false
float	masterVolume_ = 1.0f
std::string	playbackDeviceName_
std::unique_ptr< SteamAudioBackend >	steamAudio_
ma_sound *	silenceSound_ = nullptr
	Silent looping sound that keeps the engine node graph producing frames, so the onProcess hook fires even when only spatialized sources are active. Stores an ma_audio_buffer* (anonymous-struct typedef, not forward-declarable).
void *	silenceBuffer_ = nullptr
AudioHandle	nextHandle_ = 1
std::unordered_map< AudioHandle, PlayingSound >	playingSounds_
std::unordered_map< AudioHandle, SpatializedSound >	spatializedSounds_
std::unordered_map< AudioHandle, PlayingFlow >	playingFlows_
std::unordered_map< AudioHandle, PendingPlay >	pendingPlays_

Detailed Description

Owns the miniaudio engine and provides the playback API.

Initialized once during engine startup. Clips are played by stable handle (AudioClipStore); playback resolves the decoded payload through the clip store, and if the payload is still loading asynchronously the request is deferred and starts once it lands.

Definition at line 49 of file AudioEngine.h.

Constructor & Destructor Documentation

◆ AudioEngine() [1/2]

Engine::Core::AudioEngine::AudioEngine ( const AudioClipStore * audioClips = nullptr )

explicit

Construct an uninitialized audio engine.

Parameters

audioClips Audio clip store used to resolve typed handles for playback.

Referenced by AudioEngine(), and operator=().

Here is the caller graph for this function:

◆ ~AudioEngine()

Engine::Core::AudioEngine::~AudioEngine ( )

Shut down the audio engine on destruction.

◆ AudioEngine() [2/2]

Engine::Core::AudioEngine::AudioEngine ( const AudioEngine & )

delete

AudioEngine owns native audio resources and cannot be copied.

References AudioEngine().

Here is the call graph for this function:

Member Function Documentation

◆ cleanup()

void Engine::Core::AudioEngine::cleanup ( )

Shut down the audio engine and free all resources.

◆ cleanupFinishedSounds()

void Engine::Core::AudioEngine::cleanupFinishedSounds ( )

private

◆ drainPendingForPath()

void Engine::Core::AudioEngine::drainPendingForPath	(	const std::filesystem::path &	path,
		Assets::Audio *	asset )

private

Starts pending (deferred) playback requests whose clip payload just landed.

Parameters

path	Source path that finished loading.
asset	Loaded payload, or nullptr when the load failed.

◆ getMasterVolume()

float Engine::Core::AudioEngine::getMasterVolume ( ) const

inlinenodiscard

Definition at line 182 of file AudioEngine.h.

References masterVolume_.

◆ getPlaybackDeviceName()

const std::string & Engine::Core::AudioEngine::getPlaybackDeviceName ( ) const

inlinenodiscard

Returns the active playback device name, or an empty string when audio is disabled.

Definition at line 93 of file AudioEngine.h.

References playbackDeviceName_.

◆ getPlaybackDevices()

std::vector< AudioDeviceInfo > Engine::Core::AudioEngine::getPlaybackDevices ( ) const

nodiscard

Enumerates playback devices currently reported by miniaudio.

◆ init() [1/2]

bool Engine::Core::AudioEngine::init ( )

Initialize the miniaudio engine with AudioConfig settings.

Returns: true on success

◆ init() [2/2]

bool Engine::Core::AudioEngine::init ( std::optional< uint32_t > deviceIndex )

private

◆ isInitialized()

bool Engine::Core::AudioEngine::isInitialized ( ) const

inlinenodiscard

Check if the audio engine initialized successfully.

Returns: true if init() completed successfully and cleanup() has not shut it down

Definition at line 195 of file AudioEngine.h.

References initialized_.

◆ isPlaying()

bool Engine::Core::AudioEngine::isPlaying ( AudioHandle handle ) const

nodiscard

Check if a sound is currently playing.

Parameters

handle Handle returned by play()

Returns: true if the sound is still playing

◆ onAudioLoaded()

void Engine::Core::AudioEngine::onAudioLoaded	(	Assets::Audio *	asset,
		const std::filesystem::path &	path )

Called by AudioAssetPipeline when an asset finishes loading. Starts any deferred playback requests that were waiting on this clip.

Parameters

asset	The loaded audio asset
path	The asset path (used to match deferred play requests)

◆ operator=()

AudioEngine & Engine::Core::AudioEngine::operator= ( const AudioEngine & )

delete

AudioEngine owns native audio resources and cannot be copy-assigned.

References AudioEngine().

Here is the call graph for this function:

◆ play()

AudioHandle Engine::Core::AudioEngine::play	(	Assets::AudioClipHandle	clip,
		float	volume = 1.0f,
		bool	loop = false )

Play a loaded audio clip by its stable asset handle.

Parameters

clip	Handle returned by AudioClipStore::load().
volume	Volume multiplier (0.0 - 1.0).
loop	Whether to loop the sound.

Returns: Handle to the playing sound, or INVALID_AUDIO_HANDLE when the clip is invalid or not loaded.

◆ playFlow()

AudioHandle Engine::Core::AudioEngine::playFlow	(	Assets::AudioFlowHandle	flow,
		float	volume = 1.0f,
		bool	loop = false )

Play an audio flow (reactive node graph) non-spatialized.

Parameters

flow	Stable handle returned by the audio flow store.
volume	Volume multiplier (0.0 - 1.0).
loop	Whether the flow should keep playing (looping clips wrap).

Returns: Handle to the playing flow instance, or INVALID_AUDIO_HANDLE.

◆ playSpatialized()

AudioHandle Engine::Core::AudioEngine::playSpatialized	(	Assets::AudioClipHandle	clip,
		const glm::vec3 &	worldPosition,
		float	volume = 1.0f,
		bool	loop = false )

Play an audio clip spatialized at a world position by stable handle.

Parameters

clip	Handle returned by AudioClipStore::load().
worldPosition	World-space position of the sound source.
volume	Volume multiplier (0.0 - 1.0).
loop	Whether to loop the sound.

Returns: Handle to the playing spatialized sound, or INVALID_AUDIO_HANDLE on failure.

◆ purgeStalePending()

void Engine::Core::AudioEngine::purgeStalePending ( )

private

Drops deferred playback requests whose clip failed to load or expired.

◆ renderSpatialized()

void Engine::Core::AudioEngine::renderSpatialized	(	float *	pFramesOut,
		std::uint64_t	frameCount )

Accumulate the Steam Audio binaural mix into the engine output. Called from the audio thread via the miniaudio engine onProcess hook.

◆ setFlowParam()

void Engine::Core::AudioEngine::setFlowParam	(	AudioHandle	handle,
		Assets::FlowSettingHandle	setting,
		float	value )

Change a reactive flow setting on a playing flow instance.

Parameters

handle	Handle returned by playFlow().
setting	Stable setting handle from AudioFlowStore::findSetting().
value	New value (clamped to the setting's range).

◆ setFlowStore()

void Engine::Core::AudioEngine::setFlowStore ( Assets::AudioFlowStore * store )

inline

Set the flow registry used to resolve flow playback.

Parameters

store Audio flow store populated by AudioFlowLoader, or nullptr.

Definition at line 121 of file AudioEngine.h.

References flowStore_.

◆ setListener()

void Engine::Core::AudioEngine::setListener	(	const glm::vec3 &	worldPosition,
		const glm::quat &	worldOrientation )

Update the HRTF listener pose from the headset.

Parameters

worldPosition	World position of the headset.
worldOrientation	World orientation of the headset.

◆ setMasterVolume()

void Engine::Core::AudioEngine::setMasterVolume ( float volume )

Set the master volume.

Parameters

volume Volume multiplier (0.0 - 1.0)

◆ setPlaybackDevice()

bool Engine::Core::AudioEngine::setPlaybackDevice ( std::optional< uint32_t > deviceIndex )

Rebuilds the audio backend using a playback device from getPlaybackDevices().

Parameters

deviceIndex Device index, or std::nullopt to use the system default.

Returns: true when the new backend initialized successfully.

◆ shutdownBackend()

void Engine::Core::AudioEngine::shutdownBackend ( )

private

◆ startPlayback()

AudioHandle Engine::Core::AudioEngine::startPlayback	(	Assets::Audio *	asset,
		const std::string &	assetPath,
		float	volume,
		bool	loop,
		const std::optional< glm::vec3 > &	worldPosition,
		AudioHandle	handle )

private

Starts playback of a decoded audio payload.

Parameters

asset	Decoded payload (must stay valid for the duration of the call).
assetPath	Source path used for diagnostics and lifecycle bookkeeping.
volume	Volume multiplier (0.0 - 1.0).
loop	Whether to loop the sound.
worldPosition	World position for spatialized playback, or nullopt for non-spatialized.
handle	Pre-allocated AudioHandle that will own the started sound.

Returns: handle on success, or INVALID_AUDIO_HANDLE when the sound could not be created.

◆ stop()

void Engine::Core::AudioEngine::stop ( AudioHandle handle )

Stop a playing sound.

Parameters

handle Handle returned by play()

◆ stopAll()

void Engine::Core::AudioEngine::stopAll ( )

Stop all currently playing sounds.

◆ updateSpatializedSource()

void Engine::Core::AudioEngine::updateSpatializedSource	(	AudioHandle	handle,
		const glm::vec3 &	worldPosition )

Move a playing spatialized source to a new world position.

Parameters

handle	Handle returned by playSpatialized().
worldPosition	New world-space position of the source.

Member Data Documentation

◆ audioClips_

const AudioClipStore* Engine::Core::AudioEngine::audioClips_ = nullptr

private

Definition at line 234 of file AudioEngine.h.

◆ context_

ma_context* Engine::Core::AudioEngine::context_ = nullptr

private

Definition at line 236 of file AudioEngine.h.

◆ engine_

ma_engine* Engine::Core::AudioEngine::engine_ = nullptr

private

Definition at line 237 of file AudioEngine.h.

◆ flowStore_

Assets::AudioFlowStore* Engine::Core::AudioEngine::flowStore_ = nullptr

private

Definition at line 235 of file AudioEngine.h.

Referenced by setFlowStore().

◆ initialized_

bool Engine::Core::AudioEngine::initialized_ = false

private

Definition at line 238 of file AudioEngine.h.

Referenced by isInitialized().

◆ masterVolume_

float Engine::Core::AudioEngine::masterVolume_ = 1.0f

private

Definition at line 239 of file AudioEngine.h.

Referenced by getMasterVolume().

◆ nextHandle_

AudioHandle Engine::Core::AudioEngine::nextHandle_ = 1

private

Definition at line 253 of file AudioEngine.h.

◆ pendingPlays_

std::unordered_map<AudioHandle, PendingPlay> Engine::Core::AudioEngine::pendingPlays_

private

Definition at line 337 of file AudioEngine.h.

◆ playbackDeviceName_

std::string Engine::Core::AudioEngine::playbackDeviceName_

private

Definition at line 240 of file AudioEngine.h.

Referenced by getPlaybackDeviceName().

◆ playingFlows_

std::unordered_map<AudioHandle, PlayingFlow> Engine::Core::AudioEngine::playingFlows_

private

Definition at line 301 of file AudioEngine.h.

◆ playingSounds_

std::unordered_map<AudioHandle, PlayingSound> Engine::Core::AudioEngine::playingSounds_

private

Definition at line 269 of file AudioEngine.h.

◆ silenceBuffer_

void* Engine::Core::AudioEngine::silenceBuffer_ = nullptr

private

Definition at line 251 of file AudioEngine.h.

◆ silenceSound_

ma_sound* Engine::Core::AudioEngine::silenceSound_ = nullptr

private

Silent looping sound that keeps the engine node graph producing frames, so the onProcess hook fires even when only spatialized sources are active. Stores an ma_audio_buffer* (anonymous-struct typedef, not forward-declarable).

Definition at line 250 of file AudioEngine.h.

◆ spatializedSounds_

std::unordered_map<AudioHandle, SpatializedSound> Engine::Core::AudioEngine::spatializedSounds_

private

Definition at line 285 of file AudioEngine.h.

◆ steamAudio_

std::unique_ptr<SteamAudioBackend> Engine::Core::AudioEngine::steamAudio_

private

Definition at line 242 of file AudioEngine.h.

The documentation for this class was generated from the following file:

/workspace/magerbeton/gl3-vulkan/code/Engine/include/Engine/Audio/AudioEngine.h

Classes

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ AudioEngine() [1/2]

◆ ~AudioEngine()

◆ AudioEngine() [2/2]

Member Function Documentation

◆ cleanup()

◆ cleanupFinishedSounds()

◆ drainPendingForPath()

◆ getMasterVolume()

◆ getPlaybackDeviceName()

◆ getPlaybackDevices()

◆ init() [1/2]

◆ init() [2/2]

◆ isInitialized()

◆ isPlaying()

◆ onAudioLoaded()

◆ operator=()

◆ play()

◆ playFlow()

◆ playSpatialized()

◆ purgeStalePending()

◆ renderSpatialized()

◆ setFlowParam()

◆ setFlowStore()

◆ setListener()

◆ setMasterVolume()

◆ setPlaybackDevice()

◆ shutdownBackend()

◆ startPlayback()

◆ stop()

◆ stopAll()

◆ updateSpatializedSource()

Member Data Documentation

◆ audioClips_

◆ context_

◆ engine_

◆ flowStore_

◆ initialized_

◆ masterVolume_

◆ nextHandle_

◆ pendingPlays_

◆ playbackDeviceName_

◆ playingFlows_

◆ playingSounds_

◆ silenceBuffer_

◆ silenceSound_

◆ spatializedSounds_

◆ steamAudio_