Magnum::Platform::Sdl2Application class

Bootstrap application

Fully contained base application using Sdl2Application along with CMake setup is available in base branch of Magnum Bootstrap repository, download it as tar.gz or zip file. After extracting the downloaded archive you can build and run the application with these four commands:

mkdir build && cd build
cmake ..
cmake --build .
./src/MyApplication # or ./src/Debug/MyApplication

See Usage with CMake for more information.

Bootstrap application for Emscripten

Fully contained base application using Sdl2Application for both desktop and Emscripten build along with full HTML markup and CMake setup is available in base-emscripten branch of 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 above. For the Emscripten build you also need to put the contents of toolchains repository from https://github.com/mosra/toolchains in 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="../toolchains/generic/Emscripten.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 webserver, e.g. http://localhost/emscripten/MyApplication.html).

Bootstrap application for iOS

Fully contained base application using Sdl2Application for both desktop and iOS build along with pre-filled *.plist is available in base-ios branch of 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 above. For the iOS build you also need to put the contents of toolchains repository from https://github.com/mosra/toolchains in toolchains/ subdirectory.

Then create build directory and run cmake to generate the Xcode project. Set CMAKE_OSX_ROOT to SDK you want to target and enable all desired architectures in CMAKE_OSX_ARCHITECTURES. Set CMAKE_PREFIX_PATH to the directory where you have all the dependencies.

mkdir build-ios && cd build-ios
cmake .. \
    -DCMAKE_TOOLCHAIN_FILE=../toolchains/generic/iOS.cmake \
    -DCMAKE_OSX_SYSROOT=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk \
    -DCMAKE_OSX_ARCHITECTURES="arm64;armv7;armv7s" \
    -DCMAKE_PREFIX_PATH=~/ios-libs \
    -G Xcode

You can then open the generated project file in Xcode and build/deploy it from there.

Bootstrap application for Windows RT

Fully contained base application using Sdl2Application for both desktop and Windows Phone / Windows Store build along with all required plumbing is available in base-winrt branch of Magnum Bootstrap repository, download it as zip file. After extracting the downloaded archive, you can do the desktop build in the same way as above.

For the Windows RT build you need to provide your own *.pfx certificate file and pass it to CMake in a SIGNING_CERTIFICATE variable. The bootstrap application assumes that SDL2 and ANGLE is built as DLL and both Corrade and Magnum are built statically. Assuming the native Corrade installation is in C:/Sys and all WinRT dependencies are in C:/Sys-winrt, the build can be done similarly to the following:

mkdir build-winrt && cd build-winrt
cmake .. ^
    -DCORRADE_RC_EXECUTABLE="C:/Sys/bin/corrade-rc.exe" ^
    -DCMAKE_PREFIX_PATH="C:/Sys-winrt" ^
    -DCMAKE_SYSTEM_NAME=WindowsStore ^
    -DCMAKE_SYSTEM_VERSION=8.1 ^
    -G "Visual Studio 14 2015" ^
    -DSIGNING_CERTIFICATE=<path-to-your-pfx-file>
cmake --build .

Change WindowsStore to WindowsPhone if you want to build for Windows Phone instead. The build-winrt/src/AppPackages directory will then contain the final package along with a PowerShell script for easy local installation.

General usage

In order to use this library from CMake, you need to copy FindSDL2.cmake from the modules/ directory in Magnum source to the modules/ dir in your project (so it is able to find the SDL2 library). In case of Emscripten you need also FindOpenGLES2.cmake / FindOpenGLES3.cmake. Request the Sdl2Application component of the Magnum package and link to the Magnum::Sdl2Application target:

find_package(Magnum REQUIRED Sdl2Application)

# ...
target_link_libraries(your-app Magnum::Sdl2Application)

If no other application is requested, you can also use the generic Magnum::Application alias to simplify porting. Again, 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. The subclass can be then used directly in main() — see convenience macro MAGNUM_SDL2APPLICATION_MAIN(). See Platform support for more information.

class MyApplication: public Platform::Sdl2Application {
    // implement required methods...
};
MAGNUM_SDL2APPLICATION_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.

Usage with Emscripten

