Magnum::Platform::Sdl2Application class

#include <Magnum/Platform/Sdl2Application.h>

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

The dedicated application implementation for Emscripten is EmscriptenApplication, which also provides a bootstrap project along with full HTML markup and CMake setup. Sdl2Application however supports Emscripten as well — set up the bootstrap application as described in the EmscriptenApplication docs and then change src/CMakeLists.txt and the #include to use Sdl2Application for both the native and the web build.

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=path/to/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

This application library depends on the SDL2 library version 2.0.6 and newer. On Emscripten, the builtin minimal SDL implementation is used. The application library is built if MAGNUM_WITH_SDL2APPLICATION is enabled when building Magnum. To use this library with 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 PRIVATE Magnum::Sdl2Application)

Additionally, if you're using Magnum as a CMake subproject, bundle the SDL repository and do the following before calling find_package() to ensure it's enabled, as the library is not built by default. If you want to use system-installed SDL2, omit the first part and point CMAKE_PREFIX_PATH to its installation dir if necessary.

# This is the most minimal set of features which still make Sdl2Application
# work. If you need something from these, remove the setting. The SDL_AUDIO and
# SDL_EVENT options should not be needed either as Magnum doesn't use them, but
# if they're disabled they causes compiler or linker errors. Either SDL_DLOPEN
# or SDL_LOADSO needs to be enabled depending on the system to allow linking
# dependencies at runtime, so it's better to just leave them both on. The
# SDL_TIMERS option is important for rendering performance.
set(SDL_ATOMIC OFF CACHE BOOL "" FORCE)
set(SDL_CPUINFO OFF CACHE BOOL "" FORCE)
set(SDL_FILE OFF CACHE BOOL "" FORCE)
set(SDL_FILESYSTEM OFF CACHE BOOL "" FORCE)
set(SDL_HAPTIC OFF CACHE BOOL "" FORCE)
set(SDL_LOCALE OFF CACHE BOOL "" FORCE)
set(SDL_POWER OFF CACHE BOOL "" FORCE)
set(SDL_RENDER OFF CACHE BOOL "" FORCE)
set(SDL_SENSOR OFF CACHE BOOL "" FORCE)
# This assumes you want to have SDL as a static library. If not, set SDL_STATIC
# to OFF instead.
set(SDL_SHARED OFF CACHE BOOL "" FORCE)
add_subdirectory(SDL EXCLUDE_FROM_ALL)

