Magnum::Platform::EmscriptenApplication class new in 2019.10

#include <Magnum/Platform/EmscriptenApplication.h>

Bootstrap application

Fully contained base application using Sdl2Application for desktop build and EmscriptenApplication for Emscripten build along with full HTML markup and CMake setup is available in base-emscripten branch of the Magnum Bootstrap repository, download it as tar.gz or zip file. After extracting the downloaded archive, you can do the desktop build in the same way as with Sdl2Application. For the Emscripten build you also need to put the contents of toolchains repository from https://github.com/mosra/toolchains in a toolchains/ subdirectory. There are two toolchain files. The generic/Emscripten.cmake is for the classical (asm.js) build, the generic/Emscripten-wasm.cmake is for WebAssembly build. Don't forget to adapt EMSCRIPTEN_PREFIX variable in toolchains/generic/Emscripten*.cmake to path where Emscripten is installed; you can also pass it explicitly on command-line using -DEMSCRIPTEN_PREFIX. Default is /usr/emscripten.

Then create build directory and run cmake and build/install commands in it. Set CMAKE_PREFIX_PATH to where you have all the dependencies installed, set CMAKE_INSTALL_PREFIX to have the files installed in proper location (a webserver, e.g. /srv/http/emscripten).

mkdir build-emscripten && cd build-emscripten
cmake .. \
    -DCMAKE_TOOLCHAIN_FILE=path/to/toolchains/generic/Emscripten-wasm.cmake \
    -DCMAKE_PREFIX_PATH=/usr/lib/emscripten/system \
    -DCMAKE_INSTALL_PREFIX=/srv/http/emscripten
cmake --build .
cmake --build . --target install

