Device-Generated Commands

This chapter discusses the generation of command buffer content on the device, for which these principle steps are to be taken:

  • Define a layout describing the sequence of commands which should be generated.

  • Optionally set up device-bindable shaders.

  • Retrieve device addresses by vkGetBufferDeviceAddressEXT for setting buffers on the device.

  • Fill one or more VkBuffer with the appropriate content that gets interpreted by the command layout.

  • Create a preprocess VkBuffer using the device-queried allocation information.

  • Optionally preprocess the input data in a separate action.

  • Generate and execute the actual commands.

The preprocessing step executes in a separate logical pipeline from either graphics or compute. When preprocessing commands in a separate step they must be explicitly synchronized against the command execution. When not preprocessing in a separate step, the preprocessing is automatically synchronized against the command execution.

Indirect Commands Layout

The device-side command generation happens through an iterative processing of an atomic sequence comprised of command tokens, which are represented by:

// Provided by VK_EXT_device_generated_commands
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkIndirectCommandsLayoutEXT)

or:

// Provided by VK_NV_device_generated_commands
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkIndirectCommandsLayoutNV)

Each indirect command layout must have exactly one action command token and it must be the last token in the sequence.

If the indirect commands layout contains only 1 token, it will be an action command token, and the contents of the indirect buffer will be a sequence of indirect command structures, similar to the ones used for indirect draws and dispatches. On some implementations, using indirect draws and dispatches for these cases will result in increased performance compared to using device-generated commands, due to the overhead that results from using the latter.

Creation and Deletion

Indirect command layouts for VK_EXT_device_generated_commands are created by:

// Provided by VK_EXT_device_generated_commands
VkResult vkCreateIndirectCommandsLayoutEXT(
    VkDevice                                    device,
    const VkIndirectCommandsLayoutCreateInfoEXT* pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkIndirectCommandsLayoutEXT*                pIndirectCommandsLayout);

  • device is the logical device that creates the indirect command layout.

  • pCreateInfo is a pointer to a VkIndirectCommandsLayoutCreateInfoEXT structure containing parameters affecting creation of the indirect command layout.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pIndirectCommandsLayout is a pointer to a VkIndirectCommandsLayoutEXT handle in which the resulting indirect command layout is returned.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkCreateIndirectCommandsLayoutEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateIndirectCommandsLayoutEXT-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkIndirectCommandsLayoutCreateInfoEXT structure

  • VUID-vkCreateIndirectCommandsLayoutEXT-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateIndirectCommandsLayoutEXT-pIndirectCommandsLayout-parameter
    pIndirectCommandsLayout must be a valid pointer to a VkIndirectCommandsLayoutEXT handle

  • VUID-vkCreateIndirectCommandsLayoutEXT-device-queuecount
    The device must have been created with at least 1 queue

Return Codes
Success
Failure

The VkIndirectCommandsLayoutCreateInfoEXT structure is defined as:

// Provided by VK_EXT_device_generated_commands
typedef struct VkIndirectCommandsLayoutCreateInfoEXT {
    VkStructureType                            sType;
    const void*                                pNext;
    VkIndirectCommandsLayoutUsageFlagsEXT      flags;
    VkShaderStageFlags                         shaderStages;
    uint32_t                                   indirectStride;
    VkPipelineLayout                           pipelineLayout;
    uint32_t                                   tokenCount;
    const VkIndirectCommandsLayoutTokenEXT*    pTokens;
} VkIndirectCommandsLayoutCreateInfoEXT;

The following code illustrates some of the flags:

void cmdProcessAllSequences(cmd, indirectExecutionSet, indirectCommandsLayout, indirectAddress, sequencesCount)
{
  for (s = 0; s < sequencesCount; s++)
  {
    sUsed = s;

    if (indirectCommandsLayout.flags & VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_EXT) {
      sUsed = incoherent_implementation_dependent_permutation[ sUsed ];
    }

    cmdProcessSequence( cmd, indirectExecutionSet, indirectCommandsLayout, indirectAddress, sUsed );
  }
}

When tokens are consumed, an offset is computed based on token offset and stream stride. The resulting offset is required to be aligned. The alignment for a specific token is equal to the scalar alignment of the data type as defined in Alignment Requirements, or 4, whichever is lower.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkIndirectCommandsLayoutCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_INDIRECT_COMMANDS_LAYOUT_CREATE_INFO_EXT

  • VUID-VkIndirectCommandsLayoutCreateInfoEXT-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkPipelineLayoutCreateInfo

  • VUID-VkIndirectCommandsLayoutCreateInfoEXT-sType-unique
    The sType value of each structure in the pNext chain must be unique

  • VUID-VkIndirectCommandsLayoutCreateInfoEXT-flags-parameter
    flags must be a valid combination of VkIndirectCommandsLayoutUsageFlagBitsEXT values

  • VUID-VkIndirectCommandsLayoutCreateInfoEXT-shaderStages-parameter
    shaderStages must be a valid combination of VkShaderStageFlagBits values

  • VUID-VkIndirectCommandsLayoutCreateInfoEXT-shaderStages-requiredbitmask
    shaderStages must not be 0

  • VUID-VkIndirectCommandsLayoutCreateInfoEXT-pipelineLayout-parameter
    If pipelineLayout is not VK_NULL_HANDLE, pipelineLayout must be a valid VkPipelineLayout handle

  • VUID-VkIndirectCommandsLayoutCreateInfoEXT-pTokens-parameter
    pTokens must be a valid pointer to an array of tokenCount valid VkIndirectCommandsLayoutTokenEXT structures

  • VUID-VkIndirectCommandsLayoutCreateInfoEXT-tokenCount-arraylength
    tokenCount must be greater than 0

Bits which can be set in VkIndirectCommandsLayoutCreateInfoEXT::flags, specifying usage hints of an indirect command layout, are:

// Provided by VK_EXT_device_generated_commands
typedef enum VkIndirectCommandsLayoutUsageFlagBitsEXT {
    VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_EXT = 0x00000001,
    VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_EXT = 0x00000002,
} VkIndirectCommandsLayoutUsageFlagBitsEXT;
// Provided by VK_EXT_device_generated_commands
typedef VkFlags VkIndirectCommandsLayoutUsageFlagsEXT;

VkIndirectCommandsLayoutUsageFlagsEXT is a bitmask type for setting a mask of zero or more VkIndirectCommandsLayoutUsageFlagBitsEXT.

Indirect command layouts for VK_EXT_device_generated_commands are destroyed by:

// Provided by VK_EXT_device_generated_commands
void vkDestroyIndirectCommandsLayoutEXT(
    VkDevice                                    device,
    VkIndirectCommandsLayoutEXT                 indirectCommandsLayout,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the layout.

  • indirectCommandsLayout is the layout to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • VUID-vkDestroyIndirectCommandsLayoutEXT-indirectCommandsLayout-11114
    All submitted commands that refer to indirectCommandsLayout must have completed execution

  • VUID-vkDestroyIndirectCommandsLayoutEXT-indirectCommandsLayout-11115
    If VkAllocationCallbacks were provided when indirectCommandsLayout was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyIndirectCommandsLayoutEXT-indirectCommandsLayout-11116
    If no VkAllocationCallbacks were provided when indirectCommandsLayout was created, pAllocator must be NULL

Valid Usage (Implicit)

  • VUID-vkDestroyIndirectCommandsLayoutEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyIndirectCommandsLayoutEXT-indirectCommandsLayout-parameter
    If indirectCommandsLayout is not VK_NULL_HANDLE, indirectCommandsLayout must be a valid VkIndirectCommandsLayoutEXT handle

  • VUID-vkDestroyIndirectCommandsLayoutEXT-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyIndirectCommandsLayoutEXT-indirectCommandsLayout-parent
    If indirectCommandsLayout is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to indirectCommandsLayout must be externally synchronized

Indirect command layouts for VK_NV_device_generated_commands are created by:

// Provided by VK_NV_device_generated_commands
VkResult vkCreateIndirectCommandsLayoutNV(
    VkDevice                                    device,
    const VkIndirectCommandsLayoutCreateInfoNV* pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkIndirectCommandsLayoutNV*                 pIndirectCommandsLayout);

  • device is the logical device that creates the indirect command layout.

  • pCreateInfo is a pointer to a VkIndirectCommandsLayoutCreateInfoNV structure containing parameters affecting creation of the indirect command layout.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pIndirectCommandsLayout is a pointer to a VkIndirectCommandsLayoutNV handle in which the resulting indirect command layout is returned.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkCreateIndirectCommandsLayoutNV-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateIndirectCommandsLayoutNV-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkIndirectCommandsLayoutCreateInfoNV structure

  • VUID-vkCreateIndirectCommandsLayoutNV-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateIndirectCommandsLayoutNV-pIndirectCommandsLayout-parameter
    pIndirectCommandsLayout must be a valid pointer to a VkIndirectCommandsLayoutNV handle

  • VUID-vkCreateIndirectCommandsLayoutNV-device-queuecount
    The device must have been created with at least 1 queue

Return Codes
Success
Failure

The VkIndirectCommandsLayoutCreateInfoNV structure is defined as:

// Provided by VK_NV_device_generated_commands
typedef struct VkIndirectCommandsLayoutCreateInfoNV {
    VkStructureType                           sType;
    const void*                               pNext;
    VkIndirectCommandsLayoutUsageFlagsNV      flags;
    VkPipelineBindPoint                       pipelineBindPoint;
    uint32_t                                  tokenCount;
    const VkIndirectCommandsLayoutTokenNV*    pTokens;
    uint32_t                                  streamCount;
    const uint32_t*                           pStreamStrides;
} VkIndirectCommandsLayoutCreateInfoNV;

The following code illustrates some of the flags:

void cmdProcessAllSequences(cmd, pipeline, indirectCommandsLayout, pIndirectCommandsTokens, sequencesCount, indexbuffer, indexbufferOffset)
{
  for (s = 0; s < sequencesCount; s++)
  {
    sUsed = s;

    if (indirectCommandsLayout.flags & VK_INDIRECT_COMMANDS_LAYOUT_USAGE_INDEXED_SEQUENCES_BIT_NV) {
      sUsed = indexbuffer.load_uint32( sUsed * sizeof(uint32_t) + indexbufferOffset);
    }

    if (indirectCommandsLayout.flags & VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_NV) {
      sUsed = incoherent_implementation_dependent_permutation[ sUsed ];
    }

    cmdProcessSequence( cmd, pipeline, indirectCommandsLayout, pIndirectCommandsTokens, sUsed );
  }
}

When tokens are consumed, an offset is computed based on token offset and stream stride. The resulting offset is required to be aligned. The alignment for a specific token is equal to the scalar alignment of the data type as defined in Alignment Requirements, or VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::minIndirectCommandsBufferOffsetAlignment, whichever is lower.

A minIndirectCommandsBufferOffsetAlignment of 4 allows VkDeviceAddress to be packed as uvec2 with scalar layout instead of uint64_t with 8 byte alignment. This enables direct compatibility with D3D12 command signature layouts.
Valid Usage
Valid Usage (Implicit)

  • VUID-VkIndirectCommandsLayoutCreateInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_INDIRECT_COMMANDS_LAYOUT_CREATE_INFO_NV

  • VUID-VkIndirectCommandsLayoutCreateInfoNV-pNext-pNext
    pNext must be NULL

  • VUID-VkIndirectCommandsLayoutCreateInfoNV-flags-parameter
    flags must be a valid combination of VkIndirectCommandsLayoutUsageFlagBitsNV values

  • VUID-VkIndirectCommandsLayoutCreateInfoNV-pipelineBindPoint-parameter
    pipelineBindPoint must be a valid VkPipelineBindPoint value

  • VUID-VkIndirectCommandsLayoutCreateInfoNV-pTokens-parameter
    pTokens must be a valid pointer to an array of tokenCount valid VkIndirectCommandsLayoutTokenNV structures

  • VUID-VkIndirectCommandsLayoutCreateInfoNV-pStreamStrides-parameter
    pStreamStrides must be a valid pointer to an array of streamCount uint32_t values

  • VUID-VkIndirectCommandsLayoutCreateInfoNV-tokenCount-arraylength
    tokenCount must be greater than 0

  • VUID-VkIndirectCommandsLayoutCreateInfoNV-streamCount-arraylength
    streamCount must be greater than 0

Bits which can be set in VkIndirectCommandsLayoutCreateInfoNV::flags, specifying usage hints of an indirect command layout, are:

// Provided by VK_NV_device_generated_commands
typedef enum VkIndirectCommandsLayoutUsageFlagBitsNV {
    VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_NV = 0x00000001,
    VK_INDIRECT_COMMANDS_LAYOUT_USAGE_INDEXED_SEQUENCES_BIT_NV = 0x00000002,
    VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_NV = 0x00000004,
} VkIndirectCommandsLayoutUsageFlagBitsNV;
// Provided by VK_NV_device_generated_commands
typedef VkFlags VkIndirectCommandsLayoutUsageFlagsNV;

VkIndirectCommandsLayoutUsageFlagsNV is a bitmask type for setting a mask of zero or more VkIndirectCommandsLayoutUsageFlagBitsNV.

Indirect command layouts for VK_NV_device_generated_commands are destroyed by:

// Provided by VK_NV_device_generated_commands
void vkDestroyIndirectCommandsLayoutNV(
    VkDevice                                    device,
    VkIndirectCommandsLayoutNV                  indirectCommandsLayout,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the layout.

  • indirectCommandsLayout is the layout to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • VUID-vkDestroyIndirectCommandsLayoutNV-indirectCommandsLayout-02938
    All submitted commands that refer to indirectCommandsLayout must have completed execution

  • VUID-vkDestroyIndirectCommandsLayoutNV-indirectCommandsLayout-02939
    If VkAllocationCallbacks were provided when indirectCommandsLayout was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyIndirectCommandsLayoutNV-indirectCommandsLayout-02940
    If no VkAllocationCallbacks were provided when indirectCommandsLayout was created, pAllocator must be NULL

  • VUID-vkDestroyIndirectCommandsLayoutNV-deviceGeneratedCommands-02941
    The VkPhysicalDeviceDeviceGeneratedCommandsFeaturesNV::deviceGeneratedCommands feature must be enabled

Valid Usage (Implicit)

  • VUID-vkDestroyIndirectCommandsLayoutNV-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyIndirectCommandsLayoutNV-indirectCommandsLayout-parameter
    If indirectCommandsLayout is not VK_NULL_HANDLE, indirectCommandsLayout must be a valid VkIndirectCommandsLayoutNV handle

  • VUID-vkDestroyIndirectCommandsLayoutNV-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyIndirectCommandsLayoutNV-indirectCommandsLayout-parent
    If indirectCommandsLayout is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to indirectCommandsLayout must be externally synchronized

Token Input Streams

For VK_EXT_device_generated_commands, the input streams can contain raw uint32_t values, existing indirect commands such as:

or additional commands as listed below. How the data is used is described in the next section.

The VkBindIndexBufferIndirectCommandEXT structure specifies the input data for the VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXT token.

// Provided by VK_EXT_device_generated_commands
typedef struct VkBindIndexBufferIndirectCommandEXT {
    VkDeviceAddress    bufferAddress;
    uint32_t           size;
    VkIndexType        indexType;
} VkBindIndexBufferIndirectCommandEXT;

  • bufferAddress specifies a physical address of the VkBuffer used as index buffer.

  • size is the byte size range which is available for this operation from the provided address.

  • indexType is a VkIndexType value specifying how indices are treated.

Valid Usage

  • VUID-VkBindIndexBufferIndirectCommandEXT-None-11117
    The buffer’s usage flags from which the address was acquired must have the VK_BUFFER_USAGE_INDEX_BUFFER_BIT bit set

  • VUID-VkBindIndexBufferIndirectCommandEXT-bufferAddress-11118
    The bufferAddress must be aligned to the VkIndexType of the indexType used

Valid Usage (Implicit)

  • VUID-VkBindIndexBufferIndirectCommandEXT-bufferAddress-parameter
    bufferAddress must be a valid VkDeviceAddress value

  • VUID-VkBindIndexBufferIndirectCommandEXT-indexType-parameter
    indexType must be a valid VkIndexType value

The VkBindVertexBufferIndirectCommandEXT structure specifies the input data for the VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT token.

// Provided by VK_EXT_device_generated_commands
typedef struct VkBindVertexBufferIndirectCommandEXT {
    VkDeviceAddress    bufferAddress;
    uint32_t           size;
    uint32_t           stride;
} VkBindVertexBufferIndirectCommandEXT;

  • bufferAddress specifies a physical address of the VkBuffer used as vertex input binding.

  • size is the byte size range which is available for this operation from the provided address.

  • stride is the byte size stride for this vertex input binding as in VkVertexInputBindingDescription::stride.

Valid Usage

  • VUID-VkBindVertexBufferIndirectCommandEXT-None-11120
    The buffer’s usage flag from which the address was acquired must have the VK_BUFFER_USAGE_VERTEX_BUFFER_BIT bit set

Valid Usage (Implicit)

  • VUID-VkBindVertexBufferIndirectCommandEXT-bufferAddress-parameter
    bufferAddress must be a valid VkDeviceAddress value

The VkDrawIndirectCountIndirectCommandEXT structure specifies the input data for all draw-type tokens.

// Provided by VK_EXT_device_generated_commands
typedef struct VkDrawIndirectCountIndirectCommandEXT {
    VkDeviceAddress    bufferAddress;
    uint32_t           stride;
    uint32_t           commandCount;
} VkDrawIndirectCountIndirectCommandEXT;

  • bufferAddress specifies a physical address of the VkBuffer used for draw commands.

  • stride is the byte size stride for the command arguments

  • commandCount is the number of commands to execute

The corresponding indirect draw structure data will be read from the buffer address.

Valid Usage

  • VUID-VkDrawIndirectCountIndirectCommandEXT-None-11122
    The buffer’s usage flag from which the address was acquired must have the VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set

Valid Usage (Implicit)

  • VUID-VkDrawIndirectCountIndirectCommandEXT-bufferAddress-parameter
    bufferAddress must be a valid VkDeviceAddress value

The VkIndirectCommandsStreamNV structure specifies the input data for one or more tokens at processing time.

// Provided by VK_NV_device_generated_commands
typedef struct VkIndirectCommandsStreamNV {
    VkBuffer        buffer;
    VkDeviceSize    offset;
} VkIndirectCommandsStreamNV;

  • buffer specifies the VkBuffer storing the functional arguments for each sequence. These arguments can be written by the device.

  • offset specified an offset into buffer where the arguments start.

Valid Usage

  • VUID-VkIndirectCommandsStreamNV-buffer-02942
    The buffer’s usage flag must have the VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set

  • VUID-VkIndirectCommandsStreamNV-offset-02943
    The offset must be aligned to VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::minIndirectCommandsBufferOffsetAlignment

  • VUID-VkIndirectCommandsStreamNV-buffer-02975
    If buffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

Valid Usage (Implicit)

  • VUID-VkIndirectCommandsStreamNV-buffer-parameter
    buffer must be a valid VkBuffer handle

For VK_NV_device_generated_commands, the input streams can contain raw uint32_t values, existing indirect commands such as:

or additional commands as listed below. How the data is used is described in the next section.

The VkBindShaderGroupIndirectCommandNV structure specifies the input data for the VK_INDIRECT_COMMANDS_TOKEN_TYPE_SHADER_GROUP_NV token.

// Provided by VK_NV_device_generated_commands
typedef struct VkBindShaderGroupIndirectCommandNV {
    uint32_t    groupIndex;
} VkBindShaderGroupIndirectCommandNV;

  • groupIndex specifies which shader group of the current bound graphics pipeline is used.

Valid Usage

  • VUID-VkBindShaderGroupIndirectCommandNV-None-02944
    The current bound graphics pipeline, as well as the pipelines it may reference, must have been created with VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV

  • VUID-VkBindShaderGroupIndirectCommandNV-index-02945
    The index must be within range of the accessible shader groups of the current bound graphics pipeline. See vkCmdBindPipelineShaderGroupNV for further details

The VkBindIndexBufferIndirectCommandNV structure specifies the input data for the VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_NV token.

// Provided by VK_NV_device_generated_commands
typedef struct VkBindIndexBufferIndirectCommandNV {
    VkDeviceAddress    bufferAddress;
    uint32_t           size;
    VkIndexType        indexType;
} VkBindIndexBufferIndirectCommandNV;

  • bufferAddress specifies a physical address of the VkBuffer used as index buffer.

  • size is the byte size range which is available for this operation from the provided address.

  • indexType is a VkIndexType value specifying how indices are treated. Instead of the Vulkan enum values, a custom uint32_t value can be mapped to VkIndexType by specifying the VkIndirectCommandsLayoutTokenNV::pIndexTypes and VkIndirectCommandsLayoutTokenNV::pIndexTypeValues arrays.

Valid Usage

  • VUID-VkBindIndexBufferIndirectCommandNV-None-02946
    The buffer’s usage flag from which the address was acquired must have the VK_BUFFER_USAGE_INDEX_BUFFER_BIT bit set

  • VUID-VkBindIndexBufferIndirectCommandNV-bufferAddress-02947
    The bufferAddress must be aligned to the indexType used

Valid Usage (Implicit)

  • VUID-VkBindIndexBufferIndirectCommandNV-bufferAddress-parameter
    bufferAddress must be a valid VkDeviceAddress value

  • VUID-VkBindIndexBufferIndirectCommandNV-indexType-parameter
    indexType must be a valid VkIndexType value

The VkBindVertexBufferIndirectCommandNV structure specifies the input data for the VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_NV token.

// Provided by VK_NV_device_generated_commands
typedef struct VkBindVertexBufferIndirectCommandNV {
    VkDeviceAddress    bufferAddress;
    uint32_t           size;
    uint32_t           stride;
} VkBindVertexBufferIndirectCommandNV;

  • bufferAddress specifies a physical address of the VkBuffer used as vertex input binding.

  • size is the byte size range which is available for this operation from the provided address.

  • stride is the byte size stride for this vertex input binding as in VkVertexInputBindingDescription::stride. It is only used if VkIndirectCommandsLayoutTokenNV::vertexDynamicStride was set, otherwise the stride is inherited from the current bound graphics pipeline.

Valid Usage

  • VUID-VkBindVertexBufferIndirectCommandNV-None-02949
    The buffer’s usage flag from which the address was acquired must have the VK_BUFFER_USAGE_VERTEX_BUFFER_BIT bit set

Valid Usage (Implicit)

  • VUID-VkBindVertexBufferIndirectCommandNV-bufferAddress-parameter
    bufferAddress must be a valid VkDeviceAddress value

The VkSetStateFlagsIndirectCommandNV structure specifies the input data for the VK_INDIRECT_COMMANDS_TOKEN_TYPE_STATE_FLAGS_NV token. Which state is changed depends on the VkIndirectStateFlagBitsNV specified at VkIndirectCommandsLayoutNV creation time.

// Provided by VK_NV_device_generated_commands
typedef struct VkSetStateFlagsIndirectCommandNV {
    uint32_t    data;
} VkSetStateFlagsIndirectCommandNV;

A subset of the graphics pipeline state can be altered using indirect state flags:

// Provided by VK_NV_device_generated_commands
typedef enum VkIndirectStateFlagBitsNV {
    VK_INDIRECT_STATE_FLAG_FRONTFACE_BIT_NV = 0x00000001,
} VkIndirectStateFlagBitsNV;
// Provided by VK_NV_device_generated_commands
typedef VkFlags VkIndirectStateFlagsNV;

VkIndirectStateFlagsNV is a bitmask type for setting a mask of zero or more VkIndirectStateFlagBitsNV.

The VkBindPipelineIndirectCommandNV structure specifies the input data for the VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV token.

// Provided by VK_NV_device_generated_commands_compute
typedef struct VkBindPipelineIndirectCommandNV {
    VkDeviceAddress    pipelineAddress;
} VkBindPipelineIndirectCommandNV;

  • pipelineAddress specifies the pipeline address of the compute pipeline that will be used in device generated rendering.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkBindPipelineIndirectCommandNV-pipelineAddress-parameter
    pipelineAddress must be a valid VkDeviceAddress value

Tokenized Command Processing

The processing for VK_EXT_device_generated_commands is in principle illustrated below:

void cmdProcessSequence(cmd, indirectExecutionSet, indirectCommandsLayout, indirectAddress, s)
{
  for (t = 0; t < indirectCommandsLayout.tokenCount; t++)
  {
    uint32_t offset  = indirectCommandsLayout.pTokens[t].offset;
    uint32_t stride  = indirectCommandsLayout.indirectStride;
    VkDeviceAddress streamData = indirectAddress;
    const void* input = streamData + stride * s + offset;

    // further details later
    indirectCommandsLayout.pTokens[t].command (cmd, indirectExecutionSet, input, s);
  }
}

void cmdProcessAllSequences(cmd, indirectExecutionSet, indirectCommandsLayout, indirectAddress, sequencesCount)
{
  for (s = 0; s < sequencesCount; s++)
  {
    sUsed = s;

    if (indirectCommandsLayout.flags & VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_EXT) {
      sUsed = incoherent_implementation_dependent_permutation[ sUsed ];
    }

    cmdProcessSequence( cmd, indirectExecutionSet, indirectCommandsLayout, indirectAddress, sUsed );
  }
}

The processing of each sequence is considered stateless, therefore all state changes must occur prior to action commands within the sequence. A single sequence is strictly targeting the VkShaderStageFlags it was created with.

The primary input data for each token is provided through VkBuffer content at preprocessing using vkCmdPreprocessGeneratedCommandsEXT or execution time using vkCmdExecuteGeneratedCommandsEXT, however some functional arguments, for example push constant layouts, are specified at layout creation time. The input size is different for each token.

Possible values of those elements of the VkIndirectCommandsLayoutCreateInfoEXT::pTokens array specifying command tokens (other elements of the array specify command parameters) are:

// Provided by VK_EXT_device_generated_commands
typedef enum VkIndirectCommandsTokenTypeEXT {
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT = 0,
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT = 1,
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT = 2,
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXT = 3,
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT = 4,
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_EXT = 5,
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_EXT = 6,
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_COUNT_EXT = 7,
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_COUNT_EXT = 8,
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_EXT = 9,
  // Provided by VK_EXT_device_generated_commands with VK_NV_mesh_shader
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV_EXT = 1000202002,
  // Provided by VK_EXT_device_generated_commands with VK_NV_mesh_shader
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_NV_EXT = 1000202003,
  // Provided by VK_EXT_device_generated_commands with VK_EXT_mesh_shader
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_EXT = 1000328000,
  // Provided by VK_EXT_device_generated_commands with VK_EXT_mesh_shader
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_EXT = 1000328001,
  // Provided by VK_KHR_ray_tracing_maintenance1 with VK_EXT_device_generated_commands
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_TRACE_RAYS2_EXT = 1000386004,
} VkIndirectCommandsTokenTypeEXT;
Table 1. Supported Indirect Command Tokens
Common Tokens Command Data

VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT

u32[] array of indices into the indirect execution set

VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT

u32[] raw data

VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT

u32 placeholder data (not accessed by shader)

Compute Tokens

VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_EXT

VkDispatchIndirectCommand

Ray Tracing Tokens

VK_INDIRECT_COMMANDS_TOKEN_TYPE_TRACE_RAYS2_EXT

VkTraceRaysIndirectCommand2KHR

Graphics State Tokens

VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXT

VkBindIndexBufferIndirectCommandEXT

VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT

VkBindVertexBufferIndirectCommandEXT

Graphics Draw Tokens

VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_EXT

VkDrawIndexedIndirectCommand

VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_EXT

VkDrawIndirectCommand

VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_EXT

VkDrawMeshTasksIndirectCommandEXT

VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV_EXT

VkDrawMeshTasksIndirectCommandNV

Graphics Draw Count Tokens

VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_COUNT_EXT

VkDrawIndirectCountIndirectCommandEXT with VkDrawIndexedIndirectCommand

VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_COUNT_EXT

VkDrawIndirectCountIndirectCommandEXT with VkDrawIndirectCommand

VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_EXT

VkDrawIndirectCountIndirectCommandEXT with VkDrawMeshTasksIndirectCommandEXT

VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_NV_EXT

VkDrawIndirectCountIndirectCommandEXT with VkDrawMeshTasksIndirectCommandNV

The VkIndirectCommandsLayoutTokenEXT structure specifies details to the function arguments that need to be known at layout creation time:

// Provided by VK_EXT_device_generated_commands
typedef struct VkIndirectCommandsLayoutTokenEXT {
    VkStructureType                   sType;
    const void*                       pNext;
    VkIndirectCommandsTokenTypeEXT    type;
    VkIndirectCommandsTokenDataEXT    data;
    uint32_t                          offset;
} VkIndirectCommandsLayoutTokenEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • type specifies the VkIndirectCommandsTokenTypeEXT for data.

  • data specifies a VkIndirectCommandsTokenDataEXT containing token-specific details for command execution. It is ignored if type does not match any member of the VkIndirectCommandsTokenDataEXT union.

  • offset is the relative byte offset for the token within one sequence of the indirect buffer. The data stored at that offset is the command data for the token, e.g. VkDispatchIndirectCommand.

Valid Usage
Valid Usage (Implicit)

The VkIndirectCommandsTokenDataEXT structure provides token-specific details used to generate the indirect execution layout.

// Provided by VK_EXT_device_generated_commands
typedef union VkIndirectCommandsTokenDataEXT {
    const VkIndirectCommandsPushConstantTokenEXT*    pPushConstant;
    const VkIndirectCommandsVertexBufferTokenEXT*    pVertexBuffer;
    const VkIndirectCommandsIndexBufferTokenEXT*     pIndexBuffer;
    const VkIndirectCommandsExecutionSetTokenEXT*    pExecutionSet;
} VkIndirectCommandsTokenDataEXT;

The appropriate member of the union must be set for each token.

The following code provides detailed information on how an individual sequence is processed. For valid usage, all restrictions from the regular commands apply.

void cmdProcessSequence(cmd, indirectExecutionSet, indirectCommandsLayout, indirectAddress, s)
{
  for (uint32_t t = 0; t < indirectCommandsLayout.tokenCount; t++) {
    VkIndirectCommandsLayoutTokenEXT *token = &indirectCommandsLayout.pTokens[t];

    uint32_t offset  = token->offset;
    uint32_t stride  = indirectCommandsLayout.indirectStride;
    VkDeviceAddress streamData = indirectAddress;
    const void* input = streamData + stride * s + offset;

    switch (token->tokenType) {
    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT:
      uint32_t *bind = input;
      VkIndirectCommandsExecutionSetTokenEXT *info = token->data.pExecutionSet;

      if (info->type == VK_INDIRECT_EXECUTION_SET_INFO_TYPE_PIPELINES_EXT) {
        vkCmdBindPipeline(cmd, indirectExecutionSet.pipelineBindPoint, indirectExecutionSet.pipelines[*bind]);
      } else {
        VkShaderStageFlagBits stages[];
        VkShaderEXT shaders[];
        uint32_t i = 0;
        IterateBitmaskLSBToMSB(iter, info->shaderStages) {
            stages[i] = iter;
            shaders[i] = indirectExecutionSet.shaders[bind[i]].shaderObject;
            i++;
        }
        vkCmdBindShadersEXT(cmd, i, stages, shaders);
      }
      break;

    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT:
      uint32_t* data = input;
      VkPushConstantsInfoKHR info = {
        VK_STRUCTURE_TYPE_PUSH_CONSTANTS_INFO_KHR,
        // this can also use `dynamicGeneratedPipelineLayout' to pass a VkPipelineLayoutCreateInfo from pNext
        indirectCommandsLayout.pipelineLayout,
        token->token.pushConstant.updateRange.shaderStages,
        token->token.pushConstant.updateRange.offset,
        token->token.pushConstant.updateRange.size,
        data
      };

      vkCmdPushConstants2KHR(cmd, &info);
      break;

    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT:
      VkPushConstantsInfoKHR info = {
        VK_STRUCTURE_TYPE_PUSH_CONSTANTS_INFO_KHR,
        // this can also use `dynamicGeneratedPipelineLayout' to pass a VkPipelineLayoutCreateInfo from pNext
        indirectCommandsLayout.pipelineLayout,
        token->token.pushConstant.updateRange.shaderStages,
        token->token.pushConstant.updateRange.offset,
        // this must be 4
        token->token.pushConstant.updateRange.size,
        // this just updates the sequence index
        &s
      };

      vkCmdPushConstants2KHR(cmd, &info);
      break;

    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXT:
      VkBindIndexBufferIndirectCommandEXT* data = input;

      vkCmdBindIndexBuffer(cmd, deriveBuffer(data->bufferAddress), deriveOffset(data->bufferAddress), data->indexType);
      break;

    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT:
      VkBindVertexBufferIndirectCommandEXT* data = input;

      vkCmdBindVertexBuffers2(cmd, token->token.vertexBuffer->vertexBindingUnit, 1, &deriveBuffer(data->bufferAddress),
                              &deriveOffset(data->bufferAddress), data->size, data->stride);
      break;

    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_EXT:
      VkDrawIndexedIndirectCommand *data = input;

      vkCmdDrawIndexed(cmd, data->indexCount, data->instanceCount, data->firstIndex, data->vertexOffset, data->firstInstance);
      break;
    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_COUNT_EXT:
      VkDrawIndirectCountIndirectCommandEXT* data = input;

      vkCmdDrawIndexedIndirect(cmd, deriveBuffer(data->bufferAddress),  deriveoffset(data->bufferAddress), min(data->commandCount, indirectCommandsLayout.maxDrawCount), data->stride);
      break;

    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_EXT:
      VkDrawIndirectCommand* data = input;

      vkCmdDraw(cmd, data->vertex_count, data->instanceCount, data->firstVertex, data->firstIndex);
      break;

    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_COUNT_EXT:
      VkDrawIndirectCountIndirectCommandEXT* data = input;

      vkCmdDrawIndirect(cmd, deriveBuffer(data->bufferAddress), deriveoffset(data->bufferAddress), min(data->commandCount, indirectCommandsLayout.maxDrawCount), data->stride);
      break;

    // only available if VK_NV_mesh_shader is enabled
    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV_EXT:
      VkDrawMeshTasksIndirectCommandNV *data = input;

      vkCmdDrawMeshTasksNV(cmd, data->taskCount, data->firstTask);
     break;

    // only available if VK_NV_mesh_shader is enabled
    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_NV_EXT:
      VkDrawIndirectCountIndirectCommandEXT* data = input;

      vkCmdDrawMeshTasksIndirectCountNV(cmd, deriveBuffer(data->bufferAddress),  deriveoffset(data->bufferAddress), min(data->commandCount, indirectCommandsLayout.maxDrawCount), data->stride);
      break;

    // only available if VK_EXT_mesh_shader is enabled
    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_EXT:
      VkDrawMeshTasksIndirectCommandEXT *data = input;

      vkCmdDrawMeshTasksEXT(cmd, data->groupCountX, data->groupCountY, data->groupCountZ);
     break;

    // only available if VK_EXT_mesh_shader is enabled
    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_EXT:
      VkDrawIndirectCountIndirectCommandEXT* data = input;

      vkCmdDrawMeshTasksIndirectCountEXT(cmd, deriveBuffer(data->bufferAddress),  deriveoffset(data->bufferAddress), min(data->commandCount, indirectCommandsLayout.maxDrawCount), data->stride);
      break;

    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_EXT:
      VkDispatchIndirectCommand *data = input;

      vkCmdDispatch(cmd, data->x, data->y, data->z);
      break;

    // only available if VK_KHR_ray_tracing_maintenance1 is enabled
    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_TRACE_RAYS2_EXT:
      vkCmdTraceRaysIndirect2KHR(cmd, deriveBuffer(input));
      break;
    }
  }
}

The processing for VK_NV_device_generated_commands is in principle illustrated below:

void cmdProcessSequence(cmd, pipeline, indirectCommandsLayout, pIndirectCommandsStreams, s)
{
  for (t = 0; t < indirectCommandsLayout.tokenCount; t++)
  {
    uint32_t stream  = indirectCommandsLayout.pTokens[t].stream;
    uint32_t offset  = indirectCommandsLayout.pTokens[t].offset;
    uint32_t stride  = indirectCommandsLayout.pStreamStrides[stream];
    stream            = pIndirectCommandsStreams[stream];
    const void* input = stream.buffer.pointer( stream.offset + stride * s + offset )

    // further details later
    indirectCommandsLayout.pTokens[t].command (cmd, pipeline, input, s);
  }
}

void cmdProcessAllSequences(cmd, pipeline, indirectCommandsLayout, pIndirectCommandsStreams, sequencesCount)
{
  for (s = 0; s < sequencesCount; s++)
  {
    cmdProcessSequence(cmd, pipeline, indirectCommandsLayout, pIndirectCommandsStreams, s);
  }
}

The processing of each sequence is considered stateless, therefore all state changes must occur before any action command tokens within the sequence. A single sequence is strictly targeting the VkPipelineBindPoint it was created with.

The primary input data for each token is provided through VkBuffer content at preprocessing using vkCmdPreprocessGeneratedCommandsNV or execution time using vkCmdExecuteGeneratedCommandsNV, however some functional arguments, for example binding sets, are specified at layout creation time. The input size is different for each token.

The VkIndirectCommandsPushConstantTokenEXT structure specifies the layout token info for VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT and VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT tokens.

// Provided by VK_EXT_device_generated_commands
typedef struct VkIndirectCommandsPushConstantTokenEXT {
    VkPushConstantRange    updateRange;
} VkIndirectCommandsPushConstantTokenEXT;

  • updateRange is the push constant range that will be updated by the token.

The stageFlags member of updateRange is ignored.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkIndirectCommandsPushConstantTokenEXT-updateRange-parameter
    updateRange must be a valid VkPushConstantRange structure

The VkIndirectCommandsVertexBufferTokenEXT structure specifies the layout token info for the VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT token.

// Provided by VK_EXT_device_generated_commands
typedef struct VkIndirectCommandsVertexBufferTokenEXT {
    uint32_t    vertexBindingUnit;
} VkIndirectCommandsVertexBufferTokenEXT;

  • vertexBindingUnit is the vertex input binding number to be bound.

Valid Usage

  • VUID-VkIndirectCommandsVertexBufferTokenEXT-vertexBindingUnit-11134
    vertexBindingUnit must be less than the total number of vertex input bindings in use by the current graphics state

The VkIndirectCommandsIndexBufferTokenEXT structure specifies the layout token info for the VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXT token.

// Provided by VK_EXT_device_generated_commands
typedef struct VkIndirectCommandsIndexBufferTokenEXT {
    VkIndirectCommandsInputModeFlagBitsEXT    mode;
} VkIndirectCommandsIndexBufferTokenEXT;

  • mode specifies the mode to use with this token.

This allows for easy layering of Vulkan atop other APIs. When VK_INDIRECT_COMMANDS_INPUT_MODE_DXGI_INDEX_BUFFER_EXT is specified, the indirect buffer can contain a D3D12_INDEX_BUFFER_VIEW instead of VkBindIndexBufferIndirectCommandEXT as D3D’s DXGI format value is mapped to the VkIndexType. It works as both structs are otherwise binary compatible.

Valid Usage

  • VUID-VkIndirectCommandsIndexBufferTokenEXT-mode-11135
    mode must be non-zero

  • VUID-VkIndirectCommandsIndexBufferTokenEXT-mode-11136
    mode must be one of the bits supported in VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT::supportedIndirectCommandsInputModes

Valid Usage (Implicit)

Bits which are set in VkIndirectCommandsIndexBufferTokenEXT::mode, specifying how an index buffer is used, are:

// Provided by VK_EXT_device_generated_commands
typedef enum VkIndirectCommandsInputModeFlagBitsEXT {
    VK_INDIRECT_COMMANDS_INPUT_MODE_VULKAN_INDEX_BUFFER_EXT = 0x00000001,
    VK_INDIRECT_COMMANDS_INPUT_MODE_DXGI_INDEX_BUFFER_EXT = 0x00000002,
} VkIndirectCommandsInputModeFlagBitsEXT;
// Provided by VK_EXT_device_generated_commands
typedef VkFlags VkIndirectCommandsInputModeFlagsEXT;

VkIndirectCommandsInputModeFlagsEXT is a bitmask type for setting a mask of zero or more VkIndirectCommandsInputModeFlagBitsEXT.

The VkIndirectCommandsExecutionSetTokenEXT structure specifies the input data for the VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT token.

// Provided by VK_EXT_device_generated_commands
typedef struct VkIndirectCommandsExecutionSetTokenEXT {
    VkIndirectExecutionSetInfoTypeEXT    type;
    VkShaderStageFlags                   shaderStages;
} VkIndirectCommandsExecutionSetTokenEXT;

  • type describes the type of indirect execution set in use.

  • shaderStages specifies the shaders that will be changed by this token.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkIndirectCommandsExecutionSetTokenEXT-type-parameter
    type must be a valid VkIndirectExecutionSetInfoTypeEXT value

  • VUID-VkIndirectCommandsExecutionSetTokenEXT-shaderStages-parameter
    shaderStages must be a valid combination of VkShaderStageFlagBits values

  • VUID-VkIndirectCommandsExecutionSetTokenEXT-shaderStages-requiredbitmask
    shaderStages must not be 0

Possible values of those elements of the VkIndirectCommandsLayoutCreateInfoNV::pTokens array specifying command tokens (other elements of the array specify command parameters) are:

// Provided by VK_NV_device_generated_commands
typedef enum VkIndirectCommandsTokenTypeNV {
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_SHADER_GROUP_NV = 0,
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_STATE_FLAGS_NV = 1,
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_NV = 2,
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_NV = 3,
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV = 4,
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_NV = 5,
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_NV = 6,
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_TASKS_NV = 7,
  // Provided by VK_EXT_mesh_shader with VK_NV_device_generated_commands
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV = 1000328000,
  // Provided by VK_NV_device_generated_commands_compute
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV = 1000428003,
  // Provided by VK_NV_device_generated_commands_compute
    VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_NV = 1000428004,
} VkIndirectCommandsTokenTypeNV;
Table 2. Supported Indirect Command Tokens
Token type Equivalent command

VK_INDIRECT_COMMANDS_TOKEN_TYPE_SHADER_GROUP_NV

vkCmdBindPipelineShaderGroupNV

VK_INDIRECT_COMMANDS_TOKEN_TYPE_STATE_FLAGS_NV

-

VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_NV

vkCmdBindIndexBuffer

VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_NV

vkCmdBindVertexBuffers

VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV

vkCmdPushConstants

VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_NV

vkCmdDrawIndexedIndirect

VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_NV

vkCmdDrawIndirect

VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_TASKS_NV

vkCmdDrawMeshTasksIndirectNV

VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV

vkCmdDrawMeshTasksIndirectEXT

VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV

vkCmdBindPipeline

VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_NV

vkCmdDispatchIndirect

The VkIndirectCommandsLayoutTokenNV structure specifies details to the function arguments that need to be known at layout creation time:

// Provided by VK_NV_device_generated_commands
typedef struct VkIndirectCommandsLayoutTokenNV {
    VkStructureType                  sType;
    const void*                      pNext;
    VkIndirectCommandsTokenTypeNV    tokenType;
    uint32_t                         stream;
    uint32_t                         offset;
    uint32_t                         vertexBindingUnit;
    VkBool32                         vertexDynamicStride;
    VkPipelineLayout                 pushconstantPipelineLayout;
    VkShaderStageFlags               pushconstantShaderStageFlags;
    uint32_t                         pushconstantOffset;
    uint32_t                         pushconstantSize;
    VkIndirectStateFlagsNV           indirectStateFlags;
    uint32_t                         indexTypeCount;
    const VkIndexType*               pIndexTypes;
    const uint32_t*                  pIndexTypeValues;
} VkIndirectCommandsLayoutTokenNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • tokenType is a VkIndirectCommandsTokenTypeNV specifying the token command type.

  • stream is the index of the input stream containing the token argument data.

  • offset is a relative starting offset within the input stream memory for the token argument data.

  • vertexBindingUnit is used for the vertex buffer binding command.

  • vertexDynamicStride sets if the vertex buffer stride is provided by the binding command rather than the current bound graphics pipeline state.

  • pushconstantPipelineLayout is the VkPipelineLayout used for the push constant command.

  • pushconstantShaderStageFlags are the shader stage flags used for the push constant command.

  • pushconstantOffset is the offset used for the push constant command.

  • pushconstantSize is the size used for the push constant command.

  • indirectStateFlags is a VkIndirectStateFlagsNV bitfield indicating the active states for the state flag command.

  • indexTypeCount is the optional size of the pIndexTypes and pIndexTypeValues array pairings. If not zero, it allows to register a custom uint32_t value to be treated as specific VkIndexType.

  • pIndexTypes is the used VkIndexType for the corresponding uint32_t value entry in pIndexTypeValues.

Valid Usage

  • VUID-VkIndirectCommandsLayoutTokenNV-stream-02951
    stream must be smaller than VkIndirectCommandsLayoutCreateInfoNV::streamCount

  • VUID-VkIndirectCommandsLayoutTokenNV-offset-02952
    offset must be less than or equal to VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::maxIndirectCommandsTokenOffset

  • VUID-VkIndirectCommandsLayoutTokenNV-offset-06888
    offset must be aligned to the scalar alignment of tokenType or minIndirectCommandsBufferOffsetAlignment, whichever is lower

  • VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02976
    If tokenType is VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_NV, vertexBindingUnit must stay within device supported limits for the appropriate commands

  • VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02977
    If tokenType is VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, pushconstantPipelineLayout must be valid

  • VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02978
    If tokenType is VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, pushconstantOffset must be a multiple of 4

  • VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02979
    If tokenType is VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, pushconstantSize must be a multiple of 4

  • VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02980
    If tokenType is VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, pushconstantOffset must be less than VkPhysicalDeviceLimits::maxPushConstantsSize

  • VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02981
    If tokenType is VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, pushconstantSize must be less than or equal to VkPhysicalDeviceLimits::maxPushConstantsSize minus pushconstantOffset

  • VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02982
    If tokenType is VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, for each byte in the range specified by pushconstantOffset and pushconstantSize and for each shader stage in pushconstantShaderStageFlags, there must be a push constant range in pushconstantPipelineLayout that includes that byte and that stage

  • VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02983
    If tokenType is VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, for each byte in the range specified by pushconstantOffset and pushconstantSize and for each push constant range that overlaps that byte, pushconstantShaderStageFlags must include all stages in that push constant range’s VkPushConstantRange::stageFlags

  • VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02984
    If tokenType is VK_INDIRECT_COMMANDS_TOKEN_TYPE_STATE_FLAGS_NV, indirectStateFlags must not be 0

Valid Usage (Implicit)

  • VUID-VkIndirectCommandsLayoutTokenNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_INDIRECT_COMMANDS_LAYOUT_TOKEN_NV

  • VUID-VkIndirectCommandsLayoutTokenNV-pNext-pNext
    pNext must be NULL

  • VUID-VkIndirectCommandsLayoutTokenNV-tokenType-parameter
    tokenType must be a valid VkIndirectCommandsTokenTypeNV value

  • VUID-VkIndirectCommandsLayoutTokenNV-pushconstantPipelineLayout-parameter
    If pushconstantPipelineLayout is not VK_NULL_HANDLE, pushconstantPipelineLayout must be a valid VkPipelineLayout handle

  • VUID-VkIndirectCommandsLayoutTokenNV-pushconstantShaderStageFlags-parameter
    pushconstantShaderStageFlags must be a valid combination of VkShaderStageFlagBits values

  • VUID-VkIndirectCommandsLayoutTokenNV-indirectStateFlags-parameter
    indirectStateFlags must be a valid combination of VkIndirectStateFlagBitsNV values

  • VUID-VkIndirectCommandsLayoutTokenNV-pIndexTypes-parameter
    If indexTypeCount is not 0, pIndexTypes must be a valid pointer to an array of indexTypeCount valid VkIndexType values

  • VUID-VkIndirectCommandsLayoutTokenNV-pIndexTypeValues-parameter
    If indexTypeCount is not 0, pIndexTypeValues must be a valid pointer to an array of indexTypeCount uint32_t values

The following code provides detailed information on how an individual sequence is processed. For valid usage, all restrictions from the regular commands apply.

void cmdProcessSequence(cmd, pipeline, indirectCommandsLayout, pIndirectCommandsStreams, s)
{
  for (uint32_t t = 0; t < indirectCommandsLayout.tokenCount; t++){
    token = indirectCommandsLayout.pTokens[t];

    uint32_t stride   = indirectCommandsLayout.pStreamStrides[token.stream];
    stream            = pIndirectCommandsStreams[token.stream];
    uint32_t offset   = stream.offset + stride * s + token.offset;
    const void* input = stream.buffer.pointer( offset )

    switch(input.type){
    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_SHADER_GROUP_NV:
      VkBindShaderGroupIndirectCommandNV* bind = input;

      vkCmdBindPipelineShaderGroupNV(cmd, indirectCommandsLayout.pipelineBindPoint,
        pipeline, bind->groupIndex);
    break;

    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_STATE_FLAGS_NV:
      VkSetStateFlagsIndirectCommandNV* state = input;

      if (token.indirectStateFlags & VK_INDIRECT_STATE_FLAG_FRONTFACE_BIT_NV){
        if (state.data & (1 << 0)){
          set VK_FRONT_FACE_CLOCKWISE;
        } else {
          set VK_FRONT_FACE_COUNTER_CLOCKWISE;
        }
      }
    break;

    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV:
      uint32_t* data = input;

      vkCmdPushConstants(cmd,
        token.pushconstantPipelineLayout
        token.pushconstantStageFlags,
        token.pushconstantOffset,
        token.pushconstantSize, data);
    break;

    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_NV:
      VkBindIndexBufferIndirectCommandNV* data = input;

      // the indexType may optionally be remapped
      // from a custom uint32_t value, via
      // VkIndirectCommandsLayoutTokenNV::pIndexTypeValues

      vkCmdBindIndexBuffer(cmd,
        deriveBuffer(data->bufferAddress),
        deriveOffset(data->bufferAddress),
        data->indexType);
    break;

    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_NV:
      VkBindVertexBufferIndirectCommandNV* data = input;

      // if token.vertexDynamicStride is VK_TRUE
      // then the stride for this binding is set
      // using data->stride as well

      vkCmdBindVertexBuffers(cmd,
        token.vertexBindingUnit, 1,
        &deriveBuffer(data->bufferAddress),
        &deriveOffset(data->bufferAddress));
    break;

    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_NV:
      vkCmdDrawIndexedIndirect(cmd,
        stream.buffer, offset, 1, 0);
    break;

    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_NV:
      vkCmdDrawIndirect(cmd,
        stream.buffer,
        offset, 1, 0);
    break;

    // only available if VK_NV_mesh_shader is supported
    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_TASKS_NV:
      vkCmdDrawMeshTasksIndirectNV(cmd,
        stream.buffer, offset, 1, 0);
    break;

    // only available if VK_EXT_mesh_shader is supported
    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV:
      vkCmdDrawMeshTasksIndirectEXT(cmd,
        stream.buffer, offset, 1, 0);
    break;

    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV:
      VkBindPipelineIndirectCommandNV *data = input;
      VkPipeline computePipeline = deriveFromDeviceAddress(data->pipelineAddress);
      vkCmdBindPipeline(cmd, VK_PIPELINE_BIND_POINT_COMPUTE, computePipeline);
    break;

    case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_NV:
      vkCmdDispatchIndirect(cmd, stream.buffer, offset);
    break;
    }
  }
}

Indirect Commands Generation and Execution

The generation of commands on the device requires a preprocess buffer.

With VK_EXT_device_generated_commands, to retrieve the memory size and alignment requirements of a particular execution state call:

// Provided by VK_EXT_device_generated_commands
void vkGetGeneratedCommandsMemoryRequirementsEXT(
    VkDevice                                    device,
    const VkGeneratedCommandsMemoryRequirementsInfoEXT* pInfo,
    VkMemoryRequirements2*                      pMemoryRequirements);

  • device is the logical device that owns the buffer.

  • pInfo is a pointer to a VkGeneratedCommandsMemoryRequirementsInfoEXT structure containing parameters required for the memory requirements query.

  • pMemoryRequirements is a pointer to a VkMemoryRequirements2 structure in which the memory requirements of the buffer object are returned.

If the size returned is zero, the preprocessing step can be skipped for this layout.

Valid Usage (Implicit)

  • VUID-vkGetGeneratedCommandsMemoryRequirementsEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetGeneratedCommandsMemoryRequirementsEXT-pInfo-parameter
    pInfo must be a valid pointer to a valid VkGeneratedCommandsMemoryRequirementsInfoEXT structure

  • VUID-vkGetGeneratedCommandsMemoryRequirementsEXT-pMemoryRequirements-parameter
    pMemoryRequirements must be a valid pointer to a VkMemoryRequirements2 structure

// Provided by VK_EXT_device_generated_commands
typedef struct VkGeneratedCommandsMemoryRequirementsInfoEXT {
    VkStructureType                sType;
    const void*                    pNext;
    VkIndirectExecutionSetEXT      indirectExecutionSet;
    VkIndirectCommandsLayoutEXT    indirectCommandsLayout;
    uint32_t                       maxSequenceCount;
    uint32_t                       maxDrawCount;
} VkGeneratedCommandsMemoryRequirementsInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • indirectExecutionSet is the indirect execution set to be used for binding shaders.

  • indirectCommandsLayout is the VkIndirectCommandsLayoutEXT that this buffer memory is intended to be used with.

  • maxSequenceCount is the maximum number of sequences that this buffer memory can be used with.

  • maxDrawCount is the maximum number of indirect draws that can be executed by any COUNT-type multi-draw indirect tokens. The draw count in the indirect buffer is clamped to this value for these token types.

If the action command token for the layout is not a COUNT-type multi-draw indirect token, maxDrawCount is ignored.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkGeneratedCommandsMemoryRequirementsInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_GENERATED_COMMANDS_MEMORY_REQUIREMENTS_INFO_EXT

  • VUID-VkGeneratedCommandsMemoryRequirementsInfoEXT-pNext-pNext
    Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkGeneratedCommandsPipelineInfoEXT or VkGeneratedCommandsShaderInfoEXT

  • VUID-VkGeneratedCommandsMemoryRequirementsInfoEXT-sType-unique
    The sType value of each structure in the pNext chain must be unique

  • VUID-VkGeneratedCommandsMemoryRequirementsInfoEXT-indirectExecutionSet-parameter
    If indirectExecutionSet is not VK_NULL_HANDLE, indirectExecutionSet must be a valid VkIndirectExecutionSetEXT handle

  • VUID-VkGeneratedCommandsMemoryRequirementsInfoEXT-indirectCommandsLayout-parameter
    indirectCommandsLayout must be a valid VkIndirectCommandsLayoutEXT handle

  • VUID-VkGeneratedCommandsMemoryRequirementsInfoEXT-commonparent
    Both of indirectCommandsLayout, and indirectExecutionSet that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

// Provided by VK_EXT_device_generated_commands
typedef struct VkGeneratedCommandsPipelineInfoEXT {
    VkStructureType    sType;
    void*              pNext;
    VkPipeline         pipeline;
} VkGeneratedCommandsPipelineInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pipeline is a valid pipeline object.

Valid Usage (Implicit)
// Provided by VK_EXT_device_generated_commands
typedef struct VkGeneratedCommandsShaderInfoEXT {
    VkStructureType       sType;
    void*                 pNext;
    uint32_t              shaderCount;
    const VkShaderEXT*    pShaders;
} VkGeneratedCommandsShaderInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • shaderCount is the size of the pShaders array.

  • pShaders is a pointer to an array of shader objects.

Valid Usage

  • VUID-VkGeneratedCommandsShaderInfoEXT-pShaders-11127
    pShaders must not contain more than one shader object for a given VkShaderStageFlagBits stage

Valid Usage (Implicit)

  • VUID-VkGeneratedCommandsShaderInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_GENERATED_COMMANDS_SHADER_INFO_EXT

  • VUID-VkGeneratedCommandsShaderInfoEXT-pShaders-parameter
    pShaders must be a valid pointer to an array of shaderCount valid VkShaderEXT handles

  • VUID-VkGeneratedCommandsShaderInfoEXT-shaderCount-arraylength
    shaderCount must be greater than 0

With VK_NV_device_generated_commands, to retrieve the memory size and alignment requirements of a particular execution state call:

// Provided by VK_NV_device_generated_commands
void vkGetGeneratedCommandsMemoryRequirementsNV(
    VkDevice                                    device,
    const VkGeneratedCommandsMemoryRequirementsInfoNV* pInfo,
    VkMemoryRequirements2*                      pMemoryRequirements);

  • device is the logical device that owns the buffer.

  • pInfo is a pointer to a VkGeneratedCommandsMemoryRequirementsInfoNV structure containing parameters required for the memory requirements query.

  • pMemoryRequirements is a pointer to a VkMemoryRequirements2 structure in which the memory requirements of the buffer object are returned.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkGetGeneratedCommandsMemoryRequirementsNV-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetGeneratedCommandsMemoryRequirementsNV-pInfo-parameter
    pInfo must be a valid pointer to a valid VkGeneratedCommandsMemoryRequirementsInfoNV structure

  • VUID-vkGetGeneratedCommandsMemoryRequirementsNV-pMemoryRequirements-parameter
    pMemoryRequirements must be a valid pointer to a VkMemoryRequirements2 structure

// Provided by VK_NV_device_generated_commands
typedef struct VkGeneratedCommandsMemoryRequirementsInfoNV {
    VkStructureType               sType;
    const void*                   pNext;
    VkPipelineBindPoint           pipelineBindPoint;
    VkPipeline                    pipeline;
    VkIndirectCommandsLayoutNV    indirectCommandsLayout;
    uint32_t                      maxSequencesCount;
} VkGeneratedCommandsMemoryRequirementsInfoNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pipelineBindPoint is the VkPipelineBindPoint of the pipeline that this buffer memory is intended to be used with during the execution.

  • pipeline is the VkPipeline that this buffer memory is intended to be used with during the execution.

  • indirectCommandsLayout is the VkIndirectCommandsLayoutNV that this buffer memory is intended to be used with.

  • maxSequencesCount is the maximum number of sequences that this buffer memory in combination with the other state provided can be used with.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkGeneratedCommandsMemoryRequirementsInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_GENERATED_COMMANDS_MEMORY_REQUIREMENTS_INFO_NV

  • VUID-VkGeneratedCommandsMemoryRequirementsInfoNV-pNext-pNext
    pNext must be NULL

  • VUID-VkGeneratedCommandsMemoryRequirementsInfoNV-pipelineBindPoint-parameter
    pipelineBindPoint must be a valid VkPipelineBindPoint value

  • VUID-VkGeneratedCommandsMemoryRequirementsInfoNV-pipeline-parameter
    If pipeline is not VK_NULL_HANDLE, pipeline must be a valid VkPipeline handle

  • VUID-VkGeneratedCommandsMemoryRequirementsInfoNV-indirectCommandsLayout-parameter
    indirectCommandsLayout must be a valid VkIndirectCommandsLayoutNV handle

  • VUID-VkGeneratedCommandsMemoryRequirementsInfoNV-commonparent
    Both of indirectCommandsLayout, and pipeline that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

With VK_NV_device_generated_commands, to bind a compute pipeline in Device-Generated Commands, an application must query the pipeline’s device address.

To query a compute pipeline’s 64-bit device address, call:

// Provided by VK_NV_device_generated_commands_compute
VkDeviceAddress vkGetPipelineIndirectDeviceAddressNV(
    VkDevice                                    device,
    const VkPipelineIndirectDeviceAddressInfoNV* pInfo);

  • device is the logical device on which the pipeline was created.

  • pInfo is a pointer to a VkPipelineIndirectDeviceAddressInfoNV structure specifying the pipeline to retrieve the address for.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkGetPipelineIndirectDeviceAddressNV-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetPipelineIndirectDeviceAddressNV-pInfo-parameter
    pInfo must be a valid pointer to a valid VkPipelineIndirectDeviceAddressInfoNV structure

The VkPipelineIndirectDeviceAddressInfoNV structure is defined as:

// Provided by VK_NV_device_generated_commands_compute
typedef struct VkPipelineIndirectDeviceAddressInfoNV {
    VkStructureType        sType;
    const void*            pNext;
    VkPipelineBindPoint    pipelineBindPoint;
    VkPipeline             pipeline;
} VkPipelineIndirectDeviceAddressInfoNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pipelineBindPoint is a VkPipelineBindPoint value specifying the type of pipeline whose device address is being queried.

  • pipeline specifies the pipeline whose device address is being queried.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkPipelineIndirectDeviceAddressInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_INDIRECT_DEVICE_ADDRESS_INFO_NV

  • VUID-VkPipelineIndirectDeviceAddressInfoNV-pNext-pNext
    pNext must be NULL

  • VUID-VkPipelineIndirectDeviceAddressInfoNV-pipelineBindPoint-parameter
    pipelineBindPoint must be a valid VkPipelineBindPoint value

  • VUID-VkPipelineIndirectDeviceAddressInfoNV-pipeline-parameter
    pipeline must be a valid VkPipeline handle

To determine the memory requirements for a compute pipeline’s metadata, call:

// Provided by VK_NV_device_generated_commands_compute
void vkGetPipelineIndirectMemoryRequirementsNV(
    VkDevice                                    device,
    const VkComputePipelineCreateInfo*          pCreateInfo,
    VkMemoryRequirements2*                      pMemoryRequirements);

  • device is the logical device that owns the buffer.

  • pCreateInfo is a VkComputePipelineCreateInfo structure specifying the creation parameters of the compute pipeline whose memory requirements are being queried.

  • pMemoryRequirements is a pointer to a VkMemoryRequirements2 structure in which the requested pipeline’s memory requirements are returned.

If pCreateInfo->pNext chain includes a pointer to a VkComputePipelineIndirectBufferInfoNV structure, then the contents of that structure are ignored.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkGetPipelineIndirectMemoryRequirementsNV-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetPipelineIndirectMemoryRequirementsNV-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkComputePipelineCreateInfo structure

  • VUID-vkGetPipelineIndirectMemoryRequirementsNV-pMemoryRequirements-parameter
    pMemoryRequirements must be a valid pointer to a VkMemoryRequirements2 structure

Indirect Execution Sets

Indirect Execution Sets contain sets of pipelines or shader objects which can be bound individually.

// Provided by VK_EXT_device_generated_commands
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkIndirectExecutionSetEXT)

Indirect Execution Sets allow the device to bind different shaders and pipeline states using Device-Generated Commands.

Indirect Execution Sets are created by calling:

// Provided by VK_EXT_device_generated_commands
VkResult vkCreateIndirectExecutionSetEXT(
    VkDevice                                    device,
    const VkIndirectExecutionSetCreateInfoEXT*  pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkIndirectExecutionSetEXT*                  pIndirectExecutionSet);

  • device is the logical device that creates the indirect execution set.

  • pCreateInfo is a pointer to a VkIndirectExecutionSetCreateInfoEXT structure containing parameters affecting creation of the indirect execution set.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pIndirectExecutionSet is a pointer to a VkIndirectExecutionSetEXT handle in which the resulting indirect execution set is returned.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkCreateIndirectExecutionSetEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateIndirectExecutionSetEXT-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkIndirectExecutionSetCreateInfoEXT structure

  • VUID-vkCreateIndirectExecutionSetEXT-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateIndirectExecutionSetEXT-pIndirectExecutionSet-parameter
    pIndirectExecutionSet must be a valid pointer to a VkIndirectExecutionSetEXT handle

  • VUID-vkCreateIndirectExecutionSetEXT-device-queuecount
    The device must have been created with at least 1 queue

Return Codes
Success
Failure

The VkIndirectExecutionSetCreateInfoEXT structure is defined as:

// Provided by VK_EXT_device_generated_commands
typedef struct VkIndirectExecutionSetCreateInfoEXT {
    VkStructureType                      sType;
    const void*                          pNext;
    VkIndirectExecutionSetInfoTypeEXT    type;
    VkIndirectExecutionSetInfoEXT        info;
} VkIndirectExecutionSetCreateInfoEXT;
Valid Usage
Valid Usage (Implicit)

Values which can be set in VkIndirectExecutionSetCreateInfoEXT::type, specifying contents of an indirect execution set, are:

// Provided by VK_EXT_device_generated_commands
typedef enum VkIndirectExecutionSetInfoTypeEXT {
    VK_INDIRECT_EXECUTION_SET_INFO_TYPE_PIPELINES_EXT = 0,
    VK_INDIRECT_EXECUTION_SET_INFO_TYPE_SHADER_OBJECTS_EXT = 1,
} VkIndirectExecutionSetInfoTypeEXT;

The VkIndirectExecutionSetInfoEXT union is defined as:

// Provided by VK_EXT_device_generated_commands
typedef union VkIndirectExecutionSetInfoEXT {
    const VkIndirectExecutionSetPipelineInfoEXT*    pPipelineInfo;
    const VkIndirectExecutionSetShaderInfoEXT*      pShaderInfo;
} VkIndirectExecutionSetInfoEXT;

The VkIndirectExecutionSetPipelineInfoEXT structure is defined as:

// Provided by VK_EXT_device_generated_commands
typedef struct VkIndirectExecutionSetPipelineInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    VkPipeline         initialPipeline;
    uint32_t           maxPipelineCount;
} VkIndirectExecutionSetPipelineInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • initialPipeline is the initial pipeline for the set. This pipeline will be automatically added to the set at index 0.

  • maxPipelineCount is the maximum number of pipelines stored in the set.

The characteristics of initialPipeline will be used to validate all pipelines added to the set even if they are removed from the set or destroyed.

When an Indirect Execution Set created with pipelines is used, initialPipeline constitutes the initial shader state.

Valid Usage
Valid Usage (Implicit)

The VkIndirectExecutionSetShaderInfoEXT structure is defined as:

// Provided by VK_EXT_device_generated_commands
typedef struct VkIndirectExecutionSetShaderInfoEXT {
    VkStructureType                                     sType;
    const void*                                         pNext;
    uint32_t                                            shaderCount;
    const VkShaderEXT*                                  pInitialShaders;
    const VkIndirectExecutionSetShaderLayoutInfoEXT*    pSetLayoutInfos;
    uint32_t                                            maxShaderCount;
    uint32_t                                            pushConstantRangeCount;
    const VkPushConstantRange*                          pPushConstantRanges;
} VkIndirectExecutionSetShaderInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • shaderCount is the number of members in the pInitialShaders and pSetLayoutInfos arrays.

  • pInitialShaders is a pointer to an array containing a VkShaderEXT object for each shader stage that will be used in the set. These shaders will be automatically added to the set beginning at index 0.

  • pSetLayoutInfos is NULL or a pointer to an array containing a VkIndirectExecutionSetShaderLayoutInfoEXT used by each corresponding pInitialShaders shader stage in the set.

  • maxShaderCount is the maximum number of shader objects stored in the set.

  • pushConstantRangeCount is the number of members in the pPushConstantRanges array.

  • pPushConstantRanges is a pointer to the array of VkPushConstantRange ranges used by all shaders in the set.

