From b0982e89828a4f18a203f1127da90ef8753a1b32 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Mon, 21 Oct 2024 23:36:56 -0400
Subject: [PATCH] docs: Updated README-emscripten.md.
This now mentions the main callbacks as a possible option, and removes the
part about prebuilt libraries. The latter can return when Emscripten packages
SDL3.
Fixes #11080.
---
docs/README-emscripten.md | 59 +++++++++++++++------------------------
1 file changed, 22 insertions(+), 37 deletions(-)
diff --git a/docs/README-emscripten.md b/docs/README-emscripten.md
index b2ee02b2ac64e..6bf1cacca8e86 100644
--- a/docs/README-emscripten.md
+++ b/docs/README-emscripten.md
@@ -2,7 +2,7 @@
## The state of things
-(As of September 2023, but things move quickly and we don't update this
+(As of October 2024, but things move quickly and we don't update this
document often.)
In modern times, all the browsers you probably care about (Chrome, Firefox,
@@ -33,23 +33,15 @@ Many many things just need some simple adjustments and they'll compile
like any other C/C++ code, as long as SDL was handling the platform-specific
work for your program.
-First, you probably need this in at least one of your source files:
-
-```c
-#ifdef __EMSCRIPTEN__
-#include <emscripten.h>
-#endif
-```
-
-Second: assembly language code has to go. Replace it with C. You can even use
+First: assembly language code has to go. Replace it with C. You can even use
[x86 SIMD intrinsic functions in Emscripten](https://emscripten.org/docs/porting/simd.html)!
-Third: Middleware has to go. If you have a third-party library you link
+Second: Middleware has to go. If you have a third-party library you link
against, you either need an Emscripten port of it, or the source code to it
to compile yourself, or you need to remove it.
-Fourth: You still start in a function called main(), but you need to get out of
-it and into a function that gets called repeatedly, and returns quickly,
+Third: If your program starts in a function called main(), you need to get
+out of it and into a function that gets called repeatedly, and returns quickly,
called a mainloop.
Somewhere in your program, you probably have something that looks like a more
@@ -109,6 +101,13 @@ don't want any shutdown code that might be sitting below this code
to actually run if main() were to continue on, since we're just
getting started.
+Another option is to use SDL' main callbacks, which handle this for you
+without platform-specific code in your app. Please refer to
+[the wiki](https://wiki.libsdl.org/SDL3/README/main-functions#main-callbacks-in-sdl3)
+or `docs/README-main-functions.md` in the SDL source code.
+
+
+
There's a lot of little details that are beyond the scope of this
document, but that's the biggest initial set of hurdles to porting
your app to the web.
@@ -127,8 +126,8 @@ must be there, but you have to be careful (and read more detailed
documentation than this for the finer points).
Even when using threads, your main thread needs to set an Emscripten
-mainloop that runs quickly and returns, or things will fail to work
-correctly.
+mainloop (or use SDL's main callbacks) that runs quickly and returns, or
+things will fail to work correctly.
You should definitely read [Emscripten's pthreads docs](https://emscripten.org/docs/porting/pthreads.html)
for all the finer points. Mostly SDL's thread API will work as expected,
@@ -202,6 +201,9 @@ If you use SDL's 2D render API, it will use GLES2 internally, which
Emscripten will turn into WebGL calls. You can also use OpenGL ES 2
directly by creating a GL context and drawing into it.
+If the browser (and hardware) support WebGL 2, you can create an OpenGL ES 3
+context.
+
Calling SDL_RenderPresent (or SDL_GL_SwapWindow) will not actually
present anything on the screen until your return from your mainloop
function.
@@ -209,25 +211,8 @@ function.
## Building SDL/emscripten
-First: do you _really_ need to build SDL from source?
-
-If you aren't developing SDL itself, have a desire to mess with its source
-code, or need something on the bleeding edge, don't build SDL. Just use
-Emscripten's packaged version!
-
-Compile and link your app with `-sUSE_SDL=2` and it'll use a build of
-SDL packaged with Emscripten. This comes from the same source code and
-fixes the Emscripten project makes to SDL are generally merged into SDL's
-revision control, so often this is much easier for app developers.
-
-`-sUSE_SDL=1` will select Emscripten's JavaScript reimplementation of SDL
-1.2 instead; if you need SDL 1.2, this might be fine, but we generally
-recommend you don't use SDL 1.2 in modern times.
-
-
-If you want to build SDL, though...
-SDL currently requires at least Emscripten 3.1.35 to build. Newer versions
+SDL currently requires at least Emscripten 3.16.0 to build. Newer versions
are likely to work, as well.
@@ -260,6 +245,7 @@ emmake make -j4
To build the tests, add -DSDL_TESTS=On to the emcmake cmake command line.
+To build the examples, add -DSDL_EXAMPLES=On to the emcmake cmake command line.
Building your app
@@ -267,8 +253,7 @@ To build the tests, add -DSDL_TESTS=On to the emcmake cmake command line.
You need to compile with emcc instead of gcc or clang or whatever, but
mostly it uses the same command line arguments as Clang.
-Link against the SDL/build/libSDL3.a file you generated by building SDL,
-link with -sUSE_SDL=2 to use Emscripten’s prepackaged SDL2 build.
+Link against the libSDL3.a file you generated by building SDL.
Usually you would produce a binary like this:
@@ -288,8 +273,8 @@ runs your app. You will (probably) eventually want to replace or customize
that file and do -o index.js instead to just build the code pieces.
If you’re working on a program of any serious size, you’ll likely need to
-link with -sALLOW_MEMORY_GROWTH=1 -sMAXIMUM_MEMORY=1gb to get access
-to more memory. If using pthreads, you’ll need the -sMAXIMUM_MEMORY=1gb
+link with -s ALLOW_MEMORY_GROWTH=1 -s MAXIMUM_MEMORY=1gb to get access
+to more memory. If using pthreads, you’ll need the -s MAXIMUM_MEMORY=1gb
or the app will fail to start on iOS browsers, but this might be a bug that
goes away in the future.