== Indirect Commands Generation

// refBegin vkCmdReserveSpaceForCommandsNVX Perform a reservation of command buffer space

Command space for generated commands recorded into a secondary command
buffer must: be reserved by calling:

include::../../api/protos/vkCmdReserveSpaceForCommandsNVX.txt[]

  * pname:commandBuffer is the secondary command buffer in which the space
    for device-generated commands is reserved.
  * pname:pProcessCommandsInfo is a pointer to an instance of the
    slink:vkCmdReserveSpaceForCommandsNVX structure containing parameters
    affecting the reservation of command buffer space.

.Valid Usage
****
  * [[VUID-vkCmdReserveSpaceForCommandsNVX-commandBuffer-01329]]
    The provided pname:commandBuffer must: not have had a prior space
    reservation since its creation or the last reset.
  * [[VUID-vkCmdReserveSpaceForCommandsNVX-commandBuffer-01330]]
    The state of the pname:commandBuffer must: be legal to execute all
    commands within the sequence provided by the
    pname:indirectCommandsLayout member of pname:pProcessCommandsInfo.
****

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

// refBegin VkCmdReserveSpaceForCommandsInfoNVX Structure specifying parameters for the reservation of command buffer space

include::../../api/structs/VkCmdReserveSpaceForCommandsInfoNVX.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to an extension-specific structure.
  * pname:objectTable is the sname:VkObjectTableNVX to be used for the
    generation process.
    Only registered objects at the time
    flink:vkCmdReserveSpaceForCommandsNVX is called, will be taken into
    account for the reservation.
  * pname:indirectCommandsLayout is the sname:VkIndirectCommandsLayoutNVX
    that must: also be used at generation time.
  * pname:maxSequencesCount is the maximum number of sequences for which
    command buffer space will be reserved.

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

The generated commands will behave as if they were recorded within the call
to fname:vkCmdReserveSpaceForCommandsNVX, that means they can inherit state
defined in the command buffer prior this call.
However, given the stateless nature of the generated sequences, they will
not affect commands after the reserved space.
Treat the state that can: be affected by the provided
sname:VkIndirectCommandsLayoutNVX as undefined.

// refBegin vkCmdProcessCommandsNVX Performs the generation of commands on the device

The actual generation on the device is handled with:

include::../../api/protos/vkCmdProcessCommandsNVX.txt[]

  * pname:commandBuffer is the primary command buffer in which the
    generation process takes space.
  * pname:pProcessCommandsInfo is a pointer to an instance of the
    slink:VkCmdProcessCommandsInfoNVX structure containing parameters
    affecting the processing of commands.

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

// refBegin VkCmdProcessCommandsInfoNVX Structure specifying parameters for the generation of commands

include::../../api/structs/VkCmdProcessCommandsInfoNVX.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to an extension-specific structure.
  * pname:objectTable is the sname:VkObjectTableNVX to be used for the
    generation process.
    Only registered objects at the time
    flink:vkCmdReserveSpaceForCommandsNVX is called, will be taken into
    account for the reservation.
  * pname:indirectCommandsLayout is the sname:VkIndirectCommandsLayoutNVX
    that provides the command sequence to generate.
  * pname:indirectCommandsTokenCount defines the number of input tokens
    used.
  * pname:pIndirectCommandsTokens provides an array of
    slink:VkIndirectCommandsTokenNVX that reference the input data for each
    token command.
  * pname:maxSequencesCount is the maximum number of sequences for which
    command buffer space will be reserved.
    If pname:sequencesCountBuffer is dlink:VK_NULL_HANDLE, this is also the
    actual number of sequences generated.
  * pname:targetCommandBuffer can: be the secondary sname:VkCommandBuffer in
    which the commands should be recorded.
    If pname:targetCommandBuffer is `NULL` an implicit reservation as well
    as execution takes place on the processing sname:VkCommandBuffer.
  * pname:sequencesCountBuffer can: be sname:VkBuffer from which the actual
    amount of sequences is sourced from as ftext:uint32_t value.
  * pname:sequencesCountOffset is the byte offset into
    pname:sequencesCountBuffer where the count value is stored.
  * pname:sequencesIndexBuffer must: be set if
    pname:indirectCommandsLayout's
    ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_INDEXED_SEQUENCES_BIT is set and
    provides the used sequence indices as ftext:uint32_t array.
    Otherwise it must: be dlink:VK_NULL_HANDLE.
  * pname:sequencesIndexOffset is the byte offset into
    pname:sequencesIndexBuffer where the index values start.