The characteristics of pInitialShaders will be used to validate all shaders added to the set even if they are removed from the set or destroyed.

When an Indirect Execution Set created with shader objects is used, pInitialShaders constitutes the initial shader state.

If pSetLayoutInfos is NULL, the descriptor layout parameters are inherited from the shader object.

Valid Usage

  • VUID-VkIndirectExecutionSetShaderInfoEXT-pInitialShaders-11020
    All members of pInitialShaders must have a stage supported by VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT::supportedIndirectCommandsShaderStagesShaderBinding

  • VUID-VkIndirectExecutionSetShaderInfoEXT-maxShaderCount-11021
    maxShaderCount must not be zero

  • VUID-VkIndirectExecutionSetShaderInfoEXT-maxShaderCount-11022
    maxShaderCount must be less than or equal to VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT::maxIndirectShaderObjectCount

  • VUID-VkIndirectExecutionSetShaderInfoEXT-maxShaderCount-11036
    maxShaderCount must be greater than or equal to shaderCount

  • VUID-VkIndirectExecutionSetShaderInfoEXT-stage-11023
    The stage of each element in the pInitialShaders array must be unique

  • VUID-VkIndirectExecutionSetShaderInfoEXT-pInitialShaders-11154
    Each member of pInitialShaders must have been created with VK_SHADER_CREATE_INDIRECT_BINDABLE_BIT_EXT

  • VUID-VkIndirectExecutionSetShaderInfoEXT-pSetLayoutInfos-10929
    If pSetLayoutInfos is not NULL, the descriptor layout values specified must be compatible with the descriptor set layouts defined at the creation of the shader object

