VKCMDPIPELINEBARRIER(3)

NAME
vkCmdPipelineBarrier - Insert a set of execution and memory barriers.

C SPECIFICATION

    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
    The command buffer in which to wait.

srcStageMask
    Specifies which pipeline stages must complete executing prior commands (see VkPipelineStageFlags for more detail).

dstStageMask
    Specifies which pipeline stages do not begin executing subsequent commands until the barrier completes (see VkPipelineStageFlags for more detail).

byRegion
    Indicates whether the barrier has screen-space locality (described below).

memoryBarrierCount
    Number of memory barriers to insert after waiting for the pipe events.

ppMemoryBarriers
    Array of pointers to memory barrier structures specifying the parameters of the memory barriers to insert as part of the pipeline barrier. Each element of the array may point to a VkMemoryBarrier, VkBufferMemoryBarrier, or VkImageMemoryBarrier structure.

DESCRIPTION

vkCmdPipelineBarrier inserts a set of execution and memory barriers into the command buffer specified by commandBuffer. The number of barriers to insert is specified in memoryBarrierCount and the description of those barriers is specified in a number instances of the VkMemoryBarrier, VkBufferMemoryBarrier or VkImageMemoryBarrier structures. The definitions of these structures are:

    typedef struct VkMemoryBarrier {
        VkStructureType    sType;
        const void*        pNext;
        VkAccessFlags      srcAccessMask;
        VkAccessFlags      dstAccessMask;
    } VkMemoryBarrier;

    typedef struct VkBufferMemoryBarrier {
        VkStructureType    sType;
        const void*        pNext;
        VkAccessFlags      srcAccessMask;
        VkAccessFlags      dstAccessMask;
        uint32_t           srcQueueFamilyIndex;
        uint32_t           dstQueueFamilyIndex;
        VkBuffer           buffer;
        VkDeviceSize       offset;
        VkDeviceSize       size;
    } VkBufferMemoryBarrier;

    typedef struct VkImageMemoryBarrier {
        VkStructureType            sType;
        const void*                pNext;
        VkAccessFlags              srcAccessMask;
        VkAccessFlags              dstAccessMask;
        VkImageLayout              oldLayout;
        VkImageLayout              newLayout;
        uint32_t                   srcQueueFamilyIndex;
        uint32_t                   dstQueueFamilyIndex;
        VkImage                    image;
        VkImageSubresourceRange    subresourceRange;
    } VkImageMemoryBarrier;

The ppMemoryBarriers parameter points to an array of pointers to these structures. Each element of ppMemoryBarriers may point to a different type of structure. The type of each structure is identified by its sType member member. This should be set to VK_STRUCTURE_TYPE_MEMORY_BARRIER, VK_STRUCTURE_TYPE_BUFFER_MEMORY_BARRIER or VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER for VkMemoryBarrier, VkBufferMemoryBarrier and VkImageMemoryBarrier, respectively.

Writes as described by outputMask that were written by pipeline stages in srcStageMask prior to the barrier are made visible to reads as described by inputMask in pipeline stages in dstStageMask subsequent to the barrier. If byRegion is true, then the writes are made visible only to work in the same (implementation-dependent) screen-space region. This effectively reqiures that the subsequent work only reads data written by the same fragment location in the previous work. byRegion should only be set to true when the srcStageMask and dstStageMask only include screen-space work (fragment shader, early and late fragment tests, and/or attachment outputs).

In case of global memory barriers inserted by passing an VkMemoryBarrier structure to the command prior writes in the requested pipeline stages to any memory location corresponding to the set of memory output coherency flags specified in the outputMask member of the structure are made coherent with subsequent reads in the requested pipeline stages of any memory location corresponding to the set of memory input coherency flags specified in the inputMask member of the structure.

In case of buffer memory barriers inserted by passing an VkBufferMemoryBarrier structure to the command prior writes in the requested pipeline stages to the specified sub-range of the buffer corresponding to the set of memory output coherency flags specified in the outputMask member of the structure are made coherent with subsequent reads in the requested pipeline stages of the specified sub-range of the buffer corresponding to the set of memory input coherency flags specified in the inputMask member of the structure.

In case of image memory barriers inserted by passing an VkImageMemoryBarrier structure to the command prior writes in the requested pipeline stages to the specified sub-range of the image corresponding to the set of memory output coherency flags specified in the outputMask member of the structure are made coherent with subsequent reads in the requested pipeline stages of the specified sub-range of the image corresponding to the set of memory input coherency flags specified in the inputMask member of the structure. Additionally, if the oldLayout and newLayout members of the structure don’t match a layout transition is performed on the specified sub-range of the image as part of the memory barrier.

In case of buffer and image memory barriers the srcQueueFamilyIndex and dstQueueFamilyIndex members of the corresponding memory barrier structures can specify the parameters of a transfer of ownership between two distinct families of queues of a shared buffer or image object created with the VK_SHARING_MODE_EXCLUSIVE sharing mode. In case of regular resource transitions both srcQueueFamilyIndex and dstQueueFamilyIndex should be set to VK_QUEUE_FAMILY_IGNORED to indicate no transfer of ownership between queue families. In case of resource transitions involving ownership transfer of shared buffers or images one of these two members have to match the queue family index the command buffer specified by commandBuffer was created for, while the other should specify the queue family index the ownership transfer is released to or acquired from. Ownership transferring resource transitions have to be performed both on a queue from the source queue family and on a queue from the destination queue family (see VkSharingMode for more detail).

If the inputMask member is zero in any of the memory barrier structures then prior writes will only be coherent with any type of subsequent read after a future resource transition command specifies a non-empty set of memory input coherency control flags. This allows flushing device output caches unconditionally.

If the outputMask member is zero in any of the memory barrier structures then subsequent reads will only be coherent with any type of prior write if an earlier resource transition command specified a non-empty set of memory output coherency control flags. This allows invalidating device input caches unconditionally.

VALID USAGE

    • 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

    • 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 declare at least one self-dependency from the current subpass to itself - see Subpass Self-dependency

HOST SYNCHRONIZATION

    • Host access to commandBuffer must be externally synchronized

COMMAND PROPERTIES
Command Buffer Levels | Render Pass Scope | Supported Queue Types
Primary Secondary | Both | TRANSFER GRAPHICS COMPUTE

SEE ALSO

vkCmdWaitEvents, VkMemoryBarrier, VkBufferMemoryBarrier, VkImageMemoryBarrier, VkPipelineStageFlags

COPYRIGHT

Copyright © 2014-2016 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.

AUTHOR

Khronos Group
    Author.