Magnum::Platform::GlfwApplication class

#include <Magnum/Platform/GlfwApplication.h>

enum class Magnum::Platform::GlfwApplication::Modifier: Int new in Git master

Keyboard modifier.

enum class Magnum::Platform::GlfwApplication::Key: Int new in Git master

Key.

enum class Magnum::Platform::GlfwApplication::PointerEventSource: UnsignedByte new in Git master

Pointer event source.

enum class Magnum::Platform::GlfwApplication::Pointer: UnsignedByte new in Git master

Pointer type.

enum class Magnum::Platform::GlfwApplication::Cursor: UnsignedInt new in 2020.06

Cursor type.

typedef Containers::EnumSet<Modifier> Magnum::Platform::GlfwApplication::Modifiers new in Git master

Set of keyboard modifiers.

typedef Containers::EnumSet<Pointer> Magnum::Platform::GlfwApplication::Pointers new in Git master

Set of pointer types.

Magnum::Platform::GlfwApplication::GlfwApplication(const Arguments& arguments, const Configuration& configuration, const GLConfiguration& glConfiguration) explicit

Construct with an OpenGL context.

Creates application with default or user-specified configuration. See Configuration for more information. The program exits if the context cannot be created, see tryCreate() for an alternative.

Magnum::Platform::GlfwApplication::GlfwApplication(const Arguments& arguments, const Configuration& configuration = Configuration{}) explicit

Construct without explicit GPU context configuration.

If Configuration::WindowFlag::Contextless is present or Magnum was not built with MAGNUM_TARGET_GL, this creates a window without any GPU context attached, leaving that part on the user.

If none of the flags is present and Magnum was built with MAGNUM_TARGET_GL, this is equivalent to calling GlfwApplication(const Arguments&, const Configuration&, const GLConfiguration&) with default-constructed GLConfiguration.

See also Enabling or disabling features for more information.

Magnum::Platform::GlfwApplication::GlfwApplication(const Arguments& arguments, NoCreateT) explicit

Construct without creating a window.

Unlike above, the window is not created and must be created later with create() or tryCreate().

Containers::StringView Magnum::Platform::GlfwApplication::keyName(Key key, UnsignedInt scanCode = 0) const new in Git master

Name for given key.

Human-readable localized UTF-8 name for given key, intended for displaying to the user in e.g. a key binding configuration. For Key::Unknown, a concrete scanCode can be passed. If there is no name for given key, an empty string is returned. If non-empty, the returned view is always Containers::StringViewFlag::NullTerminated and is valid until the keyboard layout is changed or the application exits.

Unlike e.g. Sdl2Application::keyName(), the function isn't static because it relies on GLFW being initialized.

Containers::Optional<UnsignedInt> Magnum::Platform::GlfwApplication::keyToScanCode(Key key) const new in Git master

Scan code for given key.

If key doesn't correspond to a physical key supported on given platform, returns Containers::NullOpt. Unlike e.g. Sdl2Application::scanCodeToKey(), GLFW doesn't provide any way to map from a scan code to a key.

Unlike e.g. Sdl2Application::keyToScanCode(), the function isn't static because it relies on GLFW being initialized.

int Magnum::Platform::GlfwApplication::exec()

Execute main loop.

Calls mainLoopIteration() in a loop until exit() is called. See MAGNUM_GLFWAPPLICATION_MAIN() for usage information.

bool Magnum::Platform::GlfwApplication::mainLoopIteration() new in 2020.06

Run one iteration of application main loop.

Called internally from exec(). If you want to have better control over how the main loop behaves, you can call this function yourself from your own main() function instead of it being called automatically from exec() / MAGNUM_GLFWAPPLICATION_MAIN().

void Magnum::Platform::GlfwApplication::exit(int exitCode = 0)

Exit application.

When called from application constructor, it will cause the application to exit immediately after constructor ends, without entering the event loop. When called from within an event handler, it will cause it to exit at the start of next event loop iteration. Compared to requesting an application exit using the window close button or the Alt F4 / Cmd Q keyboard shortcut, the exitEvent() isn't called when using this function.

Calling this function from an application constructor is recommended over std::exit() or Fatal, which exit without calling destructors on local scope. Note that, however, you need to explicitly return after calling it, as it can't exit the constructor on its own:

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

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

    // …
}

