android-activity/README.md

This project includes a number of Android "glue" crates for native Rust development (comparable to android_native_app_glue.c which supports C/C++ applications).

These glue crates provide a way to load a cdylib via the onCreate method of your Activity class; run an android_main() function in a separate thread from the Java main thread and marshal events (such as lifecycle events and input events) between Java and your native thread.

Example

cargo init --lib --name=example

Cargo.toml

[dependencies]
log = "0.4"
android_logger = "0.11"
native-activity = { git = "https://github.com/rib/agdk-rust/" }

[lib]
crate_type = ["cdylib"]

lib.rs

use log::info;
use native_activity::{PollEvent, MainEvent};

#[no_mangle]
extern "C" fn android_main() {
    android_logger::init_once(
        android_logger::Config::default().with_min_level(log::Level::Info)
    );

    let app = native_activity::android_app();
    loop {
        app.poll_events(Some(std::time::Duration::from_millis(500)) /* timeout */, |event| {
            match event {
                PollEvent::Wake => { info!("Early wake up"); },
                PollEvent::Timeout => { info!("Hello, World!"); },
                PollEvent::Main(main_event) => {
                    info!("Main event: {:?}", main_event);
                    match main_event {
                        MainEvent::Destroy => { return; }
                        _ => {}
                    }
                },
                _ => {}
            }

            app.input_events(|event| {
                info!("Input Event: {event:?}");
            });
        });
    }
}

rustup target add aarch64-linux-android
cargo install cargo-apk
cargo apk run

Game Activity

Originally the aim was to enable support for building Rust applications based on the GameActivity based class provided by Google's Android Game Development Kit which should also facilitate integration with additional AGDK libraries including:

1. Game Text Input: a library to help fullscreen native applications utilize the Android soft keyboard.
2. Game Controller Library, aka 'Paddleboat': a native library designed to help support access to game controller inputs. 3.Frame Pacing Library, aka ' Swappy': a library that helps OpenGL and Vulkan games achieve smooth rendering and correct frame pacing on Android.
3. Memory Advice API: an API to help applications monitor their own memory usage to stay within safe limits for the system.
4. Oboe audio library: a low-latency audio API for native applications.

Since GameActivity is based on the widely used AppCompatActivity base class, it also provides a variety of back ported Activity APIs which can make it more practical to support a wider range of devices and Android versions.

Native Activity

This project also supports NativeActivity based applications. Although NativeActivity is more limited than GameActivity and does not derive from AppCompatActivity it can sometimes still be convenient to build on NativeActivity in situations where you are using a limited/minimal build system that is not able to compile Java or Kotlin code or fetch from Maven repositories. This is because NativeActivity is included as part of the Android platform.

Design

Compatibility

Both the game-activity glue crate and the native-activity glue crate support a common API that allows them to be used interchangably, depending on which base class your application decides to use.

Although it's expected that the game-activity crate will gain features that aren't possible with native-activity those should be covered by optional features that allow downstream crates, such as Winit to practically be able to support alternative glue layers.

The hope is that the core, common API can be supported via any Activity subclass that your application needs to use.

API Summary

android_main entrypoint

The glue crates define a standard entrypoint ABI for your cdylib that looks like:

#[no_mangle]
extern "C" fn android_main() {
    ...
}

There's currently no high-level macro provided for things like initializing logging or allowing the main function to return a Result<> since it's expected that different downstream frameworks may each have differing oppinions on the details and may want to provide their own macros.

Global AndroidApp

The glue layer provides a 'static AndroidApp API to access state about your running application and handle synchronized interaction between your native Rust application and the Activity running on the Java main thread.

For example, the AndroidApp API enables:

1. Access to Android lifecycle events
2. Notifications of SurfaceView lifecycle events
3. Access to input events
4. Ability to save and restore state each time your process stops and starts

For example:

#[no_mangle]
extern "C" fn android_main() {
    let app = game_activity::android_app();
    ...
}

Note: that some of the AndroidApp APIs (such as for polling events) are only deemed safe to use from the application's main thread

Synchronized event callbacks

The AndroidApp::poll_events() API is similar to the Winit EventLoop::run API in that it takes a FnMut closure that is called for each outstanding event (such as for lifecycle events). This is modeled on the original android_native_app_glue design for C/C++ that reserves the ability for the glue layer to insert "pre-" and "-post" hooks around the application's event callback that can handle any required synchronization with the Java main thread.

For example, when the Java main thread notifies the glue layer that its SurfaceView is being destroyed the Java thread will then block until it gets an explicit acknowledgement that the native application has had an opportunity to react to this notification. The glue layer will automatically release the blocked Java thread once it has delivered the corresponding event.

For example:

use native_activity::{PollEvent, MainEvent};
use log::info;

#[no_mangle]
extern "C" fn android_main() {
    android_logger::init_once(
        android_logger::Config::default().with_min_level(log::Level::Info)
    );

    let mut quit = false;
    let mut redraw_pending = true;
    let mut render_state: Option<()> = Default::default();

    let app = native_activity::android_app();
    while !quit {
        app.poll_events(Some(std::time::Duration::from_millis(500)) /* timeout */, |event| {
            match event {
                PollEvent::Wake => { info!("Early wake up"); },
                PollEvent::Timeout => {
                    info!("Timed out");
                    // Real app would probably rely on vblank sync via graphics API...
                    redraw_pending = true;
                },
                PollEvent::Main(main_event) => {
                    info!("Main event: {:?}", main_event);
                    match main_event {
                        MainEvent::SaveState { saver, .. } => {
                            saver.store("foo://bar".as_bytes());
                        },
                        MainEvent::Pause => {},
                        MainEvent::Resume { loader, .. } => {
                            if let Some(state) = loader.load() {
                                if let Ok(uri) = String::from_utf8(state) {
                                    info!("Resumed with saved state = {uri:#?}");
                                }
                            }
                        },
                        MainEvent::InitWindow { .. } => {
                            render_state = Some(());
                            redraw_pending = true;
                        },
                        MainEvent::TerminateWindow { .. } => {
                            render_state = None;
                        }
                        MainEvent::WindowResized { .. } => { redraw_pending = true; },
                        MainEvent::RedrawNeeded { ..} => { redraw_pending = true; },
                        MainEvent::LowMemory => {},

                        MainEvent::Destroy => { quit = true },
                        _ => { /* ... */}
                    }
                },
                _ => {}
            }

            if redraw_pending {
                if let Some(_rs) = render_state {
                    redraw_pending = false;

                    // Handle input
                    app.input_events(|event| {
                        info!("Input Event: {event:?}");

                    });

                    info!("Render...");
                }
            }
        });
    }
}