The engine's whole surface onto the audio backend. More...

#include <audio_device.h>

Public Member Functions
bool	open ()
	Open the default playback device and start its mixer thread.
bool	openOffline (uint32_t sampleRate, uint32_t channels)
	Open the mixer with no device, to be pumped by render().
void	close ()
	Stop every voice and shut the mixer down; idempotent.
uint64_t	render (float *frames, uint64_t frameCount)
	Pull mixed frames from an offline mixer into `frames`.
VoiceId	play (const AudioClipAsset &clip, const VoiceParams &params)
	Start playing `clip` and return the voice driving it.
void	updateVoice (VoiceId voice, const VoiceParams &params)
	Push a voice's parameters to the mixer; an unknown or finished voice is ignored.
bool	isVoiceActive (VoiceId voice) const
	Whether `voice` is still there with audio left to play.
void	pauseVoice (VoiceId voice)
	Hold `voice` at its cursor, silently, without ending it.
void	resumeVoice (VoiceId voice)
	Let `voice` play on from where it was held, ramped back in.
bool	isVoicePaused (VoiceId voice) const
	Whether `voice` is being held by a pause rather than playing.
float	voiceCursor (VoiceId voice) const
	How far into its clip `voice` has played, in seconds.
void	seekVoice (VoiceId voice, float seconds)
	Move `voice's` cursor to `seconds` into its clip.
void	stopVoice (VoiceId voice)
	Ramp `voice` to silence and let it go.
void	reapFinishedVoices ()
	Release every voice that has played to its end, or been ramped out by stopVoice().
void	stopAllVoices ()
	Cut and release every voice at once, leaving the device open.
void	pauseAllVoices ()
	Hold every voice that is sounding right now.
void	resumeAllVoices ()
	Let every voice pauseAllVoices() is still holding play on.
size_t	voiceCount () const
	Number of voices the mixer currently holds.
void	setListener (const glm::vec3 &position, const glm::vec3 &forward, const glm::vec3 &up)
	Place the ear.
void	setListenerActive (bool active)
	Whether anything is listening.
void	setMasterVolume (float volume)
	Master gain applied to the whole mix.
float	masterVolume () const noexcept
	The master gain the mix is running at, after setMasterVolume's sanitising.

Detailed Description

The engine's whole surface onto the audio backend.

audio_device.cpp is the only file under src/engine that includes miniaudio. A voice shares ownership of its clip's samples, so a sound outlives its graph. Main-thread only, render() included, and unguarded; with no device open() returns false and every other call is a no-op. See docs/reference/audio.md, "Which thread may call the device" and "The known races are miniaudio's".

Member Function Documentation

◆ open()

bool Vkm::Engine::AudioDevice::open ( )

Open the default playback device and start its mixer thread.

Excludes the null backend, which would succeed with no audio hardware.

Returns: True when a device opened; false leaves the engine silent.

◆ openOffline()

bool Vkm::Engine::AudioDevice::openOffline	(	uint32_t	sampleRate,
		uint32_t	channels )

Open the mixer with no device, to be pumped by render().

The same mix, output to the caller's buffer instead of hardware.

Parameters

sampleRate	Mix rate; the caller's buffer is at this rate.
channels	Output channel count (2 to hear panning at all).

Returns: True when the mixer initialised.

◆ render()

uint64_t Vkm::Engine::AudioDevice::render	(	float *	frames,
		uint64_t	frameCount )

Pull mixed frames from an offline mixer into frames.

Only meaningful after openOffline().

Parameters

frames	Destination for interleaved 32-bit float samples; must hold frameCount * the channel count openOffline() was given.
frameCount	Frames to mix.

Returns: Frames actually written.

◆ play()

VoiceId Vkm::Engine::AudioDevice::play	(	const AudioClipAsset &	clip,
		const VoiceParams &	params )

Start playing clip and return the voice driving it.

Parameters

clip	Decoded clip to play; an empty one yields no voice.
params	Initial gain, pitch, looping and position.

Returns: The new voice, or 0 if the device is closed or the sound could not be created.

◆ updateVoice()

void Vkm::Engine::AudioDevice::updateVoice	(	VoiceId	voice,
		const VoiceParams &	params )

Push a voice's parameters to the mixer; an unknown or finished voice is ignored.

Parameters

voice	Voice to update.
params	Gain, pitch, looping and position from now on.

◆ isVoiceActive()

bool Vkm::Engine::AudioDevice::isVoiceActive ( VoiceId voice ) const

Whether voice is still there with audio left to play.

False once a one-shot reaches its end; a looping voice stays true until stopped. A paused voice answers true; see isVoicePaused.

Parameters

voice Voice asked about.

Returns: Whether it still has audio to play, held or not.

◆ pauseVoice()

void Vkm::Engine::AudioDevice::pauseVoice ( VoiceId voice )

Hold voice at its cursor, silently, without ending it.

