Commit 2682b5a0 by Jamie Madill

Documentation maintenance.

Fixes links in the Vulkan back-end doc. Also includes a link to the Vulkan back-end docs on the main page. Also updates the building code section to mention VS2019 and make the win toolchain varable set more prominent. Bug: angleproject:1944 Change-Id: I8e8f0775daa3643afaa1ddd44429fa7d8e77b19b Reviewed-on: https://chromium-review.googlesource.com/c/angle/angle/+/1846014Reviewed-by: 's avatarJamie Madill <jmadill@chromium.org>
parent 1e3f2e0b
...@@ -77,4 +77,5 @@ View the [Dev setup instructions](doc/DevSetup.md). ...@@ -77,4 +77,5 @@ View the [Dev setup instructions](doc/DevSetup.md).
* Learn about the past, present, and future of the ANGLE implementation in [this presentation](https://docs.google.com/presentation/d/1CucIsdGVDmdTWRUbg68IxLE5jXwCb2y1E9YVhQo0thg/pub?start=false&loop=false). * Learn about the past, present, and future of the ANGLE implementation in [this presentation](https://docs.google.com/presentation/d/1CucIsdGVDmdTWRUbg68IxLE5jXwCb2y1E9YVhQo0thg/pub?start=false&loop=false).
* Watch a [short presentation](https://youtu.be/QrIKdjmpmaA) on the Vulkan back-end. * Watch a [short presentation](https://youtu.be/QrIKdjmpmaA) on the Vulkan back-end.
* Track the [dEQP test conformance](doc/dEQP-Charts.md) * Track the [dEQP test conformance](doc/dEQP-Charts.md)
* Read design docs on the [Vulkan back-end](src/libANGLE/renderer/vulkan/README.md)
* If you use ANGLE in your own project, we'd love to hear about it! * If you use ANGLE in your own project, we'd love to hear about it!
# ANGLE Development # 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, Linux, Mac and Android. 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.
## Development setup ## Development setup
### Version Control ### 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](http://git-scm.com/documentation). ANGLE uses git for version control. Helpful documentation can be found at [http://git-scm.com/documentation](http://git-scm.com/documentation).
### Required Tools ### Required Tools
On all platforms: On all platforms:
* GN is the build system. GYP support has been removed. * [depot_tools](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up)
* Clang will be set up by the build system and used by default. See below for platform-specific compiler choices. * Required to download dependencies (with gclient), generate build files (with GN), and compile ANGLE (with ninja).
* [depot_tools](http://dev.chromium.org/developers/how-tos/install-depot-tools) * Ensure `depot_tools` is in your path as it provides ninja for compilation.
* Required to generate projects and build files, contribute patches, run the unit tests or build the shader compiler on non-Windows systems.
On Windows: On Windows:
* [Visual Studio Community 2017 Update 3.2](https://www.visualstudio.com/en-us/news/releasenotes/vs2017-relnotes) * ***IMPORTANT: Set `DEPOT_TOOLS_WIN_TOOLCHAIN=0` in your environment if you are not a Googler.***
* Put `is_clang = false` in your gn args to compile with the Microsoft Visual C++ compiler instead of clang. * [Visual Studio Community 2019](https://visualstudio.microsoft.com/vs/)
* See the [Chromium Windows build instructions](https://chromium.googlesource.com/chromium/src/+/master/docs/windows_build_instructions.md) for more info.
* Required for the packaged Windows 10 SDK.
* [Windows 10 Standalone SDK version 10.0.17134 exactly](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk). * [Windows 10 Standalone SDK version 10.0.17134 exactly](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk).
* Comes with additional features that aid development, such as the Debug runtime for D3D11. Required for the D3D Compiler DLL. * Comes with additional features that aid development, such as the Debug runtime for D3D11. Required for the D3D Compiler DLL.
* [Cygwin's Bison, flex, and patch](https://cygwin.com/setup-x86_64.exe) (optional) * (optional) [Cygwin's Bison, flex, and patch](https://cygwin.com/setup-x86_64.exe)
* 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`). * 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. * (optional) See the [Chromium Windows build instructions](https://chromium.googlesource.com/chromium/src/+/master/docs/windows_build_instructions.md) for more info.
* **IMPORTANT**: Non-googlers need to set `DEPOT_TOOLS_WIN_TOOLCHAIN` environment variable to 0.
On Linux: On Linux:
* Development packages for OpenGL, X11 and libpci (all of these dependencies should be installed automatically when running `install-build-deps.sh` later on). * Install package dependencies by running `install-build-deps.sh` later on.
* Bison and flex are not needed as we only support generating the translator grammar on Windows. * Bison and flex are not needed as we only support generating the translator grammar on Windows.
On MacOS: On MacOS:
...@@ -58,12 +54,16 @@ After this completes successfully, you are ready to generate the ninja files: ...@@ -58,12 +54,16 @@ After this completes successfully, you are ready to generate the ninja files:
gn gen out/Debug gn gen out/Debug
``` ```
GN will generate ninja files by default. To change the default build options run `gn args out/Debug`. Some commonly used options are: On Windows only, ensure you **set `DEPOT_TOOLS_WIN_TOOLCHAIN=0` in your environment** (if you are not a Googler).
GN will generate ninja files. To change the default build options run `gn args out/Debug`. Some commonly used options are:
``` ```
target_cpu = "x64" (or "x86") target_cpu = "x86" (default is "x64")
is_clang = false (to use system default compiler instead of clang) is_clang = false (to use system default compiler instead of clang)
is_debug = true (enable debugging, true is the default) is_debug = true (enable debugging, true is the default)
dcheck_always_on = true (enable release asserts and debug layers)
``` ```
For a release build run `gn args out/Release` and set `is_debug = false`. For a release build run `gn args out/Release` and set `is_debug = false`.
On Windows, you can build for the Universal Windows Platform (UWP) by setting `target_os = "winuwp"` in the args. On Windows, you can build for the Universal Windows Platform (UWP) by setting `target_os = "winuwp"` in the args.
...@@ -72,26 +72,29 @@ For more information on GN run `gn help`. ...@@ -72,26 +72,29 @@ For more information on GN run `gn help`.
Ninja can be used to compile on all platforms with one of the following commands: Ninja can be used to compile on all platforms with one of the following commands:
``` ```
ninja -C out/Debug autoninja -C out/Debug
ninja -C out/Release autoninja -C out/Release
``` ```
Ninja automatically calls GN to regenerate the build files on any configuration change. Ninja automatically calls GN to regenerate the build files on any configuration change.
Ensure `depot_tools` is in your path as it provides ninja. Ensure `depot_tools` is in your path as it provides ninja.
### Building with Visual Studio ### Building with Visual Studio
To generate the Visual Studio solution in `out/Debug/angle-debug.sln`: To generate the Visual Studio solution in `out/Debug/angle-debug.sln`:
``` ```
gn gen out/Debug --sln=angle-debug --ide=vs<2017/2019> gn gen out/Debug --sln=angle-debug --ide=vs2019
``` ```
In Visual Studio: In Visual Studio:
1. Open the ANGLE solution file `out/Debug/angle-debug.sln`. 1. Open the ANGLE solution file `out/Debug/angle-debug.sln`.
2. Right click the "all" solution and select build. "Build Solution" is not functional with GN; instead build one target at a time." 2. It is recommended you still use `autoninja` from the command line to build.
3. If you do want to build in the solution, "Build Solution" is not functional with GN. Build one target at a time.
Once the build completes all ANGLE libraries, tests, and samples will be located in out/Debug. Once the build completes all ANGLE libraries, tests, and samples will be located in `out/Debug`.
### Building ANGLE for Android ### Building ANGLE for Android
Building ANGLE for Android is heavily dependent on the Chromium toolchain. It is not currently possible to build ANGLE for Android without a Chromium checkout. See http://anglebug.com/2344 for more details on why. Building ANGLE for Android is heavily dependent on the Chromium toolchain. It is not currently possible to build ANGLE for Android without a Chromium checkout. See http://anglebug.com/2344 for more details on why.
Please follow the steps in Please follow the steps in
[Checking out and building Chromium for Android](https://chromium.googlesource.com/chromium/src/+/master/docs/android_build_instructions.md). [Checking out and building Chromium for Android](https://chromium.googlesource.com/chromium/src/+/master/docs/android_build_instructions.md).
......
...@@ -16,11 +16,11 @@ offer a number of significant benefits: ...@@ -16,11 +16,11 @@ offer a number of significant benefits:
## Back-end Design ## Back-end Design
The [RendererVk](RendererVk.cpp) is a singleton. RendererVk owns shared global resources like the The [`RendererVk`](RendererVk.cpp) class represents an `EGLDisplay`. `RendererVk` owns shared global
[VkDevice][VkDevice], [VkQueue][VkQueue], the [Vulkan format tables](vk_format_utils.h) and resources like the [VkDevice][VkDevice], [VkQueue][VkQueue], the [Vulkan format tables](vk_format_utils.h)
[internal Vulkan shaders](shaders). The back-end creates a new [ContextVk](ContextVk.cpp) instance and [internal Vulkan shaders](shaders). The [ContextVk](ContextVk.cpp) class implements the back-end
to manage each allocated OpenGL Context. ContextVk processes state changes and handles action of a front-end OpenGL Context. ContextVk processes state changes and handles action commands like
commands like `glDrawArrays` and `glDrawElements`. `glDrawArrays` and `glDrawElements`.
Implementation details can be found in the `doc` directory. Implementation details can be found in the `doc` directory.
......
...@@ -13,7 +13,7 @@ cache reduces pipeline recompilation time significantly. But even cached ...@@ -13,7 +13,7 @@ cache reduces pipeline recompilation time significantly. But even cached
pipeline recompilations are orders of manitude slower than OpenGL state changes. pipeline recompilations are orders of manitude slower than OpenGL state changes.
The second level cache is an ANGLE-owned hash map from OpenGL state vectors to compiled pipelines. The second level cache is an ANGLE-owned hash map from OpenGL state vectors to compiled pipelines.
See [GraphicsPipelineCache][GraphicsPipelineCache] in [vk_cache_utils.h](vk_cache_utils.h). ANGLE's See [GraphicsPipelineCache][GraphicsPipelineCache] in [vk_cache_utils.h](../vk_cache_utils.h). ANGLE's
[GraphicsPipelineDesc][GraphicsPipelineDesc] class is a tightly packed 256-byte description of the [GraphicsPipelineDesc][GraphicsPipelineDesc] class is a tightly packed 256-byte description of the
current OpenGL rendering state. We also use a [xxHash](https://github.com/Cyan4973/xxHash) for the current OpenGL rendering state. We also use a [xxHash](https://github.com/Cyan4973/xxHash) for the
fastest possible hash computation. The hash map speeds up state changes considerably. But it is fastest possible hash computation. The hash map speeds up state changes considerably. But it is
......
...@@ -18,14 +18,14 @@ is not supported. ...@@ -18,14 +18,14 @@ is not supported.
## The Vulkan Format Table ## The Vulkan Format Table
Overrides and fallbacks are implemented in ANGLE's [Vulkan format Overrides and fallbacks are implemented in ANGLE's [Vulkan format
table][vk_format_table_autogen.cpp]. The table is auto-generated by table][../vk_format_table_autogen.cpp]. The table is auto-generated by
[`gen_vk_format_table.py`](gen_vk_format_table.py). We store the mapping from [`gen_vk_format_table.py`](../gen_vk_format_table.py). We store the mapping from
[`angle::Format::ID`](../FormatID_autogen.h) to [VkFormat][VkFormat] in [`angle::Format::ID`](../../FormatID_autogen.h) to [VkFormat][VkFormat] in
[`vk_format_map.json`](vk_format_map.json). The format map also lists the overrides and fallbacks. [`vk_format_map.json`](../vk_format_map.json). The format map also lists the overrides and fallbacks.
To update the tables please modify the format map JSON and then run To update the tables please modify the format map JSON and then run
[`scripts/run_code_generation.py`][RunCodeGeneration]. [`scripts/run_code_generation.py`][RunCodeGeneration].
The [`vk::Format`](vk_format_utils.h) class describes the information ANGLE needs for a particular The [`vk::Format`](../vk_format_utils.h) class describes the information ANGLE needs for a particular
`VkFormat`. The 'ANGLE' format ID is a reference to the front-end format. The 'Image' or 'Buffer' `VkFormat`. The 'ANGLE' format ID is a reference to the front-end format. The 'Image' or 'Buffer'
format are the native Vulkan formats that implement a particular front-end format for `VkImages` and format are the native Vulkan formats that implement a particular front-end format for `VkImages` and
`VkBuffers`. For the above example of `R8_UNORM` overriding `L8_UNORM`, `L8_UNORM` is the ANGLE `VkBuffers`. For the above example of `R8_UNORM` overriding `L8_UNORM`, `L8_UNORM` is the ANGLE
......
...@@ -18,7 +18,7 @@ The OpenGL spec defines a "diamond-exit" rule to select fragments on a line. Ple ...@@ -18,7 +18,7 @@ The OpenGL spec defines a "diamond-exit" rule to select fragments on a line. Ple
spec section 3.4.1 "Basic Line Segment Rasterization" spec for more details. To implement this rule spec section 3.4.1 "Basic Line Segment Rasterization" spec for more details. To implement this rule
we inject a small computation to test if a pixel falls within the diamond in the start of the pixel we inject a small computation to test if a pixel falls within the diamond in the start of the pixel
shader. If the pixel fails the diamond test we discard the fragment. Note that we only perform this shader. If the pixel fails the diamond test we discard the fragment. Note that we only perform this
test when drawing lines. See the section on [Shader Compilation](#shader-module-compilation) for test when drawing lines. See the section on [Shader Compilation](ShaderModuleCompilation.md) for
more info. See the below diagram for an illustration of the diamond rule: more info. See the below diagram for an illustration of the diamond rule:
![OpenGL Diamond Rule Example][DiamondRule] ![OpenGL Diamond Rule Example][DiamondRule]
...@@ -46,7 +46,8 @@ to correct for cases when the line segment is perfectly parallel or perpendicula ...@@ -46,7 +46,8 @@ to correct for cases when the line segment is perfectly parallel or perpendicula
code please see [TranslatorVulkan.cpp][TranslatorVulkan.cpp] under code please see [TranslatorVulkan.cpp][TranslatorVulkan.cpp] under
`AddLineSegmentRasterizationEmulation`. `AddLineSegmentRasterizationEmulation`.
[VulkanLineRaster]: https://www.khronos.org/registry/vulkan/specs/1.1/html/chap24.html#primsrast-lines-basic
[Bresenham]: https://en.wikipedia.org/wiki/Bresenham%27s_line_algorithm [Bresenham]: https://en.wikipedia.org/wiki/Bresenham%27s_line_algorithm
[VulkanVsGLLineRaster]: img/LineRasterComparison.gif
[DiamondRule]: img/LineRasterPixelExample.png [DiamondRule]: img/LineRasterPixelExample.png
[TranslatorVulkan.cpp]: https://chromium.googlesource.com/angle/angle/+/refs/heads/master/src/compiler/translator/TranslatorVulkan.cpp
[VulkanLineRaster]: https://www.khronos.org/registry/vulkan/specs/1.1/html/chap24.html#primsrast-lines-basic
[VulkanVsGLLineRaster]: img/LineRasterComparison.gif
...@@ -8,7 +8,7 @@ shader translator][translator]. The translator compiles application shaders into ...@@ -8,7 +8,7 @@ shader translator][translator]. The translator compiles application shaders into
GLSL. Vulkan-compatible GLSL matches the [GL_KHR_vulkan_glsl][GL_KHR_vulkan_glsl] extension spec GLSL. Vulkan-compatible GLSL matches the [GL_KHR_vulkan_glsl][GL_KHR_vulkan_glsl] extension spec
with some additional workarounds and emulation. We emulate OpenGL's different depth range, viewport with some additional workarounds and emulation. We emulate OpenGL's different depth range, viewport
y flipping, default uniforms, and OpenGL [line segment y flipping, default uniforms, and OpenGL [line segment
rasterization](#opengl-line-segment-rasterization). For more info see rasterization](OpenGLLineSegmentRasterization.md). For more info see
[TranslatorVulkan.cpp][TranslatorVulkan.cpp]. After initial compilation the shaders are not [TranslatorVulkan.cpp][TranslatorVulkan.cpp]. After initial compilation the shaders are not
complete. They are templated with markers that are filled in later at link time. complete. They are templated with markers that are filled in later at link time.
...@@ -16,7 +16,7 @@ complete. They are templated with markers that are filled in later at link time. ...@@ -16,7 +16,7 @@ complete. They are templated with markers that are filled in later at link time.
necessary locations and properties to write to connect the shader stage interfaces. We get the necessary locations and properties to write to connect the shader stage interfaces. We get the
completed shader source using ANGLE's [GlslangWrapper][GlslangWrapper.cpp] helper class. We still completed shader source using ANGLE's [GlslangWrapper][GlslangWrapper.cpp] helper class. We still
cannot generate `VkShaderModules` since some ANGLE features like [OpenGL line cannot generate `VkShaderModules` since some ANGLE features like [OpenGL line
rasterization](#opengl-line-segment-rasterization) emulation depend on draw-time information. rasterization](OpenGLLineSegmentRasterization.md) emulation depend on draw-time information.
1. **Draw-time SPIR-V Generation**: Once the application records a draw call we use Khronos' 1. **Draw-time SPIR-V Generation**: Once the application records a draw call we use Khronos'
[glslang][glslang] to convert the Vulkan-compatible GLSL into SPIR-V with the correct draw-time [glslang][glslang] to convert the Vulkan-compatible GLSL into SPIR-V with the correct draw-time
...@@ -74,10 +74,10 @@ Note right of "Vulkan Back-end": We init VkShaderModules\nand VkPipeline then\nr ...@@ -74,10 +74,10 @@ Note right of "Vulkan Back-end": We init VkShaderModules\nand VkPipeline then\nr
![Vulkan Shader Translation Flow](https://raw.githubusercontent.com/google/angle/master/src/libANGLE/renderer/vulkan/doc/img/VulkanShaderTranslation.svg?sanitize=true) ![Vulkan Shader Translation Flow](https://raw.githubusercontent.com/google/angle/master/src/libANGLE/renderer/vulkan/doc/img/VulkanShaderTranslation.svg?sanitize=true)
[VkShaderModule]: https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkShaderModule.html
[translator]: https://chromium.googlesource.com/angle/angle/+/refs/heads/master/src/compiler/translator/
[GL_KHR_vulkan_glsl]: https://github.com/KhronosGroup/GLSL/blob/master/extensions/khr/GL_KHR_vulkan_glsl.txt [GL_KHR_vulkan_glsl]: https://github.com/KhronosGroup/GLSL/blob/master/extensions/khr/GL_KHR_vulkan_glsl.txt
[TranslatorVulkan.cpp]: https://chromium.googlesource.com/angle/angle/+/refs/heads/master/src/compiler/translator/TranslatorVulkan.cpp
[glslang]: https://github.com/KhronosGroup/glslang [glslang]: https://github.com/KhronosGroup/glslang
[GlslangWrapper.cpp]: https://chromium.googlesource.com/angle/angle/+/refs/heads/master/src/libANGLE/renderer/vulkan/GlslangWrapper.cpp [GlslangWrapper.cpp]: https://chromium.googlesource.com/angle/angle/+/refs/heads/master/src/libANGLE/renderer/vulkan/GlslangWrapper.cpp
[SPIRV-Tools]: https://github.com/KhronosGroup/SPIRV-Tools [SPIRV-Tools]: https://github.com/KhronosGroup/SPIRV-Tools
[translator]: https://chromium.googlesource.com/angle/angle/+/refs/heads/master/src/compiler/translator/
[TranslatorVulkan.cpp]: https://chromium.googlesource.com/angle/angle/+/refs/heads/master/src/compiler/translator/TranslatorVulkan.cpp
[VkShaderModule]: https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkShaderModule.html
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment