1// Copyright 2015-2023 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[shaders]] 6= Shaders 7 8A shader specifies programmable operations that execute for each vertex, 9control point, tessellated vertex, primitive, fragment, or workgroup in the 10corresponding stage(s) of the graphics and compute pipelines. 11 12Graphics pipelines include vertex shader execution as a result of 13<<drawing,primitive assembly>>, followed, if enabled, by tessellation 14control and evaluation shaders operating on <<drawing-patch-lists,patches>>, 15geometry shaders, if enabled, operating on primitives, and fragment shaders, 16if present, operating on fragments generated by <<primsrast,Rasterization>>. 17In this specification, vertex, tessellation control, tessellation evaluation 18and geometry shaders are collectively referred to as 19<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader 20stage>>s and occur in the logical pipeline before rasterization. 21The fragment shader occurs logically after rasterization. 22 23Only the compute shader stage is included in a compute pipeline. 24Compute shaders operate on compute invocations in a workgroup. 25 26Shaders can: read from input variables, and read from and write to output 27variables. 28Input and output variables can: be used to transfer data between shader 29stages, or to allow the shader to interact with values that exist in the 30execution environment. 31Similarly, the execution environment provides constants describing 32capabilities. 33 34Shader variables are associated with execution environment-provided inputs 35and outputs using _built-in_ decorations in the shader. 36The available decorations for each stage are documented in the following 37subsections. 38 39 40ifdef::VK_EXT_shader_object[] 41[[shaders-objects]] 42== Shader Objects 43 44Shaders may: be compiled and linked into pipeline objects as described in 45<<pipelines,Pipelines>> chapter, or if the <<features-shaderObject, 46pname:shaderObject>> feature is enabled they may: be compiled into 47individual per-stage _shader objects_ which can: be bound on a command 48buffer independently from one another. 49Unlike pipelines, shader objects are not intrinsically tied to any specific 50set of state. 51Instead, state is specified dynamically in the command buffer. 52 53Each shader object represents a single compiled shader stage, which may: 54optionally: be linked with one or more other stages. 55 56[open,refpage='VkShaderEXT',desc='Opaque handle to a shader object',type='handles'] 57-- 58Shader objects are represented by sname:VkShaderEXT handles: 59 60include::{generated}/api/handles/VkShaderEXT.adoc[] 61-- 62 63[[shaders-objects-creation]] 64=== Shader Object Creation 65 66Shader objects may: be created from shader code provided as SPIR-V, or in an 67opaque, implementation-defined binary format specific to the physical 68device. 69 70[open,refpage='vkCreateShadersEXT',desc='Create one or more new shaders',type='protos'] 71-- 72To create one or more shader objects, call: 73 74include::{generated}/api/protos/vkCreateShadersEXT.adoc[] 75 76 * pname:device is the logical device that creates the shader objects. 77 * pname:createInfoCount is the length of the pname:pCreateInfos and 78 pname:pShaders arrays. 79 * pname:pCreateInfos is a pointer to an array of 80 slink:VkShaderCreateInfoEXT structures. 81 * pname:pAllocator controls host memory allocation as described in the 82 <<memory-allocation, Memory Allocation>> chapter. 83 * pname:pShaders is a pointer to an array of slink:VkShaderEXT handles in 84 which the resulting shader objects are returned. 85 86When this function returns, whether or not it succeeds, it is guaranteed 87that every element of pname:pShaders will have been overwritten by either 88dlink:VK_NULL_HANDLE or a valid sname:VkShaderEXT handle. 89 90This means that whenever shader creation fails, the application can: 91determine which shader the returned error pertains to by locating the first 92dlink:VK_NULL_HANDLE element in pname:pShaders. 93It also means that an application can: reliably clean up from a failed call 94by iterating over the pname:pShaders array and destroying every element that 95is not dlink:VK_NULL_HANDLE. 96 97.Valid Usage 98**** 99 * [[VUID-vkCreateShadersEXT-None-08400]] 100 The <<features-shaderObject, pname:shaderObject>> feature must: be 101 enabled 102 * [[VUID-vkCreateShadersEXT-pCreateInfos-08401]] 103 If pname:createInfoCount is 1, there must: be no element of 104 pname:pCreateInfos whose pname:flags member includes 105 ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT 106 * [[VUID-vkCreateShadersEXT-pCreateInfos-08402]] 107 If the pname:flags member of any element of pname:pCreateInfos includes 108 ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, the pname:flags member of all 109 other elements of pname:pCreateInfos whose pname:stage is 110 ename:VK_SHADER_STAGE_VERTEX_BIT, 111 ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, 112 ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, 113 ename:VK_SHADER_STAGE_GEOMETRY_BIT, or 114 ename:VK_SHADER_STAGE_FRAGMENT_BIT must: also include 115 ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT 116ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 117 * [[VUID-vkCreateShadersEXT-pCreateInfos-08403]] 118 If the pname:flags member of any element of pname:pCreateInfos includes 119 ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, the pname:flags member of all 120 other elements of pname:pCreateInfos whose pname:stage is 121 ename:VK_SHADER_STAGE_TASK_BIT_EXT or ename:VK_SHADER_STAGE_MESH_BIT_EXT 122 must: also include ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT 123 * [[VUID-vkCreateShadersEXT-pCreateInfos-08404]] 124 If the pname:flags member of any element of pname:pCreateInfos whose 125 pname:stage is ename:VK_SHADER_STAGE_TASK_BIT_EXT or 126 ename:VK_SHADER_STAGE_MESH_BIT_EXT includes 127 ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, there must: be no member of 128 pname:pCreateInfos whose pname:stage is ename:VK_SHADER_STAGE_VERTEX_BIT 129 and whose pname:flags member includes 130 ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT 131 * [[VUID-vkCreateShadersEXT-pCreateInfos-08405]] 132 If there is any element of pname:pCreateInfos whose pname:stage is 133 ename:VK_SHADER_STAGE_MESH_BIT_EXT and whose pname:flags member includes 134 both ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT and 135 ename:VK_SHADER_CREATE_NO_TASK_SHADER_BIT_EXT, there must: be no element 136 of pname:pCreateInfos whose pname:stage is 137 ename:VK_SHADER_STAGE_TASK_BIT_EXT and whose pname:flags member includes 138 ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT 139endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 140 * [[VUID-vkCreateShadersEXT-pCreateInfos-08409]] 141 For each element of pname:pCreateInfos whose pname:flags member includes 142 ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, if there is any other element 143 of pname:pCreateInfos whose pname:stage is logically later than the 144 pname:stage of the former and whose pname:flags member also includes 145 ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, the pname:nextStage of the 146 former must: be equal to the pname:stage of the element with the 147 logically earliest pname:stage following the pname:stage of the former 148 whose pname:flags member also includes 149 ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT 150 * [[VUID-vkCreateShadersEXT-pCreateInfos-08410]] 151 The pname:stage member of each element of pname:pCreateInfos whose 152 pname:flags member includes ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT 153 must: be unique 154 * [[VUID-vkCreateShadersEXT-pCreateInfos-08411]] 155 The pname:codeType member of all elements of pname:pCreateInfos whose 156 pname:flags member includes ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT 157 must: be the same 158 * [[VUID-vkCreateShadersEXT-pCreateInfos-08867]] 159 If pname:pCreateInfos contains elements with both 160 ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT and 161 ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, both elements' 162 pname:flags include ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, both 163 elements' pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and the 164 ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT stage's pname:pCode 165 contains an code:OpExecutionMode instruction specifying the type of 166 subdivision, it must: match the subdivision type specified in the 167 ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT stage 168 * [[VUID-vkCreateShadersEXT-pCreateInfos-08868]] 169 If pname:pCreateInfos contains elements with both 170 ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT and 171 ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, both elements' 172 pname:flags include ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, both 173 elements' pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and the 174 ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT stage's pname:pCode 175 contains an code:OpExecutionMode instruction specifying the orientation 176 of triangles, it must: match the triangle orientation specified in the 177 ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT stage 178 * [[VUID-vkCreateShadersEXT-pCreateInfos-08869]] 179 If pname:pCreateInfos contains elements with both 180 ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT and 181 ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, both elements' 182 pname:flags include ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, both 183 elements' pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and the 184 ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT stage's pname:pCode 185 contains an code:OpExecutionMode instruction specifying code:PointMode, 186 the ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT stage must: also 187 contain an code:OpExecutionMode instruction specifying code:PointMode 188 * [[VUID-vkCreateShadersEXT-pCreateInfos-08870]] 189 If pname:pCreateInfos contains elements with both 190 ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT and 191 ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, both elements' 192 pname:flags include ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, both 193 elements' pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and the 194 ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT stage's pname:pCode 195 contains an code:OpExecutionMode instruction specifying the spacing of 196 segments on the edges of tessellated primitives, it must: match the 197 segment spacing specified in the 198 ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT stage 199 * [[VUID-vkCreateShadersEXT-pCreateInfos-08871]] 200 If pname:pCreateInfos contains elements with both 201 ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT and 202 ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, both elements' 203 pname:flags include ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, both 204 elements' pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and the 205 ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT stage's pname:pCode 206 contains an code:OpExecutionMode instruction specifying the output patch 207 size, it must: match the output patch size specified in the 208 ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT stage 209**** 210 211include::{generated}/validity/protos/vkCreateShadersEXT.adoc[] 212-- 213 214[open,refpage='VkShaderCreateInfoEXT',desc='Structure specifying parameters of a newly created shader',type='structs'] 215-- 216:refpage: VkShaderCreateInfoEXT 217 218The sname:VkShaderCreateInfoEXT structure is defined as: 219 220include::{generated}/api/structs/VkShaderCreateInfoEXT.adoc[] 221 222 * pname:sType is a elink:VkStructureType value identifying this structure. 223 * pname:pNext is `NULL` or a pointer to a structure extending this 224 structure. 225 * pname:flags is a bitmask of elink:VkShaderCreateFlagBitsEXT describing 226 additional parameters of the shader. 227 * pname:stage is a elink:VkShaderStageFlagBits value specifying a single 228 shader stage. 229 * pname:nextStage is a bitmask of elink:VkShaderStageFlagBits specifying 230 zero or stages which may: be used as a logically next bound stage when 231 drawing with the shader bound. 232 * pname:codeType is a elink:VkShaderCodeTypeEXT value specifying the type 233 of the shader code pointed to be pname:pCode. 234 * pname:codeSize is the size in bytes of the shader code pointed to be 235 pname:pCode. 236 * pname:pCode is a pointer to the shader code to use to create the shader. 237 * pname:pName is a pointer to a null-terminated UTF-8 string specifying 238 the entry point name of the shader for this stage. 239 * pname:setLayoutCount is the number of descriptor set layouts pointed to 240 by pname:pSetLayouts. 241 * pname:pSetLayouts is a pointer to an array of 242 slink:VkDescriptorSetLayout objects used by the shader stage. 243 * pname:pushConstantRangeCount is the number of push constant ranges 244 pointed to by pname:pPushConstantRanges. 245 * pname:pPushConstantRanges is a pointer to an array of 246 slink:VkPushConstantRange structures used by the shader stage. 247 * pname:pSpecializationInfo is a pointer to a slink:VkSpecializationInfo 248 structure, as described in 249 <<pipelines-specialization-constants,Specialization Constants>>, or 250 `NULL`. 251 252.Valid Usage 253**** 254:prefixCondition: If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, 255include::{chapters}/commonvalidity/shader_create_spv_common.adoc[] 256 * [[VUID-VkShaderCreateInfoEXT-flags-08412]] 257 If pname:stage is not ename:VK_SHADER_STAGE_TASK_BIT_EXT, 258 ename:VK_SHADER_STAGE_MESH_BIT_EXT, ename:VK_SHADER_STAGE_VERTEX_BIT, 259 ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, 260 ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, 261 ename:VK_SHADER_STAGE_GEOMETRY_BIT, or 262 ename:VK_SHADER_STAGE_FRAGMENT_BIT, pname:flags must: not include 263 ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT 264ifdef::VK_KHR_fragment_shading_rate[] 265 * [[VUID-VkShaderCreateInfoEXT-flags-08486]] 266 If pname:stage is not ename:VK_SHADER_STAGE_FRAGMENT_BIT, pname:flags 267 must: not include 268 ename:VK_SHADER_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_EXT 269 * [[VUID-VkShaderCreateInfoEXT-flags-08487]] 270 If the <<features-attachmentFragmentShadingRate, 271 pname:attachmentFragmentShadingRate>> feature is not enabled, 272 pname:flags must: not include 273 ename:VK_SHADER_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_EXT 274endif::VK_KHR_fragment_shading_rate[] 275ifdef::VK_EXT_fragment_density_map[] 276 * [[VUID-VkShaderCreateInfoEXT-flags-08488]] 277 If pname:stage is not ename:VK_SHADER_STAGE_FRAGMENT_BIT, pname:flags 278 must: not include 279 ename:VK_SHADER_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT 280 * [[VUID-VkShaderCreateInfoEXT-flags-08489]] 281 If the <<features-fragmentDensityMap, pname:fragmentDensityMap>> feature 282 is not enabled, pname:flags must: not include 283 ename:VK_SHADER_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT 284endif::VK_EXT_fragment_density_map[] 285ifdef::VK_VERSION_1_1,VK_EXT_subgroup_size_control[] 286 * [[VUID-VkShaderCreateInfoEXT-flags-09404]] 287 If pname:flags includes 288 ename:VK_SHADER_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT, the 289 <<features-subgroupSizeControl, pname:subgroupSizeControl>> feature 290 must: be enabled 291 * [[VUID-VkShaderCreateInfoEXT-flags-09405]] 292 If pname:flags includes 293 ename:VK_SHADER_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT, the 294 <<features-computeFullSubgroups, pname:computeFullSubgroups>> feature 295 must: be enabled 296 * [[VUID-VkShaderCreateInfoEXT-flags-08992]] 297 If pname:flags includes 298 ename:VK_SHADER_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT, pname:stage must: 299 be 300ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 301 one of ename:VK_SHADER_STAGE_MESH_BIT_EXT, 302 ename:VK_SHADER_STAGE_TASK_BIT_EXT, or 303endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 304 ename:VK_SHADER_STAGE_COMPUTE_BIT 305endif::VK_VERSION_1_1,VK_EXT_subgroup_size_control[] 306ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 307 * [[VUID-VkShaderCreateInfoEXT-flags-08485]] 308 If pname:stage is not ename:VK_SHADER_STAGE_COMPUTE_BIT, pname:flags 309 must: not include ename:VK_SHADER_CREATE_DISPATCH_BASE_BIT_EXT 310endif::VK_VERSION_1_1,VK_KHR_device_group[] 311ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 312 * [[VUID-VkShaderCreateInfoEXT-flags-08414]] 313 If pname:stage is not ename:VK_SHADER_STAGE_MESH_BIT_EXT, pname:flags 314 must: not include ename:VK_SHADER_CREATE_NO_TASK_SHADER_BIT_EXT 315endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 316ifdef::VK_VERSION_1_1,VK_EXT_subgroup_size_control[] 317 * [[VUID-VkShaderCreateInfoEXT-flags-08416]] 318 If pname:flags includes both 319 ename:VK_SHADER_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT and 320 ename:VK_SHADER_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT, the local 321 workgroup size in the X dimension of the shader must: be a multiple of 322 <<limits-maxSubgroupSize,pname:maxSubgroupSize>> 323 * [[VUID-VkShaderCreateInfoEXT-flags-08417]] 324 If pname:flags includes 325 ename:VK_SHADER_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT but not 326 ename:VK_SHADER_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT and no 327 slink:VkShaderRequiredSubgroupSizeCreateInfoEXT structure is included in 328 the pname:pNext chain, the local workgroup size in the X dimension of 329 the shader must: be a multiple of 330 <<limits-subgroup-size,pname:subgroupSize>> 331endif::VK_VERSION_1_1,VK_EXT_subgroup_size_control[] 332 * [[VUID-VkShaderCreateInfoEXT-stage-08418]] 333 pname:stage must: not be ename:VK_SHADER_STAGE_ALL_GRAPHICS or 334 ename:VK_SHADER_STAGE_ALL 335 * [[VUID-VkShaderCreateInfoEXT-stage-08419]] 336 If the <<features-tessellationShader, pname:tessellationShader>> feature 337 is not enabled, pname:stage must: not be 338 ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or 339 ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT 340 * [[VUID-VkShaderCreateInfoEXT-stage-08420]] 341 If the <<features-geometryShader, pname:geometryShader>> feature is not 342 enabled, pname:stage must: not be ename:VK_SHADER_STAGE_GEOMETRY_BIT 343ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 344 * [[VUID-VkShaderCreateInfoEXT-stage-08421]] 345 If the <<features-taskShader, pname:taskShader>> feature is not enabled, 346 pname:stage must: not be ename:VK_SHADER_STAGE_TASK_BIT_EXT 347 * [[VUID-VkShaderCreateInfoEXT-stage-08422]] 348 If the <<features-meshShader, pname:meshShader>> feature is not enabled, 349 pname:stage must: not be ename:VK_SHADER_STAGE_MESH_BIT_EXT 350endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 351ifdef::VK_HUAWEI_subpass_shading[] 352 * [[VUID-VkShaderCreateInfoEXT-stage-08425]] 353 pname:stage must: not be 354 ename:VK_SHADER_STAGE_SUBPASS_SHADING_BIT_HUAWEI 355endif::VK_HUAWEI_subpass_shading[] 356ifdef::VK_HUAWEI_cluster_culling_shader[] 357 * [[VUID-VkShaderCreateInfoEXT-stage-08426]] 358 pname:stage must: not be 359 ename:VK_SHADER_STAGE_CLUSTER_CULLING_BIT_HUAWEI 360endif::VK_HUAWEI_cluster_culling_shader[] 361 * [[VUID-VkShaderCreateInfoEXT-nextStage-08427]] 362 If pname:stage is ename:VK_SHADER_STAGE_VERTEX_BIT, pname:nextStage 363 must: not include any bits other than 364 ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, 365 ename:VK_SHADER_STAGE_GEOMETRY_BIT, and 366 ename:VK_SHADER_STAGE_FRAGMENT_BIT 367 * [[VUID-VkShaderCreateInfoEXT-nextStage-08428]] 368 If the <<features-tessellationShader, pname:tessellationShader>> feature 369 is not enabled, pname:nextStage must: not include 370 ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or 371 ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT 372 * [[VUID-VkShaderCreateInfoEXT-nextStage-08429]] 373 If the <<features-geometryShader, pname:geometryShader>> feature is not 374 enabled, pname:nextStage must: not include 375 ename:VK_SHADER_STAGE_GEOMETRY_BIT 376 * [[VUID-VkShaderCreateInfoEXT-nextStage-08430]] 377 If pname:stage is ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, 378 pname:nextStage must: not include any bits other than 379 ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT 380 * [[VUID-VkShaderCreateInfoEXT-nextStage-08431]] 381 If pname:stage is ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, 382 pname:nextStage must: not include any bits other than 383 ename:VK_SHADER_STAGE_GEOMETRY_BIT and 384 ename:VK_SHADER_STAGE_FRAGMENT_BIT 385 * [[VUID-VkShaderCreateInfoEXT-nextStage-08433]] 386 If pname:stage is ename:VK_SHADER_STAGE_GEOMETRY_BIT, pname:nextStage 387 must: not include any bits other than ename:VK_SHADER_STAGE_FRAGMENT_BIT 388 * [[VUID-VkShaderCreateInfoEXT-nextStage-08434]] 389 If pname:stage is ename:VK_SHADER_STAGE_FRAGMENT_BIT or 390 ename:VK_SHADER_STAGE_COMPUTE_BIT, pname:nextStage must: be 0 391ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 392 * [[VUID-VkShaderCreateInfoEXT-nextStage-08435]] 393 If pname:stage is ename:VK_SHADER_STAGE_TASK_BIT_EXT, pname:nextStage 394 must: not include any bits other than ename:VK_SHADER_STAGE_MESH_BIT_EXT 395 * [[VUID-VkShaderCreateInfoEXT-nextStage-08436]] 396 If pname:stage is ename:VK_SHADER_STAGE_MESH_BIT_EXT, pname:nextStage 397 must: not include any bits other than ename:VK_SHADER_STAGE_FRAGMENT_BIT 398endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 399 * [[VUID-VkShaderCreateInfoEXT-pName-08440]] 400 If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, pname:pName 401 must: be the name of an code:OpEntryPoint in pname:pCode with an 402 execution model that matches pname:stage 403 * [[VUID-VkShaderCreateInfoEXT-pCode-08492]] 404 If pname:codeType is ename:VK_SHADER_CODE_TYPE_BINARY_EXT, pname:pCode 405 must: be aligned to `16` bytes 406 * [[VUID-VkShaderCreateInfoEXT-pCode-08493]] 407 If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, pname:pCode 408 must: be aligned to `4` bytes 409 * [[VUID-VkShaderCreateInfoEXT-pCode-08448]] 410 If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and the 411 identified entry point includes any variable in its interface that is 412 declared with the code:ClipDistance code:BuiltIn decoration, that 413 variable must: not have an array size greater than 414 sname:VkPhysicalDeviceLimits::pname:maxClipDistances 415 * [[VUID-VkShaderCreateInfoEXT-pCode-08449]] 416 If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and the 417 identified entry point includes any variable in its interface that is 418 declared with the code:CullDistance code:BuiltIn decoration, that 419 variable must: not have an array size greater than 420 sname:VkPhysicalDeviceLimits::pname:maxCullDistances 421 * [[VUID-VkShaderCreateInfoEXT-pCode-08450]] 422 If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and the 423 identified entry point includes any variables in its interface that are 424 declared with the code:ClipDistance or code:CullDistance code:BuiltIn 425 decoration, those variables must: not have array sizes which sum to more 426 than sname:VkPhysicalDeviceLimits::pname:maxCombinedClipAndCullDistances 427 * [[VUID-VkShaderCreateInfoEXT-pCode-08451]] 428 If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and the 429 identified entry point includes any variable in its interface that is 430 declared with the code:SampleMask code:BuiltIn decoration, that variable 431 must: not have an array size greater than 432 sname:VkPhysicalDeviceLimits::pname:maxSampleMaskWords 433 * [[VUID-VkShaderCreateInfoEXT-pCode-08452]] 434 If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and 435 pname:stage is ename:VK_SHADER_STAGE_VERTEX_BIT, the identified entry 436 point must: not include any input variable in its interface that is 437 decorated with code:CullDistance 438 * [[VUID-VkShaderCreateInfoEXT-pCode-08453]] 439 If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and 440 pname:stage is ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or 441 ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, and the identified 442 entry point has an code:OpExecutionMode instruction specifying a patch 443 size with code:OutputVertices, the patch size must: be greater than `0` 444 and less than or equal to 445 sname:VkPhysicalDeviceLimits::pname:maxTessellationPatchSize 446 * [[VUID-VkShaderCreateInfoEXT-pCode-08454]] 447 If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and 448 pname:stage is ename:VK_SHADER_STAGE_GEOMETRY_BIT, the identified entry 449 point must: have an code:OpExecutionMode instruction specifying a 450 maximum output vertex count that is greater than `0` and less than or 451 equal to sname:VkPhysicalDeviceLimits::pname:maxGeometryOutputVertices 452 * [[VUID-VkShaderCreateInfoEXT-pCode-08455]] 453 If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and 454 pname:stage is ename:VK_SHADER_STAGE_GEOMETRY_BIT, the identified entry 455 point must: have an code:OpExecutionMode instruction specifying an 456 invocation count that is greater than `0` and less than or equal to 457 sname:VkPhysicalDeviceLimits::pname:maxGeometryShaderInvocations 458 * [[VUID-VkShaderCreateInfoEXT-pCode-08456]] 459 If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and 460 pname:stage is a 461 <<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader 462 stage>>, and the identified entry point writes to code:Layer for any 463 primitive, it must: write the same value to code:Layer for all vertices 464 of a given primitive 465 * [[VUID-VkShaderCreateInfoEXT-pCode-08457]] 466 If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and 467 pname:stage is a 468 <<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader 469 stage>>, and the identified entry point writes to code:ViewportIndex for 470 any primitive, it must: write the same value to code:ViewportIndex for 471 all vertices of a given primitive 472 * [[VUID-VkShaderCreateInfoEXT-pCode-08458]] 473 If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and 474 pname:stage is ename:VK_SHADER_STAGE_FRAGMENT_BIT, the identified entry 475 point must: not include any output variables in its interface decorated 476 with code:CullDistance 477 * [[VUID-VkShaderCreateInfoEXT-pCode-08459]] 478 If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and 479 pname:stage is ename:VK_SHADER_STAGE_FRAGMENT_BIT, and the identified 480 entry point writes to code:FragDepth in any execution path, all 481 execution paths that are not exclusive to helper invocations must: 482 either discard the fragment, or write or initialize the value of 483 code:FragDepth 484 * [[VUID-VkShaderCreateInfoEXT-pCode-08460]] 485 If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, the shader 486 code in pname:pCode must: be valid as described by the 487 <<spirv-spec,Khronos SPIR-V Specification>> after applying the 488 specializations provided in pname:pSpecializationInfo, if any, and then 489 converting all specialization constants into fixed constants 490 * [[VUID-VkShaderCreateInfoEXT-codeType-08872]] 491 If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and 492 pname:stage is ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, 493 pname:pCode must: contain an code:OpExecutionMode instruction specifying 494 the type of subdivision 495 * [[VUID-VkShaderCreateInfoEXT-codeType-08873]] 496 If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and 497 pname:stage is ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, 498 pname:pCode must: contain an code:OpExecutionMode instruction specifying 499 the orientation of triangles generated by the tessellator 500 * [[VUID-VkShaderCreateInfoEXT-codeType-08874]] 501 If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and 502 pname:stage is ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, 503 pname:pCode must: contain an code:OpExecutionMode instruction specifying 504 the spacing of segments on the edges of tessellated primitives 505 * [[VUID-VkShaderCreateInfoEXT-codeType-08875]] 506 If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and 507 pname:stage is ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, 508 pname:pCode must: contain an code:OpExecutionMode instruction specifying 509 the output patch size 510**** 511 512include::{generated}/validity/structs/VkShaderCreateInfoEXT.adoc[] 513-- 514 515[open,refpage='VkShaderCreateFlagsEXT',desc='Bitmask of VkShaderCreateFlagBitsEXT',type='flags'] 516-- 517include::{generated}/api/flags/VkShaderCreateFlagsEXT.adoc[] 518 519tname:VkShaderCreateFlagsEXT is a bitmask type for setting a mask of zero or 520more elink:VkShaderCreateFlagBitsEXT. 521-- 522 523[open,refpage='VkShaderCreateFlagBitsEXT',desc='Bitmask controlling how a shader object is created',type='enums'] 524-- 525Possible values of the pname:flags member of slink:VkShaderCreateInfoEXT 526specifying how a shader object is created, are: 527 528include::{generated}/api/enums/VkShaderCreateFlagBitsEXT.adoc[] 529 530 * ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT specifies that a shader is 531 linked to all other shaders created in the same flink:vkCreateShadersEXT 532 call whose slink:VkShaderCreateInfoEXT structures' pname:flags include 533 ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT. 534ifdef::VK_VERSION_1_1,VK_EXT_subgroup_size_control[] 535 * ename:VK_SHADER_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT specifies 536 that the <<interfaces-builtin-variables-sgs, code:SubgroupSize>> may: 537 vary in a 538ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[task, mesh, or] 539 compute shader. 540 * ename:VK_SHADER_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT specifies that the 541 subgroup sizes must: be launched with all invocations active in a 542ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[task, mesh, or] 543 compute shader. 544endif::VK_VERSION_1_1,VK_EXT_subgroup_size_control[] 545ifdef::VK_EXT_mesh_shader,VK_NV_mesh_shader[] 546 * ename:VK_SHADER_CREATE_NO_TASK_SHADER_BIT_EXT specifies that a mesh 547 shader must: only be used without a task shader. 548 Otherwise, the mesh shader must: only be used with a task shader. 549endif::VK_EXT_mesh_shader,VK_NV_mesh_shader[] 550ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 551 * ename:VK_SHADER_CREATE_DISPATCH_BASE_BIT_EXT specifies that a compute 552 shader can: be used with flink:vkCmdDispatchBase with a non-zero base 553 workgroup. 554endif::VK_VERSION_1_1,VK_KHR_device_group[] 555ifdef::VK_KHR_fragment_shading_rate[] 556 * ename:VK_SHADER_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_EXT 557 specifies that a fragment shader can: be used with a fragment shading 558 rate attachment. 559endif::VK_KHR_fragment_shading_rate[] 560ifdef::VK_EXT_fragment_density_map[] 561 * ename:VK_SHADER_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT specifies 562 that a fragment shader can: be used with a fragment density map 563 attachment. 564endif::VK_EXT_fragment_density_map[] 565-- 566 567ifdef::VK_KHR_fragment_shading_rate,VK_EXT_fragment_density_map[] 568[NOTE] 569.Note 570==== 571The behavior of 572ifdef::VK_KHR_fragment_shading_rate[] 573ename:VK_SHADER_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_EXT 574endif::VK_KHR_fragment_shading_rate[] 575ifdef::VK_KHR_fragment_shading_rate+VK_EXT_fragment_density_map[and] 576ifdef::VK_EXT_fragment_density_map[] 577ename:VK_SHADER_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT 578endif::VK_EXT_fragment_density_map[] 579differs subtly from the behavior of 580ifdef::VK_KHR_fragment_shading_rate[] 581ename:VK_PIPELINE_CREATE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR 582endif::VK_KHR_fragment_shading_rate[] 583ifdef::VK_KHR_fragment_shading_rate+VK_EXT_fragment_density_map[and] 584ifdef::VK_EXT_fragment_density_map[] 585ename:VK_PIPELINE_CREATE_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT 586endif::VK_EXT_fragment_density_map[] 587in that the shader bit allows, but does not require the shader to be used 588with that type of attachment. 589This means that the application need not create multiple shaders when it 590does not know in advance whether the shader will be used with or without the 591attachment type, or when it needs the same shader to be compatible with 592usage both with and without. 593This may: come at some performance cost on some implementations, so 594applications should: still only set bits that are actually necessary. 595==== 596endif::VK_KHR_fragment_shading_rate,VK_EXT_fragment_density_map[] 597 598[open,refpage='VkShaderCodeTypeEXT',desc='Indicate a shader code type',type='enums'] 599-- 600Shader objects can: be created using different types of shader code. 601Possible values of slink:VkShaderCreateInfoEXT::pname:codeType, are: 602 603include::{generated}/api/enums/VkShaderCodeTypeEXT.adoc[] 604 605 * ename:VK_SHADER_CODE_TYPE_BINARY_EXT specifies shader code in an opaque, 606 implementation-defined binary format specific to the physical device. 607 * ename:VK_SHADER_CODE_TYPE_SPIRV_EXT specifies shader code in SPIR-V 608 format. 609-- 610 611[[shaders-objects-binary-code]] 612=== Binary Shader Code 613 614[open,refpage='vkGetShaderBinaryDataEXT',desc='Get the binary shader code from a shader object',type='protos'] 615-- 616Binary shader code can: be retrieved from a shader object using the command: 617 618include::{generated}/api/protos/vkGetShaderBinaryDataEXT.adoc[] 619 620 * pname:device is the logical device that shader object was created from. 621 * pname:shader is the shader object to retrieve binary shader code from. 622 * pname:pDataSize is a pointer to a code:size_t value related to the size 623 of the binary shader code, as described below. 624 * pname:pData is either `NULL` or a pointer to a buffer. 625 626If pname:pData is `NULL`, then the size of the binary shader code of the 627shader object, in bytes, is returned in pname:pDataSize. 628Otherwise, pname:pDataSize must: point to a variable set by the user to the 629size of the buffer, in bytes, pointed to by pname:pData, and on return the 630variable is overwritten with the amount of data actually written to 631pname:pData. 632If pname:pDataSize is less than the size of the binary shader code, nothing 633is written to pname:pData, and ename:VK_INCOMPLETE will be returned instead 634of ename:VK_SUCCESS. 635 636[NOTE] 637.Note 638==== 639The behavior of this command when pname:pDataSize is too small differs from 640how some other getter-type commands work in Vulkan. 641Because shader binary data is only usable in its entirety, it would never be 642useful for the implementation to return partial data. 643Because of this, nothing is written to pname:pData unless pname:pDataSize is 644large enough to fit the data it its entirety. 645==== 646 647Binary shader code retrieved using fname:vkGetShaderBinaryDataEXT can: be 648passed to a subsequent call to flink:vkCreateShadersEXT on a compatible 649physical device by specifying ename:VK_SHADER_CODE_TYPE_BINARY_EXT in the 650pname:codeType member of sname:VkShaderCreateInfoEXT. 651 652The shader code returned by repeated calls to this function with the same 653sname:VkShaderEXT is guaranteed to be invariant for the lifetime of the 654sname:VkShaderEXT object. 655 656.Valid Usage 657**** 658 * [[VUID-vkGetShaderBinaryDataEXT-None-08461]] 659 The <<features-shaderObject,pname:shaderObject>> feature must: be 660 enabled 661 * [[VUID-vkGetShaderBinaryDataEXT-None-08499]] 662 If pname:pData is not `NULL`, it must: be aligned to `16` bytes 663**** 664 665include::{generated}/validity/protos/vkGetShaderBinaryDataEXT.adoc[] 666-- 667 668[[shaders-objects-binary-compatibility]] 669=== Binary Shader Compatibility 670 671Binary shader compatibility means that binary shader code returned from a 672call to flink:vkGetShaderBinaryDataEXT can: be passed to a later call to 673flink:vkCreateShadersEXT, potentially on a different logical and/or physical 674device, and that this will result in the successful creation of a shader 675object functionally equivalent to the shader object that the code was 676originally queried from. 677 678Binary shader code queried from flink:vkGetShaderBinaryDataEXT is not 679guaranteed to be compatible across all devices, but implementations are 680required to provide some compatibility guarantees. 681Applications may: determine binary shader compatibility using either (or 682both) of two mechanisms. 683 684Guaranteed compatibility of shader binaries is expressed through a 685combination of the pname:shaderBinaryUUID and pname:shaderBinaryVersion 686members of the slink:VkPhysicalDeviceShaderObjectPropertiesEXT structure 687queried from a physical device. 688Binary shaders retrieved from a physical device with a certain 689pname:shaderBinaryUUID are guaranteed to be compatible with all other 690physical devices reporting the same pname:shaderBinaryUUID and the same or 691higher pname:shaderBinaryVersion. 692 693Whenever a new version of an implementation incorporates any changes that 694affect the output of flink:vkGetShaderBinaryDataEXT, the implementation 695should: either increment pname:shaderBinaryVersion if binary shader code 696retrieved from older versions remains compatible with the new 697implementation, or else replace pname:shaderBinaryUUID with a new value if 698backward compatibility has been broken. 699Binary shader code queried from a device with a matching 700pname:shaderBinaryUUID and lower pname:shaderBinaryVersion relative to the 701device on which flink:vkCreateShadersEXT is being called may: be suboptimal 702for the new device in ways that do not change shader functionality, but it 703is still guaranteed to be usable to successfully create the shader 704object(s). 705 706[NOTE] 707.Note 708==== 709Implementations are encouraged to share pname:shaderBinaryUUID between 710devices and driver versions to the maximum extent their hardware naturally 711allows, and are *strongly* discouraged from ever changing the 712pname:shaderBinaryUUID for the same hardware except unless absolutely 713necessary. 714==== 715 716In addition to the shader compatibility guarantees described above, it is 717valid for an application to call flink:vkCreateShadersEXT with binary shader 718code created on a device with a different or unknown pname:shaderBinaryUUID 719and/or higher pname:shaderBinaryVersion. 720In this case, the implementation may: use any unspecified means of its 721choosing to determine whether the provided binary shader code is usable. 722If it is, the flink:vkCreateShadersEXT call must: return ename:VK_SUCCESS, 723and the created shader object is guaranteed to be valid. 724Otherwise, in the absence of some other error, the flink:vkCreateShadersEXT 725call must: return ename:VK_ERROR_INCOMPATIBLE_SHADER_BINARY_EXT to indicate 726that the provided binary shader code is not compatible with the device. 727 728[[shaders-objects-binding]] 729=== Binding Shader Objects 730 731[open,refpage='vkCmdBindShadersEXT',desc='Bind shader objects to a command buffer',type='protos'] 732-- 733Once shader objects have been created, they can: be bound to the command 734buffer using the command: 735 736include::{generated}/api/protos/vkCmdBindShadersEXT.adoc[] 737 738 * pname:commandBuffer is the command buffer that the shader object will be 739 bound to. 740 * pname:stageCount is the length of the pname:pStages and pname:pShaders 741 arrays. 742 * pname:pStages is a pointer to an array of elink:VkShaderStageFlagBits 743 values specifying one stage per array index that is affected by the 744 corresponding value in the pname:pShaders array. 745 * pname:pShaders is a pointer to an array of sname:VkShaderEXT handles 746 and/or dlink:VK_NULL_HANDLE values describing the shader binding 747 operations to be performed on each stage in pname:pStages. 748 749When binding linked shaders, an application may: bind them in any 750combination of one or more calls to fname:vkCmdBindShadersEXT (i.e., shaders 751that were created linked together do not need to be bound in the same 752fname:vkCmdBindShadersEXT call). 753 754Any shader object bound to a particular stage may: be unbound by setting its 755value in pname:pShaders to dlink:VK_NULL_HANDLE. 756If pname:pShaders is `NULL`, fname:vkCmdBindShadersEXT behaves as if 757pname:pShaders was an array of pname:stageCount dlink:VK_NULL_HANDLE values 758(i.e., any shaders bound to the stages specified in pname:pStages are 759unbound). 760 761.Valid Usage 762**** 763 * [[VUID-vkCmdBindShadersEXT-None-08462]] 764 The <<features-shaderObject,pname:shaderObject>> feature must: be 765 enabled 766 * [[VUID-vkCmdBindShadersEXT-pStages-08463]] 767 Every element of pname:pStages must: be unique 768 * [[VUID-vkCmdBindShadersEXT-pStages-08464]] 769 pname:pStages must: not contain ename:VK_SHADER_STAGE_ALL_GRAPHICS or 770 ename:VK_SHADER_STAGE_ALL 771ifdef::VK_KHR_ray_tracing_pipeline,VK_NV_ray_tracing[] 772 * [[VUID-vkCmdBindShadersEXT-pStages-08465]] 773 pname:pStages must: not contain ename:VK_SHADER_STAGE_RAYGEN_BIT_KHR, 774 ename:VK_SHADER_STAGE_ANY_HIT_BIT_KHR, 775 ename:VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR, 776 ename:VK_SHADER_STAGE_MISS_BIT_KHR, 777 ename:VK_SHADER_STAGE_INTERSECTION_BIT_KHR, or 778 ename:VK_SHADER_STAGE_CALLABLE_BIT_KHR 779endif::VK_KHR_ray_tracing_pipeline,VK_NV_ray_tracing[] 780ifdef::VK_HUAWEI_subpass_shading[] 781 * [[VUID-vkCmdBindShadersEXT-pStages-08467]] 782 pname:pStages must: not contain 783 ename:VK_SHADER_STAGE_SUBPASS_SHADING_BIT_HUAWEI 784endif::VK_HUAWEI_subpass_shading[] 785ifdef::VK_HUAWEI_cluster_culling_shader[] 786 * [[VUID-vkCmdBindShadersEXT-pStages-08468]] 787 pname:pStages must: not contain 788 ename:VK_SHADER_STAGE_CLUSTER_CULLING_BIT_HUAWEI 789endif::VK_HUAWEI_cluster_culling_shader[] 790 * [[VUID-vkCmdBindShadersEXT-pShaders-08469]] 791 For each element of pname:pStages, if pname:pShaders is not `NULL`, and 792 the element of the pname:pShaders array with the same index is not 793 dlink:VK_NULL_HANDLE, it must: have been created with a pname:stage 794 equal to the corresponding element of pname:pStages 795ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 796 * [[VUID-vkCmdBindShadersEXT-pShaders-08470]] 797 If pname:pStages contains both ename:VK_SHADER_STAGE_TASK_BIT_EXT and 798 ename:VK_SHADER_STAGE_VERTEX_BIT, and pname:pShaders is not `NULL`, and 799 the same index in pname:pShaders as ename:VK_SHADER_STAGE_TASK_BIT_EXT 800 in pname:pStages is not dlink:VK_NULL_HANDLE, the same index in 801 pname:pShaders as ename:VK_SHADER_STAGE_VERTEX_BIT in pname:pStages 802 must: be dlink:VK_NULL_HANDLE 803 * [[VUID-vkCmdBindShadersEXT-pShaders-08471]] 804 If pname:pStages contains both ename:VK_SHADER_STAGE_MESH_BIT_EXT and 805 ename:VK_SHADER_STAGE_VERTEX_BIT, and pname:pShaders is not `NULL`, and 806 the same index in pname:pShaders as ename:VK_SHADER_STAGE_MESH_BIT_EXT 807 in pname:pStages is not dlink:VK_NULL_HANDLE, the same index in 808 pname:pShaders as ename:VK_SHADER_STAGE_VERTEX_BIT in pname:pStages 809 must: be dlink:VK_NULL_HANDLE 810endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 811 * [[VUID-vkCmdBindShadersEXT-pShaders-08474]] 812 If the <<features-tessellationShader, pname:tessellationShader>> feature 813 is not enabled, and pname:pStages contains 814 ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or 815 ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, and pname:pShaders is 816 not `NULL`, the same index or indices in pname:pShaders must: be 817 dlink:VK_NULL_HANDLE 818 * [[VUID-vkCmdBindShadersEXT-pShaders-08475]] 819 If the <<features-geometryShader, pname:geometryShader>> feature is not 820 enabled, and pname:pStages contains ename:VK_SHADER_STAGE_GEOMETRY_BIT, 821 and pname:pShaders is not `NULL`, the same index in pname:pShaders must: 822 be dlink:VK_NULL_HANDLE 823ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 824 * [[VUID-vkCmdBindShadersEXT-pShaders-08490]] 825 If the <<features-taskShader, pname:taskShader>> feature is not enabled, 826 and pname:pStages contains ename:VK_SHADER_STAGE_TASK_BIT_EXT, and 827 pname:pShaders is not `NULL`, the same index in pname:pShaders must: be 828 dlink:VK_NULL_HANDLE 829 * [[VUID-vkCmdBindShadersEXT-pShaders-08491]] 830 If the <<features-meshShader, pname:meshShader>> feature is not enabled, 831 and pname:pStages contains ename:VK_SHADER_STAGE_MESH_BIT_EXT, and 832 pname:pShaders is not `NULL`, the same index in pname:pShaders must: be 833 dlink:VK_NULL_HANDLE 834endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 835 * [[VUID-vkCmdBindShadersEXT-pShaders-08476]] 836 If pname:pStages contains ename:VK_SHADER_STAGE_COMPUTE_BIT, the 837 sname:VkCommandPool that pname:commandBuffer was allocated from must: 838 support compute operations 839 * [[VUID-vkCmdBindShadersEXT-pShaders-08477]] 840 If pname:pStages contains ename:VK_SHADER_STAGE_VERTEX_BIT, 841 ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, 842 ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, 843 ename:VK_SHADER_STAGE_GEOMETRY_BIT, or 844 ename:VK_SHADER_STAGE_FRAGMENT_BIT, the sname:VkCommandPool that 845 pname:commandBuffer was allocated from must: support graphics operations 846ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 847 * [[VUID-vkCmdBindShadersEXT-pShaders-08478]] 848 If pname:pStages contains ename:VK_SHADER_STAGE_MESH_BIT_EXT or 849 ename:VK_SHADER_STAGE_TASK_BIT_EXT, the sname:VkCommandPool that 850 pname:commandBuffer was allocated from must: support graphics operations 851endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 852**** 853 854include::{generated}/validity/protos/vkCmdBindShadersEXT.adoc[] 855-- 856 857[[shaders-objects-state]] 858=== Setting State 859 860Whenever shader objects are used to issue drawing commands, the appropriate 861<<pipelines-dynamic-state, dynamic state>> setting commands must: have been 862called to set the relevant state in the command buffer prior to drawing: 863 864 * flink:vkCmdSetViewportWithCount 865 * flink:vkCmdSetScissorWithCount 866 * flink:vkCmdSetRasterizerDiscardEnable 867 868ifdef::VK_EXT_mesh_shader,VK_NV_mesh_shader[] 869If a shader is bound to the ename:VK_SHADER_STAGE_VERTEX_BIT stage, the 870following commands must: have been called in the command buffer prior to 871drawing: 872endif::VK_EXT_mesh_shader,VK_NV_mesh_shader[] 873 874 * flink:vkCmdSetVertexInputEXT 875 * flink:vkCmdSetPrimitiveTopology 876 * flink:vkCmdSetPatchControlPointsEXT, if pname:primitiveTopology is 877 ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST 878 * flink:vkCmdSetPrimitiveRestartEnable 879 880If a shader is bound to the 881ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT stage, the following 882command must: have been called in the command buffer prior to drawing: 883 884 * flink:vkCmdSetTessellationDomainOriginEXT 885 886If pname:rasterizerDiscardEnable is ename:VK_FALSE, the following commands 887must: have been called in the command buffer prior to drawing: 888 889 * flink:vkCmdSetRasterizationSamplesEXT 890 * flink:vkCmdSetSampleMaskEXT 891 * flink:vkCmdSetAlphaToCoverageEnableEXT 892 * flink:vkCmdSetAlphaToOneEnableEXT, if the <<features-alphaToOne, 893 alphaToOne>> feature is enabled on the device 894 * flink:vkCmdSetPolygonModeEXT 895 * flink:vkCmdSetLineWidth, if pname:polygonMode is 896 ename:VK_POLYGON_MODE_LINE, or if 897ifdef::VK_EXT_mesh_shader,VK_NV_mesh_shader[] 898 a shader is bound to the ename:VK_SHADER_STAGE_VERTEX_BIT stage and 899endif::VK_EXT_mesh_shader,VK_NV_mesh_shader[] 900 pname:primitiveTopology is a line topology, or if a shader which outputs 901 line primitives is bound to the 902 ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT or 903 ename:VK_SHADER_STAGE_GEOMETRY_BIT stage 904 * flink:vkCmdSetCullMode 905 * flink:vkCmdSetFrontFace 906 * flink:vkCmdSetDepthTestEnable 907 * flink:vkCmdSetDepthWriteEnable 908 * flink:vkCmdSetDepthCompareOp, if pname:depthTestEnable is ename:VK_TRUE 909 * flink:vkCmdSetDepthBoundsTestEnable, if the <<features-depthBounds, 910 depthBounds>> feature is enabled on the device 911 * flink:vkCmdSetDepthBounds, if pname:depthBoundsTestEnable is 912 ename:VK_TRUE 913 * flink:vkCmdSetDepthBiasEnable 914ifdef::VK_EXT_depth_bias_control[] 915 * flink:vkCmdSetDepthBias or flink:vkCmdSetDepthBias2EXT, 916endif::VK_EXT_depth_bias_control[] 917ifndef::VK_EXT_depth_bias_control[] 918 * flink:vkCmdSetDepthBias, 919endif::VK_EXT_depth_bias_control[] 920 if pname:depthBiasEnable is ename:VK_TRUE 921 * flink:vkCmdSetDepthClampEnableEXT, if the <<features-depthClamp, 922 depthClamp>> feature is enabled on the device 923 * flink:vkCmdSetStencilTestEnable 924 * flink:vkCmdSetStencilOp, if pname:stencilTestEnable is ename:VK_TRUE 925 * flink:vkCmdSetStencilCompareMask, if pname:stencilTestEnable is 926 ename:VK_TRUE 927 * flink:vkCmdSetStencilWriteMask, if pname:stencilTestEnable is 928 ename:VK_TRUE 929 * flink:vkCmdSetStencilReference, if pname:stencilTestEnable is 930 ename:VK_TRUE 931 932If a shader is bound to the ename:VK_SHADER_STAGE_FRAGMENT_BIT stage, and 933pname:rasterizerDiscardEnable is ename:VK_FALSE, the following commands 934must: have been called in the command buffer prior to drawing: 935 936 * flink:vkCmdSetLogicOpEnableEXT, if the <<features-logicOp, 937 pname:logicOp>> feature is enabled on the device 938 * flink:vkCmdSetLogicOpEXT, if pname:logicOpEnable is ename:VK_TRUE 939 * flink:vkCmdSetColorBlendEnableEXT, with values set for every color 940 attachment in the render pass instance active at draw time 941ifdef::VK_EXT_blend_operation_advanced[] 942 * flink:vkCmdSetColorBlendEquationEXT or 943 flink:vkCmdSetColorBlendAdvancedEXT, 944endif::VK_EXT_blend_operation_advanced[] 945ifndef::VK_EXT_blend_operation_advanced[] 946 * flink:vkCmdSetColorBlendEquationEXT, 947endif::VK_EXT_blend_operation_advanced[] 948 for every attachment whose index in pname:pColorBlendEnables is a 949 pointer to a value of ename:VK_TRUE 950 * flink:vkCmdSetBlendConstants, if any index in pname:pColorBlendEnables 951 is ename:VK_TRUE, and the same index in pname:pColorBlendEquations is a 952 sname:VkColorBlendEquationEXT structure with any elink:VkBlendFactor 953 member with a value of ename:VK_BLEND_FACTOR_CONSTANT_COLOR, 954 ename:VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_COLOR, 955 ename:VK_BLEND_FACTOR_CONSTANT_ALPHA, or 956 ename:VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA 957 * flink:vkCmdSetColorWriteMaskEXT 958 959ifdef::VK_KHR_fragment_shading_rate[] 960If the <<features-pipelineFragmentShadingRate, 961pname:pipelineFragmentShadingRate>> feature is enabled on the device, and a 962shader is bound to the ename:VK_SHADER_STAGE_FRAGMENT_BIT stage, and 963pname:rasterizerDiscardEnable is ename:VK_FALSE, the following command must: 964have been called in the command buffer prior to drawing: 965 966 * flink:vkCmdSetFragmentShadingRateKHR 967endif::VK_KHR_fragment_shading_rate[] 968 969ifdef::VK_EXT_transform_feedback[] 970If the <<features-geometryStreams, pname:geometryStreams>> feature is 971enabled on the device, and a shader is bound to the 972ename:VK_SHADER_STAGE_GEOMETRY_BIT stage, the following command must: have 973been called in the command buffer prior to drawing: 974 975 * flink:vkCmdSetRasterizationStreamEXT 976endif::VK_EXT_transform_feedback[] 977 978ifdef::VK_EXT_discard_rectangles[] 979If the `apiext:VK_EXT_discard_rectangles` extension is enabled on the 980device, and pname:rasterizerDiscardEnable is ename:VK_FALSE, the following 981commands must: have been called in the command buffer prior to drawing: 982 983 * flink:vkCmdSetDiscardRectangleEnableEXT 984 * flink:vkCmdSetDiscardRectangleModeEXT, if `discardRectangleEnable` is 985 ename:VK_TRUE 986 * flink:vkCmdSetDiscardRectangleEXT, if `discardRectangleEnable` is 987 ename:VK_TRUE 988endif::VK_EXT_discard_rectangles[] 989 990ifdef::VK_EXT_conservative_rasterization[] 991If `apiext:VK_EXT_conservative_rasterization` extension is enabled on the 992device, and pname:rasterizerDiscardEnable is ename:VK_FALSE, the following 993commands must: have been called in the command buffer prior to drawing: 994 995 * flink:vkCmdSetConservativeRasterizationModeEXT 996 * flink:vkCmdSetExtraPrimitiveOverestimationSizeEXT, if 997 pname:conservativeRasterizationMode is 998 ename:VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT 999endif::VK_EXT_conservative_rasterization[] 1000 1001ifdef::VK_EXT_depth_clip_enable[] 1002If the <<features-depthClipEnable, pname:depthClipEnable>> feature is 1003enabled on the device, the following command must: have been called in the 1004command buffer prior to drawing: 1005 1006 * flink:vkCmdSetDepthClipEnableEXT 1007endif::VK_EXT_depth_clip_enable[] 1008 1009ifdef::VK_EXT_sample_locations[] 1010If the `apiext:VK_EXT_sample_locations` extension is enabled on the device, 1011and pname:rasterizerDiscardEnable is ename:VK_FALSE, the following commands 1012must: have been called in the command buffer prior to drawing: 1013 1014 * flink:vkCmdSetSampleLocationsEnableEXT 1015 * flink:vkCmdSetSampleLocationsEXT, if pname:sampleLocationsEnable is 1016 ename:VK_TRUE 1017endif::VK_EXT_sample_locations[] 1018 1019ifdef::VK_EXT_provoking_vertex[] 1020If the `apiext:VK_EXT_provoking_vertex` extension is enabled on the device, 1021and pname:rasterizerDiscardEnable is ename:VK_FALSE, and a shader is bound 1022to the ename:VK_SHADER_STAGE_VERTEX_BIT stage, the following command must: 1023have been called in the command buffer prior to drawing: 1024 1025 * flink:vkCmdSetProvokingVertexModeEXT 1026endif::VK_EXT_provoking_vertex[] 1027 1028ifdef::VK_EXT_line_rasterization[] 1029If the `apiext:VK_EXT_line_rasterization` extension is enabled on the 1030device, and pname:rasterizerDiscardEnable is ename:VK_FALSE, and if 1031pname:polygonMode is ename:VK_POLYGON_MODE_LINE or a shader is bound to the 1032ename:VK_SHADER_STAGE_VERTEX_BIT stage and pname:primitiveTopology is a line 1033topology or a shader which outputs line primitives is bound to the 1034ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT or 1035ename:VK_SHADER_STAGE_GEOMETRY_BIT stage, the following commands must: have 1036been called in the command buffer prior to drawing: 1037 1038 * flink:vkCmdSetLineRasterizationModeEXT 1039 * flink:vkCmdSetLineStippleEnableEXT 1040 * flink:vkCmdSetLineStippleEXT, if pname:stippledLineEnable is 1041 ename:VK_TRUE 1042endif::VK_EXT_line_rasterization[] 1043 1044ifdef::VK_EXT_depth_clip_control[] 1045If the <<features-depthClipControl, pname:depthClipControl>> feature is 1046enabled on the device, the following command must: have been called in the 1047command buffer prior to drawing: 1048 1049 * flink:vkCmdSetDepthClipNegativeOneToOneEXT 1050endif::VK_EXT_depth_clip_control[] 1051 1052ifdef::VK_EXT_color_write_enable[] 1053If the <<features-colorWriteEnable, pname:colorWriteEnable>> feature is 1054enabled on the device, and a shader is bound to the 1055ename:VK_SHADER_STAGE_FRAGMENT_BIT stage, and pname:rasterizerDiscardEnable 1056is ename:VK_FALSE, the following command must: have been called in the 1057command buffer prior to drawing: 1058 1059 * flink:vkCmdSetColorWriteEnableEXT, with values set for every color 1060 attachment in the render pass instance active at draw time 1061endif::VK_EXT_color_write_enable[] 1062 1063ifdef::VK_EXT_attachment_feedback_loop_dynamic_state[] 1064If the <<features-attachmentFeedbackLoopDynamicState, 1065attachmentFeedbackLoopDynamicState>> feature is enabled on the device, and a 1066shader is bound to the ename:VK_SHADER_STAGE_FRAGMENT_BIT stage, and 1067pname:rasterizerDiscardEnable is ename:VK_FALSE, the following command must: 1068have been called in the command buffer prior to drawing: 1069 1070 * flink:vkCmdSetAttachmentFeedbackLoopEnableEXT 1071endif::VK_EXT_attachment_feedback_loop_dynamic_state[] 1072 1073ifdef::VK_NV_clip_space_w_scaling[] 1074If the `apiext:VK_NV_clip_space_w_scaling` extension is enabled on the 1075device, the following commands must: have been called in the command buffer 1076prior to drawing: 1077 1078 * flink:vkCmdSetViewportWScalingEnableNV 1079 * flink:vkCmdSetViewportWScalingNV, if pname:viewportWScalingEnable is 1080 ename:VK_TRUE 1081endif::VK_NV_clip_space_w_scaling[] 1082 1083ifdef::VK_NV_viewport_swizzle[] 1084If the `apiext:VK_NV_viewport_swizzle` extension is enabled on the device, 1085the following command must: have been called in the command buffer prior to 1086drawing: 1087 1088 * flink:vkCmdSetViewportSwizzleNV 1089endif::VK_NV_viewport_swizzle[] 1090 1091ifdef::VK_NV_fragment_coverage_to_color[] 1092If the `apiext:VK_NV_fragment_coverage_to_color` extension is enabled on the 1093device, and a shader is bound to the ename:VK_SHADER_STAGE_FRAGMENT_BIT 1094stage, and pname:rasterizerDiscardEnable is ename:VK_FALSE, the following 1095commands must: have been called in the command buffer prior to drawing: 1096 1097 * flink:vkCmdSetCoverageToColorEnableNV 1098 * flink:vkCmdSetCoverageToColorLocationNV, if pname:coverageToColorEnable 1099 is ename:VK_TRUE 1100endif::VK_NV_fragment_coverage_to_color[] 1101 1102ifdef::VK_NV_framebuffer_mixed_samples[] 1103If the `apiext:VK_NV_framebuffer_mixed_samples` extension is enabled on the 1104device, and pname:rasterizerDiscardEnable is ename:VK_FALSE, the following 1105commands must: have been called in the command buffer prior to drawing: 1106 1107 * flink:vkCmdSetCoverageModulationModeNV 1108 * flink:vkCmdSetCoverageModulationTableEnableNV, if 1109 pname:coverageModulationMode is not 1110 ename:VK_COVERAGE_MODULATION_MODE_NONE_NV 1111 * flink:vkCmdSetCoverageModulationTableNV, if 1112 pname:coverageModulationTableEnable is ename:VK_TRUE 1113endif::VK_NV_framebuffer_mixed_samples[] 1114 1115ifdef::VK_NV_coverage_reduction_mode[] 1116If the <<features-coverageReductionMode, pname:coverageReductionMode>> 1117feature is enabled on the device, and pname:rasterizerDiscardEnable is 1118ename:VK_FALSE, the following command must: have been called in the command 1119buffer prior to drawing: 1120 1121 * flink:vkCmdSetCoverageReductionModeNV 1122endif::VK_NV_coverage_reduction_mode[] 1123 1124ifdef::VK_NV_representative_fragment_test[] 1125If the <<features-representativeFragmentTest, 1126pname:representativeFragmentTest>> feature is enabled on the device, and 1127pname:rasterizerDiscardEnable is ename:VK_FALSE, the following command must: 1128have been called in the command buffer prior to drawing: 1129 1130 * flink:vkCmdSetRepresentativeFragmentTestEnableNV 1131endif::VK_NV_representative_fragment_test[] 1132 1133ifdef::VK_NV_shading_rate_image[] 1134If the <<features-shadingRateImage, pname:shadingRateImage>> feature is 1135enabled on the device, and pname:rasterizerDiscardEnable is ename:VK_FALSE, 1136the following commands must: have been called in the command buffer prior to 1137drawing: 1138 1139 * flink:vkCmdSetCoarseSampleOrderNV 1140 * flink:vkCmdSetShadingRateImageEnableNV 1141 * flink:vkCmdSetViewportShadingRatePaletteNV, if 1142 pname:shadingRateImageEnable is ename:VK_TRUE 1143endif::VK_NV_shading_rate_image[] 1144 1145ifdef::VK_NV_scissor_exclusive[] 1146If the <<features-exclusiveScissor, pname:exclusiveScissor>> feature is 1147enabled on the device, the following commands must: have been called in the 1148command buffer prior to drawing: 1149 1150 * flink:vkCmdSetExclusiveScissorEnableNV 1151 * flink:vkCmdSetExclusiveScissorNV, if any value in 1152 pname:pExclusiveScissorEnables is ename:VK_TRUE 1153endif::VK_NV_scissor_exclusive[] 1154 1155State can: be set either at any time before or after shader objects are 1156bound, but all required state must: be set prior to issuing drawing 1157commands. 1158 1159[[shaders-objects-pipeline-interaction]] 1160=== Interaction With Pipelines 1161 1162Calling flink:vkCmdBindShadersEXT causes the pipeline bind points 1163<<shaders-binding,corresponding to each stage>> in pname:pStages to be 1164disturbed, meaning that any <<pipelines, pipelines>> that had previously 1165been bound to those pipeline bind points are no longer bound. 1166 1167If ename:VK_PIPELINE_BIND_POINT_GRAPHICS is disturbed (i.e., if 1168pname:pStages contains any graphics stage), any graphics pipeline state that 1169the previously bound pipeline did not specify as <<pipelines-dynamic-state, 1170dynamic>> becomes undefined:, and must: be set in the command buffer before 1171issuing drawing commands using shader objects. 1172 1173Calls to flink:vkCmdBindPipeline likewise disturb the shader stage(s) 1174corresponding to pname:pipelineBindPoint, meaning that any shaders that had 1175previously been bound to any of those stages are no longer bound, even if 1176the pipeline was created without shaders for some of those stages. 1177 1178[[shaders-objects-destruction]] 1179=== Shader Object Destruction 1180 1181[open,refpage='vkDestroyShaderEXT',desc='Destroy a shader object',type='protos'] 1182-- 1183To destroy a shader object, call: 1184 1185include::{generated}/api/protos/vkDestroyShaderEXT.adoc[] 1186 1187 * pname:device is the logical device that destroys the shader object. 1188 * pname:shader is the handle of the shader object to destroy. 1189 * pname:pAllocator controls host memory allocation as described in the 1190 <<memory-allocation, Memory Allocation>> chapter. 1191 1192Destroying a shader object used by one or more command buffers in the 1193<<commandbuffers-lifecycle, recording or executable state>> causes those 1194command buffers to move into the _invalid state_. 1195 1196.Valid Usage 1197**** 1198 * [[VUID-vkDestroyShaderEXT-None-08481]] 1199 The <<features-shaderObject, pname:shaderObject>> feature must: be 1200 enabled 1201 * [[VUID-vkDestroyShaderEXT-shader-08482]] 1202 All submitted commands that refer to pname:shader must: have completed 1203 execution 1204 * [[VUID-vkDestroyShaderEXT-pAllocator-08483]] 1205 If sname:VkAllocationCallbacks were provided when pname:shader was 1206 created, a compatible set of callbacks must: be provided here 1207 * [[VUID-vkDestroyShaderEXT-pAllocator-08484]] 1208 If no sname:VkAllocationCallbacks were provided when pname:shader was 1209 created, pname:pAllocator must: be `NULL` 1210**** 1211 1212include::{generated}/validity/protos/vkDestroyShaderEXT.adoc[] 1213-- 1214 1215endif::VK_EXT_shader_object[] 1216 1217[[shader-modules]] 1218== Shader Modules 1219 1220[open,refpage='VkShaderModule',desc='Opaque handle to a shader module object',type='handles'] 1221-- 1222_Shader modules_ contain _shader code_ and one or more entry points. 1223Shaders are selected from a shader module by specifying an entry point as 1224part of <<pipelines,pipeline>> creation. 1225The stages of a pipeline can: use shaders that come from different modules. 1226The shader code defining a shader module must: be in the SPIR-V format, as 1227described by the <<spirvenv,Vulkan Environment for SPIR-V>> appendix. 1228 1229Shader modules are represented by sname:VkShaderModule handles: 1230 1231include::{generated}/api/handles/VkShaderModule.adoc[] 1232 1233ifdef::VKSC_VERSION_1_0[] 1234Shader modules are not used in Vulkan SC, but the type has been retained for 1235compatibility <<SCID-8>>. 1236 1237In Vulkan SC, the shader modules and pipeline state are supplied to an 1238offline compiler which creates a pipeline cache entry which is loaded at 1239<<pipelines,pipeline>> creation time. 1240 1241ifdef::hidden[] 1242// tag::scremoved[] 1243 * elink:VkStructureType 1244 ** ename:VK_STRUCTURE_TYPE_SHADER_MODULE_CREATE_INFO <<SCID-8>> 1245 * elink:VkObjectType 1246 ** ename:VK_OBJECT_TYPE_SHADER_MODULE <<SCID-8>> 1247 * fname:vkCreateShaderModule, fname:vkDestroyShaderModule <<SCID-8>> 1248 * sname:VkShaderModule, sname:VkShaderModuleCreateInfo <<SCID-8>> 1249 * tname:VkShaderModuleCreateFlags <<SCID-8>> 1250 * ename:VkShaderModuleCreateFlagBits <<SCID-8>> 1251// end::scremoved[] 1252endif::hidden[] 1253endif::VKSC_VERSION_1_0[] 1254-- 1255 1256ifndef::VKSC_VERSION_1_0[] 1257[open,refpage='vkCreateShaderModule',desc='Creates a new shader module object',type='protos'] 1258-- 1259To create a shader module, call: 1260 1261include::{generated}/api/protos/vkCreateShaderModule.adoc[] 1262 1263 * pname:device is the logical device that creates the shader module. 1264 * pname:pCreateInfo is a pointer to a slink:VkShaderModuleCreateInfo 1265 structure. 1266 * pname:pAllocator controls host memory allocation as described in the 1267 <<memory-allocation, Memory Allocation>> chapter. 1268 * pname:pShaderModule is a pointer to a slink:VkShaderModule handle in 1269 which the resulting shader module object is returned. 1270 1271Once a shader module has been created, any entry points it contains can: be 1272used in pipeline shader stages as described in <<pipelines-compute,Compute 1273Pipelines>> and <<pipelines-graphics,Graphics Pipelines>>. 1274 1275ifdef::VK_EXT_graphics_pipeline_libraries,VK_KHR_maintenance5[] 1276[NOTE] 1277.Note 1278==== 1279If 1280ifdef::VK_EXT_graphics_pipeline_libraries[] 1281the <<features-graphicsPipelineLibrary, pname:graphicsPipelineLibrary>> 1282feature 1283endif::VK_EXT_graphics_pipeline_libraries[] 1284ifdef::VK_EXT_graphics_pipeline_libraries+VK_KHR_maintenance5[or] 1285ifdef::VK_KHR_maintenance5[] 1286the <<features-maintenance5,pname:maintenance5>> feature 1287endif::VK_KHR_maintenance5[] 1288is enabled, shader module creation can be omitted entirely. 1289Instead, applications should provide the slink:VkShaderModuleCreateInfo 1290structure directly in to pipeline creation by chaining it to 1291slink:VkPipelineShaderStageCreateInfo. 1292This avoids the overhead of creating and managing an additional object. 1293==== 1294endif::VK_EXT_graphics_pipeline_libraries,VK_KHR_maintenance5[] 1295 1296.Valid Usage 1297**** 1298 * [[VUID-vkCreateShaderModule-pCreateInfo-06904]] 1299 If pname:pCreateInfo is not `NULL`, pname:pCreateInfo->pNext must: be 1300 `NULL` 1301ifdef::VK_EXT_validation_cache[] 1302 or a pointer to a slink:VkShaderModuleValidationCacheCreateInfoEXT 1303 structure 1304endif::VK_EXT_validation_cache[] 1305**** 1306 1307include::{generated}/validity/protos/vkCreateShaderModule.adoc[] 1308-- 1309 1310[open,refpage='VkShaderModuleCreateInfo',desc='Structure specifying parameters of a newly created shader module',type='structs'] 1311-- 1312:refpage: VkShaderModuleCreateInfo 1313 1314The sname:VkShaderModuleCreateInfo structure is defined as: 1315 1316include::{generated}/api/structs/VkShaderModuleCreateInfo.adoc[] 1317 1318 * pname:sType is a elink:VkStructureType value identifying this structure. 1319 * pname:pNext is `NULL` or a pointer to a structure extending this 1320 structure. 1321 * pname:flags is reserved for future use. 1322 * pname:codeSize is the size, in bytes, of the code pointed to by 1323 pname:pCode. 1324 * pname:pCode is a pointer to code that is used to create the shader 1325 module. 1326 The type and format of the code is determined from the content of the 1327 memory addressed by pname:pCode. 1328 1329.Valid Usage 1330**** 1331:prefixCondition: 1332ifdef::VK_NV_glsl_shader[] 1333:prefixCondition: If pCode is a pointer to SPIR-V code, 1334endif::VK_NV_glsl_shader[] 1335 1336include::{chapters}/commonvalidity/shader_create_spv_common.adoc[] 1337 1338ifdef::VK_NV_glsl_shader[] 1339 * [[VUID-VkShaderModuleCreateInfo-pCode-07912]] 1340 If the apiext:VK_NV_glsl_shader extension is not enabled, pname:pCode 1341 must: be a pointer to SPIR-V code 1342 * [[VUID-VkShaderModuleCreateInfo-pCode-01379]] 1343 If pname:pCode is a pointer to GLSL code, it must: be valid GLSL code 1344 written to the `GL_KHR_vulkan_glsl` GLSL extension specification 1345endif::VK_NV_glsl_shader[] 1346 * [[VUID-VkShaderModuleCreateInfo-codeSize-01085]] 1347 pname:codeSize must: be greater than 0 1348**** 1349 1350include::{generated}/validity/structs/VkShaderModuleCreateInfo.adoc[] 1351-- 1352 1353[open,refpage='VkShaderModuleCreateFlags',desc='Reserved for future use',type='flags'] 1354-- 1355include::{generated}/api/flags/VkShaderModuleCreateFlags.adoc[] 1356 1357tname:VkShaderModuleCreateFlags is a bitmask type for setting a mask, but is 1358currently reserved for future use. 1359-- 1360 1361ifdef::VK_EXT_validation_cache[] 1362include::{chapters}/VK_EXT_validation_cache/shader-module-validation-cache.adoc[] 1363endif::VK_EXT_validation_cache[] 1364 1365 1366[open,refpage='vkDestroyShaderModule',desc='Destroy a shader module',type='protos'] 1367-- 1368To destroy a shader module, call: 1369 1370include::{generated}/api/protos/vkDestroyShaderModule.adoc[] 1371 1372 * pname:device is the logical device that destroys the shader module. 1373 * pname:shaderModule is the handle of the shader module to destroy. 1374 * pname:pAllocator controls host memory allocation as described in the 1375 <<memory-allocation, Memory Allocation>> chapter. 1376 1377A shader module can: be destroyed while pipelines created using its shaders 1378are still in use. 1379 1380.Valid Usage 1381**** 1382 * [[VUID-vkDestroyShaderModule-shaderModule-01092]] 1383 If sname:VkAllocationCallbacks were provided when pname:shaderModule was 1384 created, a compatible set of callbacks must: be provided here 1385 * [[VUID-vkDestroyShaderModule-shaderModule-01093]] 1386 If no sname:VkAllocationCallbacks were provided when pname:shaderModule 1387 was created, pname:pAllocator must: be `NULL` 1388**** 1389 1390include::{generated}/validity/protos/vkDestroyShaderModule.adoc[] 1391-- 1392endif::VKSC_VERSION_1_0[] 1393 1394 1395 1396ifdef::VK_EXT_shader_module_identifier[] 1397[[shaders-identifiers]] 1398== Shader Module Identifiers 1399 1400[open,refpage='vkGetShaderModuleIdentifierEXT',desc='Query a unique identifier for a shader module',type='protos'] 1401-- 1402Shader modules have unique identifiers associated with them. 1403To query an implementation provided identifier, call: 1404 1405include::{generated}/api/protos/vkGetShaderModuleIdentifierEXT.adoc[] 1406 1407 * pname:device is the logical device that created the shader module. 1408 * pname:shaderModule is the handle of the shader module. 1409 * pname:pIdentifier is a pointer to the returned 1410 slink:VkShaderModuleIdentifierEXT. 1411 1412The identifier returned by the implementation must: only depend on 1413pname:shaderIdentifierAlgorithmUUID and information provided in the 1414slink:VkShaderModuleCreateInfo which created pname:shaderModule. 1415The implementation may: return equal identifiers for two different 1416slink:VkShaderModuleCreateInfo structures if the difference does not affect 1417pipeline compilation. 1418Identifiers are only meaningful on different slink:VkDevice objects if the 1419device the identifier was queried from had the same 1420<<limits-shaderModuleIdentifierAlgorithmUUID, 1421pname:shaderModuleIdentifierAlgorithmUUID>> as the device consuming the 1422identifier. 1423 1424.Valid Usage 1425**** 1426 * [[VUID-vkGetShaderModuleIdentifierEXT-shaderModuleIdentifier-06884]] 1427 <<features-shaderModuleIdentifier, pname:shaderModuleIdentifier>> 1428 feature must: be enabled 1429**** 1430 1431include::{generated}/validity/protos/vkGetShaderModuleIdentifierEXT.adoc[] 1432-- 1433 1434[open,refpage='vkGetShaderModuleCreateInfoIdentifierEXT',desc='Query a unique identifier for a shader module create info',type='protos'] 1435-- 1436slink:VkShaderModuleCreateInfo structures have unique identifiers associated 1437with them. 1438To query an implementation provided identifier, call: 1439 1440include::{generated}/api/protos/vkGetShaderModuleCreateInfoIdentifierEXT.adoc[] 1441 1442 * pname:device is the logical device that can: create a 1443 slink:VkShaderModule from pname:pCreateInfo. 1444 * pname:pCreateInfo is a pointer to a slink:VkShaderModuleCreateInfo 1445 structure. 1446 * pname:pIdentifier is a pointer to the returned 1447 slink:VkShaderModuleIdentifierEXT. 1448 1449The identifier returned by implementation must: only depend on 1450pname:shaderIdentifierAlgorithmUUID and information provided in the 1451slink:VkShaderModuleCreateInfo. 1452The implementation may: return equal identifiers for two different 1453slink:VkShaderModuleCreateInfo structures if the difference does not affect 1454pipeline compilation. 1455Identifiers are only meaningful on different slink:VkDevice objects if the 1456device the identifier was queried from had the same 1457<<limits-shaderModuleIdentifierAlgorithmUUID, 1458pname:shaderModuleIdentifierAlgorithmUUID>> as the device consuming the 1459identifier. 1460 1461The identifier returned by the implementation in 1462flink:vkGetShaderModuleCreateInfoIdentifierEXT must: be equal to the 1463identifier returned by flink:vkGetShaderModuleIdentifierEXT given equivalent 1464definitions of slink:VkShaderModuleCreateInfo and any chained pname:pNext 1465structures. 1466 1467.Valid Usage 1468**** 1469 * [[VUID-vkGetShaderModuleCreateInfoIdentifierEXT-shaderModuleIdentifier-06885]] 1470 <<features-shaderModuleIdentifier, pname:shaderModuleIdentifier>> 1471 feature must: be enabled 1472**** 1473 1474include::{generated}/validity/protos/vkGetShaderModuleCreateInfoIdentifierEXT.adoc[] 1475-- 1476 1477[open,refpage='VkShaderModuleIdentifierEXT',desc='A unique identifier for a shader module',type='structs'] 1478-- 1479slink:VkShaderModuleIdentifierEXT represents a shader module identifier 1480returned by the implementation. 1481 1482include::{generated}/api/structs/VkShaderModuleIdentifierEXT.adoc[] 1483 1484 * pname:sType is a elink:VkStructureType value identifying this structure. 1485 * pname:pNext is `NULL` or a pointer to a structure extending this 1486 structure. 1487 * pname:identifierSize is the size, in bytes, of valid data returned in 1488 pname:identifier. 1489 * pname:identifier is a buffer of opaque data specifying an identifier. 1490 1491Any returned values beyond the first pname:identifierSize bytes are 1492undefined:. 1493Implementations must: return an pname:identifierSize greater than 0, and 1494less-or-equal to ename:VK_MAX_SHADER_MODULE_IDENTIFIER_SIZE_EXT. 1495 1496Two identifiers are considered equal if pname:identifierSize is equal and 1497the first pname:identifierSize bytes of pname:identifier compare equal. 1498 1499Implementations may: return a different pname:identifierSize for different 1500modules. 1501Implementations should: ensure that pname:identifierSize is large enough to 1502uniquely define a shader module. 1503 1504include::{generated}/validity/structs/VkShaderModuleIdentifierEXT.adoc[] 1505-- 1506 1507[open,refpage='VK_MAX_SHADER_MODULE_IDENTIFIER_SIZE_EXT',desc='Maximum length of a shader module identifier',type='consts'] 1508-- 1509ename:VK_MAX_SHADER_MODULE_IDENTIFIER_SIZE_EXT is the length in bytes of a 1510shader module identifier, as returned in 1511slink:VkShaderModuleIdentifierEXT::pname:identifierSize. 1512 1513include::{generated}/api/enums/VK_MAX_SHADER_MODULE_IDENTIFIER_SIZE_EXT.adoc[] 1514-- 1515endif::VK_EXT_shader_module_identifier[] 1516 1517[[shaders-binding]] 1518== Binding Shaders 1519 1520Before a shader can be used it must: be first bound to the command buffer. 1521 1522Calling flink:vkCmdBindPipeline binds all stages corresponding to the 1523elink:VkPipelineBindPoint. 1524ifdef::VK_EXT_shader_object[] 1525Calling flink:vkCmdBindShadersEXT binds all stages in pname:pStages 1526endif::VK_EXT_shader_object[] 1527 1528The following table describes the relationship between shader stages and 1529pipeline bind points: 1530 1531[cols="1,1,1"] 1532|==== 1533|Shader stage |Pipeline bind point | behavior controlled 1534 1535a| * ename:VK_SHADER_STAGE_VERTEX_BIT 1536 * ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT 1537 * ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT 1538 * ename:VK_SHADER_STAGE_GEOMETRY_BIT 1539 * ename:VK_SHADER_STAGE_FRAGMENT_BIT 1540ifdef::VK_EXT_mesh_shader[] 1541 * ename:VK_SHADER_STAGE_TASK_BIT_EXT 1542 * ename:VK_SHADER_STAGE_MESH_BIT_EXT 1543endif::VK_EXT_mesh_shader[] 1544ifndef::VK_EXT_mesh_shader[] 1545ifdef::VK_NV_mesh_shader[] 1546 * ename:VK_SHADER_STAGE_TASK_BIT_NV 1547 * ename:VK_SHADER_STAGE_MESH_BIT_NV 1548endif::VK_NV_mesh_shader[] 1549endif::VK_EXT_mesh_shader[] 1550| ename:VK_PIPELINE_BIND_POINT_GRAPHICS 1551| all <<drawing, drawing commands>> 1552 1553a| * ename:VK_SHADER_STAGE_COMPUTE_BIT 1554| ename:VK_PIPELINE_BIND_POINT_COMPUTE 1555| all <<dispatch, dispatch commands>> 1556 1557ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 1558a| * ename:VK_SHADER_STAGE_ANY_HIT_BIT_KHR 1559 * ename:VK_SHADER_STAGE_CALLABLE_BIT_KHR 1560 * ename:VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR 1561 * ename:VK_SHADER_STAGE_INTERSECTION_BIT_KHR 1562 * ename:VK_SHADER_STAGE_MISS_BIT_KHR 1563 * ename:VK_SHADER_STAGE_RAYGEN_BIT_KHR 1564| ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR 1565| flink:vkCmdTraceRaysKHR and flink:vkCmdTraceRaysIndirectKHR 1566endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 1567 1568ifdef::VK_HUAWEI_subpass_shading[] 1569a| * ename:VK_SHADER_STAGE_SUBPASS_SHADING_BIT_HUAWEI 1570 * ename:VK_SHADER_STAGE_CLUSTER_CULLING_BIT_HUAWEI 1571| ename:VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI 1572| flink:vkCmdSubpassShadingHUAWEI 1573endif::VK_HUAWEI_subpass_shading[] 1574 1575ifdef::VK_AMDX_shader_enqueue[] 1576a| * ename:VK_SHADER_STAGE_COMPUTE_BIT 1577| ename:VK_PIPELINE_BIND_POINT_EXECUTION_GRAPH_AMDX 1578| all <<executiongraphs, execution graph commands>> 1579endif::VK_AMDX_shader_enqueue[] 1580|==== 1581 1582[[shaders-execution]] 1583== Shader Execution 1584 1585At each stage of the pipeline, multiple invocations of a shader may: execute 1586simultaneously. 1587Further, invocations of a single shader produced as the result of different 1588commands may: execute simultaneously. 1589The relative execution order of invocations of the same shader type is 1590undefined:. 1591Shader invocations may: complete in a different order than that in which the 1592primitives they originated from were drawn or dispatched by the application. 1593However, fragment shader outputs are written to attachments in 1594<<primsrast-order,rasterization order>>. 1595 1596The relative execution order of invocations of different shader types is 1597largely undefined:. 1598However, when invoking a shader whose inputs are generated from a previous 1599pipeline stage, the shader invocations from the previous stage are 1600guaranteed to have executed far enough to generate input values for all 1601required inputs. 1602 1603 1604[[shaders-termination]] 1605=== Shader Termination 1606 1607A shader invocation that is _terminated_ has finished executing 1608instructions. 1609 1610Executing code:OpReturn in the entry point, or executing 1611code:OpTerminateInvocation in any function will terminate an invocation. 1612Implementations may: also terminate a shader invocation when code:OpKill is 1613executed in any function; otherwise it becomes a 1614<<shaders-helper-invocations, helper invocation>>. 1615 1616In addition to the above conditions, <<shaders-helper-invocations,helper 1617invocations>> are terminated when all non-helper invocations in the same 1618<<shaders-derivative-operations,derivative group>> either terminate or 1619become <<shaders-helper-invocations,helper invocations>> via 1620ifdef::VK_EXT_shader_demote_to_helper_invocation[] 1621code:OpDemoteToHelperInvocationEXT or 1622endif::VK_EXT_shader_demote_to_helper_invocation[] 1623code:OpKill. 1624 1625A shader stage for a given command completes execution when all invocations 1626for that stage have terminated. 1627 1628 1629[[shaders-execution-memory-ordering]] 1630== Shader Memory Access Ordering 1631 1632The order in which image or buffer memory is read or written by shaders is 1633largely undefined:. 1634For some shader types (vertex, tessellation evaluation, and in some cases, 1635fragment), even the number of shader invocations that may: perform loads and 1636stores is undefined:. 1637 1638In particular, the following rules apply: 1639 1640 * <<shaders-vertex-execution,Vertex>> and 1641 <<shaders-tessellation-evaluation-execution,tessellation evaluation>> 1642 shaders will be invoked at least once for each unique vertex, as defined 1643 in those sections. 1644 * <<fragops-shader,Fragment>> shaders will be invoked zero or more times, 1645 as defined in that section. 1646 * The relative execution order of invocations of the same shader type is 1647 undefined:. 1648 A store issued by a shader when working on primitive B might complete 1649 prior to a store for primitive A, even if primitive A is specified prior 1650 to primitive B. This applies even to fragment shaders; while fragment 1651 shader outputs are always written to the framebuffer in 1652 <<primsrast-order, rasterization order>>, stores executed by fragment 1653 shader invocations are not. 1654 * The relative execution order of invocations of different shader types is 1655 largely undefined:. 1656 1657[NOTE] 1658.Note 1659==== 1660The above limitations on shader invocation order make some forms of 1661synchronization between shader invocations within a single set of primitives 1662unimplementable. 1663For example, having one invocation poll memory written by another invocation 1664assumes that the other invocation has been launched and will complete its 1665writes in finite time. 1666==== 1667 1668ifdef::VK_VERSION_1_2,VK_KHR_vulkan_memory_model[] 1669 1670The <<memory-model,Memory Model>> appendix defines the terminology and rules 1671for how to correctly communicate between shader invocations, such as when a 1672write is <<memory-model-visible-to,Visible-To>> a read, and what constitutes 1673a <<memory-model-access-data-race,Data Race>>. 1674 1675Applications must: not cause a data race. 1676 1677endif::VK_VERSION_1_2,VK_KHR_vulkan_memory_model[] 1678 1679ifndef::VK_VERSION_1_2,VK_KHR_vulkan_memory_model[] 1680 1681Stores issued to different memory locations within a single shader 1682invocation may: not be visible to other invocations, or may: not become 1683visible in the order they were performed. 1684 1685The code:OpMemoryBarrier instruction can: be used to provide stronger 1686ordering of reads and writes performed by a single invocation. 1687code:OpMemoryBarrier guarantees that any memory transactions issued by the 1688shader invocation prior to the instruction complete prior to the memory 1689transactions issued after the instruction. 1690Memory barriers are needed for algorithms that require multiple invocations 1691to access the same memory and require the operations to be performed in a 1692partially-defined relative order. 1693For example, if one shader invocation does a series of writes, followed by 1694an code:OpMemoryBarrier instruction, followed by another write, then the 1695results of the series of writes before the barrier become visible to other 1696shader invocations at a time earlier or equal to when the results of the 1697final write become visible to those invocations. 1698In practice it means that another invocation that sees the results of the 1699final write would also see the previous writes. 1700Without the memory barrier, the final write may: be visible before the 1701previous writes. 1702 1703Writes that are the result of shader stores through a variable decorated 1704with code:Coherent automatically have available writes to the same buffer, 1705buffer view, or image view made visible to them, and are themselves 1706automatically made available to access by the same buffer, buffer view, or 1707image view. 1708Reads that are the result of shader loads through a variable decorated with 1709code:Coherent automatically have available writes to the same buffer, buffer 1710view, or image view made visible to them. 1711The order that coherent writes to different locations become available is 1712undefined:, unless enforced by a memory barrier instruction or other memory 1713dependency. 1714 1715[NOTE] 1716.Note 1717==== 1718Explicit memory dependencies must: still be used to guarantee availability 1719and visibility for access via other buffers, buffer views, or image views. 1720==== 1721 1722The built-in atomic memory transaction instructions can: be used to read and 1723write a given memory address atomically. 1724While built-in atomic functions issued by multiple shader invocations are 1725executed in undefined: order relative to each other, these functions perform 1726both a read and a write of a memory address and guarantee that no other 1727memory transaction will write to the underlying memory between the read and 1728write. 1729Atomic operations ensure automatic availability and visibility for writes 1730and reads in the same way as those to code:Coherent variables. 1731 1732[NOTE] 1733.Note 1734==== 1735Memory accesses performed on different resource descriptors with the same 1736memory backing may: not be well-defined even with the code:Coherent 1737decoration or via atomics, due to things such as image layouts or ownership 1738of the resource - as described in the <<synchronization, Synchronization and 1739Cache Control>> chapter. 1740==== 1741 1742[NOTE] 1743.Note 1744==== 1745Atomics allow shaders to use shared global addresses for mutual exclusion or 1746as counters, among other uses. 1747==== 1748 1749endif::VK_VERSION_1_2,VK_KHR_vulkan_memory_model[] 1750 1751The SPIR-V *SubgroupMemory*, *CrossWorkgroupMemory*, and 1752*AtomicCounterMemory* memory semantics are ignored. 1753Sequentially consistent atomics and barriers are not supported and 1754*SequentiallyConsistent* is treated as *AcquireRelease*. 1755*SequentiallyConsistent* should: not be used. 1756 1757 1758[[shaders-inputs]] 1759== Shader Inputs and Outputs 1760 1761Data is passed into and out of shaders using variables with input or output 1762storage class, respectively. 1763User-defined inputs and outputs are connected between stages by matching 1764their code:Location decorations. 1765Additionally, data can: be provided by or communicated to special functions 1766provided by the execution environment using code:BuiltIn decorations. 1767 1768In many cases, the same code:BuiltIn decoration can: be used in multiple 1769shader stages with similar meaning. 1770The specific behavior of variables decorated as code:BuiltIn is documented 1771in the following sections. 1772 1773ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 1774[[shaders-task]] 1775== Task Shaders 1776 1777Task shaders operate in conjunction with the mesh shaders to produce a 1778collection of primitives that will be processed by subsequent stages of the 1779graphics pipeline. 1780Its primary purpose is to create a variable amount of subsequent mesh shader 1781invocations. 1782 1783Task shaders are invoked via the execution of the 1784<<drawing-mesh-shading,programmable mesh shading>> pipeline. 1785 1786The task shader has no fixed-function inputs other than variables 1787identifying the specific workgroup and invocation. 1788ifdef::VK_NV_mesh_shader[] 1789In the code:TaskNV {ExecutionModel} the number of mesh shader workgroups to 1790create is specified via a code:TaskCountNV decorated output variable. 1791endif::VK_NV_mesh_shader[] 1792ifdef::VK_EXT_mesh_shader[] 1793In the code:TaskEXT {ExecutionModel} the number of mesh shader workgroups to 1794create is specified via the code:OpEmitMeshTasksEXT instruction. 1795endif::VK_EXT_mesh_shader[] 1796 1797The task shader can write additional outputs to task memory, which can be 1798read by all of the mesh shader workgroups it created. 1799 1800 1801=== Task Shader Execution 1802 1803Task workloads are formed from groups of work items called workgroups and 1804processed by the task shader in the current graphics pipeline. 1805A workgroup is a collection of shader invocations that execute the same 1806shader, potentially in parallel. 1807Task shaders execute in _global workgroups_ which are divided into a number 1808of _local workgroups_ with a size that can: be set by assigning a value to 1809the code:LocalSize 1810ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[or code:LocalSizeId] 1811execution mode or via an object decorated by the code:WorkgroupSize 1812decoration. 1813An invocation within a local workgroup can: share data with other members of 1814the local workgroup through shared variables and issue memory and control 1815flow barriers to synchronize with other members of the local workgroup. 1816ifdef::VK_EXT_mesh_shader[] 1817ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 1818If the subpass includes multiple views in its view mask, a Task shader using 1819code:TaskEXT {ExecutionModel} may: be invoked separately for each view. 1820endif::VK_VERSION_1_1,VK_KHR_multiview[] 1821endif::VK_EXT_mesh_shader[] 1822 1823 1824[[shaders-mesh]] 1825== Mesh Shaders 1826 1827Mesh shaders operate in workgroups to produce a collection of primitives 1828that will be processed by subsequent stages of the graphics pipeline. 1829Each workgroup emits zero or more output primitives and the group of 1830vertices and their associated data required for each output primitive. 1831 1832Mesh shaders are invoked via the execution of the 1833<<drawing-mesh-shading,programmable mesh shading>> pipeline. 1834 1835The only inputs available to the mesh shader are variables identifying the 1836specific workgroup and invocation and, if applicable, any outputs written to 1837task memory by the task shader that spawned the mesh shader's workgroup. 1838The mesh shader can operate without a task shader as well. 1839 1840The invocations of the mesh shader workgroup write an output mesh, 1841comprising a set of primitives with per-primitive attributes, a set of 1842vertices with per-vertex attributes, and an array of indices identifying the 1843mesh vertices that belong to each primitive. 1844The primitives of this mesh are then processed by subsequent graphics 1845pipeline stages, where the outputs of the mesh shader form an interface with 1846the fragment shader. 1847 1848 1849=== Mesh Shader Execution 1850 1851Mesh workloads are formed from groups of work items called workgroups and 1852processed by the mesh shader in the current graphics pipeline. 1853A workgroup is a collection of shader invocations that execute the same 1854shader, potentially in parallel. 1855Mesh shaders execute in _global workgroups_ which are divided into a number 1856of _local workgroups_ with a size that can: be set by assigning a value to 1857the code:LocalSize 1858ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[or code:LocalSizeId] 1859execution mode or via an object decorated by the code:WorkgroupSize 1860decoration. 1861An invocation within a local workgroup can: share data with other members of 1862the local workgroup through shared variables and issue memory and control 1863flow barriers to synchronize with other members of the local workgroup. 1864 1865The _global workgroups_ may be generated explicitly via the API, or 1866implicitly through the task shader's work creation mechanism. 1867endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 1868ifdef::VK_EXT_mesh_shader[] 1869ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 1870If the subpass includes multiple views in its view mask, a Mesh shader using 1871code:MeshEXT {ExecutionModel} may: be invoked separately for each view. 1872endif::VK_VERSION_1_1,VK_KHR_multiview[] 1873endif::VK_EXT_mesh_shader[] 1874 1875ifdef::VK_HUAWEI_cluster_culling_shader[] 1876[[shaders-cluster-culling]] 1877 1878== Cluster Culling Shaders 1879Cluster Culling shaders are invoked via the execution of the 1880<<drawing-cluster-culling-shading,Programmable Cluster Culling Shading>> 1881pipeline. 1882 1883The only inputs available to the cluster culling shader are variables 1884identifying the specific workgroup and invocation. 1885 1886Cluster Culling shaders operate in workgroups to perform cluster-based 1887culling and produce zero or more cluster drawing command that will be 1888processed by subsequent stages of the graphics pipeline. 1889 1890The Cluster Drawing Command(CDC) is very similar to the MDI command, 1891invocations in workgroup can emit zero of more CDC to draw zero or more 1892visible cluster. 1893 1894=== Cluster Culling Shader Execution 1895 1896Cluster Culling workloads are formed from groups of work items called 1897workgroups and processed by the cluster culling shader in the current 1898graphics pipeline. 1899A workgroup is a collection of shader invocations that execute the same 1900shader, potentially in parallel. 1901Cluster Culling shaders execute in _global workgroups_ which are divided 1902into a number of _local workgroups_ with a size that can: be set by 1903assigning a value to the code:LocalSize 1904ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[or code:LocalSizeId] 1905execution mode or via an object decorated by the code:WorkgroupSize 1906decoration. 1907An invocation within a local workgroup can: share data with other members of 1908the local workgroup through shared variables and issue memory and control 1909flow barriers to synchronize with other members of the local workgroup. 1910endif::VK_HUAWEI_cluster_culling_shader[] 1911 1912[[shaders-vertex]] 1913== Vertex Shaders 1914 1915Each vertex shader invocation operates on one vertex and its associated 1916<<fxvertex-attrib,vertex attribute>> data, and outputs one vertex and 1917associated data. 1918ifndef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 1919Graphics pipelines must: include a vertex shader, and the vertex shader 1920stage is always the first shader stage in the graphics pipeline. 1921endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 1922ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 1923Graphics pipelines using primitive shading must: include a vertex shader, 1924and the vertex shader stage is always the first shader stage in the graphics 1925pipeline. 1926endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 1927 1928 1929[[shaders-vertex-execution]] 1930=== Vertex Shader Execution 1931 1932A vertex shader must: be executed at least once for each vertex specified by 1933a drawing command. 1934ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 1935If the subpass includes multiple views in its view mask, the shader may: be 1936invoked separately for each view. 1937endif::VK_VERSION_1_1,VK_KHR_multiview[] 1938During execution, the shader is presented with the index of the vertex and 1939instance for which it has been invoked. 1940Input variables declared in the vertex shader are filled by the 1941implementation with the values of vertex attributes associated with the 1942invocation being executed. 1943 1944If the same vertex is specified multiple times in a drawing command (e.g. by 1945including the same index value multiple times in an index buffer) the 1946implementation may: reuse the results of vertex shading if it can statically 1947determine that the vertex shader invocations will produce identical results. 1948 1949[NOTE] 1950.Note 1951==== 1952It is implementation-dependent when and if results of vertex shading are 1953reused, and thus how many times the vertex shader will be executed. 1954This is true also if the vertex shader contains stores or atomic operations 1955(see <<features-vertexPipelineStoresAndAtomics, 1956pname:vertexPipelineStoresAndAtomics>>). 1957==== 1958 1959 1960[[shaders-tessellation-control]] 1961== Tessellation Control Shaders 1962 1963The tessellation control shader is used to read an input patch provided by 1964the application and to produce an output patch. 1965Each tessellation control shader invocation operates on an input patch 1966(after all control points in the patch are processed by a vertex shader) and 1967its associated data, and outputs a single control point of the output patch 1968and its associated data, and can: also output additional per-patch data. 1969The input patch is sized according to the pname:patchControlPoints member of 1970slink:VkPipelineTessellationStateCreateInfo, as part of input assembly. 1971 1972ifdef::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[] 1973The input patch can also be dynamically sized with pname:patchControlPoints 1974parameter of flink:vkCmdSetPatchControlPointsEXT. 1975 1976[open,refpage='vkCmdSetPatchControlPointsEXT',desc='Specify the number of control points per patch dynamically for a command buffer',type='protos'] 1977-- 1978To <<pipelines-dynamic-state, dynamically set>> the number of control points 1979per patch, call: 1980 1981include::{generated}/api/protos/vkCmdSetPatchControlPointsEXT.adoc[] 1982 1983 * pname:commandBuffer is the command buffer into which the command will be 1984 recorded. 1985 * pname:patchControlPoints specifies the number of control points per 1986 patch. 1987 1988This command sets the number of control points per patch for subsequent 1989drawing commands 1990ifdef::VK_EXT_shader_object[] 1991ifdef::VK_EXT_extended_dynamic_state2[when drawing using <<shaders-objects, shader objects>>, or] 1992ifndef::VK_EXT_extended_dynamic_state2[when drawing using <<shaders-objects, shader objects>>.] 1993endif::VK_EXT_shader_object[] 1994ifdef::VK_EXT_extended_dynamic_state2[] 1995when the graphics pipeline is created with 1996ename:VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT set in 1997slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1998endif::VK_EXT_extended_dynamic_state2[] 1999Otherwise, this state is specified by the 2000slink:VkPipelineTessellationStateCreateInfo::pname:patchControlPoints value 2001used to create the currently active pipeline. 2002 2003:refpage: vkCmdSetPatchControlPointsEXT 2004:requiredfeature: extendedDynamicState2PatchControlPoints 2005 2006.Valid Usage 2007**** 2008include::{chapters}/commonvalidity/dynamic_state2_optional_feature_common.adoc[] 2009 * [[VUID-vkCmdSetPatchControlPointsEXT-patchControlPoints-04874]] 2010 pname:patchControlPoints must: be greater than zero and less than or 2011 equal to sname:VkPhysicalDeviceLimits::pname:maxTessellationPatchSize 2012**** 2013 2014include::{generated}/validity/protos/vkCmdSetPatchControlPointsEXT.adoc[] 2015-- 2016endif::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[] 2017 2018The size of the output patch is controlled by the code:OpExecutionMode 2019code:OutputVertices specified in the tessellation control or tessellation 2020evaluation shaders, which must: be specified in at least one of the shaders. 2021The size of the input and output patches must: each be greater than zero and 2022less than or equal to 2023sname:VkPhysicalDeviceLimits::pname:maxTessellationPatchSize. 2024 2025 2026[[shaders-tessellation-control-execution]] 2027=== Tessellation Control Shader Execution 2028 2029A tessellation control shader is invoked at least once for each _output_ 2030vertex in a patch. 2031ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 2032If the subpass includes multiple views in its view mask, the shader may: be 2033invoked separately for each view. 2034endif::VK_VERSION_1_1,VK_KHR_multiview[] 2035 2036Inputs to the tessellation control shader are generated by the vertex 2037shader. 2038Each invocation of the tessellation control shader can: read the attributes 2039of any incoming vertices and their associated data. 2040The invocations corresponding to a given patch execute logically in 2041parallel, with undefined: relative execution order. 2042However, the code:OpControlBarrier instruction can: be used to provide 2043limited control of the execution order by synchronizing invocations within a 2044patch, effectively dividing tessellation control shader execution into a set 2045of phases. 2046Tessellation control shaders will read undefined: values if one invocation 2047reads a per-vertex or per-patch output written by another invocation at any 2048point during the same phase, or if two invocations attempt to write 2049different values to the same per-patch output in a single phase. 2050 2051 2052[[shaders-tessellation-evaluation]] 2053== Tessellation Evaluation Shaders 2054 2055The Tessellation Evaluation Shader operates on an input patch of control 2056points and their associated data, and a single input barycentric coordinate 2057indicating the invocation's relative position within the subdivided patch, 2058and outputs a single vertex and its associated data. 2059 2060 2061[[shaders-tessellation-evaluation-execution]] 2062=== Tessellation Evaluation Shader Execution 2063 2064A tessellation evaluation shader is invoked at least once for each unique 2065vertex generated by the tessellator. 2066ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 2067If the subpass includes multiple views in its view mask, the shader may: be 2068invoked separately for each view. 2069endif::VK_VERSION_1_1,VK_KHR_multiview[] 2070 2071 2072[[shaders-geometry]] 2073== Geometry Shaders 2074 2075The geometry shader operates on a group of vertices and their associated 2076data assembled from a single input primitive, and emits zero or more output 2077primitives and the group of vertices and their associated data required for 2078each output primitive. 2079 2080 2081[[shaders-geometry-execution]] 2082=== Geometry Shader Execution 2083 2084A geometry shader is invoked at least once for each primitive produced by 2085the tessellation stages, or at least once for each primitive generated by 2086<<drawing,primitive assembly>> when tessellation is not in use. 2087A shader can request that the geometry shader runs multiple 2088<<geometry-invocations, instances>>. 2089A geometry shader is invoked at least once for each instance. 2090ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 2091If the subpass includes multiple views in its view mask, the shader may: be 2092invoked separately for each view. 2093endif::VK_VERSION_1_1,VK_KHR_multiview[] 2094 2095 2096[[shaders-fragment]] 2097== Fragment Shaders 2098 2099Fragment shaders are invoked as a <<fragops-shader, fragment operation>> in 2100a graphics pipeline. 2101Each fragment shader invocation operates on a single fragment and its 2102associated data. 2103With few exceptions, fragment shaders do not have access to any data 2104associated with other fragments and are considered to execute in isolation 2105of fragment shader invocations associated with other fragments. 2106 2107 2108[[shaders-compute]] 2109== Compute Shaders 2110 2111Compute shaders are invoked via flink:vkCmdDispatch and 2112flink:vkCmdDispatchIndirect commands. 2113In general, they have access to similar resources as shader stages executing 2114as part of a graphics pipeline. 2115 2116Compute workloads are formed from groups of work items called workgroups and 2117processed by the compute shader in the current compute pipeline. 2118A workgroup is a collection of shader invocations that execute the same 2119shader, potentially in parallel. 2120Compute shaders execute in _global workgroups_ which are divided into a 2121number of _local workgroups_ with a size that can: be set by assigning a 2122value to the code:LocalSize 2123ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[or code:LocalSizeId] 2124execution mode or via an object decorated by the code:WorkgroupSize 2125decoration. 2126An invocation within a local workgroup can: share data with other members of 2127the local workgroup through shared variables and issue memory and control 2128flow barriers to synchronize with other members of the local workgroup. 2129 2130 2131ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 2132[[shaders-raytracing-shaders]] 2133[[shaders-ray-generation]] 2134== Ray Generation Shaders 2135 2136A ray generation shader is similar to a compute shader. 2137Its main purpose is to execute ray tracing queries using code:OpTraceRayKHR 2138instructions and process the results. 2139 2140 2141[[shaders-ray-generation-execution]] 2142=== Ray Generation Shader Execution 2143 2144One ray generation shader is executed per ray tracing dispatch. 2145Its location in the shader binding table (see <<shader-binding-table,Shader 2146Binding Table>> for details) is passed directly into 2147ifdef::VK_KHR_ray_tracing_pipeline[] 2148flink:vkCmdTraceRaysKHR using the pname:pRaygenShaderBindingTable parameter 2149endif::VK_KHR_ray_tracing_pipeline[] 2150ifdef::VK_KHR_ray_tracing_pipeline+VK_KHR_ray_tracing_pipeline[or] 2151ifdef::VK_NV_ray_tracing[] 2152flink:vkCmdTraceRaysNV using the pname:raygenShaderBindingTableBuffer and 2153pname:raygenShaderBindingOffset parameters 2154endif::VK_NV_ray_tracing[] 2155. 2156 2157 2158[[shaders-intersection]] 2159== Intersection Shaders 2160 2161Intersection shaders enable the implementation of arbitrary, application 2162defined geometric primitives. 2163An intersection shader for a primitive is executed whenever its axis-aligned 2164bounding box is hit by a ray. 2165 2166Like other ray tracing shader domains, an intersection shader operates on a 2167single ray at a time. 2168It also operates on a single primitive at a time. 2169It is therefore the purpose of an intersection shader to compute the 2170ray-primitive intersections and report them. 2171To report an intersection, the shader calls the code:OpReportIntersectionKHR 2172instruction. 2173 2174An intersection shader communicates with any-hit and closest shaders by 2175generating attribute values that they can: read. 2176Intersection shaders cannot: read or modify the ray payload. 2177 2178 2179[[shaders-intersection-execution]] 2180=== Intersection Shader Execution 2181The order in which intersections are found along a ray, and therefore the 2182order in which intersection shaders are executed, is unspecified. 2183 2184The intersection shader of the closest AABB which intersects the ray is 2185guaranteed to be executed at some point during traversal, unless the ray is 2186forcibly terminated. 2187 2188 2189[[shaders-any-hit]] 2190== Any-Hit Shaders 2191 2192The any-hit shader is executed after the intersection shader reports an 2193intersection that lies within the current [eq]#[t~min~,t~max~]# of the ray. 2194The main use of any-hit shaders is to programmatically decide whether or not 2195an intersection will be accepted. 2196The intersection will be accepted unless the shader calls the 2197code:OpIgnoreIntersectionKHR instruction. 2198Any-hit shaders have read-only access to the attributes generated by the 2199corresponding intersection shader, and can: read or modify the ray payload. 2200 2201 2202[[shaders-any-hit-execution]] 2203=== Any-Hit Shader Execution 2204 2205The order in which intersections are found along a ray, and therefore the 2206order in which any-hit shaders are executed, is unspecified. 2207 2208The any-hit shader of the closest hit is guaranteed to be executed at some 2209point during traversal, unless the ray is forcibly terminated. 2210 2211 2212[[shaders-closest-hit]] 2213== Closest Hit Shaders 2214 2215Closest hit shaders have read-only access to the attributes generated by the 2216corresponding intersection shader, and can: read or modify the ray payload. 2217They also have access to a number of system-generated values. 2218Closest hit shaders can: call code:OpTraceRayKHR to recursively trace rays. 2219 2220 2221[[shaders-closest-hit-execution]] 2222=== Closest Hit Shader Execution 2223 2224Exactly one closest hit shader is executed when traversal is finished and an 2225intersection has been found and accepted. 2226 2227 2228[[shaders-miss]] 2229== Miss Shaders 2230 2231Miss shaders can: access the ray payload and can: trace new rays through the 2232code:OpTraceRayKHR instruction, but cannot: access attributes since they are 2233not associated with an intersection. 2234 2235 2236[[shaders-miss-execution]] 2237=== Miss Shader Execution 2238 2239A miss shader is executed instead of a closest hit shader if no intersection 2240was found during traversal. 2241 2242 2243[[shaders-callable]] 2244== Callable Shaders 2245 2246Callable shaders can: access a callable payload that works similarly to ray 2247payloads to do subroutine work. 2248 2249 2250[[shaders-callable-execution]] 2251=== Callable Shader Execution 2252 2253A callable shader is executed by calling code:OpExecuteCallableKHR from an 2254allowed shader stage. 2255 2256endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 2257 2258 2259[[shaders-interpolation-decorations]] 2260== Interpolation Decorations 2261 2262Variables in the code:Input storage class in a fragment shader's interface 2263are interpolated from the values specified by the primitive being 2264rasterized. 2265 2266[NOTE] 2267.Note 2268==== 2269Interpolation decorations can be present on input and output variables in 2270pre-rasterization shaders but have no effect on the interpolation performed. 2271ifdef::VK_EXT_graphics_pipeline_libraries[] 2272However, when linking graphics pipeline libraries, if the 2273<<limits-graphicsPipelineLibraryIndependentInterpolationDecoration, 2274pname:graphicsPipelineLibraryIndependentInterpolationDecoration>> limit is 2275not supported, interpolation qualifiers do need to match between the 2276fragment shader input and the last pre-rasterization shader output. 2277endif::VK_EXT_graphics_pipeline_libraries[] 2278==== 2279 2280An undecorated input variable will be interpolated with perspective-correct 2281interpolation according to the primitive type being rasterized. 2282<<line_perspective_interpolation,Lines>> and 2283<<triangle_perspective_interpolation,polygons>> are interpolated in the same 2284way as the primitive's clip coordinates. 2285If the code:NoPerspective decoration is present, linear interpolation is 2286instead used for <<line_linear_interpolation,lines>> and 2287<<triangle_linear_interpolation,polygons>>. 2288For points, as there is only a single vertex, input values are never 2289interpolated and instead take the value written for the single vertex. 2290 2291If the code:Flat decoration is present on an input variable, the value is 2292not interpolated, and instead takes its value directly from the 2293<<vertexpostproc-flatshading,provoking vertex>>. 2294Fragment shader inputs that are signed or unsigned integers, integer 2295vectors, or any double-precision floating-point type must: be decorated with 2296code:Flat. 2297 2298Interpolation of input variables is performed at an implementation-defined 2299position within the fragment area being shaded. 2300The position is further constrained as follows: 2301 2302 * If the code:Centroid decoration is used, the interpolation position used 2303 for the variable must: also fall within the bounds of the primitive 2304 being rasterized. 2305 * If the code:Sample decoration is used, the interpolation position used 2306 for the variable must: be at the position of the sample being shaded by 2307 the current fragment shader invocation. 2308 * If a sample count of 1 is used, the interpolation position must: be at 2309 the center of the fragment area. 2310 2311[NOTE] 2312.Note 2313==== 2314As code:Centroid restricts the possible interpolation position to the 2315covered area of the primitive, the position can be forced to vary between 2316neighboring fragments when it otherwise would not. 2317Derivatives calculated based on these differing locations can produce 2318inconsistent results compared to undecorated inputs. 2319It is recommended that input variables used in derivative calculations are 2320not decorated with code:Centroid. 2321==== 2322 2323ifdef::VK_NV_fragment_shader_barycentric,VK_KHR_fragment_shader_barycentric[] 2324[[shaders-interpolation-decorations-pervertexkhr]] 2325If the code:PerVertexKHR decoration is present on an input variable, the 2326value is not interpolated, and instead values from all input vertices are 2327available in an array. 2328Each index of the array corresponds to one of the vertices of the primitive 2329that produced the fragment. 2330endif::VK_NV_fragment_shader_barycentric,VK_KHR_fragment_shader_barycentric[] 2331 2332ifdef::VK_AMD_shader_explicit_vertex_parameter[] 2333If the code:CustomInterpAMD decoration is present on an input variable, the 2334value cannot: be accessed directly; instead the extended instruction 2335code:InterpolateAtVertexAMD must: be used to obtain values from the input 2336vertices. 2337endif::VK_AMD_shader_explicit_vertex_parameter[] 2338 2339 2340[[shaders-staticuse]] 2341== Static Use 2342 2343A SPIR-V module declares a global object in memory using the code:OpVariable 2344instruction, which results in a pointer code:x to that object. 2345A specific entry point in a SPIR-V module is said to _statically use_ that 2346object if that entry point's call tree contains a function containing a 2347instruction with code:x as an code:id operand. 2348A shader entry point also _statically uses_ any variables explicitly 2349declared in its interface. 2350 2351 2352[[shaders-scope]] 2353== Scope 2354 2355A _scope_ describes a set of shader invocations, where each such set is a 2356_scope instance_. 2357Each invocation belongs to one or more scope instances, but belongs to no 2358more than one scope instance for each scope. 2359 2360The operations available between invocations in a given scope instance vary, 2361with smaller scopes generally able to perform more operations, and with 2362greater efficiency. 2363 2364 2365[[shaders-scope-cross-device]] 2366=== Cross Device 2367 2368All invocations executed in a Vulkan instance fall into a single _cross 2369device scope instance_. 2370 2371Whilst the code:CrossDevice scope is defined in SPIR-V, it is disallowed in 2372Vulkan. 2373API <<synchronization, synchronization>> commands can: be used to 2374communicate between devices. 2375 2376 2377[[shaders-scope-device]] 2378=== Device 2379 2380All invocations executed on a single device form a _device scope instance_. 2381 2382ifdef::VK_VERSION_1_2,VK_KHR_vulkan_memory_model[] 2383If the <<features-vulkanMemoryModel, pname:vulkanMemoryModel>> and 2384<<features-vulkanMemoryModelDeviceScope, 2385pname:vulkanMemoryModelDeviceScope>> features are enabled, this scope is 2386represented in SPIR-V by the code:Device code:Scope, which can: be used as a 2387code:Memory code:Scope for barrier and atomic operations. 2388 2389ifdef::VK_KHR_shader_clock[] 2390If both the <<features-shaderDeviceClock, pname:shaderDeviceClock>> and 2391<<features-vulkanMemoryModelDeviceScope, 2392pname:vulkanMemoryModelDeviceScope>> features are enabled, using the 2393code:Device code:Scope with the code:OpReadClockKHR instruction will read 2394from a clock that is consistent across invocations in the same device scope 2395instance. 2396endif::VK_KHR_shader_clock[] 2397endif::VK_VERSION_1_2,VK_KHR_vulkan_memory_model[] 2398 2399There is no method to synchronize the execution of these invocations within 2400SPIR-V, and this can: only be done with API synchronization primitives. 2401 2402ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 2403Invocations executing on different devices in a device group operate in 2404separate device scope instances. 2405endif::VK_VERSION_1_1,VK_KHR_device_group[] 2406 2407ifndef::VK_VERSION_1_2,VK_KHR_vulkan_memory_model[] 2408The scope only extends to the queue family, not the whole device. 2409endif::VK_VERSION_1_2,VK_KHR_vulkan_memory_model[] 2410 2411 2412[[shaders-scope-queue-family]] 2413=== Queue Family 2414 2415Invocations executed by queues in a given queue family form a _queue family 2416scope instance_. 2417 2418This scope is identified in SPIR-V as the 2419ifdef::VK_VERSION_1_2,VK_KHR_vulkan_memory_model[] 2420code:QueueFamily code:Scope if the <<features-vulkanMemoryModel, 2421pname:vulkanMemoryModel>> feature is enabled, or if not, the 2422endif::VK_VERSION_1_2,VK_KHR_vulkan_memory_model[] 2423code:Device code:Scope, which can: be used as a code:Memory code:Scope for 2424barrier and atomic operations. 2425 2426ifdef::VK_KHR_shader_clock[] 2427If the <<features-shaderDeviceClock, pname:shaderDeviceClock>> feature is 2428enabled, 2429ifdef::VK_VERSION_1_2,VK_KHR_vulkan_memory_model[] 2430but the <<features-vulkanMemoryModelDeviceScope, 2431pname:vulkanMemoryModelDeviceScope>> feature is not enabled, 2432endif::VK_VERSION_1_2,VK_KHR_vulkan_memory_model[] 2433using the code:Device code:Scope with the code:OpReadClockKHR instruction 2434will read from a clock that is consistent across invocations in the same 2435queue family scope instance. 2436endif::VK_KHR_shader_clock[] 2437 2438There is no method to synchronize the execution of these invocations within 2439SPIR-V, and this can: only be done with API synchronization primitives. 2440 2441Each invocation in a queue family scope instance must: be in the same 2442<<shaders-scope-device, device scope instance>>. 2443 2444 2445[[shaders-scope-command]] 2446=== Command 2447 2448Any shader invocations executed as the result of a single command such as 2449flink:vkCmdDispatch or flink:vkCmdDraw form a _command scope instance_. 2450For indirect drawing commands with pname:drawCount greater than one, 2451invocations from separate draws are in separate command scope instances. 2452ifdef::VK_KHR_ray_tracing_pipeline,VK_NV_ray_tracing[] 2453For ray tracing shaders, an invocation group is an implementation-dependent 2454subset of the set of shader invocations of a given shader stage which are 2455produced by a single trace rays command. 2456endif::VK_KHR_ray_tracing_pipeline,VK_NV_ray_tracing[] 2457 2458There is no specific code:Scope for communication across invocations in a 2459command scope instance. 2460As this has a clear boundary at the API level, coordination here can: be 2461performed in the API, rather than in SPIR-V. 2462 2463Each invocation in a command scope instance must: be in the same 2464<<shaders-scope-queue-family, queue-family scope instance>>. 2465 2466For shaders without defined <<shaders-scope-workgroup, workgroups>>, this 2467set of invocations forms an _invocation group_ as defined in the 2468<<spirv-spec,SPIR-V specification>>. 2469 2470 2471[[shaders-scope-primitive]] 2472=== Primitive 2473 2474Any fragment shader invocations executed as the result of rasterization of a 2475single primitive form a _primitive scope instance_. 2476 2477There is no specific code:Scope for communication across invocations in a 2478primitive scope instance. 2479 2480Any generated <<shaders-helper-invocations, helper invocations>> are 2481included in this scope instance. 2482 2483Each invocation in a primitive scope instance must: be in the same 2484<<shaders-scope-command, command scope instance>>. 2485 2486Any input variables decorated with code:Flat are uniform within a primitive 2487scope instance. 2488 2489 2490// intentionally no VK_NV_ray_tracing here since this scope does not exist there 2491ifdef::VK_KHR_ray_tracing_pipeline[] 2492[[shaders-scope-shadercall]] 2493=== Shader Call 2494 2495Any <<shader-call-related,shader-call-related>> invocations that are 2496executed in one or more ray tracing execution models form a _shader call 2497scope instance_. 2498 2499The code:ShaderCallKHR code:Scope can be used as code:Memory code:Scope for 2500barrier and atomic operations. 2501 2502Each invocation in a shader call scope instance must: be in the same 2503<<shaders-scope-queue-family, queue family scope instance>>. 2504endif::VK_KHR_ray_tracing_pipeline[] 2505 2506 2507[[shaders-scope-workgroup]] 2508=== Workgroup 2509 2510A _local workgroup_ is a set of invocations that can synchronize and share 2511data with each other using memory in the code:Workgroup storage class. 2512 2513The code:Workgroup code:Scope can be used as both an code:Execution 2514code:Scope and code:Memory code:Scope for barrier and atomic operations. 2515 2516Each invocation in a local workgroup must: be in the same 2517<<shaders-scope-command, command scope instance>>. 2518 2519Only 2520ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 2521task, mesh, and 2522endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 2523compute shaders have defined workgroups - other shader types cannot: use 2524workgroup functionality. 2525For shaders that have defined workgroups, this set of invocations forms an 2526_invocation group_ as defined in the <<spirv-spec,SPIR-V specification>>. 2527 2528[[workgroup-padding]] 2529ifdef::VK_KHR_workgroup_memory_explicit_layout[] 2530When variables declared with the code:Workgroup storage class are explicitly 2531laid out (hence they are also decorated with code:Block), the amount of 2532storage consumed is the size of the largest Block variable, not counting any 2533padding at the end. 2534endif::VK_KHR_workgroup_memory_explicit_layout[] 2535The amount of storage consumed by the 2536ifdef::VK_KHR_workgroup_memory_explicit_layout[] 2537non-Block 2538endif::VK_KHR_workgroup_memory_explicit_layout[] 2539variables declared with the code:Workgroup storage class is 2540implementation-dependent. 2541However, the amount of storage consumed may not exceed the largest block 2542size that would be obtained if all active 2543ifdef::VK_KHR_workgroup_memory_explicit_layout[] 2544non-Block 2545endif::VK_KHR_workgroup_memory_explicit_layout[] 2546variables declared with code:Workgroup storage class were assigned offsets 2547in an arbitrary order by successively taking the smallest valid offset 2548according to the <<interfaces-resources-standard-layout,Standard Storage 2549Buffer Layout>> rules, and with code:Boolean values considered as 32-bit 2550integer values for the purpose of this calculation. 2551(This is equivalent to using the GLSL std430 layout rules.) 2552 2553 2554ifdef::VK_VERSION_1_1[] 2555[[shaders-scope-subgroup]] 2556=== Subgroup 2557 2558A _subgroup_ (see the subsection "`Control Flow`" of section 2 of the SPIR-V 25591.3 Revision 1 specification) is a set of invocations that can synchronize 2560and share data with each other efficiently. 2561 2562The code:Subgroup code:Scope can be used as both an code:Execution 2563code:Scope and code:Memory code:Scope for barrier and atomic operations. 2564Other <<VkSubgroupFeatureFlagBits, subgroup features>> allow the use of 2565<<shaders-group-operations, group operations>> with subgroup scope. 2566 2567ifdef::VK_KHR_shader_clock[] 2568If the <<features-shaderSubgroupClock, pname:shaderSubgroupClock>> feature 2569is enabled, using the code:Subgroup code:Scope with the code:OpReadClockKHR 2570instruction will read from a clock that is consistent across invocations in 2571the same subgroup. 2572endif::VK_KHR_shader_clock[] 2573 2574For <<shaders-scope-workgroup, shaders that have defined workgroups>>, each 2575invocation in a subgroup must: be in the same <<shaders-scope-workgroup, 2576local workgroup>>. 2577 2578In other shader stages, each invocation in a subgroup must: be in the same 2579<<shaders-scope-device, device scope instance>>. 2580 2581Only <<limits-subgroup-supportedStages, shader stages that support subgroup 2582operations>> have defined subgroups. 2583 2584[NOTE] 2585.Note 2586==== 2587In shaders, there are two kinds of uniformity that are of primary interest 2588to applications: uniform within an invocation group (a.k.a. 2589dynamically uniform), and uniform within a subgroup scope. 2590 2591While one could make the assumption that being uniform in invocation group 2592implies being uniform in subgroup scope, it is not necessarily the case for 2593shader stages without defined workgroups. 2594 2595For shader stages with defined workgroups however, the relationship between 2596invocation group and subgroup scope is well defined as a subgroup is a 2597subset of the workgroup, and the workgroup is the invocation group. 2598If a value is uniform in invocation group, it is by definition also uniform 2599in subgroup scope. 2600This is important if writing code like: 2601 2602[source,glsl] 2603---- 2604uniform texture2D Textures[]; 2605uint dynamicallyUniformValue = gl_WorkGroupID.x; 2606vec4 value = texelFetch(Textures[dynamicallyUniformValue], coord, 0); 2607 2608// subgroupUniformValue is guaranteed to be uniform within the subgroup. 2609// This value also happens to be dynamically uniform. 2610vec4 subgroupUniformValue = subgroupBroadcastFirst(dynamicallyUniformValue); 2611---- 2612 2613In shader stages without defined workgroups, this gets complicated. 2614Due to scoping rules, there is no guarantee that a subgroup is a subset of 2615the invocation group, which in turn defines the scope for dynamically 2616uniform. 2617In graphics, the invocation group is a single draw command, except for 2618multi-draw situations, and indirect draws with drawCount > 1, where there 2619are multiple invocation groups, one per code:DrawIndex. 2620 2621[source,glsl] 2622---- 2623// Assume SubgroupSize = 8, where 3 draws are packed together. 2624// Two subgroups were generated. 2625uniform texture2D Textures[]; 2626 2627// DrawIndex builtin is dynamically uniform 2628uint dynamicallyUniformValue = gl_DrawID; 2629// | gl_DrawID = 0 | gl_DrawID = 1 | } 2630// Subgroup 0: { 0, 0, 0, 0, 1, 1, 1, 1 } 2631// | DrawID = 2 | DrawID = 1 | } 2632// Subgroup 1: { 2, 2, 2, 2, 1, 1, 1, 1 } 2633 2634uint notActuallyDynamicallyUniformAnymore = 2635 subgroupBroadcastFirst(dynamicallyUniformValue); 2636// | gl_DrawID = 0 | gl_DrawID = 1 | } 2637// Subgroup 0: { 0, 0, 0, 0, 0, 0, 0, 0 } 2638// | gl_DrawID = 2 | gl_DrawID = 1 | } 2639// Subgroup 1: { 2, 2, 2, 2, 2, 2, 2, 2 } 2640 2641// Bug. gl_DrawID = 1's invocation group observes both index 0 and 2. 2642vec4 value = texelFetch(Textures[notActuallyDynamicallyUniformAnymore], 2643 coord, 0); 2644---- 2645 2646Another problematic scenario is when a shader attempts to help the compiler 2647notice that a value is uniform in subgroup scope to potentially improve 2648performance. 2649 2650[source,c] 2651---- 2652layout(location = 0) flat in dynamicallyUniformIndex; 2653// Vertex shader might have emitted a value that depends only on gl_DrawID, 2654// making it dynamically uniform. 2655// Give knowledge to compiler that the flat input is dynamically uniform, 2656// as this is not a guarantee otherwise. 2657 2658uint uniformIndex = subgroupBroadcastFirst(dynamicallyUniformIndex); 2659// Hazard: If different draw commands are packed into one subgroup, the uniformIndex is wrong. 2660 2661DrawData d = UBO.perDrawData[uniformIndex]; 2662---- 2663 2664For implementations where subgroups are packed across draws, the 2665implementation must make sure to handle descriptor indexing correctly. 2666From the specification's point of view, a dynamically uniform index does not 2667require code:NonUniform decoration, and such an implementation will likely 2668either promote descriptor indexing into code:NonUniform on its own, or 2669handle non-uniformity implicitly. 2670==== 2671endif::VK_VERSION_1_1[] 2672 2673 2674[[shaders-scope-quad]] 2675=== Quad 2676 2677A _quad scope instance_ is formed of four shader invocations. 2678 2679In a fragment shader, each invocation in a quad scope instance is formed of 2680invocations in neighboring framebuffer locations [eq]#(x~i~, y~i~)#, where: 2681 2682 * [eq]#i# is the index of the invocation within the scope instance. 2683 * [eq]#w# and [eq]#h# are the number of pixels the fragment covers in the 2684 [eq]#x# and [eq]#y# axes. 2685 * [eq]#w# and [eq]#h# are identical for all participating invocations. 2686 * [eq]#(x~0~) = (x~1~ - w) = (x~2~) = (x~3~ - w)# 2687 * [eq]#(y~0~) = (y~1~) = (y~2~ - h) = (y~3~ - h)# 2688 * Each invocation has the same layer and sample indices. 2689 2690ifdef::VK_NV_compute_shader_derivatives[] 2691In a compute shader, if the code:DerivativeGroupQuadsNV execution mode is 2692specified, each invocation in a quad scope instance is formed of invocations 2693with adjacent local invocation IDs [eq]#(x~i~, y~i~)#, where: 2694 2695 * [eq]#i# is the index of the invocation within the quad scope instance. 2696 * [eq]#(x~0~) = (x~1~ - 1) = (x~2~) = (x~3~ - 1)# 2697 * [eq]#(y~0~) = (y~1~) = (y~2~ - 1) = (y~3~ - 1)# 2698 * [eq]#x~0~# and [eq]#y~0~# are integer multiples of 2. 2699 * Each invocation has the same [eq]#z# coordinate. 2700 2701In a compute shader, if the code:DerivativeGroupLinearNV execution mode is 2702specified, each invocation in a quad scope instance is formed of invocations 2703with adjacent local invocation indices [eq]#(l~i~)#, where: 2704 2705 * [eq]#i# is the index of the invocation within the quad scope instance. 2706 * [eq]#(l~0~) = (l~1~ - 1) = (l~2~ - 2) = (l~3~ - 3)# 2707 * [eq]#l~0~# is an integer multiple of 4. 2708 2709endif::VK_NV_compute_shader_derivatives[] 2710 2711ifdef::VK_VERSION_1_1[] 2712In all shaders, each invocation in a quad scope instance is formed of 2713invocations in adjacent subgroup invocation indices [eq]#(s~i~)#, where: 2714 2715 * [eq]#i# is the index of the invocation within the quad scope instance. 2716 * [eq]#(s~0~) = (s~1~ - 1) = (s~2~ - 2) = (s~3~ - 3)# 2717 * [eq]#s~0~# is an integer multiple of 4. 2718 2719Each invocation in a quad scope instance must: be in the same 2720<<shaders-scope-subgroup, subgroup>>. 2721endif::VK_VERSION_1_1[] 2722 2723ifndef::VK_VERSION_1_1[] 2724The specific set of invocations that make up a quad scope instance in other 2725shader stages is undefined:. 2726endif::VK_VERSION_1_1[] 2727 2728In a fragment shader, each invocation in a quad scope instance must: be in 2729the same <<shaders-scope-primitive, primitive scope instance>>. 2730 2731ifndef::VK_VERSION_1_1[] 2732For <<shaders-scope-workgroup, shaders that have defined workgroups>>, each 2733invocation in a quad scope instance must: be in the same 2734<<shaders-scope-workgroup, local workgroup>>. 2735 2736In other shader stages, each invocation in a quad scope instance must: be in 2737the same <<shaders-scope-device, device scope instance>>. 2738endif::VK_VERSION_1_1[] 2739 2740Fragment 2741ifdef::VK_NV_compute_shader_derivatives,VK_VERSION_1_1[] 2742and compute 2743endif::VK_NV_compute_shader_derivatives,VK_VERSION_1_1[] 2744shaders have defined quad scope instances. 2745ifdef::VK_VERSION_1_1[] 2746If the <<limits-subgroup-quadOperationsInAllStages, 2747pname:quadOperationsInAllStages>> limit is supported, any 2748<<limits-subgroup-supportedStages, shader stages that support subgroup 2749operations>> also have defined quad scope instances. 2750endif::VK_VERSION_1_1[] 2751 2752 2753ifdef::VK_EXT_fragment_shader_interlock[] 2754[[shaders-scope-fragment-interlock]] 2755=== Fragment Interlock 2756 2757A _fragment interlock scope instance_ is formed of fragment shader 2758invocations based on their framebuffer locations [eq]#(x,y,layer,sample)#, 2759executed by commands inside a single <<renderpass,subpass>>. 2760 2761The specific set of invocations included varies based on the execution mode 2762as follows: 2763 2764 * If the code:SampleInterlockOrderedEXT or 2765 code:SampleInterlockUnorderedEXT execution modes are used, only 2766 invocations with identical framebuffer locations 2767 [eq]#(x,y,layer,sample)# are included. 2768 * If the code:PixelInterlockOrderedEXT or code:PixelInterlockUnorderedEXT 2769 execution modes are used, fragments with different sample ids are also 2770 included. 2771ifdef::VK_NV_shading_rate_image,VK_KHR_fragment_shading_rate[] 2772 * If the code:ShadingRateInterlockOrderedEXT or 2773 code:ShadingRateInterlockUnorderedEXT execution modes are used, 2774 fragments from neighbouring framebuffer locations are also included. 2775 The 2776ifdef::VK_NV_shading_rate_image[<<primsrast-shading-rate-image, shading rate image>>] 2777ifdef::VK_KHR_fragment_shading_rate+VK_NV_shading_rate_image[or] 2778ifdef::VK_KHR_fragment_shading_rate[<<primsrast-fragment-shading-rate, fragment shading rate>>] 2779 determines these fragments. 2780endif::VK_NV_shading_rate_image,VK_KHR_fragment_shading_rate[] 2781 2782Only fragment shaders with one of the above execution modes have defined 2783fragment interlock scope instances. 2784 2785There is no specific code:Scope value for communication across invocations 2786in a fragment interlock scope instance. 2787However, this is implicitly used as a memory scope by 2788code:OpBeginInvocationInterlockEXT and code:OpEndInvocationInterlockEXT. 2789 2790Each invocation in a fragment interlock scope instance must: be in the same 2791<<shaders-scope-queue-family, queue family scope instance>>. 2792endif::VK_EXT_fragment_shader_interlock[] 2793 2794 2795[[shaders-scope-invocation]] 2796=== Invocation 2797 2798The smallest _scope_ is a single invocation; this is represented by the 2799code:Invocation code:Scope in SPIR-V. 2800 2801Fragment shader invocations must: be in a <<shaders-scope-primitive, 2802primitive scope instance>>. 2803 2804ifdef::VK_EXT_fragment_shader_interlock[] 2805Invocations in <<shaders-scope-fragment-interlock, fragment shaders that 2806have a defined fragment interlock scope>> must: be in a 2807<<shaders-scope-fragment-interlock, fragment interlock scope instance>>. 2808endif::VK_EXT_fragment_shader_interlock[] 2809 2810Invocations in <<shaders-scope-workgroup, shaders that have defined 2811workgroups>> must: be in a <<shaders-scope-workgroup, local workgroup>>. 2812 2813ifdef::VK_VERSION_1_1[] 2814Invocations in <<shaders-scope-subgroup, shaders that have a defined 2815subgroup scope>> must: be in a <<shaders-scope-subgroup, subgroup>>. 2816endif::VK_VERSION_1_1[] 2817 2818Invocations in <<shaders-scope-quad, shaders that have a defined quad 2819scope>> must: be in a <<shaders-scope-quad, quad scope instance>>. 2820 2821All invocations in all stages must: be in a <<shaders-scope-command,command 2822scope instance>>. 2823 2824 2825ifdef::VK_VERSION_1_1[] 2826[[shaders-group-operations]] 2827== Group Operations 2828 2829_Group operations_ are executed by multiple invocations within a 2830<<shaders-scope, scope instance>>; with each invocation involved in 2831calculating the result. 2832This provides a mechanism for efficient communication between invocations in 2833a particular scope instance. 2834 2835Group operations all take a code:Scope defining the desired 2836<<shaders-scope,scope instance>> to operate within. 2837Only the code:Subgroup scope can: be used for these operations; the 2838<<limits-subgroupSupportedOperations, pname:subgroupSupportedOperations>> 2839limit defines which types of operation can: be used. 2840 2841 2842[[shaders-group-operations-basic]] 2843=== Basic Group Operations 2844 2845Basic group operations include the use of code:OpGroupNonUniformElect, 2846code:OpControlBarrier, code:OpMemoryBarrier, and atomic operations. 2847 2848code:OpGroupNonUniformElect can: be used to choose a single invocation to 2849perform a task for the whole group. 2850Only the invocation with the lowest id in the group will return code:true. 2851 2852The <<memory-model,Memory Model>> appendix defines the operation of barriers 2853and atomics. 2854 2855 2856[[shaders-group-operations-vote]] 2857=== Vote Group Operations 2858 2859The vote group operations allow invocations within a group to compare values 2860across a group. 2861The types of votes enabled are: 2862 2863 * Do all active group invocations agree that an expression is true? 2864 * Do any active group invocations evaluate an expression to true? 2865 * Do all active group invocations have the same value of an expression? 2866 2867[NOTE] 2868.Note 2869==== 2870These operations are useful in combination with control flow in that they 2871allow for developers to check whether conditions match across the group and 2872choose potentially faster code-paths in these cases. 2873==== 2874 2875 2876[[shaders-group-operations-arithmetic]] 2877=== Arithmetic Group Operations 2878 2879The arithmetic group operations allow invocations to perform scans and 2880reductions across a group. 2881The operators supported are add, mul, min, max, and, or, xor. 2882 2883For reductions, every invocation in a group will obtain the cumulative 2884result of these operators applied to all values in the group. 2885For exclusive scans, each invocation in a group will obtain the cumulative 2886result of these operators applied to all values in invocations with a lower 2887index in the group. 2888Inclusive scans are identical to exclusive scans, except the cumulative 2889result includes the operator applied to the value in the current invocation. 2890 2891The order in which these operators are applied is implementation-dependent. 2892 2893 2894[[shaders-group-operations-ballot]] 2895=== Ballot Group Operations 2896 2897The ballot group operations allow invocations to perform more complex votes 2898across the group. 2899The ballot functionality allows all invocations within a group to provide a 2900boolean value and get as a result what each invocation provided as their 2901boolean value. 2902The broadcast functionality allows values to be broadcast from an invocation 2903to all other invocations within the group. 2904 2905 2906[[shaders-group-operations-shuffle]] 2907=== Shuffle Group Operations 2908 2909The shuffle group operations allow invocations to read values from other 2910invocations within a group. 2911 2912 2913[[shaders-group-operations-shuffle-relative]] 2914=== Shuffle Relative Group Operations 2915 2916The shuffle relative group operations allow invocations to read values from 2917other invocations within the group relative to the current invocation in the 2918group. 2919The relative operations supported allow data to be shifted up and down 2920through the invocations within a group. 2921 2922 2923[[shaders-group-operations-clustered]] 2924=== Clustered Group Operations 2925 2926The clustered group operations allow invocations to perform an operation 2927among partitions of a group, such that the operation is only performed 2928within the group invocations within a partition. 2929The partitions for clustered group operations are consecutive power-of-two 2930size groups of invocations and the cluster size must: be known at pipeline 2931creation time. 2932The operations supported are add, mul, min, max, and, or, xor. 2933 2934 2935[[shaders-quad-operations]] 2936== Quad Group Operations 2937 2938Quad group operations (code:OpGroupNonUniformQuad*) are a specialized type 2939of <<shaders-group-operations, group operations>> that only operate on 2940<<shaders-scope-quad, quad scope instances>>. 2941Whilst these instructions do include a code:Scope parameter, this scope is 2942always overridden; only the <<shaders-scope-quad, quad scope instance>> is 2943included in its execution scope. 2944 2945Fragment shaders that statically execute quad group operations must: launch 2946sufficient invocations to ensure their correct operation; additional 2947<<shaders-helper-invocations, helper invocations>> are launched for 2948framebuffer locations not covered by rasterized fragments if necessary. 2949 2950The index used to select participating invocations is [eq]#i#, as described 2951for a <<shaders-scope-quad, quad scope instance>>, defined as the _quad 2952index_ in the <<spirv-spec,SPIR-V specification>>. 2953 2954For code:OpGroupNonUniformQuadBroadcast this value is equal to code:Index. 2955For code:OpGroupNonUniformQuadSwap, it is equal to the implicit code:Index 2956used by each participating invocation. 2957endif::VK_VERSION_1_1[] 2958 2959 2960[[shaders-derivative-operations]] 2961== Derivative Operations 2962 2963Derivative operations calculate the partial derivative for an expression 2964[eq]#P# as a function of an invocation's [eq]#x# and [eq]#y# coordinates. 2965 2966Derivative operations operate on a set of invocations known as a _derivative 2967group_ as defined in the <<spirv-spec,SPIR-V specification>>. 2968A derivative group is equivalent to 2969ifdef::VK_NV_compute_shader_derivatives[] 2970the <<shaders-scope-quad, quad scope instance>> for a compute shader 2971invocation, or 2972endif::VK_NV_compute_shader_derivatives[] 2973the <<shaders-scope-primitive, primitive scope instance>> for a fragment 2974shader invocation. 2975 2976Derivatives are calculated assuming that [eq]#P# is piecewise linear and 2977continuous within the derivative group. 2978All dynamic instances of explicit derivative instructions (code:OpDPdx*, 2979code:OpDPdy*, and code:OpFwidth*) must: be executed in control flow that is 2980uniform within a derivative group. 2981For other derivative operations, results are undefined: if a dynamic 2982instance is executed in control flow that is not uniform within the 2983derivative group. 2984 2985Fragment shaders that statically execute derivative operations must: launch 2986sufficient invocations to ensure their correct operation; additional 2987<<shaders-helper-invocations, helper invocations>> are launched for 2988framebuffer locations not covered by rasterized fragments if necessary. 2989 2990ifdef::VK_NV_compute_shader_derivatives[] 2991[NOTE] 2992.Note 2993==== 2994In a compute shader, it is the application's responsibility to ensure that 2995sufficient invocations are launched. 2996==== 2997endif::VK_NV_compute_shader_derivatives[] 2998 2999Derivative operations calculate their results as the difference between the 3000result of [eq]#P# across invocations in the quad. 3001For fine derivative operations (code:OpDPdxFine and code:OpDPdyFine), the 3002values of [eq]#DPdx(P~i~)# are calculated as 3003 3004 {empty}:: [eq]#DPdx(P~0~) = DPdx(P~1~) = P~1~ - P~0~# 3005 {empty}:: [eq]#DPdx(P~2~) = DPdx(P~3~) = P~3~ - P~2~# 3006 3007and the values of [eq]#DPdy(P~i~)# are calculated as 3008 3009 {empty}:: [eq]#DPdy(P~0~) = DPdy(P~2~) = P~2~ - P~0~# 3010 {empty}:: [eq]#DPdy(P~1~) = DPdy(P~3~) = P~3~ - P~1~# 3011 3012where [eq]#i# is the index of each invocation as described in 3013<<shaders-scope-quad>>. 3014 3015Coarse derivative operations (code:OpDPdxCoarse and code:OpDPdyCoarse), 3016calculate their results in roughly the same manner, but may: only calculate 3017two values instead of four (one for each of [eq]#DPdx# and [eq]#DPdy#), 3018reusing the same result no matter the originating invocation. 3019If an implementation does this, it should: use the fine derivative 3020calculations described for [eq]#P~0~#. 3021 3022[NOTE] 3023.Note 3024==== 3025Derivative values are calculated between fragments rather than pixels. 3026If the fragment shader invocations involved in the calculation cover 3027multiple pixels, these operations cover a wider area, resulting in larger 3028derivative values. 3029This in turn will result in a coarser LOD being selected for image sampling 3030operations using derivatives. 3031 3032Applications may want to account for this when using multi-pixel fragments; 3033if pixel derivatives are desired, applications should use explicit 3034derivative operations and divide the results by the size of the fragment in 3035each dimension as follows: 3036 3037 {empty}:: [eq]#DPdx(P~n~)' = DPdx(P~n~) / w# 3038 {empty}:: [eq]#DPdy(P~n~)' = DPdy(P~n~) / h# 3039 3040where [eq]#w# and [eq]#h# are the size of the fragments in the quad, and 3041[eq]#DPdx(P~n~)'# and [eq]#DPdy(P~n~)'# are the pixel derivatives. 3042==== 3043 3044The results for code:OpDPdx and code:OpDPdy may: be calculated as either 3045fine or coarse derivatives, with implementations favouring the most 3046efficient approach. 3047Implementations must: choose coarse or fine consistently between the two. 3048 3049Executing code:OpFwidthFine, code:OpFwidthCoarse, or code:OpFwidth is 3050equivalent to executing the corresponding code:OpDPdx* and code:OpDPdy* 3051instructions, taking the absolute value of the results, and summing them. 3052 3053Executing an code:OpImage*Sample*ImplicitLod instruction is equivalent to 3054executing code:OpDPdx(code:Coordinate) and code:OpDPdy(code:Coordinate), and 3055passing the results as the code:Grad operands code:dx and code:dy. 3056 3057[NOTE] 3058.Note 3059==== 3060It is expected that using the code:ImplicitLod variants of sampling 3061functions will be substantially more efficient than using the 3062code:ExplicitLod variants with explicitly generated derivatives. 3063==== 3064 3065 3066[[shaders-helper-invocations]] 3067== Helper Invocations 3068 3069When performing <<shaders-derivative-operations, derivative>> 3070ifdef::VK_VERSION_1_1[] 3071or <<shaders-quad-operations, quad group>> 3072endif::VK_VERSION_1_1[] 3073operations in a fragment shader, additional invocations may: be spawned in 3074order to ensure correct results. 3075These additional invocations are known as _helper invocations_ and can: be 3076identified by a non-zero value in the code:HelperInvocation built-in. 3077Stores and atomics performed by helper invocations must: not have any effect 3078on memory except for the code:Function, code:Private and code:Output storage 3079classes, and values returned by atomic instructions in helper invocations 3080are undefined:. 3081 3082[NOTE] 3083.Note 3084==== 3085While storage to code:Output storage class has an effect even in helper 3086invocations, it does not mean that helper invocations have an effect on the 3087framebuffer. 3088code:Output variables in fragment shaders can be read from as well, and they 3089behave more like code:Private variables for the duration of the shader 3090invocation. 3091==== 3092 3093For <<shaders-group-operations, group operations>> other than 3094<<shaders-derivative-operations, derivative>> 3095ifdef::VK_VERSION_1_1[] 3096and <<shaders-quad-operations, quad group>> 3097endif::VK_VERSION_1_1[] 3098operations, helper invocations may: be treated as inactive even if they 3099would be considered otherwise active. 3100 3101ifdef::VK_VERSION_1_3,VK_EXT_shader_demote_to_helper_invocation[] 3102Helper invocations may: become permanently inactive if all invocations in a 3103quad scope instance become helper invocations. 3104endif::VK_VERSION_1_3,VK_EXT_shader_demote_to_helper_invocation[] 3105 3106 3107ifdef::VK_NV_cooperative_matrix,VK_KHR_cooperative_matrix[] 3108== Cooperative Matrices 3109 3110A _cooperative matrix_ type is a SPIR-V type where the storage for and 3111computations performed on the matrix are spread across the invocations in a 3112scope instance. 3113These types give the implementation freedom in how to optimize matrix 3114multiplies. 3115 3116SPIR-V defines the types and instructions, but does not specify rules about 3117what sizes/combinations are valid, and it is expected that different 3118implementations may: support different sizes. 3119 3120ifdef::VK_KHR_cooperative_matrix[] 3121[open,refpage='vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR',desc='Returns properties describing what cooperative matrix types are supported',type='protos'] 3122-- 3123To enumerate the supported cooperative matrix types and operations, call: 3124 3125include::{generated}/api/protos/vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR.adoc[] 3126 3127 * pname:physicalDevice is the physical device. 3128 * pname:pPropertyCount is a pointer to an integer related to the number of 3129 cooperative matrix properties available or queried. 3130 * pname:pProperties is either `NULL` or a pointer to an array of 3131 slink:VkCooperativeMatrixPropertiesKHR structures. 3132 3133If pname:pProperties is `NULL`, then the number of cooperative matrix 3134properties available is returned in pname:pPropertyCount. 3135Otherwise, pname:pPropertyCount must: point to a variable set by the user to 3136the number of elements in the pname:pProperties array, and on return the 3137variable is overwritten with the number of structures actually written to 3138pname:pProperties. 3139If pname:pPropertyCount is less than the number of cooperative matrix 3140properties available, at most pname:pPropertyCount structures will be 3141written, and ename:VK_INCOMPLETE will be returned instead of 3142ename:VK_SUCCESS, to indicate that not all the available cooperative matrix 3143properties were returned. 3144 3145include::{generated}/validity/protos/vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR.adoc[] 3146-- 3147endif::VK_KHR_cooperative_matrix[] 3148 3149ifdef::VK_NV_cooperative_matrix[] 3150[open,refpage='vkGetPhysicalDeviceCooperativeMatrixPropertiesNV',desc='Returns properties describing what cooperative matrix types are supported',type='protos'] 3151-- 3152To enumerate the supported cooperative matrix types and operations, call: 3153 3154include::{generated}/api/protos/vkGetPhysicalDeviceCooperativeMatrixPropertiesNV.adoc[] 3155 3156 * pname:physicalDevice is the physical device. 3157 * pname:pPropertyCount is a pointer to an integer related to the number of 3158 cooperative matrix properties available or queried. 3159 * pname:pProperties is either `NULL` or a pointer to an array of 3160 slink:VkCooperativeMatrixPropertiesNV structures. 3161 3162If pname:pProperties is `NULL`, then the number of cooperative matrix 3163properties available is returned in pname:pPropertyCount. 3164Otherwise, pname:pPropertyCount must: point to a variable set by the user to 3165the number of elements in the pname:pProperties array, and on return the 3166variable is overwritten with the number of structures actually written to 3167pname:pProperties. 3168If pname:pPropertyCount is less than the number of cooperative matrix 3169properties available, at most pname:pPropertyCount structures will be 3170written, and ename:VK_INCOMPLETE will be returned instead of 3171ename:VK_SUCCESS, to indicate that not all the available cooperative matrix 3172properties were returned. 3173 3174include::{generated}/validity/protos/vkGetPhysicalDeviceCooperativeMatrixPropertiesNV.adoc[] 3175-- 3176endif::VK_NV_cooperative_matrix[] 3177 3178Each 3179ifdef::VK_KHR_cooperative_matrix[slink:VkCooperativeMatrixPropertiesKHR] 3180ifdef::VK_KHR_cooperative_matrix+VK_NV_cooperative_matrix[or] 3181ifdef::VK_NV_cooperative_matrix[slink:VkCooperativeMatrixPropertiesNV] 3182structure describes a single supported combination of types for a matrix 3183multiply/add operation ( 3184ifdef::VK_KHR_cooperative_matrix[code:OpCooperativeMatrixMulAddKHR] 3185ifdef::VK_KHR_cooperative_matrix+VK_NV_cooperative_matrix[or] 3186ifdef::VK_NV_cooperative_matrix[code:OpCooperativeMatrixMulAddNV] 3187). 3188The multiply can: be described in terms of the following variables and types 3189(in SPIR-V pseudocode): 3190 3191ifdef::VK_KHR_cooperative_matrix[] 3192[source,c] 3193---- 3194 %A is of type OpTypeCooperativeMatrixKHR %AType %scope %MSize %KSize %MatrixAKHR 3195 %B is of type OpTypeCooperativeMatrixKHR %BType %scope %KSize %NSize %MatrixBKHR 3196 %C is of type OpTypeCooperativeMatrixKHR %CType %scope %MSize %NSize %MatrixAccumulatorKHR 3197 %Result is of type OpTypeCooperativeMatrixKHR %ResultType %scope %MSize %NSize %MatrixAccumulatorKHR 3198 3199 %Result = %A * %B + %C // using OpCooperativeMatrixMulAddKHR 3200---- 3201endif::VK_KHR_cooperative_matrix[] 3202 3203ifdef::VK_NV_cooperative_matrix[] 3204[source,c] 3205---- 3206 %A is of type OpTypeCooperativeMatrixNV %AType %scope %MSize %KSize 3207 %B is of type OpTypeCooperativeMatrixNV %BType %scope %KSize %NSize 3208 %C is of type OpTypeCooperativeMatrixNV %CType %scope %MSize %NSize 3209 %D is of type OpTypeCooperativeMatrixNV %DType %scope %MSize %NSize 3210 3211 %D = %A * %B + %C // using OpCooperativeMatrixMulAddNV 3212---- 3213endif::VK_NV_cooperative_matrix[] 3214 3215A matrix multiply with these dimensions is known as an _MxNxK_ matrix 3216multiply. 3217 3218ifdef::VK_KHR_cooperative_matrix[] 3219[open,refpage='VkCooperativeMatrixPropertiesKHR',desc='Structure specifying cooperative matrix properties',type='structs'] 3220-- 3221The sname:VkCooperativeMatrixPropertiesKHR structure is defined as: 3222 3223include::{generated}/api/structs/VkCooperativeMatrixPropertiesKHR.adoc[] 3224 3225 * pname:sType is a elink:VkStructureType value identifying this structure. 3226 * pname:pNext is `NULL` or a pointer to a structure extending this 3227 structure. 3228 * pname:MSize is the number of rows in matrices code:A, code:C, and 3229 code:Result. 3230 * pname:KSize is the number of columns in matrix code:A and rows in matrix 3231 code:B. 3232 * pname:NSize is the number of columns in matrices code:B, code:C, 3233 code:Result. 3234 * pname:AType is the component type of matrix code:A, of type 3235 elink:VkComponentTypeKHR. 3236 * pname:BType is the component type of matrix code:B, of type 3237 elink:VkComponentTypeKHR. 3238 * pname:CType is the component type of matrix code:C, of type 3239 elink:VkComponentTypeKHR. 3240 * pname:ResultType is the component type of matrix code:Result, of type 3241 elink:VkComponentTypeKHR. 3242 * pname:saturatingAccumulation indicates whether the 3243 code:SaturatingAccumulation operand to code:OpCooperativeMatrixMulAddKHR 3244 must: be present. 3245 * pname:scope is the scope of all the matrix types, of type 3246 elink:VkScopeKHR. 3247 3248If some types are preferred over other types (e.g. for performance), they 3249should: appear earlier in the list enumerated by 3250flink:vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR. 3251 3252At least one entry in the list must: have power of two values for all of 3253pname:MSize, pname:KSize, and pname:NSize. 3254 3255include::{generated}/validity/structs/VkCooperativeMatrixPropertiesKHR.adoc[] 3256-- 3257endif::VK_KHR_cooperative_matrix[] 3258 3259ifdef::VK_NV_cooperative_matrix[] 3260[open,refpage='VkCooperativeMatrixPropertiesNV',desc='Structure specifying cooperative matrix properties',type='structs'] 3261-- 3262The sname:VkCooperativeMatrixPropertiesNV structure is defined as: 3263 3264include::{generated}/api/structs/VkCooperativeMatrixPropertiesNV.adoc[] 3265 3266 * pname:sType is a elink:VkStructureType value identifying this structure. 3267 * pname:pNext is `NULL` or a pointer to a structure extending this 3268 structure. 3269 * pname:MSize is the number of rows in matrices A, C, and D. 3270 * pname:KSize is the number of columns in matrix A and rows in matrix B. 3271 * pname:NSize is the number of columns in matrices B, C, D. 3272 * pname:AType is the component type of matrix A, of type 3273 elink:VkComponentTypeNV. 3274 * pname:BType is the component type of matrix B, of type 3275 elink:VkComponentTypeNV. 3276 * pname:CType is the component type of matrix C, of type 3277 elink:VkComponentTypeNV. 3278 * pname:DType is the component type of matrix D, of type 3279 elink:VkComponentTypeNV. 3280 * pname:scope is the scope of all the matrix types, of type 3281 elink:VkScopeNV. 3282 3283If some types are preferred over other types (e.g. for performance), they 3284should: appear earlier in the list enumerated by 3285flink:vkGetPhysicalDeviceCooperativeMatrixPropertiesNV. 3286 3287At least one entry in the list must: have power of two values for all of 3288pname:MSize, pname:KSize, and pname:NSize. 3289 3290include::{generated}/validity/structs/VkCooperativeMatrixPropertiesNV.adoc[] 3291-- 3292endif::VK_NV_cooperative_matrix[] 3293 3294[open,refpage='VkScopeKHR',desc='Specify SPIR-V scope',type='enums'] 3295-- 3296Possible values for elink:VkScopeKHR include: 3297 3298include::{generated}/api/enums/VkScopeKHR.adoc[] 3299 3300ifdef::VK_NV_cooperative_matrix[] 3301or the equivalent 3302 3303include::{generated}/api/enums/VkScopeNV.adoc[] 3304endif::VK_NV_cooperative_matrix[] 3305 3306 * ename:VK_SCOPE_DEVICE_KHR corresponds to SPIR-V code:Device scope. 3307 * ename:VK_SCOPE_WORKGROUP_KHR corresponds to SPIR-V code:Workgroup scope. 3308 * ename:VK_SCOPE_SUBGROUP_KHR corresponds to SPIR-V code:Subgroup scope. 3309 * ename:VK_SCOPE_QUEUE_FAMILY_KHR corresponds to SPIR-V code:QueueFamily 3310 scope. 3311 3312All enum values match the corresponding SPIR-V value. 3313-- 3314 3315[open,refpage='VkComponentTypeKHR',desc='Specify SPIR-V cooperative matrix component type',type='enums'] 3316-- 3317Possible values for elink:VkComponentTypeKHR include: 3318 3319include::{generated}/api/enums/VkComponentTypeKHR.adoc[] 3320 3321ifdef::VK_NV_cooperative_matrix[] 3322or the equivalent 3323 3324include::{generated}/api/enums/VkComponentTypeNV.adoc[] 3325endif::VK_NV_cooperative_matrix[] 3326 3327 * ename:VK_COMPONENT_TYPE_FLOAT16_KHR corresponds to SPIR-V 3328 code:OpTypeFloat 16. 3329 * ename:VK_COMPONENT_TYPE_FLOAT32_KHR corresponds to SPIR-V 3330 code:OpTypeFloat 32. 3331 * ename:VK_COMPONENT_TYPE_FLOAT64_KHR corresponds to SPIR-V 3332 code:OpTypeFloat 64. 3333 * ename:VK_COMPONENT_TYPE_SINT8_KHR corresponds to SPIR-V code:OpTypeInt 8 1. 3334 * ename:VK_COMPONENT_TYPE_SINT16_KHR corresponds to SPIR-V code:OpTypeInt 3335 16 1. 3336 * ename:VK_COMPONENT_TYPE_SINT32_KHR corresponds to SPIR-V code:OpTypeInt 3337 32 1. 3338 * ename:VK_COMPONENT_TYPE_SINT64_KHR corresponds to SPIR-V code:OpTypeInt 3339 64 1. 3340 * ename:VK_COMPONENT_TYPE_UINT8_KHR corresponds to SPIR-V code:OpTypeInt 8 0. 3341 * ename:VK_COMPONENT_TYPE_UINT16_KHR corresponds to SPIR-V code:OpTypeInt 3342 16 0. 3343 * ename:VK_COMPONENT_TYPE_UINT32_KHR corresponds to SPIR-V code:OpTypeInt 3344 32 0. 3345 * ename:VK_COMPONENT_TYPE_UINT64_KHR corresponds to SPIR-V code:OpTypeInt 3346 64 0. 3347-- 3348endif::VK_NV_cooperative_matrix,VK_KHR_cooperative_matrix[] 3349 3350ifdef::VK_EXT_validation_cache[] 3351[[shaders-validation-cache]] 3352== Validation Cache 3353 3354[open,refpage='VkValidationCacheEXT',desc='Opaque handle to a validation cache object',type='handles'] 3355-- 3356Validation cache objects allow the result of internal validation to be 3357reused, both within a single application run and between multiple runs. 3358Reuse within a single run is achieved by passing the same validation cache 3359object when creating supported Vulkan objects. 3360Reuse across runs of an application is achieved by retrieving validation 3361cache contents in one run of an application, saving the contents, and using 3362them to preinitialize a validation cache on a subsequent run. 3363The contents of the validation cache objects are managed by the validation 3364layers. 3365Applications can: manage the host memory consumed by a validation cache 3366object and control the amount of data retrieved from a validation cache 3367object. 3368 3369Validation cache objects are represented by sname:VkValidationCacheEXT 3370handles: 3371 3372include::{generated}/api/handles/VkValidationCacheEXT.adoc[] 3373-- 3374 3375[open,refpage='vkCreateValidationCacheEXT',desc='Creates a new validation cache',type='protos'] 3376-- 3377To create validation cache objects, call: 3378 3379include::{generated}/api/protos/vkCreateValidationCacheEXT.adoc[] 3380 3381 * pname:device is the logical device that creates the validation cache 3382 object. 3383 * pname:pCreateInfo is a pointer to a slink:VkValidationCacheCreateInfoEXT 3384 structure containing the initial parameters for the validation cache 3385 object. 3386 * pname:pAllocator controls host memory allocation as described in the 3387 <<memory-allocation, Memory Allocation>> chapter. 3388 * pname:pValidationCache is a pointer to a slink:VkValidationCacheEXT 3389 handle in which the resulting validation cache object is returned. 3390 3391[NOTE] 3392.Note 3393==== 3394Applications can: track and manage the total host memory size of a 3395validation cache object using the pname:pAllocator. 3396Applications can: limit the amount of data retrieved from a validation cache 3397object in fname:vkGetValidationCacheDataEXT. 3398Implementations should: not internally limit the total number of entries 3399added to a validation cache object or the total host memory consumed. 3400==== 3401 3402Once created, a validation cache can: be passed to the 3403fname:vkCreateShaderModule command by adding this object to the 3404slink:VkShaderModuleCreateInfo structure's pname:pNext chain. 3405If a slink:VkShaderModuleValidationCacheCreateInfoEXT object is included in 3406the slink:VkShaderModuleCreateInfo::pname:pNext chain, and its 3407pname:validationCache field is not dlink:VK_NULL_HANDLE, the implementation 3408will query it for possible reuse opportunities and update it with new 3409content. 3410The use of the validation cache object in these commands is internally 3411synchronized, and the same validation cache object can: be used in multiple 3412threads simultaneously. 3413 3414[NOTE] 3415.Note 3416==== 3417Implementations should: make every effort to limit any critical sections to 3418the actual accesses to the cache, which is expected to be significantly 3419shorter than the duration of the fname:vkCreateShaderModule command. 3420==== 3421 3422include::{generated}/validity/protos/vkCreateValidationCacheEXT.adoc[] 3423-- 3424 3425[open,refpage='VkValidationCacheCreateInfoEXT',desc='Structure specifying parameters of a newly created validation cache',type='structs'] 3426-- 3427The sname:VkValidationCacheCreateInfoEXT structure is defined as: 3428 3429include::{generated}/api/structs/VkValidationCacheCreateInfoEXT.adoc[] 3430 3431 * pname:sType is a elink:VkStructureType value identifying this structure. 3432 * pname:pNext is `NULL` or a pointer to a structure extending this 3433 structure. 3434 * pname:flags is reserved for future use. 3435 * pname:initialDataSize is the number of bytes in pname:pInitialData. 3436 If pname:initialDataSize is zero, the validation cache will initially be 3437 empty. 3438 * pname:pInitialData is a pointer to previously retrieved validation cache 3439 data. 3440 If the validation cache data is incompatible (as defined below) with the 3441 device, the validation cache will be initially empty. 3442 If pname:initialDataSize is zero, pname:pInitialData is ignored. 3443 3444.Valid Usage 3445**** 3446 * [[VUID-VkValidationCacheCreateInfoEXT-initialDataSize-01534]] 3447 If pname:initialDataSize is not `0`, it must: be equal to the size of 3448 pname:pInitialData, as returned by fname:vkGetValidationCacheDataEXT 3449 when pname:pInitialData was originally retrieved 3450 * [[VUID-VkValidationCacheCreateInfoEXT-initialDataSize-01535]] 3451 If pname:initialDataSize is not `0`, pname:pInitialData must: have been 3452 retrieved from a previous call to fname:vkGetValidationCacheDataEXT 3453**** 3454 3455include::{generated}/validity/structs/VkValidationCacheCreateInfoEXT.adoc[] 3456-- 3457 3458[open,refpage='VkValidationCacheCreateFlagsEXT',desc='Reserved for future use',type='flags'] 3459-- 3460include::{generated}/api/flags/VkValidationCacheCreateFlagsEXT.adoc[] 3461 3462tname:VkValidationCacheCreateFlagsEXT is a bitmask type for setting a mask, 3463but is currently reserved for future use. 3464-- 3465 3466[open,refpage='vkMergeValidationCachesEXT',desc='Combine the data stores of validation caches',type='protos'] 3467-- 3468Validation cache objects can: be merged using the command: 3469 3470include::{generated}/api/protos/vkMergeValidationCachesEXT.adoc[] 3471 3472 * pname:device is the logical device that owns the validation cache 3473 objects. 3474 * pname:dstCache is the handle of the validation cache to merge results 3475 into. 3476 * pname:srcCacheCount is the length of the pname:pSrcCaches array. 3477 * pname:pSrcCaches is a pointer to an array of validation cache handles, 3478 which will be merged into pname:dstCache. 3479 The previous contents of pname:dstCache are included after the merge. 3480 3481[NOTE] 3482.Note 3483==== 3484The details of the merge operation are implementation-dependent, but 3485implementations should: merge the contents of the specified validation 3486caches and prune duplicate entries. 3487==== 3488 3489.Valid Usage 3490**** 3491 * [[VUID-vkMergeValidationCachesEXT-dstCache-01536]] 3492 pname:dstCache must: not appear in the list of source caches 3493**** 3494 3495include::{generated}/validity/protos/vkMergeValidationCachesEXT.adoc[] 3496-- 3497 3498[open,refpage='vkGetValidationCacheDataEXT',desc='Get the data store from a validation cache',type='protos'] 3499-- 3500Data can: be retrieved from a validation cache object using the command: 3501 3502include::{generated}/api/protos/vkGetValidationCacheDataEXT.adoc[] 3503 3504 * pname:device is the logical device that owns the validation cache. 3505 * pname:validationCache is the validation cache to retrieve data from. 3506 * pname:pDataSize is a pointer to a value related to the amount of data in 3507 the validation cache, as described below. 3508 * pname:pData is either `NULL` or a pointer to a buffer. 3509 3510If pname:pData is `NULL`, then the maximum size of the data that can: be 3511retrieved from the validation cache, in bytes, is returned in 3512pname:pDataSize. 3513Otherwise, pname:pDataSize must: point to a variable set by the user to the 3514size of the buffer, in bytes, pointed to by pname:pData, and on return the 3515variable is overwritten with the amount of data actually written to 3516pname:pData. 3517If pname:pDataSize is less than the maximum size that can: be retrieved by 3518the validation cache, at most pname:pDataSize bytes will be written to 3519pname:pData, and fname:vkGetValidationCacheDataEXT will return 3520ename:VK_INCOMPLETE instead of ename:VK_SUCCESS, to indicate that not all of 3521the validation cache was returned. 3522 3523Any data written to pname:pData is valid and can: be provided as the 3524pname:pInitialData member of the slink:VkValidationCacheCreateInfoEXT 3525structure passed to fname:vkCreateValidationCacheEXT. 3526 3527Two calls to fname:vkGetValidationCacheDataEXT with the same parameters 3528must: retrieve the same data unless a command that modifies the contents of 3529the cache is called between them. 3530 3531[[validation-cache-header]] 3532Applications can: store the data retrieved from the validation cache, and 3533use these data, possibly in a future run of the application, to populate new 3534validation cache objects. 3535The results of validation, however, may: depend on the vendor ID, device ID, 3536driver version, and other details of the device. 3537To enable applications to detect when previously retrieved data is 3538incompatible with the device, the initial bytes written to pname:pData must: 3539be a header consisting of the following members: 3540 3541.Layout for validation cache header version ename:VK_VALIDATION_CACHE_HEADER_VERSION_ONE_EXT 3542[width="85%",cols="8%,21%,71%",options="header"] 3543|==== 3544| Offset | Size | Meaning 3545| 0 | 4 | length in bytes of the entire validation cache header 3546 written as a stream of bytes, with the least 3547 significant byte first 3548| 4 | 4 | a elink:VkValidationCacheHeaderVersionEXT value 3549 written as a stream of bytes, with the least 3550 significant byte first 3551| 8 | ename:VK_UUID_SIZE | a layer commit ID expressed as a UUID, which uniquely 3552 identifies the version of the validation layers used 3553 to generate these validation results 3554|==== 3555 3556The first four bytes encode the length of the entire validation cache 3557header, in bytes. 3558This value includes all fields in the header including the validation cache 3559version field and the size of the length field. 3560 3561The next four bytes encode the validation cache version, as described for 3562elink:VkValidationCacheHeaderVersionEXT. 3563A consumer of the validation cache should: use the cache version to 3564interpret the remainder of the cache header. 3565 3566If pname:pDataSize is less than what is necessary to store this header, 3567nothing will be written to pname:pData and zero will be written to 3568pname:pDataSize. 3569 3570include::{generated}/validity/protos/vkGetValidationCacheDataEXT.adoc[] 3571-- 3572 3573[open,refpage='VkValidationCacheHeaderVersionEXT',desc='Encode validation cache version',type='enums',xrefs='vkCreateValidationCacheEXT vkGetValidationCacheDataEXT'] 3574-- 3575Possible values of the second group of four bytes in the header returned by 3576flink:vkGetValidationCacheDataEXT, encoding the validation cache version, 3577are: 3578 3579include::{generated}/api/enums/VkValidationCacheHeaderVersionEXT.adoc[] 3580 3581 * ename:VK_VALIDATION_CACHE_HEADER_VERSION_ONE_EXT specifies version one 3582 of the validation cache. 3583-- 3584 3585[open,refpage='vkDestroyValidationCacheEXT',desc='Destroy a validation cache object',type='protos'] 3586-- 3587To destroy a validation cache, call: 3588 3589include::{generated}/api/protos/vkDestroyValidationCacheEXT.adoc[] 3590 3591 * pname:device is the logical device that destroys the validation cache 3592 object. 3593 * pname:validationCache is the handle of the validation cache to destroy. 3594 * pname:pAllocator controls host memory allocation as described in the 3595 <<memory-allocation, Memory Allocation>> chapter. 3596 3597.Valid Usage 3598**** 3599 * [[VUID-vkDestroyValidationCacheEXT-validationCache-01537]] 3600 If sname:VkAllocationCallbacks were provided when pname:validationCache 3601 was created, a compatible set of callbacks must: be provided here 3602 * [[VUID-vkDestroyValidationCacheEXT-validationCache-01538]] 3603 If no sname:VkAllocationCallbacks were provided when 3604 pname:validationCache was created, pname:pAllocator must: be `NULL` 3605**** 3606 3607include::{generated}/validity/protos/vkDestroyValidationCacheEXT.adoc[] 3608-- 3609endif::VK_EXT_validation_cache[] 3610 3611ifdef::VK_NV_cuda_kernel_launch[] 3612include::{chapters}/VK_NV_cuda_kernel_launch/module.adoc[] 3613endif::VK_NV_cuda_kernel_launch[] 3614