Ramped like a stop, so the cursor moves a few milliseconds past the call. A voice pauseAllVoices() already holds changes hands, so a world resume leaves it held.

Parameters

voice Voice to hold; unknown ids are ignored.

◆ resumeVoice()

void Vkm::Engine::AudioDevice::resumeVoice ( VoiceId voice )

Let voice play on from where it was held, ramped back in.

Releases a pauseAllVoices() hold as readily as a pauseVoice() one.

Parameters

voice Voice to let go; one not held, or unknown, is ignored.

◆ isVoicePaused()

bool Vkm::Engine::AudioDevice::isVoicePaused ( VoiceId voice ) const

Whether voice is being held by a pause rather than playing.

Parameters

voice Voice asked about.

Returns: Whether a pause is holding it; false for an unknown one.

◆ voiceCursor()

float Vkm::Engine::AudioDevice::voiceCursor ( VoiceId voice ) const

How far into its clip voice has played, in seconds.

The only copy of the cursor; see docs/reference/audio.md, "The cursor is the device's, not the component's".

Parameters

voice Voice to read; an unknown or finished one answers 0.

Returns: Seconds from the clip's start, counting a seek that has been asked for but not yet applied by the mixer.

◆ seekVoice()

void Vkm::Engine::AudioDevice::seekVoice	(	VoiceId	voice,
		float	seconds )

Move voice's cursor to seconds into its clip.

The mixer applies it before its next read. Clamped to the clip: miniaudio refuses an out-of-range seek yet still moves the sound's clock. Seeking to the end finishes it.

Parameters

voice	Voice to move; unknown ids are ignored.
seconds	Position from the clip's start; negative and non-finite values land at 0.

◆ stopVoice()

void Vkm::Engine::AudioDevice::stopVoice ( VoiceId voice )

Ramp voice to silence and let it go.

The few-millisecond ramp avoids a click; the id answers as released at once, and reapFinishedVoices() frees it after. A held voice stops being held.

Parameters

voice Voice to stop; unknown ids are ignored.

◆ reapFinishedVoices()

void Vkm::Engine::AudioDevice::reapFinishedVoices ( )

Release every voice that has played to its end, or been ramped out by stopVoice().

Makes play() safe for a caller that never keeps the id; ids are never reused. Also reopens a device that stopped by itself (reopenLostDevice), on the frame thread.

◆ stopAllVoices()

void Vkm::Engine::AudioDevice::stopAllVoices ( )

Cut and release every voice at once, leaving the device open.

For when the voices' clips are about to be freed, so not ramped: a ramping voice still reads its clip.

◆ pauseAllVoices()

void Vkm::Engine::AudioDevice::pauseAllVoices ( )

Hold every voice that is sounding right now.

For a tool's transport, not a game's pause (see AudioSystem). A voice started afterwards plays.

◆ resumeAllVoices()

void Vkm::Engine::AudioDevice::resumeAllVoices ( )

Let every voice pauseAllVoices() is still holding play on.

A voice held by pauseVoice(), or stopped while held, stays as it is.

◆ voiceCount()

size_t Vkm::Engine::AudioDevice::voiceCount ( ) const

Number of voices the mixer currently holds.

Returns: The voices held now, including any ramping out or paused.

◆ setListener()

void Vkm::Engine::AudioDevice::setListener	(	const glm::vec3 &	position,
		const glm::vec3 &	forward,
		const glm::vec3 &	up )

Place the ear.

Parameters

position	World position of the listener.
forward	World-space facing; the engine's forward is -Z, so this is what Math::computeForward returns, not the entity's +Z column.
up	World-space up for the listener.

◆ setListenerActive()

void Vkm::Engine::AudioDevice::setListenerActive ( bool active )

Whether anything is listening.

Without one, spatial voices go silent and 2D ones play on.

Parameters

active Whether a listener exists this frame.

◆ setMasterVolume()

void Vkm::Engine::AudioDevice::setMasterVolume ( float volume )

Master gain applied to the whole mix.

Parameters

volume Linear master gain; 0 and below, or non-finite, silence the mix.

◆ masterVolume()

float Vkm::Engine::AudioDevice::masterVolume ( ) const

inlinenoexcept

The master gain the mix is running at, after setMasterVolume's sanitising.

Returns: Linear master gain; 1 until something sets it otherwise.

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

system/audio/audio_device.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ open()

◆ openOffline()

◆ render()

◆ play()

◆ updateVoice()

◆ isVoiceActive()

◆ pauseVoice()

◆ resumeVoice()

◆ isVoicePaused()

◆ voiceCursor()

◆ seekVoice()

◆ stopVoice()

◆ reapFinishedVoices()

◆ stopAllVoices()

◆ pauseAllVoices()

◆ resumeAllVoices()

◆ voiceCount()

◆ setListener()

◆ setListenerActive()

◆ setMasterVolume()

◆ masterVolume()