From f999d8d99fdcc0780d976ce2b051833f2c6a0e8d Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Mon, 20 Oct 2025 12:35:52 -0400
Subject: [PATCH] README-emscripten: Added a note about how the 2D API handles
vsync differently.
Reference PR #13962.
---
docs/README-emscripten.md | 15 +++++++++++++++
1 file changed, 15 insertions(+)
diff --git a/docs/README-emscripten.md b/docs/README-emscripten.md
index facda486f2b5c..2f976d14c1d4a 100644
--- a/docs/README-emscripten.md
+++ b/docs/README-emscripten.md
@@ -208,6 +208,21 @@ Calling SDL_RenderPresent (or SDL_GL_SwapWindow) will not actually
present anything on the screen until your return from your mainloop
function.
+Note that on other platforms, SDL will default to vsync _off_ in the 2D render
+API. Since changing this will affect how the mainloop runs, the 2D render API
+will only change vsync settings if explicitly requested by the app, either
+with SDL_PROP_RENDERER_CREATE_PRESENT_VSYNC_NUMBER, or calling
+SDL_SetRenderVSync(). Otherwise it will default to whatever the Emscripten
+mainloop is set to use via emscripten_set_main_loop().
+
+If you're using the SDL main callbacks, the mainloop defaults to using
+requestAnimationFrame (effectively vsync), because it calls
+emscripten_set_main_loop() with a zero fps. This is almost certainly what you
+want to do! Do this even if you aren't using the main callbacks!
+SDL will attempt to accomodate the app if it messes with vsync settings, or
+doesn't use requestAnimationFrame, but modern thinking is that this is the
+most efficient, consistent, and correct way to run a game in a web browser.
+
## Building SDL/emscripten