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 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 vkCmdPipelineBarrier2, except that the scopes and barriers are defined as direct parameters rather than being defined by an VkDependencyInfo.

When vkCmdPipelineBarrier is submitted to a queue, it defines a memory dependency between commands that were submitted to the same queue before it, and those submitted to the same queue 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 `geometryShader` feature is not enabled, `srcStageMask` must not contain `VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT`

- VUID-vkCmdPipelineBarrier-srcStageMask-04091
  If the `tessellationShader` 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 `conditionalRendering` feature is not enabled, `srcStageMask` must not contain `VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT`

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

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

- VUID-vkCmdPipelineBarrier-srcStageMask-04095
  If the `meshShader` feature is not enabled, `srcStageMask` must not contain `VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT`

- VUID-vkCmdPipelineBarrier-srcStageMask-04096
  If the `taskShader` feature is not enabled, `srcStageMask` must not contain `VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT`

- VUID-vkCmdPipelineBarrier-srcStageMask-07318
  If neither the `shadingRateImage` or `attachmentFragmentShadingRate` are enabled, `srcStageMask` must not contain `VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR`

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

- VUID-vkCmdPipelineBarrier-srcStageMask-07949
  If neither the VK_NV_ray_tracing extension or `rayTracingPipeline` feature are enabled, `srcStageMask` must not contain `VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR`

- VUID-vkCmdPipelineBarrier-srcAccessMask-06257
  If the `rayQuery` feature is not enabled and a memory barrier `srcAccessMask` includes `VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR`, `srcStageMask` must not include any of the `VK_PIPELINE_STAGE_*_SHADER_BIT` stages except `VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR`

- VUID-vkCmdPipelineBarrier-dstStageMask-04090
  If the `geometryShader` feature is not enabled, `dstStageMask` must not contain `VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT`

- VUID-vkCmdPipelineBarrier-dstStageMask-04091
  If the `tessellationShader` 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 `conditionalRendering` feature is not enabled, `dstStageMask` must not contain `VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT`

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

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

- VUID-vkCmdPipelineBarrier-dstStageMask-04095
  If the `meshShader` feature is not enabled, `dstStageMask` must not contain `VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT`

- VUID-vkCmdPipelineBarrier-dstStageMask-04096
  If the `taskShader` feature is not enabled, `dstStageMask` must not contain `VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT`

- VUID-vkCmdPipelineBarrier-dstStageMask-07318
  If neither the `shadingRateImage` or `attachmentFragmentShadingRate` are enabled, `dstStageMask` must not contain `VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR`

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

- VUID-vkCmdPipelineBarrier-dstStageMask-07949
  If neither the VK_NV_ray_tracing extension or `rayTracingPipeline` feature are enabled, `dstStageMask` must not contain `VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR`

- VUID-vkCmdPipelineBarrier-dstAccessMask-06257
  If the `rayQuery` feature is not enabled and a memory barrier `dstAccessMask` includes `VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR`, `dstStageMask` must not include any of the `VK_PIPELINE_STAGE_*_SHADER_BIT` stages except `VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR`

- 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-None-07889
  If `vkCmdPipelineBarrier` is called within a render pass instance using a VkRenderPass object, the render pass must have been created with at least one subpass dependency that expresses a dependency from the current subpass to itself, does not include `VK_DEPENDENCY_BY_REGION_BIT` if this command does not, does not include `VK_DEPENDENCY_VIEW_LOCAL_BIT` if this command does not, and has 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 using a VkRenderPass object, it must not include any buffer memory barriers

- VUID-vkCmdPipelineBarrier-image-04073
  If `vkCmdPipelineBarrier` is called within a render pass instance using a VkRenderPass object, 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, color resolve, or depth/stencil attachment

- VUID-vkCmdPipelineBarrier-image-09373
  If `vkCmdPipelineBarrier` is called within a render pass instance using a VkRenderPass object, and the `image` member of any image memory barrier is a color resolve attachment, the corresponding color attachment must be `VK_ATTACHMENT_UNUSED`

- VUID-vkCmdPipelineBarrier-image-09374
  If `vkCmdPipelineBarrier` is called within a render pass instance using a VkRenderPass object, and the `image` member of any image memory barrier is a color resolve attachment, it must have been created with a non-zero VkExternalFormatANDROID::`externalFormat` value

- 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 memory barrier included in this command must be equal

- VUID-vkCmdPipelineBarrier-None-07890
  If `vkCmdPipelineBarrier` is called within a render pass instance, and the source stage masks of any memory barriers include framebuffer-space stages, destination stage masks of all memory barriers must only include framebuffer-space stages

- VUID-vkCmdPipelineBarrier-dependencyFlags-07891
  If `vkCmdPipelineBarrier` is called within a render pass instance, and the source stage masks of any memory barriers include framebuffer-space stages, then `dependencyFlags` must include `VK_DEPENDENCY_BY_REGION_BIT`

- VUID-vkCmdPipelineBarrier-None-07892
  If `vkCmdPipelineBarrier` is called within a render pass instance, the source and destination stage masks of any memory barriers must only include graphics pipeline stages

- VUID-vkCmdPipelineBarrier-dependencyFlags-01186
  If `vkCmdPipelineBarrier` is called outside of a render pass instance, the dependency flags must not include `VK_DEPENDENCY_VIEW_LOCAL_BIT`

- VUID-vkCmdPipelineBarrier-None-07893
  If `vkCmdPipelineBarrier` is called inside a render pass instance, and there is more than one view in the current subpass, dependency flags must include `VK_DEPENDENCY_VIEW_LOCAL_BIT`

- VUID-vkCmdPipelineBarrier-None-09553
  If neither the `shaderTileImageColorReadAccess` nor `shaderTileImageDepthReadAccess` features are enabled, and the `dynamicRenderingLocalRead` feature is not enabled, `vkCmdPipelineBarrier` must not be called within a render pass instance started with vkCmdBeginRendering

- VUID-vkCmdPipelineBarrier-None-09554
  If the `dynamicRenderingLocalRead` feature is not enabled, and `vkCmdPipelineBarrier` is called within a render pass instance started with vkCmdBeginRendering, there must be no buffer or image memory barriers specified by this command

- VUID-vkCmdPipelineBarrier-image-09555
  If `vkCmdPipelineBarrier` is called within a render pass instance started with vkCmdBeginRendering, and the `image` member of any image memory barrier is used as an attachment in the current render pass instance, it must be in the `VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ_KHR` or `VK_IMAGE_LAYOUT_GENERAL` layout

- VUID-vkCmdPipelineBarrier-srcStageMask-09556
  If `vkCmdPipelineBarrier` is called within a render pass instance started with vkCmdBeginRendering, this command must only specify framebuffer-space stages in `srcStageMask` and `dstStageMask`

- 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, compute, decode, or encode 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 | Video Coding Scope | Supported Queue Types | Command Type
--- | --- | --- | --- | ---
Primary Secondary | Both | Both | Transfer Graphics Compute Decode Encode | Synchronization

## 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-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0