vkCmdPipelineBarrier(3)

# vkCmdPipelineBarrier(3) Manual Page

## Name

vkCmdPipelineBarrier - Insert a memory dependency

## C Specification

To record a pipeline barrier, call:

    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

- If the geometry shaders feature is not enabled, `srcStageMask` must not contain `VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT`

- If the geometry shaders feature is not enabled, `dstStageMask` must not contain `VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT`

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

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

- 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, and for which `srcStageMask` contains a subset of the bit values in `VkSubpassDependency`::`srcStageMask`, `dstStageMask` contains a subset of the bit values in `VkSubpassDependency`::`dstStageMask`, `dependencyFlags` is equal to `VkSubpassDependency`::`dependencyFlags`, `srcAccessMask` member of each element of `pMemoryBarriers` and `pImageMemoryBarriers` contains a subset of the bit values in `VkSubpassDependency`::`srcAccessMask`, and `dstAccessMask` member of each element of `pMemoryBarriers` and `pImageMemoryBarriers` contains a subset of the bit values in `VkSubpassDependency`::`dstAccessMask`

- If `vkCmdPipelineBarrier` is called within a render pass instance, `bufferMemoryBarrierCount` must be `0`

- If `vkCmdPipelineBarrier` is called within a render pass instance, the `image` member of any element of `pImageMemoryBarriers` must be equal to one of the elements of `pAttachments` that the current `framebuffer` was created with, that is also referred to by one of the elements of the `pColorAttachments`, `pResolveAttachments` or `pDepthStencilAttachment` members of the `VkSubpassDescription` instance or by the `pDepthStencilResolveAttachment` member of the `VkSubpassDescriptionDepthStencilResolve` structure that the current subpass was created with

- If `vkCmdPipelineBarrier` is called within a render pass instance, the `oldLayout` and `newLayout` members of any element of `pImageMemoryBarriers` must be equal to the `layout` member of an element of the `pColorAttachments`, `pResolveAttachments` or `pDepthStencilAttachment` members of the `VkSubpassDescription` instance or by the `pDepthStencilResolveAttachment` member of the `VkSubpassDescriptionDepthStencilResolve` structure that the current subpass was created with, that refers to the same `image`

- If `vkCmdPipelineBarrier` is called within a render pass instance, the `oldLayout` and `newLayout` members of an element of `pImageMemoryBarriers` must be equal

- If `vkCmdPipelineBarrier` is called within a render pass instance, the `srcQueueFamilyIndex` and `dstQueueFamilyIndex` members of any element of `pImageMemoryBarriers` must be `VK_QUEUE_FAMILY_IGNORED`

- Any pipeline stage included in `srcStageMask` or `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

- If `vkCmdPipelineBarrier` is called outside of a render pass instance, `dependencyFlags` must not include `VK_DEPENDENCY_VIEW_LOCAL_BIT`

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

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

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

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

- 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

- 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

- 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

- 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

- 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

- 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

Valid Usage (Implicit)

- `commandBuffer` must be a valid VkCommandBuffer handle

- `srcStageMask` must be a valid combination of VkPipelineStageFlagBits values

- `srcStageMask` must not be `0`

- `dstStageMask` must be a valid combination of VkPipelineStageFlagBits values

- `dstStageMask` must not be `0`

- `dependencyFlags` must be a valid combination of VkDependencyFlagBits values

- If `memoryBarrierCount` is not `0`, `pMemoryBarriers` must be a valid pointer to an array of `memoryBarrierCount` valid VkMemoryBarrier structures

- If `bufferMemoryBarrierCount` is not `0`, `pBufferMemoryBarriers` must be a valid pointer to an array of `bufferMemoryBarrierCount` valid VkBufferMemoryBarrier structures

- If `imageMemoryBarrierCount` is not `0`, `pImageMemoryBarriers` must be a valid pointer to an array of `imageMemoryBarrierCount` valid VkImageMemoryBarrier structures

- `commandBuffer` must be in the recording state

- 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 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.