mirror
/
SDL
mirror of https://github.com/libsdl-org/SDL.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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.
This commit is contained in:
Ryan C. Gordon 2024-10-21 23:36:56 -04:00
parent c56af0d975
commit b0982e8982
No known key found for this signature in database
GPG Key ID: FA148B892AB48044
1 changed files with 22 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
docs/README-emscripten.md
View File

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