Valid Usage (Implicit)

  • VUID-VkIndirectExecutionSetShaderInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_INDIRECT_EXECUTION_SET_SHADER_INFO_EXT

  • VUID-VkIndirectExecutionSetShaderInfoEXT-pInitialShaders-parameter
    pInitialShaders must be a valid pointer to an array of shaderCount valid VkShaderEXT handles

  • VUID-VkIndirectExecutionSetShaderInfoEXT-pSetLayoutInfos-parameter
    If pSetLayoutInfos is not NULL, pSetLayoutInfos must be a valid pointer to an array of shaderCount valid VkIndirectExecutionSetShaderLayoutInfoEXT structures

  • VUID-VkIndirectExecutionSetShaderInfoEXT-pPushConstantRanges-parameter
    If pushConstantRangeCount is not 0, pPushConstantRanges must be a valid pointer to an array of pushConstantRangeCount valid VkPushConstantRange structures

  • VUID-VkIndirectExecutionSetShaderInfoEXT-shaderCount-arraylength
    shaderCount must be greater than 0

The VkIndirectExecutionSetShaderLayoutInfoEXT structure is defined as:

// Provided by VK_EXT_device_generated_commands
typedef struct VkIndirectExecutionSetShaderLayoutInfoEXT {
    VkStructureType                 sType;
    const void*                     pNext;
    uint32_t                        setLayoutCount;
    const VkDescriptorSetLayout*    pSetLayouts;
} VkIndirectExecutionSetShaderLayoutInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • setLayoutCount is the number of members in the pSetLayouts array

  • pSetLayouts is a pointer to an array containing VkDescriptorSetLayout objects used by the shader stage. The implementation must not access these objects outside of the duration of the command this structure is passed to.

