SdlAudioSink Class Reference

An output stream for audio, using SDL. More...

#include <audio_sink.hpp>

Inheritance diagram for SdlAudioSink:

Collaboration diagram for SdlAudioSink:

Public Member Functions
	SdlAudioSink (const AudioSource &source, int device_id)
	Constructs an SdlAudioSink. More...
	~SdlAudioSink () override
	Destructs an SdlAudioSink.
void	Start () override
	Starts the audio stream. More...
void	Stop () override
	Stops the audio stream. More...
Audio::State	State () override
	Gets this AudioSink's current state (playing/stopped/at end). More...
std::uint64_t	Position () override
	Gets the current played position in the song, in samples. More...
void	SetPosition (std::uint64_t samples) override
	Sets the current played position, given a position in samples. More...
void	SourceOut () override
	Tells this AudioSink that the source has run out. More...
void	Transfer (TransferIterator &start, const TransferIterator &end) override
	Transfers a range of sample bytes into the AudioSink. More...
void	Callback (std::uint8_t *out, int nbytes)
	The callback proper. More...
Public Member Functions inherited from AudioSink
virtual	~AudioSink ()=default
	Virtual, empty destructor for AudioSink.

Static Public Member Functions
static std::vector< std::pair< int, std::string > >	GetDevicesInfo ()
	Gets the number and name of each output device entry in the AudioSystem. More...
static bool	IsOutputDevice (int id)
	Can a sound device output sound? More...
static void	InitLibrary ()
	Initialises the AudioSink's libraries, if not initialised already.
static void	CleanupLibrary ()
	Cleans up the AudioSink's libraries, if not cleaned up already.

Private Attributes
SDL_AudioDeviceID	device
	The SDL device to which we are outputting sound.
size_t	bytes_per_sample
	Number of bytes in one sample.
RingBuffer	ring_buf
	The ring buffer used to transfer samples to the playing callback.
std::uint64_t	position_sample_count
	The current position, in samples.
bool	source_out
	Whether the source has run out of things to feed the sink.
Audio::State	state
	The decoder's current state.

Static Private Attributes
static const size_t	RINGBUF_POWER = 16
	n, where 2^n is the capacity of the Audio ring buffer. More...
static const std::array< SDL_AudioFormat, SAMPLE_FORMAT_COUNT >	FORMATS
	Mapping from SampleFormats to their equivalent SDL_AudioFormats. More...

Additional Inherited Members
Public Types inherited from AudioSink
using	TransferIterator = AudioSource::DecodeVector::iterator
	Type of iterators used in the Transfer() method.

Detailed Description

An output stream for audio, using SDL.

An SdlAudioSink consists of an SDL output device and a buffer that stores decoded samples from the Audio object. While active, the SdlAudioSink periodically transfers samples from its buffer to SDL2 in a separate thread.

Definition at line 108 of file audio_sink.hpp.

Constructor & Destructor Documentation

SdlAudioSink()

SdlAudioSink::SdlAudioSink	(	const AudioSource &	source,
		int	device_id
	)

Constructs an SdlAudioSink.

Parameters

source	The source from which this sink will receive audio.
device_id	The device ID to which this sink will output.

Definition at line 61 of file audio_sink.cpp.

References AudioSource::ChannelCount(), FORMATS, AudioSource::OutputSampleFormat(), and AudioSource::SampleRate().

    : bytes_per_sample(source.BytesPerSample()),
      ring_buf(RINGBUF_POWER, source.BytesPerSample()),
      position_sample_count(0),
      source_out(false),
      state(Audio::State::STOPPED)
{
    const char *name = SDL_GetAudioDeviceName(device_id, 0);
    if (name == nullptr) {
        throw ConfigError(std::string("invalid device id: ") +
                          std::to_string(device_id));
    }

    SDL_AudioSpec want;
    SDL_zero(want);
    want.freq = source.SampleRate();
    want.format = FORMATS[static_cast<int>(source.OutputSampleFormat())];
    want.channels = source.ChannelCount();
    want.callback = &SDLCallback;
    want.userdata = (void *)this;

    SDL_AudioSpec have;
    SDL_zero(have);

    this->device = SDL_OpenAudioDevice(name, 0, &want, &have, 0);
    if (this->device == 0) {
        throw ConfigError(std::string("couldn't open device: ") +
                          SDL_GetError());
    }
}

Member Function Documentation

Callback()

