SDL_audio.c File Reference

#include "../SDL_internal.h"
#include "SDL.h"
#include "SDL_audio.h"
#include "SDL_audio_c.h"
#include "SDL_sysaudio.h"
#include "../thread/SDL_systhread.h"

Include dependency graph for SDL_audio.c:

Go to the source code of this file.

Macros
#define	_THIS   SDL_AudioDevice *_this
#define	FILL_STUB(x)
#define	CHECK_FMT_STRING(x)   if (SDL_strcmp(string, #x) == 0) return AUDIO_##x
#define	NUM_FORMATS   10

Functions
static SDL_AudioDevice *	get_audio_device (SDL_AudioDeviceID id)
static void	SDL_AudioDetectDevices_Default (void)
static void	SDL_AudioThreadInit_Default (_THIS)
static void	SDL_AudioThreadDeinit_Default (_THIS)
static void	SDL_AudioBeginLoopIteration_Default (_THIS)
static void	SDL_AudioWaitDevice_Default (_THIS)
static void	SDL_AudioPlayDevice_Default (_THIS)
static int	SDL_AudioGetPendingBytes_Default (_THIS)
static Uint8 *	SDL_AudioGetDeviceBuf_Default (_THIS)
static int	SDL_AudioCaptureFromDevice_Default (_THIS, void *buffer, int buflen)
static void	SDL_AudioFlushCapture_Default (_THIS)
static void	SDL_AudioPrepareToClose_Default (_THIS)
static void	SDL_AudioCloseDevice_Default (_THIS)
static void	SDL_AudioDeinitialize_Default (void)
static void	SDL_AudioFreeDeviceHandle_Default (void *handle)
static int	SDL_AudioOpenDevice_Default (_THIS, void *handle, const char *devname, int iscapture)
static SDL_INLINE SDL_bool	is_in_audio_device_thread (SDL_AudioDevice *device)
static void	SDL_AudioLockDevice_Default (SDL_AudioDevice *device)
static void	SDL_AudioUnlockDevice_Default (SDL_AudioDevice *device)
static void	SDL_AudioLockOrUnlockDeviceWithNoMixerLock (SDL_AudioDevice *device)
static void	finish_audio_entry_points_init (void)
static int	add_audio_device (const char *name, void *handle, SDL_AudioDeviceItem **devices, int *devCount)
static SDL_INLINE int	add_capture_device (const char *name, void *handle)
static SDL_INLINE int	add_output_device (const char *name, void *handle)
static void	free_device_list (SDL_AudioDeviceItem **devices, int *devCount)
void	SDL_AddAudioDevice (const int iscapture, const char *name, void *handle)
void	SDL_OpenedAudioDeviceDisconnected (SDL_AudioDevice *device)
static void	mark_device_removed (void *handle, SDL_AudioDeviceItem *devices, SDL_bool *removedFlag)
void	SDL_RemoveAudioDevice (const int iscapture, void *handle)
static void	SDL_BufferQueueDrainCallback (void *userdata, Uint8 *stream, int len)
static void	SDL_BufferQueueFillCallback (void *userdata, Uint8 *stream, int len)
int	SDL_QueueAudio (SDL_AudioDeviceID devid, const void *data, Uint32 len)
Uint32	SDL_DequeueAudio (SDL_AudioDeviceID devid, void *data, Uint32 len)
Uint32	SDL_GetQueuedAudioSize (SDL_AudioDeviceID devid)
void	SDL_ClearQueuedAudio (SDL_AudioDeviceID devid)
static int	SDL_RunAudio (void *devicep)
static int	SDL_CaptureAudio (void *devicep)
static SDL_AudioFormat	SDL_ParseAudioFormat (const char *string)
int	SDL_GetNumAudioDrivers (void)
const char *	SDL_GetAudioDriver (int index)
int	SDL_AudioInit (const char *driver_name)
const char *	SDL_GetCurrentAudioDriver ()
static void	clean_out_device_list (SDL_AudioDeviceItem **devices, int *devCount, SDL_bool *removedFlag)
int	SDL_GetNumAudioDevices (int iscapture)
const char *	SDL_GetAudioDeviceName (int index, int iscapture)
static void	close_audio_device (SDL_AudioDevice *device)
static int	prepare_audiospec (const SDL_AudioSpec *orig, SDL_AudioSpec *prepared)
static SDL_AudioDeviceID	open_audio_device (const char *devname, int iscapture, const SDL_AudioSpec *desired, SDL_AudioSpec *obtained, int allowed_changes, int min_id)
int	SDL_OpenAudio (SDL_AudioSpec *desired, SDL_AudioSpec *obtained)
SDL_AudioDeviceID	SDL_OpenAudioDevice (const char *device, int iscapture, const SDL_AudioSpec *desired, SDL_AudioSpec *obtained, int allowed_changes)
SDL_AudioStatus	SDL_GetAudioDeviceStatus (SDL_AudioDeviceID devid)
SDL_AudioStatus	SDL_GetAudioStatus (void)
void	SDL_PauseAudioDevice (SDL_AudioDeviceID devid, int pause_on)
void	SDL_PauseAudio (int pause_on)
void	SDL_LockAudioDevice (SDL_AudioDeviceID devid)
void	SDL_LockAudio (void)
void	SDL_UnlockAudioDevice (SDL_AudioDeviceID devid)
void	SDL_UnlockAudio (void)
void	SDL_CloseAudioDevice (SDL_AudioDeviceID devid)
void	SDL_CloseAudio (void)
void	SDL_AudioQuit (void)
SDL_AudioFormat	SDL_FirstAudioFormat (SDL_AudioFormat format)
SDL_AudioFormat	SDL_NextAudioFormat (void)
void	SDL_CalculateAudioSpec (SDL_AudioSpec *spec)
void	SDL_MixAudio (Uint8 *dst, const Uint8 *src, Uint32 len, int volume)

Variables
static SDL_AudioDriver	current_audio
static SDL_AudioDevice *	open_devices [16]
static const AudioBootStrap *const	bootstrap []
static int	format_idx
static int	format_idx_sub
static SDL_AudioFormat	format_list [NUM_FORMATS][NUM_FORMATS]

Macro Definition Documentation

#define _THIS   SDL_AudioDevice *_this

Definition at line 31 of file SDL_audio.c.

#define CHECK_FMT_STRING

(

x

)

