// 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[]