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