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/+/1846014 Reviewed-by: Jamie Madill <[email protected]>
kakashidinho · Oct 7, 2019 · 2682b5a · 2682b5a
1 parent 1e3f2e0
commit 2682b5a
Show file tree

Hide file tree

Showing 7 changed files with 47 additions and 42 deletions.
diff --git a/README.md b/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!
diff --git a/doc/DevSetup.md b/doc/DevSetup.md
@@ -1,36 +1,32 @@
 # 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).

diff --git a/src/libANGLE/renderer/vulkan/README.md b/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.
 

diff --git a/src/libANGLE/renderer/vulkan/doc/FastOpenGLStateTransitions.md b/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

diff --git a/src/libANGLE/renderer/vulkan/doc/FormatTablesAndEmulation.md b/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

diff --git a/src/libANGLE/renderer/vulkan/doc/OpenGLLineSegmentRasterization.md b/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
diff --git a/src/libANGLE/renderer/vulkan/doc/ShaderModuleCompilation.md b/src/libANGLE/renderer/vulkan/doc/ShaderModuleCompilation.md
@@ -8,15 +8,15 @@ 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.
 
 1. **Link-Time Translation**: During a call to `glLinkProgram` the Vulkan back-end can know 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
 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