Magnum::Platform::WindowlessEglApplication class
#include <Magnum/Platform/WindowlessEglApplication.h>

Windowless EGL application.

Application for offscreen rendering using WindowlessEglContext. This application library is in theory available for all platforms for which EGL works (Linux desktop or ES, iOS, Android and also Emscripten). See other Windowless*Application classes for an alternative.

Bootstrap application

Fully contained windowless application using WindowlessEglApplication along with CMake setup is available in windowless 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 windowless application together with Emscripten support along with full HTML markup and CMake setup is available in windowless-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 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_WINDOWLESSEGLAPPLICATION is enabled when building Magnum. To use this library from CMake, request the WindowlessEglApplication component of the Magnum package and link to the Magnum::WindowlessEglApplication target:

find_package(Magnum REQUIRED WindowlessEglApplication)

# ...
target_link_libraries(your-app PRIVATE Magnum::WindowlessEglApplication)

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_WINDOWLESSEGLAPPLICATION ON CACHE BOOL "" FORCE)
add_subdirectory(magnum EXCLUDE_FROM_ALL)

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

Place your code into exec(). The subclass can be then used in main function using MAGNUM_WINDOWLESSEGLAPPLICATION_MAIN() macro. See Platform support for more information.

class MyApplication: public Platform::WindowlessEglApplication {
    // implement required methods...
};
MAGNUM_WINDOWLESSEGLAPPLICATION_MAIN(MyApplication)

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

GPU device selection

The application prefers to use the EGL_EXT_device_enumeration, EGL_EXT_platform_base and EGL_EXT_platform_device extensions where available instead of EGL_DEFAULT_DISPLAY to work better on headless setups. The application chooses the first found device by default, you can override that either with Configuration::setDevice() or using a --magnum-device command-line option (and the MAGNUM_DEVICE environment variable). Unfortunately EGL doesn't provide any reasonable way to enumerate or filter named devices, so the best you can do is checking reported device count printed by the --magnum-log verbose command-line option, and then going from 0 up to figure out the desired device ID.

On systems with NVIDIA GPUs and CUDA, it's possible to directly select a particular CUDA device, allowing for EGL and CUDA to both target the same physical device for a given ID. This can be chosen via the --magnum-cuda-device command-line option (and the MAGNUM_CUDA_DEVICE environment variable), which then takes precedence over --magnum-device. The same can be also specified via via Configuration::setCudaDevice().

No EGL devices found

With GLVND versions 1.3.2 and older, EGL context creation may fail with the following error (with additional output produced when the --magnum-gpu-validation command-line option is enabled):

eglQueryDevicesEXT(): EGL_BAD_ALLOC error: In internal function: Additional INFO may be available
eglQueryDevicesEXT(): EGL_BAD_ALLOC error: In function eglQueryDevicesEXT(), backend failed to query devices
Platform::WindowlessEglApplication::tryCreateContext(): no EGL devices found

This is due to some driver implementations failing to enumerate devices (for example when the system has NVidia drivers installed as a dependency of CUDA but there actually isn't any NVidia card) and the GLVND treats that as a fatal error. This is fixed in version 1.3.3 where it just skips that particular vendor and continues. A workaround on older versions might be filtering out the bad devices manually using the __EGL_VENDOR_LIBRARY_FILENAMES environment variable as described in the libglvnd documentation, for example:

__EGL_VENDOR_LIBRARY_FILENAMES=/usr/share/glvnd/egl_vendor.d/50_mesa.json ./my-application

Shared EGL contexts

Unlike with WindowlessGlxApplication and WindowlessWglApplication, you're expected to supply both the display and the context in Configuration::setSharedContext(). This is done in order to ensure the same EGLDisplay is used for all shared contexts, especially when a non-default GPU device is selected via Configuration::setDevice().

Moreover, since eglInitialize() and eglTerminate() is expected to be called just once on a particular display, EGL initialization and termination is only done in the case of a non-shared WindowlessEglApplication (or the first one created in a shared chain). Shared instances then reuse the already initialized EGLDisplay and expect that it's terminated only after all shared instances are gone.

Public types

struct Arguments: Application arguments.
using Configuration = WindowlessEglContext::Configuration: Configuration.

Constructors, destructors, conversion operators

WindowlessEglApplication(const Arguments& arguments, const Configuration& configuration = Configuration{}) explicit: Default constructor.
WindowlessEglApplication(const Arguments& arguments, NoCreateT) explicit: Constructor.
WindowlessEglApplication(const WindowlessEglApplication&) deleted: Copying is not allowed.
WindowlessEglApplication(WindowlessEglApplication&&) deleted: Moving is not allowed.

Public functions

auto operator=(const WindowlessEglApplication&) -> WindowlessEglApplication& deleted: Copying is not allowed.
auto operator=(WindowlessEglApplication&&) -> WindowlessEglApplication& deleted: Moving is not allowed.
auto exec() -> int pure virtual: Execute application.
auto glContext() -> EGLContext new in 2020.06: Underlying OpenGL context.

Protected functions

void createContext(const Configuration& configuration = Configuration()): Create context with given configuration.
auto tryCreateContext(const Configuration& configuration) -> bool: Try to create context with given configuration.

Typedef documentation

typedef WindowlessEglContext::Configuration Magnum::Platform::WindowlessEglApplication::Configuration

Configuration.

Function documentation

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

Default constructor.

Parameters
arguments	Application arguments
configuration	Configuration

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

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

Constructor.

Parameters
arguments	Application arguments

Unlike above, the context is not created and must be created later with createContext() or tryCreateContext().

int Magnum::Platform::WindowlessEglApplication::exec() pure virtual

Execute application.

Returns	Value for returning from `main()`

See MAGNUM_WINDOWLESSEGLAPPLICATION_MAIN() for usage information.

EGLContext Magnum::Platform::WindowlessEglApplication::glContext() new in 2020.06

Underlying OpenGL context.

Use in case you need to call EGL functionality directly or in order to create a shared context. Returns nullptr in case the context was not created yet.

void Magnum::Platform::WindowlessEglApplication::createContext(const Configuration& configuration = Configuration()) protected

Create context with given configuration.

Must be called if and only if the context wasn't created by the constructor itself. Error message is printed and the program exits if the context cannot be created, see tryCreateContext() for an alternative.

bool Magnum::Platform::WindowlessEglApplication::tryCreateContext(const Configuration& configuration) protected

Try to create context with given configuration.

Unlike createContext() returns false if the context cannot be created, true otherwise.