GLFWwindow* Magnum::Platform::GlfwApplication::window()

Underlying window handle.

Use in case you need to call GLFW functionality directly.

void Magnum::Platform::GlfwApplication::create(const Configuration& configuration, const GLConfiguration& glConfiguration) protected

Create a window with given configuration for OpenGL context.

Must be called if and only if the context wasn't created by the constructor itself, i.e. when passing NoCreate to it. Error message is printed and the program exits if the context cannot be created, see tryCreate() for an alternative.

On desktop GL, if version is not specified in glConfiguration, the application first tries to create core context (OpenGL 3.2+) and if that fails, falls back to compatibility OpenGL 2.1 context.

void Magnum::Platform::GlfwApplication::create(const Configuration& configuration) protected

Create a window with given configuration.

If Configuration::WindowFlag::Contextless is present or Magnum was not built with MAGNUM_TARGET_GL, this creates a window without any GPU context attached, leaving that part on the user.

If none of the flags is present and Magnum was built with MAGNUM_TARGET_GL, this is equivalent to calling create(const Configuration&, const GLConfiguration&) with default-constructed GLConfiguration.

See also Enabling or disabling features for more information.

void Magnum::Platform::GlfwApplication::create() protected

Create a window with default configuration and OpenGL context.

Equivalent to calling create(const Configuration&) with default-constructed Configuration.

bool Magnum::Platform::GlfwApplication::tryCreate(const Configuration& configuration, const GLConfiguration& glConfiguration) protected

Try to create context with given configuration for OpenGL context.

Unlike create(const Configuration&, const GLConfiguration&) returns false if the context cannot be created, true otherwise.

bool Magnum::Platform::GlfwApplication::tryCreate(const Configuration& configuration) protected

Try to create context with given configuration.

Unlike create(const Configuration&) returns false if the context cannot be created, true otherwise.

void Magnum::Platform::GlfwApplication::tickEvent() virtual protected new in Git master

Tick event.

If implemented, this function is called periodically after processing all input events and before draw event even though there might be no input events and redraw is not requested. Useful e.g. for asynchronous task polling. Use setMinimalLoopPeriod() / setSwapInterval() to control main loop frequency.

If this implementation gets called from its override, it will effectively stop the tick event from being fired and the app returns back to waiting for input events. This can be used to disable the tick event when not needed.

Vector2i Magnum::Platform::GlfwApplication::windowSize() const

Window size.

Window size to which all input event coordinates can be related. Note that, especially on HiDPI systems, it may be different from framebufferSize(). Expects that a window is already created. See DPI awareness for more information.

void Magnum::Platform::GlfwApplication::setWindowSize(const Vector2i& size) new in 2020.06

Set window size.

To make the sizing work independently of the display DPI, size is internally multiplied with dpiScaling() before getting applied. Expects that a window is already created.

void Magnum::Platform::GlfwApplication::setMinWindowSize(const Vector2i& size = {-1, -1}) new in 2019.10

Set window minimum size.

If a value is set to -1, it will disable/remove the corresponding limit. To make the sizing work independently of the display DPI, size is internally multiplied with dpiScaling() before getting applied. Expects that a window is already created.

void Magnum::Platform::GlfwApplication::setMaxWindowSize(const Vector2i& size = {-1, -1}) new in 2019.10

Set window maximum size.

If a value is set to -1, it will disable/remove the corresponding limit. To make the sizing work independently of the display DPI, size is internally multiplied with dpiScaling() before getting applied. Expects that a window is already created.

Vector2i Magnum::Platform::GlfwApplication::framebufferSize() const

Framebuffer size.

Size of the default framebuffer. Note that, especially on HiDPI systems, it may be different from windowSize(). Expects that a window is already created. See DPI awareness for more information.

Vector2 Magnum::Platform::GlfwApplication::dpiScaling() const

DPI scaling.

How the content should be scaled relative to system defaults for given windowSize(). If a window is not created yet, returns zero vector, use dpiScaling(const Configuration&) for calculating a value independently. See DPI awareness for more information.

Vector2 Magnum::Platform::GlfwApplication::dpiScaling(const Configuration& configuration)

DPI scaling for given configuration.

Calculates DPI scaling that would be used when creating a window with given configuration. Takes into account DPI scaling policy and custom scaling specified on the command-line. See DPI awareness for more information.

