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.

Derived classes

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

Public types

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 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.

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::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>