Valid Usage
Valid Usage (Implicit)

Destroy an Indirect Execution Set by calling:

// Provided by VK_EXT_device_generated_commands
void vkDestroyIndirectExecutionSetEXT(
    VkDevice                                    device,
    VkIndirectExecutionSetEXT                   indirectExecutionSet,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that owns the indirect execution set.

  • indirectExecutionSet is the indirect execution set to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • VUID-vkDestroyIndirectExecutionSetEXT-indirectExecutionSet-11025
    All submitted commands that refer to indirectExecutionSet must have completed execution

Valid Usage (Implicit)

  • VUID-vkDestroyIndirectExecutionSetEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyIndirectExecutionSetEXT-indirectExecutionSet-parameter
    If indirectExecutionSet is not VK_NULL_HANDLE, indirectExecutionSet must be a valid VkIndirectExecutionSetEXT handle

  • VUID-vkDestroyIndirectExecutionSetEXT-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyIndirectExecutionSetEXT-indirectExecutionSet-parent
    If indirectExecutionSet is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to indirectExecutionSet must be externally synchronized

The VkWriteIndirectExecutionSetPipelineEXT structure is defined as:

// Provided by VK_EXT_device_generated_commands
typedef struct VkWriteIndirectExecutionSetPipelineEXT {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           index;
    VkPipeline         pipeline;
} VkWriteIndirectExecutionSetPipelineEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • index is the element of the set to update

  • pipeline is the pipeline to store in the indirect execution set

Valid Usage

  • VUID-VkWriteIndirectExecutionSetPipelineEXT-index-11026
    index must be less than the value of VkIndirectExecutionSetPipelineInfoEXT::maxPipelineCount used to create the set

  • VUID-VkWriteIndirectExecutionSetPipelineEXT-pipeline-11027
    pipeline must have been created with VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXT

  • VUID-VkWriteIndirectExecutionSetPipelineEXT-index-11029
    index must not be referenced by submitted command buffers

  • VUID-VkWriteIndirectExecutionSetPipelineEXT-pipeline-11030
    The shader stages contained in pipeline must be supported by VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT::supportedIndirectCommandsShaderStagesPipelineBinding

Valid Usage (Implicit)

The VkWriteIndirectExecutionSetShaderEXT structure is defined as:

// Provided by VK_EXT_device_generated_commands with VK_EXT_shader_object
typedef struct VkWriteIndirectExecutionSetShaderEXT {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           index;
    VkShaderEXT        shader;
} VkWriteIndirectExecutionSetShaderEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • index is the element of the set to update

  • shader is the shader to store in the indirect execution set

Shaders need not be stored in the Indirect Execution Set according to their stage. The only restriction for shader indices within a set is that the value of the index must be less than the maximum number of shaders in the set.

Valid Usage

  • VUID-VkWriteIndirectExecutionSetShaderEXT-index-11031
    index must be less than VkIndirectExecutionSetShaderInfoEXT::maxShaderCount

  • VUID-VkWriteIndirectExecutionSetShaderEXT-shader-11032
    shader must have been created with VK_SHADER_CREATE_INDIRECT_BINDABLE_BIT_EXT

  • VUID-VkWriteIndirectExecutionSetShaderEXT-pInitialShaders-11033
    A shader created with the same VkShaderStageFlagBits must have been passed in the VkIndirectExecutionSetShaderInfoEXT::pInitialShaders array

  • VUID-VkWriteIndirectExecutionSetShaderEXT-index-11034
    index must not be in use by submitted command buffers

Valid Usage (Implicit)

Pipeline elements in an Indirect Execution Set can be updated by calling:

// Provided by VK_EXT_device_generated_commands
void vkUpdateIndirectExecutionSetPipelineEXT(
    VkDevice                                    device,
    VkIndirectExecutionSetEXT                   indirectExecutionSet,
    uint32_t                                    executionSetWriteCount,
    const VkWriteIndirectExecutionSetPipelineEXT* pExecutionSetWrites);

  • device is the logical device that owns the indirect execution set.

  • indirectExecutionSet is the indirect execution set being updated.

  • executionSetWriteCount is the number of elements in the pExecutionSetWrites array.

  • pExecutionSetWrites is a pointer to an array of VkWriteIndirectExecutionSetPipelineEXT structures describing the elements to update.

Valid Usage

  • VUID-vkUpdateIndirectExecutionSetPipelineEXT-indirectExecutionSet-11035
    indirectExecutionSet must have been created with type VK_INDIRECT_EXECUTION_SET_INFO_TYPE_PIPELINES_EXT

  • VUID-vkUpdateIndirectExecutionSetPipelineEXT-executionSetWriteCount-11037
    executionSetWriteCount must be less than or equal to VkIndirectExecutionSetPipelineInfoEXT::maxPipelineCount

  • VUID-vkUpdateIndirectExecutionSetPipelineEXT-pExecutionSetWrites-11042
    Each element in the pExecutionSetWrites array must have a unique VkWriteIndirectExecutionSetPipelineEXT::index

  • VUID-vkUpdateIndirectExecutionSetPipelineEXT-None-11038
    Each member of the Indirect Execution Set referenced by the update command must not be in use by the device

  • VUID-vkUpdateIndirectExecutionSetPipelineEXT-None-11039
    The layout of each pipeline in pExecutionSetWrites must be compatible with the initialPipeline used to create the Indirect Execution Set

  • VUID-vkUpdateIndirectExecutionSetPipelineEXT-None-11040
    Each pipeline in the Indirect Execution Set must have identically defined static and dynamic state values to the initialPipeline used to create the Indirect Execution Set

  • VUID-vkUpdateIndirectExecutionSetPipelineEXT-initialPipeline-11147
    Each pipeline in the Indirect Execution Set must have identically defined fragment outputs interface to the initialPipeline used to create the Indirect Execution Set

  • VUID-vkUpdateIndirectExecutionSetPipelineEXT-initialPipeline-11152
    Each pipeline in the Indirect Execution Set must match the initialPipeline used to create the Indirect Execution Set in its included shader stages

  • VUID-vkUpdateIndirectExecutionSetPipelineEXT-initialPipeline-11098
    Each pipeline in the Indirect Execution Set must match the initialPipeline used to create the Indirect Execution Set in its use of FragDepth

  • VUID-vkUpdateIndirectExecutionSetPipelineEXT-initialPipeline-11086
    Each pipeline in the Indirect Execution Set must match the initialPipeline used to create the Indirect Execution Set in its use of SampleMask

  • VUID-vkUpdateIndirectExecutionSetPipelineEXT-initialPipeline-11085
    Each pipeline in the Indirect Execution Set must match the initialPipeline used to create the Indirect Execution Set in its use of StencilExportEXT

Valid Usage (Implicit)

  • VUID-vkUpdateIndirectExecutionSetPipelineEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkUpdateIndirectExecutionSetPipelineEXT-indirectExecutionSet-parameter
    indirectExecutionSet must be a valid VkIndirectExecutionSetEXT handle

  • VUID-vkUpdateIndirectExecutionSetPipelineEXT-pExecutionSetWrites-parameter
    pExecutionSetWrites must be a valid pointer to an array of executionSetWriteCount valid VkWriteIndirectExecutionSetPipelineEXT structures

  • VUID-vkUpdateIndirectExecutionSetPipelineEXT-executionSetWriteCount-arraylength
    executionSetWriteCount must be greater than 0

  • VUID-vkUpdateIndirectExecutionSetPipelineEXT-indirectExecutionSet-parent
    indirectExecutionSet must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to indirectExecutionSet must be externally synchronized

Shader object elements in an Indirect Execution Set can be updated by calling:

// Provided by VK_EXT_device_generated_commands
void vkUpdateIndirectExecutionSetShaderEXT(
    VkDevice                                    device,
    VkIndirectExecutionSetEXT                   indirectExecutionSet,
    uint32_t                                    executionSetWriteCount,
    const VkWriteIndirectExecutionSetShaderEXT* pExecutionSetWrites);

  • device is the logical device that owns the indirect execution set.

  • indirectExecutionSet is the indirect execution set being updated.

  • executionSetWriteCount is the number of elements in the pExecutionSetWrites array.

  • pExecutionSetWrites is a pointer to an array of VkWriteIndirectExecutionSetShaderEXT structures describing the elements to update.

Valid Usage

  • VUID-vkUpdateIndirectExecutionSetShaderEXT-indirectExecutionSet-11041
    indirectExecutionSet must have been created with type VK_INDIRECT_EXECUTION_SET_INFO_TYPE_SHADER_OBJECTS_EXT

  • VUID-vkUpdateIndirectExecutionSetShaderEXT-pExecutionSetWrites-11043
    Each element in the pExecutionSetWrites array must have a unique VkWriteIndirectExecutionSetShaderEXT::index

  • VUID-vkUpdateIndirectExecutionSetShaderEXT-None-11044
    Each member of the Indirect Execution Set referenced by the update command must not be in use by the device

  • VUID-vkUpdateIndirectExecutionSetShaderEXT-pExecutionSetWrites-11140
    The descriptor layout of each shader in pExecutionSetWrites must be compatible with the initial layout info used to create the Indirect Execution Set

  • VUID-vkUpdateIndirectExecutionSetShaderEXT-None-11148
    Each fragment shader element in the Indirect Execution Set must have identically defined fragment outputs interface to the initial shader state used to create the Indirect Execution Set

  • VUID-vkUpdateIndirectExecutionSetShaderEXT-FragDepth-11054
    Each fragment shader element in the Indirect Execution Set must match the initial shader state used to create the Indirect Execution Set in its use of FragDepth

  • VUID-vkUpdateIndirectExecutionSetShaderEXT-SampleMask-11050
    Each fragment shader element in the Indirect Execution Set must match the initial shader state used to create the Indirect Execution Set in its use of SampleMask

  • VUID-vkUpdateIndirectExecutionSetShaderEXT-StencilExportEXT-11003
    Each fragment shader element in the Indirect Execution Set must match the initial shader state used to create the Indirect Execution Set in its use of StencilExportEXT

Valid Usage (Implicit)

  • VUID-vkUpdateIndirectExecutionSetShaderEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkUpdateIndirectExecutionSetShaderEXT-indirectExecutionSet-parameter
    indirectExecutionSet must be a valid VkIndirectExecutionSetEXT handle

  • VUID-vkUpdateIndirectExecutionSetShaderEXT-pExecutionSetWrites-parameter
    pExecutionSetWrites must be a valid pointer to an array of executionSetWriteCount valid VkWriteIndirectExecutionSetShaderEXT structures

  • VUID-vkUpdateIndirectExecutionSetShaderEXT-executionSetWriteCount-arraylength
    executionSetWriteCount must be greater than 0

  • VUID-vkUpdateIndirectExecutionSetShaderEXT-indirectExecutionSet-parent
    indirectExecutionSet must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to indirectExecutionSet must be externally synchronized

It is legal to update an Indirect Execution Set that is in flight as long as the element indices in pExecutionSetWrites are not in use. Any change to an indirect execution set requires recalculating memory requirements by calling vkGetGeneratedCommandsMemoryRequirementsEXT for commands that use that modified state. Commands that are in flight or those not using updated elements require no changes.

The lifetimes of pipelines and shader objects contained in a set must match or exceed the lifetime of the set.

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

// Provided by VK_NV_device_generated_commands
void vkCmdExecuteGeneratedCommandsNV(
    VkCommandBuffer                             commandBuffer,
    VkBool32                                    isPreprocessed,
    const VkGeneratedCommandsInfoNV*            pGeneratedCommandsInfo);

  • commandBuffer is the command buffer into which the command is recorded.

  • isPreprocessed represents whether the input data has already been preprocessed on the device. If it is VK_FALSE this command will implicitly trigger the preprocessing step, otherwise not.

  • pGeneratedCommandsInfo is a pointer to a VkGeneratedCommandsInfoNV structure containing parameters affecting the generation of commands.

If the VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_NV flag was used to create the VkGeneratedCommandsInfoNV::indirectCommandsLayout then the order of execution of individual draws through this command may execute in any order, and may not necessarily be in the same order as specified in VkGeneratedCommandsInfoNV::pStreams.

The order of execution of individual dispatches through this command may execute in any order and may not necessarily be in the same order as specified in VkGeneratedCommandsInfoNV::pStreams.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkCmdExecuteGeneratedCommandsNV-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdExecuteGeneratedCommandsNV-pGeneratedCommandsInfo-parameter
    pGeneratedCommandsInfo must be a valid pointer to a valid VkGeneratedCommandsInfoNV structure

  • VUID-vkCmdExecuteGeneratedCommandsNV-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdExecuteGeneratedCommandsNV-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support VK_QUEUE_COMPUTE_BIT, or VK_QUEUE_GRAPHICS_BIT operations

  • VUID-vkCmdExecuteGeneratedCommandsNV-renderpass
    This command must only be called inside of a render pass instance

  • VUID-vkCmdExecuteGeneratedCommandsNV-suspended
    This command must not be called between suspended render pass instances

  • VUID-vkCmdExecuteGeneratedCommandsNV-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Inside

Outside

VK_QUEUE_COMPUTE_BIT
VK_QUEUE_GRAPHICS_BIT

Action
Indirection
Conditional Rendering

vkCmdExecuteGeneratedCommandsNV is affected by conditional rendering

The VkGeneratedCommandsInfoNV is defined as:

// Provided by VK_NV_device_generated_commands
typedef struct VkGeneratedCommandsInfoNV {
    VkStructureType                      sType;
    const void*                          pNext;
    VkPipelineBindPoint                  pipelineBindPoint;
    VkPipeline                           pipeline;
    VkIndirectCommandsLayoutNV           indirectCommandsLayout;
    uint32_t                             streamCount;
    const VkIndirectCommandsStreamNV*    pStreams;
    uint32_t                             sequencesCount;
    VkBuffer                             preprocessBuffer;
    VkDeviceSize                         preprocessOffset;
    VkDeviceSize                         preprocessSize;
    VkBuffer                             sequencesCountBuffer;
    VkDeviceSize                         sequencesCountOffset;
    VkBuffer                             sequencesIndexBuffer;
    VkDeviceSize                         sequencesIndexOffset;
} VkGeneratedCommandsInfoNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pipelineBindPoint is the VkPipelineBindPoint used for the pipeline.

  • pipeline is the VkPipeline used in the generation and execution process.

  • indirectCommandsLayout is the VkIndirectCommandsLayoutNV that provides the command sequence to generate.

  • streamCount defines the number of input streams

  • pStreams is a pointer to an array of streamCount VkIndirectCommandsStreamNV structures providing the input data for the tokens used in indirectCommandsLayout.

  • sequencesCount is the maximum number of sequences to reserve. If sequencesCountBuffer is VK_NULL_HANDLE, this is also the actual number of sequences generated.

  • preprocessBuffer is the VkBuffer that is used for preprocessing the input data for execution. If this structure is used with vkCmdExecuteGeneratedCommandsNV with its isPreprocessed set to VK_TRUE, then the preprocessing step is skipped and data in this buffer will not be modified. The contents and the layout of this buffer are opaque to applications and must not be modified outside functions related to device-generated commands or copied to another buffer for reuse.

  • preprocessOffset is the byte offset into preprocessBuffer where the preprocessed data is stored.

  • preprocessSize is the maximum byte size within the preprocessBuffer after the preprocessOffset that is available for preprocessing.

  • sequencesCountBuffer is a VkBuffer in which the actual number of sequences is provided as single uint32_t value.

  • sequencesCountOffset is the byte offset into sequencesCountBuffer where the count value is stored.

  • sequencesIndexBuffer is a VkBuffer that encodes the used sequence indices as uint32_t array.

  • sequencesIndexOffset is the byte offset into sequencesIndexBuffer where the index values start.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkGeneratedCommandsInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_GENERATED_COMMANDS_INFO_NV

  • VUID-VkGeneratedCommandsInfoNV-pNext-pNext
    pNext must be NULL

  • VUID-VkGeneratedCommandsInfoNV-pipelineBindPoint-parameter
    pipelineBindPoint must be a valid VkPipelineBindPoint value

  • VUID-VkGeneratedCommandsInfoNV-pipeline-parameter
    If pipeline is not VK_NULL_HANDLE, pipeline must be a valid VkPipeline handle

  • VUID-VkGeneratedCommandsInfoNV-indirectCommandsLayout-parameter
    indirectCommandsLayout must be a valid VkIndirectCommandsLayoutNV handle

  • VUID-VkGeneratedCommandsInfoNV-pStreams-parameter
    pStreams must be a valid pointer to an array of streamCount valid VkIndirectCommandsStreamNV structures

  • VUID-VkGeneratedCommandsInfoNV-preprocessBuffer-parameter
    preprocessBuffer must be a valid VkBuffer handle

  • VUID-VkGeneratedCommandsInfoNV-sequencesCountBuffer-parameter
    If sequencesCountBuffer is not VK_NULL_HANDLE, sequencesCountBuffer must be a valid VkBuffer handle

  • VUID-VkGeneratedCommandsInfoNV-sequencesIndexBuffer-parameter
    If sequencesIndexBuffer is not VK_NULL_HANDLE, sequencesIndexBuffer must be a valid VkBuffer handle

  • VUID-VkGeneratedCommandsInfoNV-streamCount-arraylength
    streamCount must be greater than 0

  • VUID-VkGeneratedCommandsInfoNV-commonparent
    Each of indirectCommandsLayout, pipeline, preprocessBuffer, sequencesCountBuffer, and sequencesIndexBuffer that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

Referencing the functions defined in Indirect Commands Layout, vkCmdExecuteGeneratedCommandsNV behaves as:

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)

