142 lines
6.5 KiB
Plaintext
142 lines
6.5 KiB
Plaintext
vkCmdPipelineBarrier(3)
|
|
========================
|
|
|
|
Name
|
|
----
|
|
vkCmdPipelineBarrier - Insert a set of execution and memory barriers.
|
|
|
|
C Specification
|
|
---------------
|
|
|
|
include::../protos/vkCmdPipelineBarrier.txt[]
|
|
|
|
Parameters
|
|
----------
|
|
|
|
pname:commandBuffer::
|
|
The command buffer in which to wait.
|
|
|
|
pname:srcStageMask::
|
|
Specifies which pipeline stages must complete executing prior commands
|
|
(see elink:VkPipelineStageFlags for more detail).
|
|
|
|
pname:dstStageMask::
|
|
Specifies which pipeline stages do not begin executing subsequent
|
|
commands until the barrier completes (see elink:VkPipelineStageFlags for
|
|
more detail).
|
|
|
|
pname:byRegion::
|
|
Indicates whether the barrier has screen-space locality (described below).
|
|
|
|
pname:memoryBarrierCount::
|
|
Number of memory barriers to insert after waiting for the pipe events.
|
|
|
|
pname: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 slink:VkMemoryBarrier,
|
|
slink:VkBufferMemoryBarrier, or slink:VkImageMemoryBarrier structure.
|
|
|
|
Description
|
|
-----------
|
|
|
|
fname:vkCmdPipelineBarrier inserts a set of execution and memory barriers
|
|
into the command buffer specified by pname:commandBuffer. The number of barriers
|
|
to insert is specified in pname:memoryBarrierCount and the description of those
|
|
barriers is specified in a number instances of the slink:VkMemoryBarrier,
|
|
slink:VkBufferMemoryBarrier or slink:VkImageMemoryBarrier structures. The
|
|
definitions of these structures are:
|
|
|
|
include::../structs/VkMemoryBarrier.txt[]
|
|
|
|
include::../structs/VkBufferMemoryBarrier.txt[]
|
|
|
|
include::../structs/VkImageMemoryBarrier.txt[]
|
|
|
|
The pname:ppMemoryBarriers parameter points to an array of pointers to
|
|
these structures. Each element of pname:ppMemoryBarriers may point to a
|
|
different type of structure. The type of each structure is identified by its
|
|
pname:sType member member. This should be set to ename:VK_STRUCTURE_TYPE_MEMORY_BARRIER,
|
|
ename:VK_STRUCTURE_TYPE_BUFFER_MEMORY_BARRIER or
|
|
ename:VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER for slink:VkMemoryBarrier,
|
|
slink:VkBufferMemoryBarrier and slink:VkImageMemoryBarrier, respectively.
|
|
|
|
Writes as described by pname:outputMask that were written by pipeline stages
|
|
in pname:srcStageMask prior to the barrier are made visible to reads as
|
|
described by pname:inputMask in pipeline stages in pname:dstStageMask
|
|
subsequent to the barrier. If pname: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.
|
|
pname:byRegion should only be set to true when the pname:srcStageMask and
|
|
pname: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
|
|
slink: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 pname: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 pname:inputMask member of the structure.
|
|
|
|
In case of buffer memory barriers inserted by passing an
|
|
slink: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
|
|
pname: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 pname:inputMask member of the structure.
|
|
|
|
In case of image memory barriers inserted by passing an
|
|
slink: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
|
|
pname: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 pname:inputMask member of the structure. Additionally, if the
|
|
pname:oldLayout and pname: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 pname:srcQueueFamilyIndex
|
|
and pname: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 ename:VK_SHARING_MODE_EXCLUSIVE sharing mode. In case of regular
|
|
resource transitions both pname:srcQueueFamilyIndex and
|
|
pname:dstQueueFamilyIndex should be set to ename: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 pname: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 elink:VkSharingMode for more detail).
|
|
|
|
If the pname: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 pname: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.
|
|
|
|
include::../validity/protos/vkCmdPipelineBarrier.txt[]
|
|
|
|
See Also
|
|
--------
|
|
|
|
flink:vkCmdWaitEvents, slink:VkMemoryBarrier, slink:VkBufferMemoryBarrier,
|
|
slink:VkImageMemoryBarrier, elink:VkPipelineStageFlags
|
|
|
|
include::footer.txt[]
|
|
|