Support for WebGPU backend in Android SDK (#4097)

This commit is contained in:
Birk Skyum
2026-02-28 16:24:14 +01:00
committed by GitHub
parent 166593f0fb
commit 57a14cf110
15 changed files with 1242 additions and 11 deletions

View File

@@ -8,6 +8,8 @@
- [Documentation](./platforms/android/android-documentation.md)
- [Benchmark](./platforms/android/benchmark.md)
- [Release](./platforms/android/release.md)
- [Rendering Backends](./platforms/android/android-rendering-backends.md)
- [WebGPU](./platforms/android/android-webgpu.md)
- [iOS](./platforms/ios/README.md)
- [Tests](./platforms/ios/ios-tests.md)
- [Documentation](./platforms/ios/ios-documentation.md)

View File

@@ -0,0 +1,53 @@
# Rendering Backends
The rendering backend is selected at build time through Gradle product flavors.
## Available backends
| Flavor | Backend | Status | Notes |
|---|---|---|---|
| `opengl` | OpenGL ES | Stable | Default, widest device compatibility |
| `vulkan` | Vulkan | Stable | Better performance on modern devices |
| `webgpuDawn` | WebGPU (Dawn) | Experimental | Uses Vulkan internally, see [WebGPU](./android-webgpu.md) |
| `webgpuWgpu` | WebGPU (wgpu-native) | Experimental | Uses Vulkan internally, arm64-v8a only, see [WebGPU](./android-webgpu.md) |
## Building with a specific backend
The flavor name is part of the Gradle task. For the test app:
```bash
cd platform/android
# OpenGL ES
./gradlew :MapLibreAndroidTestApp:installOpenglDebug
# Vulkan
./gradlew :MapLibreAndroidTestApp:installVulkanDebug
# WebGPU (Dawn)
./gradlew :MapLibreAndroidTestApp:installWebgpuDawnDebug
# WebGPU (wgpu-native)
./gradlew :MapLibreAndroidTestApp:installWebgpuWgpuDebug
```
The same pattern applies to the library module (`MapLibreAndroid`):
```bash
./gradlew :MapLibreAndroid:assembleVulkanRelease
```
## Selecting in Android Studio
In Android Studio, use the **Build Variants** panel (View > Tool Windows > Build Variants) to pick the renderer flavor. Each module will show a dropdown combining the flavor and build type, e.g. `vulkanDebug` or `openglRelease`.
## How it works
Each flavor sets different CMake arguments:
- `opengl`: `-DMLN_WITH_OPENGL=ON`
- `vulkan`: `-DMLN_WITH_VULKAN=ON`
- `webgpuDawn`: `-DMLN_WITH_WEBGPU=ON`, `-DMLN_WEBGPU_IMPL_DAWN=ON`
- `webgpuWgpu`: `-DMLN_WITH_WEBGPU=ON`, `-DMLN_WEBGPU_IMPL_WGPU=ON`
Only one backend is active per build. Renderer-specific Java code lives in `src/opengl/`, `src/vulkan/`, or `src/webgpu/` source sets.

View File

@@ -0,0 +1,73 @@
# WebGPU on Android
Two WebGPU implementations are supported: **Dawn** (Google, C++) and **wgpu-native** (Rust). Both use Vulkan internally on Android. The Gradle product flavors are `webgpuDawn` and `webgpuWgpu`, sharing the `src/webgpu/` Java source set.
## Building with Dawn
Dawn is fetched and built from source via CMake `FetchContent`, so no extra setup is needed. First build is slow (~20 min) because of Dawn's dependencies (abseil, SPIRV-Tools, Tint, etc.).
**Android Studio:** Open the **Build Variants** panel (View > Tool Windows > Build Variants) and select `webgpuDawnDebug` for both `:MapLibreAndroid` and `:MapLibreAndroidTestApp`, then run normally.
**Terminal:**
```bash
cd platform/android
./gradlew :MapLibreAndroidTestApp:installWebgpuDawnDebug
```
## Building with wgpu-native
wgpu-native requires a pre-built static library for the target ABI. The `webgpuWgpu` flavor is currently limited to `arm64-v8a`.
### 1. Cross-compile wgpu-native for Android
Install the Rust Android target:
```bash
rustup target add aarch64-linux-android
```
Point cargo at the NDK linker. Create or edit `~/.cargo/config.toml`:
```toml
[target.aarch64-linux-android]
linker = "<NDK_PATH>/toolchains/llvm/prebuilt/<host>/bin/aarch64-linux-android26-clang"
```
Replace `<NDK_PATH>` with the path to your Android NDK and `<host>` with your platform (e.g. `darwin-x86_64` on macOS).
Then build:
```bash
cd vendor/wgpu-native
cargo build --release --target aarch64-linux-android
```
This produces `vendor/wgpu-native/target/aarch64-linux-android/release/libwgpu_native.a`, which the CMake build picks up automatically.
### 2. Build and install
**Android Studio:** Select `webgpuWgpuDebug` in the Build Variants panel and run.
**Terminal:**
```bash
cd platform/android
./gradlew :MapLibreAndroidTestApp:installWebgpuWgpuDebug
```
## Debugging wgpu-native
wgpu-native logs are routed to Android logcat under the `wgpu-native` tag (warnings and errors by default). Rust panic messages appear under `wgpu-native-stderr`. Filter with:
```bash
adb logcat -s wgpu-native:W wgpu-native-stderr:E
```
To increase verbosity, change `WGPULogLevel_Warn` to `WGPULogLevel_Info` (or `Debug` / `Trace`) in `android_webgpu_renderer_backend.cpp`.
## Notes
The native backend is in `MapLibreAndroid/src/cpp/android_webgpu_renderer_backend.cpp`. It uses `#if MLN_WEBGPU_IMPL_DAWN` / `#elif MLN_WEBGPU_IMPL_WGPU` for the API differences, same pattern as the desktop backends.
wgpu-native's adapter request forces `backendType = Vulkan` — without this it may pick GL on some emulators, which can't present to an ANativeWindow surface.