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
.