tests/android/README.md

# Running Native Code Android

On Android the typical way to run Native code is to create a shared library with specific symbols exported.
This is actually similar to how VVL exports specific functions the vulkan loader knows how to find.
The main difference is instead of the loader, it's Java.

- https://github.com/android/ndk-samples/blob/main/camera/basic/src/main/cpp/CMakeLists.txt <- In this example the symbol exported is `ANativeActivity_onCreate`
- https://github.com/android/ndk-samples/blob/main/hello-vulkan/app/src/main/cpp/CMakeLists.txt <- In this example the symbol exported is `Java_com_google_androidgamesdk_GameActivity_initializeNativeCode`

## (WSI) ANativeActivity_onCreate

As was mentioned before, exporting a symbol in your shared library that gets loaded by Java is the idiom for running native code on Android.

In our case `ANativeActivity_onCreate` is the symbol we export for our tests.

`ANativeActivity_onCreate` is defined by `android_native_app_glue.c`

For WSI, we need to call `vkCreateAndroidSurfaceKHR` which takes a `ANativeWindow` handle

Android has a life-cycle system for apps (start, background, etc). With the `ANativeActivity_onCreate` we are getting hooks into it

This example should help illustrate things:
https://github.com/sjfricke/Vulkan-NDK-Template/blob/master/app/src/main/cpp/AndroidMain.cpp

1. We need to get the mapping from the Java events so the C++ code can see it

```
    // Set the callback to process system events
    app->onAppCmd = handle_cmd;
```

2. From here we can use `NativeAppGlueAppCmd` (https://developer.android.com/reference/games/game-activity/group/android-native-app-glue) (or just look in `android_native_app_glue.c`)

3. For `APP_CMD_INIT_WINDOW` we can go `android_app->window` to get the `ANativeWindow` handle

## Why can't we just run an executable?

You can run technically run executables on Android: https://github.com/android/ndk/discussions/1726

Here is an example of using adb with the android emulator: https://github.com/microsoft/GSL/blob/main/.github/workflows/android.yml

However, WSI functionality for Android requires running the tests as an APK. So we need to build our tests as a library instead of an executable.

Android can have many apps running, but only the ones in the foreground on the device get access to the `ANativeWindow` as that is what decides what is being displayed by SurfaceFlinger (in the AOSP).

When doing a command line executable, we have no proper way to get that handle, and therefore can't create a `VkSurface`.

We could potentially build both a regular executable / APK in the future if there is enough benefit.