docs/README-emscripten.md

# Emscripten

(This documentation is not very robust; we will update and expand this later.)

## A quick note about audio

Modern web browsers will not permit web pages to produce sound before the
user has interacted with them; this is for several reasons, not the least
of which being that no one likes when a random browser tab suddenly starts
making noise and the user has to scramble to figure out which and silence
it.

To solve this, most browsers will refuse to let a web app use the audio
subsystem at all before the user has interacted with (clicked on) the page
in a meaningful way. SDL-based apps also have to deal with this problem; if
the user hasn't interacted with the page, SDL_OpenAudioDevice will fail.

There are two reasonable ways to deal with this: if you are writing some
sort of media player thing, where the user expects there to be a volume
control when you mouseover the canvas, just default that control to a muted
state; if the user clicks on the control to unmute it, on this first click,
open the audio device. This allows the media to play at start, the user can
reasonably opt-in to listening, and you never get access denied to the audio
device.

Many games do not have this sort of UI, and are more rigid about starting
audio along with everything else at the start of the process. For these, your
best bet is to write a little Javascript that puts up a "Click here to play!"
UI, and upon the user clicking, remove that UI and then call the Emscripten
app's main() function. As far as the application knows, the audio device was
available to be opened as soon as the program started, and since this magic
happens in a little Javascript, you don't have to change your C/C++ code at
all to make it happen.

Please see the discussion at https://github.com/libsdl-org/SDL/issues/6385
for some Javascript code to steal for this approach.


## Building SDL/emscripten

SDL currently requires at least Emscripten 2.0.32 to build. Newer versions
are likely to work, as well.


Build:

    $ mkdir build
    $ cd build
    $ emcmake cmake ..
    $ emmake make

Or with cmake:

    $ mkdir build
    $ cd build
    $ emcmake cmake ..
    $ emmake make

To build one of the tests:

    $ cd test/
    $ emcc -O2 --js-opts 0 -g4 testdraw.c -I../include ../build/.libs/libSDL3.a ../build/libSDL3_test.a -o a.html

Uses GLES2 renderer or software

Some other SDL3 libraries can be easily built (assuming SDL3 is installed somewhere):

SDL_mixer (http://www.libsdl.org/projects/SDL_mixer/):

    $ emcmake cmake ..
    build as usual...

SDL_gfx (http://cms.ferzkopp.net/index.php/software/13-sdl-gfx):

    $ emcmake cmake ..
    build as usual...