1// Copyright 2015-2024 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-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 dispatching 14commands are recorded in that command buffer. 15 16[open,refpage='vkCmdDispatch',desc='Dispatch compute work items',type='protos'] 17-- 18:refpage: vkCmdDispatch 19 20To record a dispatch, call: 21 22include::{generated}/api/protos/vkCmdDispatch.adoc[] 23 24 * pname:commandBuffer is the command buffer into which the command will be 25 recorded. 26 * pname:groupCountX is the number of local workgroups to dispatch in the X 27 dimension. 28 * pname:groupCountY is the number of local workgroups to dispatch in the Y 29 dimension. 30 * pname:groupCountZ is the number of local workgroups to dispatch in the Z 31 dimension. 32 33When the command is executed, a global workgroup consisting of 34[eq]#pname:groupCountX {times} pname:groupCountY {times} pname:groupCountZ# 35local workgroups is assembled. 36 37.Valid Usage 38**** 39include::{chapters}/commonvalidity/draw_dispatch_common.adoc[] 40include::{chapters}/commonvalidity/draw_dispatch_nonindirect_common.adoc[] 41 * [[VUID-vkCmdDispatch-groupCountX-00386]] 42 pname:groupCountX must: be less than or equal to 43 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0] 44 * [[VUID-vkCmdDispatch-groupCountY-00387]] 45 pname:groupCountY must: be less than or equal to 46 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[1] 47 * [[VUID-vkCmdDispatch-groupCountZ-00388]] 48 pname:groupCountZ must: be less than or equal to 49 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2] 50**** 51 52include::{generated}/validity/protos/vkCmdDispatch.adoc[] 53-- 54 55[open,refpage='vkCmdDispatchIndirect',desc='Dispatch compute work items with indirect parameters',type='protos'] 56-- 57:refpage: vkCmdDispatchIndirect 58 59To record an indirect dispatching command, call: 60 61include::{generated}/api/protos/vkCmdDispatchIndirect.adoc[] 62 63 * pname:commandBuffer is the command buffer into which the command will be 64 recorded. 65 * pname:buffer is the buffer containing dispatch parameters. 66 * pname:offset is the byte offset into pname:buffer where parameters 67 begin. 68 69fname:vkCmdDispatchIndirect behaves similarly to flink:vkCmdDispatch except 70that the parameters are read by the device from a buffer during execution. 71The parameters of the dispatch are encoded in a 72slink:VkDispatchIndirectCommand structure taken from pname:buffer starting 73at pname:offset. 74 75.Valid Usage 76**** 77include::{chapters}/commonvalidity/draw_dispatch_common.adoc[] 78include::{chapters}/commonvalidity/draw_dispatch_indirect_common.adoc[] 79 * [[VUID-vkCmdDispatchIndirect-offset-00407]] 80 The sum of pname:offset and the size of sname:VkDispatchIndirectCommand 81 must: be less than or equal to the size of pname:buffer 82**** 83 84include::{generated}/validity/protos/vkCmdDispatchIndirect.adoc[] 85-- 86 87[open,refpage='VkDispatchIndirectCommand',desc='Structure specifying a indirect dispatching command',type='structs',xrefs='vkCmdDispatchIndirect'] 88-- 89The sname:VkDispatchIndirectCommand structure is defined as: 90 91include::{generated}/api/structs/VkDispatchIndirectCommand.adoc[] 92 93 * pname:x is the number of local workgroups to dispatch in the X 94 dimension. 95 * pname:y is the number of local workgroups to dispatch in the Y 96 dimension. 97 * pname:z is the number of local workgroups to dispatch in the Z 98 dimension. 99 100The members of sname:VkDispatchIndirectCommand have the same meaning as the 101corresponding parameters of flink:vkCmdDispatch. 102 103.Valid Usage 104**** 105 * [[VUID-VkDispatchIndirectCommand-x-00417]] 106 pname:x must: be less than or equal to 107 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0] 108 * [[VUID-VkDispatchIndirectCommand-y-00418]] 109 pname:y must: be less than or equal to 110 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[1] 111 * [[VUID-VkDispatchIndirectCommand-z-00419]] 112 pname:z must: be less than or equal to 113 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2] 114**** 115 116include::{generated}/validity/structs/VkDispatchIndirectCommand.adoc[] 117-- 118 119ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 120[open,refpage='vkCmdDispatchBase',desc='Dispatch compute work items with non-zero base values for the workgroup IDs',type='protos'] 121-- 122:refpage: vkCmdDispatchBase 123 124To record a dispatch using non-zero base values for the components of 125code:WorkgroupId, call: 126 127ifdef::VK_VERSION_1_1[] 128include::{generated}/api/protos/vkCmdDispatchBase.adoc[] 129endif::VK_VERSION_1_1[] 130 131ifdef::VK_VERSION_1_1+VK_KHR_device_group[or the equivalent command] 132 133ifdef::VK_KHR_device_group[] 134include::{generated}/api/protos/vkCmdDispatchBaseKHR.adoc[] 135endif::VK_KHR_device_group[] 136 137 * pname:commandBuffer is the command buffer into which the command will be 138 recorded. 139 * pname:baseGroupX is the start value for the X component of 140 code:WorkgroupId. 141 * pname:baseGroupY is the start value for the Y component of 142 code:WorkgroupId. 143 * pname:baseGroupZ is the start value for the Z component of 144 code:WorkgroupId. 145 * pname:groupCountX is the number of local workgroups to dispatch in the X 146 dimension. 147 * pname:groupCountY is the number of local workgroups to dispatch in the Y 148 dimension. 149 * pname:groupCountZ is the number of local workgroups to dispatch in the Z 150 dimension. 151 152When the command is executed, a global workgroup consisting of 153[eq]#pname:groupCountX {times} pname:groupCountY {times} pname:groupCountZ# 154local workgroups is assembled, with code:WorkgroupId values ranging from 155[eq]#[ptext:baseGroup*, ptext:baseGroup* {plus} ptext:groupCount*)# in each 156component. 157flink:vkCmdDispatch is equivalent to 158`vkCmdDispatchBase(0,0,0,groupCountX,groupCountY,groupCountZ)`. 159 160.Valid Usage 161**** 162include::{chapters}/commonvalidity/draw_dispatch_common.adoc[] 163include::{chapters}/commonvalidity/draw_dispatch_nonindirect_common.adoc[] 164 * [[VUID-vkCmdDispatchBase-baseGroupX-00421]] 165 pname:baseGroupX must: be less than 166 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0] 167 * [[VUID-vkCmdDispatchBase-baseGroupX-00422]] 168 pname:baseGroupY must: be less than 169 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[1] 170 * [[VUID-vkCmdDispatchBase-baseGroupZ-00423]] 171 pname:baseGroupZ must: be less than 172 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2] 173 * [[VUID-vkCmdDispatchBase-groupCountX-00424]] 174 pname:groupCountX must: be less than or equal to 175 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0] minus 176 pname:baseGroupX 177 * [[VUID-vkCmdDispatchBase-groupCountY-00425]] 178 pname:groupCountY must: be less than or equal to 179 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[1] minus 180 pname:baseGroupY 181 * [[VUID-vkCmdDispatchBase-groupCountZ-00426]] 182 pname:groupCountZ must: be less than or equal to 183 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2] minus 184 pname:baseGroupZ 185 * [[VUID-vkCmdDispatchBase-baseGroupX-00427]] 186 If any of pname:baseGroupX, pname:baseGroupY, or pname:baseGroupZ are 187 not zero, then the bound compute pipeline must: have been created with 188 the ename:VK_PIPELINE_CREATE_DISPATCH_BASE flag 189**** 190 191include::{generated}/validity/protos/vkCmdDispatchBase.adoc[] 192-- 193endif::VK_VERSION_1_1,VK_KHR_device_group[] 194 195ifdef::VK_HUAWEI_subpass_shading[] 196[open,refpage='vkCmdSubpassShadingHUAWEI',desc='Dispatch compute work items',type='protos'] 197-- 198:refpage: vkCmdSubpassShadingHUAWEI 199 200A subpass shading dispatches a compute pipeline work with the work dimension 201of render area of the calling subpass and work groups are partitioned by 202specified work group size. 203Subpass operations like subpassLoad and subpassLoadMS are allowed to be 204used. 205 206To record a subpass shading, call: 207 208include::{generated}/api/protos/vkCmdSubpassShadingHUAWEI.adoc[] 209 210 * pname:commandBuffer is the command buffer into which the command will be 211 recorded. 212 213When the command is executed, a global workgroup consisting of ceil (render 214area size / local workgroup size) local workgroups is assembled. 215 216.Valid Usage 217**** 218include::{chapters}/commonvalidity/draw_dispatch_common.adoc[] 219 * [[VUID-vkCmdSubpassShadingHUAWEI-None-04931]] 220 This command must be called in a subpass with bind point 221 ename:VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI. 222 No draw commands can be called in the same subpass. 223 Only one flink:vkCmdSubpassShadingHUAWEI command can be called in a 224 subpass 225**** 226 227include::{generated}/validity/protos/vkCmdSubpassShadingHUAWEI.adoc[] 228-- 229endif::VK_HUAWEI_subpass_shading[] 230 231ifdef::VK_NV_cuda_kernel_launch[] 232include::{chapters}/VK_NV_cuda_kernel_launch/dispatch.adoc[] 233endif::VK_NV_cuda_kernel_launch[] 234