vkCmdPipelineBarrier(3)

# vkCmdPipelineBarrier(3) Manual Page

## Name

vkCmdPipelineBarrier - Insert a memory dependency

Loading… please wait.

## 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 stage mask.

- `dstStageMask` is a bitmask of VkPipelineStageFlagBits specifying the destination stage mask.

- `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

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 access 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 access 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-04092
  If the conditional rendering feature is not enabled, `srcStageMask` must not contain `VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT`

- VUID-vkCmdPipelineBarrier-srcStageMask-04093
  If the fragment density map feature is not enabled, `srcStageMask` must not contain `VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT`

- VUID-vkCmdPipelineBarrier-srcStageMask-04094
  If the transform feedback feature is not enabled, `srcStageMask` must not contain `VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT`

- VUID-vkCmdPipelineBarrier-srcStageMask-04095
  If the mesh shaders feature is not enabled, `srcStageMask` must not contain `VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV`

- VUID-vkCmdPipelineBarrier-srcStageMask-04096
  If the task shaders feature is not enabled, `srcStageMask` must not contain `VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV`

- VUID-vkCmdPipelineBarrier-srcStageMask-04097
  If the shading rate image feature is not enabled, `srcStageMask` must not contain `VK_PIPELINE_STAGE_SHADING_RATE_IMAGE_BIT_NV`

- VUID-vkCmdPipelineBarrier-srcStageMask-4098
  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-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-04092
  If the conditional rendering feature is not enabled, `dstStageMask` must not contain `VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT`

- VUID-vkCmdPipelineBarrier-dstStageMask-04093
  If the fragment density map feature is not enabled, `dstStageMask` must not contain `VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT`

- VUID-vkCmdPipelineBarrier-dstStageMask-04094
  If the transform feedback feature is not enabled, `dstStageMask` must not contain `VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT`

- VUID-vkCmdPipelineBarrier-dstStageMask-04095
  If the mesh shaders feature is not enabled, `dstStageMask` must not contain `VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV`

- VUID-vkCmdPipelineBarrier-dstStageMask-04096
  If the task shaders feature is not enabled, `dstStageMask` must not contain `VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV`

- VUID-vkCmdPipelineBarrier-dstStageMask-04097
  If the shading rate image feature is not enabled, `dstStageMask` must not contain `VK_PIPELINE_STAGE_SHADING_RATE_IMAGE_BIT_NV`

- VUID-vkCmdPipelineBarrier-dstStageMask-4098
  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

- 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

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-srcStageMask-requiredbitmask
  `srcStageMask` must not be `0`

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

- VUID-vkCmdPipelineBarrier-dstStageMask-requiredbitmask
  `dstStageMask` must not be `0`

- 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 | Pipeline Type
--- | --- | --- | ---
Primary Secondary | Both | Transfer Graphics Compute |

## See Also

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 (c) 2014-2020 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0