1# ANGLE Development 2 3ANGLE 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. 4 5## Development setup 6 7### Version Control 8 9ANGLE uses git for version control. Helpful documentation can be found at [http://git-scm.com/documentation](http://git-scm.com/documentation). 10 11### Required First Setup (do this first) 12 13Note: If you are building inside a Chromium checkout [see these instructions instead](https://chromium.googlesource.com/angle/angle/+/HEAD/doc/BuildingAngleForChromiumDevelopment.md). 14 15Required on all platforms: 16 17 * [Python 3](https://www.python.org/downloads/) must be available in your path. 18 * [depot_tools](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up) 19 * Required to download dependencies (with gclient), generate build files (with GN), and compile ANGLE (with ninja). 20 * Ensure `depot_tools` is in your path as it provides ninja for compilation. 21 * For Googlers, run `download_from_google_storage --config` to login to Google Storage before fetching the source. 22 23On Windows: 24 25 * ***IMPORTANT: Set `DEPOT_TOOLS_WIN_TOOLCHAIN=0` in your environment if you are not a Googler.*** 26 * Install [Visual Studio Community 2022](https://visualstudio.microsoft.com/vs/) 27 * Install the [Windows SDK](https://developer.microsoft.com/en-us/windows/downloads/sdk-archive/). 28 * You can install it through Visual Studio Installer if available. It might be necessary to switch to the `Individual components` tab to find the latest version. 29 * The currently supported Windows SDK version can be found in [vs_toolchain.py](https://chromium.googlesource.com/chromium/src/build/+/refs/heads/main/vs_toolchain.py). 30 * The SDK is required for GN-generated Visual Studio projects, the D3D Debug runtime, and the latest HLSL Compiler runtime. 31 * (optional) See the [Chromium Windows build instructions](https://chromium.googlesource.com/chromium/src/+/main/docs/windows_build_instructions.md) for more info. 32 33On Linux: 34 35 * Dependencies will be handled later (see `install-build-deps.sh` below). 36 37On MacOS: 38 39 * [XCode](https://developer.apple.com/xcode/) for Clang and development files. 40 * For Googlers on MacOS, you'll first need authorization to download macOS SDK's from Chromium 41 servers before running `gclient sync`. Obtain this authorization via `cipd auth-login` 42 and following the instructions. 43 44### Getting the source 45 46``` 47mkdir angle 48cd angle 49fetch angle 50``` 51 52If you're contributing code, you will also need to set up the Git `commit-msg` hook. See [ContributingCode#getting-started-with-gerrit](ContributingCode.md#getting-started-with-gerrit) for instructions. 53 54On Linux only, you need to install all the necessary dependencies before going further by running this command: 55``` 56./build/install-build-deps.sh 57``` 58 59If building for Android (which requires Linux), switch to the [Android steps](https://chromium.googlesource.com/angle/angle.git/+/HEAD/doc/DevSetupAndroid.md) at this point. 60 61After this completes successfully, you are ready to generate the ninja files: 62``` 63gn gen out/Debug 64``` 65 66If you had trouble checking out the code, please inspect the error message. As 67a reminder, on Windows, ensure you **set `DEPOT_TOOLS_WIN_TOOLCHAIN=0` in 68your environment if you are not a Googler**. If you are a Googler, ensure you 69ran `download_from_google_storage --config`. 70 71GN will generate ninja files. The default build options build ANGLE with clang 72and in release mode. Often, the default options are the desired ones, but 73they can be changed by running `gn args out/Debug`. Some options that are 74commonly overriden for development are: 75 76``` 77is_component_build = true/false (false forces static links of dependencies) 78target_cpu = "x64"/"x86" (the default is "x64") 79is_debug = true/false (use false for release builds. is_debug = true is the default) 80angle_assert_always_on = true/false (enables release asserts and runtime debug layers) 81is_clang = false (NOT RECOMMENDED) (to use system default compiler instead of clang) 82``` 83 84For a release build run `gn args out/Release` and set `is_debug = false`. 85Optionally set `angle_assert_always_on = true` for Release testing. 86 87On Windows, you can build for the Universal Windows Platform (UWP) by setting 88`target_os = "winuwp"` in the args. Setting `is_component_build = false` is 89highly recommended to support moving libEGL.dll and libGLESv2.dll to an 90application's directory and being self-contained, instead of depending on 91other DLLs (d3dcompiler_47.dll is still needed for the Direct3D backend). We 92also recommend using `is_clang = false` with UWP. 93 94For more information on GN run `gn help`. 95 96Use `autoninja` to compile on all platforms with one of the following commands: 97 98``` 99autoninja -C out/Debug 100autoninja -C out/Release 101``` 102 103`depot_tools` provides `autoninja`, so it should be available in your path 104from earlier steps. Ninja automatically calls GN to regenerate the build 105files on any configuration change. `autoninja` automatically specifies a 106thread count to `ninja` based on your system configuration. 107 108### Building with Goma (Google employees only) 109 110In addition, we highly recommend Google employees use goma, a distributed 111compilation system. Detailed information is available internally. To enable 112Goma set the GN arg: 113 114``` 115use_goma = true 116``` 117 118### Building and Debugging with Visual Studio 119 120To generate the Visual Studio solution in `out/Debug/angle-debug.sln`: 121 122``` 123gn gen out/Debug --sln=angle-debug --ide=vs2022 --ninja-executable="C:\src\angle\third_party\ninja\ninja.exe" 124``` 125 126In Visual Studio: 127 1. Open the ANGLE solution file `out/Debug/angle-debug.sln`. 128 2. We recommended you use `autoninja` from a command line to build manually. 129 3. "Build Solution" from the IDE is broken with GN. You can use the IDE to build one target or one file at a time. 130 131Once the build completes, all ANGLE libraries, tests, and samples will be located in `out/Debug`. 132 133### Building ANGLE for Android 134 135See the Android specific [documentation](DevSetupAndroid.md#ANGLE-for-Android). 136 137## Application Development with ANGLE 138 139This sections describes how to use ANGLE to build an OpenGL ES application. 140 141### Choosing a Backend 142 143ANGLE can use a variety of backing renderers based on platform. On Windows, it defaults to D3D11 where it's available, 144or D3D9 otherwise. On other desktop platforms, it defaults to GL. On mobile, it defaults to GLES. 145 146ANGLE provides an EGL extension called `EGL_ANGLE_platform_angle` which allows uers to select 147which renderer to use at EGL initialization time by calling eglGetPlatformDisplayEXT with special 148enums. Details of the extension can be found in its specification in 149`extensions/EGL_ANGLE_platform_angle.txt` and `extensions/EGL_ANGLE_platform_angle_*.txt` and 150examples of its use can be seen in the ANGLE samples and tests, particularly `util/EGLWindow.cpp`. 151 152To change the default D3D backend: 153 154 1. Open `src/libANGLE/renderer/d3d/DisplayD3D.cpp` 155 2. Locate the definition of `ANGLE_DEFAULT_D3D11` near the head of the file, and set it to your preference. 156 157To remove any backend entirely: 158 159 1. Run `gn args <path/to/build/dir>` 160 2. Set the appropriate variable to `false`. Options are: 161 - `angle_enable_d3d9` 162 - `angle_enable_d3d11` 163 - `angle_enable_gl` 164 - `angle_enable_metal` 165 - `angle_enable_null` 166 - `angle_enable_vulkan` 167 - `angle_enable_essl` 168 - `angle_enable_glsl` 169 170### To Use ANGLE in Your Application 171On Windows: 172 173 1. Configure your build environment to have access to the `include` folder to provide access to the standard Khronos EGL and GLES2 header files. 174 * For Visual C++ 175 * Right-click your project in the _Solution Explorer_, and select _Properties_. 176 * Under the _Configuration Properties_ branch, click _C/C++_. 177 * Add the relative path to the Khronos EGL and GLES2 header files to _Additional Include Directories_. 178 2. Configure your build environment to have access to `libEGL.lib` and `libGLESv2.lib` found in the build output directory (see [Building ANGLE](#building-with-visual-studio)). 179 * For Visual C++ 180 * Right-click your project in the _Solution Explorer_, and select _Properties_. 181 * Under the _Configuration Properties_ branch, open the _Linker_ branch and click _Input_. 182 * Add the relative paths to both the `libEGL.lib` file and `libGLESv2.lib` file to _Additional Dependencies_, separated by a semicolon. 183 3. Copy `libEGL.dll` and `libGLESv2.dll` from the build output directory (see [Building ANGLE](#building-with-visual-studio)) into your application folder. 184 4. Code your application to the Khronos [OpenGL ES 2.0](http://www.khronos.org/registry/gles/) and [EGL 1.4](http://www.khronos.org/registry/egl/) APIs. 185 186On Linux and MacOS, either: 187 188 - Link you application against `libGLESv2` and `libEGL` 189 - Use `dlopen` to load the OpenGL ES and EGL entry points at runtime. 190 191## GLSL ES Translator 192 193In addition to OpenGL ES and EGL libraries, ANGLE also provides a GLSL ES 194translator. The translator targets various back-ends, including HLSL, GLSL 195for desktop and mobile, SPIR-V and Metal SL. To build the translator, build 196the `angle_shader_translator` target. Run the translator binary without 197arguments to see a usage message. 198 199### Source and Building 200 201The translator code is included with ANGLE but fully independent; it resides 202in [`src/compiler`](../src/compiler). Follow the steps above for 203[getting and building ANGLE](#getting-the-source) to build the translator on 204the platform of your choice. 205 206### Usage 207 208The ANGLE [`shader_translator`](../samples/shader_translator/shader_translator.cpp) 209sample demos basic C++ API usage. To translate a GLSL ES shader, call the following 210functions in the same order: 211 212 * `sh::Initialize()` initializes the translator library and must be called only once from each process using the translator. 213 * `sh::ContructCompiler()` creates a translator object for vertex or fragment shader. 214 * `sh::Compile()` translates the given shader. 215 * `sh::Destruct()` destroys the given translator. 216 * `sh::Finalize()` shuts down the translator library and must be called only once from each process using the translator. 217