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