SDL: emscripten: Respect SDL_HINT_MAIN_CALLBACK_RATE.

From b3af72f69e1e958fd058eac35e77c1c06f0e406c Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Tue, 15 Jul 2025 15:48:22 -0400
Subject: [PATCH] emscripten: Respect SDL_HINT_MAIN_CALLBACK_RATE.

Fixes #13345.
---
 src/main/emscripten/SDL_sysmain_callbacks.c   | 67 ++++++++++++++++++-
 src/video/emscripten/SDL_emscriptenopengles.c | 13 ++--
 2 files changed, 73 insertions(+), 7 deletions(-)

diff --git a/src/main/emscripten/SDL_sysmain_callbacks.c b/src/main/emscripten/SDL_sysmain_callbacks.c
index babffb3b757c2..059e910c74d35 100644
--- a/src/main/emscripten/SDL_sysmain_callbacks.c
+++ b/src/main/emscripten/SDL_sysmain_callbacks.c
@@ -24,9 +24,61 @@
 
 #include <emscripten.h>
 
+// For Emscripten, we let you use SDL_HINT_MAIN_CALLBACK_RATE, because it might be useful to drop it super-low for
+//  things like loopwave that don't really do much but wait on the audio device, but be warned that browser timers
+//  are super-unreliable in modern times, so you likely won't hit your desired callback rate with good precision.
+// Almost all apps should leave this alone, so we can use requestAnimationFrame, which is intended to run reliably
+//  at the refresh rate of the user's display.
+static Uint32 callback_rate_increment = 0;
+static bool iterate_after_waitevent = false;
+static bool callback_rate_changed = false;
+static void SDLCALL MainCallbackRateHintChanged(void *userdata, const char *name, const char *oldValue, const char *newValue)
+{
+    callback_rate_changed = true;
+    iterate_after_waitevent = newValue && (SDL_strcmp(newValue, "waitevent") == 0);
+    if (iterate_after_waitevent) {
+        callback_rate_increment = 0;
+    } else {
+        const double callback_rate = newValue ? SDL_atof(newValue) : 0.0;
+        if (callback_rate > 0.0) {
+            callback_rate_increment = (Uint32) SDL_NS_TO_MS((double) SDL_NS_PER_SECOND / callback_rate);
+        } else {
+            callback_rate_increment = 0;
+        }
+    }
+}
+
+// just tell us when any new event is pushed on the queue, so we can check a flag for "waitevent" mode.
+static bool saw_new_event = false;
+static bool SDLCALL EmscriptenMainCallbackEventWatcher(void *userdata, SDL_Event *event)
+{
+    saw_new_event = true;
+    return true;
+}
+
 static void EmscriptenInternalMainloop(void)
 {
-    const SDL_AppResult rc = SDL_IterateMainCallbacks(true);
+    // callback rate changed? Update emscripten's mainloop iteration speed.
+    if (callback_rate_changed) {
+        callback_rate_changed = false;
+        if (callback_rate_increment == 0) {
+            emscripten_set_main_loop_timing(EM_TIMING_RAF, 1);
+        } else {
+            emscripten_set_main_loop_timing(EM_TIMING_SETTIMEOUT, callback_rate_increment);
+        }
+    }
+
+    if (iterate_after_waitevent) {
+        SDL_PumpEvents();
+        if (!saw_new_event) {
+            // do nothing yet. Note that we're still going to iterate here because we can't block,
+            // but we can stop the app's iteration from progressing until there's an event.
+            return;
+        }
+        saw_new_event = false;
+    }
+
+    const SDL_AppResult rc = SDL_IterateMainCallbacks(!iterate_after_waitevent);
     if (rc != SDL_APP_CONTINUE) {
         SDL_QuitMainCallbacks(rc);
         emscripten_cancel_main_loop();  // kill" the mainloop, so it stops calling back into it.
@@ -36,9 +88,18 @@ static void EmscriptenInternalMainloop(void)
 
 int SDL_EnterAppMainCallbacks(int argc, char *argv[], SDL_AppInit_func appinit, SDL_AppIterate_func appiter, SDL_AppEvent_func appevent, SDL_AppQuit_func appquit)
 {
-    const SDL_AppResult rc = SDL_InitMainCallbacks(argc, argv, appinit, appiter, appevent, appquit);
+    SDL_AppResult rc = SDL_InitMainCallbacks(argc, argv, appinit, appiter, appevent, appquit);
     if (rc == SDL_APP_CONTINUE) {
-        emscripten_set_main_loop(EmscriptenInternalMainloop, 0, 0);  // run at refresh rate, don't throw an exception since we do an orderly return.
+        if (!SDL_AddEventWatch(EmscriptenMainCallbackEventWatcher, NULL)) {
+            rc = SDL_APP_FAILURE;
+        } else {
+            SDL_AddHintCallback(SDL_HINT_MAIN_CALLBACK_RATE, MainCallbackRateHintChanged, NULL);
+            callback_rate_changed = false;
+            emscripten_set_main_loop(EmscriptenInternalMainloop, 0, 0);  // don't throw an exception since we do an orderly return.
+            if (callback_rate_increment > 0.0) {
+                emscripten_set_main_loop_timing(EM_TIMING_SETTIMEOUT, callback_rate_increment);
+            }
+        }
     } else {
         SDL_QuitMainCallbacks(rc);
     }
diff --git a/src/video/emscripten/SDL_emscriptenopengles.c b/src/video/emscripten/SDL_emscriptenopengles.c
index bb490bb016afb..39faf2fb019ea 100644
--- a/src/video/emscripten/SDL_emscriptenopengles.c
+++ b/src/video/emscripten/SDL_emscriptenopengles.c
@@ -28,6 +28,7 @@
 
 #include "SDL_emscriptenvideo.h"
 #include "SDL_emscriptenopengles.h"
+#include "../../main/SDL_main_callbacks.h"
 
 bool Emscripten_GLES_LoadLibrary(SDL_VideoDevice *_this, const char *path)
 {
@@ -50,10 +51,14 @@ bool Emscripten_GLES_SetSwapInterval(SDL_VideoDevice *_this, int interval)
     }
 
     if (Emscripten_ShouldSetSwapInterval(interval)) {
-        if (interval == 0) {
-            emscripten_set_main_loop_timing(EM_TIMING_SETTIMEOUT, 0);
-        } else {
-            emscripten_set_main_loop_timing(EM_TIMING_RAF, interval);
+        // don't change the mainloop timing if the app is also driving a main callback with this hint,
+        //  as we assume that was the more deliberate action.
+        if (!SDL_HasMainCallbacks() || !SDL_GetHint(SDL_HINT_MAIN_CALLBACK_RATE)) {
+            if (interval == 0) {
+                emscripten_set_main_loop_timing(EM_TIMING_SETTIMEOUT, 0);
+            } else {
+                emscripten_set_main_loop_timing(EM_TIMING_RAF, interval);
+            }
         }
     }