diff --git a/doc/platforms-html5.dox b/doc/platforms-html5.dox index ae29f55d5..920dff145 100644 --- a/doc/platforms-html5.dox +++ b/doc/platforms-html5.dox @@ -294,6 +294,64 @@ if(CORRADE_TARGET_EMSCRIPTEN) endif() @endcode +@section platforms-html5-multiple-apps Multiple applications on one page + +@note Support for this feature is currently only tested with + @ref Platform::EmscriptenApplication. @ref Platform::Sdl2Application + and @ref Platform::GlfwApplication support largely depends on Emscripten's + underlying emulation libraries and may vary across Emscripten versions. + +Running multiple graphical applications on a single page is possible, but +requires a few changes. By default, Emscripten populates a global @cb{.js} Module @ce +object with things like callbacks and the canvas element to render into. This is not +suitable when using more than one application. Emscripten's `MODULARIZE` option +creates a script that defines a function with a local @cb{.js} Module @ce object +instead. This way each application runs inside its own function with a separate +environment: + +@code{.cmake} +target_link_libraries(my-application PRIVATE "-s MODULARIZE -s EXPORT_NAME=createModule") +@endcode + +Instead of running instantly, the application can then be instantiated +using the function name set with `EXPORT_NAME`. The function optionally +takes an object to populate the local @cb{.js} Module @ce. + +While `EmscriptenApplication.js` populates the @cb{.js} Module @ce object by default, +it also defines a function @cb{.js} createMagnumModule @ce that lets you create +new module objects to pass to the Emscripten module function. This allows you +to include `EmscriptenApplication.js` only once per page without having to bundle it with +Emscripten's `--pre-js` option. To override the default values, pass an object to +@cb{.js} createMagnumModule @ce. This is the easiest way to set the canvas or +status elements of each application: + +@code{.html-jinja} + + + +@endcode + +If you need to make changes to the @cb{.js} Module @ce object created by +EmscriptenApplication.js, you can add that code to a file that's loaded +with `--pre-js` right after `EmscriptenApplication.js`. This is usually +needed for pointing to elements with custom IDs, like the canvas to +render into or the elements to display status updates: + +@code{.js} +Module.canvas = document.getElementById('my-canvas'); +Module.status = document.getElementById('my-status'); +Module.statusDescription = document.getElementById('my-status-description'); +@endcode + @section platforms-html5-layout Modifying page style, canvas size and aspect ratio The `WebApplication.css` file contains a basic style and the additional