1# ANGLE for Android 2 3Building ANGLE for Android is heavily dependent on the Chromium toolchain. It is not currently possible to build ANGLE for Android without a Chromium checkout. See http://anglebug.com/2344 for more details on why. 4 5From a Linux platform (the only platform that Chromium for Android supports), follow the steps in 6[Checking out and building Chromium for Android](https://chromium.googlesource.com/chromium/src/+/master/docs/android_build_instructions.md). 7 8Name your output directories `out/Debug` and `out/Release`, because Chromium GPU tests look for browser binaries in these folders. Replacing '[Debug|Release]' with other names seems to be OK when working with multiple build configurations. 9 10 11## ANGLE GN args for Android 12The following command will open a text editor to populate GN args for a Debug build: 13``` 14gn args out/Debug 15``` 16 17Once the editor is up, paste the following GN args to generate an Android build, and save the file. 18``` 19target_os = "android" 20target_cpu = "arm64" 21android32_ndk_api_level = 26 22android64_ndk_api_level = 26 23angle_libs_suffix = "_angle" 24is_component_build = false 25``` 26 27More targeted GN arg combinations can be found [below](#android-gn-args-combinations). 28 29If you run into any problems with the above, you may be able to pull newer GN args from an official Android bot on [GPU.FYI waterfall](https://ci.chromium.org/p/chromium/g/chromium.gpu.fyi/console). 30 - Look for `generate_build_files` step output of that bot. 31 - Remove `goma_dir` flag. 32 33## Building ANGLE for Android 34Build an ANGLE target using the following command: 35 36``` 37autoninja -C out/Debug <target> 38``` 39 40The following ANGLE build targets are supported: 41 42``` 43angle 44angle_apks 45angle_deqp_gles2_tests 46angle_deqp_khr_gles2_tests 47angle_deqp_gles3_tests 48angle_deqp_khr_gles3_tests 49angle_deqp_gles31_tests 50angle_deqp_khr_gles31_tests 51angle_deqp_egl_tests 52angle_end2end_tests 53angle_perftests 54angle_unittests 55angle_white_box_perftests 56angle_white_box_tests 57``` 58ANGLE tests will be in your out/<target> directory, and can be run with various options. For instance, angle perftests can be run with: 59``` 60./out/Debug/angle_perftests --use-angle=vulkan --verbose --local-output --gtest_filter="*foo*" 61``` 62 63Additional details are in [Android Test Instructions](https://chromium.googlesource.com/chromium/src/+/master/docs/testing/android_test_instructions.md). 64 65Additional Android dEQP notes can be found in [Running dEQP on Android](dEQP.md#Running-dEQP-on-Android). 66 67If you are targeting WebGL and want to run GPU telemetry tests, build `chrome_public_apk` target. Then follow [GPU Testing](http://www.chromium.org/developers/testing/gpu-testing#TOC-Running-the-GPU-Tests-Locally) doc, using `--browser=android-chromium` argument. Make sure to set your `CHROMIUM_OUT_DIR` environment variable, so that your browser is found, otherwise the stock one will run. Also, follow [How to build ANGLE in Chromium for dev](BuildingAngleForChromiumDevelopment.md) to work with Top of Tree ANGLE in Chromium. 68 69## Using ANGLE as the Android OpenGL ES driver 70 71Starting with Android 10 (Q), ANGLE can be loaded as the OpenGL ES driver. 72 73`== Important Note ==` ANGLE built this way can only be used for *DEBUGGABLE APPS* (i.e. [marked debuggable](https://developer.android.com/guide/topics/manifest/application-element#debug) in the manifest) or users with *ROOT ACCESS* (i.e. a [userdebug](https://source.android.com/setup/build/building) build). 74 75To build the ANGLE APK, you must first bootstrap your build by following the steps [above](#ANGLE-for-Android). The steps below will result in an APK that contains the ANGLE libraries and can be installed on any Android 10+ build. 76 77Apps can be opted in to ANGLE [one at a time](#ANGLE-for-a-single-OpenGL-ES-app), in [groups](#ANGLE-for-multiple-OpenGL-ES-apps), or [globally](#ANGLE-for-all-OpenGL-ES-apps), but they must be launched by the Java runtime since the libraries are discovered within an installed package. This means ANGLE cannot be used by native executables or SurfaceFlinger at this time. 78 79## Build the ANGLE APK 80 81Using 'gn args` from above, you can build the ANGLE apk using: 82``` 83autoninja -C out/Debug angle_apks 84``` 85## Install the ANGLE APK 86``` 87adb install out/Debug/apks/AngleLibraries.apk 88``` 89You can verify installation by looking for the package name: 90``` 91$ adb shell pm path com.chromium.angle 92package:/data/app/com.chromium.angle-HpkUceNFjoLYKPbIVxFWLQ==/base.apk 93``` 94## Selecting ANGLE as the OpenGL ES driver 95 96For debuggable applications or root users, you can tell the platform to load ANGLE libraries from the installed package. 97``` 98adb shell settings put global angle_debug_package com.chromium.angle 99``` 100Remember that ANGLE can only be used by applications launched by the Java runtime. 101 102## ANGLE driver choices 103There are multiple values you can use for selecting which OpenGL ES driver is loaded by the platform. 104 105The following values are supported for `angle_gl_driver_selection_values`: 106 - `angle` : Use ANGLE. 107 - `native` : Use the native OpenGL ES driver. 108 - `default` : Use the default driver. This allows the platform to decide which driver to use. 109 110In each section below, replace `<driver>` with one of the values above. 111 112## ANGLE for a *single* OpenGL ES app 113``` 114adb shell settings put global angle_gl_driver_selection_pkgs <package name> 115adb shell settings put global angle_gl_driver_selection_values <driver> 116``` 117## ANGLE for *multiple* OpenGL ES apps 118Similar to selecting a single app, you can select multiple applications by listing their package names and driver choice in comma separated lists. Note the lists must be the same length, one driver choice per package name. 119``` 120adb shell settings put global angle_gl_driver_selection_pkgs <package name 1>,<package name 2>,<package name 3>,... 121adb shell settings put global angle_gl_driver_selection_values <driver 1>,<driver 2>,<driver 3>,... 122``` 123## ANGLE for *all* OpenGL ES apps 124Enable: 125``` 126adb shell settings put global angle_gl_driver_all_angle 1 127``` 128Disable: 129``` 130adb shell settings put global angle_gl_driver_all_angle 0 131``` 132## Check for success 133Check to see that ANGLE was loaded by your application: 134``` 135$ adb logcat -d | grep ANGLE 136V GraphicsEnvironment: ANGLE developer option for <package name>: angle 137I GraphicsEnvironment: ANGLE package enabled: com.chromium.angle 138I ANGLE : Version (2.1.0.f87fac56d22f), Renderer (Vulkan 1.1.87(Adreno (TM) 615 (0x06010501))) 139``` 140## Clean up 141Settings persist across reboots, so it is a good idea to delete them when finished. 142``` 143adb shell settings delete global angle_debug_package 144adb shell settings delete global angle_gl_driver_all_angle 145adb shell settings delete global angle_gl_driver_selection_pkgs 146adb shell settings delete global angle_gl_driver_selection_values 147``` 148## Troubleshooting 149If your application is not debuggable or you are not root, you may see an error like this in the log: 150``` 151$ adb logcat -d | grep ANGLE 152V GraphicsEnvironment: ANGLE developer option for <package name>: angle 153E GraphicsEnvironment: Invalid number of ANGLE packages. Required: 1, Found: 0 154E GraphicsEnvironment: Failed to find ANGLE package. 155``` 156Double check that you are root, or that your application is [marked debuggable](https://developer.android.com/guide/topics/manifest/application-element#debug). 157 158## Android GN args combinations 159 160The [above](#angle-gn-args-for-android) GN args only modify default values to generate a Debug build for Android. Below are some common configurations used for different scenarios. 161 162To determine what is different from default, you can point the following command at your target directory. It will show the list of gn args in use, where they came from, their current value, and their default values. 163``` 164gn args --list <dir> 165``` 166### Performance config 167This config is designed to get maximum performance by disabling debug configs and validation layers. 168Note: The oddly named `is_official_build` is a more aggressive optimization level than `Release`. Its names is historical. 169``` 170target_os = "android" 171target_cpu = "arm64" 172android32_ndk_api_level = 26 173android64_ndk_api_level = 26 174angle_libs_suffix = "_angle" 175is_component_build = false 176is_official_build = true 177is_debug = false 178``` 179### Release with asserts config 180This config is useful for quickly ensuring Vulkan is running cleanly. It disables debug, but enables asserts and allows validation errors. 181``` 182target_os = "android" 183target_cpu = "arm64" 184android32_ndk_api_level = 26 185android64_ndk_api_level = 26 186angle_libs_suffix = "_angle" 187is_component_build = false 188is_official_build = true 189is_debug = false 190dcheck_always_on = true 191``` 192