void SdlAudioSink::Callback	(	std::uint8_t *	out,
		int	nbytes
	)

The callback proper.

This is executed in a separate thread by SDL once a stream is playing with the callback registered to it.

Parameters

out	The output buffer to which our samples should be written.
nbytes	The number of bytes SDL wants to read from out.

Definition at line 195 of file audio_sink.cpp.

References Audio::AT_END, bytes_per_sample, Audio::PLAYING, position_sample_count, RingBuffer::Read(), RingBuffer::ReadCapacity(), ring_buf, source_out, and state.

{
    assert(out != nullptr);

    assert(0 <= nbytes);
    unsigned long lnbytes = static_cast<unsigned long>(nbytes);

    // Make sure anything not filled up with sound later is set to silence.
    // This is slightly inefficient (two writes to sound-filled regions
    // instead of one), but more elegant in failure cases.
    memset(out, 0, lnbytes);

    // If we're not supposed to be playing, don't play anything.
    if (this->state != Audio::State::PLAYING) return;

    // Let's find out how many samples are available in total to give SDL.
    //
    // Note: Since we run concurrently with the decoder, which is also
    // trying to modify the read capacity of the ringbuf (by adding
    // things), this technically causes a race condition when we try to
    // read `avail_samples` number of samples later.  Not to fear: the
    // actual read capacity can only be greater than or equal to
    // `avail_samples`, as this is the only place where we can *decrease*
    // it.
    auto avail_samples = this->ring_buf.ReadCapacity();

    // Have we run out of things to feed?
    if (avail_samples == 0) {
        // Is this a temporary condition, or have we genuinely played
        // out all we can?  If the latter, we're now out too.
        if (this->source_out) this->state = Audio::State::AT_END;

        // Don't even bother reading from the ring buffer.
        return;
    }

    // How many samples do we want to pull out of the ring buffer?
    size_t req_samples = lnbytes / this->bytes_per_sample;

    // How many can we pull out?  Send this amount to SDL.
    auto samples = std::min(req_samples, avail_samples);
    auto read_samples =
            this->ring_buf.Read(reinterpret_cast<char *>(out), samples);
    this->position_sample_count += read_samples;
}

GetDevicesInfo()

std::vector< std::pair< int, std::string > > SdlAudioSink::GetDevicesInfo ( )

static

Gets the number and name of each output device entry in the AudioSystem.

Returns

List of output devices, as strings.

Definition at line 241 of file audio_sink.cpp.

Referenced by ExitWithUsage().

{
    std::vector<std::pair<int, std::string>> list;

    // The 0 in SDL_GetNumAudioDevices tells SDL we want playback devices.
    int is = SDL_GetNumAudioDevices(0);
    for (int i = 0; i < is; i++) {
        const char *n = SDL_GetAudioDeviceName(i, 0);
        if (n != nullptr) list.emplace_back(i, std::string(n));
    }

    return list;
}

IsOutputDevice()

bool SdlAudioSink::IsOutputDevice ( int  id )

static

Can a sound device output sound?

Parameters

id	Device ID.

Returns

If the device can handle outputting sound.

Definition at line 255 of file audio_sink.cpp.

Referenced by GetDeviceID().

{
    int ids = SDL_GetNumAudioDevices(0);

    // See comment in GetDevicesInfo for why this is sufficient.
    return (0 <= id && id < ids);
}

Position()

std::uint64_t SdlAudioSink::Position ( )

overridevirtual

Gets the current played position in the song, in samples.

As this may be executing whilst the playing callback is running, do not expect it to be highly accurate.

Returns

The current position, as a count of elapsed samples.

Implements AudioSink.

Definition at line 143 of file audio_sink.cpp.

References position_sample_count.

{
    return this->position_sample_count;
}

SetPosition()

void SdlAudioSink::SetPosition ( std::uint64_t  samples )

overridevirtual

Sets the current played position, given a position in samples.

This flushes out the AudioSink ready to receive sample data from the new position.

Parameters

samples

The new position, as a count of elapsed samples.

See also

Position

Implements AudioSink.

Definition at line 148 of file audio_sink.cpp.

References Audio::AT_END, RingBuffer::Flush(), position_sample_count, ring_buf, source_out, state, Stop(), and Audio::STOPPED.

{
    this->position_sample_count = samples;

    // We might have been at the end of the file previously.
    // If so, we might not be now, so clear the out flags.
    this->source_out = false;
    if (this->state == Audio::State::AT_END) {
        this->state = Audio::State::STOPPED;
        this->Stop();
    }

    // The ringbuf will have been full of samples from the old
    // position, so we need to get rid of them.
    this->ring_buf.Flush();
}

