зеркало из https://github.com/AvaloniaUI/angle.git
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 <jmadill@chromium.org>
This commit is contained in:
Jamie Madill
Родитель
1e3f2e0b78
Коммит
2682b5a02d
|
|
@ -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!
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
|||
|
||||
|
||||
|
||||
[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
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче