VKCMDPIPELINEBARRIER(3)

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 defines a source stage mask.

    • dstStageMask defines a destination stage mask.

    • dependencyFlags is a bitmask of VkDependencyFlagBits. The bits that can be included in dependencyFlags are:

        typedef enum VkDependencyFlagBits {
            VK_DEPENDENCY_BY_REGION_BIT = 0x00000001,
        } VkDependencyFlagBits;

        • VK_DEPENDENCY_BY_REGION_BIT signifies that dependencies will be framebuffer-local.

DESCRIPTION

    • 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.

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 every command submitted to the same queue before it, including those in the same command buffer and batch. If vkCmdPipelineBarrier was recorded inside a render pass instance, the first synchronization scope includes only commands submitted before it 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 every command submitted to the same queue after it, including those in the same command buffer and batch. If vkCmdPipelineBarrier was recorded inside a render pass instance, the second synchronization scope includes only commands submitted after it 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 a VkSubpassDependency instance in pDependencies that expresses a dependency from the current subpass to itself. Additionally:

        • srcStageMask must contain a subset of the bit values in the srcStageMask member of that instance of VkSubpassDependency

        • dstStageMask must contain a subset of the bit values in the dstStageMask member of that instance of VkSubpassDependency

        • The srcAccessMask of any element of pMemoryBarriers or pImageMemoryBarriers must contain a subset of the bit values the srcAccessMask member of that instance of VkSubpassDependency

        • The dstAccessMask of any element of pMemoryBarriers or pImageMemoryBarriers must contain a subset of the bit values the dstAccessMask member of that instance of VkSubpassDependency

        • dependencyFlags must be equal to the dependencyFlags member of that instance of VkSubpassDependency

    • 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 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 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.

    • Any given element of pMemoryBarriers, pBufferMemoryBarriers or pImageMemoryBarriers must not have any access flag included in its srcAccessMask member if that bit is not supported by any of the pipeline stages in srcStageMask, as specified in the table of supported access types.

    • Any given element of pMemoryBarriers, pBufferMemoryBarriers or pImageMemoryBarriers must not have any access flag included in its dstAccessMask member if that bit is not supported by any 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 pointer to an array of memoryBarrierCount valid VkMemoryBarrier structures

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

    • If imageMemoryBarrierCount is not 0, pImageMemoryBarriers must be a 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 at URL

https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#vkCmdPipelineBarrier

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification,not directly.

COPYRIGHT

Copyright (c) 2014-2016 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.

AUTHOR

Khronos Group
    Author.