SourceOut()

void SdlAudioSink::SourceOut ( )

overridevirtual

Tells this AudioSink that the source has run out.

When this occurs, the next time the ringbuf goes empty, the sink has also run out and should stop.

Implements AudioSink.

Definition at line 135 of file audio_sink.cpp.

References Audio::AT_END, source_out, and state.

{
    // The sink should only be out if the source is.
    assert(this->source_out || this->state != Audio::State::AT_END);

    this->source_out = true;
}

Start()

void SdlAudioSink::Start ( )

overridevirtual

Starts the audio stream.

See also

Stop

IsHalted

Implements AudioSink.

Definition at line 114 of file audio_sink.cpp.

References device, Audio::PLAYING, state, and Audio::STOPPED.

{
    if (this->state != Audio::State::STOPPED) return;

    SDL_PauseAudioDevice(this->device, 0);
    this->state = Audio::State::PLAYING;
}

State()

Audio::State SdlAudioSink::State ( )

overridevirtual

Gets this AudioSink's current state (playing/stopped/at end).

Returns

The Audio::State representing this AudioSink's state.

See also

Audio::State

Reimplemented from AudioSink.

Definition at line 130 of file audio_sink.cpp.

References state.

{
    return this->state;
}

Stop()

void SdlAudioSink::Stop ( )

overridevirtual

Stops the audio stream.

See also

Start

IsHalted

Implements AudioSink.

Definition at line 122 of file audio_sink.cpp.

References device, state, and Audio::STOPPED.

Referenced by SetPosition().

{
    if (this->state == Audio::State::STOPPED) return;

    SDL_PauseAudioDevice(this->device, 1);
    this->state = Audio::State::STOPPED;
}

Transfer()

void SdlAudioSink::Transfer ( TransferIterator &  start, const TransferIterator &  end  )

overridevirtual

Transfers a range of sample bytes into the AudioSink.

The range may be empty, but must be valid.

• Precondition: start <= end, start and end point to a valid contiguous block of sample bytes.
• Postcondition: start <= end, old(start) <= start, *start and end point to a valid contiguous block of sample bytes.

Parameters

start	An iterator denoting the start of the range. This iterator will be advanced by the number of bytes accepted.
end	An iterator denoting the end of the range.

Implements AudioSink.

Definition at line 165 of file audio_sink.cpp.

References bytes_per_sample, ring_buf, RingBuffer::Write(), and RingBuffer::WriteCapacity().

{
    assert(start <= end);

    // No point transferring 0 bytes.
    if (start == end) return;

    unsigned long bytes = std::distance(start, end);
    // There should be a whole number of samples being transferred.
    assert(bytes % bytes_per_sample == 0);
    assert(0 < bytes);

    size_t samples = bytes / this->bytes_per_sample;

    // Only transfer as many samples as the ring buffer can take.
    // Don't bother trying to write 0 samples!
    auto count = std::min(samples, this->ring_buf.WriteCapacity());
    if (count == 0) return;

    auto start_ptr = reinterpret_cast<char *>(&*start);
    unsigned long written_count = this->ring_buf.Write(start_ptr, count);
    // Since we never write more than the ring buffer can take, the written
    // count should equal the requested written count.
    assert(written_count == count);

    start += (written_count * this->bytes_per_sample);
    assert(start <= end);
}

Member Data Documentation

FORMATS

const std::array< SDL_AudioFormat, SAMPLE_FORMAT_COUNT > SdlAudioSink::FORMATS

staticprivate

Initial value:

{{
    AUDIO_U8,  
    AUDIO_S8,  
    AUDIO_S16, 
    AUDIO_S32, 
    AUDIO_F32  
}}

Mapping from SampleFormats to their equivalent SDL_AudioFormats.

Definition at line 168 of file audio_sink.hpp.

Referenced by SdlAudioSink(), and AudioSink::State().

RINGBUF_POWER

const size_t SdlAudioSink::RINGBUF_POWER = 16

staticprivate

n, where 2^n is the capacity of the Audio ring buffer.

See also

RINGBUF_SIZE

Definition at line 165 of file audio_sink.hpp.

Referenced by AudioSink::State().

---

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

• src/audio/audio_sink.hpp
• src/audio/audio_sink.cpp