197 lines
7.4 KiB
Plaintext
197 lines
7.4 KiB
Plaintext
// Copyright (c) 2015-2019 Khronos Group. This work is licensed under a
|
|
// Creative Commons Attribution 4.0 International License; see
|
|
// http://creativecommons.org/licenses/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 dispatch
|
|
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 using indirect parameters',type='protos']
|
|
--
|
|
:refpage: vkCmdDispatchIndirect
|
|
|
|
To record an indirect command dispatch, 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 dispatch indirect 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',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[]
|
|
* [[VUID-vkCmdDispatchBase-baseGroupX-00421]]
|
|
pname:baseGroupX must: be less than
|
|
sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0]
|
|
* [[VUID-vkCmdDispatchBase-baseGroupX-00422]]
|
|
pname:baseGroupX 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[]
|