diff --git a/docs/README-emscripten.md b/docs/README-emscripten.md index b2ee02b2ac..6bf1cacca8 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 -#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.