Skip to main content

damascene_android/
lib.rs

1//! Native Android host shell for Damascene wgpu apps.
2//!
3//! Android does not let a Rust app create a winit event loop from
4//! process-global state. The Activity glue calls the app's exported
5//! `android_main(AndroidApp)`, and the host must attach that value to
6//! the event-loop builder before Damascene takes over.
7//!
8//! Downstream Android `cdylib` crates should export `android_main` and
9//! call [`run`] or [`run_with_config`] with their normal
10//! `damascene_core::App`.
11
12use damascene_core::{App, Rect};
13pub use damascene_winit_wgpu::HostConfig;
14
15#[cfg(target_os = "android")]
16pub use winit::platform::android::activity::AndroidApp;
17
18/// Run an Damascene app in Android's `NativeActivity` surface.
19///
20/// This is the Android equivalent of `damascene_winit_wgpu::run`: app code
21/// owns state/build/events; the host owns the platform event loop,
22/// surface, device/queue, and input translation.
23#[cfg(target_os = "android")]
24pub fn run<A: App + 'static>(
25    android_app: AndroidApp,
26    title: &'static str,
27    viewport: Rect,
28    app: A,
29) -> Result<(), Box<dyn std::error::Error>> {
30    run_with_config(android_app, title, viewport, app, HostConfig::default())
31}
32
33/// Run an Damascene app in Android's `NativeActivity` surface with explicit
34/// host configuration.
35///
36/// Routes the `log` facade to logcat (tag `damascene`) before starting —
37/// Android has no terminal, so without this the host's GPU-setup
38/// failure reports (e.g. "no compatible GPU adapter" on a device
39/// without a Vulkan driver) die invisibly. Apps that want their own
40/// logger can install it before calling this; `init_once` yields to
41/// an already-installed logger.
42#[cfg(target_os = "android")]
43pub fn run_with_config<A: App + 'static>(
44    android_app: AndroidApp,
45    title: &'static str,
46    viewport: Rect,
47    app: A,
48    config: HostConfig,
49) -> Result<(), Box<dyn std::error::Error>> {
50    use winit::platform::android::EventLoopBuilderExtAndroid;
51
52    android_logger::init_once(
53        android_logger::Config::default()
54            .with_max_level(log::LevelFilter::Info)
55            .with_tag("damascene"),
56    );
57
58    let mut builder = winit::event_loop::EventLoop::builder();
59    builder.with_android_app(android_app);
60    let event_loop = builder.build()?;
61    damascene_winit_wgpu::run_on_event_loop(event_loop, title, viewport, app, config)
62}
63
64/// Non-Android builds can type-check crates that depend on
65/// `damascene-android`, but cannot start an Android Activity.
66#[cfg(not(target_os = "android"))]
67pub fn run<A: App + 'static>(
68    _android_app: (),
69    _title: &'static str,
70    _viewport: Rect,
71    _app: A,
72) -> Result<(), Box<dyn std::error::Error>> {
73    Err("damascene-android can only run on target_os = \"android\"".into())
74}
75
76/// Non-Android builds can type-check crates that depend on
77/// `damascene-android`, but cannot start an Android Activity.
78#[cfg(not(target_os = "android"))]
79pub fn run_with_config<A: App + 'static>(
80    _android_app: (),
81    _title: &'static str,
82    _viewport: Rect,
83    _app: A,
84    _config: HostConfig,
85) -> Result<(), Box<dyn std::error::Error>> {
86    Err("damascene-android can only run on target_os = \"android\"".into())
87}