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 * ``alphaToOne`` 33 * ``shaderClipDistance`` 34 35* Device extensions: 36 37 * `VK_KHR_maintenance1`_ 38 * `VK_KHR_create_renderpass2`_ 39 * `VK_KHR_imageless_framebuffer`_ 40 * `VK_KHR_timeline_semaphore`_ 41 * `VK_EXT_custom_border_color`_ with ``customBorderColorWithoutFormat`` 42 * `VK_EXT_provoking_vertex`_ 43 * `VK_EXT_line_rasterization`_, with the following ``VkPhysicalDeviceLineRasterizationFeaturesEXT``: 44 45 * ``rectangularLines`` 46 * ``bresenhamLines`` 47 * ``smoothLines`` 48 * ``stippledRectangularLines`` 49 * ``stippledBresenhamLines`` 50 * ``stippledSmoothLines`` 51 52 * `VK_KHR_swapchain_mutable_format`_ 53 * `VK_EXT_border_color_swizzle`_ 54 55In addition to this, `VK_KHR_external_memory`_ is required to support the 56DRI code-path. 57 58We also require either the `VK_EXT_scalar_block_layout`_ extension or 59Vulkan 1.2, with the ``scalarBlockLayout`` feature. 60 61OpenGL 3.0 62^^^^^^^^^^ 63 64 65For OpenGL 3.0 support, the following additional requirements must be 66supported: 67 68* ``VkPhysicalDeviceFeatures``: 69 70 * ``independentBlend`` 71 72* Device extensions: 73 74 * `VK_EXT_transform_feedback`_ 75 * `VK_EXT_conditional_rendering`_ 76 77* Formats requiring ``VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT``: 78 79 * ``VK_FORMAT_BC4_UNORM_BLOCK`` 80 * ``VK_FORMAT_BC4_SNORM_BLOCK`` 81 * ``VK_FORMAT_BC5_UNORM_BLOCK`` 82 * ``VK_FORMAT_BC5_SNORM_BLOCK`` 83 84OpenGL 3.1 85^^^^^^^^^^ 86 87For OpenGL 3.1 support, the following additional ``VkPhysicalDeviceLimits`` 88are required: 89 90* ``maxPerStageDescriptorSamplers`` ≥ 16 91 92OpenGL 3.2 93^^^^^^^^^^ 94 95For OpenGL 3.2 support, the following additional requirements must be 96supported, although some of these might not actually get verified: 97 98* ``VkPhysicalDeviceFeatures``: 99 100 * ``depthClamp`` 101 * ``geometryShader`` 102 * ``shaderTessellationAndGeometryPointSize`` 103 104* Device extensions: 105 106 * `VK_EXT_depth_clip_enable`_ 107 108OpenGL 3.3 109^^^^^^^^^^ 110 111For OpenGL 3.3 support, the following additional requirements must be 112supported, although some of these might not actually get verified: 113 114* ``VkPhysicalDeviceFeatures``: 115 116 * ``occlusionQueryPrecise`` 117 118* Device extensions: 119 120 * `VK_EXT_vertex_attribute_divisor`_ 121 122OpenGL 4.0 123^^^^^^^^^^ 124 125For OpenGL 4.0 support, the following additional requirements must be 126supported: 127 128* ``VkPhysicalDeviceFeatures``: 129 130 * ``sampleRateShading`` 131 * ``tessellationShader`` 132 * ``imageCubeArray`` 133 134* Device extensions: 135 136 * `VK_KHR_maintenance2`_ 137 138* Formats requiring ``VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT``: 139 140 * ``VK_FORMAT_R32G32B32_SFLOAT`` 141 * ``VK_FORMAT_R32G32B32_SINT`` 142 * ``VK_FORMAT_R32G32B32_UINT`` 143 144OpenGL 4.1 145^^^^^^^^^^ 146 147For OpenGL 4.1 support, the following additional requirements must be 148supported: 149 150* ``VkPhysicalDeviceFeatures``: 151 152 * ``multiViewport`` 153 154* ``VkPhysicalDeviceLimits`` 155 156 * ``maxImageDimension2D`` ≥ 16384 157 * ``maxViewports`` ≥ 16 158 159OpenGL 4.2 160^^^^^^^^^^ 161 162For OpenGL 4.2 support, the following additional requirements must be 163supported: 164 165* Device extensions: 166 * `VK_EXT_image_2d_view_of_3d`_ 167 168* ``VkPhysicalDeviceLimits``: 169 170 * ``shaderStorageImageExtendedFormats`` 171 * ``shaderStorageImageWriteWithoutFormat`` 172 173* For Vulkan 1.2 and above: 174 175 * ``VkPhysicalDeviceVulkan11Features``: 176 177 * ``shaderDrawParameters`` 178 * ``vertexPipelineStoresAndAtomics`` 179 * ``fragmentStoresAndAtomics`` 180 * ``textureCompressionBC`` 181 182* For Vulkan 1.1 and below: 183 184 * Device extensions: 185 186 * `VK_KHR_shader_draw_parameters`_ 187 188* Formats requiring ``VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT``: 189 190 * ``VK_FORMAT_BC7_UNORM_BLOCK`` 191 * ``VK_FORMAT_BC7_SRGB_BLOCK`` 192 * ``VK_FORMAT_BC6H_SFLOAT_BLOCK`` 193 * ``VK_FORMAT_BC6H_UFLOAT_BLOCK`` 194 195OpenGL 4.3 196^^^^^^^^^^ 197 198For OpenGL 4.3 support, the following additional requirements must be 199supported: 200 201* ``VkPhysicalDeviceFeatures``: 202 203 * ``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 219supported: 220 221* Formats requiring ``VK_FORMAT_FEATURE_VERTEX_BUFFER_BIT``: 222 223 * ``VK_FORMAT_B10G11R11_UFLOAT_PACK32`` 224 225* Device extensions: 226 227 * `VK_KHR_sampler_mirror_clamp_to_edge`_ 228 229OpenGL 4.5 230^^^^^^^^^^ 231 232For OpenGL 4.5 support, the following additional ``VkPhysicalDeviceFeatures`` 233are required to be supported 234 235* ``shaderCullDistance`` 236 237OpenGL 4.6 238^^^^^^^^^^ 239 240For OpenGL 4.6 support, the following additional ``VkPhysicalDeviceFeatures`` 241are required to be supported 242 243* ``VkPhysicalDeviceFeatures``: 244 245 * ``samplerAnisotropy`` 246 * ``pipelineStatisticsQuery`` 247 * ``depthBiasClamp`` 248 249* Device extensions: 250 251 * `VK_KHR_draw_indirect_count`_ 252 253Performance 254----------- 255 256If you notice poor performance and high CPU usage while running an application, 257changing the descriptor manager may improve performance: 258 259.. envvar:: ZINK_DESCRIPTORS <mode> ("auto") 260 261``auto`` 262 Automatically detect best mode. This is the default. 263``lazy`` 264 Disable caching and attempt to use the least amount of CPU. 265``cached`` 266 Use caching to reuse descriptor sets. 267``notemplates`` 268 The same as `auto`, but disables the use of `VK_KHR_descriptor_templates`. 269 270Debugging 271--------- 272 273There's a few tools that are useful for debugging Zink, like this environment 274variable: 275 276.. envvar:: ZINK_DEBUG <flags> ("") 277 278``nir`` 279 Print the NIR form of all shaders to stderr. 280``spirv`` 281 Write the binary SPIR-V form of all compiled shaders to a file in the 282 current directory, and print a message with the filename to stderr. 283``tgsi`` 284 Print the TGSI form of TGSI shaders to stderr. 285``validation`` 286 Dump Validation layer output. 287``sync`` 288 Emit full synchronization barriers before every draw and dispatch. 289``compact`` 290 Use a maximum of 4 descriptor sets 291``noreorder`` 292 Do not reorder or optimize GL command streams 293 294Vulkan Validation Layers 295^^^^^^^^^^^^^^^^^^^^^^^^ 296 297Another useful tool for debugging is the `Vulkan Validation Layers 298<https://github.com/KhronosGroup/Vulkan-ValidationLayers/blob/master/README.md>`_. 299 300The validation layers effectively insert extra checking between Zink and the 301Vulkan driver, pointing out incorrect usage of the Vulkan API. The layers can 302be enabled by setting the environment variable :envvar:`VK_INSTANCE_LAYERS` to 303"VK_LAYER_KHRONOS_validation". You can read more about the Validation Layers 304in the link above. 305 306IRC 307--- 308 309In order to make things a bit easier to follow, we have decided to create our 310own IRC channel. If you're interested in contributing, or have any technical 311questions, don't hesitate to visit `#zink on OFTC 312<irc://irc.oftc.net/zink>`__ and say hi! 313 314 315.. _VK_KHR_maintenance1: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_maintenance1.html 316.. _VK_KHR_create_renderpass2: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_create_renderpass2.html 317.. _VK_KHR_imageless_framebuffer: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_imageless_framebuffer.html 318.. _VK_KHR_timeline_semaphore: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_timeline_semaphore.html 319.. _VK_KHR_external_memory: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_external_memory.html 320.. _VK_EXT_scalar_block_layout: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_scalar_block_layout.html 321.. _VK_EXT_transform_feedback: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_transform_feedback.html 322.. _VK_EXT_conditional_rendering: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_conditional_rendering.html 323.. _VK_EXT_vertex_attribute_divisor: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_vertex_attribute_divisor.html 324.. _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 325.. _VK_KHR_maintenance2: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_maintenance2.html 326.. _VK_KHR_shader_draw_parameters: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_shader_draw_parameters.html 327.. _VK_KHR_draw_indirect_count: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_draw_indirect_count.html 328.. _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 329.. _VK_EXT_custom_border_color: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_custom_border_color.html 330.. _VK_EXT_provoking_vertex: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_provoking_vertex.html 331.. _VK_EXT_line_rasterization: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_line_rasterization.html 332.. _VK_KHR_swapchain_mutable_format: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_swapchain_mutable_format.html 333.. _VK_EXT_border_color_swizzle: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_border_color_swizzle.html 334.. _VK_EXT_depth_clip_enable: https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VK_EXT_depth_clip_enable.html 335