• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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
8ANGLE uses git for version control. Helpful documentation can be found at [http://git-scm.com/documentation](http://git-scm.com/documentation).
9
10### Required Tools
11On all platforms:
12
13 * [depot_tools](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up)
14   * Required to download dependencies (with gclient), generate build files (with GN), and compile ANGLE (with ninja).
15   * Ensure `depot_tools` is in your path as it provides ninja for compilation.
16 * For Googlers, run `download_from_google_storage --config` to login to Google Storage.
17
18On Windows:
19
20 * ***IMPORTANT: Set `DEPOT_TOOLS_WIN_TOOLCHAIN=0` in your environment if you are not a Googler.***
21 * [Visual Studio Community 2019](https://visualstudio.microsoft.com/vs/)
22 * [Windows 10 Standalone SDK version 10.0.17134 exactly](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk).
23   * You should install it through Visual Studio Installer if available.
24   * Comes with additional features that aid development, such as the Debug runtime for D3D11. Required for the D3D Compiler DLL.
25 * (optional) See the [Chromium Windows build instructions](https://chromium.googlesource.com/chromium/src/+/master/docs/windows_build_instructions.md) for more info.
26
27On Linux:
28
29 * Install package dependencies by running `install-build-deps.sh` later on.
30 * Bison and flex are not needed as we only support generating the translator grammar on Windows.
31
32On MacOS:
33
34 * [XCode](https://developer.apple.com/xcode/) for Clang and development files.
35 * Bison and flex are not needed as we only support generating the translator grammar on Windows.
36
37### Getting the source
38
39```
40git clone https://chromium.googlesource.com/angle/angle
41cd angle
42python scripts/bootstrap.py
43gclient sync
44git checkout master
45```
46
47On Linux only, you need to install all the necessary dependencies before going further by running this command:
48```
49./build/install-build-deps.sh
50```
51
52After this completes successfully, you are ready to generate the ninja files:
53```
54gn gen out/Debug
55```
56
57On Windows only, ensure you **set `DEPOT_TOOLS_WIN_TOOLCHAIN=0` in your environment** (if you are not a Googler).
58
59GN will generate ninja files. To change the default build options run `gn args out/Debug`.  Some commonly used options are:
60```
61target_cpu = "x86"        (default is "x64")
62is_clang = false          (to use system default compiler instead of clang)
63is_debug = true           (enable debugging, true is the default)
64dcheck_always_on = true   (enable release asserts and debug layers)
65```
66
67For a release build run `gn args out/Release` and set `is_debug = false`.
68
69On Windows, you can build for the Universal Windows Platform (UWP) by setting `target_os = "winuwp"` in the args.
70
71For more information on GN run `gn help`.
72
73Ninja can be used to compile on all platforms with one of the following commands:
74```
75autoninja -C out/Debug
76autoninja -C out/Release
77```
78Ninja automatically calls GN to regenerate the build files on any configuration change.
79
80Ensure `depot_tools` is in your path as it provides ninja.
81
82### Building with Visual Studio
83
84To generate the Visual Studio solution in `out/Debug/angle-debug.sln`:
85```
86gn gen out/Debug --sln=angle-debug --ide=vs2019
87```
88
89In Visual Studio:
90 1. Open the ANGLE solution file `out/Debug/angle-debug.sln`.
91 2. It is recommended you still use `autoninja` from the command line to build.
92 3. If you do want to build in the solution, "Build Solution" is not functional with GN. Build one target at a time.
93
94Once the build completes all ANGLE libraries, tests, and samples will be located in `out/Debug`.
95
96### Building ANGLE for Android
97
98See the Android specific [documentation](DevSetupAndroid.md#ANGLE-for-Android).
99
100## Application Development with ANGLE
101This sections describes how to use ANGLE to build an OpenGL ES application.
102
103### Choosing a Backend
104ANGLE can use a variety of backing renderers based on platform.  On Windows, it defaults to D3D11 where it's available,
105or D3D9 otherwise.  On other desktop platforms, it defaults to GL.  On mobile, it defaults to GLES.
106
107ANGLE 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`.
108
109To change the default D3D backend:
110
111 1. Open `src/libANGLE/renderer/d3d/DisplayD3D.cpp`
112 2. Locate the definition of `ANGLE_DEFAULT_D3D11` near the head of the file, and set it to your preference.
113
114### To Use ANGLE in Your Application
115On Windows:
116
117 1. Configure your build environment to have access to the `include` folder to provide access to the standard Khronos EGL and GLES2 header files.
118  * For Visual C++
119     * Right-click your project in the _Solution Explorer_, and select _Properties_.
120     * Under the _Configuration Properties_ branch, click _C/C++_.
121     * Add the relative path to the Khronos EGL and GLES2 header files to _Additional Include Directories_.
122 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)).
123   * For Visual C++
124     * Right-click your project in the _Solution Explorer_, and select _Properties_.
125     * Under the _Configuration Properties_ branch, open the _Linker_ branch and click _Input_.
126     * Add the relative paths to both the `libEGL.lib` file and `libGLESv2.lib` file to _Additional Dependencies_, separated by a semicolon.
127 3. Copy `libEGL.dll` and `libGLESv2.dll` from the build output directory (see [Building ANGLE](#building-with-visual-studio)) into your application folder.
128 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.
129
130On Linux and MacOS, either:
131
132 - Link you application against `libGLESv2` and `libEGL`
133 - Use `dlopen` to load the OpenGL ES and EGL entry points at runtime.
134
135## GLSL ES to GLSL Translator
136In 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.
137
138### Source and Building
139The translator code is included with ANGLE but fully independent; it resides in `src/compiler`.
140Follow the steps above for [getting and building ANGLE](#getting-the-source) to build the translator on the platform of your choice.
141
142### Usage
143The 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:
144
145 * `ShInitialize()` initializes the translator library and must be called only once from each process using the translator.
146 * `ShContructCompiler()` creates a translator object for vertex or fragment shader.
147 * `ShCompile()` translates the given shader.
148 * `ShDestruct()` destroys the given translator.
149 * `ShFinalize()` shuts down the translator library and must be called only once from each process using the translator.
150