• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# ANGLE: Vulkan Back-end
2
3ANGLE's Vulkan back-end implementation lives in this folder.
4
5[Vulkan](https://www.khronos.org/vulkan/) is an explicit graphics API. It has a lot in common with
6other explicit APIs such as Microsoft's [D3D12][D3D12 Guide] and Apple's
7[Metal](https://developer.apple.com/metal/). Compared to APIs like OpenGL or D3D11 explicit APIs can
8offer a number of significant benefits:
9
10 * Lower API call CPU overhead.
11 * A smaller API surface with more direct hardware control.
12 * Better support for multi-core programming.
13 * Vulkan in particular has open-source tooling and tests.
14
15[D3D12 Guide]: https://docs.microsoft.com/en-us/windows/desktop/direct3d12/directx-12-programming-guide
16
17## Back-end Design
18
19The [`RendererVk`](RendererVk.cpp) class represents an `EGLDisplay`. `RendererVk` owns shared global
20resources like the [VkDevice][VkDevice], [VkQueue][VkQueue], the [Vulkan format tables](vk_format_utils.h)
21and [internal Vulkan shaders](shaders). The [ContextVk](ContextVk.cpp) class implements the back-end
22of a front-end OpenGL Context. ContextVk processes state changes and handles action commands like
23`glDrawArrays` and `glDrawElements`.
24
25## Command recording
26
27The back-end records commands into command buffers via the following `ContextVk` APIs:
28
29 * `beginNewRenderPass`: Writes out (aka flushes) prior pending commands into a primary command
30   buffer, then starts a new render pass. Returns a secondary command buffer *inside* a render pass
31   instance.
32 * `getOutsideRenderPassCommandBuffer`: May flush prior command buffers and close the render pass if
33   necessary, in addition to issuing the appropriate barriers. Returns a secondary command buffer
34   *outside* a render pass instance.
35 * `getStartedRenderPassCommands`: Returns a reference to the currently open render pass' commands
36   buffer.
37
38The back-end (mostly) records Image and Buffer barriers through additional `CommandBufferAccess`
39APIs, the result of which is passed to `getOutsideRenderPassCommandBuffer`.  Note that the
40barriers are not actually recorded until `getOutsideRenderPassCommandBuffer` is called:
41
42 * `onBufferTransferRead` and `onBufferComputeShaderRead` accumulate `VkBuffer` read barriers.
43 * `onBufferTransferWrite` and `onBufferComputeShaderWrite` accumulate `VkBuffer` write barriers.
44 * `onBuffferSelfCopy` is a special case for `VkBuffer` self copies. It behaves the same as write.
45 * `onImageTransferRead` and `onImageComputerShadeRead` accumulate `VkImage` read barriers.
46 * `onImageTransferWrite` and `onImageComputerShadeWrite` accumulate `VkImage` write barriers.
47 * `onImageRenderPassRead` and `onImageRenderPassWrite` accumulate `VkImage` barriers inside a
48   started RenderPass.
49
50After the back-end records commands to the primary buffer and we flush (e.g. on swap) or when we call
51`ContextVk::finishToSerial`, ANGLE submits the primary command buffer to a `VkQueue`.
52
53See the [code][CommandAPIs] for more details.
54
55### Simple command recording example
56
57In this example we'll be recording a buffer copy command:
58
59```
60    // Ensure that ANGLE sets proper read and write barriers for the Buffers.
61    vk::CommandBufferAccess access;
62    access.onBufferTransferWrite(dstBuffer);
63    access.onBufferTransferRead(srcBuffer);
64
65    // Get a pointer to a secondary command buffer for command recording.
66    vk::OutsideRenderPassCommandBuffer *commandBuffer;
67    ANGLE_TRY(contextVk->getOutsideRenderPassCommandBuffer(access, &commandBuffer));
68
69    // Record the copy command into the secondary buffer. We're done!
70    commandBuffer->copyBuffer(srcBuffer->getBuffer(), dstBuffer->getBuffer(), copyCount, copies);
71```
72
73## Additional Reading
74
75More implementation details can be found in the `doc` directory:
76
77- [Fast OpenGL State Transitions](doc/FastOpenGLStateTransitions.md)
78- [Shader Module Compilation](doc/ShaderModuleCompilation.md)
79- [OpenGL Line Segment Rasterization](doc/OpenGLLineSegmentRasterization.md)
80- [Format Tables and Emulation](doc/FormatTablesAndEmulation.md)
81- [Deferred Clears](doc/DeferredClears.md)
82- [Queries](doc/Queries.md)
83
84[VkDevice]: https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkDevice.html
85[VkQueue]: https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkQueue.html
86[CommandAPIs]: https://chromium.googlesource.com/angle/angle/+/df31624eaf3df986a0bdf3f58a87b79b0cc8db5c/src/libANGLE/renderer/vulkan/ContextVk.h#620
87
88