From ce573b01f87272f35fa29a16a459350ca0af65ff Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <icculus@icculus.org>
Date: Thu, 28 Nov 2024 01:21:42 -0500
Subject: [PATCH] audio: Added SDL_IsAudioDevicePhysical and
 SDL_IsAudioDevicePlayback.

Fixes #11529.
---
 include/SDL3/SDL_audio.h          | 35 +++++++++++++++++++++++++++++++
 src/audio/SDL_audio.c             | 10 +++++++++
 src/dynapi/SDL_dynapi.sym         |  2 ++
 src/dynapi/SDL_dynapi_overrides.h |  2 ++
 src/dynapi/SDL_dynapi_procs.h     |  2 ++
 5 files changed, 51 insertions(+)

diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h
index f2395e516c1bc..dc71dc9234a4e 100644
--- a/include/SDL3/SDL_audio.h
+++ b/include/SDL3/SDL_audio.h
@@ -679,6 +679,41 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioDeviceChannelMap(SDL_AudioDeviceID
  */
 extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec);
 
+/**
+ * Determine if an audio device is physical (instead of logical).
+ *
+ * An SDL_AudioDeviceID that represents physical hardare is a physical device;
+ * there is one for each piece of hardware that SDL can see. Logical devices
+ * are created by calling SDL_OpenAudioDevice or SDL_OpenAudioDeviceStream,
+ * and while each is associated with a physical device, there can be any
+ * number of logical devices on one physical device.
+ *
+ * For the most part, logical and physical IDs are interchangeable--if you
+ * try to open a logical device, SDL understands to assign that effort to the
+ * underlying physical device, etc. However, it might be useful to know if an
+ * arbitrary device ID is physical or logical. This function reports which.
+ *
+ * This function may return either true or false for invalid device IDs.
+ *
+ * \param devid the device ID to query.
+ * \returns true if devid is a physical device, false if it is logical.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ */
+extern SDL_DECLSPEC bool SDLCALL SDL_IsAudioDevicePhysical(SDL_AudioDeviceID devid);
+
+/**
+ * Determine if an audio device is a playback device (instead of recording).
+ *
+ * This function may return either true or false for invalid device IDs.
+ *
+ * \param devid the device ID to query.
+ * \returns true if devid is a playback device, false if it is recording.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ */
+extern SDL_DECLSPEC bool SDLCALL SDL_IsAudioDevicePlayback(SDL_AudioDeviceID devid);
+
 /**
  * Use this function to pause audio playback on a specified device.
  *
diff --git a/src/audio/SDL_audio.c b/src/audio/SDL_audio.c
index 2de86cec5cb46..e891a0a95a830 100644
--- a/src/audio/SDL_audio.c
+++ b/src/audio/SDL_audio.c
@@ -346,6 +346,16 @@ static SDL_AudioDeviceID AssignAudioDeviceInstanceId(bool recording, bool islogi
     return instance_id;
 }
 
+bool SDL_IsAudioDevicePhysical(SDL_AudioDeviceID devid)
+{
+    return (devid & (1 << 1)) != 0;
+}
+
+bool SDL_IsAudioDevicePlayback(SDL_AudioDeviceID devid)
+{
+    return (devid & (1 << 0)) != 0;
+}
+
 static void ObtainPhysicalAudioDeviceObj(SDL_AudioDevice *device) SDL_NO_THREAD_SAFETY_ANALYSIS  // !!! FIXMEL SDL_ACQUIRE
 {
     if (device) {
diff --git a/src/dynapi/SDL_dynapi.sym b/src/dynapi/SDL_dynapi.sym
index c750acc421634..b01bae8f62bcc 100644
--- a/src/dynapi/SDL_dynapi.sym
+++ b/src/dynapi/SDL_dynapi.sym
@@ -1187,6 +1187,8 @@ SDL3_0.0.0 {
     SDL_SaveFile_IO;
     SDL_SaveFile;
     SDL_GetCurrentDirectory;
+    SDL_IsAudioDevicePhysical;
+    SDL_IsAudioDevicePlayback;
     # extra symbols go here (don't modify this line)
   local: *;
 };
diff --git a/src/dynapi/SDL_dynapi_overrides.h b/src/dynapi/SDL_dynapi_overrides.h
index cac3f0b7dddd8..40c8a7536a36e 100644
--- a/src/dynapi/SDL_dynapi_overrides.h
+++ b/src/dynapi/SDL_dynapi_overrides.h
@@ -1212,3 +1212,5 @@
 #define SDL_SaveFile_IO SDL_SaveFile_IO_REAL
 #define SDL_SaveFile SDL_SaveFile_REAL
 #define SDL_GetCurrentDirectory SDL_GetCurrentDirectory_REAL
+#define SDL_IsAudioDevicePhysical SDL_IsAudioDevicePhysical_REAL
+#define SDL_IsAudioDevicePlayback SDL_IsAudioDevicePlayback_REAL
diff --git a/src/dynapi/SDL_dynapi_procs.h b/src/dynapi/SDL_dynapi_procs.h
index 36a8ad0cf8255..ca07422b94892 100644
--- a/src/dynapi/SDL_dynapi_procs.h
+++ b/src/dynapi/SDL_dynapi_procs.h
@@ -1218,3 +1218,5 @@ SDL_DYNAPI_PROC(bool,SDL_CancelGPUCommandBuffer,(SDL_GPUCommandBuffer *a),(a),re
 SDL_DYNAPI_PROC(bool,SDL_SaveFile_IO,(SDL_IOStream *a,const void *b,size_t c,bool d),(a,b,c,d),return)
 SDL_DYNAPI_PROC(bool,SDL_SaveFile,(const char *a,const void *b,size_t c),(a,b,c),return)
 SDL_DYNAPI_PROC(char*,SDL_GetCurrentDirectory,(void),(),return)
+SDL_DYNAPI_PROC(bool,SDL_IsAudioDevicePhysical,(SDL_AudioDeviceID a),(a),return)
+SDL_DYNAPI_PROC(bool,SDL_IsAudioDevicePlayback,(SDL_AudioDeviceID a),(a),return)