// Copyright 2015-2021 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.txt[]

  * 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.txt[]
include::{chapters}/commonvalidity/draw_dispatch_nonindirect_common.txt[]
  * [[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.txt[]
--

[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.txt[]

  * 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.txt[]
include::{chapters}/commonvalidity/draw_dispatch_indirect_common.txt[]
  * [[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.txt[]
--

[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.txt[]

  * 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.txt[]
--

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.txt[]
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.txt[]
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.txt[]
include::{chapters}/commonvalidity/draw_dispatch_nonindirect_common.txt[]
  * [[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.txt[]
--
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.txt[]

  * 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.txt[]
  * [[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.txt[]
--
endif::VK_HUAWEI_subpass_shading[]