// Copyright (c) 2019-2020 NVIDIA Corporation
//
// SPDX-License-Identifier: CC-BY-4.0

== Indirect Commands Generation And Execution

[open,refpage='vkGetGeneratedCommandsMemoryRequirementsNV',desc='Retrieve the buffer allocation requirements for generated commands',type='protos']
--
The generation of commands on the device requires a `preprocess` buffer.
To retrieve the memory size and alignment requirements of a particular
execution state call:

include::{generated}/api/protos/vkGetGeneratedCommandsMemoryRequirementsNV.txt[]

  * pname:device is the logical device that owns the buffer.
  * pname:pInfo is a pointer to a
    sname:VkGeneratedCommandsMemoryRequirementsInfoNV structure containing
    parameters required for the memory requirements query.
  * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements2
    structure in which the memory requirements of the buffer object are
    returned.

.Valid Usage
****
  * [[VUID-vkGetGeneratedCommandsMemoryRequirementsNV-deviceGeneratedCommands-02906]]
    The <<features-deviceGeneratedCommands,
    sname:VkPhysicalDeviceDeviceGeneratedCommandsFeaturesNV::pname:deviceGeneratedCommands>>
    feature must: be enabled
****

include::{generated}/validity/protos/vkGetGeneratedCommandsMemoryRequirementsNV.txt[]
--

[open,refpage='VkGeneratedCommandsMemoryRequirementsInfoNV',desc='Structure specifying parameters for the reservation of preprocess buffer space',type='structs']
--
include::{generated}/api/structs/VkGeneratedCommandsMemoryRequirementsInfoNV.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:pipelineBindPoint is the elink:VkPipelineBindPoint of the
    pname:pipeline that this buffer memory is intended to be used with
    during the execution.
  * pname:pipeline is the slink:VkPipeline that this buffer memory is
    intended to be used with during the execution.
  * pname:indirectCommandsLayout is the slink:VkIndirectCommandsLayoutNV
    that this buffer memory is intended to be used with.
  * pname:maxSequencesCount is the maximum number of sequences that this
    buffer memory in combination with the other state provided can: be used
    with.

.Valid Usage
****
  * [[VUID-VkGeneratedCommandsMemoryRequirementsInfoNV-maxSequencesCount-02907]]
    pname:maxSequencesCount must: be less or equal to
    slink:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:maxIndirectSequenceCount
****

include::{generated}/validity/structs/VkGeneratedCommandsMemoryRequirementsInfoNV.txt[]
--

[open,refpage='vkCmdExecuteGeneratedCommandsNV',desc='Generate and execute commands on the device',type='protos']
--
:refpage: vkCmdExecuteGeneratedCommandsNV

The actual generation of commands as well as their execution on the device
is handled as single action with:

include::{generated}/api/protos/vkCmdExecuteGeneratedCommandsNV.txt[]

  * pname:commandBuffer is the command buffer into which the command is
    recorded.
  * pname:isPreprocessed represents whether the input data has already been
    preprocessed on the device.
    If it is ename:VK_FALSE this command will implicitly trigger the
    preprocessing step, otherwise not.
  * pname:pGeneratedCommandsInfo is a pointer to a
    slink:VkGeneratedCommandsInfoNV structure containing parameters
    affecting the generation of commands.

.Valid Usage
****
include::{chapters}/commonvalidity/draw_common.txt[]
include::{chapters}/commonvalidity/draw_vertex_binding.txt[]
ifdef::VK_VERSION_1_1[]
  * [[VUID-vkCmdExecuteGeneratedCommandsNV-commandBuffer-02970]]
    pname:commandBuffer must: not be a protected command buffer
