audio: Added a hint to let apps force device buffer size.

This is a hint because apps might (probably mistakenly) believe they need this
to migrate from SDL2, but most things don't need to specify this.

include/SDL3/SDL_hints.h

@@ -2510,6 +2510,26 @@ extern "C" {
  */
 #define SDL_HINT_GDK_TEXTINPUT_MAX_LENGTH "SDL_GDK_TEXTINPUT_MAX_LENGTH"
 
+/**
+ * Set the next device open's buffer size.
+ *
+ * This hint is an integer > 0, that represents the size of the device's
+ * buffer in sample frames (stereo audio data in 16-bit format is 4 bytes
+ * per sample frame, for example).
+ *
+ * SDL3 generally decides this value on behalf of the app, but if for some
+ * reason the app needs to dictate this (because they want either lower
+ * latency or higher throughput AND ARE WILLING TO DEAL WITH what that
+ * might require of the app), they can specify it.
+ *
+ * SDL will try to accomodate this value, but there is no promise you'll
+ * get the buffer size requested. Many platforms won't honor this request
+ * at all, or might adjust it.
+ *
+ * This hint is checked when opening an audio device and can be changed
+ * between calls.
+ */
+#define SDL_HINT_AUDIO_DEVICE_SAMPLE_FRAMES "SDL_AUDIO_DEVICE_SAMPLE_FRAMES"
 
 /**
  *  \brief  An enumeration of hint priorities

src/audio/SDL_audio.c

@@ -1248,6 +1248,14 @@ static void PrepareAudioFormat(SDL_bool iscapture, SDL_AudioSpec *spec)
 
 static int GetDefaultSampleFramesFromFreq(const int freq)
 {
+    const char *hint = SDL_GetHint(SDL_HINT_AUDIO_DEVICE_SAMPLE_FRAMES);
+    if (hint) {
+        const int val = SDL_atoi(hint);
+        if (val > 0) {
+            return val;
+        }
+    }
+
     if (freq <= 11025) {
         return 512;
     } else if (freq <= 22050) {
@@ -1256,9 +1264,9 @@ static int GetDefaultSampleFramesFromFreq(const int freq)
         return 2048;
     } else if (freq <= 96000) {
         return 4096;
-    } else {
-        return 8192;  // shrug
     }
+
+    return 8192;  // shrug
 }
 
 void SDL_UpdatedAudioDeviceFormat(SDL_AudioDevice *device)