The open source OpenXR runtime
doc: Document the Vulkan extensions used, in a table in Doxygen.
Duplication of information, yes, but it's a lot more readable in table format...
authored by
Ryan Pavlik
and committed by
Jakob Bornecrantz
58932134
90e307bf
+134
+1
doc/mainpage.md
+1
doc/mainpage.md
+133
doc/vulkan-extensions.md
+133
doc/vulkan-extensions.md
···
1
+
# Vulkan extensions used by Monado {#vulkan-extensions}
2
+
3
+
<!--
4
+
Copyright 2020, Collabora, Ltd. and the Monado contributors
5
+
SPDX-License-Identifier: BSL-1.0
6
+
-->
7
+
8
+
<!--
9
+
adjacent vertical lines: for column spans. Aligning final vertical line
10
+
with last column's closing bar, to keep the text looking close to the rendered
11
+
version.
12
+
13
+
Using manual "footnotes" to keep table somewhat narrow.
14
+
15
+
Do not reflow this table!
16
+
17
+
Edit with word-wrap disabled and with a multiple-cursor capable editor to
18
+
minimize frustration.
19
+
20
+
-->
21
+
22
+
| | Client | XCB server (a) | Wayland server (a) | Xlib-xrandr server (b) | NVIDIA xrandr server (b) | Android server | Windows server |
23
+
| ---------------------------------------------------|--------|----------------|--------------------|------------------------|--------------------------|----------------|----------------|
24
+
| **Instance extensions** ||||||||
25
+
| [`VK_KHR_external_fence_capabilities`][] (8) | yes? |||||||
26
+
| [`VK_KHR_external_memory_capabilities`][] (8) | yes? |||||||
27
+
| [`VK_KHR_external_semaphore_capabilities`][] (8) | yes? |||||||
28
+
| [`VK_KHR_get_physical_device_properties2`][] (8) | yes |||||||
29
+
| [`VK_KHR_surface`][] | | yes ||||||
30
+
| [`VK_KHR_display`][] | | | | yes (2) (requires `VK_KHR_surface`) || | |
31
+
| **Platform-specific instance extensions** ||||||||
32
+
| [`VK_KHR_xcb_surface`][] | | yes (1, 4) | | | | | |
33
+
| [`VK_KHR_wayland_surface`][] | | | yes (1, 4) | | | | |
34
+
| [`VK_EXT_direct_mode_display`][] | | | | yes (1) | yes (2) | | |
35
+
| [`VK_EXT_acquire_xlib_display`][] | | | | yes (1) (in shared code) || | |
36
+
| [`VK_KHR_android_surface`][] | | | | | | yes (1, 4) | |
37
+
| [`VK_KHR_win32_surface`][] | | | | | | | yes (1, 4) |
38
+
| **Device Extensions** ||||||||
39
+
| [`VK_KHR_get_memory_requirements2`][] (8) | yes |||||||
40
+
| [`VK_KHR_dedicated_allocation`][] (8) | yes? (requires `VK_KHR_get_memory_requirements2`) |||||||
41
+
| [`VK_KHR_external_fence`][] (8) (+platform: 5) | yes (soon) |||||||
42
+
| [`VK_KHR_external_memory`][] (8) (+platform: 6) | yes |||||||
43
+
| [`VK_KHR_external_semaphore`][] (8) (+platform: 7) | yes (soon) |||||||
44
+
| [`VK_KHR_swapchain`][] | | yes ||||||
45
+
46
+
## Notes
47
+
48
+
Kept out of the table above to limit its width.
49
+
50
+
* Server type:
51
+
* a: Windowed
52
+
* b: Direct mode
53
+
* Usage details/reason:
54
+
* 1: Used directly
55
+
* 2: Dependency of `VK_EXT_direct_mode_display`
56
+
* 3: Dependency of `VK_EXT_acquire_xlib_display`
57
+
* 4: Platform extension building on `VK_KHR_surface`
58
+
* 5: Platform-specific extensions building on `VK_KHR_external_fence`:
59
+
* Linux and Android: [`VK_KHR_external_fence_fd`][]
60
+
* Windows: [`VK_KHR_external_fence_win32`][]
61
+
* Note: These platform-specific extensions were not promoted to Core in
62
+
Vulkan 1.1, only the platform-independent base extension.
63
+
* 6: Platform-specific extensions building on `VK_KHR_external_memory`:
64
+
* Linux: [`VK_KHR_external_memory_fd`][]
65
+
* Android: [`VK_ANDROID_external_memory_android_hardware_buffer`][] (`fd`
66
+
also usually available?)
67
+
* Windows: [`VK_KHR_external_memory_win32`][]
68
+
* Note: These platform-specific extensions were not promoted to Core in
69
+
Vulkan 1.1, only the platform-independent base extension.
70
+
* 7: Platform-specific extensions building on `VK_KHR_external_semaphore`:
71
+
* Linux and Android: [`VK_KHR_external_semaphore_fd`][]
72
+
* Windows: [`VK_KHR_external_semaphore_win32`][]
73
+
* Note: These platform-specific extensions were not promoted to Core in
74
+
Vulkan 1.1, only the platform-independent base extension.
75
+
* 8: Promoted to Vulkan 1.1 Core
76
+
77
+
<!-- links to the extension references, out of line to keep the table source readable -->
78
+
<!-- They don't show up like this in the formatted document. -->
79
+
80
+
[`VK_KHR_external_fence_capabilities`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_external_fence_capabilities.html
81
+
[`VK_KHR_external_memory_capabilities`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_external_memory_capabilities.html
82
+
[`VK_KHR_external_semaphore_capabilities`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_external_semaphore_capabilities.html
83
+
[`VK_KHR_get_physical_device_properties2`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_get_physical_device_properties2.html
84
+
[`VK_KHR_surface`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_surface.html
85
+
[`VK_KHR_display`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_display.html
86
+
[`VK_KHR_xcb_surface`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_xcb_surface.html
87
+
[`VK_KHR_wayland_surface`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_wayland_surface.html
88
+
[`VK_EXT_direct_mode_display`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_direct_mode_display.html
89
+
[`VK_EXT_acquire_xlib_display`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_acquire_xlib_display.html
90
+
[`VK_KHR_android_surface`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_android_surface.html
91
+
[`VK_KHR_win32_surface`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_win32_surface.html
92
+
[`VK_KHR_dedicated_allocation`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_dedicated_allocation.html
93
+
[`VK_KHR_external_fence`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_external_fence.html
94
+
[`VK_KHR_external_memory`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_external_memory.html
95
+
[`VK_KHR_external_semaphore`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_external_semaphore.html
96
+
[`VK_KHR_get_memory_requirements2`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_get_memory_requirements2.html
97
+
[`VK_KHR_swapchain`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_swapchain.html
98
+
[`VK_KHR_external_fence_fd`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_external_fence_fd.html
99
+
[`VK_KHR_external_fence_win32`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_external_fence_win32.html
100
+
[`VK_KHR_external_memory_fd`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_external_memory_fd.html
101
+
[`VK_ANDROID_external_memory_android_hardware_buffer`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_ANDROID_external_memory_android_hardware_buffer.html
102
+
[`VK_KHR_external_memory_win32`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_external_memory_win32.html
103
+
[`VK_KHR_external_semaphore_fd`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_external_semaphore_fd.html
104
+
[`VK_KHR_external_semaphore_win32`]: https://khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_external_semaphore_win32.html
105
+
106
+
## Reasons
107
+
108
+
* Instance extensions:
109
+
* `VK_KHR_surface` - for configuring output surface.
110
+
* `VK_KHR_get_physical_device_properties2` - for getting device UUID to share
111
+
between client compositor and main/native compositor.
112
+
113
+
* Device extensions:
114
+
* `VK_KHR_swapchain` - for displaying output on a display output.
115
+
116
+
## Code locations
117
+
118
+
* Client
119
+
* Instance extensions:
120
+
[xrt_gfx_vk_instance_extensions](@ref xrt_gfx_vk_instance_extensions)
121
+
* Device extensions:
122
+
[xrt_gfx_vk_device_extensions](@ref xrt_gfx_vk_device_extensions)
123
+
124
+
* Server
125
+
* All these are in [comp_compositor.c](@ref comp_compositor.c), with the
126
+
extensions required by all servers defined in
127
+
`COMP_INSTANCE_EXTENSIONS_COMMON`
128
+
* XCB (Windowed) Server: `instance_extensions_xcb`
129
+
* Wayland (Windowed) Server: `instance_extensions_wayland`
130
+
* Xlib-xrandr direct mode server and NVIDIA direct mode server:
131
+
`instance_extensions_direct_mode`
132
+
* Android server: `instance_extensions_android`
133
+
* Windows server: `instance_extensions_windows`