If you are targetting Emscripten, you need to provide HTML markup for your application. Template one is below or in the bootstrap application, you can modify it to your liking. The markup references two files, EmscriptenApplication.js and WebApplication.css, both are in Platform/ directory in the source tree and are also installed into share/magnum/ inside your Emscripten toolchain. Change {{application}} to name of your executable.

<!DOCTYPE html>
<html>
  <head>
    <title>Magnum Emscripten Application</title>
    <meta charset="utf-8" />
    <link rel="stylesheet" href="WebApplication.css" />
  </head>
  <body>
    <h1>Magnum Emscripten Application</h1>
    <div id="listener">
      <canvas id="module"></canvas>
      <div id="status">Initialization...</div>
      <div id="statusDescription"></div>
      <script src="EmscriptenApplication.js"></script>
      <script async="async" src="{{application}}.js"></script>
    </div>
  </body>
</html>

You can modify all the files to your liking, but the HTML file must contain at least the <canvas> enclosed in listener <div>. The JavaScript file contains event listeners which print loading status on the page. The status displayed in the remaining two <div> s, if they are available. The CSS file contains rudimentary style to avoid eye bleeding.

The application redirects all output (thus also Debug, Warning and Error) to JavaScript console. It's possible to pass command-line arguments to main() using GET URL parameters. For example, /app/?foo=bar&fizz&buzz=3 will go to the app as ['--foo', 'bar', '--fizz', '--buzz', '3'].

Usage with iOS

A lot of options for iOS build (such as HiDPI/Retina support, supported display orientation, icons, splash screen...) is specified through the *.plist file. CMake uses its own template that can be configured using various MACOSX_BUNDLE_* variables, but many options are missing from there and you are much better off rolling your own template and passing abosolute path to it to CMake using the MACOSX_BUNDLE_INFO_PLIST property. Below are contents of the *.plist file used in the bootstrap application, requesting OpenGL ES 2.0 and advertising Retina support:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>CFBundleDevelopmentRegion</key>
  <string>en-US</string>
  <key>CFBundleExecutable</key>
  <string>${MACOSX_BUNDLE_EXECUTABLE_NAME}</string>
  <key>CFBundleIdentifier</key>
  <string>cz.mosra.magnum.MyApplication</string>
  <key>CFBundleInfoDictionaryVersion</key>
  <string>6.0</string>
  <key>CFBundleName</key>
  <string>My Application</string>
  <key>CFBundlePackageType</key>
  <string>APPL</string>

  <key>UIRequiredDeviceCapabilities</key>
  <array>
    <string>opengles-2</string>
  </array>
  <key>NSHighResolutionCapable</key>
  <true/>
</dict>
</plist>

Some other options can be configured from runtime when creating the SDL2 application window, see documentation of particular value for details:

• Configuration::WindowFlag::AllowHighDpi allows creating HiDPI/Retina drawable
• Configuration::WindowFlag::Borderless hides the menu bar
• Configuration::WindowFlag::Resizable makes the application respond to device orientation changes

Usage with Windows RT

For Windows RT you need to provide logo images and splash screen, all referenced from the *.appxmanifest file. The file is slightly different for different targets, template for Windows Store and MSVC 2013 is below, others are in the bootstrap application.

<?xml version="1.0" encoding="utf-8"?>
<Package xmlns="http://schemas.microsoft.com/appx/2010/manifest" xmlns:m2="http://schemas.microsoft.com/appx/2013/manifest">
  <Identity Name="MyApplication" Publisher="CN=A Publisher" Version="1.1.0.0" />
  <Properties>
    <DisplayName>My Application</DisplayName>
    <PublisherDisplayName>A Publisher</PublisherDisplayName>
    <Logo>assets/logo-store.png</Logo>
  </Properties>
  <Resources>
    <Resource Language="x-generate" />
  </Resources>
  <Applications>
    <Application Id="App" Executable="$targetnametoken$.exe" EntryPoint="MyApplication.App">
      <m2:VisualElements
        DisplayName="Magnum Windows Store Application"
        Description="My Application"
        BackgroundColor="#202020"
        ForegroundText="light"
        Square150x150Logo="assets/logo.png"
        Square30x30Logo="assets/logo-small.png">
        <m2:SplashScreen Image="assets/splash.png" />
      </m2:VisualElements>
    </Application>
  </Applications>
