Magnum::Platform::AndroidApplication class

#include <Magnum/Platform/AndroidApplication.h>

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.

In order to build the application, you need Gradle and Android build of Corrade and Magnum. Gradle is usually able to download all SDK dependencies on its own and then you can just build and install the app on a connected device or emulator like this:

gradle build
gradle installDebug

Detailed information about deployment for Android and all needed boilerplate together with a troubleshooting guide is available in Android.

General usage

This application library is built if MAGNUM_WITH_ANDROIDAPPLICATION is enabled when building Magnum. To use this library with CMake, request the AndroidApplication component of the Magnum package and link to the Magnum::AndroidApplication target:

find_package(Magnum REQUIRED)
if(CORRADE_TARGET_ANDROID)
    find_package(Magnum REQUIRED AndroidApplication)
endif()

# ...
if(CORRADE_TARGET_ANDROID)
    target_link_libraries(your-app PRIVATE Magnum::AndroidApplication)
endif()

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

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 a shared library instead of an executable:

if(NOT CORRADE_TARGET_ANDROID)
    add_executable(your-app ...)
else()
    add_library(your-app SHARED ...)
endif()

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...
};
MAGNUM_ANDROIDAPPLICATION_MAIN(MyApplication)

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.

Responding to viewport events

Unlike in desktop application implementations, where this is controlled via Sdl2Application::Configuration::WindowFlag::Resizable, for example, on Android you have to describe this in the AndroidManifest.xml file, as by default the application gets killed and relaunched on screen orientation change. See the manifest file docs for more information.

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.

Touch input on Android

The application recognizes touch and pen input and reports it as Pointer::Finger, Pointer::Pen, Pointer::Eraser with PointerEventSource::Touch and PointerEventSource::Pen.

In case of a multi-touch scenario, PointerEvent::isPrimary() / PointerMoveEvent::isPrimary() can be used to distinguish the primary touch from secondary. For example, if an application doesn't need to recognize gestures like pinch to zoom or rotate, it can ignore all non-primary pointer events. PointerEventSource::Mouse and PointerEventSource::Pen events are always marked as primary, for touch input the first pressed finger is marked as primary and all following pressed fingers are non-primary. Note that there can be up to one primary pointer for each pointer event source, e.g. a finger, pen and a mouse press may all be marked as primary. On the other hand, in a multi-touch scenario, if the first (and thus primary) finger is lifted, no other finger becomes primary until all others are lifted as well. This is consistent with the logic in Sdl2Application and EmscriptenApplication but may not necessarily match what other Android applications do.

If gesture recognition is desirable, PointerEvent::id() / PointerMoveEvent::id() contains a pointer ID that's unique among all pointer event sources, which can be used to track movements of secondary, tertiary and further touch points. The ID allocation isn't defined and you can't rely on it to be contiguous or in any bounded range — for example, each new touch may generate a new ID that's only used until given finger is lifted, and then never again, or the IDs may get heavily reused, being unique only for the period given finger is pressed. For PointerEventSource::Mouse and PointerEventSource::Pen the ID is a constant, as there's always just a single mouse cursor or a pen stylus.

See also Handling mouse, touch and pen events for general information about handling pointer input in a portable way. There's also a Platform::TwoFingerGesture helper for recognition of common two-finger gestures for zoom, rotation and pan.

Public types

class Configuration

Configuration.

class GLConfiguration

OpenGL context configuration.

class InputEvent

Base for input events.

class MouseEvent deprecated in Git master

Mouse event.

class MouseMoveEvent deprecated in Git master

Mouse move event.

class PointerEvent new in Git master

Pointer event.

class PointerMoveEvent new in Git master

Pointer move event.

class ViewportEvent

Viewport event.

enum class PointerEventSource: UnsignedByte { Unknown, Mouse, Touch, Pen } new in Git master

Pointer event source.

enum class Pointer: UnsignedByte { Unknown = 1 << 0, MouseLeft = 1 << 1, MouseMiddle = 1 << 2, MouseRight = 1 << 3, Finger = 1 << 4, Pen = 1 << 5, Eraser = 1 << 6 } new in Git master

Pointer type.

using Arguments = android_app*

Application arguments.

using Pointers = Containers::EnumSet<Pointer> new in Git master

Set of pointer types.

Public static functions

static void exec(android_app* state, Containers::Pointer<AndroidApplication>(*)(const Arguments&) instancer)

Execute the application.

Constructors, destructors, conversion operators

AndroidApplication(const Arguments& arguments, const Configuration& configuration, const GLConfiguration& glConfiguration) explicit

Construct with an OpenGL context.

AndroidApplication(const Arguments& arguments, const Configuration& configuration = Configuration{}) explicit

Construct without explicit GPU context configuration.

AndroidApplication(const Arguments& arguments, NoCreateT) explicit

Construct without creating a window.

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.

auto nativeActivity() -> ANativeActivity*

Underlying native activity handle.

Protected functions

void create(const Configuration& configuration, const GLConfiguration& glConfiguration)

Create a window with given configuration for OpenGL context.

void create(const Configuration& configuration)

Create a window with given configuration and OpenGL context.

void create()

Create a window with default configuration and OpenGL context.

auto tryCreate(const Configuration& configuration, const GLConfiguration& glConfiguration) -> bool

Try to create context with given configuration for OpenGL context.

auto tryCreate(const Configuration& configuration) -> bool

Try to create context with given configuration and OpenGL context.

Screen handling

auto windowSize() const -> Vector2i

Window size.

auto framebufferSize() const -> Vector2i

Framebuffer size.

auto dpiScaling() const -> Vector2

DPI scaling.

auto dpiScaling(const Configuration& configuration) const -> Vector2

DPI scaling for given configuration.

void swapBuffers()

Swap buffers.

void redraw()

Redraw immediately.

void viewportEvent(ViewportEvent& event) private virtual

Viewport event.

void drawEvent() private pure virtual

Draw event.

Pointer handling

void pointerPressEvent(PointerEvent& event) private virtual new in Git master

Pointer press event.

void mousePressEvent(MouseEvent& event) deprecated in Git master private virtual

Mouse press event.

void pointerReleaseEvent(PointerEvent& event) private virtual new in Git master

Pointer release event.

void mouseReleaseEvent(MouseEvent& event) deprecated in Git master private virtual

Mouse release event.

void pointerMoveEvent(PointerMoveEvent& event) private virtual new in Git master

Pointer move event.

void mouseMoveEvent(MouseMoveEvent& event) deprecated in Git master private virtual

Mouse move event.

Enum documentation

Typedef documentation

Function documentation