From 8a69c689a995bf613afa97b713845ce2813d542c Mon Sep 17 00:00:00 2001
From: Pablo Escobar <mail@rvrs.in>
Date: Sat, 7 Nov 2020 20:55:54 +0100
Subject: [PATCH] Platform: docs for multiple applications

---
 doc/platforms-html5.dox                       | 49 +++++++++++++++++++
 src/Magnum/Platform/EmscriptenApplication.cpp |  2 +-
 src/Magnum/Platform/gl-info.html              |  2 +-
 3 files changed, 51 insertions(+), 2 deletions(-)

diff --git a/doc/platforms-html5.dox b/doc/platforms-html5.dox
index ae29f55d5..8eaceb3a9 100644
--- a/doc/platforms-html5.dox
+++ b/doc/platforms-html5.dox
@@ -294,6 +294,55 @@ 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 and `EmscriptenApplication.js`
+populate 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 `-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.
+
+To let `EmscriptenApplication.js` access the local @cb{.js} Module @ce,
+it must be prepended to the application with the `--pre-js` compiler option,
+at which point you also don't have to bundle it separately anymore:
+
+@code{.cmake}
+target_link_libraries(my-application PRIVATE "-s MODULARIZE -s EXPORT_NAME=createModule")
+target_link_libraries(my-application PRIVATE "--pre-js ${MAGNUM_EMSCRIPTENAPPLICATION_JS}")
+@endcode
+
+Instead of running instantly, the application must be instantiated
+using the function name set with `EXPORT_NAME`:
+
+@code{.html-jinja}
+<script src="{{ application }}.js"></script>
+<script>
+  createModule().then(function(myModule) {
+    // application loaded and running
+  });
+</script>
+@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
diff --git a/src/Magnum/Platform/EmscriptenApplication.cpp b/src/Magnum/Platform/EmscriptenApplication.cpp
index b26d1d5cc..2bdd88ed6 100644
--- a/src/Magnum/Platform/EmscriptenApplication.cpp
+++ b/src/Magnum/Platform/EmscriptenApplication.cpp
@@ -336,7 +336,7 @@ bool EmscriptenApplication::tryCreate(const Configuration& configuration, const
     _devicePixelRatio = Vector2{Float(emscripten_get_device_pixel_ratio())};
     Debug{verbose} << "Platform::EmscriptenApplication: device pixel ratio" << _devicePixelRatio.x();
 
-    /* Find out which elemen target strings Emscripten expects. This depends on
+    /* Find out which element target strings Emscripten expects. This depends on
        the DISABLE_DEPRECATED_FIND_EVENT_TARGET_BEHAVIOR compiler option.  */
     _deprecatedTargetBehavior = checkForDeprecatedEmscriptenTargetBehavior();
     if(_deprecatedTargetBehavior) {
diff --git a/src/Magnum/Platform/gl-info.html b/src/Magnum/Platform/gl-info.html
index 03f6f6244..f827a21d2 100644
--- a/src/Magnum/Platform/gl-info.html
+++ b/src/Magnum/Platform/gl-info.html
@@ -10,7 +10,7 @@
   <h1>Magnum GL Info</h1>
   <div class="mn-container">
     <div class="mn-sizer"><div class="mn-expander"><div class="mn-listener">
-      <canvas class="mn-canvas hidden" id="canvas"></canvas>
+      <canvas class="mn-canvas mn-hidden" id="canvas"></canvas>
       <pre class="mn-log" id="log"></pre>
       <div class="mn-status" id="status">Initialization...</div>
       <div class="mn-status-description" id="status-description"></div>