audio: add a SDL_GetPhysicalAudioDevice method, for mapping logical to physical device ids

include/SDL3/SDL_audio.h

@@ -759,6 +759,21 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDevic
  */
 extern SDL_DECLSPEC bool SDLCALL SDL_IsAudioDevicePhysical(SDL_AudioDeviceID devid);
 
+/**
+ * Get the physical audio device associated with a logical audio device.
+ *
+ * If `devid` is already a physical device, this function returns `devid`.
+ * If `devid` is an invalid device, it returns 0.
+ *
+ * \param devid the device ID to query.
+ * \returns the physical device ID, or 0 on error.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.5.0.
+ */
+extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_GetPhysicalAudioDevice(SDL_AudioDeviceID devid);
+
 /**
  * Determine if an audio device is a playback device (instead of recording).
  *

src/audio/SDL_audio.c

@@ -538,6 +538,20 @@ static SDL_AudioDevice *ObtainPhysicalAudioDeviceDefaultAllowed(SDL_AudioDeviceI
     return NULL;
 }
 
+SDL_AudioDeviceID SDL_GetPhysicalAudioDevice(SDL_AudioDeviceID devid)
+{
+    if (SDL_IsAudioDevicePhysical(devid)) {
+        return devid;
+    }
+
+    SDL_AudioDeviceID result = 0;
+    SDL_AudioDevice *device = ObtainPhysicalAudioDeviceDefaultAllowed(devid);
+    if (device) {
+        result = device->instance_id;
+        ReleaseAudioDevice(device);
+    }
+    return result;
+}
 // this assumes you hold the _physical_ device lock for this logical device! This will not unlock the lock or close the physical device!
 //  It also will not unref the physical device, since we might be shutting down; SDL_CloseAudioDevice handles the unref.
 static void DestroyLogicalAudioDevice(SDL_LogicalAudioDevice *logdev)

src/dynapi/SDL_dynapi.exports

@@ -1290,3 +1290,4 @@ _SDL_LoadJPG
 _SDL_HasSVE2
 _SDL_GamepadHasCapSense
 _SDL_GetGamepadCapSense
+_SDL_GetPhysicalAudioDevice

src/dynapi/SDL_dynapi.sym

@@ -1291,6 +1291,7 @@ SDL3_0.0.0 {
     SDL_HasSVE2;
     SDL_GamepadHasCapSense;
     SDL_GetGamepadCapSense;
+    SDL_GetPhysicalAudioDevice;
     # extra symbols go here (don't modify this line)
   local: *;
 };

src/dynapi/SDL_dynapi_overrides.h

@@ -1317,3 +1317,4 @@
 #define SDL_HasSVE2 SDL_HasSVE2_REAL
 #define SDL_GamepadHasCapSense SDL_GamepadHasCapSense_REAL
 #define SDL_GetGamepadCapSense SDL_GetGamepadCapSense_REAL
+#define SDL_GetPhysicalAudioDevice SDL_GetPhysicalAudioDevice_REAL

src/dynapi/SDL_dynapi_procs.h

@@ -1325,3 +1325,4 @@ SDL_DYNAPI_PROC(SDL_Surface*,SDL_LoadJPG,(const char *a),(a),return)
 SDL_DYNAPI_PROC(bool,SDL_HasSVE2,(void),(),return)
 SDL_DYNAPI_PROC(bool,SDL_GamepadHasCapSense,(SDL_Gamepad *a,SDL_GamepadCapSenseType b),(a,b),return)
 SDL_DYNAPI_PROC(bool,SDL_GetGamepadCapSense,(SDL_Gamepad *a,SDL_GamepadCapSenseType b),(a,b),return)
+SDL_DYNAPI_PROC(SDL_AudioDeviceID,SDL_GetPhysicalAudioDevice,(SDL_AudioDeviceID a),(a),return)