1// Copyright (c) 2015-2018 Khronos Group. This work is licensed under a 2// Creative Commons Attribution 4.0 International License; see 3// http://creativecommons.org/licenses/by/4.0/ 4 5[[dispatch]] 6= Dispatching Commands 7 8_Dispatching commands_ (commands with ftext:Dispatch in the name) provoke 9work in a compute pipeline. 10Dispatching commands are recorded into a command buffer and when executed by 11a queue, will produce work which executes according to the bound compute 12pipeline. 13A compute pipeline must: be bound to a command buffer before any dispatch 14commands are recorded in that command buffer. 15 16[open,refpage='vkCmdDispatch',desc='Dispatch compute work items',type='protos'] 17-- 18 19To record a dispatch, call: 20 21include::../api/protos/vkCmdDispatch.txt[] 22 23 * pname:commandBuffer is the command buffer into which the command will be 24 recorded. 25 * pname:groupCountX is the number of local workgroups to dispatch in the X 26 dimension. 27 * pname:groupCountY is the number of local workgroups to dispatch in the Y 28 dimension. 29 * pname:groupCountZ is the number of local workgroups to dispatch in the Z 30 dimension. 31 32When the command is executed, a global workgroup consisting of 33[eq]#groupCountX {times} groupCountY {times} groupCountZ# local workgroups 34is assembled. 35 36.Valid Usage 37**** 38 * [[VUID-vkCmdDispatch-groupCountX-00386]] 39 pname:groupCountX must: be less than or equal to 40 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0] 41 * [[VUID-vkCmdDispatch-groupCountY-00387]] 42 pname:groupCountY must: be less than or equal to 43 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[1] 44 * [[VUID-vkCmdDispatch-groupCountZ-00388]] 45 pname:groupCountZ must: be less than or equal to 46 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2] 47 * [[VUID-vkCmdDispatch-None-00389]] 48 For each set _n_ that is statically used by the sname:VkPipeline bound 49 to ename:VK_PIPELINE_BIND_POINT_COMPUTE, a descriptor set must: have 50 been bound to _n_ at ename:VK_PIPELINE_BIND_POINT_COMPUTE, with a 51 sname:VkPipelineLayout that is compatible for set _n_, with the 52 sname:VkPipelineLayout used to create the current sname:VkPipeline, as 53 described in <<descriptorsets-compatibility>> 54 * [[VUID-vkCmdDispatch-None-00390]] 55 Descriptors in each bound descriptor set, specified via 56 fname:vkCmdBindDescriptorSets, must: be valid if they are statically 57 used by the bound sname:VkPipeline object, specified via 58 fname:vkCmdBindPipeline 59 * [[VUID-vkCmdDispatch-None-00391]] 60 A valid compute pipeline must: be bound to the current command buffer 61 with ename:VK_PIPELINE_BIND_POINT_COMPUTE 62 * [[VUID-vkCmdDispatch-None-00392]] 63 For each push constant that is statically used by the sname:VkPipeline 64 bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE, a push constant value 65 must: have been set for ename:VK_PIPELINE_BIND_POINT_COMPUTE, with a 66 sname:VkPipelineLayout that is compatible for push constants with the 67 one used to create the current sname:VkPipeline, as described in 68 <<descriptorsets-compatibility>> 69 * [[VUID-vkCmdDispatch-None-00393]] 70 If any sname:VkSampler object that is accessed from a shader by the 71 sname:VkPipeline bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE uses 72 unnormalized coordinates, it must: not be used to sample from any 73 sname:VkImage with a sname:VkImageView of the type 74 ename:VK_IMAGE_VIEW_TYPE_3D, ename:VK_IMAGE_VIEW_TYPE_CUBE, 75 ename:VK_IMAGE_VIEW_TYPE_1D_ARRAY, ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY or 76 ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY, in any shader stage 77 * [[VUID-vkCmdDispatch-None-00394]] 78 If any sname:VkSampler object that is accessed from a shader by the 79 sname:VkPipeline bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE uses 80 unnormalized coordinates, it must: not be used with any of the SPIR-V 81 `OpImageSample*` or `OpImageSparseSample*` instructions with 82 code:ImplicitLod, code:Dref or code:Proj in their name, in any shader 83 stage 84 * [[VUID-vkCmdDispatch-None-00395]] 85 If any sname:VkSampler object that is accessed from a shader by the 86 sname:VkPipeline bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE uses 87 unnormalized coordinates, it must: not be used with any of the SPIR-V 88 `OpImageSample*` or `OpImageSparseSample*` instructions that includes a 89 LOD bias or any offset values, in any shader stage 90 * [[VUID-vkCmdDispatch-None-00396]] 91 If the <<features-features-robustBufferAccess,robust buffer access>> 92 feature is not enabled, and any shader stage in the sname:VkPipeline 93 object bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE accesses a uniform 94 buffer, it must: not access values outside of the range of that buffer 95 specified in the bound descriptor set 96 * [[VUID-vkCmdDispatch-None-00397]] 97 If the <<features-features-robustBufferAccess,robust buffer access>> 98 feature is not enabled, and any shader stage in the sname:VkPipeline 99 object bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE accesses a storage 100 buffer, it must: not access values outside of the range of that buffer 101 specified in the bound descriptor set 102 * [[VUID-vkCmdDispatch-None-02005]] 103 If a sname:VkImageView is sampled with with ename:VK_FILTER_LINEAR as a 104 result of this command, then the image view's 105 <<resources-image-view-format-features,format features>> must: contain 106 ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT. 107ifdef::VK_IMG_filter_cubic[] 108 * [[VUID-vkCmdDispatch-None-02006]] 109 If a sname:VkImageView is sampled with with ename:VK_FILTER_CUBIC_IMG as 110 a result of this command, then the image view's 111 <<resources-image-view-format-features,format features>> must: contain 112 ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG. 113 * [[VUID-vkCmdDispatch-None-00400]] 114 Any slink:VkImageView being sampled with ename:VK_FILTER_CUBIC_IMG as a 115 result of this command must: not have a elink:VkImageViewType of 116 ename:VK_IMAGE_VIEW_TYPE_3D, ename:VK_IMAGE_VIEW_TYPE_CUBE, or 117 ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY 118endif::VK_IMG_filter_cubic[] 119ifdef::VK_VERSION_1_1[] 120 * [[VUID-vkCmdDispatch-commandBuffer-01844]] 121 If pname:commandBuffer is an unprotected command buffer, and any 122 pipeline stage in the sname:VkPipeline object bound to 123 ename:VK_PIPELINE_BIND_POINT_COMPUTE reads from or writes to any image 124 or buffer, that image or buffer must: not be a protected image or 125 protected buffer. 126 * [[VUID-vkCmdDispatch-commandBuffer-01845]] 127 If pname:commandBuffer is a protected command buffer, and any pipeline 128 stage in the sname:VkPipeline object bound to 129 ename:VK_PIPELINE_POINT_COMPUTE writes to any image or buffer, that 130 image or buffer must: not be an unprotected image or unprotected buffer. 131 * [[VUID-vkCmdDispatch-commandBuffer-01846]] 132 If pname:commandBuffer is a protected command buffer, and any pipeline 133 stage other than the compute pipeline stage in the sname:VkPipeline 134 object bound to ename:VK_PIPELINE_POINT_COMPUTE reads from any image or 135 buffer, the image or buffer must: not be a protected image or protected 136 buffer. 137endif::VK_VERSION_1_1[] 138**** 139 140include::../validity/protos/vkCmdDispatch.txt[] 141-- 142 143[open,refpage='vkCmdDispatchIndirect',desc='Dispatch compute work items using indirect parameters',type='protos'] 144-- 145 146To record an indirect command dispatch, call: 147 148include::../api/protos/vkCmdDispatchIndirect.txt[] 149 150 * pname:commandBuffer is the command buffer into which the command will be 151 recorded. 152 * pname:buffer is the buffer containing dispatch parameters. 153 * pname:offset is the byte offset into pname:buffer where parameters 154 begin. 155 156fname:vkCmdDispatchIndirect behaves similarly to flink:vkCmdDispatch except 157that the parameters are read by the device from a buffer during execution. 158The parameters of the dispatch are encoded in a 159slink:VkDispatchIndirectCommand structure taken from pname:buffer starting 160at pname:offset. 161 162.Valid Usage 163**** 164 * [[VUID-vkCmdDispatchIndirect-buffer-00401]] 165 If pname:buffer is non-sparse then it must: be bound completely and 166 contiguously to a single sname:VkDeviceMemory object 167 * [[VUID-vkCmdDispatchIndirect-None-00402]] 168 For each set _n_ that is statically used by the sname:VkPipeline bound 169 to ename:VK_PIPELINE_BIND_POINT_COMPUTE, a descriptor set must: have 170 been bound to _n_ at ename:VK_PIPELINE_BIND_POINT_COMPUTE, with a 171 sname:VkPipelineLayout that is compatible for set _n_, with the 172 sname:VkPipelineLayout used to create the current sname:VkPipeline, as 173 described in <<descriptorsets-compatibility>> 174 * [[VUID-vkCmdDispatchIndirect-None-00403]] 175 Descriptors in each bound descriptor set, specified via 176 fname:vkCmdBindDescriptorSets, must: be valid if they are statically 177 used by the bound sname:VkPipeline object, specified via 178 fname:vkCmdBindPipeline 179 * [[VUID-vkCmdDispatchIndirect-None-00404]] 180 A valid compute pipeline must: be bound to the current command buffer 181 with ename:VK_PIPELINE_BIND_POINT_COMPUTE 182 * [[VUID-vkCmdDispatchIndirect-buffer-00405]] 183 pname:buffer must: have been created with the 184 ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set 185 * [[VUID-vkCmdDispatchIndirect-offset-00406]] 186 pname:offset must: be a multiple of `4` 187 * [[VUID-vkCmdDispatchIndirect-offset-00407]] 188 The sum of pname:offset and the size of sname:VkDispatchIndirectCommand 189 must: be less than or equal to the size of pname:buffer 190 * [[VUID-vkCmdDispatchIndirect-None-00408]] 191 For each push constant that is statically used by the sname:VkPipeline 192 bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE, a push constant value 193 must: have been set for ename:VK_PIPELINE_BIND_POINT_COMPUTE, with a 194 sname:VkPipelineLayout that is compatible for push constants with the 195 one used to create the current sname:VkPipeline, as described in 196 <<descriptorsets-compatibility>> 197 * [[VUID-vkCmdDispatchIndirect-None-00409]] 198 If any sname:VkSampler object that is accessed from a shader by the 199 sname:VkPipeline bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE uses 200 unnormalized coordinates, it must: not be used to sample from any 201 sname:VkImage with a sname:VkImageView of the type 202 ename:VK_IMAGE_VIEW_TYPE_3D, ename:VK_IMAGE_VIEW_TYPE_CUBE, 203 ename:VK_IMAGE_VIEW_TYPE_1D_ARRAY, ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY or 204 ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY, in any shader stage 205 * [[VUID-vkCmdDispatchIndirect-None-00410]] 206 If any sname:VkSampler object that is accessed from a shader by the 207 sname:VkPipeline bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE uses 208 unnormalized coordinates, it must: not be used with any of the SPIR-V 209 `OpImageSample*` or `OpImageSparseSample*` instructions with 210 code:ImplicitLod, code:Dref or code:Proj in their name, in any shader 211 stage 212 * [[VUID-vkCmdDispatchIndirect-None-00411]] 213 If any sname:VkSampler object that is accessed from a shader by the 214 sname:VkPipeline bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE uses 215 unnormalized coordinates, it must: not be used with any of the SPIR-V 216 `OpImageSample*` or `OpImageSparseSample*` instructions that includes a 217 LOD bias or any offset values, in any shader stage 218 * [[VUID-vkCmdDispatchIndirect-None-00412]] 219 If the <<features-features-robustBufferAccess,robust buffer access>> 220 feature is not enabled, and any shader stage in the sname:VkPipeline 221 object bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE accesses a uniform 222 buffer, it must: not access values outside of the range of that buffer 223 specified in the bound descriptor set 224 * [[VUID-vkCmdDispatchIndirect-None-00413]] 225 If the <<features-features-robustBufferAccess,robust buffer access>> 226 feature is not enabled, and any shader stage in the sname:VkPipeline 227 object bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE accesses a storage 228 buffer, it must: not access values outside of the range of that buffer 229 specified in the bound descriptor set 230 * [[VUID-vkCmdDispatchIndirect-None-02007]] 231 If a sname:VkImageView is sampled with with ename:VK_FILTER_LINEAR as a 232 result of this command, then the image view's 233 <<resources-image-view-format-features,format features>> must: contain 234 ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT. 235ifdef::VK_IMG_filter_cubic[] 236 * [[VUID-vkCmdDispatchIndirect-None-02008]] 237 If a sname:VkImageView is sampled with with ename:VK_FILTER_CUBIC_IMG as 238 a result of this command, then the image view's 239 <<resources-image-view-format-features,format features>> must: contain 240 ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG. 241 * [[VUID-vkCmdDispatchIndirect-None-00416]] 242 Any slink:VkImageView being sampled with ename:VK_FILTER_CUBIC_IMG as a 243 result of this command must: not have a elink:VkImageViewType of 244 ename:VK_IMAGE_VIEW_TYPE_3D, ename:VK_IMAGE_VIEW_TYPE_CUBE, or 245 ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY 246endif::VK_IMG_filter_cubic[] 247ifdef::VK_VERSION_1_1[] 248 * [[VUID-vkCmdDispatchIndirect-commandBuffer-01847]] 249 If pname:commandBuffer is an unprotected command buffer, and any 250 pipeline stage in the sname:VkPipeline object bound to 251 ename:VK_PIPELINE_BIND_POINT_COMPUTE reads from or writes to any image 252 or buffer, that image or buffer must: not be a protected image or 253 protected buffer. 254 * [[VUID-vkCmdDispatchIndirect-commandBuffer-01848]] 255 If pname:commandBuffer is a protected command buffer, and any pipeline 256 stage in the sname:VkPipeline object bound to 257 ename:VK_PIPELINE_POINT_COMPUTE writes to any image or buffer, that 258 image or buffer must: not be an unprotected image or unprotected buffer. 259 * [[VUID-vkCmdDispatchIndirect-commandBuffer-01849]] 260 If pname:commandBuffer is a protected command buffer, and any pipeline 261 stage other than the compute pipeline stage in the sname:VkPipeline 262 object bound to ename:VK_PIPELINE_POINT_COMPUTE reads from any image or 263 buffer, the image or buffer must: not be a protected image or protected 264 buffer. 265endif::VK_VERSION_1_1[] 266**** 267 268include::../validity/protos/vkCmdDispatchIndirect.txt[] 269-- 270 271[open,refpage='VkDispatchIndirectCommand',desc='Structure specifying a dispatch indirect command',type='structs',xrefs='vkCmdDispatchIndirect'] 272-- 273 274The sname:VkDispatchIndirectCommand structure is defined as: 275 276include::../api/structs/VkDispatchIndirectCommand.txt[] 277 278 * pname:x is the number of local workgroups to dispatch in the X 279 dimension. 280 * pname:y is the number of local workgroups to dispatch in the Y 281 dimension. 282 * pname:z is the number of local workgroups to dispatch in the Z 283 dimension. 284 285The members of sname:VkDispatchIndirectCommand have the same meaning as the 286corresponding parameters of flink:vkCmdDispatch. 287 288.Valid Usage 289**** 290 * [[VUID-VkDispatchIndirectCommand-x-00417]] 291 pname:x must: be less than or equal to 292 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0] 293 * [[VUID-VkDispatchIndirectCommand-y-00418]] 294 pname:y must: be less than or equal to 295 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[1] 296 * [[VUID-VkDispatchIndirectCommand-z-00419]] 297 pname:z must: be less than or equal to 298 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2] 299**** 300 301include::../validity/structs/VkDispatchIndirectCommand.txt[] 302 303-- 304 305ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 306 307[open,refpage='vkCmdDispatchBase',desc='Dispatch compute work items',type='protos'] 308-- 309 310To record a dispatch using non-zero base values for the components of 311code:WorkgroupId, call: 312 313ifdef::VK_VERSION_1_1[] 314include::../api/protos/vkCmdDispatchBase.txt[] 315endif::VK_VERSION_1_1[] 316 317ifdef::VK_VERSION_1_1+VK_KHR_device_group[or the equivalent command] 318 319ifdef::VK_KHR_device_group[] 320include::../api/protos/vkCmdDispatchBaseKHR.txt[] 321endif::VK_KHR_device_group[] 322 323 * pname:commandBuffer is the command buffer into which the command will be 324 recorded. 325 * pname:baseGroupX is the start value for the X component of 326 code:WorkgroupId. 327 * pname:baseGroupY is the start value for the Y component of 328 code:WorkgroupId. 329 * pname:baseGroupZ is the start value for the Z component of 330 code:WorkgroupId. 331 * pname:groupCountX is the number of local workgroups to dispatch in the X 332 dimension. 333 * pname:groupCountY is the number of local workgroups to dispatch in the Y 334 dimension. 335 * pname:groupCountZ is the number of local workgroups to dispatch in the Z 336 dimension. 337 338When the command is executed, a global workgroup consisting of 339[eq]#groupCountX {times} groupCountY {times} groupCountZ# local workgroups 340is assembled, with code:WorkgroupId values ranging from [eq]#[baseGroup, 341baseGroup {plus} groupCount)# in each component. 342flink:vkCmdDispatch is equivalent to 343`vkCmdDispatchBase(0,0,0,groupCountX,groupCountY,groupCountZ)`. 344 345.Valid Usage 346**** 347 * [[VUID-vkCmdDispatchBase-None-00420]] 348 All valid usage rules from flink:vkCmdDispatch apply 349 * [[VUID-vkCmdDispatchBase-baseGroupX-00421]] 350 pname:baseGroupX must: be less than 351 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0] 352 * [[VUID-vkCmdDispatchBase-baseGroupX-00422]] 353 pname:baseGroupX must: be less than 354 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[1] 355 * [[VUID-vkCmdDispatchBase-baseGroupZ-00423]] 356 pname:baseGroupZ must: be less than 357 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2] 358 * [[VUID-vkCmdDispatchBase-groupCountX-00424]] 359 pname:groupCountX must: be less than or equal to 360 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0] minus 361 pname:baseGroupX 362 * [[VUID-vkCmdDispatchBase-groupCountY-00425]] 363 pname:groupCountY must: be less than or equal to 364 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[1] minus 365 pname:baseGroupY 366 * [[VUID-vkCmdDispatchBase-groupCountZ-00426]] 367 pname:groupCountZ must: be less than or equal to 368 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2] minus 369 pname:baseGroupZ 370 * [[VUID-vkCmdDispatchBase-baseGroupX-00427]] 371 If any of pname:baseGroupX, pname:baseGroupY, or pname:baseGroupZ are 372 not zero, then the bound compute pipeline must: have been created with 373 the ename:VK_PIPELINE_CREATE_DISPATCH_BASE flag. 374**** 375 376include::../validity/protos/vkCmdDispatchBase.txt[] 377-- 378 379endif::VK_VERSION_1_1,VK_KHR_device_group[] 380