#pragma section-numbers off
#pragma camelcase off
||<tablewidth="100%" style="color: #FF0000;" :> DRAFT||

##*^*^*^*^*See http://wiki.libsdl.org/moin.cgi/SGEnumerations for details on editing this page*^*^*^*^*


= SDL_HINT_EMSCRIPTEN_ASYNCIFY =
A hint that specifies if SDL should give back control to the browser automatically when running with asyncify.


<<TableOfContents()>>

== 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 [[https://emscripten.org/docs/porting/asyncify.html|asyncify]] support, by calling [[https://emscripten.org/docs/api_reference/emscripten.h.html#pseudo-synchronous-functions|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 [[https://emscripten.org/docs/api_reference/emscripten.h.html#c.emscripten_set_main_loop|emscripten_set_main_loop]]), at the cost of a reasonable performance hit.

== Code Examples ==

To disable the default behavior:  
{{{#!highlight cpp
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 [[https://hg.libsdl.org/SDL/rev/dd5a816a4d61|development version]] as of 2020-06.

----
[[CategoryDefine]], [[CategoryHints]]
##See the Style Guide for instructions on editing the footer.