Platform: implemented handling of AndroidApplication::viewportEvent().

doc/changelog.dox

@@ -67,6 +67,9 @@ r<Player<T, K>>>)
     @ref Platform::AndroidApplication::dpiScaling() and
     @ref Platform::AndroidApplication::ViewportEvent::dpiScaling() for
     compatibility with other application implementations
+-   Implemented handling of @ref Platform::AndroidApplication::viewportEvent()
+    and documenting how to get Android to call it instead of relaunching the
+    app from scratch
 
 @subsection changelog-latest-changes Changes and improvements
 

doc/platforms-android.dox

@@ -147,7 +147,10 @@ version is:
   <uses-feature android:glEsVersion="0x00020000" />
   <uses-sdk android:minSdkVersion="4" android:targetSdkVersion="11" />
   <application android:label="{{ app_name }}" android:hasCode="false">
-    <activity android:name="android.app.NativeActivity" android:label="{{ app_name }}">
+    <activity
+        android:name="android.app.NativeActivity"
+        android:label="{{ app_name }}"
+        android:configChanges="orientation|screenSize">
       <meta-data android:name="android.app.lib_name" android:value="{{ lib_name }}" />
       <intent-filter>
         <action android:name="android.intent.action.MAIN" />
@@ -180,6 +183,16 @@ pixel size. That is not supported by @ref Platform::AndroidApplication since
 there's [no reliable way](https://stackoverflow.com/q/17481341) to get the
 actual size used for events in that case.
 
+@anchor platforms-android-apps-manifest-screen-resize
+
+The @cb{.xml} <activity … android:configChanges="orientation|screenSize"> @ce
+attribute is needed in order to make the application properly receive a
+viewport event. By default it's being outright killed and recreated when device
+orientation changes for questionable "performance reasons". If you really want
+to handle orientation changes that way, remove `screenSize` from the set.
+Among other options is restricting the app to only portrait or landscape screen
+orientation.
+
 Consult [the Android developer documentation](https://developer.android.com/guide/topics/manifest/manifest-intro.html)
 for further information about the manifest file.
 

src/Magnum/Platform/AndroidApplication.cpp

@@ -228,6 +228,16 @@ void AndroidApplication::commandEvent(android_app* state, int32_t cmd) {
         case APP_CMD_LOST_FOCUS:
             /** @todo Make use of these */
             break;
+
+        case APP_CMD_CONFIG_CHANGED: {
+            /* This says "the current device configuration has changed", which
+               is about as vague as it can get. It seems to be that this gets
+               emitted when screen orientation changes, for example. Fire the
+               viewport event in this case. */
+            ViewportEvent e{{ANativeWindow_getWidth(data.instance->_state->window),
+                             ANativeWindow_getHeight(data.instance->_state->window)}};
+            data.instance->viewportEvent(e);
+        } break;
     }
 }
 

src/Magnum/Platform/AndroidApplication.h

@@ -128,6 +128,15 @@ If no other application header is included, this class is also aliased to
 @cpp Platform::Application @ce and the macro is aliased to @cpp MAGNUM_APPLICATION_MAIN() @ce
 to simplify porting.
 
+@section Platform-AndroidApplication-resizing Responding to viewport events
+
+Unlike in desktop application implementations, where this is controlled via
+@ref 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 @ref platforms-android-apps-manifest-screen-resize "manifest file docs"
+for more information.
+
 @section Platform-AndroidApplication-output-redirection Redirecting output to Android log buffer
 
 The application by default redirects @ref Corrade::Utility::Debug "Debug",
@@ -361,7 +370,32 @@ class AndroidApplication {
     #else
     private:
     #endif
-        /** @copydoc GlfwApplication::viewportEvent(ViewportEvent&) */
+        /**
+         * @brief 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
+         * @ref GL::DefaultFramebuffer::setViewport() (if using OpenGL) and
+         * possibly elsewhere (to @ref SceneGraph::Camera::setViewport(), other
+         * framebuffers...).
+         *
+         * @attention Android by default kills and fully recreates the
+         *      application on device orientation change instead of calling the
+         *      viewport event. To prevent that, you need to modify the
+         *      `AndroidManifest.xml` file. See the
+         *      @ref platforms-android-apps-manifest-screen-resize "manifest file docs"
+         *      for more information.
+         *
+         * 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 @ref windowSize(), size of the backing framebuffer
+         * via @ref framebufferSize() and DPI scaling using @ref dpiScaling().
+         * See @ref Platform-GlfwApplication-dpi for detailed info about these
+         * values.
+         */
         virtual void viewportEvent(ViewportEvent& event);
 
         #ifdef MAGNUM_BUILD_DEPRECATED

src/Magnum/Platform/Test/AndroidManifest.xml

@@ -3,7 +3,10 @@
   <uses-feature android:glEsVersion="0x00020000" />
   <uses-sdk android:minSdkVersion="4" android:targetSdkVersion="11" />
   <application android:label="AndroidApplication Test" android:hasCode="false">
-    <activity android:name="android.app.NativeActivity" android:label="AndroidApplication Test">
+    <activity
+        android:name="android.app.NativeActivity"
+        android:label="AndroidApplication Test"
+        android:configChanges="orientation|screenSize">
       <meta-data android:name="android.app.lib_name" android:value="PlatformAndroidApplicationTest" />
       <intent-filter>
         <action android:name="android.intent.action.MAIN" />