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

@@ -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.