@ -159,10 +159,12 @@ everything can be set up directly from the HTML markup. Replace
@cb{.jinja} {{ application }} @ce with the name of your application executable
@cb{.jinja} {{ application }} @ce with the name of your application executable
and adapt page title and heading as desired. You can modify all files to your
and adapt page title and heading as desired. You can modify all files to your
liking, but the HTML file must contain at least a
liking, but the HTML file must contain at least a
@cb{.html} <canvas id="canvas"> @ce referenced in @cb{.js} Module.canvas @ce.
@cb{.html} <canvas> @ce referenced using an ID in @cb{.js} Module.canvas @ce
The JavaScript file contains event listeners that print loading status on the
--- by default it's @cb{.css} #canvas @ce but
page. The status is displayed in the remaining two @cb{.html} <div> @ce s, if
@ref platforms-html5-multiple-apps "it's possible to override it". The
they are available. The CSS file contains a basic style, see
JavaScript file contains event listeners that print loading status on the page.
The status is displayed in the remaining two @cb{.html} <div> @ce s, if they
are available. The CSS file contains a basic style, see
@ref platforms-html5-layout "below" for available options to tweak the default
@ref platforms-html5-layout "below" for available options to tweak the default
look.
look.
@ -298,60 +300,53 @@ endif()
@note Support for this feature is currently only tested with
@note Support for this feature is currently only tested with
@ref Platform::EmscriptenApplication. @ref Platform::Sdl2Application
@ref Platform::EmscriptenApplication. @ref Platform::Sdl2Application
and @ref Platform::GlfwApplication support largely depends on Emscripten's
support largely depends on Emscripten's underlying emulation libraries and
underlying emulation libraries and may vary across Emscripten versions.
may vary across Emscripten versions.
Running multiple graphical applications on a single page is possible, but
Running multiple applications on a single page is possible, but requires a few
requires a few changes. By default, Emscripten populates a global @cb{.js} Module @ce
changes. By default, Emscripten populates a global @cb{.js} Module @ce object
object with things like callbacks and the canvas element to render into. This is not
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
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
creates a script that defines a function with a local @cb{.js} Module @ce
instead. This way each application runs inside its own function with a separate
object instead. This way each application runs inside its own function with a
environment:
separate environment:
@code{.cmake}
@code{.cmake}
target_link_libraries(my-application PRIVATE "-s MODULARIZE -s EXPORT_NAME=createModule")
# If you have CMake 3.13+
target_link_options(my-application PRIVATE
"SHELL:-s MODULARIZE"
"SHELL:-s EXPORT_NAME=createModule")
# Or alternatively, supported by older CMake versions as well
target_link_libraries(my-application PRIVATE
"-s MODULARIZE -s EXPORT_NAME=createModule")
@endcode
@endcode
Instead of running instantly, the application can then be instantiated
Instead of running instantly, the application can then be instantiated using
using the function name set with `EXPORT_NAME`. The function optionally
the function name set with `EXPORT_NAME`. The function optionally takes an
takes an object to populate the local @cb{.js} Module @ce.
object to populate the local @cb{.js} Module @ce.
While `EmscriptenApplication.js` populates the @cb{.js} Module @ce object by default,
While `EmscriptenApplication.js` populates the @cb{.js} Module @ce object by
it also defines a function @cb{.js} createMagnumModule @ce that lets you create
default, it also defines a @cb{.js} createMagnumModule() @ce function that lets
new module objects to pass to the Emscripten module function. This allows you
you create new module objects to pass to the Emscripten module function. Pass
to include `EmscriptenApplication.js` only once per page without having to bundle it with
an object to it to override the default values. This is the easiest way to set
Emscripten's `--pre-js` option. To override the default values, pass an object to
the canvas or status elements of each application:
@cb{.js} createMagnumModule @ce. This is the easiest way to set the canvas or
status elements of each application:
@code{.html-jinja}
@code{.html-jinja}
<script src="EmscriptenApplication.js"></script>
<script src="EmscriptenApplication.js"></script>
<script src="{{ application }}.js"></script>
<script src="{{ application }}.js"></script>
<script>
<script>
const myModule = createMagnumModule({
const myModule = createMagnumModule({
canvas: document.getElementById('my-canvas'),
canvas: document.getElementById('my-canvas'),
status: document.getElementById('my-status'),
status: document.getElementById('my-status'),
statusDescription: document.getElementById('my-status-description')
statusDescription: document.getElementById('my-status-description')
});
});
createModule(myModule).then(function(myModule) {
createModule(myModule).then(function(myModule) {
// application loaded and running
// application loaded and running
});
});
</script>
</script>
@endcode
@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
@section platforms-html5-layout Modifying page style, canvas size and aspect ratio
The `WebApplication.css` file contains a basic style and the additional
The `WebApplication.css` file contains a basic style and the additional