promeki::SDLAudioOutput Class Reference

Manages an SDL3 audio output device for playback. More...

#include <sdlaudiooutput.h>

Inheritance diagram for promeki::SDLAudioOutput:

Collaboration diagram for promeki::SDLAudioOutput:

Public Member Functions
	SDLAudioOutput (ObjectBase *parent=nullptr)
	Constructs an SDLAudioOutput.
bool	configure (const AudioDesc &desc)
	Configures the audio output format.
bool	open ()
	Opens the SDL audio device and starts playback.
void	close ()
	Closes the audio device and frees resources.
bool	isOpen () const
	Returns true if the device is open and playing.
bool	pushAudio (const PcmAudioPayload &payload)
	Pushes uncompressed audio samples to the output stream.
virtual int	queuedBytes () const
	Returns the number of bytes currently queued.
const AudioDesc &	desc () const
	Returns the configured audio descriptor.
virtual int64_t	totalBytesPushed () const
	Returns total float32 bytes pushed since open.
virtual ClockDomain	clockDomain () const
	Returns the ClockDomain registered for the open SDL device.
virtual Error	setPaused (bool paused)
	Pauses or resumes the underlying SDL audio device.
virtual bool	isPaused () const
	Returns the current pause state.
Clock *	createClock ()
	Returns a Clock whose time is driven by this output's consumed-byte counter.

Detailed Description

Manages an SDL3 audio output device for playback.

SDLAudioOutput opens an SDL audio device and stream, accepting promeki Audio objects for playback. Audio data is converted to the platform's native float format if necessary and pushed to an SDL audio stream, which handles sample rate conversion and buffering automatically.

pushAudio() is thread-safe — it can be called from any thread (e.g. a MediaIO Strand worker) while the SDL audio device plays on its own thread.

Clock integration

Each open device registers its own ClockDomain (derived from the SDL device name) and can hand out a Clock via createClock. The returned clock is a subclass of Clock bound to this output — pausing it pauses the SDL device, and it propagates Error::ObjectGone via the underlying ObjectBasePtr when the output is destroyed.

Example

SDLAudioOutput output;
output.configure(audioDesc);
output.open();
 
Clock::Ptr clock = Clock::Ptr::takeOwnership(output.createClock());
 
// From any thread:
output.pushAudio(audioPtr);

Thread Safety

Mixed. pushAudio() is fully thread-safe and may be called from any thread (e.g. a MediaIO Strand worker) — it pushes into the SDL audio stream which is internally synchronised. Lifecycle calls (configure / open / close, signal/slot connections, destruction) are thread-affine via ObjectBase and must run on the thread that owns the bound SdlSubsystem.

Member Function Documentation

clockDomain()

virtual ClockDomain promeki::SDLAudioOutput::clockDomain ( ) const

inlinevirtual

Returns the ClockDomain registered for the open SDL device.

Invalid (default-constructed) until open succeeds. Multiple Clock instances constructed from the same device share this domain. Virtual so tests can supply a controllable stand-in without opening a real SDL audio device.

configure()

bool promeki::SDLAudioOutput::configure

(

const AudioDesc &

desc

)

Configures the audio output format.

Must be called before open(). The audio stream will accept data in this format and convert to the device's native format as needed.

Parameters

desc	The audio format descriptor.

Returns

true on success.

createClock()

Clock * promeki::SDLAudioOutput::createClock

(

)

Returns a Clock whose time is driven by this output's consumed-byte counter.

The clock's domain is this output's clockDomain, its pause mode is ClockPauseMode::PausesRawStops, and pausing it pauses the SDL device. Returned pointer is heap allocated — the caller adopts it into a Clock::Ptr.

Returns

A newly-allocated Clock, or nullptr if the output has not been opened yet.

isPaused()

virtual bool promeki::SDLAudioOutput::isPaused ( ) const

virtual

Returns the current pause state.

Virtual so tests can supply a controllable stand-in.

open()

bool promeki::SDLAudioOutput::open

(

)

Opens the SDL audio device and starts playback.

Also registers the per-device ClockDomain derived from the underlying SDL device identity. The domain is accessible via clockDomain after a successful open.

Returns

true on success.

pushAudio()

bool promeki::SDLAudioOutput::pushAudio

(

const PcmAudioPayload &

payload

)

Pushes uncompressed audio samples to the output stream.

Thread-safe. The audio data is converted to float32 if necessary before being pushed to the SDL stream.

Parameters

payload

The payload's PCM bytes to play.

Returns

true on success.

queuedBytes()

virtual int promeki::SDLAudioOutput::queuedBytes ( ) const

virtual

Returns the number of bytes currently queued.

Useful for monitoring buffer health and A/V sync.

Virtual so tests can supply a controllable stand-in without opening a real SDL audio device.

Returns

Queued byte count, or 0 if not open.

setPaused()

virtual Error promeki::SDLAudioOutput::setPaused ( bool  paused )

virtual

Pauses or resumes the underlying SDL audio device.

The SDL-level pause freezes consumption of queued audio — queuedBytes and totalBytesPushed stop advancing relative to each other until the device is resumed. Virtual so tests can override without holding a real SDL stream.

Parameters

paused

The target state.

Returns

Error::Ok on success, or a descriptive error when the SDL call fails.

totalBytesPushed()

virtual int64_t promeki::SDLAudioOutput::totalBytesPushed ( ) const

inlinevirtual

Returns total float32 bytes pushed since open.

Combined with queuedBytes(), this lets callers derive how many bytes the device has consumed: consumed = totalBytesPushed() - queuedBytes().

Virtual so tests can supply a controllable stand-in without opening a real SDL audio device.

Returns

Cumulative byte count.

---

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

• include/promeki/sdl/sdlaudiooutput.h