1# Testing with ANGLE/SwiftShaderVK (SWANGLE)
2
3## About
4
5[ANGLE](https://chromium.googlesource.com/angle/angle/) is a driver that translates OpenGL ES to native 3D backends depending on the target system, such as Vulkan.
6
7SwiftShader includes ANGLE as an optional submodule, and using the [CMake build](../development/build-systems.md?cl=amaiorano%2F79#cmake-open-source), is able to install and build ANGLE, allowing us to test GL applications against ANGLE over SwiftShader Vulkan, a.k.a. _SWANGLE_.
8
9## Setup
10
11In order to build ANGLE, you will need to install [depot_tools](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up). You will also need Python 2 installed.
12
13To be useful, we will enable building the PowerVR examples along with ANGLE (this will also init the submodules if missing):
14
15```bash
16cd SwiftShader/build
17cmake -DSWIFTSHADER_GET_PVR=1 -DSWIFTSHADER_BUILD_PVR=1 -DSWIFTSHADER_BUILD_ANGLE=1 ..
18cmake --build . --target angle
19```
20
21Note that you don't have to explicitly build the `angle` target as it's part of the `ALL` target. Also note that the first time you build `angle`, it will run the `angle-setup` target, which can take some time.
22
23The `angle` target invokes Chromium-development tools, such as [gclient](https://www.chromium.org/developers/how-tos/depottools/gclient) and [ninja](https://ninja-build.org/), which are part of `depot_tools`.
24
25## Running PowerVR examples on SWANGLE
26
27Once the `angle` target is built, you can now go to the `bin-angle` directory under the CMake binary directory (e.g. `build`), set up the environment variables, and start running tests:
28
29```bash
30cd SwiftShader/build/bin-angle
31source export-swangle-env.sh
32./OpenGLESBumpmap
33```
34
35On Windows, the process is very similar:
36
37```bash
38cd SwiftShader\build\bin-angle
39export-swangle-env.bat
40.\Debug\OpenGLESBumpmap
41```
42
43If you're using Visual Studio's CMake integration, after enabling `SWIFTSHADER_BUILD_PVR` in the CMake settings, and building the `angle` target, open cmd.exe and follow similar steps:
44
45```bash
46cd SwiftShader\out\build\x64-Debug\bin-angle
47export-swangle-env.bat
48OpenGLESBumpmap
49```
50
51## Running gles-unittests on SWANGLE
52
53On Linux, we can set `LD_LIBRARY_PATH` to point at the folder containing ANGLE binaries when running `gles-unittests`:
54
55```bash
56cd SwiftShader\build
57cmake --build . --target gles-unittests
58source ./bin-angle/export-swangle-env.sh
59LD_LIBRARY_PATH=`realpath ./bin-angle` ./gles-unittests
60```
61
62On Windows, we need to copy `gles-unittests.exe` to the folder containing the ANGLE binaries, and run from there:
63
64```bash
65cd SwiftShader\build
66cmake --build . --target gles-unittests
67copy Debug\gles-unittests.exe bin-angle\
68cd bin-angle
69export-swangle-env.bat
70gles-unittests
71```
72
73## How it works
74
75The `angle-setup` target should run only once if the `.gclient` file does not exist, and the `angle` target will build if any source file under angle/src is modfied.
76
77The `angle` target builds libEGL and libGLESv2 into `${CMAKE_BINARY_DIR}/bin-angle`. If building PowerVR examples are enabled (`SWIFTSHADER_BUILD_PVR`), the PVR output folder, `${CMAKE_BINARY_DIR}/bin`,
78gets copied to `${CMAKE_BINARY_DIR}/bin-angle` first.
79
80Finally, a script named `export-swangle-env.bat/sh` also gets copied to `${CMAKE_BINARY_DIR}/bin-angle`, which sets environment variables so that the PowerVR examples will run on SWANGLE.
81