Added audio device buffer queueing API.

--HG--
extra : rebase_source : a454256d88e413a4898b5005472625f755abfad4

src/audio/SDL_audio.c

@@ -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) {

src/audio/SDL_sysaudio.h

@@ -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;

src/dynapi/SDL_dynapi_overrides.h

@@ -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

src/dynapi/SDL_dynapi_procs.h

@@ -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),)