nCine::AudioDeviceBase class

Backend-independent part of an audio device.

Owns the source pool, the active players and the stream decoding thread. A backend hands over its source ids with SetSourcePool() and implements only the buffer and source operations.

Base classes

class IAudioDevice
Interface for an audio device backend.

Derived classes

class ALAudioDevice
OpenAL implementation of IAudioDevice.
class AicaAudioDevice
Dreamcast implementation of IAudioDevice on top of the AICA.
class AmigaAudioDevice
Classic Amiga implementation of IAudioDevice on top of ahi.device.
class AsndAudioDevice
Wii/GameCube implementation of IAudioDevice on top of libogc's ASND.
class N64AudioDevice
Nintendo 64 implementation of IAudioDevice on top of libdragon's RSP mixer.
class NdspAudioDevice
Implementation of IAudioDevice on top of the Nintendo 3DS's NDSP.
class Ps2AudioDevice
PlayStation 2 implementation of IAudioDevice on top of audsrv.
class Ps3AudioDevice
PlayStation 3 implementation of IAudioDevice on top of PSL1GHT's libaudio.
class PspAudioDevice
Implementation of IAudioDevice on top of the PSP's sceAudio hardware channel.
class SdlAudioDevice
Implementation of IAudioDevice on top of SDL2's audio queue.

Constructors, destructors, conversion operators

~AudioDeviceBase() override
AudioDeviceBase(const AudioDeviceBase&) deleted
AudioDeviceBase() protected

Public functions

auto operator=(const AudioDeviceBase&) -> AudioDeviceBase& deleted
auto GetGain() const -> float override
Returns the listener gain (master volume).
auto GetMaxPlayerCount() const -> std::uint32_t override
Returns the maximum number of players that can be active at once.
auto GetPlayerCount() const -> std::uint32_t override
Returns the number of currently active players.
auto GetPlayer(std::uint32_t index) const -> const IAudioPlayer* override
Returns the active player at the specified index.
auto GetPlayer(std::uint32_t index) -> IAudioPlayer* override
void StopPlayers() override
Stops every player currently playing.
void PausePlayers() override
Pauses every player currently playing.
void StopPlayers(PlayerType playerType) override
Stops every player of the specified type.
void PausePlayers(PlayerType playerType) override
Pauses every player of the specified type.
void FreezePlayers() override
Pauses every player currently playing while keeping it registered.
void UnfreezePlayers() override
Resumes every player previously paused by FreezePlayers().
auto RegisterPlayer(IAudioPlayer* player) -> std::uint32_t override
Registers a player so it receives state and buffer queue updates, returning its source id.
void UnregisterPlayer(IAudioPlayer* player) override
Unregisters a previously registered player.
void UpdatePlayers() override
Updates the state of every registered player, including the buffer queue of stream players.
auto SubmitStreamDecode(const std::shared_ptr<StreamDecodeRequest>& request) -> bool override
Submits a decode request to be executed asynchronously on the decoding thread.
void DrainStreamDecode(const std::shared_ptr<StreamDecodeRequest>& request) override
Ensures the specified request is neither queued nor being executed when this method returns.
auto GetListenerPosition() const -> const Vector3f& override
Returns the 3D position of the listener.
void BeginBlockingOperation() override
Tells the device the caller is about to stop feeding it for a long time.
void EndBlockingOperation() override
Ends what BeginBlockingOperation() started, and resumes playback.

Protected functions

void OnBlockingOperationBegan() virtual
Called when the outermost blocking operation begins.
void OnBlockingOperationEnded() virtual
Called when the last outstanding blocking operation ends (see OnBlockingOperationBegan()).
void SetSourcePool(ArrayView<const std::uint32_t> sourceIds)
Hands the source ids created by the backend over to the pool.
void ReportNoAvailableSources()
Reports that RegisterPlayer() had to refuse for lack of a free source.
void CheckForStalledSources()
Releases every source when the backend has stopped advancing them.
void ShutdownDecodeThread()
Stops the decoding thread and releases every request still queued.

Protected static variables

static std::size_t TypicalNumSources constexpr
Typical number of sources a backend creates, only the inline capacity of the pools.
static std::int32_t StalledCheckInterval constexpr
Number of frames between two looks at the playback positions while no source is free.
static float StalledTimeoutSecs constexpr
How long every source may read as playing without advancing before the device is given up on.
static float SourceWarningIntervalSecs constexpr
Shortest interval in seconds between two reports of an exhausted source pool.

Protected variables

float _gain
Listener gain (master volume).
Vector3f _listenerPos
Listener position.
SmallVector<std::uint32_t, TypicalNumSources> _sourcePool
Pool of currently inactive source ids.
SmallVector<IAudioPlayer*, TypicalNumSources> _players
Currently active audio players.

Function documentation

IAudioPlayer* nCine::AudioDeviceBase::GetPlayer(std::uint32_t index) override

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool nCine::AudioDeviceBase::SubmitStreamDecode(const std::shared_ptr<StreamDecodeRequest>& request) override

Submits a decode request to be executed asynchronously on the decoding thread.

Returns false when no decoding thread is available and the caller has to decode synchronously

The request state must be StreamDecodeRequest::State::Pending when submitted.

void nCine::AudioDeviceBase::DrainStreamDecode(const std::shared_ptr<StreamDecodeRequest>& request) override

Ensures the specified request is neither queued nor being executed when this method returns.

Required before touching the request's reader. A queued request is reset to StreamDecodeRequest::State::Idle, a running one is waited for.

void nCine::AudioDeviceBase::BeginBlockingOperation() override

Tells the device the caller is about to stop feeding it for a long time.

For devices mixing on the main thread, which would starve during e.g. a level load (PS2 audsrv repeats its last buffer). No-op for devices with their own mixing thread.

void nCine::AudioDeviceBase::OnBlockingOperationBegan() virtual protected

Called when the outermost blocking operation begins.

Blocking operations can nest, so backends override this instead of BeginBlockingOperation().

void nCine::AudioDeviceBase::ReportNoAvailableSources() protected

Reports that RegisterPlayer() had to refuse for lack of a free source.

Rate-limited, because the callers retry every frame.

void nCine::AudioDeviceBase::CheckForStalledSources() protected

Releases every source when the backend has stopped advancing them.

Recovers from a backend that stopped mixing silently, checked only while no source is free.

void nCine::AudioDeviceBase::ShutdownDecodeThread() protected

Stops the decoding thread and releases every request still queued.

Must be called from the backend destructor, the base destructor is too late.