C Specification

To record a pipeline barrier, call:

// Provided by VK_VERSION_1_0
void vkCmdPipelineBarrier(
    VkCommandBuffer                             commandBuffer,
    VkPipelineStageFlags                        srcStageMask,
    VkPipelineStageFlags                        dstStageMask,
    VkDependencyFlags                           dependencyFlags,
    uint32_t                                    memoryBarrierCount,
    const VkMemoryBarrier*                      pMemoryBarriers,
    uint32_t                                    bufferMemoryBarrierCount,
    const VkBufferMemoryBarrier*                pBufferMemoryBarriers,
    uint32_t                                    imageMemoryBarrierCount,
    const VkImageMemoryBarrier*                 pImageMemoryBarriers);

Parameters

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

  • srcStageMask is a bitmask of VkPipelineStageFlagBits specifying the source stages.

  • dstStageMask is a bitmask of VkPipelineStageFlagBits specifying the destination stages.

  • dependencyFlags is a bitmask of VkDependencyFlagBits specifying how execution and memory dependencies are formed.

  • memoryBarrierCount is the length of the pMemoryBarriers array.

  • pMemoryBarriers is a pointer to an array of VkMemoryBarrier structures.

  • bufferMemoryBarrierCount is the length of the pBufferMemoryBarriers array.

  • pBufferMemoryBarriers is a pointer to an array of VkBufferMemoryBarrier structures.

  • imageMemoryBarrierCount is the length of the pImageMemoryBarriers array.

  • pImageMemoryBarriers is a pointer to an array of VkImageMemoryBarrier structures.

Description

vkCmdPipelineBarrier operates almost identically to vkCmdPipelineBarrier2KHR, except that the scopes and barriers are defined as direct parameters rather than being defined by an VkDependencyInfoKHR.

When vkCmdPipelineBarrier is submitted to a queue, it defines a memory dependency between commands that were submitted before it, and those submitted after it.

If vkCmdPipelineBarrier was recorded outside a render pass instance, the first synchronization scope includes all commands that occur earlier in submission order. If vkCmdPipelineBarrier was recorded inside a render pass instance, the first synchronization scope includes only commands that occur earlier in submission order within the same subpass. In either case, the first synchronization scope is limited to operations on the pipeline stages determined by the source stage mask specified by srcStageMask.

If vkCmdPipelineBarrier was recorded outside a render pass instance, the second synchronization scope includes all commands that occur later in submission order. If vkCmdPipelineBarrier was recorded inside a render pass instance, the second synchronization scope includes only commands that occur later in submission order within the same subpass. In either case, the second synchronization scope is limited to operations on the pipeline stages determined by the destination stage mask specified by dstStageMask.

The first access scope is limited to accesses in the pipeline stages determined by the source stage mask specified by srcStageMask. Within that, the first access scope only includes the first access scopes defined by elements of the pMemoryBarriers, pBufferMemoryBarriers and pImageMemoryBarriers arrays, which each define a set of memory barriers. If no memory barriers are specified, then the first access scope includes no accesses.

The second access scope is limited to accesses in the pipeline stages determined by the destination stage mask specified by dstStageMask. Within that, the second access scope only includes the second access scopes defined by elements of the pMemoryBarriers, pBufferMemoryBarriers and pImageMemoryBarriers arrays, which each define a set of memory barriers. If no memory barriers are specified, then the second access scope includes no accesses.

If dependencyFlags includes VK_DEPENDENCY_BY_REGION_BIT, then any dependency between framebuffer-space pipeline stages is framebuffer-local - otherwise it is framebuffer-global.

