Add SDL_GetAudioDeviceSpec.

This API is supported by pipewire, pulseaudio, coreaudio, wasapi, and disk.

Author: flibitijibibo

include/SDL_audio.h

@@ -359,6 +359,25 @@ extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture);
 extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index,
                                                            int iscapture);
 
+/**
+ *  Get the audio format of a specific audio device.
+ *  Must be a value between 0 and (number of audio devices-1).
+ *  Only valid after a successfully initializing the audio subsystem.
+ *  The values returned by this function reflect the latest call to
+ *  SDL_GetNumAudioDevices(); recall that function to redetect available
+ *  hardware.
+ *
+ *  The spec will be filled with the sample rate, sample format, and channel
+ *  count. All other values in the structure are filled with 0. When the
+ *  supported struct members are 0, SDL was unable to get the property from the
+ *  backend.
+ *
+ *  \return 0 on success, nonzero on error
+ */
+extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
+                                                   int iscapture,
+                                                   SDL_AudioSpec *spec);
+
 
 /**
  *  Open a specific audio device. Passing in a device name of NULL requests

src/audio/SDL_audio.c

@@ -223,9 +223,9 @@ SDL_AudioDetectDevices_Default(void)
     SDL_assert(current_audio.impl.OnlyHasDefaultOutputDevice);
     SDL_assert(current_audio.impl.OnlyHasDefaultCaptureDevice || !current_audio.impl.HasCaptureSupport);
 
-    SDL_AddAudioDevice(SDL_FALSE, DEFAULT_OUTPUT_DEVNAME, (void *) ((size_t) 0x1));
+    SDL_AddAudioDevice(SDL_FALSE, DEFAULT_OUTPUT_DEVNAME, NULL, (void *) ((size_t) 0x1));
     if (current_audio.impl.HasCaptureSupport) {
-        SDL_AddAudioDevice(SDL_TRUE, DEFAULT_INPUT_DEVNAME, (void *) ((size_t) 0x2));
+        SDL_AddAudioDevice(SDL_TRUE, DEFAULT_INPUT_DEVNAME, NULL, (void *) ((size_t) 0x2));
     }
 }
 
@@ -377,7 +377,7 @@ finish_audio_entry_points_init(void)
 /* device hotplug support... */
 
 static int
