Documentation maintenance.

README.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).
 * Watch a [short presentation](https://youtu.be/QrIKdjmpmaA) on the Vulkan back-end.
 * 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!

doc/DevSetup.md

 # 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
 
 ### 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
 On all platforms:
 
- * GN is the build system.  GYP support has been removed.
- * Clang will be set up by the build system and used by default.  See below for platform-specific compiler choices.
- * [depot_tools](http://dev.chromium.org/developers/how-tos/install-depot-tools)
-   * Required to generate projects and build files, contribute patches, run the unit tests or build the shader compiler on non-Windows systems.
+ * [depot_tools](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up)
+   * Required to download dependencies (with gclient), generate build files (with GN), and compile ANGLE (with ninja).
+   * Ensure `depot_tools` is in your path as it provides ninja for compilation.
 
 On Windows:
 
- * [Visual Studio Community 2017 Update 3.2](https://www.visualstudio.com/en-us/news/releasenotes/vs2017-relnotes)
-   * Put `is_clang = false` in your gn args to compile with the Microsoft Visual C++ compiler instead of clang.
-   * 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.
+ * ***IMPORTANT: Set `DEPOT_TOOLS_WIN_TOOLCHAIN=0` in your environment if you are not a Googler.***
+ * [Visual Studio Community 2019](https://visualstudio.microsoft.com/vs/)
  * [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.
- * [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`).
-     Use the latest versions of bison, flex and patch from the 64-bit cygwin distribution.
- * **IMPORTANT**: Non-googlers need to set `DEPOT_TOOLS_WIN_TOOLCHAIN` environment variable to 0.
+ * (optional) See the [Chromium Windows build instructions](https://chromium.googlesource.com/chromium/src/+/master/docs/windows_build_instructions.md) for more info.
 
 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.
 
 On MacOS:
@@ -58,12 +54,16 @@ After this completes successfully, you are ready to generate the ninja files:
 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")
-is_clang = false    (to use system default compiler instead of clang)
-is_debug = true     (enable debugging, true is the default)
+target_cpu = "x86"        (default is "x64")
+is_clang = false          (to use system default compiler instead of clang)
+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`.
 
 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`.
 
 Ninja can be used to compile on all platforms with one of the following commands:
 ```
-ninja -C out/Debug
-ninja -C out/Release
+autoninja -C out/Debug
+autoninja -C out/Release
 ```
 Ninja automatically calls GN to regenerate the build files on any configuration change.
+
 Ensure `depot_tools` is in your path as it provides ninja.
 
 ### Building with Visual Studio
 
 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:
  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 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
 [Checking out and building Chromium for Android](https://chromium.googlesource.com/chromium/src/+/master/docs/android_build_instructions.md).

src/libANGLE/renderer/vulkan/README.md

@@ -16,11 +16,11 @@ offer a number of significant benefits:
 
 ## Back-end Design
 
-The [RendererVk](RendererVk.cpp) is a singleton. RendererVk owns shared global resources like the
-[VkDevice][VkDevice], [VkQueue][VkQueue], the [Vulkan format tables](vk_format_utils.h) and
-[internal Vulkan shaders](shaders). The back-end creates a new [ContextVk](ContextVk.cpp) instance
-to manage each allocated OpenGL Context. ContextVk processes state changes and handles action
-commands like `glDrawArrays` and `glDrawElements`.
+The [`RendererVk`](RendererVk.cpp) class represents an `EGLDisplay`. `RendererVk` owns shared global
+resources like the [VkDevice][VkDevice], [VkQueue][VkQueue], the [Vulkan format tables](vk_format_utils.h)
+and [internal Vulkan shaders](shaders). The [ContextVk](ContextVk.cpp) class implements the back-end
+of a front-end OpenGL Context. ContextVk processes state changes and handles action commands like
+`glDrawArrays` and `glDrawElements`.
 
 Implementation details can be found in the `doc` directory.
 

src/libANGLE/renderer/vulkan/doc/FastOpenGLStateTransitions.md

@@ -13,7 +13,7 @@ cache reduces pipeline recompilation time significantly. But even cached
 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.
-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
 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

src/libANGLE/renderer/vulkan/doc/FormatTablesAndEmulation.md

@@ -18,14 +18,14 @@ is not supported.
 ## The Vulkan Format Table
 
 Overrides and fallbacks are implemented in ANGLE's [Vulkan format
-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
-[`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.
+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
+[`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.
 To update the tables please modify the format map JSON and then run
 [`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'
 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

src/libANGLE/renderer/vulkan/doc/OpenGLLineSegmentRasterization.md

@@ -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
 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
-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:
 
 ![OpenGL Diamond Rule Example][DiamondRule]
@@ -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
 `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
-[VulkanVsGLLineRaster]: img/LineRasterComparison.gif
 [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

src/libANGLE/renderer/vulkan/doc/ShaderModuleCompilation.md

@@ -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
 with some additional workarounds and emulation. We emulate OpenGL's different depth range, viewport
 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
 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
 completed shader source using ANGLE's [GlslangWrapper][GlslangWrapper.cpp] helper class. We still
 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'
 [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
 
 ![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
-[TranslatorVulkan.cpp]: https://chromium.googlesource.com/angle/angle/+/refs/heads/master/src/compiler/translator/TranslatorVulkan.cpp
 [glslang]: https://github.com/KhronosGroup/glslang
 [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
+[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