It is important to note that the values of all state related to the pipelineBindPoint used are undefined after this command.

Commands can be preprocessed prior execution using the following command:

// Provided by VK_NV_device_generated_commands
void vkCmdPreprocessGeneratedCommandsNV(
    VkCommandBuffer                             commandBuffer,
    const VkGeneratedCommandsInfoNV*            pGeneratedCommandsInfo);

  • commandBuffer is the command buffer which does the preprocessing.

  • pGeneratedCommandsInfo is a pointer to a VkGeneratedCommandsInfoNV structure containing parameters affecting the preprocessing step.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkCmdPreprocessGeneratedCommandsNV-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdPreprocessGeneratedCommandsNV-pGeneratedCommandsInfo-parameter
    pGeneratedCommandsInfo must be a valid pointer to a valid VkGeneratedCommandsInfoNV structure

  • VUID-vkCmdPreprocessGeneratedCommandsNV-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdPreprocessGeneratedCommandsNV-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support VK_QUEUE_COMPUTE_BIT, or VK_QUEUE_GRAPHICS_BIT operations

  • VUID-vkCmdPreprocessGeneratedCommandsNV-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdPreprocessGeneratedCommandsNV-suspended
    This command must not be called between suspended render pass instances

  • VUID-vkCmdPreprocessGeneratedCommandsNV-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

VK_QUEUE_COMPUTE_BIT
VK_QUEUE_GRAPHICS_BIT

Action
Conditional Rendering

vkCmdPreprocessGeneratedCommandsNV is not affected by conditional rendering

The bound descriptor sets and push constants that will be used with indirect command generation for the compute pipelines must already be specified at the time of preprocessing commands with vkCmdPreprocessGeneratedCommandsNV. They must not change until the execution of indirect commands is submitted with vkCmdExecuteGeneratedCommandsNV.

If push constants for the compute pipeline are also specified in the VkGeneratedCommandsInfoNV::indirectCommandsLayout with VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV token, then those values override the push constants that were previously pushed for the compute pipeline.

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

// Provided by VK_EXT_device_generated_commands
void vkCmdExecuteGeneratedCommandsEXT(
    VkCommandBuffer                             commandBuffer,
    VkBool32                                    isPreprocessed,
    const VkGeneratedCommandsInfoEXT*           pGeneratedCommandsInfo);

  • commandBuffer is the command buffer into which the command is recorded.

  • isPreprocessed represents whether the input data has already been preprocessed on the device. If it is VK_FALSE this command will implicitly trigger the preprocessing step, otherwise not.

  • pGeneratedCommandsInfo is a pointer to a VkGeneratedCommandsInfoEXT structure containing parameters affecting the generation of commands.

If the VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_EXT flag was used to create the VkGeneratedCommandsInfoEXT::indirectCommandsLayout then the execution of sequences through this command may use implementation-defined ordering which is not guaranteed to be coherent using the same input data. It does not affect the order of token processing within a sequence. This is the implied ordering with VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_EXT.

After a call to vkCmdExecuteGeneratedCommandsEXT, command buffer state will become undefined according to the tokens executed. This table specifies the relationship between tokens used and state invalidation.

Table 3. Indirect Execution State Invalidation
Common Tokens States Invalidated

VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT

Bound shaders and pipelines

VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT

Push constant data

VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT

Push constant data

VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXT

Index buffer

VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT

