nCine::IAudioDevice class
#include <nCine/Audio/IAudioDevice.h>

Interface for an audio device backend.

Manages the listener, the pool of audio sources and all active players, and owns the backend objects (buffers and sources) the shared player classes drive through it. Exactly one implementation is compiled into a binary, each living in nCine/Audio/Backends/: ALAudioDevice on top of OpenAL, AsndAudioDevice on top of the Wii/GameCube DSP mixer, AicaAudioDevice on top of the Dreamcast sound processor, and NullAudioDevice as a silent fallback.

AudioBuffer, IAudioPlayer and AudioStream contain no backend calls of their own - they refer to buffers and sources by the opaque ids handed out here.

Where NCINE_HAS_NATIVE_AUDIO is defined, the device plays files in formats of its own and the engine never decodes a sample: the sample upload, the streaming queue and the decoding thread are replaced by the native playback functions.

Derived classes

class AudioDeviceBase: Backend-independent part of an audio device.

Public types

struct NativeAudioInfo: Properties of audio the device plays in a format of its own.
enum class BufferFormat { Mono8, Stereo8, Mono16, Stereo16 }: Sample format of an audio buffer.
enum class BufferUsage { Static, Streaming }: What a buffer is going to be used for.
enum class PlayerType { Buffer, Stream }: Player backing type.

Constructors, destructors, conversion operators

~IAudioDevice() pure virtual

Public functions

auto isValid() const -> bool pure virtual: Returns true if the device was initialized successfully.
auto name() const -> const char* pure virtual: Returns the name of the underlying device.
auto gain() const -> float pure virtual: Returns the listener gain (master volume).
void setGain(float gain) pure virtual: Sets the listener gain (master volume).
auto maxNumPlayers() const -> std::uint32_t pure virtual: Returns the maximum number of players that can be active at once.
auto numPlayers() const -> std::uint32_t pure virtual: Returns the number of currently active players.
auto player(std::uint32_t index) const -> const IAudioPlayer* pure virtual: Returns the active player at the specified index.
auto player(std::uint32_t index) -> IAudioPlayer* pure virtual
void stopPlayers() pure virtual: Stops every player currently playing.
void pausePlayers() pure virtual: Pauses every player currently playing.
void stopPlayers(PlayerType playerType) pure virtual: Stops every player of the specified type.
void pausePlayers(PlayerType playerType) pure virtual: Pauses every player of the specified type.
void freezePlayers() pure virtual: Pauses every player currently playing while keeping it registered.
void unfreezePlayers() pure virtual: Resumes every player previously paused by freezePlayers().
auto registerPlayer(IAudioPlayer* player) -> std::uint32_t pure virtual: Registers a player so it receives state and buffer queue updates, returning its source id.
void unregisterPlayer(IAudioPlayer* player) pure virtual: Unregisters a previously registered player.
void updatePlayers() pure virtual: Updates the state of every registered player, including the buffer queue of stream players.
auto submitStreamDecode(const std::shared_ptr<StreamDecodeRequest>& request) -> bool pure virtual: Submits a decode request to be executed asynchronously on the decoding thread.
void drainStreamDecode(const std::shared_ptr<StreamDecodeRequest>& request) pure virtual: Ensures the specified request is neither queued nor being executed when this method returns.
auto getListenerPosition() const -> const Vector3f& pure virtual: Returns the 3D position of the listener.
void updateListener(const Vector3f& position, const Vector3f& velocity) pure virtual: Updates the position and velocity of the listener.
auto nativeFrequency() -> std::int32_t pure virtual: Returns the native sample rate of the device.
void setMixingFrequency(std::int32_t frequency) virtual: Changes the rate the device mixes at, if the backend has one to change.
void beginBlockingOperation() virtual: Tells the device the caller is about to stop feeding it for a long time.
void endBlockingOperation() virtual: Ends what beginBlockingOperation() started, and resumes playback.
void suspendDevice() pure virtual: Suspends the audio device.
void resumeDevice() pure virtual: Resumes the audio device.

