Android support for EFrame (#1952)

* eframe: allow hooking into EventLoop building

This enables native applications to add an `event_loop_builder` callback
to the `NativeOptions` struct that lets them modify the Winit
`EventLoopBuilder` before the final `EventLoop` is built and run.

This makes it practical for applications to change platform
specific config options that Egui doesn't need to be directly aware of.

For example the `android-activity` glue crate that supports writing
Android applications in Rust requires that the Winit event loop be
passed a reference to the `AndroidApp` that is given to the
`android_main` entrypoint for the application.

Since the `AndroidApp` itself is abstracted by Winit then there's no
real need for Egui/EFrame to have a dependency on the `android-activity`
crate just for the sake of associating this state with the event loop.

Addresses: #1951

* eframe: defer graphics state initialization until app Resumed

Conceptually the Winit `Resumed` event signifies that the application is
ready to run and render and since
rust-windowing/winit#2331 all platforms now
consistently emit a Resumed event that can be used to initialize
graphics state for an application.

On Android in particular it's important to wait until the application
has Resumed before initializing graphics state since it won't have an
associated SurfaceView while paused.

Without this change then Android applications are likely to just show
a black screen.

This updates the Wgpu+Winit and Glow+Winit integration for eframe but
it's worth noting that the Glow integration is still not able to fully
support suspend and resume on Android due to limitations with Glutin's
API that mean we can't destroy and create a Window without also
destroying the GL context, and therefore (practically) the entire
application.

There is a plan (and progress on) to improve the Glutin API here:
rust-windowing/glutin#1435 and with that change
it should be an incremental change to enable Android suspend/resume
support with Glow later.

In the mean time the Glow changes keep the implementation consistent
with the wgpu integration and it should now at least be possible to
start an Android application - even though it won't be able to suspend
correctly.

Fixes #1951

crates/eframe/CHANGELOG.md

@@ -5,7 +5,8 @@ NOTE: [`egui-winit`](../egui-winit/CHANGELOG.md), [`egui_glium`](../egui_glium/C
 
 
 ## Unreleased
-
+* Added `NativeOptions::event_loop_builder` hook for apps to change platform specific event loop options ([#1952](https://github.com/emilk/egui/pull/1952)).
+* Enabled deferred render state initialization to support Android ([#1952](https://github.com/emilk/egui/pull/1952)).
 
 ## 0.19.0 - 2022-08-20
 * MSRV (Minimum Supported Rust Version) is now `1.61.0` ([#1846](https://github.com/emilk/egui/pull/1846)).

crates/eframe/src/epi.rs

@@ -6,6 +6,18 @@
 
 #![warn(missing_docs)] // Let's keep `epi` well-documented.
 
+#[cfg(not(target_arch = "wasm32"))]
+pub use crate::native::run::RequestRepaintEvent;
+#[cfg(not(target_arch = "wasm32"))]
+pub use winit::event_loop::EventLoopBuilder;
+
+/// Hook into the building of an event loop before it is run
+///
+/// You can configure any platform specific details required on top of the default configuration
+/// done by `EFrame`.
+#[cfg(not(target_arch = "wasm32"))]
+pub type EventLoopBuilderHook = Box<dyn FnOnce(&mut EventLoopBuilder<RequestRepaintEvent>)>;
+
 /// This is how your app is created.
 ///
 /// You can use the [`CreationContext`] to setup egui, restore state, setup OpenGL things, etc.
@@ -177,7 +189,6 @@ pub enum HardwareAcceleration {
 ///
 /// Only a single native window is currently supported.
 #[cfg(not(target_arch = "wasm32"))]
-#[derive(Clone)]
 pub struct NativeOptions {
     /// Sets whether or not the window will always be on top of other windows.
     pub always_on_top: bool,
@@ -292,6 +303,25 @@ pub struct NativeOptions {
     /// When `true`, [`winit::platform::run_return::EventLoopExtRunReturn::run_return`] is used.
     /// When `false`, [`winit::event_loop::EventLoop::run`] is used.
     pub run_and_return: bool,
+
+    /// Hook into the building of an event loop before it is run.
+    ///
+    /// Specify a callback here in case you need to make platform specific changes to the
+    /// event loop before it is run.
+    ///
+    /// Note: A [`NativeOptions`] clone will not include any `event_loop_builder` hook.
+    pub event_loop_builder: Option<EventLoopBuilderHook>,
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+impl Clone for NativeOptions {
+    fn clone(&self) -> Self {
+        Self {
+            icon_data: self.icon_data.clone(),
+            event_loop_builder: None, // Skip any builder callbacks if cloning
+            ..*self
+        }
+    }
 }
 
 #[cfg(not(target_arch = "wasm32"))]
@@ -319,6 +349,7 @@ impl Default for NativeOptions {
             follow_system_theme: cfg!(target_os = "macos") || cfg!(target_os = "windows"),
             default_theme: Theme::Dark,
             run_and_return: true,
+            event_loop_builder: None,
         }
     }
 }

crates/eframe/src/lib.rs

@@ -169,13 +169,13 @@ pub fn run_native(app_name: &str, native_options: NativeOptions, app_creator: Ap
         #[cfg(feature = "glow")]
         Renderer::Glow => {
             tracing::debug!("Using the glow renderer");
-            native::run::run_glow(app_name, &native_options, app_creator);
+            native::run::run_glow(app_name, native_options, app_creator);
         }
 
         #[cfg(feature = "wgpu")]
         Renderer::Wgpu => {
             tracing::debug!("Using the wgpu renderer");
-            native::run::run_wgpu(app_name, &native_options, app_creator);
+            native::run::run_wgpu(app_name, native_options, app_creator);
         }
     }
 }