• 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 [`vk::Renderer`](vk::Renderer.cpp) class represents an `EGLDisplay`. `vk::Renderer` 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
27A render pass has three states: `unstarted`, started and active (we call it `active` in short),
28started but inactive (we call it `inactive` in short). The back-end records commands into command
29buffers via the following `ContextVk` APIs:
30
31 * `beginNewRenderPass`: Writes out (aka flushes) prior pending commands into a primary command
32   buffer, then starts a new render pass. Returns a secondary command buffer *inside* a render pass
33instance.
34 * `getOutsideRenderPassCommandBuffer`: May flush prior command buffers and close the render pass if
35   necessary, in addition to issuing the appropriate barriers. Returns a secondary command buffer
36*outside* a render pass instance.
37 * `getStartedRenderPassCommands`: Returns a reference to the currently open render pass' commands
38   buffer.
39 * `onRenderPassFinished`: Puts render pass into inactive state where you can not record more
40   commands into secondary command buffer, except in some special cases where ANGLE does some
41optimization internally.
42 * `flushCommandsAndEndRenderPassWithoutSubmit`: Marks the end of render pass. It flushes secondary
43   command buffer into vulkan's primary command buffer, puts secondary command buffer back to
44unstarted state and then goes into recycler for reuse.
45
46The back-end (mostly) records Image and Buffer barriers through additional `CommandBufferAccess`
47APIs, the result of which is passed to `getOutsideRenderPassCommandBuffer`.  Note that the barriers
48are not actually recorded until `getOutsideRenderPassCommandBuffer` is called:
49
50 * `onBufferTransferRead` and `onBufferComputeShaderRead` accumulate `VkBuffer` read barriers.
51 * `onBufferTransferWrite` and `onBufferComputeShaderWrite` accumulate `VkBuffer` write barriers.
52 * `onBuffferSelfCopy` is a special case for `VkBuffer` self copies. It behaves the same as write.
53 * `onImageTransferRead` and `onImageComputerShadeRead` accumulate `VkImage` read barriers.
54 * `onImageTransferWrite` and `onImageComputerShadeWrite` accumulate `VkImage` write barriers.
55 * `onImageRenderPassRead` and `onImageRenderPassWrite` accumulate `VkImage` barriers inside a
56   started RenderPass.
57
58After the back-end records commands to the primary buffer and we flush (e.g. on swap) or when we call
59`vk::Renderer::finishQueueSerial`, ANGLE submits the primary command buffer to a `VkQueue`.
60
61See the [code][CommandAPIs] for more details.
62
63### Simple command recording example
64
65In this example we'll be recording a buffer copy command:
66
67```
68    // Ensure that ANGLE sets proper read and write barriers for the Buffers.
69    vk::CommandBufferAccess access;
70    access.onBufferTransferWrite(dstBuffer);
71    access.onBufferTransferRead(srcBuffer);
72
73    // Get a pointer to a secondary command buffer for command recording.
74    vk::OutsideRenderPassCommandBuffer *commandBuffer;
75    ANGLE_TRY(contextVk->getOutsideRenderPassCommandBuffer(access, &commandBuffer));
76
77    // Record the copy command into the secondary buffer. We're done!
78    commandBuffer->copyBuffer(srcBuffer->getBuffer(), dstBuffer->getBuffer(), copyCount, copies);
79```
80
81## Additional Reading
82
83More implementation details can be found in the `doc` directory:
84
85- [Fast OpenGL State Transitions](doc/FastOpenGLStateTransitions.md)
86- [Shader Module Compilation](doc/ShaderModuleCompilation.md)
87- [OpenGL Line Segment Rasterization](doc/OpenGLLineSegmentRasterization.md)
88- [Format Tables and Emulation](doc/FormatTablesAndEmulation.md)
89- [Deferred Clears](doc/DeferredClears.md)
90- [Queries](doc/Queries.md)
91
92[VkDevice]: https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkDevice.html
93[VkQueue]: https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkQueue.html
94[CommandAPIs]: https://chromium.googlesource.com/angle/angle/+/df31624eaf3df986a0bdf3f58a87b79b0cc8db5c/src/libANGLE/renderer/vulkan/ContextVk.h#620
95
96