Vertex buffer
Valid Usage

  • VUID-vkCmdExecuteGeneratedCommandsEXT-commandBuffer-11045
    commandBuffer must not be a protected command buffer

  • VUID-vkCmdExecuteGeneratedCommandsEXT-isPreprocessed-11046
    If isPreprocessed is VK_TRUE and vkGetGeneratedCommandsMemoryRequirementsEXT did not return a required size of zero then vkCmdPreprocessGeneratedCommandsEXT must have already been executed on the device before this command executes, and the preprocessing command must have used the same pGeneratedCommandsInfo content as well as the content of the input buffers it references (all except VkGeneratedCommandsInfoEXT::preprocessAddress)

  • VUID-vkCmdExecuteGeneratedCommandsEXT-isPreprocessed-11047
    If isPreprocessed is VK_TRUE then the indirectCommandsLayout member of pGeneratedCommandsInfo must have been created with the VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_EXT bit set

  • VUID-vkCmdExecuteGeneratedCommandsEXT-indirectCommandsLayout-11141
    If the indirectCommandsLayout member of pGeneratedCommandsInfo was created with the VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_EXT bit set, then isPreprocessed must be VK_TRUE

  • VUID-vkCmdExecuteGeneratedCommandsEXT-preprocessAddress-11142
    The contents of the preprocessAddress member of pGeneratedCommandsInfo must not have been previously used to record another vkCmdExecuteGeneratedCommandsEXT

  • VUID-vkCmdExecuteGeneratedCommandsEXT-isPreprocessed-11048
    If isPreprocessed is VK_TRUE then the bound descriptor sets and push constants must match identically with those bound during recording of the corresponding call to vkCmdPreprocessGeneratedCommandsEXT

  • VUID-vkCmdExecuteGeneratedCommandsEXT-isPreprocessed-10198
    If isPreprocessed is VK_TRUE then the conditional render state and its predicate value must match identically with the state and value set during execution of the corresponding call to vkCmdPreprocessGeneratedCommandsEXT

  • VUID-vkCmdExecuteGeneratedCommandsEXT-isPreprocessed-11049
    If isPreprocessed is VK_TRUE and the indirectCommandsLayout member of pGeneratedCommandsInfo contains a draw token, then the graphics state bound on commandBuffer must match identically with the graphics state bound on the stateCommandBuffer passed to vkCmdPreprocessGeneratedCommandsEXT

  • VUID-vkCmdExecuteGeneratedCommandsEXT-isPreprocessed-11149
    If isPreprocessed is VK_TRUE, then the queue family index of commandBuffer must be the same as the queue family index used to allocate the stateCommandBuffer passed to vkCmdPreprocessGeneratedCommandsEXT

  • VUID-vkCmdExecuteGeneratedCommandsEXT-isPreprocessed-11051
    If isPreprocessed is VK_TRUE and the indirectCommandsLayout member of pGeneratedCommandsInfo contains a dispatch token, then the compute state bound on commandBuffer must match identically with the compute state bound on the stateCommandBuffer passed to vkCmdPreprocessGeneratedCommandsEXT

  • VUID-vkCmdExecuteGeneratedCommandsEXT-isPreprocessed-11052
    If isPreprocessed is VK_TRUE and the indirectCommandsLayout member of pGeneratedCommandsInfo contains a ray tracing token, then the ray tracing state bound on commandBuffer must match identically with the ray tracing state bound on the stateCommandBuffer passed to vkCmdPreprocessGeneratedCommandsEXT

  • VUID-vkCmdExecuteGeneratedCommandsEXT-isPreprocessed-11150
    If isPreprocessed is VK_TRUE and the indirectCommandsLayout member of pGeneratedCommandsInfo contains a ray tracing token, the queue family index commandBuffer was allocated from must be the same queue family index used to allocate the stateCommandBuffer passed to vkCmdPreprocessGeneratedCommandsEXT

  • VUID-vkCmdExecuteGeneratedCommandsEXT-indirectCommandsLayout-11053
    If the token sequence of the passed VkGeneratedCommandsInfoEXT::indirectCommandsLayout contains a VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT token, the initial shader state of VkGeneratedCommandsInfoEXT::indirectExecutionSet must be bound on commandBuffer

  • VUID-vkCmdExecuteGeneratedCommandsEXT-indirectCommandsLayout-11004
    If indirectCommandsLayout was created with a token sequence that contained the VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT token and indirectExecutionSet was created using VK_INDIRECT_EXECUTION_SET_INFO_TYPE_SHADER_OBJECTS_EXT, every executed VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT token must bind all the shader stages set in the VkIndirectCommandsExecutionSetTokenEXT::shaderStages used to create indirectCommandsLayout

  • VUID-vkCmdExecuteGeneratedCommandsEXT-isPreprocessed-11055
    If isPreprocessed is VK_TRUE and the token sequence of the passed VkGeneratedCommandsInfoEXT::indirectCommandsLayout contains a VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT token, the members of VkGeneratedCommandsInfoEXT::indirectExecutionSet accessed by this command must not have been modified since the preprocess buffer was generated

  • VUID-vkCmdExecuteGeneratedCommandsEXT-indirectCommandsLayout-11056
    If the indirectCommandsLayout member of pGeneratedCommandsInfo contains a draw token, then the active render pass must not have a specified fragment density map

  • VUID-vkCmdExecuteGeneratedCommandsEXT-deviceGeneratedCommandsTransformFeedback-11057
    If deviceGeneratedCommandsTransformFeedback is not supported on device, transform feedback must not be active

  • VUID-vkCmdExecuteGeneratedCommandsEXT-indirectExecutionSet-11058
    If transform feedback is active, VkGeneratedCommandsInfoEXT::indirectExecutionSet must be VK_NULL_HANDLE

  • VUID-vkCmdExecuteGeneratedCommandsEXT-deviceGeneratedCommands-11059
    The VkPhysicalDeviceDeviceGeneratedCommandsFeaturesEXT::deviceGeneratedCommands feature must be enabled

  • VUID-vkCmdExecuteGeneratedCommandsEXT-supportedIndirectCommandsShaderStages-11060
    The bound shader stages must be supported by VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT::supportedIndirectCommandsShaderStages

  • VUID-vkCmdExecuteGeneratedCommandsEXT-supportedIndirectCommandsShaderStages-11061
    Only stages specified in VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT::supportedIndirectCommandsShaderStages can be set in pGeneratedCommandsInfo->shaderStages

  • VUID-vkCmdExecuteGeneratedCommandsEXT-None-11062
    If a rendering pass is currently active, the view mask must be 0

  • VUID-vkCmdExecuteGeneratedCommandsEXT-commandBuffer-11143
    commandBuffer must not have been recorded with VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT

  • VUID-vkCmdExecuteGeneratedCommandsEXT-indirectCommandsLayout-10769
    If the indirectCommandsLayout member of pGeneratedCommandsInfo contains a draw token, this command must not be called outside a render pass instance

  • VUID-vkCmdExecuteGeneratedCommandsEXT-indirectCommandsLayout-12202
    If the indirectCommandsLayout member of pGeneratedCommandsInfo does not contain a draw token, this command must not be called inside a render pass instance

Valid Usage (Implicit)

  • VUID-vkCmdExecuteGeneratedCommandsEXT-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdExecuteGeneratedCommandsEXT-pGeneratedCommandsInfo-parameter
    pGeneratedCommandsInfo must be a valid pointer to a valid VkGeneratedCommandsInfoEXT structure

  • VUID-vkCmdExecuteGeneratedCommandsEXT-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdExecuteGeneratedCommandsEXT-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support VK_QUEUE_COMPUTE_BIT, or VK_QUEUE_GRAPHICS_BIT operations

  • VUID-vkCmdExecuteGeneratedCommandsEXT-suspended
    This command must not be called between suspended render pass instances

  • VUID-vkCmdExecuteGeneratedCommandsEXT-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdExecuteGeneratedCommandsEXT-bufferlevel
    commandBuffer must be a primary VkCommandBuffer

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary

Both

Outside

VK_QUEUE_COMPUTE_BIT
VK_QUEUE_GRAPHICS_BIT

Action
Indirection
Conditional Rendering

vkCmdExecuteGeneratedCommandsEXT is affected by conditional rendering

The VkGeneratedCommandsInfoEXT is defined as:

// Provided by VK_EXT_device_generated_commands
typedef struct VkGeneratedCommandsInfoEXT {
    VkStructureType                sType;
    const void*                    pNext;
    VkShaderStageFlags             shaderStages;
    VkIndirectExecutionSetEXT      indirectExecutionSet;
    VkIndirectCommandsLayoutEXT    indirectCommandsLayout;
    VkDeviceAddress                indirectAddress;
    VkDeviceSize                   indirectAddressSize;
    VkDeviceAddress                preprocessAddress;
    VkDeviceSize                   preprocessSize;
    uint32_t                       maxSequenceCount;
    VkDeviceAddress                sequenceCountAddress;
    uint32_t                       maxDrawCount;
} VkGeneratedCommandsInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • shaderStages is the mask of shader stages used by the commands.

  • indirectExecutionSet is the indirect execution set to be used for binding shaders.

  • indirectCommandsLayout is the VkIndirectCommandsLayoutEXT that specifies the command sequence data.

  • indirectAddress is an address that holds the indirect buffer data.

  • indirectAddressSize is the size in bytes of indirect buffer data starting at indirectAddress.

  • preprocessAddress specifies a physical address of the VkBuffer used for preprocessing the input data for execution. If this structure is used with vkCmdExecuteGeneratedCommandsEXT with its isPreprocessed set to VK_TRUE, then the preprocessing step is skipped but data in this address may still be modified. The contents and the layout of this address are opaque to applications and must not be modified outside functions related to device-generated commands or copied to another buffer for reuse.

  • preprocessSize is the maximum byte size within preprocessAddress that is available for preprocessing.

  • maxSequenceCount is used to determine the number of sequences to execute.

  • sequenceCountAddress specifies an optional physical address of a single uint32_t value containing the requested number of sequences to execute.

  • maxDrawCount is the maximum number of indirect draws that can be executed by any COUNT-type multi-draw indirect tokens. The draw count in the indirect buffer is clamped to this value for these token types.

If sequenceCountAddress is not NULL, then maxSequenceCount is the maximum number of sequences that can be executed. The actual number is min(maxSequenceCount, *sequenceCountAddress). If sequenceCountAddress is NULL, then maxSequenceCount is the exact number of sequences to execute.

If the action command token for the layout is not a COUNT-type multi-draw indirect token, maxDrawCount is ignored.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkGeneratedCommandsInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_GENERATED_COMMANDS_INFO_EXT

  • VUID-VkGeneratedCommandsInfoEXT-shaderStages-parameter
    shaderStages must be a valid combination of VkShaderStageFlagBits values

  • VUID-VkGeneratedCommandsInfoEXT-shaderStages-requiredbitmask
    shaderStages must not be 0

  • VUID-VkGeneratedCommandsInfoEXT-indirectExecutionSet-parameter
    If indirectExecutionSet is not VK_NULL_HANDLE, indirectExecutionSet must be a valid VkIndirectExecutionSetEXT handle

  • VUID-VkGeneratedCommandsInfoEXT-indirectCommandsLayout-parameter
    indirectCommandsLayout must be a valid VkIndirectCommandsLayoutEXT handle

  • VUID-VkGeneratedCommandsInfoEXT-indirectAddress-parameter
    indirectAddress must be a valid VkDeviceAddress value

  • VUID-VkGeneratedCommandsInfoEXT-preprocessAddress-parameter
    If preprocessAddress is not 0, preprocessAddress must be a valid VkDeviceAddress value

  • VUID-VkGeneratedCommandsInfoEXT-sequenceCountAddress-parameter
    If sequenceCountAddress is not 0, sequenceCountAddress must be a valid VkDeviceAddress value

  • VUID-VkGeneratedCommandsInfoEXT-commonparent
    Both of indirectCommandsLayout, and indirectExecutionSet that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

Referencing the functions defined in Indirect Commands Layout, vkCmdExecuteGeneratedCommandsEXT behaves as:

uint32_t sequencesCount = sequenceCountAddress ?
      min(maxSequenceCount, sequenceCountAddress.load_uint32()) :
      maxSequenceCount;


cmdProcessAllSequences(commandBuffer, indirectExecutionSet,
                       indirectCommandsLayout, indirectAddress,
                       sequencesCount);

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

It is important to note that the affected values of all state related to the shaderStages used are undefined after this command. This means that e.g., if this command indirectly alters push constants, the push constant state becomes undefined.

Commands can be preprocessed prior execution using the following command:

// Provided by VK_EXT_device_generated_commands
void vkCmdPreprocessGeneratedCommandsEXT(
    VkCommandBuffer                             commandBuffer,
    const VkGeneratedCommandsInfoEXT*           pGeneratedCommandsInfo,
    VkCommandBuffer                             stateCommandBuffer);

  • commandBuffer is the command buffer which does the preprocessing.

  • pGeneratedCommandsInfo is a pointer to a VkGeneratedCommandsInfoEXT structure containing parameters affecting the preprocessing step.

  • stateCommandBuffer is a command buffer from which to snapshot current states affecting the preprocessing step. When a graphics command action token is used, graphics state is snapshotted. When a compute action command token is used, compute state is snapshotted. When a ray tracing action command token is used, ray tracing state is snapshotted. It can be deleted at any time after this command has been recorded.

stateCommandBuffer access is not synchronized by the driver, meaning that this command buffer must not be modified between threads in an unsafe manner.
Valid Usage
Valid Usage (Implicit)

  • VUID-vkCmdPreprocessGeneratedCommandsEXT-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdPreprocessGeneratedCommandsEXT-pGeneratedCommandsInfo-parameter
    pGeneratedCommandsInfo must be a valid pointer to a valid VkGeneratedCommandsInfoEXT structure

  • VUID-vkCmdPreprocessGeneratedCommandsEXT-stateCommandBuffer-parameter
    stateCommandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdPreprocessGeneratedCommandsEXT-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdPreprocessGeneratedCommandsEXT-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support VK_QUEUE_COMPUTE_BIT, or VK_QUEUE_GRAPHICS_BIT operations

  • VUID-vkCmdPreprocessGeneratedCommandsEXT-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdPreprocessGeneratedCommandsEXT-suspended
    This command must not be called between suspended render pass instances

  • VUID-vkCmdPreprocessGeneratedCommandsEXT-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdPreprocessGeneratedCommandsEXT-bufferlevel
    commandBuffer must be a primary VkCommandBuffer

  • VUID-vkCmdPreprocessGeneratedCommandsEXT-commonparent
    Both of commandBuffer, and stateCommandBuffer must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to stateCommandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary

Outside

Outside

VK_QUEUE_COMPUTE_BIT
VK_QUEUE_GRAPHICS_BIT

Action
Conditional Rendering

vkCmdPreprocessGeneratedCommandsEXT is not affected by conditional rendering

The bound descriptor sets and push constants that will be used with indirect command generation must already be specified on stateCommandBuffer at the time of preprocessing commands with vkCmdPreprocessGeneratedCommandsEXT. They must match the bound descriptor sets and push constants used in the execution of indirect commands with vkCmdExecuteGeneratedCommandsEXT.

If push constants for shader stages are also specified in the VkGeneratedCommandsInfoEXT::indirectCommandsLayout with a VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT or VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT token, then those values override the push constants that were previously pushed.

All State-setting commands that are bound on stateCommandBuffer will be used. Any parameters set by those commands must be set identically in a command buffer that vkCmdExecuteGeneratedCommandsEXT is recorded into, at the point vkCmdExecuteGeneratedCommandsEXT is recorded. If conditional rendering is used, the predicate value at preprocessing time must match the one at execution time. The queue family index stateCommandBuffer was allocated from must be the same as the queue family index of the command buffer used in vkCmdExecuteGeneratedCommandsEXT.

On some implementations, preprocessing may have no effect on performance.

vkCmdExecuteGeneratedCommandsEXT may write to the preprocess buffer, no matter the isPreprocess parameter. In this case, the implementation must insert appropriate synchronization automatically, which corresponds to the following pseudocode:

  • Barrier

    • srcStageMask = DRAW_INDIRECT

    • srcAccesMask = 0

    • dstStageMask = COMMAND_PREPROCESS_BIT

    • dstAccessMask = COMMAND_PREPROCESS_WRITE_BIT | COMMAND_PREPROCESS_READ_BIT

  • Do internal writes

  • Barrier

    • srcStageMask = COMMAND_PREPROCESS_BIT

    • srcAccesMask = COMMAND_PREPROCESS_WRITE_BIT

    • dstStageMask = DRAW_INDIRECT

    • dstAccessMask = INDIRECT_COMMAND_READ_BIT

  • Execute