vkCmdDispatch(3)

# vkCmdDispatch(3) Manual Page

## Name

vkCmdDispatch - Dispatch compute work items

Loading… please wait.

## C Specification

To record a dispatch, call:

    // Provided by VK_VERSION_1_0
    void vkCmdDispatch(
        VkCommandBuffer                             commandBuffer,
        uint32_t                                    groupCountX,
        uint32_t                                    groupCountY,
        uint32_t                                    groupCountZ);

## Parameters

- `commandBuffer` is the command buffer into which the command will be recorded.

- `groupCountX` is the number of local workgroups to dispatch in the X dimension.

- `groupCountY` is the number of local workgroups to dispatch in the Y dimension.

- `groupCountZ` is the number of local workgroups to dispatch in the Z dimension.

## Description

When the command is executed, a global workgroup consisting of `groupCountX` × `groupCountY` × `groupCountZ` local workgroups is assembled.

Valid Usage

- VUID-vkCmdDispatch-magFilter-04553
  If a VkSampler created with `magFilter` or `minFilter` equal to `VK_FILTER_LINEAR` and `compareEnable` equal to `VK_FALSE` is used to sample a VkImageView as a result of this command, then the image view’s format features must contain `VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT`

- VUID-vkCmdDispatch-mipmapMode-04770
  If a VkSampler created with `mipmapMode` equal to `VK_SAMPLER_MIPMAP_MODE_LINEAR` and `compareEnable` equal to `VK_FALSE` is used to sample a VkImageView as a result of this command, then the image view’s format features must contain `VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT`

- VUID-vkCmdDispatch-None-02691
  If a `VkImageView` is accessed using atomic operations as a result of this command, then the image view’s format features must contain `VK_FORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT`

- VUID-vkCmdDispatch-None-02692
  If a `VkImageView` is sampled with `VK_FILTER_CUBIC_EXT` as a result of this command, then the image view’s format features must contain `VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT`

- VUID-vkCmdDispatch-filterCubic-02694
  Any VkImageView being sampled with `VK_FILTER_CUBIC_EXT` as a result of this command must have a VkImageViewType and format that supports cubic filtering, as specified by `VkFilterCubicImageViewImageFormatPropertiesEXT`::`filterCubic` returned by `vkGetPhysicalDeviceImageFormatProperties2`

- VUID-vkCmdDispatch-filterCubicMinmax-02695
  Any VkImageView being sampled with `VK_FILTER_CUBIC_EXT` with a reduction mode of either `VK_SAMPLER_REDUCTION_MODE_MIN` or `VK_SAMPLER_REDUCTION_MODE_MAX` as a result of this command must have a VkImageViewType and format that supports cubic filtering together with minmax filtering, as specified by `VkFilterCubicImageViewImageFormatPropertiesEXT`::`filterCubicMinmax` returned by `vkGetPhysicalDeviceImageFormatProperties2`

- VUID-vkCmdDispatch-flags-02696
  Any VkImage created with a VkImageCreateInfo::`flags` containing `VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV` sampled as a result of this command must only be sampled using a VkSamplerAddressMode of `VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE`

- VUID-vkCmdDispatch-None-02697
  For each set n that is statically used by the `VkPipeline` bound to the pipeline bind point used by this command, a descriptor set must have been bound to n at the same pipeline bind point, with a `VkPipelineLayout` that is compatible for set n, with the `VkPipelineLayout` used to create the current `VkPipeline`, as described in [descriptorsets-compatibility]

- VUID-vkCmdDispatch-None-02698
  For each push constant that is statically used by the `VkPipeline` bound to the pipeline bind point used by this command, a push constant value must have been set for the same pipeline bind point, with a `VkPipelineLayout` that is compatible for push constants, with the `VkPipelineLayout` used to create the current `VkPipeline`, as described in [descriptorsets-compatibility]

- VUID-vkCmdDispatch-None-02699
  Descriptors in each bound descriptor set, specified via `vkCmdBindDescriptorSets`, must be valid if they are statically used by the `VkPipeline` bound to the pipeline bind point used by this command

- VUID-vkCmdDispatch-None-02700
  A valid pipeline must be bound to the pipeline bind point used by this command

- VUID-vkCmdDispatch-commandBuffer-02701
  If the `VkPipeline` object bound to the pipeline bind point used by this command requires any dynamic state, that state must have been set or inherited for `commandBuffer`, and done so after any previously bound pipeline with the corresponding state not specified as dynamic

- VUID-vkCmdDispatch-None-02859
  There must not have been any calls to dynamic state setting commands for any state not specified as dynamic in the `VkPipeline` object bound to the pipeline bind point used by this command, since that pipeline was bound

- VUID-vkCmdDispatch-None-02702
  If the `VkPipeline` object bound to the pipeline bind point used by this command accesses a `VkSampler` object that uses unnormalized coordinates, that sampler must not be used to sample from any `VkImage` with a `VkImageView` of the type `VK_IMAGE_VIEW_TYPE_3D`, `VK_IMAGE_VIEW_TYPE_CUBE`, `VK_IMAGE_VIEW_TYPE_1D_ARRAY`, `VK_IMAGE_VIEW_TYPE_2D_ARRAY` or `VK_IMAGE_VIEW_TYPE_CUBE_ARRAY`, in any shader stage

