zink.rst 9.79 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
Zink
====

Overview
--------

The Zink driver is a Gallium driver that emits Vulkan API calls instead
of targeting a specific GPU architecture. This can be used to get full
desktop OpenGL support on devices that only support Vulkan.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
Features
--------

The feature-level of Zink depends on two things; what's implemented in Zink,
as well as the features of the Vulkan driver.

OpenGL 2.1
^^^^^^^^^^

OpenGL 2.1 is the minimum version Zink can support, and will always be
exposed, given Vulkan support. There's a few features that are required
for correct behavior, but not all of these are validated; instead you'll
see rendering-issues and likely validation error, or even crashes.

Here's a list of those requirements:

* Vulkan 1.0
* ``VkPhysicalDeviceFeatures``:

  * ``logicOp``
  * ``fillModeNonSolid``
  * ``alphaToOne``
  * ``shaderClipDistance``

* Device extensions:

  * `VK_KHR_maintenance1`_
38
39
40
  * `VK_KHR_create_renderpass2`_
  * `VK_KHR_imageless_framebuffer`_
  * `VK_KHR_timeline_semaphore`_
41
  * `VK_EXT_custom_border_color`_ with ``customBorderColorWithoutFormat``
Mike Blumenkrantz's avatar
Mike Blumenkrantz committed
42
  * `VK_EXT_provoking_vertex`_
43
44
45
46
47
48
49
50
  * `VK_EXT_line_rasterization`_, with the following ``VkPhysicalDeviceLineRasterizationFeaturesEXT``:

    * ``rectangularLines``
    * ``bresenhamLines``
    * ``smoothLines``
    * ``stippledRectangularLines``
    * ``stippledBresenhamLines``
    * ``stippledSmoothLines``
51

52
  * `VK_KHR_swapchain_mutable_format`_
53
  * `VK_EXT_border_color_swizzle`_
54

55
56
In addition to this, `VK_KHR_external_memory`_ is required to support the
DRI code-path.
57

58
59
60
We also require either the `VK_EXT_scalar_block_layout`_ extension or
Vulkan 1.2, with the ``scalarBlockLayout`` feature.

61
62
63
64
OpenGL 3.0
^^^^^^^^^^


65
For OpenGL 3.0 support, the following additional requirements must be
66
67
68
69
70
71
72
73
74
75
supported:

* ``VkPhysicalDeviceFeatures``:

  * ``independentBlend``

* Device extensions:

  * `VK_EXT_transform_feedback`_
  * `VK_EXT_conditional_rendering`_
76

77
78
79
80
81
82
83
84
85
86
87
88

OpenGL 3.1
^^^^^^^^^^

For OpenGL 3.1 support, the following additional ``VkPhysicalDeviceLimits``
are required:

* ``maxPerStageDescriptorSamplers`` ≥ 16

OpenGL 3.2
^^^^^^^^^^

89
90
91
92
93
94
95
96
97
98
For OpenGL 3.2 support, the following additional requirements must be
supported, although some of these might not actually get verified:

* ``VkPhysicalDeviceFeatures``:

  * ``depthClamp``
  * ``geometryShader``
  * ``shaderTessellationAndGeometryPointSize``

* Device extensions:
99

100
  * `VK_EXT_depth_clip_enable`_
101
102
103
104

OpenGL 3.3
^^^^^^^^^^

105
For OpenGL 3.3 support, the following additional requirements must be
106
supported, although some of these might not actually get verified:
107

Erik Faye-Lund's avatar
Erik Faye-Lund committed
108
* ``VkPhysicalDeviceFeatures``:
109
110
111
112
113

  * ``occlusionQueryPrecise``

* Device extensions:

114
  * `VK_EXT_vertex_attribute_divisor`_
115

116
117
118
OpenGL 4.0
^^^^^^^^^^

119
For OpenGL 4.0 support, the following additional requirements must be
120
121
122
123
124
125
126
127
128
129
130
131
supported:

* ``VkPhysicalDeviceFeatures``:

  * ``sampleRateShading``
  * ``tessellationShader``
  * ``imageCubeArray``

