audio: Allow SDL_GetAudioDeviceFormat() to query the default devices.

Officially removed SDL_GetDefaultAudioInfo(), as its functionality that
isn't obsolete is now offered elsewhere.

docs/README-migration.md

@@ -162,6 +162,8 @@ SDL_AudioSpec has been reduced; now it only holds format, channel, and sample ra
 
 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.
@@ -241,6 +243,7 @@ The following functions have been removed:
 * SDL_PauseAudio()
 * SDL_GetAudioStatus()
 * SDL_GetAudioDeviceStatus()
+* SDL_GetDefaultAudioInfo()
 * SDL_LockAudio()
 * SDL_LockAudioDevice()
 * SDL_UnlockAudio()

include/SDL3/SDL_audio.h

@@ -321,6 +321,11 @@ extern DECLSPEC char *SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceID devid);
  * the device's preferred format (or a reasonable default if this
  * can't be determined).
  *
+ * 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 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

src/audio/SDL_audio.c

@@ -966,6 +966,20 @@ int SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec)
         return SDL_InvalidParamError("spec");
     }
 
+    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 ((devid == 0) && is_default) {
+        return SDL_SetError("No default audio device available");
+        return 0;
+    }
+
     SDL_AudioDevice *device = ObtainPhysicalAudioDevice(devid);
     if (!device) {
         return -1;