DRAFT |
SDL_HINT_EMSCRIPTEN_ASYNCIFY
A hint that specifies if SDL should give back control to the browser automatically when running with asyncify.
Values
0 |
disable emscripten_sleep calls (if you give back browser control manually or use asyncify for other purposes) |
1 |
enable emscripten_sleep calls (the default) |
Default
SDL pauses the application and gives back control to the browser automatically when the application is compiled with asyncify support, by calling emscripten_sleep when:
- refreshing the software graphics context,
- refreshing the GPU graphics context,
using SDL_Delay,
polling events (through SDL_Delay), hence supporting SDL_WaitEvent
The SDL application hence can be ported to the web browser without any code change to the main loop (no emscripten_set_main_loop), at the cost of a reasonable performance hit.
Code Examples
To disable the default behavior:
SDL_SetHint(SDL_HINT_EMSCRIPTEN_ASYNCIFY, "0");
//...
SDL_Init(SDL_INIT_EVERYTHING);
With the default SDL_HINT_EMSCRIPTEN_ASYNCIFY=1, to optimize performance, you'll typically want to make asyncify only instrument functions in the call path:
emcc ... -s ASYNCIFY=1 -s ASYNCIFY_WHITELIST='["main", "call_path_to_your_main_loop", "SDL_WaitEvent", "SDL_WaitEventTimeout", "SDL_Delay", "SDL_RenderPresent", "GLES2_RenderPresent", "SDL_GL_SwapWindow", "Emscripten_GLES_SwapWindow", "byn$$fpcast-emu$$Emscripten_GLES_SwapWindow", "SDL_UpdateWindowSurface", "SDL_UpdateWindowSurfaceRects", "Emscripten_UpdateWindowFramebuffer"]'
If you get a RuntimeError: unreachable executed, then check the JavaScript console and its stack trace to identify the missing function.
Remarks
This hint only applies to the Emscripten platform.
Version
This hint is available since SDL2 port version_21 / Emscripten 1.39.14, and is in the official SDL development version as of 2020-06.