void Magnum::Platform::GlfwApplication::setWindowTitle(Containers::StringView title) new in 2019.10

Set window title.

The title is expected to be encoded in UTF-8.

void Magnum::Platform::GlfwApplication::setWindowIcon(Containers::ArrayView<const ImageView2D> images) new in Git master

Set window icon.

The images are expected to be with origin at bottom left (which is the default for imported images) and in one of PixelFormat::RGB8Unorm, PixelFormat::RGB8Srgb, PixelFormat::RGBA8Unorm or PixelFormat::RGBA8Srgb formats. If you have just one image, you can use setWindowIcon(const ImageView2D&) instead.

void Magnum::Platform::GlfwApplication::setWindowIcon(std::initializer_list<ImageView2D> images) new in 2020.06

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void Magnum::Platform::GlfwApplication::setWindowIcon(const ImageView2D& image) new in 2020.06

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void Magnum::Platform::GlfwApplication::swapBuffers()

Swap buffers.

Paints currently rendered framebuffer on screen.

void Magnum::Platform::GlfwApplication::setSwapInterval(Int interval)

Set swap interval.

Set 0 for no VSync, 1 for enabled VSync. Some platforms support -1 for late swap tearing. Default is driver-dependent.

void Magnum::Platform::GlfwApplication::setMinimalLoopPeriod(Nanoseconds time) new in Git master

Set minimal loop period.

This setting reduces the main loop frequency in case setSwapInterval() wasn't called at all, was called with 0, or no drawing is done and just tickEvent() is being executed. The time is expected to be non-negative, default is 0_nsec (i.e., looping at maximum frequency). If the application is drawing on the screen and VSync was enabled by calling setSwapInterval(), this setting is ignored.

Note that as the VSync default is driver-dependent, setSwapInterval() has to be explicitly called to make the interaction between the two work correctly.

void Magnum::Platform::GlfwApplication::redraw()

Redraw immediately.

Marks the window for redrawing, resulting in call to drawEvent() in the next iteration. You can call it from drawEvent() itself to redraw immediately without waiting for user input.

void Magnum::Platform::GlfwApplication::viewportEvent(ViewportEvent& event) virtual private

Viewport event.

Called when window size changes. The default implementation does nothing. If you want to respond to size changes, you should pass the new size to GL::DefaultFramebuffer::setViewport() (if using OpenGL) and possibly elsewhere (to SceneGraph::Camera::setViewport(), other framebuffers...).

Note that this function might not get called at all if the window size doesn't change. You should configure the initial state of your cameras, framebuffers etc. in application constructor rather than relying on this function to be called. Size of the window can be retrieved using windowSize(), size of the backing framebuffer via framebufferSize() and DPI scaling using dpiScaling(). See DPI awareness for detailed info about these values.

void Magnum::Platform::GlfwApplication::focusEvent(FocusEvent& event) virtual private new in Git master

Window focus event.

Called when the window gains (keyboard) input focus. The default implementation does nothing.

void Magnum::Platform::GlfwApplication::blurEvent(FocusEvent& event) virtual private new in Git master

Window blur event.

Called when the window loses (keyboard) input focus, which for example can be used by the application code to discard all information about currently pressed keys. The default implementation does nothing.

void Magnum::Platform::GlfwApplication::drawEvent() pure virtual private

Draw event.

Called when the screen is redrawn. You should clean the framebuffer using GL::DefaultFramebuffer::clear() (if using OpenGL) and then add your own drawing functions. After drawing is finished, call swapBuffers(). If you want to draw immediately again, call also redraw().

bool Magnum::Platform::GlfwApplication::isKeyPressed(Key key) new in Git master

Whether a key is pressed.

If a key is pressed, i.e. keyPressEvent() with given key was fired but not a keyReleaseEvent() yet, the function returns true. For unknown Key values returns false.

This function only queries immediate keyboard state at given point in time, which means that if a particular key got pressed and released again in between calls to this function, it will not be reported as pressed. To avoid losing key presses, prefer to get keyboard press and release events through keyPressEvent() and keyReleaseEvent() instead if possible.

void Magnum::Platform::GlfwApplication::keyPressEvent(KeyEvent& event) virtual private

Key press event.

Called when a key is pressed. Default implementation does nothing.

void Magnum::Platform::GlfwApplication::keyReleaseEvent(KeyEvent& event) virtual private