Valid Usage

  • VUID-vkCmdPipelineBarrier-srcStageMask-04090
    If the geometry shaders feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

  • VUID-vkCmdPipelineBarrier-srcStageMask-04091
    If the tessellation shaders feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-vkCmdPipelineBarrier-srcStageMask-03937
    If the synchronization2 feature is not enabled, srcStageMask must not be 0

  • VUID-vkCmdPipelineBarrier-dstStageMask-04090
    If the geometry shaders feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

  • VUID-vkCmdPipelineBarrier-dstStageMask-04091
    If the tessellation shaders feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-vkCmdPipelineBarrier-dstStageMask-03937
    If the synchronization2 feature is not enabled, dstStageMask must not be 0

  • VUID-vkCmdPipelineBarrier-srcAccessMask-02815
    The srcAccessMask member of each element of pMemoryBarriers must only include access flags that are supported by one or more of the pipeline stages in srcStageMask, as specified in the table of supported access types

  • VUID-vkCmdPipelineBarrier-dstAccessMask-02816
    The dstAccessMask member of each element of pMemoryBarriers must only include access flags that are supported by one or more of the pipeline stages in dstStageMask, as specified in the table of supported access types

  • VUID-vkCmdPipelineBarrier-pBufferMemoryBarriers-02817
    For any element of pBufferMemoryBarriers, if its srcQueueFamilyIndex and dstQueueFamilyIndex members are equal, or if its srcQueueFamilyIndex is the queue family index that was used to create the command pool that commandBuffer was allocated from, then its srcAccessMask member must only contain access flags that are supported by one or more of the pipeline stages in srcStageMask, as specified in the table of supported access types

  • VUID-vkCmdPipelineBarrier-pBufferMemoryBarriers-02818
    For any element of pBufferMemoryBarriers, if its srcQueueFamilyIndex and dstQueueFamilyIndex members are equal, or if its dstQueueFamilyIndex is the queue family index that was used to create the command pool that commandBuffer was allocated from, then its dstAccessMask member must only contain access flags that are supported by one or more of the pipeline stages in dstStageMask, as specified in the table of supported access types

  • VUID-vkCmdPipelineBarrier-pImageMemoryBarriers-02819
    For any element of pImageMemoryBarriers, if its srcQueueFamilyIndex and dstQueueFamilyIndex members are equal, or if its srcQueueFamilyIndex is the queue family index that was used to create the command pool that commandBuffer was allocated from, then its srcAccessMask member must only contain access flags that are supported by one or more of the pipeline stages in srcStageMask, as specified in the table of supported access types

  • VUID-vkCmdPipelineBarrier-pImageMemoryBarriers-02820
    For any element of pImageMemoryBarriers, if its srcQueueFamilyIndex and dstQueueFamilyIndex members are equal, or if its dstQueueFamilyIndex is the queue family index that was used to create the command pool that commandBuffer was allocated from, then its dstAccessMask member must only contain access flags that are supported by one or more of the pipeline stages in dstStageMask, as specified in the table of supported access types

  • VUID-vkCmdPipelineBarrier-pDependencies-02285
    If vkCmdPipelineBarrier is called within a render pass instance, the render pass must have been created with at least one VkSubpassDependency instance in VkRenderPassCreateInfo::pDependencies that expresses a dependency from the current subpass to itself, with synchronization scopes and access scopes that are all supersets of the scopes defined in this command

  • VUID-vkCmdPipelineBarrier-bufferMemoryBarrierCount-01178
    If vkCmdPipelineBarrier is called within a render pass instance, it must not include any buffer memory barriers

  • VUID-vkCmdPipelineBarrier-image-04073
    If vkCmdPipelineBarrier is called within a render pass instance, the image member of any image memory barrier included in this command must be an attachment used in the current subpass both as an input attachment, and as either a color or depth/stencil attachment

  • VUID-vkCmdPipelineBarrier-oldLayout-01181
    If vkCmdPipelineBarrier is called within a render pass instance, the oldLayout and newLayout members of any image memory barrier included in this command must be equal

  • VUID-vkCmdPipelineBarrier-srcQueueFamilyIndex-01182
    If vkCmdPipelineBarrier is called within a render pass instance, the srcQueueFamilyIndex and dstQueueFamilyIndex members of any image memory barrier included in this command must be equal

  • VUID-vkCmdPipelineBarrier-dependencyFlags-01186
    If vkCmdPipelineBarrier is called outside of a render pass instance, VK_DEPENDENCY_VIEW_LOCAL_BIT must not be included in the dependency flags

  • VUID-vkCmdPipelineBarrier-srcStageMask-06461
    Any pipeline stage included in srcStageMask must be supported by the capabilities of the queue family specified by the queueFamilyIndex member of the VkCommandPoolCreateInfo structure that was used to create the VkCommandPool that commandBuffer was allocated from, as specified in the table of supported pipeline stages

  • VUID-vkCmdPipelineBarrier-dstStageMask-06462
    Any pipeline stage included in dstStageMask must be supported by the capabilities of the queue family specified by the queueFamilyIndex member of the VkCommandPoolCreateInfo structure that was used to create the VkCommandPool that commandBuffer was allocated from, as specified in the table of supported pipeline stages

Valid Usage (Implicit)

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

  • VUID-vkCmdPipelineBarrier-srcStageMask-parameter
    srcStageMask must be a valid combination of VkPipelineStageFlagBits values

  • VUID-vkCmdPipelineBarrier-dstStageMask-parameter
    dstStageMask must be a valid combination of VkPipelineStageFlagBits values

  • VUID-vkCmdPipelineBarrier-dependencyFlags-parameter
    dependencyFlags must be a valid combination of VkDependencyFlagBits values

  • VUID-vkCmdPipelineBarrier-pMemoryBarriers-parameter
    If memoryBarrierCount is not 0, pMemoryBarriers must be a valid pointer to an array of memoryBarrierCount valid VkMemoryBarrier structures

  • VUID-vkCmdPipelineBarrier-pBufferMemoryBarriers-parameter
    If bufferMemoryBarrierCount is not 0, pBufferMemoryBarriers must be a valid pointer to an array of bufferMemoryBarrierCount valid VkBufferMemoryBarrier structures

  • VUID-vkCmdPipelineBarrier-pImageMemoryBarriers-parameter
    If imageMemoryBarrierCount is not 0, pImageMemoryBarriers must be a valid pointer to an array of imageMemoryBarrierCount valid VkImageMemoryBarrier structures

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

  • VUID-vkCmdPipelineBarrier-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations

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

Primary
Secondary

Both

Transfer
Graphics
Compute

See Also

VK_VERSION_1_0, VkBufferMemoryBarrier, VkCommandBuffer, VkDependencyFlags, VkImageMemoryBarrier, VkMemoryBarrier, VkPipelineStageFlags

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