1Zink
2====
3
4Overview
5--------
6
7The Zink driver is a Gallium driver that emits Vulkan API calls instead
8of targeting a specific GPU architecture. This can be used to get full
9desktop OpenGL support on devices that only support Vulkan.
10
11Features
12--------
13
14The feature-level of Zink depends on two things; what's implemented in Zink,
15as well as the features of the Vulkan driver.
16
17OpenGL 2.1
18^^^^^^^^^^
19
20OpenGL 2.1 is the minimum version Zink can support, and will always be
21exposed, given Vulkan support. There's a few features that are required
22for correct behavior, but not all of these are validated; instead you'll
23see rendering-issues and likely validation error, or even crashes.
24
25Here's a list of those requirements:
26
27* Vulkan 1.0
28* ``VkPhysicalDeviceFeatures``:
29
30  * ``logicOp``
31  * ``fillModeNonSolid``
32  * ``wideLines``
33  * ``largePoints``
34  * ``alphaToOne``
35  * ``shaderClipDistance``
36
37* Device extensions:
38
39  * `VK_KHR_maintenance1`_
40  * `VK_EXT_custom_border_color`_
41  * `VK_EXT_provoking_vertex`_
42  * `VK_EXT_line_rasterization`_, with the following ``VkPhysicalDeviceLineRasterizationFeaturesEXT``:
43
44    * ``rectangularLines``
45    * ``bresenhamLines``
46    * ``smoothLines``
47    * ``stippledRectangularLines``
48    * ``stippledBresenhamLines``
49    * ``stippledSmoothLines``
50
51In addition to this, `VK_KHR_external_memory`_ is required to support the
52DRI code-path.
53
54We also require either the `VK_EXT_scalar_block_layout`_ extension or
55Vulkan 1.2, with the ``scalarBlockLayout`` feature.
56
57OpenGL 3.0
58^^^^^^^^^^
59
60
61For OpenGL 3.0 support, the following additional requirements needs to be
62supported:
63
64* ``VkPhysicalDeviceFeatures``:
65
66  * ``independentBlend``
67
68* Device extensions:
69
70  * `VK_EXT_transform_feedback`_
71  * `VK_EXT_conditional_rendering`_
72
73
74OpenGL 3.1
75^^^^^^^^^^
76
77For OpenGL 3.1 support, the following additional ``VkPhysicalDeviceLimits``
78are required:
79
80* ``maxPerStageDescriptorSamplers`` ≥ 16
81
82OpenGL 3.2
83^^^^^^^^^^
84
85For OpenGL 3.2 support, the following additional ``VkPhysicalDeviceFeatures``
86are required to be supported, although some of these might not actually get
87verified:
88
89* ``depthClamp``
90* ``geometryShader``
91* ``shaderTessellationAndGeometryPointSize``
92
93OpenGL 3.3
94^^^^^^^^^^
95
96For OpenGL 3.3 support, the following additional requirements needs to be
97supported, although some of these might not actually get verified:
98
99* ``VkPhysicalDeviceFeatures``:
100
101  * ``occlusionQueryPrecise``
102
103* Device extensions:
104
105  * `VK_EXT_vertex_attribute_divisor`_
106
107OpenGL 4.0
108^^^^^^^^^^
109
110For OpenGL 4.0 support, the following additional requirements needs to be
111supported:
112
113* ``VkPhysicalDeviceFeatures``:
114
115  * ``sampleRateShading``
116  * ``tessellationShader``
117  * ``imageCubeArray``
118
119* Device extensions:
120
121  * `VK_KHR_maintenance2`_
122
123* Formats requiring ``VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT``:
124
125      * ``VK_FORMAT_R32G32B32_SFLOAT``
126      * ``VK_FORMAT_R32G32B32_SINT``
127      * ``VK_FORMAT_R32G32B32_UINT``
128
129OpenGL 4.1
130^^^^^^^^^^
131
132For OpenGL 4.1 support, the following additional ``VkPhysicalDeviceLimits``
133are required:
134
135* ``maxImageDimension2D`` ≥ 16384
136* ``maxViewports`` ≥ 16
137
138OpenGL 4.2
139^^^^^^^^^^
140
141For OpenGL 4.2 support, the following additional requirements needs to be
142supported:
143
144* ``VkPhysicalDeviceLimits``:
145
146  * ``shaderStorageImageExtendedFormats``
147  * ``shaderStorageImageWriteWithoutFormat``
148
149* For Vulkan 1.2 and above:
150
151  * ``VkPhysicalDeviceVulkan11Features``:
152
153    * ``shaderDrawParameters``
154    * ``vertexPipelineStoresAndAtomics``
155    * ``fragmentStoresAndAtomics``
156    * ``textureCompressionBC``
157
158* For Vulkan 1.1 and below:
159
160  * Device extensions:
161
162    * `VK_KHR_shader_draw_parameters`_
163
164* Formats requiring ``VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT``:
165
166   * ``VK_FORMAT_BC7_UNORM_BLOCK``
167   * ``VK_FORMAT_BC7_SRGB_BLOCK``
168   * ``VK_FORMAT_BC6H_SFLOAT_BLOCK``
169   * ``VK_FORMAT_BC6H_UFLOAT_BLOCK``
170
171OpenGL 4.3
172^^^^^^^^^^
173
174For OpenGL 4.3 support, the following additional requirements needs to be
175supported:
176
177* ``VkPhysicalDeviceFeatures``:
178
179  * ``robustBufferAccess``
180  * ``multiViewport``
181
182* Formats requiring ``VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT``:
183
184   * ``VK_FORMAT_R8G8B8A8_UNORM``
185   * ``VK_FORMAT_R8G8B8A8_SRGB``
186   * ``VK_FORMAT_R16_UNORM``
187   * ``VK_FORMAT_R16G16_UNORM``
188   * ``VK_FORMAT_R16_SNORM``
189   * ``VK_FORMAT_R16G16_SNORM``
190   * ``VK_FORMAT_D32_SFLOAT_S8_UINT``
191
192OpenGL 4.4
193^^^^^^^^^^
194
195For OpenGL 4.4 support, the following additional requirements needs to be
196supported:
197
198* Formats requiring ``VK_FORMAT_FEATURE_VERTEX_BUFFER_BIT``:
199
200  * ``VK_FORMAT_B10G11R11_UFLOAT_PACK32``
201
202* Device extensions:
203
204  * `VK_KHR_sampler_mirror_clamp_to_edge`_
205
206OpenGL 4.5
207^^^^^^^^^^
208
209For OpenGL 4.5 support, the following additional ``VkPhysicalDeviceFeatures``
210are required to be supported
211
212* ``shaderCullDistance``
213
214OpenGL 4.6
215^^^^^^^^^^
216
217For OpenGL 4.6 support, the following additional ``VkPhysicalDeviceFeatures``
218are required to be supported
219
220* ``VkPhysicalDeviceFeatures``:
221
222  * ``samplerAnisotropy``
223  * ``pipelineStatisticsQuery``
224  * ``depthBiasClamp``
225
226* Device extensions:
227
228  * `VK_KHR_draw_indirect_count`_
229
230Performance
231-----------
232
233If you notice poor performance and high CPU usage while running an application,
234changing the descriptor manager may improve performance:
235
236.. envvar:: ZINK_DESCRIPTORS <mode> ("auto")
237
238``auto``
239   Automatically detect best mode. This is the default.
240``lazy``
241   Disable caching and attempt to use the least amount of CPU.
242``nofallback``
243   Always use caching to try reducing GPU churn.
244``notemplates``
245   The same as `auto`, but disables the use of `VK_KHR_descriptor_templates`.
246
247Debugging
248---------
249
250There's a few tools that are useful for debugging Zink, like this environment
251variable:
252
253.. envvar:: ZINK_DEBUG <flags> ("")
254
255``nir``
256   Print the NIR form of all shaders to stderr.
257``spirv``
258   Write the binary SPIR-V form of all compiled shaders to a file in the
259   current directory, and print a message with the filename to stderr.
260``tgsi``
261   Print the TGSI form of TGSI shaders to stderr.
262``validation``
263   Dump Validation layer output.
264
265Vulkan Validation Layers
266^^^^^^^^^^^^^^^^^^^^^^^^
267
268Another useful tool for debugging is the `Vulkan Validation Layers
269<https://github.com/KhronosGroup/Vulkan-ValidationLayers/blob/master/README.md>`_.
270
271The validation layers effectively insert extra checking between Zink and the
272Vulkan driver, pointing out incorrect usage of the Vulkan API. The layers can
273be enabled by setting the environment variable :envvar:`VK_INSTANCE_LAYERS` to
274"VK_LAYER_KHRONOS_validation". You can read more about the Validation Layers
275in the link above.
276
277IRC
278---
279
280In order to make things a bit easier to follow, we have decided to create our
281own IRC channel. If you're interested in contributing, or have any technical
282questions, don't hesitate to visit `#zink on OFTC
283<irc://irc.oftc.net/zink>`__ and say hi!
284
285
286.. _VK_KHR_maintenance1: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_maintenance1.html
287.. _VK_KHR_external_memory: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_external_memory.html
288.. _VK_EXT_scalar_block_layout: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_scalar_block_layout.html
289.. _VK_EXT_transform_feedback: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_transform_feedback.html
290.. _VK_EXT_conditional_rendering: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_conditional_rendering.html
291.. _VK_EXT_vertex_attribute_divisor: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_vertex_attribute_divisor.html
292.. _VK_KHR_maintenance2: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_maintenance2.html
293.. _VK_KHR_shader_draw_parameters: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_shader_draw_parameters.html
294.. _VK_KHR_draw_indirect_count: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_draw_indirect_count.html
295.. _VK_KHR_sampler_mirror_clamp_to_edge: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_sampler_mirror_clamp_to_edge.html
296.. _VK_EXT_custom_border_color: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_custom_border_color.html
297.. _VK_EXT_provoking_vertex: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_provoking_vertex.html
298.. _VK_EXT_line_rasterization: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_line_rasterization.html
299