Magnum::Platform::AndroidApplication class

Android application.

Application running on Android.

This application library is available only on Android, see respective sections in the Corrade and Magnum building documentation. It is built if WITH_ANDROIDAPPLICATION is enabled when building Magnum.

Bootstrap application

Fully contained base application using Sdl2Application for desktop build and AndroidApplication for Android build along with full Android packaging stuff and CMake setup is available in base-android 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 with Sdl2Application. For the Android build you also need to put the contents of toolchains repository from in toolchains/ subdirectory. Don't forget to adapt ANDROID_NDK_ROOT in toolchains/generic/Android-*.cmake to path where NDK is installed. Default is /opt/android-ndk. Adapt also ANDROID_SYSROOT to your preferred API level. You might also need to update ANDROID_TOOLCHAIN_PREFIX and ANDROID_TOOLCHAIN_ROOT to fit your system.

First you need to update Android project files with the following command. It will create build.xml file for Ant and a bunch of other files. You need to specify the target for which you will build in the -t parameter. List of all targets can be obtained by calling android list target.

android update project -p . -t "android-19"

Then create build directories for ARM and x86 and run cmake and build command in them. Set CMAKE_PREFIX_PATH to the directory where you have all the dependencies.

mkdir build-android-arm && cd build-android-arm
cmake .. \
    -DCMAKE_TOOLCHAIN_FILE="../toolchains/generic/Android-ARM.cmake" \
cmake --build .

mkdir build-android-x86 && cd build-android-x86
cmake .. \
    -DCMAKE_TOOLCHAIN_FILE="../toolchains/generic/Android-x86.cmake" \
cmake --build .

See Usage with CMake for more information.

The compiled binaries will be put into lib/armeabi-v7a and lib/x86. You can then build the APK package simply by running ant. The resulting APK package can be then installed directly on the device or emulator using adb install.

ant debug
adb install bin/NativeActivity-debug.apk

General usage

In order to use this library from CMake, you need to copy FindEGL.cmake and FindOpenGLES2.cmake (or FindOpenGLES3.cmake) from the modules/ directory in Magnum source to the modules/ dir in your project (so it is able to find EGL and OpenGL ES libraries). Request the AndroidApplication component of the Magnum package and link to the Magnum::AndroidApplication target:

find_package(Magnum REQUIRED)
    find_package(Magnum REQUIRED AndroidApplication)

# ...
    target_link_libraries(your-app Magnum::AndroidApplication)

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. Note that unlike on other platforms you need to create shared library instead of executable. The resulting binary then needs to be copied to lib/armeabi-v7a and lib/x86, you can do that automatically in CMake using the following commands:


In C++ code you need to implement at least drawEvent() to be able to draw on the screen. The subclass must be then made accessible from JNI using MAGNUM_ANDROIDAPPLICATION_MAIN() macro. See Platform support for more information.

class MyApplication: public Platform::AndroidApplication {
    // implement required methods...

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.

Android packaging stuff

The application needs at least the AndroidManifest.xml with the following contents:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="" package="cz.mosra.magnum.application" android:versionCode="1" android:versionName="1.0">
  <uses-sdk android:minSdkVersion="9" />
  <uses-feature android:glEsVersion="0x00020000" />
  <application android:label="Magnum Android Application" android:hasCode="false">
    <activity android:name="" android:label="Magnum Android Application">
      <meta-data android:name="" android:value="{{application}}" />
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />

Modify android:label to your liking, set unique package name and replace {{application}} with name of the binary file (without extension). If you plan to use OpenGL ES, set android:glEsVersion to 0x00030000. The resulting APK file will be named NativeActivity.apk by default, you can change that either by passing -n parameter to android update project or later by editing first line of the generated build.xml file.

Redirecting output to Android log buffer

The application by default redirects Debug, Warning and Error output to Android log buffer with tag "magnum", which can be then accessed through logcat utility. See also Corrade::Utility::AndroidLogStreamBuffer for more information.

Public types

class Configuration
class InputEvent
Base for input events.
class MouseEvent
Mouse event.
class MouseMoveEvent
Mouse move event.
using Arguments = android_app*
Application arguments.

Public static functions

static void exec(android_app* state, std::unique_ptr<AndroidApplication>(*)(const Arguments&) instancer)
Execute the application.

Constructors, destructors, conversion operators

AndroidApplication(const Arguments& arguments, const Configuration& configuration = Configuration()) explicit
Default constructor.
AndroidApplication(const Arguments& arguments, NoCreateT) explicit
AndroidApplication(const Arguments& arguments, std::nullptr_t) deprecated explicit
AndroidApplication(const AndroidApplication&) deleted
Copying is not allowed.
AndroidApplication(AndroidApplication&&) deleted
Moving is not allowed.

Public functions

auto operator=(const AndroidApplication&) -> AndroidApplication& deleted
Copying is not allowed.
auto operator=(AndroidApplication&&) -> AndroidApplication& deleted
Moving is not allowed.

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.

Screen handling

void swapBuffers() protected
Swap buffers.
void redraw() protected
Redraw immediately.
void viewportEvent(const Vector2i& size) protected virtual
Viewport event.
void drawEvent() protected pure virtual
Draw event.

Mouse handling

void mousePressEvent(MouseEvent& event) protected virtual
Mouse press event.
void mouseReleaseEvent(MouseEvent& event) protected virtual
Mouse release event.
void mouseMoveEvent(MouseMoveEvent& event) protected virtual
Mouse move event.

Function documentation

static void Magnum::Platform::AndroidApplication::exec(android_app* state, std::unique_ptr<AndroidApplication>(*)(const Arguments&) instancer)

Execute the application.

See MAGNUM_ANDROIDAPPLICATION_MAIN() for usage information.

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

Default constructor.

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::AndroidApplication::AndroidApplication(const Arguments& arguments, NoCreateT) explicit


arguments Application arguments

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

Magnum::Platform::AndroidApplication::AndroidApplication(const Arguments& arguments, std::nullptr_t) explicit


void Magnum::Platform::AndroidApplication::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.

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

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

Try to create context with given configuration.

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

void Magnum::Platform::AndroidApplication::swapBuffers() protected

Swap buffers.

Paints currently rendered framebuffer on screen.

void Magnum::Platform::AndroidApplication::redraw() protected

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::AndroidApplication::viewportEvent(const Vector2i& size) virtual protected

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 DefaultFramebuffer::setViewport() 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. Viewport of default framebuffer can be retrieved via DefaultFramebuffer::viewport().

void Magnum::Platform::AndroidApplication::drawEvent() pure virtual protected

Draw event.

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

void Magnum::Platform::AndroidApplication::mousePressEvent(MouseEvent& event) virtual protected

Mouse press event.

Called when mouse button is pressed. Default implementation does nothing.

void Magnum::Platform::AndroidApplication::mouseReleaseEvent(MouseEvent& event) virtual protected

Mouse release event.

Called when mouse button is released. Default implementation does nothing.

void Magnum::Platform::AndroidApplication::mouseMoveEvent(MouseMoveEvent& event) virtual protected

Mouse move event.

Called when mouse is moved. Default implementation does nothing.