Key release event.

Called when a key is released. Default implementation does nothing.

void Magnum::Platform::GlfwApplication::setCursor(Cursor cursor) new in 2020.06

Set cursor type.

Expects that a window is already created. Default is Cursor::Arrow.

void Magnum::Platform::GlfwApplication::pointerPressEvent(PointerEvent& event) virtual private new in Git master

Pointer press event.

Called when a mouse is pressed. Note that if at least one mouse button is already pressed and another button gets pressed in addition, pointerMoveEvent() with the new combination is called, not this function.

On builds with MAGNUM_BUILD_DEPRECATED enabled, default implementation delegates to mousePressEvent(). On builds with deprecated functionality disabled, default implementation does nothing.

void Magnum::Platform::GlfwApplication::mousePressEvent(MouseEvent& event) virtual private

Mouse press event.

Default implementation does nothing.

void Magnum::Platform::GlfwApplication::pointerReleaseEvent(PointerEvent& event) virtual private new in Git master

Pointer release event.

Called when a mouse is released. Note that if multiple mouse buttons are pressed and one of these is released, pointerMoveEvent() with the new combination is called, not this function.

On builds with MAGNUM_BUILD_DEPRECATED enabled, default implementation delegates to mouseReleaseEvent(). On builds with deprecated functionality disabled, default implementation does nothing.

void Magnum::Platform::GlfwApplication::mouseReleaseEvent(MouseEvent& event) virtual private

Mouse release event.

Default implementation does nothing.

void Magnum::Platform::GlfwApplication::pointerMoveEvent(PointerMoveEvent& event) virtual private new in Git master

Pointer move event.

Called when any of the currently pressed pointers is moved or changes its properties. Gets called also if the set of pressed mouse buttons changes.

On builds with MAGNUM_BUILD_DEPRECATED enabled, default implementation delegates to mouseMoveEvent(), or if PointerMoveEvent::pointer() is not Containers::NullOpt, to either mousePressEvent() or mouseReleaseEvent(). On builds with deprecated functionality disabled, default implementation does nothing.

void Magnum::Platform::GlfwApplication::mouseMoveEvent(MouseMoveEvent& event) virtual private

Mouse move event.

Default implementation does nothing.

void Magnum::Platform::GlfwApplication::scrollEvent(ScrollEvent& event) virtual private new in Git master

Scroll event.

Called when a scrolling device is used (mouse wheel or scrolling area on a touchpad).

On builds with MAGNUM_BUILD_DEPRECATED enabled, default implementation delegates to mouseScrollEvent(). On builds with deprecated functionality disabled, default implementation does nothing.

void Magnum::Platform::GlfwApplication::mouseScrollEvent(MouseScrollEvent& event) virtual private

Mouse move event.

Default implementation does nothing.

bool Magnum::Platform::GlfwApplication::isTextInputActive() const

Whether text input is active.

If text input is active, text input events go to textInputEvent().

void Magnum::Platform::GlfwApplication::startTextInput()

Start text input.

Starts text input that will go to textInputEvent().

void Magnum::Platform::GlfwApplication::stopTextInput()

Stop text input.

Stops text input that went to textInputEvent().

Containers::StringView Magnum::Platform::GlfwApplication::clipboardText() new in Git master

Current clipboard text.

The returned view is in UTF-8, is always Containers::StringViewFlag::NullTerminated and is only guaranteed to be valid until the next call to clipboardText() or setClipboardText(). If the clipboard is empty or contains non-text data (such as an image), the returned view is empty.

void Magnum::Platform::GlfwApplication::setClipboardText(Containers::StringView text) new in Git master

Set current clipboard text.

The text is expected to be in UTF-8. If it's not Containers::StringViewFlag::NullTerminated, a null-terminated copy is made before passing it to GLFW.

void Magnum::Platform::GlfwApplication::textInputEvent(TextInputEvent& event) virtual private

Text input event.

Called when text input is active and the text is being input.

void Magnum::Platform::GlfwApplication::exitEvent(ExitEvent& event) virtual private

Exit event.

If implemented, it allows the application to react to an application exit (for example to save its internal state) and suppress it as well (for example to show a exit confirmation dialog). The default implementation calls ExitEvent::setAccepted() on event, which tells the application that it's safe to exit.