Tips and tricks » Writing portable applications

Target-specific code

If Magnum is compiled with e.g. OpenGL ES 2.0 support, some features present in desktop version are not available. It means that some classes, functions and enum values are simply not included in headers. It is designed this way to make porting easier — it is better to fail at compile time on e.g. undefined enum value than fail at runtime in some corner case because given texture format is not supported.

If you include Magnum.h, you get these predefined macros:

• MAGNUM_TARGET_GLES if targeting OpenGL ES
• MAGNUM_TARGET_GLES2 if targeting OpenGL ES 2.0
• MAGNUM_TARGET_GLES3 if targeting OpenGL ES 3.0
• MAGNUM_TARGET_WEBGL if targeting WebGL

Example usage:

#ifndef MAGNUM_TARGET_GLES
GL::Renderer::setPolygonMode(GL::Renderer::PolygonMode::Line);
// draw mesh as wireframe...
#else
// use different mesh, as polygon mode is not supported in OpenGL ES...
#endif

Each feature is marked accordingly if it is not available in some targets. See also Functionality requiring desktop OpenGL, Functionality requiring OpenGL ES 2.0 or WebGL 1.0 and Functionality requiring OpenGL ES 3.0.

Compiler- and platform-specific code

Magnum is attempting to be future-proof and as intuitive for users as possible. Many features from C++11 are used to simplify things and make them faster and more secure, but on the other hand it requires a compiler with good enough support of the standard. Currently Magnum is written with at least GCC 4.8, Clang 3.1 and MSVC 2015 in mind. See Corrade.h for more information.

Each feature is marked accordingly if it is not available on some compilers, see SceneGraph::DrawableGroup3D for an example. It is up to you (or your platform) which compiler your code will support, code written for e.g. GCC 4.8 will work also on Magnum compiled with support for newer compilers, although newer compilers may catch errors that weren't spotted by earlier versions.

Some functionality (such as dynamic plugin loading or filesystem access) might not be available on particular platforms. Corrade.h contains defintions which you can use for platform-aware code.

Extension-aware code

Some functionality is depending on support of a particular OpenGL extension and thus the decision cannot be made at compile time. Header GL/Extensions.h contains list of extensions, which you can pass to GL::Context::isExtensionSupported() and decide based on that:

if(GL::Context::current().isExtensionSupported<GL::Extensions::ARB::geometry_shader4>()) {
    // draw mesh with wireframe on top in one pass using geometry shader...
} else {
    // draw underlying mesh...
    GL::Renderer::setPolygonMode(GL::Renderer::PolygonMode::Line);
    // draw mesh as wirefreame in second pass...
}

You can also decide on particular OpenGL version using GL::Context::isVersionSupported(), but remember that some features from that version might be available even if the drivers don't fully expose that version.

On the other hand, if you don't want to write fallback code for unsupported extensions, you can use macros MAGNUM_ASSERT_GL_EXTENSION_SUPPORTED() or MAGNUM_ASSERT_GL_VERSION_SUPPORTED() to add mandatory requirement of given extension or version:

MAGNUM_ASSERT_GL_EXTENSION_SUPPORTED(GL::Extensions::ARB::geometry_shader4);
// just use geometry shader and don't care about old hardware

Each class, function or enum value is marked accordingly if it needs specific extension or specific OpenGL version. Various classes in Magnum are taking advantage of some extensions and enable faster code paths if given extension is available, but also have proper fallback when it's not, see for example AbstractShaderProgram, AbstractTexture or Mesh. See also Version and extension requirements.

Writing portable shaders

Shaders are probably the most painful thing to port. There are many issues to address — different shader syntax (in / out vs. attribute and varying etc.), explicit vs. implicit methods to specify vertex attribute, uniform and texture uniform locations, required precision qualifiers in OpenGL ES etc.

Shader class allows you to explicitly specify shader version and based on that you can decide on the syntax in your shader code. You can also use GL::Context::supportedVersion() to conveniently select the first supported version from a list:

// MyShader.cpp
GL::Version version = GL::Context::current().supportedVersion({
    GL::Version::GL430, GL::Version::GL330, GL::Version::GL210});
GL::Shader vert{version, GL::Shader::Type::Vertex};
vert.addFile("MyShader.vert");

// MyShader.vert
#if __VERSION__ < 130
#define in attribute
#define out varying
#endif

in vec4 position;
in vec3 normal;

out vec4 transformedNormal;

void main() {
    // ...
}

It is often desirable to query extension presence based on actually used GLSL version — while the extension might be supported in the driver, it might not be available in given GLSL version (e.g. causing compilation errors). You can use GL::Context::isExtensionSupported(Version) const to check that the extension is present in given version:

if(!GL::Context::current().isExtensionSupported<GL::Extensions::ARB::explicit_attrib_location>(version)) {
    bindAttributeLocation(Position::Location, "position");
    // ...
}

See also GL::AbstractShaderProgram class documentation for information about specifying attribute location, uniform location and texture binding unit in various OpenGL versions.

All shaders in Shaders namespace support desktop OpenGL starting from version 2.1 and also OpenGL ES 2.0 and 3.0 (or WebGL 1.0 / 2.0). Feel free to look into their sources to see how portability is handled there.

Platform-specific application support

Your application might run on Windows box, on some embedded Linux or even in browser — each platform has different requirements how to create an entry point to the application, how to handle input events, how to create window and OpenGL context etc. Namespace Platform contains application base classes which are abstracting out most of it for your convenience.

All the classes support limited form of static polymorphism, which means you can just switch to another base class and in many cases you won't need to change any other code. It has its limitations, though — some toolkits don't support all special keys, mouse movement events etc.

As mentioned in Platform support, all the classes, macros and CMake variables have generic aliases, thus using different toolkit is in most cases only matter of replacing two lines of code.

Example application, which targets both embedded Linux (using plain X and EGL) and desktop (using SDL2 toolkit). Thanks to static polymorphism most of the functions will work on both without changes, the main difference might (or might not, depending what you use) be in particular event handlers:

#ifndef MAGNUM_TARGET_GLES
#include <Magnum/Platform/Sdl2Application.h>
#else
#include <Magnum/Platform/XEglApplication.h>
#endif

using namespace Magnum;

class MyApplication: public Platform::Application {
    public:
        MyApplication(const Arguments& arguments);

    protected:
        void viewportEvent(const Vector2i& size) override;
        void drawEvent() override;
        void keyPressEvent(KeyEvent& event) override;
};

// ...

MAGNUM_APPLICATION_MAIN(MyApplication)

And corresponding CMake code. Note that we need to call find_package() twice, first to get the MAGNUM_TARGET_GLES variable and then again to find proper application library based on its value:

find_package(Magnum REQUIRED)

if(MAGNUM_TARGET_GLES)
    find_package(Magnum REQUIRED Sdl2Application)
else()
    find_package(Magnum REQUIRED XEglApplication)
endif()

add_executable(myapplication MyApplication.cpp)
target_link_libraries(myapplication
    Magnum::Magnum
    Magnum::Application)