- VUID-vkCmdDispatch-None-02703
  If the `VkPipeline` object bound to the pipeline bind point used by this command accesses a `VkSampler` object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-V `OpImageSample*` or `OpImageSparseSample*` instructions with `ImplicitLod`, `Dref` or `Proj` in their name, in any shader stage

- VUID-vkCmdDispatch-None-02704
  If the `VkPipeline` object bound to the pipeline bind point used by this command accesses a `VkSampler` object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-V `OpImageSample*` or `OpImageSparseSample*` instructions that includes a LOD bias or any offset values, in any shader stage

- VUID-vkCmdDispatch-None-02705
  If the robust buffer access feature is not enabled, and if the `VkPipeline` object bound to the pipeline bind point used by this command accesses a uniform buffer, it must not access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point

- VUID-vkCmdDispatch-None-02706
  If the robust buffer access feature is not enabled, and if the `VkPipeline` object bound to the pipeline bind point used by this command accesses a storage buffer, it must not access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point

- VUID-vkCmdDispatch-commandBuffer-02707
  If `commandBuffer` is an unprotected command buffer, any resource accessed by the `VkPipeline` object bound to the pipeline bind point used by this command must not be a protected resource

- VUID-vkCmdDispatch-None-04115
  If a VkImageView is accessed using `OpImageWrite` as a result of this command, then the `Type` of the `Texel` operand of that instruction must have at least as many components as the image view’s format.

- VUID-vkCmdDispatch-OpImageWrite-04469
  If a VkBufferView is accessed using `OpImageWrite` as a result of this command, then the `Type` of the `Texel` operand of that instruction must have at least as many components as the buffer view’s format.

- VUID-vkCmdDispatch-SampledType-04470
  If a VkImageView with a VkFormat that has a 64-bit channel width is accessed as a result of this command, the `SampledType` of the `OpTypeImage` operand of that instruction must have a `Width` of 64.

- VUID-vkCmdDispatch-SampledType-04471
  If a VkImageView with a VkFormat that has a channel width less than 64-bit is accessed as a result of this command, the `SampledType` of the `OpTypeImage` operand of that instruction must have a `Width` of 32.

- VUID-vkCmdDispatch-SampledType-04472
  If a VkBufferView with a VkFormat that has a 64-bit channel width is accessed as a result of this command, the `SampledType` of the `OpTypeImage` operand of that instruction must have a `Width` of 64.

- VUID-vkCmdDispatch-SampledType-04473
  If a VkBufferView with a VkFormat that has a channel width less than 64-bit is accessed as a result of this command, the `SampledType` of the `OpTypeImage` operand of that instruction must have a `Width` of 32.

- VUID-vkCmdDispatch-sparseImageInt64Atomics-04474
  If the `sparseImageInt64Atomics` feature is not enabled, VkImage objects created with the `VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT` flag must not be accessed by atomic instructions through an `OpTypeImage` with a `SampledType` with a `Width` of 64 by this command.

- VUID-vkCmdDispatch-sparseImageInt64Atomics-04475
  If the `sparseImageInt64Atomics` feature is not enabled, VkBuffer objects created with the `VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT` flag must not be accessed by atomic instructions through an `OpTypeImage` with a `SampledType` with a `Width` of 64 by this command.

- VUID-vkCmdDispatch-commandBuffer-02712
  If `commandBuffer` is a protected command buffer, any resource written to by the `VkPipeline` object bound to the pipeline bind point used by this command must not be an unprotected resource

- VUID-vkCmdDispatch-commandBuffer-02713
  If `commandBuffer` is a protected command buffer, pipeline stages other than the framebuffer-space and compute stages in the `VkPipeline` object bound to the pipeline bind point must not write to any resource

- VUID-vkCmdDispatch-commandBuffer-04617
  If any of the shader stages of the `VkPipeline` bound to the pipeline bind point used by this command uses the RayQueryKHR capability, then `commandBuffer` must not be a protected command buffer

- VUID-vkCmdDispatch-groupCountX-00386
  `groupCountX` must be less than or equal to `VkPhysicalDeviceLimits`::`maxComputeWorkGroupCount`[0]

- VUID-vkCmdDispatch-groupCountY-00387
  `groupCountY` must be less than or equal to `VkPhysicalDeviceLimits`::`maxComputeWorkGroupCount`[1]

- VUID-vkCmdDispatch-groupCountZ-00388
  `groupCountZ` must be less than or equal to `VkPhysicalDeviceLimits`::`maxComputeWorkGroupCount`[2]

Valid Usage (Implicit)

- VUID-vkCmdDispatch-commandBuffer-parameter
  `commandBuffer` must be a valid VkCommandBuffer handle

- VUID-vkCmdDispatch-commandBuffer-recording
  `commandBuffer` must be in the recording state

- VUID-vkCmdDispatch-commandBuffer-cmdpool
  The `VkCommandPool` that `commandBuffer` was allocated from must support compute operations

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

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 | Supported Queue Types | Pipeline Type
--- | --- | --- | ---
Primary Secondary | Outside | Compute | Compute

## See Also

VkCommandBuffer

## Document Notes

For more information, see the Vulkan Specification

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

## Copyright

Copyright 2014-2021 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0