* Device extensions:

  * `VK_KHR_maintenance2`_

132
* Formats requiring ``VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT``:
133

134
135
136
      * ``VK_FORMAT_R32G32B32_SFLOAT``
      * ``VK_FORMAT_R32G32B32_SINT``
      * ``VK_FORMAT_R32G32B32_UINT``
137

138
139
140
OpenGL 4.1
^^^^^^^^^^

141
For OpenGL 4.1 support, the following additional requirements must be
142
143
144
supported:

* ``VkPhysicalDeviceFeatures``:
145

146
147
148
149
150
151
  * ``multiViewport``

* ``VkPhysicalDeviceLimits``

  * ``maxImageDimension2D`` ≥ 16384
  * ``maxViewports`` ≥ 16
152

153
154
155
OpenGL 4.2
^^^^^^^^^^

156
For OpenGL 4.2 support, the following additional requirements must be
157
supported:
158

159
* Device extensions:
160
    * `VK_EXT_image_2d_view_of_3d`_
161

162
163
* ``VkPhysicalDeviceLimits``:

164
165
  * ``shaderStorageImageExtendedFormats``
  * ``shaderStorageImageWriteWithoutFormat``
166

167
* For Vulkan 1.2 and above:
Yonggang Luo's avatar
Yonggang Luo committed
168

169
170
171
  * ``VkPhysicalDeviceVulkan11Features``:

    * ``shaderDrawParameters``
172
173
    * ``vertexPipelineStoresAndAtomics``
    * ``fragmentStoresAndAtomics``
174
    * ``textureCompressionBC``
175
176
177
178
179
180

* For Vulkan 1.1 and below:

  * Device extensions:

    * `VK_KHR_shader_draw_parameters`_
181

182
* Formats requiring ``VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT``:
183

184
185
186
187
   * ``VK_FORMAT_BC7_UNORM_BLOCK``
   * ``VK_FORMAT_BC7_SRGB_BLOCK``
   * ``VK_FORMAT_BC6H_SFLOAT_BLOCK``
   * ``VK_FORMAT_BC6H_UFLOAT_BLOCK``
188

189
190
191
OpenGL 4.3
^^^^^^^^^^

192
For OpenGL 4.3 support, the following additional requirements must be
193
194
195
196
197
198
supported:

* ``VkPhysicalDeviceFeatures``:

  * ``robustBufferAccess``

199
* Formats requiring ``VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT``:
200

201
202
203
204
205
206
207
   * ``VK_FORMAT_R8G8B8A8_UNORM``
   * ``VK_FORMAT_R8G8B8A8_SRGB``
   * ``VK_FORMAT_R16_UNORM``
   * ``VK_FORMAT_R16G16_UNORM``
   * ``VK_FORMAT_R16_SNORM``
   * ``VK_FORMAT_R16G16_SNORM``
   * ``VK_FORMAT_D32_SFLOAT_S8_UINT``
208

209
210
211
OpenGL 4.4
^^^^^^^^^^

212
For OpenGL 4.4 support, the following additional requirements must be
213
214
215
supported:

* Formats requiring ``VK_FORMAT_FEATURE_VERTEX_BUFFER_BIT``:
216

217
  * ``VK_FORMAT_B10G11R11_UFLOAT_PACK32``
218

219
220
221
222
* Device extensions:

  * `VK_KHR_sampler_mirror_clamp_to_edge`_

223
224
225
226
227
228
229
230
OpenGL 4.5
^^^^^^^^^^

For OpenGL 4.5 support, the following additional ``VkPhysicalDeviceFeatures``
are required to be supported

* ``shaderCullDistance``

231
232
233
234
235
236
237
238
239
OpenGL 4.6
^^^^^^^^^^

For OpenGL 4.6 support, the following additional ``VkPhysicalDeviceFeatures``
are required to be supported

* ``VkPhysicalDeviceFeatures``:

  * ``samplerAnisotropy``
240
  * ``pipelineStatisticsQuery``
241
  * ``depthBiasClamp``
242
243
244
245
246

* Device extensions:

  * `VK_KHR_draw_indirect_count`_