You can then open MyApplication.html in your browser (through a webserver, e.g. http://localhost/emscripten/MyApplication.html).

Detailed information about deployment for Emscripten and all needed boilerplate together with a troubleshooting guide is available in JavaScript, HTML5 and WebGL.

General usage

This application library is built if MAGNUM_WITH_EMSCRIPTENAPPLICATION is enabled when building Magnum. To use this library with CMake, request the EmscriptenApplication component of the Magnum package and link to the Magnum::EmscriptenApplication target:

find_package(Magnum REQUIRED)
if(CORRADE_TARGET_EMSCRIPTEN)
    find_package(Magnum REQUIRED EmscriptenApplication)
endif()

# ...
if(CORRADE_TARGET_EMSCRIPTEN)
    target_link_libraries(your-app PRIVATE Magnum::EmscriptenApplication)
endif()

Additionally, if you're using Magnum as a CMake subproject, do the following before calling find_package() to ensure it's enabled, as the library is not built by default:

set(MAGNUM_WITH_EMSCRIPTENAPPLICATION ON CACHE BOOL "" FORCE)
add_subdirectory(magnum EXCLUDE_FROM_ALL)

If no other application is requested, you can also use the generic Magnum::Application alias to simplify porting. See Downloading and building and Usage with CMake for more information.

In C++ code you need to implement at least drawEvent() to be able to draw on the screen.

class MyApplication: public Platform::EmscriptenApplication {
    // implement required methods...
};
MAGNUM_EMSCRIPTENAPPLICATION_MAIN(MyApplication)

If no other application header is included, this class is also aliased to Platform::Application and the macro is aliased to MAGNUM_APPLICATION_MAIN() to simplify porting.

Touch input in HTML5

The application recognizes touch input and reports it as Pointer::Finger and PointerEventSource::Touch. Because both mouse and touch events are exposed through a unified PointerEvent / PointerMoveEvent interface, there's no need for compatibility mouse events synthesized from touch events, and thus they get ignored when fired right after the corresponding touch. Emscripten so far doesn't support pointer events, so pen input isn't implemented yet.

In case of a multi-touch scenario, PointerEvent::isPrimary() / PointerMoveEvent::isPrimary() can be used to distinguish the primary touch from secondary. For example, if an application doesn't need to recognize gestures like pinch to zoom or rotate, it can ignore all non-primary pointer events. PointerEventSource::Mouse events are always marked as primary, for touch input the first pressed finger is marked as primary and all following pressed fingers are non-primary. Note that there can be up to one primary pointer for each pointer event source. For example, a finger and a mouse press may both be marked as primary. On the other hand, in a multi-touch scenario, if the first (and thus primary) finger is lifted, no other finger becomes primary until all others are lifted as well. This is consistent with the logic in Sdl2Application and AndroidApplication.

If gesture recognition is desirable, PointerEvent::id() / PointerMoveEvent::id() contains a pointer ID that's unique among all pointer event sources, which can be used to track movements of secondary, tertiary and further touch points. The ID allocation is platform-specific and you can't rely on it to be contiguous or in any bounded range — for example, each new touch may generate a new ID that's only used until given finger is lifted, and then never again, or the IDs may get heavily reused, being unique only for the period given finger is pressed. For PointerEventSource::Mouse the ID is a constant, as there's always just a single mouse cursor.

See also Handling mouse, touch and pen events for general information about handling pointer input in a portable way. There's also a Platform::TwoFingerGesture helper for recognition of common two-finger gestures for zoom, rotation and pan.

Browser-specific behavior

Leaving a default (zero) size in Configuration will cause the app to use a size that corresponds to CSS pixel size of the <canvas> element. The size is then multiplied by DPI scaling value, see DPI awareness below for details.

If you enable Configuration::WindowFlag::Resizable, the canvas will be resized when size of the canvas changes and you get viewportEvent(). If the flag is not enabled, no canvas resizing is performed.

Unlike desktop platforms, the browser has no concept of application exit code, so the return value of exec() is always 0 and whatever is passed to exit(int) is ignored.

WebGL-specific behavior

While WebGL itself requires all extensions to be enabled explicitly, by default Emscripten enables all supported extensions that don't have a negative effect on performance to simplify porting. This is controlled by GLConfiguration::Flag::EnableExtensionsByDefault and the flag is enabled by default. When disabled, you are expected to enable desired extensions manually using emscripten_webgl_enable_extension().

DPI awareness

Since this application targets only web browsers, DPI handling isn't as general as in case of Sdl2Application or GlfwApplication. See Sdl2Application DPI awareness documentation for a guide covering all platform differences.

For this application in particular, windowSize() can be different than framebufferSize() on HiDPI displays — which is different from Sdl2Application behavior on Emscripten. By default, dpiScaling() is 1.0f in both dimensions but it can be overridden using custom DPI scaling — the --magnum-dpi-scaling command-line options are supported the same way as in Sdl2Application, only in the form of URL GET parameters, similarly to all other command-line options.

Having dpiScaling() set to 1.0f is done in order to have consistent behavior with other platforms — platforms have either windowSize() equivalent to framebufferSize() and then dpiScaling() specifies the UI scale (Windows/Linux/Android-like) or windowSize() different from framebufferSize() (which defines the UI scale) and then dpiScaling() is 1.0f (macOS/iOS-like), so this is the second case. The actual device pixel ratio is expressed in the ratio of windowSize() and framebufferSize() so crossplatform code shouldn't have a need to query it, however for completeness it's exposed in devicePixelRatio() and ViewportEvent::devicePixelRatio().

Setting custom DPI scaling will affect framebufferSize() (larger values making the canvas backing framebuffer larger and vice versa), windowSize() will stay unaffected as it's controlled by the CSS, and devicePixelRatio() will stay the same as well as it's defined by the browser.

To avoid confusion, documentation of all EmscriptenApplication APIs always mentions only the web case, consult equivalent APIs in Sdl2Application or GlfwApplication for behavior in those implementations.

Public types

struct Arguments

Application arguments.

class Configuration

Configuration.

class GLConfiguration

WebGL context configuration.

class InputEvent

Base for input events.

class KeyEvent

Key event.

class MouseEvent deprecated in Git master

Mouse event.

class MouseMoveEvent deprecated in Git master

Mouse move event.

class MouseScrollEvent deprecated in Git master

Mouse scroll event.

class PointerEvent new in Git master

Pointer event.

class PointerMoveEvent new in Git master

Pointer move event.

class ScrollEvent new in Git master

Scroll event.

class TextInputEvent

Text input event.

class ViewportEvent

Viewport event.

enum class Modifier: Int { Shift = 1 << 0, Ctrl = 1 << 1, Alt = 1 << 2, Super = 1 << 3 } new in Git master

Keyboard modifier.

enum class Key: Int { Unknown, LeftShift, RightShift, LeftCtrl, RightCtrl, LeftAlt, RightAlt, LeftSuper, RightSuper, Enter, Esc, Up, Down, Left, Right, Home, End, PageUp, PageDown, Backspace, Insert, Delete, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, Zero = '0', One, Two, Three, Four, Five, Six, Seven, Eight, Nine, A = 'a', B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z, Space, Tab, Quote, Comma, Period, Minus, Plus, Slash, Percent, Semicolon new in 2020.06, Equal, LeftBracket, RightBracket, Backslash, Backquote, CapsLock, ScrollLock, NumLock, PrintScreen, Pause, Menu, NumZero, NumOne, NumTwo, NumThree, NumFour, NumFive, NumSix, NumSeven, NumEight, NumNine, NumDecimal, NumDivide, NumMultiply, NumSubtract, NumAdd, NumEnter, NumEqual } new in Git master

Key.

enum class PointerEventSource: UnsignedByte { Mouse, Touch } new in Git master

Pointer event source.

enum class Pointer: UnsignedByte { MouseLeft = 1 << 0, MouseMiddle = 1 << 1, MouseRight = 1 << 2, MouseButton4 = 1 << 3, MouseButton5 = 1 << 4, Finger = 1 << 5 } new in Git master

Pointer type.

using Modifiers = Containers::EnumSet<Modifier> new in Git master

Set of keyboard modifiers.

using Pointers = Containers::EnumSet<Pointer> new in Git master

Set of pointer types.

Constructors, destructors, conversion operators

EmscriptenApplication(const Arguments& arguments, const Configuration& configuration, const GLConfiguration& glConfiguration) explicit

Construct with a WebGL context.

EmscriptenApplication(const Arguments& arguments, const Configuration& configuration = Configuration{}) explicit

Construct without explicit GPU context configuration.

EmscriptenApplication(const Arguments& arguments, NoCreateT) explicit

Construct without setting up a canvas.

EmscriptenApplication(const EmscriptenApplication&) deleted

Copying is not allowed.

EmscriptenApplication(EmscriptenApplication&&) deleted

Moving is not allowed.

Public functions

auto operator=(const EmscriptenApplication&) -> EmscriptenApplication& deleted

Copying is not allowed.

auto operator=(EmscriptenApplication&&) -> EmscriptenApplication& deleted

Moving is not allowed.

auto exec() -> int

Execute the application.

void exit(int exitCode = 0)

Exit application main loop.

auto glContext() -> EMSCRIPTEN_WEBGL_CONTEXT_HANDLE

Underlying WebGL context.

Protected functions

void create(const Configuration& configuration, const GLConfiguration& glConfiguration)

Set up a canvas with given configuration for WebGL context.

void create(const Configuration& configuration)

Set up a canvas with given configuration and WebGL context.

void create()

Set up a canvas with default configuration and WebGL context.

auto tryCreate(const Configuration& configuration, const GLConfiguration& glConfiguration) -> bool

Try to create context with given configuration for WebGL context.

auto tryCreate(const Configuration& configuration) -> bool

Try to create context with given configuration.

Screen handling

auto windowSize() const -> Vector2i

Canvas size.

auto framebufferSize() const -> Vector2i

Framebuffer size.

auto dpiScaling() const -> Vector2

DPI scaling.

auto dpiScaling(const Configuration& configuration) const -> Vector2

DPI scaling for given configuration.

auto devicePixelRatio() const -> Vector2

Device pixel ratio.

void setWindowTitle(Containers::StringView title)

Set window title.

void setContainerCssClass(Containers::StringView cssClass)

Set container CSS class.

void swapBuffers()

Swap buffers.

void redraw()

Redraw immediately.

void viewportEvent(ViewportEvent& event) private virtual

Viewport event.

void drawEvent() private pure virtual

Draw event.

Keyboard handling

void keyPressEvent(KeyEvent& event) private virtual

Key press event.

void keyReleaseEvent(KeyEvent& event) private virtual

Key release event.

Pointer handling

enum class Cursor: UnsignedInt { Auto, Arrow, Hidden, ContextMenu, Help, Hand, WaitArrow, Wait, Cell, Crosshair, TextInput, VerticalTextInput, Alias, Copy, ResizeAll, NoDrop, No, Grab, Grabbing, AllScroll, ColResize, RowResize, ResizeN, ResizeE, ResizeS, ResizeW, ResizeNE, ResizeNW, ResizeSE, ResizeSW, ResizeWE, ResizeNS, ResizeNESW, ResizeNWSE, ZoomIn, ZoomOut } new in 2020.06

Cursor type.

void setCursor(Cursor cursor) new in 2020.06

Set cursor type.

auto cursor() -> Cursor new in 2020.06

Get current cursor type.

void pointerPressEvent(PointerEvent& event) private virtual new in Git master

Pointer press event.

void mousePressEvent(MouseEvent& event) deprecated in Git master private virtual

Mouse press event.

void pointerReleaseEvent(PointerEvent& event) private virtual new in Git master

Pointer release event.

void mouseReleaseEvent(MouseEvent& event) deprecated in Git master private virtual

Mouse release event.

void pointerMoveEvent(PointerMoveEvent& event) private virtual new in Git master

Pointer move event.

void mouseMoveEvent(MouseMoveEvent& event) deprecated in Git master private virtual

Mouse move event.

void scrollEvent(ScrollEvent& event) private virtual new in Git master

Scroll event.

void mouseScrollEvent(MouseScrollEvent& event) deprecated in Git master private virtual

Mouse move event.

Text input handling

auto isTextInputActive() const -> bool

Whether text input is active.

void startTextInput()

Start text input.

void stopTextInput()

Stop text input.

void setTextInputRect(const Range2Di& rect)

Set text input rectangle.

void textInputEvent(TextInputEvent& event) private virtual

Text input event.

Enum documentation

Typedef documentation

Function documentation

MyApplication::MyApplication(const Arguments& arguments):
    Platform::Application{arguments, NoCreate}
{
    // …

    if(!everythingGoingAsExpected) {
        exit(1);
        return;
    }

    // …
}