-add_audio_device(const char *name, void *handle, SDL_AudioDeviceItem **devices, int *devCount)
+add_audio_device(const char *name, SDL_AudioSpec *spec, void *handle, SDL_AudioDeviceItem **devices, int *devCount)
 {
     int retval = -1;
     SDL_AudioDeviceItem *item;
@@ -400,6 +400,11 @@ add_audio_device(const char *name, void *handle, SDL_AudioDeviceItem **devices,
 
     item->dupenum = 0;
     item->name = item->original_name;
+    if (spec != NULL) {
+        SDL_memcpy(&item->spec, spec, sizeof(SDL_AudioSpec));
+    } else {
+        SDL_zero(item->spec);
+    }
     item->handle = handle;
 
     SDL_LockMutex(current_audio.detectionLock);
@@ -437,16 +442,16 @@ add_audio_device(const char *name, void *handle, SDL_AudioDeviceItem **devices,
 }
 
 static SDL_INLINE int
-add_capture_device(const char *name, void *handle)
+add_capture_device(const char *name, SDL_AudioSpec *spec, void *handle)
 {
     SDL_assert(current_audio.impl.HasCaptureSupport);
-    return add_audio_device(name, handle, &current_audio.inputDevices, &current_audio.inputDeviceCount);
+    return add_audio_device(name, spec, handle, &current_audio.inputDevices, &current_audio.inputDeviceCount);
 }
 
 static SDL_INLINE int
-add_output_device(const char *name, void *handle)
+add_output_device(const char *name, SDL_AudioSpec *spec, void *handle)
 {
-    return add_audio_device(name, handle, &current_audio.outputDevices, &current_audio.outputDeviceCount);
+    return add_audio_device(name, spec, handle, &current_audio.outputDevices, &current_audio.outputDeviceCount);
 }
 
 static void
@@ -472,9 +477,9 @@ free_device_list(SDL_AudioDeviceItem **devices, int *devCount)
 
 /* The audio backends call this when a new device is plugged in. */
 void
-SDL_AddAudioDevice(const int iscapture, const char *name, void *handle)
+SDL_AddAudioDevice(const int iscapture, const char *name, SDL_AudioSpec *spec, void *handle)
 {
-    const int device_index = iscapture ? add_capture_device(name, handle) : add_output_device(name, 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 */
         if (SDL_GetEventState(SDL_AUDIODEVICEADDED) == SDL_ENABLE) {
@@ -1112,6 +1117,44 @@ SDL_GetAudioDeviceName(int index, int iscapture)
 }
 
 
+int
+SDL_GetAudioDeviceSpec(int index, int iscapture, SDL_AudioSpec *spec)
+{
+    if (spec == NULL) {
+        return SDL_InvalidParamError("spec");
+    }
+
+    SDL_zerop(spec);
+
+    if (!SDL_WasInit(SDL_INIT_AUDIO)) {
+        return SDL_SetError("Audio subsystem is not initialized");
+    }
+
+    if (iscapture && !current_audio.impl.HasCaptureSupport) {
+        return SDL_SetError("No capture support");
+    }
+
+    if (index >= 0) {
+        SDL_AudioDeviceItem *item;
+        int i;
+
+        SDL_LockMutex(current_audio.detectionLock);
+        item = iscapture ? current_audio.inputDevices : current_audio.outputDevices;
+        i = iscapture ? current_audio.inputDeviceCount : current_audio.outputDeviceCount;
+        if (index < i) {
+            for (i--; i > index; i--, item = item->next) {
+                SDL_assert(item != NULL);
+            }
+            SDL_assert(item != NULL);
+            SDL_memcpy(spec, &item->spec, sizeof(SDL_AudioSpec));
+        }
+        SDL_UnlockMutex(current_audio.detectionLock);
+    }
+
+    return 0;
+}
+
+
 static void
 close_audio_device(SDL_AudioDevice * device)
 {

src/audio/SDL_audiodev.c

@@ -59,7 +59,13 @@ test_device(const int iscapture, const char *fname, int flags, int (*test) (int
                 static size_t dummyhandle = 0;
                 dummyhandle++;
                 SDL_assert(dummyhandle != 0);
-                SDL_AddAudioDevice(iscapture, fname, (void *) dummyhandle);
+
+                /* Note that spec is NULL; while we are opening the device
+                 * endpoint here, the endpoint does not provide any mix format
+                 * information,  making this information inaccessible at
+                 * enumeration time
+                 */
+                SDL_AddAudioDevice(iscapture, fname, NULL, (void *) dummyhandle);
             }
         }
     }

src/audio/SDL_sysaudio.h

@@ -39,7 +39,7 @@ typedef struct SDL_AudioDevice SDL_AudioDevice;
 /* Audio targets 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 int iscapture, const char *name, void *handle);
+extern void SDL_AddAudioDevice(const int 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. */
@@ -99,6 +99,7 @@ typedef struct SDL_AudioDeviceItem
     void *handle;
     char *name;
     char *original_name;
+    SDL_AudioSpec spec;
     int dupenum;
     struct SDL_AudioDeviceItem *next;
 } SDL_AudioDeviceItem;

src/audio/alsa/SDL_alsa_audio.c

@@ -765,7 +765,11 @@ add_device(const int iscapture, const char *name, void *hint, ALSA_Device **pSee
         return;
     }
 
-    SDL_AddAudioDevice(iscapture, desc, handle);
+    /* 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(iscapture, desc, NULL, handle);
     if (hint)
         free(desc);
     dev->name = handle;

src/audio/coreaudio/SDL_coreaudio.m

@@ -56,7 +56,7 @@
     kAudioObjectPropertyElementMaster
 };
 
-typedef void (*addDevFn)(const char *name, const int iscapture, AudioDeviceID devId, void *data);
+typedef void (*addDevFn)(const char *name, SDL_AudioSpec *spec, const int iscapture, AudioDeviceID devId, void *data);
 
 typedef struct AudioDeviceList
 {
@@ -88,10 +88,10 @@
 }
 
 static void
-addToDevList(const char *name, const int iscapture, AudioDeviceID devId, void *data)
+addToDevList(const char *name, SDL_AudioSpec *spec, const int iscapture, AudioDeviceID devId, void *data)
 {
     if (add_to_internal_dev_list(iscapture, devId)) {
-        SDL_AddAudioDevice(iscapture, name, (void *) ((size_t) devId));
+        SDL_AddAudioDevice(iscapture, name, spec, (void *) ((size_t) devId));
     }
 }
 
@@ -126,17 +126,23 @@
         AudioBufferList *buflist = NULL;
         int usable = 0;
         CFIndex len = 0;
+        double sampleRate = 0;
+        SDL_AudioSpec spec;
         const AudioObjectPropertyAddress addr = {
             kAudioDevicePropertyStreamConfiguration,
             iscapture ? kAudioDevicePropertyScopeInput : kAudioDevicePropertyScopeOutput,
             kAudioObjectPropertyElementMaster
         };
-
         const AudioObjectPropertyAddress nameaddr = {
             kAudioObjectPropertyName,
             iscapture ? kAudioDevicePropertyScopeInput : kAudioDevicePropertyScopeOutput,
             kAudioObjectPropertyElementMaster
         };
+        const AudioObjectPropertyAddress freqaddr = {
+            kAudioDevicePropertyNominalSampleRate,
+            iscapture ? kAudioDevicePropertyScopeInput : kAudioDevicePropertyScopeOutput,
+            kAudioObjectPropertyElementMaster
+        };
 
         result = AudioObjectGetPropertyDataSize(dev, &addr, 0, NULL, &size);
         if (result != noErr)
@@ -149,21 +155,24 @@
         result = AudioObjectGetPropertyData(dev, &addr, 0, NULL,
                                             &size, buflist);
 
+        SDL_zero(spec);
         if (result == noErr) {
             UInt32 j;
             for (j = 0; j < buflist->mNumberBuffers; j++) {
-                if (buflist->mBuffers[j].mNumberChannels > 0) {
-                    usable = 1;
-                    break;
-                }
+                spec.channels += buflist->mBuffers[j].mNumberChannels;
             }
         }
 
         SDL_free(buflist);
 
-        if (!usable)
+        if (spec.channels == 0)
             continue;
 
+        size = sizeof (sampleRate);
+        result = AudioObjectGetPropertyData(dev, &freqaddr, 0, NULL, &size, &sampleRate);
+        if (result == noErr) {
+            spec.freq = (int) sampleRate;
+        }
 
         size = sizeof (CFStringRef);
         result = AudioObjectGetPropertyData(dev, &nameaddr, 0, NULL, &size, &cfstr);
@@ -197,7 +206,7 @@
                    ((iscapture) ? "capture" : "output"),
                    (int) i, ptr, (int) dev);
 #endif
-            addfn(ptr, iscapture, dev, addfndata);
+            addfn(ptr, &spec, iscapture, dev, addfndata);
         }
         SDL_free(ptr);  /* addfn() would have copied the string. */
     }
@@ -223,7 +232,7 @@
 }
 
 static void
-build_device_change_list(const char *name, const int iscapture, AudioDeviceID devId, void *data)
+build_device_change_list(const char *name, SDL_AudioSpec *spec, const int iscapture, AudioDeviceID devId, void *data)
 {
     AudioDeviceList **list = (AudioDeviceList **) data;
     AudioDeviceList *item;
@@ -235,7 +244,7 @@
     }
 
     add_to_internal_dev_list(iscapture, devId);  /* new device, add it. */
-    SDL_AddAudioDevice(iscapture, name, (void *) ((size_t) devId));
+    SDL_AddAudioDevice(iscapture, name, spec, (void *) ((size_t) devId));
 }
 
 static void

