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 must 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 must 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 must 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 requirements must be
133supported:
134
135* ``VkPhysicalDeviceFeatures``:
136
137  * ``multiViewport``
138
139* ``VkPhysicalDeviceLimits``
140
141  * ``maxImageDimension2D`` ≥ 16384
142  * ``maxViewports`` ≥ 16
143
144OpenGL 4.2
145^^^^^^^^^^
146
147For OpenGL 4.2 support, the following additional requirements must be
148supported:
149
150* ``VkPhysicalDeviceLimits``:
151
152  * ``shaderStorageImageExtendedFormats``
153  * ``shaderStorageImageWriteWithoutFormat``
154
155* For Vulkan 1.2 and above:
156
157  * ``VkPhysicalDeviceVulkan11Features``:
158
159    * ``shaderDrawParameters``
160    * ``vertexPipelineStoresAndAtomics``
161    * ``fragmentStoresAndAtomics``
162    * ``textureCompressionBC``
163
164* For Vulkan 1.1 and below:
165
166  * Device extensions:
167
168    * `VK_KHR_shader_draw_parameters`_
169
170* Formats requiring ``VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT``:
171
172   * ``VK_FORMAT_BC7_UNORM_BLOCK``
173   * ``VK_FORMAT_BC7_SRGB_BLOCK``
174   * ``VK_FORMAT_BC6H_SFLOAT_BLOCK``
175   * ``VK_FORMAT_BC6H_UFLOAT_BLOCK``
176
177OpenGL 4.3
178^^^^^^^^^^
179
180For OpenGL 4.3 support, the following additional requirements must be
181supported:
182
183* ``VkPhysicalDeviceFeatures``:
184
185  * ``robustBufferAccess``
186
187* Formats requiring ``VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT``:
188
189   * ``VK_FORMAT_R8G8B8A8_UNORM``
190   * ``VK_FORMAT_R8G8B8A8_SRGB``
191   * ``VK_FORMAT_R16_UNORM``
192   * ``VK_FORMAT_R16G16_UNORM``
193   * ``VK_FORMAT_R16_SNORM``
194   * ``VK_FORMAT_R16G16_SNORM``
195   * ``VK_FORMAT_D32_SFLOAT_S8_UINT``
196
197OpenGL 4.4
198^^^^^^^^^^
199
200For OpenGL 4.4 support, the following additional requirements must be
201supported:
202
203* Formats requiring ``VK_FORMAT_FEATURE_VERTEX_BUFFER_BIT``:
204
205  * ``VK_FORMAT_B10G11R11_UFLOAT_PACK32``
206
207* Device extensions:
208
209  * `VK_KHR_sampler_mirror_clamp_to_edge`_
210
211OpenGL 4.5
212^^^^^^^^^^
213
214For OpenGL 4.5 support, the following additional ``VkPhysicalDeviceFeatures``
215are required to be supported
216
217* ``shaderCullDistance``
218
219OpenGL 4.6
220^^^^^^^^^^
221
222For OpenGL 4.6 support, the following additional ``VkPhysicalDeviceFeatures``
223are required to be supported
224
225* ``VkPhysicalDeviceFeatures``:
226
227  * ``samplerAnisotropy``
228  * ``pipelineStatisticsQuery``
229  * ``depthBiasClamp``
230
231* Device extensions:
232
233  * `VK_KHR_draw_indirect_count`_
234
235Performance
236-----------
237
238If you notice poor performance and high CPU usage while running an application,
239changing the descriptor manager may improve performance:
240
241.. envvar:: ZINK_DESCRIPTORS <mode> ("auto")
242
243``auto``
244   Automatically detect best mode. This is the default.
245``lazy``
246   Disable caching and attempt to use the least amount of CPU.
247``nofallback``
248   Always use caching to try reducing GPU churn.
249``notemplates``
250   The same as `auto`, but disables the use of `VK_KHR_descriptor_templates`.
251
252Debugging
253---------
254
255There's a few tools that are useful for debugging Zink, like this environment
256variable:
257
258.. envvar:: ZINK_DEBUG <flags> ("")
259
260``nir``
261   Print the NIR form of all shaders to stderr.
262``spirv``
263   Write the binary SPIR-V form of all compiled shaders to a file in the
264   current directory, and print a message with the filename to stderr.
265``tgsi``
266   Print the TGSI form of TGSI shaders to stderr.
267``validation``
268   Dump Validation layer output.
269
270Vulkan Validation Layers
271^^^^^^^^^^^^^^^^^^^^^^^^
272
273Another useful tool for debugging is the `Vulkan Validation Layers
274<https://github.com/KhronosGroup/Vulkan-ValidationLayers/blob/master/README.md>`_.
275
276The validation layers effectively insert extra checking between Zink and the
277Vulkan driver, pointing out incorrect usage of the Vulkan API. The layers can
278be enabled by setting the environment variable :envvar:`VK_INSTANCE_LAYERS` to
279"VK_LAYER_KHRONOS_validation". You can read more about the Validation Layers
280in the link above.
281
282IRC
283---
284
285In order to make things a bit easier to follow, we have decided to create our
286own IRC channel. If you're interested in contributing, or have any technical
287questions, don't hesitate to visit `#zink on OFTC
288<irc://irc.oftc.net/zink>`__ and say hi!
289
290
291.. _VK_KHR_maintenance1: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_maintenance1.html
292.. _VK_KHR_external_memory: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_external_memory.html
293.. _VK_EXT_scalar_block_layout: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_scalar_block_layout.html
294.. _VK_EXT_transform_feedback: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_transform_feedback.html
295.. _VK_EXT_conditional_rendering: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_conditional_rendering.html
296.. _VK_EXT_vertex_attribute_divisor: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_vertex_attribute_divisor.html
297.. _VK_KHR_maintenance2: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_maintenance2.html
298.. _VK_KHR_shader_draw_parameters: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_shader_draw_parameters.html
299.. _VK_KHR_draw_indirect_count: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_draw_indirect_count.html
300.. _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
301.. _VK_EXT_custom_border_color: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_custom_border_color.html
302.. _VK_EXT_provoking_vertex: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_provoking_vertex.html
303.. _VK_EXT_line_rasterization: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_line_rasterization.html
304