Merge commit 'dec0d4ec4153bf9fc2b78ae6c2df45b6ea8dde7a' as 'external/sdl/SDL'

external/sdl/SDL/docs/README-emscripten.md

@@ -0,0 +1,76 @@
+# 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 3.1.35 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...