Merge the SDL3 audio subsystem redesign!

This rips up the entire SDL audio subsystem! While we still feed the audio device from a separate thread, the audio callback into the app is now gone a totally optional alternative.

Now the app will bind an SDL_AudioStream to a given device and feed data to it. As many streams as one likes can be bound to a device; SDL will mix them all into a single buffer and feed the device from there.

So not only does this function as a basic mixer, it also means that multiple device opens are handled seamlessly (so if you want to open the device for your game, but you also link to a library that provides VoIP and it wants to open the device separately, you don't have to worry about stepping on each other, or that the OS will fail to allow multiple opens of the same device, etc).

Merged from pull request #7704.

Fixes #7379.
Reference Issue #6889.
Reference Issue #6632.

VisualC/SDL/SDL.vcxproj

@@ -122,6 +122,7 @@
       <InlineFunctionExpansion>OnlyExplicitInline</InlineFunctionExpansion>
       <PrecompiledHeader>Use</PrecompiledHeader>
       <PrecompiledHeaderFile>SDL_internal.h</PrecompiledHeaderFile>
+      <MultiProcessorCompilation>true</MultiProcessorCompilation>
     </ClCompile>
     <ResourceCompile>
       <PreprocessorDefinitions>_DEBUG;%(PreprocessorDefinitions)</PreprocessorDefinitions>
@@ -153,6 +154,7 @@
       <InlineFunctionExpansion>OnlyExplicitInline</InlineFunctionExpansion>
       <PrecompiledHeader>Use</PrecompiledHeader>
       <PrecompiledHeaderFile>SDL_internal.h</PrecompiledHeaderFile>
+      <MultiProcessorCompilation>true</MultiProcessorCompilation>
     </ClCompile>
     <ResourceCompile>
       <PreprocessorDefinitions>_DEBUG;%(PreprocessorDefinitions)</PreprocessorDefinitions>
@@ -188,6 +190,7 @@
       <InlineFunctionExpansion>OnlyExplicitInline</InlineFunctionExpansion>
       <PrecompiledHeader>Use</PrecompiledHeader>
       <PrecompiledHeaderFile>SDL_internal.h</PrecompiledHeaderFile>
+      <MultiProcessorCompilation>true</MultiProcessorCompilation>
     </ClCompile>
     <ResourceCompile>
       <PreprocessorDefinitions>NDEBUG;%(PreprocessorDefinitions)</PreprocessorDefinitions>
@@ -220,6 +223,7 @@
       <InlineFunctionExpansion>OnlyExplicitInline</InlineFunctionExpansion>
       <PrecompiledHeader>Use</PrecompiledHeader>
       <PrecompiledHeaderFile>SDL_internal.h</PrecompiledHeaderFile>
+      <MultiProcessorCompilation>true</MultiProcessorCompilation>
     </ClCompile>
     <ResourceCompile>
       <PreprocessorDefinitions>NDEBUG;%(PreprocessorDefinitions)</PreprocessorDefinitions>
@@ -656,4 +660,4 @@
   <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
   <ImportGroup Label="ExtensionTargets">
   </ImportGroup>
-</Project>
+</Project>

VisualC/SDL_test/SDL_test.vcxproj

@@ -100,6 +100,7 @@
       <WarningLevel>Level3</WarningLevel>
       <DebugInformationFormat>OldStyle</DebugInformationFormat>
       <OmitDefaultLibName>true</OmitDefaultLibName>
+      <MultiProcessorCompilation>true</MultiProcessorCompilation>
     </ClCompile>
   </ItemDefinitionGroup>
   <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'">
@@ -116,6 +117,7 @@
       <WarningLevel>Level3</WarningLevel>
       <DebugInformationFormat>OldStyle</DebugInformationFormat>
       <OmitDefaultLibName>true</OmitDefaultLibName>
+      <MultiProcessorCompilation>true</MultiProcessorCompilation>
     </ClCompile>
   </ItemDefinitionGroup>
   <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">
@@ -134,6 +136,7 @@
       <WarningLevel>Level3</WarningLevel>
       <DebugInformationFormat>OldStyle</DebugInformationFormat>
       <OmitDefaultLibName>true</OmitDefaultLibName>
+      <MultiProcessorCompilation>true</MultiProcessorCompilation>
     </ClCompile>
   </ItemDefinitionGroup>
   <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">
@@ -150,6 +153,7 @@
       <WarningLevel>Level3</WarningLevel>
       <DebugInformationFormat>OldStyle</DebugInformationFormat>
       <OmitDefaultLibName>true</OmitDefaultLibName>
+      <MultiProcessorCompilation>true</MultiProcessorCompilation>
     </ClCompile>
   </ItemDefinitionGroup>
   <ItemGroup>
@@ -168,4 +172,4 @@
   <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
   <ImportGroup Label="ExtensionTargets">
   </ImportGroup>
-</Project>
+</Project>

android-project/app/src/main/java/org/libsdl/app/SDLAudioManager.java

@@ -21,8 +21,6 @@ public class SDLAudioManager {
     protected static AudioRecord mAudioRecord;
     protected static Context mContext;
 
-    private static final int[] NO_DEVICES = {};
-
     private static AudioDeviceCallback mAudioDeviceCallback;
 
     public static void initialize() {
@@ -36,7 +34,7 @@ public class SDLAudioManager {
                 @Override
                 public void onAudioDevicesAdded(AudioDeviceInfo[] addedDevices) {
                     for (AudioDeviceInfo deviceInfo : addedDevices) {
-                        addAudioDevice(deviceInfo.isSink(), deviceInfo.getId());
+                        addAudioDevice(deviceInfo.isSink(), deviceInfo.getProductName().toString(), deviceInfo.getId());
                     }
                 }
 
@@ -52,13 +50,10 @@ public class SDLAudioManager {
 
     public static void setContext(Context context) {
         mContext = context;
-        if (context != null) {
-            registerAudioDeviceCallback();
-        }
     }
 
     public static void release(Context context) {
-        unregisterAudioDeviceCallback(context);
+        // no-op atm
     }
 
     // Audio
@@ -311,62 +306,27 @@ public class SDLAudioManager {
         return null;
     }
 
-    private static void registerAudioDeviceCallback() {
-        if (Build.VERSION.SDK_INT >= 24 /* Android 7.0 (N) */) {
-            AudioManager audioManager = (AudioManager) mContext.getSystemService(Context.AUDIO_SERVICE);
-            audioManager.registerAudioDeviceCallback(mAudioDeviceCallback, null);
-        }
-    }
-
-    private static void unregisterAudioDeviceCallback(Context context) {
-        if (Build.VERSION.SDK_INT >= 24 /* Android 7.0 (N) */) {
-            AudioManager audioManager = (AudioManager) context.getSystemService(Context.AUDIO_SERVICE);
-            audioManager.unregisterAudioDeviceCallback(mAudioDeviceCallback);
-        }
-    }
-
-    private static int[] ArrayListToArray(ArrayList<Integer> integers)
-    {
-        int[] ret = new int[integers.size()];
-        for (int i=0; i < ret.length; i++) {
-            ret[i] = integers.get(i).intValue();
-        }
-        return ret;
-    }
-
-    /**
-     * This method is called by SDL using JNI.
-     */
-    public static int[] getAudioOutputDevices() {
+    public static void registerAudioDeviceCallback() {
         if (Build.VERSION.SDK_INT >= 24 /* Android 7.0 (N) */) {
             AudioManager audioManager = (AudioManager) mContext.getSystemService(Context.AUDIO_SERVICE);
-            ArrayList<Integer> arrlist = new ArrayList<Integer>();
+            // get an initial list now, before hotplug callbacks fire.
             for (AudioDeviceInfo dev : audioManager.getDevices(AudioManager.GET_DEVICES_OUTPUTS)) {
-                /* Device cannot be opened */
                 if (dev.getType() == AudioDeviceInfo.TYPE_TELEPHONY) {
-                    continue;
+                    continue;  // Device cannot be opened
                 }
-                arrlist.add(dev.getId());
+                addAudioDevice(dev.isSink(), dev.getProductName().toString(), dev.getId());
             }
-            return ArrayListToArray(arrlist);
-        } else {
-            return NO_DEVICES;
+            for (AudioDeviceInfo dev : audioManager.getDevices(AudioManager.GET_DEVICES_INPUTS)) {
+                addAudioDevice(dev.isSink(), dev.getProductName().toString(), dev.getId());
+            }
+            audioManager.registerAudioDeviceCallback(mAudioDeviceCallback, null);
         }
     }
 
-    /**
-     * This method is called by SDL using JNI.
-     */
-    public static int[] getAudioInputDevices() {
+    public static void unregisterAudioDeviceCallback() {
         if (Build.VERSION.SDK_INT >= 24 /* Android 7.0 (N) */) {
             AudioManager audioManager = (AudioManager) mContext.getSystemService(Context.AUDIO_SERVICE);
-            ArrayList<Integer> arrlist = new ArrayList<Integer>();
-            for (AudioDeviceInfo dev : audioManager.getDevices(AudioManager.GET_DEVICES_INPUTS)) {
-                arrlist.add(dev.getId());
-            }
-            return ArrayListToArray(arrlist);
-        } else {
-            return NO_DEVICES;
+            audioManager.unregisterAudioDeviceCallback(mAudioDeviceCallback);
         }
     }
 
@@ -535,6 +495,6 @@ public class SDLAudioManager {
 
     public static native void removeAudioDevice(boolean isCapture, int deviceId);
 
-    public static native void addAudioDevice(boolean isCapture, int deviceId);
+    public static native void addAudioDevice(boolean isCapture, String name, int deviceId);
 
 }

build-scripts/SDL_migration.cocci

@@ -308,10 +308,10 @@ expression e;
 + SDL_PauseAudioDevice(e)
 |
 - SDL_PauseAudioDevice(e, 0)
-+ SDL_PlayAudioDevice(e)
++ SDL_UnpauseAudioDevice(e)
 |
 - SDL_PauseAudioDevice(e, SDL_FALSE)
-+ SDL_PlayAudioDevice(e)
++ SDL_UnpauseAudioDevice(e)
 )
 
 @@
@@ -321,7 +321,7 @@ expression e, pause_on;
 + if (pause_on) {
 +    SDL_PauseAudioDevice(e);
 + } else {
-+    SDL_PlayAudioDevice(e);
++    SDL_UnpauseAudioDevice(e);
 + }
 
 

docs/README-migration.md

@@ -53,13 +53,128 @@ The following structures have been renamed:
 
 ## SDL_audio.h
 
+The audio subsystem in SDL3 is dramatically different than SDL2. The primary way to play audio is no longer an audio callback; instead you bind SDL_AudioStreams to devices.
+
+The SDL 1.2 audio compatibility API has also been removed, as it was a simplified version of the audio callback interface.
+
+SDL3 will not implicitly initialize the audio subsystem on your behalf if you open a device without doing so. Please explicitly call SDL_Init(SDL_INIT_AUDIO) at some point.
+
+If your app depends on the callback method, there is a similar approach you can take. But first, this is the new approach:
+
+In SDL2, you might have done something like this to play audio:
+
+```c
+    void SDLCALL MyAudioCallback(void *userdata, Uint8 * stream, int len)
+    {
+        /* calculate a little more audio here, maybe using `userdata`, write it to `stream` */
+    }
+
+    /* ...somewhere near startup... */
+    SDL_AudioSpec my_desired_audio_format;
+    SDL_zero(my_desired_audio_format);
+    my_desired_audio_format.format = AUDIO_S16;
+    my_desired_audio_format.channels = 2;
+    my_desired_audio_format.freq = 44100;
+    my_desired_audio_format.samples = 1024;
+    my_desired_audio_format.callback = MyAudioCallback;
+    my_desired_audio_format.userdata = &my_audio_callback_user_data;
+    SDL_AudioDeviceID my_audio_device = SDL_OpenAudioDevice(NULL, 0, &my_desired_audio_format, NULL, 0);
+    SDL_PauseAudioDevice(my_audio_device, 0);
+```
+
+in SDL3:
+
+```c
+    /* ...somewhere near startup... */
+    SDL_AudioSpec spec = { SDL_AUDIO_S16, 2, 44100 };
+    SDL_AudioDeviceID my_audio_device = SDL_OpenAudioDevice(SDL_AUDIO_DEVICE_DEFAULT_OUTPUT, &spec);
+    SDL_AudioSteam *stream = SDL_CreateAndBindAudioStream(my_audio_device, &spec);
+
+    /* ...in your main loop... */
+    /* calculate a little more audio into `buf`, add it to `stream` */
+    SDL_PutAudioStreamData(stream, buf, buflen);
+```
+
+If you absolutely require the callback method, SDL_AudioStreams can use a callback whenever more data is to be read from them, which can be used to simulate SDL2 semantics:
+
+```c
+    void SDLCALL MyAudioCallback(SDL_AudioStream *stream, int len, void *userdata)
+    {
+        /* calculate a little more audio here, maybe using `userdata`, write it to `stream` */
+        SDL_PutAudioStreamData(stream, newdata, len);
+    }
+
+    /* ...somewhere near startup... */
+    SDL_AudioSpec spec = { SDL_AUDIO_S16, 2, 44100 };
+    SDL_AudioDeviceID my_audio_device = SDL_OpenAudioDevice(SDL_AUDIO_DEVICE_DEFAULT_OUTPUT, &spec);
+    SDL_AudioSteam *stream = SDL_CreateAndBindAudioStream(my_audio_device, &spec);
+    SDL_SetAudioStreamGetCallback(stream, MyAudioCallback);
+
+    /* MyAudioCallback will be called whenever the device requests more audio data. */
+```
+
 SDL_AudioInit() and SDL_AudioQuit() have been removed. Instead you can call SDL_InitSubSystem() and SDL_QuitSubSystem() with SDL_INIT_AUDIO, which will properly refcount the subsystems. You can choose a specific audio driver using SDL_AUDIO_DRIVER hint.
 
-SDL_PauseAudioDevice() is only used to pause audio playback. Use SDL_PlayAudioDevice() to start playing audio.
+The `SDL_AUDIO_ALLOW_*` symbols have been removed; now one may request the format they desire from the audio device, but ultimately SDL_AudioStream will manage the difference. One can use SDL_GetAudioDeviceFormat() to see what the final format is, if any "allowed" changes should be accomodated by the app.
+
+SDL_AudioDeviceID now represents both an open audio device's handle (a "logical" device) and the instance ID that the hardware owns as long as it exists on the system (a "physical" device). The separation between device instances and device indexes is gone.
+
+Devices are opened by physical device instance ID, and a new logical instance ID is generated by the open operation; This allows any device to be opened multiple times, possibly by unrelated pieces of code. SDL will manage the logical devices to provide a single stream of audio to the physical device behind the scenes.
+
+Devices are not opened by an arbitrary string name anymore, but by device instance ID (or magic numbers to request a reasonable default, like a NULL string in SDL2). In SDL2, the string was used to open both a standard list of system devices, but also allowed for arbitrary devices, such as hostnames of network sound servers. In SDL3, many of the backends that supported arbitrary device names are obsolete and have been removed; of those that remain, arbitrary devices will be opened with a default device ID and an SDL_hint, so specific end-users can set an environment variable to fit their needs and apps don't have to concern themselves with it.
+
+Many functions that would accept a device index and an `iscapture` parameter now just take an SDL_AudioDeviceID, as they are unique across all devices, instead of separate indices into output and capture device lists.
+
+Rather than iterating over audio devices using a device index, there is a new function, SDL_GetAudioDevices(), to get the current list of devices, and new functions to get information about devices from their instance ID:
+
+```c
+{
+    if (SDL_InitSubSystem(SDL_INIT_AUDIO) == 0) {
+        int i, num_devices;
+        SDL_AudioDeviceID *devices = SDL_GetAudioDevices(/*iscapture=*/SDL_FALSE, &num_devices);
+        if (devices) {
+            for (i = 0; i < num_devices; ++i) {
+                SDL_AudioDeviceID instance_id = devices[i];
+                char *name = SDL_GetAudioDeviceName(instance_id);
+                SDL_Log("AudioDevice %" SDL_PRIu32 ": %s\n", instance_id, name);
+                SDL_free(name);
+            }
+            SDL_free(devices);
+        }
+        SDL_QuitSubSystem(SDL_INIT_AUDIO);
+    }
+}
+```
+
+SDL_LockAudioDevice() and SDL_UnlockAudioDevice() have been removed, since there is no callback in another thread to protect. SDL's audio subsystem and SDL_AudioStream maintain their own locks internally, so audio streams are safe to use from any thread. If the app assigns a callback to a specific stream, it can use the stream's lock through SDL_LockAudioStream() if necessary.
+
+SDL_PauseAudioDevice() no longer takes a second argument; it always pauses the device. To unpause, use SDL_UnpauseAudioDevice().
+
+Audio devices, opened by SDL_OpenAudioDevice(), no longer start in a paused state, as they don't begin processing audio until a stream is bound.
+
+SDL_GetAudioDeviceStatus() has been removed; there is now SDL_IsAudioDevicePaused().
+
+SDL_QueueAudio(), SDL_DequeueAudio, and SDL_ClearQueuedAudio and SDL_GetQueuedAudioSize() have been removed; an SDL_AudioStream bound to a device provides the exact same functionality.
+
+APIs that use channel counts used to use a Uint8 for the channel; now they use int.
+
+SDL_AudioSpec has been reduced; now it only holds format, channel, and sample rate. SDL_GetSilenceValueForFormat() can provide the information from the SDL_AudioSpec's `silence` field. The other SDL2 SDL_AudioSpec fields aren't relevant anymore.
+
+SDL_GetAudioDeviceSpec() is removed; use SDL_GetAudioDeviceFormat() instead.
+
+SDL_GetDefaultAudioInfo() is removed; SDL_GetAudioDeviceFormat() with SDL_AUDIO_DEVICE_DEFAULT_OUTPUT or SDL_AUDIO_DEVICE_DEFAULT_CAPTURE. There is no replacement for querying the default device name; the string is no longer used to open devices, and SDL3 will migrate between physical devices on the fly if the system default changes, so if you must show this to the user, a generic name like "System default" is recommended.
+
+SDL_MixAudio() has been removed, as it relied on legacy SDL 1.2 quirks; SDL_MixAudioFormat() remains and offers the same functionality.
+
+SDL_AudioInit() and SDL_AudioQuit() have been removed. Instead you can call SDL_InitSubSystem() and SDL_QuitSubSystem() with SDL_INIT_AUDIO, which will properly refcount the subsystems. You can choose a specific audio driver using SDL_AUDIO_DRIVER hint.
 
 SDL_FreeWAV has been removed and calls can be replaced with SDL_free.
 
-SDL_AudioCVT interface is removed, SDL_AudioStream interface or SDL_ConvertAudioSamples() helper function can be used.
+SDL_LoadWAV() is a proper function now and no longer a macro (but offers the same functionality otherwise).
+
+SDL_LoadWAV_RW() and SDL_LoadWAV() return an int now: zero on success, -1 on error, like most of SDL. They no longer return a pointer to an SDL_AudioSpec.
+
+SDL_AudioCVT interface has been removed, the SDL_AudioStream interface (for audio supplied in pieces) or the new SDL_ConvertAudioSamples() function (for converting a complete audio buffer in one call) can be used instead.
 
 Code that used to look like this:
 ```c
@@ -75,8 +190,9 @@ should be changed to:
 ```c
     Uint8 *dst_data = NULL;
     int dst_len = 0;
-    if (SDL_ConvertAudioSamples(src_format, src_channels, src_rate, src_data, src_len
-                                dst_format, dst_channels, dst_rate, &dst_data, &dst_len) < 0) {
+    const SDL_AudioSpec src_spec = { src_format, src_channels, src_rate };
+    const SDL_AudioSpec dst_spec = { dst_format, dst_channels, dst_rate };
+    if (SDL_ConvertAudioSamples(&src_spec, src_data, src_len, &dst_spec, &dst_data, &dst_len) < 0) {
         /* error */
     }
     do_something(dst_data, dst_len);
@@ -103,9 +219,13 @@ If you need to convert U16 audio data to a still-supported format at runtime, th
     }
 ```
 
-In SDL2, SDL_AudioStream would convert/resample audio data during input (via SDL_AudioStreamPut). In SDL3, it does this work when requesting audio (via SDL_GetAudioStreamData, which would have been SDL_AudioStreamPut in SDL2. The way you use an AudioStream is roughly the same, just be aware that the workload moved to a different phase.
+All remaining `AUDIO_*` symbols have been renamed to `SDL_AUDIO_*` for API consistency, but othewise are identical in value and usage.
+
+In SDL2, SDL_AudioStream would convert/resample audio data during input (via SDL_AudioStreamPut). In SDL3, it does this work when requesting audio (via SDL_GetAudioStreamData, which would have been SDL_AudioStreamGet in SDL2). The way you use an AudioStream is roughly the same, just be aware that the workload moved to a different phase.
+
 In SDL2, SDL_AudioStreamAvailable() returns 0 if passed a NULL stream. In SDL3, the equivalent SDL_GetAudioStreamAvailable() call returns -1 and sets an error string, which matches other audiostream APIs' behavior.
 
+In SDL2, SDL_AUDIODEVICEREMOVED events would fire for open devices with the `which` field set to the SDL_AudioDeviceID of the lost device, and in later SDL2 releases, would also fire this event with a `which` field of zero for unopened devices, to signify that the app might want to refresh the available device list. In SDL3, this event works the same, except it won't ever fire with a zero; in this case it'll return the physical device's SDL_AudioDeviceID. Any still-open SDL_AudioDeviceIDs generated from this device with SDL_OpenAudioDevice() will also fire a separate event.
 
 The following functions have been renamed:
 * SDL_AudioStreamAvailable() => SDL_GetAudioStreamAvailable()
@@ -118,17 +238,25 @@ The following functions have been renamed:
 
 
 The following functions have been removed:
+* SDL_GetNumAudioDevices()
+* SDL_GetAudioDeviceSpec()
 * SDL_ConvertAudio()
 * SDL_BuildAudioCVT()
 * SDL_OpenAudio()
 * SDL_CloseAudio()
 * SDL_PauseAudio()
 * SDL_GetAudioStatus()
+* SDL_GetAudioDeviceStatus()
+* SDL_GetDefaultAudioInfo()
 * SDL_LockAudio()
+* SDL_LockAudioDevice()
 * SDL_UnlockAudio()
+* SDL_UnlockAudioDevice()
 * SDL_MixAudio()
-
-Use the SDL_AudioDevice functions instead.
+* SDL_QueueAudio()
+* SDL_DequeueAudio()
+* SDL_ClearAudioQueue()
+* SDL_GetQueuedAudioSize()
 
 The following symbols have been renamed:
 * AUDIO_F32 => SDL_AUDIO_F32

include/SDL3/SDL_audio.h

@@ -19,12 +19,10 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
-/* !!! FIXME: several functions in here need Doxygen comments. */
-
 /**
  *  \file SDL_audio.h
  *
- *  \brief Access to the raw audio mixing buffer for the SDL library.
+ *  \brief Audio functionality for the SDL library.
  */
 
 #ifndef SDL_audio_h_
@@ -43,6 +41,17 @@
 extern "C" {
 #endif
 
+/*
+ *  For multi-channel audio, the default SDL channel mapping is:
+ *  2:  FL  FR                          (stereo)
+ *  3:  FL  FR LFE                      (2.1 surround)
+ *  4:  FL  FR  BL  BR                  (quad)
+ *  5:  FL  FR LFE  BL  BR              (4.1 surround)
+ *  6:  FL  FR  FC LFE  SL  SR          (5.1 surround - last two can also be BL BR)
+ *  7:  FL  FR  FC LFE  BC  SL  SR      (6.1 surround)
+ *  8:  FL  FR  FC LFE  BL  BR  SL  SR  (7.1 surround)
+ */
+
 /**
  *  \brief Audio format flags.
  *
@@ -128,63 +137,37 @@ typedef Uint16 SDL_AudioFormat;
 #endif
 /* @} */
 
-/**
- *  \name Allow change flags
- *
- *  Which audio format changes are allowed when opening a device.
- */
-/* @{ */
-#define SDL_AUDIO_ALLOW_FREQUENCY_CHANGE    0x00000001
-#define SDL_AUDIO_ALLOW_FORMAT_CHANGE       0x00000002
-#define SDL_AUDIO_ALLOW_CHANNELS_CHANGE     0x00000004
-#define SDL_AUDIO_ALLOW_SAMPLES_CHANGE      0x00000008
-#define SDL_AUDIO_ALLOW_ANY_CHANGE          (SDL_AUDIO_ALLOW_FREQUENCY_CHANGE|SDL_AUDIO_ALLOW_FORMAT_CHANGE|SDL_AUDIO_ALLOW_CHANNELS_CHANGE|SDL_AUDIO_ALLOW_SAMPLES_CHANGE)
-/* @} */
-
 /* @} *//* Audio flags */
 
 /**
- *  This function is called when the audio device needs more data.
- *
- *  \param userdata An application-specific parameter saved in
- *                  the SDL_AudioSpec structure
- *  \param stream A pointer to the audio data buffer.
- *  \param len    The length of that buffer in bytes.
- *
- *  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.
+ * SDL Audio Device instance IDs.
  */
-typedef void (SDLCALL * SDL_AudioCallback) (void *userdata, Uint8 * stream,
-                                            int len);
+typedef Uint32 SDL_AudioDeviceID;
+
+#define SDL_AUDIO_DEVICE_DEFAULT_OUTPUT ((SDL_AudioDeviceID) 0xFFFFFFFF)
+#define SDL_AUDIO_DEVICE_DEFAULT_CAPTURE ((SDL_AudioDeviceID) 0xFFFFFFFE)
 
-/**
- *  The calculated values in this structure are calculated by SDL_OpenAudioDevice().
- *
- *  For multi-channel audio, the default SDL channel mapping is:
- *  2:  FL  FR                          (stereo)
- *  3:  FL  FR LFE                      (2.1 surround)
- *  4:  FL  FR  BL  BR                  (quad)
- *  5:  FL  FR LFE  BL  BR              (4.1 surround)
- *  6:  FL  FR  FC LFE  SL  SR          (5.1 surround - last two can also be BL BR)
- *  7:  FL  FR  FC LFE  BC  SL  SR      (6.1 surround)
- *  8:  FL  FR  FC LFE  BL  BR  SL  SR  (7.1 surround)
- */
 typedef struct SDL_AudioSpec
 {
-    int freq;                   /**< DSP frequency -- samples per second */
     SDL_AudioFormat format;     /**< Audio data format */
-    Uint8 channels;             /**< Number of channels: 1 mono, 2 stereo */
-    Uint8 silence;              /**< Audio buffer silence value (calculated) */
-    Uint16 samples;             /**< Audio buffer size in sample FRAMES (total samples divided by channel count) */
-    Uint16 padding;             /**< Necessary for some compile environments */
-    Uint32 size;                /**< Audio buffer size in bytes (calculated) */
-    SDL_AudioCallback callback; /**< Callback that feeds the audio device (NULL to use SDL_QueueAudio()). */
-    void *userdata;             /**< Userdata passed to callback (ignored for NULL callbacks). */
+    int channels;               /**< Number of channels: 1 mono, 2 stereo, etc */
+    int freq;                   /**< sample rate: sample frames per second */
 } SDL_AudioSpec;
 
+/* SDL_AudioStream is an audio conversion interface.
+    - It can handle resampling data in chunks without generating
+      artifacts, when it doesn't have the complete buffer available.
+    - It can handle incoming data in any variable size.
+    - It can handle input/output format changes on the fly.
+    - You push data as you have it, and pull it when you need it
+    - It can also function as a basic audio data queue even if you
+      just have sound that needs to pass from one place to another.
+    - You can hook callbacks up to them when more data is added or
+      requested, to manage data on-the-fly.
+ */
+struct SDL_AudioStream;  /* this is opaque to the outside world. */
+typedef struct SDL_AudioStream SDL_AudioStream;
+
 
 /* Function prototypes */
 
@@ -211,6 +194,8 @@ typedef struct SDL_AudioSpec
  *
  * \returns the number of built-in audio drivers.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_GetAudioDriver
@@ -233,6 +218,8 @@ extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
  * \returns the name of the audio driver at the requested index, or NULL if an
  *          invalid index was specified.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_GetNumAudioDrivers
@@ -252,454 +239,408 @@ extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index);
  * \returns the name of the current audio driver or NULL if no driver has been
  *          initialized.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
 
 /**
- *  SDL Audio Device IDs.
- */
-typedef Uint32 SDL_AudioDeviceID;
-
-/**
- * Get the number of built-in audio devices.
+ * Get a list of currently-connected audio output devices.
  *
- * This function is only valid after successfully initializing the audio
- * subsystem.
+ * This returns of list of available devices that play sound, perhaps
+ * to speakers or headphones ("output" devices). If you want devices
+ * that record audio, like a microphone ("capture" devices), use
+ * SDL_GetAudioCaptureDevices() instead.
  *
- * Note that audio capture support is not implemented as of SDL 2.0.4, so the
- * `iscapture` parameter is for future expansion and should always be zero for
- * now.
+ * This only returns a list of physical devices; it will not have any
+ * device IDs returned by SDL_OpenAudioDevice().
  *
- * This function will return -1 if an explicit list of devices can't be
- * determined. Returning -1 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 in
- * SDL_OpenAudioDevice().
+ * \param count a pointer filled in with the number of devices returned
+ * \returns a 0 terminated array of device instance IDs which should be
+ *          freed with SDL_free(), or NULL on error; call SDL_GetError() for
+ *          more details.
  *
- * 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()).
+ * \threadsafety It is safe to call this function from any thread.
  *
- * This function may trigger a complete redetect of available hardware. It
- * should not be called for each iteration of a loop, but rather once at the
- * start of a loop:
+ * \since This function is available since SDL 3.0.0.
  *
- * ```c
- * // Don't do this:
- * for (int i = 0; i < SDL_GetNumAudioDevices(0); i++)
+ * \sa SDL_OpenAudioDevice
+ * \sa SDL_GetAudioCaptureDevices
+ */
+extern DECLSPEC SDL_AudioDeviceID *SDLCALL SDL_GetAudioOutputDevices(int *count);
+
+/**
+ * Get a list of currently-connected audio capture devices.
  *
- * // do this instead:
- * const int count = SDL_GetNumAudioDevices(0);
- * for (int i = 0; i < count; ++i) { do_something_here(); }
- * ```
+ * This returns of list of available devices that record audio, like a
+ * microphone ("capture" devices). If you want devices
+ * that play sound, perhaps to speakers or headphones ("output" devices),
+ * use SDL_GetAudioOutputDevices() instead.
  *
- * \param iscapture zero to request playback devices, non-zero to request
- *                  recording devices
- * \returns the number of available devices exposed by the current driver or
- *          -1 if an explicit list of devices can't be determined. A return
- *          value of -1 does not necessarily mean an error condition.
+ * This only returns a list of physical devices; it will not have any
+ * device IDs returned by SDL_OpenAudioDevice().
+ *
+ * \param count a pointer filled in with the number of devices returned
+ * \returns a 0 terminated array of device instance IDs which should be
+ *          freed with SDL_free(), or NULL on error; call SDL_GetError() for
+ *          more details.
+ *
+ * \threadsafety It is safe to call this function from any thread.
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_GetAudioDeviceName
  * \sa SDL_OpenAudioDevice
+ * \sa SDL_GetAudioOutputDevices
  */
-extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture);
+extern DECLSPEC SDL_AudioDeviceID *SDLCALL SDL_GetAudioCaptureDevices(int *count);
 
 /**
  * Get the human-readable name of a specific audio device.
  *
- * This function is only valid after successfully initializing the audio
- * subsystem. The values returned by this function reflect the latest call to
- * SDL_GetNumAudioDevices(); re-call that function to redetect available
- * hardware.
+ * The string returned by this function is UTF-8 encoded. The caller should
+ * call SDL_free on the return value when done with it.
  *
- * 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 are called.
+ * \param devid the instance ID of the device to query.
+ * \returns the name of the audio device, or NULL on error.
  *
- * \param index the index of the audio device; valid values range from 0 to
- *              SDL_GetNumAudioDevices() - 1
- * \param iscapture non-zero to query the list of recording devices, zero to
- *                  query the list of output devices.
- * \returns the name of the audio device at the requested index, or NULL on
- *          error.
+ * \threadsafety It is safe to call this function from any thread.
  *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_GetNumAudioDevices
  * \sa SDL_GetDefaultAudioInfo
  */
-extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index,
-                                                           int iscapture);
+extern DECLSPEC char *SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceID devid);
 
 /**
- * Get the preferred audio format of a specific audio device.
+ * Get the current audio format of a specific audio device.
  *
- * This function is only valid after a successfully initializing the audio
- * subsystem. The values returned by this function reflect the latest call to
- * SDL_GetNumAudioDevices(); re-call that function to redetect available
- * hardware.
+ * For an opened device, this will report the format the device is
+ * currently using. If the device isn't yet opened, this will report
+ * the device's preferred format (or a reasonable default if this
+ * can't be determined).
  *
- * `spec` will be filled with the sample rate, sample format, and channel
- * count.
+ * You may also specify SDL_AUDIO_DEVICE_DEFAULT_OUTPUT or
+ * SDL_AUDIO_DEVICE_DEFAULT_CAPTURE here, which is useful for getting
+ * a reasonable recommendation before opening the system-recommended
+ * default device.
  *
- * \param index the index of the audio device; valid values range from 0 to
- *              SDL_GetNumAudioDevices() - 1
- * \param iscapture non-zero to query the list of recording devices, zero to
- *                  query the list of output devices.
- * \param spec The SDL_AudioSpec to be initialized by this function.
+ * \param devid the instance ID of the device to query.
+ * \param spec On return, will be filled with device details.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
- * \since This function is available since SDL 3.0.0.
+ * \threadsafety It is safe to call this function from any thread.
  *
- * \sa SDL_GetNumAudioDevices
- * \sa SDL_GetDefaultAudioInfo
+ * \since This function is available since SDL 3.0.0.
  */
-extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
-                                                   int iscapture,
-                                                   SDL_AudioSpec *spec);
+extern DECLSPEC int SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec);
 
 
 /**
- * Get the name and preferred format of the default audio device.
- *
- * Some (but not all!) platforms have an isolated mechanism to get information
- * about the "default" device. This can actually be a completely different
- * device that's not in the list you get from SDL_GetAudioDeviceSpec(). It can
- * even be a network address! (This is discussed in SDL_OpenAudioDevice().)
- *
- * As a result, this call is not guaranteed to be performant, as it can query
- * the sound server directly every time, unlike the other query functions. You
- * should call this function sparingly!
- *
- * `spec` will be filled with the sample rate, sample format, and channel
- * count, if a default device exists on the system. If `name` is provided,
- * will be filled with either a dynamically-allocated UTF-8 string or NULL.
- *
- * \param name A pointer to be filled with the name of the default device (can
- *             be NULL). Please call SDL_free() when you are done with this
- *             pointer!
- * \param spec The SDL_AudioSpec to be initialized by this function.
- * \param iscapture non-zero to query the default recording device, zero to
- *                  query the default output device.
- * \returns 0 on success or a negative error code on failure; call
- *          SDL_GetError() for more information.
+ * Open a specific audio device.
+ *
+ * You can open both output and capture devices through this function.
+ * Output devices will take data from bound audio streams, mix it, and
+ * send it to the hardware. Capture devices will feed any bound audio
+ * streams with a copy of any incoming data.
+ *
+ * An opened audio device starts out with no audio streams bound. To
+ * start audio playing, bind a stream and supply audio data to it. Unlike
+ * SDL2, there is no audio callback; you only bind audio streams and
+ * make sure they have data flowing into them (although, as an optional
+ * feature, each audio stream may have its own callback, which can be
+ * used to simulate SDL2's semantics).
+ *
+ * If you don't care about opening a specific device, pass a `devid`
+ * of either `SDL_AUDIO_DEVICE_DEFAULT_OUTPUT` or
+ * `SDL_AUDIO_DEVICE_DEFAULT_CAPTURE`. In this case, SDL will try to
+ * pick the most reasonable default, and may also switch between
+ * physical devices seamlessly later, if the most reasonable default
+ * changes during the lifetime of this opened device (user changed
+ * the default in the OS's system preferences, the default got
+ * unplugged so the system jumped to a new default, the user plugged
+ * in headphones on a mobile device, etc). Unless you have a good
+ * reason to choose a specific device, this is probably what you want.
+ *
+ * You may request a specific format for the audio device, but there is
+ * no promise the device will honor that request for several reasons. As
+ * such, it's only meant to be a hint as to what data your app will
+ * provide. Audio streams will accept data in whatever format you specify and
+ * manage conversion for you as appropriate. SDL_GetAudioDeviceFormat can
+ * tell you the preferred format for the device before opening and the
+ * actual format the device is using after opening.
+ *
+ * It's legal to open the same device ID more than once; each successful
+ * open will generate a new logical SDL_AudioDeviceID that is managed
+ * separately from others on the same physical device. This allows
+ * libraries to open a device separately from the main app and bind its own
+ * streams without conflicting.
+ *
+ * It is also legal to open a device ID returned by a previous call to
+ * this function; doing so just creates another logical device on the same
+ * physical device. This may be useful for making logical groupings of
+ * audio streams.
+ *
+ * This function returns the opened device ID on success. This is a new,
+ * unique SDL_AudioDeviceID that represents a logical device.
+ *
+ * Some backends might offer arbitrary devices (for example, a networked
+ * audio protocol that can connect to an arbitrary server). For these, as
+ * a change from SDL2, you should open a default device ID and use an SDL
+ * hint to specify the target if you care, or otherwise let the backend
+ * figure out a reasonable default. Most backends don't offer anything like
+ * this, and often this would be an end user setting an environment
+ * variable for their custom need, and not something an application should
+ * specifically manage.
+ *
+ * When done with an audio device, possibly at the end of the app's life,
+ * one should call SDL_CloseAudioDevice() on the returned device id.
+ *
+ * \param devid the device instance id to open, or SDL_AUDIO_DEVICE_DEFAULT_OUTPUT or
+ *              SDL_AUDIO_DEVICE_DEFAULT_CAPTURE for the most reasonable default device.
+ * \param spec the requested device configuration. Can be NULL to use reasonable defaults.
+ * \returns The device ID on success, 0 on error; call SDL_GetError() for more information.
+ *
+ * \threadsafety It is safe to call this function from any thread.
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_GetAudioDeviceName
- * \sa SDL_GetAudioDeviceSpec
- * \sa SDL_OpenAudioDevice
+ * \sa SDL_CloseAudioDevice
+ * \sa SDL_GetAudioDeviceFormat
  */
-extern DECLSPEC int SDLCALL SDL_GetDefaultAudioInfo(char **name,
-                                                    SDL_AudioSpec *spec,
-                                                    int iscapture);
-
+extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec);
 
 /**
- * Open a specific audio device.
+ * Use this function to pause audio playback on a specified device.
+ *
+ * This function pauses audio processing for a given device. Any bound
+ * audio streams will not progress, and no audio will be generated.
+ * Pausing one device does not prevent other unpaused devices from running.
  *
- * Passing in a `device` name of NULL requests the most reasonable default.
- * 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.
- *
- * An opened audio device starts out paused, and should be enabled for playing
- * by calling SDL_PlayAudioDevice(devid) 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.
- *
- * The audio callback runs in a separate thread in most cases; you can prevent
- * race conditions between your callback and other threads without fully
- * pausing playback with SDL_LockAudioDevice(). For more information about the
- * callback, see SDL_AudioSpec.
- *
- * Managing the audio spec via 'desired' and 'obtained':
- *
- * When filling in the desired audio spec structure:
- *
- * - `desired->freq` should be the frequency in sample-frames-per-second (Hz).
- * - `desired->format` should be the audio format (`SDL_AUDIO_S16SYS`, etc).
- * - `desired->samples` is the desired size of the audio buffer, in _sample
- *   frames_ (with stereo output, two samples--left and right--would make a
- *   single sample frame). 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 reduce latency, but can
- *   lead to underflow if the application is doing heavy processing and cannot
- *   fill the audio buffer in time. Note that the number of sample frames is
- *   directly related to time by the following formula: `ms =
- *   (sampleframes*1000)/freq`
- * - `desired->size` is the size in _bytes_ of the audio buffer, and is
- *   calculated by SDL_OpenAudioDevice(). You don't initialize this.
- * - `desired->silence` is the value used to set the buffer to silence, and is
- *   calculated by SDL_OpenAudioDevice(). You don't initialize this.
- * - `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_LockAudioDevice() and
- *   SDL_UnlockAudioDevice() 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.
- *
- * `allowed_changes` can have the following flags OR'd together:
- *
- * - `SDL_AUDIO_ALLOW_FREQUENCY_CHANGE`
- * - `SDL_AUDIO_ALLOW_FORMAT_CHANGE`
- * - `SDL_AUDIO_ALLOW_CHANNELS_CHANGE`
- * - `SDL_AUDIO_ALLOW_SAMPLES_CHANGE`
- * - `SDL_AUDIO_ALLOW_ANY_CHANGE`
- *
- * These flags specify how SDL should behave when a device cannot offer a
- * specific feature. If the application requests a feature that the hardware
- * doesn't offer, SDL will always try to get the closest equivalent.
- *
- * For example, if you ask for float32 audio format, but the sound card only
- * supports int16, SDL will set the hardware to int16. If you had set
- * SDL_AUDIO_ALLOW_FORMAT_CHANGE, SDL will change the format in the `obtained`
- * structure. If that flag was *not* set, SDL will prepare to convert your
- * callback's float32 audio to int16 before feeding it to the hardware and
- * will keep the originally requested format in the `obtained` structure.
- *
- * The resulting audio specs, varying depending on hardware and on what
- * changes were allowed, will then be written back to `obtained`.
- *
- * If your application can only handle one specific data format, pass a zero
- * for `allowed_changes` and let SDL transparently handle any differences.
- *
- * \param device a UTF-8 string reported by SDL_GetAudioDeviceName() or a
- *               driver-specific name as appropriate. NULL requests the most
- *               reasonable default device.
- * \param iscapture non-zero to specify a device should be opened for
- *                  recording, not playback
- * \param desired an SDL_AudioSpec structure representing the desired output
- *                format
- * \param obtained an SDL_AudioSpec structure filled in with the actual output
- *                 format
- * \param allowed_changes 0, or one or more flags OR'd together
- * \returns a valid device ID that is > 0 on success or 0 on failure; call
+ * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app
+ * has to bind a stream before any audio will flow. Pausing a paused
+ * device is a legal no-op.
+ *
+ * Pausing a device can be useful to halt all audio without unbinding all
+ * the audio streams. This might be useful while a game is paused, or
+ * a level is loading, etc.
+ *
+ * Physical devices can not be paused or unpaused, only logical devices
+ * created through SDL_OpenAudioDevice() can be.
+ *
+ * \param dev a device opened by SDL_OpenAudioDevice()
+ * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
- *          For compatibility with SDL 1.2, this will never return 1, since
- *          SDL reserves that ID for the legacy SDL_OpenAudio() function.
+ * \threadsafety It is safe to call this function from any thread.
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_CloseAudioDevice
- * \sa SDL_GetAudioDeviceName
- * \sa SDL_LockAudioDevice
- * \sa SDL_PlayAudioDevice
- * \sa SDL_PauseAudioDevice
- * \sa SDL_UnlockAudioDevice
+ * \sa SDL_UnpauseAudioDevice
+ * \sa SDL_IsAudioDevicePaused
  */
-extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(
-                                                  const char *device,
-                                                  int iscapture,
-                                                  const SDL_AudioSpec *desired,
-                                                  SDL_AudioSpec *obtained,
-                                                  int allowed_changes);
-
-
+extern DECLSPEC int SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev);
 
 /**
- *  \name Audio state
+ * Use this function to unpause audio playback on a specified device.
+ *
+ * This function unpauses audio processing for a given device that has
+ * previously been paused with SDL_PauseAudioDevice(). Once unpaused, any
+ * bound audio streams will begin to progress again, and audio can be
+ * generated.
+ *
+ * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app
+ * has to bind a stream before any audio will flow. Unpausing an unpaused
+ * device is a legal no-op.
+ *
+ * Physical devices can not be paused or unpaused, only logical devices
+ * created through SDL_OpenAudioDevice() can be.
  *
- *  Get the current audio state.
+ * \param dev a device opened by SDL_OpenAudioDevice()
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_UnpauseAudioDevice
+ * \sa SDL_IsAudioDevicePaused
  */
-/* @{ */
-typedef enum
-{
-    SDL_AUDIO_STOPPED = 0,
-    SDL_AUDIO_PLAYING,
-    SDL_AUDIO_PAUSED
-} SDL_AudioStatus;
+extern DECLSPEC int SDLCALL SDL_UnpauseAudioDevice(SDL_AudioDeviceID dev);
 
 /**
- * Use this function to get the current audio state of an audio device.
+ * Use this function to query if an audio device is paused.
  *
- * \param dev the ID of an audio device previously opened with
- *            SDL_OpenAudioDevice()
- * \returns the SDL_AudioStatus of the specified audio device.
+ * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app
+ * has to bind a stream before any audio will flow.
+ *
+ * Physical devices can not be paused or unpaused, only logical devices
+ * created through SDL_OpenAudioDevice() can be. Physical and invalid
+ * device IDs will report themselves as unpaused here.
+ *
+ * \param dev a device opened by SDL_OpenAudioDevice()
+ * \returns SDL_TRUE if device is valid and paused, SDL_FALSE otherwise.
+ *
+ * \threadsafety It is safe to call this function from any thread.
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_PlayAudioDevice
  * \sa SDL_PauseAudioDevice
+ * \sa SDL_UnpauseAudioDevice
+ * \sa SDL_IsAudioDevicePaused
  */
-extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
-/* @} *//* Audio State */
+extern DECLSPEC SDL_bool SDLCALL SDL_IsAudioDevicePaused(SDL_AudioDeviceID dev);
 
 /**
- * Use this function to play audio on a specified device.
+ * Close a previously-opened audio device.
  *
- * Newly-opened audio devices start in the paused state, so you must call this
- * function after opening the specified audio device to start playing sound.
- * This allows you to safely initialize data for your callback function after
- * opening the audio device. Silence will be written to the audio device while
- * paused, and the audio callback is guaranteed to not be called. Pausing one
- * device does not prevent other unpaused devices from running their
- * callbacks.
+ * The application should close open audio devices once they are no longer
+ * needed.
  *
- * \param dev a device opened by SDL_OpenAudioDevice()
- * \returns 0 on success or a negative error code on failure; call
- *          SDL_GetError() for more information.
+ * This function may block briefly while pending audio data is played by the
+ * hardware, so that applications don't drop the last buffer of data they
+ * supplied if terminating immediately afterwards.
+ *
+ * \param devid an audio device id previously returned by SDL_OpenAudioDevice()
+ *
+ * \threadsafety It is safe to call this function from any thread.
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_LockAudioDevice
- * \sa SDL_PauseAudioDevice
+ * \sa SDL_OpenAudioDevice
  */
-extern DECLSPEC int SDLCALL SDL_PlayAudioDevice(SDL_AudioDeviceID dev);
-
-
+extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid);
 
 /**
- * Use this function to pause audio playback on a specified device.
+ * Bind a list of audio streams to an audio device.
  *
- * This function pauses the audio callback processing for a given device.
- * Silence will be written to the audio device while paused, and the audio
- * callback is guaranteed to not be called. Pausing one device does not
- * prevent other unpaused devices from running their callbacks.
+ * Audio data will flow through any bound streams. For an output device, data
+ * for all bound streams will be mixed together and fed to the device. For a
+ * capture device, a copy of recorded data will be provided to each bound
+ * stream.
  *
- * If you just need to protect a few variables from race conditions vs your
- * callback, you shouldn't pause the audio device, as it will lead to dropouts
- * in the audio playback. Instead, you should use SDL_LockAudioDevice().
+ * Audio streams can only be bound to an open device. This operation is
+ * atomic--all streams bound in the same call will start processing at the same
+ * time, so they can stay in sync. Also: either all streams will be bound or
+ * none of them will be.
  *
- * \param dev a device opened by SDL_OpenAudioDevice()
- * \returns 0 on success or a negative error code on failure; call
- *          SDL_GetError() for more information.
+ * It is an error to bind an already-bound stream; it must be explicitly unbound
+ * first.
+ *
+ * Binding a stream to a device will set its output format for output devices,
+ * and its input format for capture devices, so they match the device's
+ * settings. The caller is welcome to change the other end of the stream's
+ * format at any time.
+ *
+ * \param devid an audio device to bind a stream to.
+ * \param streams an array of audio streams to unbind.
+ * \param num_streams Number streams listed in the `streams` array.
+ * \returns 0 on success, -1 on error; call SDL_GetError() for more information.
+ *
+ * \threadsafety It is safe to call this function from any thread.
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_LockAudioDevice
- * \sa SDL_PlayAudioDevice
+ * \sa SDL_BindAudioStreams
+ * \sa SDL_UnbindAudioStreams
+ * \sa SDL_UnbindAudioStream
+ * \sa SDL_GetAudioStreamBinding
  */
-extern DECLSPEC int SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev);
-
+extern DECLSPEC int SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_AudioStream **streams, int num_streams);
 
 /**
- * Load the audio data of a WAVE file into memory.
+ * Bind a single audio stream to an audio device.
  *
- * Loading a WAVE file requires `src`, `spec`, `audio_buf` and `audio_len` to
- * be valid pointers. The entire data portion of the file is then loaded into
- * memory and decoded if necessary.
+ * This is a convenience function, equivalent to calling
+ * `SDL_BindAudioStreams(devid, &stream, 1)`.
  *
- * Supported formats are RIFF WAVE files with the formats PCM (8, 16, 24, and
- * 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and
- * A-law and mu-law (8 bits). Other formats are currently unsupported and
- * cause an error.
+ * \param devid an audio device to bind a stream to.
+ * \param stream an audio stream to bind to a device.
+ * \returns 0 on success, -1 on error; call SDL_GetError() for more information.
  *
- * If this function succeeds, the pointer returned by it is equal to `spec`
- * and the pointer to the audio data allocated by the function is written to
- * `audio_buf` and its length in bytes to `audio_len`. The SDL_AudioSpec
- * members `freq`, `channels`, and `format` are set to the values of the audio
- * data in the buffer. The `samples` member is set to a sane default and all
- * others are set to zero.
+ * \threadsafety It is safe to call this function from any thread.
  *
- * It's necessary to use SDL_free() to free the audio data returned in
- * `audio_buf` when it is no longer used.
+ * \since This function is available since SDL 3.0.0.
  *
- * Because of the underspecification of the .WAV format, there are many
- * problematic files in the wild that cause issues with strict decoders. To
- * provide compatibility with these files, this decoder is lenient in regards
- * to the truncation of the file, the fact chunk, and the size of the RIFF
- * chunk. The hints `SDL_HINT_WAVE_RIFF_CHUNK_SIZE`,
- * `SDL_HINT_WAVE_TRUNCATION`, and `SDL_HINT_WAVE_FACT_CHUNK` can be used to
- * tune the behavior of the loading process.
+ * \sa SDL_BindAudioStreams
+ * \sa SDL_UnbindAudioStreams
+ * \sa SDL_UnbindAudioStream
+ * \sa SDL_GetAudioStreamBinding
+ */
+extern DECLSPEC int SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_AudioStream *stream);
+
+/**
+ * Unbind a list of audio streams from their audio devices.
  *
- * Any file that is invalid (due to truncation, corruption, or wrong values in
- * the headers), too big, or unsupported causes an error. Additionally, any
- * critical I/O error from the data source will terminate the loading process
- * with an error. The function returns NULL on error and in all cases (with
- * the exception of `src` being NULL), an appropriate error message will be
- * set.
+ * The streams being unbound do not all have to be on the same device.
+ * All streams on the same device will be unbound atomically (data will stop flowing
+ * through them all unbound streams on the same device at the same time).
  *
- * It is required that the data source supports seeking.
+ * Unbinding a stream that isn't bound to a device is a legal no-op.
  *
- * Example:
+ * \param streams an array of audio streams to unbind.
+ * \param num_streams Number streams listed in the `streams` array.
  *
- * ```c
- * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, &spec, &buf, &len);
- * ```
+ * \threadsafety It is safe to call this function from any thread.
  *
- * Note that the SDL_LoadWAV macro does this same thing for you, but in a less
- * messy way:
+ * \since This function is available since SDL 3.0.0.
  *
- * ```c
- * SDL_LoadWAV("sample.wav", &spec, &buf, &len);
- * ```
+ * \sa SDL_BindAudioStreams
+ * \sa SDL_BindAudioStream
+ * \sa SDL_UnbindAudioStream
+ * \sa SDL_GetAudioStreamBinding
+ */
+extern DECLSPEC void SDLCALL SDL_UnbindAudioStreams(SDL_AudioStream **streams, int num_streams);
+
+/**
+ * Unbind a single audio stream from its audio device.
  *
- * \param src The data source for the WAVE data
- * \param freesrc if SDL_TRUE, calls SDL_RWclose() on `src` before returning,
- *                even in the case of an error
- * \param spec An SDL_AudioSpec that will be filled in with the wave file's
- *             format details
- * \param audio_buf A pointer filled with the audio data, allocated by the
- *                  function
- * \param audio_len A pointer filled with the length of the audio data buffer
- *                  in bytes
- * \returns This function, if successfully called, returns `spec`, which will
- *          be filled with the audio data format of the wave source data.
- *          `audio_buf` will be filled with a pointer to an allocated buffer
- *          containing the audio data, and `audio_len` is filled with the
- *          length of that audio buffer in bytes.
+ * This is a convenience function, equivalent to calling
+ * `SDL_UnbindAudioStreams(&stream, 1)`.
  *
- *          This function returns NULL if the .WAV file cannot be opened, uses
- *          an unknown data format, or is corrupt; call SDL_GetError() for
- *          more information.
+ * \param stream an audio stream to unbind from a device.
  *
- *          When the application is done with the data returned in
- *          `audio_buf`, it should call SDL_free() to dispose of it.
+ * \threadsafety It is safe to call this function from any thread.
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_free
- * \sa SDL_LoadWAV
+ * \sa SDL_BindAudioStream
+ * \sa SDL_BindAudioStreams
+ * \sa SDL_UnbindAudioStreams
+ * \sa SDL_GetAudioStreamBinding
  */
-extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
-                                                      SDL_bool freesrc,
-                                                      SDL_AudioSpec * spec,
-                                                      Uint8 ** audio_buf,
-                                                      Uint32 * audio_len);
+extern DECLSPEC void SDLCALL SDL_UnbindAudioStream(SDL_AudioStream *stream);
 
 /**
- *  Loads a WAV from a file.
- *  Compatibility convenience function.
+ * Query an audio stream for its currently-bound device.
+ *
+ * This reports the audio device that an audio stream is currently bound to.
+ *
+ * If not bound, or invalid, this returns zero, which is not a valid device ID.
+ *
+ * \param stream the audio stream to query.
+ * \returns The bound audio device, or 0 if not bound or invalid.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_BindAudioStream
+ * \sa SDL_BindAudioStreams
+ * \sa SDL_UnbindAudioStream
+ * \sa SDL_UnbindAudioStreams
  */
-#define SDL_LoadWAV(file, spec, audio_buf, audio_len) \
-    SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
+extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_GetAudioStreamBinding(SDL_AudioStream *stream);
 
 
-/* SDL_AudioStream is an audio conversion interface.
-    - It can handle resampling data in chunks without generating
-      artifacts, when it doesn't have the complete buffer available.
-    - It can handle incoming data in any variable size.
-    - You push data as you have it, and pull it when you need it
-    - It can also function as a basic audio data queue even if you
-      just have sound that needs to pass from one place to another.
- */
-struct SDL_AudioStream;  /* this is opaque to the outside world. */
-typedef struct SDL_AudioStream SDL_AudioStream;
-
 /**
  * Create a new audio stream.
  *
- * \param src_format The format of the source audio
- * \param src_channels The number of channels of the source audio
- * \param src_rate The sampling rate of the source audio
- * \param dst_format The format of the desired audio output
- * \param dst_channels The number of channels of the desired audio output
- * \param dst_rate The sampling rate of the desired audio output
+ * \param src_spec The format details of the input audio
+ * \param dst_spec The format details of the output audio
  * \returns 0 on success, or -1 on error.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -714,26 +655,15 @@ typedef struct SDL_AudioStream SDL_AudioStream;
  * \sa SDL_ChangeAudioStreamOutput
  * \sa SDL_DestroyAudioStream
  */
-extern DECLSPEC SDL_AudioStream *SDLCALL SDL_CreateAudioStream(SDL_AudioFormat src_format,
-                                                            int src_channels,
-                                                            int src_rate,
-                                                            SDL_AudioFormat dst_format,
-                                                            int dst_channels,
-                                                            int dst_rate);
+extern DECLSPEC SDL_AudioStream *SDLCALL SDL_CreateAudioStream(const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec);
 
 
 /**
  * Query the current format of an audio stream.
  *
  * \param stream the SDL_AudioStream to query.
- * \param src_format Where to store the input audio format; ignored if NULL.
- * \param src_channels Where to store the input channel count; ignored if
- *                     NULL.
- * \param src_rate Where to store the input sample rate; ignored if NULL.
- * \param dst_format Where to store the output audio format; ignored if NULL.
- * \param dst_channels Where to store the output channel count; ignored if
- *                     NULL.
- * \param dst_rate Where to store the output sample rate; ignored if NULL.
+ * \param src_spec Where to store the input audio format; ignored if NULL.
+ * \param dst_spec Where to store the output audio format; ignored if NULL.
  * \returns 0 on success, or -1 on error.
  *
  * \threadsafety It is safe to call this function from any thread, as it holds
@@ -742,12 +672,8 @@ extern DECLSPEC SDL_AudioStream *SDLCALL SDL_CreateAudioStream(SDL_AudioFormat s
  * \since This function is available since SDL 3.0.0.
  */
 extern DECLSPEC int SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream,
-                                                     SDL_AudioFormat *src_format,
-                                                     int *src_channels,
-                                                     int *src_rate,
-                                                     SDL_AudioFormat *dst_format,
-                                                     int *dst_channels,
-                                                     int *dst_rate);
+                                                     SDL_AudioSpec *src_spec,
+                                                     SDL_AudioSpec *dst_spec);
 
 /**
  * Change the input and output formats of an audio stream.
@@ -757,12 +683,8 @@ extern DECLSPEC int SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream,
  * must provide data in the new input formats.
  *
  * \param stream The stream the format is being changed
- * \param src_format The format of the audio input
- * \param src_channels The number of channels of the audio input
- * \param src_rate The sampling rate of the audio input
- * \param dst_format The format of the desired audio output
- * \param dst_channels The number of channels of the desired audio output
- * \param dst_rate The sampling rate of the desired audio output
+ * \param src_spec The new format of the audio input; if NULL, it is not changed.
+ * \param dst_spec The new format of the audio output; if NULL, it is not changed.
  * \returns 0 on success, or -1 on error.
  *
  * \threadsafety It is safe to call this function from any thread, as it holds
@@ -776,12 +698,8 @@ extern DECLSPEC int SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream,
  * \sa SDL_GetAudioStreamAvailable
  */
 extern DECLSPEC int SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream,
-                                                     SDL_AudioFormat src_format,
-                                                     int src_channels,
-                                                     int src_rate,
-                                                     SDL_AudioFormat dst_format,
-                                                     int dst_channels,
-                                                     int dst_rate);
+                                                     const SDL_AudioSpec *src_spec,
+                                                     const SDL_AudioSpec *dst_spec);
 
 /**
  * Add data to be converted/resampled to the stream.
@@ -800,6 +718,10 @@ extern DECLSPEC int SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream,
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \threadsafety It is safe to call this function from any thread, but if the
+ *               stream has a callback set, the caller might need to manage
+ *               extra locking.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_CreateAudioStream
@@ -828,6 +750,10 @@ extern DECLSPEC int SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream, cons
  * \param len The maximum number of bytes to fill
  * \returns the number of bytes read from the stream, or -1 on error
  *
+ * \threadsafety It is safe to call this function from any thread, but if the
+ *               stream has a callback set, the caller might need to manage
+ *               extra locking.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_CreateAudioStream
@@ -856,6 +782,8 @@ extern DECLSPEC int SDLCALL SDL_GetAudioStreamData(SDL_AudioStream *stream, void
  * \param stream The audio stream to query
  * \returns the number of converted/resampled bytes available.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_CreateAudioStream
@@ -879,6 +807,8 @@ extern DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *stream)
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_CreateAudioStream
@@ -897,6 +827,8 @@ extern DECLSPEC int SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream);
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_CreateAudioStream
@@ -909,316 +841,384 @@ extern DECLSPEC int SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream);
 extern DECLSPEC int SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream);
 
 /**
- * Free an audio stream
- *
- * \param stream The audio stream to free
- *
- * \since This function is available since SDL 3.0.0.
- *
- * \sa SDL_CreateAudioStream
- * \sa SDL_PutAudioStreamData
- * \sa SDL_GetAudioStreamData
- * \sa SDL_GetAudioStreamAvailable
- * \sa SDL_FlushAudioStream
- * \sa SDL_ClearAudioStream
- */
-extern DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream);
-
-#define SDL_MIX_MAXVOLUME 128
-
-/**
- * Mix audio data in a specified format.
- *
- * This takes an audio buffer `src` of `len` bytes of `format` data and mixes
- * it into `dst`, performing addition, volume adjustment, and overflow
- * clipping. The buffer pointed to by `dst` must also be `len` bytes of
- * `format` data.
+ * Lock an audio stream for serialized access.
  *
- * This is provided for convenience -- you can mix your own audio data.
+ * Each SDL_AudioStream has an internal mutex it uses to
+ * protect its data structures from threading conflicts. This function
+ * allows an app to lock that mutex, which could be useful if
+ * registering callbacks on this stream.
  *
- * Do not use this function for mixing together more than two streams of
- * sample data. The output from repeated application of this function may be
- * distorted by clipping, because there is no accumulator with greater range
- * than the input (not to mention this being an inefficient way of doing it).
+ * One does not need to lock a stream to use in it most cases,
+ * as the stream manages this lock internally. However, this lock
+ * is held during callbacks, which may run from arbitrary threads
+ * at any time, so if an app needs to protect shared data during
+ * those callbacks, locking the stream guarantees that the
+ * callback is not running while the lock is held.
  *
- * It is a common misconception that this function is required to write audio
- * data to an output stream in an audio callback. While you can do that,
- * SDL_MixAudioFormat() is really only needed when you're mixing a single
- * audio stream with a volume adjustment.
+ * As this is just a wrapper over SDL_LockMutex for an internal
+ * lock, it has all the same attributes (recursive locks are
+ * allowed, etc).
  *
- * \param dst the destination for the mixed audio
- * \param src the source audio buffer to be mixed
- * \param format the SDL_AudioFormat structure representing the desired audio
- *               format
- * \param len the length of the audio buffer in bytes
- * \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
- *               for full audio volume
+ * \param stream The audio stream to lock.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_UnlockAudioStream
+ * \sa SDL_SetAudioStreamPutCallback
+ * \sa SDL_SetAudioStreamGetCallback
  */
-extern DECLSPEC int SDLCALL SDL_MixAudioFormat(Uint8 * dst,
-                                                const Uint8 * src,
-                                                SDL_AudioFormat format,
-                                                Uint32 len, int volume);
+extern DECLSPEC int SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream);
+
 
 /**
- * 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. SDL_QueueAudio() 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.
- *
- * Note that SDL does not support planar audio. You will need to resample from
- * planar audio formats into a non-planar one (see SDL_AudioFormat) before
- * queuing audio.
- *
- * \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
+ * Unlock an audio stream for serialized access.
+ *
+ * This unlocks an audio stream after a call to SDL_LockAudioStream.
+ *
+ * \param stream The audio stream to unlock.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \threadsafety You should only call this from the same thread that
+ *               previously called SDL_LockAudioStream.
+ *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_ClearQueuedAudio
- * \sa SDL_GetQueuedAudioSize
+ * \sa SDL_LockAudioStream
+ * \sa SDL_SetAudioStreamPutCallback
+ * \sa SDL_SetAudioStreamGetCallback
  */
-extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *data, Uint32 len);
+extern DECLSPEC int SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream);
 
 /**
- * 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. SDL_DequeueAudio() 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 dequeue 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 dequeueing; SDL
- * handles locking internally for this function.
- *
- * \param dev the device ID from which we will dequeue audio
- * \param data a pointer into where audio data should be copied
- * \param len the number of bytes (not samples!) to which (data) points
- * \returns the number of bytes dequeued, which could be less than requested;
- *          call SDL_GetError() for more information.
- *
- * \since This function is available since SDL 3.0.0.
- *
- * \sa SDL_ClearQueuedAudio
- * \sa SDL_GetQueuedAudioSize
+ * A callback that fires when data passes through an SDL_AudioStream.
+ *
+ * Apps can (optionally) register a callback with an audio stream that
+ * is called when data is added with SDL_PutAudioStreamData, or requested
+ * with SDL_GetAudioStreamData. These callbacks may run from any
+ * thread, so if you need to protect shared data, you should use
+ * SDL_LockAudioStream to serialize access; this lock will be held by
+ * before your callback is called, so your callback does not need to
+ * manage the lock explicitly.
+ *
+ * \param stream The SDL audio stream associated with this callback.
+ * \param approx_request The _approximate_ amout of data, in bytes, that is requested.
+ *                       This might be slightly overestimated due to buffering or
+ *                       resampling, and may change from call to call anyhow.
+ * \param userdata An opaque pointer provided by the app for their personal use.
  */
-extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *data, Uint32 len);
+typedef void (SDLCALL *SDL_AudioStreamRequestCallback)(SDL_AudioStream *stream, int approx_request, void *userdata);
 
 /**
- * Get the number of bytes of still-queued audio.
+ * Set a callback that runs when data is requested from an audio stream.
+ *
+ * This callback is called _before_ data is obtained from the stream,
+ * giving the callback the chance to add more on-demand.
+ *
+ * The callback can (optionally) call SDL_PutAudioStreamData() to add
+ * more audio to the stream during this call; if needed, the request
+ * that triggered this callback will obtain the new data immediately.
  *
- * For playback devices: this is the number of bytes that have been queued for
- * playback with SDL_QueueAudio(), but have not yet been sent to the hardware.
+ * The callback's `approx_request` argument is roughly how many bytes
+ * of _unconverted_ data (in the stream's input format) is needed by
+ * the caller, although this may overestimate a little for safety.
+ * This takes into account how much is already in the stream and only
+ * asks for any extra necessary to resolve the request, which means
+ * the callback may be asked for zero bytes, and a different amount
+ * on each call.
  *
- * 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.
+ * The callback is not required to supply exact amounts; it is allowed
+ * to supply too much or too little or none at all. The caller will
+ * get what's available, up to the amount they requested, regardless
+ * of this callback's outcome.
  *
- * 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.
+ * Clearing or flushing an audio stream does not call this callback.
  *
- * You may not queue or dequeue 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, but
- * not both.
+ * This function obtains the stream's lock, which means any existing
+ * callback (get or put) in progress will finish running before setting
+ * the new callback.
  *
- * You should not call SDL_LockAudio() on the device before querying; SDL
- * handles locking internally for this function.
+ * Setting a NULL function turns off the callback.
  *
- * \param dev the device ID of which we will query queued audio size
- * \returns the number of bytes (not samples!) of queued audio.
+ * \param stream the audio stream to set the new callback on.
+ * \param callback the new callback function to call when data is added to the stream.
+ * \param userdata an opaque pointer provided to the callback for its own personal use.
+ * \returns 0 on success, -1 on error. This only fails if `stream` is NULL.
+ *
+ * \threadsafety It is safe to call this function from any thread.
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_ClearQueuedAudio
- * \sa SDL_QueueAudio
- * \sa SDL_DequeueAudio
+ * \sa SDL_SetAudioStreamPutCallback
  */
-extern DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev);
+extern DECLSPEC int SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamRequestCallback callback, void *userdata);
 
 /**
- * Drop any queued audio data waiting to be sent to the hardware.
+ * Set a callback that runs when data is added to an audio stream.
  *
- * Immediately after this call, SDL_GetQueuedAudioSize() will return 0. For
- * output devices, the hardware will start playing silence if more audio isn't
- * queued. For capture devices, the hardware will start filling the empty
- * queue with new data if the capture device isn't paused.
+ * This callback is called _after_ the data is added to the stream,
+ * giving the callback the chance to obtain it immediately.
  *
- * 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 or any unprocessed microphone input
- * during a level change in your game.
+ * The callback can (optionally) call SDL_GetAudioStreamData() to
+ * obtain audio from the stream during this call.
  *
- * You may not queue or dequeue 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, but
- * not both.
+ * The callback's `approx_request` argument is how many bytes
+ * of _converted_ data (in the stream's output format) was provided
+ * by the caller, although this may underestimate a little for safety.
+ * This value might be less than what is currently available in the
+ * stream, if data was already there, and might be less than the
+ * caller provided if the stream needs to keep a buffer to aid in
+ * resampling. Which means the callback may be provided with zero
+ * bytes, and a different amount on each call.
  *
- * You should not call SDL_LockAudio() on the device before clearing the
- * queue; SDL handles locking internally for this function.
+ * The callback may call SDL_GetAudioStreamAvailable to see the
+ * total amount currently available to read from the stream, instead
+ * of the total provided by the current call.
  *
- * This function always succeeds and thus returns void.
+ * The callback is not required to obtain all data. It is allowed
+ * to read less or none at all. Anything not read now simply remains
+ * in the stream for later access.
  *
- * \param dev the device ID of which to clear the audio queue
- * \returns 0 on success or a negative error code on failure; call
- *          SDL_GetError() for more information.
+ * Clearing or flushing an audio stream does not call this callback.
+ *
+ * This function obtains the stream's lock, which means any existing
+ * callback (get or put) in progress will finish running before setting
+ * the new callback.
+ *
+ * Setting a NULL function turns off the callback.
+ *
+ * \param stream the audio stream to set the new callback on.
+ * \param callback the new callback function to call when data is added to the stream.
+ * \param userdata an opaque pointer provided to the callback for its own personal use.
+ * \returns 0 on success, -1 on error. This only fails if `stream` is NULL.
+ *
+ * \threadsafety It is safe to call this function from any thread.
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_GetQueuedAudioSize
- * \sa SDL_QueueAudio
- * \sa SDL_DequeueAudio
+ * \sa SDL_SetAudioStreamGetCallback
  */
-extern DECLSPEC int SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev);
+extern DECLSPEC int SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamRequestCallback callback, void *userdata);
 
 
 /**
- *  \name Audio lock functions
+ * Free an audio stream
  *
- *  The lock manipulated by these functions protects the callback function.
- *  During a SDL_LockAudio()/SDL_UnlockAudio() pair, you can be guaranteed that
- *  the callback function is not running.  Do not call these from the callback
- *  function or you will cause deadlock.
+ * \param stream The audio stream to free
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_CreateAudioStream
+ * \sa SDL_PutAudioStreamData
+ * \sa SDL_GetAudioStreamData
+ * \sa SDL_GetAudioStreamAvailable
+ * \sa SDL_FlushAudioStream
+ * \sa SDL_ClearAudioStream
  */
-/* @{ */
+extern DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream);
+
 
 /**
- * Use this function to lock out the audio callback function for a specified
- * device.
- *
- * The lock manipulated by these functions protects the audio callback
- * function specified in SDL_OpenAudioDevice(). During a
- * SDL_LockAudioDevice()/SDL_UnlockAudioDevice() pair, you can be guaranteed
- * that the callback function for that device is not running, even if the
- * device is not paused. While a device is locked, any other unpaused,
- * unlocked devices may still run their callbacks.
- *
- * Calling this function from inside your audio callback is unnecessary. SDL
- * obtains this lock before calling your function, and releases it when the
- * function returns.
- *
- * You should not hold the lock longer than absolutely necessary. If you hold
- * it too long, you'll experience dropouts in your audio playback. Ideally,
- * your application locks the device, sets a few variables and unlocks again.
- * Do not do heavy work while holding the lock for a device.
- *
- * It is safe to lock the audio device multiple times, as long as you unlock
- * it an equivalent number of times. The callback will not run until the
- * device has been unlocked completely in this way. If your application fails
- * to unlock the device appropriately, your callback will never run, you might
- * hear repeating bursts of audio, and SDL_CloseAudioDevice() will probably
- * deadlock.
- *
- * Internally, the audio device lock is a mutex; if you lock from two threads
- * at once, not only will you block the audio callback, you'll block the other
- * thread.
- *
- * \param dev the ID of the device to be locked
- * \returns 0 on success or a negative error code on failure; call
- *          SDL_GetError() for more information.
+ * Convenience function to create and bind an audio stream in one step.
+ *
+ * This manages the creation of an audio stream, and setting its format
+ * correctly to match both the app and the audio device's needs. This is
+ * optional, but slightly less cumbersome to set up for a common use case.
+ *
+ * The `spec` parameter represents the app's side of the audio stream. That
+ * is, for recording audio, this will be the output format, and for playing
+ * audio, this will be the input format. This function will set the other
+ * side of the audio stream to the device's format.
+ *
+ * \param devid an audio device to bind a stream to. This must be an opened device, and can not be zero.
+ * \param spec the audio stream's input format
+ * \returns a bound audio stream on success, ready to use. NULL on error; call SDL_GetError() for more information.
+ *
+ * \threadsafety It is safe to call this function from any thread.
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_UnlockAudioDevice
+ * \sa SDL_BindAudioStreams
+ * \sa SDL_UnbindAudioStreams
+ * \sa SDL_UnbindAudioStream
  */
-extern DECLSPEC int SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev);
+extern DECLSPEC SDL_AudioStream *SDLCALL SDL_CreateAndBindAudioStream(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec);
+
 
 /**
- * Use this function to unlock the audio callback function for a specified
- * device.
+ * Load the audio data of a WAVE file into memory.
+ *
+ * Loading a WAVE file requires `src`, `spec`, `audio_buf` and `audio_len` to
+ * be valid pointers. The entire data portion of the file is then loaded into
+ * memory and decoded if necessary.
  *
- * This function should be paired with a previous SDL_LockAudioDevice() call.
+ * If `freesrc` is non-zero, the data source gets automatically closed and
+ * freed before the function returns.
  *
- * \param dev the ID of the device to be unlocked
+ * Supported formats are RIFF WAVE files with the formats PCM (8, 16, 24, and
+ * 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and
+ * A-law and mu-law (8 bits). Other formats are currently unsupported and
+ * cause an error.
+ *
+ * If this function succeeds, the return value is zero and the pointer to the
+ * audio data allocated by the function is written to `audio_buf` and its
+ * length in bytes to `audio_len`. The SDL_AudioSpec members `freq`,
+ * `channels`, and `format` are set to the values of the audio data in the
+ * buffer. The `samples` member is set to a sane default and all
+ * others are set to zero.
+ *
+ * It's necessary to use SDL_free() to free the audio data returned in
+ * `audio_buf` when it is no longer used.
+ *
+ * Because of the underspecification of the .WAV format, there are many
+ * problematic files in the wild that cause issues with strict decoders. To
+ * provide compatibility with these files, this decoder is lenient in regards
+ * to the truncation of the file, the fact chunk, and the size of the RIFF
+ * chunk. The hints `SDL_HINT_WAVE_RIFF_CHUNK_SIZE`,
+ * `SDL_HINT_WAVE_TRUNCATION`, and `SDL_HINT_WAVE_FACT_CHUNK` can be used to
+ * tune the behavior of the loading process.
+ *
+ * Any file that is invalid (due to truncation, corruption, or wrong values in
+ * the headers), too big, or unsupported causes an error. Additionally, any
+ * critical I/O error from the data source will terminate the loading process
+ * with an error. The function returns NULL on error and in all cases (with
+ * the exception of `src` being NULL), an appropriate error message will be
+ * set.
+ *
+ * It is required that the data source supports seeking.
+ *
+ * Example:
+ *
+ * ```c
+ * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, &spec, &buf, &len);
+ * ```
+ *
+ * Note that the SDL_LoadWAV function does this same thing for you, but in a
+ * less messy way:
+ *
+ * ```c
+ * SDL_LoadWAV("sample.wav", &spec, &buf, &len);
+ * ```
+ *
+ * \param src The data source for the WAVE data
+ * \param freesrc If non-zero, SDL will _always_ free the data source
+ * \param spec A pointer to an SDL_AudioSpec that will be set to the
+ *             WAVE data's format details on successful return.
+ * \param audio_buf A pointer filled with the audio data, allocated by the
+ *                  function.
+ * \param audio_len A pointer filled with the length of the audio data buffer
+ *                  in bytes
+ * \returns This function, if successfully called, returns 0. `audio_buf`
+ *          will be filled with a pointer to an allocated buffer
+ *          containing the audio data, and `audio_len` is filled with the
+ *          length of that audio buffer in bytes.
+ *
+ *          This function returns -1 if the .WAV file cannot be opened, uses
+ *          an unknown data format, or is corrupt; call SDL_GetError() for
+ *          more information.
+ *
+ *          When the application is done with the data returned in
+ *          `audio_buf`, it should call SDL_free() to dispose of it.
+ *
+ * \threadsafety It is safe to call this function from any thread.
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_LockAudioDevice
+ * \sa SDL_free
+ * \sa SDL_LoadWAV
  */
-extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev);
-/* @} *//* Audio lock functions */
+extern DECLSPEC int SDLCALL SDL_LoadWAV_RW(SDL_RWops * src, int freesrc,
+                                           SDL_AudioSpec * spec, Uint8 ** audio_buf,
+                                           Uint32 * audio_len);
 
 /**
- * Use this function to shut down audio processing and close the audio device.
+ * Loads a WAV from a file path.
  *
- * The application should close open audio devices once they are no longer
- * needed. Calling this function will wait until the device's audio callback
- * is not running, release the audio hardware and then clean up internal
- * state. No further audio will play from this device once this function
- * returns.
+ * This is a convenience function that is effectively the same as:
  *
- * This function may block briefly while pending audio data is played by the
- * hardware, so that applications don't drop the last buffer of data they
- * supplied.
+ * ```c
+ * SDL_LoadWAV_RW(SDL_RWFromFile(path, "rb"), 1, spec, audio_buf, audio_len);
+ * ```
  *
- * The device ID is invalid as soon as the device is closed, and is eligible
- * for reuse in a new SDL_OpenAudioDevice() call immediately.
+ * Note that in SDL2, this was a preprocessor macro and not a real function.
  *
- * \param dev an audio device previously opened with SDL_OpenAudioDevice()
+ * \param path The file path of the WAV file to open.
+ * \param spec A pointer to an SDL_AudioSpec that will be set to the
+ *             WAVE data's format details on successful return.
+ * \param audio_buf A pointer filled with the audio data, allocated by the
+ *                  function.
+ * \param audio_len A pointer filled with the length of the audio data buffer
+ *                  in bytes
+ * \returns This function, if successfully called, returns 0. `audio_buf`
+ *          will be filled with a pointer to an allocated buffer
+ *          containing the audio data, and `audio_len` is filled with the
+ *          length of that audio buffer in bytes.
+ *
+ *          This function returns -1 if the .WAV file cannot be opened, uses
+ *          an unknown data format, or is corrupt; call SDL_GetError() for
+ *          more information.
+ *
+ *          When the application is done with the data returned in
+ *          `audio_buf`, it should call SDL_free() to dispose of it.
+ *
+ * \threadsafety It is safe to call this function from any thread.
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_OpenAudioDevice
+ * \sa SDL_free
+ * \sa SDL_LoadWAV_RW
+ */
+extern DECLSPEC int SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec * spec,
+                                        Uint8 ** audio_buf, Uint32 * audio_len);
+
+
+
+#define SDL_MIX_MAXVOLUME 128
+
+/**
+ * Mix audio data in a specified format.
+ *
+ * This takes an audio buffer `src` of `len` bytes of `format` data and mixes
+ * it into `dst`, performing addition, volume adjustment, and overflow
+ * clipping. The buffer pointed to by `dst` must also be `len` bytes of
+ * `format` data.
+ *
+ * This is provided for convenience -- you can mix your own audio data.
+ *
+ * Do not use this function for mixing together more than two streams of
+ * sample data. The output from repeated application of this function may be
+ * distorted by clipping, because there is no accumulator with greater range
+ * than the input (not to mention this being an inefficient way of doing it).
+ *
+ * It is a common misconception that this function is required to write audio
+ * data to an output stream in an audio callback. While you can do that,
+ * SDL_MixAudioFormat() is really only needed when you're mixing a single
+ * audio stream with a volume adjustment.
+ *
+ * \param dst the destination for the mixed audio
+ * \param src the source audio buffer to be mixed
+ * \param format the SDL_AudioFormat structure representing the desired audio
+ *               format
+ * \param len the length of the audio buffer in bytes
+ * \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
+ *               for full audio volume
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.0.0.
  */
-extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
+extern DECLSPEC int SDLCALL SDL_MixAudioFormat(Uint8 * dst,
+                                                const Uint8 * src,
+                                                SDL_AudioFormat format,
+                                                Uint32 len, int volume);
 
 /**
  * Convert some audio data of one format to another format.
@@ -1233,14 +1233,10 @@ extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
  * use, so it's also less efficient than using one directly, if you need to
  * convert multiple times.
  *
- * \param src_format The format of the source audio
- * \param src_channels The number of channels of the source audio
- * \param src_rate The sampling rate of the source audio
+ * \param src_spec The format details of the input audio
  * \param src_data The audio data to be converted
  * \param src_len The len of src_data
- * \param dst_format The format of the desired audio output
- * \param dst_channels The number of channels of the desired audio output
- * \param dst_rate The sampling rate of the desired audio output
+ * \param dst_spec The format details of the output audio
  * \param dst_data Will be filled with a pointer to converted audio data,
  *                 which should be freed with SDL_free(). On error, it will be
  *                 NULL.
@@ -1248,21 +1244,37 @@ extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_CreateAudioStream
  */
-extern DECLSPEC int SDLCALL SDL_ConvertAudioSamples(SDL_AudioFormat src_format,
-                                                    Uint8 src_channels,
-                                                    int src_rate,
+extern DECLSPEC int SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec *src_spec,
                                                     const Uint8 *src_data,
                                                     int src_len,
-                                                    SDL_AudioFormat dst_format,
-                                                    Uint8 dst_channels,
-                                                    int dst_rate,
+                                                    const SDL_AudioSpec *dst_spec,
                                                     Uint8 **dst_data,
                                                     int *dst_len);
 
+
+/**
+ * Get the appropriate memset value for silencing an audio format.
+ *
+ * The value returned by this function can be used as the second
+ * argument to memset (or SDL_memset) to set an audio buffer in
+ * a specific format to silence.
+ *
+ * \param format the audio data format to query.
+ * \returns A byte value that can be passed to memset.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.0.0.
+ */
+extern DECLSPEC int SDLCALL SDL_GetSilenceValueForFormat(SDL_AudioFormat format);
+
+
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
 }

include/SDL3/SDL_events.h

@@ -493,7 +493,7 @@ typedef struct SDL_AudioDeviceEvent
 {
     Uint32 type;        /**< ::SDL_EVENT_AUDIO_DEVICE_ADDED, or ::SDL_EVENT_AUDIO_DEVICE_REMOVED */
     Uint64 timestamp;   /**< In nanoseconds, populated using SDL_GetTicksNS() */
-    SDL_AudioDeviceID which;       /**< The audio device index for the ADDED event (valid until next SDL_GetNumAudioDevices() call), SDL_AudioDeviceID for the REMOVED event */
+    SDL_AudioDeviceID which;       /**< SDL_AudioDeviceID for the device being added or removed */
     Uint8 iscapture;    /**< zero if an output device, non-zero if a capture device. */
     Uint8 padding1;
     Uint8 padding2;

include/SDL3/SDL_test_common.h

@@ -97,7 +97,9 @@ typedef struct
 
     /* Audio info */
     const char *audiodriver;
-    SDL_AudioSpec audiospec;
+    SDL_AudioFormat audio_format;
+    int audio_channels;
+    int audio_freq;
     SDL_AudioDeviceID audio_id;
 
     /* GL settings */

src/audio/SDL_audio.c

@@ -20,17 +20,12 @@
 */
 #include "SDL_internal.h"
 
-/* Allow access to a raw mixing buffer */
-
 #include "SDL_audio_c.h"
 #include "SDL_sysaudio.h"
 #include "../thread/SDL_systhread.h"
 #include "../SDL_utils_c.h"
 
-static SDL_AudioDriver current_audio;
-static SDL_AudioDevice *open_devices[16];
-
-/* Available audio drivers */
+// Available audio drivers
 static const AudioBootStrap *const bootstrap[] = {
 #ifdef SDL_AUDIO_DRIVER_PULSEAUDIO
     &PULSEAUDIO_bootstrap,
@@ -57,7 +52,7 @@ static const AudioBootStrap *const bootstrap[] = {
     &COREAUDIO_bootstrap,
 #endif
 #ifdef SDL_AUDIO_DRIVER_AAUDIO
-    &aaudio_bootstrap,
+    &AAUDIO_bootstrap,
 #endif
 #ifdef SDL_AUDIO_DRIVER_OPENSLES
     &openslES_bootstrap,
@@ -101,1395 +96,1443 @@ static const AudioBootStrap *const bootstrap[] = {
     NULL
 };
 
-static SDL_AudioDevice *get_audio_device(SDL_AudioDeviceID id)
-{
-    id--;
-    if ((id >= SDL_arraysize(open_devices)) || (open_devices[id] == NULL)) {
-        SDL_SetError("Invalid audio device ID");
-        return NULL;
-    }
+static SDL_AudioDriver current_audio;
 
-    return open_devices[id];
+int SDL_GetNumAudioDrivers(void)
+{
+    return SDL_arraysize(bootstrap) - 1;
 }
 
-int get_max_num_audio_dev(void)
+const char *SDL_GetAudioDriver(int index)
 {
-    return SDL_arraysize(open_devices);
+    if (index >= 0 && index < SDL_GetNumAudioDrivers()) {
+        return bootstrap[index]->name;
+    }
+    return NULL;
 }
 
-SDL_AudioDevice *get_audio_dev(SDL_AudioDeviceID id)
+const char *SDL_GetCurrentAudioDriver(void)
 {
-    return open_devices[id];
+    return current_audio.name;
 }
 
-/* stubs for audio drivers that don't need a specific entry point... */
-static void SDL_AudioDetectDevices_Default(void)
-{
-    /* 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);
+// device management and hotplug...
 
-    SDL_AddAudioDevice(SDL_FALSE, DEFAULT_OUTPUT_DEVNAME, NULL, (void *)((size_t)0x1));
-    if (current_audio.impl.HasCaptureSupport) {
-        SDL_AddAudioDevice(SDL_TRUE, DEFAULT_INPUT_DEVNAME, NULL, (void *)((size_t)0x2));
-    }
-}
 
-static void SDL_AudioThreadInit_Default(SDL_AudioDevice *_this)
-{ /* no-op. */
-}
+/* SDL_AudioDevice, in SDL3, represents a piece of physical hardware, whether it is in use or not, so these objects exist as long as
+   the system-level device is available.
 
-static void SDL_AudioThreadDeinit_Default(SDL_AudioDevice *_this)
-{ /* no-op. */
-}
+   Physical devices get destroyed for three reasons:
+    - They were lost to the system (a USB cable is kicked out, etc).
+    - They failed for some other unlikely reason at the API level (which is _also_ probably a USB cable being kicked out).
+    - We are shutting down, so all allocated resources are being freed.
 
-static void SDL_AudioWaitDevice_Default(SDL_AudioDevice *_this)
-{ /* no-op. */
-}
+   They are _not_ destroyed because we are done using them (when we "close" a playing device).
+*/
+static void ClosePhysicalAudioDevice(SDL_AudioDevice *device);
 
-static void SDL_AudioPlayDevice_Default(SDL_AudioDevice *_this)
-{ /* no-op. */
-}
 
-static Uint8 *SDL_AudioGetDeviceBuf_Default(SDL_AudioDevice *_this)
-{
-    return NULL;
-}
+// the loop in assign_audio_device_instance_id relies on this being true.
+SDL_COMPILE_TIME_ASSERT(check_lowest_audio_default_value, SDL_AUDIO_DEVICE_DEFAULT_CAPTURE < SDL_AUDIO_DEVICE_DEFAULT_OUTPUT);
 
-static int SDL_AudioCaptureFromDevice_Default(SDL_AudioDevice *_this, void *buffer, int buflen)
+static SDL_AudioDeviceID assign_audio_device_instance_id(SDL_bool iscapture, SDL_bool islogical)
 {
-    return -1; /* just fail immediately. */
-}
-
-static void SDL_AudioFlushCapture_Default(SDL_AudioDevice *_this)
-{ /* no-op. */
+    /* Assign an instance id! Start at 2, in case there are things from the SDL2 era that still think 1 is a special value.
+       There's no reasonable scenario where this rolls over, but just in case, we wrap it in a loop.
+       Also, make sure we don't assign SDL_AUDIO_DEVICE_DEFAULT_OUTPUT, etc. */
+
+    // The bottom two bits of the instance id tells you if it's an output device (1<<0), and if it's a physical device (1<<1). Make sure these are right.
+    const SDL_AudioDeviceID required_mask = (iscapture ? 0 : (1<<0)) | (islogical ? 0 : (1<<1));
+
+    SDL_AudioDeviceID instance_id;
+    do {
+        instance_id = (SDL_AudioDeviceID) (SDL_AtomicIncRef(&current_audio.last_device_instance_id) + 1);
+    } while ( (instance_id < 2) || (instance_id >= SDL_AUDIO_DEVICE_DEFAULT_CAPTURE) || ((instance_id & 0x3) != required_mask) );
+    return instance_id;
 }
 
-static void SDL_AudioCloseDevice_Default(SDL_AudioDevice *_this)
-{ /* no-op. */
-}
+// this assumes you hold the _physical_ device lock for this logical device! This will not unlock the lock or close the physical device!
+static void DestroyLogicalAudioDevice(SDL_LogicalAudioDevice *logdev)
+{
+    // remove ourselves from the physical device's list of logical devices.
+    if (logdev->next) {
+        logdev->next->prev = logdev->prev;
+    }
+    if (logdev->prev) {
+        logdev->prev->next = logdev->next;
+    }
+    if (logdev->physical_device->logical_devices == logdev) {
+        logdev->physical_device->logical_devices = logdev->next;
+    }
 
-static void SDL_AudioDeinitialize_Default(void)
-{ /* no-op. */
-}
+    // unbind any still-bound streams...
+    SDL_AudioStream *next;
+    for (SDL_AudioStream *stream = logdev->bound_streams; stream != NULL; stream = next) {
+        SDL_LockMutex(stream->lock);
+        next = stream->next_binding;
+        stream->next_binding = NULL;
+        stream->prev_binding = NULL;
+        stream->bound_device = NULL;
+        SDL_UnlockMutex(stream->lock);
+    }
 
-static void SDL_AudioFreeDeviceHandle_Default(void *handle)
-{ /* no-op. */
+    SDL_free(logdev);
 }
 
-static int SDL_AudioOpenDevice_Default(SDL_AudioDevice *_this, const char *devname)
+// this must not be called while `device` is still in a device list, or while a device's audio thread is still running (except if the thread calls this while shutting down). */
+static void DestroyPhysicalAudioDevice(SDL_AudioDevice *device)
 {
-    return SDL_Unsupported();
-}
+    if (!device) {
+        return;
+    }
 
-static void SDL_AudioLockDevice_Default(SDL_AudioDevice *device)
-{
-    SDL_LockMutex(device->mixer_lock);
-}
+    // Destroy any logical devices that still exist...
+    SDL_LockMutex(device->lock);
+    while (device->logical_devices != NULL) {
+        DestroyLogicalAudioDevice(device->logical_devices);
+    }
+    SDL_UnlockMutex(device->lock);
 
-static void SDL_AudioUnlockDevice_Default(SDL_AudioDevice *device)
-{
-    SDL_UnlockMutex(device->mixer_lock);
-}
+    // it's safe to not hold the lock for this (we can't anyhow, or the audio thread won't quit), because we shouldn't be in the device list at this point.
+    ClosePhysicalAudioDevice(device);
 
-static void finish_audio_entry_points_init(void)
-{
-    /*
-     * Fill in stub functions for unused driver entry points. This lets us
-     *  blindly call them without having to check for validity first.
-     */
+    current_audio.impl.FreeDeviceHandle(device);
 
-#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(WaitDevice);
-    FILL_STUB(PlayDevice);
-    FILL_STUB(GetDeviceBuf);
-    FILL_STUB(CaptureFromDevice);
-    FILL_STUB(FlushCapture);
-    FILL_STUB(CloseDevice);
-    FILL_STUB(LockDevice);
-    FILL_STUB(UnlockDevice);
-    FILL_STUB(FreeDeviceHandle);
-    FILL_STUB(Deinitialize);
-#undef FILL_STUB
+    SDL_DestroyMutex(device->lock);
+    SDL_free(device->work_buffer);
+    SDL_free(device->name);
+    SDL_free(device);
 }
 
-/* device hotplug support... */
-
-static int add_audio_device(const char *name, SDL_AudioSpec *spec, void *handle, SDL_AudioDeviceItem **devices, int *devCount)
+static SDL_AudioDevice *CreatePhysicalAudioDevice(const char *name, SDL_bool iscapture, const SDL_AudioSpec *spec, void *handle, SDL_AudioDevice **devices, SDL_AtomicInt *device_count)
 {
-    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();
+    if (SDL_AtomicGet(&current_audio.shutting_down)) {
+        return NULL;  // we're shutting down, don't add any devices that are hotplugged at the last possible moment.
     }
 
-    item->original_name = SDL_strdup(name);
-    if (!item->original_name) {
-        SDL_free(item);
-        return SDL_OutOfMemory();
+    SDL_AudioDevice *device = (SDL_AudioDevice *)SDL_calloc(1, sizeof(SDL_AudioDevice));
+    if (!device) {
+        SDL_OutOfMemory();
+        return NULL;
     }
 
-    item->dupenum = 0;
-    item->name = item->original_name;
-    if (spec != NULL) {
-        SDL_copyp(&item->spec, spec);
-    } else {
-        SDL_zero(item->spec);
+    device->name = SDL_strdup(name);
+    if (!device->name) {
+        SDL_free(device);
+        SDL_OutOfMemory();
+        return NULL;
     }
-    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. */
-        }
+    device->lock = SDL_CreateMutex();
+    if (!device->lock) {
+        SDL_free(device->name);
+        SDL_free(device);
+        return NULL;
     }
 
-    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);
-            return SDL_OutOfMemory();
-        }
+    SDL_AtomicSet(&device->shutdown, 0);
+    SDL_AtomicSet(&device->condemned, 0);
+    SDL_AtomicSet(&device->zombie, 0);
+    device->iscapture = iscapture;
+    SDL_memcpy(&device->spec, spec, sizeof (SDL_AudioSpec));
+    SDL_memcpy(&device->default_spec, spec, sizeof (SDL_AudioSpec));
+    device->silence_value = SDL_GetSilenceValueForFormat(device->spec.format);
+    device->handle = handle;
+    device->prev = NULL;
 
-        (void)SDL_snprintf(replacement, len, "%s (%d)", name, dupenum + 1);
-        item->dupenum = dupenum;
-        item->name = replacement;
-    }
+    device->instance_id = assign_audio_device_instance_id(iscapture, /*islogical=*/SDL_FALSE);
 
-    item->next = *devices;
-    *devices = item;
-    retval = (*devCount)++; /* !!! FIXME: this should be an atomic increment */
+    SDL_LockRWLockForWriting(current_audio.device_list_lock);
 
-    SDL_UnlockMutex(current_audio.detectionLock);
+    if (*devices) {
+        SDL_assert((*devices)->prev == NULL);
+        (*devices)->prev = device;
+    }
+    device->next = *devices;
+    *devices = device;
+    SDL_AtomicAdd(device_count, 1);
+    SDL_UnlockRWLock(current_audio.device_list_lock);
 
-    return retval;
+    return device;
 }
 
-static SDL_INLINE int add_capture_device(const char *name, SDL_AudioSpec *spec, void *handle)
+static SDL_AudioDevice *CreateAudioCaptureDevice(const char *name, const SDL_AudioSpec *spec, void *handle)
 {
     SDL_assert(current_audio.impl.HasCaptureSupport);
-    return add_audio_device(name, spec, handle, &current_audio.inputDevices, &current_audio.inputDeviceCount);
+    return CreatePhysicalAudioDevice(name, SDL_TRUE, spec, handle, &current_audio.capture_devices, &current_audio.capture_device_count);
 }
 
-static SDL_INLINE int add_output_device(const char *name, SDL_AudioSpec *spec, void *handle)
+static SDL_AudioDevice *CreateAudioOutputDevice(const char *name, const SDL_AudioSpec *spec, void *handle)
 {
-    return add_audio_device(name, spec, handle, &current_audio.outputDevices, &current_audio.outputDeviceCount);
+    return CreatePhysicalAudioDevice(name, SDL_FALSE, spec, handle, &current_audio.output_devices, &current_audio.output_device_count);
 }
 
-static void free_device_list(SDL_AudioDeviceItem **devices, int *devCount)
+// The audio backends call this when a new device is plugged in.
+SDL_AudioDevice *SDL_AddAudioDevice(const SDL_bool iscapture, const char *name, const SDL_AudioSpec *inspec, void *handle)
 {
-    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);
+    const SDL_AudioFormat default_format = iscapture ? DEFAULT_AUDIO_CAPTURE_FORMAT : DEFAULT_AUDIO_OUTPUT_FORMAT;
+    const int default_channels = iscapture ? DEFAULT_AUDIO_CAPTURE_CHANNELS : DEFAULT_AUDIO_OUTPUT_CHANNELS;
+    const int default_freq = iscapture ? DEFAULT_AUDIO_CAPTURE_FREQUENCY : DEFAULT_AUDIO_OUTPUT_FREQUENCY;
+
+    SDL_AudioSpec spec;
+    if (!inspec) {
+        spec.format = default_format;
+        spec.channels = default_channels;
+        spec.freq = default_freq;
+    } else {
+        spec.format = (inspec->format != 0) ? inspec->format : default_format;
+        spec.channels = (inspec->channels != 0) ? inspec->channels : default_channels;
+        spec.freq = (inspec->freq != 0) ? inspec->freq : default_freq;
     }
-    *devices = NULL;
-    *devCount = 0;
-}
 
-/* The audio backends call this when a new device is plugged in. */
-void SDL_AddAudioDevice(const SDL_bool iscapture, const char *name, SDL_AudioSpec *spec, void *handle)
-{
-    const int device_index = iscapture ? add_capture_device(name, spec, handle) : add_output_device(name, spec, handle);
-    if (device_index != -1) {
-        /* Post the event, if desired */
+    SDL_AudioDevice *device = iscapture ? CreateAudioCaptureDevice(name, &spec, handle) : CreateAudioOutputDevice(name, &spec, handle);
+    if (device) {
+        // Post the event, if desired
         if (SDL_EventEnabled(SDL_EVENT_AUDIO_DEVICE_ADDED)) {
             SDL_Event event;
             event.type = SDL_EVENT_AUDIO_DEVICE_ADDED;
             event.common.timestamp = 0;
-            event.adevice.which = device_index;
+            event.adevice.which = device->instance_id;
             event.adevice.iscapture = iscapture;
             SDL_PushEvent(&event);
         }
     }
+
+    return device;
 }
 
-/* The audio backends call this when a currently-opened device is lost. */
-void SDL_OpenedAudioDeviceDisconnected(SDL_AudioDevice *device)
+// this _also_ destroys the logical device!
+static void DisconnectLogicalAudioDevice(SDL_LogicalAudioDevice *logdev)
 {
-    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_EventEnabled(SDL_EVENT_AUDIO_DEVICE_REMOVED)) {
         SDL_Event event;
+        SDL_zero(event);
         event.type = SDL_EVENT_AUDIO_DEVICE_REMOVED;
         event.common.timestamp = 0;
-        event.adevice.which = device->id;
-        event.adevice.iscapture = device->iscapture ? 1 : 0;
+        event.adevice.which = logdev->instance_id;
+        event.adevice.iscapture = logdev->physical_device->iscapture ? 1 : 0;
         SDL_PushEvent(&event);
     }
-}
 
-static void mark_device_removed(void *handle, SDL_AudioDeviceItem *devices, SDL_bool *removedFlag)
-{
-    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;
-        }
-    }
+    DestroyLogicalAudioDevice(logdev);
 }
 
-/* The audio backends call this when a device is removed from the system. */
-void SDL_RemoveAudioDevice(const SDL_bool iscapture, void *handle)
+// Called when a device is removed from the system, or it fails unexpectedly, from any thread, possibly even the audio device's thread.
+void SDL_AudioDeviceDisconnected(SDL_AudioDevice *device)
 {
-    int device_index;
-    SDL_AudioDevice *device = NULL;
-    SDL_bool device_was_opened = SDL_FALSE;
-
-    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) {
-            device_was_opened = SDL_TRUE;
-            SDL_OpenedAudioDeviceDisconnected(device);
-            break;
-        }
+    if (!device) {
+        return;
     }
 
-    /* Devices that aren't opened, as of 2.24.0, will post an
-       SDL_EVENT_AUDIO_DEVICE_REMOVED event with the `which` field set to zero.
-       Apps can use this to decide if they need to refresh a list of
-       available devices instead of closing an opened one.
-       Note that opened devices will send the non-zero event in
-       SDL_OpenedAudioDeviceDisconnected(). */
-    if (!device_was_opened) {
-        if (SDL_EventEnabled(SDL_EVENT_AUDIO_DEVICE_REMOVED)) {
-            SDL_Event event;
-            event.type = SDL_EVENT_AUDIO_DEVICE_REMOVED;
-            event.common.timestamp = 0;
-            event.adevice.which = 0;
-            event.adevice.iscapture = iscapture ? 1 : 0;
-            SDL_PushEvent(&event);
+    // if the current default device is going down, mark it as dead but keep it around until a replacement is decided upon, so we can migrate logical devices to it.
+    if ((device->instance_id == current_audio.default_output_device_id) || (device->instance_id == current_audio.default_capture_device_id)) {
+        SDL_LockMutex(device->lock);  // make sure nothing else is messing with the device before continuing.
+        SDL_AtomicSet(&device->zombie, 1);
+        SDL_AtomicSet(&device->shutdown, 1);  // tell audio thread to terminate, but don't mark it condemned, so the thread won't destroy the device. We'll join on the audio thread later.
+
+        // dump any logical devices that explicitly opened this device. Things that opened the system default can stay.
+        SDL_LogicalAudioDevice *next = NULL;
+        for (SDL_LogicalAudioDevice *logdev = device->logical_devices; logdev != NULL; logdev = next) {
+            next = logdev->next;
+            if (!logdev->is_default) {  // if opened as a default, leave it on the zombie device for later migration.
+                DisconnectLogicalAudioDevice(logdev);
+            }
         }
+        SDL_UnlockMutex(device->lock);  // make sure nothing else is messing with the device before continuing.
+        return;  // done for now. Come back when a new default device is chosen!
     }
 
-    SDL_UnlockMutex(current_audio.detectionLock);
+    SDL_bool was_live = SDL_FALSE;
 
-    current_audio.impl.FreeDeviceHandle(handle);
-}
+    // take it out of the device list.
+    SDL_LockRWLockForWriting(current_audio.device_list_lock);
+    SDL_LockMutex(device->lock);  // make sure nothing else is messing with the device before continuing.
+    if (device == current_audio.output_devices) {
+        SDL_assert(device->prev == NULL);
+        current_audio.output_devices = device->next;
+        was_live = SDL_TRUE;
+    } else if (device == current_audio.capture_devices) {
+        SDL_assert(device->prev == NULL);
+        current_audio.capture_devices = device->next;
+        was_live = SDL_TRUE;
+    }
+    if (device->prev != NULL) {
+        device->prev->next = device->next;
+        was_live = SDL_TRUE;
+    }
+    if (device->next != NULL) {
+        device->next->prev = device->prev;
+        was_live = SDL_TRUE;
+    }
 
-/* buffer queueing support... */
+    device->next = NULL;
+    device->prev = NULL;
 
-static void SDLCALL SDL_BufferQueueDrainCallback(void *userdata, Uint8 *stream, int len)
-{
-    /* this function always holds the mixer lock before being called. */
-    SDL_AudioDevice *device = (SDL_AudioDevice *)userdata;
-    size_t dequeued;
+    if (was_live) {
+        SDL_AtomicAdd(device->iscapture ? &current_audio.capture_device_count : &current_audio.output_device_count, -1);
+    }
 
-    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?! */
+    SDL_UnlockRWLock(current_audio.device_list_lock);
 
-    dequeued = SDL_ReadFromDataQueue(device->buffer_queue, stream, len);
-    stream += dequeued;
-    len -= (int)dequeued;
+    // now device is not in the list, and we own it, so no one should be able to find it again, except the audio thread, which holds a pointer!
+    SDL_AtomicSet(&device->condemned, 1);
+    SDL_AtomicSet(&device->shutdown, 1);  // tell audio thread to terminate.
 
-    if (len > 0) { /* fill any remaining space in the stream with silence. */
-        SDL_assert(SDL_GetDataQueueSize(device->buffer_queue) == 0);
-        SDL_memset(stream, device->callbackspec.silence, len);
+    // disconnect each attached logical device, so apps won't find their streams still bound if they get the REMOVED event before the device thread cleans up.
+    SDL_LogicalAudioDevice *next;
+    for (SDL_LogicalAudioDevice *logdev = device->logical_devices; logdev != NULL; logdev = next) {
+        next = logdev->next;
+        DisconnectLogicalAudioDevice(logdev);
     }
-}
 
-static void SDLCALL SDL_BufferQueueFillCallback(void *userdata, Uint8 *stream, int len)
-{
-    /* this function always holds the mixer lock before being called. */
-    SDL_AudioDevice *device = (SDL_AudioDevice *)userdata;
+    // if there's an audio thread, don't free until thread is terminating, otherwise free stuff now.
+    const SDL_bool should_destroy = SDL_AtomicGet(&device->thread_alive) ? SDL_FALSE : SDL_TRUE;
+    SDL_UnlockMutex(device->lock);
 
-    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?! */
+    // Post the event, if we haven't tried to before and if it's desired
+    if (was_live && SDL_EventEnabled(SDL_EVENT_AUDIO_DEVICE_REMOVED)) {
+        SDL_Event event;
+        SDL_zero(event);
+        event.type = SDL_EVENT_AUDIO_DEVICE_REMOVED;
+        event.common.timestamp = 0;
+        event.adevice.which = device->instance_id;
+        event.adevice.iscapture = device->iscapture ? 1 : 0;
+        SDL_PushEvent(&event);
+    }
 
-    /* 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);
+    if (should_destroy) {
+        DestroyPhysicalAudioDevice(device);
+    }
 }
 
-int SDL_QueueAudio(SDL_AudioDeviceID devid, const void *data, Uint32 len)
-{
-    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");
-    }
+// stubs for audio drivers that don't need a specific entry point...
 
-    if (len > 0) {
-        current_audio.impl.LockDevice(device);
-        rc = SDL_WriteToDataQueue(device->buffer_queue, data, len);
-        current_audio.impl.UnlockDevice(device);
-    }
+static void SDL_AudioThreadDeinit_Default(SDL_AudioDevice *device) { /* no-op. */ }
+static void SDL_AudioWaitDevice_Default(SDL_AudioDevice *device) { /* no-op. */ }
+static void SDL_AudioPlayDevice_Default(SDL_AudioDevice *device, const Uint8 *buffer, int buffer_size) { /* no-op. */ }
+static void SDL_AudioWaitCaptureDevice_Default(SDL_AudioDevice *device) { /* no-op. */ }
+static void SDL_AudioFlushCapture_Default(SDL_AudioDevice *device) { /* no-op. */ }
+static void SDL_AudioCloseDevice_Default(SDL_AudioDevice *device) { /* no-op. */ }
+static void SDL_AudioDeinitialize_Default(void) { /* no-op. */ }
+static void SDL_AudioFreeDeviceHandle_Default(SDL_AudioDevice *device) { /* no-op. */ }
 
-    return rc;
+static void SDL_AudioThreadInit_Default(SDL_AudioDevice *device)
+{
+    SDL_SetThreadPriority(device->iscapture ? SDL_THREAD_PRIORITY_HIGH : SDL_THREAD_PRIORITY_TIME_CRITICAL);
 }
 
-Uint32 SDL_DequeueAudio(SDL_AudioDeviceID devid, void *data, Uint32 len)
+static void SDL_AudioDetectDevices_Default(SDL_AudioDevice **default_output, SDL_AudioDevice **default_capture)
 {
-    SDL_AudioDevice *device = get_audio_device(devid);
-    Uint32 rc;
+    // 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);
 
-    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. */
+    *default_output = SDL_AddAudioDevice(SDL_FALSE, DEFAULT_OUTPUT_DEVNAME, NULL, (void *)((size_t)0x1));
+    if (current_audio.impl.HasCaptureSupport) {
+        *default_capture = SDL_AddAudioDevice(SDL_TRUE, DEFAULT_INPUT_DEVNAME, NULL, (void *)((size_t)0x2));
     }
+}
 
-    current_audio.impl.LockDevice(device);
-    rc = (Uint32)SDL_ReadFromDataQueue(device->buffer_queue, data, len);
-    current_audio.impl.UnlockDevice(device);
-    return rc;
+static Uint8 *SDL_AudioGetDeviceBuf_Default(SDL_AudioDevice *device, int *buffer_size)
+{
+    *buffer_size = 0;
+    return NULL;
 }
 
-Uint32 SDL_GetQueuedAudioSize(SDL_AudioDeviceID devid)
+static int SDL_AudioCaptureFromDevice_Default(SDL_AudioDevice *device, void *buffer, int buflen)
 {
-    Uint32 retval = 0;
-    SDL_AudioDevice *device = get_audio_device(devid);
+    return SDL_Unsupported();
+}
 
-    if (!device) {
-        return 0;
-    }
+static int SDL_AudioOpenDevice_Default(SDL_AudioDevice *device)
+{
+    return SDL_Unsupported();
+}
 
-    /* Nothing to do unless we're set up for queueing. */
-    if (device->callbackspec.callback == SDL_BufferQueueDrainCallback ||
-        device->callbackspec.callback == SDL_BufferQueueFillCallback) {
-        current_audio.impl.LockDevice(device);
-        retval = (Uint32)SDL_GetDataQueueSize(device->buffer_queue);
-        current_audio.impl.UnlockDevice(device);
-    }
+// Fill in stub functions for unused driver entry points. This lets us blindly call them without having to check for validity first.
+static void CompleteAudioEntryPoints(void)
+{
+    #define FILL_STUB(x) if (!current_audio.impl.x) { current_audio.impl.x = SDL_Audio##x##_Default; }
+    FILL_STUB(DetectDevices);
+    FILL_STUB(OpenDevice);
+    FILL_STUB(ThreadInit);
+    FILL_STUB(ThreadDeinit);
+    FILL_STUB(WaitDevice);
+    FILL_STUB(PlayDevice);
+    FILL_STUB(GetDeviceBuf);
+    FILL_STUB(WaitCaptureDevice);
+    FILL_STUB(CaptureFromDevice);
+    FILL_STUB(FlushCapture);
+    FILL_STUB(CloseDevice);
+    FILL_STUB(FreeDeviceHandle);
+    FILL_STUB(Deinitialize);
+    #undef FILL_STUB
+}
 
+static SDL_AudioDeviceID GetFirstAddedAudioDeviceID(const SDL_bool iscapture)
+{
+    // (these are pushed to the front of the linked list as added, so the first device added is last in the list.)
+    SDL_LockRWLockForReading(current_audio.device_list_lock);
+    SDL_AudioDevice *last = NULL;
+    for (SDL_AudioDevice *i = iscapture ? current_audio.capture_devices : current_audio.output_devices; i != NULL; i = i->next) {
+        last = i;
+    }
+    const SDL_AudioDeviceID retval = last ? last->instance_id : 0;
+    SDL_UnlockRWLock(current_audio.device_list_lock);
     return retval;
 }
 
-int SDL_ClearQueuedAudio(SDL_AudioDeviceID devid)
+// !!! FIXME: the video subsystem does SDL_VideoInit, not SDL_InitVideo. Make this match.
+int SDL_InitAudio(const char *driver_name)
 {
-    SDL_AudioDevice *device = get_audio_device(devid);
-    if (!device) {
-        return SDL_InvalidParamError("devid");
+    if (SDL_GetCurrentAudioDriver()) {
+        SDL_QuitAudio(); // shutdown driver if already running.
     }
 
-    /* Blank out the device and release the mutex. Free it afterwards. */
-    current_audio.impl.LockDevice(device);
+    SDL_ChooseAudioConverters();
 
-    /* Keep up to two packets in the pool to reduce future memory allocation pressure. */
-    SDL_ClearDataQueue(device->buffer_queue, SDL_AUDIOBUFFERQUEUE_PACKETLEN * 2);
+    SDL_RWLock *device_list_lock = SDL_CreateRWLock();  // create this early, so if it fails we don't have to tear down the whole audio subsystem.
+    if (!device_list_lock) {
+        return -1;
+    }
 
-    current_audio.impl.UnlockDevice(device);
-    return 0;
-}
+    // Select the proper audio driver
+    if (driver_name == NULL) {
+        driver_name = SDL_GetHint(SDL_HINT_AUDIO_DRIVER);
+    }
 
-#ifdef SDL_AUDIO_DRIVER_ANDROID
-extern void Android_JNI_AudioSetThreadPriority(int, int);
-#endif
+    SDL_bool initialized = SDL_FALSE;
+    SDL_bool tried_to_init = SDL_FALSE;
 
-/* The general mixing thread function */
-static int SDLCALL SDL_RunAudio(void *devicep)
-{
-    SDL_AudioDevice *device = (SDL_AudioDevice *)devicep;
-    void *udata = device->callbackspec.userdata;
-    SDL_AudioCallback callback = device->callbackspec.callback;
-    int data_len = 0;
-    Uint8 *data;
+    if (driver_name != NULL && *driver_name != 0) {
+        char *driver_name_copy = SDL_strdup(driver_name);
+        const char *driver_attempt = driver_name_copy;
 
-    SDL_assert(!device->iscapture);
+        if (driver_name_copy == NULL) {
+            SDL_DestroyRWLock(device_list_lock);
+            return SDL_OutOfMemory();
+        }
 
-#ifdef SDL_AUDIO_DRIVER_ANDROID
-    {
-        /* Set thread priority to THREAD_PRIORITY_AUDIO */
-        Android_JNI_AudioSetThreadPriority(device->iscapture, device->id);
-    }
-#else
-    /* The audio mixing is always a high priority thread */
-    SDL_SetThreadPriority(SDL_THREAD_PRIORITY_TIME_CRITICAL);
-#endif
+        while (driver_attempt != NULL && *driver_attempt != 0 && !initialized) {
+            char *driver_attempt_end = SDL_strchr(driver_attempt, ',');
+            if (driver_attempt_end != NULL) {
+                *driver_attempt_end = '\0';
+            }
 
-    /* Perform any thread setup */
-    device->threadid = SDL_ThreadID();
-    current_audio.impl.ThreadInit(device);
+            // SDL 1.2 uses the name "dsound", so we'll support both.
+            if (SDL_strcmp(driver_attempt, "dsound") == 0) {
+                driver_attempt = "directsound";
+            } else if (SDL_strcmp(driver_attempt, "pulse") == 0) {  // likewise, "pulse" was renamed to "pulseaudio"
+                driver_attempt = "pulseaudio";
+            }
 
-    /* Loop, filling the audio buffers */
-    while (!SDL_AtomicGet(&device->shutdown)) {
-        data_len = device->callbackspec.size;
+            for (int i = 0; bootstrap[i]; ++i) {
+                if (SDL_strcasecmp(bootstrap[i]->name, driver_attempt) == 0) {
+                    tried_to_init = SDL_TRUE;
+                    SDL_zero(current_audio);
+                    SDL_AtomicSet(&current_audio.last_device_instance_id, 2);  // start past 1 because of SDL2's legacy interface.
+                    current_audio.device_list_lock = device_list_lock;
+                    if (bootstrap[i]->init(&current_audio.impl)) {
+                        current_audio.name = bootstrap[i]->name;
+                        current_audio.desc = bootstrap[i]->desc;
+                        initialized = SDL_TRUE;
+                    }
+                    break;
+                }
+            }
 
-        /* Fill the current buffer with sound */
-        if (!device->stream && SDL_AtomicGet(&device->enabled)) {
-            SDL_assert((Uint32)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;
+            driver_attempt = (driver_attempt_end != NULL) ? (driver_attempt_end + 1) : NULL;
         }
 
-        if (data == NULL) {
-            data = device->work_buffer;
-        }
+        SDL_free(driver_name_copy);
+    } else {
+        for (int i = 0; (!initialized) && (bootstrap[i]); ++i) {
+            if (bootstrap[i]->demand_only) {
+                continue;
+            }
 
-        /* !!! FIXME: this should be LockDevice. */
-        SDL_LockMutex(device->mixer_lock);
-        if (SDL_AtomicGet(&device->paused)) {
-            SDL_memset(data, device->callbackspec.silence, data_len);
-        } else {
-            callback(udata, data, data_len);
+            tried_to_init = SDL_TRUE;
+            SDL_zero(current_audio);
+            SDL_AtomicSet(&current_audio.last_device_instance_id, 2);  // start past 1 because of SDL2's legacy interface.
+            current_audio.device_list_lock = device_list_lock;
+            if (bootstrap[i]->init(&current_audio.impl)) {
+                current_audio.name = bootstrap[i]->name;
+                current_audio.desc = bootstrap[i]->desc;
+                initialized = SDL_TRUE;
+            }
         }
-        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_PutAudioStreamData(device->stream, data, data_len);
-
-            while (SDL_GetAudioStreamAvailable(device->stream) >= ((int)device->spec.size)) {
-                int got;
-                data = SDL_AtomicGet(&device->enabled) ? current_audio.impl.GetDeviceBuf(device) : NULL;
-                got = SDL_GetAudioStreamData(device->stream, data ? data : device->work_buffer, device->spec.size);
-                SDL_assert((got <= 0) || ((Uint32)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 ((Uint32)got != device->spec.size) {
-                        SDL_memset(data, device->spec.silence, device->spec.size);
-                    }
-                    current_audio.impl.PlayDevice(device);
-                    current_audio.impl.WaitDevice(device);
-                }
+    }
+
+    if (!initialized) {
+        // specific drivers will set the error message if they fail, but otherwise we do it here.
+        if (!tried_to_init) {
+            if (driver_name) {
+                SDL_SetError("Audio target '%s' not available", driver_name);
+            } else {
+                SDL_SetError("No available audio 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);
         }
+
+        SDL_zero(current_audio);
+        SDL_DestroyRWLock(device_list_lock);
+        current_audio.device_list_lock = NULL;
+        return -1;  // No driver was available, so fail.
     }
 
-    /* Wait for the audio to drain. */
-    SDL_Delay(((device->spec.samples * 1000) / device->spec.freq) * 2);
+    CompleteAudioEntryPoints();
 
-    current_audio.impl.ThreadDeinit(device);
+    // Make sure we have a list of devices available at startup...
+    SDL_AudioDevice *default_output = NULL;
+    SDL_AudioDevice *default_capture = NULL;
+    current_audio.impl.DetectDevices(&default_output, &default_capture);
+
+    // these are only set if default_* is non-NULL, in case the backend just called SDL_DefaultAudioDeviceChanged directly during DetectDevices.
+    if (default_output) {
+        current_audio.default_output_device_id = default_output->instance_id;
+    }
+    if (default_capture) {
+        current_audio.default_capture_device_id = default_capture->instance_id;
+    }
+
+    // If no default was _ever_ specified, just take the first device we see, if any.
+    if (!current_audio.default_output_device_id) {
+        current_audio.default_output_device_id = GetFirstAddedAudioDeviceID(/*iscapture=*/SDL_FALSE);
+    }
+    if (!current_audio.default_capture_device_id) {
+        current_audio.default_capture_device_id = GetFirstAddedAudioDeviceID(/*iscapture=*/SDL_TRUE);
+    }
 
     return 0;
 }
 
-/* !!! FIXME: this needs to deal with device spec changes. */
-/* The general capture thread function */
-static int SDLCALL SDL_CaptureAudio(void *devicep)
+void SDL_QuitAudio(void)
 {
-    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;
+    if (!current_audio.name) {  // not initialized?!
+        return;
+    }
 
-    SDL_assert(device->iscapture);
+    // merge device lists so we don't have to duplicate work below.
+    SDL_LockRWLockForWriting(current_audio.device_list_lock);
+    SDL_AtomicSet(&current_audio.shutting_down, 1);
+    SDL_AudioDevice *devices = NULL;
+    for (SDL_AudioDevice *i = current_audio.output_devices; i != NULL; i = i->next) {
+        devices = i;
+    }
+    if (!devices) {
+        devices = current_audio.capture_devices;
+    } else {
+        SDL_assert(devices->next == NULL);
+        devices->next = current_audio.capture_devices;
+        devices = current_audio.output_devices;
+    }
+    current_audio.output_devices = NULL;
+    current_audio.capture_devices = NULL;
+    SDL_AtomicSet(&current_audio.output_device_count, 0);
+    SDL_AtomicSet(&current_audio.capture_device_count, 0);
+    SDL_UnlockRWLock(current_audio.device_list_lock);
+    
+    // mark all devices for shutdown so all threads can begin to terminate.
+    for (SDL_AudioDevice *i = devices; i != NULL; i = i->next) {
+        SDL_AtomicSet(&i->shutdown, 1);
+    }
+
+    // now wait on any audio threads...
+    for (SDL_AudioDevice *i = devices; i != NULL; i = i->next) {
+        if (i->thread) {
+            SDL_assert(!SDL_AtomicGet(&i->condemned));  // these shouldn't have been in the device list still, and thread should have detached.
+            SDL_WaitThread(i->thread, NULL);
+            i->thread = NULL;
+        }
+    }
 
-#ifdef SDL_AUDIO_DRIVER_ANDROID
-    {
-        /* Set thread priority to THREAD_PRIORITY_AUDIO */
-        Android_JNI_AudioSetThreadPriority(device->iscapture, device->id);
+    while (devices) {
+        SDL_AudioDevice *next = devices->next;
+        DestroyPhysicalAudioDevice(devices);
+        devices = next;
     }
-#else
-    /* The audio mixing is always a high priority thread */
-    SDL_SetThreadPriority(SDL_THREAD_PRIORITY_HIGH);
-#endif
 
-    /* Perform any thread setup */
-    device->threadid = SDL_ThreadID();
-    current_audio.impl.ThreadInit(device);
+    // Free the driver data
+    current_audio.impl.Deinitialize();
 
-    /* Loop, filling the audio buffers */
-    while (!SDL_AtomicGet(&device->shutdown)) {
-        int still_need;
-        Uint8 *ptr;
+    SDL_DestroyRWLock(current_audio.device_list_lock);
 
-        if (SDL_AtomicGet(&device->paused)) {
-            SDL_Delay(delay); /* just so we don't cook the CPU. */
-            if (device->stream) {
-                SDL_ClearAudioStream(device->stream);
-            }
-            current_audio.impl.FlushCapture(device); /* dump anything pending. */
-            continue;
-        }
+    SDL_zero(current_audio);
+}
 
-        /* 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);
+void SDL_AudioThreadFinalize(SDL_AudioDevice *device)
+{
+    if (SDL_AtomicGet(&device->condemned)) {
+        if (device->thread) {
+            SDL_DetachThread(device->thread);  // no one is waiting for us, just detach ourselves.
+            device->thread = NULL;
+            SDL_AtomicSet(&device->thread_alive, 0);
+        }
+        DestroyPhysicalAudioDevice(device);
+    }
+    SDL_AtomicSet(&device->thread_alive, 0);
+}
 
-        ptr = data;
+// Output device thread. This is split into chunks, so backends that need to control this directly can use the pieces they need without duplicating effort.
 
-        /* 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. */
+void SDL_OutputAudioThreadSetup(SDL_AudioDevice *device)
+{
+    SDL_assert(!device->iscapture);
+    current_audio.impl.ThreadInit(device);
+}
 
-        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;
-                }
-            }
-        }
+SDL_bool SDL_OutputAudioThreadIterate(SDL_AudioDevice *device)
+{
+    SDL_assert(!device->iscapture);
 
-        if (still_need > 0) {
-            /* Keep any data we already read, silence the rest. */
-            SDL_memset(ptr, silence, still_need);
-        }
+    SDL_LockMutex(device->lock);
 
-        if (device->stream) {
-            /* if this fails...oh well. */
-            SDL_PutAudioStreamData(device->stream, data, data_len);
+    if (SDL_AtomicGet(&device->shutdown)) {
+        SDL_UnlockMutex(device->lock);
+        return SDL_FALSE;  // we're done, shut it down.
+    }
 
-            while (SDL_GetAudioStreamAvailable(device->stream) >= ((int)device->callbackspec.size)) {
-                const int got = SDL_GetAudioStreamData(device->stream, device->work_buffer, device->callbackspec.size);
-                SDL_assert((got < 0) || ((Uint32)got == device->callbackspec.size));
-                if ((Uint32)got != device->callbackspec.size) {
-                    SDL_memset(device->work_buffer, device->spec.silence, device->callbackspec.size);
-                }
+    SDL_bool retval = SDL_TRUE;
+    int buffer_size = device->buffer_size;
+    Uint8 *mix_buffer = current_audio.impl.GetDeviceBuf(device, &buffer_size);
+    if (!mix_buffer) {
+        retval = SDL_FALSE;
+    } else {
+        SDL_assert(buffer_size <= device->buffer_size);  // you can ask for less, but not more.
+        SDL_memset(mix_buffer, device->silence_value, buffer_size);  // start with silence.
 
-                /* !!! 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);
+        for (SDL_LogicalAudioDevice *logdev = device->logical_devices; logdev != NULL; logdev = logdev->next) {
+            if (SDL_AtomicGet(&logdev->paused)) {
+                continue;  // paused? Skip this logical device.
             }
-        } 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);
+
+            for (SDL_AudioStream *stream = logdev->bound_streams; stream != NULL; stream = stream->next_binding) {
+                /* this will hold a lock on `stream` while getting. We don't explicitly lock the streams
+                   for iterating here because the binding linked list can only change while the device lock is held.
+                   (we _do_ lock the stream during binding/unbinding to make sure that two threads can't try to bind
+                   the same stream to different devices at the same time, though.) */
+                const int br = SDL_GetAudioStreamData(stream, device->work_buffer, buffer_size);
+                if (br < 0) {
+                    // oh crud, we probably ran out of memory. This is possibly an overreaction to kill the audio device, but it's likely the whole thing is going down in a moment anyhow.
+                    retval = SDL_FALSE;
+                    break;
+                } else if (br > 0) {  // it's okay if we get less than requested, we mix what we have.
+                    // !!! FIXME: this needs to mix to float32 or int32, so we don't clip.
+                    if (SDL_MixAudioFormat(mix_buffer, device->work_buffer, device->spec.format, br, SDL_MIX_MAXVOLUME) < 0) {  // !!! FIXME: allow streams to specify gain?
+                        SDL_assert(!"We probably ended up with some totally unexpected audio format here");
+                        retval = SDL_FALSE;  // uh...?
+                        break;
+                    }
+                }
             }
-            SDL_UnlockMutex(device->mixer_lock);
         }
+
+        // !!! FIXME: have PlayDevice return a value and do disconnects in here with it.
+        current_audio.impl.PlayDevice(device, mix_buffer, buffer_size);  // this SHOULD NOT BLOCK, as we are holding a lock right now. Block in WaitDevice!
     }
 
-    current_audio.impl.FlushCapture(device);
+    SDL_UnlockMutex(device->lock);
 
-    current_audio.impl.ThreadDeinit(device);
+    if (!retval) {
+        SDL_AudioDeviceDisconnected(device);  // doh.
+    }
 
-    return 0;
+    return retval;
 }
 
-static SDL_AudioFormat SDL_ParseAudioFormat(const char *string)
-{
-#define CHECK_FMT_STRING(x)          \
-    if (SDL_strcmp(string, #x) == 0) \
-    return SDL_AUDIO_##x
-    CHECK_FMT_STRING(U8);
-    CHECK_FMT_STRING(S8);
-    CHECK_FMT_STRING(S16LSB);
-    CHECK_FMT_STRING(S16MSB);
-    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_OutputAudioThreadShutdown(SDL_AudioDevice *device)
+{
+    SDL_assert(!device->iscapture);
+    const int samples = (device->buffer_size / (SDL_AUDIO_BITSIZE(device->spec.format) / 8)) / device->spec.channels;
+    // Wait for the audio to drain. !!! FIXME: don't bother waiting if device is lost.
+    SDL_Delay(((samples * 1000) / device->spec.freq) * 2);
+    current_audio.impl.ThreadDeinit(device);
+    SDL_AudioThreadFinalize(device);
 }
 
-int SDL_GetNumAudioDrivers(void)
+static int SDLCALL OutputAudioThread(void *devicep)  // thread entry point
 {
-    return SDL_arraysize(bootstrap) - 1;
+    SDL_AudioDevice *device = (SDL_AudioDevice *)devicep;
+    SDL_assert(device != NULL);
+    SDL_assert(!device->iscapture);
+    SDL_OutputAudioThreadSetup(device);
+    do {
+        current_audio.impl.WaitDevice(device);
+    } while (SDL_OutputAudioThreadIterate(device));
+
+    SDL_OutputAudioThreadShutdown(device);
+    return 0;
 }
 
-const char *SDL_GetAudioDriver(int index)
+
+
+// Capture device thread. This is split into chunks, so backends that need to control this directly can use the pieces they need without duplicating effort.
+
+void SDL_CaptureAudioThreadSetup(SDL_AudioDevice *device)
 {
-    if (index >= 0 && index < SDL_GetNumAudioDrivers()) {
-        return bootstrap[index]->name;
-    }
-    return NULL;
+    SDL_assert(device->iscapture);
+    current_audio.impl.ThreadInit(device);
 }
 
-int SDL_InitAudio(const char *driver_name)
+SDL_bool SDL_CaptureAudioThreadIterate(SDL_AudioDevice *device)
 {
-    int i;
-    SDL_bool initialized = SDL_FALSE, tried_to_init = SDL_FALSE;
+    SDL_assert(device->iscapture);
 
-    if (SDL_GetCurrentAudioDriver()) {
-        SDL_QuitAudio(); /* shutdown driver if already running. */
+    SDL_LockMutex(device->lock);
+
+    SDL_bool retval = SDL_TRUE;
+
+    if (SDL_AtomicGet(&device->shutdown)) {
+        retval = SDL_FALSE;  // we're done, shut it down.
+    } else if (device->logical_devices == NULL) {
+        current_audio.impl.FlushCapture(device); // nothing wants data, dump anything pending.
+    } else {
+        // this SHOULD NOT BLOCK, as we are holding a lock right now. Block in WaitCaptureDevice!
+        const int rc = current_audio.impl.CaptureFromDevice(device, device->work_buffer, device->buffer_size);
+        if (rc < 0) {  // uhoh, device failed for some reason!
+            retval = SDL_FALSE;
+        } else if (rc > 0) {  // queue the new data to each bound stream.
+            for (SDL_LogicalAudioDevice *logdev = device->logical_devices; logdev != NULL; logdev = logdev->next) {
+                if (SDL_AtomicGet(&logdev->paused)) {
+                    continue;  // paused? Skip this logical device.
+                }
+
+                for (SDL_AudioStream *stream = logdev->bound_streams; stream != NULL; stream = stream->next_binding) {
+                    /* this will hold a lock on `stream` while putting. We don't explicitly lock the streams
+                       for iterating here because the binding linked list can only change while the device lock is held.
+                       (we _do_ lock the stream during binding/unbinding to make sure that two threads can't try to bind
+                       the same stream to different devices at the same time, though.) */
+                    if (SDL_PutAudioStreamData(stream, device->work_buffer, rc) < 0) {
+                        // oh crud, we probably ran out of memory. This is possibly an overreaction to kill the audio device, but it's likely the whole thing is going down in a moment anyhow.
+                        retval = SDL_FALSE;
+                        break;
+                    }
+                }
+            }
+        }
     }
 
-    SDL_zeroa(open_devices);
+    SDL_UnlockMutex(device->lock);
 
-    /* Select the proper audio driver */
-    if (driver_name == NULL) {
-        driver_name = SDL_GetHint(SDL_HINT_AUDIO_DRIVER);
+    if (!retval) {
+        SDL_AudioDeviceDisconnected(device);  // doh.
     }
 
-    if (driver_name != NULL && *driver_name != 0) {
-        const char *driver_attempt = driver_name;
-        while (driver_attempt != NULL && *driver_attempt != 0 && !initialized) {
-            const char *driver_attempt_end = SDL_strchr(driver_attempt, ',');
-            size_t driver_attempt_len = (driver_attempt_end != NULL) ? (driver_attempt_end - driver_attempt)
-                                                                     : SDL_strlen(driver_attempt);
-#ifdef SDL_AUDIO_DRIVER_DSOUND
-            /* SDL 1.2 uses the name "dsound", so we'll support both. */
-            if (driver_attempt_len == SDL_strlen("dsound") &&
-                (SDL_strncasecmp(driver_attempt, "dsound", driver_attempt_len) == 0)) {
-                driver_attempt = "directsound";
-                driver_attempt_len = SDL_strlen("directsound");
-            }
-#endif
+    return retval;
+}
 
-#ifdef SDL_AUDIO_DRIVER_PULSEAUDIO
-            /* SDL 1.2 uses the name "pulse", so we'll support both. */
-            if (driver_attempt_len == SDL_strlen("pulse") &&
-                (SDL_strncasecmp(driver_attempt, "pulse", driver_attempt_len) == 0)) {
-                driver_attempt = "pulseaudio";
-                driver_attempt_len = SDL_strlen("pulseaudio");
-            }
-#endif
+void SDL_CaptureAudioThreadShutdown(SDL_AudioDevice *device)
+{
+    SDL_assert(device->iscapture);
+    current_audio.impl.FlushCapture(device);
+    current_audio.impl.ThreadDeinit(device);
+    SDL_AudioThreadFinalize(device);
+}
 
-            for (i = 0; bootstrap[i]; ++i) {
-                if ((driver_attempt_len == SDL_strlen(bootstrap[i]->name)) &&
-                    (SDL_strncasecmp(bootstrap[i]->name, driver_attempt, driver_attempt_len) == 0)) {
-                    tried_to_init = SDL_TRUE;
-                    SDL_zero(current_audio);
-                    current_audio.name = bootstrap[i]->name;
-                    current_audio.desc = bootstrap[i]->desc;
-                    initialized = bootstrap[i]->init(&current_audio.impl);
-                    break;
-                }
-            }
+static int SDLCALL CaptureAudioThread(void *devicep)  // thread entry point
+{
+    SDL_AudioDevice *device = (SDL_AudioDevice *)devicep;
+    SDL_assert(device != NULL);
+    SDL_assert(device->iscapture);
+    SDL_CaptureAudioThreadSetup(device);
 
-            driver_attempt = (driver_attempt_end != NULL) ? (driver_attempt_end + 1) : NULL;
-        }
-    } else {
-        for (i = 0; (!initialized) && (bootstrap[i]); ++i) {
-            if (bootstrap[i]->demand_only) {
-                continue;
-            }
+    do {
+        current_audio.impl.WaitCaptureDevice(device);
+    } while (SDL_CaptureAudioThreadIterate(device));
 
-            tried_to_init = SDL_TRUE;
-            SDL_zero(current_audio);
-            current_audio.name = bootstrap[i]->name;
-            current_audio.desc = bootstrap[i]->desc;
-            initialized = bootstrap[i]->init(&current_audio.impl);
-        }
-    }
+    SDL_CaptureAudioThreadShutdown(device);
+    return 0;
+}
 
-    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. */
+static SDL_AudioDeviceID *GetAudioDevices(int *reqcount, SDL_AudioDevice **devices, SDL_AtomicInt *device_count)
+{
+    if (!SDL_GetCurrentAudioDriver()) {
+        SDL_SetError("Audio subsystem is not initialized");
+        return NULL;
     }
 
-    current_audio.detectionLock = SDL_CreateMutex();
+    SDL_LockRWLockForReading(current_audio.device_list_lock);
+    int num_devices = SDL_AtomicGet(device_count);
+    SDL_AudioDeviceID *retval = (SDL_AudioDeviceID *) SDL_malloc((num_devices + 1) * sizeof (SDL_AudioDeviceID));
+    if (retval == NULL) {
+        num_devices = 0;
+        SDL_OutOfMemory();
+    } else {
+        const SDL_AudioDevice *dev = *devices;  // pointer to a pointer so we can dereference it after the lock is held.
+        for (int i = 0; i < num_devices; i++) {
+            SDL_assert(dev != NULL);
+            SDL_assert(!SDL_AtomicGet((SDL_AtomicInt *) &dev->condemned));  // shouldn't be in the list if pending deletion.
+            retval[i] = dev->instance_id;
+            dev = dev->next;
+        }
+        SDL_assert(dev == NULL);  // did the whole list?
+        retval[num_devices] = 0;  // null-terminated.
+    }
+    SDL_UnlockRWLock(current_audio.device_list_lock);
 
-    finish_audio_entry_points_init();
+    if (reqcount != NULL) {
+        *reqcount = num_devices;
+    }
 
-    /* Make sure we have a list of devices available at startup. */
-    current_audio.impl.DetectDevices();
+    return retval;
+}
 
-    return 0;
+SDL_AudioDeviceID *SDL_GetAudioOutputDevices(int *count)
+{
+    return GetAudioDevices(count, &current_audio.output_devices, &current_audio.output_device_count);
 }
 
-/*
- * Get the current audio driver name
- */
-const char *SDL_GetCurrentAudioDriver(void)
+SDL_AudioDeviceID *SDL_GetAudioCaptureDevices(int *count)
 {
-    return current_audio.name;
+    return GetAudioDevices(count, &current_audio.capture_devices, &current_audio.capture_device_count);
 }
 
-/* Clean out devices that we've removed but had to keep around for stability. */
-static void clean_out_device_list(SDL_AudioDeviceItem **devices, int *devCount, SDL_bool *removedFlag)
+// If found, this locks _the physical device_ this logical device is associated with, before returning.
+static SDL_LogicalAudioDevice *ObtainLogicalAudioDevice(SDL_AudioDeviceID devid)
 {
-    SDL_AudioDeviceItem *item = *devices;
-    SDL_AudioDeviceItem *prev = NULL;
-    int total = 0;
+    if (!SDL_GetCurrentAudioDriver()) {
+        SDL_SetError("Audio subsystem is not initialized");
+        return NULL;
+    }
 
-    while (item) {
-        SDL_AudioDeviceItem *next = item->next;
-        if (item->handle != NULL) {
-            total++;
-            prev = item;
-        } else {
-            if (prev) {
-                prev->next = next;
-            } else {
-                *devices = next;
+    SDL_LogicalAudioDevice *logdev = NULL;
+
+    const SDL_bool islogical = (devid & (1<<1)) ? SDL_FALSE : SDL_TRUE;
+    if (islogical) {  // don't bother looking if it's not a logical device id value.
+        const SDL_bool iscapture = (devid & (1<<0)) ? SDL_FALSE : SDL_TRUE;
+
+        SDL_LockRWLockForReading(current_audio.device_list_lock);
+
+        for (SDL_AudioDevice *device = iscapture ? current_audio.capture_devices : current_audio.output_devices; device != NULL; device = device->next) {
+            SDL_LockMutex(device->lock);  // caller must unlock if we choose a logical device from this guy.
+            SDL_assert(!SDL_AtomicGet(&device->condemned));  // shouldn't be in the list if pending deletion.
+            for (logdev = device->logical_devices; logdev != NULL; logdev = logdev->next) {
+                if (logdev->instance_id == devid) {
+                    break; // found it!
+                }
             }
-            /* these two pointers are the same if not a duplicate devname */
-            if (item->name != item->original_name) {
-                SDL_free(item->name);
+            if (logdev != NULL) {
+                break;
             }
-            SDL_free(item->original_name);
-            SDL_free(item);
+            SDL_UnlockMutex(device->lock);  // give up this lock and try the next physical device.
         }
-        item = next;
+
+        SDL_UnlockRWLock(current_audio.device_list_lock);
     }
 
-    *devCount = total;
-    *removedFlag = SDL_FALSE;
+    if (!logdev) {
+        SDL_SetError("Invalid audio device instance ID");
+    }
+
+    return logdev;
 }
 
-int SDL_GetNumAudioDevices(int iscapture)
+/* this finds the physical device associated with `devid` and locks it for use.
+   Note that a logical device instance id will return its associated physical device! */
+static SDL_AudioDevice *ObtainPhysicalAudioDevice(SDL_AudioDeviceID devid)
 {
-    int retval = 0;
+    // bit #1 of devid is set for physical devices and unset for logical.
+    const SDL_bool islogical = (devid & (1<<1)) ? SDL_FALSE : SDL_TRUE;
+    if (islogical) {
+        SDL_LogicalAudioDevice *logdev = ObtainLogicalAudioDevice(devid);
+        if (logdev) {
+            return logdev->physical_device;
+        }
+        return NULL;
+    }
 
     if (!SDL_GetCurrentAudioDriver()) {
-        return -1;
+        SDL_SetError("Audio subsystem is not initialized");
+        return NULL;
     }
 
-    SDL_LockMutex(current_audio.detectionLock);
-    if (iscapture && current_audio.captureDevicesRemoved) {
-        clean_out_device_list(&current_audio.inputDevices, &current_audio.inputDeviceCount, &current_audio.captureDevicesRemoved);
-    }
+    // bit #0 of devid is set for output devices and unset for capture.
+    const SDL_bool iscapture = (devid & (1<<0)) ? SDL_FALSE : SDL_TRUE;
+    SDL_AudioDevice *dev = NULL;
 
-    if (!iscapture && current_audio.outputDevicesRemoved) {
-        clean_out_device_list(&current_audio.outputDevices, &current_audio.outputDeviceCount, &current_audio.outputDevicesRemoved);
+    SDL_LockRWLockForReading(current_audio.device_list_lock);
+
+    for (dev = iscapture ? current_audio.capture_devices : current_audio.output_devices; dev != NULL; dev = dev->next) {
+        if (dev->instance_id == devid) {  // found it?
+            SDL_LockMutex(dev->lock);  // caller must unlock.
+            SDL_assert(!SDL_AtomicGet(&dev->condemned));  // shouldn't be in the list if pending deletion.
+            break;
+        }
     }
 
-    retval = iscapture ? current_audio.inputDeviceCount : current_audio.outputDeviceCount;
-    SDL_UnlockMutex(current_audio.detectionLock);
+    SDL_UnlockRWLock(current_audio.device_list_lock);
 
-    return retval;
+    if (!dev) {
+        SDL_SetError("Invalid audio device instance ID");
+    }
+
+    return dev;
 }
 
-const char *SDL_GetAudioDeviceName(int index, int iscapture)
+SDL_AudioDevice *SDL_FindPhysicalAudioDeviceByCallback(SDL_bool (*callback)(SDL_AudioDevice *device, void *userdata), void *userdata)
 {
-    SDL_AudioDeviceItem *item;
-    int i;
-    const char *retval;
-
     if (!SDL_GetCurrentAudioDriver()) {
         SDL_SetError("Audio subsystem is not initialized");
         return NULL;
     }
 
-    SDL_LockMutex(current_audio.detectionLock);
-    item = iscapture ? current_audio.inputDevices : current_audio.outputDevices;
-    i = iscapture ? current_audio.inputDeviceCount : current_audio.outputDeviceCount;
-    if (index >= 0 && index < i) {
-        for (i--; i > index; i--, item = item->next) {
-            SDL_assert(item != NULL);
+    SDL_LockRWLockForReading(current_audio.device_list_lock);
+
+    SDL_AudioDevice *dev = NULL;
+    for (dev = current_audio.output_devices; dev != NULL; dev = dev->next) {
+        if (callback(dev, userdata)) {  // found it?
+            break;
         }
-        SDL_assert(item != NULL);
-        retval = item->name;
-    } else {
-        SDL_InvalidParamError("index");
-        retval = NULL;
     }
-    SDL_UnlockMutex(current_audio.detectionLock);
 
-    return retval;
+    if (!dev) {
+        // !!! FIXME: code duplication, from above.
+        for (dev = current_audio.capture_devices; dev != NULL; dev = dev->next) {
+            if (callback(dev, userdata)) {  // found it?
+                break;
+            }
+        }
+    }
+
+    SDL_UnlockRWLock(current_audio.device_list_lock);
+
+    if (!dev) {
+        SDL_SetError("Device not found");
+    }
+
+    SDL_assert(!dev || !SDL_AtomicGet(&dev->condemned));  // shouldn't be in the list if pending deletion.
+
+    return dev;
 }
 
-int SDL_GetAudioDeviceSpec(int index, int iscapture, SDL_AudioSpec *spec)
+static SDL_bool TestDeviceHandleCallback(SDL_AudioDevice *device, void *handle)
 {
-    SDL_AudioDeviceItem *item;
-    int i, retval;
+    return device->handle == handle;
+}
 
-    if (spec == NULL) {
-        return SDL_InvalidParamError("spec");
-    }
+SDL_AudioDevice *SDL_FindPhysicalAudioDeviceByHandle(void *handle)
+{
+    return SDL_FindPhysicalAudioDeviceByCallback(TestDeviceHandleCallback, handle);
+}
 
-    if (!SDL_GetCurrentAudioDriver()) {
-        return SDL_SetError("Audio subsystem is not initialized");
+char *SDL_GetAudioDeviceName(SDL_AudioDeviceID devid)
+{
+    SDL_AudioDevice *device = ObtainPhysicalAudioDevice(devid);
+    if (!device) {
+        return NULL;
     }
 
-    SDL_LockMutex(current_audio.detectionLock);
-    item = iscapture ? current_audio.inputDevices : current_audio.outputDevices;
-    i = iscapture ? current_audio.inputDeviceCount : current_audio.outputDeviceCount;
-    if (index >= 0 && index < i) {
-        for (i--; i > index; i--, item = item->next) {
-            SDL_assert(item != NULL);
-        }
-        SDL_assert(item != NULL);
-        SDL_copyp(spec, &item->spec);
-        retval = 0;
-    } else {
-        retval = SDL_InvalidParamError("index");
+    char *retval = SDL_strdup(device->name);
+    if (!retval) {
+        SDL_OutOfMemory();
     }
-    SDL_UnlockMutex(current_audio.detectionLock);
+
+    SDL_UnlockMutex(device->lock);
 
     return retval;
 }
 
-int SDL_GetDefaultAudioInfo(char **name, SDL_AudioSpec *spec, int iscapture)
+int SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec)
 {
-    if (spec == NULL) {
+    if (!spec) {
         return SDL_InvalidParamError("spec");
     }
 
-    if (!SDL_GetCurrentAudioDriver()) {
-        return SDL_SetError("Audio subsystem is not initialized");
+    SDL_bool is_default = SDL_FALSE;
+    if (devid == SDL_AUDIO_DEVICE_DEFAULT_OUTPUT) {
+        devid = current_audio.default_output_device_id;
+        is_default = SDL_TRUE;
+    } else if (devid == SDL_AUDIO_DEVICE_DEFAULT_CAPTURE) {
+        devid = current_audio.default_capture_device_id;
+        is_default = SDL_TRUE;
     }
 
-    if (current_audio.impl.GetDefaultAudioInfo == NULL) {
-        return SDL_Unsupported();
+    if ((devid == 0) && is_default) {
+        return SDL_SetError("No default audio device available");
     }
-    return current_audio.impl.GetDefaultAudioInfo(name, spec, iscapture);
-}
 
-static void close_audio_device(SDL_AudioDevice *device)
-{
+    SDL_AudioDevice *device = ObtainPhysicalAudioDevice(devid);
     if (!device) {
-        return;
+        return -1;
     }
 
-    /* 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);
+    SDL_memcpy(spec, &device->spec, sizeof (SDL_AudioSpec));
+    SDL_UnlockMutex(device->lock);
 
-    if (device->thread != NULL) {
-        SDL_WaitThread(device->thread, NULL);
-    }
-    if (device->mixer_lock != NULL) {
-        SDL_DestroyMutex(device->mixer_lock);
-    }
+    return 0;
+}
 
-    SDL_free(device->work_buffer);
-    SDL_DestroyAudioStream(device->stream);
+// this expects the device lock to be held.  !!! FIXME: no it doesn't...?
+static void ClosePhysicalAudioDevice(SDL_AudioDevice *device)
+{
+    SDL_assert(current_audio.impl.ProvidesOwnCallbackThread || ((device->thread == NULL) == (SDL_AtomicGet(&device->thread_alive) == 0)));
 
-    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 (SDL_AtomicGet(&device->thread_alive)) {
+        SDL_AtomicSet(&device->shutdown, 1);
+        if (device->thread != NULL) {
+            SDL_WaitThread(device->thread, NULL);
+            device->thread = NULL;
         }
+        SDL_AtomicSet(&device->thread_alive, 0);
     }
 
-    if (device->hidden != NULL) {
-        current_audio.impl.CloseDevice(device);
+    if (device->is_opened) {
+        current_audio.impl.CloseDevice(device);  // if ProvidesOwnCallbackThread, this must join on any existing device thread before returning!
+        device->is_opened = SDL_FALSE;
+        device->hidden = NULL;  // just in case.
     }
 
-    SDL_DestroyDataQueue(device->buffer_queue);
+    if (device->work_buffer) {
+        SDL_aligned_free(device->work_buffer);
+        device->work_buffer = NULL;
+    }
 
-    SDL_free(device);
+    SDL_memcpy(&device->spec, &device->default_spec, sizeof (SDL_AudioSpec));
+    device->sample_frames = 0;
+    device->silence_value = SDL_GetSilenceValueForFormat(device->spec.format);
+    SDL_AtomicSet(&device->shutdown, 0);  // ready to go again.
 }
 
-static Uint16 GetDefaultSamplesFromFreq(int freq)
+void SDL_CloseAudioDevice(SDL_AudioDeviceID devid)
 {
-    /* Pick a default of ~46 ms at desired frequency */
-    /* !!! FIXME: remove this when the non-Po2 resampling is in. */
-    const Uint16 max_sample = (Uint16)((freq / 1000) * 46);
-    Uint16 current_sample = 1;
-    while (current_sample < max_sample) {
-        current_sample *= 2;
+    SDL_LogicalAudioDevice *logdev = ObtainLogicalAudioDevice(devid);
+    if (logdev) {  // if NULL, maybe it was already lost?
+        SDL_AudioDevice *device = logdev->physical_device;
+        DestroyLogicalAudioDevice(logdev);
+
+        if (device->logical_devices == NULL) {  // no more logical devices? Close the physical device, too.
+            // !!! FIXME: we _need_ to release this lock, but doing so can cause a race condition if someone opens a device while we're closing it.
+            SDL_UnlockMutex(device->lock);  // can't hold the lock or the audio thread will deadlock while we WaitThread it.
+            ClosePhysicalAudioDevice(device);
+        } else {
+            SDL_UnlockMutex(device->lock);  // we're set, let everything go again.
+        }
     }
-    return current_sample;
 }
 
-/*
- * Sanity check desired AudioSpec for SDL_OpenAudio() in (orig).
- *  Fills in a sanitized copy in (prepared).
- *  Returns non-zero if okay, zero on fatal parameters in (orig).
- */
-static int prepare_audiospec(const SDL_AudioSpec *orig, SDL_AudioSpec *prepared)
-{
-    SDL_copyp(prepared, orig);
 
-    if (orig->freq == 0) {
-        static const int DEFAULT_FREQ = 22050;
-        const char *env = SDL_getenv("SDL_AUDIO_FREQUENCY");
-        if (env != NULL) {
-            int freq = SDL_atoi(env);
-            prepared->freq = freq != 0 ? freq : DEFAULT_FREQ;
-        } else {
-            prepared->freq = DEFAULT_FREQ;
-        }
+static SDL_AudioFormat ParseAudioFormatString(const char *string)
+{
+    if (string) {
+        #define CHECK_FMT_STRING(x) if (SDL_strcmp(string, #x) == 0) { return SDL_AUDIO_##x; }
+        CHECK_FMT_STRING(U8);
+        CHECK_FMT_STRING(S8);
+        CHECK_FMT_STRING(S16LSB);
+        CHECK_FMT_STRING(S16MSB);
+        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;
+}
 
-    if (orig->format == 0) {
-        const char *env = SDL_getenv("SDL_AUDIO_FORMAT");
+static void PrepareAudioFormat(SDL_bool iscapture, SDL_AudioSpec *spec)
+{
+    if (spec->freq == 0) {
+        spec->freq = iscapture ? DEFAULT_AUDIO_CAPTURE_FREQUENCY : DEFAULT_AUDIO_OUTPUT_FREQUENCY;
+
+        const char *env = SDL_getenv("SDL_AUDIO_FREQUENCY");  // !!! FIXME: should be a hint?
         if (env != NULL) {
-            const SDL_AudioFormat format = SDL_ParseAudioFormat(env);
-            prepared->format = format != 0 ? format : SDL_AUDIO_S16;
-        } else {
-            prepared->format = SDL_AUDIO_S16;
+            const int val = SDL_atoi(env);
+            if (val > 0) {
+                spec->freq = val;
+            }
         }
     }
 
-    if (orig->channels == 0) {
+    if (spec->channels == 0) {
+        spec->channels = iscapture ? DEFAULT_AUDIO_CAPTURE_CHANNELS : DEFAULT_AUDIO_OUTPUT_CHANNELS;;
         const char *env = SDL_getenv("SDL_AUDIO_CHANNELS");
         if (env != NULL) {
-            Uint8 channels = (Uint8)SDL_atoi(env);
-            prepared->channels = channels != 0 ? channels : 2;
-        } else {
-            prepared->channels = 2;
+            const int val = SDL_atoi(env);
+            if (val > 0) {
+                spec->channels = val;
+            }
         }
-    } else if (orig->channels > 8) {
-        SDL_SetError("Unsupported number of audio channels.");
-        return 0;
     }
 
-    if (orig->samples == 0) {
-        const char *env = SDL_getenv("SDL_AUDIO_SAMPLES");
-        if (env != NULL) {
-            Uint16 samples = (Uint16)SDL_atoi(env);
-            prepared->samples = samples != 0 ? samples : GetDefaultSamplesFromFreq(prepared->freq);
-        } else {
-            prepared->samples = GetDefaultSamplesFromFreq(prepared->freq);
-        }
+    if (spec->format == 0) {
+        const SDL_AudioFormat val = ParseAudioFormatString(SDL_getenv("SDL_AUDIO_FORMAT"));
+        spec->format = (val != 0) ? val : (iscapture ? DEFAULT_AUDIO_CAPTURE_FORMAT : DEFAULT_AUDIO_OUTPUT_FORMAT);
     }
+}
 
-    /* Calculate the silence and size of the audio specification */
-    SDL_CalculateAudioSpec(prepared);
+static int GetDefaultSampleFramesFromFreq(int freq)
+{
+    return SDL_powerof2((freq / 1000) * 46);  // Pick the closest power-of-two to ~46 ms at desired frequency
+}
 
-    return 1;
+void SDL_UpdatedAudioDeviceFormat(SDL_AudioDevice *device)
+{
+    device->silence_value = SDL_GetSilenceValueForFormat(device->spec.format);
+    device->buffer_size = device->sample_frames * (SDL_AUDIO_BITSIZE(device->spec.format) / 8) * device->spec.channels;
 }
 
-static SDL_AudioDeviceID open_audio_device(const char *devname, int iscapture,
-                                           const SDL_AudioSpec *desired, SDL_AudioSpec *obtained,
-                                           int allowed_changes, int min_id)
+char *SDL_GetAudioThreadName(SDL_AudioDevice *device, char *buf, size_t buflen)
 {
-    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;
+    (void)SDL_snprintf(buf, buflen, "SDLAudio%c%d", (device->iscapture) ? 'C' : 'P', (int) device->instance_id);
+    return buf;
+}
 
-    if (!SDL_GetCurrentAudioDriver()) {
-        SDL_SetError("Audio subsystem is not initialized");
-        return 0;
+
+// this expects the device lock to be held.
+static int OpenPhysicalAudioDevice(SDL_AudioDevice *device, const SDL_AudioSpec *inspec)
+{
+    SDL_assert(!device->is_opened);
+    SDL_assert(device->logical_devices == NULL);
+
+    // Just pretend to open a zombie device. It can still collect logical devices on the assumption they will all migrate when the default device is officially changed.
+    if (SDL_AtomicGet(&device->zombie)) {
+        return 0;  // Braaaaaaaaains.
+    }
+
+    SDL_AudioSpec spec;
+    SDL_memcpy(&spec, inspec ? inspec : &device->default_spec, sizeof (SDL_AudioSpec));
+    PrepareAudioFormat(device->iscapture, &spec);
+
+    /* We allow the device format to change if it's better than the current settings (by various definitions of "better"). This prevents
+       something low quality, like an old game using S8/8000Hz audio, from ruining a music thing playing at CD quality that tries to open later.
+       (or some VoIP library that opens for mono output ruining your surround-sound game because it got there first).
+       These are just requests! The backend may change any of these values during OpenDevice method! */
+    device->spec.format = (SDL_AUDIO_BITSIZE(device->default_spec.format) >= SDL_AUDIO_BITSIZE(spec.format)) ? device->default_spec.format : spec.format;
+    device->spec.freq = SDL_max(device->default_spec.freq, spec.freq);
+    device->spec.channels = SDL_max(device->default_spec.channels, spec.channels);
+    device->sample_frames = GetDefaultSampleFramesFromFreq(device->spec.freq);
+    SDL_UpdatedAudioDeviceFormat(device);  // start this off sane.
+
+    device->is_opened = SDL_TRUE;  // mark this true even if impl.OpenDevice fails, so we know to clean up.
+    if (current_audio.impl.OpenDevice(device) < 0) {
+        ClosePhysicalAudioDevice(device);  // clean up anything the backend left half-initialized.
+        return -1;
     }
 
-    if (iscapture && !current_audio.impl.HasCaptureSupport) {
-        SDL_SetError("No capture support");
-        return 0;
+    SDL_UpdatedAudioDeviceFormat(device);  // in case the backend changed things and forgot to call this.
+
+    // Allocate a scratch audio buffer
+    device->work_buffer = (Uint8 *)SDL_aligned_alloc(SDL_SIMDGetAlignment(), device->buffer_size);
+    if (device->work_buffer == NULL) {
+        ClosePhysicalAudioDevice(device);
+        return SDL_OutOfMemory();
     }
 
-    SDL_LockMutex(current_audio.detectionLock);
-    /* Find an available device ID... */
-    for (id = min_id - 1; id < SDL_arraysize(open_devices); id++) {
-        if (open_devices[id] == NULL) {
-            break;
+    // Start the audio thread if necessary
+    SDL_AtomicSet(&device->thread_alive, 1);
+    if (!current_audio.impl.ProvidesOwnCallbackThread) {
+        const size_t stacksize = 0;  // just take the system default, since audio streams might have callbacks.
+        char threadname[64];
+        SDL_GetAudioThreadName(device, threadname, sizeof (threadname));
+        device->thread = SDL_CreateThreadInternal(device->iscapture ? CaptureAudioThread : OutputAudioThread, threadname, stacksize, device);
+
+        if (device->thread == NULL) {
+            SDL_AtomicSet(&device->thread_alive, 0);
+            ClosePhysicalAudioDevice(device);
+            return SDL_SetError("Couldn't create audio thread");
         }
     }
 
-    if (id == SDL_arraysize(open_devices)) {
-        SDL_SetError("Too many open audio devices");
-        SDL_UnlockMutex(current_audio.detectionLock);
-        return 0;
-    }
+    return 0;
+}
 
-    if (!obtained) {
-        obtained = &_obtained;
-    }
-    if (!prepare_audiospec(desired, obtained)) {
-        SDL_UnlockMutex(current_audio.detectionLock);
+SDL_AudioDeviceID SDL_OpenAudioDevice(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec)
+{
+    if (!SDL_GetCurrentAudioDriver()) {
+        SDL_SetError("Audio subsystem is not initialized");
         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");
+    SDL_bool is_default = SDL_FALSE;
+    if (devid == SDL_AUDIO_DEVICE_DEFAULT_OUTPUT) {
+        devid = current_audio.default_output_device_id;
+        is_default = SDL_TRUE;
+    } else if (devid == SDL_AUDIO_DEVICE_DEFAULT_CAPTURE) {
+        devid = current_audio.default_capture_device_id;
+        is_default = SDL_TRUE;
     }
 
-    /*
-     * 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 ((devid == 0) && is_default) {
+        SDL_SetError("No default audio device available");
+        return 0;
+    }
 
-    if ((iscapture) && (current_audio.impl.OnlyHasDefaultCaptureDevice)) {
-        if ((devname) && (SDL_strcmp(devname, DEFAULT_INPUT_DEVNAME) != 0)) {
-            SDL_SetError("No such device");
-            SDL_UnlockMutex(current_audio.detectionLock);
-            return 0;
+    // this will let you use a logical device to make a new logical device on the parent physical device. Could be useful?
+    SDL_AudioDevice *device = NULL;
+    const SDL_bool islogical = (devid & (1<<1)) ? SDL_FALSE : SDL_TRUE;
+    if (!islogical) {
+        device = ObtainPhysicalAudioDevice(devid);
+    } else {
+        SDL_LogicalAudioDevice *logdev = ObtainLogicalAudioDevice(devid);  // this locks the physical device, too.
+        if (logdev) {
+            is_default = logdev->is_default;  // was the original logical device meant to be a default? Make this one, too.
+            device = logdev->physical_device;
         }
-        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");
-                SDL_UnlockMutex(current_audio.detectionLock);
-                return 0;
-            }
-        }
-    } else if ((!iscapture) && (current_audio.impl.OnlyHasDefaultOutputDevice)) {
-        if ((devname) && (SDL_strcmp(devname, DEFAULT_OUTPUT_DEVNAME) != 0)) {
-            SDL_UnlockMutex(current_audio.detectionLock);
-            SDL_SetError("No such device");
-            return 0;
-        }
-        devname = NULL;
+    SDL_AudioDeviceID retval = 0;
 
-        for (i = 0; i < SDL_arraysize(open_devices); i++) {
-            if ((open_devices[i]) && (!open_devices[i]->iscapture)) {
-                SDL_UnlockMutex(current_audio.detectionLock);
-                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;
-        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;
+    if (device) {
+        SDL_LogicalAudioDevice *logdev = NULL;
+        if (!is_default && SDL_AtomicGet(&device->zombie)) {
+            // uhoh, this device is undead, and just waiting for a new default device to be declared so it can hand off to it. Refuse explicit opens.
+            SDL_SetError("Device was already lost and can't accept new opens");
+        } else if ((logdev = (SDL_LogicalAudioDevice *) SDL_calloc(1, sizeof (SDL_LogicalAudioDevice))) == NULL) {
+            SDL_OutOfMemory();
+        } else if (!device->is_opened && OpenPhysicalAudioDevice(device, spec) == -1) {  // first thing using this physical device? Open at the OS level...
+            SDL_free(logdev);
+        } else {
+            SDL_AtomicSet(&logdev->paused, 0);
+            retval = logdev->instance_id = assign_audio_device_instance_id(device->iscapture, /*islogical=*/SDL_TRUE);
+            logdev->physical_device = device;
+            logdev->is_default = is_default;
+            logdev->next = device->logical_devices;
+            if (device->logical_devices) {
+                device->logical_devices->prev = logdev;
             }
+            device->logical_devices = logdev;
         }
+        SDL_UnlockMutex(device->lock);
     }
 
-    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.");
-            SDL_UnlockMutex(current_audio.detectionLock);
-            return 0;
-        }
-    }
+    return retval;
+}
 
-    device = (SDL_AudioDevice *)SDL_calloc(1, sizeof(SDL_AudioDevice));
-    if (device == NULL) {
-        SDL_OutOfMemory();
-        SDL_UnlockMutex(current_audio.detectionLock);
-        return 0;
+static int SetLogicalAudioDevicePauseState(SDL_AudioDeviceID devid, int value)
+{
+    SDL_LogicalAudioDevice *logdev = ObtainLogicalAudioDevice(devid);
+    if (!logdev) {
+        return -1;  // ObtainLogicalAudioDevice will have set an error.
     }
-    device->id = id + 1;
-    device->spec = *obtained;
-    device->iscapture = iscapture ? SDL_TRUE : SDL_FALSE;
-    device->handle = handle;
+    SDL_AtomicSet(&logdev->paused, value);
+    SDL_UnlockMutex(logdev->physical_device->lock);
+    return 0;
+}
 
-    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.LockDevice == SDL_AudioLockDevice_Default) {
-        device->mixer_lock = SDL_CreateMutex();
-        if (device->mixer_lock == NULL) {
-            close_audio_device(device);
-            SDL_UnlockMutex(current_audio.detectionLock);
-            SDL_SetError("Couldn't create mixer lock");
-            return 0;
-        }
-    }
+int SDL_PauseAudioDevice(SDL_AudioDeviceID devid)
+{
+    return SetLogicalAudioDevicePauseState(devid, 1);
+}
 
-    /* For backends that require a power-of-two value for spec.samples, take the
-     * value we got from 'desired' and round up to the nearest value
-     */
-    if (!current_audio.impl.SupportsNonPow2Samples && device->spec.samples > 0) {
-        int samples = SDL_powerof2(device->spec.samples);
-        if (samples <= SDL_MAX_UINT16) {
-            device->spec.samples = (Uint16)samples;
-        } else {
-            SDL_SetError("Couldn't hold sample count %d\n", samples);
-            return 0;
+int SDLCALL SDL_UnpauseAudioDevice(SDL_AudioDeviceID devid)
+{
+    return SetLogicalAudioDevicePauseState(devid, 0);
+}
+
+SDL_bool SDL_IsAudioDevicePaused(SDL_AudioDeviceID devid)
+{
+    SDL_LogicalAudioDevice *logdev = ObtainLogicalAudioDevice(devid);
+    SDL_bool retval = SDL_FALSE;
+    if (logdev) {
+        if (SDL_AtomicGet(&logdev->paused)) {
+            retval = SDL_TRUE;
         }
+        SDL_UnlockMutex(logdev->physical_device->lock);
     }
+    return retval;
+}
 
-    if (current_audio.impl.OpenDevice(device, devname) < 0) {
-        close_audio_device(device);
-        SDL_UnlockMutex(current_audio.detectionLock);
-        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);
+int SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_AudioStream **streams, int num_streams)
+{
+    const SDL_bool islogical = (devid & (1<<1)) ? SDL_FALSE : SDL_TRUE;
+    SDL_LogicalAudioDevice *logdev;
 
-    /* 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;
-        }
+    if (num_streams == 0) {
+        return 0;  // nothing to do
+    } else if (num_streams < 0) {
+        return SDL_InvalidParamError("num_streams");
+    } else if (streams == NULL) {
+        return SDL_InvalidParamError("streams");
+    } else if (!islogical) {
+        return SDL_SetError("Audio streams are bound to device ids from SDL_OpenAudioDevice, not raw physical devices");
+    } else if ((logdev = ObtainLogicalAudioDevice(devid)) == NULL) {
+        return -1;  // ObtainLogicalAudioDevice set the error message.
     }
 
-    SDL_CalculateAudioSpec(obtained); /* recalc after possible changes. */
+    // make sure start of list is sane.
+    SDL_assert(!logdev->bound_streams || (logdev->bound_streams->prev_binding == NULL));
 
-    device->callbackspec = *obtained;
+    SDL_AudioDevice *device = logdev->physical_device;
+    int retval = 0;
 
-    if (build_stream) {
-        if (iscapture) {
-            device->stream = SDL_CreateAudioStream(device->spec.format,
-                                                device->spec.channels, device->spec.freq,
-                                                obtained->format, obtained->channels, obtained->freq);
+    // lock all the streams upfront, so we can verify they aren't bound elsewhere and add them all in one block, as this is intended to add everything or nothing.
+    for (int i = 0; i < num_streams; i++) {
+        SDL_AudioStream *stream = streams[i];
+        if (stream == NULL) {
+            retval = SDL_SetError("Stream #%d is NULL", i);
         } else {
-            device->stream = SDL_CreateAudioStream(obtained->format, obtained->channels,
-                                                obtained->freq, device->spec.format,
-                                                device->spec.channels, device->spec.freq);
+            SDL_LockMutex(stream->lock);
+            SDL_assert((stream->bound_device == NULL) == ((stream->prev_binding == NULL) || (stream->next_binding == NULL)));
+            if (stream->bound_device) {
+                retval = SDL_SetError("Stream #%d is already bound to a device", i);
+            }
         }
 
-        if (!device->stream) {
-            close_audio_device(device);
-            SDL_UnlockMutex(current_audio.detectionLock);
-            return 0;
-        }
-    }
-
-    if (device->spec.callback == NULL) { /* use buffer queueing? */
-        /* pool a few packets to start. Enough for two callbacks. */
-        device->buffer_queue = SDL_CreateDataQueue(SDL_AUDIOBUFFERQUEUE_PACKETLEN, obtained->size * 2);
-        if (!device->buffer_queue) {
-            close_audio_device(device);
-            SDL_UnlockMutex(current_audio.detectionLock);
-            SDL_SetError("Couldn't create audio buffer queue");
-            return 0;
+        if (retval != 0) {
+            int j;
+            for (j = 0; j <= i; j++) {
+                SDL_UnlockMutex(streams[j]->lock);
+            }
+            break;
         }
-        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);
+    if (retval == 0) {
+        // Now that everything is verified, chain everything together.
+        const SDL_bool iscapture = device->iscapture;
+        for (int i = 0; i < num_streams; i++) {
+            SDL_AudioStream *stream = streams[i];
+            SDL_AudioSpec src_spec, dst_spec;
 
-    device->work_buffer = (Uint8 *)SDL_malloc(device->work_buffer_len);
-    if (device->work_buffer == NULL) {
-        close_audio_device(device);
-        SDL_UnlockMutex(current_audio.detectionLock);
-        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];
+            // set the proper end of the stream to the device's format.
+            SDL_GetAudioStreamFormat(stream, &src_spec, &dst_spec);
+            if (iscapture) {
+                SDL_SetAudioStreamFormat(stream, &device->spec, &dst_spec);
+            } else {
+                SDL_SetAudioStreamFormat(stream, &src_spec, &device->spec);
+            }
 
-        (void)SDL_snprintf(threadname, sizeof(threadname), "SDLAudio%c%" SDL_PRIu32, (iscapture) ? 'C' : 'P', device->id);
-        device->thread = SDL_CreateThreadInternal(iscapture ? SDL_CaptureAudio : SDL_RunAudio, threadname, stacksize, device);
+            stream->bound_device = logdev;
+            stream->prev_binding = NULL;
+            stream->next_binding = logdev->bound_streams;
+            if (logdev->bound_streams) {
+                logdev->bound_streams->prev_binding = stream;
+            }
+            logdev->bound_streams = stream;
 
-        if (device->thread == NULL) {
-            close_audio_device(device);
-            SDL_SetError("Couldn't create audio thread");
-            SDL_UnlockMutex(current_audio.detectionLock);
-            return 0;
+            SDL_UnlockMutex(stream->lock);
         }
     }
-    SDL_UnlockMutex(current_audio.detectionLock);
 
-    return device->id;
+    SDL_UnlockMutex(device->lock);
+
+    return retval;
 }
 
-SDL_AudioDeviceID SDL_OpenAudioDevice(const char *device, int iscapture,
-                    const SDL_AudioSpec *desired, SDL_AudioSpec *obtained,
-                    int allowed_changes)
+int SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_AudioStream *stream)
 {
-    return open_audio_device(device, iscapture, desired, obtained,
-                             allowed_changes, 2);
+    return SDL_BindAudioStreams(devid, &stream, 1);
 }
 
-SDL_AudioStatus SDL_GetAudioDeviceStatus(SDL_AudioDeviceID devid)
+void SDL_UnbindAudioStreams(SDL_AudioStream **streams, int num_streams)
 {
-    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;
+    /* to prevent deadlock when holding both locks, we _must_ lock the device first, and the stream second, as that is the order the audio thread will do it.
+       But this means we have an unlikely, pathological case where a stream could change its binding between when we lookup its bound device and when we lock everything,
+       so we double-check here. */
+    for (int i = 0; i < num_streams; i++) {
+        SDL_AudioStream *stream = streams[i];
+        if (!stream) {
+            continue;  // nothing to do, it's a NULL stream.
         }
-    }
-    return status;
-}
 
-int SDL_PauseAudioDevice(SDL_AudioDeviceID devid)
-{
-    SDL_AudioDevice *device = get_audio_device(devid);
-    if (!device) {
-        return SDL_InvalidParamError("devid");
+        while (SDL_TRUE) {
+            SDL_LockMutex(stream->lock);   // lock to check this and then release it, in case the device isn't locked yet.
+            SDL_LogicalAudioDevice *bounddev = stream->bound_device;
+            SDL_UnlockMutex(stream->lock);
+
+            // lock in correct order.
+            if (bounddev) {
+                SDL_LockMutex(bounddev->physical_device->lock);  // this requires recursive mutexes, since we're likely locking the same device multiple times.
+            }
+            SDL_LockMutex(stream->lock);
+
+            if (bounddev == stream->bound_device) {
+                break;  // the binding didn't change in the small window where it could, so we're good.
+            } else {
+                SDL_UnlockMutex(stream->lock);  // it changed bindings! Try again.
+                if (bounddev) {
+                    SDL_UnlockMutex(bounddev->physical_device->lock);
+                }
+            }
+        }
     }
-    current_audio.impl.LockDevice(device);
-    SDL_AtomicSet(&device->paused, 1);
-    current_audio.impl.UnlockDevice(device);
-    return 0;
-}
 
-int SDL_PlayAudioDevice(SDL_AudioDeviceID devid)
-{
-    SDL_AudioDevice *device = get_audio_device(devid);
-    if (!device) {
-        return SDL_InvalidParamError("devid");
+    // everything is locked, start unbinding streams.
+    for (int i = 0; i < num_streams; i++) {
+        SDL_AudioStream *stream = streams[i];
+        if (stream && stream->bound_device) {
+            if (stream->bound_device->bound_streams == stream) {
+                SDL_assert(stream->prev_binding == NULL);
+                stream->bound_device->bound_streams = stream->next_binding;
+            }
+            if (stream->prev_binding) {
+                stream->prev_binding->next_binding = stream->next_binding;
+            }
+            if (stream->next_binding) {
+                stream->next_binding->prev_binding = stream->prev_binding;
+            }
+            stream->prev_binding = stream->next_binding = NULL;
+        }
     }
-    current_audio.impl.LockDevice(device);
-    SDL_AtomicSet(&device->paused, 0);
-    current_audio.impl.UnlockDevice(device);
-    return 0;
-}
 
-int SDL_LockAudioDevice(SDL_AudioDeviceID devid)
-{
-    /* Obtain a lock on the mixing buffers */
-    SDL_AudioDevice *device = get_audio_device(devid);
-    if (!device) {
-        return SDL_InvalidParamError("devid");
+    // Finalize and unlock everything.
+    for (int i = 0; i < num_streams; i++) {
+        SDL_AudioStream *stream = streams[i];
+        if (stream && stream->bound_device) {
+            SDL_LogicalAudioDevice *logdev = stream->bound_device;
+            stream->bound_device = NULL;
+            SDL_UnlockMutex(stream->lock);
+            if (logdev) {
+                SDL_UnlockMutex(logdev->physical_device->lock);
+            }
+        }
     }
-    current_audio.impl.LockDevice(device);
-    return 0;
 }
 
-void SDL_UnlockAudioDevice(SDL_AudioDeviceID devid)
+void SDL_UnbindAudioStream(SDL_AudioStream *stream)
 {
-    /* Obtain a lock on the mixing buffers */
-    SDL_AudioDevice *device = get_audio_device(devid);
-    if (!device) {
-        return;
-    }
-    current_audio.impl.UnlockDevice(device);
+    SDL_UnbindAudioStreams(&stream, 1);
 }
 
-void SDL_CloseAudioDevice(SDL_AudioDeviceID devid)
+SDL_AudioDeviceID SDL_GetAudioStreamBinding(SDL_AudioStream *stream)
 {
-    SDL_AudioDevice *device = get_audio_device(devid);
-    if (!device) {
-        return;
+    SDL_AudioDeviceID retval = 0;
+    if (stream) {
+        SDL_LockMutex(stream->lock);
+        if (stream->bound_device) {
+            retval = stream->bound_device->instance_id;
+        }
+        SDL_UnlockMutex(stream->lock);
     }
-    close_audio_device(device);
+    return retval;
 }
 
-void SDL_QuitAudio(void)
+SDL_AudioStream *SDL_CreateAndBindAudioStream(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec)
 {
-    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]);
+    const SDL_bool islogical = (devid & (1<<1)) ? SDL_FALSE : SDL_TRUE;
+    if (!islogical) {
+        SDL_SetError("Audio streams are bound to device ids from SDL_OpenAudioDevice, not raw physical devices");
+        return NULL;
     }
 
-    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_AudioStream *stream = NULL;
+    SDL_LogicalAudioDevice *logdev = ObtainLogicalAudioDevice(devid);
+    if (logdev) {
+        SDL_AudioDevice *device = logdev->physical_device;
+        if (device->iscapture) {
+            stream = SDL_CreateAudioStream(&device->spec, spec);
+        } else {
+            stream = SDL_CreateAudioStream(spec, &device->spec);
+        }
 
-    SDL_zero(current_audio);
-    SDL_zeroa(open_devices);
+        if (stream) {
+            if (SDL_BindAudioStream(devid, stream) == -1) {
+                SDL_DestroyAudioStream(stream);
+                stream = NULL;
+            }
+        }
+        SDL_UnlockMutex(device->lock);
+    }
+    return stream;
 }
 
 #define NUM_FORMATS 8
@@ -1506,78 +1549,168 @@ static const SDL_AudioFormat format_list[NUM_FORMATS][NUM_FORMATS + 1] = {
 
 const SDL_AudioFormat *SDL_ClosestAudioFormats(SDL_AudioFormat format)
 {
-    int i;
-    for (i = 0; i < NUM_FORMATS; i++) {
+    for (int i = 0; i < NUM_FORMATS; i++) {
         if (format_list[i][0] == format) {
             return &format_list[i][0];
         }
     }
-    return &format_list[0][NUM_FORMATS]; /* not found; return what looks like a list with only a zero in it. */
+    return &format_list[0][NUM_FORMATS]; // not found; return what looks like a list with only a zero in it.
 }
 
-Uint8 SDL_GetSilenceValueForFormat(const SDL_AudioFormat format)
+int SDL_GetSilenceValueForFormat(SDL_AudioFormat format)
 {
     return (format == SDL_AUDIO_U8) ? 0x80 : 0x00;
 }
 
-void SDL_CalculateAudioSpec(SDL_AudioSpec *spec)
+// called internally by backends when the system default device changes.
+void SDL_DefaultAudioDeviceChanged(SDL_AudioDevice *new_default_device)
 {
-    spec->silence = SDL_GetSilenceValueForFormat(spec->format);
-    spec->size = SDL_AUDIO_BITSIZE(spec->format) / 8;
-    spec->size *= spec->channels;
-    spec->size *= spec->samples;
-}
+    if (new_default_device == NULL) {  // !!! FIXME: what should we do in this case? Maybe all devices are lost, so there _isn't_ a default?
+        return;  // uhoh.
+    }
 
-/* !!! FIXME: move this to SDL_audiocvt.c */
-int SDL_ConvertAudioSamples(SDL_AudioFormat src_format, Uint8 src_channels, int src_rate, const Uint8 *src_data, int src_len,
-                            SDL_AudioFormat dst_format, Uint8 dst_channels, int dst_rate, Uint8 **dst_data, int *dst_len)
-{
-    int ret = -1;
-    SDL_AudioStream *stream = NULL;
-    Uint8 *dst = NULL;
-    int dstlen = 0;
+    const SDL_bool iscapture = new_default_device->iscapture;
+    const SDL_AudioDeviceID current_devid = iscapture ? current_audio.default_capture_device_id : current_audio.default_output_device_id;
 
-    if (dst_data) {
-        *dst_data = NULL;
+    if (new_default_device->instance_id == current_devid) {
+        return;  // this is already the default.
     }
 
-    if (dst_len) {
-        *dst_len = 0;
+    SDL_LockMutex(new_default_device->lock);
+
+    SDL_AudioDevice *current_default_device = ObtainPhysicalAudioDevice(current_devid);
+
+    /* change the official default ID over while we have locks on both devices, so if something raced to open the default during
+       this, it either gets the new device or is ready on the old and can be migrated. */
+    if (iscapture) {
+        current_audio.default_capture_device_id = new_default_device->instance_id;
+    } else {
+        current_audio.default_output_device_id = new_default_device->instance_id;
+    }
+
+    if (current_default_device) {
+        // migrate any logical devices that were opened as a default to the new physical device...
+
+        SDL_assert(current_default_device->iscapture == iscapture);
+
+        // See if we have to open the new physical device, and if so, find the best audiospec for it.
+        SDL_AudioSpec spec;
+        SDL_bool needs_migration = SDL_FALSE;
+        SDL_zero(spec);
+        for (SDL_LogicalAudioDevice *logdev = current_default_device->logical_devices; logdev != NULL; logdev = logdev->next) {
+            if (logdev->is_default) {
+                needs_migration = SDL_TRUE;
+                for (SDL_AudioStream *stream = logdev->bound_streams; stream != NULL; stream = stream->next_binding) {
+                    const SDL_AudioSpec *streamspec = iscapture ? &stream->dst_spec : &stream->src_spec;
+                    if (SDL_AUDIO_BITSIZE(streamspec->format) > SDL_AUDIO_BITSIZE(spec.format)) {
+                        spec.format = streamspec->format;
+                    }
+                    if (streamspec->channels > spec.channels) {
+                        spec.channels = streamspec->channels;
+                    }
+                    if (streamspec->freq > spec.freq) {
+                        spec.freq = streamspec->freq;
+                    }
+                }
+            }
+        }
+
+        if (needs_migration) {
+            if (new_default_device->logical_devices == NULL) {  // New default physical device not been opened yet? Open at the OS level...
+                if (OpenPhysicalAudioDevice(new_default_device, &spec) == -1) {
+                    needs_migration = SDL_FALSE;  // uhoh, just leave everything on the old default, nothing to be done.
+                }
+            }
+        }
+
+        if (needs_migration) {
+            SDL_LogicalAudioDevice *next = NULL;
+            for (SDL_LogicalAudioDevice *logdev = current_default_device->logical_devices; logdev != NULL; logdev = next) {
+                next = logdev->next;
+
+                if (!logdev->is_default) {
+                    continue;  // not opened as a default, leave it on the current physical device.
+                }
+
+                // make sure all our streams are targeting the new device's format.
+                for (SDL_AudioStream *stream = logdev->bound_streams; stream != NULL; stream = stream->next_binding) {
+                    SDL_SetAudioStreamFormat(stream, iscapture ? &new_default_device->spec : NULL, iscapture ? NULL : &new_default_device->spec);
+                }
+
+                // now migrate the logical device.
+                if (logdev->next) {
+                    logdev->next->prev = logdev->prev;
+                }
+                if (logdev->prev) {
+                    logdev->prev->next = logdev->next;
+                }
+                if (current_default_device->logical_devices == logdev) {
+                    current_default_device->logical_devices = logdev->next;
+                }
+
+                logdev->physical_device = new_default_device;
+                logdev->prev = NULL;
+                logdev->next = new_default_device->logical_devices;
+                new_default_device->logical_devices = logdev;
+            }
+
+            if (current_default_device->logical_devices == NULL) {   // nothing left on the current physical device, close it.
+                // !!! FIXME: we _need_ to release this lock, but doing so can cause a race condition if someone opens a device while we're closing it.
+                SDL_UnlockMutex(current_default_device->lock);  // can't hold the lock or the audio thread will deadlock while we WaitThread it.
+                ClosePhysicalAudioDevice(current_default_device);
+                SDL_LockMutex(current_default_device->lock);  // we're about to unlock this again, so make sure the locks match.
+            }
+        }
+
+        SDL_UnlockMutex(current_default_device->lock);
     }
 
-    if (src_data == NULL) {
-        return SDL_InvalidParamError("src_data");
-    } else if (src_len < 0) {
-        return SDL_InvalidParamError("src_len");
-    } else if (dst_data == NULL) {
-        return SDL_InvalidParamError("dst_data");
-    } else if (dst_len == NULL) {
-        return SDL_InvalidParamError("dst_len");
+    SDL_UnlockMutex(new_default_device->lock);
+
+    // was current device already dead and just kept around to migrate to a new default device? Now we can kill it. Aim for the brain.
+    if (current_default_device && SDL_AtomicGet(&current_default_device->zombie)) {
+        SDL_AudioDeviceDisconnected(current_default_device);  // Call again, now that we're not the default; this will remove from device list, send removal events, and destroy the SDL_AudioDevice.
     }
+}
+
+int SDL_AudioDeviceFormatChangedAlreadyLocked(SDL_AudioDevice *device, const SDL_AudioSpec *newspec, int new_sample_frames)
+{
+    SDL_bool kill_device = SDL_FALSE;
+
+    const int orig_buffer_size = device->buffer_size;
+    const SDL_bool iscapture = device->iscapture;
 
-    stream = SDL_CreateAudioStream(src_format, src_channels, src_rate, dst_format, dst_channels, dst_rate);
-    if (stream != NULL) {
-        if ((SDL_PutAudioStreamData(stream, src_data, src_len) == 0) && (SDL_FlushAudioStream(stream) == 0)) {
-            dstlen = SDL_GetAudioStreamAvailable(stream);
-            if (dstlen >= 0) {
-                dst = (Uint8 *)SDL_malloc(dstlen);
-                if (!dst) {
-                    SDL_OutOfMemory();
-                } else {
-                    ret = (SDL_GetAudioStreamData(stream, dst, dstlen) >= 0) ? 0 : -1;
+    if ((device->spec.format != newspec->format) || (device->spec.channels != newspec->channels) || (device->spec.freq != newspec->freq)) {
+        SDL_memcpy(&device->spec, newspec, sizeof (newspec));
+        for (SDL_LogicalAudioDevice *logdev = device->logical_devices; !kill_device && (logdev != NULL); logdev = logdev->next) {
+            for (SDL_AudioStream *stream = logdev->bound_streams; !kill_device && (stream != NULL); stream = stream->next_binding) {
+                if (SDL_SetAudioStreamFormat(stream, iscapture ? &device->spec : NULL, iscapture ? NULL : &device->spec) == -1) {
+                    kill_device = SDL_TRUE;
                 }
             }
         }
     }
 
-    if (ret == -1) {
-        SDL_free(dst);
-    } else {
-        *dst_data = dst;
-        *dst_len = dstlen;
+    if (!kill_device) {
+        device->sample_frames = new_sample_frames;
+        SDL_UpdatedAudioDeviceFormat(device);
+        if (device->work_buffer && (device->buffer_size > orig_buffer_size)) {
+            SDL_aligned_free(device->work_buffer);
+            device->work_buffer = (Uint8 *)SDL_aligned_alloc(SDL_SIMDGetAlignment(), device->buffer_size);
+            if (!device->work_buffer) {
+                kill_device = SDL_TRUE;
+            }
+        }
     }
 
-    SDL_DestroyAudioStream(stream);
-    return ret;
+    return kill_device ? -1 : 0;
+}
+
+int SDL_AudioDeviceFormatChanged(SDL_AudioDevice *device, const SDL_AudioSpec *newspec, int new_sample_frames)
+{
+    SDL_LockMutex(device->lock);
+    const int retval = SDL_AudioDeviceFormatChangedAlreadyLocked(device, newspec, new_sample_frames);
+    SDL_UnlockMutex(device->lock);
+    return retval;
 }
 

src/audio/SDL_audio_c.h

@@ -22,59 +22,8 @@
 #ifndef SDL_audio_c_h_
 #define SDL_audio_c_h_
 
-#include "SDL_internal.h"
+/* !!! FIXME: remove this header and have things just include SDL_sysaudio.h directly. */
 
-#define DEBUG_AUDIOSTREAM 0
-#define DEBUG_AUDIO_CONVERT 0
-
-#if DEBUG_AUDIO_CONVERT
-#define LOG_DEBUG_AUDIO_CONVERT(from, to) SDL_Log("SDL_AUDIO_CONVERT: Converting %s to %s.\n", from, to);
-#else
-#define LOG_DEBUG_AUDIO_CONVERT(from, to)
-#endif
-
-/* Functions and variables exported from SDL_audio.c for SDL_sysaudio.c */
-
-/* Function to get a list of audio formats, ordered most similar to `format` to least, 0-terminated. Don't free results. */
-const SDL_AudioFormat *SDL_ClosestAudioFormats(SDL_AudioFormat format);
-
-/* Function to calculate the size and silence for a SDL_AudioSpec */
-extern Uint8 SDL_GetSilenceValueForFormat(const SDL_AudioFormat format);
-extern void SDL_CalculateAudioSpec(SDL_AudioSpec *spec);
-
-/* Must be called at least once before using converters (SDL_CreateAudioStream will call it). */
-extern void SDL_ChooseAudioConverters(void);
-
-/* These pointers get set during SDL_ChooseAudioConverters() to various SIMD implementations. */
-extern void (*SDL_Convert_S8_to_F32)(float *dst, const Sint8 *src, int num_samples);
-extern void (*SDL_Convert_U8_to_F32)(float *dst, const Uint8 *src, int num_samples);
-extern void (*SDL_Convert_S16_to_F32)(float *dst, const Sint16 *src, int num_samples);
-extern void (*SDL_Convert_S32_to_F32)(float *dst, const Sint32 *src, int num_samples);
-extern void (*SDL_Convert_F32_to_S8)(Sint8 *dst, const float *src, int num_samples);
-extern void (*SDL_Convert_F32_to_U8)(Uint8 *dst, const float *src, int num_samples);
-extern void (*SDL_Convert_F32_to_S16)(Sint16 *dst, const float *src, int num_samples);
-extern void (*SDL_Convert_F32_to_S32)(Sint32 *dst, const float *src, int num_samples);
-
-/**
- * Use this function to initialize a particular audio driver.
- *
- * This function is used internally, and should not be used unless you have a
- * specific need to designate the audio driver you want to use. You should
- * normally use SDL_Init() or SDL_InitSubSystem().
- *
- * \param driver_name the name of the desired audio driver
- * \returns 0 on success or a negative error code on failure; call
- *          SDL_GetError() for more information.
- */
-extern int SDL_InitAudio(const char *driver_name);
-
-/**
- * Use this function to shut down audio if you initialized it with SDL_InitAudio().
- *
- * This function is used internally, and should not be used unless you have a
- * specific need to specify the audio driver you want to use. You should
- * normally use SDL_Quit() or SDL_QuitSubSystem().
- */
-extern void SDL_QuitAudio(void);
+#include "SDL_sysaudio.h"
 
 #endif /* SDL_audio_c_h_ */

src/audio/SDL_audiocvt.c

@@ -20,7 +20,7 @@
 */
 #include "SDL_internal.h"
 
-/* Functions for audio drivers to perform runtime conversion of audio format */
+// Functions for audio drivers to perform runtime conversion of audio format
 
 #include "SDL_audio_c.h"
 
@@ -64,7 +64,7 @@ static int GetHistoryBufferSampleFrames(const Sint32 required_resampler_frames)
     return (int) SDL_max(required_resampler_frames, 5000);
 }
 
-/* lpadding and rpadding are expected to be buffers of (GetResamplePadding(inrate, outrate) * chans * sizeof (float)) bytes. */
+// lpadding and rpadding are expected to be buffers of (GetResamplePadding(inrate, outrate) * chans * sizeof (float)) bytes.
 static void ResampleAudio(const int chans, const int inrate, const int outrate,
                          const float *lpadding, const float *rpadding,
                          const float *inbuf, const int inframes,
@@ -97,7 +97,7 @@ static void ResampleAudio(const int chans, const int inrate, const int outrate,
         for (chan = 0; chan < chans; chan++) {
             float outsample = 0.0f;
 
-            /* do this twice to calculate the sample, once for the "left wing" and then same for the right. */
+            // do this twice to calculate the sample, once for the "left wing" and then same for the right.
             for (j = 0; (filterindex1 + (j * RESAMPLER_SAMPLES_PER_ZERO_CROSSING)) < RESAMPLER_FILTER_SIZE; j++) {
                 const int filt_ind = filterindex1 + j * RESAMPLER_SAMPLES_PER_ZERO_CROSSING;
                 const int srcframe = srcindex - j;
@@ -106,11 +106,11 @@ static void ResampleAudio(const int chans, const int inrate, const int outrate,
                 outsample += (float) (insample * (ResamplerFilter[filt_ind] + (interpolation1 * ResamplerFilterDifference[filt_ind])));
             }
 
-            /* Do the right wing! */
+            // Do the right wing!
             for (j = 0; (filterindex2 + (j * RESAMPLER_SAMPLES_PER_ZERO_CROSSING)) < RESAMPLER_FILTER_SIZE; j++) {
                 const int filt_ind = filterindex2 + j * RESAMPLER_SAMPLES_PER_ZERO_CROSSING;
                 const int srcframe = srcindex + 1 + j;
-                /* !!! FIXME: we can bubble this conditional out of here by doing a post loop. */
+                // !!! FIXME: we can bubble this conditional out of here by doing a post loop.
                 const float insample = (srcframe >= inframes) ? rpadding[((srcframe - inframes) * chans) + chan] : inbuf[(srcframe * chans) + chan];
                 outsample += (float) (insample * (ResamplerFilter[filt_ind] + (interpolation2 * ResamplerFilterDifference[filt_ind])));
             }
@@ -154,25 +154,25 @@ static void ResampleAudio(const int chans, const int inrate, const int outrate,
  */
 
 #ifdef SDL_SSE3_INTRINSICS
-/* Convert from stereo to mono. Average left and right. */
+// Convert from stereo to mono. Average left and right.
 static void SDL_TARGETING("sse3") SDL_ConvertStereoToMono_SSE3(float *dst, const float *src, int num_frames)
 {
+    LOG_DEBUG_AUDIO_CONVERT("stereo", "mono (using SSE3)");
+
     const __m128 divby2 = _mm_set1_ps(0.5f);
     int i = num_frames;
 
-    LOG_DEBUG_AUDIO_CONVERT("stereo", "mono (using SSE3)");
-
     /* Do SSE blocks as long as we have 16 bytes available.
        Just use unaligned load/stores, if the memory at runtime is
        aligned it'll be just as fast on modern processors */
-    while (i >= 4) { /* 4 * float32 */
+    while (i >= 4) {  // 4 * float32
         _mm_storeu_ps(dst, _mm_mul_ps(_mm_hadd_ps(_mm_loadu_ps(src), _mm_loadu_ps(src + 4)), divby2));
         i -= 4;
         src += 8;
         dst += 4;
     }
 
-    /* Finish off any leftovers with scalar operations. */
+    // Finish off any leftovers with scalar operations.
     while (i) {
         *dst = (src[0] + src[1]) * 0.5f;
         dst++;
@@ -183,34 +183,33 @@ static void SDL_TARGETING("sse3") SDL_ConvertStereoToMono_SSE3(float *dst, const
 #endif
 
 #ifdef SDL_SSE_INTRINSICS
-/* Convert from mono to stereo. Duplicate to stereo left and right. */
+// Convert from mono to stereo. Duplicate to stereo left and right.
 static void SDL_TARGETING("sse") SDL_ConvertMonoToStereo_SSE(float *dst, const float *src, int num_frames)
 {
-    int i = num_frames;
+    LOG_DEBUG_AUDIO_CONVERT("mono", "stereo (using SSE)");
 
-    /* convert backwards, since output is growing in-place. */
+    // convert backwards, since output is growing in-place.
     src += (num_frames-4) * 1;
     dst += (num_frames-4) * 2;
 
-    LOG_DEBUG_AUDIO_CONVERT("mono", "stereo (using SSE)");
-
     /* Do SSE blocks as long as we have 16 bytes available.
        Just use unaligned load/stores, if the memory at runtime is
        aligned it'll be just as fast on modern processors */
-    /* convert backwards, since output is growing in-place. */
-    while (i >= 4) {                                           /* 4 * float32 */
-        const __m128 input = _mm_loadu_ps(src);                /* A B C D */
-        _mm_storeu_ps(dst, _mm_unpacklo_ps(input, input));     /* A A B B */
-        _mm_storeu_ps(dst + 4, _mm_unpackhi_ps(input, input)); /* C C D D */
+    // convert backwards, since output is growing in-place.
+    int i = num_frames;
+    while (i >= 4) {                                           // 4 * float32
+        const __m128 input = _mm_loadu_ps(src);                // A B C D
+        _mm_storeu_ps(dst, _mm_unpacklo_ps(input, input));     // A A B B
+        _mm_storeu_ps(dst + 4, _mm_unpackhi_ps(input, input)); // C C D D
         i -= 4;
         src -= 4;
         dst -= 8;
     }
 
-    /* Finish off any leftovers with scalar operations. */
+    // Finish off any leftovers with scalar operations.
     src += 3;
-    dst += 6;   /* adjust for smaller buffers. */
-    while (i) { /* convert backwards, since output is growing in-place. */
+    dst += 6;   // adjust for smaller buffers.
+    while (i) {  // convert backwards, since output is growing in-place.
         const float srcFC = src[0];
         dst[1] /* FR */ = srcFC;
         dst[0] /* FL */ = srcFC;
@@ -221,14 +220,12 @@ static void SDL_TARGETING("sse") SDL_ConvertMonoToStereo_SSE(float *dst, const f
 }
 #endif
 
-/* Include the autogenerated channel converters... */
+// Include the autogenerated channel converters...
 #include "SDL_audio_channel_converters.h"
 
 
 static void AudioConvertByteswap(void *dst, const void *src, int num_samples, int bitsize)
 {
-    int i;
-
 #if DEBUG_AUDIO_CONVERT
     SDL_Log("SDL_AUDIO_CONVERT: Converting %d-bit byte order", bitsize);
 #endif
@@ -238,7 +235,7 @@ static void AudioConvertByteswap(void *dst, const void *src, int num_samples, in
     case b: { \
         const Uint##b *tsrc = (const Uint##b *)src; \
         Uint##b *tdst = (Uint##b *)dst; \
-        for (i = 0; i < num_samples; i++) { \
+        for (int i = 0; i < num_samples; i++) { \
             tdst[i] = SDL_Swap##b(tsrc[i]); \
         } \
         break; \
@@ -258,28 +255,28 @@ static void AudioConvertByteswap(void *dst, const void *src, int num_samples, in
 
 static void AudioConvertToFloat(float *dst, const void *src, int num_samples, SDL_AudioFormat src_fmt)
 {
-    SDL_assert( (SDL_AUDIO_BITSIZE(src_fmt) <= 8) || ((SDL_AUDIO_ISBIGENDIAN(src_fmt) == 0) == (SDL_BYTEORDER == SDL_LIL_ENDIAN)) );  /* This only deals with native byte order. */
+    SDL_assert( (SDL_AUDIO_BITSIZE(src_fmt) <= 8) || ((SDL_AUDIO_ISBIGENDIAN(src_fmt) == 0) == (SDL_BYTEORDER == SDL_LIL_ENDIAN)) );  // This only deals with native byte order.
 
     switch (src_fmt & ~SDL_AUDIO_MASK_ENDIAN) {
         case SDL_AUDIO_S8: SDL_Convert_S8_to_F32(dst, (const Sint8 *) src, num_samples); break;
         case SDL_AUDIO_U8: SDL_Convert_U8_to_F32(dst, (const Uint8 *) src, num_samples); break;
         case SDL_AUDIO_S16: SDL_Convert_S16_to_F32(dst, (const Sint16 *) src, num_samples); break;
         case SDL_AUDIO_S32: SDL_Convert_S32_to_F32(dst, (const Sint32 *) src, num_samples); break;
-        case SDL_AUDIO_F32: if (dst != src) { SDL_memcpy(dst, src, num_samples * sizeof (float)); } break;  /* oh well, just pass it through. */
+        case SDL_AUDIO_F32: if (dst != src) { SDL_memcpy(dst, src, num_samples * sizeof (float)); } break;  // oh well, just pass it through.
         default: SDL_assert(!"Unexpected audio format!"); break;
     }
 }
 
 static void AudioConvertFromFloat(void *dst, const float *src, int num_samples, SDL_AudioFormat dst_fmt)
 {
-    SDL_assert( (SDL_AUDIO_BITSIZE(dst_fmt) <= 8) || ((SDL_AUDIO_ISBIGENDIAN(dst_fmt) == 0) == (SDL_BYTEORDER == SDL_LIL_ENDIAN)) );  /* This only deals with native byte order. */
+    SDL_assert( (SDL_AUDIO_BITSIZE(dst_fmt) <= 8) || ((SDL_AUDIO_ISBIGENDIAN(dst_fmt) == 0) == (SDL_BYTEORDER == SDL_LIL_ENDIAN)) );  // This only deals with native byte order.
 
     switch (dst_fmt & ~SDL_AUDIO_MASK_ENDIAN) {
         case SDL_AUDIO_S8: SDL_Convert_F32_to_S8((Sint8 *) dst, src, num_samples); break;
         case SDL_AUDIO_U8: SDL_Convert_F32_to_U8((Uint8 *) dst, src, num_samples); break;
         case SDL_AUDIO_S16: SDL_Convert_F32_to_S16((Sint16 *) dst, src, num_samples); break;
         case SDL_AUDIO_S32: SDL_Convert_F32_to_S32((Sint32 *) dst, src, num_samples); break;
-        case SDL_AUDIO_F32: if (dst != src) { SDL_memcpy(dst, src, num_samples * sizeof (float)); } break;  /* oh well, just pass it through. */
+        case SDL_AUDIO_F32: if (dst != src) { SDL_memcpy(dst, src, num_samples * sizeof (float)); } break;  // oh well, just pass it through.
         default: SDL_assert(!"Unexpected audio format!"); break;
     }
 }
@@ -295,13 +292,13 @@ static SDL_bool SDL_IsSupportedAudioFormat(const SDL_AudioFormat fmt)
     case SDL_AUDIO_S32MSB:
     case SDL_AUDIO_F32LSB:
     case SDL_AUDIO_F32MSB:
-        return SDL_TRUE; /* supported. */
+        return SDL_TRUE;  // supported.
 
     default:
         break;
     }
 
-    return SDL_FALSE; /* unsupported. */
+    return SDL_FALSE;  // unsupported.
 }
 
 static SDL_bool SDL_IsSupportedChannelCount(const int channels)
@@ -320,8 +317,6 @@ static SDL_bool SDL_IsSupportedChannelCount(const int channels)
 static void ConvertAudio(int num_frames, const void *src, SDL_AudioFormat src_format, int src_channels,
                          void *dst, SDL_AudioFormat dst_format, int dst_channels)
 {
-    const int dst_bitsize = (int) SDL_AUDIO_BITSIZE(dst_format);
-    const int src_bitsize = (int) SDL_AUDIO_BITSIZE(src_format);
     SDL_assert(src != NULL);
     SDL_assert(dst != NULL);
     SDL_assert(SDL_IsSupportedAudioFormat(src_format));
@@ -329,13 +324,16 @@ static void ConvertAudio(int num_frames, const void *src, SDL_AudioFormat src_fo
     SDL_assert(SDL_IsSupportedChannelCount(src_channels));
     SDL_assert(SDL_IsSupportedChannelCount(dst_channels));
 
+    if (!num_frames) {
+        return;  // no data to convert, quit.
+    }
+
 #if DEBUG_AUDIO_CONVERT
     SDL_Log("SDL_AUDIO_CONVERT: Convert format %04x->%04x, channels %u->%u", src_format, dst_format, src_channels, dst_channels);
 #endif
 
-    if (!num_frames) {
-        return;  /* no data to convert, quit. */
-    }
+    const int dst_bitsize = (int) SDL_AUDIO_BITSIZE(dst_format);
+    const int src_bitsize = (int) SDL_AUDIO_BITSIZE(src_format);
 
     /* Type conversion goes like this now:
         - byteswap to CPU native format first if necessary.
@@ -351,55 +349,55 @@ static void ConvertAudio(int num_frames, const void *src, SDL_AudioFormat src_fo
        (script-generated) custom converters for every data type and
        it was a bloat on SDL compile times and final library size. */
 
-    /* see if we can skip float conversion entirely. */
+    // see if we can skip float conversion entirely.
     if (src_channels == dst_channels) {
         if (src_format == dst_format) {
-            /* nothing to do, we're already in the right format, just copy it over if necessary. */
+            // nothing to do, we're already in the right format, just copy it over if necessary.
             if (src != dst) {
                 SDL_memcpy(dst, src, num_frames * src_channels * (dst_bitsize / 8));
             }
             return;
         }
 
-        /* just a byteswap needed? */
+        // just a byteswap needed?
         if ((src_format & ~SDL_AUDIO_MASK_ENDIAN) == (dst_format & ~SDL_AUDIO_MASK_ENDIAN)) {
             if (src_bitsize == 8) {
                 if (src != dst) {
                     SDL_memcpy(dst, src, num_frames * src_channels * (dst_bitsize / 8));
                 }
-                return;  /* nothing to do, it's a 1-byte format. */
+                return;  // nothing to do, it's a 1-byte format.
             }
             AudioConvertByteswap(dst, src, num_frames * src_channels, src_bitsize);
-            return;  /* all done. */
+            return;  // all done.
         }
     }
 
-    /* make sure we're in native byte order. */
+    // make sure we're in native byte order.
     if ((SDL_AUDIO_ISBIGENDIAN(src_format) != 0) == (SDL_BYTEORDER == SDL_LIL_ENDIAN) && (src_bitsize > 8)) {
         AudioConvertByteswap(dst, src, num_frames * src_channels, src_bitsize);
-        src = dst;  /* we've written to dst, future work will convert in-place. */
+        src = dst;  // we've written to dst, future work will convert in-place.
     }
 
-    /* get us to float format. */
+    // get us to float format.
     if (!SDL_AUDIO_ISFLOAT(src_format)) {
         AudioConvertToFloat((float *) dst, src, num_frames * src_channels, src_format);
-        src = dst;  /* we've written to dst, future work will convert in-place. */
+        src = dst;  // we've written to dst, future work will convert in-place.
     }
 
-    /* Channel conversion */
+    // Channel conversion
 
     if (src_channels != dst_channels) {
         SDL_AudioChannelConverter channel_converter;
         SDL_AudioChannelConverter override = NULL;
 
-        /* SDL_IsSupportedChannelCount should have caught these asserts, or we added a new format and forgot to update the table. */
+        // SDL_IsSupportedChannelCount should have caught these asserts, or we added a new format and forgot to update the table.
         SDL_assert(src_channels <= SDL_arraysize(channel_converters));
         SDL_assert(dst_channels <= SDL_arraysize(channel_converters[0]));
 
         channel_converter = channel_converters[src_channels - 1][dst_channels - 1];
         SDL_assert(channel_converter != NULL);
 
-        /* swap in some SIMD versions for a few of these. */
+        // swap in some SIMD versions for a few of these.
         if (channel_converter == SDL_ConvertStereoToMono) {
             #ifdef SDL_SSE3_INTRINSICS
             if (!override && SDL_HasSSE3()) { override = SDL_ConvertStereoToMono_SSE3; }
@@ -414,88 +412,52 @@ static void ConvertAudio(int num_frames, const void *src, SDL_AudioFormat src_fo
             channel_converter = override;
         }
         channel_converter((float *) dst, (float *) src, num_frames);
-        src = dst;  /* we've written to dst, future work will convert in-place. */
+        src = dst;  // we've written to dst, future work will convert in-place.
     }
 
-    /* Resampling is not done in here. SDL_AudioStream handles that. */
+    // Resampling is not done in here. SDL_AudioStream handles that.
 
-    /* Move to final data type. */
+    // Move to final data type.
     if (!SDL_AUDIO_ISFLOAT(dst_format)) {
         AudioConvertFromFloat(dst, (float *) src, num_frames * dst_channels, dst_format);
-        src = dst;  /* we've written to dst, future work will convert in-place. */
+        src = dst;  // we've written to dst, future work will convert in-place.
     }
 
-    /* make sure we're in final byte order. */
+    // make sure we're in final byte order.
     if ((SDL_AUDIO_ISBIGENDIAN(dst_format) != 0) == (SDL_BYTEORDER == SDL_LIL_ENDIAN) && (dst_bitsize > 8)) {
         AudioConvertByteswap(dst, src, num_frames * dst_channels, dst_bitsize);
-        src = dst;  /* we've written to dst, future work will convert in-place. */
+        src = dst;  // we've written to dst, future work will convert in-place.
     }
 
-    SDL_assert(src == dst);  /* if we got here, we _had_ to have done _something_. Otherwise, we should have memcpy'd! */
+    SDL_assert(src == dst);  // if we got here, we _had_ to have done _something_. Otherwise, we should have memcpy'd!
 }
 
-struct SDL_AudioStream
-{
-    SDL_DataQueue *queue;
-    SDL_Mutex *lock;  /* this is just a copy of `queue`'s mutex. We share a lock. */
-
-    Uint8 *work_buffer;    /* used for scratch space during data conversion/resampling. */
-    Uint8 *history_buffer;  /* history for left padding and future sample rate changes. */
-    Uint8 *future_buffer;  /* stuff that left the queue for the right padding and will be next read's data. */
-    float *left_padding;  /* left padding for resampling. */
-    float *right_padding;  /* right padding for resampling. */
-
-    SDL_bool flushed;
-
-    size_t work_buffer_allocation;
-    size_t history_buffer_allocation;
-    size_t future_buffer_allocation;
-    size_t resampler_padding_allocation;
-
-    int resampler_padding_frames;
-    int history_buffer_frames;
-    int future_buffer_filled_frames;
-
-    int max_sample_frame_size;
-
-    int src_sample_frame_size;
-    SDL_AudioFormat src_format;
-    int src_channels;
-    int src_rate;
-
-    int dst_sample_frame_size;
-    SDL_AudioFormat dst_format;
-    int dst_channels;
-    int dst_rate;
-
-    int pre_resample_channels;
-    int packetlen;
-};
-
-static int GetMemsetSilenceValue(const SDL_AudioFormat fmt)
-{
-    return (fmt == SDL_AUDIO_U8) ? 0x80 : 0x00;
-}
-
-/* figure out the largest thing we might need for ConvertAudio, which might grow data in-place. */
+// figure out the largest thing we might need for ConvertAudio, which might grow data in-place.
 static int CalculateMaxSampleFrameSize(SDL_AudioFormat src_format, int src_channels, SDL_AudioFormat dst_format, int dst_channels)
 {
     const int src_format_size = SDL_AUDIO_BITSIZE(src_format) / 8;
     const int dst_format_size = SDL_AUDIO_BITSIZE(dst_format) / 8;
     const int max_app_format_size = SDL_max(src_format_size, dst_format_size);
-    const int max_format_size = SDL_max(max_app_format_size, sizeof (float));  /* ConvertAudio converts to float internally. */
+    const int max_format_size = SDL_max(max_app_format_size, sizeof (float));  // ConvertAudio converts to float internally.
     const int max_channels = SDL_max(src_channels, dst_channels);
     return max_format_size * max_channels;
 }
 
-/* this assumes you're holding the stream's lock (or are still creating the stream). */
-static int SetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioFormat src_format, int src_channels, int src_rate, SDL_AudioFormat dst_format, int dst_channels, int dst_rate)
+// this assumes you're holding the stream's lock (or are still creating the stream).
+static int SetAudioStreamFormat(SDL_AudioStream *stream, const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec)
 {
     /* If increasing channels, do it after resampling, since we'd just
        do more work to resample duplicate channels. If we're decreasing, do
        it first so we resample the interpolated data instead of interpolating
        the resampled data (!!! FIXME: decide if that works in practice, though!).
        This is decided in pre_resample_channels. */
+
+    const SDL_AudioFormat src_format = src_spec->format;
+    const int src_channels = src_spec->channels;
+    const int src_rate = src_spec->freq;
+    const SDL_AudioFormat dst_format = dst_spec->format;
+    const int dst_channels = dst_spec->channels;
+    const int dst_rate = dst_spec->freq;
     const int src_sample_frame_size = (SDL_AUDIO_BITSIZE(src_format) / 8) * src_channels;
     const int dst_sample_frame_size = (SDL_AUDIO_BITSIZE(dst_format) / 8) * dst_channels;
     const int max_sample_frame_size = CalculateMaxSampleFrameSize(src_format, src_channels, dst_format, dst_channels);
@@ -510,14 +472,15 @@ static int SetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioFormat src_for
     Uint8 *future_buffer = stream->future_buffer;
     float *padding;
 
-    /* do all the things that can fail upfront, so we can just return an error without changing the stream if anything goes wrong. */
+    // do all the things that can fail upfront, so we can just return an error without changing the stream if anything goes wrong.
 
-    /* set up for (possibly new) conversions */
+    // set up for (possibly new) conversions
 
-    /* grow the padding buffers if necessary; these buffer sizes change if sample rate or source channel count is adjusted. */
-    /* (we can replace these buffers in `stream` now even if we abandon this function when a later allocation fails, because it's safe for these buffers to be overallocated and their contents don't matter.) */
+    /* grow the padding buffers if necessary; these buffer sizes change if sample rate or source channel count is adjusted.
+       (we can replace these buffers in `stream` now even if we abandon this function when a later allocation fails, because
+       it's safe for these buffers to be overallocated and their contents don't matter.) */
     if (stream->resampler_padding_allocation < resampler_padding_allocation) {
-        /* left_padding and right_padding are just scratch buffers, so we don't need to preserve existing contents. */
+        // left_padding and right_padding are just scratch buffers, so we don't need to preserve existing contents.
         padding = (float *) SDL_aligned_alloc(SDL_SIMDGetAlignment(), resampler_padding_allocation);
         if (!padding) {
             return SDL_OutOfMemory();
@@ -535,7 +498,7 @@ static int SetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioFormat src_for
         stream->resampler_padding_allocation = resampler_padding_allocation;
     }
 
-    /* grow the history buffer if necessary; often times this won't be, as it already buffers more than immediately necessary in case of a dramatic downsample. */
+    // grow the history buffer if necessary; often times this won't be, as it already buffers more than immediately necessary in case of a dramatic downsample.
     if (stream->history_buffer_allocation < history_buffer_allocation) {
         history_buffer = (Uint8 *) SDL_aligned_alloc(SDL_SIMDGetAlignment(), history_buffer_allocation);
         if (!history_buffer) {
@@ -543,7 +506,7 @@ static int SetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioFormat src_for
         }
     }
 
-    /* grow the future buffer if necessary; the buffer size changes if sample rate is adjusted. */
+    // grow the future buffer if necessary; the buffer size changes if sample rate is adjusted.
     if (stream->future_buffer_allocation < future_buffer_allocation) {
         future_buffer = (Uint8 *) SDL_aligned_alloc(SDL_SIMDGetAlignment(), future_buffer_allocation);
         if (!future_buffer) {
@@ -554,24 +517,24 @@ static int SetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioFormat src_for
         }
     }
 
-    /* okay, we've done all the things that can fail, now we can change stream state. */
+    // okay, we've done all the things that can fail, now we can change stream state.
 
-    /* copy to new buffers and/or convert data; ConvertAudio will do a simple memcpy if format matches, and nothing at all if the buffer hasn't changed */
+    // copy to new buffers and/or convert data; ConvertAudio will do a simple memcpy if format matches, and nothing at all if the buffer hasn't changed
     if (stream->future_buffer) {
-        ConvertAudio(stream->future_buffer_filled_frames, stream->future_buffer, stream->src_format, stream->src_channels, future_buffer, src_format, src_channels);
+        ConvertAudio(stream->future_buffer_filled_frames, stream->future_buffer, stream->src_spec.format, stream->src_spec.channels, future_buffer, src_format, src_channels);
     } else if (future_buffer != NULL) {
-        SDL_memset(future_buffer, GetMemsetSilenceValue(src_format), future_buffer_allocation);
+        SDL_memset(future_buffer, SDL_GetSilenceValueForFormat(src_format), future_buffer_allocation);
     }
 
     if (stream->history_buffer) {
         if (history_buffer_frames <= prev_history_buffer_frames) {
-            ConvertAudio(history_buffer_frames, stream->history_buffer, stream->src_format, stream->src_channels, history_buffer, src_format, src_channels);
+            ConvertAudio(history_buffer_frames, stream->history_buffer, stream->src_spec.format, stream->src_spec.channels, history_buffer, src_format, src_channels);
         } else {
-            ConvertAudio(prev_history_buffer_frames, stream->history_buffer, stream->src_format, stream->src_channels, history_buffer + ((history_buffer_frames - prev_history_buffer_frames) * src_sample_frame_size), src_format, src_channels);
-            SDL_memset(history_buffer, GetMemsetSilenceValue(src_format), (history_buffer_frames - prev_history_buffer_frames) * src_sample_frame_size);  /* silence oldest history samples. */
+            ConvertAudio(prev_history_buffer_frames, stream->history_buffer, stream->src_spec.format, stream->src_spec.channels, history_buffer + ((history_buffer_frames - prev_history_buffer_frames) * src_sample_frame_size), src_format, src_channels);
+            SDL_memset(history_buffer, SDL_GetSilenceValueForFormat(src_format), (history_buffer_frames - prev_history_buffer_frames) * src_sample_frame_size);  // silence oldest history samples.
         }
     } else if (history_buffer != NULL) {
-        SDL_memset(history_buffer, GetMemsetSilenceValue(src_format), history_buffer_allocation);
+        SDL_memset(history_buffer, SDL_GetSilenceValueForFormat(src_format), history_buffer_allocation);
     }
 
     if (future_buffer != stream->future_buffer) {
@@ -590,79 +553,80 @@ static int SetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioFormat src_for
     stream->history_buffer_frames = history_buffer_frames;
     stream->max_sample_frame_size = max_sample_frame_size;
     stream->src_sample_frame_size = src_sample_frame_size;
-    stream->src_format = src_format;
-    stream->src_channels = src_channels;
-    stream->src_rate = src_rate;
     stream->dst_sample_frame_size = dst_sample_frame_size;
-    stream->dst_format = dst_format;
-    stream->dst_channels = dst_channels;
-    stream->dst_rate = dst_rate;
     stream->pre_resample_channels = pre_resample_channels;
 
+    if (src_spec != &stream->src_spec) {
+        SDL_memcpy(&stream->src_spec, src_spec, sizeof (SDL_AudioSpec));
+    }
+
+    if (dst_spec != &stream->dst_spec) {
+        SDL_memcpy(&stream->dst_spec, dst_spec, sizeof (SDL_AudioSpec));
+    }
+
     return 0;
 }
 
-SDL_AudioStream *SDL_CreateAudioStream(SDL_AudioFormat src_format,
-                   int src_channels,
-                   int src_rate,
-                   SDL_AudioFormat dst_format,
-                   int dst_channels,
-                   int dst_rate)
+SDL_AudioStream *SDL_CreateAudioStream(const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec)
 {
-    int packetlen = 4096; /* !!! FIXME: good enough for now. */
-    SDL_AudioStream *retval;
+    // !!! FIXME: fail if audio isn't initialized
 
-    if (!SDL_IsSupportedChannelCount(src_channels)) {
-        SDL_InvalidParamError("src_channels");
+    if (!src_spec) {
+        SDL_InvalidParamError("src_spec");
         return NULL;
-    } else if (!SDL_IsSupportedChannelCount(dst_channels)) {
-        SDL_InvalidParamError("dst_channels");
+    } else if (!dst_spec) {
+        SDL_InvalidParamError("dst_spec");
         return NULL;
-    } else if (src_rate <= 0) {
-        SDL_InvalidParamError("src_rate");
+    } else if (!SDL_IsSupportedChannelCount(src_spec->channels)) {
+        SDL_InvalidParamError("src_spec->channels");
         return NULL;
-    } else if (dst_rate <= 0) {
-        SDL_InvalidParamError("dst_rate");
+    } else if (!SDL_IsSupportedChannelCount(dst_spec->channels)) {
+        SDL_InvalidParamError("dst_spec->channels");
         return NULL;
-    } else if (src_rate >= SDL_MAX_SINT32 / RESAMPLER_SAMPLES_PER_ZERO_CROSSING) {
+    } else if (src_spec->freq <= 0) {
+        SDL_InvalidParamError("src_spec->freq");
+        return NULL;
+    } else if (dst_spec->freq <= 0) {
+        SDL_InvalidParamError("dst_spec->freq");
+        return NULL;
+    } else if (src_spec->freq >= SDL_MAX_SINT32 / RESAMPLER_SAMPLES_PER_ZERO_CROSSING) {
         SDL_SetError("Source rate is too high");
         return NULL;
-    } else if (dst_rate >= SDL_MAX_SINT32 / RESAMPLER_SAMPLES_PER_ZERO_CROSSING) {
+    } else if (dst_spec->freq >= SDL_MAX_SINT32 / RESAMPLER_SAMPLES_PER_ZERO_CROSSING) {
         SDL_SetError("Destination rate is too high");
         return NULL;
-    } else if (!SDL_IsSupportedAudioFormat(src_format)) {
-        SDL_InvalidParamError("src_format");
+    } else if (!SDL_IsSupportedAudioFormat(src_spec->format)) {
+        SDL_InvalidParamError("src_spec->format");
         return NULL;
-    } else if (!SDL_IsSupportedAudioFormat(dst_format)) {
-        SDL_InvalidParamError("dst_format");
+    } else if (!SDL_IsSupportedAudioFormat(dst_spec->format)) {
+        SDL_InvalidParamError("dst_spec->format");
         return NULL;
     }
 
-    retval = (SDL_AudioStream *)SDL_calloc(1, sizeof(SDL_AudioStream));
+    SDL_AudioStream *retval = (SDL_AudioStream *)SDL_calloc(1, sizeof(SDL_AudioStream));
     if (retval == NULL) {
         SDL_OutOfMemory();
         return NULL;
     }
 
+    const int packetlen = 4096; // !!! FIXME: good enough for now.
     retval->queue = SDL_CreateDataQueue(packetlen, (size_t)packetlen * 2);
     if (!retval->queue) {
         SDL_DestroyAudioStream(retval);
-        return NULL; /* SDL_CreateDataQueue should have called SDL_SetError. */
+        return NULL; // SDL_CreateDataQueue should have called SDL_SetError.
     }
 
     retval->lock = SDL_GetDataQueueMutex(retval->queue);
     SDL_assert(retval->lock != NULL);
 
-    /* Make sure we've chosen audio conversion functions (SIMD, scalar, etc.) */
-    SDL_ChooseAudioConverters();  /* !!! FIXME: let's do this during SDL_Init? */
+    // Make sure we've chosen audio conversion functions (SIMD, scalar, etc.)
+    SDL_ChooseAudioConverters();  // !!! FIXME: let's do this during SDL_Init
 
-    retval->src_sample_frame_size = (SDL_AUDIO_BITSIZE(src_format) / 8) * src_channels;
-    retval->src_format = src_format;
-    retval->src_channels = src_channels;
-    retval->src_rate = src_rate;
+    retval->src_sample_frame_size = (SDL_AUDIO_BITSIZE(src_spec->format) / 8) * src_spec->channels;
     retval->packetlen = packetlen;
+    SDL_memcpy(&retval->src_spec, src_spec, sizeof (SDL_AudioSpec));
 
-    if (SetAudioStreamFormat(retval, src_format, src_channels, src_rate, dst_format, dst_channels, dst_rate) == -1) {
+    if (SetAudioStreamFormat(retval, src_spec, dst_spec) == -1) {
         SDL_DestroyAudioStream(retval);
         return NULL;
     }
@@ -670,50 +634,88 @@ SDL_AudioStream *SDL_CreateAudioStream(SDL_AudioFormat src_format,
     return retval;
 }
 
-int SDL_GetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioFormat *src_format, int *src_channels, int *src_rate, SDL_AudioFormat *dst_format, int *dst_channels, int *dst_rate)
+int SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamRequestCallback callback, void *userdata)
+{
+    if (!stream) {
+        return SDL_InvalidParamError("stream");
+    }
+    SDL_LockMutex(stream->lock);
+    stream->get_callback = callback;
+    stream->get_callback_userdata = userdata;
+    SDL_UnlockMutex(stream->lock);
+    return 0;
+}
+
+int SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamRequestCallback callback, void *userdata)
 {
     if (!stream) {
         return SDL_InvalidParamError("stream");
     }
     SDL_LockMutex(stream->lock);
-    #define GETAUDIOSTREAMFIELD(x) if (x) { *x = stream->x; }
-    GETAUDIOSTREAMFIELD(src_format);
-    GETAUDIOSTREAMFIELD(src_channels);
-    GETAUDIOSTREAMFIELD(src_rate);
-    GETAUDIOSTREAMFIELD(dst_format);
-    GETAUDIOSTREAMFIELD(dst_channels);
-    GETAUDIOSTREAMFIELD(dst_rate);
-    #undef GETAUDIOSTREAMFIELD
+    stream->put_callback = callback;
+    stream->put_callback_userdata = userdata;
     SDL_UnlockMutex(stream->lock);
     return 0;
 }
 
-int SDL_SetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioFormat src_format, int src_channels, int src_rate, SDL_AudioFormat dst_format, int dst_channels, int dst_rate)
+int SDL_LockAudioStream(SDL_AudioStream *stream)
+{
+    return stream ? SDL_LockMutex(stream->lock) : SDL_InvalidParamError("stream");
+}
+
+int SDL_UnlockAudioStream(SDL_AudioStream *stream)
 {
-    int retval;
+    return stream ? SDL_UnlockMutex(stream->lock) : SDL_InvalidParamError("stream");
+}
 
+int SDL_GetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioSpec *src_spec, SDL_AudioSpec *dst_spec)
+{
     if (!stream) {
         return SDL_InvalidParamError("stream");
-    } else if (!SDL_IsSupportedAudioFormat(src_format)) {
-        return SDL_InvalidParamError("src_format");
-    } else if (!SDL_IsSupportedChannelCount(src_channels)) {
-        return SDL_InvalidParamError("src_channels");
-    } else if (src_rate <= 0) {
-        return SDL_InvalidParamError("src_rate");
-    } else if (src_rate >= SDL_MAX_SINT32 / RESAMPLER_SAMPLES_PER_ZERO_CROSSING) {
-        return SDL_SetError("Source rate is too high");
-    } else if (!SDL_IsSupportedAudioFormat(dst_format)) {
-        return SDL_InvalidParamError("dst_format");
-    } else if (!SDL_IsSupportedChannelCount(dst_channels)) {
-        return SDL_InvalidParamError("dst_channels");
-    } else if (dst_rate <= 0) {
-        return SDL_InvalidParamError("dst_rate");
-    } else if (dst_rate >= SDL_MAX_SINT32 / RESAMPLER_SAMPLES_PER_ZERO_CROSSING) {
-        return SDL_SetError("Destination rate is too high");
+    }
+    SDL_LockMutex(stream->lock);
+    if (src_spec) {
+        SDL_memcpy(src_spec, &stream->src_spec, sizeof (SDL_AudioSpec));
+    }
+    if (dst_spec) {
+        SDL_memcpy(dst_spec, &stream->dst_spec, sizeof (SDL_AudioSpec));
+    }
+    SDL_UnlockMutex(stream->lock);
+    return 0;
+}
+
+int SDL_SetAudioStreamFormat(SDL_AudioStream *stream, const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec)
+{
+    if (!stream) {
+        return SDL_InvalidParamError("stream");
+    }
+
+    if (src_spec) {
+        if (!SDL_IsSupportedAudioFormat(src_spec->format)) {
+            return SDL_InvalidParamError("src_spec->format");
+        } else if (!SDL_IsSupportedChannelCount(src_spec->channels)) {
+            return SDL_InvalidParamError("src_spec->channels");
+        } else if (src_spec->freq <= 0) {
+            return SDL_InvalidParamError("src_spec->freq");
+        } else if (src_spec->freq >= SDL_MAX_SINT32 / RESAMPLER_SAMPLES_PER_ZERO_CROSSING) {
+            return SDL_SetError("Source rate is too high");
+        }
+    }
+
+    if (dst_spec) {
+        if (!SDL_IsSupportedAudioFormat(dst_spec->format)) {
+            return SDL_InvalidParamError("dst_spec->format");
+        } else if (!SDL_IsSupportedChannelCount(dst_spec->channels)) {
+            return SDL_InvalidParamError("dst_spec->channels");
+        } else if (dst_spec->freq <= 0) {
+            return SDL_InvalidParamError("dst_spec->freq");
+        } else if (dst_spec->freq >= SDL_MAX_SINT32 / RESAMPLER_SAMPLES_PER_ZERO_CROSSING) {
+            return SDL_SetError("Destination rate is too high");
+        }
     }
 
     SDL_LockMutex(stream->lock);
-    retval = SetAudioStreamFormat(stream, src_format, src_channels, src_rate, dst_format, dst_channels, dst_rate);
+    const int retval = SetAudioStreamFormat(stream, src_spec ? src_spec : &stream->src_spec, dst_spec ? dst_spec : &stream->dst_spec);
     SDL_UnlockMutex(stream->lock);
 
     return retval;
@@ -721,8 +723,6 @@ int SDL_SetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioFormat src_format
 
 int SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len)
 {
-    int retval;
-
 #if DEBUG_AUDIOSTREAM
     SDL_Log("AUDIOSTREAM: wants to put %d preconverted bytes", len);
 #endif
@@ -732,19 +732,26 @@ int SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len)
     } else if (buf == NULL) {
         return SDL_InvalidParamError("buf");
     } else if (len == 0) {
-        return 0; /* nothing to do. */
+        return 0; // nothing to do.
     }
 
     SDL_LockMutex(stream->lock);
 
+    const int prev_available = stream->put_callback ? SDL_GetAudioStreamAvailable(stream) : 0;
+
     if ((len % stream->src_sample_frame_size) != 0) {
         SDL_UnlockMutex(stream->lock);
         return SDL_SetError("Can't add partial sample frames");
     }
 
-    /* just queue the data, we convert/resample when dequeueing. */
-    retval = SDL_WriteToDataQueue(stream->queue, buf, len);
+    // just queue the data, we convert/resample when dequeueing.
+    const int retval = SDL_WriteToDataQueue(stream->queue, buf, len);
     stream->flushed = SDL_FALSE;
+
+    if (stream->put_callback) {
+        stream->put_callback(stream, SDL_GetAudioStreamAvailable(stream) - prev_available, stream->put_callback_userdata);
+    }
+
     SDL_UnlockMutex(stream->lock);
 
     return retval;
@@ -768,16 +775,14 @@ int SDL_FlushAudioStream(SDL_AudioStream *stream)
    The returned buffer is aligned/padded for use with SIMD instructions. */
 static Uint8 *EnsureStreamWorkBufferSize(SDL_AudioStream *stream, size_t newlen)
 {
-    Uint8 *ptr;
-
     if (stream->work_buffer_allocation >= newlen) {
         return stream->work_buffer;
     }
 
-    ptr = (Uint8 *) SDL_aligned_alloc(SDL_SIMDGetAlignment(), newlen);
+    Uint8 *ptr = (Uint8 *) SDL_aligned_alloc(SDL_SIMDGetAlignment(), newlen);
     if (ptr == NULL) {
         SDL_OutOfMemory();
-        return NULL;  /* previous work buffer is still valid! */
+        return NULL;  // previous work buffer is still valid!
     }
 
     SDL_aligned_free(stream->work_buffer);
@@ -788,45 +793,44 @@ static Uint8 *EnsureStreamWorkBufferSize(SDL_AudioStream *stream, size_t newlen)
 
 static int CalculateAudioStreamWorkBufSize(const SDL_AudioStream *stream, int len)
 {
-    int workbuf_frames = len / stream->dst_sample_frame_size;  /* start with requested sample frames */
     int workbuflen = len;
-    int inputlen;
+    int workbuf_frames = len / stream->dst_sample_frame_size;  // start with requested sample frames
+    int inputlen = workbuf_frames * stream->max_sample_frame_size;
 
-    inputlen = workbuf_frames * stream->max_sample_frame_size;
     if (inputlen > workbuflen) {
         workbuflen = inputlen;
     }
 
-    if (stream->dst_rate != stream->src_rate) {
-        /* calculate requested sample frames needed before resampling. Use a Uint64 so the multiplication doesn't overflow. */
-        const int input_frames = ((int) ((((Uint64) workbuf_frames) * stream->src_rate) / stream->dst_rate));
+    if (stream->dst_spec.freq != stream->src_spec.freq) {
+        // calculate requested sample frames needed before resampling. Use a Uint64 so the multiplication doesn't overflow.
+        const int input_frames = ((int) ((((Uint64) workbuf_frames) * stream->src_spec.freq) / stream->dst_spec.freq));
         inputlen = input_frames * stream->max_sample_frame_size;
         if (inputlen > workbuflen) {
             workbuflen = inputlen;
         }
-        /* Calculate space needed to move to format/channels used for resampling stage. */
+        // Calculate space needed to move to format/channels used for resampling stage.
         inputlen = input_frames * stream->pre_resample_channels * sizeof (float);
         if (inputlen > workbuflen) {
             workbuflen = inputlen;
         }
-        /* Calculate space needed after resample (which lives in a second copy in the same buffer). */
+        // Calculate space needed after resample (which lives in a second copy in the same buffer).
         workbuflen += workbuf_frames * stream->pre_resample_channels * sizeof (float);
     }
 
     return workbuflen;
 }
 
-/* You must hold stream->lock and validate your parameters before calling this! */
+// You must hold stream->lock and validate your parameters before calling this!
 static int GetAudioStreamDataInternal(SDL_AudioStream *stream, void *buf, int len)
 {
     const int max_available = SDL_GetAudioStreamAvailable(stream);
-    const SDL_AudioFormat src_format = stream->src_format;
-    const int src_channels = stream->src_channels;
-    const int src_rate = stream->src_rate;
+    const SDL_AudioFormat src_format = stream->src_spec.format;
+    const int src_channels = stream->src_spec.channels;
+    const int src_rate = stream->src_spec.freq;
     const int src_sample_frame_size = stream->src_sample_frame_size;
-    const SDL_AudioFormat dst_format = stream->dst_format;
-    const int dst_channels = stream->dst_channels;
-    const int dst_rate = stream->dst_rate;
+    const SDL_AudioFormat dst_format = stream->dst_spec.format;
+    const int dst_channels = stream->dst_spec.channels;
+    const int dst_rate = stream->dst_spec.freq;
     const int dst_sample_frame_size = stream->dst_sample_frame_size;
     const int max_sample_frame_size = stream->max_sample_frame_size;
     const int pre_resample_channels = stream->pre_resample_channels;
@@ -854,29 +858,38 @@ static int GetAudioStreamDataInternal(SDL_AudioStream *stream, void *buf, int le
     output_frames = len / dst_sample_frame_size;
 
     if (output_frames == 0) {
-        return 0;  /* nothing to do. */
+        return 0;  // nothing to do.
     }
 
-    /* !!! FIXME: this could be less aggressive about allocation, if we decide the necessary size at each stage and select the maximum required. */
+    // !!! FIXME: this could be less aggressive about allocation, if we decide the necessary size at each stage and select the maximum required.
     workbuflen = CalculateAudioStreamWorkBufSize(stream, len);
     workbuf = EnsureStreamWorkBufferSize(stream, workbuflen);
     if (!workbuf) {
         return -1;
     }
 
-    /* figure out how much data we need to fulfill the request. */
-    input_frames = len / dst_sample_frame_size;  /* total sample frames caller wants */
+    // figure out how much data we need to fulfill the request.
+    input_frames = len / dst_sample_frame_size;  // total sample frames caller wants
     if (dst_rate != src_rate) {
-        /* calculate requested sample frames needed before resampling. Use a Uint64 so the multiplication doesn't overflow. */
-        input_frames = (int) ((((Uint64) input_frames) * src_rate) / dst_rate);
-        if (input_frames == 0) {
-            return 0;  /* if they are upsampling and we end up needing less than a frame of input, we reject it because it would cause artifacts on future reads to eat a full input frame. */
+        // calculate requested sample frames needed before resampling. Use a Uint64 so the multiplication doesn't overflow.
+        const int resampled_input_frames = (int) ((((Uint64) input_frames) * src_rate) / dst_rate);
+        if (resampled_input_frames > 0) {
+            input_frames = resampled_input_frames;
+        } else {  // uhoh, not enough input frames!
+            // if they are upsampling and we end up needing less than a frame of input, we reject it because it would cause artifacts on future reads to eat a full input frame.
+            //  however, if the stream is flushed, we would just be padding any remaining input with silence anyhow, so use it up.
+            if (stream->flushed) {
+                SDL_assert(((size_t) ((input_frames * src_sample_frame_size) + future_buffer_filled_frames)) <= stream->future_buffer_allocation);
+                // leave input_frames alone; this will just shuffle what's available from the future buffer and pad with silence as appropriate, below.
+            } else {
+                return 0;
+            }
         }
     }
 
-    workbuf_frames = 0;  /* no input has been moved to the workbuf yet. */
+    workbuf_frames = 0;  // no input has been moved to the workbuf yet.
 
-    /* move any previous right-padding to the start of the buffer to convert, as those would have been the next samples from the queue ("the future buffer"). */
+    // move any previous right-padding to the start of the buffer to convert, as those would have been the next samples from the queue ("the future buffer").
     if (future_buffer_filled_frames) {
         const int cpyframes = SDL_min(input_frames, future_buffer_filled_frames);
         const int cpy = cpyframes * src_sample_frame_size;
@@ -884,18 +897,18 @@ static int GetAudioStreamDataInternal(SDL_AudioStream *stream, void *buf, int le
         workbuf_frames = cpyframes;
         if (future_buffer_filled_frames == cpyframes) {
             stream->future_buffer_filled_frames = future_buffer_filled_frames = 0;
-        } else {  /* slide any remaining bytes to the start of the padding buffer, if this was a small request. */
+        } else {  // slide any remaining bytes to the start of the padding buffer, if this was a small request.
             SDL_memmove(future_buffer, future_buffer + cpy, (future_buffer_filled_frames - cpyframes) * src_sample_frame_size);
             future_buffer_filled_frames -= cpyframes;
             stream->future_buffer_filled_frames = future_buffer_filled_frames;
         }
     }
 
-    /* we either consumed all the future buffer or we don't need to read more from the queue. If this assert fails, we will have data in the wrong order in the future buffer when we top it off. */
+    // we either consumed all the future buffer or we don't need to read more from the queue. If this assert fails, we will have data in the wrong order in the future buffer when we top it off.
     SDL_assert((future_buffer_filled_frames == 0) || (workbuf_frames == input_frames));
 
-    /* now read unconverted data from the queue into the work buffer to fulfill the request. */
-    if (input_frames > workbuf_frames) {  /* need more data? */
+    // now read unconverted data from the queue into the work buffer to fulfill the request.
+    if (input_frames > workbuf_frames) {  // need more data?
         const int workbufpos = workbuf_frames * src_sample_frame_size;
         const int request_bytes = (input_frames - workbuf_frames) * src_sample_frame_size;
         int read_frames;
@@ -903,10 +916,10 @@ static int GetAudioStreamDataInternal(SDL_AudioStream *stream, void *buf, int le
         br = (int) SDL_ReadFromDataQueue(stream->queue, workbuf + workbufpos, request_bytes);
         read_frames = br / src_sample_frame_size;
         workbuf_frames += read_frames;
-        input_frames = workbuf_frames; /* what we actually have to work with */
+        input_frames = workbuf_frames; // what we actually have to work with
     }
 
-    /* for some resamples, we need to fill up the future buffer, too, to use as right padding. */
+    // for some resamples, we need to fill up the future buffer, too, to use as right padding.
     if (future_buffer_filled_frames < resampler_padding_frames) {
         const int cpyframes = resampler_padding_frames - future_buffer_filled_frames;
         const int cpy = cpyframes * src_sample_frame_size;
@@ -915,24 +928,24 @@ static int GetAudioStreamDataInternal(SDL_AudioStream *stream, void *buf, int le
         brframes = br / src_sample_frame_size;
         future_buffer_filled_frames += brframes;
         stream->future_buffer_filled_frames = future_buffer_filled_frames;
-        if (br < cpy) {  /* we couldn't fill the future buffer with enough padding! */
-            if (stream->flushed) {  /* that's okay, we're flushing, just silence the still-needed padding. */
-                SDL_memset(future_buffer + (future_buffer_filled_frames * src_sample_frame_size), GetMemsetSilenceValue(src_format), cpy - br);
-            } else {  /* Drastic measures: steal from the work buffer! */
+        if (br < cpy) {  // we couldn't fill the future buffer with enough padding!
+            if (stream->flushed) {  // that's okay, we're flushing, just silence the still-needed padding.
+                SDL_memset(future_buffer + (future_buffer_filled_frames * src_sample_frame_size), SDL_GetSilenceValueForFormat(src_format), cpy - br);
+            } else {  // Drastic measures: steal from the work buffer!
                 const int stealcpyframes = SDL_min(workbuf_frames, cpyframes - brframes);
                 const int stealcpy = stealcpyframes * src_sample_frame_size;
                 SDL_memcpy(future_buffer + (future_buffer_filled_frames * src_sample_frame_size), workbuf + ((workbuf_frames - stealcpyframes) * src_sample_frame_size), stealcpy);
                 workbuf_frames -= stealcpyframes;
-                input_frames = workbuf_frames;  /* what we actually have to work with, now */
+                input_frames = workbuf_frames;  // what we actually have to work with, now
                 future_buffer_filled_frames += stealcpyframes;
                 SDL_assert(future_buffer_filled_frames <= resampler_padding_frames);
             }
         }
     }
 
-    /* Now, the work buffer has enough sample frames to fulfill the request (or all the frames available if not), and the future buffer is loaded if necessary. */
+    // Now, the work buffer has enough sample frames to fulfill the request (or all the frames available if not), and the future buffer is loaded if necessary.
 
-    /* If we have resampling padding buffers, convert the current history and future buffers to float32. */
+    // If we have resampling padding buffers, convert the current history and future buffers to float32.
     if (resampler_padding_frames > 0) {
         const int history_buffer_bytes = history_buffer_frames * src_sample_frame_size;
         const int resampler_padding_bytes = resampler_padding_frames * src_sample_frame_size;
@@ -942,7 +955,7 @@ static int GetAudioStreamDataInternal(SDL_AudioStream *stream, void *buf, int le
         ConvertAudio(resampler_padding_frames, future_buffer, src_format, src_channels, stream->right_padding, SDL_AUDIO_F32, pre_resample_channels);
     }
 
-    /* slide in new data to the history buffer, shuffling out the oldest, for the next run, since we've already updated left_padding with current data. */
+    // slide in new data to the history buffer, shuffling out the oldest, for the next run, since we've already updated left_padding with current data.
     {
         const int history_buffer_bytes = history_buffer_frames * src_sample_frame_size;
         const int request_bytes = input_frames * src_sample_frame_size;
@@ -950,15 +963,15 @@ static int GetAudioStreamDataInternal(SDL_AudioStream *stream, void *buf, int le
             const int preserve_bytes = history_buffer_bytes - request_bytes;
             SDL_memmove(history_buffer, history_buffer + request_bytes, preserve_bytes);
             SDL_memcpy(history_buffer + preserve_bytes, workbuf, request_bytes);
-        } else {  /* are we just replacing the whole thing instead? */
+        } else {  // are we just replacing the whole thing instead?
             SDL_memcpy(history_buffer, (workbuf + request_bytes) - history_buffer_bytes, history_buffer_bytes);
         }
     }
 
-    /* Not resampling? It's an easy conversion (and maybe not even that!) */
+    // Not resampling? It's an easy conversion (and maybe not even that!)
     if (src_rate == dst_rate) {
         SDL_assert(resampler_padding_frames == 0);
-        /* see if we can do the conversion in-place (will fit in `buf` while in-progress), or if we need to do it in the workbuf and copy it over */
+        // see if we can do the conversion in-place (will fit in `buf` while in-progress), or if we need to do it in the workbuf and copy it over
         if (max_sample_frame_size <= dst_sample_frame_size) {
             ConvertAudio(input_frames, workbuf, src_format, src_channels, buf, dst_format, dst_channels);
         } else {
@@ -968,14 +981,14 @@ static int GetAudioStreamDataInternal(SDL_AudioStream *stream, void *buf, int le
         return input_frames * dst_sample_frame_size;
     }
 
-    /* Resampling! get the work buffer to float32 format, etc, in-place. */
+    // Resampling! get the work buffer to float32 format, etc, in-place.
     ConvertAudio(input_frames, workbuf, src_format, src_channels, workbuf, SDL_AUDIO_F32, pre_resample_channels);
 
     if ((dst_format == SDL_AUDIO_F32) && (dst_channels == pre_resample_channels)) {
         resample_outbuf = (float *) buf;
     } else {
         const int output_bytes = output_frames * pre_resample_channels * sizeof (float);
-        resample_outbuf = (float *) ((workbuf + stream->work_buffer_allocation) - output_bytes);  /* do at the end of the buffer so we have room for final convert at front. */
+        resample_outbuf = (float *) ((workbuf + stream->work_buffer_allocation) - output_bytes);  // do at the end of the buffer so we have room for final convert at front.
     }
 
     ResampleAudio(pre_resample_channels, src_rate, dst_rate,
@@ -983,8 +996,8 @@ static int GetAudioStreamDataInternal(SDL_AudioStream *stream, void *buf, int le
                   (const float *) workbuf, input_frames,
                   resample_outbuf, output_frames);
 
-    /* Get us to the final format! */
-    /* see if we can do the conversion in-place (will fit in `buf` while in-progress), or if we need to do it in the workbuf and copy it over */
+    // Get us to the final format!
+    // see if we can do the conversion in-place (will fit in `buf` while in-progress), or if we need to do it in the workbuf and copy it over
     if (max_sample_frame_size <= dst_sample_frame_size) {
         ConvertAudio(output_frames, resample_outbuf, SDL_AUDIO_F32, pre_resample_channels, buf, dst_format, dst_channels);
     } else {
@@ -995,11 +1008,10 @@ static int GetAudioStreamDataInternal(SDL_AudioStream *stream, void *buf, int le
     return (int) (output_frames * dst_sample_frame_size);
 }
 
-/* get converted/resampled data from the stream */
+// get converted/resampled data from the stream
 int SDL_GetAudioStreamData(SDL_AudioStream *stream, void *voidbuf, int len)
 {
     Uint8 *buf = (Uint8 *) voidbuf;
-    int retval = 0;
 
 #if DEBUG_AUDIOSTREAM
     SDL_Log("AUDIOSTREAM: want to get %d converted bytes", len);
@@ -1012,16 +1024,34 @@ int SDL_GetAudioStreamData(SDL_AudioStream *stream, void *voidbuf, int len)
     } else if (len < 0) {
         return SDL_InvalidParamError("len");
     } else if (len == 0) {
-        return 0; /* nothing to do. */
+        return 0; // nothing to do.
     }
 
     SDL_LockMutex(stream->lock);
 
-    len -= len % stream->dst_sample_frame_size;  /* chop off any fractional sample frame. */
+    len -= len % stream->dst_sample_frame_size;  // chop off any fractional sample frame.
+
+    // give the callback a chance to fill in more stream data if it wants.
+    if (stream->get_callback) {
+        int approx_request = len / stream->dst_sample_frame_size;  // start with sample frames desired
+        if (stream->src_spec.freq != stream->dst_spec.freq) {
+            // calculate difference in dataset size after resampling. Use a Uint64 so the multiplication doesn't overflow.
+            approx_request = (int) (size_t) ((((Uint64) approx_request) * stream->src_spec.freq) / stream->dst_spec.freq);
+            if (!stream->flushed) {  // do we need to fill the future buffer to accomodate this, too?
+                approx_request += stream->future_buffer_filled_frames - stream->resampler_padding_frames;
+            }
+        }
+
+        approx_request *= stream->src_sample_frame_size;  // convert sample frames to bytes.
+        const int already_have = SDL_GetAudioStreamAvailable(stream);
+        approx_request -= SDL_min(approx_request, already_have);  // we definitely have this much output already packed in.
+        stream->get_callback(stream, approx_request, stream->get_callback_userdata);
+    }
 
-    /* we convert in chunks, so we don't end up allocating a massive work buffer, etc. */
-    while (len > 0) { /* didn't ask for a whole sample frame, nothing to do */
-        const int chunk_size = 1024 * 1024;  /* !!! FIXME: a megabyte might be overly-aggressive. */
+    // we convert in chunks, so we don't end up allocating a massive work buffer, etc.
+    int retval = 0;
+    while (len > 0) { // didn't ask for a whole sample frame, nothing to do
+        const int chunk_size = 1024 * 1024;  // !!! FIXME: a megabyte might be overly-aggressive.
         const int rc = GetAudioStreamDataInternal(stream, buf, SDL_min(len, chunk_size));
 
         if (rc == -1) {
@@ -1054,41 +1084,39 @@ int SDL_GetAudioStreamData(SDL_AudioStream *stream, void *voidbuf, int len)
     return retval;
 }
 
-/* number of converted/resampled bytes available */
+// number of converted/resampled bytes available
 int SDL_GetAudioStreamAvailable(SDL_AudioStream *stream)
 {
-    const int max_int = 0x7FFFFFFF;  /* !!! FIXME: This will blow up on weird processors. Is there an SDL_INT_MAX? */
-    size_t count;
-
     if (!stream) {
         return SDL_InvalidParamError("stream");
     }
 
     SDL_LockMutex(stream->lock);
 
-    /* total bytes available in source format in data queue */
-    count = SDL_GetDataQueueSize(stream->queue);
+    // total bytes available in source format in data queue
+    size_t count = SDL_GetDataQueueSize(stream->queue);
 
-    /* total sample frames available in data queue */
+    // total sample frames available in data queue
     count /= stream->src_sample_frame_size;
     count += stream->future_buffer_filled_frames;
 
-    /* sample frames after resampling */
-    if (stream->src_rate != stream->dst_rate) {
+    // sample frames after resampling
+    if (stream->src_spec.freq != stream->dst_spec.freq) {
         if (!stream->flushed) {
-            /* have to save some samples for padding. They aren't available until more data is added or the stream is flushed. */
+            // have to save some samples for padding. They aren't available until more data is added or the stream is flushed.
             count = (count < ((size_t) stream->resampler_padding_frames)) ? 0 : (count - stream->resampler_padding_frames);
         }
-        /* calculate difference in dataset size after resampling. Use a Uint64 so the multiplication doesn't overflow. */
-        count = (size_t) ((((Uint64) count) * stream->dst_rate) / stream->src_rate);
+        // calculate difference in dataset size after resampling. Use a Uint64 so the multiplication doesn't overflow.
+        count = (size_t) ((((Uint64) count) * stream->dst_spec.freq) / stream->src_spec.freq);
     }
 
-    /* convert from sample frames to bytes in destination format. */
+    // convert from sample frames to bytes in destination format.
     count *= stream->dst_sample_frame_size;
 
     SDL_UnlockMutex(stream->lock);
 
-    /* if this overflows an int, just clamp it to a maximum. */
+    // if this overflows an int, just clamp it to a maximum.
+    const int max_int = 0x7FFFFFFF;  // !!! FIXME: This will blow up on weird processors. Is there an SDL_INT_MAX?
     return (count >= ((size_t) max_int)) ? max_int : ((int) count);
 }
 
@@ -1100,7 +1128,9 @@ int SDL_ClearAudioStream(SDL_AudioStream *stream)
 
     SDL_LockMutex(stream->lock);
     SDL_ClearDataQueue(stream->queue, (size_t)stream->packetlen * 2);
-    SDL_memset(stream->history_buffer, GetMemsetSilenceValue(stream->src_format), stream->history_buffer_frames * stream->src_channels * sizeof (float));
+    if (stream->history_buffer != NULL) {
+        SDL_memset(stream->history_buffer, SDL_GetSilenceValueForFormat(stream->src_spec.format), stream->history_buffer_frames * stream->src_spec.channels * sizeof (float));
+    }
     stream->future_buffer_filled_frames = 0;
     stream->flushed = SDL_FALSE;
     SDL_UnlockMutex(stream->lock);
@@ -1110,7 +1140,8 @@ int SDL_ClearAudioStream(SDL_AudioStream *stream)
 void SDL_DestroyAudioStream(SDL_AudioStream *stream)
 {
     if (stream) {
-        /* do not destroy stream->lock! it's a copy of `stream->queue`'s mutex, so destroying the queue will handle it. */
+        SDL_UnbindAudioStream(stream);
+        // do not destroy stream->lock! it's a copy of `stream->queue`'s mutex, so destroying the queue will handle it.
         SDL_DestroyDataQueue(stream->queue);
         SDL_aligned_free(stream->work_buffer);
         SDL_aligned_free(stream->history_buffer);
@@ -1120,3 +1151,55 @@ void SDL_DestroyAudioStream(SDL_AudioStream *stream)
         SDL_free(stream);
     }
 }
+
+int SDL_ConvertAudioSamples(const SDL_AudioSpec *src_spec, const Uint8 *src_data, int src_len,
+                            const SDL_AudioSpec *dst_spec, Uint8 **dst_data, int *dst_len)
+{
+    if (dst_data) {
+        *dst_data = NULL;
+    }
+
+    if (dst_len) {
+        *dst_len = 0;
+    }
+
+    if (src_data == NULL) {
+        return SDL_InvalidParamError("src_data");
+    } else if (src_len < 0) {
+        return SDL_InvalidParamError("src_len");
+    } else if (dst_data == NULL) {
+        return SDL_InvalidParamError("dst_data");
+    } else if (dst_len == NULL) {
+        return SDL_InvalidParamError("dst_len");
+    }
+
+    int retval = -1;
+    Uint8 *dst = NULL;
+    int dstlen = 0;
+
+    SDL_AudioStream *stream = SDL_CreateAudioStream(src_spec, dst_spec);
+    if (stream != NULL) {
+        if ((SDL_PutAudioStreamData(stream, src_data, src_len) == 0) && (SDL_FlushAudioStream(stream) == 0)) {
+            dstlen = SDL_GetAudioStreamAvailable(stream);
+            if (dstlen >= 0) {
+                dst = (Uint8 *)SDL_malloc(dstlen);
+                if (!dst) {
+                    SDL_OutOfMemory();
+                } else {
+                    retval = (SDL_GetAudioStreamData(stream, dst, dstlen) >= 0) ? 0 : -1;
+                }
+            }
+        }
+    }
+
+    if (retval == -1) {
+        SDL_free(dst);
+    } else {
+        *dst_data = dst;
+        *dst_len = dstlen;
+    }
+
+    SDL_DestroyAudioStream(stream);
+    return retval;
+}
+

src/audio/SDL_audiodev.c

@@ -45,13 +45,13 @@
 #define SDL_PATH_DEV_AUDIO "/dev/audio"
 #endif
 
-static void test_device(const int iscapture, const char *fname, int flags, int (*test)(int fd))
+static void test_device(const SDL_bool iscapture, const char *fname, int flags, SDL_bool (*test)(int fd))
 {
     struct stat sb;
     if ((stat(fname, &sb) == 0) && (S_ISCHR(sb.st_mode))) {
         const int audio_fd = open(fname, flags | O_CLOEXEC, 0);
         if (audio_fd >= 0) {
-            const int okay = test(audio_fd);
+            const SDL_bool okay = test(audio_fd);
             close(audio_fd);
             if (okay) {
                 static size_t dummyhandle = 0;
@@ -69,12 +69,12 @@ static void test_device(const int iscapture, const char *fname, int flags, int (
     }
 }
 
-static int test_stub(int fd)
+static SDL_bool test_stub(int fd)
 {
-    return 1;
+    return SDL_TRUE;
 }
 
-static void SDL_EnumUnixAudioDevices_Internal(const int iscapture, const int classic, int (*test)(int))
+static void SDL_EnumUnixAudioDevices_Internal(const SDL_bool iscapture, const SDL_bool classic, SDL_bool (*test)(int))
 {
     const int flags = iscapture ? OPEN_FLAGS_INPUT : OPEN_FLAGS_OUTPUT;
     const char *audiodev;
@@ -116,7 +116,7 @@ static void SDL_EnumUnixAudioDevices_Internal(const int iscapture, const int cla
     }
 }
 
-void SDL_EnumUnixAudioDevices(const int classic, int (*test)(int))
+void SDL_EnumUnixAudioDevices(const SDL_bool classic, SDL_bool (*test)(int))
 {
     SDL_EnumUnixAudioDevices_Internal(SDL_TRUE, classic, test);
     SDL_EnumUnixAudioDevices_Internal(SDL_FALSE, classic, test);

src/audio/SDL_audiodev_c.h

@@ -36,6 +36,6 @@
 #define OPEN_FLAGS_INPUT  (O_RDONLY | O_NONBLOCK)
 #endif
 
-extern void SDL_EnumUnixAudioDevices(const int classic, int (*test)(int));
+extern void SDL_EnumUnixAudioDevices(const SDL_bool classic, SDL_bool (*test)(int));
 
 #endif /* SDL_audiodev_c_h_ */

src/audio/SDL_sysaudio.h

@@ -18,151 +18,269 @@
      misrepresented as being the original software.
   3. This notice may not be removed or altered from any source distribution.
 */
+
 #include "SDL_internal.h"
 
 #ifndef SDL_sysaudio_h_
 #define SDL_sysaudio_h_
 
 #include "../SDL_dataqueue.h"
-#include "./SDL_audio_c.h"
 
-/* !!! FIXME: These are wordy and unlocalized... */
+#define DEBUG_AUDIOSTREAM 0
+#define DEBUG_AUDIO_CONVERT 0
+
+#if DEBUG_AUDIO_CONVERT
+#define LOG_DEBUG_AUDIO_CONVERT(from, to) SDL_Log("SDL_AUDIO_CONVERT: Converting %s to %s.\n", from, to);
+#else
+#define LOG_DEBUG_AUDIO_CONVERT(from, to)
+#endif
+
+// These pointers get set during SDL_ChooseAudioConverters() to various SIMD implementations.
+extern void (*SDL_Convert_S8_to_F32)(float *dst, const Sint8 *src, int num_samples);
+extern void (*SDL_Convert_U8_to_F32)(float *dst, const Uint8 *src, int num_samples);
+extern void (*SDL_Convert_S16_to_F32)(float *dst, const Sint16 *src, int num_samples);
+extern void (*SDL_Convert_S32_to_F32)(float *dst, const Sint32 *src, int num_samples);
+extern void (*SDL_Convert_F32_to_S8)(Sint8 *dst, const float *src, int num_samples);
+extern void (*SDL_Convert_F32_to_U8)(Uint8 *dst, const float *src, int num_samples);
+extern void (*SDL_Convert_F32_to_S16)(Sint16 *dst, const float *src, int num_samples);
+extern void (*SDL_Convert_F32_to_S32)(Sint32 *dst, const float *src, int num_samples);
+
+// !!! FIXME: These are wordy and unlocalized...
 #define DEFAULT_OUTPUT_DEVNAME "System audio output device"
 #define DEFAULT_INPUT_DEVNAME  "System audio capture device"
 
-/* The SDL audio driver */
+// these are used when no better specifics are known. We default to CD audio quality.
+#define DEFAULT_AUDIO_OUTPUT_FORMAT SDL_AUDIO_S16
+#define DEFAULT_AUDIO_OUTPUT_CHANNELS 2
+#define DEFAULT_AUDIO_OUTPUT_FREQUENCY 44100
+
+#define DEFAULT_AUDIO_CAPTURE_FORMAT SDL_AUDIO_S16
+#define DEFAULT_AUDIO_CAPTURE_CHANNELS 1
+#define DEFAULT_AUDIO_CAPTURE_FREQUENCY 44100
+
 typedef struct SDL_AudioDevice SDL_AudioDevice;
+typedef struct SDL_LogicalAudioDevice SDL_LogicalAudioDevice;
+
+// Used by src/SDL.c to initialize a particular audio driver.
+extern int SDL_InitAudio(const char *driver_name);
 
-/* Audio targets should call this as devices are added to the system (such as
+// Used by src/SDL.c to shut down previously-initialized audio.
+extern void SDL_QuitAudio(void);
+
+// Function to get a list of audio formats, ordered most similar to `format` to least, 0-terminated. Don't free results.
+const SDL_AudioFormat *SDL_ClosestAudioFormats(SDL_AudioFormat format);
+
+// Must be called at least once before using converters (SDL_CreateAudioStream will call it !!! FIXME but probably shouldn't).
+extern void SDL_ChooseAudioConverters(void);
+
+/* Backends should call this as devices are added to the system (such as
    a USB headset being plugged in), and should also be called for
    for every device found during DetectDevices(). */
-extern void SDL_AddAudioDevice(const SDL_bool iscapture, const char *name, SDL_AudioSpec *spec, void *handle);
-
-/* Audio targets should call this as devices are removed, so SDL can update
-   its list of available devices. */
-extern void SDL_RemoveAudioDevice(const SDL_bool iscapture, void *handle);
-
-/* Audio targets should call this if an opened audio device is lost while
-   being used. This can happen due to i/o errors, or a device being unplugged,
-   etc. If the device is totally gone, please also call SDL_RemoveAudioDevice()
-   as appropriate so SDL's list of devices is accurate. */
-extern void SDL_OpenedAudioDeviceDisconnected(SDL_AudioDevice *device);
-
-/* 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)
+extern SDL_AudioDevice *SDL_AddAudioDevice(const SDL_bool iscapture, const char *name, const SDL_AudioSpec *spec, void *handle);
+
+/* Backends should call this if an opened audio device is lost.
+   This can happen due to i/o errors, or a device being unplugged, etc. */
+extern void SDL_AudioDeviceDisconnected(SDL_AudioDevice *device);
+
+// Backends should call this if the system default device changes.
+extern void SDL_DefaultAudioDeviceChanged(SDL_AudioDevice *new_default_device);
+
+// Backends should call this if a device's format is changing (opened or not); SDL will update state and carry on with the new format.
+extern int SDL_AudioDeviceFormatChanged(SDL_AudioDevice *device, const SDL_AudioSpec *newspec, int new_sample_frames);
+
+// Same as above, but assume the device is already locked.
+extern int SDL_AudioDeviceFormatChangedAlreadyLocked(SDL_AudioDevice *device, const SDL_AudioSpec *newspec, int new_sample_frames);
+
+// Find the SDL_AudioDevice associated with the handle supplied to SDL_AddAudioDevice. NULL if not found. DOES NOT LOCK THE DEVICE.
+extern SDL_AudioDevice *SDL_FindPhysicalAudioDeviceByHandle(void *handle);
+
+// Find an SDL_AudioDevice, selected by a callback. NULL if not found. DOES NOT LOCK THE DEVICE.
+extern SDL_AudioDevice *SDL_FindPhysicalAudioDeviceByCallback(SDL_bool (*callback)(SDL_AudioDevice *device, void *userdata), void *userdata);
+
+// Backends should call this if they change the device format, channels, freq, or sample_frames to keep other state correct.
+extern void SDL_UpdatedAudioDeviceFormat(SDL_AudioDevice *device);
+
+// Backends can call this to get a standardized name for a thread to power a specific audio device.
+char *SDL_GetAudioThreadName(SDL_AudioDevice *device, char *buf, size_t buflen);
+
+
+// These functions are the heart of the audio threads. Backends can call them directly if they aren't using the SDL-provided thread.
+extern void SDL_OutputAudioThreadSetup(SDL_AudioDevice *device);
+extern SDL_bool SDL_OutputAudioThreadIterate(SDL_AudioDevice *device);
+extern void SDL_OutputAudioThreadShutdown(SDL_AudioDevice *device);
+extern void SDL_CaptureAudioThreadSetup(SDL_AudioDevice *device);
+extern SDL_bool SDL_CaptureAudioThreadIterate(SDL_AudioDevice *device);
+extern void SDL_CaptureAudioThreadShutdown(SDL_AudioDevice *device);
+extern void SDL_AudioThreadFinalize(SDL_AudioDevice *device);
 
 typedef struct SDL_AudioDriverImpl
 {
-    void (*DetectDevices)(void);
-    int (*OpenDevice)(SDL_AudioDevice *_this, const char *devname);
-    void (*ThreadInit)(SDL_AudioDevice *_this);   /* Called by audio thread at start */
-    void (*ThreadDeinit)(SDL_AudioDevice *_this); /* Called by audio thread at end */
-    void (*WaitDevice)(SDL_AudioDevice *_this);
-    void (*PlayDevice)(SDL_AudioDevice *_this);
-    Uint8 *(*GetDeviceBuf)(SDL_AudioDevice *_this);
-    int (*CaptureFromDevice)(SDL_AudioDevice *_this, void *buffer, int buflen);
-    void (*FlushCapture)(SDL_AudioDevice *_this);
-    void (*CloseDevice)(SDL_AudioDevice *_this);
-    void (*LockDevice)(SDL_AudioDevice *_this);
-    void (*UnlockDevice)(SDL_AudioDevice *_this);
-    void (*FreeDeviceHandle)(void *handle); /**< SDL is done with handle from SDL_AddAudioDevice() */
+    void (*DetectDevices)(SDL_AudioDevice **default_output, SDL_AudioDevice **default_capture);
+    int (*OpenDevice)(SDL_AudioDevice *device);
+    void (*ThreadInit)(SDL_AudioDevice *device);   // Called by audio thread at start
+    void (*ThreadDeinit)(SDL_AudioDevice *device); // Called by audio thread at end
+    void (*WaitDevice)(SDL_AudioDevice *device);
+    void (*PlayDevice)(SDL_AudioDevice *device, const Uint8 *buffer, int buflen);  // buffer and buflen are always from GetDeviceBuf, passed here for convenience.
+    Uint8 *(*GetDeviceBuf)(SDL_AudioDevice *device, int *buffer_size);
+    void (*WaitCaptureDevice)(SDL_AudioDevice *device);
+    int (*CaptureFromDevice)(SDL_AudioDevice *device, void *buffer, int buflen);
+    void (*FlushCapture)(SDL_AudioDevice *device);
+    void (*CloseDevice)(SDL_AudioDevice *device);
+    void (*FreeDeviceHandle)(SDL_AudioDevice *device); // SDL is done with this device; free the handle from SDL_AddAudioDevice()
     void (*Deinitialize)(void);
-    int (*GetDefaultAudioInfo)(char **name, SDL_AudioSpec *spec, int iscapture);
 
-    /* !!! FIXME: add pause(), so we can optimize instead of mixing silence. */
-
-    /* Some flags to push duplicate code into the core and reduce #ifdefs. */
-    SDL_bool ProvidesOwnCallbackThread;
+    // Some flags to push duplicate code into the core and reduce #ifdefs.
+    SDL_bool ProvidesOwnCallbackThread;  // !!! FIXME: rename this, it's not a callback thread anymore.
     SDL_bool HasCaptureSupport;
     SDL_bool OnlyHasDefaultOutputDevice;
     SDL_bool OnlyHasDefaultCaptureDevice;
     SDL_bool AllowsArbitraryDeviceNames;
-    SDL_bool SupportsNonPow2Samples;
 } SDL_AudioDriverImpl;
 
-typedef struct SDL_AudioDeviceItem
+typedef struct SDL_AudioDriver
 {
-    void *handle;
-    char *name;
-    char *original_name;
-    SDL_AudioSpec spec;
-    int dupenum;
-    struct SDL_AudioDeviceItem *next;
-} SDL_AudioDeviceItem;
+    const char *name;  // The name of this audio driver
+    const char *desc;  // The description of this audio driver
+    SDL_AudioDriverImpl impl; // the backend's interface
+    SDL_RWLock *device_list_lock;  // A mutex for device detection
+    SDL_AudioDevice *output_devices;  // the list of currently-available audio output devices.
+    SDL_AudioDevice *capture_devices;  // the list of currently-available audio capture devices.
+    SDL_AudioDeviceID default_output_device_id;
+    SDL_AudioDeviceID default_capture_device_id;
+    SDL_AtomicInt output_device_count;
+    SDL_AtomicInt capture_device_count;
+    SDL_AtomicInt last_device_instance_id;  // increments on each device add to provide unique instance IDs
+    SDL_AtomicInt shutting_down;  // non-zero during SDL_Quit, so we known not to accept any last-minute device hotplugs.
+} SDL_AudioDriver;
 
-typedef struct SDL_AudioDriver
+struct SDL_AudioStream
 {
-    /* * * */
-    /* The name of this audio driver */
-    const char *name;
+    SDL_DataQueue *queue;
+    SDL_Mutex *lock;  // this is just a copy of `queue`'s mutex. We share a lock.
 
-    /* * * */
-    /* The description of this audio driver */
-    const char *desc;
+    SDL_AudioStreamRequestCallback get_callback;
+    void *get_callback_userdata;
+    SDL_AudioStreamRequestCallback put_callback;
+    void *put_callback_userdata;
 
-    SDL_AudioDriverImpl impl;
+    Uint8 *work_buffer;    // used for scratch space during data conversion/resampling.
+    Uint8 *history_buffer;  // history for left padding and future sample rate changes.
+    Uint8 *future_buffer;  // stuff that left the queue for the right padding and will be next read's data.
+    float *left_padding;  // left padding for resampling.
+    float *right_padding;  // right padding for resampling.
 
-    /* A mutex for device detection */
-    SDL_Mutex *detectionLock;
-    SDL_bool captureDevicesRemoved;
-    SDL_bool outputDevicesRemoved;
-    int outputDeviceCount;
-    int inputDeviceCount;
-    SDL_AudioDeviceItem *outputDevices;
-    SDL_AudioDeviceItem *inputDevices;
-} SDL_AudioDriver;
+    SDL_bool flushed;
+
+    size_t work_buffer_allocation;
+    size_t history_buffer_allocation;
+    size_t future_buffer_allocation;
+    size_t resampler_padding_allocation;
+
+    int resampler_padding_frames;
+    int history_buffer_frames;
+    int future_buffer_filled_frames;
+
+    SDL_AudioSpec src_spec;
+    SDL_AudioSpec dst_spec;
+
+    int src_sample_frame_size;
+    int dst_sample_frame_size;
+    int max_sample_frame_size;
+
+    int pre_resample_channels;
+    int packetlen;
+
+    SDL_LogicalAudioDevice *bound_device;
+    SDL_AudioStream *next_binding;
+    SDL_AudioStream *prev_binding;
+};
+
+/* Logical devices are an abstraction in SDL3; you can open the same physical
+   device multiple times, and each will result in an object with its own set
+   of bound audio streams, etc, even though internally these are all processed
+   as a group when mixing the final output for the physical device. */
+struct SDL_LogicalAudioDevice
+{
+    // the unique instance ID of this device.
+    SDL_AudioDeviceID instance_id;
+
+    // The physical device associated with this opened device.
+    SDL_AudioDevice *physical_device;
+
+    // If whole logical device is paused (process no streams bound to this device).
+    SDL_AtomicInt paused;
+
+    // double-linked list of all audio streams currently bound to this opened device.
+    SDL_AudioStream *bound_streams;
+
+    // SDL_TRUE if this was opened as a default device.
+    SDL_bool is_default;
+
+    // double-linked list of opened devices on the same physical device.
+    SDL_LogicalAudioDevice *next;
+    SDL_LogicalAudioDevice *prev;
+};
 
-/* Define the SDL audio driver structure */
 struct SDL_AudioDevice
 {
-    /* * * */
-    /* Data common to all devices */
-    SDL_AudioDeviceID id;
+    // A mutex for locking access to this struct
+    SDL_Mutex *lock;
 
-    /* The device's current audio specification */
+    // human-readable name of the device. ("SoundBlaster Pro 16")
+    char *name;
+
+    // the unique instance ID of this device.
+    SDL_AudioDeviceID instance_id;
+
+    // a way for the backend to identify this device _when not opened_
+    void *handle;
+
+    // The device's current audio specification
     SDL_AudioSpec spec;
+    int buffer_size;
 
-    /* The callback's expected audio specification (converted vs device's spec). */
-    SDL_AudioSpec callbackspec;
+    // The device's default audio specification
+    SDL_AudioSpec default_spec;
 
-    /* Stream that converts and resamples. NULL if not needed. */
-    SDL_AudioStream *stream;
+    // Number of sample frames the devices wants per-buffer.
+    int sample_frames;
 
-    /* Current state flags */
-    SDL_AtomicInt shutdown; /* true if we are signaling the play thread to end. */
-    SDL_AtomicInt enabled;  /* true if device is functioning and connected. */
-    SDL_AtomicInt paused;
-    SDL_bool iscapture;
+    // Value to use for SDL_memset to silence a buffer in this device's format
+    int silence_value;
 
-    /* Scratch buffer used in the bridge between SDL and the user callback. */
-    Uint8 *work_buffer;
+    // non-zero if we are signaling the audio thread to end.
+    SDL_AtomicInt shutdown;
 
-    /* Size, in bytes, of work_buffer. */
-    Uint32 work_buffer_len;
+    // non-zero if we want the device to be destroyed (so audio thread knows to do it on termination).
+    SDL_AtomicInt condemned;
 
-    /* A mutex for locking the mixing buffers */
-    SDL_Mutex *mixer_lock;
+    // non-zero if this was a disconnected default device and we're waiting for its replacement.
+    SDL_AtomicInt zombie;
 
-    /* A thread to feed the audio device */
+    // non-zero if this has a thread running (which might be `thread` or something provided by the backend!)
+    SDL_AtomicInt thread_alive;
+
+    // SDL_TRUE if this is a capture device instead of an output device
+    SDL_bool iscapture;
+
+    // Scratch buffer used for mixing.
+    Uint8 *work_buffer;
+
+    // A thread to feed the audio device
     SDL_Thread *thread;
-    SDL_threadID threadid;
 
-    /* Queued buffers (if app not using callback). */
-    SDL_DataQueue *buffer_queue;
+    // SDL_TRUE if this physical device is currently opened by the backend.
+    SDL_bool is_opened;
 
-    /* * * */
-    /* Data private to this driver */
+    // Data private to this driver
     struct SDL_PrivateAudioData *hidden;
 
-    void *handle;
+    // All logical devices associated with this physical device.
+    SDL_LogicalAudioDevice *logical_devices;
+
+    // double-linked list of all physical devices.
+    struct SDL_AudioDevice *prev;
+    struct SDL_AudioDevice *next;
 };
 
 typedef struct AudioBootStrap
@@ -170,10 +288,10 @@ typedef struct AudioBootStrap
     const char *name;
     const char *desc;
     SDL_bool (*init)(SDL_AudioDriverImpl *impl);
-    SDL_bool demand_only; /* 1==request explicitly, or it won't be available. */
+    SDL_bool demand_only; // if SDL_TRUE: request explicitly, or it won't be available.
 } AudioBootStrap;
 
-/* Not all of these are available in a given build. Use #ifdefs, etc. */
+// Not all of these are available in a given build. Use #ifdefs, etc.
 extern AudioBootStrap PIPEWIRE_bootstrap;
 extern AudioBootStrap PULSEAUDIO_bootstrap;
 extern AudioBootStrap ALSA_bootstrap;
@@ -188,8 +306,8 @@ extern AudioBootStrap HAIKUAUDIO_bootstrap;
 extern AudioBootStrap COREAUDIO_bootstrap;
 extern AudioBootStrap DISKAUDIO_bootstrap;
 extern AudioBootStrap DUMMYAUDIO_bootstrap;
-extern AudioBootStrap aaudio_bootstrap;
-extern AudioBootStrap openslES_bootstrap;
+extern AudioBootStrap AAUDIO_bootstrap;
+extern AudioBootStrap openslES_bootstrap;  // !!! FIXME: capitalize this to match the others
 extern AudioBootStrap ANDROIDAUDIO_bootstrap;
 extern AudioBootStrap PS2AUDIO_bootstrap;
 extern AudioBootStrap PSPAUDIO_bootstrap;
@@ -201,4 +319,4 @@ extern AudioBootStrap QSAAUDIO_bootstrap;
 extern SDL_AudioDevice *get_audio_dev(SDL_AudioDeviceID id);
 extern int get_max_num_audio_dev(void);
 
-#endif /* SDL_sysaudio_h_ */
+#endif // SDL_sysaudio_h_

src/audio/SDL_wave.c

@@ -1241,7 +1241,7 @@ static int LAW_Decode(WaveFile *file, Uint8 **audio_buf, Uint32 *audio_len)
 
     dst = (Sint16 *)src;
 
-    /* Work backwards, since we're expanding in-place. SDL_AudioSpec.format will
+    /* Work backwards, since we're expanding in-place. `format` will
      * inform the caller about the byte order.
      */
     i = sample_count;
@@ -1667,15 +1667,11 @@ static int WaveCheckFormat(WaveFile *file, size_t datalength)
 
     if (format->channels == 0) {
         return SDL_SetError("Invalid number of channels");
-    } else if (format->channels > 255) {
-        /* Limit given by SDL_AudioSpec.channels. */
-        return SDL_SetError("Number of channels exceeds limit of 255");
     }
 
     if (format->frequency == 0) {
         return SDL_SetError("Invalid sample rate");
     } else if (format->frequency > INT_MAX) {
-        /* Limit given by SDL_AudioSpec.freq. */
         return SDL_SetError("Sample rate exceeds limit of %d", INT_MAX);
     }
 
@@ -2025,13 +2021,12 @@ static int WaveLoad(SDL_RWops *src, WaveFile *file, SDL_AudioSpec *spec, Uint8 *
         break;
     }
 
-    /* Setting up the SDL_AudioSpec. All unsupported formats were filtered out
+    /* Setting up the specs. All unsupported formats were filtered out
      * by checks earlier in this function.
      */
-    SDL_zerop(spec);
     spec->freq = format->frequency;
     spec->channels = (Uint8)format->channels;
-    spec->samples = 4096; /* Good default buffer size */
+    spec->format = 0;
 
     switch (format->encoding) {
     case MS_ADPCM_CODE:
@@ -2061,10 +2056,10 @@ static int WaveLoad(SDL_RWops *src, WaveFile *file, SDL_AudioSpec *spec, Uint8 *
             return SDL_SetError("Unexpected %u-bit PCM data format", (unsigned int)format->bitspersample);
         }
         break;
+    default:
+        return SDL_SetError("Unexpected data format");
     }
 
-    spec->silence = SDL_GetSilenceValueForFormat(spec->format);
-
     /* Report the end position back to the cleanup code. */
     if (RIFFlengthknown) {
         chunk->position = RIFFend;
@@ -2075,31 +2070,26 @@ static int WaveLoad(SDL_RWops *src, WaveFile *file, SDL_AudioSpec *spec, Uint8 *
     return 0;
 }
 
-SDL_AudioSpec *SDL_LoadWAV_RW(SDL_RWops *src, SDL_bool freesrc, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len)
+int SDL_LoadWAV_RW(SDL_RWops *src, int freesrc, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len)
 {
     int result = -1;
     WaveFile file;
 
-    SDL_zero(file);
-
     /* Make sure we are passed a valid data source */
     if (src == NULL) {
-        /* Error may come from RWops. */
-        goto done;
+        return -1;  /* Error may come from RWops. */
     } else if (spec == NULL) {
-        SDL_InvalidParamError("spec");
-        goto done;
+        return SDL_InvalidParamError("spec");
     } else if (audio_buf == NULL) {
-        SDL_InvalidParamError("audio_buf");
-        goto done;
+        return SDL_InvalidParamError("audio_buf");
     } else if (audio_len == NULL) {
-        SDL_InvalidParamError("audio_len");
-        goto done;
+        return SDL_InvalidParamError("audio_len");
     }
 
     *audio_buf = NULL;
     *audio_len = 0;
 
+    SDL_zero(file);
     file.riffhint = WaveGetRiffSizeHint();
     file.trunchint = WaveGetTruncationHint();
     file.facthint = WaveGetFactChunkHint();
@@ -2107,7 +2097,6 @@ SDL_AudioSpec *SDL_LoadWAV_RW(SDL_RWops *src, SDL_bool freesrc, SDL_AudioSpec *s
     result = WaveLoad(src, &file, spec, audio_buf, audio_len);
     if (result < 0) {
         SDL_free(*audio_buf);
-        spec = NULL;
         audio_buf = NULL;
         audio_len = 0;
     }
@@ -2119,13 +2108,11 @@ SDL_AudioSpec *SDL_LoadWAV_RW(SDL_RWops *src, SDL_bool freesrc, SDL_AudioSpec *s
     WaveFreeChunkData(&file.chunk);
     SDL_free(file.decoderdata);
 
-done:
-    if (freesrc && src) {
-        SDL_RWclose(src);
-    }
-    if (result == 0) {
-        return spec;
-    } else {
-        return NULL;
-    }
+    return result;
+}
+
+int SDL_LoadWAV(const char *path, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len)
+{
+    return SDL_LoadWAV_RW(SDL_RWFromFile(path, "rb"), 1, spec, audio_buf, audio_len);
 }
+

src/audio/aaudio/SDL_aaudio.c

@@ -30,37 +30,37 @@
 #include <stdbool.h>
 #include <aaudio/AAudio.h>
 
+#if __ANDROID_API__ < 31
+#define AAUDIO_FORMAT_PCM_I32 4
+#endif
+
 struct SDL_PrivateAudioData
 {
     AAudioStream *stream;
-
-    /* Raw mixing buffer */
-    Uint8 *mixbuf;
-    int mixlen;
-    int frame_size;
-
-    /* Resume device if it was paused automatically */
-    int resume;
+    Uint8 *mixbuf;    // Raw mixing buffer
+    SDL_Semaphore *semaphore;
+    SDL_AtomicInt error_callback_triggered;
+    int resume;  // Resume device if it was paused automatically
 };
 
-/* Debug */
+// Debug
 #if 0
 #define LOGI(...) SDL_Log(__VA_ARGS__);
 #else
 #define LOGI(...)
 #endif
 
+#define LIB_AAUDIO_SO "libaaudio.so"
+
 typedef struct AAUDIO_Data
 {
-    AAudioStreamBuilder *builder;
     void *handle;
 #define SDL_PROC(ret, func, params) ret (*func) params;
 #include "SDL_aaudiofuncs.h"
-#undef SDL_PROC
 } AAUDIO_Data;
 static AAUDIO_Data ctx;
 
-static int aaudio_LoadFunctions(AAUDIO_Data *data)
+static int AAUDIO_LoadFunctions(AAUDIO_Data *data)
 {
 #define SDL_PROC(ret, func, params)                                                             \
     do {                                                                                        \
@@ -70,23 +70,95 @@ static int aaudio_LoadFunctions(AAUDIO_Data *data)
         }                                                                                       \
     } while (0);
 #include "SDL_aaudiofuncs.h"
-#undef SDL_PROC
     return 0;
 }
 
-void aaudio_errorCallback(AAudioStream *stream, void *userData, aaudio_result_t error);
-void aaudio_errorCallback(AAudioStream *stream, void *userData, aaudio_result_t error)
+
+static void AAUDIO_errorCallback(AAudioStream *stream, void *userData, aaudio_result_t error)
 {
-    LOGI("SDL aaudio_errorCallback: %d - %s", error, ctx.AAudio_convertResultToText(error));
+    LOGI("SDL AAUDIO_errorCallback: %d - %s", error, ctx.AAudio_convertResultToText(error));
+
+    // You MUST NOT close the audio stream from this callback, so we cannot call SDL_AudioDeviceDisconnected here.
+    // Just flag the device so we can kill it in WaitDevice/PlayDevice instead.
+    SDL_AudioDevice *device = (SDL_AudioDevice *) userData;
+    SDL_AtomicSet(&device->hidden->error_callback_triggered, 1);
+    SDL_PostSemaphore(device->hidden->semaphore);  // in case we're blocking in WaitDevice.
 }
 
-#define LIB_AAUDIO_SO "libaaudio.so"
+// due to the way the aaudio data callback works, PlayDevice is a no-op. The callback collects audio while SDL camps in WaitDevice and
+//  fires a semaphore that will unblock WaitDevice and start a new iteration, so when the callback runs again, WaitDevice is ready
+//  to hand it more data.
+static aaudio_data_callback_result_t AAUDIO_dataCallback(AAudioStream *stream, void *userData, void *audioData, int32_t numFrames)
+{
+    SDL_AudioDevice *device = (SDL_AudioDevice *) userData;
+    SDL_assert(numFrames == device->sample_frames);
+    if (device->iscapture) {
+        SDL_memcpy(device->hidden->mixbuf, audioData, device->buffer_size);
+    } else {
+        SDL_memcpy(audioData, device->hidden->mixbuf, device->buffer_size);
+    }
+    SDL_PostSemaphore(device->hidden->semaphore);
+    return AAUDIO_CALLBACK_RESULT_CONTINUE;
+}
 
-static int aaudio_OpenDevice(SDL_AudioDevice *_this, const char *devname)
+static Uint8 *AAUDIO_GetDeviceBuf(SDL_AudioDevice *device, int *bufsize)
 {
-    struct SDL_PrivateAudioData *private;
-    SDL_bool iscapture = _this->iscapture;
+    return device->hidden->mixbuf;
+}
+
+static void AAUDIO_WaitDevice(SDL_AudioDevice *device)
+{
+    SDL_WaitSemaphore(device->hidden->semaphore);
+}
+
+static void AAUDIO_PlayDevice(SDL_AudioDevice *device, const Uint8 *buffer, int buflen)
+{
+    // AAUDIO_dataCallback picks up our work and unblocks AAUDIO_WaitDevice. But make sure we didn't fail here.
+    if (SDL_AtomicGet(&device->hidden->error_callback_triggered)) {
+        SDL_AtomicSet(&device->hidden->error_callback_triggered, 0);
+        SDL_AudioDeviceDisconnected(device);
+    }
+}
+
+// no need for a FlushCapture implementation, just don't read mixbuf until the next iteration.
+static int AAUDIO_CaptureFromDevice(SDL_AudioDevice *device, void *buffer, int buflen)
+{
+    const int cpy = SDL_min(buflen, device->buffer_size);
+    SDL_memcpy(buffer, device->hidden->mixbuf, cpy);
+    return cpy;
+}
+
+static void AAUDIO_CloseDevice(SDL_AudioDevice *device)
+{
+    struct SDL_PrivateAudioData *hidden = device->hidden;
+    LOGI(__func__);
+
+    if (hidden) {
+        if (hidden->stream) {
+            ctx.AAudioStream_requestStop(hidden->stream);
+            // !!! FIXME: do we have to wait for the state to change to make sure all buffered audio has played, or will close do this (or will the system do this after the close)?
+            // !!! FIXME: also, will this definitely wait for a running data callback to finish, and then stop the callback from firing again?
+            ctx.AAudioStream_close(hidden->stream);
+        }
+
+        if (hidden->semaphore) {
+            SDL_DestroySemaphore(hidden->semaphore);
+        }
+
+        SDL_free(hidden->mixbuf);
+        SDL_free(hidden);
+        device->hidden = NULL;
+    }
+}
+
+static int AAUDIO_OpenDevice(SDL_AudioDevice *device)
+{
+    struct SDL_PrivateAudioData *hidden;
+    const SDL_bool iscapture = device->iscapture;
     aaudio_result_t res;
+
+    SDL_assert(device->handle != NULL);  // AAUDIO_UNSPECIFIED is zero, so legit devices should all be non-zero.
+
     LOGI(__func__);
 
     if (iscapture) {
@@ -96,75 +168,111 @@ static int aaudio_OpenDevice(SDL_AudioDevice *_this, const char *devname)
         }
     }
 
-    _this->hidden = (struct SDL_PrivateAudioData *)SDL_calloc(1, sizeof(*_this->hidden));
-    if (_this->hidden == NULL) {
+    hidden = device->hidden = (struct SDL_PrivateAudioData *)SDL_calloc(1, sizeof(*device->hidden));
+    if (hidden == NULL) {
         return SDL_OutOfMemory();
     }
-    private = _this->hidden;
-
-    ctx.AAudioStreamBuilder_setSampleRate(ctx.builder, _this->spec.freq);
-    ctx.AAudioStreamBuilder_setChannelCount(ctx.builder, _this->spec.channels);
-    if(devname != NULL) {
-        int aaudio_device_id = SDL_atoi(devname);
-        LOGI("Opening device id %d", aaudio_device_id);
-        ctx.AAudioStreamBuilder_setDeviceId(ctx.builder, aaudio_device_id);
-    }
-    {
-        aaudio_direction_t direction = (iscapture ? AAUDIO_DIRECTION_INPUT : AAUDIO_DIRECTION_OUTPUT);
-        ctx.AAudioStreamBuilder_setDirection(ctx.builder, direction);
+
+    SDL_AtomicSet(&hidden->error_callback_triggered, 0);
+
+    AAudioStreamBuilder *builder = NULL;
+    res = ctx.AAudio_createStreamBuilder(&builder);
+    if (res != AAUDIO_OK) {
+        LOGI("SDL Failed AAudio_createStreamBuilder %d", res);
+        return SDL_SetError("SDL Failed AAudio_createStreamBuilder %d", res);
+    } else if (builder == NULL) {
+        LOGI("SDL Failed AAudio_createStreamBuilder - builder NULL");
+        return SDL_SetError("SDL Failed AAudio_createStreamBuilder - builder NULL");
     }
-    {
-        aaudio_format_t format = AAUDIO_FORMAT_PCM_FLOAT;
-        if (_this->spec.format == SDL_AUDIO_S16SYS) {
-            format = AAUDIO_FORMAT_PCM_I16;
-        } else if (_this->spec.format == SDL_AUDIO_S16SYS) {
-            format = AAUDIO_FORMAT_PCM_FLOAT;
-        }
-        ctx.AAudioStreamBuilder_setFormat(ctx.builder, format);
+
+    // !!! FIXME: call AAudioStreamBuilder_setPerformanceMode(builder, AAUDIO_PERFORMANCE_MODE_LOW_LATENCY); ?
+
+    ctx.AAudioStreamBuilder_setSampleRate(builder, device->spec.freq);
+    ctx.AAudioStreamBuilder_setChannelCount(builder, device->spec.channels);
+
+    const int aaudio_device_id = (int) ((size_t) device->handle);
+    LOGI("Opening device id %d", aaudio_device_id);
+    ctx.AAudioStreamBuilder_setDeviceId(builder, aaudio_device_id);
+
+    const aaudio_direction_t direction = (iscapture ? AAUDIO_DIRECTION_INPUT : AAUDIO_DIRECTION_OUTPUT);
+    ctx.AAudioStreamBuilder_setDirection(builder, direction);
+    aaudio_format_t format;
+    if ((device->spec.format == SDL_AUDIO_S32SYS) && (SDL_GetAndroidSDKVersion() >= 31)) {
+        format = AAUDIO_FORMAT_PCM_I32;
+    } else if (device->spec.format == SDL_AUDIO_F32SYS) {
+        format = AAUDIO_FORMAT_PCM_FLOAT;
+    } else {
+        format = AAUDIO_FORMAT_PCM_I16;  // sint16 is a safe bet for everything else.
     }
 
-    ctx.AAudioStreamBuilder_setErrorCallback(ctx.builder, aaudio_errorCallback, private);
+    ctx.AAudioStreamBuilder_setFormat(builder, format);
+    ctx.AAudioStreamBuilder_setErrorCallback(builder, AAUDIO_errorCallback, device);
+    ctx.AAudioStreamBuilder_setDataCallback(builder, AAUDIO_dataCallback, device);
+    ctx.AAudioStreamBuilder_setPerformanceMode(builder, AAUDIO_PERFORMANCE_MODE_LOW_LATENCY);
 
     LOGI("AAudio Try to open %u hz %u bit chan %u %s samples %u",
-         _this->spec.freq, SDL_AUDIO_BITSIZE(_this->spec.format),
-         _this->spec.channels, (_this->spec.format & 0x1000) ? "BE" : "LE", _this->spec.samples);
+         device->spec.freq, SDL_AUDIO_BITSIZE(device->spec.format),
+         device->spec.channels, SDL_AUDIO_ISBIGENDIAN(device->spec.format) ? "BE" : "LE", device->sample_frames);
+
+    res = ctx.AAudioStreamBuilder_openStream(builder, &hidden->stream);
 
-    res = ctx.AAudioStreamBuilder_openStream(ctx.builder, &private->stream);
     if (res != AAUDIO_OK) {
         LOGI("SDL Failed AAudioStreamBuilder_openStream %d", res);
+        ctx.AAudioStreamBuilder_delete(builder);
         return SDL_SetError("%s : %s", __func__, ctx.AAudio_convertResultToText(res));
     }
 
-    _this->spec.freq = ctx.AAudioStream_getSampleRate(private->stream);
-    _this->spec.channels = ctx.AAudioStream_getChannelCount(private->stream);
-    {
-        aaudio_format_t fmt = ctx.AAudioStream_getFormat(private->stream);
-        if (fmt == AAUDIO_FORMAT_PCM_I16) {
-            _this->spec.format = SDL_AUDIO_S16SYS;
-        } else if (fmt == AAUDIO_FORMAT_PCM_FLOAT) {
-            _this->spec.format = SDL_AUDIO_F32SYS;
+    device->sample_frames = (int) ctx.AAudioStream_getFramesPerDataCallback(hidden->stream);
+    if (device->sample_frames == AAUDIO_UNSPECIFIED) {
+        // if this happens, figure out a reasonable sample frame count, tear down this stream and force it in a new stream.
+        device->sample_frames = (int) (ctx.AAudioStream_getBufferCapacityInFrames(hidden->stream) / 4);
+        LOGI("AAUDIO: Got a stream with unspecified sample frames per data callback! Retrying with %d frames...", device->sample_frames);
+        ctx.AAudioStream_close(hidden->stream);
+        ctx.AAudioStreamBuilder_setFramesPerDataCallback(builder, device->sample_frames);
+        res = ctx.AAudioStreamBuilder_openStream(builder, &hidden->stream);
+        if (res != AAUDIO_OK) {  // oh well, we tried.
+            LOGI("SDL Failed AAudioStreamBuilder_openStream %d", res);
+            ctx.AAudioStreamBuilder_delete(builder);
+            return SDL_SetError("%s : %s", __func__, ctx.AAudio_convertResultToText(res));
         }
     }
 
-    LOGI("AAudio Try to open %u hz %u bit chan %u %s samples %u",
-         _this->spec.freq, SDL_AUDIO_BITSIZE(_this->spec.format),
-         _this->spec.channels, (_this->spec.format & 0x1000) ? "BE" : "LE", _this->spec.samples);
+    ctx.AAudioStreamBuilder_delete(builder);
 
-    SDL_CalculateAudioSpec(&_this->spec);
+    device->spec.freq = ctx.AAudioStream_getSampleRate(hidden->stream);
+    device->spec.channels = ctx.AAudioStream_getChannelCount(hidden->stream);
 
-    /* Allocate mixing buffer */
-    if (!iscapture) {
-        private->mixlen = _this->spec.size;
-        private->mixbuf = (Uint8 *)SDL_malloc(private->mixlen);
-        if (private->mixbuf == NULL) {
-            return SDL_OutOfMemory();
-        }
-        SDL_memset(private->mixbuf, _this->spec.silence, _this->spec.size);
+    format = ctx.AAudioStream_getFormat(hidden->stream);
+    if (format == AAUDIO_FORMAT_PCM_I16) {
+        device->spec.format = SDL_AUDIO_S16SYS;
+    } else if (format == AAUDIO_FORMAT_PCM_I32) {
+        device->spec.format = SDL_AUDIO_S32SYS;
+    } else if (format == AAUDIO_FORMAT_PCM_FLOAT) {
+        device->spec.format = SDL_AUDIO_F32SYS;
+    } else {
+        return SDL_SetError("Got unexpected audio format %d from AAudioStream_getFormat", (int) format);
+    }
+
+    LOGI("AAudio Actually opened %u hz %u bit chan %u %s samples %u",
+         device->spec.freq, SDL_AUDIO_BITSIZE(device->spec.format),
+         device->spec.channels, SDL_AUDIO_ISBIGENDIAN(device->spec.format) ? "BE" : "LE", device->sample_frames);
+
+    SDL_UpdatedAudioDeviceFormat(device);
+
+    // Allocate mixing buffer
+    hidden->mixbuf = (Uint8 *)SDL_malloc(device->buffer_size);
+    if (hidden->mixbuf == NULL) {
+        return SDL_OutOfMemory();
     }
+    SDL_memset(hidden->mixbuf, device->silence_value, device->buffer_size);
 
-    private->frame_size = _this->spec.channels * (SDL_AUDIO_BITSIZE(_this->spec.format) / 8);
+    hidden->semaphore = SDL_CreateSemaphore(0);
+    if (!hidden->semaphore) {
+        LOGI("SDL Failed SDL_CreateSemaphore %s iscapture:%d", SDL_GetError(), iscapture);
+        return -1;
+    }
 
-    res = ctx.AAudioStream_requestStart(private->stream);
+    res = ctx.AAudioStream_requestStart(hidden->stream);
     if (res != AAUDIO_OK) {
         LOGI("SDL Failed AAudioStream_requestStart %d iscapture:%d", res, iscapture);
         return SDL_SetError("%s : %s", __func__, ctx.AAudio_convertResultToText(res));
@@ -174,98 +282,114 @@ static int aaudio_OpenDevice(SDL_AudioDevice *_this, const char *devname)
     return 0;
 }
 
-static void aaudio_CloseDevice(SDL_AudioDevice *_this)
+static SDL_bool PauseOneDevice(SDL_AudioDevice *device, void *userdata)
 {
-    struct SDL_PrivateAudioData *private = _this->hidden;
-    aaudio_result_t res;
-    LOGI(__func__);
+    struct SDL_PrivateAudioData *hidden = (struct SDL_PrivateAudioData *)device->hidden;
+    if (hidden != NULL) {
+        if (hidden->stream) {
+            aaudio_result_t res;
 
-    if (private->stream) {
-        res = ctx.AAudioStream_requestStop(private->stream);
-        if (res != AAUDIO_OK) {
-            LOGI("SDL Failed AAudioStream_requestStop %d", res);
-            SDL_SetError("%s : %s", __func__, ctx.AAudio_convertResultToText(res));
-            return;
-        }
+            if (device->iscapture) {
+                // Pause() isn't implemented for 'capture', use Stop()
+                res = ctx.AAudioStream_requestStop(hidden->stream);
+            } else {
+                res = ctx.AAudioStream_requestPause(hidden->stream);
+            }
 
-        res = ctx.AAudioStream_close(private->stream);
-        if (res != AAUDIO_OK) {
-            LOGI("SDL Failed AAudioStreamBuilder_delete %d", res);
-            SDL_SetError("%s : %s", __func__, ctx.AAudio_convertResultToText(res));
-            return;
+            if (res != AAUDIO_OK) {
+                LOGI("SDL Failed AAudioStream_requestPause %d", res);
+                SDL_SetError("%s : %s", __func__, ctx.AAudio_convertResultToText(res));
+            }
+
+            SDL_LockMutex(device->lock);
+            hidden->resume = SDL_TRUE;
         }
     }
+    return SDL_FALSE;  // keep enumerating.
+}
 
-    SDL_free(_this->hidden->mixbuf);
-    SDL_free(_this->hidden);
+// Pause (block) all non already paused audio devices by taking their mixer lock
+void AAUDIO_PauseDevices(void)
+{
+    if (ctx.handle != NULL) {  // AAUDIO driver is used?
+        (void) SDL_FindPhysicalAudioDeviceByCallback(PauseOneDevice, NULL);
+    }
 }
 
-static Uint8 *aaudio_GetDeviceBuf(SDL_AudioDevice *_this)
+// Resume (unblock) all non already paused audio devices by releasing their mixer lock
+static SDL_bool ResumeOneDevice(SDL_AudioDevice *device, void *userdata)
 {
-    struct SDL_PrivateAudioData *private = _this->hidden;
-    return private->mixbuf;
+    struct SDL_PrivateAudioData *hidden = device->hidden;
+    if (hidden != NULL) {
+        if (hidden->resume) {
+            hidden->resume = SDL_FALSE;
+            SDL_UnlockMutex(device->lock);
+        }
+
+        if (hidden->stream) {
+            aaudio_result_t res = ctx.AAudioStream_requestStart(hidden->stream);
+            if (res != AAUDIO_OK) {
+                LOGI("SDL Failed AAudioStream_requestStart %d", res);
+                SDL_SetError("%s : %s", __func__, ctx.AAudio_convertResultToText(res));
+            }
+        }
+    }
+    return SDL_FALSE;  // keep enumerating.
 }
 
-static void aaudio_PlayDevice(SDL_AudioDevice *_this)
+void AAUDIO_ResumeDevices(void)
 {
-    struct SDL_PrivateAudioData *private = _this->hidden;
-    aaudio_result_t res;
-    int64_t timeoutNanoseconds = 1 * 1000 * 1000; /* 8 ms */
-    res = ctx.AAudioStream_write(private->stream, private->mixbuf, private->mixlen / private->frame_size, timeoutNanoseconds);
-    if (res < 0) {
-        LOGI("%s : %s", __func__, ctx.AAudio_convertResultToText(res));
-    } else {
-        LOGI("SDL AAudio play: %d frames, wanted:%d frames", (int)res, private->mixlen / private->frame_size);
+    if (ctx.handle != NULL) {  // AAUDIO driver is used?
+        (void) SDL_FindPhysicalAudioDeviceByCallback(ResumeOneDevice, NULL);
     }
+}
 
-#if 0
-    /* Log under-run count */
-    {
-        static int prev = 0;
-        int32_t cnt = ctx.AAudioStream_getXRunCount(private->stream);
-        if (cnt != prev) {
-            SDL_Log("AAudio underrun: %d - total: %d", cnt - prev, cnt);
-            prev = cnt;
+// !!! FIXME: do we need this now that we use the callback?
+/*
+ We can sometimes get into a state where AAudioStream_write() will just block forever until we pause and unpause.
+ None of the standard state queries indicate any problem in my testing. And the error callback doesn't actually get called.
+ But, AAudioStream_getTimestamp() does return AAUDIO_ERROR_INVALID_STATE
+*/
+static SDL_bool DetectBrokenPlayStatePerDevice(SDL_AudioDevice *device, void *userdata)
+{
+    SDL_assert(device != NULL);
+    if (!device->iscapture && device->hidden != NULL) {
+        struct SDL_PrivateAudioData *hidden = device->hidden;
+        int64_t framePosition, timeNanoseconds;
+        aaudio_result_t res = ctx.AAudioStream_getTimestamp(hidden->stream, CLOCK_MONOTONIC, &framePosition, &timeNanoseconds);
+        if (res == AAUDIO_ERROR_INVALID_STATE) {
+            aaudio_stream_state_t currentState = ctx.AAudioStream_getState(hidden->stream);
+            // AAudioStream_getTimestamp() will also return AAUDIO_ERROR_INVALID_STATE while the stream is still initially starting. But we only care if it silently went invalid while playing.
+            if (currentState == AAUDIO_STREAM_STATE_STARTED) {
+                LOGI("SDL AAUDIO_DetectBrokenPlayState: detected invalid audio device state: AAudioStream_getTimestamp result=%d, framePosition=%lld, timeNanoseconds=%lld, getState=%d", (int)res, (long long)framePosition, (long long)timeNanoseconds, (int)currentState);
+                return SDL_TRUE;  // this guy.
+            }
         }
     }
-#endif
+
+    return SDL_FALSE;  // enumerate more devices.
 }
 
-static int aaudio_CaptureFromDevice(SDL_AudioDevice *_this, void *buffer, int buflen)
+SDL_bool AAUDIO_DetectBrokenPlayState(void)
 {
-    struct SDL_PrivateAudioData *private = _this->hidden;
-    aaudio_result_t res;
-    int64_t timeoutNanoseconds = 8 * 1000 * 1000; /* 8 ms */
-    res = ctx.AAudioStream_read(private->stream, buffer, buflen / private->frame_size, timeoutNanoseconds);
-    if (res < 0) {
-        LOGI("%s : %s", __func__, ctx.AAudio_convertResultToText(res));
-        return -1;
-    }
-    LOGI("SDL AAudio capture:%d frames, wanted:%d frames", (int)res, buflen / private->frame_size);
-    return res * private->frame_size;
+    return (ctx.handle && SDL_FindPhysicalAudioDeviceByCallback(DetectBrokenPlayStatePerDevice, NULL) != NULL) ? SDL_TRUE : SDL_FALSE;
 }
 
-static void aaudio_Deinitialize(void)
+static void AAUDIO_Deinitialize(void)
 {
+    Android_StopAudioHotplug();
+
     LOGI(__func__);
     if (ctx.handle) {
-        if (ctx.builder) {
-            aaudio_result_t res;
-            res = ctx.AAudioStreamBuilder_delete(ctx.builder);
-            if (res != AAUDIO_OK) {
-                SDL_SetError("Failed AAudioStreamBuilder_delete %s", ctx.AAudio_convertResultToText(res));
-            }
-        }
         SDL_UnloadObject(ctx.handle);
     }
-    ctx.handle = NULL;
-    ctx.builder = NULL;
+    SDL_zero(ctx);
     LOGI("End AAUDIO %s", SDL_GetError());
 }
 
-static SDL_bool aaudio_Init(SDL_AudioDriverImpl *impl)
+
+static SDL_bool AAUDIO_Init(SDL_AudioDriverImpl *impl)
 {
-    aaudio_result_t res;
     LOGI(__func__);
 
     /* AAudio was introduced in Android 8.0, but has reference counting crash issues in that release,
@@ -282,241 +406,34 @@ static SDL_bool aaudio_Init(SDL_AudioDriverImpl *impl)
     ctx.handle = SDL_LoadObject(LIB_AAUDIO_SO);
     if (ctx.handle == NULL) {
         LOGI("SDL couldn't find " LIB_AAUDIO_SO);
-        goto failure;
-    }
-
-    if (aaudio_LoadFunctions(&ctx) < 0) {
-        goto failure;
-    }
-
-    res = ctx.AAudio_createStreamBuilder(&ctx.builder);
-    if (res != AAUDIO_OK) {
-        LOGI("SDL Failed AAudio_createStreamBuilder %d", res);
-        goto failure;
+        return SDL_FALSE;
     }
 
-    if (ctx.builder == NULL) {
-        LOGI("SDL Failed AAudio_createStreamBuilder - builder NULL");
-        goto failure;
+    if (AAUDIO_LoadFunctions(&ctx) < 0) {
+        SDL_UnloadObject(ctx.handle);
+        SDL_zero(ctx);
+        return SDL_FALSE;
     }
 
-    impl->DetectDevices = Android_DetectDevices;
-    impl->Deinitialize = aaudio_Deinitialize;
-    impl->OpenDevice = aaudio_OpenDevice;
-    impl->CloseDevice = aaudio_CloseDevice;
-    impl->PlayDevice = aaudio_PlayDevice;
-    impl->GetDeviceBuf = aaudio_GetDeviceBuf;
-    impl->CaptureFromDevice = aaudio_CaptureFromDevice;
-    impl->AllowsArbitraryDeviceNames = SDL_TRUE;
+    impl->ThreadInit = Android_AudioThreadInit;
+    impl->DetectDevices = Android_StartAudioHotplug;
+    impl->Deinitialize = AAUDIO_Deinitialize;
+    impl->OpenDevice = AAUDIO_OpenDevice;
+    impl->CloseDevice = AAUDIO_CloseDevice;
+    impl->WaitDevice = AAUDIO_WaitDevice;
+    impl->PlayDevice = AAUDIO_PlayDevice;
+    impl->GetDeviceBuf = AAUDIO_GetDeviceBuf;
+    impl->WaitCaptureDevice = AAUDIO_WaitDevice;
+    impl->CaptureFromDevice = AAUDIO_CaptureFromDevice;
 
-    /* and the capabilities */
     impl->HasCaptureSupport = SDL_TRUE;
-    impl->OnlyHasDefaultOutputDevice = SDL_FALSE;
-    impl->OnlyHasDefaultCaptureDevice = SDL_FALSE;
 
-    /* this audio target is available. */
-    LOGI("SDL aaudio_Init OK");
+    LOGI("SDL AAUDIO_Init OK");
     return SDL_TRUE;
-
-failure:
-    if (ctx.handle) {
-        if (ctx.builder) {
-            ctx.AAudioStreamBuilder_delete(ctx.builder);
-        }
-        SDL_UnloadObject(ctx.handle);
-    }
-    ctx.handle = NULL;
-    ctx.builder = NULL;
-    return SDL_FALSE;
 }
 
-AudioBootStrap aaudio_bootstrap = {
-    "AAudio", "AAudio audio driver", aaudio_Init, SDL_FALSE
+AudioBootStrap AAUDIO_bootstrap = {
+    "AAudio", "AAudio audio driver", AAUDIO_Init, SDL_FALSE
 };
 
-/* Pause (block) all non already paused audio devices by taking their mixer lock */
-void aaudio_PauseDevices(void)
-{
-    int i;
-
-    /* AAUDIO driver is not used */
-    if (ctx.handle == NULL) {
-        return;
-    }
-
-    for (i = 0; i < get_max_num_audio_dev(); i++) {
-        SDL_AudioDevice *_this = get_audio_dev(i);
-        SDL_AudioDevice *audioDevice = NULL;
-        SDL_AudioDevice *captureDevice = NULL;
-
-        if (_this == NULL) {
-            continue;
-        }
-
-        if (_this->iscapture) {
-            captureDevice = _this;
-        } else {
-            audioDevice = _this;
-        }
-
-        if (audioDevice != NULL && audioDevice->hidden != NULL) {
-            struct SDL_PrivateAudioData *private = (struct SDL_PrivateAudioData *)audioDevice->hidden;
-
-            if (private->stream) {
-                aaudio_result_t res = ctx.AAudioStream_requestPause(private->stream);
-                if (res != AAUDIO_OK) {
-                    LOGI("SDL Failed AAudioStream_requestPause %d", res);
-                    SDL_SetError("%s : %s", __func__, ctx.AAudio_convertResultToText(res));
-                }
-            }
-
-            if (SDL_AtomicGet(&audioDevice->paused)) {
-                /* The device is already paused, leave it alone */
-                private->resume = SDL_FALSE;
-            } else {
-                SDL_LockMutex(audioDevice->mixer_lock);
-                SDL_AtomicSet(&audioDevice->paused, 1);
-                private->resume = SDL_TRUE;
-            }
-        }
-
-        if (captureDevice != NULL && captureDevice->hidden != NULL) {
-            struct SDL_PrivateAudioData *private = (struct SDL_PrivateAudioData *)audioDevice->hidden;
-
-            if (private->stream) {
-                /* Pause() isn't implemented for 'capture', use Stop() */
-                aaudio_result_t res = ctx.AAudioStream_requestStop(private->stream);
-                if (res != AAUDIO_OK) {
-                    LOGI("SDL Failed AAudioStream_requestStop %d", res);
-                    SDL_SetError("%s : %s", __func__, ctx.AAudio_convertResultToText(res));
-                }
-            }
-
-            if (SDL_AtomicGet(&captureDevice->paused)) {
-                /* The device is already paused, leave it alone */
-                private->resume = SDL_FALSE;
-            } else {
-                SDL_LockMutex(captureDevice->mixer_lock);
-                SDL_AtomicSet(&captureDevice->paused, 1);
-                private->resume = SDL_TRUE;
-            }
-        }
-
-    }
-}
-
-/* Resume (unblock) all non already paused audio devices by releasing their mixer lock */
-void aaudio_ResumeDevices(void)
-{
-    int i;
-
-    /* AAUDIO driver is not used */
-    if (ctx.handle == NULL) {
-        return;
-    }
-
-    for (i = 0; i < get_max_num_audio_dev(); i++) {
-        SDL_AudioDevice *_this = get_audio_dev(i);
-        SDL_AudioDevice *audioDevice = NULL;
-        SDL_AudioDevice *captureDevice = NULL;
-
-        if (_this == NULL) {
-            continue;
-        }
-
-        if (_this->iscapture) {
-            captureDevice = _this;
-        } else {
-            audioDevice = _this;
-        }
-
-        if (audioDevice != NULL && audioDevice->hidden != NULL) {
-            struct SDL_PrivateAudioData *private = audioDevice->hidden;
-
-            if (private->resume) {
-                SDL_AtomicSet(&audioDevice->paused, 0);
-                private->resume = SDL_FALSE;
-                SDL_UnlockMutex(audioDevice->mixer_lock);
-            }
-
-            if (private->stream) {
-                aaudio_result_t res = ctx.AAudioStream_requestStart(private->stream);
-                if (res != AAUDIO_OK) {
-                    LOGI("SDL Failed AAudioStream_requestStart %d", res);
-                    SDL_SetError("%s : %s", __func__, ctx.AAudio_convertResultToText(res));
-                }
-            }
-        }
-
-        if (captureDevice != NULL && captureDevice->hidden != NULL) {
-            struct SDL_PrivateAudioData *private = audioDevice->hidden;
-
-            if (private->resume) {
-                SDL_AtomicSet(&captureDevice->paused, 0);
-                private->resume = SDL_FALSE;
-                SDL_UnlockMutex(captureDevice->mixer_lock);
-            }
-
-            if (private->stream) {
-                aaudio_result_t res = ctx.AAudioStream_requestStart(private->stream);
-                if (res != AAUDIO_OK) {
-                    LOGI("SDL Failed AAudioStream_requestStart %d", res);
-                    SDL_SetError("%s : %s", __func__, ctx.AAudio_convertResultToText(res));
-                }
-            }
-        }
-    }
-}
-
-/*
- We can sometimes get into a state where AAudioStream_write() will just block forever until we pause and unpause.
- None of the standard state queries indicate any problem in my testing. And the error callback doesn't actually get called.
- But, AAudioStream_getTimestamp() does return AAUDIO_ERROR_INVALID_STATE
-*/
-SDL_bool aaudio_DetectBrokenPlayState(void)
-{
-    int i;
-
-    /* AAUDIO driver is not used */
-    if (ctx.handle == NULL) {
-        return SDL_FALSE;
-    }
-
-    for (i = 0; i < get_max_num_audio_dev(); i++) {
-        SDL_AudioDevice *_this = get_audio_dev(i);
-        SDL_AudioDevice *audioDevice = NULL;
-        SDL_AudioDevice *captureDevice = NULL;
-
-        if (_this == NULL) {
-            continue;
-        }
-
-        if (_this->iscapture) {
-            captureDevice = _this;
-        } else {
-            audioDevice = _this;
-        }
-
-        if (audioDevice != NULL && audioDevice->hidden != NULL) {
-            struct SDL_PrivateAudioData *private = audioDevice->hidden;
-            int64_t framePosition, timeNanoseconds;
-
-            aaudio_result_t res = ctx.AAudioStream_getTimestamp(private->stream, CLOCK_MONOTONIC, &framePosition, &timeNanoseconds);
-            if (res == AAUDIO_ERROR_INVALID_STATE) {
-                aaudio_stream_state_t currentState = ctx.AAudioStream_getState(private->stream);
-                /* AAudioStream_getTimestamp() will also return AAUDIO_ERROR_INVALID_STATE while the stream is still initially starting. But we only care if it silently went invalid while playing. */
-                if (currentState == AAUDIO_STREAM_STATE_STARTED) {
-                    LOGI("SDL aaudio_DetectBrokenPlayState: detected invalid audio device state: AAudioStream_getTimestamp result=%d, framePosition=%lld, timeNanoseconds=%lld, getState=%d", (int)res, (long long)framePosition, (long long)timeNanoseconds, (int)currentState);
-                    return SDL_TRUE;
-                }
-            }
-
-        }
-
-        (void) captureDevice;
-    }
-
-    return SDL_FALSE;
-}
-
-#endif /* SDL_AUDIO_DRIVER_AAUDIO */
+#endif // SDL_AUDIO_DRIVER_AAUDIO

src/audio/aaudio/SDL_aaudio.h

@@ -25,15 +25,15 @@
 
 #ifdef SDL_AUDIO_DRIVER_AAUDIO
 
-void aaudio_ResumeDevices(void);
-void aaudio_PauseDevices(void);
-SDL_bool aaudio_DetectBrokenPlayState(void);
+void AAUDIO_ResumeDevices(void);
+void AAUDIO_PauseDevices(void);
+SDL_bool AAUDIO_DetectBrokenPlayState(void);
 
 #else
 
-static void aaudio_ResumeDevices(void) {}
-static void aaudio_PauseDevices(void) {}
-static SDL_bool aaudio_DetectBrokenPlayState(void) { return SDL_FALSE; }
+#define AAUDIO_ResumeDevices()
+#define AAUDIO_PauseDevices()
+#define AAUDIO_DetectBrokenPlayState() (SDL_FALSE)
 
 #endif
 

src/audio/aaudio/SDL_aaudiofuncs.h

@@ -32,15 +32,15 @@ SDL_PROC(void, AAudioStreamBuilder_setFormat, (AAudioStreamBuilder * builder, aa
 SDL_PROC_UNUSED(void, AAudioStreamBuilder_setSharingMode, (AAudioStreamBuilder * builder, aaudio_sharing_mode_t sharingMode))
 SDL_PROC(void, AAudioStreamBuilder_setDirection, (AAudioStreamBuilder * builder, aaudio_direction_t direction))
 SDL_PROC_UNUSED(void, AAudioStreamBuilder_setBufferCapacityInFrames, (AAudioStreamBuilder * builder, int32_t numFrames))
-SDL_PROC_UNUSED(void, AAudioStreamBuilder_setPerformanceMode, (AAudioStreamBuilder * builder, aaudio_performance_mode_t mode))
+SDL_PROC(void, AAudioStreamBuilder_setPerformanceMode, (AAudioStreamBuilder * builder, aaudio_performance_mode_t mode))
 SDL_PROC_UNUSED(void, AAudioStreamBuilder_setUsage, (AAudioStreamBuilder * builder, aaudio_usage_t usage))                                         /* API 28 */
 SDL_PROC_UNUSED(void, AAudioStreamBuilder_setContentType, (AAudioStreamBuilder * builder, aaudio_content_type_t contentType))                      /* API 28 */
 SDL_PROC_UNUSED(void, AAudioStreamBuilder_setInputPreset, (AAudioStreamBuilder * builder, aaudio_input_preset_t inputPreset))                      /* API 28 */
 SDL_PROC_UNUSED(void, AAudioStreamBuilder_setAllowedCapturePolicy, (AAudioStreamBuilder * builder, aaudio_allowed_capture_policy_t capturePolicy)) /* API 29 */
 SDL_PROC_UNUSED(void, AAudioStreamBuilder_setSessionId, (AAudioStreamBuilder * builder, aaudio_session_id_t sessionId))                            /* API 28 */
 SDL_PROC_UNUSED(void, AAudioStreamBuilder_setPrivacySensitive, (AAudioStreamBuilder * builder, bool privacySensitive))                             /* API 30 */
-SDL_PROC_UNUSED(void, AAudioStreamBuilder_setDataCallback, (AAudioStreamBuilder * builder, AAudioStream_dataCallback callback, void *userData))
-SDL_PROC_UNUSED(void, AAudioStreamBuilder_setFramesPerDataCallback, (AAudioStreamBuilder * builder, int32_t numFrames))
+SDL_PROC(void, AAudioStreamBuilder_setDataCallback, (AAudioStreamBuilder * builder, AAudioStream_dataCallback callback, void *userData))
+SDL_PROC(void, AAudioStreamBuilder_setFramesPerDataCallback, (AAudioStreamBuilder * builder, int32_t numFrames))
 SDL_PROC(void, AAudioStreamBuilder_setErrorCallback, (AAudioStreamBuilder * builder, AAudioStream_errorCallback callback, void *userData))
 SDL_PROC(aaudio_result_t, AAudioStreamBuilder_openStream, (AAudioStreamBuilder * builder, AAudioStream **stream))
 SDL_PROC(aaudio_result_t, AAudioStreamBuilder_delete, (AAudioStreamBuilder * builder))
@@ -52,14 +52,14 @@ SDL_PROC_UNUSED(aaudio_result_t, AAudioStream_requestFlush, (AAudioStream * stre
 SDL_PROC(aaudio_result_t, AAudioStream_requestStop, (AAudioStream * stream))
 SDL_PROC(aaudio_stream_state_t, AAudioStream_getState, (AAudioStream * stream))
 SDL_PROC_UNUSED(aaudio_result_t, AAudioStream_waitForStateChange, (AAudioStream * stream, aaudio_stream_state_t inputState, aaudio_stream_state_t *nextState, int64_t timeoutNanoseconds))
-SDL_PROC(aaudio_result_t, AAudioStream_read, (AAudioStream * stream, void *buffer, int32_t numFrames, int64_t timeoutNanoseconds))
-SDL_PROC(aaudio_result_t, AAudioStream_write, (AAudioStream * stream, const void *buffer, int32_t numFrames, int64_t timeoutNanoseconds))
+SDL_PROC_UNUSED(aaudio_result_t, AAudioStream_read, (AAudioStream * stream, void *buffer, int32_t numFrames, int64_t timeoutNanoseconds))
+SDL_PROC_UNUSED(aaudio_result_t, AAudioStream_write, (AAudioStream * stream, const void *buffer, int32_t numFrames, int64_t timeoutNanoseconds))
 SDL_PROC_UNUSED(aaudio_result_t, AAudioStream_setBufferSizeInFrames, (AAudioStream * stream, int32_t numFrames))
 SDL_PROC_UNUSED(int32_t, AAudioStream_getBufferSizeInFrames, (AAudioStream * stream))
 SDL_PROC_UNUSED(int32_t, AAudioStream_getFramesPerBurst, (AAudioStream * stream))
-SDL_PROC_UNUSED(int32_t, AAudioStream_getBufferCapacityInFrames, (AAudioStream * stream))
-SDL_PROC_UNUSED(int32_t, AAudioStream_getFramesPerDataCallback, (AAudioStream * stream))
-SDL_PROC(int32_t, AAudioStream_getXRunCount, (AAudioStream * stream))
+SDL_PROC(int32_t, AAudioStream_getBufferCapacityInFrames, (AAudioStream * stream))
+SDL_PROC(int32_t, AAudioStream_getFramesPerDataCallback, (AAudioStream * stream))
+SDL_PROC_UNUSED(int32_t, AAudioStream_getXRunCount, (AAudioStream * stream))
 SDL_PROC(int32_t, AAudioStream_getSampleRate, (AAudioStream * stream))
 SDL_PROC(int32_t, AAudioStream_getChannelCount, (AAudioStream * stream))
 SDL_PROC_UNUSED(int32_t, AAudioStream_getSamplesPerFrame, (AAudioStream * stream))
@@ -77,3 +77,6 @@ SDL_PROC_UNUSED(aaudio_content_type_t, AAudioStream_getContentType, (AAudioStrea
 SDL_PROC_UNUSED(aaudio_input_preset_t, AAudioStream_getInputPreset, (AAudioStream * stream))                    /* API 28 */
 SDL_PROC_UNUSED(aaudio_allowed_capture_policy_t, AAudioStream_getAllowedCapturePolicy, (AAudioStream * stream)) /* API 29 */
 SDL_PROC_UNUSED(bool, AAudioStream_isPrivacySensitive, (AAudioStream * stream))                                 /* API 30 */
+
+#undef SDL_PROC
+#undef SDL_PROC_UNUSED

src/audio/alsa/SDL_alsa_audio.c

@@ -20,6 +20,8 @@
 */
 #include "SDL_internal.h"
 
+// !!! FIXME: Clean out the fprintf and printf calls, replace with SDL_Log
+
 #ifdef SDL_AUDIO_DRIVER_ALSA
 
 #ifndef SDL_ALSA_NON_BLOCKING
@@ -45,6 +47,7 @@
 
 static int (*ALSA_snd_pcm_open)(snd_pcm_t **, const char *, snd_pcm_stream_t, int);
 static int (*ALSA_snd_pcm_close)(snd_pcm_t *pcm);
+static int (*ALSA_snd_pcm_start)(snd_pcm_t *pcm);
 static snd_pcm_sframes_t (*ALSA_snd_pcm_writei)(snd_pcm_t *, const void *, snd_pcm_uframes_t);
 static snd_pcm_sframes_t (*ALSA_snd_pcm_readi)(snd_pcm_t *, void *, snd_pcm_uframes_t);
 static int (*ALSA_snd_pcm_recover)(snd_pcm_t *, int, int);
@@ -115,6 +118,7 @@ static int load_alsa_syms(void)
 {
     SDL_ALSA_SYM(snd_pcm_open);
     SDL_ALSA_SYM(snd_pcm_close);
+    SDL_ALSA_SYM(snd_pcm_start);
     SDL_ALSA_SYM(snd_pcm_writei);
     SDL_ALSA_SYM(snd_pcm_readi);
     SDL_ALSA_SYM(snd_pcm_recover);
@@ -203,48 +207,21 @@ static int LoadALSALibrary(void)
 
 static const char *get_audio_device(void *handle, const int channels)
 {
-    const char *device;
-
-    if (handle != NULL) {
-        return (const char *)handle;
-    }
-
-    /* !!! FIXME: we also check "SDL_AUDIO_DEVICE_NAME" at the higher level. */
-    device = SDL_getenv("AUDIODEV"); /* Is there a standard variable name? */
-    if (device != NULL) {
-        return device;
-    }
-
-    if (channels == 6) {
-        return "plug:surround51";
-    } else if (channels == 4) {
-        return "plug:surround40";
-    }
-
-    return "default";
-}
-
-/* This function waits until it is possible to write a full sound buffer */
-static void ALSA_WaitDevice(SDL_AudioDevice *_this)
-{
-#if SDL_ALSA_NON_BLOCKING
-    const snd_pcm_sframes_t needed = (snd_pcm_sframes_t)_this->spec.samples;
-    while (SDL_AtomicGet(&_this->enabled)) {
-        const snd_pcm_sframes_t rc = ALSA_snd_pcm_avail(_this->hidden->pcm_handle);
-        if ((rc < 0) && (rc != -EAGAIN)) {
-            /* Hmm, not much we can do - abort */
-            fprintf(stderr, "ALSA snd_pcm_avail failed (unrecoverable): %s\n",
-                    ALSA_snd_strerror(rc));
-            SDL_OpenedAudioDeviceDisconnected(_this);
-            return;
-        } else if (rc < needed) {
-            const Uint32 delay = ((needed - (SDL_max(rc, 0))) * 1000) / _this->spec.freq;
-            SDL_Delay(SDL_max(delay, 10));
-        } else {
-            break; /* ready to go! */
+    SDL_assert(handle != NULL);  // SDL2 used NULL to mean "default" but that's not true in SDL3.
+
+    if (SDL_strcmp((const char *) handle, "default") == 0) {
+        const char *device = SDL_getenv("AUDIODEV"); /* Is there a standard variable name? */
+        if (device != NULL) {
+            return device;
+        } else if (channels == 6) {
+            return "plug:surround51";
+        } else if (channels == 4) {
+            return "plug:surround40";
         }
+        return "default";
     }
-#endif
+
+    return (const char *)handle;
 }
 
 /* !!! FIXME: is there a channel swizzler in alsalib instead? */
@@ -311,15 +288,15 @@ CHANNEL_SWIZZLE(SWIZ8)
 #undef SWIZ8
 
 /*
- * Called right before feeding _this->hidden->mixbuf to the hardware. Swizzle
+ * Called right before feeding device->hidden->mixbuf to the hardware. Swizzle
  *  channels from Windows/Mac order to the format alsalib will want.
  */
-static void swizzle_alsa_channels(SDL_AudioDevice *_this, void *buffer, Uint32 bufferlen)
+static void swizzle_alsa_channels(SDL_AudioDevice *device, void *buffer, Uint32 bufferlen)
 {
-    switch (_this->spec.channels) {
+    switch (device->spec.channels) {
 #define CHANSWIZ(chans)                                                \
     case chans:                                                        \
-        switch ((_this->spec.format & (0xFF))) {                        \
+        switch ((device->spec.format & (0xFF))) {                        \
         case 8:                                                        \
             swizzle_alsa_channels_##chans##_Uint8(buffer, bufferlen);  \
             break;                                                     \
@@ -348,22 +325,44 @@ static void swizzle_alsa_channels(SDL_AudioDevice *_this, void *buffer, Uint32 b
 
 #ifdef SND_CHMAP_API_VERSION
 /* Some devices have the right channel map, no swizzling necessary */
-static void no_swizzle(SDL_AudioDevice *_this, void *buffer, Uint32 bufferlen)
+static void no_swizzle(SDL_AudioDevice *device, void *buffer, Uint32 bufferlen)
 {
 }
 #endif /* SND_CHMAP_API_VERSION */
 
-static void ALSA_PlayDevice(SDL_AudioDevice *_this)
+/* This function waits until it is possible to write a full sound buffer */
+static void ALSA_WaitDevice(SDL_AudioDevice *device)
 {
-    const Uint8 *sample_buf = (const Uint8 *)_this->hidden->mixbuf;
-    const int frame_size = ((SDL_AUDIO_BITSIZE(_this->spec.format)) / 8) *
-                           _this->spec.channels;
-    snd_pcm_uframes_t frames_left = ((snd_pcm_uframes_t)_this->spec.samples);
+    const snd_pcm_sframes_t needed = (snd_pcm_sframes_t)device->sample_frames;
+    while (!SDL_AtomicGet(&device->shutdown)) {
+        const snd_pcm_sframes_t rc = ALSA_snd_pcm_avail(device->hidden->pcm_handle);
+        if ((rc < 0) && (rc != -EAGAIN)) {
+            /* Hmm, not much we can do - abort */
+            fprintf(stderr, "ALSA snd_pcm_avail failed (unrecoverable): %s\n",
+                    ALSA_snd_strerror(rc));
+            SDL_AudioDeviceDisconnected(device);
+            return;
+        } else if (rc < needed) {
+            const Uint32 delay = ((needed - (SDL_max(rc, 0))) * 1000) / device->spec.freq;
+            SDL_Delay(SDL_max(delay, 10));
+        } else {
+            break; /* ready to go! */
+        }
+    }
+}
+
+static void ALSA_PlayDevice(SDL_AudioDevice *device, const Uint8 *buffer, int buflen)
+{
+    SDL_assert(buffer == device->hidden->mixbuf);
+    Uint8 *sample_buf = device->hidden->mixbuf;
+    const int frame_size = ((SDL_AUDIO_BITSIZE(device->spec.format)) / 8) *
+                           device->spec.channels;
+    snd_pcm_uframes_t frames_left = (snd_pcm_uframes_t) (buflen / frame_size);
 
-    _this->hidden->swizzle_func(_this, _this->hidden->mixbuf, frames_left);
+    device->hidden->swizzle_func(device, sample_buf, frames_left);
 
-    while (frames_left > 0 && SDL_AtomicGet(&_this->enabled)) {
-        int status = ALSA_snd_pcm_writei(_this->hidden->pcm_handle,
+    while ((frames_left > 0) && !SDL_AtomicGet(&device->shutdown)) {
+        int status = ALSA_snd_pcm_writei(device->hidden->pcm_handle,
                                          sample_buf, frames_left);
 
         if (status < 0) {
@@ -373,21 +372,20 @@ static void ALSA_PlayDevice(SDL_AudioDevice *_this)
                 SDL_Delay(1);
                 continue;
             }
-            status = ALSA_snd_pcm_recover(_this->hidden->pcm_handle, status, 0);
+            status = ALSA_snd_pcm_recover(device->hidden->pcm_handle, status, 0);
             if (status < 0) {
                 /* Hmm, not much we can do - abort */
                 SDL_LogError(SDL_LOG_CATEGORY_AUDIO,
-                             "ALSA write failed (unrecoverable): %s\n",
+                             "ALSA write failed (unrecoverable): %s",
                              ALSA_snd_strerror(status));
-                SDL_OpenedAudioDeviceDisconnected(_this);
+                SDL_AudioDeviceDisconnected(device);
                 return;
             }
             continue;
         } else if (status == 0) {
             /* No frames were written (no available space in pcm device).
                Allow other threads to catch up. */
-            Uint32 delay = (frames_left / 2 * 1000) / _this->spec.freq;
-            SDL_Delay(delay);
+            SDL_Delay((frames_left / 2 * 1000) / device->spec.freq);
         }
 
         sample_buf += status * frame_size;
@@ -395,34 +393,30 @@ static void ALSA_PlayDevice(SDL_AudioDevice *_this)
     }
 }
 
-static Uint8 *ALSA_GetDeviceBuf(SDL_AudioDevice *_this)
+static Uint8 *ALSA_GetDeviceBuf(SDL_AudioDevice *device, int *buffer_size)
 {
-    return _this->hidden->mixbuf;
+    return device->hidden->mixbuf;
 }
 
-static int ALSA_CaptureFromDevice(SDL_AudioDevice *_this, void *buffer, int buflen)
+static int ALSA_CaptureFromDevice(SDL_AudioDevice *device, void *buffer, int buflen)
 {
     Uint8 *sample_buf = (Uint8 *)buffer;
-    const int frame_size = ((SDL_AUDIO_BITSIZE(_this->spec.format)) / 8) *
-                           _this->spec.channels;
+    const int frame_size = ((SDL_AUDIO_BITSIZE(device->spec.format)) / 8) *
+                           device->spec.channels;
     const int total_frames = buflen / frame_size;
     snd_pcm_uframes_t frames_left = total_frames;
-    snd_pcm_uframes_t wait_time = frame_size / 2;
 
     SDL_assert((buflen % frame_size) == 0);
 
-    while (frames_left > 0 && SDL_AtomicGet(&_this->enabled)) {
-        int status;
-
-        status = ALSA_snd_pcm_readi(_this->hidden->pcm_handle,
-                                    sample_buf, frames_left);
+    while ((frames_left > 0) && !SDL_AtomicGet(&device->shutdown)) {
+        int status = ALSA_snd_pcm_readi(device->hidden->pcm_handle,
+                                        sample_buf, frames_left);
 
         if (status == -EAGAIN) {
-            ALSA_snd_pcm_wait(_this->hidden->pcm_handle, wait_time);
-            status = 0;
+            break;  // Can this even happen? Go back to WaitCaptureDevice, where the device lock isn't held.
         } else if (status < 0) {
             /*printf("ALSA: capture error %d\n", status);*/
-            status = ALSA_snd_pcm_recover(_this->hidden->pcm_handle, status, 0);
+            status = ALSA_snd_pcm_recover(device->hidden->pcm_handle, status, 0);
             if (status < 0) {
                 /* Hmm, not much we can do - abort */
                 SDL_LogError(SDL_LOG_CATEGORY_AUDIO,
@@ -430,7 +424,7 @@ static int ALSA_CaptureFromDevice(SDL_AudioDevice *_this, void *buffer, int bufl
                              ALSA_snd_strerror(status));
                 return -1;
             }
-            continue;
+            break;  // Go back to WaitCaptureDevice, where the device lock isn't held.
         }
 
         /*printf("ALSA: captured %d bytes\n", status * frame_size);*/
@@ -438,32 +432,32 @@ static int ALSA_CaptureFromDevice(SDL_AudioDevice *_this, void *buffer, int bufl
         frames_left -= status;
     }
 
-    _this->hidden->swizzle_func(_this, buffer, total_frames - frames_left);
+    device->hidden->swizzle_func(device, buffer, total_frames - frames_left);
 
     return (total_frames - frames_left) * frame_size;
 }
 
-static void ALSA_FlushCapture(SDL_AudioDevice *_this)
+static void ALSA_FlushCapture(SDL_AudioDevice *device)
 {
-    ALSA_snd_pcm_reset(_this->hidden->pcm_handle);
+    ALSA_snd_pcm_reset(device->hidden->pcm_handle);
 }
 
-static void ALSA_CloseDevice(SDL_AudioDevice *_this)
+static void ALSA_CloseDevice(SDL_AudioDevice *device)
 {
-    if (_this->hidden->pcm_handle) {
-        /* Wait for the submitted audio to drain
-           ALSA_snd_pcm_drop() can hang, so don't use that.
-         */
-        Uint32 delay = ((_this->spec.samples * 1000) / _this->spec.freq) * 2;
-        SDL_Delay(delay);
-
-        ALSA_snd_pcm_close(_this->hidden->pcm_handle);
+    if (device->hidden) {
+        if (device->hidden->pcm_handle) {
+            /* Wait for the submitted audio to drain
+               ALSA_snd_pcm_drop() can hang, so don't use that.
+             */
+            SDL_Delay(((device->sample_frames * 1000) / device->spec.freq) * 2);
+            ALSA_snd_pcm_close(device->hidden->pcm_handle);
+        }
+        SDL_free(device->hidden->mixbuf);
+        SDL_free(device->hidden);
     }
-    SDL_free(_this->hidden->mixbuf);
-    SDL_free(_this->hidden);
 }
 
-static int ALSA_set_buffer_size(SDL_AudioDevice *_this, snd_pcm_hw_params_t *params)
+static int ALSA_set_buffer_size(SDL_AudioDevice *device, snd_pcm_hw_params_t *params)
 {
     int status;
     snd_pcm_hw_params_t *hwparams;
@@ -475,9 +469,9 @@ static int ALSA_set_buffer_size(SDL_AudioDevice *_this, snd_pcm_hw_params_t *par
     ALSA_snd_pcm_hw_params_copy(hwparams, params);
 
     /* Attempt to match the period size to the requested buffer size */
-    persize = _this->spec.samples;
+    persize = device->sample_frames;
     status = ALSA_snd_pcm_hw_params_set_period_size_near(
-        _this->hidden->pcm_handle, hwparams, &persize, NULL);
+        device->hidden->pcm_handle, hwparams, &persize, NULL);
     if (status < 0) {
         return -1;
     }
@@ -485,24 +479,24 @@ static int ALSA_set_buffer_size(SDL_AudioDevice *_this, snd_pcm_hw_params_t *par
     /* Need to at least double buffer */
     periods = 2;
     status = ALSA_snd_pcm_hw_params_set_periods_min(
-        _this->hidden->pcm_handle, hwparams, &periods, NULL);
+        device->hidden->pcm_handle, hwparams, &periods, NULL);
     if (status < 0) {
         return -1;
     }
 
     status = ALSA_snd_pcm_hw_params_set_periods_first(
-        _this->hidden->pcm_handle, hwparams, &periods, NULL);
+        device->hidden->pcm_handle, hwparams, &periods, NULL);
     if (status < 0) {
         return -1;
     }
 
     /* "set" the hardware with the desired parameters */
-    status = ALSA_snd_pcm_hw_params(_this->hidden->pcm_handle, hwparams);
+    status = ALSA_snd_pcm_hw_params(device->hidden->pcm_handle, hwparams);
     if (status < 0) {
         return -1;
     }
 
-    _this->spec.samples = persize;
+    device->sample_frames = persize;
 
     /* This is useful for debugging */
     if (SDL_getenv("SDL_AUDIO_ALSA_DEBUG")) {
@@ -518,34 +512,22 @@ static int ALSA_set_buffer_size(SDL_AudioDevice *_this, snd_pcm_hw_params_t *par
     return 0;
 }
 
-static int ALSA_OpenDevice(SDL_AudioDevice *_this, const char *devname)
+static int ALSA_OpenDevice(SDL_AudioDevice *device)
 {
+    const SDL_bool iscapture = device->iscapture;
     int status = 0;
-    SDL_bool iscapture = _this->iscapture;
-    snd_pcm_t *pcm_handle = NULL;
-    snd_pcm_hw_params_t *hwparams = NULL;
-    snd_pcm_sw_params_t *swparams = NULL;
-    snd_pcm_format_t format = 0;
-    SDL_AudioFormat test_format = 0;
-    const SDL_AudioFormat *closefmts;
-    unsigned int rate = 0;
-    unsigned int channels = 0;
-#ifdef SND_CHMAP_API_VERSION
-    snd_pcm_chmap_t *chmap;
-    char chmap_str[64];
-#endif
 
     /* Initialize all variables that we clean on shutdown */
-    _this->hidden = (struct SDL_PrivateAudioData *)SDL_malloc(sizeof(*_this->hidden));
-    if (_this->hidden == NULL) {
+    device->hidden = (struct SDL_PrivateAudioData *)SDL_calloc(1, sizeof(*device->hidden));
+    if (device->hidden == NULL) {
         return SDL_OutOfMemory();
     }
-    SDL_zerop(_this->hidden);
 
     /* Open the audio device */
     /* Name of device should depend on # channels in spec */
+    snd_pcm_t *pcm_handle = NULL;
     status = ALSA_snd_pcm_open(&pcm_handle,
-                               get_audio_device(_this->handle, _this->spec.channels),
+                               get_audio_device(device->handle, device->spec.channels),
                                iscapture ? SND_PCM_STREAM_CAPTURE : SND_PCM_STREAM_PLAYBACK,
                                SND_PCM_NONBLOCK);
 
@@ -553,9 +535,10 @@ static int ALSA_OpenDevice(SDL_AudioDevice *_this, const char *devname)
         return SDL_SetError("ALSA: Couldn't open audio device: %s", ALSA_snd_strerror(status));
     }
 
-    _this->hidden->pcm_handle = pcm_handle;
+    device->hidden->pcm_handle = pcm_handle;
 
     /* Figure out what the hardware is capable of */
+    snd_pcm_hw_params_t *hwparams = NULL;
     snd_pcm_hw_params_alloca(&hwparams);
     status = ALSA_snd_pcm_hw_params_any(pcm_handle, hwparams);
     if (status < 0) {
@@ -570,7 +553,9 @@ static int ALSA_OpenDevice(SDL_AudioDevice *_this, const char *devname)
     }
 
     /* Try for a closest match on audio format */
-    closefmts = SDL_ClosestAudioFormats(_this->spec.format);
+    snd_pcm_format_t format = 0;
+    const SDL_AudioFormat *closefmts = SDL_ClosestAudioFormats(device->spec.format);
+    SDL_AudioFormat test_format;
     while ((test_format = *(closefmts++)) != 0) {
         switch (test_format) {
         case SDL_AUDIO_U8:
@@ -605,21 +590,22 @@ static int ALSA_OpenDevice(SDL_AudioDevice *_this, const char *devname)
         }
     }
     if (!test_format) {
-        return SDL_SetError("%s: Unsupported audio format", "alsa");
+        return SDL_SetError("ALSA: Unsupported audio format");
     }
-    _this->spec.format = test_format;
+    device->spec.format = test_format;
 
     /* Validate number of channels and determine if swizzling is necessary
      * Assume original swizzling, until proven otherwise.
      */
-    _this->hidden->swizzle_func = swizzle_alsa_channels;
+    device->hidden->swizzle_func = swizzle_alsa_channels;
 #ifdef SND_CHMAP_API_VERSION
-    chmap = ALSA_snd_pcm_get_chmap(pcm_handle);
+    snd_pcm_chmap_t *chmap = ALSA_snd_pcm_get_chmap(pcm_handle);
     if (chmap) {
+        char chmap_str[64];
         if (ALSA_snd_pcm_chmap_print(chmap, sizeof(chmap_str), chmap_str) > 0) {
             if (SDL_strcmp("FL FR FC LFE RL RR", chmap_str) == 0 ||
                 SDL_strcmp("FL FR FC LFE SL SR", chmap_str) == 0) {
-                _this->hidden->swizzle_func = no_swizzle;
+                device->hidden->swizzle_func = no_swizzle;
             }
         }
         free(chmap); /* This should NOT be SDL_free() */
@@ -628,38 +614,39 @@ static int ALSA_OpenDevice(SDL_AudioDevice *_this, const char *devname)
 
     /* Set the number of channels */
     status = ALSA_snd_pcm_hw_params_set_channels(pcm_handle, hwparams,
-                                                 _this->spec.channels);
-    channels = _this->spec.channels;
+                                                 device->spec.channels);
+    unsigned int channels = device->spec.channels;
     if (status < 0) {
         status = ALSA_snd_pcm_hw_params_get_channels(hwparams, &channels);
         if (status < 0) {
             return SDL_SetError("ALSA: Couldn't set audio channels");
         }
-        _this->spec.channels = channels;
+        device->spec.channels = channels;
     }
 
     /* Set the audio rate */
-    rate = _this->spec.freq;
+    unsigned int rate = device->spec.freq;
     status = ALSA_snd_pcm_hw_params_set_rate_near(pcm_handle, hwparams,
                                                   &rate, NULL);
     if (status < 0) {
         return SDL_SetError("ALSA: Couldn't set audio frequency: %s", ALSA_snd_strerror(status));
     }
-    _this->spec.freq = rate;
+    device->spec.freq = rate;
 
     /* Set the buffer size, in samples */
-    status = ALSA_set_buffer_size(_this, hwparams);
+    status = ALSA_set_buffer_size(device, hwparams);
     if (status < 0) {
         return SDL_SetError("Couldn't set hardware audio parameters: %s", ALSA_snd_strerror(status));
     }
 
     /* Set the software parameters */
+    snd_pcm_sw_params_t *swparams = NULL;
     snd_pcm_sw_params_alloca(&swparams);
     status = ALSA_snd_pcm_sw_params_current(pcm_handle, swparams);
     if (status < 0) {
         return SDL_SetError("ALSA: Couldn't get software config: %s", ALSA_snd_strerror(status));
     }
-    status = ALSA_snd_pcm_sw_params_set_avail_min(pcm_handle, swparams, _this->spec.samples);
+    status = ALSA_snd_pcm_sw_params_set_avail_min(pcm_handle, swparams, device->sample_frames);
     if (status < 0) {
         return SDL_SetError("Couldn't set minimum available samples: %s", ALSA_snd_strerror(status));
     }
@@ -673,17 +660,16 @@ static int ALSA_OpenDevice(SDL_AudioDevice *_this, const char *devname)
         return SDL_SetError("Couldn't set software audio parameters: %s", ALSA_snd_strerror(status));
     }
 
-    /* Calculate the final parameters for this audio specification */
-    SDL_CalculateAudioSpec(&_this->spec);
+    // Calculate the final parameters for this audio specification
+    SDL_UpdatedAudioDeviceFormat(device);
 
-    /* Allocate mixing buffer */
+    // Allocate mixing buffer
     if (!iscapture) {
-        _this->hidden->mixlen = _this->spec.size;
-        _this->hidden->mixbuf = (Uint8 *)SDL_malloc(_this->hidden->mixlen);
-        if (_this->hidden->mixbuf == NULL) {
+        device->hidden->mixbuf = (Uint8 *)SDL_malloc(device->buffer_size);
+        if (device->hidden->mixbuf == NULL) {
             return SDL_OutOfMemory();
         }
-        SDL_memset(_this->hidden->mixbuf, _this->spec.silence, _this->hidden->mixlen);
+        SDL_memset(device->hidden->mixbuf, device->silence_value, device->buffer_size);
     }
 
 #if !SDL_ALSA_NON_BLOCKING
@@ -692,6 +678,8 @@ static int ALSA_OpenDevice(SDL_AudioDevice *_this, const char *devname)
     }
 #endif
 
+    ALSA_snd_pcm_start(pcm_handle);
+
     /* We're ready to rock and roll. :-) */
     return 0;
 }
@@ -703,7 +691,7 @@ typedef struct ALSA_Device
     struct ALSA_Device *next;
 } ALSA_Device;
 
-static void add_device(const int iscapture, const char *name, void *hint, ALSA_Device **pSeen)
+static void add_device(const SDL_bool iscapture, const char *name, void *hint, ALSA_Device **pSeen)
 {
     ALSA_Device *dev = SDL_malloc(sizeof(ALSA_Device));
     char *desc;
@@ -765,21 +753,17 @@ static void add_device(const int iscapture, const char *name, void *hint, ALSA_D
 
 static ALSA_Device *hotplug_devices = NULL;
 
-static void ALSA_HotplugIteration(void)
+static void ALSA_HotplugIteration(SDL_bool *has_default_output, SDL_bool *has_default_capture)
 {
     void **hints = NULL;
-    ALSA_Device *dev;
-    ALSA_Device *unseen;
-    ALSA_Device *seen;
-    ALSA_Device *next;
-    ALSA_Device *prev;
+    ALSA_Device *unseen = NULL;
+    ALSA_Device *seen = NULL;
 
     if (ALSA_snd_device_name_hint(-1, "pcm", &hints) == 0) {
-        int i, j;
         const char *match = NULL;
         int bestmatch = 0xFFFF;
+        int has_default = -1;
         size_t match_len = 0;
-        int defaultdev = -1;
         static const char *const prefixes[] = {
             "hw:", "sysdefault:", "default:", NULL
         };
@@ -791,92 +775,100 @@ static void ALSA_HotplugIteration(void)
            actual hardware. It could be prefixed with "hw:" or "default:"
            or "sysdefault:" and maybe others. Go through the list and see
            if we can find a preferred prefix for the system. */
-        for (i = 0; hints[i]; i++) {
+        for (int i = 0; hints[i]; i++) {
             char *name = ALSA_snd_device_name_get_hint(hints[i], "NAME");
             if (name == NULL) {
                 continue;
             }
 
-            /* full name, not a prefix */
-            if ((defaultdev == -1) && (SDL_strcmp(name, "default") == 0)) {
-                defaultdev = i;
-            }
-
-            for (j = 0; prefixes[j]; j++) {
-                const char *prefix = prefixes[j];
-                const size_t prefixlen = SDL_strlen(prefix);
-                if (SDL_strncmp(name, prefix, prefixlen) == 0) {
-                    if (j < bestmatch) {
-                        bestmatch = j;
-                        match = prefix;
-                        match_len = prefixlen;
+            if (SDL_strcmp(name, "default") == 0) {
+                if (has_default < 0) {
+                    has_default = i;
+                }
+            } else {
+                for (int j = 0; prefixes[j]; j++) {
+                    const char *prefix = prefixes[j];
+                    const size_t prefixlen = SDL_strlen(prefix);
+                    if (SDL_strncmp(name, prefix, prefixlen) == 0) {
+                        if (j < bestmatch) {
+                            bestmatch = j;
+                            match = prefix;
+                            match_len = prefixlen;
+                        }
                     }
                 }
-            }
 
-            free(name); /* This should NOT be SDL_free() */
+                free(name); /* This should NOT be SDL_free() */
+            }
         }
 
         /* look through the list of device names to find matches */
-        for (i = 0; hints[i]; i++) {
-            char *name;
-
-            /* if we didn't find a device name prefix we like at all... */
-            if ((match == NULL) && (defaultdev != i)) {
-                continue; /* ...skip anything that isn't the default device. */
-            }
+        if (match || (has_default >= 0)) {  // did we find a device name prefix we like at all...?
+            for (int i = 0; hints[i]; i++) {
+                char *name = ALSA_snd_device_name_get_hint(hints[i], "NAME");
+                if (name == NULL) {
+                    continue;
+                }
 
-            name = ALSA_snd_device_name_get_hint(hints[i], "NAME");
-            if (name == NULL) {
-                continue;
-            }
+                // only want physical hardware interfaces
+                const SDL_bool is_default = (has_default == i) ? SDL_TRUE : SDL_FALSE;
+                if (is_default || SDL_strncmp(name, match, match_len) == 0) {
+                    char *ioid = ALSA_snd_device_name_get_hint(hints[i], "IOID");
+                    const SDL_bool isoutput = (ioid == NULL) || (SDL_strcmp(ioid, "Output") == 0);
+                    const SDL_bool isinput = (ioid == NULL) || (SDL_strcmp(ioid, "Input") == 0);
+                    SDL_bool have_output = SDL_FALSE;
+                    SDL_bool have_input = SDL_FALSE;
 
-            /* only want physical hardware interfaces */
-            if (match == NULL || (SDL_strncmp(name, match, match_len) == 0)) {
-                char *ioid = ALSA_snd_device_name_get_hint(hints[i], "IOID");
-                const SDL_bool isoutput = (ioid == NULL) || (SDL_strcmp(ioid, "Output") == 0);
-                const SDL_bool isinput = (ioid == NULL) || (SDL_strcmp(ioid, "Input") == 0);
-                SDL_bool have_output = SDL_FALSE;
-                SDL_bool have_input = SDL_FALSE;
+                    free(ioid);
 
-                free(ioid); /* This should NOT be SDL_free() */
+                    if (!isoutput && !isinput) {
+                        free(name);
+                        continue;
+                    }
 
-                if (!isoutput && !isinput) {
-                    free(name); /* This should NOT be SDL_free() */
-                    continue;
-                }
+                    if (is_default) {
+                        if (has_default_output && isoutput) {
+                            *has_default_output = SDL_TRUE;
+                        } else if (has_default_capture && isinput) {
+                            *has_default_capture = SDL_TRUE;
+                        }
+                        free(name);
+                        continue;
+                    }
 
-                prev = NULL;
-                for (dev = unseen; dev; dev = next) {
-                    next = dev->next;
-                    if ((SDL_strcmp(dev->name, name) == 0) && (((isinput) && dev->iscapture) || ((isoutput) && !dev->iscapture))) {
-                        if (prev) {
-                            prev->next = next;
+                    ALSA_Device *prev = NULL;
+                    ALSA_Device *next;
+                    for (ALSA_Device *dev = unseen; dev; dev = next) {
+                        next = dev->next;
+                        if ((SDL_strcmp(dev->name, name) == 0) && (((isinput) && dev->iscapture) || ((isoutput) && !dev->iscapture))) {
+                            if (prev) {
+                                prev->next = next;
+                            } else {
+                                unseen = next;
+                            }
+                            dev->next = seen;
+                            seen = dev;
+                            if (isinput) {
+                                have_input = SDL_TRUE;
+                            }
+                            if (isoutput) {
+                                have_output = SDL_TRUE;
+                            }
                         } else {
-                            unseen = next;
+                            prev = dev;
                         }
-                        dev->next = seen;
-                        seen = dev;
-                        if (isinput) {
-                            have_input = SDL_TRUE;
-                        }
-                        if (isoutput) {
-                            have_output = SDL_TRUE;
-                        }
-                    } else {
-                        prev = dev;
                     }
-                }
 
-                if (isinput && !have_input) {
-                    add_device(SDL_TRUE, name, hints[i], &seen);
-                }
-                if (isoutput && !have_output) {
-                    add_device(SDL_FALSE, name, hints[i], &seen);
+                    if (isinput && !have_input) {
+                        add_device(SDL_TRUE, name, hints[i], &seen);
+                    }
+                    if (isoutput && !have_output) {
+                        add_device(SDL_FALSE, name, hints[i], &seen);
+                    }
                 }
-            }
 
-            free(name); /* This should NOT be SDL_free() */
+                free(name); /* This should NOT be SDL_free() */
+            }
         }
 
         ALSA_snd_device_name_free_hint(hints);
@@ -884,10 +876,11 @@ static void ALSA_HotplugIteration(void)
         hotplug_devices = seen; /* now we have a known-good list of attached devices. */
 
         /* report anything still in unseen as removed. */
-        for (dev = unseen; dev; dev = next) {
+        ALSA_Device *next = NULL;
+        for (ALSA_Device *dev = unseen; dev; dev = next) {
             /*printf("ALSA: removing usb %s device '%s'\n", dev->iscapture ? "capture" : "output", dev->name);*/
             next = dev->next;
-            SDL_RemoveAudioDevice(dev->iscapture, dev->name);
+            SDL_AudioDeviceDisconnected(SDL_FindPhysicalAudioDeviceByHandle(dev->name));
             SDL_free(dev->name);
             SDL_free(dev);
         }
@@ -909,16 +902,25 @@ static int SDLCALL ALSA_HotplugThread(void *arg)
             SDL_Delay(100);
         }
 
-        ALSA_HotplugIteration(); /* run the check. */
+        ALSA_HotplugIteration(NULL, NULL); /* run the check. */
     }
 
     return 0;
 }
 #endif
 
-static void ALSA_DetectDevices(void)
+static void ALSA_DetectDevices(SDL_AudioDevice **default_output, SDL_AudioDevice **default_capture)
 {
-    ALSA_HotplugIteration(); /* run once now before a thread continues to check. */
+    // ALSA doesn't have a concept of a changeable default device, afaik, so we expose a generic default
+    // device here. It's the best we can do at this level.
+    SDL_bool has_default_output = SDL_FALSE, has_default_capture = SDL_FALSE;
+    ALSA_HotplugIteration(&has_default_output, &has_default_capture); // run once now before a thread continues to check. */
+    if (has_default_output) {
+        *default_output = SDL_AddAudioDevice(/*iscapture=*/SDL_FALSE, "ALSA default output device", NULL, SDL_strdup("default"));
+    }
+    if (has_default_capture) {
+        *default_capture = SDL_AddAudioDevice(/*iscapture=*/SDL_TRUE, "ALSA default capture device", NULL, SDL_strdup("default"));
+    }
 
 #if SDL_ALSA_HOTPLUG_THREAD
     SDL_AtomicSet(&ALSA_hotplug_shutdown, 0);
@@ -966,11 +968,11 @@ static SDL_bool ALSA_Init(SDL_AudioDriverImpl *impl)
     impl->PlayDevice = ALSA_PlayDevice;
     impl->CloseDevice = ALSA_CloseDevice;
     impl->Deinitialize = ALSA_Deinitialize;
+    impl->WaitCaptureDevice = ALSA_WaitDevice;
     impl->CaptureFromDevice = ALSA_CaptureFromDevice;
     impl->FlushCapture = ALSA_FlushCapture;
 
     impl->HasCaptureSupport = SDL_TRUE;
-    impl->SupportsNonPow2Samples = SDL_TRUE;
 
     return SDL_TRUE; /* this audio target is available. */
 }

src/audio/alsa/SDL_alsa_audio.h

@@ -34,7 +34,6 @@ struct SDL_PrivateAudioData
 
     /* Raw mixing buffer */
     Uint8 *mixbuf;
-    int mixlen;
 
     /* swizzle function */
     void (*swizzle_func)(SDL_AudioDevice *_this, void *buffer, Uint32 bufferlen);

src/audio/android/SDL_androidaudio.c

@@ -22,7 +22,7 @@
 
 #ifdef SDL_AUDIO_DRIVER_ANDROID
 
-/* Output audio to Android */
+// Output audio to Android (legacy interface)
 
 #include "../SDL_sysaudio.h"
 #include "../SDL_audio_c.h"
@@ -34,185 +34,158 @@
 
 struct SDL_PrivateAudioData
 {
-    /* Resume device if it was paused automatically */
-    int resume;
+    int resume;  // Resume device if it was paused automatically
 };
 
 static SDL_AudioDevice *audioDevice = NULL;
 static SDL_AudioDevice *captureDevice = NULL;
 
-
-static int ANDROIDAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
+static int ANDROIDAUDIO_OpenDevice(SDL_AudioDevice *device)
 {
-    SDL_AudioFormat test_format;
-    const SDL_AudioFormat *closefmts;
-    SDL_bool iscapture = _this->iscapture;
+    device->hidden = (struct SDL_PrivateAudioData *)SDL_calloc(1, sizeof(*device->hidden));
+    if (device->hidden == NULL) {
+        return SDL_OutOfMemory();
+    }
+
+    const SDL_bool iscapture = device->iscapture;
 
     if (iscapture) {
         if (captureDevice) {
             return SDL_SetError("An audio capture device is already opened");
         }
-    }
-
-    if (!iscapture) {
+        captureDevice = device;
+    } else {
         if (audioDevice) {
             return SDL_SetError("An audio playback device is already opened");
         }
+        audioDevice = device;
     }
 
-    if (iscapture) {
-        captureDevice = _this;
-    } else {
-        audioDevice = _this;
-    }
-
-    _this->hidden = (struct SDL_PrivateAudioData *)SDL_calloc(1, sizeof(*_this->hidden));
-    if (_this->hidden == NULL) {
-        return SDL_OutOfMemory();
-    }
-
-    closefmts = SDL_ClosestAudioFormats(_this->spec.format);
+    SDL_AudioFormat test_format;
+    const SDL_AudioFormat *closefmts = SDL_ClosestAudioFormats(device->spec.format);
     while ((test_format = *(closefmts++)) != 0) {
         if ((test_format == SDL_AUDIO_U8) ||
             (test_format == SDL_AUDIO_S16) ||
             (test_format == SDL_AUDIO_F32)) {
-            _this->spec.format = test_format;
+            device->spec.format = test_format;
             break;
         }
     }
 
     if (!test_format) {
-        /* Didn't find a compatible format :( */
-        return SDL_SetError("%s: Unsupported audio format", "android");
+        return SDL_SetError("android: Unsupported audio format");
     }
 
-    {
-        int audio_device_id = 0;
-        if (devname != NULL) {
-            audio_device_id = SDL_atoi(devname);
-        }
-        if (Android_JNI_OpenAudioDevice(iscapture, audio_device_id, &_this->spec) < 0) {
-            return -1;
-        }
+    if (Android_JNI_OpenAudioDevice(device) < 0) {
+        return -1;
     }
 
-    SDL_CalculateAudioSpec(&_this->spec);
+    SDL_UpdatedAudioDeviceFormat(device);
 
     return 0;
 }
 
-static void ANDROIDAUDIO_PlayDevice(SDL_AudioDevice *_this)
+// !!! FIXME: this needs a WaitDevice implementation.
+
+static void ANDROIDAUDIO_PlayDevice(SDL_AudioDevice *device, const Uint8 *buffer, int buflen)
 {
     Android_JNI_WriteAudioBuffer();
 }
 
-static Uint8 *ANDROIDAUDIO_GetDeviceBuf(SDL_AudioDevice *_this)
+static Uint8 *ANDROIDAUDIO_GetDeviceBuf(SDL_AudioDevice *device, int *buffer_size)
 {
     return Android_JNI_GetAudioBuffer();
 }
 
-static int ANDROIDAUDIO_CaptureFromDevice(SDL_AudioDevice *_this, void *buffer, int buflen)
+static int ANDROIDAUDIO_CaptureFromDevice(SDL_AudioDevice *device, void *buffer, int buflen)
 {
     return Android_JNI_CaptureAudioBuffer(buffer, buflen);
 }
 
-static void ANDROIDAUDIO_FlushCapture(SDL_AudioDevice *_this)
+static void ANDROIDAUDIO_FlushCapture(SDL_AudioDevice *device)
 {
     Android_JNI_FlushCapturedAudio();
 }
 
-static void ANDROIDAUDIO_CloseDevice(SDL_AudioDevice *_this)
+static void ANDROIDAUDIO_CloseDevice(SDL_AudioDevice *device)
 {
     /* At this point SDL_CloseAudioDevice via close_audio_device took care of terminating the audio thread
        so it's safe to terminate the Java side buffer and AudioTrack
      */
-    Android_JNI_CloseAudioDevice(_this->iscapture);
-    if (_this->iscapture) {
-        SDL_assert(captureDevice == _this);
-        captureDevice = NULL;
-    } else {
-        SDL_assert(audioDevice == _this);
-        audioDevice = NULL;
+    if (device->hidden) {
+        Android_JNI_CloseAudioDevice(device->iscapture);
+        if (device->iscapture) {
+            SDL_assert(captureDevice == device);
+            captureDevice = NULL;
+        } else {
+            SDL_assert(audioDevice == device);
+            audioDevice = NULL;
+        }
+        SDL_free(device->hidden);
+        device->hidden = NULL;
     }
-    SDL_free(_this->hidden);
-}
-
-static SDL_bool ANDROIDAUDIO_Init(SDL_AudioDriverImpl *impl)
-{
-    /* Set the function pointers */
-    impl->DetectDevices = Android_DetectDevices;
-    impl->OpenDevice = ANDROIDAUDIO_OpenDevice;
-    impl->PlayDevice = ANDROIDAUDIO_PlayDevice;
-    impl->GetDeviceBuf = ANDROIDAUDIO_GetDeviceBuf;
-    impl->CloseDevice = ANDROIDAUDIO_CloseDevice;
-    impl->CaptureFromDevice = ANDROIDAUDIO_CaptureFromDevice;
-    impl->FlushCapture = ANDROIDAUDIO_FlushCapture;
-    impl->AllowsArbitraryDeviceNames = SDL_TRUE;
-
-    /* and the capabilities */
-    impl->HasCaptureSupport = SDL_TRUE;
-    impl->OnlyHasDefaultOutputDevice = SDL_FALSE;
-    impl->OnlyHasDefaultCaptureDevice = SDL_FALSE;
-
-    return SDL_TRUE; /* this audio target is available. */
 }
 
-AudioBootStrap ANDROIDAUDIO_bootstrap = {
-    "android", "SDL Android audio driver", ANDROIDAUDIO_Init, SDL_FALSE
-};
-
-/* Pause (block) all non already paused audio devices by taking their mixer lock */
+// Pause (block) all non already paused audio devices by taking their mixer lock
 void ANDROIDAUDIO_PauseDevices(void)
 {
-    /* TODO: Handle multiple devices? */
-    struct SDL_PrivateAudioData *private;
+    // TODO: Handle multiple devices?
+    struct SDL_PrivateAudioData *hidden;
     if (audioDevice != NULL && audioDevice->hidden != NULL) {
-        private = (struct SDL_PrivateAudioData *)audioDevice->hidden;
-        if (SDL_AtomicGet(&audioDevice->paused)) {
-            /* The device is already paused, leave it alone */
-            private->resume = SDL_FALSE;
-        } else {
-            SDL_LockMutex(audioDevice->mixer_lock);
-            SDL_AtomicSet(&audioDevice->paused, 1);
-            private->resume = SDL_TRUE;
-        }
+        hidden = (struct SDL_PrivateAudioData *)audioDevice->hidden;
+        SDL_LockMutex(audioDevice->lock);
+        hidden->resume = SDL_TRUE;
     }
 
     if (captureDevice != NULL && captureDevice->hidden != NULL) {
-        private = (struct SDL_PrivateAudioData *)captureDevice->hidden;
-        if (SDL_AtomicGet(&captureDevice->paused)) {
-            /* The device is already paused, leave it alone */
-            private->resume = SDL_FALSE;
-        } else {
-            SDL_LockMutex(captureDevice->mixer_lock);
-            SDL_AtomicSet(&captureDevice->paused, 1);
-            private->resume = SDL_TRUE;
-        }
+        hidden = (struct SDL_PrivateAudioData *)captureDevice->hidden;
+        SDL_LockMutex(captureDevice->lock);
+        hidden->resume = SDL_TRUE;
     }
 }
 
-/* Resume (unblock) all non already paused audio devices by releasing their mixer lock */
+// Resume (unblock) all non already paused audio devices by releasing their mixer lock
 void ANDROIDAUDIO_ResumeDevices(void)
 {
-    /* TODO: Handle multiple devices? */
-    struct SDL_PrivateAudioData *private;
+    // TODO: Handle multiple devices?
+    struct SDL_PrivateAudioData *hidden;
     if (audioDevice != NULL && audioDevice->hidden != NULL) {
-        private = (struct SDL_PrivateAudioData *)audioDevice->hidden;
-        if (private->resume) {
-            SDL_AtomicSet(&audioDevice->paused, 0);
-            private->resume = SDL_FALSE;
-            SDL_UnlockMutex(audioDevice->mixer_lock);
+        hidden = (struct SDL_PrivateAudioData *)audioDevice->hidden;
+        if (hidden->resume) {
+            hidden->resume = SDL_FALSE;
+            SDL_UnlockMutex(audioDevice->lock);
         }
     }
 
     if (captureDevice != NULL && captureDevice->hidden != NULL) {
-        private = (struct SDL_PrivateAudioData *)captureDevice->hidden;
-        if (private->resume) {
-            SDL_AtomicSet(&captureDevice->paused, 0);
-            private->resume = SDL_FALSE;
-            SDL_UnlockMutex(captureDevice->mixer_lock);
+        hidden = (struct SDL_PrivateAudioData *)captureDevice->hidden;
+        if (hidden->resume) {
+            hidden->resume = SDL_FALSE;
+            SDL_UnlockMutex(captureDevice->lock);
         }
     }
 }
 
-#endif /* SDL_AUDIO_DRIVER_ANDROID */
+static SDL_bool ANDROIDAUDIO_Init(SDL_AudioDriverImpl *impl)
+{
+    // !!! FIXME: if on Android API < 24, DetectDevices and Deinitialize should be NULL and OnlyHasDefaultOutputDevice and OnlyHasDefaultCaptureDevice should be SDL_TRUE, since audio device enum and hotplug appears to require Android 7.0+.
+    impl->ThreadInit = Android_AudioThreadInit;
+    impl->DetectDevices = Android_StartAudioHotplug;
+    impl->Deinitialize = Android_StopAudioHotplug;
+    impl->OpenDevice = ANDROIDAUDIO_OpenDevice;
+    impl->PlayDevice = ANDROIDAUDIO_PlayDevice;
+    impl->GetDeviceBuf = ANDROIDAUDIO_GetDeviceBuf;
+    impl->CloseDevice = ANDROIDAUDIO_CloseDevice;
+    impl->CaptureFromDevice = ANDROIDAUDIO_CaptureFromDevice;
+    impl->FlushCapture = ANDROIDAUDIO_FlushCapture;
+
+    impl->HasCaptureSupport = SDL_TRUE;
+
+    return SDL_TRUE;
+}
+
+AudioBootStrap ANDROIDAUDIO_bootstrap = {
+    "android", "SDL Android audio driver", ANDROIDAUDIO_Init, SDL_FALSE
+};
+
+#endif // SDL_AUDIO_DRIVER_ANDROID

src/audio/coreaudio/SDL_coreaudio.h

@@ -53,15 +53,12 @@ struct SDL_PrivateAudioData
     AudioQueueRef audioQueue;
     int numAudioBuffers;
     AudioQueueBufferRef *audioBuffer;
-    void *buffer;
-    UInt32 bufferOffset;
-    UInt32 bufferSize;
+    AudioQueueBufferRef current_buffer;
     AudioStreamBasicDescription strdesc;
     SDL_Semaphore *ready_semaphore;
     char *thread_error;
 #ifdef MACOSX_COREAUDIO
     AudioDeviceID deviceID;
-    SDL_AtomicInt device_change_flag;
 #else
     SDL_bool interrupted;
     CFTypeRef interruption_listener;

src/audio/coreaudio/SDL_coreaudio.m

@@ -22,28 +22,24 @@
 
 #ifdef SDL_AUDIO_DRIVER_COREAUDIO
 
-/* !!! FIXME: clean out some of the macro salsa in here. */
-
 #include "../SDL_audio_c.h"
 #include "../SDL_sysaudio.h"
 #include "SDL_coreaudio.h"
 #include "../../thread/SDL_systhread.h"
 
-#define DEBUG_COREAUDIO 0
+#define DEBUG_COREAUDIO 1
 
 #if DEBUG_COREAUDIO
-#define CHECK_RESULT(msg)                                                 \
-    if (result != noErr) {                                                \
-        printf("COREAUDIO: Got error %d from '%s'!\n", (int)result, msg); \
-        SDL_SetError("CoreAudio error (%s): %d", msg, (int)result);       \
-        return 0;                                                         \
-    }
+    #define CHECK_RESULT(msg) \
+        if (result != noErr) { \
+            SDL_Log("COREAUDIO: Got error %d from '%s'!\n", (int)result, msg); \
+            return SDL_SetError("CoreAudio error (%s): %d", msg, (int)result); \
+        }
 #else
-#define CHECK_RESULT(msg)                                           \
-    if (result != noErr) {                                          \
-        SDL_SetError("CoreAudio error (%s): %d", msg, (int)result); \
-        return 0;                                                   \
-    }
+    #define CHECK_RESULT(msg) \
+        if (result != noErr) { \
+            return SDL_SetError("CoreAudio error (%s): %d", msg, (int)result); \
+        }
 #endif
 
 #ifdef MACOSX_COREAUDIO
@@ -53,78 +49,83 @@ static const AudioObjectPropertyAddress devlist_address = {
     kAudioObjectPropertyElementMain
 };
 
-typedef void (*addDevFn)(const char *name, SDL_AudioSpec *spec, const int iscapture, AudioDeviceID devId, void *data);
+static const AudioObjectPropertyAddress default_output_device_address = {
+    kAudioHardwarePropertyDefaultOutputDevice,
+    kAudioObjectPropertyScopeGlobal,
+    kAudioObjectPropertyElementMain
+};
 
-typedef struct AudioDeviceList
-{
-    AudioDeviceID devid;
-    SDL_bool alive;
-    struct AudioDeviceList *next;
-} AudioDeviceList;
+static const AudioObjectPropertyAddress default_input_device_address = {
+    kAudioHardwarePropertyDefaultInputDevice,
+    kAudioObjectPropertyScopeGlobal,
+    kAudioObjectPropertyElementMain
+};
+
+static const AudioObjectPropertyAddress alive_address = {
+    kAudioDevicePropertyDeviceIsAlive,
+    kAudioObjectPropertyScopeGlobal,
+    kAudioObjectPropertyElementMain
+};
 
-static AudioDeviceList *output_devs = NULL;
-static AudioDeviceList *capture_devs = NULL;
 
-static SDL_bool add_to_internal_dev_list(const int iscapture, AudioDeviceID devId)
+static OSStatus DeviceAliveNotification(AudioObjectID devid, UInt32 num_addr, const AudioObjectPropertyAddress *addrs, void *data)
 {
-    AudioDeviceList *item = (AudioDeviceList *)SDL_malloc(sizeof(AudioDeviceList));
-    if (item == NULL) {
-        return SDL_FALSE;
+    SDL_AudioDevice *device = (SDL_AudioDevice *)data;
+    SDL_assert(((AudioObjectID)(size_t)device->handle) == devid);
+
+    UInt32 alive = 1;
+    UInt32 size = sizeof(alive);
+    const OSStatus error = AudioObjectGetPropertyData(devid, addrs, 0, NULL, &size, &alive);
+
+    SDL_bool dead = SDL_FALSE;
+    if (error == kAudioHardwareBadDeviceError) {
+        dead = SDL_TRUE; /* device was unplugged. */
+    } else if ((error == kAudioHardwareNoError) && (!alive)) {
+        dead = SDL_TRUE; /* device died in some other way. */
     }
-    item->devid = devId;
-    item->alive = SDL_TRUE;
-    item->next = iscapture ? capture_devs : output_devs;
-    if (iscapture) {
-        capture_devs = item;
-    } else {
-        output_devs = item;
+
+    if (dead) {
+        #if DEBUG_COREAUDIO
+        SDL_Log("COREAUDIO: device '%s' is lost!", device->name);
+        #endif
+        SDL_AudioDeviceDisconnected(device);
     }
 
-    return SDL_TRUE;
+    return noErr;
 }
 
-static void addToDevList(const char *name, SDL_AudioSpec *spec, const int iscapture, AudioDeviceID devId, void *data)
+static void COREAUDIO_FreeDeviceHandle(SDL_AudioDevice *device)
 {
-    if (add_to_internal_dev_list(iscapture, devId)) {
-        SDL_AddAudioDevice(iscapture, name, spec, (void *)((size_t)devId));
-    }
+    const AudioDeviceID devid = (AudioDeviceID)(size_t)device->handle;
+    AudioObjectRemovePropertyListener(devid, &alive_address, DeviceAliveNotification, device);
 }
 
-static void build_device_list(int iscapture, addDevFn addfn, void *addfndata)
+// This only _adds_ new devices. Removal is handled by devices triggering kAudioDevicePropertyDeviceIsAlive property changes.
+static void RefreshPhysicalDevices(void)
 {
-    OSStatus result = noErr;
     UInt32 size = 0;
     AudioDeviceID *devs = NULL;
-    UInt32 i = 0;
-    UInt32 max = 0;
+    SDL_bool isstack;
 
-    result = AudioObjectGetPropertyDataSize(kAudioObjectSystemObject,
-                                            &devlist_address, 0, NULL, &size);
-    if (result != kAudioHardwareNoError) {
+    if (AudioObjectGetPropertyDataSize(kAudioObjectSystemObject, &devlist_address, 0, NULL, &size) != kAudioHardwareNoError) {
         return;
-    }
-
-    devs = (AudioDeviceID *)alloca(size);
-    if (devs == NULL) {
+    } else if ((devs = (AudioDeviceID *) SDL_small_alloc(Uint8, size, &isstack)) == NULL) {
+        return;
+    } else if (AudioObjectGetPropertyData(kAudioObjectSystemObject, &devlist_address, 0, NULL, &size, devs) != kAudioHardwareNoError) {
+        SDL_small_free(devs, isstack);
         return;
     }
 
-    result = AudioObjectGetPropertyData(kAudioObjectSystemObject,
-                                        &devlist_address, 0, NULL, &size, devs);
-    if (result != kAudioHardwareNoError) {
-        return;
+    const UInt32 total_devices = (UInt32) (size / sizeof(AudioDeviceID));
+    for (UInt32 i = 0; i < total_devices; i++) {
+        SDL_AudioDevice *device = SDL_FindPhysicalAudioDeviceByHandle((void *)((size_t)devs[i]));
+        if (device) {
+            devs[i] = 0;  // The system and SDL both agree it's already here, don't check it again.
+        }
     }
 
-    max = size / sizeof(AudioDeviceID);
-    for (i = 0; i < max; i++) {
-        CFStringRef cfstr = NULL;
-        char *ptr = NULL;
-        AudioDeviceID dev = devs[i];
-        AudioBufferList *buflist = NULL;
-        int usable = 0;
-        CFIndex len = 0;
-        double sampleRate = 0;
-        SDL_AudioSpec spec;
+    // any non-zero items remaining in `devs` are new devices to be added.
+    for (int iscapture = 0; iscapture < 2; iscapture++) {
         const AudioObjectPropertyAddress addr = {
             kAudioDevicePropertyStreamConfiguration,
             iscapture ? kAudioDevicePropertyScopeInput : kAudioDevicePropertyScopeOutput,
@@ -141,200 +142,192 @@ static void build_device_list(int iscapture, addDevFn addfn, void *addfndata)
             kAudioObjectPropertyElementMain
         };
 
-        result = AudioObjectGetPropertyDataSize(dev, &addr, 0, NULL, &size);
-        if (result != noErr) {
-            continue;
-        }
-
-        buflist = (AudioBufferList *)SDL_malloc(size);
-        if (buflist == NULL) {
-            continue;
-        }
+        for (UInt32 i = 0; i < total_devices; i++) {
+            const AudioDeviceID dev = devs[i];
+            if (!dev) {
+                continue;  // already added.
+            }
 
-        result = AudioObjectGetPropertyData(dev, &addr, 0, NULL,
-                                            &size, buflist);
+            AudioBufferList *buflist = NULL;
+            double sampleRate = 0;
 
-        SDL_zero(spec);
-        if (result == noErr) {
-            UInt32 j;
-            for (j = 0; j < buflist->mNumberBuffers; j++) {
-                spec.channels += buflist->mBuffers[j].mNumberChannels;
+            if (AudioObjectGetPropertyDataSize(dev, &addr, 0, NULL, &size) != noErr) {
+                continue;
+            } else if ((buflist = (AudioBufferList *)SDL_malloc(size)) == NULL) {
+                continue;
             }
-        }
 
-        SDL_free(buflist);
+            OSStatus result = AudioObjectGetPropertyData(dev, &addr, 0, NULL, &size, buflist);
 
-        if (spec.channels == 0) {
-            continue;
-        }
+            SDL_AudioSpec spec;
+            SDL_zero(spec);
+            if (result == noErr) {
+                for (Uint32 j = 0; j < buflist->mNumberBuffers; j++) {
+                    spec.channels += buflist->mBuffers[j].mNumberChannels;
+                }
+            }
 
-        size = sizeof(sampleRate);
-        result = AudioObjectGetPropertyData(dev, &freqaddr, 0, NULL, &size, &sampleRate);
-        if (result == noErr) {
-            spec.freq = (int)sampleRate;
-        }
+            SDL_free(buflist);
 
-        size = sizeof(CFStringRef);
-        result = AudioObjectGetPropertyData(dev, &nameaddr, 0, NULL, &size, &cfstr);
-        if (result != kAudioHardwareNoError) {
-            continue;
-        }
+            if (spec.channels == 0) {
+                continue;
+            }
+
+            size = sizeof(sampleRate);
+            if (AudioObjectGetPropertyData(dev, &freqaddr, 0, NULL, &size, &sampleRate) == noErr) {
+                spec.freq = (int)sampleRate;
+            }
 
-        len = CFStringGetMaximumSizeForEncoding(CFStringGetLength(cfstr),
-                                                kCFStringEncodingUTF8);
+            CFStringRef cfstr = NULL;
+            size = sizeof(CFStringRef);
+            if (AudioObjectGetPropertyData(dev, &nameaddr, 0, NULL, &size, &cfstr) != kAudioHardwareNoError) {
+                continue;
+            }
 
-        ptr = (char *)SDL_malloc(len + 1);
-        usable = ((ptr != NULL) &&
-                  (CFStringGetCString(cfstr, ptr, len + 1, kCFStringEncodingUTF8)));
+            CFIndex len = CFStringGetMaximumSizeForEncoding(CFStringGetLength(cfstr), kCFStringEncodingUTF8);
+            char *name = (char *)SDL_malloc(len + 1);
+            SDL_bool usable = ((name != NULL) && (CFStringGetCString(cfstr, name, len + 1, kCFStringEncodingUTF8))) ? SDL_TRUE : SDL_FALSE;
 
-        CFRelease(cfstr);
+            CFRelease(cfstr);
 
-        if (usable) {
-            len = SDL_strlen(ptr);
-            /* Some devices have whitespace at the end...trim it. */
-            while ((len > 0) && (ptr[len - 1] == ' ')) {
-                len--;
+            if (usable) {
+                // Some devices have whitespace at the end...trim it.
+                len = (CFIndex) SDL_strlen(name);
+                while ((len > 0) && (name[len - 1] == ' ')) {
+                    len--;
+                }
+                usable = (len > 0);
             }
-            usable = (len > 0);
-        }
 
-        if (usable) {
-            ptr[len] = '\0';
+            if (usable) {
+                name[len] = '\0';
 
-#if DEBUG_COREAUDIO
-            printf("COREAUDIO: Found %s device #%d: '%s' (devid %d)\n",
-                   ((iscapture) ? "capture" : "output"),
-                   (int)i, ptr, (int)dev);
-#endif
-            addfn(ptr, &spec, iscapture, dev, addfndata);
+                #if DEBUG_COREAUDIO
+                SDL_Log("COREAUDIO: Found %s device #%d: '%s' (devid %d)\n",
+                       ((iscapture) ? "capture" : "output"),
+                       (int)i, name, (int)dev);
+                #endif
+
+                devs[i] = 0;  // don't bother checking this one on the next iscapture iteration of the loop
+
+                SDL_AudioDevice *device = SDL_AddAudioDevice(iscapture ? SDL_TRUE : SDL_FALSE, name, &spec, (void *)((size_t)dev));
+                if (device) {
+                    AudioObjectAddPropertyListener(dev, &alive_address, DeviceAliveNotification, device);
+                }
+            }
+            SDL_free(name); // SDL_AddAudioDevice() would have copied the string.
         }
-        SDL_free(ptr); /* addfn() would have copied the string. */
     }
+
+    SDL_small_free(devs, isstack);
 }
 
-static void free_audio_device_list(AudioDeviceList **list)
+// this is called when the system's list of available audio devices changes.
+static OSStatus DeviceListChangedNotification(AudioObjectID systemObj, UInt32 num_addr, const AudioObjectPropertyAddress *addrs, void *data)
 {
-    AudioDeviceList *item = *list;
-    while (item) {
-        AudioDeviceList *next = item->next;
-        SDL_free(item);
-        item = next;
-    }
-    *list = NULL;
+    RefreshPhysicalDevices();
+    return noErr;
 }
 
-static void COREAUDIO_DetectDevices(void)
+static OSStatus DefaultAudioDeviceChangedNotification(AudioObjectID inObjectID, const AudioObjectPropertyAddress *addr)
 {
-    build_device_list(SDL_TRUE, addToDevList, NULL);
-    build_device_list(SDL_FALSE, addToDevList, NULL);
+    AudioDeviceID devid;
+    Uint32 size = sizeof(devid);
+    if (AudioObjectGetPropertyData(inObjectID, addr, 0, NULL, &size, &devid) == noErr) {
+        SDL_DefaultAudioDeviceChanged(SDL_FindPhysicalAudioDeviceByHandle((void *)((size_t)devid)));
+    }
+    return noErr;
 }
 
-static void build_device_change_list(const char *name, SDL_AudioSpec *spec, const int iscapture, AudioDeviceID devId, void *data)
+static OSStatus DefaultOutputDeviceChangedNotification(AudioObjectID inObjectID, UInt32 inNumberAddresses, const AudioObjectPropertyAddress *inAddresses, void *inUserData)
 {
-    AudioDeviceList **list = (AudioDeviceList **)data;
-    AudioDeviceList *item;
-    for (item = *list; item != NULL; item = item->next) {
-        if (item->devid == devId) {
-            item->alive = SDL_TRUE;
-            return;
-        }
-    }
+    #if DEBUG_COREAUDIO
+    SDL_Log("COREAUDIO: default output device changed!");
+    #endif
+    SDL_assert(inNumberAddresses == 1);
+    return DefaultAudioDeviceChangedNotification(inObjectID, inAddresses);
+}
 
-    add_to_internal_dev_list(iscapture, devId); /* new device, add it. */
-    SDL_AddAudioDevice(iscapture, name, spec, (void *)((size_t)devId));
+static OSStatus DefaultInputDeviceChangedNotification(AudioObjectID inObjectID, UInt32 inNumberAddresses, const AudioObjectPropertyAddress *inAddresses, void *inUserData)
+{
+    #if DEBUG_COREAUDIO
+    SDL_Log("COREAUDIO: default input device changed!");
+    #endif
+    SDL_assert(inNumberAddresses == 1);
+    return DefaultAudioDeviceChangedNotification(inObjectID, inAddresses);
 }
 
-static void reprocess_device_list(const int iscapture, AudioDeviceList **list)
+static void COREAUDIO_DetectDevices(SDL_AudioDevice **default_output, SDL_AudioDevice **default_capture)
 {
-    AudioDeviceList *item;
-    AudioDeviceList *prev = NULL;
-    for (item = *list; item != NULL; item = item->next) {
-        item->alive = SDL_FALSE;
-    }
+    RefreshPhysicalDevices();
 
-    build_device_list(iscapture, build_device_change_list, list);
+    AudioObjectAddPropertyListener(kAudioObjectSystemObject, &devlist_address, DeviceListChangedNotification, NULL);
 
-    /* free items in the list that aren't still alive. */
-    item = *list;
-    while (item != NULL) {
-        AudioDeviceList *next = item->next;
-        if (item->alive) {
-            prev = item;
-        } else {
-            SDL_RemoveAudioDevice(iscapture, (void *)((size_t)item->devid));
-            if (prev) {
-                prev->next = item->next;
-            } else {
-                *list = item->next;
-            }
-            SDL_free(item);
+    /* Get the Device ID */
+    UInt32 size;
+    AudioDeviceID devid;
+
+    size = sizeof(AudioDeviceID);
+    if (AudioObjectGetPropertyData(kAudioObjectSystemObject, &default_output_device_address, 0, NULL, &size, &devid) == noErr) {
+        SDL_AudioDevice *device = SDL_FindPhysicalAudioDeviceByHandle((void *)((size_t)devid));
+        if (device) {
+            *default_output = device;
         }
-        item = next;
     }
-}
+    AudioObjectAddPropertyListener(kAudioObjectSystemObject, &default_output_device_address, DefaultOutputDeviceChangedNotification, NULL);
 
-/* this is called when the system's list of available audio devices changes. */
-static OSStatus device_list_changed(AudioObjectID systemObj, UInt32 num_addr, const AudioObjectPropertyAddress *addrs, void *data)
-{
-    reprocess_device_list(SDL_TRUE, &capture_devs);
-    reprocess_device_list(SDL_FALSE, &output_devs);
-    return 0;
+    size = sizeof(AudioDeviceID);
+    if (AudioObjectGetPropertyData(kAudioObjectSystemObject, &default_input_device_address, 0, NULL, &size, &devid) == noErr) {
+        SDL_AudioDevice *device = SDL_FindPhysicalAudioDeviceByHandle((void *)((size_t)devid));
+        if (device) {
+            *default_capture = device;
+        }
+    }
+    AudioObjectAddPropertyListener(kAudioObjectSystemObject, &default_input_device_address, DefaultInputDeviceChangedNotification, NULL);
 }
-#endif
 
-static int open_playback_devices;
-static int open_capture_devices;
-static int num_open_devices;
-static SDL_AudioDevice **open_devices;
+#else  // iOS-specific section follows.
 
-#ifndef MACOSX_COREAUDIO
+static SDL_bool session_active = SDL_FALSE;
 
-static BOOL session_active = NO;
-
-static void pause_audio_devices(void)
+static SDL_bool PauseOneAudioDevice(SDL_AudioDevice *device, void *userdata)
 {
-    int i;
-
-    if (!open_devices) {
-        return;
-    }
-
-    for (i = 0; i < num_open_devices; ++i) {
-        SDL_AudioDevice *device = open_devices[i];
-        if (device->hidden->audioQueue && !device->hidden->interrupted) {
-            AudioQueuePause(device->hidden->audioQueue);
-        }
+    if (device->hidden && device->hidden->audioQueue && !device->hidden->interrupted) {
+        AudioQueuePause(device->hidden->audioQueue);
     }
+    return SDL_FALSE;  // keep enumerating devices until we've paused them all.
 }
 
-static void resume_audio_devices(void)
+static void PauseAudioDevices(void)
 {
-    int i;
+    (void) SDL_FindPhysicalAudioDeviceByCallback(PauseOneAudioDevice, NULL);
+}
 
-    if (!open_devices) {
-        return;
+static SDL_bool ResumeOneAudioDevice(SDL_AudioDevice *device, void *userdata)
+{
+    if (device->hidden && device->hidden->audioQueue && !device->hidden->interrupted) {
+        AudioQueueStart(device->hidden->audioQueue, NULL);
     }
+    return SDL_FALSE;  // keep enumerating devices until we've resumed them all.
+}
 
-    for (i = 0; i < num_open_devices; ++i) {
-        SDL_AudioDevice *device = open_devices[i];
-        if (device->hidden->audioQueue && !device->hidden->interrupted) {
-            AudioQueueStart(device->hidden->audioQueue, NULL);
-        }
-    }
+static void ResumeAudioDevices(void)
+{
+    (void) SDL_FindPhysicalAudioDeviceByCallback(ResumeOneAudioDevice, NULL);
 }
 
-static void interruption_begin(SDL_AudioDevice *_this)
+static void InterruptionBegin(SDL_AudioDevice *device)
 {
-    if (_this != NULL && _this->hidden->audioQueue != NULL) {
-        _this->hidden->interrupted = SDL_TRUE;
-        AudioQueuePause(_this->hidden->audioQueue);
+    if (device != NULL && device->hidden->audioQueue != NULL) {
+        device->hidden->interrupted = SDL_TRUE;
+        AudioQueuePause(device->hidden->audioQueue);
     }
 }
 
-static void interruption_end(SDL_AudioDevice *_this)
+static void InterruptionEnd(SDL_AudioDevice *device)
 {
-    if (_this != NULL && _this->hidden != NULL && _this->hidden->audioQueue != NULL && _this->hidden->interrupted && AudioQueueStart(_this->hidden->audioQueue, NULL) == AVAudioSessionErrorCodeNone) {
-        _this->hidden->interrupted = SDL_FALSE;
+    if (device != NULL && device->hidden != NULL && device->hidden->audioQueue != NULL && device->hidden->interrupted && AudioQueueStart(device->hidden->audioQueue, NULL) == AVAudioSessionErrorCodeNone) {
+        device->hidden->interrupted = SDL_FALSE;
     }
 }
 
@@ -351,9 +344,9 @@ static void interruption_end(SDL_AudioDevice *_this)
     @synchronized(self) {
         NSNumber *type = note.userInfo[AVAudioSessionInterruptionTypeKey];
         if (type.unsignedIntegerValue == AVAudioSessionInterruptionTypeBegan) {
-            interruption_begin(self.device);
+            InterruptionBegin(self.device);
         } else {
-            interruption_end(self.device);
+            InterruptionEnd(self.device);
         }
     }
 }
@@ -361,13 +354,32 @@ static void interruption_end(SDL_AudioDevice *_this)
 - (void)applicationBecameActive:(NSNotification *)note
 {
     @synchronized(self) {
-        interruption_end(self.device);
+        InterruptionEnd(self.device);
     }
 }
 
 @end
 
-static BOOL update_audio_session(SDL_AudioDevice *_this, SDL_bool open, SDL_bool allow_playandrecord)
+typedef struct
+{
+    int output;
+    int capture;
+} CountOpenAudioDevicesData;
+
+static SDL_bool CountOpenAudioDevices(SDL_AudioDevice *device, void *userdata)
+{
+    CountOpenAudioDevicesData *data = (CountOpenAudioDevicesData *) userdata;
+    if (device->hidden != NULL) {  // assume it's open if hidden != NULL
+        if (device->iscapture) {
+            data->capture++;
+        } else {
+            data->output++;
+        }
+    }
+    return SDL_FALSE;  // keep enumerating until all devices have been checked.
+}
+
+static SDL_bool UpdateAudioSession(SDL_AudioDevice *device, SDL_bool open, SDL_bool allow_playandrecord)
 {
     @autoreleasepool {
         AVAudioSession *session = [AVAudioSession sharedInstance];
@@ -379,6 +391,10 @@ static BOOL update_audio_session(SDL_AudioDevice *_this, SDL_bool open, SDL_bool
         NSError *err = nil;
         const char *hint;
 
+        CountOpenAudioDevicesData data;
+        SDL_zero(data);
+        (void) SDL_FindPhysicalAudioDeviceByCallback(CountOpenAudioDevices, &data);
+
         hint = SDL_GetHint(SDL_HINT_AUDIO_CATEGORY);
         if (hint) {
             if (SDL_strcasecmp(hint, "AVAudioSessionCategoryAmbient") == 0) {
@@ -396,17 +412,17 @@ static BOOL update_audio_session(SDL_AudioDevice *_this, SDL_bool open, SDL_bool
                     category = AVAudioSessionCategoryPlayAndRecord;
                 }
             }
-        } else if (open_playback_devices && open_capture_devices) {
+        } else if (data.output && data.capture) {
             category = AVAudioSessionCategoryPlayAndRecord;
-        } else if (open_capture_devices) {
+        } else if (data.capture) {
             category = AVAudioSessionCategoryRecord;
         }
 
-#if !TARGET_OS_TV
+        #if !TARGET_OS_TV
         if (category == AVAudioSessionCategoryPlayAndRecord) {
             options |= AVAudioSessionCategoryOptionDefaultToSpeaker;
         }
-#endif
+        #endif
         if (category == AVAudioSessionCategoryRecord ||
             category == AVAudioSessionCategoryPlayAndRecord) {
             /* AVAudioSessionCategoryOptionAllowBluetooth isn't available in the SDK for
@@ -426,53 +442,53 @@ static BOOL update_audio_session(SDL_AudioDevice *_this, SDL_bool open, SDL_bool
         if ([session respondsToSelector:@selector(setCategory:mode:options:error:)]) {
             if (![session.category isEqualToString:category] || session.categoryOptions != options) {
                 /* Stop the current session so we don't interrupt other application audio */
-                pause_audio_devices();
+                PauseAudioDevices();
                 [session setActive:NO error:nil];
-                session_active = NO;
+                session_active = SDL_FALSE;
 
                 if (![session setCategory:category mode:mode options:options error:&err]) {
                     NSString *desc = err.description;
                     SDL_SetError("Could not set Audio Session category: %s", desc.UTF8String);
-                    return NO;
+                    return SDL_FALSE;
                 }
             }
         } else {
             if (![session.category isEqualToString:category]) {
                 /* Stop the current session so we don't interrupt other application audio */
-                pause_audio_devices();
+                PauseAudioDevices();
                 [session setActive:NO error:nil];
-                session_active = NO;
+                session_active = SDL_FALSE;
 
                 if (![session setCategory:category error:&err]) {
                     NSString *desc = err.description;
                     SDL_SetError("Could not set Audio Session category: %s", desc.UTF8String);
-                    return NO;
+                    return SDL_FALSE;
                 }
             }
         }
 
-        if ((open_playback_devices || open_capture_devices) && !session_active) {
+        if ((data.output || data.capture) && !session_active) {
             if (![session setActive:YES error:&err]) {
                 if ([err code] == AVAudioSessionErrorCodeResourceNotAvailable &&
                     category == AVAudioSessionCategoryPlayAndRecord) {
-                    return update_audio_session(_this, open, SDL_FALSE);
+                    return UpdateAudioSession(device, open, SDL_FALSE);
                 }
 
                 NSString *desc = err.description;
                 SDL_SetError("Could not activate Audio Session: %s", desc.UTF8String);
-                return NO;
+                return SDL_FALSE;
             }
-            session_active = YES;
-            resume_audio_devices();
-        } else if (!open_playback_devices && !open_capture_devices && session_active) {
-            pause_audio_devices();
+            session_active = SDL_TRUE;
+            ResumeAudioDevices();
+        } else if (!data.output && !data.capture && session_active) {
+            PauseAudioDevices();
             [session setActive:NO error:nil];
-            session_active = NO;
+            session_active = SDL_FALSE;
         }
 
         if (open) {
             SDLInterruptionListener *listener = [SDLInterruptionListener new];
-            listener.device = _this;
+            listener.device = device;
 
             [center addObserver:listener
                        selector:@selector(audioSessionInterruption:)
@@ -493,10 +509,10 @@ static BOOL update_audio_session(SDL_AudioDevice *_this, SDL_bool open, SDL_bool
                            name:UIApplicationWillEnterForegroundNotification
                          object:nil];
 
-            _this->hidden->interruption_listener = CFBridgingRetain(listener);
+            device->hidden->interruption_listener = CFBridgingRetain(listener);
         } else {
             SDLInterruptionListener *listener = nil;
-            listener = (SDLInterruptionListener *)CFBridgingRelease(_this->hidden->interruption_listener);
+            listener = (SDLInterruptionListener *)CFBridgingRelease(device->hidden->interruption_listener);
             [center removeObserver:listener];
             @synchronized(listener) {
                 listener.device = NULL;
@@ -504,247 +520,117 @@ static BOOL update_audio_session(SDL_AudioDevice *_this, SDL_bool open, SDL_bool
         }
     }
 
-    return YES;
+    return SDL_TRUE;
 }
 #endif
 
-/* The AudioQueue callback */
-static void outputCallback(void *inUserData, AudioQueueRef inAQ, AudioQueueBufferRef inBuffer)
-{
-    SDL_AudioDevice *_this = (SDL_AudioDevice *)inUserData;
-
-    /* This flag is set before _this->mixer_lock is destroyed during
-       shutdown, so check it before grabbing the mutex, and then check it
-       again _after_ in case we blocked waiting on the lock. */
-    if (SDL_AtomicGet(&_this->shutdown)) {
-        return; /* don't do anything, since we don't even want to enqueue this buffer again. */
-    }
-
-    SDL_LockMutex(_this->mixer_lock);
-
-    if (SDL_AtomicGet(&_this->shutdown)) {
-        SDL_UnlockMutex(_this->mixer_lock);
-        return; /* don't do anything, since we don't even want to enqueue this buffer again. */
-    }
 
-    if (!SDL_AtomicGet(&_this->enabled) || SDL_AtomicGet(&_this->paused)) {
-        /* Supply silence if audio is not enabled or paused */
-        SDL_memset(inBuffer->mAudioData, _this->spec.silence, inBuffer->mAudioDataBytesCapacity);
-    } else if (_this->stream) {
-        UInt32 remaining = inBuffer->mAudioDataBytesCapacity;
-        Uint8 *ptr = (Uint8 *)inBuffer->mAudioData;
-
-        while (remaining > 0) {
-            if (SDL_GetAudioStreamAvailable(_this->stream) == 0) {
-                /* Generate the data */
-                (*_this->callbackspec.callback)(_this->callbackspec.userdata,
-                                               _this->hidden->buffer, _this->hidden->bufferSize);
-                _this->hidden->bufferOffset = 0;
-                SDL_PutAudioStreamData(_this->stream, _this->hidden->buffer, _this->hidden->bufferSize);
-            }
-            if (SDL_GetAudioStreamAvailable(_this->stream) > 0) {
-                int got;
-                UInt32 len = SDL_GetAudioStreamAvailable(_this->stream);
-                if (len > remaining) {
-                    len = remaining;
-                }
-                got = SDL_GetAudioStreamData(_this->stream, ptr, len);
-                SDL_assert((got < 0) || (got == len));
-                if (got != len) {
-                    SDL_memset(ptr, _this->spec.silence, len);
-                }
-                ptr = ptr + len;
-                remaining -= len;
-            }
-        }
-    } else {
-        UInt32 remaining = inBuffer->mAudioDataBytesCapacity;
-        Uint8 *ptr = (Uint8 *)inBuffer->mAudioData;
-
-        while (remaining > 0) {
-            UInt32 len;
-            if (_this->hidden->bufferOffset >= _this->hidden->bufferSize) {
-                /* Generate the data */
-                (*_this->callbackspec.callback)(_this->callbackspec.userdata,
-                                               _this->hidden->buffer, _this->hidden->bufferSize);
-                _this->hidden->bufferOffset = 0;
-            }
-
-            len = _this->hidden->bufferSize - _this->hidden->bufferOffset;
-            if (len > remaining) {
-                len = remaining;
-            }
-            SDL_memcpy(ptr, (char *)_this->hidden->buffer + _this->hidden->bufferOffset, len);
-            ptr = ptr + len;
-            remaining -= len;
-            _this->hidden->bufferOffset += len;
-        }
-    }
-
-    AudioQueueEnqueueBuffer(_this->hidden->audioQueue, inBuffer, 0, NULL);
-
-    inBuffer->mAudioDataByteSize = inBuffer->mAudioDataBytesCapacity;
-
-    SDL_UnlockMutex(_this->mixer_lock);
+static void COREAUDIO_PlayDevice(SDL_AudioDevice *device, const Uint8 *buffer, int buffer_size)
+{
+    AudioQueueBufferRef current_buffer = device->hidden->current_buffer;
+    SDL_assert(current_buffer != NULL);  // should have been called from OutputBufferReadyCallback
+    SDL_assert(buffer == (Uint8 *) current_buffer->mAudioData);
+    current_buffer->mAudioDataByteSize = current_buffer->mAudioDataBytesCapacity;
+    device->hidden->current_buffer = NULL;
+    AudioQueueEnqueueBuffer(device->hidden->audioQueue, current_buffer, 0, NULL);
 }
 
-static void inputCallback(void *inUserData, AudioQueueRef inAQ, AudioQueueBufferRef inBuffer,
-                          const AudioTimeStamp *inStartTime, UInt32 inNumberPacketDescriptions,
-                          const AudioStreamPacketDescription *inPacketDescs)
+static Uint8 *COREAUDIO_GetDeviceBuf(SDL_AudioDevice *device, int *buffer_size)
 {
-    SDL_AudioDevice *_this = (SDL_AudioDevice *)inUserData;
-
-    if (SDL_AtomicGet(&_this->shutdown)) {
-        return; /* don't do anything. */
-    }
-
-    /* ignore unless we're active. */
-    if (!SDL_AtomicGet(&_this->paused) && SDL_AtomicGet(&_this->enabled)) {
-        const Uint8 *ptr = (const Uint8 *)inBuffer->mAudioData;
-        UInt32 remaining = inBuffer->mAudioDataByteSize;
-        while (remaining > 0) {
-            UInt32 len = _this->hidden->bufferSize - _this->hidden->bufferOffset;
-            if (len > remaining) {
-                len = remaining;
-            }
-
-            SDL_memcpy((char *)_this->hidden->buffer + _this->hidden->bufferOffset, ptr, len);
-            ptr += len;
-            remaining -= len;
-            _this->hidden->bufferOffset += len;
-
-            if (_this->hidden->bufferOffset >= _this->hidden->bufferSize) {
-                SDL_LockMutex(_this->mixer_lock);
-                (*_this->callbackspec.callback)(_this->callbackspec.userdata, _this->hidden->buffer, _this->hidden->bufferSize);
-                SDL_UnlockMutex(_this->mixer_lock);
-                _this->hidden->bufferOffset = 0;
-            }
-        }
-    }
-
-    AudioQueueEnqueueBuffer(_this->hidden->audioQueue, inBuffer, 0, NULL);
+    AudioQueueBufferRef current_buffer = device->hidden->current_buffer;
+    SDL_assert(current_buffer != NULL);  // should have been called from OutputBufferReadyCallback
+    SDL_assert(current_buffer->mAudioData != NULL);
+    *buffer_size = (int) current_buffer->mAudioDataBytesCapacity;
+    return (Uint8 *) current_buffer->mAudioData;
 }
 
-#ifdef MACOSX_COREAUDIO
-static const AudioObjectPropertyAddress alive_address = {
-    kAudioDevicePropertyDeviceIsAlive,
-    kAudioObjectPropertyScopeGlobal,
-    kAudioObjectPropertyElementMain
-};
-
-static OSStatus device_unplugged(AudioObjectID devid, UInt32 num_addr, const AudioObjectPropertyAddress *addrs, void *data)
+static void OutputBufferReadyCallback(void *inUserData, AudioQueueRef inAQ, AudioQueueBufferRef inBuffer)
 {
-    SDL_AudioDevice *_this = (SDL_AudioDevice *)data;
-    SDL_bool dead = SDL_FALSE;
-    UInt32 isAlive = 1;
-    UInt32 size = sizeof(isAlive);
-    OSStatus error;
-
-    if (!SDL_AtomicGet(&_this->enabled)) {
-        return 0; /* already known to be dead. */
-    }
-
-    error = AudioObjectGetPropertyData(_this->hidden->deviceID, &alive_address,
-                                       0, NULL, &size, &isAlive);
-
-    if (error == kAudioHardwareBadDeviceError) {
-        dead = SDL_TRUE; /* device was unplugged. */
-    } else if ((error == kAudioHardwareNoError) && (!isAlive)) {
-        dead = SDL_TRUE; /* device died in some other way. */
-    }
-
-    if (dead) {
-        SDL_OpenedAudioDeviceDisconnected(_this);
-    }
-
-    return 0;
+    SDL_AudioDevice *device = (SDL_AudioDevice *)inUserData;
+    SDL_assert(inBuffer != NULL);  // ...right?
+    SDL_assert(device->hidden->current_buffer == NULL);  // shouldn't have anything pending
+    device->hidden->current_buffer = inBuffer;
+    SDL_OutputAudioThreadIterate(device);
+    SDL_assert(device->hidden->current_buffer == NULL);  // PlayDevice should have enqueued and cleaned it out.
 }
 
-/* macOS calls this when the default device changed (if we have a default device open). */
-static OSStatus default_device_changed(AudioObjectID inObjectID, UInt32 inNumberAddresses, const AudioObjectPropertyAddress *inAddresses, void *inUserData)
+static int COREAUDIO_CaptureFromDevice(SDL_AudioDevice *device, void *buffer, int buflen)
 {
-    SDL_AudioDevice *_this = (SDL_AudioDevice *)inUserData;
-#if DEBUG_COREAUDIO
-    printf("COREAUDIO: default device changed for SDL audio device %p!\n", _this);
-#endif
-    SDL_AtomicSet(&_this->hidden->device_change_flag, 1); /* let the audioqueue thread pick up on this when safe to do so. */
-    return noErr;
+    AudioQueueBufferRef current_buffer = device->hidden->current_buffer;
+    SDL_assert(current_buffer != NULL);  // should have been called from InputBufferReadyCallback
+    SDL_assert(current_buffer->mAudioData != NULL);
+    SDL_assert(buflen >= (int) current_buffer->mAudioDataByteSize);  // `cpy` makes sure this won't overflow a buffer, but we _will_ drop samples if this assertion fails!
+    const int cpy = SDL_min(buflen, (int) current_buffer->mAudioDataByteSize);
+    SDL_memcpy(buffer, current_buffer->mAudioData, cpy);
+    device->hidden->current_buffer = NULL;
+    AudioQueueEnqueueBuffer(device->hidden->audioQueue, current_buffer, 0, NULL);  // requeue for capturing more data later.
+    return cpy;
 }
-#endif
 
-static void COREAUDIO_CloseDevice(SDL_AudioDevice *_this)
+static void COREAUDIO_FlushCapture(SDL_AudioDevice *device)
 {
-    const SDL_bool iscapture = _this->iscapture;
-    int i;
-
-/* !!! FIXME: what does iOS do when a bluetooth audio device vanishes? Headphones unplugged? */
-/* !!! FIXME: (we only do a "default" device on iOS right now...can we do more?) */
-#ifdef MACOSX_COREAUDIO
-    if (_this->handle != NULL) { /* we don't register this listener for default devices. */
-        AudioObjectRemovePropertyListener(_this->hidden->deviceID, &alive_address, device_unplugged, _this);
+    AudioQueueBufferRef current_buffer = device->hidden->current_buffer;
+    if (current_buffer != NULL) {  // also gets called at shutdown, when no buffer is available.
+        // just requeue the current buffer without reading from it, so it can be refilled with new data later.
+        device->hidden->current_buffer = NULL;
+        AudioQueueEnqueueBuffer(device->hidden->audioQueue, current_buffer, 0, NULL);
     }
-#endif
+}
 
-    /* if callback fires again, feed silence; don't call into the app. */
-    SDL_AtomicSet(&_this->paused, 1);
+static void InputBufferReadyCallback(void *inUserData, AudioQueueRef inAQ, AudioQueueBufferRef inBuffer,
+                          const AudioTimeStamp *inStartTime, UInt32 inNumberPacketDescriptions,
+                          const AudioStreamPacketDescription *inPacketDescs)
+{
+    SDL_AudioDevice *device = (SDL_AudioDevice *)inUserData;
+    SDL_assert(inAQ == device->hidden->audioQueue);
+    SDL_assert(inBuffer != NULL);  // ...right?
+    SDL_assert(device->hidden->current_buffer == NULL);  // shouldn't have anything pending
+    device->hidden->current_buffer = inBuffer;
+    SDL_CaptureAudioThreadIterate(device);
+    SDL_assert(device->hidden->current_buffer == NULL);  // CaptureFromDevice/FlushCapture should have enqueued and cleaned it out.
+}
 
-    /* dispose of the audio queue before waiting on the thread, or it might stall for a long time! */
-    if (_this->hidden->audioQueue) {
-        AudioQueueFlush(_this->hidden->audioQueue);
-        AudioQueueStop(_this->hidden->audioQueue, 0);
-        AudioQueueDispose(_this->hidden->audioQueue, 0);
+static void COREAUDIO_CloseDevice(SDL_AudioDevice *device)
+{
+    if (!device->hidden) {
+        return;
     }
 
-    if (_this->hidden->thread) {
-        SDL_assert(SDL_AtomicGet(&_this->shutdown) != 0); /* should have been set by SDL_audio.c */
-        SDL_WaitThread(_this->hidden->thread, NULL);
+    // dispose of the audio queue before waiting on the thread, or it might stall for a long time!
+    if (device->hidden->audioQueue) {
+        AudioQueueFlush(device->hidden->audioQueue);
+        AudioQueueStop(device->hidden->audioQueue, 0);
+        AudioQueueDispose(device->hidden->audioQueue, 0);
     }
 
-    if (iscapture) {
-        open_capture_devices--;
-    } else {
-        open_playback_devices--;
+    if (device->hidden->thread) {
+        SDL_assert(SDL_AtomicGet(&device->shutdown) != 0); // should have been set by SDL_audio.c
+        SDL_WaitThread(device->hidden->thread, NULL);
     }
 
-#ifndef MACOSX_COREAUDIO
-    update_audio_session(_this, SDL_FALSE, SDL_TRUE);
-#endif
-
-    for (i = 0; i < num_open_devices; ++i) {
-        if (open_devices[i] == _this) {
-            --num_open_devices;
-            if (i < num_open_devices) {
-                SDL_memmove(&open_devices[i], &open_devices[i + 1], sizeof(open_devices[i]) * (num_open_devices - i));
-            }
-            break;
-        }
-    }
-    if (num_open_devices == 0) {
-        SDL_free(open_devices);
-        open_devices = NULL;
-    }
+    #ifndef MACOSX_COREAUDIO
+    UpdateAudioSession(device, SDL_FALSE, SDL_TRUE);
+    #endif
 
-    if (_this->hidden->ready_semaphore) {
-        SDL_DestroySemaphore(_this->hidden->ready_semaphore);
+    if (device->hidden->ready_semaphore) {
+        SDL_DestroySemaphore(device->hidden->ready_semaphore);
     }
 
-    /* AudioQueueDispose() frees the actual buffer objects. */
-    SDL_free(_this->hidden->audioBuffer);
-    SDL_free(_this->hidden->thread_error);
-    SDL_free(_this->hidden->buffer);
-    SDL_free(_this->hidden);
+    // AudioQueueDispose() frees the actual buffer objects.
+    SDL_free(device->hidden->audioBuffer);
+    SDL_free(device->hidden->thread_error);
+    SDL_free(device->hidden);
 }
 
 #ifdef MACOSX_COREAUDIO
-static int prepare_device(SDL_AudioDevice *_this)
+static int PrepareDevice(SDL_AudioDevice *device)
 {
-    void *handle = _this->handle;
-    SDL_bool iscapture = _this->iscapture;
-    AudioDeviceID devid = (AudioDeviceID)((size_t)handle);
+    void *handle = device->handle;
+    SDL_assert(handle != NULL);  // this meant "system default" in SDL2, but doesn't anymore
+
+    const AudioDeviceID devid = (AudioDeviceID)((size_t)handle);
     OSStatus result = noErr;
     UInt32 size = 0;
-    UInt32 alive = 0;
-    pid_t pid = 0;
 
     AudioObjectPropertyAddress addr = {
         0,
@@ -752,104 +638,80 @@ static int prepare_device(SDL_AudioDevice *_this)
         kAudioObjectPropertyElementMain
     };
 
-    if (handle == NULL) {
-        size = sizeof(AudioDeviceID);
-        addr.mSelector =
-            ((iscapture) ? kAudioHardwarePropertyDefaultInputDevice : kAudioHardwarePropertyDefaultOutputDevice);
-        result = AudioObjectGetPropertyData(kAudioObjectSystemObject, &addr,
-                                            0, NULL, &size, &devid);
-        CHECK_RESULT("AudioHardwareGetProperty (default device)");
-    }
-
-    addr.mSelector = kAudioDevicePropertyDeviceIsAlive;
-    addr.mScope = iscapture ? kAudioDevicePropertyScopeInput : kAudioDevicePropertyScopeOutput;
-
+    UInt32 alive = 0;
     size = sizeof(alive);
+    addr.mSelector = kAudioDevicePropertyDeviceIsAlive;
+    addr.mScope = device->iscapture ? kAudioDevicePropertyScopeInput : kAudioDevicePropertyScopeOutput;
     result = AudioObjectGetPropertyData(devid, &addr, 0, NULL, &size, &alive);
     CHECK_RESULT("AudioDeviceGetProperty (kAudioDevicePropertyDeviceIsAlive)");
-
     if (!alive) {
-        SDL_SetError("CoreAudio: requested device exists, but isn't alive.");
-        return 0;
+        return SDL_SetError("CoreAudio: requested device exists, but isn't alive.");
     }
 
-    addr.mSelector = kAudioDevicePropertyHogMode;
+    // some devices don't support this property, so errors are fine here.
+    pid_t pid = 0;
     size = sizeof(pid);
+    addr.mSelector = kAudioDevicePropertyHogMode;
     result = AudioObjectGetPropertyData(devid, &addr, 0, NULL, &size, &pid);
-
-    /* some devices don't support this property, so errors are fine here. */
     if ((result == noErr) && (pid != -1)) {
-        SDL_SetError("CoreAudio: requested device is being hogged.");
-        return 0;
+        return SDL_SetError("CoreAudio: requested device is being hogged.");
     }
 
-    _this->hidden->deviceID = devid;
-    return 1;
+    device->hidden->deviceID = devid;
+
+    return 0;
 }
 
-static int assign_device_to_audioqueue(SDL_AudioDevice *_this)
+static int AssignDeviceToAudioQueue(SDL_AudioDevice *device)
 {
     const AudioObjectPropertyAddress prop = {
         kAudioDevicePropertyDeviceUID,
-        _this->iscapture ? kAudioDevicePropertyScopeInput : kAudioDevicePropertyScopeOutput,
+        device->iscapture ? kAudioDevicePropertyScopeInput : kAudioDevicePropertyScopeOutput,
         kAudioObjectPropertyElementMain
     };
 
     OSStatus result;
     CFStringRef devuid;
     UInt32 devuidsize = sizeof(devuid);
-    result = AudioObjectGetPropertyData(_this->hidden->deviceID, &prop, 0, NULL, &devuidsize, &devuid);
+    result = AudioObjectGetPropertyData(device->hidden->deviceID, &prop, 0, NULL, &devuidsize, &devuid);
     CHECK_RESULT("AudioObjectGetPropertyData (kAudioDevicePropertyDeviceUID)");
-    result = AudioQueueSetProperty(_this->hidden->audioQueue, kAudioQueueProperty_CurrentDevice, &devuid, devuidsize);
+    result = AudioQueueSetProperty(device->hidden->audioQueue, kAudioQueueProperty_CurrentDevice, &devuid, devuidsize);
     CHECK_RESULT("AudioQueueSetProperty (kAudioQueueProperty_CurrentDevice)");
 
-    return 1;
+    // !!! FIXME: do we need to CFRelease(devuid)?
+
+    return 0;
 }
 #endif
 
-static int prepare_audioqueue(SDL_AudioDevice *_this)
+static int PrepareAudioQueue(SDL_AudioDevice *device)
 {
-    const AudioStreamBasicDescription *strdesc = &_this->hidden->strdesc;
-    const int iscapture = _this->iscapture;
+    const AudioStreamBasicDescription *strdesc = &device->hidden->strdesc;
+    const SDL_bool iscapture = device->iscapture;
     OSStatus result;
-    int i, numAudioBuffers = 2;
-    AudioChannelLayout layout;
-    double MINIMUM_AUDIO_BUFFER_TIME_MS;
-    const double msecs = (_this->spec.samples / ((double)_this->spec.freq)) * 1000.0;
-    ;
 
     SDL_assert(CFRunLoopGetCurrent() != NULL);
 
     if (iscapture) {
-        result = AudioQueueNewInput(strdesc, inputCallback, _this, CFRunLoopGetCurrent(), kCFRunLoopDefaultMode, 0, &_this->hidden->audioQueue);
+        result = AudioQueueNewInput(strdesc, InputBufferReadyCallback, device, CFRunLoopGetCurrent(), kCFRunLoopDefaultMode, 0, &device->hidden->audioQueue);
         CHECK_RESULT("AudioQueueNewInput");
     } else {
-        result = AudioQueueNewOutput(strdesc, outputCallback, _this, CFRunLoopGetCurrent(), kCFRunLoopDefaultMode, 0, &_this->hidden->audioQueue);
+        result = AudioQueueNewOutput(strdesc, OutputBufferReadyCallback, device, CFRunLoopGetCurrent(), kCFRunLoopDefaultMode, 0, &device->hidden->audioQueue);
         CHECK_RESULT("AudioQueueNewOutput");
     }
 
-#ifdef MACOSX_COREAUDIO
-    if (!assign_device_to_audioqueue(_this)) {
-        return 0;
-    }
-
-    /* only listen for unplugging on specific devices, not the default device, as that should
-       switch to a different device (or hang out silently if there _is_ no other device). */
-    if (_this->handle != NULL) {
-        /* !!! FIXME: what does iOS do when a bluetooth audio device vanishes? Headphones unplugged? */
-        /* !!! FIXME: (we only do a "default" device on iOS right now...can we do more?) */
-        /* Fire a callback if the device stops being "alive" (disconnected, etc). */
-        /* If this fails, oh well, we won't notice a device had an extraordinary event take place. */
-        AudioObjectAddPropertyListener(_this->hidden->deviceID, &alive_address, device_unplugged, _this);
+    #ifdef MACOSX_COREAUDIO
+    if (AssignDeviceToAudioQueue(device) < 0) {
+        return -1;
     }
-#endif
+    #endif
 
-    /* Calculate the final parameters for this audio specification */
-    SDL_CalculateAudioSpec(&_this->spec);
+    SDL_UpdatedAudioDeviceFormat(device);  // make sure this is correct.
 
     /* Set the channel layout for the audio queue */
+    AudioChannelLayout layout;
     SDL_zero(layout);
-    switch (_this->spec.channels) {
+    switch (device->spec.channels) {
     case 1:
         layout.mChannelLayoutTag = kAudioChannelLayoutTag_Mono;
         break;
@@ -877,198 +739,129 @@ static int prepare_audioqueue(SDL_AudioDevice *_this)
         break;
     }
     if (layout.mChannelLayoutTag != 0) {
-        result = AudioQueueSetProperty(_this->hidden->audioQueue, kAudioQueueProperty_ChannelLayout, &layout, sizeof(layout));
+        result = AudioQueueSetProperty(device->hidden->audioQueue, kAudioQueueProperty_ChannelLayout, &layout, sizeof(layout));
         CHECK_RESULT("AudioQueueSetProperty(kAudioQueueProperty_ChannelLayout)");
     }
 
-    /* Allocate a sample buffer */
-    _this->hidden->bufferSize = _this->spec.size;
-    _this->hidden->bufferOffset = iscapture ? 0 : _this->hidden->bufferSize;
-
-    _this->hidden->buffer = SDL_malloc(_this->hidden->bufferSize);
-    if (_this->hidden->buffer == NULL) {
-        SDL_OutOfMemory();
-        return 0;
-    }
-
-    /* Make sure we can feed the device a minimum amount of time */
-    MINIMUM_AUDIO_BUFFER_TIME_MS = 15.0;
-#ifdef __IOS__
+    // Make sure we can feed the device a minimum amount of time
+    double MINIMUM_AUDIO_BUFFER_TIME_MS = 15.0;
+    #ifdef __IOS__
     if (SDL_floor(NSFoundationVersionNumber) <= NSFoundationVersionNumber_iOS_7_1) {
-        /* Older iOS hardware, use 40 ms as a minimum time */
+        // Older iOS hardware, use 40 ms as a minimum time
         MINIMUM_AUDIO_BUFFER_TIME_MS = 40.0;
     }
-#endif
+    #endif
+
+    int numAudioBuffers = 2;
+    const double msecs = (device->sample_frames / ((double)device->spec.freq)) * 1000.0;
     if (msecs < MINIMUM_AUDIO_BUFFER_TIME_MS) { /* use more buffers if we have a VERY small sample set. */
         numAudioBuffers = ((int)SDL_ceil(MINIMUM_AUDIO_BUFFER_TIME_MS / msecs) * 2);
     }
 
-    _this->hidden->numAudioBuffers = numAudioBuffers;
-    _this->hidden->audioBuffer = SDL_calloc(1, sizeof(AudioQueueBufferRef) * numAudioBuffers);
-    if (_this->hidden->audioBuffer == NULL) {
-        SDL_OutOfMemory();
-        return 0;
+    device->hidden->numAudioBuffers = numAudioBuffers;
+    device->hidden->audioBuffer = SDL_calloc(numAudioBuffers, sizeof(AudioQueueBufferRef));
+    if (device->hidden->audioBuffer == NULL) {
+        return SDL_OutOfMemory();
     }
 
-#if DEBUG_COREAUDIO
-    printf("COREAUDIO: numAudioBuffers == %d\n", numAudioBuffers);
-#endif
+    #if DEBUG_COREAUDIO
+    SDL_Log("COREAUDIO: numAudioBuffers == %d\n", numAudioBuffers);
+    #endif
 
-    for (i = 0; i < numAudioBuffers; i++) {
-        result = AudioQueueAllocateBuffer(_this->hidden->audioQueue, _this->spec.size, &_this->hidden->audioBuffer[i]);
+    for (int i = 0; i < numAudioBuffers; i++) {
+        result = AudioQueueAllocateBuffer(device->hidden->audioQueue, device->buffer_size, &device->hidden->audioBuffer[i]);
         CHECK_RESULT("AudioQueueAllocateBuffer");
-        SDL_memset(_this->hidden->audioBuffer[i]->mAudioData, _this->spec.silence, _this->hidden->audioBuffer[i]->mAudioDataBytesCapacity);
-        _this->hidden->audioBuffer[i]->mAudioDataByteSize = _this->hidden->audioBuffer[i]->mAudioDataBytesCapacity;
+        SDL_memset(device->hidden->audioBuffer[i]->mAudioData, device->silence_value, device->hidden->audioBuffer[i]->mAudioDataBytesCapacity);
+        device->hidden->audioBuffer[i]->mAudioDataByteSize = device->hidden->audioBuffer[i]->mAudioDataBytesCapacity;
         /* !!! FIXME: should we use AudioQueueEnqueueBufferWithParameters and specify all frames be "trimmed" so these are immediately ready to refill with SDL callback data? */
-        result = AudioQueueEnqueueBuffer(_this->hidden->audioQueue, _this->hidden->audioBuffer[i], 0, NULL);
+        result = AudioQueueEnqueueBuffer(device->hidden->audioQueue, device->hidden->audioBuffer[i], 0, NULL);
         CHECK_RESULT("AudioQueueEnqueueBuffer");
     }
 
-    result = AudioQueueStart(_this->hidden->audioQueue, NULL);
+    result = AudioQueueStart(device->hidden->audioQueue, NULL);
     CHECK_RESULT("AudioQueueStart");
 
-    /* We're running! */
-    return 1;
+    return 0;  // We're running!
 }
 
-static int audioqueue_thread(void *arg)
+static int AudioQueueThreadEntry(void *arg)
 {
-    SDL_AudioDevice *_this = (SDL_AudioDevice *)arg;
-    int rc;
+    SDL_AudioDevice *device = (SDL_AudioDevice *)arg;
 
-#ifdef MACOSX_COREAUDIO
-    const AudioObjectPropertyAddress default_device_address = {
-        _this->iscapture ? kAudioHardwarePropertyDefaultInputDevice : kAudioHardwarePropertyDefaultOutputDevice,
-        kAudioObjectPropertyScopeGlobal,
-        kAudioObjectPropertyElementMain
-    };
-
-    if (_this->handle == NULL) { /* opened the default device? Register to know if the user picks a new default. */
-        /* we don't care if this fails; we just won't change to new default devices, but we still otherwise function in this case. */
-        AudioObjectAddPropertyListener(kAudioObjectSystemObject, &default_device_address, default_device_changed, _this);
+    if (device->iscapture) {
+        SDL_CaptureAudioThreadSetup(device);
+    } else {
+        SDL_OutputAudioThreadSetup(device);
     }
-#endif
 
-    rc = prepare_audioqueue(_this);
-    if (!rc) {
-        _this->hidden->thread_error = SDL_strdup(SDL_GetError());
-        SDL_PostSemaphore(_this->hidden->ready_semaphore);
+    if (PrepareAudioQueue(device) < 0) {
+        device->hidden->thread_error = SDL_strdup(SDL_GetError());
+        SDL_PostSemaphore(device->hidden->ready_semaphore);
         return 0;
     }
 
-    SDL_SetThreadPriority(SDL_THREAD_PRIORITY_HIGH);
+    // init was successful, alert parent thread and start running...
+    SDL_PostSemaphore(device->hidden->ready_semaphore);
 
-    /* init was successful, alert parent thread and start running... */
-    SDL_PostSemaphore(_this->hidden->ready_semaphore);
-
-    while (!SDL_AtomicGet(&_this->shutdown)) {
+    // This would be WaitDevice/WaitCaptureDevice in the normal SDL audio thread, but we get *BufferReadyCallback calls here to know when to iterate.
+    while (!SDL_AtomicGet(&device->shutdown)) {
         CFRunLoopRunInMode(kCFRunLoopDefaultMode, 0.10, 1);
-
-#ifdef MACOSX_COREAUDIO
-        if ((_this->handle == NULL) && SDL_AtomicGet(&_this->hidden->device_change_flag)) {
-            const AudioDeviceID prev_devid = _this->hidden->deviceID;
-            SDL_AtomicSet(&_this->hidden->device_change_flag, 0);
-
-#if DEBUG_COREAUDIO
-            printf("COREAUDIO: audioqueue_thread is trying to switch to new default device!\n");
-#endif
-
-            /* if any of this fails, there's not much to do but wait to see if the user gives up
-               and quits (flagging the audioqueue for shutdown), or toggles to some other system
-               output device (in which case we'll try again). */
-            if (prepare_device(_this) && (prev_devid != _this->hidden->deviceID)) {
-                AudioQueueStop(_this->hidden->audioQueue, 1);
-                if (assign_device_to_audioqueue(_this)) {
-                    int i;
-                    for (i = 0; i < _this->hidden->numAudioBuffers; i++) {
-                        SDL_memset(_this->hidden->audioBuffer[i]->mAudioData, _this->spec.silence, _this->hidden->audioBuffer[i]->mAudioDataBytesCapacity);
-                        /* !!! FIXME: should we use AudioQueueEnqueueBufferWithParameters and specify all frames be "trimmed" so these are immediately ready to refill with SDL callback data? */
-                        AudioQueueEnqueueBuffer(_this->hidden->audioQueue, _this->hidden->audioBuffer[i], 0, NULL);
-                    }
-                    AudioQueueStart(_this->hidden->audioQueue, NULL);
-                }
-            }
-        }
-#endif
     }
 
-    if (!_this->iscapture) { /* Drain off any pending playback. */
-        const CFTimeInterval secs = (((_this->spec.size / (SDL_AUDIO_BITSIZE(_this->spec.format) / 8.0)) / _this->spec.channels) / ((CFTimeInterval)_this->spec.freq)) * 2.0;
+    if (device->iscapture) {
+        SDL_CaptureAudioThreadShutdown(device);
+    } else {
+        // Drain off any pending playback.
+        const CFTimeInterval secs = (((CFTimeInterval)device->sample_frames) / ((CFTimeInterval)device->spec.freq)) * 2.0;
         CFRunLoopRunInMode(kCFRunLoopDefaultMode, secs, 0);
+        SDL_OutputAudioThreadShutdown(device);
     }
 
-#ifdef MACOSX_COREAUDIO
-    if (_this->handle == NULL) {
-        /* we don't care if this fails; we just won't change to new default devices, but we still otherwise function in this case. */
-        AudioObjectRemovePropertyListener(kAudioObjectSystemObject, &default_device_address, default_device_changed, _this);
-    }
-#endif
-
     return 0;
 }
 
-static int COREAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
+static int COREAUDIO_OpenDevice(SDL_AudioDevice *device)
 {
-    AudioStreamBasicDescription *strdesc;
-    const SDL_AudioFormat *closefmts;
-    SDL_AudioFormat test_format;
-    SDL_bool iscapture = _this->iscapture;
-    SDL_AudioDevice **new_open_devices;
-
     /* Initialize all variables that we clean on shutdown */
-    _this->hidden = (struct SDL_PrivateAudioData *)SDL_malloc(sizeof(*_this->hidden));
-    if (_this->hidden == NULL) {
+    device->hidden = (struct SDL_PrivateAudioData *)SDL_calloc(1, sizeof(*device->hidden));
+    if (device->hidden == NULL) {
         return SDL_OutOfMemory();
     }
-    SDL_zerop(_this->hidden);
-
-    strdesc = &_this->hidden->strdesc;
-
-    if (iscapture) {
-        open_capture_devices++;
-    } else {
-        open_playback_devices++;
-    }
-
-    new_open_devices = (SDL_AudioDevice **)SDL_realloc(open_devices, sizeof(open_devices[0]) * (num_open_devices + 1));
-    if (new_open_devices) {
-        open_devices = new_open_devices;
-        open_devices[num_open_devices++] = _this;
-    }
 
-#ifndef MACOSX_COREAUDIO
-    if (!update_audio_session(_this, SDL_TRUE, SDL_TRUE)) {
+    #ifndef MACOSX_COREAUDIO
+    if (!UpdateAudioSession(device, SDL_TRUE, SDL_TRUE)) {
         return -1;
     }
 
     /* Stop CoreAudio from doing expensive audio rate conversion */
     @autoreleasepool {
         AVAudioSession *session = [AVAudioSession sharedInstance];
-        [session setPreferredSampleRate:_this->spec.freq error:nil];
-        _this->spec.freq = (int)session.sampleRate;
-#if TARGET_OS_TV
-        if (iscapture) {
-            [session setPreferredInputNumberOfChannels:_this->spec.channels error:nil];
-            _this->spec.channels = session.preferredInputNumberOfChannels;
+        [session setPreferredSampleRate:device->spec.freq error:nil];
+        device->spec.freq = (int)session.sampleRate;
+        #if TARGET_OS_TV
+        if (device->iscapture) {
+            [session setPreferredInputNumberOfChannels:device->spec.channels error:nil];
+            device->spec.channels = session.preferredInputNumberOfChannels;
         } else {
-            [session setPreferredOutputNumberOfChannels:_this->spec.channels error:nil];
-            _this->spec.channels = session.preferredOutputNumberOfChannels;
+            [session setPreferredOutputNumberOfChannels:device->spec.channels error:nil];
+            device->spec.channels = session.preferredOutputNumberOfChannels;
         }
-#else
+        #else
         /* Calling setPreferredOutputNumberOfChannels seems to break audio output on iOS */
-#endif /* TARGET_OS_TV */
+        #endif /* TARGET_OS_TV */
     }
-#endif
+    #endif
 
     /* Setup a AudioStreamBasicDescription with the requested format */
-    SDL_zerop(strdesc);
+    AudioStreamBasicDescription *strdesc = &device->hidden->strdesc;
     strdesc->mFormatID = kAudioFormatLinearPCM;
     strdesc->mFormatFlags = kLinearPCMFormatFlagIsPacked;
-    strdesc->mChannelsPerFrame = _this->spec.channels;
-    strdesc->mSampleRate = _this->spec.freq;
+    strdesc->mChannelsPerFrame = device->spec.channels;
+    strdesc->mSampleRate = device->spec.freq;
     strdesc->mFramesPerPacket = 1;
 
-    closefmts = SDL_ClosestAudioFormats(_this->spec.format);
+    const SDL_AudioFormat *closefmts = SDL_ClosestAudioFormats(device->spec.format);
+    SDL_AudioFormat test_format;
     while ((test_format = *(closefmts++)) != 0) {
         /* CoreAudio handles most of SDL's formats natively. */
         switch (test_format) {
@@ -1091,7 +884,7 @@ static int COREAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
     if (!test_format) { /* shouldn't happen, but just in case... */
         return SDL_SetError("%s: Unsupported audio format", "coreaudio");
     }
-    _this->spec.format = test_format;
+    device->spec.format = test_format;
     strdesc->mBitsPerChannel = SDL_AUDIO_BITSIZE(test_format);
     if (SDL_AUDIO_ISBIGENDIAN(test_format)) {
         strdesc->mFormatFlags |= kLinearPCMFormatFlagIsBigEndian;
@@ -1107,175 +900,43 @@ static int COREAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
     strdesc->mBytesPerPacket = strdesc->mBytesPerFrame * strdesc->mFramesPerPacket;
 
 #ifdef MACOSX_COREAUDIO
-    if (!prepare_device(_this)) {
+    if (PrepareDevice(device) < 0) {
         return -1;
     }
 #endif
 
     /* This has to init in a new thread so it can get its own CFRunLoop. :/ */
-    _this->hidden->ready_semaphore = SDL_CreateSemaphore(0);
-    if (!_this->hidden->ready_semaphore) {
+    device->hidden->ready_semaphore = SDL_CreateSemaphore(0);
+    if (!device->hidden->ready_semaphore) {
         return -1; /* oh well. */
     }
 
-    _this->hidden->thread = SDL_CreateThreadInternal(audioqueue_thread, "AudioQueue thread", 512 * 1024, _this);
-    if (!_this->hidden->thread) {
+    char threadname[64];
+    SDL_GetAudioThreadName(device, threadname, sizeof(threadname));
+    device->hidden->thread = SDL_CreateThreadInternal(AudioQueueThreadEntry, threadname, 0, device);
+    if (!device->hidden->thread) {
         return -1;
     }
 
-    SDL_WaitSemaphore(_this->hidden->ready_semaphore);
-    SDL_DestroySemaphore(_this->hidden->ready_semaphore);
-    _this->hidden->ready_semaphore = NULL;
-
-    if ((_this->hidden->thread != NULL) && (_this->hidden->thread_error != NULL)) {
-        return SDL_SetError("%s", _this->hidden->thread_error);
-    }
-
-    return (_this->hidden->thread != NULL) ? 0 : -1;
-}
-
-#ifndef MACOSX_COREAUDIO
-static int COREAUDIO_GetDefaultAudioInfo(char **name, SDL_AudioSpec *spec, int iscapture)
-{
-    AVAudioSession *session = [AVAudioSession sharedInstance];
+    SDL_WaitSemaphore(device->hidden->ready_semaphore);
+    SDL_DestroySemaphore(device->hidden->ready_semaphore);
+    device->hidden->ready_semaphore = NULL;
 
-    if (name != NULL) {
-        *name = NULL;
+    if ((device->hidden->thread != NULL) && (device->hidden->thread_error != NULL)) {
+        SDL_WaitThread(device->hidden->thread, NULL);
+        device->hidden->thread = NULL;
+        return SDL_SetError("%s", device->hidden->thread_error);
     }
-    SDL_zerop(spec);
-    spec->freq = [session sampleRate];
-    spec->channels = [session outputNumberOfChannels];
-    return 0;
-}
-#else  /* MACOSX_COREAUDIO */
-static int COREAUDIO_GetDefaultAudioInfo(char **name, SDL_AudioSpec *spec, int iscapture)
-{
-    AudioDeviceID devid;
-    AudioBufferList *buflist;
-    OSStatus result;
-    UInt32 size;
-    CFStringRef cfstr;
-    char *devname;
-    int usable;
-    double sampleRate;
-    CFIndex len;
 
-    AudioObjectPropertyAddress addr = {
-        iscapture ? kAudioHardwarePropertyDefaultInputDevice
-                  : kAudioHardwarePropertyDefaultOutputDevice,
-        iscapture ? kAudioDevicePropertyScopeInput
-                  : kAudioDevicePropertyScopeOutput,
-        kAudioObjectPropertyElementMain
-    };
-    AudioObjectPropertyAddress nameaddr = {
-        kAudioObjectPropertyName,
-        iscapture ? kAudioDevicePropertyScopeInput
-                  : kAudioDevicePropertyScopeOutput,
-        kAudioObjectPropertyElementMain
-    };
-    AudioObjectPropertyAddress freqaddr = {
-        kAudioDevicePropertyNominalSampleRate,
-        iscapture ? kAudioDevicePropertyScopeInput
-                  : kAudioDevicePropertyScopeOutput,
-        kAudioObjectPropertyElementMain
-    };
-    AudioObjectPropertyAddress bufaddr = {
-        kAudioDevicePropertyStreamConfiguration,
-        iscapture ? kAudioDevicePropertyScopeInput : kAudioDevicePropertyScopeOutput,
-        kAudioObjectPropertyElementMain
-    };
-
-    /* Get the Device ID */
-    cfstr = NULL;
-    size = sizeof(AudioDeviceID);
-    result = AudioObjectGetPropertyData(kAudioObjectSystemObject, &addr,
-                                        0, NULL, &size, &devid);
-
-    if (result != noErr) {
-        return SDL_SetError("%s: Default Device ID not found", "coreaudio");
-    }
-
-    if (name != NULL) {
-        /* Use the Device ID to get the name */
-        size = sizeof(CFStringRef);
-        result = AudioObjectGetPropertyData(devid, &nameaddr, 0, NULL, &size, &cfstr);
-
-        if (result != noErr) {
-            return SDL_SetError("%s: Default Device Name not found", "coreaudio");
-        }
-
-        len = CFStringGetMaximumSizeForEncoding(CFStringGetLength(cfstr),
-                                                kCFStringEncodingUTF8);
-        devname = (char *)SDL_malloc(len + 1);
-        usable = ((devname != NULL) &&
-                  (CFStringGetCString(cfstr, devname, len + 1, kCFStringEncodingUTF8)));
-        CFRelease(cfstr);
-
-        if (usable) {
-            usable = 0;
-            len = SDL_strlen(devname);
-            /* Some devices have whitespace at the end...trim it. */
-            while ((len > 0) && (devname[len - 1] == ' ')) {
-                len--;
-                usable = (int)len;
-            }
-        }
-
-        if (usable) {
-            devname[len] = '\0';
-        }
-        *name = devname;
-    }
-
-    /* Uses the Device ID to get the spec */
-    SDL_zerop(spec);
-
-    sampleRate = 0;
-    size = sizeof(sampleRate);
-    result = AudioObjectGetPropertyData(devid, &freqaddr, 0, NULL, &size, &sampleRate);
-
-    if (result != noErr) {
-        return SDL_SetError("%s: Default Device Sample Rate not found", "coreaudio");
-    }
-
-    spec->freq = (int)sampleRate;
-
-    result = AudioObjectGetPropertyDataSize(devid, &bufaddr, 0, NULL, &size);
-    if (result != noErr) {
-        return SDL_SetError("%s: Default Device Data Size not found", "coreaudio");
-    }
-
-    buflist = (AudioBufferList *)SDL_malloc(size);
-    if (buflist == NULL) {
-        return SDL_SetError("%s: Default Device Buffer List not found", "coreaudio");
-    }
-
-    result = AudioObjectGetPropertyData(devid, &bufaddr, 0, NULL,
-                                        &size, buflist);
-
-    if (result == noErr) {
-        UInt32 j;
-        for (j = 0; j < buflist->mNumberBuffers; j++) {
-            spec->channels += buflist->mBuffers[j].mNumberChannels;
-        }
-    }
-
-    SDL_free(buflist);
-
-    if (spec->channels == 0) {
-        return SDL_SetError("%s: Default Device has no channels!", "coreaudio");
-    }
-
-    return 0;
+    return (device->hidden->thread != NULL) ? 0 : -1;
 }
-#endif /* MACOSX_COREAUDIO */
 
 static void COREAUDIO_Deinitialize(void)
 {
 #ifdef MACOSX_COREAUDIO
-    AudioObjectRemovePropertyListener(kAudioObjectSystemObject, &devlist_address, device_list_changed, NULL);
-    free_audio_device_list(&capture_devs);
-    free_audio_device_list(&output_devs);
+    AudioObjectRemovePropertyListener(kAudioObjectSystemObject, &devlist_address, DeviceListChangedNotification, NULL);
+    AudioObjectRemovePropertyListener(kAudioObjectSystemObject, &default_output_device_address, DefaultOutputDeviceChangedNotification, NULL);
+    AudioObjectRemovePropertyListener(kAudioObjectSystemObject, &default_input_device_address, DefaultInputDeviceChangedNotification, NULL);
 #endif
 }
 
@@ -1283,13 +944,16 @@ static SDL_bool COREAUDIO_Init(SDL_AudioDriverImpl *impl)
 {
     /* Set the function pointers */
     impl->OpenDevice = COREAUDIO_OpenDevice;
+    impl->PlayDevice = COREAUDIO_PlayDevice;
+    impl->GetDeviceBuf = COREAUDIO_GetDeviceBuf;
+    impl->CaptureFromDevice = COREAUDIO_CaptureFromDevice;
+    impl->FlushCapture = COREAUDIO_FlushCapture;
     impl->CloseDevice = COREAUDIO_CloseDevice;
     impl->Deinitialize = COREAUDIO_Deinitialize;
-    impl->GetDefaultAudioInfo = COREAUDIO_GetDefaultAudioInfo;
 
 #ifdef MACOSX_COREAUDIO
     impl->DetectDevices = COREAUDIO_DetectDevices;
-    AudioObjectAddPropertyListener(kAudioObjectSystemObject, &devlist_address, device_list_changed, NULL);
+    impl->FreeDeviceHandle = COREAUDIO_FreeDeviceHandle;
 #else
     impl->OnlyHasDefaultOutputDevice = SDL_TRUE;
     impl->OnlyHasDefaultCaptureDevice = SDL_TRUE;
@@ -1297,7 +961,6 @@ static SDL_bool COREAUDIO_Init(SDL_AudioDriverImpl *impl)
 
     impl->ProvidesOwnCallbackThread = SDL_TRUE;
     impl->HasCaptureSupport = SDL_TRUE;
-    impl->SupportsNonPow2Samples = SDL_TRUE;
 
     return SDL_TRUE; /* this audio target is available. */
 }

src/audio/directsound/SDL_directsound.c

@@ -22,34 +22,34 @@
 
 #ifdef SDL_AUDIO_DRIVER_DSOUND
 
-/* Allow access to a raw mixing buffer */
-
 #include "../SDL_audio_c.h"
 #include "SDL_directsound.h"
 #include <mmreg.h>
 #ifdef HAVE_MMDEVICEAPI_H
 #include "../../core/windows/SDL_immdevice.h"
-#endif /* HAVE_MMDEVICEAPI_H */
+#endif
 
 #ifndef WAVE_FORMAT_IEEE_FLOAT
 #define WAVE_FORMAT_IEEE_FLOAT 0x0003
 #endif
 
-/* For Vista+, we can enumerate DSound devices with IMMDevice */
+// For Vista+, we can enumerate DSound devices with IMMDevice
 #ifdef HAVE_MMDEVICEAPI_H
 static SDL_bool SupportsIMMDevice = SDL_FALSE;
-#endif /* HAVE_MMDEVICEAPI_H */
+#endif
 
-/* DirectX function pointers for audio */
+// DirectX function pointers for audio
 static void *DSoundDLL = NULL;
 typedef HRESULT(WINAPI *fnDirectSoundCreate8)(LPGUID, LPDIRECTSOUND *, LPUNKNOWN);
 typedef HRESULT(WINAPI *fnDirectSoundEnumerateW)(LPDSENUMCALLBACKW, LPVOID);
 typedef HRESULT(WINAPI *fnDirectSoundCaptureCreate8)(LPCGUID, LPDIRECTSOUNDCAPTURE8 *, LPUNKNOWN);
 typedef HRESULT(WINAPI *fnDirectSoundCaptureEnumerateW)(LPDSENUMCALLBACKW, LPVOID);
+typedef HRESULT(WINAPI *fnGetDeviceID)(LPCGUID, LPGUID);
 static fnDirectSoundCreate8 pDirectSoundCreate8 = NULL;
 static fnDirectSoundEnumerateW pDirectSoundEnumerateW = NULL;
 static fnDirectSoundCaptureCreate8 pDirectSoundCaptureCreate8 = NULL;
 static fnDirectSoundCaptureEnumerateW pDirectSoundCaptureEnumerateW = NULL;
+static fnGetDeviceID pGetDeviceID = NULL;
 
 static const GUID SDL_KSDATAFORMAT_SUBTYPE_PCM = { 0x00000001, 0x0000, 0x0010, { 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71 } };
 static const GUID SDL_KSDATAFORMAT_SUBTYPE_IEEE_FLOAT = { 0x00000003, 0x0000, 0x0010, { 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71 } };
@@ -60,6 +60,7 @@ static void DSOUND_Unload(void)
     pDirectSoundEnumerateW = NULL;
     pDirectSoundCaptureCreate8 = NULL;
     pDirectSoundCaptureEnumerateW = NULL;
+    pGetDeviceID = NULL;
 
     if (DSoundDLL != NULL) {
         SDL_UnloadObject(DSoundDLL);
@@ -77,18 +78,19 @@ static int DSOUND_Load(void)
     if (DSoundDLL == NULL) {
         SDL_SetError("DirectSound: failed to load DSOUND.DLL");
     } else {
-/* Now make sure we have DirectX 8 or better... */
+// Now make sure we have DirectX 8 or better...
 #define DSOUNDLOAD(f)                                  \
     {                                                  \
         p##f = (fn##f)SDL_LoadFunction(DSoundDLL, #f); \
         if (!p##f)                                     \
             loaded = 0;                                \
     }
-        loaded = 1; /* will reset if necessary. */
+        loaded = 1; // will reset if necessary.
         DSOUNDLOAD(DirectSoundCreate8);
         DSOUNDLOAD(DirectSoundEnumerateW);
         DSOUNDLOAD(DirectSoundCaptureCreate8);
         DSOUNDLOAD(DirectSoundCaptureEnumerateW);
+        DSOUNDLOAD(GetDeviceID);
 #undef DSOUNDLOAD
 
         if (!loaded) {
@@ -149,56 +151,81 @@ static int SetDSerror(const char *function, int code)
     return SDL_SetError("%s: %s (0x%x)", function, error, code);
 }
 
-static void DSOUND_FreeDeviceHandle(void *handle)
-{
-    SDL_free(handle);
-}
-
-static int DSOUND_GetDefaultAudioInfo(char **name, SDL_AudioSpec *spec, int iscapture)
+static void DSOUND_FreeDeviceHandle(SDL_AudioDevice *device)
 {
 #ifdef HAVE_MMDEVICEAPI_H
     if (SupportsIMMDevice) {
-        return SDL_IMMDevice_GetDefaultAudioInfo(name, spec, iscapture);
+        SDL_IMMDevice_FreeDeviceHandle(device);
+    } else
+#endif
+    {
+        SDL_free(device->handle);
     }
-#endif /* HAVE_MMDEVICEAPI_H */
-    return SDL_Unsupported();
 }
 
-static BOOL CALLBACK FindAllDevs(LPGUID guid, LPCWSTR desc, LPCWSTR module, LPVOID data)
+// FindAllDevs is presumably only used on WinXP; Vista and later can use IMMDevice for better results.
+typedef struct FindAllDevsData
 {
-    const int iscapture = (int)((size_t)data);
-    if (guid != NULL) { /* skip default device */
+    SDL_bool iscapture;
+    SDL_AudioDevice **default_device;
+    LPCGUID default_device_guid;
+} FindAllDevsData;
+
+static BOOL CALLBACK FindAllDevs(LPGUID guid, LPCWSTR desc, LPCWSTR module, LPVOID userdata)
+{
+    FindAllDevsData *data = (FindAllDevsData *) userdata;
+    if (guid != NULL) { // skip default device
         char *str = WIN_LookupAudioDeviceName(desc, guid);
         if (str != NULL) {
             LPGUID cpyguid = (LPGUID)SDL_malloc(sizeof(GUID));
-            SDL_memcpy(cpyguid, guid, sizeof(GUID));
-
-            /* Note that spec is NULL, because we are required to connect to the
-             * device before getting the channel mask and output format, making
-             * this information inaccessible at enumeration time
-             */
-            SDL_AddAudioDevice(iscapture, str, NULL, cpyguid);
-            SDL_free(str); /* addfn() makes a copy of this string. */
+            if (cpyguid) {
+                SDL_memcpy(cpyguid, guid, sizeof(GUID));
+
+                /* Note that spec is NULL, because we are required to connect to the
+                 * device before getting the channel mask and output format, making
+                 * this information inaccessible at enumeration time
+                 */
+                SDL_AudioDevice *device = SDL_AddAudioDevice(data->iscapture, str, NULL, cpyguid);
+                if (device && data->default_device && data->default_device_guid) {
+                    if (SDL_memcmp(cpyguid, data->default_device_guid, sizeof (GUID)) == 0) {
+                        *data->default_device = device;
+                    }
+                }
+            }
+            SDL_free(str); // SDL_AddAudioDevice() makes a copy of this string.
         }
     }
-    return TRUE; /* keep enumerating. */
+    return TRUE; // keep enumerating.
 }
 
-static void DSOUND_DetectDevices(void)
+static void DSOUND_DetectDevices(SDL_AudioDevice **default_output, SDL_AudioDevice **default_capture)
 {
 #ifdef HAVE_MMDEVICEAPI_H
     if (SupportsIMMDevice) {
-        SDL_IMMDevice_EnumerateEndpoints(SDL_TRUE);
-    } else {
-#endif /* HAVE_MMDEVICEAPI_H */
-        pDirectSoundCaptureEnumerateW(FindAllDevs, (void *)((size_t)1));
-        pDirectSoundEnumerateW(FindAllDevs, (void *)((size_t)0));
-#ifdef HAVE_MMDEVICEAPI_H
+        SDL_IMMDevice_EnumerateEndpoints(default_output, default_capture);
+    } else
+#endif
+    {
+        // Without IMMDevice, you can enumerate devices and figure out the default devices,
+        //  but you won't get device hotplug or default device change notifications. But this is
+        //  only for WinXP; Windows Vista and later should be using IMMDevice.
+        FindAllDevsData data;
+        GUID guid;
+
+        data.iscapture = SDL_TRUE;
+        data.default_device = default_capture;
+        data.default_device_guid = (pGetDeviceID(&DSDEVID_DefaultCapture, &guid) == DS_OK) ? &guid : NULL;
+        pDirectSoundCaptureEnumerateW(FindAllDevs, &data);
+
+        data.iscapture = SDL_FALSE;
+        data.default_device = default_output;
+        data.default_device_guid = (pGetDeviceID(&DSDEVID_DefaultPlayback, &guid) == DS_OK) ? &guid : NULL;
+        pDirectSoundEnumerateW(FindAllDevs, &data);
     }
-#endif /* HAVE_MMDEVICEAPI_H*/
+
 }
 
-static void DSOUND_WaitDevice(SDL_AudioDevice *_this)
+static void DSOUND_WaitDevice(SDL_AudioDevice *device)
 {
     DWORD status = 0;
     DWORD cursor = 0;
@@ -208,11 +235,11 @@ static void DSOUND_WaitDevice(SDL_AudioDevice *_this)
     /* Semi-busy wait, since we have no way of getting play notification
        on a primary mixing buffer located in hardware (DirectX 5.0)
      */
-    result = IDirectSoundBuffer_GetCurrentPosition(_this->hidden->mixbuf,
+    result = IDirectSoundBuffer_GetCurrentPosition(device->hidden->mixbuf,
                                                    &junk, &cursor);
     if (result != DS_OK) {
         if (result == DSERR_BUFFERLOST) {
-            IDirectSoundBuffer_Restore(_this->hidden->mixbuf);
+            IDirectSoundBuffer_Restore(device->hidden->mixbuf);
         }
 #ifdef DEBUG_SOUND
         SetDSerror("DirectSound GetCurrentPosition", result);
@@ -220,21 +247,24 @@ static void DSOUND_WaitDevice(SDL_AudioDevice *_this)
         return;
     }
 
-    while ((cursor / _this->spec.size) == _this->hidden->lastchunk) {
-        /* FIXME: find out how much time is left and sleep that long */
+    while ((cursor / device->buffer_size) == device->hidden->lastchunk) {
+        if (SDL_AtomicGet(&device->shutdown)) {
+            return;
+        }
+
         SDL_Delay(1);
 
-        /* Try to restore a lost sound buffer */
-        IDirectSoundBuffer_GetStatus(_this->hidden->mixbuf, &status);
+        // Try to restore a lost sound buffer
+        IDirectSoundBuffer_GetStatus(device->hidden->mixbuf, &status);
         if (status & DSBSTATUS_BUFFERLOST) {
-            IDirectSoundBuffer_Restore(_this->hidden->mixbuf);
-            IDirectSoundBuffer_GetStatus(_this->hidden->mixbuf, &status);
+            IDirectSoundBuffer_Restore(device->hidden->mixbuf);
+            IDirectSoundBuffer_GetStatus(device->hidden->mixbuf, &status);
             if (status & DSBSTATUS_BUFFERLOST) {
                 break;
             }
         }
         if (!(status & DSBSTATUS_PLAYING)) {
-            result = IDirectSoundBuffer_Play(_this->hidden->mixbuf, 0, 0,
+            result = IDirectSoundBuffer_Play(device->hidden->mixbuf, 0, 0,
                                              DSBPLAY_LOOPING);
             if (result == DS_OK) {
                 continue;
@@ -245,8 +275,8 @@ static void DSOUND_WaitDevice(SDL_AudioDevice *_this)
             return;
         }
 
-        /* Find out where we are playing */
-        result = IDirectSoundBuffer_GetCurrentPosition(_this->hidden->mixbuf,
+        // Find out where we are playing
+        result = IDirectSoundBuffer_GetCurrentPosition(device->hidden->mixbuf,
                                                        &junk, &cursor);
         if (result != DS_OK) {
             SetDSerror("DirectSound GetCurrentPosition", result);
@@ -255,102 +285,100 @@ static void DSOUND_WaitDevice(SDL_AudioDevice *_this)
     }
 }
 
-static void DSOUND_PlayDevice(SDL_AudioDevice *_this)
+static void DSOUND_PlayDevice(SDL_AudioDevice *device, const Uint8 *buffer, int buflen)
 {
-    /* Unlock the buffer, allowing it to play */
-    if (_this->hidden->locked_buf) {
-        IDirectSoundBuffer_Unlock(_this->hidden->mixbuf,
-                                  _this->hidden->locked_buf,
-                                  _this->spec.size, NULL, 0);
-    }
+    // Unlock the buffer, allowing it to play
+    SDL_assert(buflen == device->buffer_size);
+    IDirectSoundBuffer_Unlock(device->hidden->mixbuf, (LPVOID) buffer, buflen, NULL, 0);
 }
 
-static Uint8 *DSOUND_GetDeviceBuf(SDL_AudioDevice *_this)
+static Uint8 *DSOUND_GetDeviceBuf(SDL_AudioDevice *device, int *buffer_size)
 {
     DWORD cursor = 0;
     DWORD junk = 0;
     HRESULT result = DS_OK;
-    DWORD rawlen = 0;
 
-    /* Figure out which blocks to fill next */
-    _this->hidden->locked_buf = NULL;
-    result = IDirectSoundBuffer_GetCurrentPosition(_this->hidden->mixbuf,
+    SDL_assert(*buffer_size == device->buffer_size);
+
+    // Figure out which blocks to fill next
+    device->hidden->locked_buf = NULL;
+    result = IDirectSoundBuffer_GetCurrentPosition(device->hidden->mixbuf,
                                                    &junk, &cursor);
     if (result == DSERR_BUFFERLOST) {
-        IDirectSoundBuffer_Restore(_this->hidden->mixbuf);
-        result = IDirectSoundBuffer_GetCurrentPosition(_this->hidden->mixbuf,
+        IDirectSoundBuffer_Restore(device->hidden->mixbuf);
+        result = IDirectSoundBuffer_GetCurrentPosition(device->hidden->mixbuf,
                                                        &junk, &cursor);
     }
     if (result != DS_OK) {
         SetDSerror("DirectSound GetCurrentPosition", result);
         return NULL;
     }
-    cursor /= _this->spec.size;
+    cursor /= device->buffer_size;
 #ifdef DEBUG_SOUND
-    /* Detect audio dropouts */
+    // Detect audio dropouts
     {
         DWORD spot = cursor;
-        if (spot < _this->hidden->lastchunk) {
-            spot += _this->hidden->num_buffers;
+        if (spot < device->hidden->lastchunk) {
+            spot += device->hidden->num_buffers;
         }
-        if (spot > _this->hidden->lastchunk + 1) {
+        if (spot > device->hidden->lastchunk + 1) {
             fprintf(stderr, "Audio dropout, missed %d fragments\n",
-                    (spot - (_this->hidden->lastchunk + 1)));
+                    (spot - (device->hidden->lastchunk + 1)));
         }
     }
 #endif
-    _this->hidden->lastchunk = cursor;
-    cursor = (cursor + 1) % _this->hidden->num_buffers;
-    cursor *= _this->spec.size;
-
-    /* Lock the audio buffer */
-    result = IDirectSoundBuffer_Lock(_this->hidden->mixbuf, cursor,
-                                     _this->spec.size,
-                                     (LPVOID *)&_this->hidden->locked_buf,
+    device->hidden->lastchunk = cursor;
+    cursor = (cursor + 1) % device->hidden->num_buffers;
+    cursor *= device->buffer_size;
+
+    // Lock the audio buffer
+    DWORD rawlen = 0;
+    result = IDirectSoundBuffer_Lock(device->hidden->mixbuf, cursor,
+                                     device->buffer_size,
+                                     (LPVOID *)&device->hidden->locked_buf,
                                      &rawlen, NULL, &junk, 0);
     if (result == DSERR_BUFFERLOST) {
-        IDirectSoundBuffer_Restore(_this->hidden->mixbuf);
-        result = IDirectSoundBuffer_Lock(_this->hidden->mixbuf, cursor,
-                                         _this->spec.size,
-                                         (LPVOID *)&_this->hidden->locked_buf, &rawlen, NULL,
+        IDirectSoundBuffer_Restore(device->hidden->mixbuf);
+        result = IDirectSoundBuffer_Lock(device->hidden->mixbuf, cursor,
+                                         device->buffer_size,
+                                         (LPVOID *)&device->hidden->locked_buf, &rawlen, NULL,
                                          &junk, 0);
     }
     if (result != DS_OK) {
         SetDSerror("DirectSound Lock", result);
         return NULL;
     }
-    return _this->hidden->locked_buf;
+    return device->hidden->locked_buf;
 }
 
-static int DSOUND_CaptureFromDevice(SDL_AudioDevice *_this, void *buffer, int buflen)
+static void DSOUND_WaitCaptureDevice(SDL_AudioDevice *device)
 {
-    struct SDL_PrivateAudioData *h = _this->hidden;
-    DWORD junk, cursor, ptr1len, ptr2len;
-    VOID *ptr1, *ptr2;
-
-    SDL_assert((Uint32)buflen == _this->spec.size);
-
-    while (SDL_TRUE) {
-        if (SDL_AtomicGet(&_this->shutdown)) { /* in case the buffer froze... */
-            SDL_memset(buffer, _this->spec.silence, buflen);
-            return buflen;
-        }
-
+    struct SDL_PrivateAudioData *h = device->hidden;
+    while (!SDL_AtomicGet(&device->shutdown)) {
+        DWORD junk, cursor;
         if (IDirectSoundCaptureBuffer_GetCurrentPosition(h->capturebuf, &junk, &cursor) != DS_OK) {
-            return -1;
-        }
-        if ((cursor / _this->spec.size) == h->lastchunk) {
-            SDL_Delay(1); /* FIXME: find out how much time is left and sleep that long */
-        } else {
-            break;
+            SDL_AudioDeviceDisconnected(device);
+            return;
+        } else if ((cursor / device->buffer_size) != h->lastchunk) {
+            return;
         }
+        SDL_Delay(1);
     }
+}
 
-    if (IDirectSoundCaptureBuffer_Lock(h->capturebuf, h->lastchunk * _this->spec.size, _this->spec.size, &ptr1, &ptr1len, &ptr2, &ptr2len, 0) != DS_OK) {
+static int DSOUND_CaptureFromDevice(SDL_AudioDevice *device, void *buffer, int buflen)
+{
+    struct SDL_PrivateAudioData *h = device->hidden;
+    DWORD ptr1len, ptr2len;
+    VOID *ptr1, *ptr2;
+
+    SDL_assert(buflen == device->buffer_size);
+
+    if (IDirectSoundCaptureBuffer_Lock(h->capturebuf, h->lastchunk * buflen, buflen, &ptr1, &ptr1len, &ptr2, &ptr2len, 0) != DS_OK) {
         return -1;
     }
 
-    SDL_assert(ptr1len == _this->spec.size);
+    SDL_assert(ptr1len == buflen);
     SDL_assert(ptr2 == NULL);
     SDL_assert(ptr2len == 0);
 
@@ -362,51 +390,54 @@ static int DSOUND_CaptureFromDevice(SDL_AudioDevice *_this, void *buffer, int bu
 
     h->lastchunk = (h->lastchunk + 1) % h->num_buffers;
 
-    return ptr1len;
+    return (int) ptr1len;
 }
 
-static void DSOUND_FlushCapture(SDL_AudioDevice *_this)
+static void DSOUND_FlushCapture(SDL_AudioDevice *device)
 {
-    struct SDL_PrivateAudioData *h = _this->hidden;
+    struct SDL_PrivateAudioData *h = device->hidden;
     DWORD junk, cursor;
     if (IDirectSoundCaptureBuffer_GetCurrentPosition(h->capturebuf, &junk, &cursor) == DS_OK) {
-        h->lastchunk = cursor / _this->spec.size;
+        h->lastchunk = cursor / device->buffer_size;
     }
 }
 
-static void DSOUND_CloseDevice(SDL_AudioDevice *_this)
+static void DSOUND_CloseDevice(SDL_AudioDevice *device)
 {
-    if (_this->hidden->mixbuf != NULL) {
-        IDirectSoundBuffer_Stop(_this->hidden->mixbuf);
-        IDirectSoundBuffer_Release(_this->hidden->mixbuf);
-    }
-    if (_this->hidden->sound != NULL) {
-        IDirectSound_Release(_this->hidden->sound);
-    }
-    if (_this->hidden->capturebuf != NULL) {
-        IDirectSoundCaptureBuffer_Stop(_this->hidden->capturebuf);
-        IDirectSoundCaptureBuffer_Release(_this->hidden->capturebuf);
-    }
-    if (_this->hidden->capture != NULL) {
-        IDirectSoundCapture_Release(_this->hidden->capture);
+    if (device->hidden) {
+        if (device->hidden->mixbuf != NULL) {
+            IDirectSoundBuffer_Stop(device->hidden->mixbuf);
+            IDirectSoundBuffer_Release(device->hidden->mixbuf);
+        }
+        if (device->hidden->sound != NULL) {
+            IDirectSound_Release(device->hidden->sound);
+        }
+        if (device->hidden->capturebuf != NULL) {
+            IDirectSoundCaptureBuffer_Stop(device->hidden->capturebuf);
+            IDirectSoundCaptureBuffer_Release(device->hidden->capturebuf);
+        }
+        if (device->hidden->capture != NULL) {
+            IDirectSoundCapture_Release(device->hidden->capture);
+        }
+        SDL_free(device->hidden);
+        device->hidden = NULL;
     }
-    SDL_free(_this->hidden);
 }
 
 /* This function tries to create a secondary audio buffer, and returns the
    number of audio chunks available in the created buffer. This is for
    playback devices, not capture.
 */
-static int CreateSecondary(SDL_AudioDevice *_this, const DWORD bufsize, WAVEFORMATEX *wfmt)
+static int CreateSecondary(SDL_AudioDevice *device, const DWORD bufsize, WAVEFORMATEX *wfmt)
 {
-    LPDIRECTSOUND sndObj = _this->hidden->sound;
-    LPDIRECTSOUNDBUFFER *sndbuf = &_this->hidden->mixbuf;
+    LPDIRECTSOUND sndObj = device->hidden->sound;
+    LPDIRECTSOUNDBUFFER *sndbuf = &device->hidden->mixbuf;
     HRESULT result = DS_OK;
     DSBUFFERDESC format;
     LPVOID pvAudioPtr1, pvAudioPtr2;
     DWORD dwAudioBytes1, dwAudioBytes2;
 
-    /* Try to create the secondary buffer */
+    // Try to create the secondary buffer
     SDL_zero(format);
     format.dwSize = sizeof(format);
     format.dwFlags = DSBCAPS_GETCURRENTPOSITION2;
@@ -419,30 +450,29 @@ static int CreateSecondary(SDL_AudioDevice *_this, const DWORD bufsize, WAVEFORM
     }
     IDirectSoundBuffer_SetFormat(*sndbuf, wfmt);
 
-    /* Silence the initial audio buffer */
+    // Silence the initial audio buffer
     result = IDirectSoundBuffer_Lock(*sndbuf, 0, format.dwBufferBytes,
                                      (LPVOID *)&pvAudioPtr1, &dwAudioBytes1,
                                      (LPVOID *)&pvAudioPtr2, &dwAudioBytes2,
                                      DSBLOCK_ENTIREBUFFER);
     if (result == DS_OK) {
-        SDL_memset(pvAudioPtr1, _this->spec.silence, dwAudioBytes1);
+        SDL_memset(pvAudioPtr1, device->silence_value, dwAudioBytes1);
         IDirectSoundBuffer_Unlock(*sndbuf,
                                   (LPVOID)pvAudioPtr1, dwAudioBytes1,
                                   (LPVOID)pvAudioPtr2, dwAudioBytes2);
     }
 
-    /* We're ready to go */
-    return 0;
+    return 0;  // We're ready to go
 }
 
 /* This function tries to create a capture buffer, and returns the
    number of audio chunks available in the created buffer. This is for
    capture devices, not playback.
 */
-static int CreateCaptureBuffer(SDL_AudioDevice *_this, const DWORD bufsize, WAVEFORMATEX *wfmt)
+static int CreateCaptureBuffer(SDL_AudioDevice *device, const DWORD bufsize, WAVEFORMATEX *wfmt)
 {
-    LPDIRECTSOUNDCAPTURE capture = _this->hidden->capture;
-    LPDIRECTSOUNDCAPTUREBUFFER *capturebuf = &_this->hidden->capturebuf;
+    LPDIRECTSOUNDCAPTURE capture = device->hidden->capture;
+    LPDIRECTSOUNDCAPTUREBUFFER *capturebuf = &device->hidden->capturebuf;
     DSCBUFFERDESC format;
     HRESULT result;
 
@@ -464,7 +494,7 @@ static int CreateCaptureBuffer(SDL_AudioDevice *_this, const DWORD bufsize, WAVE
     }
 
 #if 0
-    /* presumably this starts at zero, but just in case... */
+    // presumably this starts at zero, but just in case...
     result = IDirectSoundCaptureBuffer_GetCurrentPosition(*capturebuf, &junk, &cursor);
     if (result != DS_OK) {
         IDirectSoundCaptureBuffer_Stop(*capturebuf);
@@ -472,42 +502,45 @@ static int CreateCaptureBuffer(SDL_AudioDevice *_this, const DWORD bufsize, WAVE
         return SetDSerror("DirectSound GetCurrentPosition", result);
     }
 
-    _this->hidden->lastchunk = cursor / _this->spec.size;
+    device->hidden->lastchunk = cursor / device->buffer_size;
 #endif
 
     return 0;
 }
 
-static int DSOUND_OpenDevice(SDL_AudioDevice *_this, const char *devname)
+static int DSOUND_OpenDevice(SDL_AudioDevice *device)
 {
-    const DWORD numchunks = 8;
-    HRESULT result;
-    SDL_bool tried_format = SDL_FALSE;
-    SDL_bool iscapture = _this->iscapture;
-    SDL_AudioFormat test_format;
-    const SDL_AudioFormat *closefmts;
-    LPGUID guid = (LPGUID)_this->handle;
-    DWORD bufsize;
-
-    /* Initialize all variables that we clean on shutdown */
-    _this->hidden = (struct SDL_PrivateAudioData *)SDL_malloc(sizeof(*_this->hidden));
-    if (_this->hidden == NULL) {
+    // Initialize all variables that we clean on shutdown
+    device->hidden = (struct SDL_PrivateAudioData *)SDL_calloc(1, sizeof(*device->hidden));
+    if (device->hidden == NULL) {
         return SDL_OutOfMemory();
     }
-    SDL_zerop(_this->hidden);
 
-    /* Open the audio device */
-    if (iscapture) {
-        result = pDirectSoundCaptureCreate8(guid, &_this->hidden->capture, NULL);
+    // Open the audio device
+    LPGUID guid;
+#ifdef HAVE_MMDEVICEAPI_H
+    if (SupportsIMMDevice) {
+        guid = SDL_IMMDevice_GetDirectSoundGUID(device);
+    } else
+#endif
+    {
+        guid = (LPGUID) device->handle;
+    }
+
+    SDL_assert(guid != NULL);
+
+    HRESULT result;
+    if (device->iscapture) {
+        result = pDirectSoundCaptureCreate8(guid, &device->hidden->capture, NULL);
         if (result != DS_OK) {
             return SetDSerror("DirectSoundCaptureCreate8", result);
         }
     } else {
-        result = pDirectSoundCreate8(guid, &_this->hidden->sound, NULL);
+        result = pDirectSoundCreate8(guid, &device->hidden->sound, NULL);
         if (result != DS_OK) {
             return SetDSerror("DirectSoundCreate8", result);
         }
-        result = IDirectSound_SetCooperativeLevel(_this->hidden->sound,
+        result = IDirectSound_SetCooperativeLevel(device->hidden->sound,
                                                   GetDesktopWindow(),
                                                   DSSCL_NORMAL);
         if (result != DS_OK) {
@@ -515,7 +548,10 @@ static int DSOUND_OpenDevice(SDL_AudioDevice *_this, const char *devname)
         }
     }
 
-    closefmts = SDL_ClosestAudioFormats(_this->spec.format);
+    const DWORD numchunks = 8;
+    SDL_bool tried_format = SDL_FALSE;
+    SDL_AudioFormat test_format;
+    const SDL_AudioFormat *closefmts = SDL_ClosestAudioFormats(device->spec.format);
     while ((test_format = *(closefmts++)) != 0) {
         switch (test_format) {
         case SDL_AUDIO_U8:
@@ -524,69 +560,68 @@ static int DSOUND_OpenDevice(SDL_AudioDevice *_this, const char *devname)
         case SDL_AUDIO_F32:
             tried_format = SDL_TRUE;
 
-            _this->spec.format = test_format;
+            device->spec.format = test_format;
 
-            /* Update the fragment size as size in bytes */
-            SDL_CalculateAudioSpec(&_this->spec);
+            // Update the fragment size as size in bytes
+            SDL_UpdatedAudioDeviceFormat(device);
 
-            bufsize = numchunks * _this->spec.size;
+            const DWORD bufsize = numchunks * device->buffer_size;
             if ((bufsize < DSBSIZE_MIN) || (bufsize > DSBSIZE_MAX)) {
                 SDL_SetError("Sound buffer size must be between %d and %d",
                              (int)((DSBSIZE_MIN < numchunks) ? 1 : DSBSIZE_MIN / numchunks),
                              (int)(DSBSIZE_MAX / numchunks));
             } else {
-                int rc;
                 WAVEFORMATEXTENSIBLE wfmt;
                 SDL_zero(wfmt);
-                if (_this->spec.channels > 2) {
+                if (device->spec.channels > 2) {
                     wfmt.Format.wFormatTag = WAVE_FORMAT_EXTENSIBLE;
                     wfmt.Format.cbSize = sizeof(wfmt) - sizeof(WAVEFORMATEX);
 
-                    if (SDL_AUDIO_ISFLOAT(_this->spec.format)) {
+                    if (SDL_AUDIO_ISFLOAT(device->spec.format)) {
                         SDL_memcpy(&wfmt.SubFormat, &SDL_KSDATAFORMAT_SUBTYPE_IEEE_FLOAT, sizeof(GUID));
                     } else {
                         SDL_memcpy(&wfmt.SubFormat, &SDL_KSDATAFORMAT_SUBTYPE_PCM, sizeof(GUID));
                     }
-                    wfmt.Samples.wValidBitsPerSample = SDL_AUDIO_BITSIZE(_this->spec.format);
+                    wfmt.Samples.wValidBitsPerSample = SDL_AUDIO_BITSIZE(device->spec.format);
 
-                    switch (_this->spec.channels) {
-                    case 3: /* 3.0 (or 2.1) */
+                    switch (device->spec.channels) {
+                    case 3: // 3.0 (or 2.1)
                         wfmt.dwChannelMask = SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT | SPEAKER_FRONT_CENTER;
                         break;
-                    case 4: /* 4.0 */
+                    case 4: // 4.0
                         wfmt.dwChannelMask = SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT | SPEAKER_BACK_LEFT | SPEAKER_BACK_RIGHT;
                         break;
-                    case 5: /* 5.0 (or 4.1) */
+                    case 5: // 5.0 (or 4.1)
                         wfmt.dwChannelMask = SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT | SPEAKER_FRONT_CENTER | SPEAKER_BACK_LEFT | SPEAKER_BACK_RIGHT;
                         break;
-                    case 6: /* 5.1 */
+                    case 6: // 5.1
                         wfmt.dwChannelMask = SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT | SPEAKER_FRONT_CENTER | SPEAKER_LOW_FREQUENCY | SPEAKER_BACK_LEFT | SPEAKER_BACK_RIGHT;
                         break;
-                    case 7: /* 6.1 */
+                    case 7: // 6.1
                         wfmt.dwChannelMask = SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT | SPEAKER_FRONT_CENTER | SPEAKER_LOW_FREQUENCY | SPEAKER_BACK_LEFT | SPEAKER_BACK_RIGHT | SPEAKER_BACK_CENTER;
                         break;
-                    case 8: /* 7.1 */
+                    case 8: // 7.1
                         wfmt.dwChannelMask = SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT | SPEAKER_FRONT_CENTER | SPEAKER_LOW_FREQUENCY | SPEAKER_BACK_LEFT | SPEAKER_BACK_RIGHT | SPEAKER_SIDE_LEFT | SPEAKER_SIDE_RIGHT;
                         break;
                     default:
                         SDL_assert(0 && "Unsupported channel count!");
                         break;
                     }
-                } else if (SDL_AUDIO_ISFLOAT(_this->spec.format)) {
+                } else if (SDL_AUDIO_ISFLOAT(device->spec.format)) {
                     wfmt.Format.wFormatTag = WAVE_FORMAT_IEEE_FLOAT;
                 } else {
                     wfmt.Format.wFormatTag = WAVE_FORMAT_PCM;
                 }
 
-                wfmt.Format.wBitsPerSample = SDL_AUDIO_BITSIZE(_this->spec.format);
-                wfmt.Format.nChannels = _this->spec.channels;
-                wfmt.Format.nSamplesPerSec = _this->spec.freq;
+                wfmt.Format.wBitsPerSample = SDL_AUDIO_BITSIZE(device->spec.format);
+                wfmt.Format.nChannels = device->spec.channels;
+                wfmt.Format.nSamplesPerSec = device->spec.freq;
                 wfmt.Format.nBlockAlign = wfmt.Format.nChannels * (wfmt.Format.wBitsPerSample / 8);
                 wfmt.Format.nAvgBytesPerSec = wfmt.Format.nSamplesPerSec * wfmt.Format.nBlockAlign;
 
-                rc = iscapture ? CreateCaptureBuffer(_this, bufsize, (WAVEFORMATEX *)&wfmt) : CreateSecondary(_this, bufsize, (WAVEFORMATEX *)&wfmt);
+                const int rc = device->iscapture ? CreateCaptureBuffer(device, bufsize, (WAVEFORMATEX *)&wfmt) : CreateSecondary(device, bufsize, (WAVEFORMATEX *)&wfmt);
                 if (rc == 0) {
-                    _this->hidden->num_buffers = numchunks;
+                    device->hidden->num_buffers = numchunks;
                     break;
                 }
             }
@@ -599,14 +634,14 @@ static int DSOUND_OpenDevice(SDL_AudioDevice *_this, const char *devname)
 
     if (!test_format) {
         if (tried_format) {
-            return -1; /* CreateSecondary() should have called SDL_SetError(). */
+            return -1; // CreateSecondary() should have called SDL_SetError().
         }
         return SDL_SetError("%s: Unsupported audio format", "directsound");
     }
 
-    /* Playback buffers will auto-start playing in DSOUND_WaitDevice() */
+    // Playback buffers will auto-start playing in DSOUND_WaitDevice()
 
-    return 0; /* good to go. */
+    return 0; // good to go.
 }
 
 static void DSOUND_Deinitialize(void)
@@ -616,7 +651,7 @@ static void DSOUND_Deinitialize(void)
         SDL_IMMDevice_Quit();
         SupportsIMMDevice = SDL_FALSE;
     }
-#endif /* HAVE_MMDEVICEAPI_H */
+#endif
     DSOUND_Unload();
 }
 
@@ -628,29 +663,27 @@ static SDL_bool DSOUND_Init(SDL_AudioDriverImpl *impl)
 
 #ifdef HAVE_MMDEVICEAPI_H
     SupportsIMMDevice = !(SDL_IMMDevice_Init() < 0);
-#endif /* HAVE_MMDEVICEAPI_H */
+#endif
 
-    /* Set the function pointers */
     impl->DetectDevices = DSOUND_DetectDevices;
     impl->OpenDevice = DSOUND_OpenDevice;
     impl->PlayDevice = DSOUND_PlayDevice;
     impl->WaitDevice = DSOUND_WaitDevice;
     impl->GetDeviceBuf = DSOUND_GetDeviceBuf;
+    impl->WaitCaptureDevice = DSOUND_WaitCaptureDevice;
     impl->CaptureFromDevice = DSOUND_CaptureFromDevice;
     impl->FlushCapture = DSOUND_FlushCapture;
     impl->CloseDevice = DSOUND_CloseDevice;
     impl->FreeDeviceHandle = DSOUND_FreeDeviceHandle;
     impl->Deinitialize = DSOUND_Deinitialize;
-    impl->GetDefaultAudioInfo = DSOUND_GetDefaultAudioInfo;
 
     impl->HasCaptureSupport = SDL_TRUE;
-    impl->SupportsNonPow2Samples = SDL_TRUE;
 
-    return SDL_TRUE; /* this audio target is available. */
+    return SDL_TRUE;
 }
 
 AudioBootStrap DSOUND_bootstrap = {
     "directsound", "DirectSound", DSOUND_Init, SDL_FALSE
 };
 
-#endif /* SDL_AUDIO_DRIVER_DSOUND */
+#endif // SDL_AUDIO_DRIVER_DSOUND

src/audio/directsound/SDL_directsound.h

@@ -27,9 +27,10 @@
 
 #include "../SDL_sysaudio.h"
 
-/* The DirectSound objects */
+// The DirectSound objects
 struct SDL_PrivateAudioData
 {
+    // !!! FIXME: make this a union with capture/playback sections?
     LPDIRECTSOUND sound;
     LPDIRECTSOUNDBUFFER mixbuf;
     LPDIRECTSOUNDCAPTURE capture;
@@ -39,4 +40,4 @@ struct SDL_PrivateAudioData
     Uint8 *locked_buf;
 };
 
-#endif /* SDL_directsound_h_ */
+#endif // SDL_directsound_h_

src/audio/disk/SDL_diskaudio.c

@@ -22,171 +22,151 @@
 
 #ifdef SDL_AUDIO_DRIVER_DISK
 
-/* Output raw audio data to a file. */
-
-#ifdef HAVE_STDIO_H
-#include <stdio.h>
-#endif
+// Output raw audio data to a file.
 
 #include "../SDL_audio_c.h"
 #include "SDL_diskaudio.h"
 
-/* !!! FIXME: these should be SDL hints, not environment variables. */
-/* environment variables and defaults. */
+// !!! FIXME: these should be SDL hints, not environment variables.
+// environment variables and defaults.
 #define DISKENVR_OUTFILE    "SDL_DISKAUDIOFILE"
 #define DISKDEFAULT_OUTFILE "sdlaudio.raw"
 #define DISKENVR_INFILE     "SDL_DISKAUDIOFILEIN"
 #define DISKDEFAULT_INFILE  "sdlaudio-in.raw"
 #define DISKENVR_IODELAY    "SDL_DISKAUDIODELAY"
 
-/* This function waits until it is possible to write a full sound buffer */
-static void DISKAUDIO_WaitDevice(SDL_AudioDevice *_this)
+static void DISKAUDIO_WaitDevice(SDL_AudioDevice *device)
 {
-    SDL_Delay(_this->hidden->io_delay);
+    SDL_Delay(device->hidden->io_delay);
 }
 
-static void DISKAUDIO_PlayDevice(SDL_AudioDevice *_this)
+static void DISKAUDIO_PlayDevice(SDL_AudioDevice *device, const Uint8 *buffer, int buffer_size)
 {
-    const Sint64 written = SDL_RWwrite(_this->hidden->io,
-                                       _this->hidden->mixbuf,
-                                       _this->spec.size);
-
-    /* If we couldn't write, assume fatal error for now */
-    if (written != _this->spec.size) {
-        SDL_OpenedAudioDeviceDisconnected(_this);
+    const Sint64 written = SDL_RWwrite(device->hidden->io, buffer, buffer_size);
+    if (written != buffer_size) { // If we couldn't write, assume fatal error for now
+        SDL_AudioDeviceDisconnected(device);
     }
 #ifdef DEBUG_AUDIO
-    fprintf(stderr, "Wrote %d bytes of audio data\n", (int) written);
+    SDL_Log("DISKAUDIO: Wrote %d bytes of audio data", (int) written);
 #endif
 }
 
-static Uint8 *DISKAUDIO_GetDeviceBuf(SDL_AudioDevice *_this)
+static Uint8 *DISKAUDIO_GetDeviceBuf(SDL_AudioDevice *device, int *buffer_size)
 {
-    return _this->hidden->mixbuf;
+    return device->hidden->mixbuf;
 }
 
-static int DISKAUDIO_CaptureFromDevice(SDL_AudioDevice *_this, void *buffer, int buflen)
+static int DISKAUDIO_CaptureFromDevice(SDL_AudioDevice *device, void *buffer, int buflen)
 {
-    struct SDL_PrivateAudioData *h = _this->hidden;
+    struct SDL_PrivateAudioData *h = device->hidden;
     const int origbuflen = buflen;
 
-    SDL_Delay(h->io_delay);
-
     if (h->io) {
         const int br = (int) SDL_RWread(h->io, buffer, (Sint64) buflen);
         buflen -= br;
         buffer = ((Uint8 *)buffer) + br;
-        if (buflen > 0) { /* EOF (or error, but whatever). */
+        if (buflen > 0) { // EOF (or error, but whatever).
             SDL_RWclose(h->io);
             h->io = NULL;
         }
     }
 
-    /* if we ran out of file, just write silence. */
-    SDL_memset(buffer, _this->spec.silence, buflen);
+    // if we ran out of file, just write silence.
+    SDL_memset(buffer, device->silence_value, buflen);
 
     return origbuflen;
 }
 
-static void DISKAUDIO_FlushCapture(SDL_AudioDevice *_this)
+static void DISKAUDIO_FlushCapture(SDL_AudioDevice *device)
 {
-    /* no op...we don't advance the file pointer or anything. */
+    // no op...we don't advance the file pointer or anything.
 }
 
-static void DISKAUDIO_CloseDevice(SDL_AudioDevice *_this)
+static void DISKAUDIO_CloseDevice(SDL_AudioDevice *device)
 {
-    if (_this->hidden->io != NULL) {
-        SDL_RWclose(_this->hidden->io);
+    if (device->hidden) {
+        if (device->hidden->io != NULL) {
+            SDL_RWclose(device->hidden->io);
+        }
+        SDL_free(device->hidden->mixbuf);
+        SDL_free(device->hidden);
+        device->hidden = NULL;
     }
-    SDL_free(_this->hidden->mixbuf);
-    SDL_free(_this->hidden);
 }
 
-static const char *get_filename(const SDL_bool iscapture, const char *devname)
+static const char *get_filename(const SDL_bool iscapture)
 {
+    const char *devname = SDL_getenv(iscapture ? DISKENVR_INFILE : DISKENVR_OUTFILE);
     if (devname == NULL) {
-        devname = SDL_getenv(iscapture ? DISKENVR_INFILE : DISKENVR_OUTFILE);
-        if (devname == NULL) {
-            devname = iscapture ? DISKDEFAULT_INFILE : DISKDEFAULT_OUTFILE;
-        }
+        devname = iscapture ? DISKDEFAULT_INFILE : DISKDEFAULT_OUTFILE;
     }
     return devname;
 }
 
-static int DISKAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
+static int DISKAUDIO_OpenDevice(SDL_AudioDevice *device)
 {
-    void *handle = _this->handle;
-    /* handle != NULL means "user specified the placeholder name on the fake detected device list" */
-    SDL_bool iscapture = _this->iscapture;
-    const char *fname = get_filename(iscapture, handle ? NULL : devname);
+    SDL_bool iscapture = device->iscapture;
+    const char *fname = get_filename(iscapture);
     const char *envr = SDL_getenv(DISKENVR_IODELAY);
 
-    _this->hidden = (struct SDL_PrivateAudioData *)
-        SDL_malloc(sizeof(*_this->hidden));
-    if (_this->hidden == NULL) {
+    device->hidden = (struct SDL_PrivateAudioData *) SDL_calloc(1, sizeof(*device->hidden));
+    if (device->hidden == NULL) {
         return SDL_OutOfMemory();
     }
-    SDL_zerop(_this->hidden);
 
     if (envr != NULL) {
-        _this->hidden->io_delay = SDL_atoi(envr);
+        device->hidden->io_delay = SDL_atoi(envr);
     } else {
-        _this->hidden->io_delay = ((_this->spec.samples * 1000) / _this->spec.freq);
+        device->hidden->io_delay = ((device->sample_frames * 1000) / device->spec.freq);
     }
 
-    /* Open the audio device */
-    _this->hidden->io = SDL_RWFromFile(fname, iscapture ? "rb" : "wb");
-    if (_this->hidden->io == NULL) {
+    // Open the "audio device"
+    device->hidden->io = SDL_RWFromFile(fname, iscapture ? "rb" : "wb");
+    if (device->hidden->io == NULL) {
         return -1;
     }
 
-    /* Allocate mixing buffer */
+    // Allocate mixing buffer
     if (!iscapture) {
-        _this->hidden->mixbuf = (Uint8 *)SDL_malloc(_this->spec.size);
-        if (_this->hidden->mixbuf == NULL) {
+        device->hidden->mixbuf = (Uint8 *)SDL_malloc(device->buffer_size);
+        if (device->hidden->mixbuf == NULL) {
             return SDL_OutOfMemory();
         }
-        SDL_memset(_this->hidden->mixbuf, _this->spec.silence, _this->spec.size);
+        SDL_memset(device->hidden->mixbuf, device->silence_value, device->buffer_size);
     }
 
-    SDL_LogCritical(SDL_LOG_CATEGORY_AUDIO,
-                    "You are using the SDL disk i/o audio driver!\n");
-    SDL_LogCritical(SDL_LOG_CATEGORY_AUDIO,
-                    " %s file [%s].\n", iscapture ? "Reading from" : "Writing to",
-                    fname);
+    SDL_LogCritical(SDL_LOG_CATEGORY_AUDIO, "You are using the SDL disk i/o audio driver!");
+    SDL_LogCritical(SDL_LOG_CATEGORY_AUDIO, " %s file [%s].\n", iscapture ? "Reading from" : "Writing to", fname);
 
-    /* We're ready to rock and roll. :-) */
-    return 0;
+    return 0;  // We're ready to rock and roll. :-)
 }
 
-static void DISKAUDIO_DetectDevices(void)
+static void DISKAUDIO_DetectDevices(SDL_AudioDevice **default_output, SDL_AudioDevice **default_capture)
 {
-    SDL_AddAudioDevice(SDL_FALSE, DEFAULT_OUTPUT_DEVNAME, NULL, (void *)0x1);
-    SDL_AddAudioDevice(SDL_TRUE, DEFAULT_INPUT_DEVNAME, NULL, (void *)0x2);
+    *default_output = SDL_AddAudioDevice(SDL_FALSE, DEFAULT_OUTPUT_DEVNAME, NULL, (void *)0x1);
+    *default_capture = SDL_AddAudioDevice(SDL_TRUE, DEFAULT_INPUT_DEVNAME, NULL, (void *)0x2);
 }
 
 static SDL_bool DISKAUDIO_Init(SDL_AudioDriverImpl *impl)
 {
-    /* Set the function pointers */
     impl->OpenDevice = DISKAUDIO_OpenDevice;
     impl->WaitDevice = DISKAUDIO_WaitDevice;
+    impl->WaitCaptureDevice = DISKAUDIO_WaitDevice;
     impl->PlayDevice = DISKAUDIO_PlayDevice;
     impl->GetDeviceBuf = DISKAUDIO_GetDeviceBuf;
     impl->CaptureFromDevice = DISKAUDIO_CaptureFromDevice;
     impl->FlushCapture = DISKAUDIO_FlushCapture;
-
     impl->CloseDevice = DISKAUDIO_CloseDevice;
     impl->DetectDevices = DISKAUDIO_DetectDevices;
 
     impl->AllowsArbitraryDeviceNames = SDL_TRUE;
     impl->HasCaptureSupport = SDL_TRUE;
-    impl->SupportsNonPow2Samples = SDL_TRUE;
 
-    return SDL_TRUE; /* this audio target is available. */
+    return SDL_TRUE;
 }
 
 AudioBootStrap DISKAUDIO_bootstrap = {
     "disk", "direct-to-disk audio", DISKAUDIO_Init, SDL_TRUE
 };
 
-#endif /* SDL_AUDIO_DRIVER_DISK */
+#endif // SDL_AUDIO_DRIVER_DISK

src/audio/dsp/SDL_dspaudio.c

@@ -20,9 +20,9 @@
 */
 #include "SDL_internal.h"
 
-#ifdef SDL_AUDIO_DRIVER_OSS
+// !!! FIXME: clean out perror and fprintf calls in here.
 
-/* Allow access to a raw mixing buffer */
+#ifdef SDL_AUDIO_DRIVER_OSS
 
 #include <stdio.h>  /* For perror() */
 #include <string.h> /* For strerror() */
@@ -38,82 +38,69 @@
 
 #include "../SDL_audio_c.h"
 #include "../SDL_audiodev_c.h"
+#include "../../SDL_utils_c.h"
 #include "SDL_dspaudio.h"
 
-static void DSP_DetectDevices(void)
+static void DSP_DetectDevices(SDL_AudioDevice **default_output, SDL_AudioDevice **default_capture)
 {
-    SDL_EnumUnixAudioDevices(0, NULL);
+    SDL_EnumUnixAudioDevices(SDL_FALSE, NULL);
 }
 
-static void DSP_CloseDevice(SDL_AudioDevice *_this)
+static void DSP_CloseDevice(SDL_AudioDevice *device)
 {
-    if (_this->hidden->audio_fd >= 0) {
-        close(_this->hidden->audio_fd);
+    if (device->hidden) {
+        if (device->hidden->audio_fd >= 0) {
+            close(device->hidden->audio_fd);
+        }
+        SDL_free(device->hidden->mixbuf);
+        SDL_free(device->hidden);
     }
-    SDL_free(_this->hidden->mixbuf);
-    SDL_free(_this->hidden);
 }
 
-static int DSP_OpenDevice(SDL_AudioDevice *_this, const char *devname)
+static int DSP_OpenDevice(SDL_AudioDevice *device)
 {
-    SDL_bool iscapture = _this->iscapture;
-    const int flags = ((iscapture) ? OPEN_FLAGS_INPUT : OPEN_FLAGS_OUTPUT);
-    int format = 0;
-    int value;
-    int frag_spec;
-    SDL_AudioFormat test_format;
-    const SDL_AudioFormat *closefmts;
-
-    /* We don't care what the devname is...we'll try to open anything. */
-    /*  ...but default to first name in the list... */
-    if (devname == NULL) {
-        devname = SDL_GetAudioDeviceName(0, iscapture);
-        if (devname == NULL) {
-            return SDL_SetError("No such audio device");
-        }
+    // Make sure fragment size stays a power of 2, or OSS fails.
+    // (I don't know which of these are actually legal values, though...)
+    if (device->spec.channels > 8) {
+        device->spec.channels = 8;
+    } else if (device->spec.channels > 4) {
+        device->spec.channels = 4;
+    } else if (device->spec.channels > 2) {
+        device->spec.channels = 2;
     }
 
-    /* Make sure fragment size stays a power of 2, or OSS fails. */
-    /* I don't know which of these are actually legal values, though... */
-    if (_this->spec.channels > 8) {
-        _this->spec.channels = 8;
-    } else if (_this->spec.channels > 4) {
-        _this->spec.channels = 4;
-    } else if (_this->spec.channels > 2) {
-        _this->spec.channels = 2;
-    }
-
-    /* Initialize all variables that we clean on shutdown */
-    _this->hidden = (struct SDL_PrivateAudioData *) SDL_malloc(sizeof(*_this->hidden));
-    if (_this->hidden == NULL) {
+    // Initialize all variables that we clean on shutdown
+    device->hidden = (struct SDL_PrivateAudioData *) SDL_calloc(1, sizeof(*device->hidden));
+    if (device->hidden == NULL) {
         return SDL_OutOfMemory();
     }
-    SDL_zerop(_this->hidden);
 
-    /* Open the audio device */
-    _this->hidden->audio_fd = open(devname, flags | O_CLOEXEC, 0);
-    if (_this->hidden->audio_fd < 0) {
-        return SDL_SetError("Couldn't open %s: %s", devname, strerror(errno));
+    // Open the audio device; we hardcode the device path in `device->name` for lack of better info, so use that.
+    const int flags = ((device->iscapture) ? OPEN_FLAGS_INPUT : OPEN_FLAGS_OUTPUT);
+    device->hidden->audio_fd = open(device->name, flags | O_CLOEXEC, 0);
+    if (device->hidden->audio_fd < 0) {
+        return SDL_SetError("Couldn't open %s: %s", device->name, strerror(errno));
     }
 
-    /* Make the file descriptor use blocking i/o with fcntl() */
+    // Make the file descriptor use blocking i/o with fcntl()
     {
-        long ctlflags;
-        ctlflags = fcntl(_this->hidden->audio_fd, F_GETFL);
-        ctlflags &= ~O_NONBLOCK;
-        if (fcntl(_this->hidden->audio_fd, F_SETFL, ctlflags) < 0) {
+        const long ctlflags = fcntl(device->hidden->audio_fd, F_GETFL) & ~O_NONBLOCK;
+        if (fcntl(device->hidden->audio_fd, F_SETFL, ctlflags) < 0) {
             return SDL_SetError("Couldn't set audio blocking mode");
         }
     }
 
-    /* Get a list of supported hardware formats */
-    if (ioctl(_this->hidden->audio_fd, SNDCTL_DSP_GETFMTS, &value) < 0) {
+    // Get a list of supported hardware formats
+    int value;
+    if (ioctl(device->hidden->audio_fd, SNDCTL_DSP_GETFMTS, &value) < 0) {
         perror("SNDCTL_DSP_GETFMTS");
         return SDL_SetError("Couldn't get audio format list");
     }
 
     /* Try for a closest match on audio format */
-    closefmts = SDL_ClosestAudioFormats(_this->spec.format);
+    int format = 0;
+    SDL_AudioFormat test_format;
+    const SDL_AudioFormat *closefmts = SDL_ClosestAudioFormats(device->spec.format);
     while ((test_format = *(closefmts++)) != 0) {
 #ifdef DEBUG_AUDIO
         fprintf(stderr, "Trying format 0x%4.4x\n", test_format);
@@ -134,17 +121,7 @@ static int DSP_OpenDevice(SDL_AudioDevice *_this, const char *devname)
                 format = AFMT_S16_BE;
             }
             break;
-#if 0
-/*
- * These formats are not used by any real life systems so they are not
- * needed here.
- */
-        case SDL_AUDIO_S8:
-            if (value & AFMT_S8) {
-                format = AFMT_S8;
-            }
-            break;
-#endif
+
         default:
             continue;
         }
@@ -153,40 +130,43 @@ static int DSP_OpenDevice(SDL_AudioDevice *_this, const char *devname)
     if (format == 0) {
         return SDL_SetError("Couldn't find any hardware audio formats");
     }
-    _this->spec.format = test_format;
+    device->spec.format = test_format;
 
-    /* Set the audio format */
+    // Set the audio format
     value = format;
-    if ((ioctl(_this->hidden->audio_fd, SNDCTL_DSP_SETFMT, &value) < 0) ||
+    if ((ioctl(device->hidden->audio_fd, SNDCTL_DSP_SETFMT, &value) < 0) ||
         (value != format)) {
         perror("SNDCTL_DSP_SETFMT");
         return SDL_SetError("Couldn't set audio format");
     }
 
-    /* Set the number of channels of output */
-    value = _this->spec.channels;
-    if (ioctl(_this->hidden->audio_fd, SNDCTL_DSP_CHANNELS, &value) < 0) {
+    // Set the number of channels of output
+    value = device->spec.channels;
+    if (ioctl(device->hidden->audio_fd, SNDCTL_DSP_CHANNELS, &value) < 0) {
         perror("SNDCTL_DSP_CHANNELS");
         return SDL_SetError("Cannot set the number of channels");
     }
-    _this->spec.channels = value;
+    device->spec.channels = value;
 
-    /* Set the DSP frequency */
-    value = _this->spec.freq;
-    if (ioctl(_this->hidden->audio_fd, SNDCTL_DSP_SPEED, &value) < 0) {
+    // Set the DSP frequency
+    value = device->spec.freq;
+    if (ioctl(device->hidden->audio_fd, SNDCTL_DSP_SPEED, &value) < 0) {
         perror("SNDCTL_DSP_SPEED");
         return SDL_SetError("Couldn't set audio frequency");
     }
-    _this->spec.freq = value;
+    device->spec.freq = value;
 
     /* Calculate the final parameters for this audio specification */
-    SDL_CalculateAudioSpec(&_this->spec);
+    SDL_UpdatedAudioDeviceFormat(device);
 
-    /* Determine the power of two of the fragment size */
-    for (frag_spec = 0; (0x01U << frag_spec) < _this->spec.size; ++frag_spec) {
-    }
-    if ((0x01U << frag_spec) != _this->spec.size) {
-        return SDL_SetError("Fragment size must be a power of two");
+    /* Determine the power of two of the fragment size
+       Since apps don't control this in SDL3, and this driver only accepts 8, 16
+       bit formats and 1, 2, 4, 8 channels, this should always be a power of 2 already. */
+    SDL_assert(SDL_powerof2(device->buffer_size) == device->buffer_size);
+
+    int frag_spec = 0;
+    while ((0x01U << frag_spec) < device->buffer_size) {
+        frag_spec++;
     }
     frag_spec |= 0x00020000; /* two fragments, for low latency */
 
@@ -195,13 +175,13 @@ static int DSP_OpenDevice(SDL_AudioDevice *_this, const char *devname)
     fprintf(stderr, "Requesting %d fragments of size %d\n",
             (frag_spec >> 16), 1 << (frag_spec & 0xFFFF));
 #endif
-    if (ioctl(_this->hidden->audio_fd, SNDCTL_DSP_SETFRAGMENT, &frag_spec) < 0) {
+    if (ioctl(device->hidden->audio_fd, SNDCTL_DSP_SETFRAGMENT, &frag_spec) < 0) {
         perror("SNDCTL_DSP_SETFRAGMENT");
     }
 #ifdef DEBUG_AUDIO
     {
         audio_buf_info info;
-        ioctl(_this->hidden->audio_fd, SNDCTL_DSP_GETOSPACE, &info);
+        ioctl(device->hidden->audio_fd, SNDCTL_DSP_GETOSPACE, &info);
         fprintf(stderr, "fragments = %d\n", info.fragments);
         fprintf(stderr, "fragstotal = %d\n", info.fragstotal);
         fprintf(stderr, "fragsize = %d\n", info.fragsize);
@@ -210,44 +190,67 @@ static int DSP_OpenDevice(SDL_AudioDevice *_this, const char *devname)
 #endif
 
     /* Allocate mixing buffer */
-    if (!iscapture) {
-        _this->hidden->mixlen = _this->spec.size;
-        _this->hidden->mixbuf = (Uint8 *)SDL_malloc(_this->hidden->mixlen);
-        if (_this->hidden->mixbuf == NULL) {
+    if (!device->iscapture) {
+        device->hidden->mixbuf = (Uint8 *)SDL_malloc(device->buffer_size);
+        if (device->hidden->mixbuf == NULL) {
             return SDL_OutOfMemory();
         }
-        SDL_memset(_this->hidden->mixbuf, _this->spec.silence, _this->spec.size);
+        SDL_memset(device->hidden->mixbuf, device->silence_value, device->buffer_size);
     }
 
-    /* We're ready to rock and roll. :-) */
-    return 0;
+    return 0;  // We're ready to rock and roll. :-)
+}
+
+static void DSP_WaitDevice(SDL_AudioDevice *device)
+{
+    const unsigned long ioctlreq = device->iscapture ? SNDCTL_DSP_GETISPACE : SNDCTL_DSP_GETOSPACE;
+    struct SDL_PrivateAudioData *h = device->hidden;
+
+    while (!SDL_AtomicGet(&device->shutdown)) {
+        audio_buf_info info;
+        const int rc = ioctl(h->audio_fd, ioctlreq, &info);
+        if (rc < 0) {
+            if (errno == EAGAIN) {
+                continue;
+            }
+            // Hmm, not much we can do - abort
+            fprintf(stderr, "dsp WaitDevice ioctl failed (unrecoverable): %s\n", strerror(errno));
+            SDL_AudioDeviceDisconnected(device);
+            return;
+        } else if (info.bytes < device->buffer_size) {
+            SDL_Delay(10);
+        } else {
+            break; // ready to go!
+        }
+    }
 }
 
-static void DSP_PlayDevice(SDL_AudioDevice *_this)
+static void DSP_PlayDevice(SDL_AudioDevice *device, const Uint8 *buffer, int buflen)
 {
-    struct SDL_PrivateAudioData *h = _this->hidden;
-    if (write(h->audio_fd, h->mixbuf, h->mixlen) == -1) {
+    struct SDL_PrivateAudioData *h = device->hidden;
+    if (write(h->audio_fd, buffer, buflen) == -1) {
         perror("Audio write");
-        SDL_OpenedAudioDeviceDisconnected(_this);
+        SDL_AudioDeviceDisconnected(device);
+        return;
     }
 #ifdef DEBUG_AUDIO
     fprintf(stderr, "Wrote %d bytes of audio data\n", h->mixlen);
 #endif
 }
 
-static Uint8 *DSP_GetDeviceBuf(SDL_AudioDevice *_this)
+static Uint8 *DSP_GetDeviceBuf(SDL_AudioDevice *device, int *buffer_size)
 {
-    return _this->hidden->mixbuf;
+    return device->hidden->mixbuf;
 }
 
-static int DSP_CaptureFromDevice(SDL_AudioDevice *_this, void *buffer, int buflen)
+static int DSP_CaptureFromDevice(SDL_AudioDevice *device, void *buffer, int buflen)
 {
-    return (int)read(_this->hidden->audio_fd, buffer, buflen);
+    return (int)read(device->hidden->audio_fd, buffer, buflen);
 }
 
-static void DSP_FlushCapture(SDL_AudioDevice *_this)
+static void DSP_FlushCapture(SDL_AudioDevice *device)
 {
-    struct SDL_PrivateAudioData *h = _this->hidden;
+    struct SDL_PrivateAudioData *h = device->hidden;
     audio_buf_info info;
     if (ioctl(h->audio_fd, SNDCTL_DSP_GETISPACE, &info) == 0) {
         while (info.bytes > 0) {
@@ -263,17 +266,17 @@ static void DSP_FlushCapture(SDL_AudioDevice *_this)
 }
 
 static SDL_bool InitTimeDevicesExist = SDL_FALSE;
-static int look_for_devices_test(int fd)
+static SDL_bool look_for_devices_test(int fd)
 {
     InitTimeDevicesExist = SDL_TRUE; /* note that _something_ exists. */
     /* Don't add to the device list, we're just seeing if any devices exist. */
-    return 0;
+    return SDL_FALSE;
 }
 
 static SDL_bool DSP_Init(SDL_AudioDriverImpl *impl)
 {
     InitTimeDevicesExist = SDL_FALSE;
-    SDL_EnumUnixAudioDevices(0, look_for_devices_test);
+    SDL_EnumUnixAudioDevices(SDL_FALSE, look_for_devices_test);
     if (!InitTimeDevicesExist) {
         SDL_SetError("dsp: No such audio device");
         return SDL_FALSE; /* maybe try a different backend. */
@@ -282,9 +285,11 @@ static SDL_bool DSP_Init(SDL_AudioDriverImpl *impl)
     /* Set the function pointers */
     impl->DetectDevices = DSP_DetectDevices;
     impl->OpenDevice = DSP_OpenDevice;
+    impl->WaitDevice = DSP_WaitDevice;
     impl->PlayDevice = DSP_PlayDevice;
     impl->GetDeviceBuf = DSP_GetDeviceBuf;
     impl->CloseDevice = DSP_CloseDevice;
+    impl->WaitCaptureDevice = DSP_WaitDevice;
     impl->CaptureFromDevice = DSP_CaptureFromDevice;
     impl->FlushCapture = DSP_FlushCapture;
 
@@ -295,7 +300,7 @@ static SDL_bool DSP_Init(SDL_AudioDriverImpl *impl)
 }
 
 AudioBootStrap DSP_bootstrap = {
-    "dsp", "OSS /dev/dsp standard audio", DSP_Init, SDL_FALSE
+    "dsp", "Open Sound System (/dev/dsp)", DSP_Init, SDL_FALSE
 };
 
 #endif /* SDL_AUDIO_DRIVER_OSS */

src/audio/dsp/SDL_dspaudio.h

@@ -32,8 +32,6 @@ struct SDL_PrivateAudioData
 
     /* Raw mixing buffer */
     Uint8 *mixbuf;
-    int mixlen;
 };
-#define FUDGE_TICKS 10 /* The scheduler overhead ticks per frame */
 
 #endif /* SDL_dspaudio_h_ */

src/audio/dummy/SDL_dummyaudio.c

@@ -20,39 +20,75 @@
 */
 #include "SDL_internal.h"
 
-/* Output audio to nowhere... */
+// Output audio to nowhere...
 
 #include "../SDL_audio_c.h"
 #include "SDL_dummyaudio.h"
 
-static int DUMMYAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
+// !!! FIXME: this should be an SDL hint, not an environment variable.
+#define DUMMYENVR_IODELAY "SDL_DUMMYAUDIODELAY"
+
+static void DUMMYAUDIO_WaitDevice(SDL_AudioDevice *device)
+{
+    SDL_Delay(device->hidden->io_delay);
+}
+
+static int DUMMYAUDIO_OpenDevice(SDL_AudioDevice *device)
 {
-    _this->hidden = (void *)0x1; /* just something non-NULL */
+    const char *envr = SDL_getenv(DUMMYENVR_IODELAY);
+
+    device->hidden = (struct SDL_PrivateAudioData *) SDL_calloc(1, sizeof(*device->hidden));
+    if (!device->hidden) {
+        return SDL_OutOfMemory();
+    }
+
+    if (!device->iscapture) {
+        device->hidden->mixbuf = (Uint8 *) SDL_malloc(device->buffer_size);
+        if (!device->hidden->mixbuf) {
+            return SDL_OutOfMemory();
+        }
+    }
 
-    return 0; /* always succeeds. */
+    device->hidden->io_delay = (Uint32) (envr ? SDL_atoi(envr) : ((device->sample_frames * 1000) / device->spec.freq));
+
+    return 0; // we're good; don't change reported device format.
+}
+
+static void DUMMYAUDIO_CloseDevice(SDL_AudioDevice *device)
+{
+    if (device->hidden) {
+        SDL_free(device->hidden->mixbuf);
+        SDL_free(device->hidden);
+        device->hidden = NULL;
+    }
 }
 
-static int DUMMYAUDIO_CaptureFromDevice(SDL_AudioDevice *_this, void *buffer, int buflen)
+static Uint8 *DUMMYAUDIO_GetDeviceBuf(SDL_AudioDevice *device, int *buffer_size)
 {
-    /* Delay to make this sort of simulate real audio input. */
-    SDL_Delay((_this->spec.samples * 1000) / _this->spec.freq);
+    return device->hidden->mixbuf;
+}
 
-    /* always return a full buffer of silence. */
-    SDL_memset(buffer, _this->spec.silence, buflen);
+static int DUMMYAUDIO_CaptureFromDevice(SDL_AudioDevice *device, void *buffer, int buflen)
+{
+    // always return a full buffer of silence.
+    SDL_memset(buffer, device->silence_value, buflen);
     return buflen;
 }
 
 static SDL_bool DUMMYAUDIO_Init(SDL_AudioDriverImpl *impl)
 {
-    /* Set the function pointers */
     impl->OpenDevice = DUMMYAUDIO_OpenDevice;
+    impl->CloseDevice = DUMMYAUDIO_CloseDevice;
+    impl->WaitDevice = DUMMYAUDIO_WaitDevice;
+    impl->GetDeviceBuf = DUMMYAUDIO_GetDeviceBuf;
+    impl->WaitCaptureDevice = DUMMYAUDIO_WaitDevice;
     impl->CaptureFromDevice = DUMMYAUDIO_CaptureFromDevice;
 
     impl->OnlyHasDefaultOutputDevice = SDL_TRUE;
     impl->OnlyHasDefaultCaptureDevice = SDL_TRUE;
     impl->HasCaptureSupport = SDL_TRUE;
 
-    return SDL_TRUE; /* this audio target is available. */
+    return SDL_TRUE;
 }
 
 AudioBootStrap DUMMYAUDIO_bootstrap = {

src/audio/dummy/SDL_dummyaudio.h

@@ -27,11 +27,8 @@
 
 struct SDL_PrivateAudioData
 {
-    /* The file descriptor for the audio device */
-    Uint8 *mixbuf;
-    Uint32 mixlen;
-    Uint32 write_delay;
-    Uint32 initial_calls;
+    Uint8 *mixbuf;   // The file descriptor for the audio device
+    Uint32 io_delay; // miliseconds to sleep in WaitDevice.
 };
 
-#endif /* SDL_dummyaudio_h_ */
+#endif // SDL_dummyaudio_h_

src/audio/emscripten/SDL_emscriptenaudio.c

@@ -27,15 +27,18 @@
 
 #include <emscripten/emscripten.h>
 
-/* !!! FIXME: this currently expects that the audio callback runs in the main thread,
-   !!! FIXME:  in intervals when the application isn't running, but that may not be
-   !!! FIXME:  true always once pthread support becomes widespread. Revisit this code
-   !!! FIXME:  at some point and see what needs to be done for that! */
+// just turn off clang-format for this whole file, this INDENT_OFF stuff on
+//  each EM_ASM section is ugly.
+/* *INDENT-OFF* */ /* clang-format off */
 
-static void FeedAudioDevice(SDL_AudioDevice *_this, const void *buf, const int buflen)
+static Uint8 *EMSCRIPTENAUDIO_GetDeviceBuf(SDL_AudioDevice *device, int *buffer_size)
 {
-    const int framelen = (SDL_AUDIO_BITSIZE(_this->spec.format) / 8) * _this->spec.channels;
-    /* *INDENT-OFF* */ /* clang-format off */
+    return device->hidden->mixbuf;
+}
+
+static void EMSCRIPTENAUDIO_PlayDevice(SDL_AudioDevice *device, const Uint8 *buffer, int buffer_size)
+{
+    const int framelen = (SDL_AUDIO_BITSIZE(device->spec.format) / 8) * device->spec.channels;
     MAIN_THREAD_EM_ASM({
         var SDL3 = Module['SDL3'];
         var numChannels = SDL3.audio.currentOutputBuffer['numberOfChannels'];
@@ -46,65 +49,25 @@ static void FeedAudioDevice(SDL_AudioDevice *_this, const void *buf, const int b
             }
 
             for (var j = 0; j < $1; ++j) {
-                channelData[j] = HEAPF32[$0 + ((j*numChannels + c) << 2) >> 2];  /* !!! FIXME: why are these shifts here? */
+                channelData[j] = HEAPF32[$0 + ((j*numChannels + c) << 2) >> 2];  // !!! FIXME: why are these shifts here?
             }
         }
-    }, buf, buflen / framelen);
-/* *INDENT-ON* */ /* clang-format on */
+    }, buffer, buffer_size / framelen);
 }
 
-static void HandleAudioProcess(SDL_AudioDevice *_this)
+static void HandleAudioProcess(SDL_AudioDevice *device)  // this fires when the main thread is idle.
 {
-    SDL_AudioCallback callback = _this->callbackspec.callback;
-    const int stream_len = _this->callbackspec.size;
-
-    /* Only do something if audio is enabled */
-    if (!SDL_AtomicGet(&_this->enabled) || SDL_AtomicGet(&_this->paused)) {
-        if (_this->stream) {
-            SDL_ClearAudioStream(_this->stream);
-        }
-
-        SDL_memset(_this->work_buffer, _this->spec.silence, _this->spec.size);
-        FeedAudioDevice(_this, _this->work_buffer, _this->spec.size);
-        return;
-    }
-
-    if (_this->stream == NULL) { /* no conversion necessary. */
-        SDL_assert(_this->spec.size == stream_len);
-        callback(_this->callbackspec.userdata, _this->work_buffer, stream_len);
-    } else { /* streaming/converting */
-        int got;
-        while (SDL_GetAudioStreamAvailable(_this->stream) < ((int)_this->spec.size)) {
-            callback(_this->callbackspec.userdata, _this->work_buffer, stream_len);
-            if (SDL_PutAudioStreamData(_this->stream, _this->work_buffer, stream_len) == -1) {
-                SDL_ClearAudioStream(_this->stream);
-                SDL_AtomicSet(&_this->enabled, 0);
-                break;
-            }
-        }
+    SDL_OutputAudioThreadIterate(device);
+}
 
-        got = SDL_GetAudioStreamData(_this->stream, _this->work_buffer, _this->spec.size);
-        SDL_assert((got < 0) || (got == _this->spec.size));
-        if (got != _this->spec.size) {
-            SDL_memset(_this->work_buffer, _this->spec.silence, _this->spec.size);
-        }
-    }
 
-    FeedAudioDevice(_this, _this->work_buffer, _this->spec.size);
+static void EMSCRIPTENAUDIO_FlushCapture(SDL_AudioDevice *device)
+{
+    // Do nothing, the new data will just be dropped.
 }
 
-static void HandleCaptureProcess(SDL_AudioDevice *_this)
+static int EMSCRIPTENAUDIO_CaptureFromDevice(SDL_AudioDevice *device, void *buffer, int buflen)
 {
-    SDL_AudioCallback callback = _this->callbackspec.callback;
-    const int stream_len = _this->callbackspec.size;
-
-    /* Only do something if audio is enabled */
-    if (!SDL_AtomicGet(&_this->enabled) || SDL_AtomicGet(&_this->paused)) {
-        SDL_ClearAudioStream(_this->stream);
-        return;
-    }
-
-    /* *INDENT-OFF* */ /* clang-format off */
     MAIN_THREAD_EM_ASM({
         var SDL3 = Module['SDL3'];
         var numChannels = SDL3.capture.currentCaptureBuffer.numberOfChannels;
@@ -114,7 +77,7 @@ static void HandleCaptureProcess(SDL_AudioDevice *_this)
                 throw 'Web Audio capture buffer length mismatch! Destination size: ' + channelData.length + ' samples vs expected ' + $1 + ' samples!';
             }
 
-            if (numChannels == 1) {  /* fastpath this a little for the common (mono) case. */
+            if (numChannels == 1) {  // fastpath this a little for the common (mono) case.
                 for (var j = 0; j < $1; ++j) {
                     setValue($0 + (j * 4), channelData[j], 'float');
                 }
@@ -124,33 +87,22 @@ static void HandleCaptureProcess(SDL_AudioDevice *_this)
                 }
             }
         }
-    }, _this->work_buffer, (_this->spec.size / sizeof(float)) / _this->spec.channels);
-/* *INDENT-ON* */ /* clang-format on */
-
-    /* okay, we've got an interleaved float32 array in C now. */
+    }, buffer, (buflen / sizeof(float)) / device->spec.channels);
 
-    if (_this->stream == NULL) { /* no conversion necessary. */
-        SDL_assert(_this->spec.size == stream_len);
-        callback(_this->callbackspec.userdata, _this->work_buffer, stream_len);
-    } else { /* streaming/converting */
-        if (SDL_PutAudioStreamData(_this->stream, _this->work_buffer, _this->spec.size) == -1) {
-            SDL_AtomicSet(&_this->enabled, 0);
-        }
+    return buflen;
+}
 
-        while (SDL_GetAudioStreamAvailable(_this->stream) >= stream_len) {
-            const int got = SDL_GetAudioStreamData(_this->stream, _this->work_buffer, stream_len);
-            SDL_assert((got < 0) || (got == stream_len));
-            if (got != stream_len) {
-                SDL_memset(_this->work_buffer, _this->callbackspec.silence, stream_len);
-            }
-            callback(_this->callbackspec.userdata, _this->work_buffer, stream_len); /* Send it to the app. */
-        }
-    }
+static void HandleCaptureProcess(SDL_AudioDevice *device)  // this fires when the main thread is idle.
+{
+    SDL_CaptureAudioThreadIterate(device);
 }
 
-static void EMSCRIPTENAUDIO_CloseDevice(SDL_AudioDevice *_this)
+static void EMSCRIPTENAUDIO_CloseDevice(SDL_AudioDevice *device)
 {
-    /* *INDENT-OFF* */ /* clang-format off */
+    if (!device->hidden) {
+        return;
+    }
+
     MAIN_THREAD_EM_ASM({
         var SDL3 = Module['SDL3'];
         if ($0) {
@@ -188,29 +140,23 @@ static void EMSCRIPTENAUDIO_CloseDevice(SDL_AudioDevice *_this)
             SDL3.audioContext.close();
             SDL3.audioContext = undefined;
         }
-    }, _this->iscapture);
-/* *INDENT-ON* */ /* clang-format on */
+    }, device->iscapture);
 
-#if 0 /* !!! FIXME: currently not used. Can we move some stuff off the SDL3 namespace? --ryan. */
-    SDL_free(_this->hidden);
-#endif
-}
+    SDL_free(device->hidden->mixbuf);
+    SDL_free(device->hidden);
+    device->hidden = NULL;
 
+    SDL_AudioThreadFinalize(device);
+}
 
 EM_JS_DEPS(sdlaudio, "$autoResumeAudioContext,$dynCall");
 
-static int EMSCRIPTENAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
+static int EMSCRIPTENAUDIO_OpenDevice(SDL_AudioDevice *device)
 {
-    SDL_AudioFormat test_format;
-    const SDL_AudioFormat *closefmts;
-    SDL_bool iscapture = _this->iscapture;
-    int result;
-
-    /* based on parts of library_sdl.js */
+    // based on parts of library_sdl.js
 
-    /* *INDENT-OFF* */ /* clang-format off */
-    /* create context */
-    result = MAIN_THREAD_EM_ASM_INT({
+    // create context
+    const int result = MAIN_THREAD_EM_ASM_INT({
         if (typeof(Module['SDL3']) === 'undefined') {
             Module['SDL3'] = {};
         }
@@ -232,57 +178,41 @@ static int EMSCRIPTENAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devnam
             }
         }
         return SDL3.audioContext === undefined ? -1 : 0;
-    }, iscapture);
-/* *INDENT-ON* */ /* clang-format on */
+    }, device->iscapture);
 
     if (result < 0) {
         return SDL_SetError("Web Audio API is not available!");
     }
 
-    closefmts = SDL_ClosestAudioFormats(_this->spec.format);
-    while ((test_format = *(closefmts++)) != 0) {
-        switch (test_format) {
-        case SDL_AUDIO_F32: /* web audio only supports floats */
-            break;
-        default:
-            continue;
-        }
-        break;
-    }
-
-    if (!test_format) {
-        /* Didn't find a compatible format :( */
-        return SDL_SetError("%s: Unsupported audio format", "emscripten");
-    }
-    _this->spec.format = test_format;
+    device->spec.format = SDL_AUDIO_F32;  // web audio only supports floats
 
-    /* Initialize all variables that we clean on shutdown */
-#if 0 /* !!! FIXME: currently not used. Can we move some stuff off the SDL3 namespace? --ryan. */
-    _this->hidden = (struct SDL_PrivateAudioData *)SDL_malloc(sizeof(*_this->hidden));
-    if (_this->hidden == NULL) {
+    // Initialize all variables that we clean on shutdown
+    device->hidden = (struct SDL_PrivateAudioData *)SDL_calloc(1, sizeof(*device->hidden));
+    if (device->hidden == NULL) {
         return SDL_OutOfMemory();
     }
-    SDL_zerop(_this->hidden);
-#endif
-    _this->hidden = (struct SDL_PrivateAudioData *)0x1;
 
-    /* limit to native freq */
-    _this->spec.freq = EM_ASM_INT({
-        var SDL3 = Module['SDL3'];
-        return SDL3.audioContext.sampleRate;
-    });
+    // limit to native freq
+    device->spec.freq = EM_ASM_INT({ return Module['SDL3'].audioContext.sampleRate; });
 
-    SDL_CalculateAudioSpec(&_this->spec);
+    SDL_UpdatedAudioDeviceFormat(device);
 
-    /* *INDENT-OFF* */ /* clang-format off */
-    if (iscapture) {
+    if (!device->iscapture) {
+        device->hidden->mixbuf = (Uint8 *)SDL_malloc(device->buffer_size);
+        if (device->hidden->mixbuf == NULL) {
+            return SDL_OutOfMemory();
+        }
+        SDL_memset(device->hidden->mixbuf, device->silence_value, device->buffer_size);
+    }
+
+    if (device->iscapture) {
         /* The idea is to take the capture media stream, hook it up to an
            audio graph where we can pass it through a ScriptProcessorNode
            to access the raw PCM samples and push them to the SDL app's
            callback. From there, we "process" the audio data into silence
-           and forget about it. */
+           and forget about it.
 
-        /* This should, strictly speaking, use MediaRecorder for capture, but
+           This should, strictly speaking, use MediaRecorder for capture, but
            this API is cleaner to use and better supported, and fires a
            callback whenever there's enough data to fire down into the app.
            The downside is that we are spending CPU time silencing a buffer
@@ -317,7 +247,7 @@ static int EMSCRIPTENAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devnam
                 //console.log('SDL audio capture: we DO NOT have a microphone! (' + error.name + ')...leaving silence callback running.');
             };
 
-            /* we write silence to the audio callback until the microphone is available (user approves use, etc). */
+            // we write silence to the audio callback until the microphone is available (user approves use, etc).
             SDL3.capture.silenceBuffer = SDL3.audioContext.createBuffer($0, $1, SDL3.audioContext.sampleRate);
             SDL3.capture.silenceBuffer.getChannelData(0).fill(0.0);
             var silence_callback = function() {
@@ -332,9 +262,9 @@ static int EMSCRIPTENAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devnam
             } else if (navigator.webkitGetUserMedia !== undefined) {
                 navigator.webkitGetUserMedia({ audio: true, video: false }, have_microphone, no_microphone);
             }
-        }, _this->spec.channels, _this->spec.samples, HandleCaptureProcess, _this);
+        }, device->spec.channels, device->sample_frames, HandleCaptureProcess, device);
     } else {
-        /* setup a ScriptProcessorNode */
+        // setup a ScriptProcessorNode
         MAIN_THREAD_EM_ASM({
             var SDL3 = Module['SDL3'];
             SDL3.audio.scriptProcessorNode = SDL3.audioContext['createScriptProcessor']($1, 0, $0);
@@ -344,33 +274,29 @@ static int EMSCRIPTENAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devnam
                 dynCall('vi', $2, [$3]);
             };
             SDL3.audio.scriptProcessorNode['connect'](SDL3.audioContext['destination']);
-        }, _this->spec.channels, _this->spec.samples, HandleAudioProcess, _this);
+        }, device->spec.channels, device->sample_frames, HandleAudioProcess, device);
     }
-/* *INDENT-ON* */ /* clang-format on */
 
     return 0;
 }
 
-static void EMSCRIPTENAUDIO_LockOrUnlockDeviceWithNoMixerLock(SDL_AudioDevice *device)
-{
-}
-
 static SDL_bool EMSCRIPTENAUDIO_Init(SDL_AudioDriverImpl *impl)
 {
     SDL_bool available, capture_available;
 
-    /* Set the function pointers */
     impl->OpenDevice = EMSCRIPTENAUDIO_OpenDevice;
     impl->CloseDevice = EMSCRIPTENAUDIO_CloseDevice;
+    impl->GetDeviceBuf = EMSCRIPTENAUDIO_GetDeviceBuf;
+    impl->PlayDevice = EMSCRIPTENAUDIO_PlayDevice;
+    impl->FlushCapture = EMSCRIPTENAUDIO_FlushCapture;
+    impl->CaptureFromDevice = EMSCRIPTENAUDIO_CaptureFromDevice;
 
     impl->OnlyHasDefaultOutputDevice = SDL_TRUE;
 
-    /* no threads here */
-    impl->LockDevice = impl->UnlockDevice = EMSCRIPTENAUDIO_LockOrUnlockDeviceWithNoMixerLock;
+    // technically, this is just runs in idle time in the main thread, but it's close enough to a "thread" for our purposes.
     impl->ProvidesOwnCallbackThread = SDL_TRUE;
 
-    /* *INDENT-OFF* */ /* clang-format off */
-    /* check availability */
+    // check availability
     available = MAIN_THREAD_EM_ASM_INT({
         if (typeof(AudioContext) !== 'undefined') {
             return true;
@@ -378,14 +304,12 @@ static SDL_bool EMSCRIPTENAUDIO_Init(SDL_AudioDriverImpl *impl)
             return true;
         }
         return false;
-    });
-/* *INDENT-ON* */ /* clang-format on */
+    }) ? SDL_TRUE : SDL_FALSE;
 
     if (!available) {
         SDL_SetError("No audio context available");
     }
 
-    /* *INDENT-OFF* */ /* clang-format off */
     capture_available = available && MAIN_THREAD_EM_ASM_INT({
         if ((typeof(navigator.mediaDevices) !== 'undefined') && (typeof(navigator.mediaDevices.getUserMedia) !== 'undefined')) {
             return true;
@@ -393,8 +317,7 @@ static SDL_bool EMSCRIPTENAUDIO_Init(SDL_AudioDriverImpl *impl)
             return true;
         }
         return false;
-    });
-/* *INDENT-ON* */ /* clang-format on */
+    }) ? SDL_TRUE : SDL_FALSE;
 
     impl->HasCaptureSupport = capture_available ? SDL_TRUE : SDL_FALSE;
     impl->OnlyHasDefaultCaptureDevice = capture_available ? SDL_TRUE : SDL_FALSE;
@@ -406,4 +329,6 @@ AudioBootStrap EMSCRIPTENAUDIO_bootstrap = {
     "emscripten", "SDL emscripten audio driver", EMSCRIPTENAUDIO_Init, SDL_FALSE
 };
 
-#endif /* SDL_AUDIO_DRIVER_EMSCRIPTEN */
+/* *INDENT-ON* */ /* clang-format on */
+
+#endif // SDL_AUDIO_DRIVER_EMSCRIPTEN

src/audio/emscripten/SDL_emscriptenaudio.h

@@ -27,7 +27,7 @@
 
 struct SDL_PrivateAudioData
 {
-    int unused;
+    Uint8 *mixbuf;
 };
 
 #endif /* SDL_emscriptenaudio_h_ */

src/audio/haiku/SDL_haikuaudio.cc

@@ -22,7 +22,7 @@
 
 #ifdef SDL_AUDIO_DRIVER_HAIKU
 
-/* Allow access to the audio stream on Haiku */
+// Allow access to the audio stream on Haiku
 
 #include <SoundPlayer.h>
 #include <signal.h>
@@ -38,58 +38,45 @@ extern "C"
 
 }
 
-
-/* !!! FIXME: have the callback call the higher level to avoid code dupe. */
-/* The Haiku callback for handling the audio buffer */
-static void FillSound(void *device, void *stream, size_t len,
-          const media_raw_audio_format & format)
+static Uint8 *HAIKUAUDIO_GetDeviceBuf(SDL_AudioDevice *device, int *buffer_size)
 {
-    SDL_AudioDevice *audio = (SDL_AudioDevice *) device;
-    SDL_AudioCallback callback = audio->callbackspec.callback;
-
-    SDL_LockMutex(audio->mixer_lock);
+    SDL_assert(device->hidden->current_buffer != NULL);
+    SDL_assert(device->hidden->current_buffer_len > 0);
+    *buffer_size = device->hidden->current_buffer_len;
+    return device->hidden->current_buffer;
+}
 
-    /* Only do something if audio is enabled */
-    if (!SDL_AtomicGet(&audio->enabled) || SDL_AtomicGet(&audio->paused)) {
-        if (audio->stream) {
-            SDL_ClearAudioStream(audio->stream);
-        }
-        SDL_memset(stream, audio->spec.silence, len);
-    } else {
-        SDL_assert(audio->spec.size == len);
-
-        if (audio->stream == NULL) {  /* no conversion necessary. */
-            callback(audio->callbackspec.userdata, (Uint8 *) stream, len);
-        } else {  /* streaming/converting */
-            const int stream_len = audio->callbackspec.size;
-            const int ilen = (int) len;
-            while (SDL_GetAudioStreamAvailable(audio->stream) < ilen) {
-                callback(audio->callbackspec.userdata, audio->work_buffer, stream_len);
-                if (SDL_PutAudioStreamData(audio->stream, audio->work_buffer, stream_len) == -1) {
-                    SDL_ClearAudioStream(audio->stream);
-                    SDL_AtomicSet(&audio->enabled, 0);
-                    break;
-                }
-            }
-
-            const int got = SDL_GetAudioStreamData(audio->stream, stream, ilen);
-            SDL_assert((got < 0) || (got == ilen));
-            if (got != ilen) {
-                SDL_memset(stream, audio->spec.silence, len);
-            }
-        }
-    }
+static void HAIKUAUDIO_PlayDevice(SDL_AudioDevice *device, const Uint8 *buffer, int buffer_size)
+{
+    // We already wrote our output right into the BSoundPlayer's callback's stream. Just clean up our stuff.
+    SDL_assert(device->hidden->current_buffer != NULL);
+    SDL_assert(device->hidden->current_buffer_len > 0);
+    device->hidden->current_buffer = NULL;
+    device->hidden->current_buffer_len = 0;
+}
 
-    SDL_UnlockMutex(audio->mixer_lock);
+// The Haiku callback for handling the audio buffer
+static void FillSound(void *data, void *stream, size_t len, const media_raw_audio_format & format)
+{
+    SDL_AudioDevice *device = (SDL_AudioDevice *)data;
+    SDL_assert(device->hidden->current_buffer == NULL);
+    SDL_assert(device->hidden->current_buffer_len == 0);
+    device->hidden->current_buffer = (Uint8 *) stream;
+    device->hidden->current_buffer_len = (int) len;
+    SDL_OutputAudioThreadIterate(device);
 }
 
-static void HAIKUAUDIO_CloseDevice(SDL_AudioDevice *_this)
+static void HAIKUAUDIO_CloseDevice(SDL_AudioDevice *device)
 {
-    if (_this->hidden->audio_obj) {
-        _this->hidden->audio_obj->Stop();
-        delete _this->hidden->audio_obj;
+    if (device->hidden) {
+        if (device->hidden->audio_obj) {
+            device->hidden->audio_obj->Stop();
+            delete device->hidden->audio_obj;
+        }
+        delete device->hidden;
+        device->hidden = NULL;
+        SDL_AudioThreadFinalize(device);
     }
-    delete _this->hidden;
 }
 
 
@@ -115,26 +102,24 @@ static inline void UnmaskSignals(sigset_t * omask)
 }
 
 
-static int HAIKUAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
+static int HAIKUAUDIO_OpenDevice(SDL_AudioDevice *device)
 {
-    media_raw_audio_format format;
-    SDL_AudioFormat test_format;
-    const SDL_AudioFormat *closefmts;
-
-    /* Initialize all variables that we clean on shutdown */
-    _this->hidden = new SDL_PrivateAudioData;
-    if (_this->hidden == NULL) {
+    // Initialize all variables that we clean on shutdown
+    device->hidden = new SDL_PrivateAudioData;
+    if (device->hidden == NULL) {
         return SDL_OutOfMemory();
     }
-    SDL_zerop(_this->hidden);
+    SDL_zerop(device->hidden);
 
-    /* Parse the audio format and fill the Be raw audio format */
+    // Parse the audio format and fill the Be raw audio format
+    media_raw_audio_format format;
     SDL_zero(format);
     format.byte_order = B_MEDIA_LITTLE_ENDIAN;
-    format.frame_rate = (float) _this->spec.freq;
-    format.channel_count = _this->spec.channels;        /* !!! FIXME: support > 2? */
+    format.frame_rate = (float) device->spec.freq;
+    format.channel_count = device->spec.channels;        // !!! FIXME: support > 2?
 
-    closefmts = SDL_ClosestAudioFormats(_this->spec.format);
+    SDL_AudioFormat test_format;
+    const SDL_AudioFormat *closefmts = SDL_ClosestAudioFormats(device->spec.format);
     while ((test_format = *(closefmts++)) != 0) {
         switch (test_format) {
         case SDL_AUDIO_S8:
@@ -178,31 +163,30 @@ static int HAIKUAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
         break;
     }
 
-    if (!test_format) {      /* shouldn't happen, but just in case... */
-        return SDL_SetError("%s: Unsupported audio format", "haiku");
+    if (!test_format) {      // shouldn't happen, but just in case...
+        return SDL_SetError("HAIKU: Unsupported audio format");
     }
-    _this->spec.format = test_format;
+    device->spec.format = test_format;
 
-    /* Calculate the final parameters for this audio specification */
-    SDL_CalculateAudioSpec(&_this->spec);
+    // Calculate the final parameters for this audio specification
+    SDL_UpdatedAudioDeviceFormat(device);
 
-    format.buffer_size = _this->spec.size;
+    format.buffer_size = device->buffer_size;
 
-    /* Subscribe to the audio stream (creates a new thread) */
+    // Subscribe to the audio stream (creates a new thread)
     sigset_t omask;
     MaskSignals(&omask);
-    _this->hidden->audio_obj = new BSoundPlayer(&format, "SDL Audio",
-                                                FillSound, NULL, _this);
+    device->hidden->audio_obj = new BSoundPlayer(&format, "SDL Audio",
+                                                FillSound, NULL, device);
     UnmaskSignals(&omask);
 
-    if (_this->hidden->audio_obj->Start() == B_NO_ERROR) {
-        _this->hidden->audio_obj->SetHasData(true);
+    if (device->hidden->audio_obj->Start() == B_NO_ERROR) {
+        device->hidden->audio_obj->SetHasData(true);
     } else {
-        return SDL_SetError("Unable to start Be audio");
+        return SDL_SetError("Unable to start Haiku audio");
     }
 
-    /* We're running! */
-    return 0;
+    return 0;  // We're running!
 }
 
 static void HAIKUAUDIO_Deinitialize(void)
@@ -210,29 +194,29 @@ static void HAIKUAUDIO_Deinitialize(void)
     SDL_QuitBeApp();
 }
 
-static SDL_bool HAIKUAUDIO_Init(SDL_AudioDriverImpl * impl)
+static SDL_bool HAIKUAUDIO_Init(SDL_AudioDriverImpl *impl)
 {
-    /* Initialize the Be Application, if it's not already started */
     if (SDL_InitBeApp() < 0) {
         return SDL_FALSE;
     }
 
-    /* Set the function pointers */
+    // Set the function pointers
     impl->OpenDevice = HAIKUAUDIO_OpenDevice;
+    impl->GetDeviceBuf = HAIKUAUDIO_GetDeviceBuf;
+    impl->PlayDevice = HAIKUAUDIO_PlayDevice;
     impl->CloseDevice = HAIKUAUDIO_CloseDevice;
     impl->Deinitialize = HAIKUAUDIO_Deinitialize;
     impl->ProvidesOwnCallbackThread = SDL_TRUE;
     impl->OnlyHasDefaultOutputDevice = SDL_TRUE;
 
-    return SDL_TRUE;   /* this audio target is available. */
+    return SDL_TRUE;
 }
 
-extern "C"
-{
-    extern AudioBootStrap HAIKUAUDIO_bootstrap;
-}
+
+extern "C" { extern AudioBootStrap HAIKUAUDIO_bootstrap; }
+
 AudioBootStrap HAIKUAUDIO_bootstrap = {
     "haiku", "Haiku BSoundPlayer", HAIKUAUDIO_Init, SDL_FALSE
 };
 
-#endif /* SDL_AUDIO_DRIVER_HAIKU */
+#endif // SDL_AUDIO_DRIVER_HAIKU

src/audio/haiku/SDL_haikuaudio.h

@@ -28,6 +28,8 @@
 struct SDL_PrivateAudioData
 {
     BSoundPlayer *audio_obj;
+    Uint8 *current_buffer;
+    int current_buffer_len;
 };
 
 #endif /* SDL_haikuaudio_h_ */

src/audio/jack/SDL_jackaudio.c

@@ -135,9 +135,7 @@ static int load_jack_syms(void)
 
 static void jackShutdownCallback(void *arg) /* JACK went away; device is lost. */
 {
-    SDL_AudioDevice *_this = (SDL_AudioDevice *)arg;
-    SDL_OpenedAudioDeviceDisconnected(_this);
-    SDL_PostSemaphore(_this->hidden->iosem); /* unblock the SDL thread. */
+    SDL_AudioDeviceDisconnected((SDL_AudioDevice *)arg);
 }
 
 // !!! FIXME: implement and register these!
@@ -146,124 +144,117 @@ static void jackShutdownCallback(void *arg) /* JACK went away; device is lost. *
 
 static int jackProcessPlaybackCallback(jack_nframes_t nframes, void *arg)
 {
-    SDL_AudioDevice *_this = (SDL_AudioDevice *)arg;
-    jack_port_t **ports = _this->hidden->sdlports;
-    const int total_channels = _this->spec.channels;
-    const int total_frames = _this->spec.samples;
-    int channelsi;
-
-    if (!SDL_AtomicGet(&_this->enabled)) {
-        /* silence the buffer to avoid repeats and corruption. */
-        SDL_memset(_this->hidden->iobuffer, '\0', _this->spec.size);
-    }
+    SDL_assert(nframes == ((SDL_AudioDevice *)arg)->sample_frames);
+    SDL_OutputAudioThreadIterate((SDL_AudioDevice *)arg);
+    return 0;
+}
+
+static void JACK_PlayDevice(SDL_AudioDevice *device, const Uint8 *ui8buffer, int buflen)
+{
+    const float *buffer = (float *) ui8buffer;
+    jack_port_t **ports = device->hidden->sdlports;
+    const int total_channels = device->spec.channels;
+    const int total_frames = device->sample_frames;
+    const jack_nframes_t nframes = (jack_nframes_t) device->sample_frames;
 
-    for (channelsi = 0; channelsi < total_channels; channelsi++) {
+    for (int channelsi = 0; channelsi < total_channels; channelsi++) {
         float *dst = (float *)JACK_jack_port_get_buffer(ports[channelsi], nframes);
         if (dst) {
-            const float *src = _this->hidden->iobuffer + channelsi;
-            int framesi;
-            for (framesi = 0; framesi < total_frames; framesi++) {
+            const float *src = buffer + channelsi;
+            for (int framesi = 0; framesi < total_frames; framesi++) {
                 *(dst++) = *src;
                 src += total_channels;
             }
         }
     }
-
-    SDL_PostSemaphore(_this->hidden->iosem); /* tell SDL thread we're done; refill the buffer. */
-    return 0;
 }
 
-/* This function waits until it is possible to write a full sound buffer */
-static void JACK_WaitDevice(SDL_AudioDevice *_this)
+static Uint8 *JACK_GetDeviceBuf(SDL_AudioDevice *device, int *buffer_size)
 {
-    if (SDL_AtomicGet(&_this->enabled)) {
-        if (SDL_WaitSemaphore(_this->hidden->iosem) == -1) {
-            SDL_OpenedAudioDeviceDisconnected(_this);
-        }
-    }
-}
-
-static Uint8 *JACK_GetDeviceBuf(SDL_AudioDevice *_this)
-{
-    return (Uint8 *)_this->hidden->iobuffer;
+    return (Uint8 *)device->hidden->iobuffer;
 }
 
 static int jackProcessCaptureCallback(jack_nframes_t nframes, void *arg)
 {
-    SDL_AudioDevice *_this = (SDL_AudioDevice *)arg;
-    if (SDL_AtomicGet(&_this->enabled)) {
-        jack_port_t **ports = _this->hidden->sdlports;
-        const int total_channels = _this->spec.channels;
-        const int total_frames = _this->spec.samples;
-        int channelsi;
-
-        for (channelsi = 0; channelsi < total_channels; channelsi++) {
-            const float *src = (const float *)JACK_jack_port_get_buffer(ports[channelsi], nframes);
-            if (src) {
-                float *dst = _this->hidden->iobuffer + channelsi;
-                int framesi;
-                for (framesi = 0; framesi < total_frames; framesi++) {
-                    *dst = *(src++);
-                    dst += total_channels;
-                }
-            }
-        }
-    }
-
-    SDL_PostSemaphore(_this->hidden->iosem); /* tell SDL thread we're done; new buffer is ready! */
+    SDL_assert(nframes == ((SDL_AudioDevice *)arg)->sample_frames);
+    SDL_CaptureAudioThreadIterate((SDL_AudioDevice *)arg);
     return 0;
 }
 
-static int JACK_CaptureFromDevice(SDL_AudioDevice *_this, void *buffer, int buflen)
+static int JACK_CaptureFromDevice(SDL_AudioDevice *device, void *vbuffer, int buflen)
 {
-    SDL_assert(buflen == _this->spec.size); /* we always fill a full buffer. */
-
-    /* Wait for JACK to fill the iobuffer */
-    if (SDL_WaitSemaphore(_this->hidden->iosem) == -1) {
-        return -1;
+    float *buffer = (float *) vbuffer;
+    jack_port_t **ports = device->hidden->sdlports;
+    const int total_channels = device->spec.channels;
+    const int total_frames = device->sample_frames;
+    const jack_nframes_t nframes = (jack_nframes_t) device->sample_frames;
+
+    for (int channelsi = 0; channelsi < total_channels; channelsi++) {
+        const float *src = (const float *)JACK_jack_port_get_buffer(ports[channelsi], nframes);
+        if (src) {
+            float *dst = buffer + channelsi;
+            for (int framesi = 0; framesi < total_frames; framesi++) {
+                *dst = *(src++);
+                dst += total_channels;
+            }
+        }
     }
 
-    SDL_memcpy(buffer, _this->hidden->iobuffer, buflen);
     return buflen;
 }
 
-static void JACK_FlushCapture(SDL_AudioDevice *_this)
+static void JACK_FlushCapture(SDL_AudioDevice *device)
 {
-    SDL_WaitSemaphore(_this->hidden->iosem);
+    // do nothing, the data will just be replaced next callback.
 }
 
-static void JACK_CloseDevice(SDL_AudioDevice *_this)
+static void JACK_CloseDevice(SDL_AudioDevice *device)
 {
-    if (_this->hidden->client) {
-        JACK_jack_deactivate(_this->hidden->client);
-
-        if (_this->hidden->sdlports) {
-            const int channels = _this->spec.channels;
-            int i;
-            for (i = 0; i < channels; i++) {
-                JACK_jack_port_unregister(_this->hidden->client, _this->hidden->sdlports[i]);
+    if (device->hidden) {
+        if (device->hidden->client) {
+            JACK_jack_deactivate(device->hidden->client);
+
+            if (device->hidden->sdlports) {
+                const int channels = device->spec.channels;
+                int i;
+                for (i = 0; i < channels; i++) {
+                    JACK_jack_port_unregister(device->hidden->client, device->hidden->sdlports[i]);
+                }
+                SDL_free(device->hidden->sdlports);
             }
-            SDL_free(_this->hidden->sdlports);
+
+            JACK_jack_client_close(device->hidden->client);
         }
 
-        JACK_jack_client_close(_this->hidden->client);
-    }
+        SDL_free(device->hidden->iobuffer);
+        SDL_free(device->hidden);
+        device->hidden = NULL;
 
-    if (_this->hidden->iosem) {
-        SDL_DestroySemaphore(_this->hidden->iosem);
+        SDL_AudioThreadFinalize(device);
     }
+}
 
-    SDL_free(_this->hidden->iobuffer);
-    SDL_free(_this->hidden);
+// !!! FIXME: unify this (PulseAudio has a getAppName, Pipewire has a thing, etc
+static const char *GetJackAppName(void)
+{
+    const char *retval = SDL_GetHint(SDL_HINT_AUDIO_DEVICE_APP_NAME);
+    if (retval && *retval) {
+        return retval;
+    }
+    retval = SDL_GetHint(SDL_HINT_APP_NAME);
+    if (retval && *retval) {
+        return retval;
+    }
+    return "SDL Application";
 }
 
-static int JACK_OpenDevice(SDL_AudioDevice *_this, const char *devname)
+static int JACK_OpenDevice(SDL_AudioDevice *device)
 {
     /* Note that JACK uses "output" for capture devices (they output audio
         data to us) and "input" for playback (we input audio data to them).
         Likewise, SDL's playback port will be "output" (we write data out)
         and capture will be "input" (we read data in). */
-    SDL_bool iscapture = _this->iscapture;
+    SDL_bool iscapture = device->iscapture;
     const unsigned long sysportflags = iscapture ? JackPortIsOutput : JackPortIsInput;
     const unsigned long sdlportflags = iscapture ? JackPortIsInput : JackPortIsOutput;
     const JackProcessCallback callback = iscapture ? jackProcessCaptureCallback : jackProcessPlaybackCallback;
@@ -277,14 +268,13 @@ static int JACK_OpenDevice(SDL_AudioDevice *_this, const char *devname)
     int i;
 
     /* Initialize all variables that we clean on shutdown */
-    _this->hidden = (struct SDL_PrivateAudioData *)SDL_calloc(1, sizeof(*_this->hidden));
-    if (_this->hidden == NULL) {
+    device->hidden = (struct SDL_PrivateAudioData *)SDL_calloc(1, sizeof(*device->hidden));
+    if (device->hidden == NULL) {
         return SDL_OutOfMemory();
     }
 
-    /* !!! FIXME: we _still_ need an API to specify an app name */
-    client = JACK_jack_client_open("SDL", JackNoStartServer, &status, NULL);
-    _this->hidden->client = client;
+    client = JACK_jack_client_open(GetJackAppName(), JackNoStartServer, &status, NULL);
+    device->hidden->client = client;
     if (client == NULL) {
         return SDL_SetError("Can't open JACK client");
     }
@@ -317,28 +307,24 @@ static int JACK_OpenDevice(SDL_AudioDevice *_this, const char *devname)
     /* !!! FIXME: docs say about buffer size: "This size may change, clients that depend on it must register a bufsize_callback so they will be notified if it does." */
 
     /* Jack pretty much demands what it wants. */
-    _this->spec.format = SDL_AUDIO_F32SYS;
-    _this->spec.freq = JACK_jack_get_sample_rate(client);
-    _this->spec.channels = channels;
-    _this->spec.samples = JACK_jack_get_buffer_size(client);
-
-    SDL_CalculateAudioSpec(&_this->spec);
+    device->spec.format = SDL_AUDIO_F32SYS;
+    device->spec.freq = JACK_jack_get_sample_rate(client);
+    device->spec.channels = channels;
+    device->sample_frames = JACK_jack_get_buffer_size(client);
 
-    _this->hidden->iosem = SDL_CreateSemaphore(0);
-    if (!_this->hidden->iosem) {
-        SDL_free(audio_ports);
-        return -1; /* error was set by SDL_CreateSemaphore */
-    }
+    SDL_UpdatedAudioDeviceFormat(device);
 
-    _this->hidden->iobuffer = (float *)SDL_calloc(1, _this->spec.size);
-    if (!_this->hidden->iobuffer) {
-        SDL_free(audio_ports);
-        return SDL_OutOfMemory();
+    if (!device->iscapture) {
+        device->hidden->iobuffer = (float *)SDL_calloc(1, device->buffer_size);
+        if (!device->hidden->iobuffer) {
+            SDL_free(audio_ports);
+            return SDL_OutOfMemory();
+        }
     }
 
     /* Build SDL's ports, which we will connect to the device ports. */
-    _this->hidden->sdlports = (jack_port_t **)SDL_calloc(channels, sizeof(jack_port_t *));
-    if (_this->hidden->sdlports == NULL) {
+    device->hidden->sdlports = (jack_port_t **)SDL_calloc(channels, sizeof(jack_port_t *));
+    if (device->hidden->sdlports == NULL) {
         SDL_free(audio_ports);
         return SDL_OutOfMemory();
     }
@@ -346,19 +332,19 @@ static int JACK_OpenDevice(SDL_AudioDevice *_this, const char *devname)
     for (i = 0; i < channels; i++) {
         char portname[32];
         (void)SDL_snprintf(portname, sizeof(portname), "sdl_jack_%s_%d", sdlportstr, i);
-        _this->hidden->sdlports[i] = JACK_jack_port_register(client, portname, JACK_DEFAULT_AUDIO_TYPE, sdlportflags, 0);
-        if (_this->hidden->sdlports[i] == NULL) {
+        device->hidden->sdlports[i] = JACK_jack_port_register(client, portname, JACK_DEFAULT_AUDIO_TYPE, sdlportflags, 0);
+        if (device->hidden->sdlports[i] == NULL) {
             SDL_free(audio_ports);
             return SDL_SetError("jack_port_register failed");
         }
     }
 
-    if (JACK_jack_set_process_callback(client, callback, _this) != 0) {
+    if (JACK_jack_set_process_callback(client, callback, device) != 0) {
         SDL_free(audio_ports);
         return SDL_SetError("JACK: Couldn't set process callback");
     }
 
-    JACK_jack_on_shutdown(client, jackShutdownCallback, _this);
+    JACK_jack_on_shutdown(client, jackShutdownCallback, device);
 
     if (JACK_jack_activate(client) != 0) {
         SDL_free(audio_ports);
@@ -367,7 +353,7 @@ static int JACK_OpenDevice(SDL_AudioDevice *_this, const char *devname)
 
     /* once activated, we can connect all the ports. */
     for (i = 0; i < channels; i++) {
-        const char *sdlport = JACK_jack_port_name(_this->hidden->sdlports[i]);
+        const char *sdlport = JACK_jack_port_name(device->hidden->sdlports[i]);
         const char *srcport = iscapture ? devports[audio_ports[i]] : sdlport;
         const char *dstport = iscapture ? sdlport : devports[audio_ports[i]];
         if (JACK_jack_connect(client, srcport, dstport) != 0) {
@@ -406,8 +392,8 @@ static SDL_bool JACK_Init(SDL_AudioDriverImpl *impl)
 
     /* Set the function pointers */
     impl->OpenDevice = JACK_OpenDevice;
-    impl->WaitDevice = JACK_WaitDevice;
     impl->GetDeviceBuf = JACK_GetDeviceBuf;
+    impl->PlayDevice = JACK_PlayDevice;
     impl->CloseDevice = JACK_CloseDevice;
     impl->Deinitialize = JACK_Deinitialize;
     impl->CaptureFromDevice = JACK_CaptureFromDevice;
@@ -415,6 +401,7 @@ static SDL_bool JACK_Init(SDL_AudioDriverImpl *impl)
     impl->OnlyHasDefaultOutputDevice = SDL_TRUE;
     impl->OnlyHasDefaultCaptureDevice = SDL_TRUE;
     impl->HasCaptureSupport = SDL_TRUE;
+    impl->ProvidesOwnCallbackThread = SDL_TRUE;
 
     return SDL_TRUE; /* this audio target is available. */
 }

src/audio/jack/SDL_jackaudio.h

@@ -28,9 +28,8 @@
 struct SDL_PrivateAudioData
 {
     jack_client_t *client;
-    SDL_Semaphore *iosem;
-    float *iobuffer;
     jack_port_t **sdlports;
+    float *iobuffer;
 };
 
 #endif /* SDL_jackaudio_h_ */

src/audio/n3ds/SDL_n3dsaudio.c

@@ -22,7 +22,7 @@
 
 #ifdef SDL_AUDIO_DRIVER_N3DS
 
-/* N3DS Audio driver */
+// N3DS Audio driver
 
 #include "../SDL_sysaudio.h"
 #include "SDL_n3dsaudio.h"
@@ -32,27 +32,14 @@
 static dspHookCookie dsp_hook;
 static SDL_AudioDevice *audio_device;
 
-static void FreePrivateData(SDL_AudioDevice *_this);
-static int FindAudioFormat(SDL_AudioDevice *_this);
-
-static SDL_INLINE void contextLock(SDL_AudioDevice *_this)
-{
-    LightLock_Lock(&_this->hidden->lock);
-}
-
-static SDL_INLINE void contextUnlock(SDL_AudioDevice *_this)
+static SDL_INLINE void contextLock(SDL_AudioDevice *device)
 {
-    LightLock_Unlock(&_this->hidden->lock);
+    LightLock_Lock(&device->hidden->lock);
 }
 
-static void N3DSAUD_LockAudio(SDL_AudioDevice *_this)
+static SDL_INLINE void contextUnlock(SDL_AudioDevice *device)
 {
-    contextLock(_this);
-}
-
-static void N3DSAUD_UnlockAudio(SDL_AudioDevice *_this)
-{
-    contextUnlock(_this);
+    LightLock_Unlock(&device->hidden->lock);
 }
 
 static void N3DSAUD_DspHook(DSP_HookType hook)
@@ -60,46 +47,46 @@ static void N3DSAUD_DspHook(DSP_HookType hook)
     if (hook == DSPHOOK_ONCANCEL) {
         contextLock(audio_device);
         audio_device->hidden->isCancelled = SDL_TRUE;
-        SDL_AtomicSet(&audio_device->enabled, SDL_FALSE);
+        SDL_AudioDeviceDisconnected(audio_device);
         CondVar_Broadcast(&audio_device->hidden->cv);
         contextUnlock(audio_device);
     }
 }
 
-static void AudioFrameFinished(void *device)
+static void AudioFrameFinished(void *vdevice)
 {
     bool shouldBroadcast = false;
     unsigned i;
-    SDL_AudioDevice *_this = (SDL_AudioDevice *)device;
+    SDL_AudioDevice *device = (SDL_AudioDevice *)vdevice;
 
-    contextLock(_this);
+    contextLock(device);
 
     for (i = 0; i < NUM_BUFFERS; i++) {
-        if (_this->hidden->waveBuf[i].status == NDSP_WBUF_DONE) {
-            _this->hidden->waveBuf[i].status = NDSP_WBUF_FREE;
+        if (device->hidden->waveBuf[i].status == NDSP_WBUF_DONE) {
+            device->hidden->waveBuf[i].status = NDSP_WBUF_FREE;
             shouldBroadcast = SDL_TRUE;
         }
     }
 
     if (shouldBroadcast) {
-        CondVar_Broadcast(&_this->hidden->cv);
+        CondVar_Broadcast(&device->hidden->cv);
     }
 
-    contextUnlock(_this);
+    contextUnlock(device);
 }
 
-static int N3DSAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
+static int N3DSAUDIO_OpenDevice(SDL_AudioDevice *device)
 {
     Result ndsp_init_res;
     Uint8 *data_vaddr;
     float mix[12];
-    _this->hidden = (struct SDL_PrivateAudioData *)SDL_calloc(1, sizeof(*_this->hidden));
 
-    if (_this->hidden == NULL) {
+    device->hidden = (struct SDL_PrivateAudioData *)SDL_calloc(1, sizeof(*device->hidden));
+    if (device->hidden == NULL) {
         return SDL_OutOfMemory();
     }
 
-    /* Initialise the DSP service */
+    // Initialise the DSP service
     ndsp_init_res = ndspInit();
     if (R_FAILED(ndsp_init_res)) {
         if ((R_SUMMARY(ndsp_init_res) == RS_NOTFOUND) && (R_MODULE(ndsp_init_res) == RM_DSP)) {
@@ -110,173 +97,180 @@ static int N3DSAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
         return -1;
     }
 
-    /* Initialise internal state */
-    LightLock_Init(&_this->hidden->lock);
-    CondVar_Init(&_this->hidden->cv);
+    // Initialise internal state
+    LightLock_Init(&device->hidden->lock);
+    CondVar_Init(&device->hidden->cv);
 
-    if (_this->spec.channels > 2) {
-        _this->spec.channels = 2;
+    if (device->spec.channels > 2) {
+        device->spec.channels = 2;
     }
 
-    /* Should not happen but better be safe. */
-    if (FindAudioFormat(_this) < 0) {
+    Uint32 format = 0;
+    SDL_AudioFormat test_format;
+    const SDL_AudioFormat *closefmts = SDL_ClosestAudioFormats(device->spec.format);
+    while ((test_format = *(closefmts++)) != 0) {
+        if (test_format == SDL_AUDIO_S8) {  // Signed 8-bit audio supported
+            format = (device->spec.channels == 2) ? NDSP_FORMAT_STEREO_PCM8 : NDSP_FORMAT_MONO_PCM8;
+            break;
+        } else if (test_format == SDL_AUDIO_S16) {  // Signed 16-bit audio supported
+            format = (device->spec.channels == 2) ? NDSP_FORMAT_STEREO_PCM16 : NDSP_FORMAT_MONO_PCM16;
+            break;
+        }
+    }
+
+    if (!test_format) {      // shouldn't happen, but just in case...
         return SDL_SetError("No supported audio format found.");
     }
 
-    /* Update the fragment size as size in bytes */
-    SDL_CalculateAudioSpec(&_this->spec);
+    device->spec.format = test_format;
+
+    // Update the fragment size as size in bytes
+    SDL_UpdatedAudioDeviceFormat(device);
 
-    /* Allocate mixing buffer */
-    if (_this->spec.size >= SDL_MAX_UINT32 / 2) {
+    // Allocate mixing buffer
+    if (device->buffer_size >= SDL_MAX_UINT32 / 2) {
         return SDL_SetError("Mixing buffer is too large.");
     }
 
-    _this->hidden->mixlen = _this->spec.size;
-    _this->hidden->mixbuf = (Uint8 *)SDL_malloc(_this->spec.size);
-    if (_this->hidden->mixbuf == NULL) {
+    device->hidden->mixbuf = (Uint8 *)SDL_malloc(device->buffer_size);
+    if (device->hidden->mixbuf == NULL) {
         return SDL_OutOfMemory();
     }
 
-    SDL_memset(_this->hidden->mixbuf, _this->spec.silence, _this->spec.size);
+    SDL_memset(device->hidden->mixbuf, device->silence_value, device->buffer_size);
 
-    data_vaddr = (Uint8 *)linearAlloc(_this->hidden->mixlen * NUM_BUFFERS);
+    data_vaddr = (Uint8 *)linearAlloc(device->buffer_size * NUM_BUFFERS);
     if (data_vaddr == NULL) {
         return SDL_OutOfMemory();
     }
 
-    SDL_memset(data_vaddr, 0, _this->hidden->mixlen * NUM_BUFFERS);
-    DSP_FlushDataCache(data_vaddr, _this->hidden->mixlen * NUM_BUFFERS);
+    SDL_memset(data_vaddr, 0, device->buffer_size * NUM_BUFFERS);
+    DSP_FlushDataCache(data_vaddr, device->buffer_size * NUM_BUFFERS);
 
-    _this->hidden->nextbuf = 0;
-    _this->hidden->channels = _this->spec.channels;
-    _this->hidden->samplerate = _this->spec.freq;
+    device->hidden->nextbuf = 0;
 
     ndspChnReset(0);
 
     ndspChnSetInterp(0, NDSP_INTERP_LINEAR);
-    ndspChnSetRate(0, _this->spec.freq);
-    ndspChnSetFormat(0, _this->hidden->format);
+    ndspChnSetRate(0, device->spec.freq);
+    ndspChnSetFormat(0, format);
 
-    SDL_memset(mix, 0, sizeof(mix));
-    mix[0] = 1.0;
-    mix[1] = 1.0;
+    SDL_zeroa(mix);
+    mix[0] = mix[1] = 1.0f;
     ndspChnSetMix(0, mix);
 
-    SDL_memset(_this->hidden->waveBuf, 0, sizeof(ndspWaveBuf) * NUM_BUFFERS);
+    SDL_memset(device->hidden->waveBuf, 0, sizeof(ndspWaveBuf) * NUM_BUFFERS);
 
+    const int sample_frame_size = device->spec.channels * (SDL_AUDIO_BITSIZE(device->spec.format) / 8);
     for (unsigned i = 0; i < NUM_BUFFERS; i++) {
-        _this->hidden->waveBuf[i].data_vaddr = data_vaddr;
-        _this->hidden->waveBuf[i].nsamples = _this->hidden->mixlen / _this->hidden->bytePerSample;
-        data_vaddr += _this->hidden->mixlen;
+        device->hidden->waveBuf[i].data_vaddr = data_vaddr;
+        device->hidden->waveBuf[i].nsamples = device->buffer_size / sample_frame_size;
+        data_vaddr += device->buffer_size;
     }
 
-    /* Setup callback */
-    audio_device = _this;
-    ndspSetCallback(AudioFrameFinished, _this);
+    // Setup callback
+    audio_device = device;
+    ndspSetCallback(AudioFrameFinished, device);
     dspHook(&dsp_hook, N3DSAUD_DspHook);
 
     return 0;
 }
 
-static int N3DSAUDIO_CaptureFromDevice(SDL_AudioDevice *_this, void *buffer, int buflen)
-{
-    /* Delay to make this sort of simulate real audio input. */
-    SDL_Delay((_this->spec.samples * 1000) / _this->spec.freq);
-
-    /* always return a full buffer of silence. */
-    SDL_memset(buffer, _this->spec.silence, buflen);
-    return buflen;
-}
-
-static void N3DSAUDIO_PlayDevice(SDL_AudioDevice *_this)
+static void N3DSAUDIO_PlayDevice(SDL_AudioDevice *device, const Uint8 *buffer, int buflen)
 {
-    size_t nextbuf;
-    size_t sampleLen;
-    contextLock(_this);
+    contextLock(device);
 
-    nextbuf = _this->hidden->nextbuf;
-    sampleLen = _this->hidden->mixlen;
+    const size_t nextbuf = device->hidden->nextbuf;
 
-    if (_this->hidden->isCancelled ||
-        _this->hidden->waveBuf[nextbuf].status != NDSP_WBUF_FREE) {
-        contextUnlock(_this);
+    if (device->hidden->isCancelled ||
+        device->hidden->waveBuf[nextbuf].status != NDSP_WBUF_FREE) {
+        contextUnlock(device);
         return;
     }
 
-    _this->hidden->nextbuf = (nextbuf + 1) % NUM_BUFFERS;
+    device->hidden->nextbuf = (nextbuf + 1) % NUM_BUFFERS;
 
-    contextUnlock(_this);
+    contextUnlock(device);
 
-    SDL_memcpy((void *)_this->hidden->waveBuf[nextbuf].data_vaddr,
-           _this->hidden->mixbuf, sampleLen);
-    DSP_FlushDataCache(_this->hidden->waveBuf[nextbuf].data_vaddr, sampleLen);
+    SDL_memcpy((void *)device->hidden->waveBuf[nextbuf].data_vaddr, buffer, buflen);
+    DSP_FlushDataCache(device->hidden->waveBuf[nextbuf].data_vaddr, buflen);
 
-    ndspChnWaveBufAdd(0, &_this->hidden->waveBuf[nextbuf]);
+    ndspChnWaveBufAdd(0, &device->hidden->waveBuf[nextbuf]);
 }
 
-static void N3DSAUDIO_WaitDevice(SDL_AudioDevice *_this)
+static void N3DSAUDIO_WaitDevice(SDL_AudioDevice *device)
 {
-    contextLock(_this);
-    while (!_this->hidden->isCancelled &&
-           _this->hidden->waveBuf[_this->hidden->nextbuf].status != NDSP_WBUF_FREE) {
-        CondVar_Wait(&_this->hidden->cv, &_this->hidden->lock);
+    contextLock(device);
+    while (!device->hidden->isCancelled && !SDL_AtomicGet(&device->shutdown) &&
+           device->hidden->waveBuf[device->hidden->nextbuf].status != NDSP_WBUF_FREE) {
+        CondVar_Wait(&device->hidden->cv, &device->hidden->lock);
     }
-    contextUnlock(_this);
+    contextUnlock(device);
 }
 
-static Uint8 *N3DSAUDIO_GetDeviceBuf(SDL_AudioDevice *_this)
+static Uint8 *N3DSAUDIO_GetDeviceBuf(SDL_AudioDevice *device, int *buffer_size)
 {
-    return _this->hidden->mixbuf;
+    return device->hidden->mixbuf;
 }
 
-static void N3DSAUDIO_CloseDevice(SDL_AudioDevice *_this)
+static void N3DSAUDIO_CloseDevice(SDL_AudioDevice *device)
 {
-    contextLock(_this);
+    if (!device->hidden) {
+        return;
+    }
+
+    contextLock(device);
 
     dspUnhook(&dsp_hook);
     ndspSetCallback(NULL, NULL);
 
-    if (!_this->hidden->isCancelled) {
+    if (!device->hidden->isCancelled) {
         ndspChnReset(0);
-        SDL_memset(_this->hidden->waveBuf, 0, sizeof(ndspWaveBuf) * NUM_BUFFERS);
-        CondVar_Broadcast(&_this->hidden->cv);
+        SDL_memset(device->hidden->waveBuf, 0, sizeof(ndspWaveBuf) * NUM_BUFFERS);
+        CondVar_Broadcast(&device->hidden->cv);
     }
 
-    contextUnlock(_this);
+    contextUnlock(device);
 
     ndspExit();
 
-    FreePrivateData(_this);
+    if (device->hidden->waveBuf[0].data_vaddr) {
+        linearFree((void *)device->hidden->waveBuf[0].data_vaddr);
+    }
+
+    if (device->hidden->mixbuf) {
+        SDL_free(device->hidden->mixbuf);
+        device->hidden->mixbuf = NULL;
+    }
+
+    SDL_free(device->hidden);
+    device->hidden = NULL;
 }
 
-static void N3DSAUDIO_ThreadInit(SDL_AudioDevice *_this)
+static void N3DSAUDIO_ThreadInit(SDL_AudioDevice *device)
 {
     s32 current_priority;
     svcGetThreadPriority(&current_priority, CUR_THREAD_HANDLE);
     current_priority--;
-    /* 0x18 is reserved for video, 0x30 is the default for main thread */
+    // 0x18 is reserved for video, 0x30 is the default for main thread
     current_priority = SDL_clamp(current_priority, 0x19, 0x2F);
     svcSetThreadPriority(CUR_THREAD_HANDLE, current_priority);
 }
 
 static SDL_bool N3DSAUDIO_Init(SDL_AudioDriverImpl *impl)
 {
-    /* Set the function pointers */
     impl->OpenDevice = N3DSAUDIO_OpenDevice;
     impl->PlayDevice = N3DSAUDIO_PlayDevice;
     impl->WaitDevice = N3DSAUDIO_WaitDevice;
     impl->GetDeviceBuf = N3DSAUDIO_GetDeviceBuf;
     impl->CloseDevice = N3DSAUDIO_CloseDevice;
     impl->ThreadInit = N3DSAUDIO_ThreadInit;
-    impl->LockDevice = N3DSAUD_LockAudio;
-    impl->UnlockDevice = N3DSAUD_UnlockAudio;
     impl->OnlyHasDefaultOutputDevice = SDL_TRUE;
 
-    /* Should be possible, but micInit would fail */
+    // Should be possible, but micInit would fail
     impl->HasCaptureSupport = SDL_FALSE;
-    impl->CaptureFromDevice = N3DSAUDIO_CaptureFromDevice;
 
-    return SDL_TRUE; /* this audio target is available. */
+    return SDL_TRUE;
 }
 
 AudioBootStrap N3DSAUDIO_bootstrap = {
@@ -286,51 +280,4 @@ AudioBootStrap N3DSAUDIO_bootstrap = {
     0
 };
 
-/**
- * Cleans up all allocated memory, safe to call with null pointers
- */
-static void FreePrivateData(SDL_AudioDevice *_this)
-{
-    if (!_this->hidden) {
-        return;
-    }
-
-    if (_this->hidden->waveBuf[0].data_vaddr) {
-        linearFree((void *)_this->hidden->waveBuf[0].data_vaddr);
-    }
-
-    if (_this->hidden->mixbuf) {
-        SDL_free(_this->hidden->mixbuf);
-        _this->hidden->mixbuf = NULL;
-    }
-
-    SDL_free(_this->hidden);
-    _this->hidden = NULL;
-}
-
-static int FindAudioFormat(SDL_AudioDevice *_this)
-{
-    SDL_AudioFormat test_format;
-    const SDL_AudioFormat *closefmts = SDL_ClosestAudioFormats(_this->spec.format);
-    while ((test_format = *(closefmts++)) != 0) {
-        _this->spec.format = test_format;
-        switch (test_format) {
-        case SDL_AUDIO_S8:
-            /* Signed 8-bit audio supported */
-            _this->hidden->format = (_this->spec.channels == 2) ? NDSP_FORMAT_STEREO_PCM8 : NDSP_FORMAT_MONO_PCM8;
-            _this->hidden->isSigned = 1;
-            _this->hidden->bytePerSample = _this->spec.channels;
-            return 0;
-        case SDL_AUDIO_S16:
-            /* Signed 16-bit audio supported */
-            _this->hidden->format = (_this->spec.channels == 2) ? NDSP_FORMAT_STEREO_PCM16 : NDSP_FORMAT_MONO_PCM16;
-            _this->hidden->isSigned = 1;
-            _this->hidden->bytePerSample = _this->spec.channels * 2;
-            return 0;
-        }
-    }
-
-    return -1;
-}
-
-#endif /* SDL_AUDIO_DRIVER_N3DS */
+#endif // SDL_AUDIO_DRIVER_N3DS

src/audio/n3ds/SDL_n3dsaudio.h

@@ -30,12 +30,6 @@ struct SDL_PrivateAudioData
 {
     /* Speaker data */
     Uint8 *mixbuf;
-    Uint32 mixlen;
-    Uint32 format;
-    Uint32 samplerate;
-    Uint32 channels;
-    Uint8 bytePerSample;
-    Uint32 isSigned;
     Uint32 nextbuf;
     ndspWaveBuf waveBuf[NUM_BUFFERS];
     LightLock lock;

src/audio/netbsd/SDL_netbsdaudio.c

@@ -22,10 +22,7 @@
 
 #ifdef SDL_AUDIO_DRIVER_NETBSD
 
-/*
- * Driver for native NetBSD audio(4).
- * nia@NetBSD.org
- */
+// Driver for native NetBSD audio(4).
 
 #include <errno.h>
 #include <unistd.h>
@@ -41,26 +38,26 @@
 #include "../SDL_audiodev_c.h"
 #include "SDL_netbsdaudio.h"
 
-/* #define DEBUG_AUDIO */
+//#define DEBUG_AUDIO
 
-static void NETBSDAUDIO_DetectDevices(void)
+static void NETBSDAUDIO_DetectDevices(SDL_AudioDevice **default_output, SDL_AudioDevice **default_capture)
 {
-    SDL_EnumUnixAudioDevices(0, NULL);
+    SDL_EnumUnixAudioDevices(SDL_FALSE, NULL);
 }
 
-static void NETBSDAUDIO_Status(SDL_AudioDevice *_this)
+static void NETBSDAUDIO_Status(SDL_AudioDevice *device)
 {
 #ifdef DEBUG_AUDIO
     /* *INDENT-OFF* */ /* clang-format off */
     audio_info_t info;
     const struct audio_prinfo *prinfo;
 
-    if (ioctl(_this->hidden->audio_fd, AUDIO_GETINFO, &info) < 0) {
+    if (ioctl(device->hidden->audio_fd, AUDIO_GETINFO, &info) < 0) {
         fprintf(stderr, "AUDIO_GETINFO failed.\n");
         return;
     }
 
-    prinfo = _this->iscapture ? &info.record : &info.play;
+    prinfo = device->iscapture ? &info.record : &info.play;
 
     fprintf(stderr, "\n"
             "[%s info]\n"
@@ -77,7 +74,7 @@ static void NETBSDAUDIO_Status(SDL_AudioDevice *_this)
             "waiting		:   %s\n"
             "active		:   %s\n"
             "",
-            _this->iscapture ? "record" : "play",
+            device->iscapture ? "record" : "play",
             prinfo->buffer_size,
             prinfo->sample_rate,
             prinfo->channels,
@@ -103,7 +100,7 @@ static void NETBSDAUDIO_Status(SDL_AudioDevice *_this)
             info.blocksize,
             info.hiwat, info.lowat,
             (info.mode == AUMODE_PLAY) ? "PLAY"
-            : (info.mode = AUMODE_RECORD) ? "RECORD"
+            : (info.mode == AUMODE_RECORD) ? "RECORD"
             : (info.mode == AUMODE_PLAY_ALL ? "PLAY_ALL" : "?"));
 
     fprintf(stderr, "\n"
@@ -111,23 +108,46 @@ static void NETBSDAUDIO_Status(SDL_AudioDevice *_this)
             "format		:   0x%x\n"
             "size		:   %u\n"
             "",
-            _this->spec.format,
-            _this->spec.size);
+            device->spec.format,
+            device->buffer_size);
     /* *INDENT-ON* */ /* clang-format on */
 
-#endif /* DEBUG_AUDIO */
+#endif // DEBUG_AUDIO
 }
 
-static void NETBSDAUDIO_PlayDevice(SDL_AudioDevice *_this)
+static void NETBSDAUDIO_WaitDevice(SDL_AudioDevice *device)
 {
-    struct SDL_PrivateAudioData *h = _this->hidden;
-    int written;
+    const SDL_bool iscapture = device->iscapture;
+    while (!SDL_AtomicGet(&device->shutdown)) {
+        audio_info_t info;
+        const int rc = ioctl(device->hidden->audio_fd, AUDIO_GETINFO, &info);
+        if (rc < 0) {
+            if (errno == EAGAIN) {
+                continue;
+            }
+            // Hmm, not much we can do - abort
+            fprintf(stderr, "netbsdaudio WaitDevice ioctl failed (unrecoverable): %s\n", strerror(errno));
+            SDL_AudioDeviceDisconnected(device);
+            return;
+        }
+        const size_t remain = (size_t)((iscapture ? info.record.seek : info.play.seek) * (SDL_AUDIO_BITSIZE(device->spec.format) / 8));
+        if (!iscapture && (remain >= device->buffer_size)) {
+            SDL_Delay(10);
+        } else if (iscapture && (remain < device->buffer_size)) {
+            SDL_Delay(10);
+        } else {
+            break; /* ready to go! */
+        }
+    }
+}
 
-    /* Write the audio data */
-    written = write(h->audio_fd, h->mixbuf, h->mixlen);
+static void NETBSDAUDIO_PlayDevice(SDL_AudioDevice *device, const Uint8 *buffer, int buflen)
+{
+    struct SDL_PrivateAudioData *h = device->hidden;
+    const int written = write(h->audio_fd, buffer, buflen);
     if (written == -1) {
-        /* Non recoverable error has occurred. It should be reported!!! */
-        SDL_OpenedAudioDeviceDisconnected(_this);
+        // Non recoverable error has occurred. It should be reported!!!
+        SDL_AudioDeviceDisconnected(device);
         perror("audio");
         return;
     }
@@ -137,19 +157,17 @@ static void NETBSDAUDIO_PlayDevice(SDL_AudioDevice *_this)
 #endif
 }
 
-static Uint8 *NETBSDAUDIO_GetDeviceBuf(SDL_AudioDevice *_this)
+static Uint8 *NETBSDAUDIO_GetDeviceBuf(SDL_AudioDevice *device, int *buffer_size)
 {
-    return _this->hidden->mixbuf;
+    return device->hidden->mixbuf;
 }
 
-static int NETBSDAUDIO_CaptureFromDevice(SDL_AudioDevice *_this, void *_buffer, int buflen)
+static int NETBSDAUDIO_CaptureFromDevice(SDL_AudioDevice *device, void *vbuffer, int buflen)
 {
-    Uint8 *buffer = (Uint8 *)_buffer;
-    int br;
-
-    br = read(_this->hidden->audio_fd, buffer, buflen);
+    Uint8 *buffer = (Uint8 *)vbuffer;
+    const int br = read(device->hidden->audio_fd, buffer, buflen);
     if (br == -1) {
-        /* Non recoverable error has occurred. It should be reported!!! */
+        // Non recoverable error has occurred. It should be reported!!!
         perror("audio");
         return -1;
     }
@@ -157,86 +175,73 @@ static int NETBSDAUDIO_CaptureFromDevice(SDL_AudioDevice *_this, void *_buffer,
 #ifdef DEBUG_AUDIO
     fprintf(stderr, "Captured %d bytes of audio data\n", br);
 #endif
-    return 0;
+    return br;
 }
 
-static void NETBSDAUDIO_FlushCapture(SDL_AudioDevice *_this)
+static void NETBSDAUDIO_FlushCapture(SDL_AudioDevice *device)
 {
+    struct SDL_PrivateAudioData *h = device->hidden;
     audio_info_t info;
-    size_t remain;
-    Uint8 buf[512];
-
-    if (ioctl(_this->hidden->audio_fd, AUDIO_GETINFO, &info) < 0) {
-        return; /* oh well. */
-    }
-
-    remain = (size_t)(info.record.samples * (SDL_AUDIO_BITSIZE(_this->spec.format) / 8));
-    while (remain > 0) {
-        const size_t len = SDL_min(sizeof(buf), remain);
-        const int br = read(_this->hidden->audio_fd, buf, len);
-        if (br <= 0) {
-            return; /* oh well. */
+    if (ioctl(device->hidden->audio_fd, AUDIO_GETINFO, &info) == 0) {
+        size_t remain = (size_t)(info.record.seek * (SDL_AUDIO_BITSIZE(device->spec.format) / 8));
+        while (remain > 0) {
+            char buf[512];
+            const size_t len = SDL_min(sizeof(buf), remain);
+            const ssize_t br = read(h->audio_fd, buf, len);
+            if (br <= 0) {
+                break;
+            }
+            remain -= br;
         }
-        remain -= br;
     }
 }
 
-static void NETBSDAUDIO_CloseDevice(SDL_AudioDevice *_this)
+static void NETBSDAUDIO_CloseDevice(SDL_AudioDevice *device)
 {
-    if (_this->hidden->audio_fd >= 0) {
-        close(_this->hidden->audio_fd);
+    if (device->hidden) {
+        if (device->hidden->audio_fd >= 0) {
+            close(device->hidden->audio_fd);
+        }
+        SDL_free(device->hidden->mixbuf);
+        SDL_free(device->hidden);
+        device->hidden = NULL;
     }
-    SDL_free(_this->hidden->mixbuf);
-    SDL_free(_this->hidden);
 }
 
-static int NETBSDAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
+static int NETBSDAUDIO_OpenDevice(SDL_AudioDevice *device)
 {
-    SDL_bool iscapture = _this->iscapture;
-    SDL_AudioFormat test_format;
-    const SDL_AudioFormat *closefmts;
+    const SDL_bool iscapture = device->iscapture;
     int encoding = AUDIO_ENCODING_NONE;
     audio_info_t info, hwinfo;
     struct audio_prinfo *prinfo = iscapture ? &info.record : &info.play;
 
-    /* We don't care what the devname is...we'll try to open anything. */
-    /*  ...but default to first name in the list... */
-    if (devname == NULL) {
-        devname = SDL_GetAudioDeviceName(0, iscapture);
-        if (devname == NULL) {
-            return SDL_SetError("No such audio device");
-        }
-    }
-
-    /* Initialize all variables that we clean on shutdown */
-    _this->hidden = (struct SDL_PrivateAudioData *) SDL_malloc(sizeof(*_this->hidden));
-    if (_this->hidden == NULL) {
+    // Initialize all variables that we clean on shutdown
+    device->hidden = (struct SDL_PrivateAudioData *) SDL_calloc(1, sizeof(*device->hidden));
+    if (device->hidden == NULL) {
         return SDL_OutOfMemory();
     }
-    SDL_zerop(_this->hidden);
 
-    /* Open the audio device */
-    _this->hidden->audio_fd = open(devname, (iscapture ? O_RDONLY : O_WRONLY) | O_CLOEXEC);
-    if (_this->hidden->audio_fd < 0) {
-        return SDL_SetError("Couldn't open %s: %s", devname, strerror(errno));
+    // Open the audio device; we hardcode the device path in `device->name` for lack of better info, so use that.
+    const int flags = ((device->iscapture) ? O_RDONLY : O_WRONLY);
+    device->hidden->audio_fd = open(device->name, flags | O_CLOEXEC);
+    if (device->hidden->audio_fd < 0) {
+        return SDL_SetError("Couldn't open %s: %s", device->name, strerror(errno));
     }
 
     AUDIO_INITINFO(&info);
 
-#ifdef AUDIO_GETFORMAT /* Introduced in NetBSD 9.0 */
-    if (ioctl(_this->hidden->audio_fd, AUDIO_GETFORMAT, &hwinfo) != -1) {
-        /*
-         * Use the device's native sample rate so the kernel doesn't have to
-         * resample.
-         */
-        _this->spec.freq = iscapture ? hwinfo.record.sample_rate : hwinfo.play.sample_rate;
+#ifdef AUDIO_GETFORMAT // Introduced in NetBSD 9.0
+    if (ioctl(device->hidden->audio_fd, AUDIO_GETFORMAT, &hwinfo) != -1) {
+        // Use the device's native sample rate so the kernel doesn't have to resample.
+        device->spec.freq = iscapture ? hwinfo.record.sample_rate : hwinfo.play.sample_rate;
     }
 #endif
 
-    prinfo->sample_rate = _this->spec.freq;
-    prinfo->channels = _this->spec.channels;
+    prinfo->sample_rate = device->spec.freq;
+    prinfo->channels = device->spec.channels;
 
-    closefmts = SDL_ClosestAudioFormats(_this->spec.format);
+    SDL_AudioFormat test_format;
+    const SDL_AudioFormat *closefmts = SDL_ClosestAudioFormats(device->spec.format);
     while ((test_format = *(closefmts++)) != 0) {
         switch (test_format) {
         case SDL_AUDIO_U8:
@@ -271,56 +276,56 @@ static int NETBSDAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
 
     info.hiwat = 5;
     info.lowat = 3;
-    if (ioctl(_this->hidden->audio_fd, AUDIO_SETINFO, &info) < 0) {
-        return SDL_SetError("AUDIO_SETINFO failed for %s: %s", devname, strerror(errno));
+    if (ioctl(device->hidden->audio_fd, AUDIO_SETINFO, &info) < 0) {
+        return SDL_SetError("AUDIO_SETINFO failed for %s: %s", device->name, strerror(errno));
     }
 
-    if (ioctl(_this->hidden->audio_fd, AUDIO_GETINFO, &info) < 0) {
-        return SDL_SetError("AUDIO_GETINFO failed for %s: %s", devname, strerror(errno));
+    if (ioctl(device->hidden->audio_fd, AUDIO_GETINFO, &info) < 0) {
+        return SDL_SetError("AUDIO_GETINFO failed for %s: %s", device->name, strerror(errno));
     }
 
-    /* Final spec used for the device. */
-    _this->spec.format = test_format;
-    _this->spec.freq = prinfo->sample_rate;
-    _this->spec.channels = prinfo->channels;
+    // Final spec used for the device.
+    device->spec.format = test_format;
+    device->spec.freq = prinfo->sample_rate;
+    device->spec.channels = prinfo->channels;
 
-    SDL_CalculateAudioSpec(&_this->spec);
+    SDL_UpdatedAudioDeviceFormat(device);
 
     if (!iscapture) {
-        /* Allocate mixing buffer */
-        _this->hidden->mixlen = _this->spec.size;
-        _this->hidden->mixbuf = (Uint8 *)SDL_malloc(_this->hidden->mixlen);
-        if (_this->hidden->mixbuf == NULL) {
+        // Allocate mixing buffer
+        device->hidden->mixlen = device->buffer_size;
+        device->hidden->mixbuf = (Uint8 *)SDL_malloc(device->hidden->mixlen);
+        if (device->hidden->mixbuf == NULL) {
             return SDL_OutOfMemory();
         }
-        SDL_memset(_this->hidden->mixbuf, _this->spec.silence, _this->spec.size);
+        SDL_memset(device->hidden->mixbuf, device->silence_value, device->buffer_size);
     }
 
-    NETBSDAUDIO_Status(_this);
+    NETBSDAUDIO_Status(device);
 
-    /* We're ready to rock and roll. :-) */
-    return 0;
+    return 0;  // We're ready to rock and roll. :-)
 }
 
 static SDL_bool NETBSDAUDIO_Init(SDL_AudioDriverImpl *impl)
 {
-    /* Set the function pointers */
     impl->DetectDevices = NETBSDAUDIO_DetectDevices;
     impl->OpenDevice = NETBSDAUDIO_OpenDevice;
+    impl->WaitDevice = NETBSDAUDIO_WaitDevice;
     impl->PlayDevice = NETBSDAUDIO_PlayDevice;
     impl->GetDeviceBuf = NETBSDAUDIO_GetDeviceBuf;
     impl->CloseDevice = NETBSDAUDIO_CloseDevice;
+    impl->WaitCaptureDevice = NETBSDAUDIO_WaitDevice;
     impl->CaptureFromDevice = NETBSDAUDIO_CaptureFromDevice;
     impl->FlushCapture = NETBSDAUDIO_FlushCapture;
 
     impl->HasCaptureSupport = SDL_TRUE;
     impl->AllowsArbitraryDeviceNames = SDL_TRUE;
 
-    return SDL_TRUE; /* this audio target is available. */
+    return SDL_TRUE;
 }
 
 AudioBootStrap NETBSDAUDIO_bootstrap = {
     "netbsd", "NetBSD audio", NETBSDAUDIO_Init, SDL_FALSE
 };
 
-#endif /* SDL_AUDIO_DRIVER_NETBSD */
+#endif // SDL_AUDIO_DRIVER_NETBSD

src/audio/openslES/SDL_openslES.c

@@ -22,9 +22,8 @@
 
 #ifdef SDL_AUDIO_DRIVER_OPENSLES
 
-/* For more discussion of low latency audio on Android, see this:
-   https://googlesamples.github.io/android-audio-high-performance/guides/opensl_es.html
-*/
+// For more discussion of low latency audio on Android, see this:
+//   https://googlesamples.github.io/android-audio-high-performance/guides/opensl_es.html
 
 #include "../SDL_sysaudio.h"
 #include "../SDL_audio_c.h"
@@ -36,7 +35,7 @@
 #include <android/log.h>
 
 
-#define NUM_BUFFERS 2 /* -- Don't lower this! */
+#define NUM_BUFFERS 2 // -- Don't lower this!
 
 struct SDL_PrivateAudioData
 {
@@ -83,14 +82,14 @@ struct SDL_PrivateAudioData
 #define SL_ANDROID_SPEAKER_5DOT1  (SL_ANDROID_SPEAKER_QUAD | SL_SPEAKER_FRONT_CENTER | SL_SPEAKER_LOW_FREQUENCY)
 #define SL_ANDROID_SPEAKER_7DOT1  (SL_ANDROID_SPEAKER_5DOT1 | SL_SPEAKER_SIDE_LEFT | SL_SPEAKER_SIDE_RIGHT)
 
-/* engine interfaces */
+// engine interfaces
 static SLObjectItf engineObject = NULL;
 static SLEngineItf engineEngine = NULL;
 
-/* output mix interfaces */
+// output mix interfaces
 static SLObjectItf outputMixObject = NULL;
 
-/* buffer queue player interfaces */
+// buffer queue player interfaces
 static SLObjectItf bqPlayerObject = NULL;
 static SLPlayItf bqPlayerPlay = NULL;
 static SLAndroidSimpleBufferQueueItf bqPlayerBufferQueue = NULL;
@@ -98,7 +97,7 @@ static SLAndroidSimpleBufferQueueItf bqPlayerBufferQueue = NULL;
 static SLVolumeItf bqPlayerVolume;
 #endif
 
-/* recorder interfaces */
+// recorder interfaces
 static SLObjectItf recorderObject = NULL;
 static SLRecordItf recorderRecord = NULL;
 static SLAndroidSimpleBufferQueueItf recorderBufferQueue = NULL;
@@ -123,13 +122,13 @@ static void openslES_DestroyEngine(void)
 {
     LOGI("openslES_DestroyEngine()");
 
-    /* destroy output mix object, and invalidate all associated interfaces */
+    // destroy output mix object, and invalidate all associated interfaces
     if (outputMixObject != NULL) {
         (*outputMixObject)->Destroy(outputMixObject);
         outputMixObject = NULL;
     }
 
-    /* destroy engine object, and invalidate all associated interfaces */
+    // destroy engine object, and invalidate all associated interfaces
     if (engineObject != NULL) {
         (*engineObject)->Destroy(engineObject);
         engineObject = NULL;
@@ -145,7 +144,7 @@ static int openslES_CreateEngine(void)
 
     LOGI("openSLES_CreateEngine()");
 
-    /* create engine */
+    // create engine
     result = slCreateEngine(&engineObject, 0, NULL, 0, NULL, NULL);
     if (SL_RESULT_SUCCESS != result) {
         LOGE("slCreateEngine failed: %d", result);
@@ -153,7 +152,7 @@ static int openslES_CreateEngine(void)
     }
     LOGI("slCreateEngine OK");
 
-    /* realize the engine */
+    // realize the engine
     result = (*engineObject)->Realize(engineObject, SL_BOOLEAN_FALSE);
     if (SL_RESULT_SUCCESS != result) {
         LOGE("RealizeEngine failed: %d", result);
@@ -161,7 +160,7 @@ static int openslES_CreateEngine(void)
     }
     LOGI("RealizeEngine OK");
 
-    /* get the engine interface, which is needed in order to create other objects */
+    // get the engine interface, which is needed in order to create other objects
     result = (*engineObject)->GetInterface(engineObject, SL_IID_ENGINE, &engineEngine);
     if (SL_RESULT_SUCCESS != result) {
         LOGE("EngineGetInterface failed: %d", result);
@@ -169,7 +168,7 @@ static int openslES_CreateEngine(void)
     }
     LOGI("EngineGetInterface OK");
 
-    /* create output mix */
+    // create output mix
     result = (*engineEngine)->CreateOutputMix(engineEngine, &outputMixObject, 1, ids, req);
     if (SL_RESULT_SUCCESS != result) {
         LOGE("CreateOutputMix failed: %d", result);
@@ -177,7 +176,7 @@ static int openslES_CreateEngine(void)
     }
     LOGI("CreateOutputMix OK");
 
-    /* realize the output mix */
+    // realize the output mix
     result = (*outputMixObject)->Realize(outputMixObject, SL_BOOLEAN_FALSE);
     if (SL_RESULT_SUCCESS != result) {
         LOGE("RealizeOutputMix failed: %d", result);
@@ -190,7 +189,7 @@ error:
     return 0;
 }
 
-/* this callback handler is called every time a buffer finishes recording */
+// this callback handler is called every time a buffer finishes recording
 static void bqRecorderCallback(SLAndroidSimpleBufferQueueItf bq, void *context)
 {
     struct SDL_PrivateAudioData *audiodata = (struct SDL_PrivateAudioData *)context;
@@ -199,12 +198,12 @@ static void bqRecorderCallback(SLAndroidSimpleBufferQueueItf bq, void *context)
     SDL_PostSemaphore(audiodata->playsem);
 }
 
-static void openslES_DestroyPCMRecorder(SDL_AudioDevice *_this)
+static void openslES_DestroyPCMRecorder(SDL_AudioDevice *device)
 {
-    struct SDL_PrivateAudioData *audiodata = _this->hidden;
+    struct SDL_PrivateAudioData *audiodata = device->hidden;
     SLresult result;
 
-    /* stop recording */
+    // stop recording
     if (recorderRecord != NULL) {
         result = (*recorderRecord)->SetRecordState(recorderRecord, SL_RECORDSTATE_STOPPED);
         if (SL_RESULT_SUCCESS != result) {
@@ -212,7 +211,7 @@ static void openslES_DestroyPCMRecorder(SDL_AudioDevice *_this)
         }
     }
 
-    /* destroy audio recorder object, and invalidate all associated interfaces */
+    // destroy audio recorder object, and invalidate all associated interfaces
     if (recorderObject != NULL) {
         (*recorderObject)->Destroy(recorderObject);
         recorderObject = NULL;
@@ -230,9 +229,9 @@ static void openslES_DestroyPCMRecorder(SDL_AudioDevice *_this)
     }
 }
 
-static int openslES_CreatePCMRecorder(SDL_AudioDevice *_this)
+static int openslES_CreatePCMRecorder(SDL_AudioDevice *device)
 {
-    struct SDL_PrivateAudioData *audiodata = _this->hidden;
+    struct SDL_PrivateAudioData *audiodata = device->hidden;
     SLDataFormat_PCM format_pcm;
     SLDataLocator_AndroidSimpleBufferQueue loc_bufq;
     SLDataSink audioSnk;
@@ -248,19 +247,19 @@ static int openslES_CreatePCMRecorder(SDL_AudioDevice *_this)
         return SDL_SetError("This app doesn't have RECORD_AUDIO permission");
     }
 
-    /* Just go with signed 16-bit audio as it's the most compatible */
-    _this->spec.format = SDL_AUDIO_S16SYS;
-    _this->spec.channels = 1;
-    /*_this->spec.freq = SL_SAMPLINGRATE_16 / 1000;*/
+    // Just go with signed 16-bit audio as it's the most compatible
+    device->spec.format = SDL_AUDIO_S16SYS;
+    device->spec.channels = 1;
+    //device->spec.freq = SL_SAMPLINGRATE_16 / 1000;*/
 
-    /* Update the fragment size as size in bytes */
-    SDL_CalculateAudioSpec(&_this->spec);
+    // Update the fragment size as size in bytes
+    SDL_UpdatedAudioDeviceFormat(device);
 
     LOGI("Try to open %u hz %u bit chan %u %s samples %u",
-         _this->spec.freq, SDL_AUDIO_BITSIZE(_this->spec.format),
-         _this->spec.channels, (_this->spec.format & 0x1000) ? "BE" : "LE", _this->spec.samples);
+         device->spec.freq, SDL_AUDIO_BITSIZE(device->spec.format),
+         device->spec.channels, (device->spec.format & 0x1000) ? "BE" : "LE", device->sample_frames);
 
-    /* configure audio source */
+    // configure audio source
     loc_dev.locatorType = SL_DATALOCATOR_IODEVICE;
     loc_dev.deviceType = SL_IODEVICE_AUDIOINPUT;
     loc_dev.deviceID = SL_DEFAULTDEVICEID_AUDIOINPUT;
@@ -268,93 +267,93 @@ static int openslES_CreatePCMRecorder(SDL_AudioDevice *_this)
     audioSrc.pLocator = &loc_dev;
     audioSrc.pFormat = NULL;
 
-    /* configure audio sink */
+    // configure audio sink
     loc_bufq.locatorType = SL_DATALOCATOR_ANDROIDSIMPLEBUFFERQUEUE;
     loc_bufq.numBuffers = NUM_BUFFERS;
 
     format_pcm.formatType = SL_DATAFORMAT_PCM;
-    format_pcm.numChannels = _this->spec.channels;
-    format_pcm.samplesPerSec = _this->spec.freq * 1000; /* / kilo Hz to milli Hz */
-    format_pcm.bitsPerSample = SDL_AUDIO_BITSIZE(_this->spec.format);
-    format_pcm.containerSize = SDL_AUDIO_BITSIZE(_this->spec.format);
+    format_pcm.numChannels = device->spec.channels;
+    format_pcm.samplesPerSec = device->spec.freq * 1000; // / kilo Hz to milli Hz
+    format_pcm.bitsPerSample = SDL_AUDIO_BITSIZE(device->spec.format);
+    format_pcm.containerSize = SDL_AUDIO_BITSIZE(device->spec.format);
     format_pcm.endianness = SL_BYTEORDER_LITTLEENDIAN;
     format_pcm.channelMask = SL_SPEAKER_FRONT_CENTER;
 
     audioSnk.pLocator = &loc_bufq;
     audioSnk.pFormat = &format_pcm;
 
-    /* create audio recorder */
-    /* (requires the RECORD_AUDIO permission) */
+    // create audio recorder
+    // (requires the RECORD_AUDIO permission)
     result = (*engineEngine)->CreateAudioRecorder(engineEngine, &recorderObject, &audioSrc, &audioSnk, 1, ids, req);
     if (SL_RESULT_SUCCESS != result) {
         LOGE("CreateAudioRecorder failed: %d", result);
         goto failed;
     }
 
-    /* realize the recorder */
+    // realize the recorder
     result = (*recorderObject)->Realize(recorderObject, SL_BOOLEAN_FALSE);
     if (SL_RESULT_SUCCESS != result) {
         LOGE("RealizeAudioPlayer failed: %d", result);
         goto failed;
     }
 
-    /* get the record interface */
+    // get the record interface
     result = (*recorderObject)->GetInterface(recorderObject, SL_IID_RECORD, &recorderRecord);
     if (SL_RESULT_SUCCESS != result) {
         LOGE("SL_IID_RECORD interface get failed: %d", result);
         goto failed;
     }
 
-    /* get the buffer queue interface */
+    // get the buffer queue interface
     result = (*recorderObject)->GetInterface(recorderObject, SL_IID_ANDROIDSIMPLEBUFFERQUEUE, &recorderBufferQueue);
     if (SL_RESULT_SUCCESS != result) {
         LOGE("SL_IID_BUFFERQUEUE interface get failed: %d", result);
         goto failed;
     }
 
-    /* register callback on the buffer queue */
-    /* context is '(SDL_PrivateAudioData *)_this->hidden' */
-    result = (*recorderBufferQueue)->RegisterCallback(recorderBufferQueue, bqRecorderCallback, _this->hidden);
+    // register callback on the buffer queue
+    // context is '(SDL_PrivateAudioData *)device->hidden'
+    result = (*recorderBufferQueue)->RegisterCallback(recorderBufferQueue, bqRecorderCallback, device->hidden);
     if (SL_RESULT_SUCCESS != result) {
         LOGE("RegisterCallback failed: %d", result);
         goto failed;
     }
 
-    /* Create the audio buffer semaphore */
+    // Create the audio buffer semaphore
     audiodata->playsem = SDL_CreateSemaphore(0);
     if (!audiodata->playsem) {
         LOGE("cannot create Semaphore!");
         goto failed;
     }
 
-    /* Create the sound buffers */
-    audiodata->mixbuff = (Uint8 *)SDL_malloc(NUM_BUFFERS * _this->spec.size);
+    // Create the sound buffers
+    audiodata->mixbuff = (Uint8 *)SDL_malloc(NUM_BUFFERS * device->buffer_size);
     if (audiodata->mixbuff == NULL) {
         LOGE("mixbuffer allocate - out of memory");
         goto failed;
     }
 
     for (i = 0; i < NUM_BUFFERS; i++) {
-        audiodata->pmixbuff[i] = audiodata->mixbuff + i * _this->spec.size;
+        audiodata->pmixbuff[i] = audiodata->mixbuff + i * device->buffer_size;
     }
 
-    /* in case already recording, stop recording and clear buffer queue */
+    // in case already recording, stop recording and clear buffer queue
     result = (*recorderRecord)->SetRecordState(recorderRecord, SL_RECORDSTATE_STOPPED);
     if (SL_RESULT_SUCCESS != result) {
         LOGE("Record set state failed: %d", result);
         goto failed;
     }
 
-    /* enqueue empty buffers to be filled by the recorder */
+    // enqueue empty buffers to be filled by the recorder
     for (i = 0; i < NUM_BUFFERS; i++) {
-        result = (*recorderBufferQueue)->Enqueue(recorderBufferQueue, audiodata->pmixbuff[i], _this->spec.size);
+        result = (*recorderBufferQueue)->Enqueue(recorderBufferQueue, audiodata->pmixbuff[i], device->buffer_size);
         if (SL_RESULT_SUCCESS != result) {
             LOGE("Record enqueue buffers failed: %d", result);
             goto failed;
         }
     }
 
-    /* start recording */
+    // start recording
     result = (*recorderRecord)->SetRecordState(recorderRecord, SL_RECORDSTATE_RECORDING);
     if (SL_RESULT_SUCCESS != result) {
         LOGE("Record set state failed: %d", result);
@@ -367,7 +366,7 @@ failed:
     return SDL_SetError("Open device failed!");
 }
 
-/* this callback handler is called every time a buffer finishes playing */
+// this callback handler is called every time a buffer finishes playing
 static void bqPlayerCallback(SLAndroidSimpleBufferQueueItf bq, void *context)
 {
     struct SDL_PrivateAudioData *audiodata = (struct SDL_PrivateAudioData *)context;
@@ -376,20 +375,19 @@ static void bqPlayerCallback(SLAndroidSimpleBufferQueueItf bq, void *context)
     SDL_PostSemaphore(audiodata->playsem);
 }
 
-static void openslES_DestroyPCMPlayer(SDL_AudioDevice *_this)
+static void openslES_DestroyPCMPlayer(SDL_AudioDevice *device)
 {
-    struct SDL_PrivateAudioData *audiodata = _this->hidden;
-    SLresult result;
+    struct SDL_PrivateAudioData *audiodata = device->hidden;
 
-    /* set the player's state to 'stopped' */
+    // set the player's state to 'stopped'
     if (bqPlayerPlay != NULL) {
-        result = (*bqPlayerPlay)->SetPlayState(bqPlayerPlay, SL_PLAYSTATE_STOPPED);
+        const SLresult result = (*bqPlayerPlay)->SetPlayState(bqPlayerPlay, SL_PLAYSTATE_STOPPED);
         if (SL_RESULT_SUCCESS != result) {
             LOGE("SetPlayState stopped failed: %d", result);
         }
     }
 
-    /* destroy buffer queue audio player object, and invalidate all associated interfaces */
+    // destroy buffer queue audio player object, and invalidate all associated interfaces
     if (bqPlayerObject != NULL) {
         (*bqPlayerObject)->Destroy(bqPlayerObject);
 
@@ -408,26 +406,14 @@ static void openslES_DestroyPCMPlayer(SDL_AudioDevice *_this)
     }
 }
 
-static int openslES_CreatePCMPlayer(SDL_AudioDevice *_this)
+static int openslES_CreatePCMPlayer(SDL_AudioDevice *device)
 {
-    struct SDL_PrivateAudioData *audiodata = _this->hidden;
-    SLDataLocator_AndroidSimpleBufferQueue loc_bufq;
-    SLDataFormat_PCM format_pcm;
-    SLAndroidDataFormat_PCM_EX format_pcm_ex;
-    SLDataSource audioSrc;
-    SLDataSink audioSnk;
-    SLDataLocator_OutputMix loc_outmix;
-    const SLInterfaceID ids[2] = { SL_IID_ANDROIDSIMPLEBUFFERQUEUE, SL_IID_VOLUME };
-    const SLboolean req[2] = { SL_BOOLEAN_TRUE, SL_BOOLEAN_FALSE };
-    SLresult result;
-    int i;
-
     /* If we want to add floating point audio support (requires API level 21)
        it can be done as described here:
         https://developer.android.com/ndk/guides/audio/opensl/android-extensions.html#floating-point
     */
     if (SDL_GetAndroidSDKVersion() >= 21) {
-        const SDL_AudioFormat *closefmts = SDL_ClosestAudioFormats(_this->spec.format);
+        const SDL_AudioFormat *closefmts = SDL_ClosestAudioFormats(device->spec.format);
         SDL_AudioFormat test_format;
         while ((test_format = *(closefmts++)) != 0) {
             if (SDL_AUDIO_ISSIGNED(test_format)) {
@@ -436,40 +422,42 @@ static int openslES_CreatePCMPlayer(SDL_AudioDevice *_this)
         }
 
         if (!test_format) {
-            /* Didn't find a compatible format : */
+            // Didn't find a compatible format :
             LOGI("No compatible audio format, using signed 16-bit audio");
             test_format = SDL_AUDIO_S16SYS;
         }
-        _this->spec.format = test_format;
+        device->spec.format = test_format;
     } else {
-        /* Just go with signed 16-bit audio as it's the most compatible */
-        _this->spec.format = SDL_AUDIO_S16SYS;
+        // Just go with signed 16-bit audio as it's the most compatible
+        device->spec.format = SDL_AUDIO_S16SYS;
     }
 
-    /* Update the fragment size as size in bytes */
-    SDL_CalculateAudioSpec(&_this->spec);
+    // Update the fragment size as size in bytes
+    SDL_UpdatedAudioDeviceFormat(device);
 
     LOGI("Try to open %u hz %s %u bit chan %u %s samples %u",
-         _this->spec.freq, SDL_AUDIO_ISFLOAT(_this->spec.format) ? "float" : "pcm", SDL_AUDIO_BITSIZE(_this->spec.format),
-         _this->spec.channels, (_this->spec.format & 0x1000) ? "BE" : "LE", _this->spec.samples);
+         device->spec.freq, SDL_AUDIO_ISFLOAT(device->spec.format) ? "float" : "pcm", SDL_AUDIO_BITSIZE(device->spec.format),
+         device->spec.channels, (device->spec.format & 0x1000) ? "BE" : "LE", device->sample_frames);
 
-    /* configure audio source */
+    // configure audio source
+    SLDataLocator_AndroidSimpleBufferQueue loc_bufq;
     loc_bufq.locatorType = SL_DATALOCATOR_ANDROIDSIMPLEBUFFERQUEUE;
     loc_bufq.numBuffers = NUM_BUFFERS;
 
+    SLDataFormat_PCM format_pcm;
     format_pcm.formatType = SL_DATAFORMAT_PCM;
-    format_pcm.numChannels = _this->spec.channels;
-    format_pcm.samplesPerSec = _this->spec.freq * 1000; /* / kilo Hz to milli Hz */
-    format_pcm.bitsPerSample = SDL_AUDIO_BITSIZE(_this->spec.format);
-    format_pcm.containerSize = SDL_AUDIO_BITSIZE(_this->spec.format);
+    format_pcm.numChannels = device->spec.channels;
+    format_pcm.samplesPerSec = device->spec.freq * 1000; // / kilo Hz to milli Hz
+    format_pcm.bitsPerSample = SDL_AUDIO_BITSIZE(device->spec.format);
+    format_pcm.containerSize = SDL_AUDIO_BITSIZE(device->spec.format);
 
-    if (SDL_AUDIO_ISBIGENDIAN(_this->spec.format)) {
+    if (SDL_AUDIO_ISBIGENDIAN(device->spec.format)) {
         format_pcm.endianness = SL_BYTEORDER_BIGENDIAN;
     } else {
         format_pcm.endianness = SL_BYTEORDER_LITTLEENDIAN;
     }
 
-    switch (_this->spec.channels) {
+    switch (device->spec.channels) {
     case 1:
         format_pcm.channelMask = SL_SPEAKER_FRONT_LEFT;
         break;
@@ -495,14 +483,19 @@ static int openslES_CreatePCMPlayer(SDL_AudioDevice *_this)
         format_pcm.channelMask = SL_ANDROID_SPEAKER_7DOT1;
         break;
     default:
-        /* Unknown number of channels, fall back to stereo */
-        _this->spec.channels = 2;
+        // Unknown number of channels, fall back to stereo
+        device->spec.channels = 2;
         format_pcm.channelMask = SL_SPEAKER_FRONT_LEFT | SL_SPEAKER_FRONT_RIGHT;
         break;
     }
 
-    if (SDL_AUDIO_ISFLOAT(_this->spec.format)) {
-        /* Copy all setup into PCM EX structure */
+    SLDataSink audioSnk;
+    SLDataSource audioSrc;
+    audioSrc.pFormat = (void *)&format_pcm;
+
+    SLAndroidDataFormat_PCM_EX format_pcm_ex;
+    if (SDL_AUDIO_ISFLOAT(device->spec.format)) {
+        // Copy all setup into PCM EX structure
         format_pcm_ex.formatType = SL_ANDROID_DATAFORMAT_PCM_EX;
         format_pcm_ex.endianness = format_pcm.endianness;
         format_pcm_ex.channelMask = format_pcm.channelMask;
@@ -511,81 +504,87 @@ static int openslES_CreatePCMPlayer(SDL_AudioDevice *_this)
         format_pcm_ex.bitsPerSample = format_pcm.bitsPerSample;
         format_pcm_ex.containerSize = format_pcm.containerSize;
         format_pcm_ex.representation = SL_ANDROID_PCM_REPRESENTATION_FLOAT;
+        audioSrc.pFormat = (void *)&format_pcm_ex;
     }
 
     audioSrc.pLocator = &loc_bufq;
-    audioSrc.pFormat = SDL_AUDIO_ISFLOAT(_this->spec.format) ? (void *)&format_pcm_ex : (void *)&format_pcm;
 
-    /* configure audio sink */
+    // configure audio sink
+    SLDataLocator_OutputMix loc_outmix;
     loc_outmix.locatorType = SL_DATALOCATOR_OUTPUTMIX;
     loc_outmix.outputMix = outputMixObject;
     audioSnk.pLocator = &loc_outmix;
     audioSnk.pFormat = NULL;
 
-    /* create audio player */
+    // create audio player
+    const SLInterfaceID ids[2] = { SL_IID_ANDROIDSIMPLEBUFFERQUEUE, SL_IID_VOLUME };
+    const SLboolean req[2] = { SL_BOOLEAN_TRUE, SL_BOOLEAN_FALSE };
+    SLresult result;
     result = (*engineEngine)->CreateAudioPlayer(engineEngine, &bqPlayerObject, &audioSrc, &audioSnk, 2, ids, req);
     if (SL_RESULT_SUCCESS != result) {
         LOGE("CreateAudioPlayer failed: %d", result);
         goto failed;
     }
 
-    /* realize the player */
+    // realize the player
     result = (*bqPlayerObject)->Realize(bqPlayerObject, SL_BOOLEAN_FALSE);
     if (SL_RESULT_SUCCESS != result) {
         LOGE("RealizeAudioPlayer failed: %d", result);
         goto failed;
     }
 
-    /* get the play interface */
+    // get the play interface
     result = (*bqPlayerObject)->GetInterface(bqPlayerObject, SL_IID_PLAY, &bqPlayerPlay);
     if (SL_RESULT_SUCCESS != result) {
         LOGE("SL_IID_PLAY interface get failed: %d", result);
         goto failed;
     }
 
-    /* get the buffer queue interface */
+    // get the buffer queue interface
     result = (*bqPlayerObject)->GetInterface(bqPlayerObject, SL_IID_ANDROIDSIMPLEBUFFERQUEUE, &bqPlayerBufferQueue);
     if (SL_RESULT_SUCCESS != result) {
         LOGE("SL_IID_BUFFERQUEUE interface get failed: %d", result);
         goto failed;
     }
 
-    /* register callback on the buffer queue */
-    /* context is '(SDL_PrivateAudioData *)_this->hidden' */
-    result = (*bqPlayerBufferQueue)->RegisterCallback(bqPlayerBufferQueue, bqPlayerCallback, _this->hidden);
+    // register callback on the buffer queue
+    // context is '(SDL_PrivateAudioData *)device->hidden'
+    result = (*bqPlayerBufferQueue)->RegisterCallback(bqPlayerBufferQueue, bqPlayerCallback, device->hidden);
     if (SL_RESULT_SUCCESS != result) {
         LOGE("RegisterCallback failed: %d", result);
         goto failed;
     }
 
 #if 0
-    /* get the volume interface */
+    // get the volume interface
     result = (*bqPlayerObject)->GetInterface(bqPlayerObject, SL_IID_VOLUME, &bqPlayerVolume);
     if (SL_RESULT_SUCCESS != result) {
         LOGE("SL_IID_VOLUME interface get failed: %d", result);
-        /* goto failed; */
+        // goto failed;
     }
 #endif
 
-    /* Create the audio buffer semaphore */
+    struct SDL_PrivateAudioData *audiodata = device->hidden;
+
+    // Create the audio buffer semaphore
     audiodata->playsem = SDL_CreateSemaphore(NUM_BUFFERS - 1);
     if (!audiodata->playsem) {
         LOGE("cannot create Semaphore!");
         goto failed;
     }
 
-    /* Create the sound buffers */
-    audiodata->mixbuff = (Uint8 *)SDL_malloc(NUM_BUFFERS * _this->spec.size);
+    // Create the sound buffers
+    audiodata->mixbuff = (Uint8 *)SDL_malloc(NUM_BUFFERS * device->buffer_size);
     if (audiodata->mixbuff == NULL) {
         LOGE("mixbuffer allocate - out of memory");
         goto failed;
     }
 
-    for (i = 0; i < NUM_BUFFERS; i++) {
-        audiodata->pmixbuff[i] = audiodata->mixbuff + i * _this->spec.size;
+    for (int i = 0; i < NUM_BUFFERS; i++) {
+        audiodata->pmixbuff[i] = audiodata->mixbuff + i * device->buffer_size;
     }
 
-    /* set the player's state to playing */
+    // set the player's state to playing
     result = (*bqPlayerPlay)->SetPlayState(bqPlayerPlay, SL_PLAYSTATE_PLAYING);
     if (SL_RESULT_SUCCESS != result) {
         LOGE("Play set state failed: %d", result);
@@ -598,103 +597,98 @@ failed:
     return -1;
 }
 
-static int openslES_OpenDevice(SDL_AudioDevice *_this, const char *devname)
+static int openslES_OpenDevice(SDL_AudioDevice *device)
 {
-    _this->hidden = (struct SDL_PrivateAudioData *)SDL_calloc(1, sizeof(*_this->hidden));
-    if (_this->hidden == NULL) {
+    device->hidden = (struct SDL_PrivateAudioData *)SDL_calloc(1, sizeof(*device->hidden));
+    if (device->hidden == NULL) {
         return SDL_OutOfMemory();
     }
 
-    if (_this->iscapture) {
-        LOGI("openslES_OpenDevice() %s for capture", devname);
-        return openslES_CreatePCMRecorder(_this);
+    if (device->iscapture) {
+        LOGI("openslES_OpenDevice() for capture");
+        return openslES_CreatePCMRecorder(device);
     } else {
         int ret;
-        LOGI("openslES_OpenDevice() %s for playing", devname);
-        ret = openslES_CreatePCMPlayer(_this);
+        LOGI("openslES_OpenDevice() for playing");
+        ret = openslES_CreatePCMPlayer(device);
         if (ret < 0) {
-            /* Another attempt to open the device with a lower frequency */
-            if (_this->spec.freq > 48000) {
-                openslES_DestroyPCMPlayer(_this);
-                _this->spec.freq = 48000;
-                ret = openslES_CreatePCMPlayer(_this);
+            // Another attempt to open the device with a lower frequency
+            if (device->spec.freq > 48000) {
+                openslES_DestroyPCMPlayer(device);
+                device->spec.freq = 48000;
+                ret = openslES_CreatePCMPlayer(device);
             }
         }
 
-        if (ret == 0) {
-            return 0;
-        } else {
+        if (ret != 0) {
             return SDL_SetError("Open device failed!");
         }
     }
+
+    return 0;
 }
 
-static void openslES_WaitDevice(SDL_AudioDevice *_this)
+static void openslES_WaitDevice(SDL_AudioDevice *device)
 {
-    struct SDL_PrivateAudioData *audiodata = _this->hidden;
+    struct SDL_PrivateAudioData *audiodata = device->hidden;
 
     LOGV("openslES_WaitDevice()");
 
-    /* Wait for an audio chunk to finish */
+    // Wait for an audio chunk to finish
     SDL_WaitSemaphore(audiodata->playsem);
 }
 
-static void openslES_PlayDevice(SDL_AudioDevice *_this)
+static void openslES_PlayDevice(SDL_AudioDevice *device, const Uint8 *buffer, int buflen)
 {
-    struct SDL_PrivateAudioData *audiodata = _this->hidden;
-    SLresult result;
+    struct SDL_PrivateAudioData *audiodata = device->hidden;
 
     LOGV("======openslES_PlayDevice()======");
 
-    /* Queue it up */
-    result = (*bqPlayerBufferQueue)->Enqueue(bqPlayerBufferQueue, audiodata->pmixbuff[audiodata->next_buffer], _this->spec.size);
+    // Queue it up
+    const SLresult result = (*bqPlayerBufferQueue)->Enqueue(bqPlayerBufferQueue, buffer, buflen);
 
     audiodata->next_buffer++;
     if (audiodata->next_buffer >= NUM_BUFFERS) {
         audiodata->next_buffer = 0;
     }
 
-    /* If Enqueue fails, callback won't be called.
-     * Post the semaphore, not to run out of buffer */
+    // If Enqueue fails, callback won't be called.
+    // Post the semaphore, not to run out of buffer
     if (SL_RESULT_SUCCESS != result) {
         SDL_PostSemaphore(audiodata->playsem);
     }
 }
 
-/*/           n   playn sem */
-/* getbuf     0   -     1 */
-/* fill buff  0   -     1 */
-/* play       0 - 0     1 */
-/* wait       1   0     0 */
-/* getbuf     1   0     0 */
-/* fill buff  1   0     0 */
-/* play       0   0     0 */
-/* wait */
-/* */
-/* okay.. */
-
-static Uint8 *openslES_GetDeviceBuf(SDL_AudioDevice *_this)
+///           n   playn sem
+// getbuf     0   -     1
+// fill buff  0   -     1
+// play       0 - 0     1
+// wait       1   0     0
+// getbuf     1   0     0
+// fill buff  1   0     0
+// play       0   0     0
+// wait
+//
+// okay..
+
+static Uint8 *openslES_GetDeviceBuf(SDL_AudioDevice *device, int *bufsize)
 {
-    struct SDL_PrivateAudioData *audiodata = _this->hidden;
+    struct SDL_PrivateAudioData *audiodata = device->hidden;
 
     LOGV("openslES_GetDeviceBuf()");
     return audiodata->pmixbuff[audiodata->next_buffer];
 }
 
-static int openslES_CaptureFromDevice(SDL_AudioDevice *_this, void *buffer, int buflen)
+static int openslES_CaptureFromDevice(SDL_AudioDevice *device, void *buffer, int buflen)
 {
-    struct SDL_PrivateAudioData *audiodata = _this->hidden;
-    SLresult result;
-
-    /* Wait for new recorded data */
-    SDL_WaitSemaphore(audiodata->playsem);
+    struct SDL_PrivateAudioData *audiodata = device->hidden;
 
-    /* Copy it to the output buffer */
-    SDL_assert(buflen == _this->spec.size);
-    SDL_memcpy(buffer, audiodata->pmixbuff[audiodata->next_buffer], _this->spec.size);
+    // Copy it to the output buffer
+    SDL_assert(buflen == device->buffer_size);
+    SDL_memcpy(buffer, audiodata->pmixbuff[audiodata->next_buffer], device->buffer_size);
 
-    /* Re-enqueue the buffer */
-    result = (*recorderBufferQueue)->Enqueue(recorderBufferQueue, audiodata->pmixbuff[audiodata->next_buffer], _this->spec.size);
+    // Re-enqueue the buffer
+    const SLresult result = (*recorderBufferQueue)->Enqueue(recorderBufferQueue, audiodata->pmixbuff[audiodata->next_buffer], device->buffer_size);
     if (SL_RESULT_SUCCESS != result) {
         LOGE("Record enqueue buffers failed: %d", result);
         return -1;
@@ -705,22 +699,24 @@ static int openslES_CaptureFromDevice(SDL_AudioDevice *_this, void *buffer, int
         audiodata->next_buffer = 0;
     }
 
-    return _this->spec.size;
+    return device->buffer_size;
 }
 
-static void openslES_CloseDevice(SDL_AudioDevice *_this)
+static void openslES_CloseDevice(SDL_AudioDevice *device)
 {
-    /* struct SDL_PrivateAudioData *audiodata = _this->hidden; */
+    // struct SDL_PrivateAudioData *audiodata = device->hidden;
+    if (device->hidden) {
+        if (device->iscapture) {
+            LOGI("openslES_CloseDevice() for capture");
+            openslES_DestroyPCMRecorder(device);
+        } else {
+            LOGI("openslES_CloseDevice() for playing");
+            openslES_DestroyPCMPlayer(device);
+        }
 
-    if (_this->iscapture) {
-        LOGI("openslES_CloseDevice() for capture");
-        openslES_DestroyPCMRecorder(_this);
-    } else {
-        LOGI("openslES_CloseDevice() for playing");
-        openslES_DestroyPCMPlayer(_this);
+        SDL_free(device->hidden);
+        device->hidden = NULL;
     }
-
-    SDL_free(_this->hidden);
 }
 
 static SDL_bool openslES_Init(SDL_AudioDriverImpl *impl)
@@ -733,24 +729,26 @@ static SDL_bool openslES_Init(SDL_AudioDriverImpl *impl)
 
     LOGI("openslES_Init() - set pointers");
 
-    /* Set the function pointers */
-    /* impl->DetectDevices = openslES_DetectDevices; */
+    // Set the function pointers
+    // impl->DetectDevices = openslES_DetectDevices;
+    impl->ThreadInit = Android_AudioThreadInit;
     impl->OpenDevice = openslES_OpenDevice;
     impl->WaitDevice = openslES_WaitDevice;
     impl->PlayDevice = openslES_PlayDevice;
     impl->GetDeviceBuf = openslES_GetDeviceBuf;
+    impl->WaitCaptureDevice = openslES_WaitDevice;
     impl->CaptureFromDevice = openslES_CaptureFromDevice;
     impl->CloseDevice = openslES_CloseDevice;
     impl->Deinitialize = openslES_DestroyEngine;
 
-    /* and the capabilities */
+    // and the capabilities
     impl->HasCaptureSupport = SDL_TRUE;
     impl->OnlyHasDefaultOutputDevice = SDL_TRUE;
     impl->OnlyHasDefaultCaptureDevice = SDL_TRUE;
 
     LOGI("openslES_Init() - success");
 
-    /* this audio target is available. */
+    // this audio target is available.
     return SDL_TRUE;
 }
 
@@ -761,7 +759,7 @@ AudioBootStrap openslES_bootstrap = {
 void openslES_ResumeDevices(void)
 {
     if (bqPlayerPlay != NULL) {
-        /* set the player's state to 'playing' */
+        // set the player's state to 'playing'
         SLresult result = (*bqPlayerPlay)->SetPlayState(bqPlayerPlay, SL_PLAYSTATE_PLAYING);
         if (SL_RESULT_SUCCESS != result) {
             LOGE("openslES_ResumeDevices failed: %d", result);
@@ -772,7 +770,7 @@ void openslES_ResumeDevices(void)
 void openslES_PauseDevices(void)
 {
     if (bqPlayerPlay != NULL) {
-        /* set the player's state to 'paused' */
+        // set the player's state to 'paused'
         SLresult result = (*bqPlayerPlay)->SetPlayState(bqPlayerPlay, SL_PLAYSTATE_PAUSED);
         if (SL_RESULT_SUCCESS != result) {
             LOGE("openslES_PauseDevices failed: %d", result);
@@ -780,4 +778,4 @@ void openslES_PauseDevices(void)
     }
 }
 
-#endif /* SDL_AUDIO_DRIVER_OPENSLES */
+#endif // SDL_AUDIO_DRIVER_OPENSLES

src/audio/pipewire/SDL_pipewire.c

@@ -327,7 +327,7 @@ static void io_list_remove(Uint32 id)
             spa_list_remove(&n->link);
 
             if (hotplug_events_enabled) {
-                SDL_RemoveAudioDevice(n->is_capture, PW_ID_TO_HANDLE(id));
+                SDL_AudioDeviceDisconnected(SDL_FindPhysicalAudioDeviceByHandle(PW_ID_TO_HANDLE(id)));
             }
 
             SDL_free(n);
@@ -337,31 +337,6 @@ static void io_list_remove(Uint32 id)
     }
 }
 
-static void io_list_sort(void)
-{
-    struct io_node *default_sink = NULL, *default_source = NULL;
-    struct io_node *n, *temp;
-
-    /* Find and move the default nodes to the beginning of the list */
-    spa_list_for_each_safe (n, temp, &hotplug_io_list, link) {
-        if (pipewire_default_sink_id != NULL && SDL_strcmp(n->path, pipewire_default_sink_id) == 0) {
-            default_sink = n;
-            spa_list_remove(&n->link);
-        } else if (pipewire_default_source_id != NULL && SDL_strcmp(n->path, pipewire_default_source_id) == 0) {
-            default_source = n;
-            spa_list_remove(&n->link);
-        }
-    }
-
-    if (default_source) {
-        spa_list_prepend(&hotplug_io_list, &default_source->link);
-    }
-
-    if (default_sink) {
-        spa_list_prepend(&hotplug_io_list, &default_sink->link);
-    }
-}
-
 static void io_list_clear(void)
 {
     struct io_node *n, *temp;
@@ -383,17 +358,6 @@ static struct io_node *io_list_get_by_id(Uint32 id)
     return NULL;
 }
 
-static struct io_node *io_list_get_by_path(char *path)
-{
-    struct io_node *n, *temp;
-    spa_list_for_each_safe (n, temp, &hotplug_io_list, link) {
-        if (SDL_strcmp(n->path, path) == 0) {
-            return n;
-        }
-    }
-    return NULL;
-}
-
 static void node_object_destroy(struct node_object *node)
 {
     SDL_assert(node);
@@ -640,6 +604,19 @@ static char *get_name_from_json(const char *json)
     return SDL_strdup(value);
 }
 
+static void change_default_device(const char *path)
+{
+    if (hotplug_events_enabled) {
+        struct io_node *n, *temp;
+        spa_list_for_each_safe (n, temp, &hotplug_io_list, link) {
+            if (SDL_strcmp(n->path, path) == 0) {
+                SDL_DefaultAudioDeviceChanged(SDL_FindPhysicalAudioDeviceByHandle(PW_ID_TO_HANDLE(n->id)));
+                return; // found it, we're done.
+            }
+        }
+    }
+}
+
 /* Metadata node callback */
 static int metadata_property(void *object, Uint32 subject, const char *key, const char *type, const char *value)
 {
@@ -652,12 +629,14 @@ static int metadata_property(void *object, Uint32 subject, const char *key, cons
             }
             pipewire_default_sink_id = get_name_from_json(value);
             node->persist = SDL_TRUE;
+            change_default_device(pipewire_default_sink_id);
         } else if (!SDL_strcmp(key, "default.audio.source")) {
             if (pipewire_default_source_id != NULL) {
                 SDL_free(pipewire_default_source_id);
             }
             pipewire_default_source_id = get_name_from_json(value);
             node->persist = SDL_TRUE;
+            change_default_device(pipewire_default_source_id);
         }
     }
 
@@ -833,7 +812,7 @@ static void hotplug_loop_destroy(void)
     }
 }
 
-static void PIPEWIRE_DetectDevices(void)
+static void PIPEWIRE_DetectDevices(SDL_AudioDevice **default_output, SDL_AudioDevice **default_capture)
 {
     struct io_node *io;
 
@@ -844,11 +823,15 @@ static void PIPEWIRE_DetectDevices(void)
         PIPEWIRE_pw_thread_loop_wait(hotplug_loop);
     }
 
-    /* Sort the I/O list so the default source/sink are listed first */
-    io_list_sort();
-
     spa_list_for_each (io, &hotplug_io_list, link) {
-        SDL_AddAudioDevice(io->is_capture, io->name, &io->spec, PW_ID_TO_HANDLE(io->id));
+        SDL_AudioDevice *device = SDL_AddAudioDevice(io->is_capture, io->name, &io->spec, PW_ID_TO_HANDLE(io->id));
+        if (pipewire_default_sink_id != NULL && SDL_strcmp(io->path, pipewire_default_sink_id) == 0) {
+            SDL_assert(!io->is_capture);
+            *default_output = device;
+        } else if (pipewire_default_source_id != NULL && SDL_strcmp(io->path, pipewire_default_source_id) == 0) {
+            SDL_assert(io->is_capture);
+            *default_capture = device;
+        }
     }
 
     hotplug_events_enabled = SDL_TRUE;
@@ -936,167 +919,115 @@ static void initialize_spa_info(const SDL_AudioSpec *spec, struct spa_audio_info
     }
 }
 
-static void output_callback(void *data)
+static Uint8 *PIPEWIRE_GetDeviceBuf(SDL_AudioDevice *device, int *buffer_size)
 {
-    struct pw_buffer *pw_buf;
-    struct spa_buffer *spa_buf;
-    Uint8 *dst;
+    // See if a buffer is available. If this returns NULL, SDL_OutputAudioThreadIterate will return SDL_FALSE, but since we own the thread, it won't kill playback.
+    // !!! FIXME: It's not clear to me if this ever returns NULL or if this was just defensive coding.
 
-    SDL_AudioDevice *_this = (SDL_AudioDevice *)data;
-    struct pw_stream *stream = _this->hidden->stream;
-
-    /* Shutting down, don't do anything */
-    if (SDL_AtomicGet(&_this->shutdown)) {
-        return;
-    }
-
-    /* See if a buffer is available */
-    pw_buf = PIPEWIRE_pw_stream_dequeue_buffer(stream);
+    struct pw_stream *stream = device->hidden->stream;
+    struct pw_buffer *pw_buf = PIPEWIRE_pw_stream_dequeue_buffer(stream);
     if (pw_buf == NULL) {
-        return;
+        return NULL;
     }
 
-    spa_buf = pw_buf->buffer;
-
+    struct spa_buffer *spa_buf = pw_buf->buffer;
     if (spa_buf->datas[0].data == NULL) {
-        return;
+        PIPEWIRE_pw_stream_queue_buffer(stream, pw_buf);
+        return NULL;
     }
 
-    /*
-     * If the device is disabled, write silence to the stream buffer
-     * and run the callback with the work buffer to keep the callback
-     * firing regularly in case the audio is being used as a timer.
-     */
-    SDL_LockMutex(_this->mixer_lock);
-    if (!SDL_AtomicGet(&_this->paused)) {
-        if (SDL_AtomicGet(&_this->enabled)) {
-            dst = spa_buf->datas[0].data;
-        } else {
-            dst = _this->work_buffer;
-            SDL_memset(spa_buf->datas[0].data, _this->spec.silence, _this->spec.size);
-        }
-
-        if (!_this->stream) {
-            _this->callbackspec.callback(_this->callbackspec.userdata, dst, _this->callbackspec.size);
-        } else {
-            int got;
-
-            /* Fire the callback until we have enough to fill a buffer */
-            while (SDL_GetAudioStreamAvailable(_this->stream) < _this->spec.size) {
-                _this->callbackspec.callback(_this->callbackspec.userdata, _this->work_buffer, _this->callbackspec.size);
-                SDL_PutAudioStreamData(_this->stream, _this->work_buffer, _this->callbackspec.size);
-            }
-
-            got = SDL_GetAudioStreamData(_this->stream, dst, _this->spec.size);
-            SDL_assert(got == _this->spec.size);
-        }
-    } else {
-        SDL_memset(spa_buf->datas[0].data, _this->spec.silence, _this->spec.size);
-    }
-    SDL_UnlockMutex(_this->mixer_lock);
+    device->hidden->pw_buf = pw_buf;
+    return (Uint8 *) spa_buf->datas[0].data;
+}
 
+static void PIPEWIRE_PlayDevice(SDL_AudioDevice *device, const Uint8 *buffer, int buffer_size)
+{
+    struct pw_stream *stream = device->hidden->stream;
+    struct pw_buffer *pw_buf = device->hidden->pw_buf;
+    struct spa_buffer *spa_buf = pw_buf->buffer;
     spa_buf->datas[0].chunk->offset = 0;
-    spa_buf->datas[0].chunk->stride = _this->hidden->stride;
-    spa_buf->datas[0].chunk->size = _this->spec.size;
+    spa_buf->datas[0].chunk->stride = device->hidden->stride;
+    spa_buf->datas[0].chunk->size = buffer_size;
 
     PIPEWIRE_pw_stream_queue_buffer(stream, pw_buf);
+    device->hidden->pw_buf = NULL;
 }
 
-static void input_callback(void *data)
+static void output_callback(void *data)
 {
-    struct pw_buffer *pw_buf;
-    struct spa_buffer *spa_buf;
-    Uint8 *src;
-    SDL_AudioDevice *_this = (SDL_AudioDevice *)data;
-    struct pw_stream *stream = _this->hidden->stream;
-
-    /* Shutting down, don't do anything */
-    if (SDL_AtomicGet(&_this->shutdown)) {
-        return;
-    }
+    SDL_OutputAudioThreadIterate((SDL_AudioDevice *)data);
+}
 
-    pw_buf = PIPEWIRE_pw_stream_dequeue_buffer(stream);
-    if (pw_buf == NULL) {
-        return;
+static void PIPEWIRE_FlushCapture(SDL_AudioDevice *device)
+{
+    struct pw_stream *stream = device->hidden->stream;
+    struct pw_buffer *pw_buf = PIPEWIRE_pw_stream_dequeue_buffer(stream);
+    if (pw_buf != NULL) {  // just requeue it without any further thought.
+        PIPEWIRE_pw_stream_queue_buffer(stream, pw_buf);
     }
+}
 
-    spa_buf = pw_buf->buffer;
-    (src = (Uint8 *)spa_buf->datas[0].data);
-    if (src == NULL) {
-        return;
+static int PIPEWIRE_CaptureFromDevice(SDL_AudioDevice *device, void *buffer, int buflen)
+{
+    struct pw_stream *stream = device->hidden->stream;
+    struct pw_buffer *pw_buf = PIPEWIRE_pw_stream_dequeue_buffer(stream);
+    if (!pw_buf) {
+        return 0;
     }
 
-    if (!SDL_AtomicGet(&_this->paused)) {
-        /* Calculate the offset and data size */
-        const Uint32 offset = SPA_MIN(spa_buf->datas[0].chunk->offset, spa_buf->datas[0].maxsize);
-        const Uint32 size = SPA_MIN(spa_buf->datas[0].chunk->size, spa_buf->datas[0].maxsize - offset);
-
-        src += offset;
+    struct spa_buffer *spa_buf = pw_buf->buffer;
+    if (!spa_buf) {
+        PIPEWIRE_pw_stream_queue_buffer(stream, pw_buf);
+        return 0;
+    }
 
-        /* Fill the buffer with silence if the stream is disabled. */
-        if (!SDL_AtomicGet(&_this->enabled)) {
-            SDL_memset(src, _this->callbackspec.silence, size);
-        }
+    const Uint8 *src = (const Uint8 *)spa_buf->datas[0].data;
+    const Uint32 offset = SPA_MIN(spa_buf->datas[0].chunk->offset, spa_buf->datas[0].maxsize);
+    const Uint32 size = SPA_MIN(spa_buf->datas[0].chunk->size, spa_buf->datas[0].maxsize - offset);
+    const int cpy = SDL_min(buflen, (int) size);
 
-        /* Pipewire can vary the latency, so buffer all incoming data */
-        SDL_WriteToDataQueue(_this->hidden->buffer, src, size);
+    SDL_assert(size <= buflen);  // We'll have to reengineer some stuff if this turns out to not be true.
 
-        while (SDL_GetDataQueueSize(_this->hidden->buffer) >= _this->callbackspec.size) {
-            SDL_ReadFromDataQueue(_this->hidden->buffer, _this->work_buffer, _this->callbackspec.size);
+    SDL_memcpy(buffer, src + offset, cpy);
+    PIPEWIRE_pw_stream_queue_buffer(stream, pw_buf);
 
-            SDL_LockMutex(_this->mixer_lock);
-            _this->callbackspec.callback(_this->callbackspec.userdata, _this->work_buffer, _this->callbackspec.size);
-            SDL_UnlockMutex(_this->mixer_lock);
-        }
-    } else if (_this->hidden->buffer) { /* Flush the buffer when paused */
-        if (SDL_GetDataQueueSize(_this->hidden->buffer) != 0) {
-            SDL_ClearDataQueue(_this->hidden->buffer, _this->hidden->input_buffer_packet_size);
-        }
-    }
+    return cpy;
+}
 
-    PIPEWIRE_pw_stream_queue_buffer(stream, pw_buf);
+static void input_callback(void *data)
+{
+    SDL_CaptureAudioThreadIterate((SDL_AudioDevice *)data);
 }
 
 static void stream_add_buffer_callback(void *data, struct pw_buffer *buffer)
 {
-    SDL_AudioDevice *_this = data;
-
-    if (_this->iscapture == SDL_FALSE) {
-        /*
-         * Clamp the output spec samples and size to the max size of the Pipewire buffer.
-         * If they exceed the maximum size of the Pipewire buffer, double buffering will be used.
-         */
-        if (_this->spec.size > buffer->buffer->datas[0].maxsize) {
-            _this->spec.samples = buffer->buffer->datas[0].maxsize / _this->hidden->stride;
-            _this->spec.size = buffer->buffer->datas[0].maxsize;
+    SDL_AudioDevice *device = (SDL_AudioDevice *) data;
+
+    if (device->iscapture == SDL_FALSE) {
+        /* Clamp the output spec samples and size to the max size of the Pipewire buffer.
+           If they exceed the maximum size of the Pipewire buffer, double buffering will be used. */
+        if (device->buffer_size > buffer->buffer->datas[0].maxsize) {
+            SDL_LockMutex(device->lock);
+            device->sample_frames = buffer->buffer->datas[0].maxsize / device->hidden->stride;
+            device->buffer_size = buffer->buffer->datas[0].maxsize;
+            SDL_UnlockMutex(device->lock);
         }
-    } else if (_this->hidden->buffer == NULL) {
-        /*
-         * The latency of source nodes can change, so buffering is always required.
-         *
-         * Ensure that the intermediate input buffer is large enough to hold the requested
-         * application packet size or a full buffer of data from Pipewire, whichever is larger.
-         *
-         * A packet size of 2 periods should be more than is ever needed.
-         */
-        _this->hidden->input_buffer_packet_size = SPA_MAX(_this->spec.size, buffer->buffer->datas[0].maxsize) * 2;
-        _this->hidden->buffer = SDL_CreateDataQueue(_this->hidden->input_buffer_packet_size, _this->hidden->input_buffer_packet_size);
     }
 
-    _this->hidden->stream_init_status |= PW_READY_FLAG_BUFFER_ADDED;
-    PIPEWIRE_pw_thread_loop_signal(_this->hidden->loop, false);
+    device->hidden->stream_init_status |= PW_READY_FLAG_BUFFER_ADDED;
+    PIPEWIRE_pw_thread_loop_signal(device->hidden->loop, false);
 }
 
 static void stream_state_changed_callback(void *data, enum pw_stream_state old, enum pw_stream_state state, const char *error)
 {
-    SDL_AudioDevice *_this = data;
+    SDL_AudioDevice *device = (SDL_AudioDevice *) data;
 
     if (state == PW_STREAM_STATE_STREAMING) {
-        _this->hidden->stream_init_status |= PW_READY_FLAG_STREAM_READY;
+        device->hidden->stream_init_status |= PW_READY_FLAG_STREAM_READY;
     }
 
     if (state == PW_STREAM_STATE_STREAMING || state == PW_STREAM_STATE_ERROR) {
-        PIPEWIRE_pw_thread_loop_signal(_this->hidden->loop, false);
+        PIPEWIRE_pw_thread_loop_signal(device->hidden->loop, false);
     }
 }
 
@@ -1109,7 +1040,7 @@ static const struct pw_stream_events stream_input_events = { PW_VERSION_STREAM_E
                                                              .add_buffer = stream_add_buffer_callback,
                                                              .process = input_callback };
 
-static int PIPEWIRE_OpenDevice(SDL_AudioDevice *_this, const char *devname)
+static int PIPEWIRE_OpenDevice(SDL_AudioDevice *device)
 {
     /*
      * NOTE: The PW_STREAM_FLAG_RT_PROCESS flag can be set to call the stream
@@ -1128,12 +1059,12 @@ static int PIPEWIRE_OpenDevice(SDL_AudioDevice *_this, const char *devname)
     struct SDL_PrivateAudioData *priv;
     struct pw_properties *props;
     const char *app_name, *app_id, *stream_name, *stream_role, *error;
-    Uint32 node_id = _this->handle == NULL ? PW_ID_ANY : PW_HANDLE_TO_ID(_this->handle);
-    SDL_bool iscapture = _this->iscapture;
+    Uint32 node_id = device->handle == NULL ? PW_ID_ANY : PW_HANDLE_TO_ID(device->handle);
+    const SDL_bool iscapture = device->iscapture;
     int res;
 
     /* Clamp the period size to sane values */
-    const int min_period = PW_MIN_SAMPLES * SPA_MAX(_this->spec.freq / PW_BASE_CLOCK_RATE, 1);
+    const int min_period = PW_MIN_SAMPLES * SPA_MAX(device->spec.freq / PW_BASE_CLOCK_RATE, 1);
 
     /* Get the hints for the application name, stream name and role */
     app_name = SDL_GetHint(SDL_HINT_AUDIO_DEVICE_APP_NAME);
@@ -1162,27 +1093,28 @@ static int PIPEWIRE_OpenDevice(SDL_AudioDevice *_this, const char *devname)
     }
 
     /* Initialize the Pipewire stream info from the SDL audio spec */
-    initialize_spa_info(&_this->spec, &spa_info);
+    initialize_spa_info(&device->spec, &spa_info);
     params = spa_format_audio_raw_build(&b, SPA_PARAM_EnumFormat, &spa_info);
     if (params == NULL) {
         return SDL_SetError("Pipewire: Failed to set audio format parameters");
     }
 
     priv = SDL_calloc(1, sizeof(struct SDL_PrivateAudioData));
-    _this->hidden = priv;
+    device->hidden = priv;
     if (priv == NULL) {
         return SDL_OutOfMemory();
     }
 
     /* Size of a single audio frame in bytes */
-    priv->stride = (SDL_AUDIO_BITSIZE(_this->spec.format) >> 3) * _this->spec.channels;
+    priv->stride = (SDL_AUDIO_BITSIZE(device->spec.format) / 8) * device->spec.channels;
 
-    if (_this->spec.samples < min_period) {
-        _this->spec.samples = min_period;
-        _this->spec.size = _this->spec.samples * priv->stride;
+    if (device->sample_frames < min_period) {
+        device->sample_frames = min_period;
     }
 
-    (void)SDL_snprintf(thread_name, sizeof(thread_name), "SDLAudio%c%ld", (iscapture) ? 'C' : 'P', (long)_this->handle);
+    SDL_UpdatedAudioDeviceFormat(device);
+
+    SDL_GetAudioThreadName(device, thread_name, sizeof(thread_name));
     priv->loop = PIPEWIRE_pw_thread_loop_new(thread_name, NULL);
     if (priv->loop == NULL) {
         return SDL_SetError("Pipewire: Failed to create stream loop (%i)", errno);
@@ -1213,9 +1145,10 @@ static int PIPEWIRE_OpenDevice(SDL_AudioDevice *_this, const char *devname)
     }
     PIPEWIRE_pw_properties_set(props, PW_KEY_NODE_NAME, stream_name);
     PIPEWIRE_pw_properties_set(props, PW_KEY_NODE_DESCRIPTION, stream_name);
-    PIPEWIRE_pw_properties_setf(props, PW_KEY_NODE_LATENCY, "%u/%i", _this->spec.samples, _this->spec.freq);
-    PIPEWIRE_pw_properties_setf(props, PW_KEY_NODE_RATE, "1/%u", _this->spec.freq);
+    PIPEWIRE_pw_properties_setf(props, PW_KEY_NODE_LATENCY, "%u/%i", device->sample_frames, device->spec.freq);
+    PIPEWIRE_pw_properties_setf(props, PW_KEY_NODE_RATE, "1/%u", device->spec.freq);
     PIPEWIRE_pw_properties_set(props, PW_KEY_NODE_ALWAYS_PROCESS, "true");
+    PIPEWIRE_pw_properties_set(props, PW_KEY_NODE_DONT_RECONNECT, "true");  // Requesting a specific device, don't migrate to new default hardware.
 
     /*
      * Pipewire 0.3.44 introduced PW_KEY_TARGET_OBJECT that takes either a path
@@ -1240,7 +1173,7 @@ static int PIPEWIRE_OpenDevice(SDL_AudioDevice *_this, const char *devname)
 
     /* Create the new stream */
     priv->stream = PIPEWIRE_pw_stream_new_simple(PIPEWIRE_pw_thread_loop_get_loop(priv->loop), stream_name, props,
-                                                 iscapture ? &stream_input_events : &stream_output_events, _this);
+                                                 iscapture ? &stream_input_events : &stream_output_events, device);
     if (priv->stream == NULL) {
         return SDL_SetError("Pipewire: Failed to create stream (%i)", errno);
     }
@@ -1268,75 +1201,35 @@ static int PIPEWIRE_OpenDevice(SDL_AudioDevice *_this, const char *devname)
         return SDL_SetError("Pipewire: Stream error: %s", error);
     }
 
-    /* If this is a capture stream, make sure the intermediate buffer was successfully allocated. */
-    if (iscapture && priv->buffer == NULL) {
-        return SDL_SetError("Pipewire: Failed to allocate source buffer");
-    }
-
     return 0;
 }
 
-static void PIPEWIRE_CloseDevice(SDL_AudioDevice *_this)
+static void PIPEWIRE_CloseDevice(SDL_AudioDevice *device)
 {
-    if (_this->hidden->loop) {
-        PIPEWIRE_pw_thread_loop_stop(_this->hidden->loop);
+    if (!device->hidden) {
+        return;
     }
 
-    if (_this->hidden->stream) {
-        PIPEWIRE_pw_stream_destroy(_this->hidden->stream);
+    if (device->hidden->loop) {
+        PIPEWIRE_pw_thread_loop_stop(device->hidden->loop);
     }
 
-    if (_this->hidden->context) {
-        PIPEWIRE_pw_context_destroy(_this->hidden->context);
+    if (device->hidden->stream) {
+        PIPEWIRE_pw_stream_destroy(device->hidden->stream);
     }
 
-    if (_this->hidden->loop) {
-        PIPEWIRE_pw_thread_loop_destroy(_this->hidden->loop);
+    if (device->hidden->context) {
+        PIPEWIRE_pw_context_destroy(device->hidden->context);
     }
 
-    if (_this->hidden->buffer) {
-        SDL_DestroyDataQueue(_this->hidden->buffer);
+    if (device->hidden->loop) {
+        PIPEWIRE_pw_thread_loop_destroy(device->hidden->loop);
     }
 
-    SDL_free(_this->hidden);
-}
-
-static int PIPEWIRE_GetDefaultAudioInfo(char **name, SDL_AudioSpec *spec, int iscapture)
-{
-    struct io_node *node;
-    char *target;
-    int ret = 0;
-
-    PIPEWIRE_pw_thread_loop_lock(hotplug_loop);
+    SDL_free(device->hidden);
+    device->hidden = NULL;
 
-    if (iscapture) {
-        if (pipewire_default_source_id == NULL) {
-            ret = SDL_SetError("PipeWire could not find a default source");
-            goto failed;
-        }
-        target = pipewire_default_source_id;
-    } else {
-        if (pipewire_default_sink_id == NULL) {
-            ret = SDL_SetError("PipeWire could not find a default sink");
-            goto failed;
-        }
-        target = pipewire_default_sink_id;
-    }
-
-    node = io_list_get_by_path(target);
-    if (node == NULL) {
-        ret = SDL_SetError("PipeWire device list is out of sync with defaults");
-        goto failed;
-    }
-
-    if (name != NULL) {
-        *name = SDL_strdup(node->name);
-    }
-    SDL_copyp(spec, &node->spec);
-
-failed:
-    PIPEWIRE_pw_thread_loop_unlock(hotplug_loop);
-    return ret;
+    SDL_AudioThreadFinalize(device);
 }
 
 static void PIPEWIRE_Deinitialize(void)
@@ -1366,13 +1259,15 @@ static SDL_bool PIPEWIRE_Init(SDL_AudioDriverImpl *impl)
     /* Set the function pointers */
     impl->DetectDevices = PIPEWIRE_DetectDevices;
     impl->OpenDevice = PIPEWIRE_OpenDevice;
-    impl->CloseDevice = PIPEWIRE_CloseDevice;
     impl->Deinitialize = PIPEWIRE_Deinitialize;
-    impl->GetDefaultAudioInfo = PIPEWIRE_GetDefaultAudioInfo;
+    impl->PlayDevice = PIPEWIRE_PlayDevice;
+    impl->GetDeviceBuf = PIPEWIRE_GetDeviceBuf;
+    impl->CaptureFromDevice = PIPEWIRE_CaptureFromDevice;
+    impl->FlushCapture = PIPEWIRE_FlushCapture;
+    impl->CloseDevice = PIPEWIRE_CloseDevice;
 
     impl->HasCaptureSupport = SDL_TRUE;
     impl->ProvidesOwnCallbackThread = SDL_TRUE;
-    impl->SupportsNonPow2Samples = SDL_TRUE;
 
     return SDL_TRUE;
 }

src/audio/pipewire/SDL_pipewire.h

@@ -32,11 +32,12 @@ struct SDL_PrivateAudioData
     struct pw_thread_loop *loop;
     struct pw_stream *stream;
     struct pw_context *context;
-    struct SDL_DataQueue *buffer;
 
-    size_t input_buffer_packet_size;
     Sint32 stride; /* Bytes-per-frame */
     int stream_init_status;
+
+    // Set in GetDeviceBuf, filled in AudioThreadIterate, queued in PlayDevice
+    struct pw_buffer *pw_buf;
 };
 
 #endif /* SDL_pipewire_h_ */

src/audio/ps2/SDL_ps2audio.c

@@ -20,8 +20,6 @@
 */
 #include "SDL_internal.h"
 
-/* Output audio to nowhere... */
-
 #include "../SDL_audio_c.h"
 #include "SDL_ps2audio.h"
 
@@ -29,23 +27,15 @@
 #include <audsrv.h>
 #include <ps2_audio_driver.h>
 
-/* The tag name used by PS2 audio */
-#define PS2AUDIO_DRIVER_NAME "ps2"
-
-static int PS2AUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
+static int PS2AUDIO_OpenDevice(SDL_AudioDevice *device)
 {
-    int i, mixlen;
-    struct audsrv_fmt_t format;
-
-    _this->hidden = (struct SDL_PrivateAudioData *)
-        SDL_malloc(sizeof(*_this->hidden));
-    if (_this->hidden == NULL) {
+    device->hidden = (struct SDL_PrivateAudioData *) SDL_calloc(1, sizeof(*device->hidden));
+    if (device->hidden == NULL) {
         return SDL_OutOfMemory();
     }
-    SDL_zerop(_this->hidden);
 
-    /* These are the native supported audio PS2 configs  */
-    switch (_this->spec.freq) {
+    // These are the native supported audio PS2 configs
+    switch (device->spec.freq) {
     case 11025:
     case 12000:
     case 22050:
@@ -53,93 +43,89 @@ static int PS2AUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
     case 32000:
     case 44100:
     case 48000:
-        _this->spec.freq = _this->spec.freq;
-        break;
+        break;  // acceptable value, keep it
     default:
-        _this->spec.freq = 48000;
+        device->spec.freq = 48000;
         break;
     }
 
-    _this->spec.samples = 512;
-    _this->spec.channels = _this->spec.channels == 1 ? 1 : 2;
-    _this->spec.format = _this->spec.format == SDL_AUDIO_S8 ? SDL_AUDIO_S8 : SDL_AUDIO_S16;
+    device->sample_frames = 512;
+    device->spec.channels = device->spec.channels == 1 ? 1 : 2;
+    device->spec.format = device->spec.format == SDL_AUDIO_S8 ? SDL_AUDIO_S8 : SDL_AUDIO_S16;
 
-    SDL_CalculateAudioSpec(&_this->spec);
-
-    format.bits = _this->spec.format == SDL_AUDIO_S8 ? 8 : 16;
-    format.freq = _this->spec.freq;
-    format.channels = _this->spec.channels;
+    struct audsrv_fmt_t format;
+    format.bits = device->spec.format == SDL_AUDIO_S8 ? 8 : 16;
+    format.freq = device->spec.freq;
+    format.channels = device->spec.channels;
 
-    _this->hidden->channel = audsrv_set_format(&format);
+    device->hidden->channel = audsrv_set_format(&format);
     audsrv_set_volume(MAX_VOLUME);
 
-    if (_this->hidden->channel < 0) {
-        SDL_aligned_free(_this->hidden->rawbuf);
-        _this->hidden->rawbuf = NULL;
+    if (device->hidden->channel < 0) {
         return SDL_SetError("Couldn't reserve hardware channel");
     }
 
-    /* Update the fragment size as size in bytes. */
-    SDL_CalculateAudioSpec(&_this->spec);
+    // Update the fragment size as size in bytes.
+    SDL_UpdatedAudioDeviceFormat(device);
 
     /* Allocate the mixing buffer.  Its size and starting address must
        be a multiple of 64 bytes.  Our sample count is already a multiple of
        64, so spec->size should be a multiple of 64 as well. */
-    mixlen = _this->spec.size * NUM_BUFFERS;
-    _this->hidden->rawbuf = (Uint8 *)SDL_aligned_alloc(64, mixlen);
-    if (_this->hidden->rawbuf == NULL) {
+    const int mixlen = device->buffer_size * NUM_BUFFERS;
+    device->hidden->rawbuf = (Uint8 *)SDL_aligned_alloc(64, mixlen);
+    if (device->hidden->rawbuf == NULL) {
         return SDL_SetError("Couldn't allocate mixing buffer");
     }
 
-    SDL_memset(_this->hidden->rawbuf, 0, mixlen);
-    for (i = 0; i < NUM_BUFFERS; i++) {
-        _this->hidden->mixbufs[i] = &_this->hidden->rawbuf[i * _this->spec.size];
+    SDL_memset(device->hidden->rawbuf, device->silence_value, mixlen);
+    for (int i = 0; i < NUM_BUFFERS; i++) {
+        device->hidden->mixbufs[i] = &device->hidden->rawbuf[i * device->buffer_size];
     }
 
-    _this->hidden->next_buffer = 0;
     return 0;
 }
 
-static void PS2AUDIO_PlayDevice(SDL_AudioDevice *_this)
+static void PS2AUDIO_PlayDevice(SDL_AudioDevice *device, const Uint8 *buffer, int buflen)
 {
-    uint8_t *mixbuf = _this->hidden->mixbufs[_this->hidden->next_buffer];
-    audsrv_play_audio((char *)mixbuf, _this->spec.size);
-
-    _this->hidden->next_buffer = (_this->hidden->next_buffer + 1) % NUM_BUFFERS;
+    audsrv_play_audio((char *)buffer, buflen);
 }
 
-/* This function waits until it is possible to write a full sound buffer */
-static void PS2AUDIO_WaitDevice(SDL_AudioDevice *_this)
+static void PS2AUDIO_WaitDevice(SDL_AudioDevice *device)
 {
-    audsrv_wait_audio(_this->spec.size);
+    audsrv_wait_audio(device->buffer_size);
 }
 
-static Uint8 *PS2AUDIO_GetDeviceBuf(SDL_AudioDevice *_this)
+static Uint8 *PS2AUDIO_GetDeviceBuf(SDL_AudioDevice *device, int *buffer_size)
 {
-    return _this->hidden->mixbufs[_this->hidden->next_buffer];
+    Uint8 *buffer = device->hidden->mixbufs[device->hidden->next_buffer];
+    device->hidden->next_buffer = (device->hidden->next_buffer + 1) % NUM_BUFFERS;
+    return buffer;
 }
 
-static void PS2AUDIO_CloseDevice(SDL_AudioDevice *_this)
+static void PS2AUDIO_CloseDevice(SDL_AudioDevice *device)
 {
-    if (_this->hidden->channel >= 0) {
-        audsrv_stop_audio();
-        _this->hidden->channel = -1;
-    }
-
-    if (_this->hidden->rawbuf != NULL) {
-        SDL_aligned_free(_this->hidden->rawbuf);
-        _this->hidden->rawbuf = NULL;
+    if (device->hidden) {
+        if (device->hidden->channel >= 0) {
+            audsrv_stop_audio();
+            device->hidden->channel = -1;
+        }
+
+        if (device->hidden->rawbuf != NULL) {
+            SDL_aligned_free(device->hidden->rawbuf);
+            device->hidden->rawbuf = NULL;
+        }
+        SDL_free(device->hidden);
+        device->hidden = NULL;
     }
 }
 
-static void PS2AUDIO_ThreadInit(SDL_AudioDevice *_this)
+static void PS2AUDIO_ThreadInit(SDL_AudioDevice *device)
 {
     /* Increase the priority of this audio thread by 1 to put it
        ahead of other SDL threads. */
-    int32_t thid;
+    const int32_t thid = GetThreadId();
     ee_thread_status_t status;
-    thid = GetThreadId();
-    if (ReferThreadStatus(GetThreadId(), &status) == 0) {
+    if (ReferThreadStatus(thid, &status) == 0) {
         ChangeThreadPriority(thid, status.current_priority - 1);
     }
 }
@@ -155,7 +141,6 @@ static SDL_bool PS2AUDIO_Init(SDL_AudioDriverImpl *impl)
         return SDL_FALSE;
     }
 
-    /* Set the function pointers */
     impl->OpenDevice = PS2AUDIO_OpenDevice;
     impl->PlayDevice = PS2AUDIO_PlayDevice;
     impl->WaitDevice = PS2AUDIO_WaitDevice;
@@ -164,7 +149,7 @@ static SDL_bool PS2AUDIO_Init(SDL_AudioDriverImpl *impl)
     impl->ThreadInit = PS2AUDIO_ThreadInit;
     impl->Deinitialize = PS2AUDIO_Deinitialize;
     impl->OnlyHasDefaultOutputDevice = SDL_TRUE;
-    return SDL_TRUE; /* this audio target is available. */
+    return SDL_TRUE; // this audio target is available.
 }
 
 AudioBootStrap PS2AUDIO_bootstrap = {

src/audio/psp/SDL_pspaudio.c

@@ -34,41 +34,34 @@
 #include <pspaudio.h>
 #include <pspthreadman.h>
 
-/* The tag name used by PSP audio */
-#define PSPAUDIO_DRIVER_NAME "psp"
-
 static inline SDL_bool isBasicAudioConfig(const SDL_AudioSpec *spec)
 {
     return spec->freq == 44100;
 }
 
-static int PSPAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
+static int PSPAUDIO_OpenDevice(SDL_AudioDevice *device)
 {
-    int format, mixlen, i;
-
-    _this->hidden = (struct SDL_PrivateAudioData *)
-        SDL_malloc(sizeof(*_this->hidden));
-    if (_this->hidden == NULL) {
+    device->hidden = (struct SDL_PrivateAudioData *) SDL_calloc(1, sizeof(*device->hidden));
+    if (device->hidden == NULL) {
         return SDL_OutOfMemory();
     }
-    SDL_zerop(_this->hidden);
 
-    /* device only natively supports S16LSB */
-    _this->spec.format = SDL_AUDIO_S16LSB;
+    // device only natively supports S16LSB
+    device->spec.format = SDL_AUDIO_S16LSB;
 
     /*  PSP has some limitations with the Audio. It fully supports 44.1KHz (Mono & Stereo),
         however with frequencies different than 44.1KHz, it just supports Stereo,
         so a resampler must be done for these scenarios */
-    if (isBasicAudioConfig(&_this->spec)) {
-        /* The sample count must be a multiple of 64. */
-        _this->spec.samples = PSP_AUDIO_SAMPLE_ALIGN(_this->spec.samples);
-        /* The number of channels (1 or 2). */
-        _this->spec.channels = _this->spec.channels == 1 ? 1 : 2;
-        format = _this->spec.channels == 1 ? PSP_AUDIO_FORMAT_MONO : PSP_AUDIO_FORMAT_STEREO;
-        _this->hidden->channel = sceAudioChReserve(PSP_AUDIO_NEXT_CHANNEL, _this->spec.samples, format);
+    if (isBasicAudioConfig(&device->spec)) {
+        // The sample count must be a multiple of 64.
+        device->sample_frames = PSP_AUDIO_SAMPLE_ALIGN(device->sample_frames);
+        // The number of channels (1 or 2).
+        device->spec.channels = device->spec.channels == 1 ? 1 : 2;
+        const int format = (device->spec.channels == 1) ? PSP_AUDIO_FORMAT_MONO : PSP_AUDIO_FORMAT_STEREO;
+        device->hidden->channel = sceAudioChReserve(PSP_AUDIO_NEXT_CHANNEL, device->sample_frames, format);
     } else {
-        /* 48000, 44100, 32000, 24000, 22050, 16000, 12000, 11050, 8000 */
-        switch (_this->spec.freq) {
+        // 48000, 44100, 32000, 24000, 22050, 16000, 12000, 11050, 8000
+        switch (device->spec.freq) {
         case 8000:
         case 11025:
         case 12000:
@@ -78,93 +71,90 @@ static int PSPAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
         case 32000:
         case 44100:
         case 48000:
-            _this->spec.freq = _this->spec.freq;
-            break;
+            break;  // acceptable, keep it
         default:
-            _this->spec.freq = 48000;
+            device->spec.freq = 48000;
             break;
         }
-        /* The number of samples to output in one output call (min 17, max 4111). */
-        _this->spec.samples = _this->spec.samples < 17 ? 17 : (_this->spec.samples > 4111 ? 4111 : _this->spec.samples);
-        _this->spec.channels = 2; /* we're forcing the hardware to stereo. */
-        _this->hidden->channel = sceAudioSRCChReserve(_this->spec.samples, _this->spec.freq, 2);
+        // The number of samples to output in one output call (min 17, max 4111).
+        device->sample_frames = device->sample_frames < 17 ? 17 : (device->sample_frames > 4111 ? 4111 : device->sample_frames);
+        device->spec.channels = 2; // we're forcing the hardware to stereo.
+        device->hidden->channel = sceAudioSRCChReserve(device->sample_frames, device->spec.freq, 2);
     }
 
-    if (_this->hidden->channel < 0) {
-        SDL_aligned_free(_this->hidden->rawbuf);
-        _this->hidden->rawbuf = NULL;
+    if (device->hidden->channel < 0) {
         return SDL_SetError("Couldn't reserve hardware channel");
     }
 
-    /* Update the fragment size as size in bytes. */
-    SDL_CalculateAudioSpec(&_this->spec);
+    // Update the fragment size as size in bytes.
+    SDL_UpdatedAudioDeviceFormat(device);
 
     /* Allocate the mixing buffer.  Its size and starting address must
        be a multiple of 64 bytes.  Our sample count is already a multiple of
        64, so spec->size should be a multiple of 64 as well. */
-    mixlen = _this->spec.size * NUM_BUFFERS;
-    _this->hidden->rawbuf = (Uint8 *)SDL_aligned_alloc(64, mixlen);
-    if (_this->hidden->rawbuf == NULL) {
+    const int mixlen = device->buffer_size * NUM_BUFFERS;
+    device->hidden->rawbuf = (Uint8 *)SDL_aligned_alloc(64, mixlen);
+    if (device->hidden->rawbuf == NULL) {
         return SDL_SetError("Couldn't allocate mixing buffer");
     }
 
-    SDL_memset(_this->hidden->rawbuf, 0, mixlen);
-    for (i = 0; i < NUM_BUFFERS; i++) {
-        _this->hidden->mixbufs[i] = &_this->hidden->rawbuf[i * _this->spec.size];
+    SDL_memset(device->hidden->rawbuf, device->silence_value, mixlen);
+    for (int i = 0; i < NUM_BUFFERS; i++) {
+        device->hidden->mixbufs[i] = &device->hidden->rawbuf[i * device->buffer_size];
     }
 
-    _this->hidden->next_buffer = 0;
     return 0;
 }
 
-static void PSPAUDIO_PlayDevice(SDL_AudioDevice *_this)
+static void PSPAUDIO_PlayDevice(SDL_AudioDevice *device, const Uint8 *buffer, int buflen)
 {
-    Uint8 *mixbuf = _this->hidden->mixbufs[_this->hidden->next_buffer];
-    if (!isBasicAudioConfig(&_this->spec)) {
-        SDL_assert(_this->spec.channels == 2);
-        sceAudioSRCOutputBlocking(PSP_AUDIO_VOLUME_MAX, mixbuf);
+    if (!isBasicAudioConfig(&device->spec)) {
+        SDL_assert(device->spec.channels == 2);
+        sceAudioSRCOutputBlocking(PSP_AUDIO_VOLUME_MAX, (void *) buffer);
     } else {
-        sceAudioOutputPannedBlocking(_this->hidden->channel, PSP_AUDIO_VOLUME_MAX, PSP_AUDIO_VOLUME_MAX, mixbuf);
+        sceAudioOutputPannedBlocking(device->hidden->channel, PSP_AUDIO_VOLUME_MAX, PSP_AUDIO_VOLUME_MAX, (void *) buffer);
     }
-
-    _this->hidden->next_buffer = (_this->hidden->next_buffer + 1) % NUM_BUFFERS;
 }
 
-/* This function waits until it is possible to write a full sound buffer */
-static void PSPAUDIO_WaitDevice(SDL_AudioDevice *_this)
+static void PSPAUDIO_WaitDevice(SDL_AudioDevice *device)
 {
-    /* Because we block when sending audio, there's no need for this function to do anything. */
+    // Because we block when sending audio, there's no need for this function to do anything.
 }
 
-static Uint8 *PSPAUDIO_GetDeviceBuf(SDL_AudioDevice *_this)
+static Uint8 *PSPAUDIO_GetDeviceBuf(SDL_AudioDevice *device, int *buffer_size)
 {
-    return _this->hidden->mixbufs[_this->hidden->next_buffer];
+    Uint8 *buffer = device->hidden->mixbufs[device->hidden->next_buffer];
+    device->hidden->next_buffer = (device->hidden->next_buffer + 1) % NUM_BUFFERS;
+    return buffer;
 }
 
-static void PSPAUDIO_CloseDevice(SDL_AudioDevice *_this)
+static void PSPAUDIO_CloseDevice(SDL_AudioDevice *device)
 {
-    if (_this->hidden->channel >= 0) {
-        if (!isBasicAudioConfig(&_this->spec)) {
-            sceAudioSRCChRelease();
-        } else {
-            sceAudioChRelease(_this->hidden->channel);
+    if (device->hidden) {
+        if (device->hidden->channel >= 0) {
+            if (!isBasicAudioConfig(&device->spec)) {
+                sceAudioSRCChRelease();
+            } else {
+                sceAudioChRelease(device->hidden->channel);
+            }
+            device->hidden->channel = -1;
         }
-        _this->hidden->channel = -1;
-    }
 
-    if (_this->hidden->rawbuf != NULL) {
-        SDL_aligned_free(_this->hidden->rawbuf);
-        _this->hidden->rawbuf = NULL;
+        if (device->hidden->rawbuf != NULL) {
+            SDL_aligned_free(device->hidden->rawbuf);
+            device->hidden->rawbuf = NULL;
+        }
+        SDL_free(device->hidden);
+        device->hidden = NULL;
     }
 }
 
-static void PSPAUDIO_ThreadInit(SDL_AudioDevice *_this)
+static void PSPAUDIO_ThreadInit(SDL_AudioDevice *device)
 {
     /* Increase the priority of this audio thread by 1 to put it
        ahead of other SDL threads. */
-    SceUID thid;
+    const SceUID thid = sceKernelGetThreadId();
     SceKernelThreadInfo status;
-    thid = sceKernelGetThreadId();
     status.size = sizeof(SceKernelThreadInfo);
     if (sceKernelReferThreadStatus(thid, &status) == 0) {
         sceKernelChangeThreadPriority(thid, status.currentPriority - 1);
@@ -173,25 +163,20 @@ static void PSPAUDIO_ThreadInit(SDL_AudioDevice *_this)
 
 static SDL_bool PSPAUDIO_Init(SDL_AudioDriverImpl *impl)
 {
-    /* Set the function pointers */
     impl->OpenDevice = PSPAUDIO_OpenDevice;
     impl->PlayDevice = PSPAUDIO_PlayDevice;
     impl->WaitDevice = PSPAUDIO_WaitDevice;
     impl->GetDeviceBuf = PSPAUDIO_GetDeviceBuf;
     impl->CloseDevice = PSPAUDIO_CloseDevice;
     impl->ThreadInit = PSPAUDIO_ThreadInit;
-
-    /* PSP audio device */
     impl->OnlyHasDefaultOutputDevice = SDL_TRUE;
-    /*
-    impl->HasCaptureSupport = SDL_TRUE;
-    impl->OnlyHasDefaultCaptureDevice = SDL_TRUE;
-    */
-    return SDL_TRUE; /* this audio target is available. */
+    //impl->HasCaptureSupport = SDL_TRUE;
+    //impl->OnlyHasDefaultCaptureDevice = SDL_TRUE;
+    return SDL_TRUE;
 }
 
 AudioBootStrap PSPAUDIO_bootstrap = {
     "psp", "PSP audio driver", PSPAUDIO_Init, SDL_FALSE
 };
 
-#endif /* SDL_AUDIO_DRIVER_PSP */
+#endif // SDL_AUDIO_DRIVER_PSP

src/audio/pulseaudio/SDL_pulseaudio.c

@@ -43,13 +43,12 @@ static pa_context *pulseaudio_context = NULL;
 static SDL_Thread *pulseaudio_hotplug_thread = NULL;
 static SDL_AtomicInt pulseaudio_hotplug_thread_active;
 
-/* These are the OS identifiers (i.e. ALSA strings)... */
+// These are the OS identifiers (i.e. ALSA strings)...
 static char *default_sink_path = NULL;
 static char *default_source_path = NULL;
-/* ... and these are the descriptions we use in GetDefaultAudioInfo. */
-static char *default_sink_name = NULL;
-static char *default_source_name = NULL;
-
+// ... and these are the PulseAudio device indices of the default devices.
+static uint32_t default_sink_index = 0;
+static uint32_t default_source_index = 0;
 
 static const char *(*PULSEAUDIO_pa_get_library_version)(void);
 static pa_channel_map *(*PULSEAUDIO_pa_channel_map_init_auto)(
@@ -359,12 +358,6 @@ failed:
     return -1;
 }
 
-/* This function waits until it is possible to write a full sound buffer */
-static void PULSEAUDIO_WaitDevice(SDL_AudioDevice *_this)
-{
-    /* this is a no-op; we wait in PULSEAUDIO_PlayDevice now. */
-}
-
 static void WriteCallback(pa_stream *p, size_t nbytes, void *userdata)
 {
     struct SDL_PrivateAudioData *h = (struct SDL_PrivateAudioData *)userdata;
@@ -373,50 +366,56 @@ static void WriteCallback(pa_stream *p, size_t nbytes, void *userdata)
     PULSEAUDIO_pa_threaded_mainloop_signal(pulseaudio_threaded_mainloop, 0);
 }
 
-static void PULSEAUDIO_PlayDevice(SDL_AudioDevice *_this)
+/* This function waits until it is possible to write a full sound buffer */
+static void PULSEAUDIO_WaitDevice(SDL_AudioDevice *device)
 {
-    struct SDL_PrivateAudioData *h = _this->hidden;
-    int available = h->mixlen;
-    int written = 0;
-    int cpy;
+    struct SDL_PrivateAudioData *h = device->hidden;
 
     /*printf("PULSEAUDIO PLAYDEVICE START! mixlen=%d\n", available);*/
 
     PULSEAUDIO_pa_threaded_mainloop_lock(pulseaudio_threaded_mainloop);
 
-    while (SDL_AtomicGet(&_this->enabled) && (available > 0)) {
-        cpy = SDL_min(h->bytes_requested, available);
-        if (cpy) {
-            if (PULSEAUDIO_pa_stream_write(h->stream, h->mixbuf + written, cpy, NULL, 0LL, PA_SEEK_RELATIVE) < 0) {
-                SDL_OpenedAudioDeviceDisconnected(_this);
-                break;
-            }
-            /*printf("PULSEAUDIO FEED! nbytes=%u\n", (unsigned int) cpy);*/
-            h->bytes_requested -= cpy;
-            written += cpy;
-            available -= cpy;
-        }
-
-        if (available > 0) {
-            /* let WriteCallback fire if necessary. */
-            /*printf("PULSEAUDIO WAIT IN PLAYDEVICE!\n");*/
-            PULSEAUDIO_pa_threaded_mainloop_wait(pulseaudio_threaded_mainloop);
+    while (!SDL_AtomicGet(&device->shutdown) && (h->bytes_requested < (device->buffer_size / 2))) {
+        /*printf("PULSEAUDIO WAIT IN WAITDEVICE!\n");*/
+        PULSEAUDIO_pa_threaded_mainloop_wait(pulseaudio_threaded_mainloop);
 
-            if ((PULSEAUDIO_pa_context_get_state(pulseaudio_context) != PA_CONTEXT_READY) || (PULSEAUDIO_pa_stream_get_state(h->stream) != PA_STREAM_READY)) {
-                /*printf("PULSEAUDIO DEVICE FAILURE IN PLAYDEVICE!\n");*/
-                SDL_OpenedAudioDeviceDisconnected(_this);
-                break;
-            }
+        if ((PULSEAUDIO_pa_context_get_state(pulseaudio_context) != PA_CONTEXT_READY) || (PULSEAUDIO_pa_stream_get_state(h->stream) != PA_STREAM_READY)) {
+            /*printf("PULSEAUDIO DEVICE FAILURE IN WAITDEVICE!\n");*/
+            SDL_AudioDeviceDisconnected(device);
+            break;
         }
     }
+    PULSEAUDIO_pa_threaded_mainloop_unlock(pulseaudio_threaded_mainloop);
+}
+
+static void PULSEAUDIO_PlayDevice(SDL_AudioDevice *device, const Uint8 *buffer, int buffer_size)
+{
+    struct SDL_PrivateAudioData *h = device->hidden;
 
+    /*printf("PULSEAUDIO PLAYDEVICE START! mixlen=%d\n", available);*/
+
+    SDL_assert(h->bytes_requested >= buffer_size);
+
+    PULSEAUDIO_pa_threaded_mainloop_lock(pulseaudio_threaded_mainloop);
+    const int rc = PULSEAUDIO_pa_stream_write(h->stream, buffer, buffer_size, NULL, 0LL, PA_SEEK_RELATIVE);
     PULSEAUDIO_pa_threaded_mainloop_unlock(pulseaudio_threaded_mainloop);
+
+    if (rc < 0) {
+        SDL_AudioDeviceDisconnected(device);
+        return;
+    }
+
+    /*printf("PULSEAUDIO FEED! nbytes=%d\n", buffer_size);*/
+    h->bytes_requested -= buffer_size;
+
     /*printf("PULSEAUDIO PLAYDEVICE END! written=%d\n", written);*/
 }
 
-static Uint8 *PULSEAUDIO_GetDeviceBuf(SDL_AudioDevice *_this)
+static Uint8 *PULSEAUDIO_GetDeviceBuf(SDL_AudioDevice *device, int *buffer_size)
 {
-    return _this->hidden->mixbuf;
+    struct SDL_PrivateAudioData *h = device->hidden;
+    *buffer_size = SDL_min(*buffer_size, h->bytes_requested);
+    return device->hidden->mixbuf;
 }
 
 static void ReadCallback(pa_stream *p, size_t nbytes, void *userdata)
@@ -425,67 +424,70 @@ static void ReadCallback(pa_stream *p, size_t nbytes, void *userdata)
     PULSEAUDIO_pa_threaded_mainloop_signal(pulseaudio_threaded_mainloop, 0);  /* the capture code queries what it needs, we just need to signal to end any wait */
 }
 
-static int PULSEAUDIO_CaptureFromDevice(SDL_AudioDevice *_this, void *buffer, int buflen)
+static void PULSEAUDIO_WaitCaptureDevice(SDL_AudioDevice *device)
 {
-    struct SDL_PrivateAudioData *h = _this->hidden;
-    const void *data = NULL;
-    size_t nbytes = 0;
-    int retval = 0;
+    struct SDL_PrivateAudioData *h = device->hidden;
+
+    if (h->capturebuf != NULL) {
+        return;  // there's still data available to read.
+    }
 
     PULSEAUDIO_pa_threaded_mainloop_lock(pulseaudio_threaded_mainloop);
 
-    while (SDL_AtomicGet(&_this->enabled)) {
-        if (h->capturebuf != NULL) {
-            const int cpy = SDL_min(buflen, h->capturelen);
-            SDL_memcpy(buffer, h->capturebuf, cpy);
-            /*printf("PULSEAUDIO: fed %d captured bytes\n", cpy);*/
-            h->capturebuf += cpy;
-            h->capturelen -= cpy;
-            if (h->capturelen == 0) {
-                h->capturebuf = NULL;
-                PULSEAUDIO_pa_stream_drop(h->stream); /* done with this fragment. */
-            }
-            retval = cpy; /* new data, return it. */
+    while (!SDL_AtomicGet(&device->shutdown)) {
+        PULSEAUDIO_pa_threaded_mainloop_wait(pulseaudio_threaded_mainloop);
+        if ((PULSEAUDIO_pa_context_get_state(pulseaudio_context) != PA_CONTEXT_READY) || (PULSEAUDIO_pa_stream_get_state(h->stream) != PA_STREAM_READY)) {
+            //printf("PULSEAUDIO DEVICE FAILURE IN WAITCAPTUREDEVICE!\n");
+            SDL_AudioDeviceDisconnected(device);
             break;
-        }
-
-        while (SDL_AtomicGet(&_this->enabled) && (PULSEAUDIO_pa_stream_readable_size(h->stream) == 0)) {
-            PULSEAUDIO_pa_threaded_mainloop_wait(pulseaudio_threaded_mainloop);
-            if ((PULSEAUDIO_pa_context_get_state(pulseaudio_context) != PA_CONTEXT_READY) || (PULSEAUDIO_pa_stream_get_state(h->stream) != PA_STREAM_READY)) {
-                /*printf("PULSEAUDIO DEVICE FAILURE IN CAPTUREFROMDEVICE!\n");*/
-                SDL_OpenedAudioDeviceDisconnected(_this);
-                retval = -1;
+        } else if (PULSEAUDIO_pa_stream_readable_size(h->stream) > 0) {
+            // a new fragment is available!
+            const void *data = NULL;
+            size_t nbytes = 0;
+            PULSEAUDIO_pa_stream_peek(h->stream, &data, &nbytes);
+            SDL_assert(nbytes > 0);
+            if (data == NULL) {  // If NULL, then the buffer had a hole, ignore that
+                PULSEAUDIO_pa_stream_drop(h->stream);  // drop this fragment.
+            } else {
+                // store this fragment's data for use with CaptureFromDevice
+                //printf("PULSEAUDIO: captured %d new bytes\n", (int) nbytes);
+                h->capturebuf = (const Uint8 *)data;
+                h->capturelen = nbytes;
                 break;
             }
         }
+    }
 
-        if ((retval == -1) || !SDL_AtomicGet(&_this->enabled)) {  /* in case this happened while we were blocking. */
-            retval = -1;
-            break;
-        }
+    PULSEAUDIO_pa_threaded_mainloop_unlock(pulseaudio_threaded_mainloop);
+}
 
-        /* a new fragment is available! */
-        PULSEAUDIO_pa_stream_peek(h->stream, &data, &nbytes);
-        SDL_assert(nbytes > 0);
-        /* If data == NULL, then the buffer had a hole, ignore that */
-        if (data == NULL) {
-            PULSEAUDIO_pa_stream_drop(h->stream); /* drop this fragment. */
-        } else {
-            /* store this fragment's data, start feeding it to SDL. */
-            /*printf("PULSEAUDIO: captured %d new bytes\n", (int) nbytes);*/
-            h->capturebuf = (const Uint8 *)data;
-            h->capturelen = nbytes;
+static int PULSEAUDIO_CaptureFromDevice(SDL_AudioDevice *device, void *buffer, int buflen)
+{
+    struct SDL_PrivateAudioData *h = device->hidden;
+
+    if (h->capturebuf != NULL) {
+        const int cpy = SDL_min(buflen, h->capturelen);
+        if (cpy > 0) {
+            //printf("PULSEAUDIO: fed %d captured bytes\n", cpy);
+            SDL_memcpy(buffer, h->capturebuf, cpy);
+            h->capturebuf += cpy;
+            h->capturelen -= cpy;
+        }
+        if (h->capturelen == 0) {
+            h->capturebuf = NULL;
+            PULSEAUDIO_pa_threaded_mainloop_lock(pulseaudio_threaded_mainloop);  // don't know if you _have_ to lock for this, but just in case.
+            PULSEAUDIO_pa_stream_drop(h->stream); // done with this fragment.
+            PULSEAUDIO_pa_threaded_mainloop_unlock(pulseaudio_threaded_mainloop);
         }
+        return cpy; /* new data, return it. */
     }
 
-    PULSEAUDIO_pa_threaded_mainloop_unlock(pulseaudio_threaded_mainloop);
-
-    return retval;
+    return 0;
 }
 
-static void PULSEAUDIO_FlushCapture(SDL_AudioDevice *_this)
+static void PULSEAUDIO_FlushCapture(SDL_AudioDevice *device)
 {
-    struct SDL_PrivateAudioData *h = _this->hidden;
+    struct SDL_PrivateAudioData *h = device->hidden;
     const void *data = NULL;
     size_t nbytes = 0;
 
@@ -497,11 +499,11 @@ static void PULSEAUDIO_FlushCapture(SDL_AudioDevice *_this)
         h->capturelen = 0;
     }
 
-    while (SDL_AtomicGet(&_this->enabled) && (PULSEAUDIO_pa_stream_readable_size(h->stream) > 0)) {
+    while (!SDL_AtomicGet(&device->shutdown) && (PULSEAUDIO_pa_stream_readable_size(h->stream) > 0)) {
         PULSEAUDIO_pa_threaded_mainloop_wait(pulseaudio_threaded_mainloop);
         if ((PULSEAUDIO_pa_context_get_state(pulseaudio_context) != PA_CONTEXT_READY) || (PULSEAUDIO_pa_stream_get_state(h->stream) != PA_STREAM_READY)) {
             /*printf("PULSEAUDIO DEVICE FAILURE IN FLUSHCAPTURE!\n");*/
-            SDL_OpenedAudioDeviceDisconnected(_this);
+            SDL_AudioDeviceDisconnected(device);
             break;
         }
 
@@ -515,22 +517,23 @@ static void PULSEAUDIO_FlushCapture(SDL_AudioDevice *_this)
     PULSEAUDIO_pa_threaded_mainloop_unlock(pulseaudio_threaded_mainloop);
 }
 
-static void PULSEAUDIO_CloseDevice(SDL_AudioDevice *_this)
+static void PULSEAUDIO_CloseDevice(SDL_AudioDevice *device)
 {
     PULSEAUDIO_pa_threaded_mainloop_lock(pulseaudio_threaded_mainloop);
 
-    if (_this->hidden->stream) {
-        if (_this->hidden->capturebuf != NULL) {
-            PULSEAUDIO_pa_stream_drop(_this->hidden->stream);
+    if (device->hidden->stream) {
+        if (device->hidden->capturebuf != NULL) {
+            PULSEAUDIO_pa_stream_drop(device->hidden->stream);
         }
-        PULSEAUDIO_pa_stream_disconnect(_this->hidden->stream);
-        PULSEAUDIO_pa_stream_unref(_this->hidden->stream);
+        PULSEAUDIO_pa_stream_disconnect(device->hidden->stream);
+        PULSEAUDIO_pa_stream_unref(device->hidden->stream);
     }
+    PULSEAUDIO_pa_threaded_mainloop_signal(pulseaudio_threaded_mainloop, 0);  // in case the device thread is waiting somewhere, this will unblock it.
     PULSEAUDIO_pa_threaded_mainloop_unlock(pulseaudio_threaded_mainloop);
 
-    SDL_free(_this->hidden->mixbuf);
-    SDL_free(_this->hidden->device_name);
-    SDL_free(_this->hidden);
+    SDL_free(device->hidden->mixbuf);
+    SDL_free(device->hidden->device_name);
+    SDL_free(device->hidden);
 }
 
 static void SinkDeviceNameCallback(pa_context *c, const pa_sink_info *i, int is_last, void *data)
@@ -551,15 +554,13 @@ static void SourceDeviceNameCallback(pa_context *c, const pa_source_info *i, int
     PULSEAUDIO_pa_threaded_mainloop_signal(pulseaudio_threaded_mainloop, 0);
 }
 
-static SDL_bool FindDeviceName(struct SDL_PrivateAudioData *h, const SDL_bool iscapture, void *handle)
+static SDL_bool FindDeviceName(SDL_AudioDevice *device)
 {
-    const uint32_t idx = ((uint32_t)((intptr_t)handle)) - 1;
-
-    if (handle == NULL) { /* NULL == default device. */
-        return SDL_TRUE;
-    }
+    struct SDL_PrivateAudioData *h = device->hidden;
+    SDL_assert(device->handle != NULL);  // this was a thing in SDL2, but shouldn't be in SDL3.
+    const uint32_t idx = ((uint32_t)((intptr_t)device->handle)) - 1;
 
-    if (iscapture) {
+    if (device->iscapture) {
         WaitForPulseOperation(PULSEAUDIO_pa_context_get_source_info_by_index(pulseaudio_context, idx, SourceDeviceNameCallback, &h->device_name));
     } else {
         WaitForPulseOperation(PULSEAUDIO_pa_context_get_sink_info_by_index(pulseaudio_context, idx, SinkDeviceNameCallback, &h->device_name));
@@ -573,8 +574,9 @@ static void PulseStreamStateChangeCallback(pa_stream *stream, void *userdata)
     PULSEAUDIO_pa_threaded_mainloop_signal(pulseaudio_threaded_mainloop, 0);  /* just signal any waiting code, it can look up the details. */
 }
 
-static int PULSEAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
+static int PULSEAUDIO_OpenDevice(SDL_AudioDevice *device)
 {
+    const SDL_bool iscapture = device->iscapture;
     struct SDL_PrivateAudioData *h = NULL;
     SDL_AudioFormat test_format;
     const SDL_AudioFormat *closefmts;
@@ -582,7 +584,6 @@ static int PULSEAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
     pa_buffer_attr paattr;
     pa_channel_map pacmap;
     pa_stream_flags_t flags = 0;
-    SDL_bool iscapture = _this->iscapture;
     int format = PA_SAMPLE_INVALID;
     int retval = 0;
 
@@ -590,14 +591,13 @@ static int PULSEAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
     SDL_assert(pulseaudio_context != NULL);
 
     /* Initialize all variables that we clean on shutdown */
-    h = _this->hidden = (struct SDL_PrivateAudioData *)SDL_malloc(sizeof(*_this->hidden));
-    if (_this->hidden == NULL) {
+    h = device->hidden = (struct SDL_PrivateAudioData *)SDL_calloc(1, sizeof(*device->hidden));
+    if (device->hidden == NULL) {
         return SDL_OutOfMemory();
     }
-    SDL_zerop(_this->hidden);
 
     /* Try for a closest match on audio format */
-    closefmts = SDL_ClosestAudioFormats(_this->spec.format);
+    closefmts = SDL_ClosestAudioFormats(device->spec.format);
     while ((test_format = *(closefmts++)) != 0) {
 #ifdef DEBUG_AUDIO
         fprintf(stderr, "Trying format 0x%4.4x\n", test_format);
@@ -632,28 +632,27 @@ static int PULSEAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
     if (!test_format) {
         return SDL_SetError("pulseaudio: Unsupported audio format");
     }
-    _this->spec.format = test_format;
+    device->spec.format = test_format;
     paspec.format = format;
 
     /* Calculate the final parameters for this audio specification */
-    SDL_CalculateAudioSpec(&_this->spec);
+    SDL_UpdatedAudioDeviceFormat(device);
 
     /* Allocate mixing buffer */
     if (!iscapture) {
-        h->mixlen = _this->spec.size;
-        h->mixbuf = (Uint8 *)SDL_malloc(h->mixlen);
+        h->mixbuf = (Uint8 *)SDL_malloc(device->buffer_size);
         if (h->mixbuf == NULL) {
             return SDL_OutOfMemory();
         }
-        SDL_memset(h->mixbuf, _this->spec.silence, _this->spec.size);
+        SDL_memset(h->mixbuf, device->silence_value, device->buffer_size);
     }
 
-    paspec.channels = _this->spec.channels;
-    paspec.rate = _this->spec.freq;
+    paspec.channels = device->spec.channels;
+    paspec.rate = device->spec.freq;
 
     /* Reduced prebuffering compared to the defaults. */
-    paattr.fragsize = _this->spec.size;
-    paattr.tlength = h->mixlen;
+    paattr.fragsize = device->buffer_size;
+    paattr.tlength = device->buffer_size;
     paattr.prebuf = -1;
     paattr.maxlength = -1;
     paattr.minreq = -1;
@@ -661,14 +660,13 @@ static int PULSEAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
 
     PULSEAUDIO_pa_threaded_mainloop_lock(pulseaudio_threaded_mainloop);
 
-    if (!FindDeviceName(h, iscapture, _this->handle)) {
+    if (!FindDeviceName(device)) {
         retval = SDL_SetError("Requested PulseAudio sink/source missing?");
     } else {
         const char *name = SDL_GetHint(SDL_HINT_AUDIO_DEVICE_STREAM_NAME);
         /* The SDL ALSA output hints us that we use Windows' channel mapping */
         /* https://bugzilla.libsdl.org/show_bug.cgi?id=110 */
-        PULSEAUDIO_pa_channel_map_init_auto(&pacmap, _this->spec.channels,
-                                            PA_CHANNEL_MAP_WAVEEX);
+        PULSEAUDIO_pa_channel_map_init_auto(&pacmap, device->spec.channels, PA_CHANNEL_MAP_WAVEEX);
 
         h->stream = PULSEAUDIO_pa_stream_new(
             pulseaudio_context,
@@ -684,11 +682,8 @@ static int PULSEAUDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
 
             PULSEAUDIO_pa_stream_set_state_callback(h->stream, PulseStreamStateChangeCallback, NULL);
 
-            /* now that we have multi-device support, don't move a stream from
-                a device that was unplugged to something else, unless we're default. */
-            if (h->device_name != NULL) {
-                flags |= PA_STREAM_DONT_MOVE;
-            }
+            // SDL manages device moves if the default changes, so don't ever let Pulse automatically migrate this stream.
+            flags |= PA_STREAM_DONT_MOVE;
 
             if (iscapture) {
                 PULSEAUDIO_pa_stream_set_read_callback(h->stream, ReadCallback, h);
@@ -744,62 +739,46 @@ static SDL_AudioFormat PulseFormatToSDLFormat(pa_sample_format_t format)
     }
 }
 
-/* This is called when PulseAudio adds an output ("sink") device. */
+// This is called when PulseAudio adds an output ("sink") device.
+// !!! FIXME: this is almost identical to SourceInfoCallback, merge the two.
 static void SinkInfoCallback(pa_context *c, const pa_sink_info *i, int is_last, void *data)
 {
-    SDL_AudioSpec spec;
-    SDL_bool add = (SDL_bool)((intptr_t)data);
     if (i) {
-        spec.freq = i->sample_spec.rate;
-        spec.channels = i->sample_spec.channels;
-        spec.format = PulseFormatToSDLFormat(i->sample_spec.format);
-        spec.silence = 0;
-        spec.samples = 0;
-        spec.size = 0;
-        spec.callback = NULL;
-        spec.userdata = NULL;
+        const SDL_bool add = (SDL_bool) ((intptr_t)data);
 
         if (add) {
+            SDL_AudioSpec spec;
+            spec.format = PulseFormatToSDLFormat(i->sample_spec.format);
+            spec.channels = i->sample_spec.channels;
+            spec.freq = i->sample_spec.rate;
             SDL_AddAudioDevice(SDL_FALSE, i->description, &spec, (void *)((intptr_t)i->index + 1));
         }
 
         if (default_sink_path != NULL && SDL_strcmp(i->name, default_sink_path) == 0) {
-            if (default_sink_name != NULL) {
-                SDL_free(default_sink_name);
-            }
-            default_sink_name = SDL_strdup(i->description);
+            default_sink_index = i->index;
         }
     }
     PULSEAUDIO_pa_threaded_mainloop_signal(pulseaudio_threaded_mainloop, 0);
 }
 
 /* This is called when PulseAudio adds a capture ("source") device. */
+// !!! FIXME: this is almost identical to SinkInfoCallback, merge the two.
 static void SourceInfoCallback(pa_context *c, const pa_source_info *i, int is_last, void *data)
 {
-    SDL_AudioSpec spec;
-    SDL_bool add = (SDL_bool)((intptr_t)data);
-    if (i) {
-        /* Maybe skip "monitor" sources. These are just output from other sinks. */
-        if (include_monitors || (i->monitor_of_sink == PA_INVALID_INDEX)) {
-            spec.freq = i->sample_spec.rate;
-            spec.channels = i->sample_spec.channels;
+    /* Maybe skip "monitor" sources. These are just output from other sinks. */
+    if (i && (include_monitors || (i->monitor_of_sink == PA_INVALID_INDEX))) {
+        const SDL_bool add = (SDL_bool) ((intptr_t)data);
+
+        if (add) {
+            SDL_AudioSpec spec;
             spec.format = PulseFormatToSDLFormat(i->sample_spec.format);
-            spec.silence = 0;
-            spec.samples = 0;
-            spec.size = 0;
-            spec.callback = NULL;
-            spec.userdata = NULL;
-
-            if (add) {
-                SDL_AddAudioDevice(SDL_TRUE, i->description, &spec, (void *)((intptr_t)i->index + 1));
-            }
+            spec.channels = i->sample_spec.channels;
+            spec.freq = i->sample_spec.rate;
+            SDL_AddAudioDevice(SDL_TRUE, i->description, &spec, (void *)((intptr_t)i->index + 1));
+        }
 
-            if (default_source_path != NULL && SDL_strcmp(i->name, default_source_path) == 0) {
-                if (default_source_name != NULL) {
-                    SDL_free(default_source_name);
-                }
-                default_source_name = SDL_strdup(i->description);
-            }
+        if (default_source_path != NULL && SDL_strcmp(i->name, default_source_path) == 0) {
+            default_source_index = i->index;
         }
     }
     PULSEAUDIO_pa_threaded_mainloop_signal(pulseaudio_threaded_mainloop, 0);
@@ -807,14 +786,22 @@ static void SourceInfoCallback(pa_context *c, const pa_source_info *i, int is_la
 
 static void ServerInfoCallback(pa_context *c, const pa_server_info *i, void *data)
 {
-    SDL_free(default_sink_path);
-    SDL_free(default_source_path);
-    default_sink_path = SDL_strdup(i->default_sink_name);
-    default_source_path = SDL_strdup(i->default_source_name);
+    if (!default_sink_path || (SDL_strcmp(i->default_sink_name, default_sink_path) != 0)) {
+        /*printf("DEFAULT SINK PATH CHANGED TO '%s'\n", i->default_sink_name);*/
+        SDL_free(default_sink_path);
+        default_sink_path = SDL_strdup(i->default_sink_name);
+    }
+
+    if (!default_source_path || (SDL_strcmp(i->default_source_name, default_source_path) != 0)) {
+        /*printf("DEFAULT SOURCE PATH CHANGED TO '%s'\n", i->default_source_name);*/
+        SDL_free(default_source_path);
+        default_source_path = SDL_strdup(i->default_source_name);
+    }
+
     PULSEAUDIO_pa_threaded_mainloop_signal(pulseaudio_threaded_mainloop, 0);
 }
 
-/* This is called when PulseAudio has a device connected/removed/changed. */
+// This is called when PulseAudio has a device connected/removed/changed. */
 static void HotplugCallback(pa_context *c, pa_subscription_event_type_t t, uint32_t idx, void *data)
 {
     const SDL_bool added = ((t & PA_SUBSCRIPTION_EVENT_TYPE_MASK) == PA_SUBSCRIPTION_EVENT_NEW);
@@ -825,29 +812,41 @@ static void HotplugCallback(pa_context *c, pa_subscription_event_type_t t, uint3
         const SDL_bool sink = ((t & PA_SUBSCRIPTION_EVENT_FACILITY_MASK) == PA_SUBSCRIPTION_EVENT_SINK);
         const SDL_bool source = ((t & PA_SUBSCRIPTION_EVENT_FACILITY_MASK) == PA_SUBSCRIPTION_EVENT_SOURCE);
 
-        /* adds need sink details from the PulseAudio server. Another callback... */
-        /* (just unref all these operations right away, because we aren't going to wait on them and their callbacks will handle any work, so they can free as soon as that happens.) */
+        if (changed) {
+            PULSEAUDIO_pa_operation_unref(PULSEAUDIO_pa_context_get_server_info(pulseaudio_context, ServerInfoCallback, NULL));
+        }
+
+        /* adds need sink details from the PulseAudio server. Another callback...
+           (just unref all these operations right away, because we aren't going to wait on them
+           and their callbacks will handle any work, so they can free as soon as that happens.) */
         if ((added || changed) && sink) {
-            if (changed) {
-                PULSEAUDIO_pa_operation_unref(PULSEAUDIO_pa_context_get_server_info(pulseaudio_context, ServerInfoCallback, NULL));
-            }
             PULSEAUDIO_pa_operation_unref(PULSEAUDIO_pa_context_get_sink_info_by_index(pulseaudio_context, idx, SinkInfoCallback, (void *)((intptr_t)added)));
         } else if ((added || changed) && source) {
-            if (changed) {
-                PULSEAUDIO_pa_operation_unref(PULSEAUDIO_pa_context_get_server_info(pulseaudio_context, ServerInfoCallback, NULL));
-            }
             PULSEAUDIO_pa_operation_unref(PULSEAUDIO_pa_context_get_source_info_by_index(pulseaudio_context, idx, SourceInfoCallback, (void *)((intptr_t)added)));
         } else if (removed && (sink || source)) {
-            /* removes we can handle just with the device index. */
-            SDL_RemoveAudioDevice(source != 0, (void *)((intptr_t)idx + 1));
+            // removes we can handle just with the device index.
+            SDL_AudioDeviceDisconnected(SDL_FindPhysicalAudioDeviceByHandle((void *)((intptr_t)idx + 1)));
         }
     }
     PULSEAUDIO_pa_threaded_mainloop_signal(pulseaudio_threaded_mainloop, 0);
 }
 
-/* this runs as a thread while the Pulse target is initialized to catch hotplug events. */
+static void CheckDefaultDevice(uint32_t *prev_default, uint32_t new_default)
+{
+    if (*prev_default != new_default) {
+        SDL_AudioDevice *device = SDL_FindPhysicalAudioDeviceByHandle((void *)((intptr_t)new_default + 1));
+        if (device) {
+            *prev_default = new_default;
+            SDL_DefaultAudioDeviceChanged(device);
+        }
+    }
+}
+
+// this runs as a thread while the Pulse target is initialized to catch hotplug events.
 static int SDLCALL HotplugThread(void *data)
 {
+    uint32_t prev_default_sink_index = default_sink_index;
+    uint32_t prev_default_source_index = default_source_index;
     pa_operation *op;
 
     SDL_SetThreadPriority(SDL_THREAD_PRIORITY_LOW);
@@ -855,7 +854,7 @@ static int SDLCALL HotplugThread(void *data)
     PULSEAUDIO_pa_context_set_subscribe_callback(pulseaudio_context, HotplugCallback, NULL);
 
     /* don't WaitForPulseOperation on the subscription; when it's done we'll be able to get hotplug events, but waiting doesn't changing anything. */
-    op = PULSEAUDIO_pa_context_subscribe(pulseaudio_context, PA_SUBSCRIPTION_MASK_SINK | PA_SUBSCRIPTION_MASK_SOURCE, NULL, NULL);
+    op = PULSEAUDIO_pa_context_subscribe(pulseaudio_context, PA_SUBSCRIPTION_MASK_SINK | PA_SUBSCRIPTION_MASK_SOURCE | PA_SUBSCRIPTION_MASK_SERVER, NULL, NULL);
 
     SDL_PostSemaphore((SDL_Semaphore *) data);
 
@@ -865,6 +864,13 @@ static int SDLCALL HotplugThread(void *data)
             PULSEAUDIO_pa_operation_unref(op);
             op = NULL;
         }
+
+        // Update default devices; don't hold the pulse lock during this, since it could deadlock vs a playing device that we're about to lock here.
+        PULSEAUDIO_pa_threaded_mainloop_unlock(pulseaudio_threaded_mainloop);
+        CheckDefaultDevice(&prev_default_sink_index, default_sink_index);
+        CheckDefaultDevice(&prev_default_source_index, default_source_index);
+        PULSEAUDIO_pa_threaded_mainloop_lock(pulseaudio_threaded_mainloop);
+
     }
 
     if (op) {
@@ -874,9 +880,11 @@ static int SDLCALL HotplugThread(void *data)
     PULSEAUDIO_pa_context_set_subscribe_callback(pulseaudio_context, NULL, NULL);
     PULSEAUDIO_pa_threaded_mainloop_unlock(pulseaudio_threaded_mainloop);
     return 0;
+
+
 }
 
-static void PULSEAUDIO_DetectDevices(void)
+static void PULSEAUDIO_DetectDevices(SDL_AudioDevice **default_output, SDL_AudioDevice **default_capture)
 {
     SDL_Semaphore *ready_sem = SDL_CreateSemaphore(0);
 
@@ -886,44 +894,24 @@ static void PULSEAUDIO_DetectDevices(void)
     WaitForPulseOperation(PULSEAUDIO_pa_context_get_source_info_list(pulseaudio_context, SourceInfoCallback, (void *)((intptr_t)SDL_TRUE)));
     PULSEAUDIO_pa_threaded_mainloop_unlock(pulseaudio_threaded_mainloop);
 
+    SDL_AudioDevice *device;
+    device = SDL_FindPhysicalAudioDeviceByHandle((void *)((intptr_t)default_sink_index + 1));
+    if (device) {
+        *default_output = device;
+    }
+
+    device = SDL_FindPhysicalAudioDeviceByHandle((void *)((intptr_t)default_source_index + 1));
+    if (device) {
+        *default_capture = device;
+    }
+
     /* ok, we have a sane list, let's set up hotplug notifications now... */
     SDL_AtomicSet(&pulseaudio_hotplug_thread_active, 1);
-    pulseaudio_hotplug_thread = SDL_CreateThreadInternal(HotplugThread, "PulseHotplug", 256 * 1024, ready_sem);  /* !!! FIXME: this can probably survive in significantly less stack space. */
+    pulseaudio_hotplug_thread = SDL_CreateThreadInternal(HotplugThread, "PulseHotplug", 256 * 1024, ready_sem);  // !!! FIXME: this can probably survive in significantly less stack space.
     SDL_WaitSemaphore(ready_sem);
     SDL_DestroySemaphore(ready_sem);
 }
 
-static int PULSEAUDIO_GetDefaultAudioInfo(char **name, SDL_AudioSpec *spec, int iscapture)
-{
-    int i;
-    int numdevices;
-
-    char *target;
-    if (iscapture) {
-        if (default_source_name == NULL) {
-            return SDL_SetError("PulseAudio could not find a default source");
-        }
-        target = default_source_name;
-    } else {
-        if (default_sink_name == NULL) {
-            return SDL_SetError("PulseAudio could not find a default sink");
-        }
-        target = default_sink_name;
-    }
-
-    numdevices = SDL_GetNumAudioDevices(iscapture);
-    for (i = 0; i < numdevices; i += 1) {
-        if (SDL_strcmp(SDL_GetAudioDeviceName(i, iscapture), target) == 0) {
-            if (name != NULL) {
-                *name = SDL_strdup(target);
-            }
-            SDL_GetAudioDeviceSpec(i, iscapture, spec);
-            return 0;
-        }
-    }
-    return SDL_SetError("Could not find default PulseAudio device");
-}
-
 static void PULSEAUDIO_Deinitialize(void)
 {
     if (pulseaudio_hotplug_thread) {
@@ -941,10 +929,9 @@ static void PULSEAUDIO_Deinitialize(void)
     default_sink_path = NULL;
     SDL_free(default_source_path);
     default_source_path = NULL;
-    SDL_free(default_sink_name);
-    default_sink_name = NULL;
-    SDL_free(default_source_name);
-    default_source_name = NULL;
+
+    default_source_index = 0;
+    default_sink_index = 0;
 
     UnloadPulseAudioLibrary();
 }
@@ -968,12 +955,11 @@ static SDL_bool PULSEAUDIO_Init(SDL_AudioDriverImpl *impl)
     impl->GetDeviceBuf = PULSEAUDIO_GetDeviceBuf;
     impl->CloseDevice = PULSEAUDIO_CloseDevice;
     impl->Deinitialize = PULSEAUDIO_Deinitialize;
+    impl->WaitCaptureDevice = PULSEAUDIO_WaitCaptureDevice;
     impl->CaptureFromDevice = PULSEAUDIO_CaptureFromDevice;
     impl->FlushCapture = PULSEAUDIO_FlushCapture;
-    impl->GetDefaultAudioInfo = PULSEAUDIO_GetDefaultAudioInfo;
 
     impl->HasCaptureSupport = SDL_TRUE;
-    impl->SupportsNonPow2Samples = SDL_TRUE;
 
     return SDL_TRUE; /* this audio target is available. */
 }

src/audio/pulseaudio/SDL_pulseaudio.h

@@ -36,7 +36,6 @@ struct SDL_PrivateAudioData
 
     /* Raw mixing buffer */
     Uint8 *mixbuf;
-    int mixlen;
 
     int bytes_requested; /* bytes of data the hardware wants _now_. */
 

src/audio/qnx/SDL_qsa_audio.c

@@ -19,13 +19,7 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
-/*
- * !!! FIXME: streamline this a little by removing all the
- * !!! FIXME:  if (capture) {} else {} sections that are identical
- * !!! FIXME:  except for one flag.
- */
-
-/* !!! FIXME: can this target support hotplugging? */
+// !!! FIXME: can this target support hotplugging?
 
 #include "../../SDL_internal.h"
 
@@ -48,7 +42,7 @@
 #include "../SDL_audio_c.h"
 #include "SDL_qsa_audio.h"
 
-/* default channel communication parameters */
+// default channel communication parameters
 #define DEFAULT_CPARAMS_RATE   44100
 #define DEFAULT_CPARAMS_VOICES 1
 
@@ -56,32 +50,17 @@
 #define DEFAULT_CPARAMS_FRAGS_MIN 1
 #define DEFAULT_CPARAMS_FRAGS_MAX 1
 
-/* List of found devices */
-#define QSA_MAX_DEVICES       32
-#define QSA_MAX_NAME_LENGTH   81+16     /* Hardcoded in QSA, can't be changed */
-
-typedef struct _QSA_Device
-{
-    char name[QSA_MAX_NAME_LENGTH];     /* Long audio device name for SDL  */
-    int cardno;
-    int deviceno;
-} QSA_Device;
-
-QSA_Device qsa_playback_device[QSA_MAX_DEVICES];
-uint32_t qsa_playback_devices;
-
-QSA_Device qsa_capture_device[QSA_MAX_DEVICES];
-uint32_t qsa_capture_devices;
+#define QSA_MAX_NAME_LENGTH   81+16     // Hardcoded in QSA, can't be changed
 
 static int QSA_SetError(const char *fn, int status)
 {
     return SDL_SetError("QSA: %s() failed: %s", fn, snd_strerror(status));
 }
 
-/* !!! FIXME: does this need to be here? Does the SDL version not work? */
-static void QSA_ThreadInit(SDL_AudioDevice *_this)
+// !!! FIXME: does this need to be here? Does the SDL version not work?
+static void QSA_ThreadInit(SDL_AudioDevice *device)
 {
-    /* Increase default 10 priority to 25 to avoid jerky sound */
+    // Increase default 10 priority to 25 to avoid jerky sound
     struct sched_param param;
     if (SchedGet(0, 0, &param) != -1) {
         param.sched_priority = param.sched_curpriority + 15;
@@ -89,7 +68,7 @@ static void QSA_ThreadInit(SDL_AudioDevice *_this)
     }
 }
 
-/* PCM channel parameters initialize function */
+// PCM channel parameters initialize function
 static void QSA_InitAudioParams(snd_pcm_channel_params_t * cpars)
 {
     SDL_zerop(cpars);
@@ -106,209 +85,150 @@ static void QSA_InitAudioParams(snd_pcm_channel_params_t * cpars)
     cpars->buf.block.frags_max = DEFAULT_CPARAMS_FRAGS_MAX;
 }
 
-/* This function waits until it is possible to write a full sound buffer */
-static void QSA_WaitDevice(SDL_AudioDevice *_this)
+// This function waits until it is possible to write a full sound buffer
+static void QSA_WaitDevice(SDL_AudioDevice *device)
 {
     int result;
 
-    /* Setup timeout for playing one fragment equal to 2 seconds          */
-    /* If timeout occurred than something wrong with hardware or driver   */
-    /* For example, Vortex 8820 audio driver stucks on second DAC because */
-    /* it doesn't exist !                                                 */
-    result = SDL_IOReady(_this->hidden->audio_fd,
-                         _this->hidden->iscapture ? SDL_IOR_READ : SDL_IOR_WRITE,
+    // Setup timeout for playing one fragment equal to 2 seconds
+    // If timeout occurred than something wrong with hardware or driver
+    // For example, Vortex 8820 audio driver stucks on second DAC because
+    // it doesn't exist !
+    result = SDL_IOReady(device->hidden->audio_fd,
+                         device->iscapture ? SDL_IOR_READ : SDL_IOR_WRITE,
                          2 * 1000);
     switch (result) {
     case -1:
-        SDL_SetError("QSA: SDL_IOReady() failed: %s", strerror(errno));
+        SDL_SetError("QSA: SDL_IOReady() failed: %s", strerror(errno));  // !!! FIXME: Should we just disconnect the device in this case?
         break;
     case 0:
-        SDL_SetError("QSA: timeout on buffer waiting occurred");
-        _this->hidden->timeout_on_wait = 1;
+        device->hidden->timeout_on_wait = SDL_TRUE;  // !!! FIXME: Should we just disconnect the device in this case?
         break;
     default:
-        _this->hidden->timeout_on_wait = 0;
+        device->hidden->timeout_on_wait = SDL_FALSE;
         break;
     }
 }
 
-static void QSA_PlayDevice(SDL_AudioDevice *_this)
+static void QSA_PlayDevice(SDL_AudioDevice *device, const Uint8 *buffer, int buflen)
 {
-    snd_pcm_channel_status_t cstatus;
-    int written;
-    int status;
-    int towrite;
-    void *pcmbuffer;
-
-    if (!SDL_AtomicGet(&_this->enabled) || !_this->hidden) {
+    if (SDL_AtomicGet(&device->shutdown) || !device->hidden) {
         return;
     }
 
-    towrite = _this->spec.size;
-    pcmbuffer = _this->hidden->pcm_buf;
-
-    /* Write the audio data, checking for EAGAIN (buffer full) and underrun */
-    do {
-        written =
-            snd_pcm_plugin_write(_this->hidden->audio_handle, pcmbuffer,
-                                 towrite);
-        if (written != towrite) {
-            /* Check if samples playback got stuck somewhere in hardware or in */
-            /* the audio device driver */
-            if ((errno == EAGAIN) && (written == 0)) {
-                if (_this->hidden->timeout_on_wait != 0) {
-                    SDL_SetError("QSA: buffer playback timeout");
-                    return;
+    int towrite = buflen;
+
+    // Write the audio data, checking for EAGAIN (buffer full) and underrun
+    while ((towrite > 0) && !SDL_AtomicGet(&device->shutdown));
+        const int bw = snd_pcm_plugin_write(device->hidden->audio_handle, buffer, towrite);
+        if (bw != towrite) {
+            // Check if samples playback got stuck somewhere in hardware or in the audio device driver
+            if ((errno == EAGAIN) && (bw == 0)) {
+                if (device->hidden->timeout_on_wait) {
+                    return;  // oh well, try again next time.  !!! FIXME: Should we just disconnect the device in this case?
                 }
             }
 
-            /* Check for errors or conditions */
+            // Check for errors or conditions
             if ((errno == EAGAIN) || (errno == EWOULDBLOCK)) {
-                /* Let a little CPU time go by and try to write again */
-                SDL_Delay(1);
+                SDL_Delay(1);  // Let a little CPU time go by and try to write again
 
-                /* if we wrote some data */
-                towrite -= written;
-                pcmbuffer += written * _this->spec.channels;
+                // if we wrote some data
+                towrite -= bw;
+                buffer += bw * device->spec.channels;
                 continue;
-            } else {
-                if ((errno == EINVAL) || (errno == EIO)) {
-                    SDL_zero(cstatus);
-                    if (!_this->hidden->iscapture) {
-                        cstatus.channel = SND_PCM_CHANNEL_PLAYBACK;
-                    } else {
-                        cstatus.channel = SND_PCM_CHANNEL_CAPTURE;
-                    }
-
-                    status =
-                        snd_pcm_plugin_status(_this->hidden->audio_handle,
-                                              &cstatus);
+            } else if ((errno == EINVAL) || (errno == EIO)) {
+                snd_pcm_channel_status_t cstatus;
+                SDL_zero(cstatus);
+                cstatus.channel = device->iscapture ? SND_PCM_CHANNEL_CAPTURE : SND_PCM_CHANNEL_PLAYBACK;
+
+                int status = snd_pcm_plugin_status(device->hidden->audio_handle, &cstatus);
+                if (status < 0) {
+                    QSA_SetError("snd_pcm_plugin_status", status);
+                    return;  // !!! FIXME: disconnect the device?
+                } else if ((cstatus.status == SND_PCM_STATUS_UNDERRUN) || (cstatus.status == SND_PCM_STATUS_READY)) {
+                    status = snd_pcm_plugin_prepare(device->hidden->audio_handle, device->iscapture ? SND_PCM_CHANNEL_CAPTURE : SND_PCM_CHANNEL_PLAYBACK);
                     if (status < 0) {
-                        QSA_SetError("snd_pcm_plugin_status", status);
-                        return;
-                    }
-
-                    if ((cstatus.status == SND_PCM_STATUS_UNDERRUN) ||
-                        (cstatus.status == SND_PCM_STATUS_READY)) {
-                        if (!_this->hidden->iscapture) {
-                            status =
-                                snd_pcm_plugin_prepare(_this->hidden->
-                                                       audio_handle,
-                                                       SND_PCM_CHANNEL_PLAYBACK);
-                        } else {
-                            status =
-                                snd_pcm_plugin_prepare(_this->hidden->
-                                                       audio_handle,
-                                                       SND_PCM_CHANNEL_CAPTURE);
-                        }
-                        if (status < 0) {
-                            QSA_SetError("snd_pcm_plugin_prepare", status);
-                            return;
-                        }
+                        QSA_SetError("snd_pcm_plugin_prepare", status);
+                        return;  // !!! FIXME: disconnect the device?
                     }
-                    continue;
-                } else {
-                    return;
                 }
+                continue;
+            } else {
+                return;  // !!! FIXME: disconnect the device?
             }
         } else {
-            /* we wrote all remaining data */
-            towrite -= written;
-            pcmbuffer += written * _this->spec.channels;
+            // we wrote all remaining data
+            towrite -= bw;
+            buffer += bw * device->spec.channels;
         }
-    } while ((towrite > 0) && SDL_AtomicGet(&_this->enabled));
+    }
 
-    /* If we couldn't write, assume fatal error for now */
+    // If we couldn't write, assume fatal error for now
     if (towrite != 0) {
-        SDL_OpenedAudioDeviceDisconnected(_this);
+        SDL_AudioDeviceDisconnected(device);
     }
 }
 
-static Uint8 *QSA_GetDeviceBuf(SDL_AudioDevice *_this)
+static Uint8 *QSA_GetDeviceBuf(SDL_AudioDevice *device, int *buffer_size)
 {
-    return _this->hidden->pcm_buf;
+    return device->hidden->pcm_buf;
 }
 
-static void QSA_CloseDevice(SDL_AudioDevice *_this)
+static void QSA_CloseDevice(SDL_AudioDevice *device)
 {
-    if (_this->hidden->audio_handle != NULL) {
-#if _NTO_VERSION < 710
-        if (!_this->hidden->iscapture) {
-            /* Finish playing available samples */
-            snd_pcm_plugin_flush(_this->hidden->audio_handle,
-                                 SND_PCM_CHANNEL_PLAYBACK);
-        } else {
-            /* Cancel unread samples during capture */
-            snd_pcm_plugin_flush(_this->hidden->audio_handle,
-                                 SND_PCM_CHANNEL_CAPTURE);
+    if (device->hidden) {
+        if (device->hidden->audio_handle != NULL) {
+            #if _NTO_VERSION < 710
+            // Finish playing available samples or cancel unread samples during capture
+            snd_pcm_plugin_flush(device->hidden->audio_handle, device->iscapture ? SND_PCM_CHANNEL_CAPTURE : SND_PCM_CHANNEL_PLAYBACK);
+            #endif
+            snd_pcm_close(device->hidden->audio_handle);
         }
-#endif
-        snd_pcm_close(_this->hidden->audio_handle);
-    }
 
-    SDL_free(_this->hidden->pcm_buf);
-    SDL_free(_this->hidden);
+        SDL_free(device->hidden->pcm_buf);
+        SDL_free(device->hidden);
+        device->hidden = NULL;
+    }
 }
 
-static int QSA_OpenDevice(SDL_AudioDevice *_this, const char *devname)
+static int QSA_OpenDevice(SDL_AudioDevice *device)
 {
-#if 0
-    /* !!! FIXME: SDL2 used to pass this handle. What's the alternative? */
-    const QSA_Device *device = (const QSA_Device *) handle;
-#else
-    const QSA_Device *device = NULL;
-#endif
+    if (device->iscapture) {
+        return SDL_SetError("SDL capture support isn't available on QNX atm"); // !!! FIXME: most of this code has support for capture devices, but there's no CaptureFromDevice, etc functions. Fill them in!
+    }
+
+    SDL_assert(device->handle != NULL);  // NULL used to mean "system default device" in SDL2; it does not mean that in SDL3.
+    const Uint32 sdlhandle = (Uint32) ((size_t) device->handle);
+    const uint32_t cardno = (uint32_t) (sdlhandle & 0xFFFF);
+    const uint32_t deviceno = (uint32_t) ((sdlhandle >> 16) & 0xFFFF);
+    const SDL_bool iscapture = device->iscapture;
     int status = 0;
-    int format = 0;
-    SDL_AudioFormat test_format = 0;
-    const SDL_AudioFormat *closefmts;
-    snd_pcm_channel_setup_t csetup;
-    snd_pcm_channel_params_t cparams;
-    SDL_bool iscapture = _this->iscapture;
-
-    /* Initialize all variables that we clean on shutdown */
-    _this->hidden =
-        (struct SDL_PrivateAudioData *) SDL_calloc(1,
-                                                   (sizeof
-                                                    (struct
-                                                     SDL_PrivateAudioData)));
-    if (_this->hidden == NULL) {
+
+    // Initialize all variables that we clean on shutdown
+    device->hidden = (struct SDL_PrivateAudioData *) SDL_calloc(1, (sizeof (struct SDL_PrivateAudioData)));
+    if (device->hidden == NULL) {
         return SDL_OutOfMemory();
     }
 
-    /* Initialize channel transfer parameters to default */
+    // Initialize channel transfer parameters to default
+    snd_pcm_channel_params_t cparams;
     QSA_InitAudioParams(&cparams);
 
-    /* Initialize channel direction: capture or playback */
-    _this->hidden->iscapture = iscapture ? SDL_TRUE : SDL_FALSE;
-
-    if (device != NULL) {
-        /* Open requested audio device */
-        _this->hidden->deviceno = device->deviceno;
-        _this->hidden->cardno = device->cardno;
-        status = snd_pcm_open(&_this->hidden->audio_handle,
-                              device->cardno, device->deviceno,
-                              iscapture ? SND_PCM_OPEN_CAPTURE : SND_PCM_OPEN_PLAYBACK);
-    } else {
-        /* Open system default audio device */
-        status = snd_pcm_open_preferred(&_this->hidden->audio_handle,
-                                        &_this->hidden->cardno,
-                                        &_this->hidden->deviceno,
-                                        iscapture ? SND_PCM_OPEN_CAPTURE : SND_PCM_OPEN_PLAYBACK);
-    }
-
-    /* Check if requested device is opened */
+    // Open requested audio device
+    status = snd_pcm_open(&device->hidden->audio_handle, cardno, deviceno, iscapture ? SND_PCM_OPEN_CAPTURE : SND_PCM_OPEN_PLAYBACK);
     if (status < 0) {
-        _this->hidden->audio_handle = NULL;
+        device->hidden->audio_handle = NULL;
         return QSA_SetError("snd_pcm_open", status);
     }
 
-    /* Try for a closest match on audio format */
-    closefmts = SDL_ClosestAudioFormats(_this->spec.format);
+    // Try for a closest match on audio format
+    SDL_AudioFormat test_format = 0;
+    const SDL_AudioFormat *closefmts = SDL_ClosestAudioFormats(device->spec.format);
     while ((test_format = *(closefmts++)) != 0) {
-        /* if match found set format to equivalent QSA format */
+        // if match found set format to equivalent QSA format
         switch (test_format) {
-        #define CHECKFMT(sdlfmt, qsafmt) case SDL_AUDIO_##sdlfmt: format = SND_PCM_SFMT_##qsafmt; break
+        #define CHECKFMT(sdlfmt, qsafmt) case SDL_AUDIO_##sdlfmt: cparams.format.format = SND_PCM_SFMT_##qsafmt; break
         CHECKFMT(U8, U8);
         CHECKFMT(S8, S8);
         CHECKFMT(S16LSB, S16_LE);
@@ -323,267 +243,192 @@ static int QSA_OpenDevice(SDL_AudioDevice *_this, const char *devname)
         break;
     }
 
-    /* assumes test_format not 0 on success */
+    // assumes test_format not 0 on success
     if (test_format == 0) {
         return SDL_SetError("QSA: Couldn't find any hardware audio formats");
     }
 
-    _this->spec.format = test_format;
+    device->spec.format = test_format;
 
-    /* Set the audio format */
-    cparams.format.format = format;
+    // Set mono/stereo/4ch/6ch/8ch audio
+    cparams.format.voices = device->spec.channels;
 
-    /* Set mono/stereo/4ch/6ch/8ch audio */
-    cparams.format.voices = _this->spec.channels;
+    // Set rate
+    cparams.format.rate = device->spec.freq;
 
-    /* Set rate */
-    cparams.format.rate = _this->spec.freq;
-
-    /* Setup the transfer parameters according to cparams */
-    status = snd_pcm_plugin_params(_this->hidden->audio_handle, &cparams);
+    // Setup the transfer parameters according to cparams
+    status = snd_pcm_plugin_params(device->hidden->audio_handle, &cparams);
     if (status < 0) {
         return QSA_SetError("snd_pcm_plugin_params", status);
     }
 
-    /* Make sure channel is setup right one last time */
+    // Make sure channel is setup right one last time
+    snd_pcm_channel_setup_t csetup;
     SDL_zero(csetup);
-    if (!_this->hidden->iscapture) {
-        csetup.channel = SND_PCM_CHANNEL_PLAYBACK;
-    } else {
-        csetup.channel = SND_PCM_CHANNEL_CAPTURE;
-    }
-
-    /* Setup an audio channel */
-    if (snd_pcm_plugin_setup(_this->hidden->audio_handle, &csetup) < 0) {
+    csetup.channel = iscapture ? SND_PCM_CHANNEL_CAPTURE : SND_PCM_CHANNEL_PLAYBACK;
+    if (snd_pcm_plugin_setup(device->hidden->audio_handle, &csetup) < 0) {
         return SDL_SetError("QSA: Unable to setup channel");
     }
 
-    /* Calculate the final parameters for this audio specification */
-    SDL_CalculateAudioSpec(&_this->spec);
-
-    _this->hidden->pcm_len = _this->spec.size;
+    device->sample_frames = csetup.buf.block.frag_size;
 
-    if (_this->hidden->pcm_len == 0) {
-        _this->hidden->pcm_len =
-            csetup.buf.block.frag_size * _this->spec.channels *
-            (snd_pcm_format_width(format) / 8);
-    }
+    // Calculate the final parameters for this audio specification
+    SDL_UpdatedAudioDeviceFormat(device);
 
-    /*
-     * Allocate memory to the audio buffer and initialize with silence
-     *  (Note that buffer size must be a multiple of fragment size, so find
-     *  closest multiple)
-     */
-    _this->hidden->pcm_buf =
-        (Uint8 *) SDL_malloc(_this->hidden->pcm_len);
-    if (_this->hidden->pcm_buf == NULL) {
+    device->hidden->pcm_buf = (Uint8 *) SDL_malloc(device->buffer_size);
+    if (device->hidden->pcm_buf == NULL) {
         return SDL_OutOfMemory();
     }
-    SDL_memset(_this->hidden->pcm_buf, _this->spec.silence,
-               _this->hidden->pcm_len);
-
-    /* get the file descriptor */
-    if (!_this->hidden->iscapture) {
-        _this->hidden->audio_fd =
-            snd_pcm_file_descriptor(_this->hidden->audio_handle,
-                                    SND_PCM_CHANNEL_PLAYBACK);
-    } else {
-        _this->hidden->audio_fd =
-            snd_pcm_file_descriptor(_this->hidden->audio_handle,
-                                    SND_PCM_CHANNEL_CAPTURE);
-    }
+    SDL_memset(device->hidden->pcm_buf, device->silence_value, device->buffer_size);
 
-    if (_this->hidden->audio_fd < 0) {
-        return QSA_SetError("snd_pcm_file_descriptor", status);
-    }
-
-    /* Prepare an audio channel */
-    if (!_this->hidden->iscapture) {
-        /* Prepare audio playback */
-        status =
-            snd_pcm_plugin_prepare(_this->hidden->audio_handle,
-                                   SND_PCM_CHANNEL_PLAYBACK);
-    } else {
-        /* Prepare audio capture */
-        status =
-            snd_pcm_plugin_prepare(_this->hidden->audio_handle,
-                                   SND_PCM_CHANNEL_CAPTURE);
+    // get the file descriptor
+    device->hidden->audio_fd = snd_pcm_file_descriptor(device->hidden->audio_handle, csetup.channel);
+    if (device->hidden->audio_fd < 0) {
+        return QSA_SetError("snd_pcm_file_descriptor", device->hidden->audio_fd);
     }
 
+    // Prepare an audio channel
+    status = snd_pcm_plugin_prepare(device->hidden->audio_handle, csetup.channel)
     if (status < 0) {
         return QSA_SetError("snd_pcm_plugin_prepare", status);
     }
 
-    /* We're really ready to rock and roll. :-) */
-    return 0;
+    return 0;  // We're really ready to rock and roll. :-)
 }
 
-static void QSA_DetectDevices(void)
+static SDL_AudioFormat QnxFormatToSDLFormat(const int32_t qnxfmt)
 {
-    uint32_t it;
-    uint32_t cards;
-    uint32_t devices;
-    int32_t status;
-
-    /* Detect amount of available devices       */
-    /* this value can be changed in the runtime */
-    cards = snd_cards();
-
-    /* If io-audio manager is not running we will get 0 as number */
-    /* of available audio devices                                 */
-    if (cards == 0) {
-        /* We have no any available audio devices */
-        return;
+    switch (qnxfmt) {
+        #define CHECKFMT(sdlfmt, qsafmt) case SND_PCM_SFMT_##qsafmt: return SDL_AUDIO_##sdlfmt
+        CHECKFMT(U8, U8);
+        CHECKFMT(S8, S8);
+        CHECKFMT(S16LSB, S16_LE);
+        CHECKFMT(S16MSB, S16_BE);
+        CHECKFMT(S32LSB, S32_LE);
+        CHECKFMT(S32MSB, S32_BE);
+        CHECKFMT(F32LSB, FLOAT_LE);
+        CHECKFMT(F32MSB, FLOAT_BE);
+        #undef CHECKFMT
+        default: break;
     }
+    return SDL_AUDIO_S16SYS;  // oh well.
+}
 
-    /* !!! FIXME: code duplication */
-    /* Find requested devices by type */
-    {  /* output devices */
-        /* Playback devices enumeration requested */
-        for (it = 0; it < cards; it++) {
-            devices = 0;
-            do {
-                status =
-                    snd_card_get_longname(it,
-                                          qsa_playback_device
-                                          [qsa_playback_devices].name,
-                                          QSA_MAX_NAME_LENGTH);
-                if (status == EOK) {
-                    snd_pcm_t *handle;
-
-                    /* Add device number to device name */
-                    sprintf(qsa_playback_device[qsa_playback_devices].name +
-                            SDL_strlen(qsa_playback_device
-                                       [qsa_playback_devices].name), " d%d",
-                            devices);
-
-                    /* Store associated card number id */
-                    qsa_playback_device[qsa_playback_devices].cardno = it;
+static void QSA_DetectDevices(SDL_AudioDevice **default_output, SDL_AudioDevice **default_capture)
+{
+    // Detect amount of available devices
+    // this value can be changed in the runtime
+    int num_cards = 0;
+    (void) snd_cards_list(NULL, 0, &alloc_num_cards);
+    SDL_bool isstack = SDL_FALSE;
+    int *cards = SDL_small_alloc(int, num_cards, &isstack);
+    if (!cards) {
+        return;  // we're in trouble.
+    }
+    int overflow_cards = 0;
+    const int total_num_cards = snd_cards_list(cards, num_cards, &overflow_cards);
+    // if overflow_cards > 0 or total_num_cards > num_cards, it changed at the last moment; oh well, we lost some.
+    num_cards = SDL_min(num_cards, total_num_cards);  // ...but make sure it didn't _shrink_.
+
+    // If io-audio manager is not running we will get 0 as number of available audio devices
+    if (num_cards == 0) {   // not any available audio devices?
+        SDL_small_free(cards, isstack);
+        return;
+    }
 
-                    /* Check if this device id could play anything */
-                    status =
-                        snd_pcm_open(&handle, it, devices,
-                                     SND_PCM_OPEN_PLAYBACK);
+    // Find requested devices by type
+    for (int it = 0; it < num_cards; it++) {
+        const int card = cards[it];
+        for (uint32_t deviceno = 0; ; deviceno++) {
+            int32_t status;
+            char name[QSA_MAX_NAME_LENGTH];
+
+            status = snd_card_get_longname(card, name, sizeof (name));
+            if (status == EOK) {
+                snd_pcm_t *handle;
+
+                // Add device number to device name
+                char fullname[QSA_MAX_NAME_LENGTH + 32];
+                SDL_snprintf(fullname, sizeof (fullname), "%s d%d", name, (int) deviceno);
+
+                // Check if this device id could play anything
+                SDL_bool iscapture = SDL_FALSE;
+                status = snd_pcm_open(&handle, card, deviceno, SND_PCM_OPEN_PLAYBACK);
+                if (status != EOK) {  // no? See if it's a capture device instead.
+                    #if 0  // !!! FIXME: most of this code has support for capture devices, but there's no CaptureFromDevice, etc functions. Fill them in!
+                    status = snd_pcm_open(&handle, card, deviceno, SND_PCM_OPEN_CAPTURE);
                     if (status == EOK) {
-                        qsa_playback_device[qsa_playback_devices].deviceno =
-                            devices;
-                        status = snd_pcm_close(handle);
-                        if (status == EOK) {
-                            /* Note that spec is NULL, because we are required to open the device before
-                             * acquiring the mix format, making this information inaccessible at
-                             * enumeration time
-                             */
-                            SDL_AddAudioDevice(SDL_FALSE, qsa_playback_device[qsa_playback_devices].name, NULL, &qsa_playback_device[qsa_playback_devices]);
-                            qsa_playback_devices++;
-                        }
-                    } else {
-                        /* Check if we got end of devices list */
-                        if (status == -ENOENT) {
-                            break;
-                        }
+                        iscapture = SDL_TRUE;
                     }
-                } else {
-                    break;
-                }
-
-                /* Check if we reached maximum devices count */
-                if (qsa_playback_devices >= QSA_MAX_DEVICES) {
-                    break;
+                    #endif
                 }
-                devices++;
-            } while (1);
-
-            /* Check if we reached maximum devices count */
-            if (qsa_playback_devices >= QSA_MAX_DEVICES) {
-                break;
-            }
-        }
-    }
 
-    {  /* capture devices */
-        /* Capture devices enumeration requested */
-        for (it = 0; it < cards; it++) {
-            devices = 0;
-            do {
-                status =
-                    snd_card_get_longname(it,
-                                          qsa_capture_device
-                                          [qsa_capture_devices].name,
-                                          QSA_MAX_NAME_LENGTH);
                 if (status == EOK) {
-                    snd_pcm_t *handle;
-
-                    /* Add device number to device name */
-                    sprintf(qsa_capture_device[qsa_capture_devices].name +
-                            SDL_strlen(qsa_capture_device
-                                       [qsa_capture_devices].name), " d%d",
-                            devices);
-
-                    /* Store associated card number id */
-                    qsa_capture_device[qsa_capture_devices].cardno = it;
-
-                    /* Check if this device id could play anything */
-                    status =
-                        snd_pcm_open(&handle, it, devices,
-                                     SND_PCM_OPEN_CAPTURE);
-                    if (status == EOK) {
-                        qsa_capture_device[qsa_capture_devices].deviceno =
-                            devices;
-                        status = snd_pcm_close(handle);
-                        if (status == EOK) {
-                            /* Note that spec is NULL, because we are required to open the device before
-                             * acquiring the mix format, making this information inaccessible at
-                             * enumeration time
-                             */
-                            SDL_AddAudioDevice(SDL_TRUE, qsa_capture_device[qsa_capture_devices].name, NULL, &qsa_capture_device[qsa_capture_devices]);
-                            qsa_capture_devices++;
-                        }
+                    SDL_AudioSpec spec;
+                    SDL_AudioSpec *pspec = &spec;
+                    snd_pcm_channel_setup_t csetup;
+                    SDL_zero(csetup);
+                    csetup.channel = iscapture ? SND_PCM_CHANNEL_CAPTURE : SND_PCM_CHANNEL_PLAYBACK;
+
+                    if (snd_pcm_plugin_setup(device->hidden->audio_handle, &csetup) < 0) {
+                        pspec = NULL;  // go on without spec info.
                     } else {
-                        /* Check if we got end of devices list */
-                        if (status == -ENOENT) {
-                            break;
-                        }
+                        spec.format = QnxFormatToSDLFormat(csetup.format.format);
+                        spec.channels = csetup.format.channels;
+                        spec.freq = csetup.format.rate;
                     }
 
-                    /* Check if we reached maximum devices count */
-                    if (qsa_capture_devices >= QSA_MAX_DEVICES) {
-                        break;
+                    status = snd_pcm_close(handle);
+                    if (status == EOK) {
+                        // !!! FIXME: I'm assuming each of these values are way less than 0xFFFF. Fix this if not.
+                        SDL_assert(card <= 0xFFFF);
+                        SDL_assert(deviceno <= 0xFFFF);
+                        const Uint32 sdlhandle = ((Uint32) card) | (((Uint32) deviceno) << 16);
+                        SDL_AddAudioDevice(iscapture, fullname, pspec, (void *) ((size_t) sdlhandle));
                     }
                 } else {
-                    break;
+                    // Check if we got end of devices list
+                    if (status == -ENOENT) {
+                        break;
+                    }
                 }
-                devices++;
-            } while (1);
-
-            /* Check if we reached maximum devices count */
-            if (qsa_capture_devices >= QSA_MAX_DEVICES) {
+            } else {
                 break;
             }
         }
     }
+
+    SDL_small_free(cards, isstack);
+
+    // Try to open the "preferred" devices, which will tell us the card/device pairs for the default devices.
+    snd_pcm_t handle;
+    int cardno, deviceno;
+    if (snd_pcm_open_preferred(&handle, &cardno, &deviceno, SND_PCM_OPEN_PLAYBACK) == 0) {
+        snd_pcm_close(handle);
+        // !!! FIXME: I'm assuming each of these values are way less than 0xFFFF. Fix this if not.
+        SDL_assert(cardno <= 0xFFFF);
+        SDL_assert(deviceno <= 0xFFFF);
+        const Uint32 sdlhandle = ((Uint32) card) | (((Uint32) deviceno) << 16);
+        *default_output = SDL_FindPhysicalAudioDeviceByHandle((void *) ((size_t) sdlhandle));
+    }
+
+    if (snd_pcm_open_preferred(&handle, &cardno, &deviceno, SND_PCM_OPEN_CAPTURE) == 0) {
+        snd_pcm_close(handle);
+        // !!! FIXME: I'm assuming each of these values are way less than 0xFFFF. Fix this if not.
+        SDL_assert(cardno <= 0xFFFF);
+        SDL_assert(deviceno <= 0xFFFF);
+        const Uint32 sdlhandle = ((Uint32) card) | (((Uint32) deviceno) << 16);
+        *default_capture = SDL_FindPhysicalAudioDeviceByHandle((void *) ((size_t) sdlhandle));
+    }
 }
 
 static void QSA_Deinitialize(void)
 {
-    /* Clear devices array on shutdown */
-    /* !!! FIXME: we zero these on init...any reason to do it here? */
-    SDL_zeroa(qsa_playback_device);
-    SDL_zeroa(qsa_capture_device);
-    qsa_playback_devices = 0;
-    qsa_capture_devices = 0;
+    // nothing to do here atm.
 }
 
 static SDL_bool QSA_Init(SDL_AudioDriverImpl * impl)
 {
-    /* Clear devices array */
-    SDL_zeroa(qsa_playback_device);
-    SDL_zeroa(qsa_capture_device);
-    qsa_playback_devices = 0;
-    qsa_capture_devices = 0;
-
-    /* Set function pointers                                     */
-    /* DeviceLock and DeviceUnlock functions are used default,   */
-    /* provided by SDL, which uses pthread_mutex for lock/unlock */
     impl->DetectDevices = QSA_DetectDevices;
     impl->OpenDevice = QSA_OpenDevice;
     impl->ThreadInit = QSA_ThreadInit;
@@ -592,21 +437,16 @@ static SDL_bool QSA_Init(SDL_AudioDriverImpl * impl)
     impl->GetDeviceBuf = QSA_GetDeviceBuf;
     impl->CloseDevice = QSA_CloseDevice;
     impl->Deinitialize = QSA_Deinitialize;
-    impl->LockDevice = NULL;
-    impl->UnlockDevice = NULL;
 
-    impl->ProvidesOwnCallbackThread = 0;
-    impl->HasCaptureSupport = 1;
-    impl->OnlyHasDefaultOutputDevice = 0;
-    impl->OnlyHasDefaultCaptureDevice = 0;
+    // !!! FIXME: most of this code has support for capture devices, but there's no CaptureFromDevice, etc functions. Fill them in!
+    //impl->HasCaptureSupport = SDL_TRUE;
 
-    return SDL_TRUE;   /* this audio target is available. */
+    return SDL_TRUE;
 }
 
 AudioBootStrap QSAAUDIO_bootstrap = {
     "qsa", "QNX QSA Audio", QSA_Init, 0
 };
 
-#endif /* SDL_AUDIO_DRIVER_QNX */
+#endif // SDL_AUDIO_DRIVER_QNX
 
-/* vi: set ts=4 sw=4 expandtab: */

src/audio/qnx/SDL_qsa_audio.h

@@ -30,23 +30,10 @@
 
 struct SDL_PrivateAudioData
 {
-    /* SDL capture state */
-    SDL_bool iscapture;
-
-    /* The audio device handle */
-    int cardno;
-    int deviceno;
-    snd_pcm_t *audio_handle;
-
-    /* The audio file descriptor */
-    int audio_fd;
-
-    /* Select timeout status */
-    uint32_t timeout_on_wait;
-
-    /* Raw mixing buffer */
-    Uint8 *pcm_buf;
-    Uint32 pcm_len;
+    snd_pcm_t *audio_handle;  // The audio device handle
+    int audio_fd;  // The audio file descriptor, for selecting on
+    SDL_bool timeout_on_wait; // Select timeout status
+    Uint8 *pcm_buf;  // Raw mixing buffer
 };
 
 #endif /* __SDL_QSA_AUDIO_H__ */

src/audio/sndio/SDL_sndioaudio.c

@@ -23,7 +23,7 @@
 
 #ifdef SDL_AUDIO_DRIVER_SNDIO
 
-/* OpenBSD sndio target */
+// OpenBSD sndio target
 
 #ifdef HAVE_STDIO_H
 #include <stdio.h>
@@ -72,14 +72,13 @@ static int load_sndio_sym(const char *fn, void **addr)
 {
     *addr = SDL_LoadFunction(sndio_handle, fn);
     if (*addr == NULL) {
-        /* Don't call SDL_SetError(): SDL_LoadFunction already did. */
-        return 0;
+        return 0;  // Don't call SDL_SetError(): SDL_LoadFunction already did.
     }
 
     return 1;
 }
 
-/* cast funcs to char* first, to please GCC's strict aliasing rules. */
+// cast funcs to char* first, to please GCC's strict aliasing rules.
 #define SDL_SNDIO_SYM(x)                                  \
     if (!load_sndio_sym(#x, (void **)(char *)&SNDIO_##x)) \
     return -1
@@ -123,8 +122,7 @@ static int LoadSNDIOLibrary(void)
     if (sndio_handle == NULL) {
         sndio_handle = SDL_LoadObject(sndio_library);
         if (sndio_handle == NULL) {
-            retval = -1;
-            /* Don't call SDL_SetError(): SDL_LoadObject already did. */
+            retval = -1;  // Don't call SDL_SetError(): SDL_LoadObject already did.
         } else {
             retval = load_sndio_syms();
             if (retval < 0) {
@@ -147,129 +145,128 @@ static int LoadSNDIOLibrary(void)
     return 0;
 }
 
-#endif /* SDL_AUDIO_DRIVER_SNDIO_DYNAMIC */
+#endif // SDL_AUDIO_DRIVER_SNDIO_DYNAMIC
 
-static void SNDIO_WaitDevice(SDL_AudioDevice *_this)
+static void SNDIO_WaitDevice(SDL_AudioDevice *device)
 {
-    /* no-op; SNDIO_sio_write() blocks if necessary. */
+    const SDL_bool iscapture = device->iscapture;
+
+    while (!SDL_AtomicGet(&device->shutdown)) {
+        if (SNDIO_sio_eof(device->hidden->dev)) {
+            SDL_AudioDeviceDisconnected(device);
+            return;
+        }
+
+        const int nfds = SNDIO_sio_pollfd(device->hidden->dev, device->hidden->pfd, iscapture ? POLLIN : POLLOUT);
+        if (nfds <= 0 || poll(device->hidden->pfd, nfds, 10) < 0) {
+            SDL_AudioDeviceDisconnected(device);
+            return;
+        }
+
+        const int revents = SNDIO_sio_revents(device->hidden->dev, device->hidden->pfd);
+        if (iscapture && (revents & POLLIN)) {
+            return;
+        } else if (!iscapture && (revents & POLLOUT)) {
+            return;
+        } else if (revents & POLLHUP) {
+            SDL_AudioDeviceDisconnected(device);
+            return;
+        }
+    }
 }
 
-static void SNDIO_PlayDevice(SDL_AudioDevice *_this)
+static void SNDIO_PlayDevice(SDL_AudioDevice *device, const Uint8 *buffer, int buflen)
 {
-    const int written = SNDIO_sio_write(_this->hidden->dev,
-                                        _this->hidden->mixbuf,
-                                        _this->hidden->mixlen);
-
-    /* If we couldn't write, assume fatal error for now */
-    if (written == 0) {
-        SDL_OpenedAudioDeviceDisconnected(_this);
+    // !!! FIXME: this should be non-blocking so we can check device->shutdown.
+    // this is set to blocking, because we _have_ to send the entire buffer down, but hopefully WaitDevice took most of the delay time.
+    if (SNDIO_sio_write(device->hidden->dev, buffer, buflen) != buflen) {
+        SDL_AudioDeviceDisconnected(device);  // If we couldn't write, assume fatal error for now
     }
 #ifdef DEBUG_AUDIO
     fprintf(stderr, "Wrote %d bytes of audio data\n", written);
 #endif
 }
 
-static int SNDIO_CaptureFromDevice(SDL_AudioDevice *_this, void *buffer, int buflen)
+static int SNDIO_CaptureFromDevice(SDL_AudioDevice *device, void *buffer, int buflen)
 {
-    size_t r;
-    int revents;
-    int nfds;
-
-    /* Emulate a blocking read */
-    r = SNDIO_sio_read(_this->hidden->dev, buffer, buflen);
-    while (r == 0 && !SNDIO_sio_eof(_this->hidden->dev)) {
-        nfds = SNDIO_sio_pollfd(_this->hidden->dev, _this->hidden->pfd, POLLIN);
-        if (nfds <= 0 || poll(_this->hidden->pfd, nfds, INFTIM) < 0) {
-            return -1;
-        }
-        revents = SNDIO_sio_revents(_this->hidden->dev, _this->hidden->pfd);
-        if (revents & POLLIN) {
-            r = SNDIO_sio_read(_this->hidden->dev, buffer, buflen);
-        }
-        if (revents & POLLHUP) {
-            break;
-        }
+    // We set capture devices non-blocking; this can safely return 0 in SDL3, but we'll check for EOF to cause a device disconnect.
+    const size_t br = SNDIO_sio_read(device->hidden->dev, buffer, buflen);
+    if ((br == 0) && SNDIO_sio_eof(device->hidden->dev)) {
+        return -1;
     }
-    return (int)r;
+    return (int) br;
 }
 
-static void SNDIO_FlushCapture(SDL_AudioDevice *_this)
+static void SNDIO_FlushCapture(SDL_AudioDevice *device)
 {
     char buf[512];
-
-    while (SNDIO_sio_read(_this->hidden->dev, buf, sizeof(buf)) != 0) {
-        /* do nothing */;
+    while (!SDL_AtomicGet(&device->shutdown) && (SNDIO_sio_read(device->hidden->dev, buf, sizeof(buf)) > 0)) {
+        // do nothing
     }
 }
 
-static Uint8 *SNDIO_GetDeviceBuf(SDL_AudioDevice *_this)
+static Uint8 *SNDIO_GetDeviceBuf(SDL_AudioDevice *device, int *buffer_size)
 {
-    return _this->hidden->mixbuf;
+    return device->hidden->mixbuf;
 }
 
-static void SNDIO_CloseDevice(SDL_AudioDevice *_this)
+static void SNDIO_CloseDevice(SDL_AudioDevice *device)
 {
-    if (_this->hidden->pfd != NULL) {
-        SDL_free(_this->hidden->pfd);
-    }
-    if (_this->hidden->dev != NULL) {
-        SNDIO_sio_stop(_this->hidden->dev);
-        SNDIO_sio_close(_this->hidden->dev);
+    if (device->hidden) {
+        if (device->hidden->dev != NULL) {
+            SNDIO_sio_stop(device->hidden->dev);
+            SNDIO_sio_close(device->hidden->dev);
+        }
+        SDL_free(device->hidden->pfd);
+        SDL_free(device->hidden->mixbuf);
+        SDL_free(device->hidden);
+        device->hidden = NULL;
     }
-    SDL_free(_this->hidden->mixbuf);
-    SDL_free(_this->hidden);
 }
 
-static int SNDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
+static int SNDIO_OpenDevice(SDL_AudioDevice *device)
 {
-    SDL_AudioFormat test_format;
-    const SDL_AudioFormat *closefmts;
-    struct sio_par par;
-    SDL_bool iscapture = _this->iscapture;
-
-    _this->hidden = (struct SDL_PrivateAudioData *)
-        SDL_malloc(sizeof(*_this->hidden));
-    if (_this->hidden == NULL) {
+    device->hidden = (struct SDL_PrivateAudioData *) SDL_calloc(1, sizeof(*device->hidden));
+    if (device->hidden == NULL) {
         return SDL_OutOfMemory();
     }
-    SDL_zerop(_this->hidden);
 
-    _this->hidden->mixlen = _this->spec.size;
+    // !!! FIXME: we really should standardize this on a specific SDL hint.
+    const char *audiodev = SDL_getenv("AUDIODEV");
 
-    /* Capture devices must be non-blocking for SNDIO_FlushCapture */
-    _this->hidden->dev = SNDIO_sio_open(devname != NULL ? devname : SIO_DEVANY,
-                                       iscapture ? SIO_REC : SIO_PLAY, iscapture);
-    if (_this->hidden->dev == NULL) {
+    // Capture devices must be non-blocking for SNDIO_FlushCapture
+    device->hidden->dev = SNDIO_sio_open(audiodev != NULL ? audiodev : SIO_DEVANY,
+                                         device->iscapture ? SIO_REC : SIO_PLAY, device->iscapture);
+    if (device->hidden->dev == NULL) {
         return SDL_SetError("sio_open() failed");
     }
 
-    /* Allocate the pollfd array for capture devices */
-    if (iscapture) {
-        _this->hidden->pfd = SDL_malloc(sizeof(struct pollfd) * SNDIO_sio_nfds(_this->hidden->dev));
-        if (_this->hidden->pfd == NULL) {
-            return SDL_OutOfMemory();
-        }
+    device->hidden->pfd = SDL_malloc(sizeof(struct pollfd) * SNDIO_sio_nfds(device->hidden->dev));
+    if (device->hidden->pfd == NULL) {
+        return SDL_OutOfMemory();
     }
 
+    struct sio_par par;
     SNDIO_sio_initpar(&par);
 
-    par.rate = _this->spec.freq;
-    par.pchan = _this->spec.channels;
-    par.round = _this->spec.samples;
+    par.rate = device->spec.freq;
+    par.pchan = device->spec.channels;
+    par.round = device->sample_frames;
     par.appbufsz = par.round * 2;
 
-    /* Try for a closest match on audio format */
-    closefmts = SDL_ClosestAudioFormats(_this->spec.format);
+    // Try for a closest match on audio format
+    SDL_AudioFormat test_format;
+    const SDL_AudioFormat *closefmts = SDL_ClosestAudioFormats(device->spec.format);
     while ((test_format = *(closefmts++)) != 0) {
         if (!SDL_AUDIO_ISFLOAT(test_format)) {
             par.le = SDL_AUDIO_ISLITTLEENDIAN(test_format) ? 1 : 0;
             par.sig = SDL_AUDIO_ISSIGNED(test_format) ? 1 : 0;
             par.bits = SDL_AUDIO_BITSIZE(test_format);
 
-            if (SNDIO_sio_setpar(_this->hidden->dev, &par) == 0) {
+            if (SNDIO_sio_setpar(device->hidden->dev, &par) == 0) {
                 continue;
             }
-            if (SNDIO_sio_getpar(_this->hidden->dev, &par) == 0) {
+            if (SNDIO_sio_getpar(device->hidden->dev, &par) == 0) {
                 return SDL_SetError("sio_getpar() failed");
             }
             if (par.bps != SIO_BPS(par.bits)) {
@@ -282,46 +279,44 @@ static int SNDIO_OpenDevice(SDL_AudioDevice *_this, const char *devname)
     }
 
     if (!test_format) {
-        return SDL_SetError("%s: Unsupported audio format", "sndio");
+        return SDL_SetError("sndio: Unsupported audio format");
     }
 
     if ((par.bps == 4) && (par.sig) && (par.le)) {
-        _this->spec.format = SDL_AUDIO_S32LSB;
+        device->spec.format = SDL_AUDIO_S32LSB;
     } else if ((par.bps == 4) && (par.sig) && (!par.le)) {
-        _this->spec.format = SDL_AUDIO_S32MSB;
+        device->spec.format = SDL_AUDIO_S32MSB;
     } else if ((par.bps == 2) && (par.sig) && (par.le)) {
-        _this->spec.format = SDL_AUDIO_S16LSB;
+        device->spec.format = SDL_AUDIO_S16LSB;
     } else if ((par.bps == 2) && (par.sig) && (!par.le)) {
-        _this->spec.format = SDL_AUDIO_S16MSB;
+        device->spec.format = SDL_AUDIO_S16MSB;
     } else if ((par.bps == 1) && (par.sig)) {
-        _this->spec.format = SDL_AUDIO_S8;
+        device->spec.format = SDL_AUDIO_S8;
     } else if ((par.bps == 1) && (!par.sig)) {
-        _this->spec.format = SDL_AUDIO_U8;
+        device->spec.format = SDL_AUDIO_U8;
     } else {
         return SDL_SetError("sndio: Got unsupported hardware audio format.");
     }
 
-    _this->spec.freq = par.rate;
-    _this->spec.channels = par.pchan;
-    _this->spec.samples = par.round;
+    device->spec.freq = par.rate;
+    device->spec.channels = par.pchan;
+    device->sample_frames = par.round;
 
-    /* Calculate the final parameters for this audio specification */
-    SDL_CalculateAudioSpec(&_this->spec);
+    // Calculate the final parameters for this audio specification
+    SDL_UpdatedAudioDeviceFormat(device);
 
-    /* Allocate mixing buffer */
-    _this->hidden->mixlen = _this->spec.size;
-    _this->hidden->mixbuf = (Uint8 *)SDL_malloc(_this->hidden->mixlen);
-    if (_this->hidden->mixbuf == NULL) {
+    // Allocate mixing buffer
+    device->hidden->mixbuf = (Uint8 *)SDL_malloc(device->buffer_size);
+    if (device->hidden->mixbuf == NULL) {
         return SDL_OutOfMemory();
     }
-    SDL_memset(_this->hidden->mixbuf, _this->spec.silence, _this->hidden->mixlen);
+    SDL_memset(device->hidden->mixbuf, device->silence_value, device->buffer_size);
 
-    if (!SNDIO_sio_start(_this->hidden->dev)) {
+    if (!SNDIO_sio_start(device->hidden->dev)) {
         return SDL_SetError("sio_start() failed");
     }
 
-    /* We're ready to rock and roll. :-) */
-    return 0;
+    return 0;  // We're ready to rock and roll. :-)
 }
 
 static void SNDIO_Deinitialize(void)
@@ -329,10 +324,10 @@ static void SNDIO_Deinitialize(void)
     UnloadSNDIOLibrary();
 }
 
-static void SNDIO_DetectDevices(void)
+static void SNDIO_DetectDevices(SDL_AudioDevice **default_output, SDL_AudioDevice **default_capture)
 {
-    SDL_AddAudioDevice(SDL_FALSE, DEFAULT_OUTPUT_DEVNAME, NULL, (void *)0x1);
-    SDL_AddAudioDevice(SDL_TRUE, DEFAULT_INPUT_DEVNAME, NULL, (void *)0x2);
+    *default_output = SDL_AddAudioDevice(SDL_FALSE, DEFAULT_OUTPUT_DEVNAME, NULL, (void *)0x1);
+    *default_capture = SDL_AddAudioDevice(SDL_TRUE, DEFAULT_INPUT_DEVNAME, NULL, (void *)0x2);
 }
 
 static SDL_bool SNDIO_Init(SDL_AudioDriverImpl *impl)
@@ -341,12 +336,12 @@ static SDL_bool SNDIO_Init(SDL_AudioDriverImpl *impl)
         return SDL_FALSE;
     }
 
-    /* Set the function pointers */
     impl->OpenDevice = SNDIO_OpenDevice;
     impl->WaitDevice = SNDIO_WaitDevice;
     impl->PlayDevice = SNDIO_PlayDevice;
     impl->GetDeviceBuf = SNDIO_GetDeviceBuf;
     impl->CloseDevice = SNDIO_CloseDevice;
+    impl->WaitCaptureDevice = SNDIO_WaitDevice;
     impl->CaptureFromDevice = SNDIO_CaptureFromDevice;
     impl->FlushCapture = SNDIO_FlushCapture;
     impl->Deinitialize = SNDIO_Deinitialize;
@@ -355,11 +350,11 @@ static SDL_bool SNDIO_Init(SDL_AudioDriverImpl *impl)
     impl->AllowsArbitraryDeviceNames = SDL_TRUE;
     impl->HasCaptureSupport = SDL_TRUE;
 
-    return SDL_TRUE; /* this audio target is available. */
+    return SDL_TRUE;
 }
 
 AudioBootStrap SNDIO_bootstrap = {
     "sndio", "OpenBSD sndio", SNDIO_Init, SDL_FALSE
 };
 
-#endif /* SDL_AUDIO_DRIVER_SNDIO */
+#endif // SDL_AUDIO_DRIVER_SNDIO

src/audio/sndio/SDL_sndioaudio.h

@@ -30,15 +30,9 @@
 
 struct SDL_PrivateAudioData
 {
-    /* The audio device handle */
-    struct sio_hdl *dev;
-
-    /* Raw mixing buffer */
-    Uint8 *mixbuf;
-    int mixlen;
-
-    /* Polling structures for non-blocking sndio devices */
-    struct pollfd *pfd;
+    struct sio_hdl *dev;  // The audio device handle
+    Uint8 *mixbuf; // Raw mixing buffer
+    struct pollfd *pfd;  // Polling structures for non-blocking sndio devices
 };
 
 #endif /* SDL_sndioaudio_h_ */

src/audio/vita/SDL_vitaaudio.c

@@ -38,41 +38,41 @@
 #define SCE_AUDIO_SAMPLE_ALIGN(s) (((s) + 63) & ~63)
 #define SCE_AUDIO_MAX_VOLUME      0x8000
 
-static int VITAAUD_OpenCaptureDevice(SDL_AudioDevice *_this)
+static int VITAAUD_OpenCaptureDevice(SDL_AudioDevice *device)
 {
-    _this->spec.freq = 16000;
-    _this->spec.samples = 512;
-    _this->spec.channels = 1;
+    device->spec.freq = 16000;
+    device->spec.channels = 1;
+    device->sample_frames = 512;
 
-    SDL_CalculateAudioSpec(&_this->spec);
+    SDL_UpdatedAudioDeviceFormat(device);
 
-    _this->hidden->port = sceAudioInOpenPort(SCE_AUDIO_IN_PORT_TYPE_VOICE, 512, 16000, SCE_AUDIO_IN_PARAM_FORMAT_S16_MONO);
+    device->hidden->port = sceAudioInOpenPort(SCE_AUDIO_IN_PORT_TYPE_VOICE, 512, 16000, SCE_AUDIO_IN_PARAM_FORMAT_S16_MONO);
 
-    if (_this->hidden->port < 0) {
-        return SDL_SetError("Couldn't open audio in port: %x", _this->hidden->port);
+    if (device->hidden->port < 0) {
+        return SDL_SetError("Couldn't open audio in port: %x", device->hidden->port);
     }
 
     return 0;
 }
 
-static int VITAAUD_OpenDevice(SDL_AudioDevice *_this, const char *devname)
+static int VITAAUD_OpenDevice(SDL_AudioDevice *device)
 {
     int format, mixlen, i, port = SCE_AUDIO_OUT_PORT_TYPE_MAIN;
     int vols[2] = { SCE_AUDIO_MAX_VOLUME, SCE_AUDIO_MAX_VOLUME };
     SDL_AudioFormat test_format;
     const SDL_AudioFormat *closefmts;
 
-    _this->hidden = (struct SDL_PrivateAudioData *)
-        SDL_malloc(sizeof(*_this->hidden));
-    if (_this->hidden == NULL) {
+    device->hidden = (struct SDL_PrivateAudioData *)
+        SDL_malloc(sizeof(*device->hidden));
+    if (device->hidden == NULL) {
         return SDL_OutOfMemory();
     }
-    SDL_memset(_this->hidden, 0, sizeof(*_this->hidden));
+    SDL_memset(device->hidden, 0, sizeof(*device->hidden));
 
-    closefmts = SDL_ClosestAudioFormats(_this->spec.format);
+    closefmts = SDL_ClosestAudioFormats(device->spec.format);
     while ((test_format = *(closefmts++)) != 0) {
         if (test_format == SDL_AUDIO_S16LSB) {
-            _this->spec.format = test_format;
+            device->spec.format = test_format;
             break;
         }
     }
@@ -81,106 +81,127 @@ static int VITAAUD_OpenDevice(SDL_AudioDevice *_this, const char *devname)
         return SDL_SetError("Unsupported audio format");
     }
 
-    if (_this->iscapture) {
-        return VITAAUD_OpenCaptureDevice(_this);
+    if (device->iscapture) {
+        return VITAAUD_OpenCaptureDevice(device);
     }
 
-    /* The sample count must be a multiple of 64. */
-    _this->spec.samples = SCE_AUDIO_SAMPLE_ALIGN(_this->spec.samples);
+    // The sample count must be a multiple of 64.
+    device->sample_frames = SCE_AUDIO_SAMPLE_ALIGN(device->sample_frames);
 
-    /* Update the fragment size as size in bytes. */
-    SDL_CalculateAudioSpec(&_this->spec);
+    // Update the fragment size as size in bytes.
+    SDL_UpdatedAudioDeviceFormat(device);
 
     /* Allocate the mixing buffer.  Its size and starting address must
        be a multiple of 64 bytes.  Our sample count is already a multiple of
        64, so spec->size should be a multiple of 64 as well. */
-    mixlen = _this->spec.size * NUM_BUFFERS;
-    _this->hidden->rawbuf = (Uint8 *)SDL_aligned_alloc(64, mixlen);
-    if (_this->hidden->rawbuf == NULL) {
+    mixlen = device->buffer_size * NUM_BUFFERS;
+    device->hidden->rawbuf = (Uint8 *)SDL_aligned_alloc(64, mixlen);
+    if (device->hidden->rawbuf == NULL) {
         return SDL_SetError("Couldn't allocate mixing buffer");
     }
 
-    /* Setup the hardware channel. */
-    if (_this->spec.channels == 1) {
+    // Setup the hardware channel.
+    if (device->spec.channels == 1) {
         format = SCE_AUDIO_OUT_MODE_MONO;
     } else {
         format = SCE_AUDIO_OUT_MODE_STEREO;
     }
 
-    if (_this->spec.freq < 48000) {
+    // the main port requires 48000Hz audio, so this drops to the background music port if necessary
+    if (device->spec.freq < 48000) {
         port = SCE_AUDIO_OUT_PORT_TYPE_BGM;
     }
 
-    _this->hidden->port = sceAudioOutOpenPort(port, _this->spec.samples, _this->spec.freq, format);
-    if (_this->hidden->port < 0) {
-        SDL_aligned_free(_this->hidden->rawbuf);
-        _this->hidden->rawbuf = NULL;
-        return SDL_SetError("Couldn't open audio out port: %x", _this->hidden->port);
+    device->hidden->port = sceAudioOutOpenPort(port, device->sample_frames, device->spec.freq, format);
+    if (device->hidden->port < 0) {
+        SDL_aligned_free(device->hidden->rawbuf);
+        device->hidden->rawbuf = NULL;
+        return SDL_SetError("Couldn't open audio out port: %x", device->hidden->port);
     }
 
-    sceAudioOutSetVolume(_this->hidden->port, SCE_AUDIO_VOLUME_FLAG_L_CH | SCE_AUDIO_VOLUME_FLAG_R_CH, vols);
+    sceAudioOutSetVolume(device->hidden->port, SCE_AUDIO_VOLUME_FLAG_L_CH | SCE_AUDIO_VOLUME_FLAG_R_CH, vols);
 
-    SDL_memset(_this->hidden->rawbuf, 0, mixlen);
+    SDL_memset(device->hidden->rawbuf, 0, mixlen);
     for (i = 0; i < NUM_BUFFERS; i++) {
-        _this->hidden->mixbufs[i] = &_this->hidden->rawbuf[i * _this->spec.size];
+        device->hidden->mixbufs[i] = &device->hidden->rawbuf[i * device->buffer_size];
     }
 
-    _this->hidden->next_buffer = 0;
+    device->hidden->next_buffer = 0;
     return 0;
 }
 
-static void VITAAUD_PlayDevice(SDL_AudioDevice *_this)
+static void VITAAUD_PlayDevice(SDL_AudioDevice *device, const Uint8 *buffer, int buffer_size)
 {
-    Uint8 *mixbuf = _this->hidden->mixbufs[_this->hidden->next_buffer];
-
-    sceAudioOutOutput(_this->hidden->port, mixbuf);
-
-    _this->hidden->next_buffer = (_this->hidden->next_buffer + 1) % NUM_BUFFERS;
+    sceAudioOutOutput(device->hidden->port, buffer);
 }
 
-/* This function waits until it is possible to write a full sound buffer */
-static void VITAAUD_WaitDevice(SDL_AudioDevice *_this)
+// This function waits until it is possible to write a full sound buffer
+static void VITAAUD_WaitDevice(SDL_AudioDevice *device)
 {
-    /* Because we block when sending audio, there's no need for this function to do anything. */
+    // !!! FIXME: we might just need to sleep roughly as long as playback buffers take to process, based on sample rate, etc.
+    while (!SDL_AtomicGet(&device->shutdown) && (sceAudioOutGetRestSample(device->hidden->port) >= device->buffer_size)) {
+        SDL_Delay(1);
+    }
 }
 
-static Uint8 *VITAAUD_GetDeviceBuf(SDL_AudioDevice *_this)
+static Uint8 *VITAAUD_GetDeviceBuf(SDL_AudioDevice *device, int *buffer_size)
 {
-    return _this->hidden->mixbufs[_this->hidden->next_buffer];
+    Uint8 *retval = device->hidden->mixbufs[device->hidden->next_buffer];
+    device->hidden->next_buffer = (device->hidden->next_buffer + 1) % NUM_BUFFERS;
+    return retval;
 }
 
-static void VITAAUD_CloseDevice(SDL_AudioDevice *_this)
+static void VITAAUD_CloseDevice(SDL_AudioDevice *device)
 {
-    if (_this->hidden->port >= 0) {
-        if (_this->iscapture) {
-            sceAudioInReleasePort(_this->hidden->port);
-        } else {
-            sceAudioOutReleasePort(_this->hidden->port);
+    if (device->hidden) {
+        if (device->hidden->port >= 0) {
+            if (device->iscapture) {
+                sceAudioInReleasePort(device->hidden->port);
+            } else {
+                sceAudioOutReleasePort(device->hidden->port);
+            }
+            device->hidden->port = -1;
         }
-        _this->hidden->port = -1;
+
+        if (!device->iscapture && device->hidden->rawbuf != NULL) {
+            SDL_aligned_free(device->hidden->rawbuf); // this uses memalign(), not SDL_malloc().
+            device->hidden->rawbuf = NULL;
+        }
+        SDL_free(device->hidden);
+        device->hidden = NULL;
     }
+}
 
-    if (!_this->iscapture && _this->hidden->rawbuf != NULL) {
-        SDL_aligned_free(_this->hidden->rawbuf);
-        _this->hidden->rawbuf = NULL;
+static void VITAAUD_WaitCaptureDevice(SDL_AudioDevice *device)
+{
+    // there's only a blocking call to obtain more data, so we'll just sleep as
+    //  long as a buffer would run.
+    const Uint64 endticks = SDL_GetTicks() + ((device->sample_frames * 1000) / device->spec.freq);
+    while (!SDL_AtomicGet(&device->shutdown) && (SDL_GetTicks() < endticks)) {
+        SDL_Delay(1);
     }
 }
 
-static int VITAAUD_CaptureFromDevice(SDL_AudioDevice *_this, void *buffer, int buflen)
+static int VITAAUD_CaptureFromDevice(SDL_AudioDevice *device, void *buffer, int buflen)
 {
     int ret;
-    SDL_assert(buflen == _this->spec.size);
-    ret = sceAudioInInput(_this->hidden->port, buffer);
+    SDL_assert(buflen == device->buffer_size);
+    ret = sceAudioInInput(device->hidden->port, buffer);
     if (ret < 0) {
         return SDL_SetError("Failed to capture from device: %x", ret);
     }
-    return _this->spec.size;
+    return device->buffer_size;
 }
 
-static void VITAAUD_ThreadInit(SDL_AudioDevice *_this)
+static void VITAAUD_FlushCapture(SDL_AudioDevice *device)
 {
-    /* Increase the priority of this audio thread by 1 to put it
-       ahead of other SDL threads. */
+    // just grab the latest and dump it.
+    sceAudioInInput(device->hidden->port, device->work_buffer);
+}
+
+static void VITAAUD_ThreadInit(SDL_AudioDevice *device)
+{
+    // Increase the priority of this audio thread by 1 to put it ahead of other SDL threads.
     SceUID thid;
     SceKernelThreadInfo info;
     thid = sceKernelGetThreadId();
@@ -192,26 +213,25 @@ static void VITAAUD_ThreadInit(SDL_AudioDevice *_this)
 
 static SDL_bool VITAAUD_Init(SDL_AudioDriverImpl *impl)
 {
-    /* Set the function pointers */
     impl->OpenDevice = VITAAUD_OpenDevice;
     impl->PlayDevice = VITAAUD_PlayDevice;
     impl->WaitDevice = VITAAUD_WaitDevice;
     impl->GetDeviceBuf = VITAAUD_GetDeviceBuf;
     impl->CloseDevice = VITAAUD_CloseDevice;
     impl->ThreadInit = VITAAUD_ThreadInit;
-
+    impl->WaitCaptureDevice = VITAAUD_WaitCaptureDevice;
+    impl->FlushCapture = VITAAUD_FlushCapture;
     impl->CaptureFromDevice = VITAAUD_CaptureFromDevice;
 
-    /* and the capabilities */
     impl->HasCaptureSupport = SDL_TRUE;
     impl->OnlyHasDefaultOutputDevice = SDL_TRUE;
     impl->OnlyHasDefaultCaptureDevice = SDL_TRUE;
 
-    return SDL_TRUE; /* this audio target is available. */
+    return SDL_TRUE;
 }
 
 AudioBootStrap VITAAUD_bootstrap = {
     "vita", "VITA audio driver", VITAAUD_Init, SDL_FALSE
 };
 
-#endif /* SDL_AUDIO_DRIVER_VITA */
+#endif // SDL_AUDIO_DRIVER_VITA

src/audio/wasapi/SDL_wasapi.c

@@ -24,6 +24,7 @@
 
 #include "../../core/windows/SDL_windows.h"
 #include "../../core/windows/SDL_immdevice.h"
+#include "../../thread/SDL_systhread.h"
 #include "../SDL_audio_c.h"
 #include "../SDL_sysaudio.h"
 
@@ -32,7 +33,7 @@
 
 #include "SDL_wasapi.h"
 
-/* These constants aren't available in older SDKs */
+// These constants aren't available in older SDKs
 #ifndef AUDCLNT_STREAMFLAGS_RATEADJUST
 #define AUDCLNT_STREAMFLAGS_RATEADJUST 0x00100000
 #endif
@@ -43,140 +44,367 @@
 #define AUDCLNT_STREAMFLAGS_AUTOCONVERTPCM 0x80000000
 #endif
 
-/* Some GUIDs we need to know without linking to libraries that aren't available before Vista. */
+// Some GUIDs we need to know without linking to libraries that aren't available before Vista.
 static const IID SDL_IID_IAudioRenderClient = { 0xf294acfc, 0x3146, 0x4483, { 0xa7, 0xbf, 0xad, 0xdc, 0xa7, 0xc2, 0x60, 0xe2 } };
 static const IID SDL_IID_IAudioCaptureClient = { 0xc8adbd64, 0xe71e, 0x48a0, { 0xa4, 0xde, 0x18, 0x5c, 0x39, 0x5c, 0xd3, 0x17 } };
 
 
-static void WASAPI_DetectDevices(void)
+// WASAPI is _really_ particular about various things happening on the same thread, for COM and such,
+//  so we proxy various stuff to a single background thread to manage.
+
+typedef struct ManagementThreadPendingTask
+{
+    ManagementThreadTask fn;
+    void *userdata;
+    int result;
+    SDL_Semaphore *task_complete_sem;
+    char *errorstr;
+    struct ManagementThreadPendingTask *next;
+} ManagementThreadPendingTask;
+
+static SDL_Thread *ManagementThread = NULL;
+static ManagementThreadPendingTask *ManagementThreadPendingTasks = NULL;
+static SDL_Mutex *ManagementThreadLock = NULL;
+static SDL_Condition *ManagementThreadCondition = NULL;
+static SDL_AtomicInt ManagementThreadShutdown;
+
+static void ManagementThreadMainloop(void)
 {
-    WASAPI_EnumerateEndpoints();
+    SDL_LockMutex(ManagementThreadLock);
+    ManagementThreadPendingTask *task;
+    while (((task = SDL_AtomicGetPtr((void **) &ManagementThreadPendingTasks)) != NULL) || !SDL_AtomicGet(&ManagementThreadShutdown)) {
+        if (!task) {
+            SDL_WaitCondition(ManagementThreadCondition, ManagementThreadLock); // block until there's something to do.
+        } else {
+            SDL_AtomicSetPtr((void **) &ManagementThreadPendingTasks, task->next); // take task off the pending list.
+            SDL_UnlockMutex(ManagementThreadLock);                       // let other things add to the list while we chew on this task.
+            task->result = task->fn(task->userdata);                     // run this task.
+            if (task->task_complete_sem) {                               // something waiting on result?
+                task->errorstr = SDL_strdup(SDL_GetError());
+                SDL_PostSemaphore(task->task_complete_sem);
+            } else { // nothing waiting, we're done, free it.
+                SDL_free(task);
+            }
+            SDL_LockMutex(ManagementThreadLock); // regrab the lock so we can get the next task; if nothing to do, we'll release the lock in SDL_WaitCondition.
+        }
+    }
+    SDL_UnlockMutex(ManagementThreadLock); // told to shut down and out of tasks, let go of the lock and return.
 }
 
-static SDL_INLINE SDL_bool WasapiFailed(SDL_AudioDevice *_this, const HRESULT err)
+int WASAPI_ProxyToManagementThread(ManagementThreadTask task, void *userdata, int *wait_on_result)
 {
-    if (err == S_OK) {
-        return SDL_FALSE;
+    // We want to block for a result, but we are already running from the management thread! Just run the task now so we don't deadlock.
+    if ((wait_on_result != NULL) && (SDL_ThreadID() == SDL_GetThreadID(ManagementThread))) {
+        *wait_on_result = task(userdata);
+        return 0;  // completed!
     }
 
-    if (err == AUDCLNT_E_DEVICE_INVALIDATED) {
-        _this->hidden->device_lost = SDL_TRUE;
-    } else if (SDL_AtomicGet(&_this->enabled)) {
-        IAudioClient_Stop(_this->hidden->client);
-        SDL_OpenedAudioDeviceDisconnected(_this);
-        SDL_assert(!SDL_AtomicGet(&_this->enabled));
+    if (SDL_AtomicGet(&ManagementThreadShutdown)) {
+        return SDL_SetError("Can't add task, we're shutting down");
     }
 
-    return SDL_TRUE;
-}
+    ManagementThreadPendingTask *pending = SDL_calloc(1, sizeof(ManagementThreadPendingTask));
+    if (!pending) {
+        return SDL_OutOfMemory();
+    }
 
-static int UpdateAudioStream(SDL_AudioDevice *_this, const SDL_AudioSpec *oldspec)
-{
-    /* Since WASAPI requires us to handle all audio conversion, and our
-       device format might have changed, we might have to add/remove/change
-       the audio stream that the higher level uses to convert data, so
-       SDL keeps firing the callback as if nothing happened here. */
-
-    if ((_this->callbackspec.channels == _this->spec.channels) &&
-        (_this->callbackspec.format == _this->spec.format) &&
-        (_this->callbackspec.freq == _this->spec.freq) &&
-        (_this->callbackspec.samples == _this->spec.samples)) {
-        /* no need to buffer/convert in an AudioStream! */
-        SDL_DestroyAudioStream(_this->stream);
-        _this->stream = NULL;
-    } else if ((oldspec->channels == _this->spec.channels) &&
-               (oldspec->format == _this->spec.format) &&
-               (oldspec->freq == _this->spec.freq)) {
-        /* The existing audio stream is okay to keep using. */
-    } else {
-        /* replace the audiostream for new format */
-        SDL_DestroyAudioStream(_this->stream);
-        if (_this->iscapture) {
-            _this->stream = SDL_CreateAudioStream(_this->spec.format,
-                                              _this->spec.channels, _this->spec.freq,
-                                              _this->callbackspec.format,
-                                              _this->callbackspec.channels,
-                                              _this->callbackspec.freq);
-        } else {
-            _this->stream = SDL_CreateAudioStream(_this->callbackspec.format,
-                                              _this->callbackspec.channels,
-                                              _this->callbackspec.freq, _this->spec.format,
-                                              _this->spec.channels, _this->spec.freq);
-        }
+    pending->fn = task;
+    pending->userdata = userdata;
 
-        if (!_this->stream) {
-            return -1; /* SDL_CreateAudioStream should have called SDL_SetError. */
+    if (wait_on_result) {
+        pending->task_complete_sem = SDL_CreateSemaphore(0);
+        if (!pending->task_complete_sem) {
+            SDL_free(pending);
+            return -1;
         }
     }
 
-    /* make sure our scratch buffer can cover the new device spec. */
-    if (_this->spec.size > _this->work_buffer_len) {
-        Uint8 *ptr = (Uint8 *)SDL_realloc(_this->work_buffer, _this->spec.size);
-        if (ptr == NULL) {
-            return SDL_OutOfMemory();
+    pending->next = NULL;
+
+    SDL_LockMutex(ManagementThreadLock);
+
+    // add to end of task list.
+    ManagementThreadPendingTask *prev = NULL;
+    for (ManagementThreadPendingTask *i = SDL_AtomicGetPtr((void **) &ManagementThreadPendingTasks); i != NULL; i = i->next) {
+        prev = i;
+    }
+
+    if (prev != NULL) {
+        prev->next = pending;
+    } else {
+        SDL_AtomicSetPtr((void **) &ManagementThreadPendingTasks, pending);
+    }
+
+    // task is added to the end of the pending list, let management thread rip!
+    SDL_SignalCondition(ManagementThreadCondition);
+    SDL_UnlockMutex(ManagementThreadLock);
+
+    if (wait_on_result) {
+        SDL_WaitSemaphore(pending->task_complete_sem);
+        SDL_DestroySemaphore(pending->task_complete_sem);
+        *wait_on_result = pending->result;
+        if (pending->errorstr) {
+            SDL_SetError("%s", pending->errorstr);
+            SDL_free(pending->errorstr);
         }
-        _this->work_buffer = ptr;
-        _this->work_buffer_len = _this->spec.size;
+        SDL_free(pending);
+    }
+
+    return 0; // successfully added (and possibly executed)!
+}
+
+static int ManagementThreadPrepare(void)
+{
+    if (WASAPI_PlatformInit() == -1) {
+        return -1;
+    }
+
+    ManagementThreadLock = SDL_CreateMutex();
+    if (!ManagementThreadLock) {
+        WASAPI_PlatformDeinit();
+        return -1;
+    }
+
+    ManagementThreadCondition = SDL_CreateCondition();
+    if (!ManagementThreadCondition) {
+        SDL_DestroyMutex(ManagementThreadLock);
+        ManagementThreadLock = NULL;
+        WASAPI_PlatformDeinit();
+        return -1;
     }
 
     return 0;
 }
 
-static void ReleaseWasapiDevice(SDL_AudioDevice *_this);
+typedef struct
+{
+    char *errorstr;
+    SDL_Semaphore *ready_sem;
+} ManagementThreadEntryData;
+
+static int ManagementThreadEntry(void *userdata)
+{
+    ManagementThreadEntryData *data = (ManagementThreadEntryData *)userdata;
+
+    if (ManagementThreadPrepare() < 0) {
+        data->errorstr = SDL_strdup(SDL_GetError());
+        SDL_PostSemaphore(data->ready_sem); // unblock calling thread.
+        return 0;
+    }
+
+    SDL_PostSemaphore(data->ready_sem); // unblock calling thread.
+    ManagementThreadMainloop();
+
+    WASAPI_PlatformDeinit();
+    return 0;
+}
 
-static SDL_bool RecoverWasapiDevice(SDL_AudioDevice *_this)
+static int InitManagementThread(void)
 {
-    ReleaseWasapiDevice(_this); /* dump the lost device's handles. */
+    ManagementThreadEntryData mgmtdata;
+    SDL_zero(mgmtdata);
+    mgmtdata.ready_sem = SDL_CreateSemaphore(0);
+    if (!mgmtdata.ready_sem) {
+        return -1;
+    }
+
+    SDL_AtomicSetPtr((void **) &ManagementThreadPendingTasks, NULL);
+    SDL_AtomicSet(&ManagementThreadShutdown, 0);
+    ManagementThread = SDL_CreateThreadInternal(ManagementThreadEntry, "SDLWASAPIMgmt", 256 * 1024, &mgmtdata); // !!! FIXME: maybe even smaller stack size?
+    if (!ManagementThread) {
+        return -1;
+    }
+
+    SDL_WaitSemaphore(mgmtdata.ready_sem);
+    SDL_DestroySemaphore(mgmtdata.ready_sem);
 
-    if (_this->hidden->default_device_generation) {
-        _this->hidden->default_device_generation = SDL_AtomicGet(_this->iscapture ? &SDL_IMMDevice_DefaultCaptureGeneration : &SDL_IMMDevice_DefaultPlaybackGeneration);
+    if (mgmtdata.errorstr) {
+        SDL_WaitThread(ManagementThread, NULL);
+        ManagementThread = NULL;
+        SDL_SetError("%s", mgmtdata.errorstr);
+        SDL_free(mgmtdata.errorstr);
+        return -1;
     }
 
-    /* this can fail for lots of reasons, but the most likely is we had a
-       non-default device that was disconnected, so we can't recover. Default
-       devices try to reinitialize whatever the new default is, so it's more
-       likely to carry on here, but this handles a non-default device that
-       simply had its format changed in the Windows Control Panel. */
-    if (WASAPI_ActivateDevice(_this, SDL_TRUE) == -1) {
-        SDL_OpenedAudioDeviceDisconnected(_this);
+    return 0;
+}
+
+static void DeinitManagementThread(void)
+{
+    if (ManagementThread) {
+        SDL_AtomicSet(&ManagementThreadShutdown, 1);
+        SDL_LockMutex(ManagementThreadLock);
+        SDL_SignalCondition(ManagementThreadCondition);
+        SDL_UnlockMutex(ManagementThreadLock);
+        SDL_WaitThread(ManagementThread, NULL);
+        ManagementThread = NULL;
+    }
+
+    SDL_assert(SDL_AtomicGetPtr((void **) &ManagementThreadPendingTasks) == NULL);
+
+    SDL_DestroyCondition(ManagementThreadCondition);
+    SDL_DestroyMutex(ManagementThreadLock);
+    ManagementThreadCondition = NULL;
+    ManagementThreadLock = NULL;
+    SDL_AtomicSet(&ManagementThreadShutdown, 0);
+}
+
+typedef struct
+{
+    SDL_AudioDevice **default_output;
+    SDL_AudioDevice **default_capture;
+} mgmtthrtask_DetectDevicesData;
+
+static int mgmtthrtask_DetectDevices(void *userdata)
+{
+    mgmtthrtask_DetectDevicesData *data = (mgmtthrtask_DetectDevicesData *)userdata;
+    WASAPI_EnumerateEndpoints(data->default_output, data->default_capture);
+    return 0;
+}
+
+static void WASAPI_DetectDevices(SDL_AudioDevice **default_output, SDL_AudioDevice **default_capture)
+{
+    int rc;
+    mgmtthrtask_DetectDevicesData data = { default_output, default_capture };
+    WASAPI_ProxyToManagementThread(mgmtthrtask_DetectDevices, &data, &rc);
+}
+
+static int mgmtthrtask_DisconnectDevice(void *userdata)
+{
+    SDL_AudioDeviceDisconnected((SDL_AudioDevice *)userdata);
+    return 0;
+}
+
+void WASAPI_DisconnectDevice(SDL_AudioDevice *device)
+{
+    // this runs async, so it can hold the device lock from the management thread.
+    WASAPI_ProxyToManagementThread(mgmtthrtask_DisconnectDevice, device, NULL);
+}
+
+static SDL_bool WasapiFailed(SDL_AudioDevice *device, const HRESULT err)
+{
+    if (err == S_OK) {
         return SDL_FALSE;
     }
 
-    _this->hidden->device_lost = SDL_FALSE;
+    if (err == AUDCLNT_E_DEVICE_INVALIDATED) {
+        device->hidden->device_lost = SDL_TRUE;
+    } else {
+        IAudioClient_Stop(device->hidden->client);
+        WASAPI_DisconnectDevice(device);
+    }
+
+    return SDL_TRUE;
+}
+
+static int mgmtthrtask_ReleaseCaptureClient(void *userdata)
+{
+    IAudioCaptureClient_Release((IAudioCaptureClient *)userdata);
+    return 0;
+}
 
-    return SDL_TRUE; /* okay, carry on with new device details! */
+static int mgmtthrtask_ReleaseRenderClient(void *userdata)
+{
+    IAudioRenderClient_Release((IAudioRenderClient *)userdata);
+    return 0;
 }
 
-static SDL_bool RecoverWasapiIfLost(SDL_AudioDevice *_this)
+static int mgmtthrtask_ResetWasapiDevice(void *userdata)
 {
-    const int generation = _this->hidden->default_device_generation;
-    SDL_bool lost = _this->hidden->device_lost;
+    SDL_AudioDevice *device = (SDL_AudioDevice *)userdata;
 
-    if (!SDL_AtomicGet(&_this->enabled)) {
-        return SDL_FALSE; /* already failed. */
+    if (!device || !device->hidden) {
+        return 0;
     }
 
-    if (!_this->hidden->client) {
-        return SDL_TRUE; /* still waiting for activation. */
+    if (device->hidden->client) {
+        IAudioClient_Stop(device->hidden->client);
+        IAudioClient_Release(device->hidden->client);
+        device->hidden->client = NULL;
     }
 
-    if (!lost && (generation > 0)) { /* is a default device? */
-        const int newgen = SDL_AtomicGet(_this->iscapture ? &SDL_IMMDevice_DefaultCaptureGeneration : &SDL_IMMDevice_DefaultPlaybackGeneration);
-        if (generation != newgen) { /* the desired default device was changed, jump over to it. */
-            lost = SDL_TRUE;
-        }
+    if (device->hidden->render) {
+        // this is silly, but this will block indefinitely if you call it from SDLMMNotificationClient_OnDefaultDeviceChanged, so
+        //  proxy this to the management thread to be released later.
+        WASAPI_ProxyToManagementThread(mgmtthrtask_ReleaseRenderClient, device->hidden->render, NULL);
+        device->hidden->render = NULL;
     }
 
-    return lost ? RecoverWasapiDevice(_this) : SDL_TRUE;
+    if (device->hidden->capture) {
+        // this is silly, but this will block indefinitely if you call it from SDLMMNotificationClient_OnDefaultDeviceChanged, so
+        //  proxy this to the management thread to be released later.
+        WASAPI_ProxyToManagementThread(mgmtthrtask_ReleaseCaptureClient, device->hidden->capture, NULL);
+        device->hidden->capture = NULL;
+    }
+
+    if (device->hidden->waveformat) {
+        CoTaskMemFree(device->hidden->waveformat);
+        device->hidden->waveformat = NULL;
+    }
+
+    if (device->hidden->activation_handler) {
+        WASAPI_PlatformDeleteActivationHandler(device->hidden->activation_handler);
+        device->hidden->activation_handler = NULL;
+    }
+
+    if (device->hidden->event) {
+        CloseHandle(device->hidden->event);
+        device->hidden->event = NULL;
+    }
+
+    return 0;
+}
+
+static void ResetWasapiDevice(SDL_AudioDevice *device)
+{
+    int rc;
+    WASAPI_ProxyToManagementThread(mgmtthrtask_ResetWasapiDevice, device, &rc);
 }
 
-static Uint8 *WASAPI_GetDeviceBuf(SDL_AudioDevice *_this)
+static int mgmtthrtask_ActivateDevice(void *userdata)
 {
-    /* get an endpoint buffer from WASAPI. */
+    return WASAPI_ActivateDevice((SDL_AudioDevice *)userdata);
+}
+
+static int ActivateWasapiDevice(SDL_AudioDevice *device)
+{
+    int rc;
+    return ((WASAPI_ProxyToManagementThread(mgmtthrtask_ActivateDevice, device, &rc) < 0) || (rc < 0)) ? -1 : 0;
+}
+
+static SDL_bool RecoverWasapiDevice(SDL_AudioDevice *device)
+{
+    ResetWasapiDevice(device); // dump the lost device's handles.
+
+    // This handles a non-default device that simply had its format changed in the Windows Control Panel.
+    if (ActivateWasapiDevice(device) == -1) {
+        WASAPI_DisconnectDevice(device);
+        return SDL_FALSE;
+    }
+
+    device->hidden->device_lost = SDL_FALSE;
+
+    return SDL_TRUE; // okay, carry on with new device details!
+}
+
+static SDL_bool RecoverWasapiIfLost(SDL_AudioDevice *device)
+{
+    if (SDL_AtomicGet(&device->shutdown)) {
+        return SDL_FALSE; // already failed.
+    } else if (!device->hidden->client) {
+        return SDL_TRUE; // still waiting for activation.
+    }
+
+    return device->hidden->device_lost ? RecoverWasapiDevice(device) : SDL_TRUE;
+}
+
+static Uint8 *WASAPI_GetDeviceBuf(SDL_AudioDevice *device, int *buffer_size)
+{
+    // get an endpoint buffer from WASAPI.
     BYTE *buffer = NULL;
 
-    while (RecoverWasapiIfLost(_this) && _this->hidden->render) {
-        if (!WasapiFailed(_this, IAudioRenderClient_GetBuffer(_this->hidden->render, _this->spec.samples, &buffer))) {
+    while (RecoverWasapiIfLost(device) && device->hidden->render) {
+        if (!WasapiFailed(device, IAudioRenderClient_GetBuffer(device->hidden->render, device->sample_frames, &buffer))) {
             return (Uint8 *)buffer;
         }
         SDL_assert(buffer == NULL);
@@ -185,197 +413,108 @@ static Uint8 *WASAPI_GetDeviceBuf(SDL_AudioDevice *_this)
     return (Uint8 *)buffer;
 }
 
-static void WASAPI_PlayDevice(SDL_AudioDevice *_this)
+static void WASAPI_PlayDevice(SDL_AudioDevice *device, const Uint8 *buffer, int buflen)
 {
-    if (_this->hidden->render != NULL) { /* definitely activated? */
-        /* WasapiFailed() will mark the device for reacquisition or removal elsewhere. */
-        WasapiFailed(_this, IAudioRenderClient_ReleaseBuffer(_this->hidden->render, _this->spec.samples, 0));
+    if (device->hidden->render != NULL) { // definitely activated?
+        // WasapiFailed() will mark the device for reacquisition or removal elsewhere.
+        WasapiFailed(device, IAudioRenderClient_ReleaseBuffer(device->hidden->render, device->sample_frames, 0));
     }
 }
 
-static void WASAPI_WaitDevice(SDL_AudioDevice *_this)
+static void WASAPI_WaitDevice(SDL_AudioDevice *device)
 {
-    while (RecoverWasapiIfLost(_this) && _this->hidden->client && _this->hidden->event) {
-        DWORD waitResult = WaitForSingleObjectEx(_this->hidden->event, 200, FALSE);
+    while (RecoverWasapiIfLost(device) && device->hidden->client && device->hidden->event) {
+        DWORD waitResult = WaitForSingleObjectEx(device->hidden->event, 200, FALSE);
         if (waitResult == WAIT_OBJECT_0) {
-            const UINT32 maxpadding = _this->spec.samples;
+            const UINT32 maxpadding = device->sample_frames;
             UINT32 padding = 0;
-            if (!WasapiFailed(_this, IAudioClient_GetCurrentPadding(_this->hidden->client, &padding))) {
-                /*SDL_Log("WASAPI EVENT! padding=%u maxpadding=%u", (unsigned int)padding, (unsigned int)maxpadding);*/
-                if (_this->iscapture) {
-                    if (padding > 0) {
-                        break;
-                    }
-                } else {
-                    if (padding <= maxpadding) {
-                        break;
-                    }
+            if (!WasapiFailed(device, IAudioClient_GetCurrentPadding(device->hidden->client, &padding))) {
+                //SDL_Log("WASAPI EVENT! padding=%u maxpadding=%u", (unsigned int)padding, (unsigned int)maxpadding);*/
+                if (device->iscapture && (padding > 0)) {
+                    break;
+                } else if (!device->iscapture && (padding <= maxpadding)) {
+                    break;
                 }
             }
         } else if (waitResult != WAIT_TIMEOUT) {
-            /*SDL_Log("WASAPI FAILED EVENT!");*/
-            IAudioClient_Stop(_this->hidden->client);
-            SDL_OpenedAudioDeviceDisconnected(_this);
+            //SDL_Log("WASAPI FAILED EVENT!");*/
+            IAudioClient_Stop(device->hidden->client);
+            WASAPI_DisconnectDevice(device);
         }
     }
 }
 
-static int WASAPI_CaptureFromDevice(SDL_AudioDevice *_this, void *buffer, int buflen)
+static int WASAPI_CaptureFromDevice(SDL_AudioDevice *device, void *buffer, int buflen)
 {
-    SDL_AudioStream *stream = _this->hidden->capturestream;
-    const int avail = SDL_GetAudioStreamAvailable(stream);
-    if (avail > 0) {
-        const int cpy = SDL_min(buflen, avail);
-        SDL_GetAudioStreamData(stream, buffer, cpy);
-        return cpy;
-    }
-
-    while (RecoverWasapiIfLost(_this)) {
-        HRESULT ret;
-        BYTE *ptr = NULL;
-        UINT32 frames = 0;
-        DWORD flags = 0;
+    BYTE *ptr = NULL;
+    UINT32 frames = 0;
+    DWORD flags = 0;
 
-        /* uhoh, client isn't activated yet, just return silence. */
-        if (!_this->hidden->capture) {
-            /* Delay so we run at about the speed that audio would be arriving. */
-            SDL_Delay(((_this->spec.samples * 1000) / _this->spec.freq));
-            SDL_memset(buffer, _this->spec.silence, buflen);
-            return buflen;
+    while (RecoverWasapiIfLost(device) && device->hidden->capture) {
+        HRESULT ret = IAudioCaptureClient_GetBuffer(device->hidden->capture, &ptr, &frames, &flags, NULL, NULL);
+        if (ret == AUDCLNT_S_BUFFER_EMPTY) {
+            return 0;  // in theory we should have waited until there was data, but oh well, we'll go back to waiting. Returning 0 is safe in SDL
         }
 
-        ret = IAudioCaptureClient_GetBuffer(_this->hidden->capture, &ptr, &frames, &flags, NULL, NULL);
-        if (ret != AUDCLNT_S_BUFFER_EMPTY) {
-            WasapiFailed(_this, ret); /* mark device lost/failed if necessary. */
-        }
+        WasapiFailed(device, ret); // mark device lost/failed if necessary.
 
-        if ((ret == AUDCLNT_S_BUFFER_EMPTY) || !frames) {
-            WASAPI_WaitDevice(_this);
-        } else if (ret == S_OK) {
-            const int total = ((int)frames) * _this->hidden->framesize;
+        if (ret == S_OK) {
+            const int total = ((int)frames) * device->hidden->framesize;
             const int cpy = SDL_min(buflen, total);
             const int leftover = total - cpy;
             const SDL_bool silent = (flags & AUDCLNT_BUFFERFLAGS_SILENT) ? SDL_TRUE : SDL_FALSE;
 
+            SDL_assert(leftover == 0);  // according to MSDN, this isn't everything available, just one "packet" of data per-GetBuffer call.
+
             if (silent) {
-                SDL_memset(buffer, _this->spec.silence, cpy);
+                SDL_memset(buffer, device->silence_value, cpy);
             } else {
                 SDL_memcpy(buffer, ptr, cpy);
             }
 
-            if (leftover > 0) {
-                ptr += cpy;
-                if (silent) {
-                    SDL_memset(ptr, _this->spec.silence, leftover); /* I guess this is safe? */
-                }
-
-                if (SDL_PutAudioStreamData(stream, ptr, leftover) == -1) {
-                    return -1; /* uhoh, out of memory, etc. Kill device.  :( */
-                }
-            }
-
-            ret = IAudioCaptureClient_ReleaseBuffer(_this->hidden->capture, frames);
-            WasapiFailed(_this, ret); /* mark device lost/failed if necessary. */
+            ret = IAudioCaptureClient_ReleaseBuffer(device->hidden->capture, frames);
+            WasapiFailed(device, ret); // mark device lost/failed if necessary.
 
             return cpy;
         }
     }
 
-    return -1; /* unrecoverable error. */
+    return -1; // unrecoverable error.
 }
 
-static void WASAPI_FlushCapture(SDL_AudioDevice *_this)
+static void WASAPI_FlushCapture(SDL_AudioDevice *device)
 {
     BYTE *ptr = NULL;
     UINT32 frames = 0;
     DWORD flags = 0;
 
-    if (!_this->hidden->capture) {
-        return; /* not activated yet? */
-    }
-
-    /* just read until we stop getting packets, throwing them away. */
-    while (SDL_TRUE) {
-        const HRESULT ret = IAudioCaptureClient_GetBuffer(_this->hidden->capture, &ptr, &frames, &flags, NULL, NULL);
+    // just read until we stop getting packets, throwing them away.
+    while (!SDL_AtomicGet(&device->shutdown) && device->hidden->capture) {
+        const HRESULT ret = IAudioCaptureClient_GetBuffer(device->hidden->capture, &ptr, &frames, &flags, NULL, NULL);
         if (ret == AUDCLNT_S_BUFFER_EMPTY) {
-            break; /* no more buffered data; we're done. */
-        } else if (WasapiFailed(_this, ret)) {
-            break; /* failed for some other reason, abort. */
-        } else if (WasapiFailed(_this, IAudioCaptureClient_ReleaseBuffer(_this->hidden->capture, frames))) {
-            break; /* something broke. */
+            break; // no more buffered data; we're done.
+        } else if (WasapiFailed(device, ret)) {
+            break; // failed for some other reason, abort.
+        } else if (WasapiFailed(device, IAudioCaptureClient_ReleaseBuffer(device->hidden->capture, frames))) {
+            break; // something broke.
         }
     }
-    SDL_ClearAudioStream(_this->hidden->capturestream);
 }
 
-static void ReleaseWasapiDevice(SDL_AudioDevice *_this)
+static void WASAPI_CloseDevice(SDL_AudioDevice *device)
 {
-    if (_this->hidden->client) {
-        IAudioClient_Stop(_this->hidden->client);
-        IAudioClient_Release(_this->hidden->client);
-        _this->hidden->client = NULL;
-    }
-
-    if (_this->hidden->render) {
-        IAudioRenderClient_Release(_this->hidden->render);
-        _this->hidden->render = NULL;
+    if (device->hidden) {
+        ResetWasapiDevice(device);
+        SDL_free(device->hidden->devid);
+        SDL_free(device->hidden);
+        device->hidden = NULL;
     }
-
-    if (_this->hidden->capture) {
-        IAudioCaptureClient_Release(_this->hidden->capture);
-        _this->hidden->capture = NULL;
-    }
-
-    if (_this->hidden->waveformat) {
-        CoTaskMemFree(_this->hidden->waveformat);
-        _this->hidden->waveformat = NULL;
-    }
-
-    if (_this->hidden->capturestream) {
-        SDL_DestroyAudioStream(_this->hidden->capturestream);
-        _this->hidden->capturestream = NULL;
-    }
-
-    if (_this->hidden->activation_handler) {
-        WASAPI_PlatformDeleteActivationHandler(_this->hidden->activation_handler);
-        _this->hidden->activation_handler = NULL;
-    }
-
-    if (_this->hidden->event) {
-        CloseHandle(_this->hidden->event);
-        _this->hidden->event = NULL;
-    }
-}
-
-static void WASAPI_CloseDevice(SDL_AudioDevice *_this)
-{
-    WASAPI_UnrefDevice(_this);
-}
-
-void WASAPI_RefDevice(SDL_AudioDevice *_this)
-{
-    SDL_AtomicIncRef(&_this->hidden->refcount);
 }
 
-void WASAPI_UnrefDevice(SDL_AudioDevice *_this)
+static int mgmtthrtask_PrepDevice(void *userdata)
 {
-    if (!SDL_AtomicDecRef(&_this->hidden->refcount)) {
-        return;
-    }
-
-    /* actual closing happens here. */
+    SDL_AudioDevice *device = (SDL_AudioDevice *)userdata;
 
-    /* don't touch _this->hidden->task in here; it has to be reverted from
-       our callback thread. We do that in WASAPI_ThreadDeinit().
-       (likewise for _this->hidden->coinitialized). */
-    ReleaseWasapiDevice(_this);
-    SDL_free(_this->hidden->devid);
-    SDL_free(_this->hidden);
-}
-
-/* This is called once a device is activated, possibly asynchronously. */
-int WASAPI_PrepDevice(SDL_AudioDevice *_this, const SDL_bool updatestream)
-{
     /* !!! FIXME: we could request an exclusive mode stream, which is lower latency;
        !!!  it will write into the kernel's audio buffer directly instead of
        !!!  shared memory that a user-mode mixer then writes to the kernel with
@@ -387,49 +526,42 @@ int WASAPI_PrepDevice(SDL_AudioDevice *_this, const SDL_bool updatestream)
        !!!  wins actually look like. Maybe add a hint to force exclusive mode at
        !!!  some point. To be sure, defaulting to shared mode is the right thing to
        !!!  do in any case. */
-    const SDL_AudioSpec oldspec = _this->spec;
     const AUDCLNT_SHAREMODE sharemode = AUDCLNT_SHAREMODE_SHARED;
-    UINT32 bufsize = 0; /* this is in sample frames, not samples, not bytes. */
-    REFERENCE_TIME default_period = 0;
-    IAudioClient *client = _this->hidden->client;
-    IAudioRenderClient *render = NULL;
-    IAudioCaptureClient *capture = NULL;
-    WAVEFORMATEX *waveformat = NULL;
-    SDL_AudioFormat test_format;
-    SDL_AudioFormat wasapi_format = 0;
-    const SDL_AudioFormat *closefmts;
-    HRESULT ret = S_OK;
-    DWORD streamflags = 0;
 
+    IAudioClient *client = device->hidden->client;
     SDL_assert(client != NULL);
 
-#if defined(__WINRT__) || defined(__GDK__) /* CreateEventEx() arrived in Vista, so we need an #ifdef for XP. */
-    _this->hidden->event = CreateEventEx(NULL, NULL, 0, EVENT_ALL_ACCESS);
+#if defined(__WINRT__) || defined(__GDK__) // CreateEventEx() arrived in Vista, so we need an #ifdef for XP.
+    device->hidden->event = CreateEventEx(NULL, NULL, 0, EVENT_ALL_ACCESS);
 #else
-    _this->hidden->event = CreateEventW(NULL, 0, 0, NULL);
+    device->hidden->event = CreateEventW(NULL, 0, 0, NULL);
 #endif
 
-    if (_this->hidden->event == NULL) {
+    if (device->hidden->event == NULL) {
         return WIN_SetError("WASAPI can't create an event handle");
     }
 
+    HRESULT ret;
+
+    WAVEFORMATEX *waveformat = NULL;
     ret = IAudioClient_GetMixFormat(client, &waveformat);
     if (FAILED(ret)) {
         return WIN_SetErrorFromHRESULT("WASAPI can't determine mix format", ret);
     }
-
     SDL_assert(waveformat != NULL);
-    _this->hidden->waveformat = waveformat;
+    device->hidden->waveformat = waveformat;
 
-    _this->spec.channels = (Uint8)waveformat->nChannels;
+    SDL_AudioSpec newspec;
+    newspec.channels = (Uint8)waveformat->nChannels;
 
-    /* Make sure we have a valid format that we can convert to whatever WASAPI wants. */
-    wasapi_format = WaveFormatToSDLFormat(waveformat);
+    // Make sure we have a valid format that we can convert to whatever WASAPI wants.
+    const SDL_AudioFormat wasapi_format = SDL_WaveFormatExToSDLFormat(waveformat);
 
-    closefmts = SDL_ClosestAudioFormats(_this->spec.format);
+    SDL_AudioFormat test_format;
+    const SDL_AudioFormat *closefmts = SDL_ClosestAudioFormats(device->spec.format);
     while ((test_format = *(closefmts++)) != 0) {
         if (test_format == wasapi_format) {
-            _this->spec.format = test_format;
+            newspec.format = test_format;
             break;
         }
     }
@@ -438,36 +570,40 @@ int WASAPI_PrepDevice(SDL_AudioDevice *_this, const SDL_bool updatestream)
         return SDL_SetError("%s: Unsupported audio format", "wasapi");
     }
 
+    REFERENCE_TIME default_period = 0;
     ret = IAudioClient_GetDevicePeriod(client, &default_period, NULL);
     if (FAILED(ret)) {
         return WIN_SetErrorFromHRESULT("WASAPI can't determine minimum device period", ret);
     }
 
+    DWORD streamflags = 0;
+
     /* we've gotten reports that WASAPI's resampler introduces distortions, but in the short term
        it fixes some other WASAPI-specific quirks we haven't quite tracked down.
        Refer to bug #6326 for the immediate concern. */
-#if 0
-    _this->spec.freq = waveformat->nSamplesPerSec;  /* force sampling rate so our resampler kicks in, if necessary. */
-#else
-    /* favor WASAPI's resampler over our own */
-    if ((DWORD)_this->spec.freq != waveformat->nSamplesPerSec) {
+#if 1
+    // favor WASAPI's resampler over our own
+    if ((DWORD)device->spec.freq != waveformat->nSamplesPerSec) {
         streamflags |= (AUDCLNT_STREAMFLAGS_AUTOCONVERTPCM | AUDCLNT_STREAMFLAGS_SRC_DEFAULT_QUALITY);
-        waveformat->nSamplesPerSec = _this->spec.freq;
+        waveformat->nSamplesPerSec = device->spec.freq;
         waveformat->nAvgBytesPerSec = waveformat->nSamplesPerSec * waveformat->nChannels * (waveformat->wBitsPerSample / 8);
     }
 #endif
 
+    newspec.freq = waveformat->nSamplesPerSec;
+
     streamflags |= AUDCLNT_STREAMFLAGS_EVENTCALLBACK;
     ret = IAudioClient_Initialize(client, sharemode, streamflags, 0, 0, waveformat, NULL);
     if (FAILED(ret)) {
         return WIN_SetErrorFromHRESULT("WASAPI can't initialize audio client", ret);
     }
 
-    ret = IAudioClient_SetEventHandle(client, _this->hidden->event);
+    ret = IAudioClient_SetEventHandle(client, device->hidden->event);
     if (FAILED(ret)) {
         return WIN_SetErrorFromHRESULT("WASAPI can't set event handle", ret);
     }
 
+    UINT32 bufsize = 0; // this is in sample frames, not samples, not bytes.
     ret = IAudioClient_GetBufferSize(client, &bufsize);
     if (FAILED(ret)) {
         return WIN_SetErrorFromHRESULT("WASAPI can't determine buffer size", ret);
@@ -475,116 +611,108 @@ int WASAPI_PrepDevice(SDL_AudioDevice *_this, const SDL_bool updatestream)
 
     /* Match the callback size to the period size to cut down on the number of
        interrupts waited for in each call to WaitDevice */
-    {
-        const float period_millis = default_period / 10000.0f;
-        const float period_frames = period_millis * _this->spec.freq / 1000.0f;
-        _this->spec.samples = (Uint16)SDL_ceilf(period_frames);
-    }
-
-    /* Update the fragment size as size in bytes */
-    SDL_CalculateAudioSpec(&_this->spec);
+    const float period_millis = default_period / 10000.0f;
+    const float period_frames = period_millis * newspec.freq / 1000.0f;
+    const int new_sample_frames = (int) SDL_ceilf(period_frames);
 
-    _this->hidden->framesize = (SDL_AUDIO_BITSIZE(_this->spec.format) / 8) * _this->spec.channels;
+    // Update the fragment size as size in bytes
+    if (SDL_AudioDeviceFormatChangedAlreadyLocked(device, &newspec, new_sample_frames) < 0) {
+        return -1;
+    }
 
-    if (_this->iscapture) {
-        _this->hidden->capturestream = SDL_CreateAudioStream(_this->spec.format, _this->spec.channels, _this->spec.freq, _this->spec.format, _this->spec.channels, _this->spec.freq);
-        if (!_this->hidden->capturestream) {
-            return -1; /* already set SDL_Error */
-        }
+    device->hidden->framesize = (SDL_AUDIO_BITSIZE(device->spec.format) / 8) * device->spec.channels;
 
+    if (device->iscapture) {
+        IAudioCaptureClient *capture = NULL;
         ret = IAudioClient_GetService(client, &SDL_IID_IAudioCaptureClient, (void **)&capture);
         if (FAILED(ret)) {
             return WIN_SetErrorFromHRESULT("WASAPI can't get capture client service", ret);
         }
 
         SDL_assert(capture != NULL);
-        _this->hidden->capture = capture;
+        device->hidden->capture = capture;
         ret = IAudioClient_Start(client);
         if (FAILED(ret)) {
             return WIN_SetErrorFromHRESULT("WASAPI can't start capture", ret);
         }
 
-        WASAPI_FlushCapture(_this); /* MSDN says you should flush capture endpoint right after startup. */
+        WASAPI_FlushCapture(device); // MSDN says you should flush capture endpoint right after startup.
     } else {
+        IAudioRenderClient *render = NULL;
         ret = IAudioClient_GetService(client, &SDL_IID_IAudioRenderClient, (void **)&render);
         if (FAILED(ret)) {
             return WIN_SetErrorFromHRESULT("WASAPI can't get render client service", ret);
         }
 
         SDL_assert(render != NULL);
-        _this->hidden->render = render;
+        device->hidden->render = render;
         ret = IAudioClient_Start(client);
         if (FAILED(ret)) {
             return WIN_SetErrorFromHRESULT("WASAPI can't start playback", ret);
         }
     }
 
-    if (updatestream) {
-        return UpdateAudioStream(_this, &oldspec);
-    }
-
-    return 0; /* good to go. */
+    return 0; // good to go.
 }
 
-static int WASAPI_OpenDevice(SDL_AudioDevice *_this, const char *devname)
+// This is called once a device is activated, possibly asynchronously.
+int WASAPI_PrepDevice(SDL_AudioDevice *device)
 {
-    LPCWSTR devid = (LPCWSTR)_this->handle;
+    int rc = 0;
+    return (WASAPI_ProxyToManagementThread(mgmtthrtask_PrepDevice, device, &rc) < 0) ? -1 : rc;
+}
 
-    /* Initialize all variables that we clean on shutdown */
-    _this->hidden = (struct SDL_PrivateAudioData *) SDL_malloc(sizeof(*_this->hidden));
-    if (_this->hidden == NULL) {
+static int WASAPI_OpenDevice(SDL_AudioDevice *device)
+{
+    // Initialize all variables that we clean on shutdown
+    device->hidden = (struct SDL_PrivateAudioData *) SDL_calloc(1, sizeof(*device->hidden));
+    if (device->hidden == NULL) {
         return SDL_OutOfMemory();
-    }
-    SDL_zerop(_this->hidden);
-
-    WASAPI_RefDevice(_this); /* so CloseDevice() will unref to zero. */
-
-    if (!devid) { /* is default device? */
-        _this->hidden->default_device_generation = SDL_AtomicGet(_this->iscapture ? &SDL_IMMDevice_DefaultCaptureGeneration : &SDL_IMMDevice_DefaultPlaybackGeneration);
-    } else {
-        _this->hidden->devid = SDL_wcsdup(devid);
-        if (!_this->hidden->devid) {
-            return SDL_OutOfMemory();
-        }
-    }
-
-    if (WASAPI_ActivateDevice(_this, SDL_FALSE) == -1) {
-        return -1; /* already set error. */
+    } else if (ActivateWasapiDevice(device) < 0) {
+        return -1; // already set error.
     }
 
-    /* Ready, but waiting for async device activation.
+    /* Ready, but possibly waiting for async device activation.
        Until activation is successful, we will report silence from capture
-       devices and ignore data on playback devices.
-       Also, since we don't know the _actual_ device format until after
-       activation, we let the app have whatever it asks for. We set up
-       an SDL_AudioStream to convert, if necessary, once the activation
-       completes. */
+       devices and ignore data on playback devices. Upon activation, we'll make
+       sure any bound audio streams are adjusted for the final device format. */
 
     return 0;
 }
 
-static void WASAPI_ThreadInit(SDL_AudioDevice *_this)
+static void WASAPI_ThreadInit(SDL_AudioDevice *device)
+{
+    WASAPI_PlatformThreadInit(device);
+}
+
+static void WASAPI_ThreadDeinit(SDL_AudioDevice *device)
+{
+    WASAPI_PlatformThreadDeinit(device);
+}
+
+static int mgmtthrtask_FreeDeviceHandle(void *userdata)
 {
-    WASAPI_PlatformThreadInit(_this);
+    WASAPI_PlatformFreeDeviceHandle((SDL_AudioDevice *)userdata);
+    return 0;
 }
 
-static void WASAPI_ThreadDeinit(SDL_AudioDevice *_this)
+static void WASAPI_FreeDeviceHandle(SDL_AudioDevice *device)
 {
-    WASAPI_PlatformThreadDeinit(_this);
+    int rc;
+    WASAPI_ProxyToManagementThread(mgmtthrtask_FreeDeviceHandle, device, &rc);
 }
 
 static void WASAPI_Deinitialize(void)
 {
-    WASAPI_PlatformDeinit();
+    DeinitManagementThread();
 }
 
 static SDL_bool WASAPI_Init(SDL_AudioDriverImpl *impl)
 {
-    if (WASAPI_PlatformInit() == -1) {
+    if (InitManagementThread() < 0) {
         return SDL_FALSE;
     }
 
-    /* Set the function pointers */
     impl->DetectDevices = WASAPI_DetectDevices;
     impl->ThreadInit = WASAPI_ThreadInit;
     impl->ThreadDeinit = WASAPI_ThreadDeinit;
@@ -592,19 +720,20 @@ static SDL_bool WASAPI_Init(SDL_AudioDriverImpl *impl)
     impl->PlayDevice = WASAPI_PlayDevice;
     impl->WaitDevice = WASAPI_WaitDevice;
     impl->GetDeviceBuf = WASAPI_GetDeviceBuf;
+    impl->WaitCaptureDevice = WASAPI_WaitDevice;
     impl->CaptureFromDevice = WASAPI_CaptureFromDevice;
     impl->FlushCapture = WASAPI_FlushCapture;
     impl->CloseDevice = WASAPI_CloseDevice;
     impl->Deinitialize = WASAPI_Deinitialize;
-    impl->GetDefaultAudioInfo = WASAPI_GetDefaultAudioInfo;
+    impl->FreeDeviceHandle = WASAPI_FreeDeviceHandle;
+
     impl->HasCaptureSupport = SDL_TRUE;
-    impl->SupportsNonPow2Samples = SDL_TRUE;
 
-    return SDL_TRUE; /* this audio target is available. */
+    return SDL_TRUE;
 }
 
 AudioBootStrap WASAPI_bootstrap = {
     "wasapi", "WASAPI", WASAPI_Init, SDL_FALSE
 };
 
-#endif /* SDL_AUDIO_DRIVER_WASAPI */
+#endif // SDL_AUDIO_DRIVER_WASAPI

src/audio/wasapi/SDL_wasapi.h

@@ -31,37 +31,38 @@ extern "C" {
 
 struct SDL_PrivateAudioData
 {
-    SDL_AtomicInt refcount;
     WCHAR *devid;
     WAVEFORMATEX *waveformat;
     IAudioClient *client;
     IAudioRenderClient *render;
     IAudioCaptureClient *capture;
-    SDL_AudioStream *capturestream;
     HANDLE event;
     HANDLE task;
     SDL_bool coinitialized;
     int framesize;
-    int default_device_generation;
     SDL_bool device_lost;
     void *activation_handler;
-    SDL_AtomicInt just_activated;
 };
 
 /* win32 and winrt implementations call into these. */
-int WASAPI_PrepDevice(SDL_AudioDevice *_this, const SDL_bool updatestream);
-void WASAPI_RefDevice(SDL_AudioDevice *_this);
-void WASAPI_UnrefDevice(SDL_AudioDevice *_this);
+int WASAPI_PrepDevice(SDL_AudioDevice *device);
+void WASAPI_DisconnectDevice(SDL_AudioDevice *device);
+
+
+// BE CAREFUL: if you are holding the device lock and proxy to the management thread with wait_until_complete, and grab the lock again, you will deadlock.
+typedef int (*ManagementThreadTask)(void *userdata);
+int WASAPI_ProxyToManagementThread(ManagementThreadTask task, void *userdata, int *wait_until_complete);
 
 /* These are functions that are implemented differently for Windows vs WinRT. */
+// UNLESS OTHERWISE NOTED THESE ALL HAPPEN ON THE MANAGEMENT THREAD.
 int WASAPI_PlatformInit(void);
 void WASAPI_PlatformDeinit(void);
-void WASAPI_EnumerateEndpoints(void);
-int WASAPI_GetDefaultAudioInfo(char **name, SDL_AudioSpec *spec, int iscapture);
-int WASAPI_ActivateDevice(SDL_AudioDevice *_this, const SDL_bool isrecovery);
-void WASAPI_PlatformThreadInit(SDL_AudioDevice *_this);
-void WASAPI_PlatformThreadDeinit(SDL_AudioDevice *_this);
+void WASAPI_EnumerateEndpoints(SDL_AudioDevice **default_output, SDL_AudioDevice **default_capture);
+int WASAPI_ActivateDevice(SDL_AudioDevice *device);
+void WASAPI_PlatformThreadInit(SDL_AudioDevice *device);  // this happens on the audio device thread, not the management thread.
+void WASAPI_PlatformThreadDeinit(SDL_AudioDevice *device);  // this happens on the audio device thread, not the management thread.
 void WASAPI_PlatformDeleteActivationHandler(void *handler);
+void WASAPI_PlatformFreeDeviceHandle(SDL_AudioDevice *device);
 
 #ifdef __cplusplus
 }

src/audio/wasapi/SDL_wasapi_win32.c

@@ -49,7 +49,7 @@ static const IID SDL_IID_IAudioClient = { 0x1cb9ad4c, 0xdbfa, 0x4c32, { 0xb1, 0x
 
 int WASAPI_PlatformInit(void)
 {
-    if (SDL_IMMDevice_Init() < 0) {
+    if (SDL_IMMDevice_Init() < 0) {   // this will call WIN_CoInitialize for us!
         return -1; /* This is set by SDL_IMMDevice_Init */
     }
 
@@ -72,72 +72,68 @@ void WASAPI_PlatformDeinit(void)
     pAvSetMmThreadCharacteristicsW = NULL;
     pAvRevertMmThreadCharacteristics = NULL;
 
-    SDL_IMMDevice_Quit();
+    SDL_IMMDevice_Quit();  // This will call WIN_CoUninitialize for us!
 }
 
-void WASAPI_PlatformThreadInit(SDL_AudioDevice *_this)
+void WASAPI_PlatformThreadInit(SDL_AudioDevice *device)
 {
     /* this thread uses COM. */
     if (SUCCEEDED(WIN_CoInitialize())) { /* can't report errors, hope it worked! */
-        _this->hidden->coinitialized = SDL_TRUE;
+        device->hidden->coinitialized = SDL_TRUE;
     }
 
     /* Set this thread to very high "Pro Audio" priority. */
     if (pAvSetMmThreadCharacteristicsW) {
         DWORD idx = 0;
-        _this->hidden->task = pAvSetMmThreadCharacteristicsW(L"Pro Audio", &idx);
+        device->hidden->task = pAvSetMmThreadCharacteristicsW(L"Pro Audio", &idx);
+    } else {
+        SDL_SetThreadPriority(device->iscapture ? SDL_THREAD_PRIORITY_HIGH : SDL_THREAD_PRIORITY_TIME_CRITICAL);
     }
+
 }
 
-void WASAPI_PlatformThreadDeinit(SDL_AudioDevice *_this)
+void WASAPI_PlatformThreadDeinit(SDL_AudioDevice *device)
 {
     /* Set this thread back to normal priority. */
-    if (_this->hidden->task && pAvRevertMmThreadCharacteristics) {
-        pAvRevertMmThreadCharacteristics(_this->hidden->task);
-        _this->hidden->task = NULL;
+    if (device->hidden->task && pAvRevertMmThreadCharacteristics) {
+        pAvRevertMmThreadCharacteristics(device->hidden->task);
+        device->hidden->task = NULL;
     }
 
-    if (_this->hidden->coinitialized) {
+    if (device->hidden->coinitialized) {
         WIN_CoUninitialize();
-        _this->hidden->coinitialized = SDL_FALSE;
+        device->hidden->coinitialized = SDL_FALSE;
     }
 }
 
-int WASAPI_ActivateDevice(SDL_AudioDevice *_this, const SDL_bool isrecovery)
+int WASAPI_ActivateDevice(SDL_AudioDevice *device)
 {
-    IMMDevice *device = NULL;
-    HRESULT ret;
-
-    if (SDL_IMMDevice_Get(_this->hidden->devid, &device, _this->iscapture) < 0) {
-        _this->hidden->client = NULL;
+    IMMDevice *immdevice = NULL;
+    if (SDL_IMMDevice_Get(device, &immdevice, device->iscapture) < 0) {
+        device->hidden->client = NULL;
         return -1; /* This is already set by SDL_IMMDevice_Get */
     }
 
-    /* this is not async in standard win32, yay! */
-    ret = IMMDevice_Activate(device, &SDL_IID_IAudioClient, CLSCTX_ALL, NULL, (void **)&_this->hidden->client);
-    IMMDevice_Release(device);
+    /* this is _not_ async in standard win32, yay! */
+    HRESULT ret = IMMDevice_Activate(immdevice, &SDL_IID_IAudioClient, CLSCTX_ALL, NULL, (void **)&device->hidden->client);
+    IMMDevice_Release(immdevice);
 
     if (FAILED(ret)) {
-        SDL_assert(_this->hidden->client == NULL);
+        SDL_assert(device->hidden->client == NULL);
         return WIN_SetErrorFromHRESULT("WASAPI can't activate audio endpoint", ret);
     }
 
-    SDL_assert(_this->hidden->client != NULL);
-    if (WASAPI_PrepDevice(_this, isrecovery) == -1) { /* not async, fire it right away. */
+    SDL_assert(device->hidden->client != NULL);
+    if (WASAPI_PrepDevice(device) == -1) { /* not async, fire it right away. */
         return -1;
     }
 
     return 0; /* good to go. */
 }
 
-void WASAPI_EnumerateEndpoints(void)
-{
-    SDL_IMMDevice_EnumerateEndpoints(SDL_FALSE);
-}
-
-int WASAPI_GetDefaultAudioInfo(char **name, SDL_AudioSpec *spec, int iscapture)
+void WASAPI_EnumerateEndpoints(SDL_AudioDevice **default_output, SDL_AudioDevice **default_capture)
 {
-    return SDL_IMMDevice_GetDefaultAudioInfo(name, spec, iscapture);
+    SDL_IMMDevice_EnumerateEndpoints(default_output, default_capture);
 }
 
 void WASAPI_PlatformDeleteActivationHandler(void *handler)
@@ -146,4 +142,9 @@ void WASAPI_PlatformDeleteActivationHandler(void *handler)
     SDL_assert(!"This function should have only been called on WinRT.");
 }
 
+void WASAPI_PlatformFreeDeviceHandle(SDL_AudioDevice *device)
+{
+    SDL_IMMDevice_FreeDeviceHandle(device);
+}
+
 #endif /* SDL_AUDIO_DRIVER_WASAPI && !defined(__WINRT__) */

src/audio/wasapi/SDL_wasapi_winrt.cpp

@@ -53,21 +53,16 @@ using namespace Microsoft::WRL;
 
 static Platform::String ^ SDL_PKEY_AudioEngine_DeviceFormat = L"{f19f064d-082c-4e27-bc73-6882a1bb8e4c} 0";
 
-static void WASAPI_AddDevice(const SDL_bool iscapture, const char *devname, WAVEFORMATEXTENSIBLE *fmt, LPCWSTR devid);
-static void WASAPI_RemoveDevice(const SDL_bool iscapture, LPCWSTR devid);
-extern "C" {
-SDL_AtomicInt SDL_IMMDevice_DefaultPlaybackGeneration;
-SDL_AtomicInt SDL_IMMDevice_DefaultCaptureGeneration;
-}
 
-/* This is a list of device id strings we have inflight, so we have consistent pointers to the same device. */
-typedef struct DevIdList
+static SDL_bool FindWinRTAudioDeviceCallback(SDL_AudioDevice *device, void *userdata)
 {
-    WCHAR *str;
-    struct DevIdList *next;
-} DevIdList;
+    return (SDL_wcscmp((LPCWSTR) device->handle, (LPCWSTR) userdata) == 0) ? SDL_TRUE : SDL_FALSE;
+}
 
-static DevIdList *deviceid_list = NULL;
+static SDL_AudioDevice *FindWinRTAudioDevice(LPCWSTR devid)
+{
+    return SDL_FindPhysicalAudioDeviceByCallback(FindWinRTAudioDeviceCallback, (void *) devid);
+}
 
 class SDL_WasapiDeviceEventHandler
 {
@@ -80,9 +75,10 @@ class SDL_WasapiDeviceEventHandler
     void OnEnumerationCompleted(DeviceWatcher ^ sender, Platform::Object ^ args);
     void OnDefaultRenderDeviceChanged(Platform::Object ^ sender, DefaultAudioRenderDeviceChangedEventArgs ^ args);
     void OnDefaultCaptureDeviceChanged(Platform::Object ^ sender, DefaultAudioCaptureDeviceChangedEventArgs ^ args);
-    SDL_Semaphore *completed;
+    void WaitForCompletion();
 
   private:
+    SDL_Semaphore *completed_semaphore;
     const SDL_bool iscapture;
     DeviceWatcher ^ watcher;
     Windows::Foundation::EventRegistrationToken added_handler;
@@ -93,10 +89,11 @@ class SDL_WasapiDeviceEventHandler
 };
 
 SDL_WasapiDeviceEventHandler::SDL_WasapiDeviceEventHandler(const SDL_bool _iscapture)
-    : iscapture(_iscapture), completed(SDL_CreateSemaphore(0))
+    : iscapture(_iscapture), completed_semaphore(SDL_CreateSemaphore(0))
 {
-    if (!completed)
+    if (!completed_semaphore) {
         return; // uhoh.
+    }
 
     Platform::String ^ selector = _iscapture ? MediaDevice::GetAudioCaptureSelector() : MediaDevice::GetAudioRenderSelector();
     Platform::Collections::Vector<Platform::String ^> properties;
@@ -128,9 +125,10 @@ SDL_WasapiDeviceEventHandler::~SDL_WasapiDeviceEventHandler()
         watcher->Stop();
         watcher = nullptr;
     }
-    if (completed) {
-        SDL_DestroySemaphore(completed);
-        completed = nullptr;
+
+    if (completed_semaphore) {
+        SDL_DestroySemaphore(completed_semaphore);
+        completed_semaphore = nullptr;
     }
 
     if (iscapture) {
@@ -142,21 +140,34 @@ SDL_WasapiDeviceEventHandler::~SDL_WasapiDeviceEventHandler()
 
 void SDL_WasapiDeviceEventHandler::OnDeviceAdded(DeviceWatcher ^ sender, DeviceInformation ^ info)
 {
+    /* You can have multiple endpoints on a device that are mutually exclusive ("Speakers" vs "Line Out" or whatever).
+       In a perfect world, things that are unplugged won't be in this collection. The only gotcha is probably for
+       phones and tablets, where you might have an internal speaker and a headphone jack and expect both to be
+       available and switch automatically. (!!! FIXME...?) */
+
     SDL_assert(sender == this->watcher);
     char *utf8dev = WIN_StringToUTF8(info->Name->Data());
     if (utf8dev) {
-        WAVEFORMATEXTENSIBLE fmt;
+        SDL_AudioSpec spec;
+        SDL_zero(spec);
+
         Platform::Object ^ obj = info->Properties->Lookup(SDL_PKEY_AudioEngine_DeviceFormat);
         if (obj) {
             IPropertyValue ^ property = (IPropertyValue ^) obj;
             Platform::Array<unsigned char> ^ data;
             property->GetUInt8Array(&data);
-            SDL_memcpy(&fmt, data->Data, SDL_min(data->Length, sizeof(WAVEFORMATEXTENSIBLE)));
-        } else {
+            WAVEFORMATEXTENSIBLE fmt;
             SDL_zero(fmt);
+            SDL_memcpy(&fmt, data->Data, SDL_min(data->Length, sizeof(WAVEFORMATEXTENSIBLE)));
+            spec.channels = (Uint8)fmt.Format.nChannels;
+            spec.freq = fmt.Format.nSamplesPerSec;
+            spec.format = SDL_WaveFormatExToSDLFormat((WAVEFORMATEX *)&fmt);
         }
 
-        WASAPI_AddDevice(this->iscapture, utf8dev, &fmt, info->Id->Data());
+        LPWSTR devid = SDL_wcsdup(info->Id->Data());
+        if (devid) {
+            SDL_AddAudioDevice(this->iscapture, utf8dev, spec.channels ? &spec : NULL, devid);
+        }
         SDL_free(utf8dev);
     }
 }
@@ -164,7 +175,7 @@ void SDL_WasapiDeviceEventHandler::OnDeviceAdded(DeviceWatcher ^ sender, DeviceI
 void SDL_WasapiDeviceEventHandler::OnDeviceRemoved(DeviceWatcher ^ sender, DeviceInformationUpdate ^ info)
 {
     SDL_assert(sender == this->watcher);
-    WASAPI_RemoveDevice(this->iscapture, info->Id->Data());
+    WASAPI_DisconnectDevice(FindWinRTAudioDevice(info->Id->Data()));
 }
 
 void SDL_WasapiDeviceEventHandler::OnDeviceUpdated(DeviceWatcher ^ sender, DeviceInformationUpdate ^ args)
@@ -175,19 +186,30 @@ void SDL_WasapiDeviceEventHandler::OnDeviceUpdated(DeviceWatcher ^ sender, Devic
 void SDL_WasapiDeviceEventHandler::OnEnumerationCompleted(DeviceWatcher ^ sender, Platform::Object ^ args)
 {
     SDL_assert(sender == this->watcher);
-    SDL_PostSemaphore(this->completed);
+    if (this->completed_semaphore) {
+        SDL_PostSemaphore(this->completed_semaphore);
+    }
 }
 
 void SDL_WasapiDeviceEventHandler::OnDefaultRenderDeviceChanged(Platform::Object ^ sender, DefaultAudioRenderDeviceChangedEventArgs ^ args)
 {
     SDL_assert(!this->iscapture);
-    SDL_AtomicAdd(&SDL_IMMDevice_DefaultPlaybackGeneration, 1);
+    SDL_DefaultAudioDeviceChanged(FindWinRTAudioDevice(args->Id->Data()));
 }
 
 void SDL_WasapiDeviceEventHandler::OnDefaultCaptureDeviceChanged(Platform::Object ^ sender, DefaultAudioCaptureDeviceChangedEventArgs ^ args)
 {
     SDL_assert(this->iscapture);
-    SDL_AtomicAdd(&SDL_IMMDevice_DefaultCaptureGeneration, 1);
+    SDL_DefaultAudioDeviceChanged(FindWinRTAudioDevice(args->Id->Data()));
+}
+
+void SDL_WasapiDeviceEventHandler::WaitForCompletion()
+{
+    if (this->completed_semaphore) {
+        SDL_WaitSemaphore(this->completed_semaphore);
+        SDL_DestroySemaphore(this->completed_semaphore);
+        this->completed_semaphore = nullptr;
+    }
 }
 
 static SDL_WasapiDeviceEventHandler *playback_device_event_handler;
@@ -195,54 +217,63 @@ static SDL_WasapiDeviceEventHandler *capture_device_event_handler;
 
 int WASAPI_PlatformInit(void)
 {
-    SDL_AtomicSet(&SDL_IMMDevice_DefaultPlaybackGeneration, 1);
-    SDL_AtomicSet(&SDL_IMMDevice_DefaultCaptureGeneration, 1);
     return 0;
 }
 
 void WASAPI_PlatformDeinit(void)
 {
-    DevIdList *devidlist;
-    DevIdList *next;
-
     delete playback_device_event_handler;
     playback_device_event_handler = nullptr;
     delete capture_device_event_handler;
     capture_device_event_handler = nullptr;
-
-    for (devidlist = deviceid_list; devidlist; devidlist = next) {
-        next = devidlist->next;
-        SDL_free(devidlist->str);
-        SDL_free(devidlist);
-    }
-    deviceid_list = NULL;
 }
 
-void WASAPI_EnumerateEndpoints(void)
+void WASAPI_EnumerateEndpoints(SDL_AudioDevice **default_output, SDL_AudioDevice **default_capture)
 {
+    Platform::String ^ defdevid;
+
     // DeviceWatchers will fire an Added event for each existing device at
     //  startup, so we don't need to enumerate them separately before
     //  listening for updates.
     playback_device_event_handler = new SDL_WasapiDeviceEventHandler(SDL_FALSE);
+    playback_device_event_handler->WaitForCompletion();
+    defdevid = MediaDevice::GetDefaultAudioRenderId(AudioDeviceRole::Default);
+    if (defdevid) {
+        *default_output = FindWinRTAudioDevice(defdevid->Data());
+    }
+
     capture_device_event_handler = new SDL_WasapiDeviceEventHandler(SDL_TRUE);
-    SDL_WaitSemaphore(playback_device_event_handler->completed);
-    SDL_WaitSemaphore(capture_device_event_handler->completed);
+    capture_device_event_handler->WaitForCompletion();
+    defdevid = MediaDevice::GetDefaultAudioCaptureId(AudioDeviceRole::Default);
+    if (defdevid) {
+        *default_capture = FindWinRTAudioDevice(defdevid->Data());
+    }
 }
 
-struct SDL_WasapiActivationHandler : public RuntimeClass<RuntimeClassFlags<ClassicCom>, FtmBase, IActivateAudioInterfaceCompletionHandler>
+class SDL_WasapiActivationHandler : public RuntimeClass<RuntimeClassFlags<ClassicCom>, FtmBase, IActivateAudioInterfaceCompletionHandler>
 {
-    SDL_WasapiActivationHandler() : device(nullptr) {}
-    STDMETHOD(ActivateCompleted)
-    (IActivateAudioInterfaceAsyncOperation *operation);
-    SDL_AudioDevice *device;
+public:
+    SDL_WasapiActivationHandler() : completion_semaphore(SDL_CreateSemaphore(0)) { SDL_assert(completion_semaphore != NULL); }
+    STDMETHOD(ActivateCompleted)(IActivateAudioInterfaceAsyncOperation *operation);
+    void WaitForCompletion();
+private:
+    SDL_Semaphore *completion_semaphore;
 };
 
+void SDL_WasapiActivationHandler::WaitForCompletion()
+{
+    if (completion_semaphore) {
+        SDL_WaitSemaphore(completion_semaphore);
+        SDL_DestroySemaphore(completion_semaphore);
+        completion_semaphore = NULL;
+    }
+}
+
 HRESULT
 SDL_WasapiActivationHandler::ActivateCompleted(IActivateAudioInterfaceAsyncOperation *async)
 {
     // Just set a flag, since we're probably in a different thread. We'll pick it up and init everything on our own thread to prevent races.
-    SDL_AtomicSet(&device->hidden->just_activated, 1);
-    WASAPI_UnrefDevice(device);
+    SDL_PostSemaphore(completion_semaphore);
     return S_OK;
 }
 
@@ -251,24 +282,10 @@ void WASAPI_PlatformDeleteActivationHandler(void *handler)
     ((SDL_WasapiActivationHandler *)handler)->Release();
 }
 
-int WASAPI_GetDefaultAudioInfo(char **name, SDL_AudioSpec *spec, int iscapture)
+int WASAPI_ActivateDevice(SDL_AudioDevice *device)
 {
-    return SDL_Unsupported();
-}
-
-int WASAPI_ActivateDevice(SDL_AudioDevice *_this, const SDL_bool isrecovery)
-{
-    LPCWSTR devid = _this->hidden->devid;
-    Platform::String ^ defdevid;
-
-    if (devid == nullptr) {
-        defdevid = _this->iscapture ? MediaDevice::GetDefaultAudioCaptureId(AudioDeviceRole::Default) : MediaDevice::GetDefaultAudioRenderId(AudioDeviceRole::Default);
-        if (defdevid) {
-            devid = defdevid->Data();
-        }
-    }
-
-    SDL_AtomicSet(&_this->hidden->just_activated, 0);
+    LPCWSTR devid = (LPCWSTR) device->handle;
+    SDL_assert(devid != NULL);
 
     ComPtr<SDL_WasapiActivationHandler> handler = Make<SDL_WasapiActivationHandler>();
     if (handler == nullptr) {
@@ -276,10 +293,8 @@ int WASAPI_ActivateDevice(SDL_AudioDevice *_this, const SDL_bool isrecovery)
     }
 
     handler.Get()->AddRef(); // we hold a reference after ComPtr destructs on return, causing a Release, and Release ourselves in WASAPI_PlatformDeleteActivationHandler(), etc.
-    handler.Get()->device = _this;
-    _this->hidden->activation_handler = handler.Get();
+    device->hidden->activation_handler = handler.Get();
 
-    WASAPI_RefDevice(_this); /* completion handler will unref it. */
     IActivateAudioInterfaceAsyncOperation *async = nullptr;
     const HRESULT ret = ActivateAudioInterfaceAsync(devid, __uuidof(IAudioClient), nullptr, handler.Get(), &async);
 
@@ -288,21 +303,11 @@ int WASAPI_ActivateDevice(SDL_AudioDevice *_this, const SDL_bool isrecovery)
             async->Release();
         }
         handler.Get()->Release();
-        WASAPI_UnrefDevice(_this);
         return WIN_SetErrorFromHRESULT("WASAPI can't activate requested audio endpoint", ret);
     }
 
-    /* Spin until the async operation is complete.
-     * If we don't PrepDevice before leaving this function, the bug list gets LONG:
-     * - device.spec is not filled with the correct information
-     * - The 'obtained' spec will be wrong for ALLOW_CHANGE properties
-     * - SDL_AudioStreams will/will not be allocated at the right time
-     * - SDL_assert(device->callbackspec.size == device->spec.size) will fail
-     * - When the assert is ignored, skipping or a buffer overflow will occur
-     */
-    while (!SDL_AtomicCAS(&_this->hidden->just_activated, 1, 0)) {
-        SDL_Delay(1);
-    }
+    // !!! FIXME: the problems in SDL2 that needed this to be synchronous are _probably_ solved by SDL3, and this can block indefinitely if a user prompt is shown to get permission to use a microphone.
+    handler.Get()->WaitForCompletion();  // block here until we have an answer, so this is synchronous to us after all.
 
     HRESULT activateRes = S_OK;
     IUnknown *iunknown = nullptr;
@@ -314,114 +319,32 @@ int WASAPI_ActivateDevice(SDL_AudioDevice *_this, const SDL_bool isrecovery)
         return WIN_SetErrorFromHRESULT("Failed to activate WASAPI device", activateRes);
     }
 
-    iunknown->QueryInterface(IID_PPV_ARGS(&_this->hidden->client));
-    if (!_this->hidden->client) {
+    iunknown->QueryInterface(IID_PPV_ARGS(&device->hidden->client));
+    if (!device->hidden->client) {
         return SDL_SetError("Failed to query WASAPI client interface");
     }
 
-    if (WASAPI_PrepDevice(_this, isrecovery) == -1) {
+    if (WASAPI_PrepDevice(device) == -1) {
         return -1;
     }
 
     return 0;
 }
 
-void WASAPI_PlatformThreadInit(SDL_AudioDevice *_this)
+void WASAPI_PlatformThreadInit(SDL_AudioDevice *device)
 {
     // !!! FIXME: set this thread to "Pro Audio" priority.
+    SDL_SetThreadPriority(device->iscapture ? SDL_THREAD_PRIORITY_HIGH : SDL_THREAD_PRIORITY_TIME_CRITICAL);
 }
 
-void WASAPI_PlatformThreadDeinit(SDL_AudioDevice *_this)
+void WASAPI_PlatformThreadDeinit(SDL_AudioDevice *device)
 {
     // !!! FIXME: set this thread to "Pro Audio" priority.
 }
 
-/* Everything below was copied from SDL_wasapi.c, before it got moved to SDL_immdevice.c! */
-
-static const GUID SDL_KSDATAFORMAT_SUBTYPE_PCM = { 0x00000001, 0x0000, 0x0010, { 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71 } };
-static const GUID SDL_KSDATAFORMAT_SUBTYPE_IEEE_FLOAT = { 0x00000003, 0x0000, 0x0010, { 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71 } };
-
-extern "C" SDL_AudioFormat
-WaveFormatToSDLFormat(WAVEFORMATEX *waveformat)
-{
-    if ((waveformat->wFormatTag == WAVE_FORMAT_IEEE_FLOAT) && (waveformat->wBitsPerSample == 32)) {
-        return SDL_AUDIO_F32SYS;
-    } else if ((waveformat->wFormatTag == WAVE_FORMAT_PCM) && (waveformat->wBitsPerSample == 16)) {
-        return SDL_AUDIO_S16SYS;
-    } else if ((waveformat->wFormatTag == WAVE_FORMAT_PCM) && (waveformat->wBitsPerSample == 32)) {
-        return SDL_AUDIO_S32SYS;
-    } else if (waveformat->wFormatTag == WAVE_FORMAT_EXTENSIBLE) {
-        const WAVEFORMATEXTENSIBLE *ext = (const WAVEFORMATEXTENSIBLE *)waveformat;
-        if ((SDL_memcmp(&ext->SubFormat, &SDL_KSDATAFORMAT_SUBTYPE_IEEE_FLOAT, sizeof(GUID)) == 0) && (waveformat->wBitsPerSample == 32)) {
-            return SDL_AUDIO_F32SYS;
-        } else if ((SDL_memcmp(&ext->SubFormat, &SDL_KSDATAFORMAT_SUBTYPE_PCM, sizeof(GUID)) == 0) && (waveformat->wBitsPerSample == 16)) {
-            return SDL_AUDIO_S16SYS;
-        } else if ((SDL_memcmp(&ext->SubFormat, &SDL_KSDATAFORMAT_SUBTYPE_PCM, sizeof(GUID)) == 0) && (waveformat->wBitsPerSample == 32)) {
-            return SDL_AUDIO_S32SYS;
-        }
-    }
-    return 0;
-}
-
-static void WASAPI_RemoveDevice(const SDL_bool iscapture, LPCWSTR devid)
-{
-    DevIdList *i;
-    DevIdList *next;
-    DevIdList *prev = NULL;
-    for (i = deviceid_list; i; i = next) {
-        next = i->next;
-        if (SDL_wcscmp(i->str, devid) == 0) {
-            if (prev) {
-                prev->next = next;
-            } else {
-                deviceid_list = next;
-            }
-            SDL_RemoveAudioDevice(iscapture, i->str);
-            SDL_free(i->str);
-            SDL_free(i);
-        } else {
-            prev = i;
-        }
-    }
-}
-
-static void WASAPI_AddDevice(const SDL_bool iscapture, const char *devname, WAVEFORMATEXTENSIBLE *fmt, LPCWSTR devid)
+void WASAPI_PlatformFreeDeviceHandle(SDL_AudioDevice *device)
 {
-    DevIdList *devidlist;
-    SDL_AudioSpec spec;
-
-    /* You can have multiple endpoints on a device that are mutually exclusive ("Speakers" vs "Line Out" or whatever).
-       In a perfect world, things that are unplugged won't be in this collection. The only gotcha is probably for
-       phones and tablets, where you might have an internal speaker and a headphone jack and expect both to be
-       available and switch automatically. (!!! FIXME...?) */
-
-    /* see if we already have this one. */
-    for (devidlist = deviceid_list; devidlist; devidlist = devidlist->next) {
-        if (SDL_wcscmp(devidlist->str, devid) == 0) {
-            return; /* we already have this. */
-        }
-    }
-
-    devidlist = (DevIdList *)SDL_malloc(sizeof(*devidlist));
-    if (devidlist == NULL) {
-        return; /* oh well. */
-    }
-
-    devid = SDL_wcsdup(devid);
-    if (!devid) {
-        SDL_free(devidlist);
-        return; /* oh well. */
-    }
-
-    devidlist->str = (WCHAR *)devid;
-    devidlist->next = deviceid_list;
-    deviceid_list = devidlist;
-
-    SDL_zero(spec);
-    spec.channels = (Uint8)fmt->Format.nChannels;
-    spec.freq = fmt->Format.nSamplesPerSec;
-    spec.format = WaveFormatToSDLFormat((WAVEFORMATEX *)fmt);
-    SDL_AddAudioDevice(iscapture, devname, &spec, (void *)devid);
+    SDL_free(device->handle);
 }
 
 #endif // SDL_AUDIO_DRIVER_WASAPI && defined(__WINRT__)

src/core/android/SDL_android.c

@@ -233,7 +233,7 @@ JNIEXPORT void JNICALL SDL_JAVA_AUDIO_INTERFACE(nativeSetupJNI)(
     JNIEnv *env, jclass jcls);
 
 JNIEXPORT void JNICALL
-    SDL_JAVA_AUDIO_INTERFACE(addAudioDevice)(JNIEnv *env, jclass jcls, jboolean is_capture,
+    SDL_JAVA_AUDIO_INTERFACE(addAudioDevice)(JNIEnv *env, jclass jcls, jboolean is_capture, jstring name,
                                              jint device_id);
 
 JNIEXPORT void JNICALL
@@ -242,7 +242,7 @@ JNIEXPORT void JNICALL
 
 static JNINativeMethod SDLAudioManager_tab[] = {
     { "nativeSetupJNI", "()I", SDL_JAVA_AUDIO_INTERFACE(nativeSetupJNI) },
-    { "addAudioDevice", "(ZI)V", SDL_JAVA_AUDIO_INTERFACE(addAudioDevice) },
+    { "addAudioDevice", "(ZLjava/lang/String;I)V", SDL_JAVA_AUDIO_INTERFACE(addAudioDevice) },
     { "removeAudioDevice", "(ZI)V", SDL_JAVA_AUDIO_INTERFACE(removeAudioDevice) }
 };
 
@@ -350,8 +350,8 @@ static jmethodID midSupportsRelativeMouse;
 static jclass mAudioManagerClass;
 
 /* method signatures */
-static jmethodID midGetAudioOutputDevices;
-static jmethodID midGetAudioInputDevices;
+static jmethodID midRegisterAudioDeviceCallback;
+static jmethodID midUnregisterAudioDeviceCallback;
 static jmethodID midAudioOpen;
 static jmethodID midAudioWriteByteBuffer;
 static jmethodID midAudioWriteShortBuffer;
@@ -681,12 +681,12 @@ JNIEXPORT void JNICALL SDL_JAVA_AUDIO_INTERFACE(nativeSetupJNI)(JNIEnv *env, jcl
 
     mAudioManagerClass = (jclass)((*env)->NewGlobalRef(env, cls));
 
-    midGetAudioOutputDevices = (*env)->GetStaticMethodID(env, mAudioManagerClass,
-                                                         "getAudioOutputDevices",
-                                                         "()[I");
-    midGetAudioInputDevices = (*env)->GetStaticMethodID(env, mAudioManagerClass,
-                                                        "getAudioInputDevices",
-                                                        "()[I");
+    midRegisterAudioDeviceCallback = (*env)->GetStaticMethodID(env, mAudioManagerClass,
+                                                         "registerAudioDeviceCallback",
+                                                         "()V");
+    midUnregisterAudioDeviceCallback = (*env)->GetStaticMethodID(env, mAudioManagerClass,
+                                                         "unregisterAudioDeviceCallback",
+                                                         "()V");
     midAudioOpen = (*env)->GetStaticMethodID(env, mAudioManagerClass,
                                              "audioOpen", "(IIIII)[I");
     midAudioWriteByteBuffer = (*env)->GetStaticMethodID(env, mAudioManagerClass,
@@ -710,7 +710,7 @@ JNIEXPORT void JNICALL SDL_JAVA_AUDIO_INTERFACE(nativeSetupJNI)(JNIEnv *env, jcl
     midAudioSetThreadPriority = (*env)->GetStaticMethodID(env, mAudioManagerClass,
                                                           "audioSetThreadPriority", "(ZI)V");
 
-    if (!midGetAudioOutputDevices || !midGetAudioInputDevices || !midAudioOpen ||
+    if (!midRegisterAudioDeviceCallback || !midUnregisterAudioDeviceCallback || !midAudioOpen ||
         !midAudioWriteByteBuffer || !midAudioWriteShortBuffer || !midAudioWriteFloatBuffer ||
         !midAudioClose ||
         !midCaptureOpen || !midCaptureReadByteBuffer || !midCaptureReadShortBuffer ||
@@ -1002,18 +1002,17 @@ JNIEXPORT void JNICALL SDL_JAVA_INTERFACE(nativePermissionResult)(
     SDL_AtomicSet(&bPermissionRequestPending, SDL_FALSE);
 }
 
-extern void SDL_AddAudioDevice(const SDL_bool iscapture, const char *name, SDL_AudioSpec *spec, void *handle);
-extern void SDL_RemoveAudioDevice(const SDL_bool iscapture, void *handle);
-
 JNIEXPORT void JNICALL
 SDL_JAVA_AUDIO_INTERFACE(addAudioDevice)(JNIEnv *env, jclass jcls, jboolean is_capture,
-                                         jint device_id)
+                                         jstring name, jint device_id)
 {
     if (SDL_GetCurrentAudioDriver() != NULL) {
-        char device_name[64];
-        SDL_snprintf(device_name, sizeof(device_name), "%d", device_id);
-        SDL_Log("Adding device with name %s, capture %d", device_name, is_capture);
-        SDL_AddAudioDevice(is_capture, SDL_strdup(device_name), NULL, (void *)((size_t)device_id + 1));
+        void *handle = (void *)((size_t)device_id);
+        if (!SDL_FindPhysicalAudioDeviceByHandle(handle)) {
+            const char *utf8name = (*env)->GetStringUTFChars(env, name, NULL);
+            SDL_AddAudioDevice(is_capture ? SDL_TRUE : SDL_FALSE, SDL_strdup(utf8name), NULL, handle);
+            (*env)->ReleaseStringUTFChars(env, name, utf8name);
+        }
     }
 }
 
@@ -1022,8 +1021,8 @@ SDL_JAVA_AUDIO_INTERFACE(removeAudioDevice)(JNIEnv *env, jclass jcls, jboolean i
                                             jint device_id)
 {
     if (SDL_GetCurrentAudioDriver() != NULL) {
-        SDL_Log("Removing device with handle %d, capture %d", device_id + 1, is_capture);
-        SDL_RemoveAudioDevice(is_capture, (void *)((size_t)device_id + 1));
+        SDL_Log("Removing device with handle %d, capture %d", device_id, is_capture);
+        SDL_AudioDeviceDisconnected(SDL_FindPhysicalAudioDeviceByHandle((void *)((size_t)device_id)));
     }
 }
 
@@ -1564,58 +1563,25 @@ static void *audioBufferPinned = NULL;
 static int captureBufferFormat = 0;
 static jobject captureBuffer = NULL;
 
-static void Android_JNI_GetAudioDevices(int *devices, int *length, int max_len, int is_input)
+void Android_StartAudioHotplug(SDL_AudioDevice **default_output, SDL_AudioDevice **default_capture)
 {
     JNIEnv *env = Android_JNI_GetEnv();
-    jintArray result;
-
-    if (is_input) {
-        result = (*env)->CallStaticObjectMethod(env, mAudioManagerClass, midGetAudioInputDevices);
-    } else {
-        result = (*env)->CallStaticObjectMethod(env, mAudioManagerClass, midGetAudioOutputDevices);
-    }
-
-    *length = (*env)->GetArrayLength(env, result);
-
-    *length = SDL_min(*length, max_len);
-
-    (*env)->GetIntArrayRegion(env, result, 0, *length, devices);
+    // this will fire the callback for each existing device right away (which will eventually SDL_AddAudioDevice), and again later when things change.
+    (*env)->CallStaticVoidMethod(env, mAudioManagerClass, midRegisterAudioDeviceCallback);
+    *default_output = *default_capture = NULL;  // !!! FIXME: how do you decide the default device id?
 }
 
-void Android_DetectDevices(void)
+void Android_StopAudioHotplug(void)
 {
-    int inputs[100];
-    int outputs[100];
-    int inputs_length = 0;
-    int outputs_length = 0;
-
-    SDL_zeroa(inputs);
-
-    Android_JNI_GetAudioDevices(inputs, &inputs_length, 100, 1 /* input devices */);
-
-    for (int i = 0; i < inputs_length; ++i) {
-        int device_id = inputs[i];
-        char device_name[64];
-        SDL_snprintf(device_name, sizeof(device_name), "%d", device_id);
-        SDL_Log("Adding input device with name %s", device_name);
-        SDL_AddAudioDevice(SDL_TRUE, SDL_strdup(device_name), NULL, (void *)((size_t)device_id + 1));
-    }
-
-    SDL_zeroa(outputs);
-
-    Android_JNI_GetAudioDevices(outputs, &outputs_length, 100, 0 /* output devices */);
-
-    for (int i = 0; i < outputs_length; ++i) {
-        int device_id = outputs[i];
-        char device_name[64];
-        SDL_snprintf(device_name, sizeof(device_name), "%d", device_id);
-        SDL_Log("Adding output device with name %s", device_name);
-        SDL_AddAudioDevice(SDL_FALSE, SDL_strdup(device_name), NULL, (void *)((size_t)device_id + 1));
-    }
+    JNIEnv *env = Android_JNI_GetEnv();
+    (*env)->CallStaticVoidMethod(env, mAudioManagerClass, midUnregisterAudioDeviceCallback);
 }
 
-int Android_JNI_OpenAudioDevice(int iscapture, int device_id, SDL_AudioSpec *spec)
+int Android_JNI_OpenAudioDevice(SDL_AudioDevice *device)
 {
+    const SDL_bool iscapture = device->iscapture;
+    SDL_AudioSpec *spec = &device->spec;
+    const int device_id = (int) ((size_t) device->handle);
     int audioformat;
     jobject jbufobj = NULL;
     jobject result;
@@ -1640,10 +1606,10 @@ int Android_JNI_OpenAudioDevice(int iscapture, int device_id, SDL_AudioSpec *spe
 
     if (iscapture) {
         __android_log_print(ANDROID_LOG_VERBOSE, "SDL", "SDL audio: opening device for capture");
-        result = (*env)->CallStaticObjectMethod(env, mAudioManagerClass, midCaptureOpen, spec->freq, audioformat, spec->channels, spec->samples, device_id);
+        result = (*env)->CallStaticObjectMethod(env, mAudioManagerClass, midCaptureOpen, spec->freq, audioformat, spec->channels, device->sample_frames, device_id);
     } else {
         __android_log_print(ANDROID_LOG_VERBOSE, "SDL", "SDL audio: opening device for output");
-        result = (*env)->CallStaticObjectMethod(env, mAudioManagerClass, midAudioOpen, spec->freq, audioformat, spec->channels, spec->samples, device_id);
+        result = (*env)->CallStaticObjectMethod(env, mAudioManagerClass, midAudioOpen, spec->freq, audioformat, spec->channels, device->sample_frames, device_id);
     }
     if (result == NULL) {
         /* Error during audio initialization, error printed from Java */
@@ -1668,10 +1634,10 @@ int Android_JNI_OpenAudioDevice(int iscapture, int device_id, SDL_AudioSpec *spe
         spec->format = SDL_AUDIO_F32;
         break;
     default:
-        return SDL_SetError("Unexpected audio format from Java: %d\n", audioformat);
+        return SDL_SetError("Unexpected audio format from Java: %d", audioformat);
     }
     spec->channels = resultElements[2];
-    spec->samples = resultElements[3];
+    device->sample_frames = resultElements[3];
     (*env)->ReleaseIntArrayElements(env, (jintArray)result, resultElements, JNI_ABORT);
     (*env)->DeleteLocalRef(env, result);
 
@@ -1680,7 +1646,7 @@ int Android_JNI_OpenAudioDevice(int iscapture, int device_id, SDL_AudioSpec *spe
     switch (audioformat) {
     case ENCODING_PCM_8BIT:
     {
-        jbyteArray audioBufferLocal = (*env)->NewByteArray(env, spec->samples * spec->channels);
+        jbyteArray audioBufferLocal = (*env)->NewByteArray(env, device->sample_frames * spec->channels);
         if (audioBufferLocal) {
             jbufobj = (*env)->NewGlobalRef(env, audioBufferLocal);
             (*env)->DeleteLocalRef(env, audioBufferLocal);
@@ -1688,7 +1654,7 @@ int Android_JNI_OpenAudioDevice(int iscapture, int device_id, SDL_AudioSpec *spe
     } break;
     case ENCODING_PCM_16BIT:
     {
-        jshortArray audioBufferLocal = (*env)->NewShortArray(env, spec->samples * spec->channels);
+        jshortArray audioBufferLocal = (*env)->NewShortArray(env, device->sample_frames * spec->channels);
         if (audioBufferLocal) {
             jbufobj = (*env)->NewGlobalRef(env, audioBufferLocal);
             (*env)->DeleteLocalRef(env, audioBufferLocal);
@@ -1696,7 +1662,7 @@ int Android_JNI_OpenAudioDevice(int iscapture, int device_id, SDL_AudioSpec *spe
     } break;
     case ENCODING_PCM_FLOAT:
     {
-        jfloatArray audioBufferLocal = (*env)->NewFloatArray(env, spec->samples * spec->channels);
+        jfloatArray audioBufferLocal = (*env)->NewFloatArray(env, device->sample_frames * spec->channels);
         if (audioBufferLocal) {
             jbufobj = (*env)->NewGlobalRef(env, audioBufferLocal);
             (*env)->DeleteLocalRef(env, audioBufferLocal);
@@ -1887,12 +1853,17 @@ void Android_JNI_CloseAudioDevice(const int iscapture)
     }
 }
 
-void Android_JNI_AudioSetThreadPriority(int iscapture, int device_id)
+static void Android_JNI_AudioSetThreadPriority(int iscapture, int device_id)
 {
     JNIEnv *env = Android_JNI_GetEnv();
     (*env)->CallStaticVoidMethod(env, mAudioManagerClass, midAudioSetThreadPriority, iscapture, device_id);
 }
 
+void Android_AudioThreadInit(SDL_AudioDevice *device)
+{
+    Android_JNI_AudioSetThreadPriority((int) device->iscapture, (int)device->instance_id);
+}
+
 /* Test for an exception and call SDL_SetError with its detail if one occurs */
 /* If the parameter silent is truthy then SDL_SetError() will not be called. */
 static SDL_bool Android_JNI_ExceptionOccurred(SDL_bool silent)

src/core/android/SDL_android.h

@@ -30,6 +30,8 @@ extern "C" {
 #include <EGL/eglplatform.h>
 #include <android/native_window_jni.h>
 
+#include "../../audio/SDL_sysaudio.h"
+
 /* Interface from the SDL library into the Android Java activity */
 extern void Android_JNI_SetActivityTitle(const char *title);
 extern void Android_JNI_SetWindowStyle(SDL_bool fullscreen);
@@ -47,14 +49,15 @@ extern SDL_DisplayOrientation Android_JNI_GetDisplayNaturalOrientation(void);
 extern SDL_DisplayOrientation Android_JNI_GetDisplayCurrentOrientation(void);
 
 /* Audio support */
-extern void Android_DetectDevices(void);
-extern int Android_JNI_OpenAudioDevice(int iscapture, int device_id, SDL_AudioSpec *spec);
+void Android_StartAudioHotplug(SDL_AudioDevice **default_output, SDL_AudioDevice **default_capture);
+void Android_StopAudioHotplug(void);
+extern void Android_AudioThreadInit(SDL_AudioDevice *device);
+extern int Android_JNI_OpenAudioDevice(SDL_AudioDevice *device);
 extern void *Android_JNI_GetAudioBuffer(void);
 extern void Android_JNI_WriteAudioBuffer(void);
 extern int Android_JNI_CaptureAudioBuffer(void *buffer, int buflen);
 extern void Android_JNI_FlushCapturedAudio(void);
 extern void Android_JNI_CloseAudioDevice(const int iscapture);
-extern void Android_JNI_AudioSetThreadPriority(int iscapture, int device_id);
 
 /* Detecting device type */
 extern SDL_bool Android_IsDeXMode(void);

src/core/windows/SDL_immdevice.c

@@ -27,6 +27,12 @@
 #include "../../audio/SDL_sysaudio.h"
 #include <objbase.h> /* For CLSIDFromString */
 
+typedef struct SDL_IMMDevice_HandleData
+{
+    LPWSTR immdevice_id;
+    GUID directsound_guid;
+} SDL_IMMDevice_HandleData;
+
 static const ERole SDL_IMMDevice_role = eConsole; /* !!! FIXME: should this be eMultimedia? Should be a hint? */
 
 /* This is global to the WASAPI target, to handle hotplug and default device lookup. */
@@ -47,13 +53,28 @@ static const IID SDL_IID_IMMEndpoint = { 0x1be09788, 0x6894, 0x4089,{ 0x85, 0x86
 static const PROPERTYKEY SDL_PKEY_Device_FriendlyName = { { 0xa45c254e, 0xdf1c, 0x4efd,{ 0x80, 0x20, 0x67, 0xd1, 0x46, 0xa8, 0x50, 0xe0, } }, 14 };
 static const PROPERTYKEY SDL_PKEY_AudioEngine_DeviceFormat = { { 0xf19f064d, 0x82c, 0x4e27,{ 0xbc, 0x73, 0x68, 0x82, 0xa1, 0xbb, 0x8e, 0x4c, } }, 0 };
 static const PROPERTYKEY SDL_PKEY_AudioEndpoint_GUID = { { 0x1da5d803, 0xd492, 0x4edd,{ 0x8c, 0x23, 0xe0, 0xc0, 0xff, 0xee, 0x7f, 0x0e, } }, 4 };
-static const GUID SDL_KSDATAFORMAT_SUBTYPE_PCM = { 0x00000001, 0x0000, 0x0010,{ 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71 } };
-static const GUID SDL_KSDATAFORMAT_SUBTYPE_IEEE_FLOAT = { 0x00000003, 0x0000, 0x0010,{ 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71 } };
 /* *INDENT-ON* */ /* clang-format on */
 
-/* these increment as default devices change. Opened default devices pick up changes in their threads. */
-SDL_AtomicInt SDL_IMMDevice_DefaultPlaybackGeneration;
-SDL_AtomicInt SDL_IMMDevice_DefaultCaptureGeneration;
+static SDL_bool FindByDevIDCallback(SDL_AudioDevice *device, void *userdata)
+{
+    const SDL_IMMDevice_HandleData *handle = (const SDL_IMMDevice_HandleData *) device->handle;
+    return (SDL_wcscmp(handle->immdevice_id, (LPCWSTR) userdata) == 0) ? SDL_TRUE : SDL_FALSE;
+}
+
+static SDL_AudioDevice *SDL_IMMDevice_FindByDevID(LPCWSTR devid)
+{
+    return SDL_FindPhysicalAudioDeviceByCallback(FindByDevIDCallback, (void *) devid);
+}
+
+LPGUID SDL_IMMDevice_GetDirectSoundGUID(SDL_AudioDevice *device)
+{
+    return (device && device->handle) ? &(((SDL_IMMDevice_HandleData *) device->handle)->directsound_guid) : NULL;
+}
+
+LPCWSTR SDL_IMMDevice_GetDevID(SDL_AudioDevice *device)
+{
+    return (device && device->handle) ? ((const SDL_IMMDevice_HandleData *) device->handle)->immdevice_id : NULL;
+}
 
 static void GetMMDeviceInfo(IMMDevice *device, char **utf8dev, WAVEFORMATEXTENSIBLE *fmt, GUID *guid)
 {
@@ -82,94 +103,54 @@ static void GetMMDeviceInfo(IMMDevice *device, char **utf8dev, WAVEFORMATEXTENSI
     }
 }
 
-/* This is a list of device id strings we have inflight, so we have consistent pointers to the same device. */
-typedef struct DevIdList
-{
-    LPWSTR str;
-    LPGUID guid;
-    struct DevIdList *next;
-} DevIdList;
-
-static DevIdList *deviceid_list = NULL;
-
-static void SDL_IMMDevice_Remove(const SDL_bool iscapture, LPCWSTR devid, SDL_bool useguid)
+void SDL_IMMDevice_FreeDeviceHandle(SDL_AudioDevice *device)
 {
-    DevIdList *i;
-    DevIdList *next;
-    DevIdList *prev = NULL;
-    for (i = deviceid_list; i; i = next) {
-        next = i->next;
-        if (SDL_wcscmp(i->str, devid) == 0) {
-            if (prev) {
-                prev->next = next;
-            } else {
-                deviceid_list = next;
-            }
-            SDL_RemoveAudioDevice(iscapture, useguid ? ((void *)i->guid) : ((void *)i->str));
-            SDL_free(i->str);
-            SDL_free(i);
-        } else {
-            prev = i;
-        }
+    if (device && device->handle) {
+        SDL_IMMDevice_HandleData *handle = (SDL_IMMDevice_HandleData *) device->handle;
+        SDL_free(handle->immdevice_id);
+        SDL_free(handle);
+        device->handle = NULL;
     }
 }
 
-static void SDL_IMMDevice_Add(const SDL_bool iscapture, const char *devname, WAVEFORMATEXTENSIBLE *fmt, LPCWSTR devid, GUID *dsoundguid, SDL_bool useguid)
+static SDL_AudioDevice *SDL_IMMDevice_Add(const SDL_bool iscapture, const char *devname, WAVEFORMATEXTENSIBLE *fmt, LPCWSTR devid, GUID *dsoundguid)
 {
-    DevIdList *devidlist;
-    SDL_AudioSpec spec;
-    LPWSTR devidcopy;
-    LPGUID cpyguid;
-    LPVOID driverdata;
-
     /* You can have multiple endpoints on a device that are mutually exclusive ("Speakers" vs "Line Out" or whatever).
        In a perfect world, things that are unplugged won't be in this collection. The only gotcha is probably for
        phones and tablets, where you might have an internal speaker and a headphone jack and expect both to be
        available and switch automatically. (!!! FIXME...?) */
 
-    /* see if we already have this one. */
-    for (devidlist = deviceid_list; devidlist; devidlist = devidlist->next) {
-        if (SDL_wcscmp(devidlist->str, devid) == 0) {
-            return; /* we already have this. */
-        }
+    if (!devname) {
+        return NULL;
     }
 
-    devidlist = (DevIdList *)SDL_malloc(sizeof(*devidlist));
-    if (devidlist == NULL) {
-        return; /* oh well. */
-    }
+    // see if we already have this one first.
+    SDL_AudioDevice *device = SDL_IMMDevice_FindByDevID(devid);
+    if (!device) {
+        // handle is freed by SDL_IMMDevice_FreeDeviceHandle!
+        SDL_IMMDevice_HandleData *handle = SDL_malloc(sizeof(SDL_IMMDevice_HandleData));
+        if (!handle) {
+            SDL_OutOfMemory();
+            return NULL;
+        }
+        handle->immdevice_id = SDL_wcsdup(devid);
+        if (!handle->immdevice_id) {
+            SDL_OutOfMemory();
+            SDL_free(handle);
+            return NULL;
+        }
+        SDL_memcpy(&handle->directsound_guid, dsoundguid, sizeof(GUID));
 
-    devidcopy = SDL_wcsdup(devid);
-    if (!devidcopy) {
-        SDL_free(devidlist);
-        return; /* oh well. */
-    }
+        SDL_AudioSpec spec;
+        SDL_zero(spec);
+        spec.channels = (Uint8)fmt->Format.nChannels;
+        spec.freq = fmt->Format.nSamplesPerSec;
+        spec.format = SDL_WaveFormatExToSDLFormat((WAVEFORMATEX *)fmt);
 
-    if (useguid) {
-        /* This is freed by DSOUND_FreeDeviceData! */
-        cpyguid = (LPGUID)SDL_malloc(sizeof(GUID));
-        if (!cpyguid) {
-            SDL_free(devidlist);
-            SDL_free(devidcopy);
-            return; /* oh well. */
-        }
-        SDL_memcpy(cpyguid, dsoundguid, sizeof(GUID));
-        driverdata = cpyguid;
-    } else {
-        cpyguid = NULL;
-        driverdata = devidcopy;
+        device = SDL_AddAudioDevice(iscapture, devname, &spec, handle);
     }
 
-    devidlist->str = devidcopy;
-    devidlist->guid = cpyguid;
-    devidlist->next = deviceid_list;
-    deviceid_list = devidlist;
-
-    SDL_zero(spec);
-    spec.channels = (Uint8)fmt->Format.nChannels;
-    spec.freq = fmt->Format.nSamplesPerSec;
-    spec.format = WaveFormatToSDLFormat((WAVEFORMATEX *)fmt);
-    SDL_AddAudioDevice(iscapture, devname, &spec, driverdata);
+    return device;
 }
 
 /* We need a COM subclass of IMMNotificationClient for hotplug support, which is
@@ -181,14 +162,13 @@ typedef struct SDLMMNotificationClient
 {
     const IMMNotificationClientVtbl *lpVtbl;
     SDL_AtomicInt refcount;
-    SDL_bool useguid;
 } SDLMMNotificationClient;
 
-static HRESULT STDMETHODCALLTYPE SDLMMNotificationClient_QueryInterface(IMMNotificationClient *this, REFIID iid, void **ppv)
+static HRESULT STDMETHODCALLTYPE SDLMMNotificationClient_QueryInterface(IMMNotificationClient *client, REFIID iid, void **ppv)
 {
     if ((WIN_IsEqualIID(iid, &IID_IUnknown)) || (WIN_IsEqualIID(iid, &SDL_IID_IMMNotificationClient))) {
-        *ppv = this;
-        this->lpVtbl->AddRef(this);
+        *ppv = client;
+        client->lpVtbl->AddRef(client);
         return S_OK;
     }
 
@@ -196,55 +176,34 @@ static HRESULT STDMETHODCALLTYPE SDLMMNotificationClient_QueryInterface(IMMNotif
     return E_NOINTERFACE;
 }
 
-static ULONG STDMETHODCALLTYPE SDLMMNotificationClient_AddRef(IMMNotificationClient *ithis)
+static ULONG STDMETHODCALLTYPE SDLMMNotificationClient_AddRef(IMMNotificationClient *iclient)
 {
-    SDLMMNotificationClient *this = (SDLMMNotificationClient *)ithis;
-    return (ULONG)(SDL_AtomicIncRef(&this->refcount) + 1);
+    SDLMMNotificationClient *client = (SDLMMNotificationClient *)iclient;
+    return (ULONG)(SDL_AtomicIncRef(&client->refcount) + 1);
 }
 
-static ULONG STDMETHODCALLTYPE SDLMMNotificationClient_Release(IMMNotificationClient *ithis)
+static ULONG STDMETHODCALLTYPE SDLMMNotificationClient_Release(IMMNotificationClient *iclient)
 {
-    /* this is a static object; we don't ever free it. */
-    SDLMMNotificationClient *this = (SDLMMNotificationClient *)ithis;
-    const ULONG retval = SDL_AtomicDecRef(&this->refcount);
+    /* client is a static object; we don't ever free it. */
+    SDLMMNotificationClient *client = (SDLMMNotificationClient *)iclient;
+    const ULONG retval = SDL_AtomicDecRef(&client->refcount);
     if (retval == 0) {
-        SDL_AtomicSet(&this->refcount, 0); /* uhh... */
+        SDL_AtomicSet(&client->refcount, 0); /* uhh... */
         return 0;
     }
     return retval - 1;
 }
 
-/* These are the entry points called when WASAPI device endpoints change. */
-static HRESULT STDMETHODCALLTYPE SDLMMNotificationClient_OnDefaultDeviceChanged(IMMNotificationClient *ithis, EDataFlow flow, ERole role, LPCWSTR pwstrDeviceId)
+// These are the entry points called when WASAPI device endpoints change.
+static HRESULT STDMETHODCALLTYPE SDLMMNotificationClient_OnDefaultDeviceChanged(IMMNotificationClient *iclient, EDataFlow flow, ERole role, LPCWSTR pwstrDeviceId)
 {
-    if (role != SDL_IMMDevice_role) {
-        return S_OK; /* ignore it. */
-    }
-
-    /* Increment the "generation," so opened devices will pick this up in their threads. */
-    switch (flow) {
-    case eRender:
-        SDL_AtomicAdd(&SDL_IMMDevice_DefaultPlaybackGeneration, 1);
-        break;
-
-    case eCapture:
-        SDL_AtomicAdd(&SDL_IMMDevice_DefaultCaptureGeneration, 1);
-        break;
-
-    case eAll:
-        SDL_AtomicAdd(&SDL_IMMDevice_DefaultPlaybackGeneration, 1);
-        SDL_AtomicAdd(&SDL_IMMDevice_DefaultCaptureGeneration, 1);
-        break;
-
-    default:
-        SDL_assert(!"uhoh, unexpected OnDefaultDeviceChange flow!");
-        break;
+    if (role == SDL_IMMDevice_role) {
+        SDL_DefaultAudioDeviceChanged(SDL_IMMDevice_FindByDevID(pwstrDeviceId));
     }
-
     return S_OK;
 }
 
-static HRESULT STDMETHODCALLTYPE SDLMMNotificationClient_OnDeviceAdded(IMMNotificationClient *ithis, LPCWSTR pwstrDeviceId)
+static HRESULT STDMETHODCALLTYPE SDLMMNotificationClient_OnDeviceAdded(IMMNotificationClient *iclient, LPCWSTR pwstrDeviceId)
 {
     /* we ignore this; devices added here then progress to ACTIVE, if appropriate, in
        OnDeviceStateChange, making that a better place to deal with device adds. More
@@ -254,13 +213,12 @@ static HRESULT STDMETHODCALLTYPE SDLMMNotificationClient_OnDeviceAdded(IMMNotifi
     return S_OK;
 }
 
-static HRESULT STDMETHODCALLTYPE SDLMMNotificationClient_OnDeviceRemoved(IMMNotificationClient *ithis, LPCWSTR pwstrDeviceId)
+static HRESULT STDMETHODCALLTYPE SDLMMNotificationClient_OnDeviceRemoved(IMMNotificationClient *iclient, LPCWSTR pwstrDeviceId)
 {
-    /* See notes in OnDeviceAdded handler about why we ignore this. */
-    return S_OK;
+    return S_OK;  // See notes in OnDeviceAdded handler about why we ignore this.
 }
 
-static HRESULT STDMETHODCALLTYPE SDLMMNotificationClient_OnDeviceStateChanged(IMMNotificationClient *ithis, LPCWSTR pwstrDeviceId, DWORD dwNewState)
+static HRESULT STDMETHODCALLTYPE SDLMMNotificationClient_OnDeviceStateChanged(IMMNotificationClient *iclient, LPCWSTR pwstrDeviceId, DWORD dwNewState)
 {
     IMMDevice *device = NULL;
 
@@ -270,18 +228,17 @@ static HRESULT STDMETHODCALLTYPE SDLMMNotificationClient_OnDeviceStateChanged(IM
             EDataFlow flow;
             if (SUCCEEDED(IMMEndpoint_GetDataFlow(endpoint, &flow))) {
                 const SDL_bool iscapture = (flow == eCapture);
-                const SDLMMNotificationClient *client = (SDLMMNotificationClient *)ithis;
                 if (dwNewState == DEVICE_STATE_ACTIVE) {
                     char *utf8dev;
                     WAVEFORMATEXTENSIBLE fmt;
                     GUID dsoundguid;
                     GetMMDeviceInfo(device, &utf8dev, &fmt, &dsoundguid);
                     if (utf8dev) {
-                        SDL_IMMDevice_Add(iscapture, utf8dev, &fmt, pwstrDeviceId, &dsoundguid, client->useguid);
+                        SDL_IMMDevice_Add(iscapture, utf8dev, &fmt, pwstrDeviceId, &dsoundguid);
                         SDL_free(utf8dev);
                     }
                 } else {
-                    SDL_IMMDevice_Remove(iscapture, pwstrDeviceId, client->useguid);
+                    SDL_AudioDeviceDisconnected(SDL_IMMDevice_FindByDevID(pwstrDeviceId));
                 }
             }
             IMMEndpoint_Release(endpoint);
@@ -292,9 +249,9 @@ static HRESULT STDMETHODCALLTYPE SDLMMNotificationClient_OnDeviceStateChanged(IM
     return S_OK;
 }
 
-static HRESULT STDMETHODCALLTYPE SDLMMNotificationClient_OnPropertyValueChanged(IMMNotificationClient *this, LPCWSTR pwstrDeviceId, const PROPERTYKEY key)
+static HRESULT STDMETHODCALLTYPE SDLMMNotificationClient_OnPropertyValueChanged(IMMNotificationClient *client, LPCWSTR pwstrDeviceId, const PROPERTYKEY key)
 {
-    return S_OK; /* we don't care about these. */
+    return S_OK; // we don't care about these.
 }
 
 static const IMMNotificationClientVtbl notification_client_vtbl = {
@@ -314,31 +271,25 @@ int SDL_IMMDevice_Init(void)
 {
     HRESULT ret;
 
-    SDL_AtomicSet(&SDL_IMMDevice_DefaultPlaybackGeneration, 1);
-    SDL_AtomicSet(&SDL_IMMDevice_DefaultCaptureGeneration, 1);
-
     /* just skip the discussion with COM here. */
     if (!WIN_IsWindowsVistaOrGreater()) {
-        return SDL_SetError("WASAPI support requires Windows Vista or later");
+        return SDL_SetError("IMMDevice support requires Windows Vista or later");
     }
 
     if (FAILED(WIN_CoInitialize())) {
-        return SDL_SetError("WASAPI: CoInitialize() failed");
+        return SDL_SetError("IMMDevice: CoInitialize() failed");
     }
 
     ret = CoCreateInstance(&SDL_CLSID_MMDeviceEnumerator, NULL, CLSCTX_INPROC_SERVER, &SDL_IID_IMMDeviceEnumerator, (LPVOID *)&enumerator);
     if (FAILED(ret)) {
         WIN_CoUninitialize();
-        return WIN_SetErrorFromHRESULT("WASAPI CoCreateInstance(MMDeviceEnumerator)", ret);
+        return WIN_SetErrorFromHRESULT("IMMDevice CoCreateInstance(MMDeviceEnumerator)", ret);
     }
     return 0;
 }
 
 void SDL_IMMDevice_Quit(void)
 {
-    DevIdList *devidlist;
-    DevIdList *next;
-
     if (enumerator) {
         IMMDeviceEnumerator_UnregisterEndpointNotificationCallback(enumerator, (IMMNotificationClient *)&notification_client);
         IMMDeviceEnumerator_Release(enumerator);
@@ -346,197 +297,99 @@ void SDL_IMMDevice_Quit(void)
     }
 
     WIN_CoUninitialize();
-
-    for (devidlist = deviceid_list; devidlist; devidlist = next) {
-        next = devidlist->next;
-        SDL_free(devidlist->str);
-        SDL_free(devidlist);
-    }
-    deviceid_list = NULL;
 }
 
-int SDL_IMMDevice_Get(LPCWSTR devid, IMMDevice **device, SDL_bool iscapture)
+int SDL_IMMDevice_Get(SDL_AudioDevice *device, IMMDevice **immdevice, SDL_bool iscapture)
 {
     const Uint64 timeout = SDL_GetTicks() + 8000;  /* intel's audio drivers can fail for up to EIGHT SECONDS after a device is connected or we wake from sleep. */
-    HRESULT ret;
 
     SDL_assert(device != NULL);
+    SDL_assert(immdevice != NULL);
 
-    while (SDL_TRUE) {
-        if (devid == NULL) {
-            const EDataFlow dataflow = iscapture ? eCapture : eRender;
-            ret = IMMDeviceEnumerator_GetDefaultAudioEndpoint(enumerator, dataflow, SDL_IMMDevice_role, device);
-        } else {
-            ret = IMMDeviceEnumerator_GetDevice(enumerator, devid, device);
-        }
+    LPCWSTR devid = SDL_IMMDevice_GetDevID(device);
+    SDL_assert(devid != NULL);
 
-        if (SUCCEEDED(ret)) {
-            break;
-        }
-
-        if (ret == E_NOTFOUND) {
-            const Uint64 now = SDL_GetTicks();
-            if (timeout > now) {
-                const Uint64 ticksleft = timeout - now;
-                SDL_Delay((Uint32)SDL_min(ticksleft, 300));   /* wait awhile and try again. */
-                continue;
-            }
+    HRESULT ret;
+    while ((ret = IMMDeviceEnumerator_GetDevice(enumerator, devid, immdevice)) == E_NOTFOUND) {
+        const Uint64 now = SDL_GetTicks();
+        if (timeout > now) {
+            const Uint64 ticksleft = timeout - now;
+            SDL_Delay((Uint32)SDL_min(ticksleft, 300));   /* wait awhile and try again. */
+            continue;
         }
-
-        return WIN_SetErrorFromHRESULT("WASAPI can't find requested audio endpoint", ret);
+        break;
     }
-    return 0;
-}
-
-typedef struct
-{
-    LPWSTR devid;
-    char *devname;
-    WAVEFORMATEXTENSIBLE fmt;
-    GUID dsoundguid;
-} EndpointItem;
 
-static int SDLCALL sort_endpoints(const void *_a, const void *_b)
-{
-    LPWSTR a = ((const EndpointItem *)_a)->devid;
-    LPWSTR b = ((const EndpointItem *)_b)->devid;
-    if (!a && !b) {
-        return 0;
-    } else if (!a && b) {
-        return -1;
-    } else if (a && !b) {
-        return 1;
-    }
+    return SUCCEEDED(ret) ? 0 : WIN_SetErrorFromHRESULT("WASAPI can't find requested audio endpoint", ret);
 
-    while (SDL_TRUE) {
-        if (*a < *b) {
-            return -1;
-        } else if (*a > *b) {
-            return 1;
-        } else if (*a == 0) {
-            break;
-        }
-        a++;
-        b++;
-    }
-
-    return 0;
 }
 
-static void EnumerateEndpointsForFlow(const SDL_bool iscapture)
+static void EnumerateEndpointsForFlow(const SDL_bool iscapture, SDL_AudioDevice **default_device)
 {
-    IMMDeviceCollection *collection = NULL;
-    EndpointItem *items;
-    UINT i, total;
-
     /* Note that WASAPI separates "adapter devices" from "audio endpoint devices"
        ...one adapter device ("SoundBlaster Pro") might have multiple endpoint devices ("Speakers", "Line-Out"). */
 
+    IMMDeviceCollection *collection = NULL;
     if (FAILED(IMMDeviceEnumerator_EnumAudioEndpoints(enumerator, iscapture ? eCapture : eRender, DEVICE_STATE_ACTIVE, &collection))) {
         return;
     }
 
+    UINT total = 0;
     if (FAILED(IMMDeviceCollection_GetCount(collection, &total))) {
         IMMDeviceCollection_Release(collection);
         return;
     }
 
-    items = (EndpointItem *)SDL_calloc(total, sizeof(EndpointItem));
-    if (items == NULL) {
-        return; /* oh well. */
-    }
-
-    for (i = 0; i < total; i++) {
-        EndpointItem *item = items + i;
-        IMMDevice *device = NULL;
-        if (SUCCEEDED(IMMDeviceCollection_Item(collection, i, &device))) {
-            if (SUCCEEDED(IMMDevice_GetId(device, &item->devid))) {
-                GetMMDeviceInfo(device, &item->devname, &item->fmt, &item->dsoundguid);
+    LPWSTR default_devid = NULL;
+    if (default_device) {
+        IMMDevice *default_immdevice = NULL;
+        const EDataFlow dataflow = iscapture ? eCapture : eRender;
+        if (SUCCEEDED(IMMDeviceEnumerator_GetDefaultAudioEndpoint(enumerator, dataflow, SDL_IMMDevice_role, &default_immdevice))) {
+            LPWSTR devid = NULL;
+            if (SUCCEEDED(IMMDevice_GetId(default_immdevice, &devid))) {
+                default_devid = SDL_wcsdup(devid);  // if this fails, oh well.
+                CoTaskMemFree(devid);
             }
-            IMMDevice_Release(device);
+            IMMDevice_Release(default_immdevice);
         }
     }
 
-    /* sort the list of devices by their guid so list is consistent between runs */
-    SDL_qsort(items, total, sizeof(*items), sort_endpoints);
-
-    /* Send the sorted list on to the SDL's higher level. */
-    for (i = 0; i < total; i++) {
-        EndpointItem *item = items + i;
-        if ((item->devid) && (item->devname)) {
-            SDL_IMMDevice_Add(iscapture, item->devname, &item->fmt, item->devid, &item->dsoundguid, notification_client.useguid);
+    for (UINT i = 0; i < total; i++) {
+        IMMDevice *immdevice = NULL;
+        if (SUCCEEDED(IMMDeviceCollection_Item(collection, i, &immdevice))) {
+            LPWSTR devid = NULL;
+            if (SUCCEEDED(IMMDevice_GetId(immdevice, &devid))) {
+                char *devname = NULL;
+                WAVEFORMATEXTENSIBLE fmt;
+                GUID dsoundguid;
+                SDL_zero(fmt);
+                SDL_zero(dsoundguid);
+                GetMMDeviceInfo(immdevice, &devname, &fmt, &dsoundguid);
+                if (devname) {
+                    SDL_AudioDevice *sdldevice = SDL_IMMDevice_Add(iscapture, devname, &fmt, devid, &dsoundguid);
+                    if (default_device && default_devid && SDL_wcscmp(default_devid, devid) == 0) {
+                        *default_device = sdldevice;
+                    }
+                    SDL_free(devname);
+                }
+                CoTaskMemFree(devid);
+            }
+            IMMDevice_Release(immdevice);
         }
-        SDL_free(item->devname);
-        CoTaskMemFree(item->devid);
     }
 
-    SDL_free(items);
+    SDL_free(default_devid);
+
     IMMDeviceCollection_Release(collection);
 }
 
-void SDL_IMMDevice_EnumerateEndpoints(SDL_bool useguid)
+void SDL_IMMDevice_EnumerateEndpoints(SDL_AudioDevice **default_output, SDL_AudioDevice **default_capture)
 {
-    notification_client.useguid = useguid;
-
-    EnumerateEndpointsForFlow(SDL_FALSE); /* playback */
-    EnumerateEndpointsForFlow(SDL_TRUE);  /* capture */
+    EnumerateEndpointsForFlow(SDL_FALSE, default_output); /* playback */
+    EnumerateEndpointsForFlow(SDL_TRUE, default_capture);  /* capture */
 
     /* if this fails, we just won't get hotplug events. Carry on anyhow. */
     IMMDeviceEnumerator_RegisterEndpointNotificationCallback(enumerator, (IMMNotificationClient *)&notification_client);
 }
 
-int SDL_IMMDevice_GetDefaultAudioInfo(char **name, SDL_AudioSpec *spec, int iscapture)
-{
-    WAVEFORMATEXTENSIBLE fmt;
-    IMMDevice *device = NULL;
-    char *filler;
-    GUID morefiller;
-    const EDataFlow dataflow = iscapture ? eCapture : eRender;
-    HRESULT ret = IMMDeviceEnumerator_GetDefaultAudioEndpoint(enumerator, dataflow, SDL_IMMDevice_role, &device);
-
-    if (FAILED(ret)) {
-        SDL_assert(device == NULL);
-        return WIN_SetErrorFromHRESULT("WASAPI can't find default audio endpoint", ret);
-    }
-
-    if (name == NULL) {
-        name = &filler;
-    }
-
-    SDL_zero(fmt);
-    GetMMDeviceInfo(device, name, &fmt, &morefiller);
-    IMMDevice_Release(device);
-
-    if (name == &filler) {
-        SDL_free(filler);
-    }
-
-    SDL_zerop(spec);
-    spec->channels = (Uint8)fmt.Format.nChannels;
-    spec->freq = fmt.Format.nSamplesPerSec;
-    spec->format = WaveFormatToSDLFormat((WAVEFORMATEX *)&fmt);
-    return 0;
-}
-
-SDL_AudioFormat WaveFormatToSDLFormat(WAVEFORMATEX *waveformat)
-{
-    if ((waveformat->wFormatTag == WAVE_FORMAT_IEEE_FLOAT) && (waveformat->wBitsPerSample == 32)) {
-        return SDL_AUDIO_F32SYS;
-    } else if ((waveformat->wFormatTag == WAVE_FORMAT_PCM) && (waveformat->wBitsPerSample == 16)) {
-        return SDL_AUDIO_S16SYS;
-    } else if ((waveformat->wFormatTag == WAVE_FORMAT_PCM) && (waveformat->wBitsPerSample == 32)) {
-        return SDL_AUDIO_S32SYS;
-    } else if (waveformat->wFormatTag == WAVE_FORMAT_EXTENSIBLE) {
-        const WAVEFORMATEXTENSIBLE *ext = (const WAVEFORMATEXTENSIBLE *)waveformat;
-        if ((SDL_memcmp(&ext->SubFormat, &SDL_KSDATAFORMAT_SUBTYPE_IEEE_FLOAT, sizeof(GUID)) == 0) && (waveformat->wBitsPerSample == 32)) {
-            return SDL_AUDIO_F32SYS;
-        } else if ((SDL_memcmp(&ext->SubFormat, &SDL_KSDATAFORMAT_SUBTYPE_PCM, sizeof(GUID)) == 0) && (waveformat->wBitsPerSample == 16)) {
-            return SDL_AUDIO_S16SYS;
-        } else if ((SDL_memcmp(&ext->SubFormat, &SDL_KSDATAFORMAT_SUBTYPE_PCM, sizeof(GUID)) == 0) && (waveformat->wBitsPerSample == 32)) {
-            return SDL_AUDIO_S32SYS;
-        }
-    }
-    return 0;
-}
-
 #endif /* (defined(__WIN32__) || defined(__GDK__)) && defined(HAVE_MMDEVICEAPI_H) */

src/core/windows/SDL_immdevice.h

@@ -26,16 +26,14 @@
 #include <mmdeviceapi.h>
 #include <mmreg.h>
 
+typedef struct SDL_AudioDevice SDL_AudioDevice; // this is defined in src/audio/SDL_sysaudio.h
+
 int SDL_IMMDevice_Init(void);
 void SDL_IMMDevice_Quit(void);
-int SDL_IMMDevice_Get(LPCWSTR devid, IMMDevice **device, SDL_bool iscapture);
-void SDL_IMMDevice_EnumerateEndpoints(SDL_bool useguid);
-int SDL_IMMDevice_GetDefaultAudioInfo(char **name, SDL_AudioSpec *spec, int iscapture);
-
-SDL_AudioFormat WaveFormatToSDLFormat(WAVEFORMATEX *waveformat);
-
-/* these increment as default devices change. Opened default devices pick up changes in their threads. */
-extern SDL_AtomicInt SDL_IMMDevice_DefaultPlaybackGeneration;
-extern SDL_AtomicInt SDL_IMMDevice_DefaultCaptureGeneration;
+int SDL_IMMDevice_Get(SDL_AudioDevice *device, IMMDevice **immdevice, SDL_bool iscapture);
+void SDL_IMMDevice_EnumerateEndpoints(SDL_AudioDevice **default_output, SDL_AudioDevice **default_capture);
+LPGUID SDL_IMMDevice_GetDirectSoundGUID(SDL_AudioDevice *device);
+LPCWSTR SDL_IMMDevice_GetDevID(SDL_AudioDevice *device);
+void SDL_IMMDevice_FreeDeviceHandle(SDL_AudioDevice *device);
 
 #endif /* SDL_IMMDEVICE_H */

src/core/windows/SDL_windows.c

@@ -335,6 +335,33 @@ BOOL WIN_IsRectEmpty(const RECT *rect)
     return (rect->right <= rect->left) || (rect->bottom <= rect->top);
 }
 
+/* Some GUIDs we need to know without linking to libraries that aren't available before Vista. */
+/* *INDENT-OFF* */ /* clang-format off */
+static const GUID SDL_KSDATAFORMAT_SUBTYPE_PCM = { 0x00000001, 0x0000, 0x0010,{ 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71 } };
+static const GUID SDL_KSDATAFORMAT_SUBTYPE_IEEE_FLOAT = { 0x00000003, 0x0000, 0x0010,{ 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71 } };
+/* *INDENT-ON* */ /* clang-format on */
+
+SDL_AudioFormat SDL_WaveFormatExToSDLFormat(WAVEFORMATEX *waveformat)
+{
+    if ((waveformat->wFormatTag == WAVE_FORMAT_IEEE_FLOAT) && (waveformat->wBitsPerSample == 32)) {
+        return SDL_AUDIO_F32SYS;
+    } else if ((waveformat->wFormatTag == WAVE_FORMAT_PCM) && (waveformat->wBitsPerSample == 16)) {
+        return SDL_AUDIO_S16SYS;
+    } else if ((waveformat->wFormatTag == WAVE_FORMAT_PCM) && (waveformat->wBitsPerSample == 32)) {
+        return SDL_AUDIO_S32SYS;
+    } else if (waveformat->wFormatTag == WAVE_FORMAT_EXTENSIBLE) {
+        const WAVEFORMATEXTENSIBLE *ext = (const WAVEFORMATEXTENSIBLE *)waveformat;
+        if ((SDL_memcmp(&ext->SubFormat, &SDL_KSDATAFORMAT_SUBTYPE_IEEE_FLOAT, sizeof(GUID)) == 0) && (waveformat->wBitsPerSample == 32)) {
+            return SDL_AUDIO_F32SYS;
+        } else if ((SDL_memcmp(&ext->SubFormat, &SDL_KSDATAFORMAT_SUBTYPE_PCM, sizeof(GUID)) == 0) && (waveformat->wBitsPerSample == 16)) {
+            return SDL_AUDIO_S16SYS;
+        } else if ((SDL_memcmp(&ext->SubFormat, &SDL_KSDATAFORMAT_SUBTYPE_PCM, sizeof(GUID)) == 0) && (waveformat->wBitsPerSample == 32)) {
+            return SDL_AUDIO_S32SYS;
+        }
+    }
+    return 0;
+}
+
 /* Win32-specific SDL_RunApp(), which does most of the SDL_main work,
   based on SDL_windows_main.c, placed in the public domain by Sam Lantinga  4/13/98 */
 #ifdef __WIN32__

src/core/windows/SDL_windows.h

@@ -78,6 +78,7 @@
 
 #include <windows.h>
 #include <basetyps.h> /* for REFIID with broken mingw.org headers */
+#include <mmreg.h>
 
 /* Older Visual C++ headers don't have the Win64-compatible typedefs... */
 #if defined(_MSC_VER) && (_MSC_VER <= 1200)
@@ -154,6 +155,8 @@ extern void WIN_RectToRECT(const SDL_Rect *sdlrect, RECT *winrect);
 /* Returns SDL_TRUE if the rect is empty */
 extern BOOL WIN_IsRectEmpty(const RECT *rect);
 
+extern SDL_AudioFormat SDL_WaveFormatExToSDLFormat(WAVEFORMATEX *waveformat);
+
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
 }

src/dynapi/SDL_dynapi.sym

@@ -35,22 +35,17 @@ SDL3_0.0.0 {
     SDL_BroadcastCondition;
     SDL_CaptureMouse;
     SDL_CleanupTLS;
-    SDL_ClearAudioStream;
     SDL_ClearComposition;
     SDL_ClearError;
     SDL_ClearHints;
-    SDL_ClearQueuedAudio;
-    SDL_CloseAudioDevice;
     SDL_CloseGamepad;
     SDL_CloseJoystick;
     SDL_CloseSensor;
     SDL_ComposeCustomBlendMode;
-    SDL_ConvertAudioSamples;
     SDL_ConvertEventToRenderCoordinates;
     SDL_ConvertPixels;
     SDL_ConvertSurface;
     SDL_ConvertSurfaceFormat;
-    SDL_CreateAudioStream;
     SDL_CreateColorCursor;
     SDL_CreateCondition;
     SDL_CreateCursor;
@@ -82,8 +77,6 @@ SDL3_0.0.0 {
     SDL_DelHintCallback;
     SDL_Delay;
     SDL_DelayNS;
-    SDL_DequeueAudio;
-    SDL_DestroyAudioStream;
     SDL_DestroyCondition;
     SDL_DestroyCursor;
     SDL_DestroyMutex;
@@ -114,7 +107,6 @@ SDL3_0.0.0 {
     SDL_FillSurfaceRects;
     SDL_FilterEvents;
     SDL_FlashWindow;
-    SDL_FlushAudioStream;
     SDL_FlushEvent;
     SDL_FlushEvents;
     SDL_GDKGetTaskQueue;
@@ -150,27 +142,18 @@ SDL3_0.0.0 {
     SDL_GetAndroidSDKVersion;
     SDL_GetAssertionHandler;
     SDL_GetAssertionReport;
-    SDL_GetAudioDeviceName;
-    SDL_GetAudioDeviceSpec;
-    SDL_GetAudioDeviceStatus;
-    SDL_GetAudioDriver;
-    SDL_GetAudioStreamAvailable;
-    SDL_GetAudioStreamData;
-    SDL_GetAudioStreamFormat;
     SDL_GetBasePath;
     SDL_GetCPUCacheLineSize;
     SDL_GetCPUCount;
     SDL_GetClipboardData;
     SDL_GetClipboardText;
     SDL_GetClosestFullscreenDisplayMode;
-    SDL_GetCurrentAudioDriver;
     SDL_GetCurrentDisplayMode;
     SDL_GetCurrentDisplayOrientation;
     SDL_GetCurrentRenderOutputSize;
     SDL_GetCurrentVideoDriver;
     SDL_GetCursor;
     SDL_GetDefaultAssertionHandler;
-    SDL_GetDefaultAudioInfo;
     SDL_GetDefaultCursor;
     SDL_GetDesktopDisplayMode;
     SDL_GetDisplayBounds;
@@ -267,8 +250,6 @@ SDL3_0.0.0 {
     SDL_GetMouseState;
     SDL_GetNaturalDisplayOrientation;
     SDL_GetNumAllocations;
-    SDL_GetNumAudioDevices;
-    SDL_GetNumAudioDrivers;
     SDL_GetNumGamepadMappings;
     SDL_GetNumGamepadTouchpadFingers;
     SDL_GetNumGamepadTouchpads;
@@ -291,7 +272,6 @@ SDL3_0.0.0 {
     SDL_GetPreferredLocales;
     SDL_GetPrimaryDisplay;
     SDL_GetPrimarySelectionText;
-    SDL_GetQueuedAudioSize;
     SDL_GetRGB;
     SDL_GetRGBA;
     SDL_GetRectAndLineIntersection;
@@ -461,8 +441,6 @@ SDL3_0.0.0 {
     SDL_LoadFile_RW;
     SDL_LoadFunction;
     SDL_LoadObject;
-    SDL_LoadWAV_RW;
-    SDL_LockAudioDevice;
     SDL_LockJoysticks;
     SDL_LockMutex;
     SDL_LockRWLockForReading;
@@ -494,7 +472,6 @@ SDL3_0.0.0 {
     SDL_Metal_DestroyView;
     SDL_Metal_GetLayer;
     SDL_MinimizeWindow;
-    SDL_MixAudioFormat;
     SDL_MouseIsHaptic;
     SDL_NumHaptics;
     SDL_OnApplicationDidBecomeActive;
@@ -504,22 +481,17 @@ SDL3_0.0.0 {
     SDL_OnApplicationWillEnterForeground;
     SDL_OnApplicationWillResignActive;
     SDL_OnApplicationWillTerminate;
-    SDL_OpenAudioDevice;
     SDL_OpenGamepad;
     SDL_OpenJoystick;
     SDL_OpenSensor;
     SDL_OpenURL;
-    SDL_PauseAudioDevice;
     SDL_PeepEvents;
-    SDL_PlayAudioDevice;
     SDL_PollEvent;
     SDL_PostSemaphore;
     SDL_PremultiplyAlpha;
     SDL_PumpEvents;
     SDL_PushEvent;
-    SDL_PutAudioStreamData;
     SDL_QueryTexture;
-    SDL_QueueAudio;
     SDL_Quit;
     SDL_QuitSubSystem;
     SDL_RWFromConstMem;
@@ -672,7 +644,6 @@ SDL3_0.0.0 {
     SDL_TryLockRWLockForWriting;
     SDL_TryWaitSemaphore;
     SDL_UnloadObject;
-    SDL_UnlockAudioDevice;
     SDL_UnlockJoysticks;
     SDL_UnlockMutex;
     SDL_UnlockRWLock;
@@ -879,6 +850,43 @@ SDL3_0.0.0 {
     SDL_strnlen;
     SDL_AddGamepadMappingsFromFile;
     SDL_ReloadGamepadMappings;
+    SDL_GetNumAudioDrivers;
+    SDL_GetAudioDriver;
+    SDL_GetCurrentAudioDriver;
+    SDL_GetAudioOutputDevices;
+    SDL_GetAudioCaptureDevices;
+    SDL_GetAudioDeviceName;
+    SDL_GetAudioDeviceFormat;
+    SDL_OpenAudioDevice;
+    SDL_CloseAudioDevice;
+    SDL_BindAudioStreams;
+    SDL_BindAudioStream;
+    SDL_UnbindAudioStreams;
+    SDL_UnbindAudioStream;
+    SDL_CreateAudioStream;
+    SDL_GetAudioStreamFormat;
+    SDL_SetAudioStreamFormat;
+    SDL_PutAudioStreamData;
+    SDL_GetAudioStreamData;
+    SDL_GetAudioStreamAvailable;
+    SDL_FlushAudioStream;
+    SDL_ClearAudioStream;
+    SDL_LockAudioStream;
+    SDL_UnlockAudioStream;
+    SDL_SetAudioStreamGetCallback;
+    SDL_SetAudioStreamPutCallback;
+    SDL_DestroyAudioStream;
+    SDL_CreateAndBindAudioStream;
+    SDL_LoadWAV_RW;
+    SDL_LoadWAV;
+    SDL_MixAudioFormat;
+    SDL_ConvertAudioSamples;
+    SDL_GetSilenceValueForFormat;
+    SDL_LoadWAV;
+    SDL_PauseAudioDevice;
+    SDL_UnpauseAudioDevice;
+    SDL_IsAudioDevicePaused;
+    SDL_GetAudioStreamBinding;
     # extra symbols go here (don't modify this line)
   local: *;
 };

src/dynapi/SDL_dynapi_overrides.h

@@ -59,22 +59,17 @@
 #define SDL_BroadcastCondition SDL_BroadcastCondition_REAL
 #define SDL_CaptureMouse SDL_CaptureMouse_REAL
 #define SDL_CleanupTLS SDL_CleanupTLS_REAL
-#define SDL_ClearAudioStream SDL_ClearAudioStream_REAL
 #define SDL_ClearComposition SDL_ClearComposition_REAL
 #define SDL_ClearError SDL_ClearError_REAL
 #define SDL_ClearHints SDL_ClearHints_REAL
-#define SDL_ClearQueuedAudio SDL_ClearQueuedAudio_REAL
-#define SDL_CloseAudioDevice SDL_CloseAudioDevice_REAL
 #define SDL_CloseGamepad SDL_CloseGamepad_REAL
 #define SDL_CloseJoystick SDL_CloseJoystick_REAL
 #define SDL_CloseSensor SDL_CloseSensor_REAL
 #define SDL_ComposeCustomBlendMode SDL_ComposeCustomBlendMode_REAL
-#define SDL_ConvertAudioSamples SDL_ConvertAudioSamples_REAL
 #define SDL_ConvertEventToRenderCoordinates SDL_ConvertEventToRenderCoordinates_REAL
 #define SDL_ConvertPixels SDL_ConvertPixels_REAL
 #define SDL_ConvertSurface SDL_ConvertSurface_REAL
 #define SDL_ConvertSurfaceFormat SDL_ConvertSurfaceFormat_REAL
-#define SDL_CreateAudioStream SDL_CreateAudioStream_REAL
 #define SDL_CreateColorCursor SDL_CreateColorCursor_REAL
 #define SDL_CreateCondition SDL_CreateCondition_REAL
 #define SDL_CreateCursor SDL_CreateCursor_REAL
@@ -106,8 +101,6 @@
 #define SDL_DelHintCallback SDL_DelHintCallback_REAL
 #define SDL_Delay SDL_Delay_REAL
 #define SDL_DelayNS SDL_DelayNS_REAL
-#define SDL_DequeueAudio SDL_DequeueAudio_REAL
-#define SDL_DestroyAudioStream SDL_DestroyAudioStream_REAL
 #define SDL_DestroyCondition SDL_DestroyCondition_REAL
 #define SDL_DestroyCursor SDL_DestroyCursor_REAL
 #define SDL_DestroyMutex SDL_DestroyMutex_REAL
@@ -138,7 +131,6 @@
 #define SDL_FillSurfaceRects SDL_FillSurfaceRects_REAL
 #define SDL_FilterEvents SDL_FilterEvents_REAL
 #define SDL_FlashWindow SDL_FlashWindow_REAL
-#define SDL_FlushAudioStream SDL_FlushAudioStream_REAL
 #define SDL_FlushEvent SDL_FlushEvent_REAL
 #define SDL_FlushEvents SDL_FlushEvents_REAL
 #define SDL_GDKGetTaskQueue SDL_GDKGetTaskQueue_REAL
@@ -174,27 +166,18 @@
 #define SDL_GetAndroidSDKVersion    SDL_GetAndroidSDKVersion_REAL
 #define SDL_GetAssertionHandler SDL_GetAssertionHandler_REAL
 #define SDL_GetAssertionReport SDL_GetAssertionReport_REAL
-#define SDL_GetAudioDeviceName SDL_GetAudioDeviceName_REAL
-#define SDL_GetAudioDeviceSpec SDL_GetAudioDeviceSpec_REAL
-#define SDL_GetAudioDeviceStatus SDL_GetAudioDeviceStatus_REAL
-#define SDL_GetAudioDriver SDL_GetAudioDriver_REAL
-#define SDL_GetAudioStreamAvailable SDL_GetAudioStreamAvailable_REAL
-#define SDL_GetAudioStreamData SDL_GetAudioStreamData_REAL
-#define SDL_GetAudioStreamFormat SDL_GetAudioStreamFormat_REAL
 #define SDL_GetBasePath SDL_GetBasePath_REAL
 #define SDL_GetCPUCacheLineSize SDL_GetCPUCacheLineSize_REAL
 #define SDL_GetCPUCount SDL_GetCPUCount_REAL
 #define SDL_GetClipboardData SDL_GetClipboardData_REAL
 #define SDL_GetClipboardText SDL_GetClipboardText_REAL
 #define SDL_GetClosestFullscreenDisplayMode SDL_GetClosestFullscreenDisplayMode_REAL
-#define SDL_GetCurrentAudioDriver SDL_GetCurrentAudioDriver_REAL
 #define SDL_GetCurrentDisplayMode SDL_GetCurrentDisplayMode_REAL
 #define SDL_GetCurrentDisplayOrientation SDL_GetCurrentDisplayOrientation_REAL
 #define SDL_GetCurrentRenderOutputSize SDL_GetCurrentRenderOutputSize_REAL
 #define SDL_GetCurrentVideoDriver SDL_GetCurrentVideoDriver_REAL
 #define SDL_GetCursor SDL_GetCursor_REAL
 #define SDL_GetDefaultAssertionHandler SDL_GetDefaultAssertionHandler_REAL
-#define SDL_GetDefaultAudioInfo SDL_GetDefaultAudioInfo_REAL
 #define SDL_GetDefaultCursor SDL_GetDefaultCursor_REAL
 #define SDL_GetDesktopDisplayMode SDL_GetDesktopDisplayMode_REAL
 #define SDL_GetDisplayBounds SDL_GetDisplayBounds_REAL
@@ -291,8 +274,6 @@
 #define SDL_GetMouseState SDL_GetMouseState_REAL
 #define SDL_GetNaturalDisplayOrientation SDL_GetNaturalDisplayOrientation_REAL
 #define SDL_GetNumAllocations SDL_GetNumAllocations_REAL
-#define SDL_GetNumAudioDevices SDL_GetNumAudioDevices_REAL
-#define SDL_GetNumAudioDrivers SDL_GetNumAudioDrivers_REAL
 #define SDL_GetNumGamepadMappings SDL_GetNumGamepadMappings_REAL
 #define SDL_GetNumGamepadTouchpadFingers SDL_GetNumGamepadTouchpadFingers_REAL
 #define SDL_GetNumGamepadTouchpads SDL_GetNumGamepadTouchpads_REAL
@@ -315,7 +296,6 @@
 #define SDL_GetPreferredLocales SDL_GetPreferredLocales_REAL
 #define SDL_GetPrimaryDisplay SDL_GetPrimaryDisplay_REAL
 #define SDL_GetPrimarySelectionText SDL_GetPrimarySelectionText_REAL
-#define SDL_GetQueuedAudioSize SDL_GetQueuedAudioSize_REAL
 #define SDL_GetRGB SDL_GetRGB_REAL
 #define SDL_GetRGBA SDL_GetRGBA_REAL
 #define SDL_GetRectAndLineIntersection SDL_GetRectAndLineIntersection_REAL
@@ -485,8 +465,6 @@
 #define SDL_LoadFile_RW SDL_LoadFile_RW_REAL
 #define SDL_LoadFunction SDL_LoadFunction_REAL
 #define SDL_LoadObject SDL_LoadObject_REAL
-#define SDL_LoadWAV_RW SDL_LoadWAV_RW_REAL
-#define SDL_LockAudioDevice SDL_LockAudioDevice_REAL
 #define SDL_LockJoysticks SDL_LockJoysticks_REAL
 #define SDL_LockMutex SDL_LockMutex_REAL
 #define SDL_LockRWLockForReading SDL_LockRWLockForReading_REAL
@@ -518,7 +496,6 @@
 #define SDL_Metal_DestroyView SDL_Metal_DestroyView_REAL
 #define SDL_Metal_GetLayer SDL_Metal_GetLayer_REAL
 #define SDL_MinimizeWindow SDL_MinimizeWindow_REAL
-#define SDL_MixAudioFormat SDL_MixAudioFormat_REAL
 #define SDL_MouseIsHaptic SDL_MouseIsHaptic_REAL
 #define SDL_NumHaptics SDL_NumHaptics_REAL
 #define SDL_OnApplicationDidBecomeActive SDL_OnApplicationDidBecomeActive_REAL
@@ -528,22 +505,17 @@
 #define SDL_OnApplicationWillEnterForeground SDL_OnApplicationWillEnterForeground_REAL
 #define SDL_OnApplicationWillResignActive SDL_OnApplicationWillResignActive_REAL
 #define SDL_OnApplicationWillTerminate SDL_OnApplicationWillTerminate_REAL
-#define SDL_OpenAudioDevice SDL_OpenAudioDevice_REAL
 #define SDL_OpenGamepad SDL_OpenGamepad_REAL
 #define SDL_OpenJoystick SDL_OpenJoystick_REAL
 #define SDL_OpenSensor SDL_OpenSensor_REAL
 #define SDL_OpenURL SDL_OpenURL_REAL
-#define SDL_PauseAudioDevice SDL_PauseAudioDevice_REAL
 #define SDL_PeepEvents SDL_PeepEvents_REAL
-#define SDL_PlayAudioDevice SDL_PlayAudioDevice_REAL
 #define SDL_PollEvent SDL_PollEvent_REAL
 #define SDL_PostSemaphore SDL_PostSemaphore_REAL
 #define SDL_PremultiplyAlpha SDL_PremultiplyAlpha_REAL
 #define SDL_PumpEvents SDL_PumpEvents_REAL
 #define SDL_PushEvent SDL_PushEvent_REAL
-#define SDL_PutAudioStreamData SDL_PutAudioStreamData_REAL
 #define SDL_QueryTexture SDL_QueryTexture_REAL
-#define SDL_QueueAudio SDL_QueueAudio_REAL
 #define SDL_Quit SDL_Quit_REAL
 #define SDL_QuitSubSystem SDL_QuitSubSystem_REAL
 #define SDL_RWFromConstMem SDL_RWFromConstMem_REAL
@@ -605,7 +577,6 @@
 #define SDL_SendGamepadEffect SDL_SendGamepadEffect_REAL
 #define SDL_SendJoystickEffect SDL_SendJoystickEffect_REAL
 #define SDL_SetAssertionHandler SDL_SetAssertionHandler_REAL
-#define SDL_SetAudioStreamFormat SDL_SetAudioStreamFormat_REAL
 #define SDL_SetClipboardData SDL_SetClipboardData_REAL
 #define SDL_SetClipboardText SDL_SetClipboardText_REAL
 #define SDL_SetCursor SDL_SetCursor_REAL
@@ -696,7 +667,6 @@
 #define SDL_TryLockRWLockForWriting SDL_TryLockRWLockForWriting_REAL
 #define SDL_TryWaitSemaphore SDL_TryWaitSemaphore_REAL
 #define SDL_UnloadObject SDL_UnloadObject_REAL
-#define SDL_UnlockAudioDevice SDL_UnlockAudioDevice_REAL
 #define SDL_UnlockJoysticks SDL_UnlockJoysticks_REAL
 #define SDL_UnlockMutex SDL_UnlockMutex_REAL
 #define SDL_UnlockRWLock SDL_UnlockRWLock_REAL
@@ -905,3 +875,40 @@
 #define SDL_strnlen SDL_strnlen_REAL
 #define SDL_AddGamepadMappingsFromFile SDL_AddGamepadMappingsFromFile_REAL
 #define SDL_ReloadGamepadMappings SDL_ReloadGamepadMappings_REAL
+#define SDL_GetNumAudioDrivers SDL_GetNumAudioDrivers_REAL
+#define SDL_GetAudioDriver SDL_GetAudioDriver_REAL
+#define SDL_GetCurrentAudioDriver SDL_GetCurrentAudioDriver_REAL
+#define SDL_GetAudioOutputDevices SDL_GetAudioOutputDevices_REAL
+#define SDL_GetAudioCaptureDevices SDL_GetAudioCaptureDevices_REAL
+#define SDL_GetAudioDeviceName SDL_GetAudioDeviceName_REAL
+#define SDL_GetAudioDeviceFormat SDL_GetAudioDeviceFormat_REAL
+#define SDL_OpenAudioDevice SDL_OpenAudioDevice_REAL
+#define SDL_CloseAudioDevice SDL_CloseAudioDevice_REAL
+#define SDL_BindAudioStreams SDL_BindAudioStreams_REAL
+#define SDL_BindAudioStream SDL_BindAudioStream_REAL
+#define SDL_UnbindAudioStreams SDL_UnbindAudioStreams_REAL
+#define SDL_UnbindAudioStream SDL_UnbindAudioStream_REAL
+#define SDL_CreateAudioStream SDL_CreateAudioStream_REAL
+#define SDL_GetAudioStreamFormat SDL_GetAudioStreamFormat_REAL
+#define SDL_SetAudioStreamFormat SDL_SetAudioStreamFormat_REAL
+#define SDL_PutAudioStreamData SDL_PutAudioStreamData_REAL
+#define SDL_GetAudioStreamData SDL_GetAudioStreamData_REAL
+#define SDL_GetAudioStreamAvailable SDL_GetAudioStreamAvailable_REAL
+#define SDL_FlushAudioStream SDL_FlushAudioStream_REAL
+#define SDL_ClearAudioStream SDL_ClearAudioStream_REAL
+#define SDL_LockAudioStream SDL_LockAudioStream_REAL
+#define SDL_UnlockAudioStream SDL_UnlockAudioStream_REAL
+#define SDL_SetAudioStreamGetCallback SDL_SetAudioStreamGetCallback_REAL
+#define SDL_SetAudioStreamPutCallback SDL_SetAudioStreamPutCallback_REAL
+#define SDL_DestroyAudioStream SDL_DestroyAudioStream_REAL
+#define SDL_CreateAndBindAudioStream SDL_CreateAndBindAudioStream_REAL
+#define SDL_LoadWAV_RW SDL_LoadWAV_RW_REAL
+#define SDL_LoadWAV SDL_LoadWAV_REAL
+#define SDL_MixAudioFormat SDL_MixAudioFormat_REAL
+#define SDL_ConvertAudioSamples SDL_ConvertAudioSamples_REAL
+#define SDL_GetSilenceValueForFormat SDL_GetSilenceValueForFormat_REAL
+#define SDL_LoadWAV SDL_LoadWAV_REAL
+#define SDL_PauseAudioDevice SDL_PauseAudioDevice_REAL
+#define SDL_UnpauseAudioDevice SDL_UnpauseAudioDevice_REAL
+#define SDL_IsAudioDevicePaused SDL_IsAudioDevicePaused_REAL
+#define SDL_GetAudioStreamBinding SDL_GetAudioStreamBinding_REAL

src/dynapi/SDL_dynapi_procs.h

@@ -141,22 +141,17 @@ SDL_DYNAPI_PROC(int,SDL_BlitSurfaceUncheckedScaled,(SDL_Surface *a, const SDL_Re
 SDL_DYNAPI_PROC(int,SDL_BroadcastCondition,(SDL_Condition *a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_CaptureMouse,(SDL_bool a),(a),return)
 SDL_DYNAPI_PROC(void,SDL_CleanupTLS,(void),(),)
-SDL_DYNAPI_PROC(int,SDL_ClearAudioStream,(SDL_AudioStream *a),(a),return)
 SDL_DYNAPI_PROC(void,SDL_ClearComposition,(void),(),)
 SDL_DYNAPI_PROC(void,SDL_ClearError,(void),(),)
 SDL_DYNAPI_PROC(void,SDL_ClearHints,(void),(),)
-SDL_DYNAPI_PROC(int,SDL_ClearQueuedAudio,(SDL_AudioDeviceID a),(a),return)
-SDL_DYNAPI_PROC(void,SDL_CloseAudioDevice,(SDL_AudioDeviceID a),(a),)
 SDL_DYNAPI_PROC(void,SDL_CloseGamepad,(SDL_Gamepad *a),(a),)
 SDL_DYNAPI_PROC(void,SDL_CloseJoystick,(SDL_Joystick *a),(a),)
 SDL_DYNAPI_PROC(void,SDL_CloseSensor,(SDL_Sensor *a),(a),)
 SDL_DYNAPI_PROC(SDL_BlendMode,SDL_ComposeCustomBlendMode,(SDL_BlendFactor a, SDL_BlendFactor b, SDL_BlendOperation c, SDL_BlendFactor d, SDL_BlendFactor e, SDL_BlendOperation f),(a,b,c,d,e,f),return)
-SDL_DYNAPI_PROC(int,SDL_ConvertAudioSamples,(SDL_AudioFormat a, Uint8 b, int c, const Uint8 *d, int e, SDL_AudioFormat f, Uint8 g, int h, Uint8 **i, int *j),(a,b,c,d,e,f,g,h,i,j),return)
 SDL_DYNAPI_PROC(int,SDL_ConvertEventToRenderCoordinates,(SDL_Renderer *a, SDL_Event *b),(a,b),return)
 SDL_DYNAPI_PROC(int,SDL_ConvertPixels,(int a, int b, Uint32 c, const void *d, int e, Uint32 f, void *g, int h),(a,b,c,d,e,f,g,h),return)
 SDL_DYNAPI_PROC(SDL_Surface*,SDL_ConvertSurface,(SDL_Surface *a, const SDL_PixelFormat *b),(a,b),return)
 SDL_DYNAPI_PROC(SDL_Surface*,SDL_ConvertSurfaceFormat,(SDL_Surface *a, Uint32 b),(a,b),return)
-SDL_DYNAPI_PROC(SDL_AudioStream*,SDL_CreateAudioStream,(SDL_AudioFormat a, int b, int c, SDL_AudioFormat d, int e, int f),(a,b,c,d,e,f),return)
 SDL_DYNAPI_PROC(SDL_Cursor*,SDL_CreateColorCursor,(SDL_Surface *a, int b, int c),(a,b,c),return)
 SDL_DYNAPI_PROC(SDL_Condition*,SDL_CreateCondition,(void),(),return)
 SDL_DYNAPI_PROC(SDL_Cursor*,SDL_CreateCursor,(const Uint8 *a, const Uint8 *b, int c, int d, int e, int f),(a,b,c,d,e,f),return)
@@ -185,8 +180,6 @@ SDL_DYNAPI_PROC(void,SDL_DelEventWatch,(SDL_EventFilter a, void *b),(a,b),)
 SDL_DYNAPI_PROC(void,SDL_DelHintCallback,(const char *a, SDL_HintCallback b, void *c),(a,b,c),)
 SDL_DYNAPI_PROC(void,SDL_Delay,(Uint32 a),(a),)
 SDL_DYNAPI_PROC(void,SDL_DelayNS,(Uint64 a),(a),)
-SDL_DYNAPI_PROC(Uint32,SDL_DequeueAudio,(SDL_AudioDeviceID a, void *b, Uint32 c),(a,b,c),return)
-SDL_DYNAPI_PROC(void,SDL_DestroyAudioStream,(SDL_AudioStream *a),(a),)
 SDL_DYNAPI_PROC(void,SDL_DestroyCondition,(SDL_Condition *a),(a),)
 SDL_DYNAPI_PROC(void,SDL_DestroyCursor,(SDL_Cursor *a),(a),)
 SDL_DYNAPI_PROC(void,SDL_DestroyMutex,(SDL_Mutex *a),(a),)
@@ -216,7 +209,6 @@ SDL_DYNAPI_PROC(int,SDL_FillSurfaceRect,(SDL_Surface *a, const SDL_Rect *b, Uint
 SDL_DYNAPI_PROC(int,SDL_FillSurfaceRects,(SDL_Surface *a, const SDL_Rect *b, int c, Uint32 d),(a,b,c,d),return)
 SDL_DYNAPI_PROC(void,SDL_FilterEvents,(SDL_EventFilter a, void *b),(a,b),)
 SDL_DYNAPI_PROC(int,SDL_FlashWindow,(SDL_Window *a, SDL_FlashOperation b),(a,b),return)
-SDL_DYNAPI_PROC(int,SDL_FlushAudioStream,(SDL_AudioStream *a),(a),return)
 SDL_DYNAPI_PROC(void,SDL_FlushEvent,(Uint32 a),(a),)
 SDL_DYNAPI_PROC(void,SDL_FlushEvents,(Uint32 a, Uint32 b),(a,b),)
 SDL_DYNAPI_PROC(int,SDL_GL_BindTexture,(SDL_Texture *a, float *b, float *c),(a,b,c),return)
@@ -249,27 +241,18 @@ SDL_DYNAPI_PROC(SDL_bool,SDL_GamepadHasSensor,(SDL_Gamepad *a, SDL_SensorType b)
 SDL_DYNAPI_PROC(SDL_bool,SDL_GamepadSensorEnabled,(SDL_Gamepad *a, SDL_SensorType b),(a,b),return)
 SDL_DYNAPI_PROC(SDL_AssertionHandler,SDL_GetAssertionHandler,(void **a),(a),return)
 SDL_DYNAPI_PROC(const SDL_AssertData*,SDL_GetAssertionReport,(void),(),return)
-SDL_DYNAPI_PROC(const char*,SDL_GetAudioDeviceName,(int a, int b),(a,b),return)
-SDL_DYNAPI_PROC(int,SDL_GetAudioDeviceSpec,(int a, int b, SDL_AudioSpec *c),(a,b,c),return)
-SDL_DYNAPI_PROC(SDL_AudioStatus,SDL_GetAudioDeviceStatus,(SDL_AudioDeviceID a),(a),return)
-SDL_DYNAPI_PROC(const char*,SDL_GetAudioDriver,(int a),(a),return)
-SDL_DYNAPI_PROC(int,SDL_GetAudioStreamAvailable,(SDL_AudioStream *a),(a),return)
-SDL_DYNAPI_PROC(int,SDL_GetAudioStreamData,(SDL_AudioStream *a, void *b, int c),(a,b,c),return)
-SDL_DYNAPI_PROC(int,SDL_GetAudioStreamFormat,(SDL_AudioStream *a, SDL_AudioFormat *b, int *c, int *d, SDL_AudioFormat *e, int *f, int *g),(a,b,c,d,e,f,g),return)
 SDL_DYNAPI_PROC(char*,SDL_GetBasePath,(void),(),return)
 SDL_DYNAPI_PROC(int,SDL_GetCPUCacheLineSize,(void),(),return)
 SDL_DYNAPI_PROC(int,SDL_GetCPUCount,(void),(),return)
 SDL_DYNAPI_PROC(void*,SDL_GetClipboardData,(const char *a, size_t *b),(a,b),return)
 SDL_DYNAPI_PROC(char*,SDL_GetClipboardText,(void),(),return)
 SDL_DYNAPI_PROC(const SDL_DisplayMode*,SDL_GetClosestFullscreenDisplayMode,(SDL_DisplayID a, int b, int c, float d, SDL_bool e),(a,b,c,d,e),return)
-SDL_DYNAPI_PROC(const char*,SDL_GetCurrentAudioDriver,(void),(),return)
 SDL_DYNAPI_PROC(const SDL_DisplayMode*,SDL_GetCurrentDisplayMode,(SDL_DisplayID a),(a),return)
 SDL_DYNAPI_PROC(SDL_DisplayOrientation,SDL_GetCurrentDisplayOrientation,(SDL_DisplayID a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_GetCurrentRenderOutputSize,(SDL_Renderer *a, int *b, int *c),(a,b,c),return)
 SDL_DYNAPI_PROC(const char*,SDL_GetCurrentVideoDriver,(void),(),return)
 SDL_DYNAPI_PROC(SDL_Cursor*,SDL_GetCursor,(void),(),return)
 SDL_DYNAPI_PROC(SDL_AssertionHandler,SDL_GetDefaultAssertionHandler,(void),(),return)
-SDL_DYNAPI_PROC(int,SDL_GetDefaultAudioInfo,(char **a, SDL_AudioSpec *b, int c),(a,b,c),return)
 SDL_DYNAPI_PROC(SDL_Cursor*,SDL_GetDefaultCursor,(void),(),return)
 SDL_DYNAPI_PROC(const SDL_DisplayMode*,SDL_GetDesktopDisplayMode,(SDL_DisplayID a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_GetDisplayBounds,(SDL_DisplayID a, SDL_Rect *b),(a,b),return)
@@ -366,8 +349,6 @@ SDL_DYNAPI_PROC(SDL_Window*,SDL_GetMouseFocus,(void),(),return)
 SDL_DYNAPI_PROC(Uint32,SDL_GetMouseState,(float *a, float *b),(a,b),return)
 SDL_DYNAPI_PROC(SDL_DisplayOrientation,SDL_GetNaturalDisplayOrientation,(SDL_DisplayID a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_GetNumAllocations,(void),(),return)
-SDL_DYNAPI_PROC(int,SDL_GetNumAudioDevices,(int a),(a),return)
-SDL_DYNAPI_PROC(int,SDL_GetNumAudioDrivers,(void),(),return)
 SDL_DYNAPI_PROC(int,SDL_GetNumGamepadMappings,(void),(),return)
 SDL_DYNAPI_PROC(int,SDL_GetNumGamepadTouchpadFingers,(SDL_Gamepad *a, int b),(a,b),return)
 SDL_DYNAPI_PROC(int,SDL_GetNumGamepadTouchpads,(SDL_Gamepad *a),(a),return)
@@ -390,7 +371,6 @@ SDL_DYNAPI_PROC(char*,SDL_GetPrefPath,(const char *a, const char *b),(a,b),retur
 SDL_DYNAPI_PROC(SDL_Locale*,SDL_GetPreferredLocales,(void),(),return)
 SDL_DYNAPI_PROC(SDL_DisplayID,SDL_GetPrimaryDisplay,(void),(),return)
 SDL_DYNAPI_PROC(char*,SDL_GetPrimarySelectionText,(void),(),return)
-SDL_DYNAPI_PROC(Uint32,SDL_GetQueuedAudioSize,(SDL_AudioDeviceID a),(a),return)
 SDL_DYNAPI_PROC(void,SDL_GetRGB,(Uint32 a, const SDL_PixelFormat *b, Uint8 *c, Uint8 *d, Uint8 *e),(a,b,c,d,e),)
 SDL_DYNAPI_PROC(void,SDL_GetRGBA,(Uint32 a, const SDL_PixelFormat *b, Uint8 *c, Uint8 *d, Uint8 *e, Uint8 *f),(a,b,c,d,e,f),)
 SDL_DYNAPI_PROC(SDL_bool,SDL_GetRectAndLineIntersection,(const SDL_Rect *a, int *b, int *c, int *d, int *e),(a,b,c,d,e),return)
@@ -553,8 +533,6 @@ SDL_DYNAPI_PROC(void*,SDL_LoadFile,(const char *a, size_t *b),(a,b),return)
 SDL_DYNAPI_PROC(void*,SDL_LoadFile_RW,(SDL_RWops *a, size_t *b, SDL_bool c),(a,b,c),return)
 SDL_DYNAPI_PROC(SDL_FunctionPointer,SDL_LoadFunction,(void *a, const char *b),(a,b),return)
 SDL_DYNAPI_PROC(void*,SDL_LoadObject,(const char *a),(a),return)
-SDL_DYNAPI_PROC(SDL_AudioSpec*,SDL_LoadWAV_RW,(SDL_RWops *a, SDL_bool b, SDL_AudioSpec *c, Uint8 **d, Uint32 *e),(a,b,c,d,e),return)
-SDL_DYNAPI_PROC(int,SDL_LockAudioDevice,(SDL_AudioDeviceID a),(a),return)
 SDL_DYNAPI_PROC(void,SDL_LockJoysticks,(void),(),)
 SDL_DYNAPI_PROC(int,SDL_LockMutex,(SDL_Mutex *a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_LockRWLockForReading,(SDL_RWLock *a),(a),return)
@@ -578,7 +556,6 @@ SDL_DYNAPI_PROC(SDL_MetalView,SDL_Metal_CreateView,(SDL_Window *a),(a),return)
 SDL_DYNAPI_PROC(void,SDL_Metal_DestroyView,(SDL_MetalView a),(a),)
 SDL_DYNAPI_PROC(void*,SDL_Metal_GetLayer,(SDL_MetalView a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_MinimizeWindow,(SDL_Window *a),(a),return)
-SDL_DYNAPI_PROC(int,SDL_MixAudioFormat,(Uint8 *a, const Uint8 *b, SDL_AudioFormat c, Uint32 d, int e),(a,b,c,d,e),return)
 SDL_DYNAPI_PROC(int,SDL_MouseIsHaptic,(void),(),return)
 SDL_DYNAPI_PROC(int,SDL_NumHaptics,(void),(),return)
 SDL_DYNAPI_PROC(void,SDL_OnApplicationDidBecomeActive,(void),(),)
@@ -587,22 +564,17 @@ SDL_DYNAPI_PROC(void,SDL_OnApplicationDidReceiveMemoryWarning,(void),(),)
 SDL_DYNAPI_PROC(void,SDL_OnApplicationWillEnterForeground,(void),(),)
 SDL_DYNAPI_PROC(void,SDL_OnApplicationWillResignActive,(void),(),)
 SDL_DYNAPI_PROC(void,SDL_OnApplicationWillTerminate,(void),(),)
-SDL_DYNAPI_PROC(SDL_AudioDeviceID,SDL_OpenAudioDevice,(const char *a, int b, const SDL_AudioSpec *c, SDL_AudioSpec *d, int e),(a,b,c,d,e),return)
 SDL_DYNAPI_PROC(SDL_Gamepad*,SDL_OpenGamepad,(SDL_JoystickID a),(a),return)
 SDL_DYNAPI_PROC(SDL_Joystick*,SDL_OpenJoystick,(SDL_JoystickID a),(a),return)
 SDL_DYNAPI_PROC(SDL_Sensor*,SDL_OpenSensor,(SDL_SensorID a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_OpenURL,(const char *a),(a),return)
-SDL_DYNAPI_PROC(int,SDL_PauseAudioDevice,(SDL_AudioDeviceID a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_PeepEvents,(SDL_Event *a, int b, SDL_eventaction c, Uint32 d, Uint32 e),(a,b,c,d,e),return)
-SDL_DYNAPI_PROC(int,SDL_PlayAudioDevice,(SDL_AudioDeviceID a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_PollEvent,(SDL_Event *a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_PostSemaphore,(SDL_Semaphore *a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_PremultiplyAlpha,(int a, int b, Uint32 c, const void *d, int e, Uint32 f, void *g, int h),(a,b,c,d,e,f,g,h),return)
 SDL_DYNAPI_PROC(void,SDL_PumpEvents,(void),(),)
 SDL_DYNAPI_PROC(int,SDL_PushEvent,(SDL_Event *a),(a),return)
-SDL_DYNAPI_PROC(int,SDL_PutAudioStreamData,(SDL_AudioStream *a, const void *b, int c),(a,b,c),return)
 SDL_DYNAPI_PROC(int,SDL_QueryTexture,(SDL_Texture *a, Uint32 *b, int *c, int *d, int *e),(a,b,c,d,e),return)
-SDL_DYNAPI_PROC(int,SDL_QueueAudio,(SDL_AudioDeviceID a, const void *b, Uint32 c),(a,b,c),return)
 SDL_DYNAPI_PROC(void,SDL_Quit,(void),(),)
 SDL_DYNAPI_PROC(void,SDL_QuitSubSystem,(Uint32 a),(a),)
 SDL_DYNAPI_PROC(SDL_RWops*,SDL_RWFromConstMem,(const void *a, size_t b),(a,b),return)
@@ -662,7 +634,6 @@ SDL_DYNAPI_PROC(SDL_bool,SDL_ScreenSaverEnabled,(void),(),return)
 SDL_DYNAPI_PROC(int,SDL_SendGamepadEffect,(SDL_Gamepad *a, const void *b, int c),(a,b,c),return)
 SDL_DYNAPI_PROC(int,SDL_SendJoystickEffect,(SDL_Joystick *a, const void *b, int c),(a,b,c),return)
 SDL_DYNAPI_PROC(void,SDL_SetAssertionHandler,(SDL_AssertionHandler a, void *b),(a,b),)
-SDL_DYNAPI_PROC(int,SDL_SetAudioStreamFormat,(SDL_AudioStream *a, SDL_AudioFormat b, int c, int d, SDL_AudioFormat e, int f, int g),(a,b,c,d,e,f,g),return)
 SDL_DYNAPI_PROC(int,SDL_SetClipboardData,(SDL_ClipboardDataCallback a, SDL_ClipboardCleanupCallback b, void *c, const char **d, size_t e),(a,b,c,d,e),return)
 SDL_DYNAPI_PROC(int,SDL_SetClipboardText,(const char *a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_SetCursor,(SDL_Cursor *a),(a),return)
@@ -751,7 +722,6 @@ SDL_DYNAPI_PROC(int,SDL_TryLockRWLockForReading,(SDL_RWLock *a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_TryLockRWLockForWriting,(SDL_RWLock *a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_TryWaitSemaphore,(SDL_Semaphore *a),(a),return)
 SDL_DYNAPI_PROC(void,SDL_UnloadObject,(void *a),(a),)
-SDL_DYNAPI_PROC(void,SDL_UnlockAudioDevice,(SDL_AudioDeviceID a),(a),)
 SDL_DYNAPI_PROC(void,SDL_UnlockJoysticks,(void),(),)
 SDL_DYNAPI_PROC(int,SDL_UnlockMutex,(SDL_Mutex *a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_UnlockRWLock,(SDL_RWLock *a),(a),return)
@@ -950,3 +920,39 @@ SDL_DYNAPI_PROC(size_t,SDL_wcsnlen,(const wchar_t *a, size_t b),(a,b),return)
 SDL_DYNAPI_PROC(size_t,SDL_strnlen,(const char *a, size_t b),(a,b),return)
 SDL_DYNAPI_PROC(int,SDL_AddGamepadMappingsFromFile,(const char *a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_ReloadGamepadMappings,(void),(),return)
+SDL_DYNAPI_PROC(int,SDL_GetNumAudioDrivers,(void),(),return)
+SDL_DYNAPI_PROC(const char*,SDL_GetAudioDriver,(int a),(a),return)
+SDL_DYNAPI_PROC(const char*,SDL_GetCurrentAudioDriver,(void),(),return)
+SDL_DYNAPI_PROC(SDL_AudioDeviceID*,SDL_GetAudioOutputDevices,(int *a),(a),return)
+SDL_DYNAPI_PROC(SDL_AudioDeviceID*,SDL_GetAudioCaptureDevices,(int *a),(a),return)
+SDL_DYNAPI_PROC(char*,SDL_GetAudioDeviceName,(SDL_AudioDeviceID a),(a),return)
+SDL_DYNAPI_PROC(int,SDL_GetAudioDeviceFormat,(SDL_AudioDeviceID a, SDL_AudioSpec *b),(a,b),return)
+SDL_DYNAPI_PROC(SDL_AudioDeviceID,SDL_OpenAudioDevice,(SDL_AudioDeviceID a, const SDL_AudioSpec *b),(a,b),return)
+SDL_DYNAPI_PROC(void,SDL_CloseAudioDevice,(SDL_AudioDeviceID a),(a),)
+SDL_DYNAPI_PROC(int,SDL_BindAudioStreams,(SDL_AudioDeviceID a, SDL_AudioStream **b, int c),(a,b,c),return)
+SDL_DYNAPI_PROC(int,SDL_BindAudioStream,(SDL_AudioDeviceID a, SDL_AudioStream *b),(a,b),return)
+SDL_DYNAPI_PROC(void,SDL_UnbindAudioStreams,(SDL_AudioStream **a, int b),(a,b),)
+SDL_DYNAPI_PROC(void,SDL_UnbindAudioStream,(SDL_AudioStream *a),(a),)
+SDL_DYNAPI_PROC(SDL_AudioStream*,SDL_CreateAudioStream,(const SDL_AudioSpec *a, const SDL_AudioSpec *b),(a,b),return)
+SDL_DYNAPI_PROC(int,SDL_GetAudioStreamFormat,(SDL_AudioStream *a, SDL_AudioSpec *b, SDL_AudioSpec *c),(a,b,c),return)
+SDL_DYNAPI_PROC(int,SDL_SetAudioStreamFormat,(SDL_AudioStream *a, const SDL_AudioSpec *b, const SDL_AudioSpec *c),(a,b,c),return)
+SDL_DYNAPI_PROC(int,SDL_PutAudioStreamData,(SDL_AudioStream *a, const void *b, int c),(a,b,c),return)
+SDL_DYNAPI_PROC(int,SDL_GetAudioStreamData,(SDL_AudioStream *a, void *b, int c),(a,b,c),return)
+SDL_DYNAPI_PROC(int,SDL_GetAudioStreamAvailable,(SDL_AudioStream *a),(a),return)
+SDL_DYNAPI_PROC(int,SDL_FlushAudioStream,(SDL_AudioStream *a),(a),return)
+SDL_DYNAPI_PROC(int,SDL_ClearAudioStream,(SDL_AudioStream *a),(a),return)
+SDL_DYNAPI_PROC(int,SDL_LockAudioStream,(SDL_AudioStream *a),(a),return)
+SDL_DYNAPI_PROC(int,SDL_UnlockAudioStream,(SDL_AudioStream *a),(a),return)
+SDL_DYNAPI_PROC(int,SDL_SetAudioStreamGetCallback,(SDL_AudioStream *a, SDL_AudioStreamRequestCallback b, void *c),(a,b,c),return)
+SDL_DYNAPI_PROC(int,SDL_SetAudioStreamPutCallback,(SDL_AudioStream *a, SDL_AudioStreamRequestCallback b, void *c),(a,b,c),return)
+SDL_DYNAPI_PROC(void,SDL_DestroyAudioStream,(SDL_AudioStream *a),(a),)
+SDL_DYNAPI_PROC(SDL_AudioStream*,SDL_CreateAndBindAudioStream,(SDL_AudioDeviceID a, const SDL_AudioSpec *b),(a,b),return)
+SDL_DYNAPI_PROC(int,SDL_LoadWAV_RW,(SDL_RWops *a, int b, SDL_AudioSpec *c, Uint8 **d, Uint32 *e),(a,b,c,d,e),return)
+SDL_DYNAPI_PROC(int,SDL_MixAudioFormat,(Uint8 *a, const Uint8 *b, SDL_AudioFormat c, Uint32 d, int e),(a,b,c,d,e),return)
+SDL_DYNAPI_PROC(int,SDL_ConvertAudioSamples,(const SDL_AudioSpec *a, const Uint8 *b, int c, const SDL_AudioSpec *d, Uint8 **e, int *f),(a,b,c,d,e,f),return)
+SDL_DYNAPI_PROC(int,SDL_GetSilenceValueForFormat,(SDL_AudioFormat a),(a),return)
+SDL_DYNAPI_PROC(int,SDL_LoadWAV,(const char *a, SDL_AudioSpec *b, Uint8 **c, Uint32 *d),(a,b,c,d),return)
+SDL_DYNAPI_PROC(int,SDL_PauseAudioDevice,(SDL_AudioDeviceID a),(a),return)
+SDL_DYNAPI_PROC(int,SDL_UnpauseAudioDevice,(SDL_AudioDeviceID a),(a),return)
+SDL_DYNAPI_PROC(SDL_bool,SDL_IsAudioDevicePaused,(SDL_AudioDeviceID a),(a),return)
+SDL_DYNAPI_PROC(SDL_AudioDeviceID,SDL_GetAudioStreamBinding,(SDL_AudioStream *a),(a),return)

src/test/SDL_test_common.c

@@ -117,10 +117,9 @@ SDLTest_CommonState *SDLTest_CommonCreateState(char **argv, Uint32 flags)
     state->logical_presentation = SDL_LOGICAL_PRESENTATION_DISABLED;
     state->logical_scale_mode = SDL_SCALEMODE_LINEAR;
     state->num_windows = 1;
-    state->audiospec.freq = 22050;
-    state->audiospec.format = SDL_AUDIO_S16;
-    state->audiospec.channels = 2;
-    state->audiospec.samples = 2048;
+    state->audio_freq = 22050;
+    state->audio_format = SDL_AUDIO_S16;
+    state->audio_channels = 2;
 
     /* Set some very sane GL defaults */
     state->gl_red_size = 8;
@@ -604,7 +603,7 @@ int SDLTest_CommonArg(SDLTest_CommonState *state, int index)
             if (!argv[index]) {
                 return -1;
             }
-            state->audiospec.freq = SDL_atoi(argv[index]);
+            state->audio_freq = SDL_atoi(argv[index]);
             return 2;
         }
         if (SDL_strcasecmp(argv[index], "--format") == 0) {
@@ -613,23 +612,23 @@ int SDLTest_CommonArg(SDLTest_CommonState *state, int index)
                 return -1;
             }
             if (SDL_strcasecmp(argv[index], "U8") == 0) {
-                state->audiospec.format = SDL_AUDIO_U8;
+                state->audio_format = SDL_AUDIO_U8;
                 return 2;
             }
             if (SDL_strcasecmp(argv[index], "S8") == 0) {
-                state->audiospec.format = SDL_AUDIO_S8;
+                state->audio_format = SDL_AUDIO_S8;
                 return 2;
             }
             if (SDL_strcasecmp(argv[index], "S16") == 0) {
-                state->audiospec.format = SDL_AUDIO_S16;
+                state->audio_format = SDL_AUDIO_S16;
                 return 2;
             }
             if (SDL_strcasecmp(argv[index], "S16LE") == 0) {
-                state->audiospec.format = SDL_AUDIO_S16LSB;
+                state->audio_format = SDL_AUDIO_S16LSB;
                 return 2;
             }
             if (SDL_strcasecmp(argv[index], "S16BE") == 0) {
-                state->audiospec.format = SDL_AUDIO_S16MSB;
+                state->audio_format = SDL_AUDIO_S16MSB;
                 return 2;
             }
 
@@ -642,15 +641,7 @@ int SDLTest_CommonArg(SDLTest_CommonState *state, int index)
             if (!argv[index]) {
                 return -1;
             }
-            state->audiospec.channels = (Uint8) SDL_atoi(argv[index]);
-            return 2;
-        }
-        if (SDL_strcasecmp(argv[index], "--samples") == 0) {
-            ++index;
-            if (!argv[index]) {
-                return -1;
-            }
-            state->audiospec.samples = (Uint16) SDL_atoi(argv[index]);
+            state->audio_channels = (Uint8) SDL_atoi(argv[index]);
             return 2;
         }
     }
@@ -1452,7 +1443,8 @@ SDL_bool SDLTest_CommonInit(SDLTest_CommonState *state)
                     SDL_GetCurrentAudioDriver());
         }
 
-        state->audio_id = SDL_OpenAudioDevice(NULL, 0, &state->audiospec, NULL, 0);
+        const SDL_AudioSpec spec = { state->audio_format, state->audio_channels, state->audio_freq };
+        state->audio_id = SDL_OpenAudioDevice(SDL_AUDIO_DEVICE_DEFAULT_OUTPUT, &spec);
         if (!state->audio_id) {
             SDL_Log("Couldn't open audio: %s\n", SDL_GetError());
             return SDL_FALSE;

src/video/android/SDL_androidevents.c

@@ -108,7 +108,7 @@ void Android_PumpEvents_Blocking(SDL_VideoDevice *_this)
 
         ANDROIDAUDIO_PauseDevices();
         openslES_PauseDevices();
-        aaudio_PauseDevices();
+        AAUDIO_PauseDevices();
 
         if (SDL_WaitSemaphore(Android_ResumeSem) == 0) {
 
@@ -119,7 +119,7 @@ void Android_PumpEvents_Blocking(SDL_VideoDevice *_this)
 
             ANDROIDAUDIO_ResumeDevices();
             openslES_ResumeDevices();
-            aaudio_ResumeDevices();
+            AAUDIO_ResumeDevices();
 
             /* Restore the GL Context from here, as this operation is thread dependent */
 #ifdef SDL_VIDEO_OPENGL_EGL
@@ -160,9 +160,9 @@ void Android_PumpEvents_Blocking(SDL_VideoDevice *_this)
         }
     }
 
-    if (aaudio_DetectBrokenPlayState()) {
-        aaudio_PauseDevices();
-        aaudio_ResumeDevices();
+    if (AAUDIO_DetectBrokenPlayState()) {
+        AAUDIO_PauseDevices();
+        AAUDIO_ResumeDevices();
     }
 }
 
@@ -187,7 +187,7 @@ void Android_PumpEvents_NonBlocking(SDL_VideoDevice *_this)
             if (videodata->pauseAudio) {
                 ANDROIDAUDIO_PauseDevices();
                 openslES_PauseDevices();
-                aaudio_PauseDevices();
+                AAUDIO_PauseDevices();
             }
 
             backup_context = 0;
@@ -203,7 +203,7 @@ void Android_PumpEvents_NonBlocking(SDL_VideoDevice *_this)
             if (videodata->pauseAudio) {
                 ANDROIDAUDIO_ResumeDevices();
                 openslES_ResumeDevices();
-                aaudio_ResumeDevices();
+                AAUDIO_ResumeDevices();
             }
 
 #ifdef SDL_VIDEO_OPENGL_EGL
@@ -246,9 +246,9 @@ void Android_PumpEvents_NonBlocking(SDL_VideoDevice *_this)
         }
     }
 
-    if (aaudio_DetectBrokenPlayState()) {
-        aaudio_PauseDevices();
-        aaudio_ResumeDevices();
+    if (AAUDIO_DetectBrokenPlayState()) {
+        AAUDIO_PauseDevices();
+        AAUDIO_ResumeDevices();
     }
 }
 

test/CMakeLists.txt

@@ -119,11 +119,10 @@ endif()
 add_sdl_test_executable(checkkeys SOURCES checkkeys.c)
 add_sdl_test_executable(checkkeysthreads SOURCES checkkeysthreads.c)
 add_sdl_test_executable(loopwave NEEDS_RESOURCES TESTUTILS SOURCES loopwave.c)
-add_sdl_test_executable(loopwavequeue NEEDS_RESOURCES TESTUTILS SOURCES loopwavequeue.c)
 add_sdl_test_executable(testsurround SOURCES testsurround.c)
 add_sdl_test_executable(testresample NEEDS_RESOURCES SOURCES testresample.c)
 add_sdl_test_executable(testaudioinfo SOURCES testaudioinfo.c)
-add_sdl_test_executable(testaudiostreamdynamicresample SOURCES testaudiostreamdynamicresample.c)
+add_sdl_test_executable(testaudiostreamdynamicresample NEEDS_RESOURCES TESTUTILS SOURCES testaudiostreamdynamicresample.c)
 
 file(GLOB TESTAUTOMATION_SOURCE_FILES testautomation*.c)
 add_sdl_test_executable(testautomation NEEDS_RESOURCES NO_C90 SOURCES ${TESTAUTOMATION_SOURCE_FILES})
@@ -203,6 +202,7 @@ if(Python3_FOUND AND Python3_VERSION VERSION_GREATER_EQUAL "3.2")
     endforeach()
 endif()
 
+add_sdl_test_executable(testaudio NEEDS_RESOURCES TESTUTILS SOURCES testaudio.c)
 add_sdl_test_executable(testfile NONINTERACTIVE SOURCES testfile.c)
 add_sdl_test_executable(testcontroller TESTUTILS SOURCES testcontroller.c gamepadutils.c ${gamepad_image_headers})
 add_sdl_test_executable(testgeometry TESTUTILS SOURCES testgeometry.c)

test/README

@@ -3,7 +3,6 @@ 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
 	testsurround	Audio test -- play test tone on each audio channel
 	testaudioinfo	Lists audio device capabilities
 	testerror	Tests multi-threaded error handling

test/loopwave.c

@@ -31,10 +31,18 @@ static struct
     SDL_AudioSpec spec;
     Uint8 *sound;    /* Pointer to wave data */
     Uint32 soundlen; /* Length of wave data */
-    int soundpos;    /* Current play position */
+    Uint32 soundpos;
 } wave;
 
 static SDL_AudioDeviceID device;
+static SDL_AudioStream *stream;
+
+static void fillerup(void)
+{
+    if (SDL_GetAudioStreamAvailable(stream) < (int) ((wave.soundlen / 2))) {
+        SDL_PutAudioStreamData(stream, wave.sound, wave.soundlen);
+    }
+}
 
 /* Call this instead of exit(), so we can clean up SDL: atexit() is evil. */
 static void
@@ -51,6 +59,8 @@ static void
 close_audio(void)
 {
     if (device != 0) {
+        SDL_DestroyAudioStream(stream);
+        stream = NULL;
         SDL_CloseAudioDevice(device);
         device = 0;
     }
@@ -59,56 +69,33 @@ close_audio(void)
 static void
 open_audio(void)
 {
-    /* Initialize fillerup() variables */
-    device = SDL_OpenAudioDevice(NULL, SDL_FALSE, &wave.spec, NULL, 0);
+    device = SDL_OpenAudioDevice(SDL_AUDIO_DEVICE_DEFAULT_OUTPUT, &wave.spec);
     if (!device) {
         SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Couldn't open audio: %s\n", SDL_GetError());
         SDL_free(wave.sound);
         quit(2);
     }
-
-    /* Let the audio run */
-    SDL_PlayAudioDevice(device);
-}
-
-#ifndef __EMSCRIPTEN__
-static void reopen_audio(void)
-{
-    close_audio();
-    open_audio();
-}
-#endif
-
-static void SDLCALL
-fillerup(void *unused, Uint8 *stream, int len)
-{
-    Uint8 *waveptr;
-    int waveleft;
-
-    /* Set up the pointers */
-    waveptr = wave.sound + wave.soundpos;
-    waveleft = wave.soundlen - wave.soundpos;
-
-    /* Go! */
-    while (waveleft <= len) {
-        SDL_memcpy(stream, waveptr, waveleft);
-        stream += waveleft;
-        len -= waveleft;
-        waveptr = wave.sound;
-        waveleft = wave.soundlen;
-        wave.soundpos = 0;
+    stream = SDL_CreateAndBindAudioStream(device, &wave.spec);
+    if (!stream) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Couldn't create audio stream: %s\n", SDL_GetError());
+        SDL_CloseAudioDevice(device);
+        SDL_free(wave.sound);
+        quit(2);
     }
-    SDL_memcpy(stream, waveptr, len);
-    wave.soundpos += len;
 }
 
+
 static int done = 0;
 
+
+
 #ifdef __EMSCRIPTEN__
 static void loop(void)
 {
-    if (done || (SDL_GetAudioDeviceStatus(device) != SDL_AUDIO_PLAYING)) {
+    if (done) {
         emscripten_cancel_main_loop();
+    } else {
+        fillerup();
     }
 }
 #endif
@@ -162,13 +149,11 @@ int main(int argc, char *argv[])
     }
 
     /* Load the wave file into memory */
-    if (SDL_LoadWAV(filename, &wave.spec, &wave.sound, &wave.soundlen) == NULL) {
+    if (SDL_LoadWAV(filename, &wave.spec, &wave.sound, &wave.soundlen) == -1) {
         SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Couldn't load %s: %s\n", filename, SDL_GetError());
         quit(1);
     }
 
-    wave.spec.callback = fillerup;
-
     /* Show the list of available drivers */
     SDL_Log("Available audio drivers:");
     for (i = 0; i < SDL_GetNumAudioDrivers(); ++i) {
@@ -179,8 +164,6 @@ int main(int argc, char *argv[])
 
     open_audio();
 
-    SDL_FlushEvents(SDL_EVENT_AUDIO_DEVICE_ADDED, SDL_EVENT_AUDIO_DEVICE_REMOVED);
-
 #ifdef __EMSCRIPTEN__
     emscripten_set_main_loop(loop, 0, 1);
 #else
@@ -191,11 +174,9 @@ int main(int argc, char *argv[])
             if (event.type == SDL_EVENT_QUIT) {
                 done = 1;
             }
-            if ((event.type == SDL_EVENT_AUDIO_DEVICE_ADDED && !event.adevice.iscapture) ||
-                (event.type == SDL_EVENT_AUDIO_DEVICE_REMOVED && !event.adevice.iscapture && event.adevice.which == device)) {
-                reopen_audio();
-            }
         }
+
+        fillerup();
         SDL_Delay(100);
     }
 #endif

test/loopwavequeue.c

@@ -1,183 +0,0 @@
-/*
-  Copyright (C) 1997-2023 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 <stdlib.h>
-
-#ifdef __EMSCRIPTEN__
-#include <emscripten/emscripten.h>
-#endif
-
-#include <SDL3/SDL.h>
-#include <SDL3/SDL_main.h>
-#include <SDL3/SDL_test.h>
-
-#ifdef HAVE_SIGNAL_H
-#include <signal.h>
-#endif
-
-#include "testutils.h"
-
-static struct
-{
-    SDL_AudioSpec spec;
-    Uint8 *sound;    /* Pointer to wave data */
-    Uint32 soundlen; /* Length of wave data */
-} wave;
-
-/* Call this instead of exit(), so we can clean up SDL: atexit() is evil. */
-static void
-quit(int rc)
-{
-    SDL_Quit();
-    /* Let 'main()' return normally */
-    if (rc != 0) {
-        exit(rc);
-    }
-}
-
-static int done = 0;
-static void poked(int sig)
-{
-    done = 1;
-}
-
-static SDL_AudioDeviceID g_audio_id = 0;
-
-static void loop(void)
-{
-#ifdef __EMSCRIPTEN__
-    if (done || (SDL_GetAudioDeviceStatus(g_audio_id) != SDL_AUDIO_PLAYING)) {
-        emscripten_cancel_main_loop();
-    } else
-#endif
-    {
-        /* The device from SDL_OpenAudio() is always device #1. */
-        const Uint32 queued = SDL_GetQueuedAudioSize(g_audio_id);
-        SDL_Log("Device has %u bytes queued.\n", (unsigned int)queued);
-        if (queued <= 8192) { /* time to requeue the whole thing? */
-            if (SDL_QueueAudio(g_audio_id, 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());
-            }
-        }
-    }
-}
-
-int main(int argc, char *argv[])
-{
-    int i;
-    char *filename = NULL;
-    SDLTest_CommonState *state;
-
-    /* Initialize test framework */
-    state = SDLTest_CommonCreateState(argv, 0);
-    if (state == NULL) {
-        return 1;
-    }
-
-    /* Enable standard application logging */
-    SDL_LogSetPriority(SDL_LOG_CATEGORY_APPLICATION, SDL_LOG_PRIORITY_INFO);
-
-    /* Parse commandline */
-    for (i = 1; i < argc;) {
-        int consumed;
-
-        consumed = SDLTest_CommonArg(state, i);
-        if (!consumed) {
-            if (!filename) {
-                filename = argv[i];
-                consumed = 1;
-            }
-        }
-        if (consumed <= 0) {
-            static const char *options[] = { "[sample.wav]", NULL };
-            SDLTest_CommonLogUsage(state, argv[0], options);
-            exit(1);
-        }
-
-        i += consumed;
-    }
-
-    /* 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;
-    }
-
-    filename = GetResourceFilename(filename, "sample.wav");
-
-    if (filename == NULL) {
-        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "%s\n", SDL_GetError());
-        quit(1);
-    }
-
-    /* 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. */
-
-#ifdef HAVE_SIGNAL_H
-    /* Set the signals */
-#ifdef SIGHUP
-    (void)signal(SIGHUP, poked);
-#endif
-    (void)signal(SIGINT, poked);
-#ifdef SIGQUIT
-    (void)signal(SIGQUIT, poked);
-#endif
-    (void)signal(SIGTERM, poked);
-#endif /* HAVE_SIGNAL_H */
-
-    /* Initialize fillerup() variables */
-    g_audio_id = SDL_OpenAudioDevice(NULL, 0, &wave.spec, NULL, 0);
-
-    if (!g_audio_id) {
-        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Couldn't open audio: %s\n", SDL_GetError());
-        SDL_free(wave.sound);
-        quit(2);
-    }
-
-    /*static x[99999]; SDL_QueueAudio(1, x, sizeof (x));*/
-
-    /* Let the audio run */
-    SDL_PlayAudioDevice(g_audio_id);
-
-    done = 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. */
-
-#ifdef __EMSCRIPTEN__
-    emscripten_set_main_loop(loop, 0, 1);
-#else
-    while (!done && (SDL_GetAudioDeviceStatus(g_audio_id) == SDL_AUDIO_PLAYING)) {
-        loop();
-
-        SDL_Delay(100); /* let it play for a while. */
-    }
-#endif
-
-    /* Clean up on signal */
-    SDL_CloseAudioDevice(g_audio_id);
-    SDL_free(wave.sound);
-    SDL_free(filename);
-    SDL_Quit();
-    SDLTest_CommonDestroyState(state);
-    return 0;
-}

test/testaudio-art.txt

@@ -0,0 +1,8 @@
+The .bmp files used by testaudio.c were made by AlDraw:
+
+https://linktr.ee/AlexDraw
+
+They may be distributed as public domain files!
+
+
+

test/testaudio.c

@@ -0,0 +1,1064 @@
+#include <stdlib.h>
+
+#ifdef __EMSCRIPTEN__
+#include <emscripten/emscripten.h>
+#endif
+
+#include <SDL3/SDL_test.h>
+#include <SDL3/SDL_test_common.h>
+#include <SDL3/SDL_main.h>
+#include "testutils.h"
+
+#define POOF_LIFETIME 250
+
+typedef struct Texture
+{
+    SDL_Texture *texture;
+    float w;
+    float h;
+} Texture;
+
+typedef enum ThingType
+{
+    THING_NULL,
+    THING_PHYSDEV,
+    THING_PHYSDEV_CAPTURE,
+    THING_LOGDEV,
+    THING_LOGDEV_CAPTURE,
+    THING_TRASHCAN,
+    THING_STREAM,
+    THING_POOF,
+    THING_WAV
+} ThingType;
+
+
+typedef struct Thing Thing;
+
+struct Thing
+{
+    ThingType what;
+
+    union {
+        struct {
+            SDL_AudioDeviceID devid;
+            SDL_bool iscapture;
+            SDL_AudioSpec spec;
+            char *name;
+        } physdev;
+        struct {
+            SDL_AudioDeviceID devid;
+            SDL_bool iscapture;
+            SDL_AudioSpec spec;
+            Thing *physdev;
+        } logdev;
+        struct {
+            SDL_AudioSpec spec;
+            Uint8 *buf;
+            Uint32 buflen;
+        } wav;
+        struct {
+            float startw;
+            float starth;
+            float centerx;
+            float centery;
+        } poof;
+        struct {
+            SDL_AudioStream *stream;
+            int total_ticks;
+            Uint64 next_level_update;
+            Uint8 levels[5];
+        } stream;
+    } data;
+
+    Thing *line_connected_to;
+    char *titlebar;
+    SDL_FRect rect;
+    float z;
+    Uint8 r, g, b, a;
+    float progress;
+    float scale;
+    Uint64 createticks;
+    Texture *texture;
+    const ThingType *can_be_dropped_onto;
+
+    void (*ontick)(Thing *thing, Uint64 now);
+    void (*ondrag)(Thing *thing, int button, float x, float y);
+    void (*ondrop)(Thing *thing, int button, float x, float y);
+    void (*ondraw)(Thing *thing, SDL_Renderer *renderer);
+
+    Thing *prev;
+    Thing *next;
+};
+
+
+static Uint64 app_ready_ticks = 0;
+static int done = 0;
+static SDLTest_CommonState *state = NULL;
+
+static Thing *things = NULL;
+static char *current_titlebar = NULL;
+
+static Thing *droppable_highlighted_thing = NULL;
+static Thing *dragging_thing = NULL;
+static int dragging_button = -1;
+
+static Texture *physdev_texture = NULL;
+static Texture *logdev_texture = NULL;
+static Texture *audio_texture = NULL;
+static Texture *trashcan_texture = NULL;
+static Texture *soundboard_texture = NULL;
+static Texture *soundboard_levels_texture = NULL;
+
+static void DestroyTexture(Texture *tex);
+
+/* Call this instead of exit(), so we can clean up SDL: atexit() is evil. */
+static void Quit(int rc)
+{
+    DestroyTexture(physdev_texture);
+    DestroyTexture(logdev_texture);
+    DestroyTexture(audio_texture);
+    DestroyTexture(trashcan_texture);
+    DestroyTexture(soundboard_texture);
+    DestroyTexture(soundboard_levels_texture);
+    SDLTest_CommonQuit(state);
+    /* Let 'main()' return normally */
+    if (rc != 0) {
+        exit(rc);
+    }
+}
+
+static char *xstrdup(const char *str)
+{
+    char *ptr = SDL_strdup(str);
+    if (!ptr) {
+        SDL_Log("Out of memory!");
+        Quit(1);
+    }
+    return ptr;
+}
+
+static void *xalloc(const size_t len)
+{
+    void *ptr = SDL_calloc(1, len);
+    if (!ptr) {
+        SDL_Log("Out of memory!");
+        Quit(1);
+    }
+    return ptr;
+}
+
+
+static void SetTitleBar(const char *fmt, ...)
+{
+    char *newstr = NULL;
+    va_list ap;
+    va_start(ap, fmt);
+    SDL_vasprintf(&newstr, fmt, ap);
+    va_end(ap);
+
+    if (newstr && (!current_titlebar || (SDL_strcmp(current_titlebar, newstr) != 0))) {
+        SDL_SetWindowTitle(state->windows[0], newstr);
+        SDL_free(current_titlebar);
+        current_titlebar = newstr;
+    } else {
+        SDL_free(newstr);
+    }
+}
+
+static void SetDefaultTitleBar(void)
+{
+    SetTitleBar("testaudio: %s", SDL_GetCurrentAudioDriver());
+}
+
+static Thing *FindThingAtPoint(const float x, const float y)
+{
+    const SDL_FPoint pt = { x, y };
+    Thing *retval = NULL;
+    Thing *i;
+    for (i = things; i != NULL; i = i->next) {
+        if ((i != dragging_thing) && SDL_PointInRectFloat(&pt, &i->rect)) {
+            retval = i;  /* keep going, though, because things drawn on top are later in the list. */
+        }
+    }
+    return retval;
+}
+
+static Thing *UpdateMouseOver(const float x, const float y)
+{
+    Thing *thing;
+
+    if (dragging_thing) {
+        thing = dragging_thing;
+    } else {
+        thing = FindThingAtPoint(x, y);
+    }
+
+    if (!thing) {
+        SetDefaultTitleBar();
+    } else if (thing->titlebar) {
+        SetTitleBar("%s", thing->titlebar);
+    }
+
+    return thing;
+}
+
+static Thing *CreateThing(ThingType what, float x, float y, float z, float w, float h, Texture *texture, char *titlebar)
+{
+    Thing *last = NULL;
+    Thing *i;
+    Thing *thing;
+
+    thing = (Thing *) xalloc(sizeof (Thing));
+    if ((w < 0) || (h < 0)) {
+        SDL_assert(texture != NULL);
+        if (w < 0) {
+            w = texture->w;
+        }
+        if (h < 0) {
+            h = texture->h;
+        }
+    }
+
+    thing->what = what;
+    thing->rect.x = x;
+    thing->rect.y = y;
+    thing->rect.w = w;
+    thing->rect.h = h;
+    thing->z = z;
+    thing->r = 255;
+    thing->g = 255;
+    thing->b = 255;
+    thing->a = 255;
+    thing->scale = 1.0f;
+    thing->createticks = SDL_GetTicks();
+    thing->texture = texture;
+    thing->titlebar = titlebar;
+
+    /* insert in list by Z order (furthest from the "camera" first, so they get drawn over; negative Z is not drawn at all). */
+    if (things == NULL) {
+        things = thing;
+        return thing;
+    }
+
+    for (i = things; i != NULL; i = i->next) {
+        if (z > i->z) {  /* insert here. */
+            thing->next = i;
+            thing->prev = i->prev;
+
+            SDL_assert(i->prev == last);
+
+            if (i->prev) {
+                i->prev->next = thing;
+            } else {
+                SDL_assert(i == things);
+                things = thing;
+            }
+            i->prev = thing;
+            return thing;
+        }
+        last = i;
+    }
+
+    if (last) {
+        last->next = thing;
+        thing->prev = last;
+    }
+    return thing;
+}
+
+static void DestroyThing(Thing *thing)
+{
+    if (!thing) {
+        return;
+    }
+
+    switch (thing->what) {
+        case THING_POOF: break;
+        case THING_NULL: break;
+        case THING_TRASHCAN: break;
+        case THING_LOGDEV:
+        case THING_LOGDEV_CAPTURE:
+            SDL_CloseAudioDevice(thing->data.logdev.devid);
+            break;
+        case THING_PHYSDEV:
+        case THING_PHYSDEV_CAPTURE:
+            SDL_free(thing->data.physdev.name);
+            break;
+        case THING_WAV:
+            SDL_free(thing->data.wav.buf);
+            break;
+        case THING_STREAM:
+            SDL_DestroyAudioStream(thing->data.stream.stream);
+            break;
+    }
+
+    if (thing->prev) {
+        thing->prev->next = thing->next;
+    } else {
+        SDL_assert(thing == things);
+        things = thing->next;
+    }
+
+    if (thing->next) {
+        thing->next->prev = thing->prev;
+    }
+
+    SDL_free(thing->titlebar);
+    SDL_free(thing);
+}
+
+static void DrawOneThing(SDL_Renderer *renderer, Thing *thing)
+{
+    SDL_FRect dst;
+    SDL_memcpy(&dst, &thing->rect, sizeof (SDL_FRect));
+    if (thing->scale != 1.0f) {
+        const float centerx = thing->rect.x + (thing->rect.w / 2);
+        const float centery = thing->rect.y + (thing->rect.h / 2);
+        SDL_assert(thing->texture != NULL);
+        dst.w = thing->texture->w * thing->scale;
+        dst.h = thing->texture->h * thing->scale;
+        dst.x = centerx - (dst.w / 2);
+        dst.y = centery - (dst.h / 2);
+    }
+
+    if (thing->texture) {
+        if (droppable_highlighted_thing == thing) {
+            SDL_SetRenderDrawColor(renderer, 255, 0, 255, 100);
+            SDL_RenderFillRect(renderer, &dst);
+        }
+        SDL_SetRenderDrawColor(renderer, thing->r, thing->g, thing->b, thing->a);
+        SDL_RenderTexture(renderer, thing->texture->texture, NULL, &dst);
+    } else {
+        SDL_SetRenderDrawColor(renderer, thing->r, thing->g, thing->b, thing->a);
+        SDL_RenderFillRect(renderer, &dst);
+    }
+
+    if (thing->ondraw) {
+        thing->ondraw(thing, renderer);
+    }
+
+    if (thing->progress > 0.0f) {
+        SDL_FRect r = { thing->rect.x, thing->rect.y + (thing->rect.h + 2.0f), 0.0f, 10.0f };
+        r.w = thing->rect.w * ((thing->progress > 1.0f) ? 1.0f : thing->progress);
+        SDL_SetRenderDrawColor(renderer, 255, 255, 255, 128);
+        SDL_RenderFillRect(renderer, &r);
+    }
+}
+
+static void DrawThings(SDL_Renderer *renderer)
+{
+    Thing *i;
+
+    /* draw connecting lines first, so they're behind everything else. */
+    for (i = things; i && (i->z >= 0.0f); i = i->next) {
+        Thing *dst = i->line_connected_to;
+        if (dst) {
+            SDL_SetRenderDrawColor(renderer, 255, 0, 0, 255);
+            SDL_RenderLine(renderer, i->rect.x + (i->rect.w / 2), i->rect.y + (i->rect.h / 2), dst->rect.x + (dst->rect.w / 2), dst->rect.y + (dst->rect.h / 2));
+        }
+    }
+
+    /* Draw the actual things. */
+    for (i = things; i && (i->z >= 0.0f); i = i->next) {
+        if (i != dragging_thing) {
+            DrawOneThing(renderer, i);
+        }
+    }
+
+    if (dragging_thing) {
+        DrawOneThing(renderer, dragging_thing);  /* draw last so it's always on top. */
+    }
+}
+
+static void Draw(void)
+{
+    SDL_Renderer *renderer = state->renderers[0];
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+    SDL_SetRenderDrawColor(renderer, 64, 0, 64, 255);
+    SDL_RenderClear(renderer);
+    DrawThings(renderer);
+    SDL_RenderPresent(renderer);
+}
+
+static void RepositionRowOfThings(const ThingType what, const float y)
+{
+    int total_things = 0;
+    float texw = 0.0f;
+    float texh = 0.0f;
+    Thing *i;
+
+    for (i = things; i != NULL; i = i->next) {
+        if (i->what == what) {
+            texw = i->rect.w;
+            texh = i->rect.h;
+            total_things++;
+        }
+    }
+
+    if (total_things > 0) {
+        int w, h;
+        SDL_GetWindowSize(state->windows[0], &w, &h);
+        const float spacing = w / ((float) total_things);
+        float x = (spacing - texw) / 2.0f;
+        for (i = things; i != NULL; i = i->next) {
+            if (i->what == what) {
+                i->rect.x = x;
+                i->rect.y = (y >= 0.0f) ? y : ((h + y) - texh);
+                x += spacing;
+            }
+        }
+    }
+}
+
+static const char *AudioFmtToString(const SDL_AudioFormat fmt)
+{
+    switch (fmt) {
+        #define FMTCASE(x) case SDL_AUDIO_##x: return #x
+        FMTCASE(U8);
+        FMTCASE(S8);
+        FMTCASE(S16LSB);
+        FMTCASE(S16MSB);
+        FMTCASE(S32LSB);
+        FMTCASE(S32MSB);
+        FMTCASE(F32LSB);
+        FMTCASE(F32MSB);
+        #undef FMTCASE
+    }
+    return "?";
+}
+
+static const char *AudioChansToStr(const int channels)
+{
+    switch (channels) {
+        case 1: return "mono";
+        case 2: return "stereo";
+        case 3: return "2.1";
+        case 4: return "quad";
+        case 5: return "4.1";
+        case 6: return "5.1";
+        case 7: return "6.1";
+        case 8: return "7.1";
+        default: break;
+    }
+    return "?";
+}
+
+static void PoofThing_ondrag(Thing *thing, int button, float x, float y)
+{
+    dragging_thing = NULL;   /* refuse to be dragged. */
+}
+
+static void PoofThing_ontick(Thing *thing, Uint64 now)
+{
+    const int lifetime = POOF_LIFETIME;
+    const int elasped = (int) (now - thing->createticks);
+    if (elasped > lifetime) {
+        DestroyThing(thing);
+    } else {
+        const float pct = ((float) elasped) / ((float) lifetime);
+        thing->a = (Uint8) (int) (255.0f - (pct * 255.0f));
+        thing->scale = 1.0f - pct;  /* shrink to nothing! */
+    }
+}
+
+static Thing *CreatePoofThing(Thing *poofing_thing)
+{
+    const float centerx = poofing_thing->rect.x + (poofing_thing->rect.w / 2);
+    const float centery = poofing_thing->rect.y + (poofing_thing->rect.h / 2);
+    const float z = poofing_thing->z;
+    Thing *thing = CreateThing(THING_POOF, poofing_thing->rect.x, poofing_thing->rect.y, z, poofing_thing->rect.w, poofing_thing->rect.h, poofing_thing->texture, NULL);
+    thing->data.poof.startw = poofing_thing->rect.w;
+    thing->data.poof.starth = poofing_thing->rect.h;
+    thing->data.poof.centerx = centerx;
+    thing->data.poof.centery = centery;
+    thing->ontick = PoofThing_ontick;
+    thing->ondrag = PoofThing_ondrag;
+    return thing;
+}
+
+static void DestroyThingInPoof(Thing *thing)
+{
+    if (thing) {
+        if (thing->what != THING_POOF) {
+            CreatePoofThing(thing);
+        }
+        DestroyThing(thing);
+    }
+}
+
+/* this poofs a thing and additionally poofs all things connected to the thing. */
+static void TrashThing(Thing *thing)
+{
+    Thing *i, *next;
+    for (i = things; i != NULL; i = next) {
+        next = i->next;
+        if (i->line_connected_to == thing) {
+            TrashThing(i);
+            next = things;  /* start over in case this blew up the list. */
+        }
+    }
+    DestroyThingInPoof(thing);
+}
+
+static void StreamThing_ontick(Thing *thing, Uint64 now)
+{
+    if (!thing->line_connected_to) {
+        return;
+    }
+
+    /* are we playing? See if we're done, or update state. */
+    if (thing->line_connected_to->what == THING_LOGDEV) {
+        const int available = SDL_GetAudioStreamAvailable(thing->data.stream.stream);
+        SDL_AudioSpec spec;
+        if (!available || (SDL_GetAudioStreamFormat(thing->data.stream.stream, NULL, &spec) < 0)) {
+            DestroyThingInPoof(thing);
+        } else {
+            const int ticksleft = (int) ((((Uint64) ((available / (SDL_AUDIO_BITSIZE(spec.format) / 8)) / spec.channels)) * 1000) / spec.freq);
+            const float pct = thing->data.stream.total_ticks ? (((float) (ticksleft)) / ((float) thing->data.stream.total_ticks)) : 0.0f;
+            thing->progress = 1.0f - pct;
+        }
+    }
+
+    if (thing->data.stream.next_level_update <= now) {
+        Uint64 perf = SDL_GetPerformanceCounter();
+        int i;
+        for (i = 0; i < SDL_arraysize(thing->data.stream.levels); i++) {
+            thing->data.stream.levels[i] = (Uint8) (perf % 6);
+            perf >>= 3;
+        }
+        thing->data.stream.next_level_update += 150;
+    }
+}
+
+static void StreamThing_ondrag(Thing *thing, int button, float x, float y)
+{
+    if (button == SDL_BUTTON_RIGHT) {  /* this is kinda hacky, but use this to disconnect from a playing source. */
+        if (thing->line_connected_to) {
+            SDL_UnbindAudioStream(thing->data.stream.stream); /* unbind from current device */
+            thing->line_connected_to = NULL;
+        }
+    }
+}
+
+static void StreamThing_ondrop(Thing *thing, int button, float x, float y)
+{
+    if (droppable_highlighted_thing) {
+        if (droppable_highlighted_thing->what == THING_TRASHCAN) {
+            TrashThing(thing);
+        } else if (((droppable_highlighted_thing->what == THING_LOGDEV) || (droppable_highlighted_thing->what == THING_LOGDEV_CAPTURE)) && (droppable_highlighted_thing != thing->line_connected_to)) {
+            /* connect to a logical device! */
+            SDL_Log("Binding audio stream ('%s') to logical device %u", thing->titlebar, (unsigned int) droppable_highlighted_thing->data.logdev.devid);
+            if (thing->line_connected_to) {
+                const SDL_AudioSpec *spec = &droppable_highlighted_thing->data.logdev.spec;
+                SDL_UnbindAudioStream(thing->data.stream.stream); /* unbind from current device */
+                if (thing->line_connected_to->what == THING_LOGDEV_CAPTURE) {
+                    SDL_FlushAudioStream(thing->data.stream.stream);
+                    thing->data.stream.total_ticks = (int) (((((Uint64) (SDL_GetAudioStreamAvailable(thing->data.stream.stream) / (SDL_AUDIO_BITSIZE(spec->format) / 8))) / spec->channels) * 1000) / spec->freq);
+                }
+            }
+
+            SDL_BindAudioStream(droppable_highlighted_thing->data.logdev.devid, thing->data.stream.stream); /* bind to new device! */
+
+            thing->progress = 0.0f;  /* ontick will adjust this if we're on an output device.*/
+            thing->data.stream.next_level_update = SDL_GetTicks() + 100;
+            thing->line_connected_to = droppable_highlighted_thing;
+        }
+    }
+}
+
+static void StreamThing_ondraw(Thing *thing, SDL_Renderer *renderer)
+{
+    if (thing->line_connected_to) {  /* are we playing? Update progress bar, and bounce the levels a little. */
+        static const float xlocs[5] = { 18, 39, 59, 79, 99 };
+        static const float ylocs[5] = { 49, 39, 29, 19, 10 };
+        const float blockw = soundboard_levels_texture->w;
+        const float blockh = soundboard_levels_texture->h / 5.0f;
+        int i, j;
+        SDL_SetRenderDrawColor(renderer, thing->r, thing->g, thing->b, thing->a);
+        for (i = 0; i < SDL_arraysize(thing->data.stream.levels); i++) {
+            const int level = (int) thing->data.stream.levels[i];
+            const float x = xlocs[i];
+            for (j = 0; j < level; j++) {
+                const SDL_FRect src = { 0, soundboard_levels_texture->h - ((j+1) * blockh), blockw, blockh };
+                const SDL_FRect dst = { thing->rect.x + x, thing->rect.y + ylocs[j], blockw, blockh };
+                SDL_RenderTexture(renderer, soundboard_levels_texture->texture, &src, &dst);
+            }
+        }
+    }
+}
+
+static Thing *CreateStreamThing(const SDL_AudioSpec *spec, const Uint8 *buf, const Uint32 buflen, const char *fname, const float x, const float y)
+{
+    static const ThingType can_be_dropped_onto[] = { THING_TRASHCAN, THING_LOGDEV, THING_LOGDEV_CAPTURE, THING_NULL };
+    Thing *thing = CreateThing(THING_STREAM, x, y, 0, -1, -1, soundboard_texture, fname ? xstrdup(fname) : NULL);
+    SDL_Log("Adding audio stream for %s", fname ? fname : "(null)");
+    thing->data.stream.stream = SDL_CreateAudioStream(spec, spec);
+    if (buf && buflen) {
+        SDL_PutAudioStreamData(thing->data.stream.stream, buf, (int) buflen);
+        SDL_FlushAudioStream(thing->data.stream.stream);
+        thing->data.stream.total_ticks = (int) (((((Uint64) (SDL_GetAudioStreamAvailable(thing->data.stream.stream) / (SDL_AUDIO_BITSIZE(spec->format) / 8))) / spec->channels) * 1000) / spec->freq);
+    }
+    thing->ontick = StreamThing_ontick;
+    thing->ondrag = StreamThing_ondrag;
+    thing->ondrop = StreamThing_ondrop;
+    thing->ondraw = StreamThing_ondraw;
+    thing->can_be_dropped_onto = can_be_dropped_onto;
+    return thing;
+}
+
+static void WavThing_ondrag(Thing *thing, int button, float x, float y)
+{
+    if (button == SDL_BUTTON_RIGHT) {  /* drag out a new audio stream. */
+        dragging_thing = CreateStreamThing(&thing->data.wav.spec, thing->data.wav.buf, thing->data.wav.buflen, thing->titlebar, x - (thing->rect.w / 2), y - (thing->rect.h / 2));
+    }
+}
+
+static void WavThing_ondrop(Thing *thing, int button, float x, float y)
+{
+    if (droppable_highlighted_thing) {
+        if (droppable_highlighted_thing->what == THING_TRASHCAN) {
+            TrashThing(thing);
+        }
+    }
+}
+
+static Thing *LoadWavThing(const char *fname, float x, float y)
+{
+    Thing *thing = NULL;
+    char *path;
+    SDL_AudioSpec spec;
+    Uint8 *buf = NULL;
+    Uint32 buflen = 0;
+
+    path = GetNearbyFilename(fname);
+    if (path) {
+        fname = path;
+    }
+
+    if (SDL_LoadWAV(fname, &spec, &buf, &buflen) == 0) {
+        static const ThingType can_be_dropped_onto[] = { THING_TRASHCAN, THING_NULL };
+        char *titlebar = NULL;
+        const char *nodirs = SDL_strrchr(fname, '/');
+        #ifdef __WINDOWS__
+        const char *nodirs2 = SDL_strrchr(nodirs ? nodirs : fname, '\\');
+        if (nodirs2) {
+            nodirs = nodirs2;
+        }
+        #endif
+
+        SDL_Log("Adding WAV file '%s'", fname);
+
+        if (nodirs) {
+            nodirs++;
+        } else {
+            nodirs = fname;
+        }
+
+        SDL_asprintf(&titlebar, "WAV file (\"%s\", %s, %s, %uHz)", nodirs, AudioFmtToString(spec.format), AudioChansToStr(spec.channels), (unsigned int) spec.freq);
+        thing = CreateThing(THING_WAV, x - (audio_texture->w / 2), y - (audio_texture->h / 2), 5, -1, -1, audio_texture, titlebar);
+        SDL_memcpy(&thing->data.wav.spec, &spec, sizeof (SDL_AudioSpec));
+        thing->data.wav.buf = buf;
+        thing->data.wav.buflen = buflen;
+        thing->can_be_dropped_onto = can_be_dropped_onto;
+        thing->ondrag = WavThing_ondrag;
+        thing->ondrop = WavThing_ondrop;
+    }
+
+    SDL_free(path);
+
+    return thing;
+}
+
+static Thing *LoadStockWavThing(const char *fname)
+{
+    char *path = GetNearbyFilename(fname);
+    Thing *thing = LoadWavThing(path ? path : fname, 0.0f, 0.0f);  /* will reposition in a moment. */
+    SDL_free(path);
+    return thing;
+}
+
+static void LoadStockWavThings(void)
+{
+    LoadStockWavThing("sample.wav");
+    RepositionRowOfThings(THING_WAV, -10.0f);
+}
+
+static void DestroyTexture(Texture *tex)
+{
+    if (tex) {
+        SDL_DestroyTexture(tex->texture);
+        SDL_free(tex);
+    }
+}
+
+static Texture *CreateTexture(const char *fname)
+{
+    Texture *tex = (Texture *) xalloc(sizeof (Texture));
+    int texw, texh;
+    tex->texture = LoadTexture(state->renderers[0], fname, SDL_TRUE, &texw, &texh);
+    if (!tex->texture) {
+        SDL_Log("Failed to load '%s': %s", fname, SDL_GetError());
+        SDL_free(tex);
+        Quit(1);
+    }
+    SDL_SetTextureBlendMode(tex->texture, SDL_BLENDMODE_BLEND);
+    tex->w = (float) texw;
+    tex->h = (float) texh;
+    return tex;
+}
+
+static Thing *CreateLogicalDeviceThing(Thing *parent, const SDL_AudioDeviceID which, const float x, const float y);
+
+static void DeviceThing_ondrag(Thing *thing, int button, float x, float y)
+{
+    if ((button == SDL_BUTTON_MIDDLE) && (thing->what == THING_LOGDEV_CAPTURE)) {  /* drag out a new stream. This is a UX mess. :/ */
+        dragging_thing = CreateStreamThing(&thing->data.logdev.spec, NULL, 0, NULL, x, y);
+        dragging_thing->data.stream.next_level_update = SDL_GetTicks() + 100;
+        SDL_BindAudioStream(thing->data.logdev.devid, dragging_thing->data.stream.stream); /* bind to new device! */
+        dragging_thing->line_connected_to = thing;
+    } else if (button == SDL_BUTTON_RIGHT) {  /* drag out a new logical device. */
+        const SDL_AudioDeviceID which = ((thing->what == THING_LOGDEV) || (thing->what == THING_LOGDEV_CAPTURE)) ? thing->data.logdev.devid : thing->data.physdev.devid;
+        const SDL_AudioDeviceID devid = SDL_OpenAudioDevice(which, NULL);
+        dragging_thing = devid ? CreateLogicalDeviceThing(thing, devid, x - (thing->rect.w / 2), y - (thing->rect.h / 2)) : NULL;
+    }
+}
+
+static void SetLogicalDeviceTitlebar(Thing *thing)
+{
+    SDL_AudioSpec *spec = &thing->data.logdev.spec;
+    SDL_GetAudioDeviceFormat(thing->data.logdev.devid, spec);
+    SDL_asprintf(&thing->titlebar, "Logical device #%u (%s, %s, %s, %uHz)", (unsigned int) thing->data.logdev.devid, thing->data.logdev.iscapture ? "CAPTURE" : "OUTPUT", AudioFmtToString(spec->format), AudioChansToStr(spec->channels), (unsigned int) spec->freq);
+}
+
+static void LogicalDeviceThing_ondrop(Thing *thing, int button, float x, float y)
+{
+    if (droppable_highlighted_thing) {
+        if (droppable_highlighted_thing->what == THING_TRASHCAN) {
+            TrashThing(thing);
+        }
+    }
+}
+
+static Thing *CreateLogicalDeviceThing(Thing *parent, const SDL_AudioDeviceID which, const float x, const float y)
+{
+    static const ThingType can_be_dropped_onto[] = { THING_TRASHCAN, THING_NULL };
+    Thing *physthing = ((parent->what == THING_LOGDEV) || (parent->what == THING_LOGDEV_CAPTURE)) ? parent->data.logdev.physdev : parent;
+    const SDL_bool iscapture = physthing->data.physdev.iscapture;
+    Thing *thing;
+
+    SDL_Log("Adding logical audio device %u", (unsigned int) which);
+    thing = CreateThing(iscapture ? THING_LOGDEV_CAPTURE : THING_LOGDEV, x, y, 5, -1, -1, logdev_texture, NULL);
+    thing->data.logdev.devid = which;
+    thing->data.logdev.iscapture = iscapture;
+    thing->data.logdev.physdev = physthing;
+    thing->line_connected_to = physthing;
+    thing->ondrag = DeviceThing_ondrag;
+    thing->ondrop = LogicalDeviceThing_ondrop;
+    thing->can_be_dropped_onto = can_be_dropped_onto;
+
+    SetLogicalDeviceTitlebar(thing);
+    return thing;
+}
+
+static void SetPhysicalDeviceTitlebar(Thing *thing)
+{
+    SDL_AudioSpec *spec = &thing->data.physdev.spec;
+    SDL_GetAudioDeviceFormat(thing->data.physdev.devid, spec);
+    if (thing->data.physdev.devid == SDL_AUDIO_DEVICE_DEFAULT_CAPTURE) {
+        SDL_asprintf(&thing->titlebar, "Default system device (CAPTURE, %s, %s, %uHz)", AudioFmtToString(spec->format), AudioChansToStr(spec->channels), (unsigned int) spec->freq);
+    } else if (thing->data.physdev.devid == SDL_AUDIO_DEVICE_DEFAULT_OUTPUT) {
+        SDL_asprintf(&thing->titlebar, "Default system device (OUTPUT, %s, %s, %uHz)", AudioFmtToString(spec->format), AudioChansToStr(spec->channels), (unsigned int) spec->freq);
+    } else {
+        SDL_asprintf(&thing->titlebar, "Physical device #%u (%s, \"%s\", %s, %s, %uHz)", (unsigned int) thing->data.physdev.devid, thing->data.physdev.iscapture ? "CAPTURE" : "OUTPUT", thing->data.physdev.name, AudioFmtToString(spec->format), AudioChansToStr(spec->channels), (unsigned int) spec->freq);
+    }
+}
+
+static void PhysicalDeviceThing_ondrop(Thing *thing, int button, float x, float y)
+{
+    if (droppable_highlighted_thing) {
+        if (droppable_highlighted_thing->what == THING_TRASHCAN) {
+            TrashThing(thing);
+        }
+    }
+}
+
+static void PhysicalDeviceThing_ontick(Thing *thing, Uint64 now)
+{
+    const int lifetime = POOF_LIFETIME;
+    const int elasped = (int) (now - thing->createticks);
+    if (elasped > lifetime) {
+        thing->scale = 1.0f;
+        thing->a = 255;
+        thing->ontick = NULL;  /* no more ticking. */
+    } else {
+        const float pct = ((float) elasped) / ((float) lifetime);
+        thing->a = (Uint8) (int) (pct * 255.0f);
+        thing->scale = pct;  /* grow to normal size */
+    }
+}
+
+
+static Thing *CreatePhysicalDeviceThing(const SDL_AudioDeviceID which, const SDL_bool iscapture)
+{
+    static const ThingType can_be_dropped_onto[] = { THING_TRASHCAN, THING_NULL };
+    static float next_physdev_x = 0;
+    Thing *thing;
+    int winw, winh;
+
+    SDL_GetWindowSize(state->windows[0], &winw, &winh);
+    if (next_physdev_x > (winw-physdev_texture->w)) {
+        next_physdev_x = 0;
+    }
+
+    SDL_Log("Adding physical audio device %u", (unsigned int) which);
+    thing = CreateThing(iscapture ? THING_PHYSDEV_CAPTURE : THING_PHYSDEV, next_physdev_x, 170, 5, -1, -1, physdev_texture, NULL);
+    thing->data.physdev.devid = which;
+    thing->data.physdev.iscapture = iscapture;
+    thing->data.physdev.name = SDL_GetAudioDeviceName(which);
+    thing->ondrag = DeviceThing_ondrag;
+    thing->ondrop = PhysicalDeviceThing_ondrop;
+    thing->ontick = PhysicalDeviceThing_ontick;
+    thing->can_be_dropped_onto = can_be_dropped_onto;
+
+    SetPhysicalDeviceTitlebar(thing);
+    if (SDL_GetTicks() <= (app_ready_ticks + 2000)) {  /* assume this is the initial batch if it happens in the first two seconds. */
+        RepositionRowOfThings(THING_PHYSDEV, 10.0f);  /* don't rearrange them after the initial add. */
+        RepositionRowOfThings(THING_PHYSDEV_CAPTURE, 170.0f);  /* don't rearrange them after the initial add. */
+        next_physdev_x = 0.0f;
+    } else {
+        next_physdev_x += physdev_texture->w * 1.5f;
+    }
+
+    return thing;
+}
+
+static Thing *CreateTrashcanThing(void)
+{
+    int winw, winh;
+    SDL_GetWindowSize(state->windows[0], &winw, &winh);
+    return CreateThing(THING_TRASHCAN, winw - trashcan_texture->w, winh - trashcan_texture->h, 10, -1, -1, trashcan_texture, "Drag things here to remove them.");
+}
+
+static Thing *CreateDefaultPhysicalDevice(const SDL_bool iscapture)
+{
+    return CreatePhysicalDeviceThing(iscapture ? SDL_AUDIO_DEVICE_DEFAULT_CAPTURE : SDL_AUDIO_DEVICE_DEFAULT_OUTPUT, iscapture);
+}
+
+static void TickThings(void)
+{
+    Thing *i;
+    Thing *next;
+    const Uint64 now = SDL_GetTicks();
+    for (i = things; i != NULL; i = next) {
+        next = i->next;  /* in case this deletes itself. */
+        if (i->ontick) {
+            i->ontick(i, now);
+        }
+    }
+}
+
+static void WindowResized(const int newwinw, const int newwinh)
+{
+    Thing *i;
+    const float neww = (float) newwinw;
+    const float newh = (float) newwinh;
+    const float oldw = (float) state->window_w;
+    const float oldh = (float) state->window_h;
+    for (i = things; i != NULL; i = i->next) {
+        const float halfw = i->rect.w / 2.0f;
+        const float halfh = i->rect.h / 2.0f;
+        const float x = (i->rect.x + halfw) / oldw;
+        const float y = (i->rect.y + halfh) / oldh;
+        i->rect.x = (x * neww) - halfw;
+        i->rect.y = (y * newh) - halfh;
+    }
+    state->window_w = newwinw;
+    state->window_h = newwinh;
+}
+
+
+static void Loop(void)
+{
+    SDL_Event event;
+    SDL_bool saw_event = SDL_FALSE;
+
+    if (app_ready_ticks == 0) {
+        app_ready_ticks = SDL_GetTicks();
+    }
+
+    while (SDL_PollEvent(&event)) {
+        Thing *thing = NULL;
+
+        saw_event = SDL_TRUE;
+
+        switch (event.type) {
+            case SDL_EVENT_MOUSE_MOTION:
+                thing = UpdateMouseOver(event.motion.x, event.motion.y);
+                if ((dragging_button == -1) && event.motion.state) {
+                    if (event.motion.state & SDL_BUTTON_LMASK) {
+                        dragging_button = SDL_BUTTON_LEFT;
+                    } else if (event.motion.state & SDL_BUTTON_RMASK) {
+                        dragging_button = SDL_BUTTON_RIGHT;
+                    } else if (event.motion.state & SDL_BUTTON_MMASK) {
+                        dragging_button = SDL_BUTTON_MIDDLE;
+                    }
+
+
+                    if (dragging_button != -1) {
+                        dragging_thing = thing;
+                        if (thing && thing->ondrag) {
+                            thing->ondrag(thing, dragging_button, event.motion.x, event.motion.y);
+                        }
+                    }
+                }
+
+                droppable_highlighted_thing = NULL;
+                if (dragging_thing) {
+                    dragging_thing->rect.x = event.motion.x - (dragging_thing->rect.w / 2);
+                    dragging_thing->rect.y = event.motion.y - (dragging_thing->rect.h / 2);
+                    if (dragging_thing->can_be_dropped_onto) {
+                        thing = FindThingAtPoint(event.motion.x, event.motion.y);
+                        if (thing) {
+                            int i;
+                            for (i = 0; dragging_thing->can_be_dropped_onto[i]; i++) {
+                                if (dragging_thing->can_be_dropped_onto[i] == thing->what) {
+                                    droppable_highlighted_thing = thing;
+                                    break;
+                                }
+                            }
+                        }
+                    }
+                }
+                break;
+
+            case SDL_EVENT_MOUSE_BUTTON_DOWN:
+                thing = UpdateMouseOver(event.button.x, event.button.y);
+                break;
+
+            case SDL_EVENT_MOUSE_BUTTON_UP:
+                if (dragging_button == event.button.button) {
+                    Thing *dropped_thing = dragging_thing;
+                    dragging_thing = NULL;
+                    dragging_button = -1;
+                    if (dropped_thing && dropped_thing->ondrop) {
+                        dropped_thing->ondrop(dropped_thing, event.button.button, event.button.x, event.button.y);
+                    }
+                    droppable_highlighted_thing = NULL;
+                }
+                thing = UpdateMouseOver(event.button.x, event.button.y);
+                break;
+
+            case SDL_EVENT_MOUSE_WHEEL:
+                UpdateMouseOver(event.wheel.mouseX, event.wheel.mouseY);
+                break;
+
+            case SDL_EVENT_DROP_FILE:
+                SDL_Log("Drop file! '%s'", event.drop.file);
+                LoadWavThing(event.drop.file, event.drop.x, event.drop.y);
+                /* SDLTest_CommonEvent will free the string, below. */
+                break;
+
+            case SDL_EVENT_WINDOW_RESIZED:
+                WindowResized(event.window.data1, event.window.data2);
+                break;
+
+            case SDL_EVENT_AUDIO_DEVICE_ADDED:
+                CreatePhysicalDeviceThing(event.adevice.which, event.adevice.iscapture);
+                break;
+    
+            case SDL_EVENT_AUDIO_DEVICE_REMOVED: {
+                const SDL_AudioDeviceID which = event.adevice.which;
+                Thing *i, *next;
+                SDL_Log("Removing audio device %u", (unsigned int) which);
+                for (i = things; i != NULL; i = next) {
+                    next = i->next;
+                    if (((i->what == THING_PHYSDEV) || (i->what == THING_PHYSDEV_CAPTURE)) && (i->data.physdev.devid == which)) {
+                        TrashThing(i);
+                        next = things;  /* in case we mangled the list. */
+                    } else if (((i->what == THING_LOGDEV) || (i->what == THING_LOGDEV_CAPTURE)) && (i->data.logdev.devid == which)) {
+                        TrashThing(i);
+                        next = things;  /* in case we mangled the list. */
+                    }
+                }
+                break;
+            }
+
+            default: break;
+        }
+
+        SDLTest_CommonEvent(state, &event, &done);
+    }
+
+    TickThings();
+    Draw();
+
+    if (!saw_event) {
+        SDL_Delay(10);
+    }
+
+    #ifdef __EMSCRIPTEN__
+    if (done) {
+        emscripten_cancel_main_loop();
+    }
+    #endif
+}
+
+int main(int argc, char *argv[])
+{
+    int i;
+
+    state = SDLTest_CommonCreateState(argv, SDL_INIT_VIDEO | SDL_INIT_AUDIO);
+    if (state == NULL) {
+        Quit(1);
+    }
+
+    state->window_flags |= SDL_WINDOW_RESIZABLE;
+
+    for (i = 1; i < argc;) {
+        int consumed = SDLTest_CommonArg(state, i);
+        if (consumed == 0) {
+            consumed = -1;
+            /* add our own command lines here. */
+        }
+        if (consumed < 0) {
+            static const char *options[] = {
+                /* add our own command lines here. */
+                /*"[--blend none|blend|add|mod|mul|sub]",*/
+                NULL
+            };
+            SDLTest_CommonLogUsage(state, argv[0], options);
+            Quit(1);
+        }
+        i += consumed;
+    }
+
+    if (!SDLTest_CommonInit(state)) {
+        Quit(2);
+    }
+
+    SetDefaultTitleBar();
+
+    physdev_texture = CreateTexture("physaudiodev.bmp");
+    logdev_texture = CreateTexture("logaudiodev.bmp");
+    audio_texture = CreateTexture("audiofile.bmp");
+    trashcan_texture = CreateTexture("trashcan.bmp");
+    soundboard_texture = CreateTexture("soundboard.bmp");
+    soundboard_levels_texture = CreateTexture("soundboard_levels.bmp");
+
+    LoadStockWavThings();
+    CreateTrashcanThing();
+    CreateDefaultPhysicalDevice(SDL_FALSE);
+    CreateDefaultPhysicalDevice(SDL_TRUE);
+
+#ifdef __EMSCRIPTEN__
+    emscripten_set_main_loop(Loop, 0, 1);
+#else
+    while (!done) {
+        Loop();
+    }
+#endif
+
+    Quit(0);
+    return 0;
+}
+

test/testaudiocapture.c

@@ -22,13 +22,14 @@
 
 static SDL_Window *window = NULL;
 static SDL_Renderer *renderer = NULL;
-static SDL_AudioSpec spec;
-static SDL_AudioDeviceID devid_in = 0;
-static SDL_AudioDeviceID devid_out = 0;
+static SDL_AudioStream *stream_in = NULL;
+static SDL_AudioStream *stream_out = NULL;
 static int done = 0;
 
 static void loop(void)
 {
+    const SDL_AudioDeviceID devid_in = SDL_GetAudioStreamBinding(stream_in);
+    const SDL_AudioDeviceID devid_out = SDL_GetAudioStreamBinding(stream_out);
     SDL_bool please_quit = SDL_FALSE;
     SDL_Event e;
 
@@ -42,17 +43,18 @@ static void loop(void)
         } else if (e.type == SDL_EVENT_MOUSE_BUTTON_DOWN) {
             if (e.button.button == 1) {
                 SDL_PauseAudioDevice(devid_out);
-                SDL_PlayAudioDevice(devid_in);
+                SDL_UnpauseAudioDevice(devid_in);
             }
         } else if (e.type == SDL_EVENT_MOUSE_BUTTON_UP) {
             if (e.button.button == 1) {
                 SDL_PauseAudioDevice(devid_in);
-                SDL_PlayAudioDevice(devid_out);
+                SDL_FlushAudioStream(stream_in);  /* so no samples are held back for resampling purposes. */
+                SDL_UnpauseAudioDevice(devid_out);
             }
         }
     }
 
-    if (SDL_GetAudioDeviceStatus(devid_in) == SDL_AUDIO_PLAYING) {
+    if (!SDL_IsAudioDevicePaused(devid_in)) {
         SDL_SetRenderDrawColor(renderer, 0, 255, 0, 255);
     } else {
         SDL_SetRenderDrawColor(renderer, 255, 0, 0, 255);
@@ -60,13 +62,26 @@ static void loop(void)
     SDL_RenderClear(renderer);
     SDL_RenderPresent(renderer);
 
+    /* Feed any new data we captured to the output stream. It'll play when we unpause the device. */
+    while (!please_quit && (SDL_GetAudioStreamAvailable(stream_in) > 0)) {
+        Uint8 buf[1024];
+        const int br = SDL_GetAudioStreamData(stream_in, buf, sizeof(buf));
+        if (br < 0) {
+            SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Failed to read from input audio stream: %s\n", SDL_GetError());
+            please_quit = 1;
+        } else if (SDL_PutAudioStreamData(stream_out, buf, br) < 0) {
+            SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Failed to write to output audio stream: %s\n", SDL_GetError());
+            please_quit = 1;
+        }
+    }
+
     if (please_quit) {
         /* stop playing back, quit. */
         SDL_Log("Shutting down.\n");
-        SDL_PauseAudioDevice(devid_in);
         SDL_CloseAudioDevice(devid_in);
-        SDL_PauseAudioDevice(devid_out);
         SDL_CloseAudioDevice(devid_out);
+        SDL_DestroyAudioStream(stream_in);
+        SDL_DestroyAudioStream(stream_out);
         SDL_DestroyRenderer(renderer);
         SDL_DestroyWindow(window);
         SDL_Quit();
@@ -77,28 +92,17 @@ static void loop(void)
         done = 1;
         return;
     }
-
-    /* Note that it would be easier to just have a one-line function that
-        calls SDL_QueueAudio() as a capture device callback, but we're
-        trying to test the API, so we use SDL_DequeueAudio() here. */
-    while (SDL_TRUE) {
-        Uint8 buf[1024];
-        const Uint32 br = SDL_DequeueAudio(devid_in, buf, sizeof(buf));
-        SDL_QueueAudio(devid_out, buf, br);
-        if (br < sizeof(buf)) {
-            break;
-        }
-    }
 }
 
 int main(int argc, char **argv)
 {
-    /* (NULL means "open default device.") */
+    SDL_AudioDeviceID *devices;
+    SDLTest_CommonState *state;
+    SDL_AudioSpec spec;
+    SDL_AudioDeviceID device;
+    SDL_AudioDeviceID want_device = SDL_AUDIO_DEVICE_DEFAULT_CAPTURE;
     const char *devname = NULL;
-    SDL_AudioSpec wanted;
-    int devcount;
     int i;
-    SDLTest_CommonState *state;
 
     /* Initialize test framework */
     state = SDLTest_CommonCreateState(argv, 0);
@@ -121,7 +125,7 @@ int main(int argc, char **argv)
             }
         }
         if (consumed <= 0) {
-            static const char *options[] = { "[driver_name]", NULL };
+            static const char *options[] = { "[device_name]", NULL };
             SDLTest_CommonLogUsage(state, argv[0], options);
             exit(1);
         }
@@ -145,19 +149,20 @@ int main(int argc, char **argv)
 
     SDL_Log("Using audio driver: %s\n", SDL_GetCurrentAudioDriver());
 
-    devcount = SDL_GetNumAudioDevices(SDL_TRUE);
-    for (i = 0; i < devcount; i++) {
-        SDL_Log(" Capture device #%d: '%s'\n", i, SDL_GetAudioDeviceName(i, SDL_TRUE));
+    devices = SDL_GetAudioCaptureDevices(NULL);
+    for (i = 0; devices[i] != 0; i++) {
+        char *name = SDL_GetAudioDeviceName(devices[i]);
+        SDL_Log(" Capture device #%d: '%s'\n", i, name);
+        if (devname && (SDL_strcmp(devname, name) == 0)) {
+            want_device = devices[i];
+        }
+        SDL_free(name);
     }
 
-    SDL_zero(wanted);
-    wanted.freq = 44100;
-    wanted.format = SDL_AUDIO_F32SYS;
-    wanted.channels = 1;
-    wanted.samples = 4096;
-    wanted.callback = NULL;
-
-    SDL_zero(spec);
+    if (devname && (want_device == SDL_AUDIO_DEVICE_DEFAULT_CAPTURE)) {
+        SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION, "Didn't see a capture device named '%s', using the system default instead.\n", devname);
+        devname = NULL;
+    }
 
     /* DirectSound can fail in some instances if you open the same hardware
        for both capture and output and didn't open the output end first,
@@ -166,24 +171,40 @@ int main(int argc, char **argv)
        circumstances. */
 
     SDL_Log("Opening default playback device...\n");
-    devid_out = SDL_OpenAudioDevice(NULL, SDL_FALSE, &wanted, &spec, SDL_AUDIO_ALLOW_ANY_CHANGE);
-    if (!devid_out) {
+    device = SDL_OpenAudioDevice(SDL_AUDIO_DEVICE_DEFAULT_OUTPUT, NULL);
+    if (!device) {
         SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Couldn't open an audio device for playback: %s!\n", SDL_GetError());
         SDL_Quit();
         exit(1);
     }
+    SDL_PauseAudioDevice(device);
+    SDL_GetAudioDeviceFormat(device, &spec);
+    stream_out = SDL_CreateAndBindAudioStream(device, &spec);
+    if (!stream_out) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Couldn't create an audio stream for playback: %s!\n", SDL_GetError());
+        SDL_Quit();
+        exit(1);
+    }
 
     SDL_Log("Opening capture device %s%s%s...\n",
             devname ? "'" : "",
             devname ? devname : "[[default]]",
             devname ? "'" : "");
 
-    devid_in = SDL_OpenAudioDevice(devname, SDL_TRUE, &spec, &spec, 0);
-    if (!devid_in) {
+    device = SDL_OpenAudioDevice(want_device, NULL);
+    if (!device) {
         SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Couldn't open an audio device for capture: %s!\n", SDL_GetError());
         SDL_Quit();
         exit(1);
     }
+    SDL_PauseAudioDevice(device);
+    SDL_GetAudioDeviceFormat(device, &spec);
+    stream_in = SDL_CreateAndBindAudioStream(device, &spec);
+    if (!stream_in) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Couldn't create an audio stream for capture: %s!\n", SDL_GetError());
+        SDL_Quit();
+        exit(1);
+    }
 
     SDL_Log("Ready! Hold down mouse or finger to record!\n");
 
@@ -198,11 +219,7 @@ int main(int argc, char **argv)
     }
 #endif
 
-    /* SDL_DestroyRenderer(renderer); */
-    /* SDL_DestroyWindow(window); */
-
-    /* SDL_Quit(); */
-    /* SDLTest_CommonDestroyState(state); */
+    SDLTest_CommonDestroyState(state);
 
     return 0;
 }

test/testaudiohotplug.c

@@ -31,9 +31,6 @@ static SDL_AudioSpec spec;
 static Uint8 *sound = NULL; /* Pointer to wave data */
 static Uint32 soundlen = 0; /* Length of wave data */
 
-static int posindex = 0;
-static Uint32 positions[64];
-
 static SDLTest_CommonState *state;
 
 /* Call this instead of exit(), so we can clean up SDL: atexit() is evil. */
@@ -48,31 +45,6 @@ quit(int rc)
     }
 }
 
-static void SDLCALL
-fillerup(void *_pos, Uint8 *stream, int len)
-{
-    Uint32 pos = *((Uint32 *)_pos);
-    Uint8 *waveptr;
-    int waveleft;
-
-    /* Set up the pointers */
-    waveptr = sound + pos;
-    waveleft = soundlen - pos;
-
-    /* Go! */
-    while (waveleft <= len) {
-        SDL_memcpy(stream, waveptr, waveleft);
-        stream += waveleft;
-        len -= waveleft;
-        waveptr = sound;
-        waveleft = soundlen;
-        pos = 0;
-    }
-    SDL_memcpy(stream, waveptr, len);
-    pos += len;
-    *((Uint32 *)_pos) = pos;
-}
-
 static int done = 0;
 
 static void poked(int sig)
@@ -97,28 +69,35 @@ static void iteration(void)
                 done = 1;
             }
         } else if (e.type == SDL_EVENT_AUDIO_DEVICE_ADDED) {
-            int index = e.adevice.which;
-            int iscapture = e.adevice.iscapture;
-            const char *name = SDL_GetAudioDeviceName(index, iscapture);
+            const SDL_AudioDeviceID which = (SDL_AudioDeviceID ) e.adevice.which;
+            const SDL_bool iscapture = e.adevice.iscapture ? SDL_TRUE : SDL_FALSE;
+            char *name = SDL_GetAudioDeviceName(which);
             if (name != NULL) {
-                SDL_Log("New %s audio device at index %u: %s\n", devtypestr(iscapture), (unsigned int)index, name);
+                SDL_Log("New %s audio device at id %u: %s", devtypestr(iscapture), (unsigned int)which, name);
             } else {
-                SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Got new %s device at index %u, but failed to get the name: %s\n",
-                             devtypestr(iscapture), (unsigned int)index, SDL_GetError());
+                SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Got new %s device, id %u, but failed to get the name: %s",
+                             devtypestr(iscapture), (unsigned int)which, SDL_GetError());
                 continue;
             }
             if (!iscapture) {
-                positions[posindex] = 0;
-                spec.userdata = &positions[posindex++];
-                spec.callback = fillerup;
-                dev = SDL_OpenAudioDevice(name, 0, &spec, NULL, 0);
+                dev = SDL_OpenAudioDevice(which, &spec);
                 if (!dev) {
                     SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Couldn't open '%s': %s\n", name, SDL_GetError());
                 } else {
+                    SDL_AudioStream *stream;
                     SDL_Log("Opened '%s' as %u\n", name, (unsigned int)dev);
-                    SDL_PlayAudioDevice(dev);
+                    stream = SDL_CreateAndBindAudioStream(dev, &spec);
+                    if (!stream) {
+                        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Failed to create/bind an audio stream to %u ('%s'): %s", (unsigned int) dev, name, SDL_GetError());
+                        SDL_CloseAudioDevice(dev);
+                    }
+                    /* !!! FIXME: laziness, this used to loop the audio, but we'll just play it once for now on each connect. */
+                    SDL_PutAudioStreamData(stream, sound, soundlen);
+                    SDL_FlushAudioStream(stream);
+                    /* !!! FIXME: this is leaking the stream for now. We'll wire it up to a dictionary or whatever later. */
                 }
             }
+            SDL_free(name);
         } else if (e.type == SDL_EVENT_AUDIO_DEVICE_REMOVED) {
             dev = (SDL_AudioDeviceID)e.adevice.which;
             SDL_Log("%s device %u removed.\n", devtypestr(e.adevice.iscapture), (unsigned int)dev);
@@ -194,7 +173,7 @@ int main(int argc, char *argv[])
     }
 
     /* Load the wave file into memory */
-    if (SDL_LoadWAV(filename, &spec, &sound, &soundlen) == NULL) {
+    if (SDL_LoadWAV(filename, &spec, &sound, &soundlen) == -1) {
         SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Couldn't load %s: %s\n", filename, SDL_GetError());
         quit(1);
     }

test/testaudioinfo.c

@@ -14,29 +14,30 @@
 #include <SDL3/SDL_test.h>
 
 static void
-print_devices(int iscapture)
+print_devices(SDL_bool iscapture)
 {
     SDL_AudioSpec spec;
     const char *typestr = ((iscapture) ? "capture" : "output");
-    int n = SDL_GetNumAudioDevices(iscapture);
+    int n = 0;
+    SDL_AudioDeviceID *devices = iscapture ? SDL_GetAudioCaptureDevices(&n) : SDL_GetAudioOutputDevices(&n);
 
-    SDL_Log("Found %d %s device%s:\n", n, typestr, n != 1 ? "s" : "");
-
-    if (n == -1) {
-        SDL_Log("  Driver can't detect specific %s devices.\n\n", typestr);
+    if (devices == NULL) {
+        SDL_Log("  Driver failed to report %s devices: %s\n\n", typestr, SDL_GetError());
     } else if (n == 0) {
         SDL_Log("  No %s devices found.\n\n", typestr);
     } else {
         int i;
+        SDL_Log("Found %d %s device%s:\n", n, typestr, n != 1 ? "s" : "");
         for (i = 0; i < n; i++) {
-            const char *name = SDL_GetAudioDeviceName(i, iscapture);
+            char *name = SDL_GetAudioDeviceName(devices[i]);
             if (name != NULL) {
                 SDL_Log("  %d: %s\n", i, name);
+                SDL_free(name);
             } else {
                 SDL_Log("  %d Error: %s\n", i, SDL_GetError());
             }
 
-            if (SDL_GetAudioDeviceSpec(i, iscapture, &spec) == 0) {
+            if (SDL_GetAudioDeviceFormat(devices[i], &spec) == 0) {
                 SDL_Log("     Sample Rate: %d\n", spec.freq);
                 SDL_Log("     Channels: %d\n", spec.channels);
                 SDL_Log("     SDL_AudioFormat: %X\n", spec.format);
@@ -44,11 +45,11 @@ print_devices(int iscapture)
         }
         SDL_Log("\n");
     }
+    SDL_free(devices);
 }
 
 int main(int argc, char **argv)
 {
-    char *deviceName = NULL;
     SDL_AudioSpec spec;
     int i;
     int n;
@@ -88,24 +89,22 @@ int main(int argc, char **argv)
 
     SDL_Log("Using audio driver: %s\n\n", SDL_GetCurrentAudioDriver());
 
-    print_devices(0);
-    print_devices(1);
+    print_devices(SDL_FALSE);
+    print_devices(SDL_TRUE);
 
-    if (SDL_GetDefaultAudioInfo(&deviceName, &spec, 0) < 0) {
-        SDL_Log("Error when calling SDL_GetDefaultAudioInfo: %s\n", SDL_GetError());
+    if (SDL_GetAudioDeviceFormat(SDL_AUDIO_DEVICE_DEFAULT_OUTPUT, &spec) < 0) {
+        SDL_Log("Error when calling SDL_GetAudioDeviceFormat(default output): %s\n", SDL_GetError());
     } else {
-        SDL_Log("Default Output Name: %s\n", deviceName != NULL ? deviceName : "unknown");
-        SDL_free(deviceName);
+        SDL_Log("Default Output Device:\n");
         SDL_Log("Sample Rate: %d\n", spec.freq);
         SDL_Log("Channels: %d\n", spec.channels);
         SDL_Log("SDL_AudioFormat: %X\n", spec.format);
     }
 
-    if (SDL_GetDefaultAudioInfo(&deviceName, &spec, 1) < 0) {
-        SDL_Log("Error when calling SDL_GetDefaultAudioInfo: %s\n", SDL_GetError());
+    if (SDL_GetAudioDeviceFormat(SDL_AUDIO_DEVICE_DEFAULT_CAPTURE, &spec) < 0) {
+        SDL_Log("Error when calling SDL_GetAudioDeviceFormat(default capture): %s\n", SDL_GetError());
     } else {
-        SDL_Log("Default Capture Name: %s\n", deviceName != NULL ? deviceName : "unknown");
-        SDL_free(deviceName);
+        SDL_Log("Default Capture Device:\n");
         SDL_Log("Sample Rate: %d\n", spec.freq);
         SDL_Log("Channels: %d\n", spec.channels);
         SDL_Log("SDL_AudioFormat: %X\n", spec.format);
@@ -115,3 +114,4 @@ int main(int argc, char **argv)
     SDLTest_CommonDestroyState(state);
     return 0;
 }
+

test/testaudiostreamdynamicresample.c

@@ -15,13 +15,7 @@
 #include <SDL3/SDL.h>
 #include <SDL3/SDL_main.h>
 #include <SDL3/SDL_test.h>
-
-static void SDLCALL audio_callback(void *userdata, Uint8 * stream, int len)
-{
-    SDL_AudioStream *audiostream = (SDL_AudioStream *) userdata;
-    SDL_memset(stream, 0, len);
-    SDL_GetAudioStreamData(audiostream, stream, len);
-}
+#include "testutils.h"
 
 int main(int argc, char *argv[])
 {
@@ -36,24 +30,35 @@ int main(int argc, char *argv[])
     Uint32 audio_len = 0;
     SDL_AudioStream *stream;
     SDL_AudioDeviceID device;
+    const char *fname = "sample.wav";
+    char *path;
+    int rc;
 
     SDL_Init(SDL_INIT_VIDEO | SDL_INIT_AUDIO);
     window = SDL_CreateWindow("Drag the slider: Normal speed", 640, 480, 0);
     renderer = SDL_CreateRenderer(window, NULL, 0);
 
-    SDL_LoadWAV("sample.wav", &spec, &audio_buf, &audio_len);
-    stream = SDL_CreateAudioStream(spec.format, spec.channels, spec.freq, spec.format, spec.channels, spec.freq);
+    path = GetNearbyFilename(fname);
+    rc = SDL_LoadWAV(path ? path : fname, &spec, &audio_buf, &audio_len);
+    SDL_free(path);
+
+    if (rc < 0) {
+        SDL_Log("Failed to load '%s': %s", fname, SDL_GetError());
+        SDL_Quit();
+        return 1;
+    }
+
+    stream = SDL_CreateAudioStream(&spec, &spec);
     SDL_PutAudioStreamData(stream, audio_buf, audio_len);
-    spec.callback = audio_callback;
-    spec.userdata = stream;
-    device = SDL_OpenAudioDevice(NULL, SDL_FALSE, &spec, NULL, 0);
-    SDL_PlayAudioDevice(device);
+    device = SDL_OpenAudioDevice(SDL_AUDIO_DEVICE_DEFAULT_OUTPUT, &spec);
+    SDL_BindAudioStream(device, stream);
 
     slider_fill_area.w /= 2;
 
     while (!done) {
         SDL_Event e;
         int newmultiplier = multiplier;
+
         while (SDL_PollEvent(&e)) {
             if (e.type == SDL_EVENT_QUIT) {
                 done = 1;
@@ -74,6 +79,7 @@ int main(int argc, char *argv[])
         }
 
         if (multiplier != newmultiplier) {
+            SDL_AudioSpec newspec;
             char title[64];
             int newfreq = spec.freq;
 
@@ -94,13 +100,13 @@ int main(int argc, char *argv[])
                 newfreq = spec.freq + (int) (spec.freq * (multiplier / 100.0f));
             }
             /* SDL_Log("newfreq=%d   multiplier=%d\n", newfreq, multiplier); */
-            SDL_LockAudioDevice(device);
-            SDL_SetAudioStreamFormat(stream, spec.format, spec.channels, newfreq, spec.format, spec.channels, spec.freq);
-            SDL_UnlockAudioDevice(device);
+            SDL_memcpy(&newspec, &spec, sizeof (spec));
+            newspec.freq = newfreq;
+            SDL_SetAudioStreamFormat(stream, &newspec, NULL);
         }
 
         /* keep it looping. */
-        if (SDL_GetAudioStreamAvailable(stream) < (1024 * 100)) {
+        if (SDL_GetAudioStreamAvailable(stream) < ((int) (audio_len / 2))) {
             SDL_PutAudioStreamData(stream, audio_buf, audio_len);
         }
 
@@ -116,6 +122,7 @@ int main(int argc, char *argv[])
     SDL_DestroyRenderer(renderer);
     SDL_DestroyWindow(window);
     SDL_CloseAudioDevice(device);
+    SDL_DestroyAudioStream(stream);
     SDL_free(audio_buf);
     SDL_Quit();
     return 0;

test/testautomation_audio.c

@@ -38,6 +38,7 @@ static void audioTearDown(void *arg)
     SDLTest_AssertPass("Cleanup of test files completed");
 }
 
+#if 0  /* !!! FIXME: maybe update this? */
 /* Global counter for callback invocation */
 static int g_audio_testCallbackCounter;
 
@@ -51,6 +52,7 @@ static void SDLCALL audio_testCallback(void *userdata, Uint8 *stream, int len)
     g_audio_testCallbackCounter++;
     g_audio_testCallbackLength += len;
 }
+#endif
 
 static SDL_AudioDeviceID g_audio_id = -1;
 
@@ -176,28 +178,22 @@ static int audio_initOpenCloseQuitAudio(void *arg)
                 desired.freq = 22050;
                 desired.format = SDL_AUDIO_S16SYS;
                 desired.channels = 2;
-                desired.samples = 4096;
-                desired.callback = audio_testCallback;
-                desired.userdata = NULL;
 
             case 1:
                 /* Set custom desired spec */
                 desired.freq = 48000;
                 desired.format = SDL_AUDIO_F32SYS;
                 desired.channels = 2;
-                desired.samples = 2048;
-                desired.callback = audio_testCallback;
-                desired.userdata = NULL;
                 break;
             }
 
             /* Call Open (maybe multiple times) */
             for (k = 0; k <= j; k++) {
-                result = SDL_OpenAudioDevice(NULL, 0, &desired, NULL, 0);
+                result = SDL_OpenAudioDevice(SDL_AUDIO_DEVICE_DEFAULT_OUTPUT, &desired);
                 if (k == 0) {
                     g_audio_id = result;
                 }
-                SDLTest_AssertPass("Call to SDL_OpenAudioDevice(NULL, 0, desired_spec_%d, NULL, 0), call %d", j, k + 1);
+                SDLTest_AssertPass("Call to SDL_OpenAudioDevice(SDL_AUDIO_DEVICE_DEFAULT_OUTPUT, desired_spec_%d), call %d", j, k + 1);
                 SDLTest_AssertCheck(result > 0, "Verify return value; expected: > 0, got: %d", result);
             }
 
@@ -230,11 +226,9 @@ static int audio_initOpenCloseQuitAudio(void *arg)
  */
 static int audio_pauseUnpauseAudio(void *arg)
 {
+    int iMax;
+    int i, j /*, k, l*/;
     int result;
-    int i, iMax, j, k, l;
-    int totalDelay;
-    int pause_on;
-    int originalCounter;
     const char *audioDriver;
     SDL_AudioSpec desired;
 
@@ -269,9 +263,6 @@ static int audio_pauseUnpauseAudio(void *arg)
                 desired.freq = 22050;
                 desired.format = SDL_AUDIO_S16SYS;
                 desired.channels = 2;
-                desired.samples = 4096;
-                desired.callback = audio_testCallback;
-                desired.userdata = NULL;
                 break;
 
             case 1:
@@ -279,18 +270,16 @@ static int audio_pauseUnpauseAudio(void *arg)
                 desired.freq = 48000;
                 desired.format = SDL_AUDIO_F32SYS;
                 desired.channels = 2;
-                desired.samples = 2048;
-                desired.callback = audio_testCallback;
-                desired.userdata = NULL;
                 break;
             }
 
             /* Call Open */
-            g_audio_id = SDL_OpenAudioDevice(NULL, 0, &desired, NULL, 0);
+            g_audio_id = SDL_OpenAudioDevice(SDL_AUDIO_DEVICE_DEFAULT_OUTPUT, &desired);
             result = g_audio_id;
-            SDLTest_AssertPass("Call to SDL_OpenAudioDevice(NULL, 0, desired_spec_%d, NULL, 0)", j);
+            SDLTest_AssertPass("Call to SDL_OpenAudioDevice(SDL_AUDIO_DEVICE_DEFAULT_OUTPUT, desired_spec_%d)", j);
             SDLTest_AssertCheck(result > 0, "Verify return value; expected > 0 got: %d", result);
 
+#if 0  /* !!! FIXME: maybe update this? */
             /* Start and stop audio multiple times */
             for (l = 0; l < 3; l++) {
                 SDLTest_Log("Pause/Unpause iteration: %d", l + 1);
@@ -300,14 +289,13 @@ static int audio_pauseUnpauseAudio(void *arg)
                 g_audio_testCallbackLength = 0;
 
                 /* Un-pause audio to start playing (maybe multiple times) */
-                pause_on = 0;
                 for (k = 0; k <= j; k++) {
                     SDL_PlayAudioDevice(g_audio_id);
                     SDLTest_AssertPass("Call to SDL_PlayAudioDevice(g_audio_id), call %d", k + 1);
                 }
 
                 /* Wait for callback */
-                totalDelay = 0;
+                int totalDelay = 0;
                 do {
                     SDL_Delay(10);
                     totalDelay += 10;
@@ -317,7 +305,7 @@ static int audio_pauseUnpauseAudio(void *arg)
 
                 /* Pause audio to stop playing (maybe multiple times) */
                 for (k = 0; k <= j; k++) {
-                    pause_on = (k == 0) ? 1 : SDLTest_RandomIntegerInRange(99, 9999);
+                    const int pause_on = (k == 0) ? 1 : SDLTest_RandomIntegerInRange(99, 9999);
                     if (pause_on) {
                         SDL_PauseAudioDevice(g_audio_id);
                         SDLTest_AssertPass("Call to SDL_PauseAudioDevice(g_audio_id), call %d", k + 1);
@@ -328,10 +316,11 @@ static int audio_pauseUnpauseAudio(void *arg)
                 }
 
                 /* Ensure callback is not called again */
-                originalCounter = g_audio_testCallbackCounter;
+                const int originalCounter = g_audio_testCallbackCounter;
                 SDL_Delay(totalDelay + 10);
                 SDLTest_AssertCheck(originalCounter == g_audio_testCallbackCounter, "Verify callback counter; expected: %d, got: %d", originalCounter, g_audio_testCallbackCounter);
             }
+#endif
 
             /* Call Close */
             SDL_CloseAudioDevice(g_audio_id);
@@ -358,51 +347,34 @@ static int audio_pauseUnpauseAudio(void *arg)
  */
 static int audio_enumerateAndNameAudioDevices(void *arg)
 {
-    int t, tt;
-    int i, n, nn;
-    const char *name, *nameAgain;
+    int t;
+    int i, n;
+    char *name;
+    SDL_AudioDeviceID *devices = NULL;
 
     /* Iterate over types: t=0 output device, t=1 input/capture device */
     for (t = 0; t < 2; t++) {
-
         /* Get number of devices. */
-        n = SDL_GetNumAudioDevices(t);
-        SDLTest_AssertPass("Call to SDL_GetNumAudioDevices(%i)", t);
+        devices = (t) ? SDL_GetAudioCaptureDevices(&n) : SDL_GetAudioOutputDevices(&n);
+        SDLTest_AssertPass("Call to SDL_GetAudio%sDevices(%i)", (t) ? "Capture" : "Output", t);
         SDLTest_Log("Number of %s devices < 0, reported as %i", (t) ? "capture" : "output", n);
         SDLTest_AssertCheck(n >= 0, "Validate result is >= 0, got: %i", n);
 
-        /* Variation of non-zero type */
-        if (t == 1) {
-            tt = t + SDLTest_RandomIntegerInRange(1, 10);
-            nn = SDL_GetNumAudioDevices(tt);
-            SDLTest_AssertCheck(n == nn, "Verify result from SDL_GetNumAudioDevices(%i), expected same number of audio devices %i, got %i", tt, n, nn);
-            nn = SDL_GetNumAudioDevices(-tt);
-            SDLTest_AssertCheck(n == nn, "Verify result from SDL_GetNumAudioDevices(%i), expected same number of audio devices %i, got %i", -tt, n, nn);
-        }
-
         /* List devices. */
         if (n > 0) {
+            SDLTest_AssertCheck(devices != NULL, "Validate devices is not NULL if n > 0");
             for (i = 0; i < n; i++) {
-                name = SDL_GetAudioDeviceName(i, t);
-                SDLTest_AssertPass("Call to SDL_GetAudioDeviceName(%i, %i)", i, t);
-                SDLTest_AssertCheck(name != NULL, "Verify result from SDL_GetAudioDeviceName(%i, %i) is not NULL", i, t);
+                name = SDL_GetAudioDeviceName(devices[i]);
+                SDLTest_AssertPass("Call to SDL_GetAudioDeviceName(%i)", i);
+                SDLTest_AssertCheck(name != NULL, "Verify result from SDL_GetAudioDeviceName(%i) is not NULL", i);
                 if (name != NULL) {
-                    SDLTest_AssertCheck(name[0] != '\0', "verify result from SDL_GetAudioDeviceName(%i, %i) is not empty, got: '%s'", i, t, name);
-                    if (t == 1) {
-                        /* Also try non-zero type */
-                        tt = t + SDLTest_RandomIntegerInRange(1, 10);
-                        nameAgain = SDL_GetAudioDeviceName(i, tt);
-                        SDLTest_AssertCheck(nameAgain != NULL, "Verify result from SDL_GetAudioDeviceName(%i, %i) is not NULL", i, tt);
-                        if (nameAgain != NULL) {
-                            SDLTest_AssertCheck(nameAgain[0] != '\0', "Verify result from SDL_GetAudioDeviceName(%i, %i) is not empty, got: '%s'", i, tt, nameAgain);
-                            SDLTest_AssertCheck(SDL_strcmp(name, nameAgain) == 0,
-                                                "Verify SDL_GetAudioDeviceName(%i, %i) and SDL_GetAudioDeviceName(%i %i) return the same string",
-                                                i, t, i, tt);
-                        }
-                    }
+                    SDLTest_AssertCheck(name[0] != '\0', "verify result from SDL_GetAudioDeviceName(%i) is not empty, got: '%s'", i, name);
+                    SDL_free(name);
                 }
             }
         }
+
+        SDL_free(devices);
     }
 
     return TEST_COMPLETED;
@@ -416,42 +388,7 @@ static int audio_enumerateAndNameAudioDevices(void *arg)
  */
 static int audio_enumerateAndNameAudioDevicesNegativeTests(void *arg)
 {
-    int t;
-    int i, j, no, nc;
-    const char *name;
-
-    /* Get number of devices. */
-    no = SDL_GetNumAudioDevices(0);
-    SDLTest_AssertPass("Call to SDL_GetNumAudioDevices(0)");
-    nc = SDL_GetNumAudioDevices(1);
-    SDLTest_AssertPass("Call to SDL_GetNumAudioDevices(1)");
-
-    /* Invalid device index when getting name */
-    for (t = 0; t < 2; t++) {
-        /* Negative device index */
-        i = SDLTest_RandomIntegerInRange(-10, -1);
-        name = SDL_GetAudioDeviceName(i, t);
-        SDLTest_AssertPass("Call to SDL_GetAudioDeviceName(%i, %i)", i, t);
-        SDLTest_AssertCheck(name == NULL, "Check SDL_GetAudioDeviceName(%i, %i) result NULL, expected NULL, got: %s", i, t, (name == NULL) ? "NULL" : name);
-
-        /* Device index past range */
-        for (j = 0; j < 3; j++) {
-            i = (t) ? nc + j : no + j;
-            name = SDL_GetAudioDeviceName(i, t);
-            SDLTest_AssertPass("Call to SDL_GetAudioDeviceName(%i, %i)", i, t);
-            SDLTest_AssertCheck(name == NULL, "Check SDL_GetAudioDeviceName(%i, %i) result, expected: NULL, got: %s", i, t, (name == NULL) ? "NULL" : name);
-        }
-
-        /* Capture index past capture range but within output range */
-        if ((no > 0) && (no > nc) && (t == 1)) {
-            i = no - 1;
-            name = SDL_GetAudioDeviceName(i, t);
-            SDLTest_AssertPass("Call to SDL_GetAudioDeviceName(%i, %i)", i, t);
-            SDLTest_AssertCheck(name == NULL, "Check SDL_GetAudioDeviceName(%i, %i) result, expected: NULL, got: %s", i, t, (name == NULL) ? "NULL" : name);
-        }
-    }
-
-    return TEST_COMPLETED;
+    return TEST_COMPLETED;  /* nothing in here atm since these interfaces changed in SDL3. */
 }
 
 /**
@@ -532,8 +469,7 @@ static int audio_buildAudioStream(void *arg)
     spec1.format = SDL_AUDIO_S16LSB;
     spec1.channels = 2;
     spec1.freq = 22050;
-    stream = SDL_CreateAudioStream(spec1.format, spec1.channels, spec1.freq,
-                                   spec1.format, spec1.channels, spec1.freq);
+    stream = SDL_CreateAudioStream(&spec1, &spec1);
     SDLTest_AssertPass("Call to SDL_CreateAudioStream(spec1 ==> spec1)");
     SDLTest_AssertCheck(stream != NULL, "Verify stream value; expected: != NULL, got: %p", (void *)stream);
     SDL_DestroyAudioStream(stream);
@@ -545,8 +481,7 @@ static int audio_buildAudioStream(void *arg)
     spec2.format = SDL_AUDIO_S16LSB;
     spec2.channels = 2;
     spec2.freq = 44100;
-    stream = SDL_CreateAudioStream(spec1.format, spec1.channels, spec1.freq,
-                                   spec2.format, spec2.channels, spec2.freq);
+    stream = SDL_CreateAudioStream(&spec1, &spec2);
     SDLTest_AssertPass("Call to SDL_CreateAudioStream(spec1 ==> spec2)");
     SDLTest_AssertCheck(stream != NULL, "Verify stream value; expected: != NULL, got: %p", (void *)stream);
     SDL_DestroyAudioStream(stream);
@@ -564,8 +499,7 @@ static int audio_buildAudioStream(void *arg)
                 spec2.format = g_audioFormats[ii];
                 spec2.channels = g_audioChannels[jj];
                 spec2.freq = g_audioFrequencies[kk];
-                stream = SDL_CreateAudioStream(spec1.format, spec1.channels, spec1.freq,
-                                               spec2.format, spec2.channels, spec2.freq);
+                stream = SDL_CreateAudioStream(&spec1, &spec2);
 
                 SDLTest_AssertPass("Call to SDL_CreateAudioStream(format[%i]=%s(%i),channels[%i]=%i,freq[%i]=%i ==> format[%i]=%s(%i),channels[%i]=%i,freq[%i]=%i)",
                                    i, g_audioFormatsVerbose[i], spec1.format, j, spec1.channels, k, spec1.freq, ii, g_audioFormatsVerbose[ii], spec2.format, jj, spec2.channels, kk, spec2.freq);
@@ -646,8 +580,7 @@ static int audio_buildAudioStreamNegative(void *arg)
             spec2.freq = 0;
         }
         SDLTest_Log("%s", message);
-        stream = SDL_CreateAudioStream(spec1.format, spec1.channels, spec1.freq,
-                                       spec2.format, spec2.channels, spec2.freq);
+        stream = SDL_CreateAudioStream(&spec1, &spec2);
         SDLTest_AssertPass("Call to SDL_CreateAudioStream(spec1 ==> spec2)");
         SDLTest_AssertCheck(stream == NULL, "Verify stream value; expected: NULL, got: %p", (void *)stream);
         error = SDL_GetError();
@@ -669,16 +602,7 @@ static int audio_buildAudioStreamNegative(void *arg)
  */
 static int audio_getAudioStatus(void *arg)
 {
-    SDL_AudioStatus result;
-
-    /* Check current audio status */
-    result = SDL_GetAudioDeviceStatus(g_audio_id);
-    SDLTest_AssertPass("Call to SDL_GetAudioDeviceStatus(g_audio_id)");
-    SDLTest_AssertCheck(result == SDL_AUDIO_STOPPED || result == SDL_AUDIO_PLAYING || result == SDL_AUDIO_PAUSED,
-                        "Verify returned value; expected: STOPPED (%i) | PLAYING (%i) | PAUSED (%i), got: %i",
-                        SDL_AUDIO_STOPPED, SDL_AUDIO_PLAYING, SDL_AUDIO_PAUSED, result);
-
-    return TEST_COMPLETED;
+    return TEST_COMPLETED;  /* no longer a thing in SDL3. */
 }
 
 /**
@@ -688,57 +612,7 @@ static int audio_getAudioStatus(void *arg)
  */
 static int audio_openCloseAndGetAudioStatus(void *arg)
 {
-    SDL_AudioStatus result;
-    int i;
-    int count;
-    const char *device;
-    SDL_AudioDeviceID id;
-    SDL_AudioSpec desired, obtained;
-
-    /* Get number of devices. */
-    count = SDL_GetNumAudioDevices(0);
-    SDLTest_AssertPass("Call to SDL_GetNumAudioDevices(0)");
-    if (count > 0) {
-        for (i = 0; i < count; i++) {
-            /* Get device name */
-            device = SDL_GetAudioDeviceName(i, 0);
-            SDLTest_AssertPass("SDL_GetAudioDeviceName(%i,0)", i);
-            SDLTest_AssertCheck(device != NULL, "Validate device name is not NULL; got: %s", (device != NULL) ? device : "NULL");
-            if (device == NULL) {
-                return TEST_ABORTED;
-            }
-
-            /* Set standard desired spec */
-            desired.freq = 22050;
-            desired.format = SDL_AUDIO_S16SYS;
-            desired.channels = 2;
-            desired.samples = 4096;
-            desired.callback = audio_testCallback;
-            desired.userdata = NULL;
-
-            /* Open device */
-            id = SDL_OpenAudioDevice(device, 0, &desired, &obtained, SDL_AUDIO_ALLOW_ANY_CHANGE);
-            SDLTest_AssertPass("SDL_OpenAudioDevice('%s',...)", device);
-            SDLTest_AssertCheck(id > 0, "Validate device ID; expected: > 0, got: %" SDL_PRIu32, id);
-            if (id > 0) {
-
-                /* Check device audio status */
-                result = SDL_GetAudioDeviceStatus(id);
-                SDLTest_AssertPass("Call to SDL_GetAudioDeviceStatus()");
-                SDLTest_AssertCheck(result == SDL_AUDIO_STOPPED || result == SDL_AUDIO_PLAYING || result == SDL_AUDIO_PAUSED,
-                                    "Verify returned value; expected: STOPPED (%i) | PLAYING (%i) | PAUSED (%i), got: %i",
-                                    SDL_AUDIO_STOPPED, SDL_AUDIO_PLAYING, SDL_AUDIO_PAUSED, result);
-
-                /* Close device again */
-                SDL_CloseAudioDevice(id);
-                SDLTest_AssertPass("Call to SDL_CloseAudioDevice()");
-            }
-        }
-    } else {
-        SDLTest_Log("No devices to test with");
-    }
-
-    return TEST_COMPLETED;
+    return TEST_COMPLETED;  /* not a thing in SDL3. */
 }
 
 /**
@@ -749,60 +623,7 @@ static int audio_openCloseAndGetAudioStatus(void *arg)
  */
 static int audio_lockUnlockOpenAudioDevice(void *arg)
 {
-    int i;
-    int count;
-    const char *device;
-    SDL_AudioDeviceID id;
-    SDL_AudioSpec desired, obtained;
-
-    /* Get number of devices. */
-    count = SDL_GetNumAudioDevices(0);
-    SDLTest_AssertPass("Call to SDL_GetNumAudioDevices(0)");
-    if (count > 0) {
-        for (i = 0; i < count; i++) {
-            /* Get device name */
-            device = SDL_GetAudioDeviceName(i, 0);
-            SDLTest_AssertPass("SDL_GetAudioDeviceName(%i,0)", i);
-            SDLTest_AssertCheck(device != NULL, "Validate device name is not NULL; got: %s", (device != NULL) ? device : "NULL");
-            if (device == NULL) {
-                return TEST_ABORTED;
-            }
-
-            /* Set standard desired spec */
-            desired.freq = 22050;
-            desired.format = SDL_AUDIO_S16SYS;
-            desired.channels = 2;
-            desired.samples = 4096;
-            desired.callback = audio_testCallback;
-            desired.userdata = NULL;
-
-            /* Open device */
-            id = SDL_OpenAudioDevice(device, 0, &desired, &obtained, SDL_AUDIO_ALLOW_ANY_CHANGE);
-            SDLTest_AssertPass("SDL_OpenAudioDevice('%s',...)", device);
-            SDLTest_AssertCheck(id > 1, "Validate device ID; expected: > 0, got: %" SDL_PRIu32, id);
-            if (id > 0) {
-                /* Lock to protect callback */
-                SDL_LockAudioDevice(id);
-                SDLTest_AssertPass("SDL_LockAudioDevice(%" SDL_PRIu32 ")", id);
-
-                /* Simulate callback processing */
-                SDL_Delay(10);
-                SDLTest_Log("Simulate callback processing - delay");
-
-                /* Unlock again */
-                SDL_UnlockAudioDevice(id);
-                SDLTest_AssertPass("SDL_UnlockAudioDevice(%" SDL_PRIu32 ")", id);
-
-                /* Close device again */
-                SDL_CloseAudioDevice(id);
-                SDLTest_AssertPass("Call to SDL_CloseAudioDevice()");
-            }
-        }
-    } else {
-        SDLTest_Log("No devices to test with");
-    }
-
-    return TEST_COMPLETED;
+    return TEST_COMPLETED;  /* not a thing in SDL3 */
 }
 
 /**
@@ -862,8 +683,7 @@ static int audio_convertAudio(void *arg)
                     spec2.channels = g_audioChannels[jj];
                     spec2.freq = g_audioFrequencies[kk];
 
-                    stream = SDL_CreateAudioStream(spec1.format, spec1.channels, spec1.freq,
-                                                   spec2.format, spec2.channels, spec2.freq);
+                    stream = SDL_CreateAudioStream(&spec1, &spec2);
                     SDLTest_AssertPass("Call to SDL_CreateAudioStream(format[%i]=%s(%i),channels[%i]=%i,freq[%i]=%i ==> format[%i]=%s(%i),channels[%i]=%i,freq[%i]=%i)",
                                        i, g_audioFormatsVerbose[i], spec1.format, j, spec1.channels, k, spec1.freq, ii, g_audioFormatsVerbose[ii], spec2.format, jj, spec2.channels, kk, spec2.freq);
                     SDLTest_AssertCheck(stream != NULL, "Verify stream value; expected: != NULL, got: %p", (void *)stream);
@@ -936,59 +756,7 @@ static int audio_convertAudio(void *arg)
  */
 static int audio_openCloseAudioDeviceConnected(void *arg)
 {
-    int result = -1;
-    int i;
-    int count;
-    const char *device;
-    SDL_AudioDeviceID id;
-    SDL_AudioSpec desired, obtained;
-
-    /* Get number of devices. */
-    count = SDL_GetNumAudioDevices(0);
-    SDLTest_AssertPass("Call to SDL_GetNumAudioDevices(0)");
-    if (count > 0) {
-        for (i = 0; i < count; i++) {
-            /* Get device name */
-            device = SDL_GetAudioDeviceName(i, 0);
-            SDLTest_AssertPass("SDL_GetAudioDeviceName(%i,0)", i);
-            SDLTest_AssertCheck(device != NULL, "Validate device name is not NULL; got: %s", (device != NULL) ? device : "NULL");
-            if (device == NULL) {
-                return TEST_ABORTED;
-            }
-
-            /* Set standard desired spec */
-            desired.freq = 22050;
-            desired.format = SDL_AUDIO_S16SYS;
-            desired.channels = 2;
-            desired.samples = 4096;
-            desired.callback = audio_testCallback;
-            desired.userdata = NULL;
-
-            /* Open device */
-            id = SDL_OpenAudioDevice(device, 0, &desired, &obtained, SDL_AUDIO_ALLOW_ANY_CHANGE);
-            SDLTest_AssertPass("SDL_OpenAudioDevice('%s',...)", device);
-            SDLTest_AssertCheck(id > 0, "Validate device ID; expected: > 0, got: %" SDL_PRIu32, id);
-            if (id > 0) {
-
-                /* TODO: enable test code when function is available in SDL3 */
-
-#ifdef AUDIODEVICECONNECTED_DEFINED
-                /* Get connected status */
-                result = SDL_AudioDeviceConnected(id);
-                SDLTest_AssertPass("Call to SDL_AudioDeviceConnected()");
-#endif
-                SDLTest_AssertCheck(result == 1, "Verify returned value; expected: 1; got: %i", result);
-
-                /* Close device again */
-                SDL_CloseAudioDevice(id);
-                SDLTest_AssertPass("Call to SDL_CloseAudioDevice()");
-            }
-        }
-    } else {
-        SDLTest_Log("No devices to test with");
-    }
-
-    return TEST_COMPLETED;
+    return TEST_COMPLETED;  /* not a thing in SDL3. */
 }
 
 static double sine_wave_sample(const Sint64 idx, const Sint64 rate, const Sint64 freq, const double phase)
@@ -1040,6 +808,7 @@ static int audio_resampleLoss(void *arg)
     const int len_in = frames_in * (int)sizeof(float);
     const int len_target = frames_target * (int)sizeof(float);
 
+    SDL_AudioSpec tmpspec1, tmpspec2;
     Uint64 tick_beg = 0;
     Uint64 tick_end = 0;
     int i = 0;
@@ -1056,7 +825,13 @@ static int audio_resampleLoss(void *arg)
     SDLTest_AssertPass("Test resampling of %i s %i Hz %f phase sine wave from sampling rate of %i Hz to %i Hz",
                        spec->time, spec->freq, spec->phase, spec->rate_in, spec->rate_out);
 
-    stream = SDL_CreateAudioStream(SDL_AUDIO_F32, 1, spec->rate_in, SDL_AUDIO_F32, 1, spec->rate_out);
+    tmpspec1.format = SDL_AUDIO_F32;
+    tmpspec1.channels = 1;
+    tmpspec1.freq = spec->rate_in;
+    tmpspec2.format = SDL_AUDIO_F32;
+    tmpspec2.channels = 1;
+    tmpspec2.freq = spec->rate_out;
+    stream = SDL_CreateAudioStream(&tmpspec1, &tmpspec2);
     SDLTest_AssertPass("Call to SDL_CreateAudioStream(SDL_AUDIO_F32, 1, %i, SDL_AUDIO_F32, 1, %i)", spec->rate_in, spec->rate_out);
     SDLTest_AssertCheck(stream != NULL, "Expected SDL_CreateAudioStream to succeed.");
     if (stream == NULL) {

test/testmultiaudio.c

@@ -27,85 +27,57 @@ static SDL_AudioSpec spec;
 static Uint8 *sound = NULL; /* Pointer to wave data */
 static Uint32 soundlen = 0; /* Length of wave data */
 
-typedef struct
-{
-    SDL_AudioDeviceID dev;
-    int soundpos;
-    SDL_AtomicInt done;
-} callback_data;
+/* these have to be in globals so the Emscripten port can see them in the mainloop.  :/  */
+static SDL_AudioDeviceID device = 0;
+static SDL_AudioStream *stream = NULL;
 
-static callback_data cbd[64];
-
-static void SDLCALL
-play_through_once(void *arg, Uint8 *stream, int len)
-{
-    callback_data *cbdata = (callback_data *)arg;
-    Uint8 *waveptr = sound + cbdata->soundpos;
-    int waveleft = soundlen - cbdata->soundpos;
-    int cpy = len;
-    if (cpy > waveleft) {
-        cpy = waveleft;
-    }
-
-    SDL_memcpy(stream, waveptr, cpy);
-    len -= cpy;
-    cbdata->soundpos += cpy;
-    if (len > 0) {
-        stream += cpy;
-        SDL_memset(stream, spec.silence, len);
-        SDL_AtomicSet(&cbdata->done, 1);
-    }
-}
 
 #ifdef __EMSCRIPTEN__
 static void loop(void)
 {
-    if (SDL_AtomicGet(&cbd[0].done)) {
-        emscripten_cancel_main_loop();
-        SDL_PauseAudioDevice(cbd[0].dev);
-        SDL_CloseAudioDevice(cbd[0].dev);
+    if (SDL_GetAudioStreamAvailable(stream) == 0) {
+        SDL_Log("done.");
+        SDL_CloseAudioDevice(device);
+        SDL_DestroyAudioStream(stream);
         SDL_free(sound);
         SDL_Quit();
+        emscripten_cancel_main_loop();
     }
 }
 #endif
 
 static void
-test_multi_audio(int devcount)
+test_multi_audio(SDL_AudioDeviceID *devices, int devcount)
 {
     int keep_going = 1;
+    SDL_AudioStream **streams = NULL;
     int i;
 
-#ifdef __ANDROID__
+#ifdef __ANDROID__  /* !!! FIXME: maybe always create a window, in the SDLTest layer, so these #ifdefs don't have to be here? */
     SDL_Event event;
 
     /* Create a Window to get fully initialized event processing for testing pause on Android. */
     SDL_CreateWindow("testmultiaudio", 320, 240, 0);
 #endif
 
-    if (devcount > 64) {
-        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Too many devices (%d), clamping to 64...\n",
-                     devcount);
-        devcount = 64;
-    }
+    for (i = 0; i < devcount; i++) {
+        char *devname = SDL_GetAudioDeviceName(devices[i]);
 
-    spec.callback = play_through_once;
+        SDL_Log("Playing on device #%d of %d: id=%u, name='%s'...", i, devcount, (unsigned int) devices[i], devname);
 
-    for (i = 0; i < devcount; i++) {
-        const char *devname = SDL_GetAudioDeviceName(i, 0);
-        SDL_Log("playing on device #%d: ('%s')...", i, devname);
-
-        SDL_memset(&cbd[0], '\0', sizeof(callback_data));
-        spec.userdata = &cbd[0];
-        cbd[0].dev = SDL_OpenAudioDevice(devname, 0, &spec, NULL, 0);
-        if (cbd[0].dev == 0) {
-            SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Open device failed: %s\n", SDL_GetError());
+        device = SDL_OpenAudioDevice(devices[i], &spec);
+        if (device == 0) {
+            SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Open device failed: %s", SDL_GetError());
+        } else if ((stream = SDL_CreateAndBindAudioStream(device, &spec)) == NULL) {  /* we can reuse these, but we'll just make one each time for now. */
+            SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Audio stream creation failed: %s", SDL_GetError());
+            SDL_CloseAudioDevice(device);
         } else {
-            SDL_PlayAudioDevice(cbd[0].dev);
+            SDL_PutAudioStreamData(stream, sound, soundlen);
+            SDL_FlushAudioStream(stream);
 #ifdef __EMSCRIPTEN__
             emscripten_set_main_loop(loop, 0, 1);
 #else
-            while (!SDL_AtomicGet(&cbd[0].done)) {
+            while (SDL_GetAudioStreamAvailable(stream) > 0) {
 #ifdef __ANDROID__
                 /* Empty queue, some application events would prevent pause. */
                 while (SDL_PollEvent(&event)) {
@@ -113,61 +85,77 @@ test_multi_audio(int devcount)
 #endif
                 SDL_Delay(100);
             }
-            SDL_PauseAudioDevice(cbd[0].dev);
 #endif
-            SDL_Log("done.\n");
-            SDL_CloseAudioDevice(cbd[0].dev);
-        }
-    }
-
-    SDL_memset(cbd, '\0', sizeof(cbd));
-
-    SDL_Log("playing on all devices...\n");
-    for (i = 0; i < devcount; i++) {
-        const char *devname = SDL_GetAudioDeviceName(i, 0);
-        spec.userdata = &cbd[i];
-        cbd[i].dev = SDL_OpenAudioDevice(devname, 0, &spec, NULL, 0);
-        if (cbd[i].dev == 0) {
-            SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Open device %d failed: %s\n", i, SDL_GetError());
+            SDL_Log("done.");
+            SDL_CloseAudioDevice(device);
+            SDL_DestroyAudioStream(stream);
         }
+        SDL_free(devname);
+        stream = NULL;
     }
 
-    for (i = 0; i < devcount; i++) {
-        if (cbd[i].dev) {
-            SDL_PlayAudioDevice(cbd[i].dev);
+    /* note that Emscripten currently doesn't run this part (but maybe only has a single audio device anyhow?) */
+    SDL_Log("Playing on all devices...\n");
+    streams = (SDL_AudioStream **) SDL_calloc(devcount, sizeof (SDL_AudioStream *));
+    if (!streams) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Out of memory!");
+    } else {
+        for (i = 0; i < devcount; i++) {
+            char *devname = SDL_GetAudioDeviceName(devices[i]);
+            device = SDL_OpenAudioDevice(devices[i], &spec);
+            if (device == 0) {
+                SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Open device %d of %d (id=%u, name='%s') failed: %s\n", i, devcount, (unsigned int) devices[i], devname, SDL_GetError());
+            }
+            SDL_free(devname);
+            devices[i] = device; /* just replace the physical device ID with the newly-opened logical device ID. */
+            if (device) {
+                SDL_PauseAudioDevice(device);  /* hold while we set up all the streams. */
+                streams[i] = SDL_CreateAndBindAudioStream(device, &spec);
+                if (streams[i] == NULL) {
+                    SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Audio stream creation failed for device %d of %d: %s", i, devcount, SDL_GetError());
+                } else {
+                    SDL_PutAudioStreamData(streams[i], sound, soundlen);
+                    SDL_FlushAudioStream(streams[i]);
+                }
+            }
         }
-    }
 
-    while (keep_going) {
-        keep_going = 0;
+        /* try to start all the devices about the same time. SDL does not guarantee sync across physical devices. */
         for (i = 0; i < devcount; i++) {
-            if ((cbd[i].dev) && (!SDL_AtomicGet(&cbd[i].done))) {
-                keep_going = 1;
+            if (devices[i]) {
+                SDL_UnpauseAudioDevice(devices[i]);
             }
         }
+
+        while (keep_going) {
+            keep_going = 0;
+            for (i = 0; i < devcount; i++) {
+                if (streams[i] && (SDL_GetAudioStreamAvailable(streams[i]) > 0)) {
+                    keep_going = 1;
+                }
+            }
 #ifdef __ANDROID__
-        /* Empty queue, some application events would prevent pause. */
-        while (SDL_PollEvent(&event)) {
-        }
+            /* Empty queue, some application events would prevent pause. */
+            while (SDL_PollEvent(&event)) {}
 #endif
 
-        SDL_Delay(100);
-    }
+            SDL_Delay(100);
+        }
 
-#ifndef __EMSCRIPTEN__
-    for (i = 0; i < devcount; i++) {
-        if (cbd[i].dev) {
-            SDL_PauseAudioDevice(cbd[i].dev);
-            SDL_CloseAudioDevice(cbd[i].dev);
+        for (i = 0; i < devcount; i++) {
+            SDL_CloseAudioDevice(devices[i]);
+            SDL_DestroyAudioStream(streams[i]);
         }
+
+        SDL_free(streams);
     }
 
     SDL_Log("All done!\n");
-#endif
 }
 
 int main(int argc, char **argv)
 {
+    SDL_AudioDeviceID *devices = NULL;
     int devcount = 0;
     int i;
     char *filename = NULL;
@@ -212,20 +200,21 @@ int main(int argc, char **argv)
 
     filename = GetResourceFilename(filename, "sample.wav");
 
-    devcount = SDL_GetNumAudioDevices(0);
-    if (devcount < 1) {
-        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Don't see any specific audio devices!\n");
+    devices = SDL_GetAudioOutputDevices(&devcount);
+    if (devices == NULL) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Don't see any specific audio devices!");
     } else {
         /* Load the wave file into memory */
-        if (SDL_LoadWAV(filename, &spec, &sound, &soundlen) == NULL) {
+        if (SDL_LoadWAV(filename, &spec, &sound, &soundlen) == -1) {
             SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Couldn't load %s: %s\n", filename,
                          SDL_GetError());
         } else {
-            test_multi_audio(devcount);
+            test_multi_audio(devices, devcount);
             SDL_free(sound);
         }
     }
 
+    SDL_free(devices);
     SDL_free(filename);
 
     SDL_Quit();
@@ -233,3 +222,4 @@ int main(int argc, char **argv)
 
     return 0;
 }
+

test/testresample.c

@@ -22,12 +22,11 @@ static void log_usage(char *progname, SDLTest_CommonState *state) {
 int main(int argc, char **argv)
 {
     SDL_AudioSpec spec;
+    SDL_AudioSpec cvtspec;
     SDL_AudioStream *stream = NULL;
     Uint8 *dst_buf = NULL;
     Uint32 len = 0;
     Uint8 *data = NULL;
-    int cvtfreq = 0;
-    int cvtchans = 0;
     int bitsize = 0;
     int blockalign = 0;
     int avgbytes = 0;
@@ -49,6 +48,8 @@ int main(int argc, char **argv)
     /* Enable standard application logging */
     SDL_LogSetPriority(SDL_LOG_CATEGORY_APPLICATION, SDL_LOG_PRIORITY_INFO);
 
+    SDL_zero(cvtspec);
+
     /* Parse commandline */
     for (i = 1; i < argc;) {
         int consumed;
@@ -65,14 +66,14 @@ int main(int argc, char **argv)
                 consumed = 1;
             } else if (argpos == 2) {
                 char *endp;
-                cvtfreq  = (int)SDL_strtoul(argv[i], &endp, 0);
+                cvtspec.freq  = (int)SDL_strtoul(argv[i], &endp, 0);
                 if (endp != argv[i] && *endp == '\0') {
                     argpos++;
                     consumed = 1;
                 }
             } else if (argpos == 3) {
                 char *endp;
-                cvtchans = (int)SDL_strtoul(argv[i], &endp, 0);
+                cvtspec.channels = (int)SDL_strtoul(argv[i], &endp, 0);
                 if (endp != argv[i] && *endp == '\0') {
                     argpos++;
                     consumed = 1;
@@ -100,14 +101,14 @@ int main(int argc, char **argv)
         goto end;
     }
 
-    if (SDL_LoadWAV(file_in, &spec, &data, &len) == NULL) {
+    if (SDL_LoadWAV(file_in, &spec, &data, &len) == -1) {
         SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "failed to load %s: %s\n", file_in, SDL_GetError());
         ret = 3;
         goto end;
     }
 
-    if (SDL_ConvertAudioSamples(spec.format, spec.channels, spec.freq, data, len,
-                           spec.format, cvtchans, cvtfreq, &dst_buf, &dst_len) < 0) {
+    cvtspec.format = spec.format;
+    if (SDL_ConvertAudioSamples(&spec, data, len, &cvtspec, &dst_buf, &dst_len) < 0) {
         SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "failed to convert samples: %s\n", SDL_GetError());
         ret = 4;
         goto end;
@@ -122,8 +123,8 @@ int main(int argc, char **argv)
     }
 
     bitsize = SDL_AUDIO_BITSIZE(spec.format);
-    blockalign = (bitsize / 8) * cvtchans;
-    avgbytes = cvtfreq * blockalign;
+    blockalign = (bitsize / 8) * cvtspec.channels;
+    avgbytes = cvtspec.freq * blockalign;
 
     SDL_WriteLE32(io, 0x46464952); /* RIFF */
     SDL_WriteLE32(io, dst_len + 36);
@@ -131,8 +132,8 @@ int main(int argc, char **argv)
     SDL_WriteLE32(io, 0x20746D66);                             /* fmt */
     SDL_WriteLE32(io, 16);                                     /* chunk size */
     SDL_WriteLE16(io, SDL_AUDIO_ISFLOAT(spec.format) ? 3 : 1); /* uncompressed */
-    SDL_WriteLE16(io, cvtchans);                               /* channels */
-    SDL_WriteLE32(io, cvtfreq);                                /* sample rate */
+    SDL_WriteLE16(io, cvtspec.channels);                       /* channels */
+    SDL_WriteLE32(io, cvtspec.freq);                           /* sample rate */
     SDL_WriteLE32(io, avgbytes);                               /* average bytes per second */
     SDL_WriteLE16(io, blockalign);                             /* block align */
     SDL_WriteLE16(io, bitsize);                                /* significant bits per sample */

test/testsurround.c

@@ -96,20 +96,23 @@ static SDL_bool is_lfe_channel(int channel_index, int channel_count)
     return (channel_count == 3 && channel_index == 2) || (channel_count >= 6 && channel_index == 3);
 }
 
-static void SDLCALL fill_buffer(void *unused, Uint8 *stream, int len)
+static void SDLCALL fill_buffer(SDL_AudioStream *stream, int len, void *unused)
 {
-    Sint16 *buffer = (Sint16 *)stream;
-    int samples = len / sizeof(Sint16);
+    const int samples = len / sizeof(Sint16);
+    Sint16 *buffer = NULL;
     static int total_samples = 0;
     int i;
 
-    SDL_memset(stream, 0, len);
-
     /* This can happen for a short time when switching devices */
     if (active_channel == total_channels) {
         return;
     }
 
+    buffer = (Sint16 *) SDL_calloc(samples, sizeof(Sint16));
+    if (!buffer) {
+        return;  /* oh well. */
+    }
+
     /* Play a sine wave on the active channel only */
     for (i = active_channel; i < samples; i += total_channels) {
         float time = (float)total_samples++ / SAMPLE_RATE_HZ;
@@ -134,12 +137,18 @@ static void SDLCALL fill_buffer(void *unused, Uint8 *stream, int len)
             break;
         }
     }
+
+    SDL_PutAudioStreamData(stream, buffer, samples * sizeof (Sint16));
+
+    SDL_free(buffer);
 }
 
 int main(int argc, char *argv[])
 {
-    int i;
+    SDL_AudioDeviceID *devices = NULL;
     SDLTest_CommonState *state;
+    int devcount = 0;
+    int i;
 
     /* Initialize test framework */
     state = SDLTest_CommonCreateState(argv, 0);
@@ -168,38 +177,58 @@ int main(int argc, char *argv[])
 
     SDL_Log("Using audio driver: %s\n", SDL_GetCurrentAudioDriver());
 
-    for (i = 0; i < SDL_GetNumAudioDevices(0); i++) {
-        const char *devname = SDL_GetAudioDeviceName(i, 0);
+    devices = SDL_GetAudioOutputDevices(&devcount);
+    if (!devices) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "SDL_GetAudioOutputDevices() failed: %s\n", SDL_GetError());
+        devcount = 0;
+    }
+
+    SDL_Log("Available audio devices:");
+    for (i = 0; i < devcount; i++) {
+        SDL_Log("%s", SDL_GetAudioDeviceName(devices[i]));
+    }
+
+    for (i = 0; i < devcount; i++) {
+        SDL_AudioStream *stream = NULL;
+        char *devname = SDL_GetAudioDeviceName(devices[i]);
         int j;
         SDL_AudioSpec spec;
         SDL_AudioDeviceID dev;
 
-        if (SDL_GetAudioDeviceSpec(i, 0, &spec) != 0) {
-            SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "SDL_GetAudioSpec() failed: %s\n", SDL_GetError());
+        SDL_Log("Testing audio device: %s\n", devname);
+        SDL_free(devname);
+
+        if (SDL_GetAudioDeviceFormat(devices[i], &spec) != 0) {
+            SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "SDL_GetAudioDeviceFormat() failed: %s\n", SDL_GetError());
             continue;
         }
 
+        SDL_Log("  (%d channels)\n", spec.channels);
+
         spec.freq = SAMPLE_RATE_HZ;
         spec.format = SDL_AUDIO_S16SYS;
-        spec.samples = 4096;
-        spec.callback = fill_buffer;
 
-        dev = SDL_OpenAudioDevice(devname, 0, &spec, NULL, 0);
+        dev = SDL_OpenAudioDevice(devices[i], &spec);
         if (dev == 0) {
             SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "SDL_OpenAudioDevice() failed: %s\n", SDL_GetError());
             continue;
         }
 
-        SDL_Log("Testing audio device: %s (%d channels)\n", devname, spec.channels);
+        stream = SDL_CreateAndBindAudioStream(dev, &spec);
+        if (stream == NULL) {
+            SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "SDL_CreateAndBindAudioStream() failed: %s\n", SDL_GetError());
+            SDL_CloseAudioDevice(dev);
+            continue;
+        }
 
         /* These are used by the fill_buffer callback */
         total_channels = spec.channels;
         active_channel = 0;
 
-        SDL_PlayAudioDevice(dev);
+        SDL_SetAudioStreamGetCallback(stream, fill_buffer, NULL);
 
         for (j = 0; j < total_channels; j++) {
-            int sine_freq = is_lfe_channel(j, total_channels) ? LFE_SINE_FREQ_HZ : SINE_FREQ_HZ;
+            const int sine_freq = is_lfe_channel(j, total_channels) ? LFE_SINE_FREQ_HZ : SINE_FREQ_HZ;
 
             SDL_Log("Playing %d Hz test tone on channel: %s\n", sine_freq, get_channel_name(j, total_channels));
 
@@ -212,8 +241,11 @@ int main(int argc, char *argv[])
         }
 
         SDL_CloseAudioDevice(dev);
+        SDL_DestroyAudioStream(stream);
     }
 
+    SDL_free(devices);
+
     SDL_Quit();
     return 0;
 }