Constants

static std::uint32_t UnavailableSource constexpr: Value returned by registerPlayer() when no source is available.
static float LengthToPhysical constexpr: Scale factor converting game length units to physical (OpenAL) units.
static float VelocityToPhysical constexpr: Scale factor converting game velocity units to physical (OpenAL) units.
static float ReferenceDistance constexpr: Distance at which attenuation begins, in physical units.
static float MaxDistance constexpr: Distance beyond which attenuation no longer increases, in physical units.

Buffers

auto createBuffer(BufferUsage usage) -> std::uint32_t pure virtual: Creates an empty backend buffer, returning its id or 0 on failure.
void deleteBuffer(std::uint32_t bufferId) pure virtual: Destroys a buffer previously returned by createBuffer().
auto uploadBuffer(std::uint32_t bufferId, BufferFormat format, const void* data, std::int32_t size, std::int32_t frequency) -> bool pure virtual: Replaces the contents of a buffer with the specified samples.

Native playback

auto loadNativeBuffer(std::uint32_t bufferId, Death::Containers::StringView path, NativeAudioInfo& info) -> bool pure virtual: Makes a buffer play a file the device reads by itself instead of holding its decoded samples.
auto openNativeStream(Death::Containers::StringView path, NativeAudioInfo& info) -> std::uint32_t pure virtual: Opens a file the device streams by itself, returning its id or 0.
void closeNativeStream(std::uint32_t streamId) pure virtual: Closes a stream returned by openNativeStream(), stopping it if it is playing.
void setSourceNativeStream(std::uint32_t sourceId, std::uint32_t streamId) pure virtual: Binds a native stream to a source.

Sources

void setSourceBuffer(std::uint32_t sourceId, std::uint32_t bufferId) pure virtual: Attaches a buffer to a source for non-streamed playback, 0 detaches the current one.
void setSourceGain(std::uint32_t sourceId, float gain) pure virtual: Sets the gain of a source.
void setSourcePitch(std::uint32_t sourceId, float pitch) pure virtual: Sets the pitch of a source, as a multiplier of its natural playback rate.
void setSourceLooping(std::uint32_t sourceId, bool looping) pure virtual: Sets whether a source repeats its attached buffer.
void setSourceRelative(std::uint32_t sourceId, bool relative) pure virtual: Sets whether the position of a source is relative to the listener.
void setSourcePosition(std::uint32_t sourceId, const Vector3f& position) pure virtual: Sets the position of a source, in physical units.
void setSourceLowPass(std::uint32_t sourceId, float value) pure virtual: Sets the low-pass amount of a source, 1.0f disables the filter.
auto sourceSampleOffset(std::uint32_t sourceId) -> std::int32_t pure virtual: Returns the playback position of a source in samples.
void setSourceSampleOffset(std::uint32_t sourceId, std::int32_t offset) pure virtual: Sets the playback position of a source in samples.
void playSource(std::uint32_t sourceId) pure virtual: Starts or resumes a source.
void pauseSource(std::uint32_t sourceId) pure virtual: Pauses a source at its current position.
void stopSource(std::uint32_t sourceId) pure virtual: Stops a source.
auto isSourcePlaying(std::uint32_t sourceId) -> bool pure virtual: Returns true if a source is still producing sound.

Streaming

void queueBuffer(std::uint32_t sourceId, std::uint32_t bufferId) pure virtual: Appends a buffer to the streaming queue of a source.
auto numProcessedBuffers(std::uint32_t sourceId) -> std::int32_t pure virtual: Returns the number of queued buffers a source has finished playing.
void unqueueBuffers(std::uint32_t sourceId, std::int32_t count, std::uint32_t* bufferIds) pure virtual: Removes the specified number of played buffers from the front of the queue.

Enum documentation

enum class nCine::IAudioDevice::BufferFormat

Sample format of an audio buffer.

Enumerators
Mono8	8-bit unsigned, single channel
Stereo8	8-bit unsigned, two channels
Mono16	16-bit signed, single channel
Stereo16	16-bit signed, two channels