src/audio/directsound/SDL_directsound.c

@@ -163,7 +163,12 @@ FindAllDevs(LPGUID guid, LPCWSTR desc, LPCWSTR module, LPVOID data)
         if (str != NULL) {
             LPGUID cpyguid = (LPGUID) SDL_malloc(sizeof (GUID));
             SDL_memcpy(cpyguid, guid, sizeof (GUID));
-            SDL_AddAudioDevice(iscapture, str, cpyguid);
+
+            /* 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. */
         }
     }

src/audio/disk/SDL_diskaudio.c

@@ -173,8 +173,8 @@ DISKAUDIO_OpenDevice(_THIS, void *handle, const char *devname, int iscapture)
 static void
 DISKAUDIO_DetectDevices(void)
 {
-    SDL_AddAudioDevice(SDL_FALSE, DEFAULT_OUTPUT_DEVNAME, (void *) 0x1);
-    SDL_AddAudioDevice(SDL_TRUE, DEFAULT_INPUT_DEVNAME, (void *) 0x2);
+    SDL_AddAudioDevice(SDL_FALSE, DEFAULT_OUTPUT_DEVNAME, NULL, (void *) 0x1);
+    SDL_AddAudioDevice(SDL_TRUE, DEFAULT_INPUT_DEVNAME, NULL, (void *) 0x2);
 }
 
 static int

src/audio/os2/SDL_os2audio.c

@@ -160,9 +160,9 @@ static void OS2_DetectDevices(void)
         }
 
         ulHandle++;
-        SDL_AddAudioDevice(0, stLogDevice.szProductInfo, (void *)(ulHandle));
+        SDL_AddAudioDevice(0, stLogDevice.szProductInfo, NULL, (void *)(ulHandle));
         ulHandle++;
-        SDL_AddAudioDevice(1, stLogDevice.szProductInfo, (void *)(ulHandle));
+        SDL_AddAudioDevice(1, stLogDevice.szProductInfo, NULL, (void *)(ulHandle));
     }
 }
 

src/audio/pipewire/SDL_pipewire.c

@@ -266,7 +266,7 @@ io_list_check_add(struct io_node *node)
     spa_list_append(&hotplug_io_list, &node->link);
 
     if (SDL_AtomicGet(&hotplug_events_enabled)) {
-        SDL_AddAudioDevice(node->is_capture, node->name, PW_ID_TO_HANDLE(node->id));
+        SDL_AddAudioDevice(node->is_capture, node->name, &node->spec, PW_ID_TO_HANDLE(node->id));
     }
 
 dup_found:
@@ -768,7 +768,7 @@ PIPEWIRE_DetectDevices()
     io_list_sort();
 
     spa_list_for_each (io, &hotplug_io_list, link) {
-        SDL_AddAudioDevice(io->is_capture, io->name, PW_ID_TO_HANDLE(io->id));
+        SDL_AddAudioDevice(io->is_capture, io->name, &io->spec, PW_ID_TO_HANDLE(io->id));
     }
 
     SDL_AtomicSet(&hotplug_events_enabled, 1);