geemili
/
SDL
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Added audio device buffer queueing API.

main
Ryan C. Gordon 2014-07-22 21:41:49 -04:00
parent dfc7535ff7
commit f30e120aa9
9 changed files with 469 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.hgignore
View File

@ -73,6 +73,7 @@ test/Makefile
test/SDL2.dll
test/checkkeys
test/loopwave
test/loopwavequeue
test/testatomic
test/testaudioinfo
test/testautomation

107
include/SDL_audio.h
View File

@ -155,6 +155,9 @@ typedef Uint16 SDL_AudioFormat;
*
* Once the callback returns, the buffer will no longer be valid.
* Stereo samples are stored in a LRLRLR ordering.
*
* You can choose to avoid callbacks and use SDL_QueueAudio() instead, if
* you like. Just open your audio device with a NULL callback.
*/
typedef void (SDLCALL * SDL_AudioCallback) (void *userdata, Uint8 * stream,
int len);
@ -171,8 +174,8 @@ typedef struct SDL_AudioSpec
Uint16 samples; /**< Audio buffer size in samples (power of 2) */
Uint16 padding; /**< Necessary for some compile environments */
Uint32 size; /**< Audio buffer size in bytes (calculated) */
SDL_AudioCallback callback;
void *userdata;
SDL_AudioCallback callback; /**< Callback that feeds the audio device (NULL to use SDL_QueueAudio()). */
void *userdata; /**< Userdata passed to callback (ignored for NULL callbacks). */
} SDL_AudioSpec;
@ -273,9 +276,11 @@ extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
* 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.
* 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.
* - \c desired->userdata is passed as the first parameter to your callback
* function.
* 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 \c SDL_PauseAudio(0) when you are ready
@ -474,6 +479,100 @@ extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
SDL_AudioFormat format,
Uint32 len, int volume);
/**
* Queue more audio on non-callback 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.
*
* \param dev The device ID to which we will queue audio.
* \param data The data to queue to the device for later playback.
* \param len The number of bytes (not samples!) to which (data) points.
* \return zero on success, -1 on error.
*
* \sa SDL_GetQueuedAudioSize
* \sa SDL_ClearQueuedAudio
*/
extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *data, Uint32 len);
/**
* Get the number of bytes of still-queued audio.
*
* This is the number of bytes that have been queued for playback with
* SDL_QueueAudio(), but have not yet been sent to the hardware.
*
* 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.
*
* 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 use the audio callback or queue audio with SDL_QueueAudio(),
* but not both.
*
* You should not call SDL_LockAudio() on the device before querying; SDL
* handles locking internally for this function.
*
* \param dev The device ID of which we will query queued audio size.
* \return Number of bytes (not samples!) of queued audio.
*
* \sa SDL_QueueAudio
* \sa SDL_ClearQueuedAudio
*/
extern DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev);
/**
* Drop any queued audio data waiting to be sent to the hardware.
*
* Immediately after this call, SDL_GetQueuedAudioSize() will return 0 and
* the hardware will start playing silence if more audio isn't queued.
*
* 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 use the audio callback or queue audio with SDL_QueueAudio(),
* 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.
*
* \param dev The device ID of which to clear the audio queue.
*
* \sa SDL_QueueAudio
* \sa SDL_GetQueuedAudioSize
*/
extern DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev);
/**
* \name Audio lock functions
*

209
src/audio/SDL_audio.c
View File

@ -324,6 +324,181 @@ SDL_StreamDeinit(SDL_AudioStreamer * stream)
}
#endif
/* buffer queueing support... */
/* this expects that you managed thread safety elsewhere. */
static void
free_audio_queue(SDL_AudioBufferQueue *buffer)
{
while (buffer) {
SDL_AudioBufferQueue *next = buffer->next;
SDL_free(buffer);
buffer = next;
}
}
static void SDLCALL
SDL_BufferQueueDrainCallback(void *userdata, Uint8 *stream, int _len)
{
/* this function always holds the mixer lock before being called. */
Uint32 len = (Uint32) _len;
SDL_AudioDevice *device = (SDL_AudioDevice *) userdata;
SDL_AudioBufferQueue *buffer;
SDL_assert(device != NULL); /* this shouldn't ever happen, right?! */
SDL_assert(_len >= 0); /* this shouldn't ever happen, right?! */
while ((len > 0) && ((buffer = device->buffer_queue_head) != NULL)) {
const Uint32 avail = buffer->datalen - buffer->startpos;
const Uint32 cpy = SDL_min(len, avail);
SDL_assert(device->queued_bytes >= avail);
SDL_memcpy(stream, buffer->data + buffer->startpos, cpy);
buffer->startpos += cpy;
stream += cpy;
device->queued_bytes -= cpy;
len -= cpy;
if (buffer->startpos == buffer->datalen) { /* packet is done, put it in the pool. */
device->buffer_queue_head = buffer->next;
SDL_assert((buffer->next != NULL) || (buffer == device->buffer_queue_tail));
buffer->next = device->buffer_queue_pool;
device->buffer_queue_pool = buffer;
}
}
SDL_assert((device->buffer_queue_head != NULL) == (device->queued_bytes != 0));
if (len > 0) { /* fill any remaining space in the stream with silence. */
SDL_assert(device->buffer_queue_head == NULL);
SDL_memset(stream, device->spec.silence, len);
}
if (device->buffer_queue_head == NULL) {
device->buffer_queue_tail = NULL; /* in case we drained the queue entirely. */
}
}
int
SDL_QueueAudio(SDL_AudioDeviceID devid, const void *_data, Uint32 len)
{
SDL_AudioDevice *device = get_audio_device(devid);
const Uint8 *data = (const Uint8 *) _data;
SDL_AudioBufferQueue *orighead;
SDL_AudioBufferQueue *origtail;
Uint32 origlen;
Uint32 datalen;
if (!device) {
return -1; /* get_audio_device() will have set the error state */
}
if (device->spec.callback != SDL_BufferQueueDrainCallback) {
return SDL_SetError("Audio device has a callback, queueing not allowed");
}
current_audio.impl.LockDevice(device);
orighead = device->buffer_queue_head;
origtail = device->buffer_queue_tail;
origlen = origtail ? origtail->datalen : 0;
while (len > 0) {
SDL_AudioBufferQueue *packet = device->buffer_queue_tail;
SDL_assert(!packet || (packet->datalen <= SDL_AUDIOBUFFERQUEUE_PACKETLEN));
if (!packet || (packet->datalen >= SDL_AUDIOBUFFERQUEUE_PACKETLEN)) {
/* tail packet missing or completely full; we need a new packet. */
packet = device->buffer_queue_pool;
if (packet != NULL) {
/* we have one available in the pool. */
device->buffer_queue_pool = packet->next;
} else {
/* Have to allocate a new one! */
packet = (SDL_AudioBufferQueue *) SDL_malloc(sizeof (SDL_AudioBufferQueue));
if (packet == NULL) {
/* uhoh, reset so we've queued nothing new, free what we can. */
if (!origtail) {
packet = device->buffer_queue_head; /* whole queue. */
} else {
packet = origtail->next; /* what we added to existing queue. */
origtail->next = NULL;
origtail->datalen = origlen;
}
device->buffer_queue_head = orighead;
device->buffer_queue_tail = origtail;
device->buffer_queue_pool = NULL;
current_audio.impl.UnlockDevice(device);
free_audio_queue(packet); /* give back what we can. */
return SDL_OutOfMemory();
}
}
packet->datalen = 0;
packet->startpos = 0;
packet->next = NULL;
SDL_assert((device->buffer_queue_head != NULL) == (device->queued_bytes != 0));
if (device->buffer_queue_tail == NULL) {
device->buffer_queue_head = packet;
} else {
device->buffer_queue_tail->next = packet;
}
device->buffer_queue_tail = packet;
}
datalen = SDL_min(len, SDL_AUDIOBUFFERQUEUE_PACKETLEN - packet->datalen);
SDL_memcpy(packet->data + packet->datalen, data, datalen);
data += datalen;
len -= datalen;
packet->datalen += datalen;
device->queued_bytes += datalen;
}
current_audio.impl.UnlockDevice(device);
return 0;
}
Uint32
SDL_GetQueuedAudioSize(SDL_AudioDeviceID devid)
{
/* this happens to work for non-queueing devices, since we memset()
the device to zero at init time, and these devices should return 0. */
Uint32 retval = 0;
SDL_AudioDevice *device = get_audio_device(devid);
if (device) {
current_audio.impl.LockDevice(device);
retval = device->queued_bytes;
current_audio.impl.UnlockDevice(device);
}
return retval;
}
void
SDL_ClearQueuedAudio(SDL_AudioDeviceID devid)
{
SDL_AudioDevice *device = get_audio_device(devid);
SDL_AudioBufferQueue *buffer = NULL;
if (!device) {
return; /* nothing to do. */
}
/* Blank out the device and release the mutex. Free it afterwards. */
current_audio.impl.LockDevice(device);
buffer = device->buffer_queue_head;
device->buffer_queue_tail = NULL;
device->buffer_queue_head = NULL;
device->queued_bytes = 0;
current_audio.impl.UnlockDevice(device);
free_audio_queue(buffer);
}
#if defined(__ANDROID__)
#include <android/log.h>
#endif
@ -800,6 +975,10 @@ close_audio_device(SDL_AudioDevice * device)
current_audio.impl.CloseDevice(device);
device->opened = 0;
}
free_audio_queue(device->buffer_queue_head);
free_audio_queue(device->buffer_queue_pool);
SDL_FreeAudioMem(device);
}
@ -814,11 +993,6 @@ prepare_audiospec(const SDL_AudioSpec * orig, SDL_AudioSpec * prepared)
{
SDL_memcpy(prepared, orig, sizeof(SDL_AudioSpec));
if (orig->callback == NULL) {
SDL_SetError("SDL_OpenAudio() passed a NULL callback");
return 0;
}
if (orig->freq == 0) {
const char *env = SDL_getenv("SDL_AUDIO_FREQUENCY");
if ((!env) || ((prepared->freq = SDL_atoi(env)) == 0)) {
@ -871,7 +1045,6 @@ prepare_audiospec(const SDL_AudioSpec * orig, SDL_AudioSpec * prepared)
return 1;
}
static SDL_AudioDeviceID
open_audio_device(const char *devname, int iscapture,
const SDL_AudioSpec * desired, SDL_AudioSpec * obtained,
@ -950,7 +1123,7 @@ open_audio_device(const char *devname, int iscapture,
SDL_OutOfMemory();
return 0;
}
SDL_memset(device, '\0', sizeof(SDL_AudioDevice));
SDL_zerop(device);
device->spec = *obtained;
device->enabled = 1;
device->paused = 1;
@ -968,8 +1141,9 @@ open_audio_device(const char *devname, int iscapture,
/* force a device detection if we haven't done one yet. */
if ( ((iscapture) && (current_audio.inputDevices == NULL)) ||
((!iscapture) && (current_audio.outputDevices == NULL)) )
((!iscapture) && (current_audio.outputDevices == NULL)) ) {
SDL_GetNumAudioDevices(iscapture);
}
if (current_audio.impl.OpenDevice(device, devname, iscapture) < 0) {
close_audio_device(device);
@ -1043,6 +1217,25 @@ open_audio_device(const char *devname, int iscapture,
}
}
if (device->spec.callback == NULL) { /* use buffer queueing? */
/* pool a few packets to start. Enough for two callbacks. */
const int packetlen = SDL_AUDIOBUFFERQUEUE_PACKETLEN;
const int wantbytes = ((device->convert.needed) ? device->convert.len : device->spec.size) * 2;
const int wantpackets = (wantbytes / packetlen) + ((wantbytes % packetlen) ? packetlen : 0);
for (i = 0; i < wantpackets; i++) {
SDL_AudioBufferQueue *packet = (SDL_AudioBufferQueue *) SDL_malloc(sizeof (SDL_AudioBufferQueue));
if (packet) { /* don't care if this fails, we'll deal later. */
packet->datalen = 0;
packet->startpos = 0;
packet->next = device->buffer_queue_pool;
device->buffer_queue_pool = packet;
}
}
device->spec.callback = SDL_BufferQueueDrainCallback;
device->spec.userdata = device;
}
/* Find an available device ID and store the structure... */
for (id = min_id - 1; id < SDL_arraysize(open_devices); id++) {
if (open_devices[id] == NULL) {

26
src/audio/SDL_sysaudio.h
View File

@ -33,6 +33,26 @@ typedef struct SDL_AudioDevice SDL_AudioDevice;
/* Used by audio targets during DetectDevices() */
typedef void (*SDL_AddAudioDevice)(const char *name);
/* This is the size of a packet when using SDL_QueueAudio(). We allocate
these as necessary and pool them, under the assumption that we'll
eventually end up with a handful that keep recycling, meeting whatever
the app needs. We keep packing data tightly as more arrives to avoid
wasting space, and if we get a giant block of data, we'll split them
into multiple packets behind the scenes. My expectation is that most
apps will have 2-3 of these in the pool. 8k should cover most needs, but
if this is crippling for some embedded system, we can #ifdef this.
The system preallocates enough packets for 2 callbacks' worth of data. */
#define SDL_AUDIOBUFFERQUEUE_PACKETLEN (8 * 1024)
/* Used by apps that queue audio instead of using the callback. */
typedef struct SDL_AudioBufferQueue
{
Uint8 data[SDL_AUDIOBUFFERQUEUE_PACKETLEN]; /* packet data. */
Uint32 datalen; /* bytes currently in use in this packet. */
Uint32 startpos; /* bytes currently consumed in this packet. */
struct SDL_AudioBufferQueue *next; /* next item in linked list. */
} SDL_AudioBufferQueue;
typedef struct SDL_AudioDriverImpl
{
void (*DetectDevices) (int iscapture, SDL_AddAudioDevice addfn);
@ -119,6 +139,12 @@ struct SDL_AudioDevice
SDL_Thread *thread;
SDL_threadID threadid;
/* Queued buffers (if app not using callback). */
SDL_AudioBufferQueue *buffer_queue_head; /* device fed from here. */
SDL_AudioBufferQueue *buffer_queue_tail; /* queue fills to here. */
SDL_AudioBufferQueue *buffer_queue_pool; /* these are unused packets. */
Uint32 queued_bytes; /* number of bytes of audio data in the queue. */
/* * * */
/* Data private to this driver */
struct SDL_PrivateAudioData *hidden;

3
src/dynapi/SDL_dynapi_overrides.h
View File

@ -588,3 +588,6 @@
#define SDL_SetWindowHitTest SDL_SetWindowHitTest_REAL
#define SDL_GetGlobalMouseState SDL_GetGlobalMouseState_REAL
#define SDL_HasAVX2 SDL_HasAVX2_REAL
#define SDL_QueueAudio SDL_QueueAudio_REAL
#define SDL_GetQueuedAudioSize SDL_GetQueuedAudioSize_REAL
#define SDL_ClearQueuedAudio SDL_ClearQueuedAudio_REAL

3
src/dynapi/SDL_dynapi_procs.h
View File

@ -620,3 +620,6 @@ SDL_DYNAPI_PROC(int,SDL_CaptureMouse,(SDL_bool a),(a),return)
SDL_DYNAPI_PROC(int,SDL_SetWindowHitTest,(SDL_Window *a, SDL_HitTest b, void *c),(a,b,c),return)
SDL_DYNAPI_PROC(Uint32,SDL_GetGlobalMouseState,(int *a, int *b),(a,b),return)
SDL_DYNAPI_PROC(SDL_bool,SDL_HasAVX2,(void),(),return)
SDL_DYNAPI_PROC(int,SDL_QueueAudio,(SDL_AudioDeviceID a, const void *b, Uint32 c),(a,b,c),return)
SDL_DYNAPI_PROC(Uint32,SDL_GetQueuedAudioSize,(SDL_AudioDeviceID a),(a),return)
SDL_DYNAPI_PROC(void,SDL_ClearQueuedAudio,(SDL_AudioDeviceID a),(a),)

4
test/Makefile.in
View File

@ -10,6 +10,7 @@ LIBS = @LIBS@
TARGETS = \
checkkeys$(EXE) \
loopwave$(EXE) \
loopwavequeue$(EXE) \
testatomic$(EXE) \
testaudioinfo$(EXE) \
testautomation$(EXE) \
@ -71,6 +72,9 @@ checkkeys$(EXE): $(srcdir)/checkkeys.c
loopwave$(EXE): $(srcdir)/loopwave.c
$(CC) -o $@ $^ $(CFLAGS) $(LIBS)
loopwavequeue$(EXE): $(srcdir)/loopwavequeue.c
$(CC) -o $@ $^ $(CFLAGS) $(LIBS)
testresample$(EXE): $(srcdir)/testresample.c
$(CC) -o $@ $^ $(CFLAGS) $(LIBS)

1
test/README
View File

@ -3,6 +3,7 @@ These are test programs for the SDL library:
checkkeys Watch the key events to check the keyboard
loopwave Audio test -- loop playing a WAV file
loopwavequeue Audio test -- loop playing a WAV file with SDL_QueueAudio
testaudioinfo Lists audio device capabilities
testcdrom Sample audio CD control program
testerror Tests multi-threaded error handling

127
test/loopwavequeue.c Normal file
View File

@ -0,0 +1,127 @@
/*
Copyright (C) 1997-2014 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.
*/
/* Program to load a wave file and loop playing it using SDL sound queueing */
#include <stdio.h>
#include <stdlib.h>
#if HAVE_SIGNAL_H
#include <signal.h>
#endif
#include "SDL.h"
struct
{
SDL_AudioSpec spec;
Uint8 *sound; /* Pointer to wave data */
Uint32 soundlen; /* Length of wave data */
int soundpos; /* Current play position */
} wave;
/* Call this instead of exit(), so we can clean up SDL: atexit() is evil. */
static void
quit(int rc)
{
SDL_Quit();
exit(rc);
}
static int done = 0;
void
poked(int sig)
{
done = 1;
}
int
main(int argc, char *argv[])
{
int i;
char filename[4096];
/* Enable standard application logging */
SDL_LogSetPriority(SDL_LOG_CATEGORY_APPLICATION, SDL_LOG_PRIORITY_INFO);
/* Load the SDL library */
if (SDL_Init(SDL_INIT_AUDIO) < 0) {
SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Couldn't initialize SDL: %s\n", SDL_GetError());
return (1);
}
if (argc > 1) {
SDL_strlcpy(filename, argv[1], sizeof(filename));
} else {
SDL_strlcpy(filename, "sample.wav", sizeof(filename));
}
/* Load the wave file into memory */
if (SDL_LoadWAV(filename, &wave.spec, &wave.sound, &wave.soundlen) == NULL) {
SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Couldn't load %s: %s\n", filename, SDL_GetError());
quit(1);
}
wave.spec.callback = NULL; /* we'll push audio. */
#if HAVE_SIGNAL_H
/* Set the signals */
#ifdef SIGHUP
signal(SIGHUP, poked);
#endif
signal(SIGINT, poked);
#ifdef SIGQUIT
signal(SIGQUIT, poked);
#endif
signal(SIGTERM, poked);
#endif /* HAVE_SIGNAL_H */
/* Initialize fillerup() variables */
if (SDL_OpenAudio(&wave.spec, NULL) < 0) {
SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Couldn't open audio: %s\n", SDL_GetError());
SDL_FreeWAV(wave.sound);
quit(2);
}
/*static x[99999]; SDL_QueueAudio(1, x, sizeof (x));*/
/* Let the audio run */
SDL_PauseAudio(0);
/* Note that we stuff the entire audio buffer into the queue in one
shot. Most apps would want to feed it a little at a time, as it
plays, but we're going for simplicity here. */
while (!done && (SDL_GetAudioStatus() == SDL_AUDIO_PLAYING))
{
/* The device from SDL_OpenAudio() is always device #1. */
const Uint32 queued = SDL_GetQueuedAudioSize(1);
SDL_Log("Device has %u bytes queued.\n", (unsigned int) queued);
if (queued <= 8192) { /* time to requeue the whole thing? */
if (SDL_QueueAudio(1, wave.sound, wave.soundlen) == 0) {
SDL_Log("Device queued %u more bytes.\n", (unsigned int) wave.soundlen);
} else {
SDL_Log("Device FAILED to queue %u more bytes: %s\n", (unsigned int) wave.soundlen, SDL_GetError());
}
}
SDL_Delay(100); /* let it play for awhile. */
}
/* Clean up on signal */
SDL_CloseAudio();
SDL_FreeWAV(wave.sound);
SDL_Quit();
return 0;
}
/* vi: set ts=4 sw=4 expandtab: */