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 capabilities of the Vulkan driver. 16 17The feature-levels implemented by Zink are exposed by `Vulkan Profiles 18<https://dev.vulkan.org/tools#vulkan-profiles>`__ in the 19:file:`VP_ZINK_requirements.json` profiles file. 20 21Used with the `Vulkan Profiles tools <https://github.com/KhronosGroup/Vulkan-Profiles>`__, 22we can compare the ZINK profiles with Vulkan devices profiles generated with 23`Vulkaninfo <https://vulkan.lunarg.com/doc/view/latest/windows/vulkaninfo.html>`__ 24or `downloaded from GPUinfo.org`_ 25to establish the feature-levels supported by these drivers. 26 27OpenGL 2.1 28^^^^^^^^^^ 29 30OpenGL 2.1 is the minimum version Zink can support, and will always be 31exposed, given Vulkan support. There's a few features that are required 32for correct behavior, but not all of these are validated; instead you'll 33see rendering-issues and likely validation error, or even crashes. 34 35Here's a list of those requirements: 36 37* Vulkan 1.0 38* ``VkPhysicalDeviceFeatures``: 39 40 * :vk-feat:`logicOp` 41 * :vk-feat:`fillModeNonSolid` 42 * :vk-feat:`alphaToOne` 43 * :vk-feat:`shaderClipDistance` 44 45* Device extensions: 46 47 * :ext:`VK_KHR_maintenance1` 48 * :ext:`VK_KHR_create_renderpass2` 49 * :ext:`VK_KHR_imageless_framebuffer` 50 * :ext:`VK_KHR_timeline_semaphore` 51 * :ext:`VK_EXT_custom_border_color` with ``customBorderColorWithoutFormat`` 52 * :ext:`VK_EXT_provoking_vertex` 53 * :ext:`VK_EXT_line_rasterization`, with the following ``VkPhysicalDeviceLineRasterizationFeaturesEXT``: 54 55 * :vk-feat:`rectangularLines` 56 * :vk-feat:`bresenhamLines` 57 * :vk-feat:`smoothLines` 58 * :vk-feat:`stippledRectangularLines` 59 * :vk-feat:`stippledBresenhamLines` 60 * :vk-feat:`stippledSmoothLines` 61 62 * :ext:`VK_KHR_swapchain_mutable_format` 63 * :ext:`VK_EXT_border_color_swizzle` 64 * :ext:`VK_KHR_descriptor_update_template` 65 66In addition to this, :ext:`VK_KHR_external_memory` is required to support the 67DRI code-path. 68 69We also require either the :ext:`VK_EXT_scalar_block_layout` extension or 70Vulkan 1.2, with the :vk-feat:`scalarBlockLayout` feature. 71 72OpenGL 3.0 73^^^^^^^^^^ 74 75 76For OpenGL 3.0 support, the following additional requirements must be 77met: 78 79* ``VkPhysicalDeviceFeatures``: 80 81 * :vk-feat:`independentBlend` 82 83* Device extensions: 84 85 * :ext:`VK_EXT_transform_feedback` 86 * :ext:`VK_EXT_conditional_rendering` 87 88OpenGL 3.1 89^^^^^^^^^^ 90 91For OpenGL 3.1 support, the following additional ``VkPhysicalDeviceLimits`` 92are required: 93 94* ``maxPerStageDescriptorSamplers`` ≥ 16 95 96OpenGL 3.2 97^^^^^^^^^^ 98 99For OpenGL 3.2 support, the following additional requirements must be 100met, although some of these might not actually get verified: 101 102* ``VkPhysicalDeviceFeatures``: 103 104 * :vk-feat:`depthClamp` 105 * :vk-feat:`geometryShader` 106 * :vk-feat:`shaderTessellationAndGeometryPointSize` 107 108* Device extensions: 109 110 * :ext:`VK_EXT_depth_clip_enable` 111 112OpenGL 3.3 113^^^^^^^^^^ 114 115For OpenGL 3.3 support, the following additional requirements must be 116met, although some of these might not actually get verified: 117 118* ``VkPhysicalDeviceFeatures``: 119 120 * :vk-feat:`dualSrcBlend` 121 122* Device extensions: 123 124 * :ext:`VK_EXT_vertex_attribute_divisor` 125 126OpenGL 4.0 127^^^^^^^^^^ 128 129For OpenGL 4.0 support, the following additional requirements must be 130met: 131 132* ``VkPhysicalDeviceFeatures``: 133 134 * :vk-feat:`sampleRateShading` 135 * :vk-feat:`tessellationShader` 136 * :vk-feat:`imageCubeArray` 137 138* Device extensions: 139 140 * :ext:`VK_KHR_maintenance2` 141 142* Formats requiring ``VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT``: 143 144 * ``VK_FORMAT_R32G32B32_SFLOAT`` 145 * ``VK_FORMAT_R32G32B32_SINT`` 146 * ``VK_FORMAT_R32G32B32_UINT`` 147 148OpenGL 4.1 149^^^^^^^^^^ 150 151For OpenGL 4.1 support, the following additional requirements must be 152met: 153 154* ``VkPhysicalDeviceFeatures``: 155 156 * :vk-feat:`multiViewport` 157 158* ``VkPhysicalDeviceLimits`` 159 160 * ``maxImageDimension1D`` ≥ 16384 161 * ``maxImageDimension2D`` ≥ 16384 162 * ``maxImageDimension3D`` ≥ 2048 163 * ``maxImageDimensionCube`` ≥ 16384 164 * ``maxImageArrayLayers`` ≥ 2048 165 * ``maxViewports`` ≥ 16 166 167OpenGL 4.2 168^^^^^^^^^^ 169 170For OpenGL 4.2 support, the following additional requirements must be 171met: 172 173* Device extensions: 174 * :ext:`VK_EXT_image_2d_view_of_3d` 175 176* ``VkPhysicalDeviceLimits``: 177 178 * ``shaderStorageImageExtendedFormats`` 179 * ``shaderStorageImageWriteWithoutFormat`` 180 * ``vertexPipelineStoresAndAtomics`` 181 * ``fragmentStoresAndAtomics`` 182 183* For Vulkan 1.2 and above: 184 185 * ``VkPhysicalDeviceVulkan11Features``: 186 187 * :vk-feat:`shaderDrawParameters` 188 189* For Vulkan 1.1 and below: 190 191 * Device extensions: 192 193 * :ext:`VK_KHR_shader_draw_parameters` 194 195OpenGL 4.3 196^^^^^^^^^^ 197 198For OpenGL 4.3 support, the following additional requirements must be 199met: 200 201* ``VkPhysicalDeviceFeatures``: 202 203 * :vk-feat:`robustBufferAccess` 204 205* Formats requiring ``VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT``: 206 207 * ``VK_FORMAT_R8G8B8A8_UNORM`` 208 * ``VK_FORMAT_R8G8B8A8_SRGB`` 209 * ``VK_FORMAT_R16_UNORM`` 210 * ``VK_FORMAT_R16G16_UNORM`` 211 * ``VK_FORMAT_R16_SNORM`` 212 * ``VK_FORMAT_R16G16_SNORM`` 213 * ``VK_FORMAT_D32_SFLOAT_S8_UINT`` 214 215OpenGL 4.4 216^^^^^^^^^^ 217 218For OpenGL 4.4 support, the following additional requirements must be 219met: 220 221* Formats requiring ``VK_FORMAT_FEATURE_VERTEX_BUFFER_BIT``: 222 223 * ``VK_FORMAT_B10G11R11_UFLOAT_PACK32`` 224 225* For Vulkan 1.2 and above: 226 227 * ``VkPhysicalDeviceVulkan12Features``: 228 229 * ``samplerMirrorClampToEdge`` 230 231* For Vulkan 1.1 and below: 232 233 * Device extensions: 234 235 * :ext:`VK_KHR_sampler_mirror_clamp_to_edge` 236 237OpenGL 4.5 238^^^^^^^^^^ 239 240For OpenGL 4.5 support, the following additional ``VkPhysicalDeviceFeatures`` 241are required to be supported 242 243* :vk-feat:`shaderCullDistance` 244 245OpenGL 4.6 246^^^^^^^^^^ 247 248For OpenGL 4.6 support, the following additional requirements must be 249met: 250 251* ``VkPhysicalDeviceFeatures``: 252 253 * :vk-feat:`samplerAnisotropy` 254 * :vk-feat:`depthBiasClamp` 255 256* Device extensions: 257 258 * :ext:`VK_KHR_draw_indirect_count` 259 260Performance 261----------- 262 263If you notice poor performance and high CPU usage while running an application, 264changing the descriptor manager may improve performance: 265 266.. envvar:: ZINK_DESCRIPTORS <mode> ("auto") 267 268``auto`` 269 Automatically detect best mode. This is the default. 270``lazy`` 271 Attempt to use the least amount of CPU by binding descriptors opportunistically. 272``db`` 273 Use EXT_descriptor_buffer when possible. 274 275Debugging 276--------- 277 278There's a few tools that are useful for debugging Zink, like this environment 279variable: 280 281.. envvar:: ZINK_DEBUG 282 283 Accepts the following comma-separated list of flags: 284 285 ``nir`` 286 Print the NIR form of all shaders to stderr. 287 ``spirv`` 288 Write the binary SPIR-V form of all compiled shaders to a file in the 289 current directory, and print a message with the filename to stderr. 290 ``tgsi`` 291 Print the TGSI form of TGSI shaders to stderr. 292 ``validation`` 293 Dump Validation layer output. 294 ``sync`` 295 Emit full synchronization barriers before every draw and dispatch. 296 ``compact`` 297 Use a maximum of 4 descriptor sets 298 ``noreorder`` 299 Do not reorder or optimize GL command streams 300 ``gpl`` 301 Force using Graphics Pipeline Library for all shaders 302 ``rp`` 303 Enable render pass optimizations (for tiling GPUs) 304 ``norp`` 305 Disable render pass optimizations (for tiling GPUs) 306 ``map`` 307 Print info about mapped VRAM 308 ``flushsync`` 309 Force synchronous flushes/presents 310 ``noshobj`` 311 Disable EXT_shader_object 312 ``optimal_keys`` 313 Debug/use optimal_keys 314 ``noopt`` 315 Disable async optimized pipeline compiles 316 ``nobgc`` 317 Disable all async pipeline compiles 318 ``mem`` 319 Enable memory allocation debugging 320 ``quiet`` 321 Suppress probably-harmless warnings 322 323Vulkan Validation Layers 324^^^^^^^^^^^^^^^^^^^^^^^^ 325 326Another useful tool for debugging is the `Vulkan Validation Layers 327<https://github.com/KhronosGroup/Vulkan-ValidationLayers/blob/main/README.md>`__. 328 329The validation layers effectively insert extra checking between Zink and the 330Vulkan driver, pointing out incorrect usage of the Vulkan API. The layers can 331be enabled by setting the environment variable :envvar:`VK_LOADER_LAYERS_ENABLE` to 332``VK_LAYER_KHRONOS_validation``. You can read more about the Validation Layers 333in the link above. 334 335Apple macOS and MoltenVK 336------------------------ 337 338Zink on macOS is experimental with very limited capabilities. 339The Vulkan SDK (1.3.250 or newer) is required to build Zink. 340Set the build option ``-Dmoltenvk-dir=<directory>`` to point at your Vulkan SDK install or MoltenVK build. 341Add Zink to the Gallium drivers build option ``-Dgallium-drivers=zink``. 342If installed using ``brew``, you can set ``-D moltenvk-dir=$(brew --prefix molten-vk)``. 343 344 345IRC 346--- 347 348In order to make things a bit easier to follow, we have decided to create our 349own IRC channel. If you're interested in contributing, or have any technical 350questions, don't hesitate to visit `#zink on OFTC 351<irc://irc.oftc.net/zink>`__ and say hi! 352 353 354.. _downloaded from GPUinfo.org: https://www.saschawillems.de/blog/2022/03/12/vulkan-profiles-support-for-the-vulkan-hardware-capability-viewer-and-database/ 355