enum class nCine::IAudioDevice::BufferUsage

What a buffer is going to be used for.

Most backends ignore this, but where sample memory is not one uniform pool the two kinds have to live in different places: the Dreamcast plays a fully loaded sound out of the AICA's own sound RAM, while a streamed one stays in main memory and is transferred into the sound processor's ring buffer a chunk at a time.

Enumerators
Static	Loaded once and played as a whole, by AudioBuffer
Streaming	Refilled continuously and played through a queue, by AudioStream

enum class nCine::IAudioDevice::PlayerType

Player backing type.

Enumerators
Buffer	Player backed by a fully loaded AudioBuffer
Stream	Player decoding an AudioStream on the fly

Function documentation

IAudioPlayer* nCine::IAudioDevice::player(std::uint32_t index) pure virtual

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

bool nCine::IAudioDevice::submitStreamDecode(const std::shared_ptr<StreamDecodeRequest>& request) pure virtual

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::IAudioDevice::drainStreamDecode(const std::shared_ptr<StreamDecodeRequest>& request) pure virtual

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

Required before the caller touches the request's reader (rewinding, changing looping or replacing it). A request removed from the queue before execution is reset to StreamDecodeRequest::State::Idle, a request already being executed is waited for.

void nCine::IAudioDevice::setMixingFrequency(std::int32_t frequency) virtual

Changes the rate the device mixes at, if the backend has one to change.

Only the software-mixing backends whose cost is linear in this rate honour it (the PSP's, where the mix is upsampled to the hardware's fixed rate, and the Amiga's, where AHI resamples the output); nativeFrequency() then reports the new rate, so the module music decoders that size themselves by it follow on the next stream they open. A rate the backend cannot run at, or 0, is ignored. Everywhere else this is a no-op.

void nCine::IAudioDevice::beginBlockingOperation() virtual

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

A device that mixes on the main thread is fed once per frame, so an operation that blocks that thread for longer than it has queued ahead - a level load, above all - starves it. What starving sounds like is the hardware's business and not always silence: the PlayStation 2's audsrv repeats its last buffer for as long as nothing replaces it (measured), which turns a two second load into two seconds of the same fragment of music over and over. A device that has something better to do with the gap says so here and puts itself back together in endBlockingOperation().

A no-op for every device that mixes on a thread of its own or hands whole sounds to hardware, which is all of them but one - they carry on playing through the block and should.

bool nCine::IAudioDevice::loadNativeBuffer(std::uint32_t bufferId, Death::Containers::StringView path, NativeAudioInfo& info) pure virtual

Makes a buffer play a file the device reads by itself instead of holding its decoded samples.

The Nintendo 64 streams its sound effects straight out of the cartridge instead of holding them in its 8 MB of RAM: the device takes the file over here, and the buffer then plays like any other. Returns false for a file the device cannot open or play, which then stays silent.

std::uint32_t nCine::IAudioDevice::openNativeStream(Death::Containers::StringView path, NativeAudioInfo& info) pure virtual

Opens a file the device streams by itself, returning its id or 0.

The counterpart of loadNativeBuffer() for long content played through AudioStream - music in a format the hardware plays without the engine decoding it. 0 means the device cannot open or play the file.

void nCine::IAudioDevice::setSourceNativeStream(std::uint32_t sourceId, std::uint32_t streamId) pure virtual

Binds a native stream to a source.

The source's own controls then drive the stream: playSource(), pauseSource(), stopSource() (which also rewinds it), setSourceGain(), setSourceLooping() and isSourcePlaying(). The binding lasts until the source is handed out again.

void nCine::IAudioDevice::unqueueBuffers(std::uint32_t sourceId, std::int32_t count, std::uint32_t* bufferIds) pure virtual

Removes the specified number of played buffers from the front of the queue.

Parameters
sourceId
count
bufferIds	Receives the ids of the removed buffers, must hold `count` entries

nCine::IAudioDevice class #include <nCine/Audio/IAudioDevice.h>