Merged 'default' into branch 'iOS-improvements'

include/SDL.h

@@ -25,41 +25,6 @@
  *  Main include header for the SDL library
  */
 
-/**
- *  \mainpage Simple DirectMedia Layer (SDL)
- *
- *  http://www.libsdl.org/
- *
- *  \section intro_sec Introduction
- *
- *  Simple DirectMedia Layer is a cross-platform development library designed
- *  to provide low level access to audio, keyboard, mouse, joystick, and
- *  graphics hardware via OpenGL and Direct3D. It is used by video playback
- *  software, emulators, and popular games including Valve's award winning
- *  catalog and many Humble Bundle games.
- *
- *  SDL officially supports Windows, Mac OS X, Linux, iOS, and Android.
- *  Support for other platforms may be found in the source code.
- *
- *  SDL is written in C, works natively with C++, and there are bindings 
- *  available for several other languages, including C# and Python.
- *
- *  This library is distributed under the zlib license, which can be found
- *  in the file "COPYING.txt".
- *
- *  The best way to learn how to use SDL is to check out the header files in
- *  the "include" subdirectory and the programs in the "test" subdirectory.
- *  The header files and test programs are well commented and always up to date.
- *  More documentation and FAQs are available online at:
- *      http://wiki.libsdl.org/
- *
- *  If you need help with the library, or just want to discuss SDL related
- *  issues, you can join the developers mailing list:
- *      http://www.libsdl.org/mailing-list.php
- *
- *  Enjoy!
- *      Sam Lantinga                (slouken@libsdl.org)
- */
 
 #ifndef _SDL_H
 #define _SDL_H

include/SDL_assert.h

@@ -141,16 +141,13 @@ extern DECLSPEC SDL_assert_state SDLCALL SDL_ReportAssertion(SDL_assert_data *,
 #define SDL_enabled_assert(condition) \
     do { \
         while ( !(condition) ) { \
-            static struct SDL_assert_data assert_data = { \
+            static struct SDL_assert_data sdl_assert_data = { \
                 0, 0, #condition, 0, 0, 0, 0 \
             }; \
-            const SDL_assert_state state = SDL_ReportAssertion(&assert_data, \
-                                                               SDL_FUNCTION, \
-                                                               SDL_FILE, \
-                                                               SDL_LINE); \
-            if (state == SDL_ASSERTION_RETRY) { \
+            const SDL_assert_state sdl_assert_state = SDL_ReportAssertion(&sdl_assert_data, SDL_FUNCTION, SDL_FILE, SDL_LINE); \
+            if (sdl_assert_state == SDL_ASSERTION_RETRY) { \
                 continue; /* go again. */ \
-            } else if (state == SDL_ASSERTION_BREAK) { \
+            } else if (sdl_assert_state == SDL_ASSERTION_BREAK) { \
                 SDL_TriggerBreakpoint(); \
             } \
             break; /* not retrying. */ \

include/SDL_audio.h

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