247
248
249
250
251
252
253
254
255
256
257
258
Performance
-----------

If you notice poor performance and high CPU usage while running an application,
changing the descriptor manager may improve performance:

.. envvar:: ZINK_DESCRIPTORS <mode> ("auto")

``auto``
   Automatically detect best mode. This is the default.
``lazy``
   Disable caching and attempt to use the least amount of CPU.
259
260
``cached``
   Use caching to reuse descriptor sets.
261
262
263
``notemplates``
   The same as `auto`, but disables the use of `VK_KHR_descriptor_templates`.

264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
Debugging
---------

There's a few tools that are useful for debugging Zink, like this environment
variable:

.. envvar:: ZINK_DEBUG <flags> ("")

``nir``
   Print the NIR form of all shaders to stderr.
``spirv``
   Write the binary SPIR-V form of all compiled shaders to a file in the
   current directory, and print a message with the filename to stderr.
``tgsi``
   Print the TGSI form of TGSI shaders to stderr.
Erik Faye-Lund's avatar
Erik Faye-Lund committed
279
280
``validation``
   Dump Validation layer output.
Mike Blumenkrantz's avatar
Mike Blumenkrantz committed
281
282
``sync``
   Emit full synchronization barriers before every draw and dispatch.
283
284
``compact``
   Use a maximum of 4 descriptor sets
285
286
``noreorder``
   Do not reorder or optimize GL command streams
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304

Vulkan Validation Layers
^^^^^^^^^^^^^^^^^^^^^^^^

Another useful tool for debugging is the `Vulkan Validation Layers
<https://github.com/KhronosGroup/Vulkan-ValidationLayers/blob/master/README.md>`_.

The validation layers effectively insert extra checking between Zink and the
Vulkan driver, pointing out incorrect usage of the Vulkan API. The layers can
be enabled by setting the environment variable :envvar:`VK_INSTANCE_LAYERS` to
"VK_LAYER_KHRONOS_validation". You can read more about the Validation Layers
in the link above.

IRC
---

In order to make things a bit easier to follow, we have decided to create our
own IRC channel. If you're interested in contributing, or have any technical
Erik Faye-Lund's avatar
Erik Faye-Lund committed
305
306
questions, don't hesitate to visit `#zink on OFTC
<irc://irc.oftc.net/zink>`__ and say hi!
307
308
309


.. _VK_KHR_maintenance1: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_maintenance1.html
310
311
312
.. _VK_KHR_create_renderpass2: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_create_renderpass2.html
.. _VK_KHR_imageless_framebuffer: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_imageless_framebuffer.html
.. _VK_KHR_timeline_semaphore: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_timeline_semaphore.html
313
.. _VK_KHR_external_memory: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_external_memory.html
314
.. _VK_EXT_scalar_block_layout: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_scalar_block_layout.html
315
316
.. _VK_EXT_transform_feedback: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_transform_feedback.html
.. _VK_EXT_conditional_rendering: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_conditional_rendering.html
317
.. _VK_EXT_vertex_attribute_divisor: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_vertex_attribute_divisor.html
318
.. _VK_EXT_image_2d_view_of_3d: https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VK_EXT_image_2d_view_of_3d.html
319
.. _VK_KHR_maintenance2: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_maintenance2.html
320
.. _VK_KHR_shader_draw_parameters: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_shader_draw_parameters.html
321
.. _VK_KHR_draw_indirect_count: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_draw_indirect_count.html
322
.. _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
Erik Faye-Lund's avatar
Erik Faye-Lund committed
323
.. _VK_EXT_custom_border_color: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_custom_border_color.html
Mike Blumenkrantz's avatar
Mike Blumenkrantz committed
324
.. _VK_EXT_provoking_vertex: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_provoking_vertex.html
325
.. _VK_EXT_line_rasterization: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_line_rasterization.html
326
.. _VK_KHR_swapchain_mutable_format: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_swapchain_mutable_format.html
327
.. _VK_EXT_border_color_swizzle: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_border_color_swizzle.html
328
.. _VK_EXT_depth_clip_enable: https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VK_EXT_depth_clip_enable.html