class
AndroidApplicationAndroid application.
Application running on Android. Available only on Android, see respective sections in the Corrade and Magnum building documentation.
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, put FindEGL.cmake and FindOpenGLES2.cmake (or FindOpenGLES3.cmake) into your modules/
directory, 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_
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::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::
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.
- class ViewportEvent
- Viewport event.
- using Arguments = android_app*
- Application arguments.
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 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 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.
Mouse handling
- void mousePressEvent(MouseEvent& event) private virtual
- Mouse press event.
- void mouseReleaseEvent(MouseEvent& event) private virtual
- Mouse release event.
- void mouseMoveEvent(MouseMoveEvent& event) private virtual
- Mouse move event.
Function documentation
static void Magnum:: Platform:: AndroidApplication:: exec(android_app* state,
Containers:: Pointer<AndroidApplication>(*)(const Arguments&) instancer)
Execute the application.
See MAGNUM_
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().
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.
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.
Vector2i Magnum:: Platform:: AndroidApplication:: windowSize() const
Window size.
Window size to which all input event coordinates can be related. Expects that a window is already created, equivalent to framebufferSize().
Vector2i Magnum:: Platform:: AndroidApplication:: framebufferSize() const
Framebuffer size.
Size of the default framebuffer, equivalent to windowSize(). Expects that a window is already created.
Vector2 Magnum:: Platform:: AndroidApplication:: dpiScaling() const
DPI scaling.
Provided only for compatibility with other toolkits. Returns always {1.0f, 1.0f}
.
Vector2 Magnum:: Platform:: AndroidApplication:: dpiScaling(const Configuration& configuration) const
DPI scaling for given configuration.
Provided only for compatibility with other toolkits. Returns always {1.0f, 1.0f}
.
void Magnum:: Platform:: AndroidApplication:: swapBuffers()
Swap buffers.
Paints currently rendered framebuffer on screen.
void Magnum:: Platform:: AndroidApplication:: redraw()
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(ViewportEvent& event) virtual private
Viewport event.
Called when window size changes, for example after device orientation change. The default implementation does nothing. If you want to respond to size changes, you should pass the new size to GL::
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. Size of the window can be retrieved using windowSize(), size of the backing framebuffer via framebufferSize() and DPI scaling using dpiScaling(). See DPI awareness for detailed info about these values.
void Magnum:: Platform:: AndroidApplication:: drawEvent() pure virtual private
Draw event.
Called when the screen is redrawn. You should clean the framebuffer using GL::
void Magnum:: Platform:: AndroidApplication:: mousePressEvent(MouseEvent& event) virtual private
Mouse press event.
Called when mouse button is pressed. Default implementation does nothing.
void Magnum:: Platform:: AndroidApplication:: mouseReleaseEvent(MouseEvent& event) virtual private
Mouse release event.
Called when mouse button is released. Default implementation does nothing.
void Magnum:: Platform:: AndroidApplication:: mouseMoveEvent(MouseMoveEvent& event) virtual private
Mouse move event.
Called when mouse is moved. Default implementation does nothing.