if (SDL_strcmp(string, #x) == 0) return AUDIO_##x

Referenced by SDL_ParseAudioFormat().

#define FILL_STUB

(

x

)

Value:

if (current_audio.impl.x == NULL) { \
            current_audio.impl.x = SDL_Audio##x##_Default; \
        }

Referenced by finish_audio_entry_points_init().

#define NUM_FORMATS   10

Definition at line 1612 of file SDL_audio.c.

Referenced by SDL_FirstAudioFormat(), and SDL_NextAudioFormat().

Function Documentation

static int add_audio_device ( const char *  name, void *  handle, SDL_AudioDeviceItem **  devices, int *  devCount  )

static

Definition at line 378 of file SDL_audio.c.

References SDL_AudioDriver::detectionLock, SDL_AudioDeviceItem::dupenum, SDL_AudioDeviceItem::handle, i, SDL_AudioDeviceItem::name, SDL_AudioDeviceItem::next, NULL, SDL_AudioDeviceItem::original_name, retval, SDL_assert, SDL_free, SDL_LockMutex, SDL_malloc, SDL_OutOfMemory, SDL_snprintf, SDL_strcmp, SDL_strdup, SDL_strlen, and SDL_UnlockMutex.

Referenced by add_capture_device(), and add_output_device().

{
    int retval = -1;
    SDL_AudioDeviceItem *item;
    const SDL_AudioDeviceItem *i;
    int dupenum = 0;

    SDL_assert(handle != NULL);  /* we reserve NULL, audio backends can't use it. */
    SDL_assert(name != NULL);

    item = (SDL_AudioDeviceItem *) SDL_malloc(sizeof (SDL_AudioDeviceItem));
    if (!item) {
        return SDL_OutOfMemory();
    }

    item->original_name = SDL_strdup(name);
    if (!item->original_name) {
        SDL_free(item);
        return SDL_OutOfMemory();
    }

    item->dupenum = 0;
    item->name = item->original_name;
    item->handle = handle;

    SDL_LockMutex(current_audio.detectionLock);

    for (i = *devices; i != NULL; i = i->next) {
        if (SDL_strcmp(name, i->original_name) == 0) {
            dupenum = i->dupenum + 1;
            break;  /* stop at the highest-numbered dupe. */
        }
    }

    if (dupenum) {
        const size_t len = SDL_strlen(name) + 16;
        char *replacement = (char *) SDL_malloc(len);
        if (!replacement) {
            SDL_UnlockMutex(current_audio.detectionLock);
            SDL_free(item->original_name);
            SDL_free(item);
            SDL_OutOfMemory();
            return -1;
        }

        SDL_snprintf(replacement, len, "%s (%d)", name, dupenum + 1);
        item->dupenum = dupenum;
        item->name = replacement;
    }

    item->next = *devices;
    *devices = item;
    retval = (*devCount)++;   /* !!! FIXME: this should be an atomic increment */

    SDL_UnlockMutex(current_audio.detectionLock);

    return retval;
}

static SDL_INLINE int add_capture_device ( const char *  name, void *  handle  )

static

Definition at line 438 of file SDL_audio.c.

References add_audio_device(), SDL_AudioDriverImpl::HasCaptureSupport, SDL_AudioDriver::impl, SDL_AudioDriver::inputDeviceCount, SDL_AudioDriver::inputDevices, and SDL_assert.

Referenced by SDL_AddAudioDevice().

{
    SDL_assert(current_audio.impl.HasCaptureSupport);
    return add_audio_device(name, handle, &current_audio.inputDevices, &current_audio.inputDeviceCount);
}

static SDL_INLINE int add_output_device ( const char *  name, void *  handle  )

static

Definition at line 445 of file SDL_audio.c.

References add_audio_device(), SDL_AudioDriver::outputDeviceCount, and SDL_AudioDriver::outputDevices.

Referenced by SDL_AddAudioDevice().

{
    return add_audio_device(name, handle, &current_audio.outputDevices, &current_audio.outputDeviceCount);
}

static void clean_out_device_list ( SDL_AudioDeviceItem **  devices, int *  devCount, SDL_bool *  removedFlag  )

static

Definition at line 1004 of file SDL_audio.c.

References SDL_AudioDeviceItem::handle, SDL_AudioDeviceItem::name, SDL_AudioDeviceItem::next, NULL, SDL_AudioDeviceItem::original_name, SDL_FALSE, and SDL_free.

Referenced by SDL_GetNumAudioDevices().

{
    SDL_AudioDeviceItem *item = *devices;
    SDL_AudioDeviceItem *prev = NULL;
    int total = 0;

    while (item) {
        SDL_AudioDeviceItem *next = item->next;
        if (item->handle != NULL) {
            total++;
            prev = item;
        } else {
            if (prev) {
                prev->next = next;
            } else {
                *devices = next;
            }
            /* these two pointers are the same if not a duplicate devname */
            if (item->name != item->original_name) {
                SDL_free(item->name);
            }
            SDL_free(item->original_name);
            SDL_free(item);
        }
        item = next;
    }

    *devCount = total;
    *removedFlag = SDL_FALSE;
}

static void close_audio_device ( SDL_AudioDevice *  device )

static

Definition at line 1102 of file SDL_audio.c.

References SDL_AudioDevice::buffer_queue, SDL_AudioDriverImpl::CloseDevice, SDL_AudioDevice::enabled, SDL_AudioDevice::hidden, SDL_AudioDevice::id, SDL_AudioDriver::impl, SDL_AudioDriverImpl::LockDevice, SDL_AudioDevice::mixer_lock, NULL, SDL_AudioDevice::paused, SDL_assert, SDL_AtomicSet, SDL_DestroyMutex, SDL_free, SDL_FreeAudioStream, SDL_FreeDataQueue(), SDL_WaitThread, SDL_AudioDevice::shutdown, SDL_AudioDevice::stream, SDL_AudioDevice::thread, SDL_AudioDriverImpl::UnlockDevice, and SDL_AudioDevice::work_buffer.

Referenced by open_audio_device(), SDL_AudioQuit(), and SDL_CloseAudioDevice().

{
    if (!device) {
        return;
    }

    /* make sure the device is paused before we do anything else, so the
       audio callback definitely won't fire again. */
    current_audio.impl.LockDevice(device);
    SDL_AtomicSet(&device->paused, 1);
    SDL_AtomicSet(&device->shutdown, 1);
    SDL_AtomicSet(&device->enabled, 0);
    current_audio.impl.UnlockDevice(device);

    if (device->thread != NULL) {
        SDL_WaitThread(device->thread, NULL);
    }
    if (device->mixer_lock != NULL) {
        SDL_DestroyMutex(device->mixer_lock);
    }

    SDL_free(device->work_buffer);
    SDL_FreeAudioStream(device->stream);

    if (device->id > 0) {
        SDL_AudioDevice *opendev = open_devices[device->id - 1];
        SDL_assert((opendev == device) || (opendev == NULL));
        if (opendev == device) {
            open_devices[device->id - 1] = NULL;
        }
    }

    if (device->hidden != NULL) {
        current_audio.impl.CloseDevice(device);
    }

    SDL_FreeDataQueue(device->buffer_queue);

    SDL_free(device);
}

static void finish_audio_entry_points_init ( void  )

static

Definition at line 334 of file SDL_audio.c.

References FILL_STUB, SDL_AudioDriver::impl, SDL_AudioDriverImpl::LockDevice, NULL, SDL_AudioLockOrUnlockDeviceWithNoMixerLock(), SDL_AudioDriverImpl::SkipMixerLock, and SDL_AudioDriverImpl::UnlockDevice.

Referenced by SDL_AudioInit().

{
    /*
     * Fill in stub functions for unused driver entry points. This lets us
     *  blindly call them without having to check for validity first.
     */

    if (current_audio.impl.SkipMixerLock) {
        if (current_audio.impl.LockDevice == NULL) {
            current_audio.impl.LockDevice = SDL_AudioLockOrUnlockDeviceWithNoMixerLock;
        }
        if (current_audio.impl.UnlockDevice == NULL) {
            current_audio.impl.UnlockDevice = SDL_AudioLockOrUnlockDeviceWithNoMixerLock;
        }
    }

#define FILL_STUB(x) \
        if (current_audio.impl.x == NULL) { \
            current_audio.impl.x = SDL_Audio##x##_Default; \
        }
    FILL_STUB(DetectDevices);
    FILL_STUB(OpenDevice);
    FILL_STUB(ThreadInit);
    FILL_STUB(ThreadDeinit);
    FILL_STUB(BeginLoopIteration);
    FILL_STUB(WaitDevice);
    FILL_STUB(PlayDevice);
    FILL_STUB(GetPendingBytes);
    FILL_STUB(GetDeviceBuf);
    FILL_STUB(CaptureFromDevice);
    FILL_STUB(FlushCapture);
    FILL_STUB(PrepareToClose);
    FILL_STUB(CloseDevice);
    FILL_STUB(LockDevice);
    FILL_STUB(UnlockDevice);
    FILL_STUB(FreeDeviceHandle);
    FILL_STUB(Deinitialize);
#undef FILL_STUB
}

static void free_device_list ( SDL_AudioDeviceItem **  devices, int *  devCount  )

static

Definition at line 451 of file SDL_audio.c.

References SDL_AudioDriverImpl::FreeDeviceHandle, SDL_AudioDeviceItem::handle, SDL_AudioDriver::impl, SDL_AudioDeviceItem::name, SDL_AudioDeviceItem::next, NULL, SDL_AudioDeviceItem::original_name, and SDL_free.

Referenced by SDL_AudioQuit().

{
    SDL_AudioDeviceItem *item, *next;
    for (item = *devices; item != NULL; item = next) {
        next = item->next;
        if (item->handle != NULL) {
            current_audio.impl.FreeDeviceHandle(item->handle);
        }
        /* these two pointers are the same if not a duplicate devname */
        if (item->name != item->original_name) {
            SDL_free(item->name);
        }
        SDL_free(item->original_name);
        SDL_free(item);
    }
    *devices = NULL;
    *devCount = 0;
}

static SDL_AudioDevice* get_audio_device ( SDL_AudioDeviceID  id )

static

Definition at line 197 of file SDL_audio.c.

References NULL, SDL_arraysize, and SDL_SetError.

Referenced by SDL_ClearQueuedAudio(), SDL_CloseAudioDevice(), SDL_DequeueAudio(), SDL_GetAudioDeviceStatus(), SDL_GetQueuedAudioSize(), SDL_LockAudioDevice(), SDL_MixAudio(), SDL_OpenedAudioDeviceDisconnected(), SDL_PauseAudioDevice(), SDL_QueueAudio(), and SDL_UnlockAudioDevice().

{
    id--;
    if ((id >= SDL_arraysize(open_devices)) || (open_devices[id] == NULL)) {
        SDL_SetError("Invalid audio device ID");
        return NULL;
    }

    return open_devices[id];
}

static SDL_INLINE SDL_bool is_in_audio_device_thread ( SDL_AudioDevice *  device )

static

Definition at line 299 of file SDL_audio.c.

References SDL_FALSE, SDL_ThreadID, SDL_TRUE, SDL_AudioDevice::thread, and SDL_AudioDevice::threadid.

Referenced by SDL_AudioLockDevice_Default(), and SDL_AudioUnlockDevice_Default().

{
    /* The device thread locks the same mutex, but not through the public API.
       This check is in case the application, in the audio callback,
       tries to lock the thread that we've already locked from the
       device thread...just in case we only have non-recursive mutexes. */
    if (device->thread && (SDL_ThreadID() == device->threadid)) {
        return SDL_TRUE;
    }

    return SDL_FALSE;
}

static void mark_device_removed ( void *  handle, SDL_AudioDeviceItem *  devices, SDL_bool *  removedFlag  )

static

Definition at line 520 of file SDL_audio.c.

References SDL_AudioDeviceItem::handle, SDL_AudioDeviceItem::next, NULL, SDL_assert, and SDL_TRUE.

Referenced by SDL_RemoveAudioDevice().

{
    SDL_AudioDeviceItem *item;
    SDL_assert(handle != NULL);
    for (item = devices; item != NULL; item = item->next) {
        if (item->handle == handle) {
            item->handle = NULL;
            *removedFlag = SDL_TRUE;
            return;
        }
    }
}

static SDL_AudioDeviceID open_audio_device ( const char *  devname, int  iscapture, const SDL_AudioSpec *  desired, SDL_AudioSpec *  obtained, int  allowed_changes, int  min_id  )

static

Definition at line 1208 of file SDL_audio.c.

References SDL_AudioDriverImpl::AllowsArbitraryDeviceNames, SDL_AudioDevice::buffer_queue, SDL_AudioSpec::callback, SDL_AudioDevice::callbackspec, SDL_AudioSpec::channels, close_audio_device(), DEFAULT_INPUT_DEVNAME, DEFAULT_OUTPUT_DEVNAME, SDL_AudioDriver::detectionLock, device, SDL_AudioDevice::enabled, SDL_AudioSpec::format, SDL_AudioSpec::freq, SDL_AudioDeviceItem::handle, SDL_AudioDevice::handle, SDL_AudioDriverImpl::HasCaptureSupport, SDL_AudioDevice::hidden, i, SDL_AudioDevice::id, SDL_AudioDriver::impl, SDL_AudioDriver::inputDevices, SDL_AudioDevice::iscapture, SDL_AudioDevice::mixer_lock, SDL_AudioDeviceItem::name, SDL_AudioDeviceItem::next, NULL, SDL_AudioDriverImpl::OnlyHasDefaultCaptureDevice, SDL_AudioDriverImpl::OnlyHasDefaultOutputDevice, SDL_AudioDriverImpl::OpenDevice, SDL_AudioDriver::outputDevices, SDL_AudioDevice::paused, prepare_audiospec(), SDL_AudioDriverImpl::ProvidesOwnCallbackThread, SDL_AudioSpec::samples, SDL_arraysize, SDL_assert, SDL_AtomicSet, SDL_AUDIO_ALLOW_CHANNELS_CHANGE, SDL_AUDIO_ALLOW_FORMAT_CHANGE, SDL_AUDIO_ALLOW_FREQUENCY_CHANGE, SDL_AUDIO_ALLOW_SAMPLES_CHANGE, SDL_AUDIOBUFFERQUEUE_PACKETLEN, SDL_BufferQueueDrainCallback(), SDL_BufferQueueFillCallback(), SDL_CalculateAudioSpec(), SDL_calloc, SDL_CaptureAudio(), SDL_CreateMutex, SDL_CreateThreadInternal(), SDL_FALSE, SDL_getenv, SDL_INIT_AUDIO, SDL_LockMutex, SDL_malloc, SDL_NewAudioStream, SDL_NewDataQueue(), SDL_OutOfMemory, SDL_RunAudio(), SDL_SetError, SDL_snprintf, SDL_strcmp, SDL_TRUE, SDL_UnlockMutex, SDL_WasInit, SDL_AudioDevice::shutdown, SDL_AudioSpec::size, SDL_AudioDriverImpl::SkipMixerLock, SDL_AudioDevice::spec, SDL_AudioDevice::stream, SDL_AudioDevice::thread, SDL_AudioSpec::userdata, SDL_AudioDevice::work_buffer, and SDL_AudioDevice::work_buffer_len.

Referenced by SDL_OpenAudio(), and SDL_OpenAudioDevice().

{
    const SDL_bool is_internal_thread = (desired->callback == NULL);
    SDL_AudioDeviceID id = 0;
    SDL_AudioSpec _obtained;
    SDL_AudioDevice *device;
    SDL_bool build_stream;
    void *handle = NULL;
    int i = 0;

    if (!SDL_WasInit(SDL_INIT_AUDIO)) {
        SDL_SetError("Audio subsystem is not initialized");
        return 0;
    }

    if ((iscapture) && (!current_audio.impl.HasCaptureSupport)) {
        SDL_SetError("No capture support");
        return 0;
    }

    /* !!! FIXME: there is a race condition here if two devices open from two threads at once. */
    /* Find an available device ID... */
    for (id = min_id - 1; id < SDL_arraysize(open_devices); id++) {
        if (open_devices[id] == NULL) {
            break;
        }
    }

    if (id == SDL_arraysize(open_devices)) {
        SDL_SetError("Too many open audio devices");
        return 0;
    }

    if (!obtained) {
        obtained = &_obtained;
    }
    if (!prepare_audiospec(desired, obtained)) {
        return 0;
    }

    /* If app doesn't care about a specific device, let the user override. */
    if (devname == NULL) {
        devname = SDL_getenv("SDL_AUDIO_DEVICE_NAME");
    }

    /*
     * Catch device names at the high level for the simple case...
     * This lets us have a basic "device enumeration" for systems that
     *  don't have multiple devices, but makes sure the device name is
     *  always NULL when it hits the low level.
     *
     * Also make sure that the simple case prevents multiple simultaneous
     *  opens of the default system device.
     */

    if ((iscapture) && (current_audio.impl.OnlyHasDefaultCaptureDevice)) {
        if ((devname) && (SDL_strcmp(devname, DEFAULT_INPUT_DEVNAME) != 0)) {
            SDL_SetError("No such device");
            return 0;
        }
        devname = NULL;

        for (i = 0; i < SDL_arraysize(open_devices); i++) {
            if ((open_devices[i]) && (open_devices[i]->iscapture)) {
                SDL_SetError("Audio device already open");
                return 0;
            }
        }
    } else if ((!iscapture) && (current_audio.impl.OnlyHasDefaultOutputDevice)) {
        if ((devname) && (SDL_strcmp(devname, DEFAULT_OUTPUT_DEVNAME) != 0)) {
            SDL_SetError("No such device");
            return 0;
        }
        devname = NULL;

        for (i = 0; i < SDL_arraysize(open_devices); i++) {
            if ((open_devices[i]) && (!open_devices[i]->iscapture)) {
                SDL_SetError("Audio device already open");
                return 0;
            }
        }
    } else if (devname != NULL) {
        /* if the app specifies an exact string, we can pass the backend
           an actual device handle thingey, which saves them the effort of
           figuring out what device this was (such as, reenumerating
           everything again to find the matching human-readable name).
           It might still need to open a device based on the string for,
           say, a network audio server, but this optimizes some cases. */
        SDL_AudioDeviceItem *item;
        SDL_LockMutex(current_audio.detectionLock);
        for (item = iscapture ? current_audio.inputDevices : current_audio.outputDevices; item; item = item->next) {
            if ((item->handle != NULL) && (SDL_strcmp(item->name, devname) == 0)) {
                handle = item->handle;
                break;
            }
        }
        SDL_UnlockMutex(current_audio.detectionLock);
    }

    if (!current_audio.impl.AllowsArbitraryDeviceNames) {
        /* has to be in our device list, or the default device. */
        if ((handle == NULL) && (devname != NULL)) {
            SDL_SetError("No such device.");
            return 0;
        }
    }

    device = (SDL_AudioDevice *) SDL_calloc(1, sizeof (SDL_AudioDevice));
    if (device == NULL) {
        SDL_OutOfMemory();
        return 0;
    }
    device->id = id + 1;
    device->spec = *obtained;
    device->iscapture = iscapture ? SDL_TRUE : SDL_FALSE;
    device->handle = handle;

    SDL_AtomicSet(&device->shutdown, 0);  /* just in case. */
    SDL_AtomicSet(&device->paused, 1);
    SDL_AtomicSet(&device->enabled, 1);

    /* Create a mutex for locking the sound buffers */
    if (!current_audio.impl.SkipMixerLock) {
        device->mixer_lock = SDL_CreateMutex();
        if (device->mixer_lock == NULL) {
            close_audio_device(device);
            SDL_SetError("Couldn't create mixer lock");
            return 0;
        }
    }

    if (current_audio.impl.OpenDevice(device, handle, devname, iscapture) < 0) {
        close_audio_device(device);
        return 0;
    }

    /* if your target really doesn't need it, set it to 0x1 or something. */
    /* otherwise, close_audio_device() won't call impl.CloseDevice(). */
    SDL_assert(device->hidden != NULL);

    /* See if we need to do any conversion */
    build_stream = SDL_FALSE;
    if (obtained->freq != device->spec.freq) {
        if (allowed_changes & SDL_AUDIO_ALLOW_FREQUENCY_CHANGE) {
            obtained->freq = device->spec.freq;
        } else {
            build_stream = SDL_TRUE;
        }
    }
    if (obtained->format != device->spec.format) {
        if (allowed_changes & SDL_AUDIO_ALLOW_FORMAT_CHANGE) {
            obtained->format = device->spec.format;
        } else {
            build_stream = SDL_TRUE;
        }
    }
    if (obtained->channels != device->spec.channels) {
        if (allowed_changes & SDL_AUDIO_ALLOW_CHANNELS_CHANGE) {
            obtained->channels = device->spec.channels;
        } else {
            build_stream = SDL_TRUE;
        }
    }
    if (device->spec.samples != obtained->samples) {
        if (allowed_changes & SDL_AUDIO_ALLOW_SAMPLES_CHANGE) {
            obtained->samples = device->spec.samples;
        } else {
            build_stream = SDL_TRUE;
        }
    }

    SDL_CalculateAudioSpec(obtained);  /* recalc after possible changes. */

    device->callbackspec = *obtained;

    if (build_stream) {
        if (iscapture) {
            device->stream = SDL_NewAudioStream(device->spec.format,
                                  device->spec.channels, device->spec.freq,
                                  obtained->format, obtained->channels, obtained->freq);
        } else {
            device->stream = SDL_NewAudioStream(obtained->format, obtained->channels,
                                  obtained->freq, device->spec.format,
                                  device->spec.channels, device->spec.freq);
        }

        if (!device->stream) {
            close_audio_device(device);
            return 0;
        }
    }

    if (device->spec.callback == NULL) {  /* use buffer queueing? */
        /* pool a few packets to start. Enough for two callbacks. */
        device->buffer_queue = SDL_NewDataQueue(SDL_AUDIOBUFFERQUEUE_PACKETLEN, obtained->size * 2);
        if (!device->buffer_queue) {
            close_audio_device(device);
            SDL_SetError("Couldn't create audio buffer queue");
            return 0;
        }
        device->callbackspec.callback = iscapture ? SDL_BufferQueueFillCallback : SDL_BufferQueueDrainCallback;
        device->callbackspec.userdata = device;
    }

    /* Allocate a scratch audio buffer */
    device->work_buffer_len = build_stream ? device->callbackspec.size : 0;
    if (device->spec.size > device->work_buffer_len) {
        device->work_buffer_len = device->spec.size;
    }
    SDL_assert(device->work_buffer_len > 0);

    device->work_buffer = (Uint8 *) SDL_malloc(device->work_buffer_len);
    if (device->work_buffer == NULL) {
        close_audio_device(device);
        SDL_OutOfMemory();
        return 0;
    }

    open_devices[id] = device;  /* add it to our list of open devices. */

    /* Start the audio thread if necessary */
    if (!current_audio.impl.ProvidesOwnCallbackThread) {
        /* Start the audio thread */
        /* !!! FIXME: we don't force the audio thread stack size here if it calls into user code, but maybe we should? */
        /* buffer queueing callback only needs a few bytes, so make the stack tiny. */
        const size_t stacksize = is_internal_thread ? 64 * 1024 : 0;
        char threadname[64];

        SDL_snprintf(threadname, sizeof (threadname), "SDLAudio%c%d", (iscapture) ? 'C' : 'P', (int) device->id);
        device->thread = SDL_CreateThreadInternal(iscapture ? SDL_CaptureAudio : SDL_RunAudio, threadname, stacksize, device);

        if (device->thread == NULL) {
            close_audio_device(device);
            SDL_SetError("Couldn't create audio thread");
            return 0;
        }
    }

    return device->id;
}

static int prepare_audiospec ( const SDL_AudioSpec *  orig, SDL_AudioSpec *  prepared  )

static

Definition at line 1150 of file SDL_audio.c.

References AUDIO_S16, SDL_AudioSpec::channels, SDL_AudioSpec::format, SDL_AudioSpec::freq, SDL_AudioSpec::samples, SDL_atoi, SDL_CalculateAudioSpec(), SDL_getenv, SDL_memcpy, SDL_ParseAudioFormat(), and SDL_SetError.

Referenced by open_audio_device().

{
    SDL_memcpy(prepared, orig, sizeof(SDL_AudioSpec));

    if (orig->freq == 0) {
        const char *env = SDL_getenv("SDL_AUDIO_FREQUENCY");
        if ((!env) || ((prepared->freq = SDL_atoi(env)) == 0)) {
            prepared->freq = 22050;     /* a reasonable default */
        }
    }

    if (orig->format == 0) {
        const char *env = SDL_getenv("SDL_AUDIO_FORMAT");
        if ((!env) || ((prepared->format = SDL_ParseAudioFormat(env)) == 0)) {
            prepared->format = AUDIO_S16;       /* a reasonable default */
        }
    }

    switch (orig->channels) {
    case 0:{
            const char *env = SDL_getenv("SDL_AUDIO_CHANNELS");
            if ((!env) || ((prepared->channels = (Uint8) SDL_atoi(env)) == 0)) {
                prepared->channels = 2; /* a reasonable default */
            }
            break;
        }
    case 1:                    /* Mono */
    case 2:                    /* Stereo */
    case 4:                    /* Quadrophonic */
    case 6:                    /* 5.1 surround */
    case 8:                    /* 7.1 surround */
        break;
    default:
        SDL_SetError("Unsupported number of audio channels.");
        return 0;
    }

    if (orig->samples == 0) {
        const char *env = SDL_getenv("SDL_AUDIO_SAMPLES");
        if ((!env) || ((prepared->samples = (Uint16) SDL_atoi(env)) == 0)) {
            /* Pick a default of ~46 ms at desired frequency */
            /* !!! FIXME: remove this when the non-Po2 resampling is in. */
            const int samples = (prepared->freq / 1000) * 46;
            int power2 = 1;
            while (power2 < samples) {
                power2 *= 2;
            }
            prepared->samples = power2;
        }
    }

    /* Calculate the silence and size of the audio specification */
    SDL_CalculateAudioSpec(prepared);

    return 1;
}

void SDL_AddAudioDevice	(	const int	iscapture,
		const char *	name,
		void *	handle
	)

Definition at line 473 of file SDL_audio.c.

References add_capture_device(), add_output_device(), SDL_AUDIODEVICEADDED, SDL_ENABLE, SDL_GetEventState, SDL_PushEvent, and SDL_zero.

Referenced by SDL_AudioDetectDevices_Default().

{
    const int device_index = iscapture ? add_capture_device(name, handle) : add_output_device(name, handle);
    if (device_index != -1) {
        /* Post the event, if desired */
        if (SDL_GetEventState(SDL_AUDIODEVICEADDED) == SDL_ENABLE) {
            SDL_Event event;
            SDL_zero(event);
            event.adevice.type = SDL_AUDIODEVICEADDED;
            event.adevice.which = device_index;
            event.adevice.iscapture = iscapture;
            SDL_PushEvent(&event);
        }
    }
}

static void SDL_AudioBeginLoopIteration_Default ( _THIS  )

static

Definition at line 234 of file SDL_audio.c.

{                               /* no-op. */
}

static int SDL_AudioCaptureFromDevice_Default ( _THIS  , void *  buffer, int  buflen  )

static

Definition at line 261 of file SDL_audio.c.

{
    return -1;  /* just fail immediately. */
}

static void SDL_AudioCloseDevice_Default ( _THIS  )

static

Definition at line 277 of file SDL_audio.c.

{                               /* no-op. */
}

static void SDL_AudioDeinitialize_Default ( void  )

static

Definition at line 282 of file SDL_audio.c.

{                               /* no-op. */
}

static void SDL_AudioDetectDevices_Default ( void  )

static

Definition at line 211 of file SDL_audio.c.

References DEFAULT_INPUT_DEVNAME, DEFAULT_OUTPUT_DEVNAME, SDL_AudioDriverImpl::HasCaptureSupport, SDL_AudioDriver::impl, SDL_AudioDriverImpl::OnlyHasDefaultCaptureDevice, SDL_AudioDriverImpl::OnlyHasDefaultOutputDevice, SDL_AddAudioDevice(), SDL_assert, SDL_FALSE, and SDL_TRUE.

{
    /* you have to write your own implementation if these assertions fail. */
    SDL_assert(current_audio.impl.OnlyHasDefaultOutputDevice);
    SDL_assert(current_audio.impl.OnlyHasDefaultCaptureDevice || !current_audio.impl.HasCaptureSupport);

    SDL_AddAudioDevice(SDL_FALSE, DEFAULT_OUTPUT_DEVNAME, (void *) ((size_t) 0x1));
    if (current_audio.impl.HasCaptureSupport) {
        SDL_AddAudioDevice(SDL_TRUE, DEFAULT_INPUT_DEVNAME, (void *) ((size_t) 0x2));
    }
}

static void SDL_AudioFlushCapture_Default ( _THIS  )

static

Definition at line 267 of file SDL_audio.c.

{                               /* no-op. */
}

static void SDL_AudioFreeDeviceHandle_Default ( void *  handle )

static

Definition at line 287 of file SDL_audio.c.

{                               /* no-op. */
}

static Uint8* SDL_AudioGetDeviceBuf_Default ( _THIS  )

static

Definition at line 255 of file SDL_audio.c.

References NULL.

{
    return NULL;
}

static int SDL_AudioGetPendingBytes_Default ( _THIS  )

static

Definition at line 249 of file SDL_audio.c.

{
    return 0;
}

int SDL_AudioInit

(

const char *

driver_name

)

Definition at line 932 of file SDL_audio.c.

References AudioBootStrap::demand_only, SDL_AudioDriver::desc, AudioBootStrap::desc, SDL_AudioDriverImpl::DetectDevices, SDL_AudioDriver::detectionLock, finish_audio_entry_points_init(), i, SDL_AudioDriver::impl, AudioBootStrap::init, SDL_AudioDriver::name, AudioBootStrap::name, NULL, SDL_AudioQuit, SDL_CreateMutex, SDL_getenv, SDL_INIT_AUDIO, SDL_SetError, SDL_strlen, SDL_strncasecmp, SDL_WasInit, and SDL_zero.

{
    int i = 0;
    int initialized = 0;
    int tried_to_init = 0;

    if (SDL_WasInit(SDL_INIT_AUDIO)) {
        SDL_AudioQuit();        /* shutdown driver if already running. */
    }

    SDL_zero(current_audio);
    SDL_zero(open_devices);

    /* Select the proper audio driver */
    if (driver_name == NULL) {
        driver_name = SDL_getenv("SDL_AUDIODRIVER");
    }

    for (i = 0; (!initialized) && (bootstrap[i]); ++i) {
        /* make sure we should even try this driver before doing so... */
        const AudioBootStrap *backend = bootstrap[i];
        if ((driver_name && (SDL_strncasecmp(backend->name, driver_name, SDL_strlen(driver_name)) != 0)) ||
            (!driver_name && backend->demand_only)) {
            continue;
        }

        tried_to_init = 1;
        SDL_zero(current_audio);
        current_audio.name = backend->name;
        current_audio.desc = backend->desc;
        initialized = backend->init(&current_audio.impl);
    }

    if (!initialized) {
        /* specific drivers will set the error message if they fail... */
        if (!tried_to_init) {
            if (driver_name) {
                SDL_SetError("Audio target '%s' not available", driver_name);
            } else {
                SDL_SetError("No available audio device");
            }
        }

        SDL_zero(current_audio);
        return -1;            /* No driver was available, so fail. */
    }

    current_audio.detectionLock = SDL_CreateMutex();

    finish_audio_entry_points_init();

    /* Make sure we have a list of devices available at startup. */
    current_audio.impl.DetectDevices();

#ifdef HAVE_LIBSAMPLERATE_H
    LoadLibSampleRate();
#endif

    return 0;
}

static void SDL_AudioLockDevice_Default ( SDL_AudioDevice *  device )

static

Definition at line 313 of file SDL_audio.c.

References is_in_audio_device_thread(), SDL_AudioDevice::mixer_lock, and SDL_LockMutex.

{
    if (!is_in_audio_device_thread(device)) {
        SDL_LockMutex(device->mixer_lock);
    }
}

static void SDL_AudioLockOrUnlockDeviceWithNoMixerLock ( SDL_AudioDevice *  device )

static

Definition at line 329 of file SDL_audio.c.

Referenced by finish_audio_entry_points_init().

{
}

static int SDL_AudioOpenDevice_Default ( _THIS  , void *  handle, const char *  devname, int  iscapture  )

static

Definition at line 293 of file SDL_audio.c.

References SDL_Unsupported.

{
    return SDL_Unsupported();
}

static void SDL_AudioPlayDevice_Default ( _THIS  )

static

Definition at line 244 of file SDL_audio.c.

{                               /* no-op. */
}

static void SDL_AudioPrepareToClose_Default ( _THIS  )

static

Definition at line 272 of file SDL_audio.c.

{                               /* no-op. */
}

void SDL_AudioQuit

(

void

)

Definition at line 1582 of file SDL_audio.c.

References close_audio_device(), SDL_AudioDriverImpl::Deinitialize, SDL_AudioDriver::detectionLock, free_device_list(), i, SDL_AudioDriver::impl, SDL_AudioDriver::inputDeviceCount, SDL_AudioDriver::inputDevices, SDL_AudioDriver::name, SDL_AudioDriver::outputDeviceCount, SDL_AudioDriver::outputDevices, SDL_arraysize, SDL_DestroyMutex, SDL_FreeResampleFilter(), and SDL_zero.

{
    SDL_AudioDeviceID i;

    if (!current_audio.name) {  /* not initialized?! */
        return;
    }

    for (i = 0; i < SDL_arraysize(open_devices); i++) {
        close_audio_device(open_devices[i]);
    }

    free_device_list(&current_audio.outputDevices, &current_audio.outputDeviceCount);
    free_device_list(&current_audio.inputDevices, &current_audio.inputDeviceCount);

    /* Free the driver data */
    current_audio.impl.Deinitialize();

    SDL_DestroyMutex(current_audio.detectionLock);

    SDL_zero(current_audio);
    SDL_zero(open_devices);

#ifdef HAVE_LIBSAMPLERATE_H
    UnloadLibSampleRate();
#endif

    SDL_FreeResampleFilter();
}

static void SDL_AudioThreadDeinit_Default ( _THIS  )

static

Definition at line 229 of file SDL_audio.c.

{                               /* no-op. */
}

static void SDL_AudioThreadInit_Default ( _THIS  )

static

Definition at line 224 of file SDL_audio.c.

{                               /* no-op. */
}

static void SDL_AudioUnlockDevice_Default ( SDL_AudioDevice *  device )

static

Definition at line 321 of file SDL_audio.c.

References is_in_audio_device_thread(), SDL_AudioDevice::mixer_lock, and SDL_UnlockMutex.

{
    if (!is_in_audio_device_thread(device)) {
        SDL_UnlockMutex(device->mixer_lock);
    }
}

static void SDL_AudioWaitDevice_Default ( _THIS  )

static

Definition at line 239 of file SDL_audio.c.

{                               /* no-op. */
}

static void SDL_BufferQueueDrainCallback ( void *  userdata, Uint8 *  stream, int  len  )

static

Definition at line 565 of file SDL_audio.c.

References SDL_AudioDevice::buffer_queue, device, SDL_AudioDevice::iscapture, NULL, SDL_assert, SDL_CountDataQueue(), SDL_memset, SDL_ReadFromDataQueue(), SDL_AudioSpec::silence, and SDL_AudioDevice::spec.

Referenced by open_audio_device(), SDL_GetQueuedAudioSize(), and SDL_QueueAudio().

{
    /* this function always holds the mixer lock before being called. */
    SDL_AudioDevice *device = (SDL_AudioDevice *) userdata;
    size_t dequeued;

    SDL_assert(device != NULL);  /* this shouldn't ever happen, right?! */
    SDL_assert(!device->iscapture);  /* this shouldn't ever happen, right?! */
    SDL_assert(len >= 0);  /* this shouldn't ever happen, right?! */

    dequeued = SDL_ReadFromDataQueue(device->buffer_queue, stream, len);
    stream += dequeued;
    len -= (int) dequeued;

    if (len > 0) {  /* fill any remaining space in the stream with silence. */
        SDL_assert(SDL_CountDataQueue(device->buffer_queue) == 0);
        SDL_memset(stream, device->spec.silence, len);
    }
}

static void SDL_BufferQueueFillCallback ( void *  userdata, Uint8 *  stream, int  len  )

static

Definition at line 586 of file SDL_audio.c.

References SDL_AudioDevice::buffer_queue, device, SDL_AudioDevice::iscapture, NULL, SDL_assert, and SDL_WriteToDataQueue().

Referenced by open_audio_device(), SDL_DequeueAudio(), and SDL_GetQueuedAudioSize().

{
    /* this function always holds the mixer lock before being called. */
    SDL_AudioDevice *device = (SDL_AudioDevice *) userdata;

    SDL_assert(device != NULL);  /* this shouldn't ever happen, right?! */
    SDL_assert(device->iscapture);  /* this shouldn't ever happen, right?! */
    SDL_assert(len >= 0);  /* this shouldn't ever happen, right?! */

    /* note that if this needs to allocate more space and run out of memory,
       we have no choice but to quietly drop the data and hope it works out
       later, but you probably have bigger problems in this case anyhow. */
    SDL_WriteToDataQueue(device->buffer_queue, stream, len);
}

void SDL_CalculateAudioSpec

(

SDL_AudioSpec *

spec

)

Definition at line 1660 of file SDL_audio.c.

References AUDIO_U8, SDL_AudioSpec::channels, SDL_AudioSpec::format, SDL_AudioSpec::samples, SDL_AUDIO_BITSIZE, SDL_AudioSpec::silence, and SDL_AudioSpec::size.

Referenced by open_audio_device(), and prepare_audiospec().

{
    switch (spec->format) {
    case AUDIO_U8:
        spec->silence = 0x80;
        break;
    default:
        spec->silence = 0x00;
        break;
    }
    spec->size = SDL_AUDIO_BITSIZE(spec->format) / 8;
    spec->size *= spec->channels;
    spec->size *= spec->samples;
}

static int SDL_CaptureAudio ( void *  devicep )

static

Definition at line 783 of file SDL_audio.c.

References SDL_AudioDriverImpl::BeginLoopIteration, callback(), SDL_AudioSpec::callback, SDL_AudioDevice::callbackspec, SDL_AudioDriverImpl::CaptureFromDevice, device, SDL_AudioDevice::enabled, SDL_AudioDriverImpl::FlushCapture, SDL_AudioSpec::freq, SDL_AudioDriver::impl, SDL_AudioDevice::iscapture, SDL_AudioDevice::mixer_lock, NULL, SDL_AudioDevice::paused, SDL_AudioDriverImpl::PrepareToClose, SDL_AudioSpec::samples, SDL_assert, SDL_AtomicGet, SDL_AudioStreamAvailable, SDL_AudioStreamClear, SDL_AudioStreamGet, SDL_AudioStreamPut, SDL_Delay, SDL_LockMutex, SDL_memset, SDL_OpenedAudioDeviceDisconnected(), SDL_SetThreadPriority, SDL_THREAD_PRIORITY_HIGH, SDL_ThreadID, SDL_UnlockMutex, SDL_AudioDevice::shutdown, SDL_AudioSpec::silence, SDL_AudioSpec::size, SDL_AudioDevice::spec, SDL_AudioDevice::stream, SDL_AudioDriverImpl::ThreadDeinit, SDL_AudioDevice::threadid, SDL_AudioDriverImpl::ThreadInit, SDL_AudioSpec::userdata, and SDL_AudioDevice::work_buffer.

Referenced by open_audio_device().

{
    SDL_AudioDevice *device = (SDL_AudioDevice *) devicep;
    const int silence = (int) device->spec.silence;
    const Uint32 delay = ((device->spec.samples * 1000) / device->spec.freq);
    const int data_len = device->spec.size;
    Uint8 *data;
    void *udata = device->callbackspec.userdata;
    SDL_AudioCallback callback = device->callbackspec.callback;

    SDL_assert(device->iscapture);

    /* The audio mixing is always a high priority thread */
    SDL_SetThreadPriority(SDL_THREAD_PRIORITY_HIGH);

    /* Perform any thread setup */
    device->threadid = SDL_ThreadID();
    current_audio.impl.ThreadInit(device);

    /* Loop, filling the audio buffers */
    while (!SDL_AtomicGet(&device->shutdown)) {
        int still_need;
        Uint8 *ptr;

        current_audio.impl.BeginLoopIteration(device);

        if (SDL_AtomicGet(&device->paused)) {
            SDL_Delay(delay);  /* just so we don't cook the CPU. */
            if (device->stream) {
                SDL_AudioStreamClear(device->stream);
            }
            current_audio.impl.FlushCapture(device);  /* dump anything pending. */
            continue;
        }

        /* Fill the current buffer with sound */
        still_need = data_len;

        /* Use the work_buffer to hold data read from the device. */
        data = device->work_buffer;
        SDL_assert(data != NULL);

        ptr = data;

        /* We still read from the device when "paused" to keep the state sane,
           and block when there isn't data so this thread isn't eating CPU.
           But we don't process it further or call the app's callback. */

        if (!SDL_AtomicGet(&device->enabled)) {
            SDL_Delay(delay);  /* try to keep callback firing at normal pace. */
        } else {
            while (still_need > 0) {
                const int rc = current_audio.impl.CaptureFromDevice(device, ptr, still_need);
                SDL_assert(rc <= still_need);  /* device should not overflow buffer. :) */
                if (rc > 0) {
                    still_need -= rc;
                    ptr += rc;
                } else {  /* uhoh, device failed for some reason! */
                    SDL_OpenedAudioDeviceDisconnected(device);
                    break;
                }
            }
        }

        if (still_need > 0) {
            /* Keep any data we already read, silence the rest. */
            SDL_memset(ptr, silence, still_need);
        }

        if (device->stream) {
            /* if this fails...oh well. */
            SDL_AudioStreamPut(device->stream, data, data_len);

            while (SDL_AudioStreamAvailable(device->stream) >= ((int) device->callbackspec.size)) {
                const int got = SDL_AudioStreamGet(device->stream, device->work_buffer, device->callbackspec.size);
                SDL_assert((got < 0) || (got == device->callbackspec.size));
                if (got != device->callbackspec.size) {
                    SDL_memset(device->work_buffer, device->spec.silence, device->callbackspec.size);
                }

                /* !!! FIXME: this should be LockDevice. */
                SDL_LockMutex(device->mixer_lock);
                if (!SDL_AtomicGet(&device->paused)) {
                    callback(udata, device->work_buffer, device->callbackspec.size);
                }
                SDL_UnlockMutex(device->mixer_lock);
            }
        } else {  /* feeding user callback directly without streaming. */
            /* !!! FIXME: this should be LockDevice. */
            SDL_LockMutex(device->mixer_lock);
            if (!SDL_AtomicGet(&device->paused)) {
                callback(udata, data, device->callbackspec.size);
            }
            SDL_UnlockMutex(device->mixer_lock);
        }
    }

    current_audio.impl.PrepareToClose(device);

    current_audio.impl.FlushCapture(device);

    current_audio.impl.ThreadDeinit(device);

    return 0;
}

void SDL_ClearQueuedAudio

(

SDL_AudioDeviceID

dev

)

Drop any queued audio data. For playback devices, this is any queued data still waiting to be submitted to the hardware. For capture devices, this is any data that was queued by the device that hasn't yet been dequeued by the application.

Immediately after this call, SDL_GetQueuedAudioSize() will return 0. For playback devices, the hardware will start playing silence if more audio isn't queued. Unpaused capture devices will start filling the queue again as soon as they have more data available (which, depending on the state of the hardware and the thread, could be before this function call returns!).

This will not prevent playback of queued audio that's already been sent to the hardware, as we can not undo that, so expect there to be some fraction of a second of audio that might still be heard. This can be useful if you want to, say, drop any pending music during a level change in your game.

You may not queue audio on a device that is using an application-supplied callback; calling this function on such a device is always a no-op. You have to queue audio with SDL_QueueAudio()/SDL_DequeueAudio(), or use the audio callback, but not both.

You should not call SDL_LockAudio() on the device before clearing the queue; SDL handles locking internally for this function.

This function always succeeds and thus returns void.

Parameters

dev	The device ID of which to clear the audio queue.

See Also

SDL_QueueAudio

SDL_GetQueuedAudioSize

Definition at line 668 of file SDL_audio.c.

References SDL_AudioDevice::buffer_queue, device, get_audio_device(), SDL_AudioDriver::impl, SDL_AudioDriverImpl::LockDevice, SDL_AUDIOBUFFERQUEUE_PACKETLEN, SDL_ClearDataQueue(), and SDL_AudioDriverImpl::UnlockDevice.

{
    SDL_AudioDevice *device = get_audio_device(devid);

    if (!device) {
        return;  /* nothing to do. */
    }

    /* Blank out the device and release the mutex. Free it afterwards. */
    current_audio.impl.LockDevice(device);

    /* Keep up to two packets in the pool to reduce future malloc pressure. */
    SDL_ClearDataQueue(device->buffer_queue, SDL_AUDIOBUFFERQUEUE_PACKETLEN * 2);

    current_audio.impl.UnlockDevice(device);
}

void SDL_CloseAudio

(

void

)

This function shuts down audio processing and closes the audio device.

Definition at line 1576 of file SDL_audio.c.

References SDL_CloseAudioDevice.

{
    SDL_CloseAudioDevice(1);
}

void SDL_CloseAudioDevice

(

SDL_AudioDeviceID

devid

)

Definition at line 1570 of file SDL_audio.c.

References close_audio_device(), and get_audio_device().

{
    close_audio_device(get_audio_device(devid));
}

Uint32 SDL_DequeueAudio	(	SDL_AudioDeviceID	dev,
		void *	data,
		Uint32	len
	)

Dequeue more audio on non-callback devices.

(If you are looking to queue audio for output on a non-callback playback device, you want SDL_QueueAudio() instead. This will always return 0 if you use it with playback devices.)

SDL offers two ways to retrieve audio from a capture device: you can either supply a callback that SDL triggers with some frequency as the device records more audio data, (push method), or you can supply no callback, and then SDL will expect you to retrieve data at regular intervals (pull method) with this function.

There are no limits on the amount of data you can queue, short of exhaustion of address space. Data from the device will keep queuing as necessary without further intervention from you. This means you will eventually run out of memory if you aren't routinely dequeueing data.

Capture devices will not queue data when paused; if you are expecting to not need captured audio for some length of time, use SDL_PauseAudioDevice() to stop the capture device from queueing more data. This can be useful during, say, level loading times. When unpaused, capture devices will start queueing data from that point, having flushed any capturable data available while paused.

This function is thread-safe, but dequeueing from the same device from two threads at once does not promise which thread will dequeued data first.

You may not dequeue audio from a device that is using an application-supplied callback; doing so returns an error. You have to use the audio callback, or dequeue audio with this function, but not both.

You should not call SDL_LockAudio() on the device before queueing; SDL handles locking internally for this function.

Parameters

dev	The device ID from which we will dequeue audio.
data	A pointer into where audio data should be copied.
len	The number of bytes (not samples!) to which (data) points.

Returns

number of bytes dequeued, which could be less than requested.

See Also

SDL_GetQueuedAudioSize

SDL_ClearQueuedAudio

Definition at line 625 of file SDL_audio.c.

References SDL_AudioDevice::buffer_queue, SDL_AudioSpec::callback, SDL_AudioDevice::callbackspec, device, get_audio_device(), SDL_AudioDriver::impl, SDL_AudioDevice::iscapture, SDL_AudioDriverImpl::LockDevice, SDL_BufferQueueFillCallback(), SDL_ReadFromDataQueue(), and SDL_AudioDriverImpl::UnlockDevice.

{
    SDL_AudioDevice *device = get_audio_device(devid);
    Uint32 rc;

    if ( (len == 0) ||  /* nothing to do? */
         (!device) ||  /* called with bogus device id */
         (!device->iscapture) ||  /* playback devices can't dequeue */
         (device->callbackspec.callback != SDL_BufferQueueFillCallback) ) { /* not set for queueing */
        return 0;  /* just report zero bytes dequeued. */
    }

    current_audio.impl.LockDevice(device);
    rc = (Uint32) SDL_ReadFromDataQueue(device->buffer_queue, data, len);
    current_audio.impl.UnlockDevice(device);
    return rc;
}

SDL_AudioFormat SDL_FirstAudioFormat

(

SDL_AudioFormat

format

)

Definition at line 1639 of file SDL_audio.c.

References format_idx, NUM_FORMATS, and SDL_NextAudioFormat().

{
    for (format_idx = 0; format_idx < NUM_FORMATS; ++format_idx) {
        if (format_list[format_idx][0] == format) {
            break;
        }
    }
    format_idx_sub = 0;
    return SDL_NextAudioFormat();
}

const char* SDL_GetAudioDeviceName	(	int	index,
		int	iscapture
	)

Get the human-readable name of a specific audio device. Must be a value between 0 and (number of audio devices-1). Only valid after a successfully initializing the audio subsystem. The values returned by this function reflect the latest call to SDL_GetNumAudioDevices(); recall that function to redetect available hardware.

The string returned by this function is UTF-8 encoded, read-only, and managed internally. You are not to free it. If you need to keep the string for any length of time, you should make your own copy of it, as it will be invalid next time any of several other SDL functions is called.

Definition at line 1062 of file SDL_audio.c.

References SDL_AudioDriver::detectionLock, SDL_AudioDriverImpl::HasCaptureSupport, i, SDL_AudioDriver::impl, SDL_AudioDriver::inputDeviceCount, SDL_AudioDriver::inputDevices, SDL_AudioDeviceItem::next, NULL, SDL_AudioDriver::outputDeviceCount, SDL_AudioDriver::outputDevices, retval, SDL_assert, SDL_INIT_AUDIO, SDL_LockMutex, SDL_SetError, SDL_UnlockMutex, and SDL_WasInit.

{
    const char *retval = NULL;

    if (!SDL_WasInit(SDL_INIT_AUDIO)) {
        SDL_SetError("Audio subsystem is not initialized");
        return NULL;
    }

    if ((iscapture) && (!current_audio.impl.HasCaptureSupport)) {
        SDL_SetError("No capture support");
        return NULL;
    }

    if (index >= 0) {
        SDL_AudioDeviceItem *item;
        int i;

        SDL_LockMutex(current_audio.detectionLock);
        item = iscapture ? current_audio.inputDevices : current_audio.outputDevices;
        i = iscapture ? current_audio.inputDeviceCount : current_audio.outputDeviceCount;
        if (index < i) {
            for (i--; i > index; i--, item = item->next) {
                SDL_assert(item != NULL);
            }
            SDL_assert(item != NULL);
            retval = item->name;
        }
        SDL_UnlockMutex(current_audio.detectionLock);
    }

    if (retval == NULL) {
        SDL_SetError("No such device");
    }

    return retval;
}

SDL_AudioStatus SDL_GetAudioDeviceStatus

(

SDL_AudioDeviceID

devid

)

Definition at line 1498 of file SDL_audio.c.

References device, SDL_AudioDevice::enabled, get_audio_device(), SDL_AudioDevice::paused, SDL_AtomicGet, SDL_AUDIO_PAUSED, SDL_AUDIO_PLAYING, and SDL_AUDIO_STOPPED.

{
    SDL_AudioDevice *device = get_audio_device(devid);
    SDL_AudioStatus status = SDL_AUDIO_STOPPED;
    if (device && SDL_AtomicGet(&device->enabled)) {
        if (SDL_AtomicGet(&device->paused)) {
            status = SDL_AUDIO_PAUSED;
        } else {
            status = SDL_AUDIO_PLAYING;
        }
    }
    return status;
}

const char* SDL_GetAudioDriver

(

int

index

)

Definition at line 923 of file SDL_audio.c.

References AudioBootStrap::name, NULL, and SDL_GetNumAudioDrivers.

{
    if (index >= 0 && index < SDL_GetNumAudioDrivers()) {
        return bootstrap[index]->name;
    }
    return NULL;
}

SDL_AudioStatus SDL_GetAudioStatus

(

void

)

Definition at line 1514 of file SDL_audio.c.

References SDL_GetAudioDeviceStatus.

{
    return SDL_GetAudioDeviceStatus(1);
}

const char* SDL_GetCurrentAudioDriver

(

void

)

This function returns the name of the current audio driver, or NULL if no driver has been initialized.

Definition at line 997 of file SDL_audio.c.

References SDL_AudioDriver::name.

{
    return current_audio.name;
}

int SDL_GetNumAudioDevices

(

int

iscapture

)

Get the number of available devices exposed by the current driver. Only valid after a successfully initializing the audio subsystem. Returns -1 if an explicit list of devices can't be determined; this is not an error. For example, if SDL is set up to talk to a remote audio server, it can't list every one available on the Internet, but it will still allow a specific host to be specified to SDL_OpenAudioDevice().

In many common cases, when this function returns a value <= 0, it can still successfully open the default device (NULL for first argument of SDL_OpenAudioDevice()).

Definition at line 1037 of file SDL_audio.c.

References SDL_AudioDriver::captureDevicesRemoved, clean_out_device_list(), SDL_AudioDriver::detectionLock, SDL_AudioDriver::inputDeviceCount, SDL_AudioDriver::inputDevices, SDL_AudioDriver::outputDeviceCount, SDL_AudioDriver::outputDevices, SDL_AudioDriver::outputDevicesRemoved, retval, SDL_INIT_AUDIO, SDL_LockMutex, SDL_UnlockMutex, and SDL_WasInit.

{
    int retval = 0;

    if (!SDL_WasInit(SDL_INIT_AUDIO)) {
        return -1;
    }

    SDL_LockMutex(current_audio.detectionLock);
    if (iscapture && current_audio.captureDevicesRemoved) {
        clean_out_device_list(&current_audio.inputDevices, &current_audio.inputDeviceCount, &current_audio.captureDevicesRemoved);
    }

    if (!iscapture && current_audio.outputDevicesRemoved) {
        clean_out_device_list(&current_audio.outputDevices, &current_audio.outputDeviceCount, &current_audio.outputDevicesRemoved);
    }

    retval = iscapture ? current_audio.inputDeviceCount : current_audio.outputDeviceCount;
    SDL_UnlockMutex(current_audio.detectionLock);

    return retval;
}

int SDL_GetNumAudioDrivers

(

void

)

Definition at line 917 of file SDL_audio.c.

References SDL_arraysize.

{
    return SDL_arraysize(bootstrap) - 1;
}

Uint32 SDL_GetQueuedAudioSize

(

SDL_AudioDeviceID

dev

)

Get the number of bytes of still-queued audio.

For playback device:

This is the number of bytes that have been queued for playback with SDL_QueueAudio(), but have not yet been sent to the hardware. This number may shrink at any time, so this only informs of pending data.

Once we've sent it to the hardware, this function can not decide the exact byte boundary of what has been played. It's possible that we just gave the hardware several kilobytes right before you called this function, but it hasn't played any of it yet, or maybe half of it, etc.

For capture devices:

This is the number of bytes that have been captured by the device and are waiting for you to dequeue. This number may grow at any time, so this only informs of the lower-bound of available data.

You may not queue audio on a device that is using an application-supplied callback; calling this function on such a device always returns 0. You have to queue audio with SDL_QueueAudio()/SDL_DequeueAudio(), or use the audio callback, but not both.

You should not call SDL_LockAudio() on the device before querying; SDL handles locking internally for this function.

Parameters

dev	The device ID of which we will query queued audio size.

Returns

Number of bytes (not samples!) of queued audio.

See Also

SDL_QueueAudio

SDL_ClearQueuedAudio

Definition at line 644 of file SDL_audio.c.

References SDL_AudioDevice::buffer_queue, SDL_AudioSpec::callback, SDL_AudioDevice::callbackspec, device, get_audio_device(), SDL_AudioDriverImpl::GetPendingBytes, SDL_AudioDriver::impl, SDL_AudioDriverImpl::LockDevice, retval, SDL_BufferQueueDrainCallback(), SDL_BufferQueueFillCallback(), SDL_CountDataQueue(), and SDL_AudioDriverImpl::UnlockDevice.

{
    Uint32 retval = 0;
    SDL_AudioDevice *device = get_audio_device(devid);

    if (!device) {
        return 0;
    }

    /* Nothing to do unless we're set up for queueing. */
    if (device->callbackspec.callback == SDL_BufferQueueDrainCallback) {
        current_audio.impl.LockDevice(device);
        retval = ((Uint32) SDL_CountDataQueue(device->buffer_queue)) + current_audio.impl.GetPendingBytes(device);
        current_audio.impl.UnlockDevice(device);
    } else if (device->callbackspec.callback == SDL_BufferQueueFillCallback) {
        current_audio.impl.LockDevice(device);
        retval = (Uint32) SDL_CountDataQueue(device->buffer_queue);
        current_audio.impl.UnlockDevice(device);
    }

    return retval;
}

void SDL_LockAudio

(

void

)

Definition at line 1548 of file SDL_audio.c.

References SDL_LockAudioDevice.

{
    SDL_LockAudioDevice(1);
}

void SDL_LockAudioDevice

(

SDL_AudioDeviceID

devid

)

Definition at line 1538 of file SDL_audio.c.

References device, get_audio_device(), SDL_AudioDriver::impl, and SDL_AudioDriverImpl::LockDevice.

{
    /* Obtain a lock on the mixing buffers */
    SDL_AudioDevice *device = get_audio_device(devid);
    if (device) {
        current_audio.impl.LockDevice(device);
    }
}

void SDL_MixAudio	(	Uint8 *	dst,
		const Uint8 *	src,
		Uint32	len,
		int	volume
	)

This takes two audio buffers of the playing audio format and mixes them, performing addition, volume adjustment, and overflow clipping. The volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME for full audio volume. Note this does not change hardware volume. This is provided for convenience – you can mix your own audio data.

Definition at line 1681 of file SDL_audio.c.

References SDL_AudioDevice::callbackspec, device, SDL_AudioSpec::format, get_audio_device(), NULL, and SDL_MixAudioFormat.

{
    /* Mix the user-level audio format */
    SDL_AudioDevice *device = get_audio_device(1);
    if (device != NULL) {
        SDL_MixAudioFormat(dst, src, device->callbackspec.format, len, volume);
    }
}

SDL_AudioFormat SDL_NextAudioFormat

(

void

)

Definition at line 1651 of file SDL_audio.c.

References format_idx, and NUM_FORMATS.

Referenced by SDL_FirstAudioFormat().

{
    if ((format_idx == NUM_FORMATS) || (format_idx_sub == NUM_FORMATS)) {
        return 0;
    }
    return format_list[format_idx][format_idx_sub++];
}

int SDL_OpenAudio	(	SDL_AudioSpec *	desired,
		SDL_AudioSpec *	obtained
	)

This function opens the audio device with the desired parameters, and returns 0 if successful, placing the actual hardware parameters in the structure pointed to by obtained. If obtained is NULL, the audio data passed to the callback function will be guaranteed to be in the requested format, and will be automatically converted to the hardware audio format if necessary. This function returns -1 if it failed to open the audio device, or couldn't set up the audio thread.

When filling in the desired audio spec structure,

• desired->freq should be the desired audio frequency in samples-per- second.
• desired->format should be the desired audio format.
• desired->samples is the desired size of the audio buffer, in samples. This number should be a power of two, and may be adjusted by the audio driver to a value more suitable for the hardware. Good values seem to range between 512 and 8096 inclusive, depending on the application and CPU speed. Smaller values yield faster response time, but can lead to underflow if the application is doing heavy processing and cannot fill the audio buffer in time. A stereo sample consists of both right and left channels in LR ordering. Note that the number of samples is directly related to time by the following formula:

  ms = (samples*1000)/freq 

• desired->size is the size in bytes of the audio buffer, and is calculated by SDL_OpenAudio().
• desired->silence is the value used to set the buffer to silence, and is calculated by SDL_OpenAudio().
• desired->callback should be set to a function that will be called when the audio device is ready for more data. It is passed a pointer to the audio buffer, and the length in bytes of the audio buffer. This function usually runs in a separate thread, and so you should protect data structures that it accesses by calling SDL_LockAudio() and SDL_UnlockAudio() in your code. Alternately, you may pass a NULL pointer here, and call SDL_QueueAudio() with some frequency, to queue more audio samples to be played (or for capture devices, call SDL_DequeueAudio() with some frequency, to obtain audio samples).
• desired->userdata is passed as the first parameter to your callback function. If you passed a NULL callback, this value is ignored.

The audio device starts out playing silence when it's opened, and should be enabled for playing by calling SDL_PauseAudio(0) when you are ready for your audio callback function to be called. Since the audio driver may modify the requested size of the audio buffer, you should allocate any local mixing buffers after you open the audio device.

Definition at line 1453 of file SDL_audio.c.

References NULL, open_audio_device(), SDL_assert, SDL_AUDIO_ALLOW_ANY_CHANGE, SDL_INIT_AUDIO, SDL_InitSubSystem, SDL_SetError, SDL_WasInit, SDL_zero, SDL_AudioSpec::silence, and SDL_AudioSpec::size.

{
    SDL_AudioDeviceID id = 0;

    /* Start up the audio driver, if necessary. This is legacy behaviour! */
    if (!SDL_WasInit(SDL_INIT_AUDIO)) {
        if (SDL_InitSubSystem(SDL_INIT_AUDIO) < 0) {
            return -1;
        }
    }

    /* SDL_OpenAudio() is legacy and can only act on Device ID #1. */
    if (open_devices[0] != NULL) {
        SDL_SetError("Audio device is already opened");
        return -1;
    }

    if (obtained) {
        id = open_audio_device(NULL, 0, desired, obtained,
                               SDL_AUDIO_ALLOW_ANY_CHANGE, 1);
    } else {
        SDL_AudioSpec _obtained;
        SDL_zero(_obtained);
        id = open_audio_device(NULL, 0, desired, &_obtained, 0, 1);
        /* On successful open, copy calculated values into 'desired'. */
        if (id > 0) {
            desired->size = _obtained.size;
            desired->silence = _obtained.silence;
        }
    }

    SDL_assert((id == 0) || (id == 1));
    return (id == 0) ? -1 : 0;
}

SDL_AudioDeviceID SDL_OpenAudioDevice	(	const char *	device,
		int	iscapture,
		const SDL_AudioSpec *	desired,
		SDL_AudioSpec *	obtained,
		int	allowed_changes
	)

Open a specific audio device. Passing in a device name of NULL requests the most reasonable default (and is equivalent to calling SDL_OpenAudio()).

The device name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but some drivers allow arbitrary and driver-specific strings, such as a hostname/IP address for a remote audio server, or a filename in the diskaudio driver.

Returns

0 on error, a valid device ID that is >= 2 on success.

SDL_OpenAudio(), unlike this function, always acts on device ID 1.

Definition at line 1489 of file SDL_audio.c.

References open_audio_device().

{
    return open_audio_device(device, iscapture, desired, obtained,
                             allowed_changes, 2);
}

void SDL_OpenedAudioDeviceDisconnected

(

SDL_AudioDevice *

device

)

Definition at line 490 of file SDL_audio.c.

References SDL_AudioDevice::enabled, get_audio_device(), SDL_AudioDevice::id, SDL_AudioDriver::impl, SDL_AudioDevice::iscapture, SDL_AudioDriverImpl::LockDevice, SDL_assert, SDL_AtomicGet, SDL_AtomicSet, SDL_AUDIODEVICEREMOVED, SDL_ENABLE, SDL_GetEventState, SDL_PushEvent, SDL_zero, SDL_AudioDevice::shutdown, and SDL_AudioDriverImpl::UnlockDevice.

Referenced by SDL_CaptureAudio(), and SDL_RemoveAudioDevice().

{
    SDL_assert(get_audio_device(device->id) == device);

    if (!SDL_AtomicGet(&device->enabled)) {
        return;  /* don't report disconnects more than once. */
    }

    if (SDL_AtomicGet(&device->shutdown)) {
        return;  /* don't report disconnect if we're trying to close device. */
    }

    /* Ends the audio callback and mark the device as STOPPED, but the
       app still needs to close the device to free resources. */
    current_audio.impl.LockDevice(device);
    SDL_AtomicSet(&device->enabled, 0);
    current_audio.impl.UnlockDevice(device);

    /* Post the event, if desired */
    if (SDL_GetEventState(SDL_AUDIODEVICEREMOVED) == SDL_ENABLE) {
        SDL_Event event;
        SDL_zero(event);
        event.adevice.type = SDL_AUDIODEVICEREMOVED;
        event.adevice.which = device->id;
        event.adevice.iscapture = device->iscapture ? 1 : 0;
        SDL_PushEvent(&event);
    }
}

static SDL_AudioFormat SDL_ParseAudioFormat ( const char *  string )

static

Definition at line 891 of file SDL_audio.c.

References CHECK_FMT_STRING, and S32.

Referenced by prepare_audiospec().

{
#define CHECK_FMT_STRING(x) if (SDL_strcmp(string, #x) == 0) return AUDIO_##x
    CHECK_FMT_STRING(U8);
    CHECK_FMT_STRING(S8);
    CHECK_FMT_STRING(U16LSB);
    CHECK_FMT_STRING(S16LSB);
    CHECK_FMT_STRING(U16MSB);
    CHECK_FMT_STRING(S16MSB);
    CHECK_FMT_STRING(U16SYS);
    CHECK_FMT_STRING(S16SYS);
    CHECK_FMT_STRING(U16);
    CHECK_FMT_STRING(S16);
    CHECK_FMT_STRING(S32LSB);
    CHECK_FMT_STRING(S32MSB);
    CHECK_FMT_STRING(S32SYS);
    CHECK_FMT_STRING(S32);
    CHECK_FMT_STRING(F32LSB);
    CHECK_FMT_STRING(F32MSB);
    CHECK_FMT_STRING(F32SYS);
    CHECK_FMT_STRING(F32);
#undef CHECK_FMT_STRING
    return 0;
}

void SDL_PauseAudio

(

int

pause_on

)

Definition at line 1531 of file SDL_audio.c.

References SDL_PauseAudioDevice.

{
    SDL_PauseAudioDevice(1, pause_on);
}

void SDL_PauseAudioDevice	(	SDL_AudioDeviceID	devid,
		int	pause_on
	)

Definition at line 1520 of file SDL_audio.c.

References device, get_audio_device(), SDL_AudioDriver::impl, SDL_AudioDriverImpl::LockDevice, SDL_AudioDevice::paused, SDL_AtomicSet, and SDL_AudioDriverImpl::UnlockDevice.

{
    SDL_AudioDevice *device = get_audio_device(devid);
    if (device) {
        current_audio.impl.LockDevice(device);
        SDL_AtomicSet(&device->paused, pause_on ? 1 : 0);
        current_audio.impl.UnlockDevice(device);
    }
}

int SDL_QueueAudio	(	SDL_AudioDeviceID	dev,
		const void *	data,
		Uint32	len
	)

Queue more audio on non-callback devices.

(If you are looking to retrieve queued audio from a non-callback capture device, you want SDL_DequeueAudio() instead. This will return -1 to signify an error if you use it with capture devices.)

SDL offers two ways to feed audio to the device: you can either supply a callback that SDL triggers with some frequency to obtain more audio (pull method), or you can supply no callback, and then SDL will expect you to supply data at regular intervals (push method) with this function.

There are no limits on the amount of data you can queue, short of exhaustion of address space. Queued data will drain to the device as necessary without further intervention from you. If the device needs audio but there is not enough queued, it will play silence to make up the difference. This means you will have skips in your audio playback if you aren't routinely queueing sufficient data.

This function copies the supplied data, so you are safe to free it when the function returns. This function is thread-safe, but queueing to the same device from two threads at once does not promise which buffer will be queued first.

You may not queue audio on a device that is using an application-supplied callback; doing so returns an error. You have to use the audio callback or queue audio with this function, but not both.

You should not call SDL_LockAudio() on the device before queueing; SDL handles locking internally for this function.

Parameters

dev	The device ID to which we will queue audio.
data	The data to queue to the device for later playback.
len	The number of bytes (not samples!) to which (data) points.

Returns

0 on success, or -1 on error.

See Also

SDL_GetQueuedAudioSize

SDL_ClearQueuedAudio

Definition at line 602 of file SDL_audio.c.

References SDL_AudioDevice::buffer_queue, SDL_AudioSpec::callback, SDL_AudioDevice::callbackspec, device, get_audio_device(), SDL_AudioDriver::impl, SDL_AudioDevice::iscapture, SDL_AudioDriverImpl::LockDevice, SDL_BufferQueueDrainCallback(), SDL_SetError, SDL_WriteToDataQueue(), and SDL_AudioDriverImpl::UnlockDevice.

{
    SDL_AudioDevice *device = get_audio_device(devid);
    int rc = 0;

    if (!device) {
        return -1;  /* get_audio_device() will have set the error state */
    } else if (device->iscapture) {
        return SDL_SetError("This is a capture device, queueing not allowed");
    } else if (device->callbackspec.callback != SDL_BufferQueueDrainCallback) {
        return SDL_SetError("Audio device has a callback, queueing not allowed");
    }

    if (len > 0) {
        current_audio.impl.LockDevice(device);
        rc = SDL_WriteToDataQueue(device->buffer_queue, data, len);
        current_audio.impl.UnlockDevice(device);
    }

    return rc;
}

void SDL_RemoveAudioDevice	(	const int	iscapture,
		void *	handle
	)

Definition at line 535 of file SDL_audio.c.

References SDL_AudioDriver::captureDevicesRemoved, SDL_AudioDriver::detectionLock, device, SDL_AudioDriverImpl::FreeDeviceHandle, SDL_AudioDevice::handle, SDL_AudioDriver::impl, SDL_AudioDriver::inputDevices, mark_device_removed(), NULL, SDL_AudioDriver::outputDevices, SDL_AudioDriver::outputDevicesRemoved, SDL_arraysize, SDL_LockMutex, SDL_OpenedAudioDeviceDisconnected(), and SDL_UnlockMutex.

{
    int device_index;
    SDL_AudioDevice *device = NULL;

    SDL_LockMutex(current_audio.detectionLock);
    if (iscapture) {
        mark_device_removed(handle, current_audio.inputDevices, &current_audio.captureDevicesRemoved);
    } else {
        mark_device_removed(handle, current_audio.outputDevices, &current_audio.outputDevicesRemoved);
    }
    for (device_index = 0; device_index < SDL_arraysize(open_devices); device_index++)
    {
        device = open_devices[device_index];
        if (device != NULL && device->handle == handle)
        {
            SDL_OpenedAudioDeviceDisconnected(device);
            break;
        }
    }
    SDL_UnlockMutex(current_audio.detectionLock);

    current_audio.impl.FreeDeviceHandle(handle);
}

static int SDL_RunAudio ( void *  devicep )

static

Definition at line 688 of file SDL_audio.c.

References SDL_AudioDriverImpl::BeginLoopIteration, callback(), SDL_AudioSpec::callback, SDL_AudioDevice::callbackspec, device, SDL_AudioDevice::enabled, SDL_AudioSpec::freq, SDL_AudioDriverImpl::GetDeviceBuf, SDL_AudioDriver::impl, SDL_AudioDevice::iscapture, SDL_AudioDevice::mixer_lock, NULL, SDL_AudioDevice::paused, SDL_AudioDriverImpl::PlayDevice, SDL_AudioDriverImpl::PrepareToClose, SDL_AudioSpec::samples, SDL_assert, SDL_AtomicGet, SDL_AudioStreamAvailable, SDL_AudioStreamGet, SDL_AudioStreamPut, SDL_Delay, SDL_LockMutex, SDL_memset, SDL_SetThreadPriority, SDL_THREAD_PRIORITY_TIME_CRITICAL, SDL_ThreadID, SDL_UnlockMutex, SDL_AudioDevice::shutdown, SDL_AudioSpec::silence, SDL_AudioSpec::size, SDL_AudioDevice::spec, SDL_AudioDevice::stream, SDL_AudioDriverImpl::ThreadDeinit, SDL_AudioDevice::threadid, SDL_AudioDriverImpl::ThreadInit, SDL_AudioSpec::userdata, SDL_AudioDriverImpl::WaitDevice, and SDL_AudioDevice::work_buffer.

Referenced by open_audio_device().

{
    SDL_AudioDevice *device = (SDL_AudioDevice *) devicep;
    void *udata = device->callbackspec.userdata;
    SDL_AudioCallback callback = device->callbackspec.callback;
    int data_len = 0;
    Uint8 *data;

    SDL_assert(!device->iscapture);

    /* The audio mixing is always a high priority thread */
    SDL_SetThreadPriority(SDL_THREAD_PRIORITY_TIME_CRITICAL);

    /* Perform any thread setup */
    device->threadid = SDL_ThreadID();
    current_audio.impl.ThreadInit(device);

    /* Loop, filling the audio buffers */
    while (!SDL_AtomicGet(&device->shutdown)) {
        current_audio.impl.BeginLoopIteration(device);
        data_len = device->callbackspec.size;

        /* Fill the current buffer with sound */
        if (!device->stream && SDL_AtomicGet(&device->enabled)) {
            SDL_assert(data_len == device->spec.size);
            data = current_audio.impl.GetDeviceBuf(device);
        } else {
            /* if the device isn't enabled, we still write to the
               work_buffer, so the app's callback will fire with
               a regular frequency, in case they depend on that
               for timing or progress. They can use hotplug
               now to know if the device failed.
               Streaming playback uses work_buffer, too. */
            data = NULL;
        }

        if (data == NULL) {
            data = device->work_buffer;
        }

        /* !!! FIXME: this should be LockDevice. */
        SDL_LockMutex(device->mixer_lock);
        if (SDL_AtomicGet(&device->paused)) {
            SDL_memset(data, device->spec.silence, data_len);
        } else {
            callback(udata, data, data_len);
        }
        SDL_UnlockMutex(device->mixer_lock);

        if (device->stream) {
            /* Stream available audio to device, converting/resampling. */
            /* if this fails...oh well. We'll play silence here. */
            SDL_AudioStreamPut(device->stream, data, data_len);

            while (SDL_AudioStreamAvailable(device->stream) >= ((int) device->spec.size)) {
                int got;
                data = SDL_AtomicGet(&device->enabled) ? current_audio.impl.GetDeviceBuf(device) : NULL;
                got = SDL_AudioStreamGet(device->stream, data ? data : device->work_buffer, device->spec.size);
                SDL_assert((got < 0) || (got == device->spec.size));

                if (data == NULL) {  /* device is having issues... */
                    const Uint32 delay = ((device->spec.samples * 1000) / device->spec.freq);
                    SDL_Delay(delay);  /* wait for as long as this buffer would have played. Maybe device recovers later? */
                } else {
                    if (got != device->spec.size) {
                        SDL_memset(data, device->spec.silence, device->spec.size);
                    }
                    current_audio.impl.PlayDevice(device);
                    current_audio.impl.WaitDevice(device);
                }
            }
        } else if (data == device->work_buffer) {
            /* nothing to do; pause like we queued a buffer to play. */
            const Uint32 delay = ((device->spec.samples * 1000) / device->spec.freq);
            SDL_Delay(delay);
        } else {  /* writing directly to the device. */
            /* queue this buffer and wait for it to finish playing. */
            current_audio.impl.PlayDevice(device);
            current_audio.impl.WaitDevice(device);
        }
    }

    current_audio.impl.PrepareToClose(device);

    /* Wait for the audio to drain. */
    SDL_Delay(((device->spec.samples * 1000) / device->spec.freq) * 2);

    current_audio.impl.ThreadDeinit(device);

    return 0;
}

void SDL_UnlockAudio

(

void

)

Definition at line 1564 of file SDL_audio.c.

References SDL_UnlockAudioDevice.

{
    SDL_UnlockAudioDevice(1);
}

void SDL_UnlockAudioDevice

(

SDL_AudioDeviceID

devid

)

Definition at line 1554 of file SDL_audio.c.

References device, get_audio_device(), SDL_AudioDriver::impl, and SDL_AudioDriverImpl::UnlockDevice.

{
    /* Obtain a lock on the mixing buffers */
    SDL_AudioDevice *device = get_audio_device(devid);
    if (device) {
        current_audio.impl.UnlockDevice(device);
    }
}

Variable Documentation

const AudioBootStrap* const bootstrap[]

static

Definition at line 37 of file SDL_audio.c.

SDL_AudioDriver current_audio

static

Definition at line 33 of file SDL_audio.c.

int format_idx

static

Definition at line 1613 of file SDL_audio.c.

Referenced by SDL_FirstAudioFormat(), and SDL_NextAudioFormat().

int format_idx_sub

static

Definition at line 1614 of file SDL_audio.c.

SDL_AudioFormat format_list[NUM_FORMATS][NUM_FORMATS]

static

Initial value:

 {
    {AUDIO_U8, AUDIO_S8, AUDIO_S16LSB, AUDIO_S16MSB, AUDIO_U16LSB,
     AUDIO_U16MSB, AUDIO_S32LSB, AUDIO_S32MSB, AUDIO_F32LSB, AUDIO_F32MSB},
    {AUDIO_S8, AUDIO_U8, AUDIO_S16LSB, AUDIO_S16MSB, AUDIO_U16LSB,
     AUDIO_U16MSB, AUDIO_S32LSB, AUDIO_S32MSB, AUDIO_F32LSB, AUDIO_F32MSB},
    {AUDIO_S16LSB, AUDIO_S16MSB, AUDIO_U16LSB, AUDIO_U16MSB, AUDIO_S32LSB,
     AUDIO_S32MSB, AUDIO_F32LSB, AUDIO_F32MSB, AUDIO_U8, AUDIO_S8},
    {AUDIO_S16MSB, AUDIO_S16LSB, AUDIO_U16MSB, AUDIO_U16LSB, AUDIO_S32MSB,
     AUDIO_S32LSB, AUDIO_F32MSB, AUDIO_F32LSB, AUDIO_U8, AUDIO_S8},
    {AUDIO_U16LSB, AUDIO_U16MSB, AUDIO_S16LSB, AUDIO_S16MSB, AUDIO_S32LSB,
     AUDIO_S32MSB, AUDIO_F32LSB, AUDIO_F32MSB, AUDIO_U8, AUDIO_S8},
    {AUDIO_U16MSB, AUDIO_U16LSB, AUDIO_S16MSB, AUDIO_S16LSB, AUDIO_S32MSB,
     AUDIO_S32LSB, AUDIO_F32MSB, AUDIO_F32LSB, AUDIO_U8, AUDIO_S8},
    {AUDIO_S32LSB, AUDIO_S32MSB, AUDIO_F32LSB, AUDIO_F32MSB, AUDIO_S16LSB,
     AUDIO_S16MSB, AUDIO_U16LSB, AUDIO_U16MSB, AUDIO_U8, AUDIO_S8},
    {AUDIO_S32MSB, AUDIO_S32LSB, AUDIO_F32MSB, AUDIO_F32LSB, AUDIO_S16MSB,
     AUDIO_S16LSB, AUDIO_U16MSB, AUDIO_U16LSB, AUDIO_U8, AUDIO_S8},
    {AUDIO_F32LSB, AUDIO_F32MSB, AUDIO_S32LSB, AUDIO_S32MSB, AUDIO_S16LSB,
     AUDIO_S16MSB, AUDIO_U16LSB, AUDIO_U16MSB, AUDIO_U8, AUDIO_S8},
    {AUDIO_F32MSB, AUDIO_F32LSB, AUDIO_S32MSB, AUDIO_S32LSB, AUDIO_S16MSB,
     AUDIO_S16LSB, AUDIO_U16MSB, AUDIO_U16LSB, AUDIO_U8, AUDIO_S8},
}

Definition at line 1615 of file SDL_audio.c.

SDL_AudioDevice* open_devices[16]

static

Definition at line 34 of file SDL_audio.c.