endif::VK_VERSION_1_1[]
  * [[VUID-vkCmdExecuteGeneratedCommandsNV-isPreprocessed-02908]]
    If pname:isPreprocessed is ename:VK_TRUE then
    flink:vkCmdPreprocessGeneratedCommandsNV must: have already been
    executed on the device, using the same pname:pGeneratedCommandsInfo
    content as well as the content of the input buffers it references (all
    except slink:VkGeneratedCommandsInfoNV::pname:preprocessBuffer).
    Furthermore pname:pGeneratedCommandsInfo`s pname:indirectCommandsLayout
    must: have been created with the
    ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_NV bit
    set
  * [[VUID-vkCmdExecuteGeneratedCommandsNV-pipeline-02909]]
    sname:VkGeneratedCommandsInfoNV::pname:pipeline must: match the current
    bound pipeline at
    sname:VkGeneratedCommandsInfoNV::pname:pipelineBindPoint
ifdef::VK_EXT_transform_feedback[]
  * [[VUID-vkCmdExecuteGeneratedCommandsNV-None-02910]]
    Transform feedback must: not be active
endif::VK_EXT_transform_feedback[]
  * [[VUID-vkCmdExecuteGeneratedCommandsNV-deviceGeneratedCommands-02911]]
    The <<features-deviceGeneratedCommands,
    sname:VkPhysicalDeviceDeviceGeneratedCommandsFeaturesNV::pname:deviceGeneratedCommands>>
    feature must: be enabled
****

include::{generated}/validity/protos/vkCmdExecuteGeneratedCommandsNV.txt[]
--

[open,refpage='VkGeneratedCommandsInfoNV',desc='Structure specifying parameters for the generation of commands',type='structs']
--
include::{generated}/api/structs/VkGeneratedCommandsInfoNV.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:pipelineBindPoint is the elink:VkPipelineBindPoint used for the
    pname:pipeline.
  * pname:pipeline is the slink:VkPipeline used in the generation and
    execution process.
  * pname:indirectCommandsLayout is the slink:VkIndirectCommandsLayoutNV
    that provides the command sequence to generate.
  * pname:streamCount defines the number of input streams
  * pname:pStreams is a pointer to an array of pname:streamCount
    slink:VkIndirectCommandsStreamNV structures providing the input data for
    the tokens used in pname:indirectCommandsLayout.
  * pname:sequencesCount is the maximum number of sequences to reserve.
    If pname:sequencesCountBuffer is dlink:VK_NULL_HANDLE, this is also the
    actual number of sequences generated.
  * pname:preprocessBuffer is the slink:VkBuffer that is used for
    preprocessing the input data for execution.
    If this structure is used with flink:vkCmdExecuteGeneratedCommandsNV
    with its pname:isPreprocessed set to `VK_TRUE`, then the preprocessing
    step is skipped and data is only read from this buffer.
  * pname:preprocessOffset is the byte offset into pname:preprocessBuffer
    where the preprocessed data is stored.
  * pname:preprocessSize is the maximum byte size within the
    pname:preprocessBuffer after the pname:preprocessOffset that is
    available for preprocessing.
  * pname:sequencesCountBuffer is a sname:VkBuffer in which the actual
    number of sequences is provided as single code:uint32_t value.
  * pname:sequencesCountOffset is the byte offset into
    pname:sequencesCountBuffer where the count value is stored.
  * pname:sequencesIndexBuffer is a sname:VkBuffer that encodes the used
    sequence indices as code:uint32_t array.
  * pname:sequencesIndexOffset is the byte offset into
    pname:sequencesIndexBuffer where the index values start.

.Valid Usage
****
  * [[VUID-VkGeneratedCommandsInfoNV-pipeline-02912]]
    The provided pname:pipeline must: match the pipeline bound at execution
    time
  * [[VUID-VkGeneratedCommandsInfoNV-indirectCommandsLayout-02913]]
    If the pname:indirectCommandsLayout uses a token of
    ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SHADER_GROUP_NV, then the
    pname:pipeline must: have been created with multiple shader groups
  * [[VUID-VkGeneratedCommandsInfoNV-indirectCommandsLayout-02914]]
    If the pname:indirectCommandsLayout uses a token of
    ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SHADER_GROUP_NV, then the
    pname:pipeline must: have been created with
    ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV set in
    sname:VkGraphicsPipelineCreateInfo::pname:flags
  * [[VUID-VkGeneratedCommandsInfoNV-indirectCommandsLayout-02915]]
    If the pname:indirectCommandsLayout uses a token of
    ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, then the
    pname:pipeline`s sname:VkPipelineLayout must: match the
    slink:VkIndirectCommandsLayoutTokenNV::pname:pushconstantPipelineLayout
  * [[VUID-VkGeneratedCommandsInfoNV-streamCount-02916]]
    pname:streamCount must: match the pname:indirectCommandsLayout's
    pname:streamCount
  * [[VUID-VkGeneratedCommandsInfoNV-sequencesCount-02917]]
    pname:sequencesCount must: be less or equal to
    slink:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:maxIndirectSequenceCount
    and
    slink:VkGeneratedCommandsMemoryRequirementsInfoNV::pname:maxSequencesCount
    that was used to determine the pname:preprocessSize
  * [[VUID-VkGeneratedCommandsInfoNV-preprocessBuffer-02918]]
    pname:preprocessBuffer must: have the
    ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set in its usage flag
  * [[VUID-VkGeneratedCommandsInfoNV-preprocessOffset-02919]]
    pname:preprocessOffset must: be aligned to
    slink:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:minIndirectCommandsBufferOffsetAlignment
  * [[VUID-VkGeneratedCommandsInfoNV-preprocessBuffer-02971]]
    If pname:preprocessBuffer is non-sparse then it must: be bound
    completely and contiguously to a single sname:VkDeviceMemory object
  * [[VUID-VkGeneratedCommandsInfoNV-preprocessSize-02920]]
    pname:preprocessSize must: be at least equal to the memory requirement`s
    size returned by flink:vkGetGeneratedCommandsMemoryRequirementsNV using
    the matching inputs (pname:indirectCommandsLayout, ...) as within this
    structure
  * [[VUID-VkGeneratedCommandsInfoNV-sequencesCountBuffer-02921]]
    pname:sequencesCountBuffer can: be set if the actual used count of
    sequences is sourced from the provided buffer.
    In that case the pname:sequencesCount serves as upper bound
  * [[VUID-VkGeneratedCommandsInfoNV-sequencesCountBuffer-02922]]
    If pname:sequencesCountBuffer is not dlink:VK_NULL_HANDLE, its usage
    flag must: have the ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set
  * [[VUID-VkGeneratedCommandsInfoNV-sequencesCountBuffer-02923]]
    If pname:sequencesCountBuffer is not dlink:VK_NULL_HANDLE,
    pname:sequencesCountOffset must: be aligned to
    sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:minSequencesCountBufferOffsetAlignment
  * [[VUID-VkGeneratedCommandsInfoNV-sequencesCountBuffer-02972]]
    If pname:sequencesCountBuffer is not dlink:VK_NULL_HANDLE and is
    non-sparse then it must: be bound completely and contiguously to a
    single sname:VkDeviceMemory object
  * [[VUID-VkGeneratedCommandsInfoNV-sequencesIndexBuffer-02924]]
    If pname:indirectCommandsLayout's
    ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_INDEXED_SEQUENCES_BIT_NV is set,
    pname:sequencesIndexBuffer must: be set otherwise it must: be
    dlink:VK_NULL_HANDLE
  * [[VUID-VkGeneratedCommandsInfoNV-sequencesIndexBuffer-02925]]
    If pname:sequencesIndexBuffer is not dlink:VK_NULL_HANDLE, its usage
    flag must: have the ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set
  * [[VUID-VkGeneratedCommandsInfoNV-sequencesIndexBuffer-02926]]
    If pname:sequencesIndexBuffer is not dlink:VK_NULL_HANDLE,
    pname:sequencesIndexOffset must: be aligned to
    sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:minSequencesIndexBufferOffsetAlignment
  * [[VUID-VkGeneratedCommandsInfoNV-sequencesIndexBuffer-02973]]
    If pname:sequencesIndexBuffer is not dlink:VK_NULL_HANDLE and is
    non-sparse then it must: be bound completely and contiguously to a
    single sname:VkDeviceMemory object
****

include::{generated}/validity/structs/VkGeneratedCommandsInfoNV.txt[]
--

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

[source,c]
---------------------------------------------------
uint32_t sequencesCount = sequencesCountBuffer ?
      min(maxSequencesCount, sequencesCountBuffer.load_uint32(sequencesCountOffset) :
      maxSequencesCount;


cmdProcessAllSequences(commandBuffer, pipeline,
                       indirectCommandsLayout, pIndirectCommandsStreams,
                       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 values of all state related to the
pname:pipelineBindPoint used are undefined: after this command.
====

[open,refpage='vkCmdPreprocessGeneratedCommandsNV',desc='Performs preprocessing for generated commands',type='protos']
--
Commands can: be preprocessed prior execution using the following command:

include::{generated}/api/protos/vkCmdPreprocessGeneratedCommandsNV.txt[]

  * pname:commandBuffer is the command buffer which does the preprocessing.
  * pname:pGeneratedCommandsInfo is a pointer to a
    slink:VkGeneratedCommandsInfoNV structure containing parameters
    affecting the preprocessing step.

.Valid Usage
****
ifdef::VK_VERSION_1_1[]
  * [[VUID-vkCmdPreprocessGeneratedCommandsNV-commandBuffer-02974]]
    pname:commandBuffer must: not be a protected command buffer
endif::VK_VERSION_1_1[]
  * [[VUID-vkCmdPreprocessGeneratedCommandsNV-pGeneratedCommandsInfo-02927]]
    pname:pGeneratedCommandsInfo`s pname:indirectCommandsLayout must: have
    been created with the
    ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_NV bit
    set
  * [[VUID-vkCmdPreprocessGeneratedCommandsNV-deviceGeneratedCommands-02928]]
    The <<features-deviceGeneratedCommands,
    sname:VkPhysicalDeviceDeviceGeneratedCommandsFeaturesNV::pname:deviceGeneratedCommands>>
    feature must: be enabled
****

include::{generated}/validity/protos/vkCmdPreprocessGeneratedCommandsNV.txt[]
--