// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html

[[dispatch]]
= Dispatching Commands

_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:

include::../protos/vkCmdDispatch.txt[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * 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.

When the command is executed, a global workgroup consisting of
latexmath:[$x \times y \times z$] local workgroups is assembled.

include::../validity/protos/vkCmdDispatch.txt[]

An indirect dispatch is recorded by calling:

include::../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.

include::../validity/protos/vkCmdDispatchIndirect.txt[]

The definition of sname:VkDispatchIndirectCommand is:

include::../structs/VkDispatchIndirectCommand.txt[]

The members of sname:VkDispatchIndirectCommand structure have the same
meaning as the similarly named parameters of flink:vkCmdDispatch.

include::../validity/structs/VkDispatchIndirectCommand.txt[]