Skip to content

Latest commit

 

History

History
122 lines (86 loc) · 6.92 KB

DevSetup.md

File metadata and controls

122 lines (86 loc) · 6.92 KB

ANGLE Development

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.

Development setup

Version Control

ANGLE uses git for version control. If you are not familiar with git, helpful documentation can be found at http://git-scm.com/documentation.

Required Tools

On all platforms:

  • depot_tools
    • Required to generate projects and build files, contribute patches, run the unit tests or build the shader compiler on non-Windows systems.

On Windows:

  • Visual Studio Community 2015 Update 2 Required to build ANGLE on Windows and for the packaged Windows 8.1 SDK.
  • Cygwin's Bison, flex, and patch (optional) This is only required if you need to modify GLSL ES grammar files (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.

On Linux:

  • The GCC or Clang compilers
  • Development packages for OpenGL, X11 and libpci
  • Bison and flex are not needed as we only support generating the translator grammar on Windows.

On MacOS:

  • XCode for Clang and development files.
  • Bison and flex are not needed as we only support generating the translator grammar on Windows.

Getting the source

Set the following environment variables as needed:

On Windows:

  • GYP_GENERATORS to msvs (other options include ninja and make)
  • GYP_DEFINES to windows_sdk_path=YOUR_WIN_SDK_INSTALL_DIR if you did not install the Windows 8.1 SDK in the default location.
  • GYP_MSVS_VERSION to 2015

On Linux and MacOS:

  • GYP_GENERATORS to ninja (defaults to 'make' that pollutes your source directory)

Download the ANGLE source by running the following commands:

git clone https://chromium.googlesource.com/angle/angle
cd angle
python scripts/bootstrap.py
gclient sync
git checkout master

GYP will generate the project files, if you update ANGLE or make a change to the projects, they can be regenerated by executing gclient runhooks.

On Windows GYP will generate the main VS2015 solution file as build/ANGLE.sln. For generating a Windows Store version of ANGLE view the Windows Store instructions.

On Linux and MacOS, GYP will generate the out/Debug and out/Release directories.

Building ANGLE on Windows

  1. Open one of the ANGLE Visual Studio solution files (see Getting the source).
  2. Select Build -> Configuration Manager
  3. In the "Active solution configuration:" drop down, select the desired configuration (eg. Release), and close the Configuration Manager.
  4. Select Build -> Build Solution. Once the build completes, the output directory for your selected configuration (eg. Release_Win32, located next to the solution file) will contain the required libraries and dlls to build and run an OpenGL ES 2.0 application.

Building ANGLE on Linux and MacOS

Run ninja -C out/Debug or ninja -C out/Release. Ninja is provided by depot_tools so make sure you set up your PATH correctly. Once the build completes, the out/Debug or out/Release directories will contain the .so or .dylib libraries and test binaries.

Application Development with ANGLE

This sections describes how to use ANGLE to build an OpenGL ES application.

Choosing a D3D Backend

ANGLE can use either a backing renderer which uses D3D11 on systems where it is available, or a D3D9-only renderer.

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_d3d.txt and examples of it's use can be seen in the ANGLE samples and tests, particularly util/EGLWindow.cpp.

By default, ANGLE will use a D3D11 renderer. To change the default:

  1. Open src/libANGLE/renderer/d3d/DisplayD3D.cpp
  2. Locate the definition of ANGLE_DEFAULT_D3D11 near the head of the file, and set it to your preference.

To Use ANGLE in Your Application

On Windows:

  1. Configure your build environment to have access to the include folder to provide access to the standard Khronos EGL and GLES2 header files.
  • For Visual C++
    • Right-click your project in the Solution Explorer, and select Properties.
    • Under the Configuration Properties branch, click C/C++.
    • Add the relative path to the Khronos EGL and GLES2 header files to Additional Include Directories.
  1. Configure your build environment to have access to libEGL.lib and libGLESv2.lib found in the build output directory (see Building ANGLE).
  • For Visual C++
    • Right-click your project in the Solution Explorer, and select Properties.
    • Under the Configuration Properties branch, open the Linker branch and click Input.
    • Add the relative paths to both the libEGL.lib file and libGLESv2.lib file to Additional Dependencies, separated by a semicolon.
  1. Copy libEGL.dll and libGLESv2.dll from the build output directory (see Building ANGLE) into your application folder.
  2. Code your application to the Khronos OpenGL ES 2.0 and EGL 1.4 APIs.

On Linux and MacOS, either:

  • Link you application against libGLESv2 and libEGL
  • Use dlopen to load the OpenGL ES and EGL entry points at runtime.

GLSL ES to GLSL Translator

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.

Getting the source

The translator code is fully independent of the rest of ANGLE code and resides in src/compiler. It is cross-platform and build files for operating systems other than Windows can be generated by following the Generating project files steps above.

Usage

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.