SDL/src/audio/SDL_audio.c at main · aljen/SDL

Repository navigation

  Simple DirectMedia Layer
  Copyright (C) 1997-2026 Sam Lantinga <slouken@libsdl.org>
  This software is provided 'as-is', without any express or implied
  warranty.  In no event will the authors be held liable for any damages
  arising from the use of this software.
  Permission is granted to anyone to use this software for any purpose,
  including commercial applications, and to alter it and redistribute it
  freely, subject to the following restrictions:
  1. The origin of this software must not be misrepresented; you must not
     claim that you wrote the original software. If you use this software
     in a product, an acknowledgment in the product documentation would be
     appreciated but is not required.
  2. Altered source versions must be plainly marked as such, and must not be
     misrepresented as being the original software.
  3. This notice may not be removed or altered from any source distribution.
#include "SDL_internal.h"
#include "SDL_audio_c.h"
#include "SDL_sysaudio.h"
#include "../thread/SDL_systhread.h"
// Available audio drivers
static const AudioBootStrap *const bootstrap[] = {
#ifdef SDL_AUDIO_DRIVER_PRIVATE
    &PRIVATEAUDIO_bootstrap,
#ifdef SDL_AUDIO_DRIVER_PULSEAUDIO
#ifdef SDL_AUDIO_DRIVER_PIPEWIRE
    &PIPEWIRE_PREFERRED_bootstrap,
    &PULSEAUDIO_bootstrap,
#ifdef SDL_AUDIO_DRIVER_PIPEWIRE
    &PIPEWIRE_bootstrap,
#ifdef SDL_AUDIO_DRIVER_ALSA
    &ALSA_bootstrap,
#ifdef SDL_AUDIO_DRIVER_SNDIO
    &SNDIO_bootstrap,
#ifdef SDL_AUDIO_DRIVER_NETBSD
    &NETBSDAUDIO_bootstrap,
#ifdef SDL_AUDIO_DRIVER_WASAPI
    &WASAPI_bootstrap,
#ifdef SDL_AUDIO_DRIVER_DSOUND
    &DSOUND_bootstrap,
#ifdef SDL_AUDIO_DRIVER_HAIKU
    &HAIKUAUDIO_bootstrap,
#ifdef SDL_AUDIO_DRIVER_COREAUDIO
    &COREAUDIO_bootstrap,
#ifdef SDL_AUDIO_DRIVER_AAUDIO
    &AAUDIO_bootstrap,
#ifdef SDL_AUDIO_DRIVER_OPENSLES
    &OPENSLES_bootstrap,
#ifdef SDL_AUDIO_DRIVER_PS2
    &PS2AUDIO_bootstrap,
#ifdef SDL_AUDIO_DRIVER_PSP
    &PSPAUDIO_bootstrap,
#ifdef SDL_AUDIO_DRIVER_VITA
    &VITAAUD_bootstrap,
#ifdef SDL_AUDIO_DRIVER_N3DS
    &N3DSAUDIO_bootstrap,
#ifdef SDL_AUDIO_DRIVER_NGAGE
    &NGAGEAUDIO_bootstrap,
#ifdef SDL_AUDIO_DRIVER_EMSCRIPTEN
    &EMSCRIPTENAUDIO_bootstrap,
#ifdef SDL_AUDIO_DRIVER_JACK
    &JACK_bootstrap,
#ifdef SDL_AUDIO_DRIVER_OSS
    &DSP_bootstrap,
#ifdef SDL_AUDIO_DRIVER_QNX
    &QSAAUDIO_bootstrap,
#ifdef SDL_AUDIO_DRIVER_DISK
    &DISKAUDIO_bootstrap,
#ifdef SDL_AUDIO_DRIVER_DUMMY
    &DUMMYAUDIO_bootstrap,
static SDL_AudioDriver current_audio;
// Deduplicated list of audio bootstrap drivers.
static const AudioBootStrap *deduped_bootstrap[SDL_arraysize(bootstrap) - 1];
int SDL_GetNumAudioDrivers(void)
    static int num_drivers = -1;
    if (num_drivers >= 0) {
        return num_drivers;
    num_drivers = 0;
    // Build a list of unique audio drivers.
    for (int i = 0; bootstrap[i] != NULL; ++i) {
        bool duplicate = false;
        for (int j = 0; j < i; ++j) {
            if (SDL_strcmp(bootstrap[i]->name, bootstrap[j]->name) == 0) {
                duplicate = true;
                break;
        if (!duplicate) {
            deduped_bootstrap[num_drivers++] = bootstrap[i];
    return num_drivers;
const char *SDL_GetAudioDriver(int index)
    CHECK_PARAM(index < 0 || index >= SDL_GetNumAudioDrivers()) {
        SDL_InvalidParamError("index");
        return NULL;
    return deduped_bootstrap[index]->name;
const char *SDL_GetCurrentAudioDriver(void)
    return current_audio.name;
int SDL_GetDefaultSampleFramesFromFreq(const int freq)
    const char *hint = SDL_GetHint(SDL_HINT_AUDIO_DEVICE_SAMPLE_FRAMES);
    if (hint) {
        const int val = SDL_atoi(hint);
        if (val > 0) {
            return val;
    if (freq <= 22050) {
        return 512;
    } else if (freq <= 48000) {
        return 1024;
    } else if (freq <= 96000) {
        return 2048;
    } else {
        return 4096;
int *SDL_ChannelMapDup(const int *origchmap, int channels)
    int *chmap = NULL;
    if ((channels > 0) && origchmap) {
        const size_t chmaplen = sizeof (*origchmap) * channels;
        chmap = (int *)SDL_malloc(chmaplen);
        if (chmap) {
            SDL_memcpy(chmap, origchmap, chmaplen);
    return chmap;
void OnAudioStreamCreated(SDL_AudioStream *stream)
    SDL_assert(stream != NULL);
    // NOTE that you can create an audio stream without initializing the audio subsystem,
    //  but it will not be automatically destroyed during a later call to SDL_Quit!
    //  You must explicitly destroy it yourself!
    if (current_audio.subsystem_rwlock) {
        SDL_LockRWLockForWriting(current_audio.subsystem_rwlock);
        if (current_audio.existing_streams) {
            current_audio.existing_streams->prev = stream;
        stream->prev = NULL;
        stream->next = current_audio.existing_streams;
        current_audio.existing_streams = stream;
        SDL_UnlockRWLock(current_audio.subsystem_rwlock);
void OnAudioStreamDestroy(SDL_AudioStream *stream)
    SDL_assert(stream != NULL);
    // NOTE that you can create an audio stream without initializing the audio subsystem,
    //  but it will not be automatically destroyed during a later call to SDL_Quit!
    //  You must explicitly destroy it yourself!
    if (current_audio.subsystem_rwlock) {
        SDL_LockRWLockForWriting(current_audio.subsystem_rwlock);
        if (stream->prev) {
            stream->prev->next = stream->next;
        if (stream->next) {
            stream->next->prev = stream->prev;
        if (stream == current_audio.existing_streams) {
            current_audio.existing_streams = stream->next;
        SDL_UnlockRWLock(current_audio.subsystem_rwlock);
// device should be locked when calling this.
static bool AudioDeviceCanUseSimpleCopy(SDL_AudioDevice *device)
    SDL_assert(device != NULL);
    return (
        device->logical_devices &&  // there's a logical device
        !device->logical_devices->next &&  // there's only _ONE_ logical device
        !device->logical_devices->postmix && // there isn't a postmix callback
        device->logical_devices->bound_streams &&  // there's a bound stream
        !device->logical_devices->bound_streams->next_binding  // there's only _ONE_ bound stream.
// should hold device->lock before calling.
static void UpdateAudioStreamFormatsPhysical(SDL_AudioDevice *device)
    if (!device) {
        return;
    const bool recording = device->recording;
    SDL_AudioSpec spec;
    SDL_copyp(&spec, &device->spec);
    const SDL_AudioFormat devformat = spec.format;
    if (!recording) {
        const bool simple_copy = AudioDeviceCanUseSimpleCopy(device);
        device->simple_copy = simple_copy;
        if (!simple_copy) {
            spec.format = SDL_AUDIO_F32;  // mixing and postbuf operates in float32 format.
    for (SDL_LogicalAudioDevice *logdev = device->logical_devices; logdev; logdev = logdev->next) {
        if (recording) {
            const bool need_float32 = (logdev->postmix || logdev->gain != 1.0f);
            spec.format = need_float32 ? SDL_AUDIO_F32 : devformat;
        for (SDL_AudioStream *stream = logdev->bound_streams; stream; stream = stream->next_binding) {
            // set the proper end of the stream to the device's format.
            // SDL_SetAudioStreamFormat does a ton of validation just to memcpy an audiospec.
            SDL_AudioSpec *streamspec = recording ? &stream->src_spec : &stream->dst_spec;
            int **streamchmap = recording ? &stream->src_chmap : &stream->dst_chmap;
            SDL_LockMutex(stream->lock);
            SDL_copyp(streamspec, &spec);
            SetAudioStreamChannelMap(stream, streamspec, streamchmap, device->chmap, device->spec.channels, -1);  // this should be fast for normal cases, though!
            SDL_UnlockMutex(stream->lock);
bool SDL_AudioSpecsEqual(const SDL_AudioSpec *a, const SDL_AudioSpec *b, const int *channel_map_a, const int *channel_map_b)
    if ((a->format != b->format) || (a->channels != b->channels) || (a->freq != b->freq) || ((channel_map_a != NULL) != (channel_map_b != NULL))) {
        return false;
    } else if (channel_map_a && (SDL_memcmp(channel_map_a, channel_map_b, sizeof (*channel_map_a) * a->channels) != 0)) {
        return false;
    return true;
bool SDL_AudioChannelMapsEqual(int channels, const int *channel_map_a, const int *channel_map_b)
    if (channel_map_a == channel_map_b) {
        return true;
    } else if ((channel_map_a != NULL) != (channel_map_b != NULL)) {
        return false;
    } else if (channel_map_a && (SDL_memcmp(channel_map_a, channel_map_b, sizeof (*channel_map_a) * channels) != 0)) {
        return false;
    return true;
// Zombie device implementation...
// These get used when a device is disconnected or fails, so audiostreams don't overflow with data that isn't being
// consumed and apps relying on audio callbacks don't stop making progress.
static bool ZombieWaitDevice(SDL_AudioDevice *device)
    if (!SDL_GetAtomicInt(&device->shutdown)) {
        const int frames = device->buffer_size / SDL_AUDIO_FRAMESIZE(device->spec);
        SDL_Delay((frames * 1000) / device->spec.freq);
    return true;
static bool ZombiePlayDevice(SDL_AudioDevice *device, const Uint8 *buffer, int buflen)
    return true;  // no-op, just throw the audio away.
static Uint8 *ZombieGetDeviceBuf(SDL_AudioDevice *device, int *buffer_size)
    return device->work_buffer;
static int ZombieRecordDevice(SDL_AudioDevice *device, void *buffer, int buflen)
    // return a full buffer of silence every time.
    SDL_memset(buffer, device->silence_value, buflen);
    return buflen;
static void ZombieFlushRecording(SDL_AudioDevice *device)
    // no-op, this is all imaginary.
// device management and hotplug...
/* SDL_AudioDevice, in SDL3, represents a piece of physical hardware, whether it is in use or not, so these objects exist as long as
   the system-level device is available.
   Physical devices get destroyed for three reasons:
    - They were lost to the system (a USB cable is kicked out, etc).
    - They failed for some other unlikely reason at the API level (which is _also_ probably a USB cable being kicked out).
    - We are shutting down, so all allocated resources are being freed.
   They are _not_ destroyed because we are done using them (when we "close" a playing device).
static void ClosePhysicalAudioDevice(SDL_AudioDevice *device);
SDL_COMPILE_TIME_ASSERT(check_lowest_audio_default_value, SDL_AUDIO_DEVICE_DEFAULT_RECORDING < SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK);
static SDL_AtomicInt last_device_instance_id;  // increments on each device add to provide unique instance IDs
static SDL_AudioDeviceID AssignAudioDeviceInstanceId(bool recording, bool islogical)
    /* Assign an instance id! Start at 2, in case there are things from the SDL2 era that still think 1 is a special value.
       Also, make sure we don't assign SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK, etc. */
    // The bottom two bits of the instance id tells you if it's an playback device (1<<0), and if it's a physical device (1<<1).
    const SDL_AudioDeviceID flags = (recording ? 0 : (1<<0)) | (islogical ? 0 : (1<<1));
    const SDL_AudioDeviceID instance_id = (((SDL_AudioDeviceID) (SDL_AtomicIncRef(&last_device_instance_id) + 1)) << 2) | flags;
    SDL_assert( (instance_id >= 2) && (instance_id < SDL_AUDIO_DEVICE_DEFAULT_RECORDING) );
    return instance_id;
bool SDL_IsAudioDevicePhysical(SDL_AudioDeviceID devid)
    // bit #1 of devid is set for physical devices and unset for logical.
    return (devid & (1 << 1)) != 0;
static bool SDL_IsAudioDeviceLogical(SDL_AudioDeviceID devid)
    // bit #1 of devid is set for physical devices and unset for logical.
    return (devid & (1 << 1)) == 0;
bool SDL_IsAudioDevicePlayback(SDL_AudioDeviceID devid)
    // bit #0 of devid is set for playback devices and unset for recording.
    return (devid & (1 << 0)) != 0;
static bool SDL_IsAudioDeviceRecording(SDL_AudioDeviceID devid)
    // bit #0 of devid is set for playback devices and unset for recording.
    return (devid & (1 << 0)) == 0;
static void ObtainPhysicalAudioDeviceObj(SDL_AudioDevice *device) SDL_NO_THREAD_SAFETY_ANALYSIS  // !!! FIXMEL SDL_ACQUIRE
    if (device) {
        RefPhysicalAudioDevice(device);
        SDL_LockMutex(device->lock);
static void ReleaseAudioDevice(SDL_AudioDevice *device) SDL_NO_THREAD_SAFETY_ANALYSIS  // !!! FIXME: SDL_RELEASE
    if (device) {
        SDL_UnlockMutex(device->lock);
        UnrefPhysicalAudioDevice(device);
// If found, this locks _the physical device_ this logical device is associated with, before returning.
static SDL_LogicalAudioDevice *ObtainLogicalAudioDevice(SDL_AudioDeviceID devid, SDL_AudioDevice **_device) SDL_NO_THREAD_SAFETY_ANALYSIS    // !!! FIXME: SDL_ACQUIRE
    SDL_assert(_device != NULL);
    if (!SDL_GetCurrentAudioDriver()) {
        SDL_SetError("Audio subsystem is not initialized");
        *_device = NULL;
        return NULL;
    SDL_AudioDevice *device = NULL;
    SDL_LogicalAudioDevice *logdev = NULL;
    if (SDL_IsAudioDeviceLogical(devid)) {  // don't bother looking if it's not a logical device id value.
        SDL_LockRWLockForReading(current_audio.subsystem_rwlock);
        SDL_FindInHashTable(current_audio.device_hash_logical, (const void *) (uintptr_t) devid, (const void **) &logdev);
        if (logdev) {
            SDL_assert(logdev->instance_id == devid);
            device = logdev->physical_device;
            SDL_assert(device != NULL);
            RefPhysicalAudioDevice(device);  // reference it, in case the logical device migrates to a new default.
        SDL_UnlockRWLock(current_audio.subsystem_rwlock);
        if (logdev) {
            // we have to release the subsystem_rwlock before we take the device lock, to avoid deadlocks, so do a loop
            //  to make sure the correct physical device gets locked, in case we're in a race with the default changing.
            while (true) {
                SDL_LockMutex(device->lock);
                SDL_AudioDevice *recheck_device = (SDL_AudioDevice *) SDL_GetAtomicPointer((void **) &logdev->physical_device);
                if (device == recheck_device) {
                    break;
                // default changed from under us! Try again!
                RefPhysicalAudioDevice(recheck_device);
                SDL_UnlockMutex(device->lock);
                UnrefPhysicalAudioDevice(device);
                device = recheck_device;
    if (!logdev) {
        SDL_SetError("Invalid audio device instance ID");
    *_device = device;
    return logdev;
/* this finds the physical device associated with `devid` and locks it for use.
   Note that a logical device instance id will return its associated physical device! */
static SDL_AudioDevice *ObtainPhysicalAudioDevice(SDL_AudioDeviceID devid)  // !!! FIXME: SDL_ACQUIRE
    SDL_AudioDevice *device = NULL;
    if (SDL_IsAudioDeviceLogical(devid)) {
        ObtainLogicalAudioDevice(devid, &device);
    } else if (!SDL_GetCurrentAudioDriver()) {  // (the `islogical` path, above, checks this in ObtainLogicalAudioDevice.)
        SDL_SetError("Audio subsystem is not initialized");
    } else {
        SDL_LockRWLockForReading(current_audio.subsystem_rwlock);
        SDL_FindInHashTable(current_audio.device_hash_physical, (const void *) (uintptr_t) devid, (const void **) &device);
        SDL_assert(!device || (device->instance_id == devid));
        SDL_UnlockRWLock(current_audio.subsystem_rwlock);
        if (!device) {
            SDL_SetError("Invalid audio device instance ID");
        } else {
            ObtainPhysicalAudioDeviceObj(device);
    return device;
static SDL_AudioDevice *ObtainPhysicalAudioDeviceDefaultAllowed(SDL_AudioDeviceID devid)  // !!! FIXME: SDL_ACQUIRE
    const bool wants_default = ((devid == SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK) || (devid == SDL_AUDIO_DEVICE_DEFAULT_RECORDING));
    if (!wants_default) {
        return ObtainPhysicalAudioDevice(devid);
    const SDL_AudioDeviceID orig_devid = devid;
    while (true) {
        SDL_LockRWLockForReading(current_audio.subsystem_rwlock);
        if (orig_devid == SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK) {
            devid = current_audio.default_playback_device_id;
        } else if (orig_devid == SDL_AUDIO_DEVICE_DEFAULT_RECORDING) {
            devid = current_audio.default_recording_device_id;
        SDL_UnlockRWLock(current_audio.subsystem_rwlock);
        if (devid == 0) {
            SDL_SetError("No default audio device available");
            break;
        SDL_AudioDevice *device = ObtainPhysicalAudioDevice(devid);
        if (!device) {
            break;
        // make sure the default didn't change while we were waiting for the lock...
        bool got_it = false;
        SDL_LockRWLockForReading(current_audio.subsystem_rwlock);
        if ((orig_devid == SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK) && (devid == current_audio.default_playback_device_id)) {
            got_it = true;
        } else if ((orig_devid == SDL_AUDIO_DEVICE_DEFAULT_RECORDING) && (devid == current_audio.default_recording_device_id)) {
            got_it = true;
        SDL_UnlockRWLock(current_audio.subsystem_rwlock);
        if (got_it) {
            return device;
        ReleaseAudioDevice(device);  // let it go and try again.
    return NULL;
// this assumes you hold the _physical_ device lock for this logical device! This will not unlock the lock or close the physical device!
//  It also will not unref the physical device, since we might be shutting down; SDL_CloseAudioDevice handles the unref.
static void DestroyLogicalAudioDevice(SDL_LogicalAudioDevice *logdev)
    // Remove ourselves from the device_hash hashtable.
    if (current_audio.device_hash_logical) {  // will be NULL while shutting down.
        SDL_LockRWLockForWriting(current_audio.subsystem_rwlock);
        SDL_RemoveFromHashTable(current_audio.device_hash_logical, (const void *) (uintptr_t) logdev->instance_id);
        SDL_UnlockRWLock(current_audio.subsystem_rwlock);
    // remove ourselves from the physical device's list of logical devices.
    if (logdev->next) {
        logdev->next->prev = logdev->prev;
    if (logdev->prev) {
        logdev->prev->next = logdev->next;
    if (logdev->physical_device->logical_devices == logdev) {
        logdev->physical_device->logical_devices = logdev->next;
    // unbind any still-bound streams...
    SDL_AudioStream *next;
    for (SDL_AudioStream *stream = logdev->bound_streams; stream; stream = next) {
        SDL_LockMutex(stream->lock);
        next = stream->next_binding;
        stream->next_binding = NULL;
        stream->prev_binding = NULL;
        stream->bound_device = NULL;
        SDL_UnlockMutex(stream->lock);
    UpdateAudioStreamFormatsPhysical(logdev->physical_device);
    SDL_free(logdev);
// this must not be called while `device` is still in a device list, or while a device's audio thread is still running.
static void DestroyPhysicalAudioDevice(SDL_AudioDevice *device)
    if (!device) {
        return;
    // Destroy any logical devices that still exist...
    SDL_LockMutex(device->lock);  // don't use ObtainPhysicalAudioDeviceObj because we don't want to change refcounts while destroying.
    while (device->logical_devices) {
        DestroyLogicalAudioDevice(device->logical_devices);
    ClosePhysicalAudioDevice(device);
    current_audio.impl.FreeDeviceHandle(device);
    SDL_UnlockMutex(device->lock);  // don't use ReleaseAudioDevice because we don't want to change refcounts while destroying.
    SDL_DestroyMutex(device->lock);
    SDL_DestroyCondition(device->close_cond);
    SDL_free(device->work_buffer);
    SDL_free(device->chmap);
    SDL_free(device->name);
    SDL_free(device);
// Don't hold the device lock when calling this, as we may destroy the device!
void UnrefPhysicalAudioDevice(SDL_AudioDevice *device)
    if (SDL_AtomicDecRef(&device->refcount)) {
        // take it out of the device list.
        SDL_LockRWLockForWriting(current_audio.subsystem_rwlock);
        if (SDL_RemoveFromHashTable(current_audio.device_hash_physical, (const void *) (uintptr_t) device->instance_id)) {
            SDL_AddAtomicInt(device->recording ? &current_audio.recording_device_count : &current_audio.playback_device_count, -1);
        SDL_UnlockRWLock(current_audio.subsystem_rwlock);
        DestroyPhysicalAudioDevice(device);  // ...and nuke it.
void RefPhysicalAudioDevice(SDL_AudioDevice *device)
    SDL_AtomicIncRef(&device->refcount);
static SDL_AudioDevice *CreatePhysicalAudioDevice(const char *name, bool recording, const SDL_AudioSpec *spec, void *handle, SDL_AtomicInt *device_count)
    SDL_assert(name != NULL);
    SDL_LockRWLockForReading(current_audio.subsystem_rwlock);
    const int shutting_down = SDL_GetAtomicInt(&current_audio.shutting_down);
    SDL_UnlockRWLock(current_audio.subsystem_rwlock);
    if (shutting_down) {
        return NULL;  // we're shutting down, don't add any devices that are hotplugged at the last possible moment.
    SDL_AudioDevice *device = (SDL_AudioDevice *)SDL_calloc(1, sizeof(SDL_AudioDevice));
    if (!device) {
        return NULL;
    device->name = SDL_strdup(name);
    if (!device->name) {
        SDL_free(device);
        return NULL;
    device->lock = SDL_CreateMutex();
    if (!device->lock) {
        SDL_free(device->name);
        SDL_free(device);
        return NULL;
    device->close_cond = SDL_CreateCondition();
    if (!device->close_cond) {
        SDL_DestroyMutex(device->lock);
        SDL_free(device->name);
        SDL_free(device);
        return NULL;
    SDL_SetAtomicInt(&device->shutdown, 0);
    SDL_SetAtomicInt(&device->zombie, 0);
    device->recording = recording;
    SDL_copyp(&device->spec, spec);
    SDL_copyp(&device->default_spec, spec);
    device->sample_frames = SDL_GetDefaultSampleFramesFromFreq(device->spec.freq);
    device->silence_value = SDL_GetSilenceValueForFormat(device->spec.format);
    device->handle = handle;
    device->instance_id = AssignAudioDeviceInstanceId(recording, /*islogical=*/false);
    SDL_LockRWLockForWriting(current_audio.subsystem_rwlock);
    if (SDL_InsertIntoHashTable(current_audio.device_hash_physical, (const void *) (uintptr_t) device->instance_id, device, false)) {
        SDL_AddAtomicInt(device_count, 1);
    } else {
        SDL_DestroyCondition(device->close_cond);
        SDL_DestroyMutex(device->lock);
        SDL_free(device->name);
        SDL_free(device);
        device = NULL;
    SDL_UnlockRWLock(current_audio.subsystem_rwlock);
    RefPhysicalAudioDevice(device);  // unref'd on device disconnect.
    return device;
static SDL_AudioDevice *CreateAudioRecordingDevice(const char *name, const SDL_AudioSpec *spec, void *handle)
    SDL_assert(current_audio.impl.HasRecordingSupport);
    return CreatePhysicalAudioDevice(name, true, spec, handle, &current_audio.recording_device_count);
static SDL_AudioDevice *CreateAudioPlaybackDevice(const char *name, const SDL_AudioSpec *spec, void *handle)
    return CreatePhysicalAudioDevice(name, false, spec, handle, &current_audio.playback_device_count);
// The audio backends call this when a new device is plugged in.
SDL_AudioDevice *SDL_AddAudioDevice(bool recording, const char *name, const SDL_AudioSpec *inspec, void *handle)
    // device handles MUST be unique! If the target reuses the same handle for hardware with both recording and playback interfaces, wrap it in a pointer you SDL_malloc'd!
    SDL_assert(SDL_FindPhysicalAudioDeviceByHandle(handle) == NULL);
    const SDL_AudioFormat default_format = recording ? DEFAULT_AUDIO_RECORDING_FORMAT : DEFAULT_AUDIO_PLAYBACK_FORMAT;
    const int default_channels = recording ? DEFAULT_AUDIO_RECORDING_CHANNELS : DEFAULT_AUDIO_PLAYBACK_CHANNELS;
    const int default_freq = recording ? DEFAULT_AUDIO_RECORDING_FREQUENCY : DEFAULT_AUDIO_PLAYBACK_FREQUENCY;
    SDL_AudioSpec spec;
    SDL_zero(spec);
    if (!inspec) {
        spec.format = default_format;
        spec.channels = default_channels;
        spec.freq = default_freq;
    } else {
        spec.format = (inspec->format != 0) ? inspec->format : default_format;
        spec.channels = (inspec->channels != 0) ? inspec->channels : default_channels;
        spec.freq = (inspec->freq != 0) ? inspec->freq : default_freq;
    SDL_AudioDevice *device = recording ? CreateAudioRecordingDevice(name, &spec, handle) : CreateAudioPlaybackDevice(name, &spec, handle);
    // Add a device add event to the pending list, to be pushed when the event queue is pumped (away from any of our internal threads).
    if (device) {
        SDL_PendingAudioDeviceEvent *p = (SDL_PendingAudioDeviceEvent *) SDL_malloc(sizeof (SDL_PendingAudioDeviceEvent));
        if (p) {  // if allocation fails, you won't get an event, but we can't help that.
            p->type = SDL_EVENT_AUDIO_DEVICE_ADDED;
            p->devid = device->instance_id;
            p->next = NULL;
            SDL_LockRWLockForWriting(current_audio.subsystem_rwlock);
            SDL_assert(current_audio.pending_events_tail != NULL);
            SDL_assert(current_audio.pending_events_tail->next == NULL);
            current_audio.pending_events_tail->next = p;
            current_audio.pending_events_tail = p;
            SDL_UnlockRWLock(current_audio.subsystem_rwlock);
    return device;
// Called when a device is removed from the system, or it fails unexpectedly, from any thread, possibly even the audio device's thread.
static void SDLCALL SDL_AudioDeviceDisconnected_OnMainThread(void *userdata)
    SDL_AudioDevice *device = (SDL_AudioDevice *) userdata;
    SDL_assert(device != NULL);
    // Save off removal info in a list so we can send events for each, next
    //  time the event queue pumps, in case something tries to close a device
    //  from an event filter, as this would risk deadlocks and other disasters
    //  if done from the device thread.
    SDL_PendingAudioDeviceEvent pending;
    pending.next = NULL;
    SDL_PendingAudioDeviceEvent *pending_tail = &pending;
    ObtainPhysicalAudioDeviceObj(device);
    SDL_LockRWLockForReading(current_audio.subsystem_rwlock);
    const SDL_AudioDeviceID devid = device->instance_id;
    const bool is_default_device = ((devid == current_audio.default_playback_device_id) || (devid == current_audio.default_recording_device_id));
    SDL_UnlockRWLock(current_audio.subsystem_rwlock);
    const bool first_disconnect = SDL_CompareAndSwapAtomicInt(&device->zombie, 0, 1);
    if (first_disconnect) {   // if already disconnected this device, don't do it twice.
        // Swap in "Zombie" versions of the usual platform interfaces, so the device will keep
        // making progress until the app closes it. Otherwise, streams might continue to
        // accumulate waste data that never drains, apps that depend on audio callbacks to
        // progress will freeze, etc.
        device->WaitDevice = ZombieWaitDevice;
        device->GetDeviceBuf = ZombieGetDeviceBuf;
        device->PlayDevice = ZombiePlayDevice;
        device->WaitRecordingDevice = ZombieWaitDevice;
        device->RecordDevice = ZombieRecordDevice;
        device->FlushRecording = ZombieFlushRecording;
        // on default devices, dump any logical devices that explicitly opened this device. Things that opened the system default can stay.
        // on non-default devices, dump everything.
        // (by "dump" we mean send a REMOVED event; the zombie will keep consuming audio data for these logical devices until explicitly closed.)
        for (SDL_LogicalAudioDevice *logdev = device->logical_devices; logdev; logdev = logdev->next) {
            if (!is_default_device || !logdev->opened_as_default) {  // if opened as a default, leave it on the zombie device for later migration.
                SDL_PendingAudioDeviceEvent *p = (SDL_PendingAudioDeviceEvent *) SDL_malloc(sizeof (SDL_PendingAudioDeviceEvent));
                if (p) {  // if this failed, no event for you, but you have deeper problems anyhow.
                    p->type = SDL_EVENT_AUDIO_DEVICE_REMOVED;
                    p->devid = logdev->instance_id;
                    p->next = NULL;
                    pending_tail->next = p;
                    pending_tail = p;
        SDL_PendingAudioDeviceEvent *p = (SDL_PendingAudioDeviceEvent *) SDL_malloc(sizeof (SDL_PendingAudioDeviceEvent));
        if (p) {  // if this failed, no event for you, but you have deeper problems anyhow.
            p->type = SDL_EVENT_AUDIO_DEVICE_REMOVED;
            p->devid = device->instance_id;
            p->next = NULL;
            pending_tail->next = p;
            pending_tail = p;
    ReleaseAudioDevice(device);
    if (first_disconnect) {
        if (pending.next) {  // NULL if event is disabled or disaster struck.
            SDL_LockRWLockForWriting(current_audio.subsystem_rwlock);
            SDL_assert(current_audio.pending_events_tail != NULL);
            SDL_assert(current_audio.pending_events_tail->next == NULL);
            current_audio.pending_events_tail->next = pending.next;
            current_audio.pending_events_tail = pending_tail;
            SDL_UnlockRWLock(current_audio.subsystem_rwlock);
        UnrefPhysicalAudioDevice(device);
    // We always ref this in SDL_AudioDeviceDisconnected(), so if multiple attempts
    // to disconnect are queued, the pointer stays valid until the last one comes
    // through.
    UnrefPhysicalAudioDevice(device);
void SDL_AudioDeviceDisconnected(SDL_AudioDevice *device)
    // lots of risk of various audio backends deadlocking because they're calling
    // this while holding a backend-specific lock, which causes problems when we
    // want to obtain the device lock while its audio thread is also waiting for
    // that lock to be released. So just queue the work on the main thread.
    if (device) {
        RefPhysicalAudioDevice(device);
        SDL_RunOnMainThread(SDL_AudioDeviceDisconnected_OnMainThread, device, false);
// stubs for audio drivers that don't need a specific entry point...
static void SDL_AudioThreadDeinit_Default(SDL_AudioDevice *device) { /* no-op. */ }
static bool SDL_AudioWaitDevice_Default(SDL_AudioDevice *device) { return true; /* no-op. */ }
static bool SDL_AudioPlayDevice_Default(SDL_AudioDevice *device, const Uint8 *buffer, int buffer_size) { return true; /* no-op. */ }
static bool SDL_AudioWaitRecordingDevice_Default(SDL_AudioDevice *device) { return true; /* no-op. */ }
static void SDL_AudioFlushRecording_Default(SDL_AudioDevice *device) { /* no-op. */ }
static void SDL_AudioCloseDevice_Default(SDL_AudioDevice *device) { /* no-op. */ }
static void SDL_AudioDeinitializeStart_Default(void) { /* no-op. */ }
static void SDL_AudioDeinitialize_Default(void) { /* no-op. */ }
static void SDL_AudioFreeDeviceHandle_Default(SDL_AudioDevice *device) { /* no-op. */ }
static void SDL_AudioThreadInit_Default(SDL_AudioDevice *device)
    SDL_SetCurrentThreadPriority(device->recording ? SDL_THREAD_PRIORITY_HIGH : SDL_THREAD_PRIORITY_TIME_CRITICAL);
static void SDL_AudioDetectDevices_Default(SDL_AudioDevice **default_playback, SDL_AudioDevice **default_recording)
    // you have to write your own implementation if these assertions fail.
    SDL_assert(current_audio.impl.OnlyHasDefaultPlaybackDevice);
    SDL_assert(current_audio.impl.OnlyHasDefaultRecordingDevice || !current_audio.impl.HasRecordingSupport);
    *default_playback = SDL_AddAudioDevice(false, DEFAULT_PLAYBACK_DEVNAME, NULL, (void *)((size_t)0x1));
    if (current_audio.impl.HasRecordingSupport) {
        *default_recording = SDL_AddAudioDevice(true, DEFAULT_RECORDING_DEVNAME, NULL, (void *)((size_t)0x2));
static Uint8 *SDL_AudioGetDeviceBuf_Default(SDL_AudioDevice *device, int *buffer_size)
    *buffer_size = 0;
    return NULL;
static int SDL_AudioRecordDevice_Default(SDL_AudioDevice *device, void *buffer, int buflen)
    SDL_Unsupported();
    return -1;
static bool SDL_AudioOpenDevice_Default(SDL_AudioDevice *device)
    return SDL_Unsupported();
// Fill in stub functions for unused driver entry points. This lets us blindly call them without having to check for validity first.
static void CompleteAudioEntryPoints(void)
    #define FILL_STUB(x) if (!current_audio.impl.x) { current_audio.impl.x = SDL_Audio##x##_Default; }
    FILL_STUB(DetectDevices);
    FILL_STUB(OpenDevice);
    FILL_STUB(ThreadInit);
    FILL_STUB(ThreadDeinit);
    FILL_STUB(WaitDevice);
    FILL_STUB(PlayDevice);
    FILL_STUB(GetDeviceBuf);
    FILL_STUB(WaitRecordingDevice);
    FILL_STUB(RecordDevice);
    FILL_STUB(FlushRecording);
    FILL_STUB(CloseDevice);
    FILL_STUB(FreeDeviceHandle);
    FILL_STUB(DeinitializeStart);
    FILL_STUB(Deinitialize);
    #undef FILL_STUB
typedef struct FindLowestDeviceIDData
    const bool recording;
    SDL_AudioDeviceID highest;
    SDL_AudioDevice *result;
} FindLowestDeviceIDData;
static bool SDLCALL FindLowestDeviceID(void *userdata, const SDL_HashTable *table, const void *key, const void *value)
    FindLowestDeviceIDData *data = (FindLowestDeviceIDData *) userdata;
    const SDL_AudioDeviceID devid = (SDL_AudioDeviceID) (uintptr_t) key;
    SDL_assert(SDL_IsAudioDevicePhysical(devid));  // should only be iterating device_hash_physical.
    if ((SDL_IsAudioDeviceRecording(devid) == data->recording) && (devid < data->highest)) {
        data->highest = devid;
        data->result = (SDL_AudioDevice *) value;
        SDL_assert(data->result->instance_id == devid);
    return true;  // keep iterating.
static SDL_AudioDevice *GetFirstAddedAudioDevice(const bool recording)
    const SDL_AudioDeviceID highest = SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK;  // According to AssignAudioDeviceInstanceId, nothing can have a value this large.
    // (Device IDs increase as new devices are added, so the first device added has the lowest SDL_AudioDeviceID value.)
    FindLowestDeviceIDData data = { recording, highest, NULL };
    SDL_LockRWLockForReading(current_audio.subsystem_rwlock);
    SDL_IterateHashTable(current_audio.device_hash_physical, FindLowestDeviceID, &data);
    SDL_UnlockRWLock(current_audio.subsystem_rwlock);
    return data.result;
static Uint32 SDLCALL HashAudioDeviceID(void *userdata, const void *key)
    // shift right 2, to dump the first two bits, since these are flags
    //  (recording vs playback, logical vs physical) and the rest are unique incrementing integers.
    return ((Uint32) ((uintptr_t) key)) >> 2;
// !!! FIXME: the video subsystem does SDL_VideoInit, not SDL_InitVideo. Make this match.
bool SDL_InitAudio(const char *driver_name)
    if (SDL_GetCurrentAudioDriver()) {
        SDL_QuitAudio(); // shutdown driver if already running.
    // make sure device IDs start at 2 (because of SDL2 legacy interface), but don't reset the counter on each init, in case the app is holding an old device ID somewhere.
    SDL_CompareAndSwapAtomicInt(&last_device_instance_id, 0, 2);
    SDL_ChooseAudioConverters();
    SDL_Se
8
tupAudio
61F9
Resampler();
    SDL_RWLock *subsystem_rwlock = SDL_CreateRWLock();  // create this early, so if it fails we don't have to tear down the whole audio subsystem.
    if (!subsystem_rwlock) {
        return false;
    SDL_HashTable *device_hash_physical = SDL_CreateHashTable(0, false, HashAudioDeviceID, SDL_KeyMatchID, NULL, NULL);
    if (!device_hash_physical) {
        SDL_DestroyRWLock(subsystem_rwlock);
        return false;
    SDL_HashTable *device_hash_logical = SDL_CreateHashTable(0, false, HashAudioDeviceID, SDL_KeyMatchID, NULL, NULL);
    if (!device_hash_logical) {
        SDL_DestroyHashTable(device_hash_physical);
        SDL_DestroyRWLock(subsystem_rwlock);
        return false;
    // Select the proper audio driver
    if (!driver_name) {
        driver_name = SDL_GetHint(SDL_HINT_AUDIO_DRIVER);
    bool initialized = false;
    bool tried_to_init = false;
    if (driver_name && *driver_name != 0) {
        char *driver_name_copy = SDL_strdup(driver_name);
        const char *driver_attempt = driver_name_copy;
        if (!driver_name_copy) {
            SDL_DestroyRWLock(subsystem_rwlock);
            SDL_DestroyHashTable(device_hash_physical);
            SDL_DestroyHashTable(device_hash_logical);
            return false;
        while (driver_attempt && *driver_attempt != 0 && !initialized) {
            char *driver_attempt_end = SDL_strchr(driver_attempt, ',');
            if (driver_attempt_end) {
                *driver_attempt_end = '\0';
            // SDL 1.2 uses the name "dsound", so we'll support both.
            if (SDL_strcmp(driver_attempt, "dsound") == 0) {
                driver_attempt = "directsound";
            } else if (SDL_strcmp(driver_attempt, "pulse") == 0) {  // likewise, "pulse" was renamed to "pulseaudio"
                driver_attempt = "pulseaudio";
View remainder of file in raw view
FilesExpand file tree

SDL_audio.c

Latest commit

History

SDL_audio.c

File metadata and controls
