vkCmdPipelineBarrier is a synchronization command that inserts a
dependency between commands submitted to the same queue, or between commands
in the same subpass.
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);
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.
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.
If vkCmdPipelineBarrier is called inside a render pass instance, the
following restrictions apply.
For a given subpass to allow a pipeline barrier, the render pass must
declare a self-dependency from that subpass to itself.
That is, there must exist a VkSubpassDependency in the subpass
dependency list for the render pass with srcSubpass and
dstSubpass equal to that subpass index.
More than one self-dependency can be declared for each subpass.
Self-dependencies must only include pipeline stage bits that are graphics
stages.
Self-dependencies must not have any earlier pipeline stages depend on any
later pipeline stages.
More precisely, this means that whatever is the last pipeline stage in
srcStageMask must be no later than whatever is the first pipeline
stage in dstStageMask (the latest source stage can be equal to the
earliest destination stage).
If the source and destination stage masks both include framebuffer-space
stages, then dependencyFlags must include
VK_DEPENDENCY_BY_REGION_BIT.
A vkCmdPipelineBarrier command inside a render pass instance must be
a subset of one of the self-dependencies of the subpass it is used in,
meaning that the stage masks and access masks must each include only a
subset of the bits of the corresponding mask in that self-dependency.
If the self-dependency has VK_DEPENDENCY_BY_REGION_BIT set, then so
must the pipeline barrier.
Pipeline barriers within a render pass instance can only be types
VkMemoryBarrier or VkImageMemoryBarrier.
If a VkImageMemoryBarrier is used, the image and image subresource
range specified in the barrier must be a subset of one of the image views
used by the framebuffer in the current subpass.
Additionally, oldLayout must be equal to newLayout, and both
the srcQueueFamilyIndex and dstQueueFamilyIndex must be
VK_QUEUE_FAMILY_IGNORED.