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