ANGLE provides OpenGL ES 3.1 and EGL 1.5 libraries and tests. You can use these to build and run OpenGL ES applications on Windows, Linux, Mac and Android.
ANGLE uses git for version control. Helpful documentation can be found at http://git-scm.com/documentation.
Note: If you are building inside a Chromium checkout see these instructions instead.
Required on all platforms:
depot_tools is in your path as it provides ninja for compilation.download_from_google_storage --config to login to Google Storage before fetching the source.On Windows:
DEPOT_TOOLS_WIN_TOOLCHAIN=0 in your environment if you are not a Googler.Individual components tab to find the latest version.On Linux:
install-build-deps.sh below).On MacOS:
gclient sync. Obtain this authorization via cipd auth-login and following the instructions.mkdir angle cd angle fetch angle
If you're contributing code, you will also need to set up the Git commit-msg hook. See ContributingCode#getting-started-with-gerrit for instructions.
On Linux only, you need to install all the necessary dependencies before going further by running this command:
./build/install-build-deps.sh
If building for Android (which requires Linux), switch to the Android steps at this point.
After this completes successfully, you are ready to generate the ninja files:
gn gen out/Debug
If you had trouble checking out the code, please inspect the error message. As a reminder, on Windows, ensure you set DEPOT_TOOLS_WIN_TOOLCHAIN=0 in your environment if you are not a Googler. If you are a Googler, ensure you ran download_from_google_storage --config.
GN will generate ninja files. The default build options build ANGLE with clang and in release mode. Often, the default options are the desired ones, but they can be changed by running gn args out/Debug. Some options that are commonly overriden for development are:
is_component_build = true/false (false forces static links of dependencies) target_cpu = "x64"/"x86" (the default is "x64") is_debug = true/false (use false for release builds. is_debug = true is the default) angle_assert_always_on = true/false (enables release asserts and runtime debug layers) is_clang = false (NOT RECOMMENDED) (to use system default compiler instead of clang)
For a release build run gn args out/Release and set is_debug = false. Optionally set angle_assert_always_on = true for Release testing.
On Windows, you can build for the Universal Windows Platform (UWP) or WinUI 3. For UWP, set target_os = "winuwp" in the args. For WinUI 3, instead set angle_is_winappsdk=true along with the path to the Windows App SDK headers: winappsdk_dir="/path/to/headers". The headers need to be generated from the winmd files, which is done by running the scripts/winappsdk_setup.py script and passing in the path to store the headers. For both UWP and WinUI 3, setting is_component_build = false is highly recommended to support moving libEGL.dll and libGLESv2.dll to an application's directory and being self-contained, instead of depending on other DLLs (d3dcompiler_47.dll is still needed for the Direct3D backend). We also recommend using is_clang = false.
For more information on GN run gn help.
Use autoninja to compile on all platforms with one of the following commands:
autoninja -C out/Debug autoninja -C out/Release
depot_tools provides autoninja, so it should be available in your path from earlier steps. Ninja automatically calls GN to regenerate the build files on any configuration change. autoninja automatically specifies a thread count to ninja based on your system configuration.
Reclient is the recommended distributed compiler service to build ANGLE faster.
Step 1. Follow Setup remote execution to download the required configuration, and complete the authentication.
To download the required configuration:
In .gclient, add "download_remoteexec_cfg: True," in custom_vars:
solutions = [
{
# some other args
"custom_vars": {
"download_remoteexec_cfg": True,
},
},
]
Then run
gclient sync
To complete authentication:
Install gcloud SDK go/gcloud-cli#installing-and-using-the-cloud-sdk. Make sure the gcloud tool is available on your $PATH.
Log into gcloud with your @google.com account:
gcloud auth login
If asked for a project ID, enter “0”.
Step 2. Enable the usage of reclient by adding below content in GN arg:
use_remoteexec = true
To generate the Visual Studio solution in out/Debug/angle-debug.sln:
gn gen out/Debug --sln=angle-debug --ide=vs2022 --ninja-executable="C:\src\angle\third_party\ninja\ninja.exe"
In Visual Studio:
out/Debug/angle-debug.sln.autoninja from a command line to build manually.Once the build completes, all ANGLE libraries, tests, and samples will be located in out/Debug.
See the Android specific documentation.
This is currently possible only from Chromium checkout. Follow Chromium for iOS build instructions. GN args used by ANGLE for iOS builder are supported, e.g.:
dcheck_always_on = true enable_run_ios_unittests_with_xctest = true is_component_build = false is_debug = false symbol_level = 1 target_cpu = "x64" target_environment = "simulator" target_os = "ios"
Building angle_end2end_tests and angle_white_box_tests targets is supported.
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 its specification in extensions/EGL_ANGLE_platform_angle.txt and extensions/EGL_ANGLE_platform_angle_*.txt and examples of its 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.To remove any backend entirely:
gn args <path/to/build/dir>false. Options are:angle_enable_d3d9angle_enable_d3d11angle_enable_glangle_enable_metalangle_enable_nullangle_enable_vulkanangle_enable_esslangle_enable_glslOn 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 and EGL libraries, ANGLE also provides a GLSL ES translator. The translator targets various back-ends, including HLSL, GLSL for desktop and mobile, SPIR-V and Metal SL. To build the translator, build the angle_shader_translator target. Run the translator binary without arguments to see a usage message.
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 ANGLE shader_translator sample demos basic C++ API usage. To translate a GLSL ES shader, call the following functions in the same order:
sh::Initialize() initializes the translator library and must be called only once from each process using the translator.sh::ContructCompiler() creates a translator object for vertex or fragment shader.sh::Compile() translates the given shader.sh::Destruct() destroys the given translator.sh::Finalize() shuts down the translator library and must be called only once from each process using the translator.A few GN args are needed to enable OpenCL runtime code to be built in the ANGLE lib(s).
args.gn
# Global enable flag for OpenCL support angle_enable_cl = true # Enable the Vulkan backend angle_enable_vulkan = true # Enable the CL backend (i.e. passthrough) if needed angle_enable_cl_passthrough = false // or true
The two main artifacts generated here are OpenCL_ANGLE and GLESv2:
OpenCL_ANGLE : Acts as a loader for CL entrypoints from the GLESv2 library and populates it's API dispatch table with them.GLESv2 : Is the ANGLE library itself that also includes the OpenCL entrypoints/runtime when angle_enable_cl = true.Additional Vulkan-backend artifacts
clspv_core_shared : clspv as a shared library to compile OpenCL C source over a C API used by the GLESv2 library.ANGLE's OpenCL implementation acts no different from any other OpenCL ICD. Applications can either link to an existing system OpenCL-ICD-Loader, or it can link directly to the OpenCL_ANGLE via its exported OpenCL entrypoints.
If using an existing system OpenCL-ICD-Loader, then make sure OpenCL_ANGLE can be found by the OpenCL-ICD-Loader, see OpenCL-ICD-Loader for details on this.
In both cases, OpenCL_ANGLE works by using LoadLibrary/dlopen on the GLESv2 library to build the OpenCL dispatch table using the entrypoints/symbols from GLESv2 library. From then on, that API dispatch table is either given to the system ICD Loader, or if app is linked directly to the OpenCL_ANGLE lib, it just uses its singular dispatch table to forward onto GLESv2 OpenCL entrypoints.