Wiki Page Content

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.


CategoryDefine, CategoryHints

None: SDL_HINT_EMSCRIPTEN_ASYNCIFY (last edited 2020-06-27 20:56:31 by SylvainBeucler)

Feedback
Please include your contact information if you'd like to receive a reply.
Submit