Support for WebGPU backend in Android SDK (#4097)
This commit is contained in:
@@ -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)
|
||||
|
||||
@@ -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.
|
||||
73
docs/mdbook/src/platforms/android/android-webgpu.md
Normal file
73
docs/mdbook/src/platforms/android/android-webgpu.md
Normal 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.
|
||||
Reference in New Issue
Block a user