.Valid Usage
****
  * [[VUID-VkCmdProcessCommandsInfoNVX-objectTable-01331]]
    The provided pname:objectTable must: include all objects referenced by
    the generation process.
  * [[VUID-VkCmdProcessCommandsInfoNVX-indirectCommandsTokenCount-01332]]
    pname:indirectCommandsTokenCount must: match the
    pname:indirectCommandsLayout's pname:tokenCount.
  * [[VUID-VkCmdProcessCommandsInfoNVX-tokenType-01333]]
    The pname:tokenType member of each entry in the
    pname:pIndirectCommandsTokens array must: match the values used at
    creation time of pname:indirectCommandsLayout
  * [[VUID-VkCmdProcessCommandsInfoNVX-targetCommandBuffer-01334]]
    If pname:targetCommandBuffer is provided, it must: have reserved command
    space.
  * [[VUID-VkCmdProcessCommandsInfoNVX-targetCommandBuffer-01335]]
    If pname:targetCommandBuffer is provided, the pname:objectTable must:
    match the reservation's objectTable and must: have had all referenced
    objects registered at reservation time.
  * [[VUID-VkCmdProcessCommandsInfoNVX-targetCommandBuffer-01336]]
    If pname:targetCommandBuffer is provided, the
    pname:indirectCommandsLayout must: match the reservation's
    indirectCommandsLayout.
  * [[VUID-VkCmdProcessCommandsInfoNVX-targetCommandBuffer-01337]]
    If pname:targetCommandBuffer is provided, the pname:maxSequencesCount
    must: not exceed the reservation's maxSequencesCount.
  * [[VUID-VkCmdProcessCommandsInfoNVX-sequencesCountBuffer-01338]]
    If pname:sequencesCountBuffer is used, its usage flag must: have
    ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set.
  * [[VUID-VkCmdProcessCommandsInfoNVX-sequencesCountBuffer-01339]]
    If pname:sequencesCountBuffer is used, pname:sequencesCountOffset must:
    be aligned to
    sname:VkDeviceGeneratedCommandsLimitsNVX::pname:minSequenceCountBufferOffsetAlignment.
  * [[VUID-VkCmdProcessCommandsInfoNVX-sequencesIndexBuffer-01340]]
    If pname:sequencesIndexBuffer is used, its usage flag must: have
    ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set.
  * [[VUID-VkCmdProcessCommandsInfoNVX-sequencesIndexBuffer-01341]]
    If pname:sequencesIndexBuffer is used, pname:sequencesIndexOffset must:
    be aligned to
    sname:VkDeviceGeneratedCommandsLimitsNVX::pname:minSequenceIndexBufferOffsetAlignment.
****

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

Referencing the functions defined in <<indirectmdslayout>>,
fname:vkCmdProcessCommandsNVX behaves as:

[source,c]
---------------------------------------------------
// For targetCommandBuffers the existing reservedSpace is reset & overwritten.

VkCommandBuffer cmd = targetCommandBuffer ?
      targetCommandBuffer.reservedSpace :
      commandBuffer;

uint32_t sequencesCount = sequencesCountBuffer ?
      min(maxSequencesCount, sequencesCountBuffer.load_uint32(sequencesCountOffset) :
      maxSequencesCount;


cmdProcessAllSequences(cmd, objectTable,
                       indirectCommandsLayout, pIndirectCommandsTokens,
                       sequencesCount,
                       sequencesIndexBuffer, sequencesIndexOffset);

// The stateful commands within indirectCommandsLayout will not
// affect the state of subsequent commands in the target
// command buffer (cmd)
---------------------------------------------------

[NOTE]
.Note
====
It is important to note that the state that may be affected through
generated commands must: be considered undefined for the commands following
them.
It is not possible to setup generated state and provoking work that uses
this state outside of the generated sequence.
====
