Magnum::Platform::AndroidApplication class

Android application.

Bootstrap application
General usage
Redirecting output to Android log buffer
Reference

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.

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

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)
if(CORRADE_TARGET_ANDROID)
    find_package(Magnum REQUIRED AndroidApplication)
endif()

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

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.

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.

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: Configuration.
class GLConfiguration: OpenGL context 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, const GLConfiguration& glConfiguration) explicit: Construct with given configuration for OpenGL context.
AndroidApplication(const Arguments& arguments, const Configuration& configuration) explicit: Construct with given configuration.
AndroidApplication(const Arguments& arguments) explicit: Construct with default configuration.
AndroidApplication(const Arguments& arguments, NoCreateT) explicit: Construct without creating a window.
AndroidApplication(const Arguments& arguments, std::nullptr_t) deprecated 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.
void createContext(const Configuration& configuration) deprecated: Create a window with given configuration for OpenGL context.
void createContext() deprecated: 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.
auto tryCreateContext(const Configuration& configuration) -> bool deprecated: Try to create context with given configuration for OpenGL context.

Screen handling

auto windowSize() -> Vector2i protected: Window size.
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, const GLConfiguration& glConfiguration) explicit

Construct with given configuration for OpenGL context.

Parameters
arguments	Application arguments
configuration	Application configuration
glConfiguration	OpenGL context configuration

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

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

Construct with given configuration.

Equivalent to calling AndroidApplication(const Arguments&, const Configuration&, const GLConfiguration&) with default-constructed GLConfiguration.

Magnum::Platform::AndroidApplication::AndroidApplication(const Arguments& arguments) explicit

Construct with default configuration.

Equivalent to calling AndroidApplication(const Arguments&, const Configuration&) with default-constructed Configuration.

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

Construct without creating a window.

Parameters
arguments	Application arguments

Unlike above, the window is not created and must be created later with create() or tryCreate().

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

Construct without creating a window.

ANativeActivity* Magnum::Platform::AndroidApplication::nativeActivity()

Underlying native activity handle.

Use in case you need to call NDK functionality directly.

void Magnum::Platform::AndroidApplication::create(const Configuration& configuration, const GLConfiguration& glConfiguration) protected

Create a window with given configuration for OpenGL context.

Parameters
configuration	Application configuration
glConfiguration	OpenGL context configuration

Must be called only if the context wasn't created by the constructor itself, i.e. when passing NoCreate to it. Error message is printed and the program exits if the context cannot be created, see tryCreate() for an alternative.

void Magnum::Platform::AndroidApplication::create(const Configuration& configuration) protected

Create a window with given configuration and OpenGL context.

Equivalent to calling create(const Configuration&, const GLConfiguration&) with default-constructed GLConfiguration.

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

Create a window with default configuration and OpenGL context.

Equivalent to calling create(const Configuration&) with default-constructed Configuration.

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

Create a window with given configuration for OpenGL context.

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

Create a window with default configuration and OpenGL context.

bool Magnum::Platform::AndroidApplication::tryCreate(const Configuration& configuration, const GLConfiguration& glConfiguration) protected

Try to create context with given configuration for OpenGL context.

Unlike create(const Configuration&, const GLConfiguration&) returns false if the context cannot be created, true otherwise.

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

Try to create context with given configuration and OpenGL context.

Unlike create(const Configuration&) returns false if the context cannot be created, true otherwise.

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

Try to create context with given configuration for OpenGL context.

Vector2i Magnum::Platform::AndroidApplication::windowSize() protected

Window size.

Window size to which all input event coordinates can be related. Note that especially on HiDPI systems the reported window size might not be the same as framebuffer size.

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 GL::DefaultFramebuffer::setViewport() (if using OpenGL) 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 GL::DefaultFramebuffer::viewport().

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

Draw event.

Called when the screen is redrawn. You should clean the framebuffer using GL::DefaultFramebuffer::clear() (if using OpenGL) 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.