| // Copyright 2015-2023 The Khronos Group Inc. |
| // |
| // SPDX-License-Identifier: CC-BY-4.0 |
| |
| [[dispatch]] |
| = Dispatching Commands |
| |
| _Dispatching commands_ (commands with ftext:Dispatch in the name) provoke |
| work in a compute pipeline. |
| Dispatching commands are recorded into a command buffer and when executed by |
| a queue, will produce work which executes according to the bound compute |
| pipeline. |
| A compute pipeline must: be bound to a command buffer before any dispatching |
| commands are recorded in that command buffer. |
| |
| [open,refpage='vkCmdDispatch',desc='Dispatch compute work items',type='protos'] |
| -- |
| :refpage: vkCmdDispatch |
| |
| To record a dispatch, call: |
| |
| include::{generated}/api/protos/vkCmdDispatch.adoc[] |
| |
| * pname:commandBuffer is the command buffer into which the command will be |
| recorded. |
| * pname:groupCountX is the number of local workgroups to dispatch in the X |
| dimension. |
| * pname:groupCountY is the number of local workgroups to dispatch in the Y |
| dimension. |
| * pname:groupCountZ is the number of local workgroups to dispatch in the Z |
| dimension. |
| |
| When the command is executed, a global workgroup consisting of |
| [eq]#pname:groupCountX {times} pname:groupCountY {times} pname:groupCountZ# |
| local workgroups is assembled. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/draw_dispatch_common.adoc[] |
| include::{chapters}/commonvalidity/draw_dispatch_nonindirect_common.adoc[] |
| * [[VUID-vkCmdDispatch-groupCountX-00386]] |
| pname:groupCountX must: be less than or equal to |
| sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0] |
| * [[VUID-vkCmdDispatch-groupCountY-00387]] |
| pname:groupCountY must: be less than or equal to |
| sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[1] |
| * [[VUID-vkCmdDispatch-groupCountZ-00388]] |
| pname:groupCountZ must: be less than or equal to |
| sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2] |
| **** |
| |
| include::{generated}/validity/protos/vkCmdDispatch.adoc[] |
| -- |
| |
| [open,refpage='vkCmdDispatchIndirect',desc='Dispatch compute work items with indirect parameters',type='protos'] |
| -- |
| :refpage: vkCmdDispatchIndirect |
| |
| To record an indirect dispatching command, call: |
| |
| include::{generated}/api/protos/vkCmdDispatchIndirect.adoc[] |
| |
| * pname:commandBuffer is the command buffer into which the command will be |
| recorded. |
| * pname:buffer is the buffer containing dispatch parameters. |
| * pname:offset is the byte offset into pname:buffer where parameters |
| begin. |
| |
| fname:vkCmdDispatchIndirect behaves similarly to flink:vkCmdDispatch except |
| that the parameters are read by the device from a buffer during execution. |
| The parameters of the dispatch are encoded in a |
| slink:VkDispatchIndirectCommand structure taken from pname:buffer starting |
| at pname:offset. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/draw_dispatch_common.adoc[] |
| include::{chapters}/commonvalidity/draw_dispatch_indirect_common.adoc[] |
| * [[VUID-vkCmdDispatchIndirect-offset-00407]] |
| The sum of pname:offset and the size of sname:VkDispatchIndirectCommand |
| must: be less than or equal to the size of pname:buffer |
| **** |
| |
| include::{generated}/validity/protos/vkCmdDispatchIndirect.adoc[] |
| -- |
| |
| [open,refpage='VkDispatchIndirectCommand',desc='Structure specifying a indirect dispatching command',type='structs',xrefs='vkCmdDispatchIndirect'] |
| -- |
| The sname:VkDispatchIndirectCommand structure is defined as: |
| |
| include::{generated}/api/structs/VkDispatchIndirectCommand.adoc[] |
| |
| * pname:x is the number of local workgroups to dispatch in the X |
| dimension. |
| * pname:y is the number of local workgroups to dispatch in the Y |
| dimension. |
| * pname:z is the number of local workgroups to dispatch in the Z |
| dimension. |
| |
| The members of sname:VkDispatchIndirectCommand have the same meaning as the |
| corresponding parameters of flink:vkCmdDispatch. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkDispatchIndirectCommand-x-00417]] |
| pname:x must: be less than or equal to |
| sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0] |
| * [[VUID-VkDispatchIndirectCommand-y-00418]] |
| pname:y must: be less than or equal to |
| sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[1] |
| * [[VUID-VkDispatchIndirectCommand-z-00419]] |
| pname:z must: be less than or equal to |
| sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2] |
| **** |
| |
| include::{generated}/validity/structs/VkDispatchIndirectCommand.adoc[] |
| -- |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_device_group[] |
| [open,refpage='vkCmdDispatchBase',desc='Dispatch compute work items with non-zero base values for the workgroup IDs',type='protos'] |
| -- |
| :refpage: vkCmdDispatchBase |
| |
| To record a dispatch using non-zero base values for the components of |
| code:WorkgroupId, call: |
| |
| ifdef::VK_VERSION_1_1[] |
| include::{generated}/api/protos/vkCmdDispatchBase.adoc[] |
| endif::VK_VERSION_1_1[] |
| |
| ifdef::VK_VERSION_1_1+VK_KHR_device_group[or the equivalent command] |
| |
| ifdef::VK_KHR_device_group[] |
| include::{generated}/api/protos/vkCmdDispatchBaseKHR.adoc[] |
| endif::VK_KHR_device_group[] |
| |
| * pname:commandBuffer is the command buffer into which the command will be |
| recorded. |
| * pname:baseGroupX is the start value for the X component of |
| code:WorkgroupId. |
| * pname:baseGroupY is the start value for the Y component of |
| code:WorkgroupId. |
| * pname:baseGroupZ is the start value for the Z component of |
| code:WorkgroupId. |
| * pname:groupCountX is the number of local workgroups to dispatch in the X |
| dimension. |
| * pname:groupCountY is the number of local workgroups to dispatch in the Y |
| dimension. |
| * pname:groupCountZ is the number of local workgroups to dispatch in the Z |
| dimension. |
| |
| When the command is executed, a global workgroup consisting of |
| [eq]#pname:groupCountX {times} pname:groupCountY {times} pname:groupCountZ# |
| local workgroups is assembled, with code:WorkgroupId values ranging from |
| [eq]#[ptext:baseGroup*, ptext:baseGroup* {plus} ptext:groupCount*)# in each |
| component. |
| flink:vkCmdDispatch is equivalent to |
| `vkCmdDispatchBase(0,0,0,groupCountX,groupCountY,groupCountZ)`. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/draw_dispatch_common.adoc[] |
| include::{chapters}/commonvalidity/draw_dispatch_nonindirect_common.adoc[] |
| * [[VUID-vkCmdDispatchBase-baseGroupX-00421]] |
| pname:baseGroupX must: be less than |
| sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0] |
| * [[VUID-vkCmdDispatchBase-baseGroupX-00422]] |
| pname:baseGroupY must: be less than |
| sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[1] |
| * [[VUID-vkCmdDispatchBase-baseGroupZ-00423]] |
| pname:baseGroupZ must: be less than |
| sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2] |
| * [[VUID-vkCmdDispatchBase-groupCountX-00424]] |
| pname:groupCountX must: be less than or equal to |
| sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0] minus |
| pname:baseGroupX |
| * [[VUID-vkCmdDispatchBase-groupCountY-00425]] |
| pname:groupCountY must: be less than or equal to |
| sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[1] minus |
| pname:baseGroupY |
| * [[VUID-vkCmdDispatchBase-groupCountZ-00426]] |
| pname:groupCountZ must: be less than or equal to |
| sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2] minus |
| pname:baseGroupZ |
| * [[VUID-vkCmdDispatchBase-baseGroupX-00427]] |
| If any of pname:baseGroupX, pname:baseGroupY, or pname:baseGroupZ are |
| not zero, then the bound compute pipeline must: have been created with |
| the ename:VK_PIPELINE_CREATE_DISPATCH_BASE flag |
| **** |
| |
| include::{generated}/validity/protos/vkCmdDispatchBase.adoc[] |
| -- |
| endif::VK_VERSION_1_1,VK_KHR_device_group[] |
| |
| ifdef::VK_HUAWEI_subpass_shading[] |
| [open,refpage='vkCmdSubpassShadingHUAWEI',desc='Dispatch compute work items',type='protos'] |
| -- |
| :refpage: vkCmdSubpassShadingHUAWEI |
| |
| A subpass shading dispatches a compute pipeline work with the work dimension |
| of render area of the calling subpass and work groups are partitioned by |
| specified work group size. |
| Subpass operations like subpassLoad and subpassLoadMS are allowed to be |
| used. |
| |
| To record a subpass shading, call: |
| |
| include::{generated}/api/protos/vkCmdSubpassShadingHUAWEI.adoc[] |
| |
| * pname:commandBuffer is the command buffer into which the command will be |
| recorded. |
| |
| When the command is executed, a global workgroup consisting of ceil (render |
| area size / local workgroup size) local workgroups is assembled. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/draw_dispatch_common.adoc[] |
| * [[VUID-vkCmdSubpassShadingHUAWEI-None-04931]] |
| This command must be called in a subpass with bind point |
| ename:VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI. |
| No draw commands can be called in the same subpass. |
| Only one flink:vkCmdSubpassShadingHUAWEI command can be called in a |
| subpass |
| **** |
| |
| include::{generated}/validity/protos/vkCmdSubpassShadingHUAWEI.adoc[] |
| -- |
| endif::VK_HUAWEI_subpass_shading[] |
| |
| ifdef::VK_NV_cuda_kernel_launch[] |
| include::{chapters}/VK_NV_cuda_kernel_launch/dispatch.adoc[] |
| endif::VK_NV_cuda_kernel_launch[] |
