C Specification

To record a dispatch using non-zero base values for the components of WorkgroupId, call:

// Provided by VK_VERSION_1_1
void vkCmdDispatchBase(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    baseGroupX,
    uint32_t                                    baseGroupY,
    uint32_t                                    baseGroupZ,
    uint32_t                                    groupCountX,
    uint32_t                                    groupCountY,
    uint32_t                                    groupCountZ);
// Provided by VK_KHR_device_group
// Equivalent to vkCmdDispatchBase
void vkCmdDispatchBaseKHR(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    baseGroupX,
    uint32_t                                    baseGroupY,
    uint32_t                                    baseGroupZ,
    uint32_t                                    groupCountX,
    uint32_t                                    groupCountY,
    uint32_t                                    groupCountZ);

Parameters

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

  • baseGroupX is the start value for the X component of WorkgroupId.

  • baseGroupY is the start value for the Y component of WorkgroupId.

  • baseGroupZ is the start value for the Z component of WorkgroupId.

  • 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, with WorkgroupId values ranging from [baseGroup*, baseGroup* + groupCount*) in each component. vkCmdDispatch is equivalent to vkCmdDispatchBase(0,0,0,groupCountX,groupCountY,groupCountZ).

Valid Usage

  • VUID-vkCmdDispatchBase-commandBuffer-02712
    If commandBuffer is a protected command buffer and protectedNoFault is not supported, 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-vkCmdDispatchBase-commandBuffer-02713
    If commandBuffer is a protected command buffer and protectedNoFault is not supported, pipeline stages other than the framebuffer-space and compute stages in the VkPipeline object bound to the pipeline bind point used by this command must not write to any resource

  • VUID-vkCmdDispatchBase-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-vkCmdDispatchBase-baseGroupX-00421
    baseGroupX must be less than VkPhysicalDeviceLimits::maxComputeWorkGroupCount[0]

  • VUID-vkCmdDispatchBase-baseGroupX-00422
    baseGroupY must be less than VkPhysicalDeviceLimits::maxComputeWorkGroupCount[1]

  • VUID-vkCmdDispatchBase-baseGroupZ-00423
    baseGroupZ must be less than VkPhysicalDeviceLimits::maxComputeWorkGroupCount[2]

  • VUID-vkCmdDispatchBase-groupCountX-00424
    groupCountX must be less than or equal to VkPhysicalDeviceLimits::maxComputeWorkGroupCount[0] minus baseGroupX

  • VUID-vkCmdDispatchBase-groupCountY-00425
    groupCountY must be less than or equal to VkPhysicalDeviceLimits::maxComputeWorkGroupCount[1] minus baseGroupY

  • VUID-vkCmdDispatchBase-groupCountZ-00426
    groupCountZ must be less than or equal to VkPhysicalDeviceLimits::maxComputeWorkGroupCount[2] minus baseGroupZ

  • VUID-vkCmdDispatchBase-baseGroupX-00427
    If any of baseGroupX, baseGroupY, or baseGroupZ are not zero, then the bound compute pipeline must have been created with the VK_PIPELINE_CREATE_DISPATCH_BASE_BIT flag or the bound compute shader object must have been created with the VK_SHADER_CREATE_DISPATCH_BASE_BIT_EXT flag

Valid Usage (Implicit)

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

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

  • VUID-vkCmdDispatchBase-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support VK_QUEUE_COMPUTE_BIT operations

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

  • VUID-vkCmdDispatchBase-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

Both

Outside

VK_QUEUE_COMPUTE_BIT

Action
Conditional Rendering

vkCmdDispatchBase is affected by conditional rendering

See Also

VK_KHR_device_group, VK_VERSION_1_1, 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-2026 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0