ANGLE provides OpenGL ES 2.0 and EGL 1.4 libraries and dlls. You can use these to build and run OpenGL ES 2.0 applications on Windows, Linux, Mac and Android.
ANGLE uses git for version control. If you are not familiar with git, helpful documentation can be found at http://git-scm.com/documentation.
On all platforms:
On Windows:
is_clang = false in your gn args to compile with the Microsoft Visual C++ compiler instead of clang.glslang.l and glslang.y under src/compiler/translator, or ExpressionParser.y and Tokenizer.l in src/compiler/preprocessor). Use the latest versions of bison, flex and patch from the 64-bit cygwin distribution.DEPOT_TOOLS_WIN_TOOLCHAIN environment variable to 0.On Linux:
install-build-deps.sh later on).On MacOS:
git clone https://chromium.googlesource.com/angle/angle cd angle python scripts/bootstrap.py gclient sync git checkout master
On Linux only, you need to install all the necessary dependencies before going further by running this command:
./build/install-build-deps.sh
After this completes successfully, you are ready to generate the ninja files:
gn gen out/Debug
GN will generate ninja files by default. To change the default build options run gn args out/Debug. Some commonly used options are:
target_cpu = "x64" (or "x86") is_clang = false (to use system default compiler instead of clang) is_debug = true (enable debugging, true is the default)
For a release build run gn args out/Release and set is_debug = false.
For more information on GN run gn help.
Ninja can be used to compile on all platforms with one of the following commands:
ninja -C out/Debug ninja -C out/Release
Ninja automatically calls GN to regenerate the build files on any configuration change. Ensure depot_tools is in your path as it provides ninja.
Run scripts/msvs_projects.py to generate a Visual Studio solution in out/sln/ANGLE.sln. This script runs GN and consolidates all the targets in out into a single meta-solution.
In Visual Studio:
out/sln/ANGLE.sln.out directory will be mapped to configurations in the configuration manager. For compatibility reasons all configurations are listed as 64-bits.out/Release_x64) will contain the required libraries and dlls to build and run an OpenGL ES 2.0 application. ANGLE executables (tests and samples) are under out/sln.Building 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. Please follow the steps in Checking out and building Chromium for Android. This must be done on Linux, the only platform that Chromium for Android supports. Name your output directories out/Debug and out/Release, because Chromium GPU tests look for browser binaries in these folders. Replacing out with other names seems to be OK when working with multiple build configurations. It's best to use a build configuration of some Android bot on GPU.FYI waterfall. Look for generate_build_files step output of that bot. Remove goma_dir flag. For example, these are the build flags from Nexus 5X bot:
build_angle_deqp_tests = true dcheck_always_on = true ffmpeg_branding = "Chrome" is_component_build = false is_debug = false proprietary_codecs = true symbol_level = 1 target_cpu = "arm64" # Nexus 5X is 64 bit, remove this on 32 bit devices target_os = "android" use_goma = true # Remove this if you don't have goma
Additional flags to build the Vulkan backend, enable only if running on Android O or higher:
android32_ndk_api_level = 26 android64_ndk_api_level = 26
These ANGLE targets are supported: ninja -C out/Release translator libEGL libGLESv2 angle_unittests angle_end2end_tests angle_white_box_tests angle_deqp_gles2_tests angle_deqp_gles3_tests angle_deqp_egl_tests angle_perftests angle_white_box_perftests
In order to run ANGLE tests, prepend bin/run_ to the test name, for example: ./out/Release/bin/run_angle_unittests. Additional details are in Android Test Instructions.
dEQP Note: Running the tests not using the test runner is tricky, but is necessary in order to get a complete TestResults.qpa from the dEQP tests (since the runner shards the tests, only the results of the last shard will be available when using the test runner). First, use the runner to install the APK, test data and test expectations on the device. After the tests start running, the test runner can be stopped with Ctrl+C. Then, run
adb shell am start -a android.intent.action.MAIN -n org.chromium.native_test/.NativeUnitTestNativeActivity -e org.chromium.native_test.NativeTest.StdoutFile /sdcard/chromium_tests_root/out.txt
After the tests finish, get the results with
adb pull /sdcard/chromium_tests_root/third_party/deqp/src/data/TestResults.qpa .
In order to run GPU telemetry tests, build chrome_public_apk target. Then follow GPU Testing 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 to work with Top of Tree ANGLE in Chromium.
This sections describes how to use ANGLE to build an OpenGL ES application.
ANGLE can use a variety of backing renderers based on platform. On Windows, it defaults to D3D11 where it's available, or D3D9 otherwise. On other desktop platforms, it defaults to GL. On mobile, it defaults to GLES.
ANGLE provides an EGL extension called EGL_ANGLE_platform_angle which allows uers to select which renderer to use at EGL initialization time by calling eglGetPlatformDisplayEXT with special enums. Details of the extension can be found in it‘s specification in extensions/ANGLE_platform_angle.txt and extensions/ANGLE_platform_angle_*.txt and examples of it’s use can be seen in the ANGLE samples and tests, particularly util/EGLWindow.cpp.
To change the default D3D backend:
src/libANGLE/renderer/d3d/DisplayD3D.cppANGLE_DEFAULT_D3D11 near the head of the file, and set it to your preference.On Windows:
include folder to provide access to the standard Khronos EGL and GLES2 header files.libEGL.lib and libGLESv2.lib found in the build output directory (see Building ANGLE).libEGL.lib file and libGLESv2.lib file to Additional Dependencies, separated by a semicolon.libEGL.dll and libGLESv2.dll from the build output directory (see Building ANGLE) into your application folder.On Linux and MacOS, either:
libGLESv2 and libEGLdlopen to load the OpenGL ES and EGL entry points at runtime.In addition to OpenGL ES 2.0 and EGL 1.4 libraries, ANGLE also provides a GLSL ES to GLSL translator. This is useful for implementing OpenGL ES emulators on top of desktop OpenGL.
The translator code is included with ANGLE but fully independent; it resides in src/compiler. Follow the steps above for getting and building ANGLE to build the translator on the platform of your choice.
The basic usage is shown in essl_to_glsl sample under samples/translator. To translate a GLSL ES shader, following functions need to be called in the same order:
ShInitialize() initializes the translator library and must be called only once from each process using the translator.ShContructCompiler() creates a translator object for vertex or fragment shader.ShCompile() translates the given shader.ShDestruct() destroys the given translator.ShFinalize() shuts down the translator library and must be called only once from each process using the translator.