</Package>

The assets are referenced also from the main CMakeLists.txt file. You have to mark all non-source files (except for the *.pfx key) with VS_DEPLOYMENT_CONTENT property and optionally set their location with VS_DEPLOYMENT_LOCATION. If you are using *.resw files, these need to have the VS_TOOL_OVERRIDE property set to PRIResource.

Public types

struct Arguments

Application arguments.

class Configuration

Configuration.

class GLConfiguration

OpenGL context configuration.

class InputEvent

Base for input events.

class KeyEvent

Key event.

class MouseEvent

Mouse event.

class MouseMoveEvent

Mouse move event.

class MouseScrollEvent

Mouse scroll event.

class MultiGestureEvent

Multi gesture event.

class TextEditingEvent

Text editing event.

class TextInputEvent

Text input event.

Constructors, destructors, conversion operators

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

Construct with given configuration for OpenGL context.

Sdl2Application(const Arguments& arguments, const Configuration& configuration) explicit

Construct with given configuration.

Sdl2Application(const Arguments& arguments) explicit

Construct with default configuration.

Sdl2Application(const Arguments& arguments, NoCreateT) explicit

Construct without creating a window.

Sdl2Application(const Arguments& arguments, std::nullptr_t) deprecated explicit

Construct without creating a window.

Sdl2Application(const Sdl2Application&) deleted

Copying is not allowed.

Sdl2Application(Sdl2Application&&) deleted

Moving is not allowed.

Public functions

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

Copying is not allowed.

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

Moving is not allowed.

auto exec() -> int

Execute main loop.

void exit()

Exit application main loop.

void mainLoopIteration()

Run one iteration of application main loop.

auto window() -> SDL_Window*

Underlying window handle.

Protected functions

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

Create a window with given configuration for OpenGL context.

void create(const Configuration& configuration)

Create a window with given configuration.

void create()

Create a window with default configuration and OpenGL context.

void createContext(const Configuration& configuration) deprecated

Create a window with given configuration for OpenGL context.

void createContext() deprecated

Create a window with default configuration and OpenGL context.

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

Try to create context with given configuration for OpenGL context.

auto tryCreate(const Configuration& configuration) -> bool

Try to create context with given configuration.

auto tryCreateContext(const Configuration& configuration) -> bool deprecated

Try to create context with given configuration for OpenGL context.

Screen handling

auto windowSize() -> Vector2i protected

Window size.

void swapBuffers() protected

Swap buffers.

auto swapInterval() const -> Int protected

Swap interval.

auto setSwapInterval(Int interval) -> bool protected

Set swap interval.

void setMinimalLoopPeriod(UnsignedInt milliseconds) protected

Set minimal loop period.

void redraw() protected

Redraw immediately.

void tickEvent() protected virtual

Tick event.

void viewportEvent(const Vector2i& size) protected virtual

Viewport event.

void drawEvent() protected pure virtual

Draw event.

Keyboard handling

void keyPressEvent(KeyEvent& event) protected virtual

Key press event.

void keyReleaseEvent(KeyEvent& event) protected virtual

Key release event.

Mouse handling

auto isMouseLocked() const -> bool

Whether mouse is locked.

void setMouseLocked(bool enabled)

Enable or disable mouse locking.

void mousePressEvent(MouseEvent& event) protected virtual

Mouse press event.

void mouseReleaseEvent(MouseEvent& event) protected virtual

Mouse release event.

void mouseMoveEvent(MouseMoveEvent& event) protected virtual

Mouse move event.

void mouseScrollEvent(MouseScrollEvent& event) protected virtual

Mouse scroll event.

Touch gesture handling

void multiGestureEvent(MultiGestureEvent& event) protected virtual

Multi gesture event.

Text input handling

auto isTextInputActive() -> 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) protected virtual

Text input event.

void textEditingEvent(TextEditingEvent& event) protected virtual

Text editing event.

Function documentation