Magnum
Classes | Public Types | Public Member Functions | Protected Member Functions | List of all members
Magnum::Platform::WindowlessEglApplication Class Referenceabstract

Windowless EGL application. More...

#include <Magnum/Platform/WindowlessEglApplication.h>

Classes

struct  Arguments
 Application arguments. More...
 

Public Types

typedef WindowlessEglContext::Configuration Configuration
 Configuration. More...
 

Public Member Functions

 WindowlessEglApplication (const Arguments &arguments, const Configuration &configuration=Configuration())
 Default constructor. More...
 
 WindowlessEglApplication (const Arguments &arguments, NoCreateT)
 Constructor. More...
 
 WindowlessEglApplication (const Arguments &arguments, std::nullptr_t)
 
 WindowlessEglApplication (const WindowlessEglApplication &)=delete
 Copying is not allowed.
 
 WindowlessEglApplication (WindowlessEglApplication &&)=delete
 Moving is not allowed.
 
WindowlessEglApplicationoperator= (const WindowlessEglApplication &)=delete
 Copying is not allowed.
 
WindowlessEglApplicationoperator= (WindowlessEglApplication &&)=delete
 Moving is not allowed.
 
virtual int exec ()=0
 Execute application. More...
 

Protected Member Functions

void createContext (const Configuration &configuration=Configuration())
 Create context with given configuration. More...
 
bool tryCreateContext (const Configuration &configuration)
 Try to create context with given configuration. More...
 

Detailed Description

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 and also Emscripten). See other Windowless*Application classes for an alternative. It is built if WITH_WINDOWLESSEGLAPPLICATION is enabled in CMake.

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 webserver, e.g. http://localhost/emscripten/MyApplication.html).

General usage

In CMake you need to request WindowlessEglApplication component and link to Magnum::WindowlessEglApplication target. If no other windowless application is requested, you can also use 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...
};

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.

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, WindowlessEmscriptenApplication.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 xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Magnum Windowless Emscripten Application</title>
<meta charset="utf-8" />
<link rel="stylesheet" href="WebApplication.css" />
</head>
<body>
<h1>Magnum Windowless Emscripten Application</h1>
<div id="listener">
<canvas id="module" class="hidden"></canvas>
<pre id="log"></pre>
<div id="status">Initialization...</div>
<div id="statusDescription"></div>
<script src="WindowlessEmscriptenApplication.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 prints all output (thus also Debug, Warning and Error) to the <pre> on the page. 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']`.

Member Typedef Documentation

Constructor & Destructor Documentation

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

Default constructor.

Parameters
argumentsApplication arguments
configurationConfiguration

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.

See also
WindowlessEglContext
Magnum::Platform::WindowlessEglApplication::WindowlessEglApplication ( const Arguments arguments,
NoCreateT   
)
explicit

Constructor.

Parameters
argumentsApplication arguments

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

Magnum::Platform::WindowlessEglApplication::WindowlessEglApplication ( const Arguments arguments,
std::nullptr_t   
)
inlineexplicit

Member Function Documentation

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

Execute application.

Returns
Value for returning from main()

See MAGNUM_WINDOWLESSEGLAPPLICATION_MAIN() for usage information.

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.

See also
WindowlessEglContext
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.