set(MAGNUM_WITH_SDL2APPLICATION 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. 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.

Touch input in SDL2

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 to be synthesized from touch events and vice versa, and thus given behavior is disabled in SDL. Pen input is still reported as a mouse because SDL has dedicated support for pen stylus only since SDL 3.

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, e.g. 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. The same logic is implemented in EmscriptenApplication 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. 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.

Platform-specific behavior

SDL_VIDEO_ALLOW_SCREENSAVER=0 ./your-app

SDL_NO_SIGNAL_HANDLERS=1 ./your-app

SDL_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR=1 ./your-app

DPI awareness

On displays that match the platform default DPI (96 or 72), Configuration::setSize() will create the window in exactly the requested size and the framebuffer pixels will match display pixels 1:1. On displays that have different DPI, there are three possible scenarios, listed below. It's possible to fine tune the behavior either using extra parameters passed to Configuration::setSize() or via the --magnum-dpi-scaling command-line option (or the equivalent $MAGNUM_DPI_SCALING environment variable).

• Framebuffer DPI scaling. The window is created with exactly the requested size and all event coordinates are reported also relative to that size. However, the window backing framebuffer has a different size. This is only supported on macOS and iOS. See HiDPI (Retina) support for details how to enable it. Equivalent to passing Configuration::DpiScalingPolicy::Framebuffer to Configuration::setSize() or framebuffer via command line / environment.
• Virtual DPI scaling. Scales the window based on DPI scaling setting in the system. For example if a 800x600 window is requested and DPI scaling is set to 200%, the resulting window will have 1600x1200 pixels. The backing framebuffer will have the same size. This is supported on Linux and Windows; on Windows the application is first checked for DPI awareness as described in HiDPI support and if the application is not DPI-aware, 1:1 scaling is used. Equivalent to passing Configuration::DpiScalingPolicy::Virtual to Configuration::setSize() or virtual on command line.
• Physical DPI scaling. Takes the requested window size as a physical size that a window would have on platform's default DPI and scales it to have the same physical size on given display physical DPI. So, for example on a display with 240 DPI the window size will be 2000x1500 in pixels, but it will be 21 centimeters wide, the same as a 800x600 window would be on a 96 DPI display. On platforms that don't have a concept of a window (such as mobile platforms or Emscripten), it causes the framebuffer to match display pixels 1:1 without any scaling. This is supported on Linux and all mobile platforms (except iOS) and Emscripten. On Windows this is equivalent to virtual DPI scaling but without doing an explicit check for DPI awareness first. Equivalent to passing Configuration::DpiScalingPolicy::Physical to Configuration::setSize() or physical via command line / environment.

Besides the above, it's possible to supply a custom DPI scaling value to Configuration::setSize() or the --magnum-dpi-scaling command-line option (or environment variable). Using --magnum-dpi-scaling <number> will make the scaling same in both directions, with --magnum-dpi-scaling "<horizontal> <vertical>" the scaling will be different in each direction. On desktop systems custom DPI scaling value will affect physical window size (with the content being scaled), on mobile and web it will affect sharpness of the contents.

The default is depending on the platform:

• On macOS and iOS, the default and only supported option is Configuration::DpiScalingPolicy::Framebuffer. On this platform, windowSize() and framebufferSize() will differ depending on whether NSHighResolutionCapable is enabled in the *.plist file or not. By default, dpiScaling() is 1.0f in both dimensions but it can be overridden using custom DPI scaling.
• On Windows, the default is Configuration::DpiScalingPolicy::Framebuffer. The windowSize() and framebufferSize() is always the same. Depending on whether the DPI awareness was enabled in the manifest file or set by the SetProcessDpiAwareness() API, dpiScaling() is either 1.0f in both dimensions, indicating a low-DPI screen or a non-DPI-aware app, or some other value for HiDPI screens. In both cases the value can be overridden using custom DPI scaling.
• On Linux, the default is Configuration::DpiScalingPolicy::Virtual, taken from the Xft.dpi property. If the property is not available, it falls back to Configuration::DpiScalingPolicy::Physical, querying the monitor DPI value. The windowSize() and framebufferSize() is always the same, dpiScaling() contains the queried DPI scaling value. The value can be overridden using custom DPI scaling.
• On Emscripten, the default is physical DPI scaling, taken from Window.getDevicePixelRatio(). The windowSize() and framebufferSize() is always the same, dpiScaling() contains the queried DPI scaling value. The value can be overridden using custom DPI scaling. Note that this is different from the behavior in EmscriptenApplication — Emscripten's SDL implementation has some additional emulation code that reports event coordinates in framebuffer pixels instead of CSS pixels. See EmscriptenApplication DPI awareness docs for more information.

With windowSize(), framebufferSize() and dpiScaling() having a different relation on each platform, the way to calculate context scaling consistently everywhere is using this expression:

Vector2 scaling = Vector2{framebufferSize()}*dpiScaling()/Vector2{windowSize()};

If your application is saving and restoring window size, it's advisable to take dpiScaling() into account:

• Either divide the window size by the DPI scaling value and use that to restore the window next time — but note this might accumulate slight differences in window sizes over time, especially if fractional scaling is involved.
• Or save the scaled size and use Configuration::setSize(const Vector2i&, const Vector2&) with 1.0f as custom DPI scaling next time — but this doesn't properly handle cases where the window is opened on a display with different DPI.

Public types

struct Arguments

Application arguments.

class Configuration

Configuration.

class ExitEvent

Exit event.

class GLConfiguration

OpenGL 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 MultiGestureEvent deprecated in Git master

Multi gesture 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 TextEditingEvent

Text editing event.

class TextInputEvent

Text input event.

class ViewportEvent

Viewport event.

enum class Modifier: Uint16 { Shift = KMOD_SHIFT, Ctrl = KMOD_CTRL, Alt = KMOD_ALT, Super = KMOD_GUI, AltGr = KMOD_MODE, CapsLock = KMOD_CAPS, NumLock = KMOD_NUM } new in Git master

Keyboard modifier.

enum class Key: SDL_Keycode { Unknown = SDLK_UNKNOWN, LeftShift = SDLK_LSHIFT, RightShift = SDLK_RSHIFT, LeftCtrl = SDLK_LCTRL, RightCtrl = SDLK_RCTRL, LeftAlt = SDLK_LALT, RightAlt = SDLK_RALT, LeftSuper = SDLK_LGUI, RightSuper = SDLK_RGUI, AltGr = SDLK_MODE, Enter = SDLK_RETURN, Esc = SDLK_ESCAPE, Up = SDLK_UP, Down = SDLK_DOWN, Left = SDLK_LEFT, Right = SDLK_RIGHT, Home = SDLK_HOME, End = SDLK_END, PageUp = SDLK_PAGEUP, PageDown = SDLK_PAGEDOWN, Backspace = SDLK_BACKSPACE, Insert = SDLK_INSERT, Delete = SDLK_DELETE, F1 = SDLK_F1, F2 = SDLK_F2, F3 = SDLK_F3, F4 = SDLK_F4, F5 = SDLK_F5, F6 = SDLK_F6, F7 = SDLK_F7, F8 = SDLK_F8, F9 = SDLK_F9, F10 = SDLK_F10, F11 = SDLK_F11, F12 = SDLK_F12, Space = SDLK_SPACE, Tab = SDLK_TAB, Quote = SDLK_QUOTE new in 2020.06, Comma = SDLK_COMMA, Period = SDLK_PERIOD, Minus = SDLK_MINUS, Plus = SDLK_PLUS, Slash = SDLK_SLASH, Percent = SDLK_PERCENT, Semicolon = SDLK_SEMICOLON, Equal = SDLK_EQUALS, LeftBracket = SDLK_LEFTBRACKET new in 2020.06, RightBracket = SDLK_RIGHTBRACKET new in 2020.06, Backslash = SDLK_BACKSLASH new in 2020.06, Backquote = SDLK_BACKQUOTE new in 2020.06, Zero = SDLK_0, One = SDLK_1, Two = SDLK_2, Three = SDLK_3, Four = SDLK_4, Five = SDLK_5, Six = SDLK_6, Seven = SDLK_7, Eight = SDLK_8, Nine = SDLK_9, A = SDLK_a, B = SDLK_b, C = SDLK_c, D = SDLK_d, E = SDLK_e, F = SDLK_f, G = SDLK_g, H = SDLK_h, I = SDLK_i, J = SDLK_j, K = SDLK_k, L = SDLK_l, M = SDLK_m, N = SDLK_n, O = SDLK_o, P = SDLK_p, Q = SDLK_q, R = SDLK_r, S = SDLK_s, T = SDLK_t, U = SDLK_u, V = SDLK_v, W = SDLK_w, X = SDLK_x, Y = SDLK_y, Z = SDLK_z, CapsLock = SDLK_CAPSLOCK new in Git master, ScrollLock = SDLK_SCROLLLOCK new in Git master, NumLock = SDLK_NUMLOCKCLEAR new in Git master, PrintScreen = SDLK_PRINTSCREEN new in Git master, Pause = SDLK_PAUSE new in Git master, Menu = SDLK_APPLICATION new in Git master, NumZero = SDLK_KP_0, NumOne = SDLK_KP_1, NumTwo = SDLK_KP_2, NumThree = SDLK_KP_3, NumFour = SDLK_KP_4, NumFive = SDLK_KP_5, NumSix = SDLK_KP_6, NumSeven = SDLK_KP_7, NumEight = SDLK_KP_8, NumNine = SDLK_KP_9, NumDecimal = SDLK_KP_DECIMAL, NumDivide = SDLK_KP_DIVIDE, NumMultiply = SDLK_KP_MULTIPLY, NumSubtract = SDLK_KP_MINUS, NumAdd = SDLK_KP_PLUS, NumEnter = SDLK_KP_ENTER, NumEqual = SDLK_KP_EQUALS } 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.

Public static functions

static auto keyName(Key key) -> Containers::StringView new in Git master

Name for given key.

static auto scanCodeName(UnsignedInt scanCode) -> Containers::StringView new in Git master

Name for given key scan code.

static auto keyToScanCode(Key key) -> Containers::Optional<UnsignedInt> new in Git master

Scan code for given key.

static auto scanCodeToKey(UnsignedInt scanCode) -> Containers::Optional<Key> new in Git master

Scan code for given key.

Constructors, destructors, conversion operators

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

Construct with an OpenGL context.

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

Construct without explicit GPU context configuration.

Sdl2Application(const Arguments& arguments, NoCreateT) 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 application main loop.

auto mainLoopIteration() -> bool

Run one iteration of application main loop.

void exit(int exitCode = 0)

Exit application.

auto window() -> SDL_Window*

Underlying window handle.

auto glContext() -> SDL_GLContext new in 2019.10

Underlying OpenGL context.

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.

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.

Screen handling

auto windowSize() const -> Vector2i

Window size.

void setWindowSize(const Vector2i& size) new in 2020.06

Set window size.

void setMinWindowSize(const Vector2i& size) new in 2019.10

Set minimum window size.

void setMaxWindowSize(const Vector2i& size) new in 2019.10

Set maximal window size.

auto framebufferSize() const -> Vector2i

Framebuffer size.

auto dpiScaling() const -> Vector2

DPI scaling.

auto dpiScaling(const Configuration& configuration) -> Vector2

DPI scaling for given configuration.

void setWindowTitle(Containers::StringView title) new in 2019.10

Set window title.

void setWindowIcon(const ImageView2D& image) new in 2020.06

Set window icon.

void setContainerCssClass(Containers::StringView cssClass)

Set container CSS class.

void swapBuffers()

Swap buffers.

auto swapInterval() const -> Int

Swap interval.

auto setSwapInterval(Int interval) -> bool

Set swap interval.

void setMinimalLoopPeriod(Nanoseconds time) new in Git master

Set minimal loop period.

void setMinimalLoopPeriod(UnsignedInt milliseconds) deprecated in Git master

Set minimal loop period.

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 { Arrow, TextInput, Wait, Crosshair, WaitArrow, ResizeNWSE, ResizeNESW, ResizeWE, ResizeNS, ResizeAll, No, Hand, Hidden, HiddenLocked } 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 warpCursor(const Vector2i& position)

Warp mouse cursor to given coordinates.

auto isMouseLocked() const -> bool deprecated in 2020.06

Whether mouse is locked.

void setMouseLocked(bool enabled) deprecated in 2020.06

Enable or disable mouse locking.

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.

void multiGestureEvent(MultiGestureEvent& event) deprecated in Git master private 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) private virtual

Text input event.

void textEditingEvent(TextEditingEvent& event) private virtual

Text editing event.

Special events

void tickEvent() protected virtual

Tick event.

void exitEvent(ExitEvent& event) private virtual

Exit event.

void anyEvent(SDL_Event& event) private virtual

Any event.

Enum documentation

Typedef documentation

Function documentation

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

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

    // …
}