Dispatching commands (commands with 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 currently bound compute pipeline. A compute pipeline must
be bound to a command buffer before any dispatch commands are recorded in
that command buffer.
To record a dispatch, call:
void vkCmdDispatch( VkCommandBuffer commandBuffer, uint32_t x, uint32_t y, uint32_t z);
commandBuffer
is the command buffer into which the command will be
recorded.
x
is the number of local workgroups to dispatch in the X dimension.
y
is the number of local workgroups to dispatch in the Y dimension.
z
is the number of local workgroups to dispatch in the Z dimension.
When the command is executed, a global workgroup consisting of $x \times y \times z$ local workgroups is assembled.
To record an indirect command dispatch, call:
void vkCmdDispatchIndirect( VkCommandBuffer commandBuffer, VkBuffer buffer, VkDeviceSize offset);
commandBuffer
is the command buffer into which the command will be
recorded.
buffer
is the buffer containing dispatch parameters.
offset
is the byte offset into buffer
where parameters
begin.
vkCmdDispatchIndirect
behaves similarly to vkCmdDispatch
except
that the parameters are read by the device from a buffer during execution.
The parameters of the dispatch are encoded in a
VkDispatchIndirectCommand
structure taken from buffer
starting
at offset
.
The VkDispatchIndirectCommand
structure is defined as:
typedef struct VkDispatchIndirectCommand { uint32_t x; uint32_t y; uint32_t z; } VkDispatchIndirectCommand;
x
is the number of local workgroups to dispatch in the X dimension.
y
is the number of local workgroups to dispatch in the Y dimension.
z
is the number of local workgroups to dispatch in the Z dimension.
The members of VkDispatchIndirectCommand
structure have the same
meaning as the similarly named parameters of vkCmdDispatch
.