From bd2fcc7824764762a622c157975f9474ac12d8bf Mon Sep 17 00:00:00 2001 From: William Candillon Date: Fri, 5 Jun 2026 21:21:08 +0200 Subject: [PATCH 1/2] :wrench: --- README.md | 16 ++++++++++++++++ packages/webgpu/README.md | 16 ++++++++++++++++ packages/webgpu/src/hooks.tsx | 2 +- 3 files changed, 33 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index e01550476..2450221ec 100644 --- a/README.md +++ b/README.md @@ -346,6 +346,22 @@ In "Edit Scheme," uncheck "Metal Validation". Learn more [here](https://develope Uncheck 'Metal Validation' +### Android Emulators + +By default, Android emulators expose Vulkan through SwiftShader, a software (CPU) renderer. React Native WebGPU runs on it, but rendering is slow and some features are unavailable. When the adapter is software, you will see a "GPUAdapter is not hardware accelerated" warning in the console. + +On Apple Silicon, you can instead get a hardware accelerated adapter that runs on the host GPU through MoltenVK (Vulkan on top of Metal): + +1. Use a system image at API level 35 or lower. The API 36 image forces software rendering: it reports "system image does not support guest rendering" and falls back to `swiftshader_indirect`. +2. Enable hardware graphics on the AVD. In Android Studio's Device Manager set "Graphics acceleration" to "Hardware", or set `hw.gpu.enabled=yes` and `hw.gpu.mode=host` in the AVD `config.ini`. +3. Launch the emulator with the host GPU and the MoltenVK ICD: + +```sh +ANDROID_EMU_VK_ICD=moltenvk emulator -avd -gpu host +``` + +When this works, the emulator log reports the host GPU instead of SwiftShader (for example `Selecting Vulkan device: Apple M... , MoltenVK is supported, enabling Vulkan portability`) and the warning above no longer appears. + ## Library Development Make sure to check out the submodules: diff --git a/packages/webgpu/README.md b/packages/webgpu/README.md index e01550476..2450221ec 100644 --- a/packages/webgpu/README.md +++ b/packages/webgpu/README.md @@ -346,6 +346,22 @@ In "Edit Scheme," uncheck "Metal Validation". Learn more [here](https://develope Uncheck 'Metal Validation' +### Android Emulators + +By default, Android emulators expose Vulkan through SwiftShader, a software (CPU) renderer. React Native WebGPU runs on it, but rendering is slow and some features are unavailable. When the adapter is software, you will see a "GPUAdapter is not hardware accelerated" warning in the console. + +On Apple Silicon, you can instead get a hardware accelerated adapter that runs on the host GPU through MoltenVK (Vulkan on top of Metal): + +1. Use a system image at API level 35 or lower. The API 36 image forces software rendering: it reports "system image does not support guest rendering" and falls back to `swiftshader_indirect`. +2. Enable hardware graphics on the AVD. In Android Studio's Device Manager set "Graphics acceleration" to "Hardware", or set `hw.gpu.enabled=yes` and `hw.gpu.mode=host` in the AVD `config.ini`. +3. Launch the emulator with the host GPU and the MoltenVK ICD: + +```sh +ANDROID_EMU_VK_ICD=moltenvk emulator -avd -gpu host +``` + +When this works, the emulator log reports the host GPU instead of SwiftShader (for example `Selecting Vulkan device: Apple M... , MoltenVK is supported, enabling Vulkan portability`) and the warning above no longer appears. + ## Library Development Make sure to check out the submodules: diff --git a/packages/webgpu/src/hooks.tsx b/packages/webgpu/src/hooks.tsx index ba33cc879..75b8b7037 100644 --- a/packages/webgpu/src/hooks.tsx +++ b/packages/webgpu/src/hooks.tsx @@ -15,7 +15,7 @@ export const warnIfNotHardwareAccelerated = (adapter: GPUAdapter) => { // Note: isFallbackAdapter was moved from GPUAdapter to GPUAdapterInfo in Chrome 140 if (adapter.info && adapter.info.isFallbackAdapter) { console.warn( - "GPUAdapter is not hardware accelerated. This is common on Android emulators. Rendering will be slow. Some features may be unavailable.", + "GPUAdapter is not hardware accelerated. This is common on Android emulators, which default to the SwiftShader software renderer. Rendering will be slow and some features may be unavailable. On Apple Silicon you can run the emulator on the host GPU via MoltenVK: use a system image at API level 35 or lower and launch it with `ANDROID_EMU_VK_ICD=moltenvk emulator -avd -gpu host`. See the \"Android Emulators\" section of the React Native WebGPU README for details.", ); } }; From cb570be6495913aed21b4f770f1a0befd5c096c3 Mon Sep 17 00:00:00 2001 From: William Candillon Date: Fri, 5 Jun 2026 21:27:49 +0200 Subject: [PATCH 2/2] :wrench: --- README.md | 2 ++ packages/webgpu/README.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/README.md b/README.md index 2450221ec..4bd5c0a15 100644 --- a/README.md +++ b/README.md @@ -362,6 +362,8 @@ ANDROID_EMU_VK_ICD=moltenvk emulator -avd -gpu host When this works, the emulator log reports the host GPU instead of SwiftShader (for example `Selecting Vulkan device: Apple M... , MoltenVK is supported, enabling Vulkan portability`) and the warning above no longer appears. +Note that even with MoltenVK, the emulator runs Vulkan through a translation stack: the guest driver forwards calls to MoltenVK, which maps Vulkan onto Metal. This is convenient for development, but it is not a faithful reference implementation. Some examples render differently, and some features are missing or behave differently than on a physical device. Always validate on a real Android device before relying on a given behavior. + ## Library Development Make sure to check out the submodules: diff --git a/packages/webgpu/README.md b/packages/webgpu/README.md index 2450221ec..4bd5c0a15 100644 --- a/packages/webgpu/README.md +++ b/packages/webgpu/README.md @@ -362,6 +362,8 @@ ANDROID_EMU_VK_ICD=moltenvk emulator -avd -gpu host When this works, the emulator log reports the host GPU instead of SwiftShader (for example `Selecting Vulkan device: Apple M... , MoltenVK is supported, enabling Vulkan portability`) and the warning above no longer appears. +Note that even with MoltenVK, the emulator runs Vulkan through a translation stack: the guest driver forwards calls to MoltenVK, which maps Vulkan onto Metal. This is convenient for development, but it is not a faithful reference implementation. Some examples render differently, and some features are missing or behave differently than on a physical device. Always validate on a real Android device before relying on a given behavior. + ## Library Development Make sure to check out the submodules: