20. Copy Commands
An application can copy buffer and image data using several methods
depending on the type of data transfer.
Data can be copied between buffer objects with
vkCmdCopyBuffer2 and
vkCmdCopyBuffer and a portion of an image can be copied to another
image with
vkCmdCopyImage2 and
vkCmdCopyImage.
Image data can also be copied to and from buffer memory using
vkCmdCopyImageToBuffer2, vkCmdCopyImageToBuffer,
vkCmdCopyBufferToImage2, and vkCmdCopyBufferToImage.
Image data can be blitted (with or without scaling and filtering) with
vkCmdBlitImage2 and
vkCmdBlitImage.
Multisampled images can be resolved to a non-multisampled image with
vkCmdResolveImage2 and
vkCmdResolveImage.
All copy commands are treated as “transfer” operations for the purposes of synchronization barriers.
All copy commands that have a source format with an X component in its format description read undefined values from those bits.
All copy commands that have a destination format with an X component in its format description write undefined values to those bits.
20.1. Copying Data Between Buffers
To copy data between buffer objects, call:
// Provided by VK_VERSION_1_0
void vkCmdCopyBuffer(
VkCommandBuffer commandBuffer,
VkBuffer srcBuffer,
VkBuffer dstBuffer,
uint32_t regionCount,
const VkBufferCopy* pRegions);-
commandBufferis the command buffer into which the command will be recorded. -
srcBufferis the source buffer. -
dstBufferis the destination buffer. -
regionCountis the number of regions to copy. -
pRegionsis a pointer to an array of VkBufferCopy structures specifying the regions to copy.
Each region in pRegions is copied from the source buffer to the same
region of the destination buffer.
srcBuffer and dstBuffer can be the same buffer or alias the
same memory, but the resulting values are undefined if the copy regions
overlap in memory.
The VkBufferCopy structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkBufferCopy {
VkDeviceSize srcOffset;
VkDeviceSize dstOffset;
VkDeviceSize size;
} VkBufferCopy;-
srcOffsetis the starting offset in bytes from the start ofsrcBuffer. -
dstOffsetis the starting offset in bytes from the start ofdstBuffer. -
sizeis the number of bytes to copy.
A more extensible version of the copy buffer command is defined below.
To copy data between buffer objects, call:
// Provided by VK_VERSION_1_3
void vkCmdCopyBuffer2(
VkCommandBuffer commandBuffer,
const VkCopyBufferInfo2* pCopyBufferInfo);or the equivalent command
// Provided by VK_KHR_copy_commands2
void vkCmdCopyBuffer2KHR(
VkCommandBuffer commandBuffer,
const VkCopyBufferInfo2* pCopyBufferInfo);-
commandBufferis the command buffer into which the command will be recorded. -
pCopyBufferInfois a pointer to a VkCopyBufferInfo2 structure describing the copy parameters.
This command is functionally identical to vkCmdCopyBuffer, but
includes extensible sub-structures that include sType and pNext
parameters, allowing them to be more easily extended.
The VkCopyBufferInfo2 structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkCopyBufferInfo2 {
VkStructureType sType;
const void* pNext;
VkBuffer srcBuffer;
VkBuffer dstBuffer;
uint32_t regionCount;
const VkBufferCopy2* pRegions;
} VkCopyBufferInfo2;or the equivalent
// Provided by VK_KHR_copy_commands2
typedef VkCopyBufferInfo2 VkCopyBufferInfo2KHR;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcBufferis the source buffer. -
dstBufferis the destination buffer. -
regionCountis the number of regions to copy. -
pRegionsis a pointer to an array of VkBufferCopy2 structures specifying the regions to copy.
Members defined by this structure with the same name as parameters in
vkCmdCopyBuffer have the identical effect to those parameters; the
child structure VkBufferCopy2 is a variant of VkBufferCopy which
includes sType and pNext parameters, allowing it to be extended.
The VkBufferCopy2 structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkBufferCopy2 {
VkStructureType sType;
const void* pNext;
VkDeviceSize srcOffset;
VkDeviceSize dstOffset;
VkDeviceSize size;
} VkBufferCopy2;or the equivalent
// Provided by VK_KHR_copy_commands2
typedef VkBufferCopy2 VkBufferCopy2KHR;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcOffsetis the starting offset in bytes from the start ofsrcBuffer. -
dstOffsetis the starting offset in bytes from the start ofdstBuffer. -
sizeis the number of bytes to copy.
20.2. Copying Data Between Images
vkCmdCopyImage performs image copies in a similar manner to a host
memcpy.
It does not perform general-purpose conversions such as scaling, resizing,
blending, color-space conversion, or format conversions.
Rather, it simply copies raw image data.
vkCmdCopyImage can copy between images with different formats,
provided the formats are compatible as defined below.
To copy data between image objects, call:
// Provided by VK_VERSION_1_0
void vkCmdCopyImage(
VkCommandBuffer commandBuffer,
VkImage srcImage,
VkImageLayout srcImageLayout,
VkImage dstImage,
VkImageLayout dstImageLayout,
uint32_t regionCount,
const VkImageCopy* pRegions);-
commandBufferis the command buffer into which the command will be recorded. -
srcImageis the source image. -
srcImageLayoutis the current layout of the source image subresource. -
dstImageis the destination image. -
dstImageLayoutis the current layout of the destination image subresource. -
regionCountis the number of regions to copy. -
pRegionsis a pointer to an array of VkImageCopy structures specifying the regions to copy.
Each region in pRegions is copied from the source image to the same
region of the destination image.
srcImage and dstImage can be the same image or alias the same
memory.
The formats of srcImage and dstImage must be compatible.
Formats are compatible if they share the same class, as shown in the
Compatible Formats table.
Depth/stencil formats must match exactly.
If either srcImage or dstImage has a
multi-planar format,
regions of each plane to be copied must be specified separately using the
srcSubresource and dstSubresource members of the
VkImageCopy structure.
In this case, the aspectMask of the srcSubresource or
dstSubresource that refers to the multi-planar image must be
VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or
VK_IMAGE_ASPECT_PLANE_2_BIT.
For the purposes of vkCmdCopyImage, each plane of a multi-planar image
is treated as having the format listed in Compatible formats of planes of multi-planar formats for
the plane identified by the aspectMask of the corresponding
subresource.
This applies both to VkFormat and to coordinates used in the copy,
which correspond to texels in the plane rather than how these texels map
to coordinates in the image as a whole.
|
Note
For example, the |
vkCmdCopyImage allows copying between size-compatible compressed and
uncompressed internal formats.
Formats are size-compatible if the texel block size of the uncompressed
format is equal to the texel block size of the compressed format.
Such a copy does not perform on-the-fly compression or decompression.
When copying from an uncompressed format to a compressed format, each texel
of uncompressed data of the source image is copied as a raw value to the
corresponding compressed texel block of the destination image.
When copying from a compressed format to an uncompressed format, each
compressed texel block of the source image is copied as a raw value to the
corresponding texel of uncompressed data in the destination image.
Thus, for example, it is legal to copy between a 128-bit uncompressed format
and a compressed format which has a 128-bit sized compressed texel block
representing 4×4 texels (using 8 bits per texel), or between a 64-bit
uncompressed format and a compressed format which has a 64-bit sized
compressed texel block representing 4×4 texels (using 4 bits per
texel).
When copying between compressed and uncompressed formats the extent
members represent the texel dimensions of the source image and not the
destination.
When copying from a compressed image to an uncompressed image the image
texel dimensions written to the uncompressed image will be source extent
divided by the compressed texel block dimensions.
When copying from an uncompressed image to a compressed image the image
texel dimensions written to the compressed image will be the source extent
multiplied by the compressed texel block dimensions.
In both cases the number of bytes read and the number of bytes written will
be identical.
Copying to or from block-compressed images is typically done in multiples of
the compressed texel block size.
For this reason the extent must be a multiple of the compressed texel
block dimension.
There is one exception to this rule which is required to handle compressed
images created with dimensions that are not a multiple of the compressed
texel block dimensions: if the srcImage is compressed, then:
-
If
extent.widthis not a multiple of the compressed texel block width, then (extent.width+srcOffset.x) must equal the image subresource width. -
If
extent.heightis not a multiple of the compressed texel block height, then (extent.height+srcOffset.y) must equal the image subresource height. -
If
extent.depthis not a multiple of the compressed texel block depth, then (extent.depth+srcOffset.z) must equal the image subresource depth.
Similarly, if the dstImage is compressed, then:
-
If
extent.widthis not a multiple of the compressed texel block width, then (extent.width+dstOffset.x) must equal the image subresource width. -
If
extent.heightis not a multiple of the compressed texel block height, then (extent.height+dstOffset.y) must equal the image subresource height. -
If
extent.depthis not a multiple of the compressed texel block depth, then (extent.depth+dstOffset.z) must equal the image subresource depth.
This allows the last compressed texel block of the image in each non-multiple dimension to be included as a source or destination of the copy.
“_422” image formats that are not
multi-planar are treated as
having a 2×1 compressed texel block for the purposes of these rules.
vkCmdCopyImage can be used to copy image data between multisample
images, but both images must have the same number of samples.
The VkImageCopy structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkImageCopy {
VkImageSubresourceLayers srcSubresource;
VkOffset3D srcOffset;
VkImageSubresourceLayers dstSubresource;
VkOffset3D dstOffset;
VkExtent3D extent;
} VkImageCopy;-
srcSubresourceanddstSubresourceare VkImageSubresourceLayers structures specifying the image subresources of the images used for the source and destination image data, respectively. -
srcOffsetanddstOffsetselect the initialx,y, andzoffsets in texels of the sub-regions of the source and destination image data. -
extentis the size in texels of the image to copy inwidth,heightanddepth.
For VK_IMAGE_TYPE_3D images, copies are performed slice by slice
starting with the z member of the srcOffset or dstOffset,
and copying depth slices.
For images with multiple layers, copies are performed layer by layer
starting with the baseArrayLayer member of the srcSubresource or
dstSubresource and copying layerCount layers.
Image data can be copied between images with different image types.
If one image is VK_IMAGE_TYPE_3D and the other image is
VK_IMAGE_TYPE_2D with multiple layers, then each slice is copied to or
from a different layer; depth slices in the 3D image correspond to
layerCount layers in the 2D image, with an effective depth of
1 used for the 2D image.
Copies involving a multi-planar image format specify the region to be copied in terms of the
plane to be copied, not the coordinates of the multi-planar image.
This means that copies accessing the R/B planes of “_422” format
images must fit the copied region within half the width of the parent
image, and that copies accessing the R/B planes of “_420” format
images must fit the copied region within half the width and
height of the parent image.
The VkImageSubresourceLayers structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkImageSubresourceLayers {
VkImageAspectFlags aspectMask;
uint32_t mipLevel;
uint32_t baseArrayLayer;
uint32_t layerCount;
} VkImageSubresourceLayers;-
aspectMaskis a combination of VkImageAspectFlagBits, selecting the color, depth and/or stencil aspects to be copied. -
mipLevelis the mipmap level to copy -
baseArrayLayerandlayerCountare the starting layer and number of layers to copy.
A more extensible version of the copy image command is defined below.
To copy data between image objects, call:
// Provided by VK_VERSION_1_3
void vkCmdCopyImage2(
VkCommandBuffer commandBuffer,
const VkCopyImageInfo2* pCopyImageInfo);or the equivalent command
// Provided by VK_KHR_copy_commands2
void vkCmdCopyImage2KHR(
VkCommandBuffer commandBuffer,
const VkCopyImageInfo2* pCopyImageInfo);-
commandBufferis the command buffer into which the command will be recorded. -
pCopyImageInfois a pointer to a VkCopyImageInfo2 structure describing the copy parameters.
This command is functionally identical to vkCmdCopyImage, but includes
extensible sub-structures that include sType and pNext
parameters, allowing them to be more easily extended.
The VkCopyImageInfo2 structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkCopyImageInfo2 {
VkStructureType sType;
const void* pNext;
VkImage srcImage;
VkImageLayout srcImageLayout;
VkImage dstImage;
VkImageLayout dstImageLayout;
uint32_t regionCount;
const VkImageCopy2* pRegions;
} VkCopyImageInfo2;or the equivalent
// Provided by VK_KHR_copy_commands2
typedef VkCopyImageInfo2 VkCopyImageInfo2KHR;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcImageis the source image. -
srcImageLayoutis the current layout of the source image subresource. -
dstImageis the destination image. -
dstImageLayoutis the current layout of the destination image subresource. -
regionCountis the number of regions to copy. -
pRegionsis a pointer to an array of VkImageCopy2 structures specifying the regions to copy.
The VkImageCopy2 structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkImageCopy2 {
VkStructureType sType;
const void* pNext;
VkImageSubresourceLayers srcSubresource;
VkOffset3D srcOffset;
VkImageSubresourceLayers dstSubresource;
VkOffset3D dstOffset;
VkExtent3D extent;
} VkImageCopy2;or the equivalent
// Provided by VK_KHR_copy_commands2
typedef VkImageCopy2 VkImageCopy2KHR;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcSubresourceanddstSubresourceare VkImageSubresourceLayers structures specifying the image subresources of the images used for the source and destination image data, respectively. -
srcOffsetanddstOffsetselect the initialx,y, andzoffsets in texels of the sub-regions of the source and destination image data. -
extentis the size in texels of the image to copy inwidth,heightanddepth.
20.3. Copying Data Between Buffers and Images
To copy data from a buffer object to an image object, call:
// Provided by VK_VERSION_1_0
void vkCmdCopyBufferToImage(
VkCommandBuffer commandBuffer,
VkBuffer srcBuffer,
VkImage dstImage,
VkImageLayout dstImageLayout,
uint32_t regionCount,
const VkBufferImageCopy* pRegions);-
commandBufferis the command buffer into which the command will be recorded. -
srcBufferis the source buffer. -
dstImageis the destination image. -
dstImageLayoutis the layout of the destination image subresources for the copy. -
regionCountis the number of regions to copy. -
pRegionsis a pointer to an array of VkBufferImageCopy structures specifying the regions to copy.
Each region in pRegions is copied from the specified region of the
source buffer to the specified region of the destination image.
If dstImage has a
multi-planar format, regions
of each plane to be a target of a copy must be specified separately using
the pRegions member of the VkBufferImageCopy structure.
In this case, the aspectMask of imageSubresource must be
VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or
VK_IMAGE_ASPECT_PLANE_2_BIT.
For the purposes of vkCmdCopyBufferToImage, each plane of a
multi-planar image is treated as having the format listed in
Compatible formats of planes of multi-planar formats for the plane identified by the
aspectMask of the corresponding subresource.
This applies both to VkFormat and to coordinates used in the copy,
which correspond to texels in the plane rather than how these texels map
to coordinates in the image as a whole.
To copy data from an image object to a buffer object, call:
// Provided by VK_VERSION_1_0
void vkCmdCopyImageToBuffer(
VkCommandBuffer commandBuffer,
VkImage srcImage,
VkImageLayout srcImageLayout,
VkBuffer dstBuffer,
uint32_t regionCount,
const VkBufferImageCopy* pRegions);-
commandBufferis the command buffer into which the command will be recorded. -
srcImageis the source image. -
srcImageLayoutis the layout of the source image subresources for the copy. -
dstBufferis the destination buffer. -
regionCountis the number of regions to copy. -
pRegionsis a pointer to an array of VkBufferImageCopy structures specifying the regions to copy.
Each region in pRegions is copied from the specified region of the
source image to the specified region of the destination buffer.
If srcImage has a multi-planar format, regions of each plane to be a source of a copy must
be specified separately using the pRegions member of the
VkBufferImageCopy structure.
In this case, the aspectMask of imageSubresource must be
VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or
VK_IMAGE_ASPECT_PLANE_2_BIT.
For the purposes of vkCmdCopyBufferToImage, each plane of a
multi-planar image is treated as having the format listed in
Compatible formats of planes of multi-planar formats for the plane identified by the
aspectMask of the corresponding subresource.
This applies both to VkFormat and to coordinates used in the copy,
which correspond to texels in the plane rather than how these texels map
to coordinates in the image as a whole.
For both vkCmdCopyBufferToImage and vkCmdCopyImageToBuffer, each
element of pRegions is a structure defined as:
// Provided by VK_VERSION_1_0
typedef struct VkBufferImageCopy {
VkDeviceSize bufferOffset;
uint32_t bufferRowLength;
uint32_t bufferImageHeight;
VkImageSubresourceLayers imageSubresource;
VkOffset3D imageOffset;
VkExtent3D imageExtent;
} VkBufferImageCopy;-
bufferOffsetis the offset in bytes from the start of the buffer object where the image data is copied from or to. -
bufferRowLengthandbufferImageHeightspecify in texels a subregion of a larger two- or three-dimensional image in buffer memory, and control the addressing calculations. If either of these values is zero, that aspect of the buffer memory is considered to be tightly packed according to theimageExtent. -
imageSubresourceis a VkImageSubresourceLayers used to specify the specific image subresources of the image used for the source or destination image data. -
imageOffsetselects the initialx,y,zoffsets in texels of the sub-region of the source or destination image data. -
imageExtentis the size in texels of the image to copy inwidth,heightanddepth.
When copying to or from a depth or stencil aspect, the data in buffer memory uses a layout that is a (mostly) tightly packed representation of the depth or stencil data. Specifically:
-
data copied to or from the stencil aspect of any depth/stencil format is tightly packed with one
VK_FORMAT_S8_UINTvalue per texel. -
data copied to or from the depth aspect of a
VK_FORMAT_D16_UNORMorVK_FORMAT_D16_UNORM_S8_UINTformat is tightly packed with oneVK_FORMAT_D16_UNORMvalue per texel. -
data copied to or from the depth aspect of a
VK_FORMAT_D32_SFLOATorVK_FORMAT_D32_SFLOAT_S8_UINTformat is tightly packed with oneVK_FORMAT_D32_SFLOATvalue per texel. -
data copied to or from the depth aspect of a
VK_FORMAT_X8_D24_UNORM_PACK32orVK_FORMAT_D24_UNORM_S8_UINTformat is packed with one 32-bit word per texel with the D24 value in the LSBs of the word, and undefined values in the eight MSBs.
|
Note
To copy both the depth and stencil aspects of a depth/stencil format, two
entries in |
Because depth or stencil aspect buffer to image copies may require format conversions on some implementations, they are not supported on queues that do not support graphics.
When copying to a depth aspect,
and the VK_EXT_depth_range_unrestricted extension is not enabled,
the data in buffer memory must be in the range [0,1], or the
resulting values are undefined.
Copies are done layer by layer starting with image layer
baseArrayLayer member of imageSubresource.
layerCount layers are copied from the source image or to the
destination image.
For purpose of valid usage statements here and in related copy commands, a blocked image is defined as:
-
an image with a single-plane, “
_422” format, which is treated as a format with a 2 × 1 compressed texel block, or -
a compressed image.
More extensible versions of the commands to copy between buffers and images are defined below.
To copy data from a buffer object to an image object, call:
// Provided by VK_VERSION_1_3
void vkCmdCopyBufferToImage2(
VkCommandBuffer commandBuffer,
const VkCopyBufferToImageInfo2* pCopyBufferToImageInfo);or the equivalent command
// Provided by VK_KHR_copy_commands2
void vkCmdCopyBufferToImage2KHR(
VkCommandBuffer commandBuffer,
const VkCopyBufferToImageInfo2* pCopyBufferToImageInfo);-
commandBufferis the command buffer into which the command will be recorded. -
pCopyBufferToImageInfois a pointer to a VkCopyBufferToImageInfo2 structure describing the copy parameters.
This command is functionally identical to vkCmdCopyBufferToImage, but
includes extensible sub-structures that include sType and pNext
parameters, allowing them to be more easily extended.
The VkCopyBufferToImageInfo2 structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkCopyBufferToImageInfo2 {
VkStructureType sType;
const void* pNext;
VkBuffer srcBuffer;
VkImage dstImage;
VkImageLayout dstImageLayout;
uint32_t regionCount;
const VkBufferImageCopy2* pRegions;
} VkCopyBufferToImageInfo2;or the equivalent
// Provided by VK_KHR_copy_commands2
typedef VkCopyBufferToImageInfo2 VkCopyBufferToImageInfo2KHR;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcBufferis the source buffer. -
dstImageis the destination image. -
dstImageLayoutis the layout of the destination image subresources for the copy. -
regionCountis the number of regions to copy. -
pRegionsis a pointer to an array of VkBufferImageCopy2 structures specifying the regions to copy.
To copy data from an image object to a buffer object, call:
// Provided by VK_VERSION_1_3
void vkCmdCopyImageToBuffer2(
VkCommandBuffer commandBuffer,
const VkCopyImageToBufferInfo2* pCopyImageToBufferInfo);or the equivalent command
// Provided by VK_KHR_copy_commands2
void vkCmdCopyImageToBuffer2KHR(
VkCommandBuffer commandBuffer,
const VkCopyImageToBufferInfo2* pCopyImageToBufferInfo);-
commandBufferis the command buffer into which the command will be recorded. -
pCopyImageToBufferInfois a pointer to a VkCopyImageToBufferInfo2 structure describing the copy parameters.
This command is functionally identical to vkCmdCopyImageToBuffer, but
includes extensible sub-structures that include sType and pNext
parameters, allowing them to be more easily extended.
The VkCopyImageToBufferInfo2 structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkCopyImageToBufferInfo2 {
VkStructureType sType;
const void* pNext;
VkImage srcImage;
VkImageLayout srcImageLayout;
VkBuffer dstBuffer;
uint32_t regionCount;
const VkBufferImageCopy2* pRegions;
} VkCopyImageToBufferInfo2;or the equivalent
// Provided by VK_KHR_copy_commands2
typedef VkCopyImageToBufferInfo2 VkCopyImageToBufferInfo2KHR;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcImageis the source image. -
srcImageLayoutis the layout of the source image subresources for the copy. -
dstBufferis the destination buffer. -
regionCountis the number of regions to copy. -
pRegionsis a pointer to an array of VkBufferImageCopy2 structures specifying the regions to copy.
For both vkCmdCopyBufferToImage2 and vkCmdCopyImageToBuffer2,
each element of pRegions is a structure defined as:
// Provided by VK_VERSION_1_3
typedef struct VkBufferImageCopy2 {
VkStructureType sType;
const void* pNext;
VkDeviceSize bufferOffset;
uint32_t bufferRowLength;
uint32_t bufferImageHeight;
VkImageSubresourceLayers imageSubresource;
VkOffset3D imageOffset;
VkExtent3D imageExtent;
} VkBufferImageCopy2;or the equivalent
// Provided by VK_KHR_copy_commands2
typedef VkBufferImageCopy2 VkBufferImageCopy2KHR;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
bufferOffsetis the offset in bytes from the start of the buffer object where the image data is copied from or to. -
bufferRowLengthandbufferImageHeightspecify in texels a subregion of a larger two- or three-dimensional image in buffer memory, and control the addressing calculations. If either of these values is zero, that aspect of the buffer memory is considered to be tightly packed according to theimageExtent. -
imageSubresourceis a VkImageSubresourceLayers used to specify the specific image subresources of the image used for the source or destination image data. -
imageOffsetselects the initialx,y,zoffsets in texels of the sub-region of the source or destination image data. -
imageExtentis the size in texels of the image to copy inwidth,heightanddepth.
This structure is functionally identical to VkBufferImageCopy, but
adds sType and pNext parameters, allowing it to be more easily
extended.
For both vkCmdCopyBufferToImage2 and vkCmdCopyImageToBuffer2,
each region copied can include a rotation.
To specify a region with rotation, add the
VkCopyCommandTransformInfoQCOM to the pNext chain of
VkBufferImageCopy2.
When a rotation is specified, Buffer and Image Addressing with Rotation specifies how coordinates of
texels in the source region are rotated by transform to produce texel
coordinates in the destination region.
When rotation is specified, the source and destination images must each be
2D images.
They must not be blocked images or have a
multi-planar format.
The VkRenderPassTransformBeginInfoQCOM structure is defined as:
// Provided by VK_QCOM_rotated_copy_commands
typedef struct VkCopyCommandTransformInfoQCOM {
VkStructureType sType;
const void* pNext;
VkSurfaceTransformFlagBitsKHR transform;
} VkCopyCommandTransformInfoQCOM;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
transformis a VkSurfaceTransformFlagBitsKHR value describing the transform to be applied.
20.3.1. Buffer and Image Addressing
Pseudocode for image/buffer addressing of uncompressed formats is:
rowLength = region->bufferRowLength;
if (rowLength == 0)
rowLength = region->imageExtent.width;
imageHeight = region->bufferImageHeight;
if (imageHeight == 0)
imageHeight = region->imageExtent.height;
texelBlockSize = <texel block size of the format of the src/dstImage>;
address of (x,y,z) = region->bufferOffset + (((z * imageHeight) + y) * rowLength + x) * texelBlockSize;
where x,y,z range from (0,0,0) to region->imageExtent.{width,height,depth}.Note that imageOffset does not affect addressing calculations for
buffer memory.
Instead, bufferOffset can be used to select the starting address in
buffer memory.
For block-compressed formats, all parameters are still specified in texels rather than compressed texel blocks, but the addressing math operates on whole compressed texel blocks. Pseudocode for compressed copy addressing is:
rowLength = region->bufferRowLength;
if (rowLength == 0)
rowLength = region->imageExtent.width;
imageHeight = region->bufferImageHeight;
if (imageHeight == 0)
imageHeight = region->imageExtent.height;
compressedTexelBlockSizeInBytes = <compressed texel block size taken from the src/dstImage>;
rowLength = (rowLength + compressedTexelBlockWidth - 1) / compressedTexelBlockWidth;
imageHeight = (imageHeight + compressedTexelBlockHeight - 1) / compressedTexelBlockHeight;
address of (x,y,z) = region->bufferOffset + (((z * imageHeight) + y) * rowLength + x) * compressedTexelBlockSizeInBytes;
where x,y,z range from (0,0,0) to region->imageExtent.{width/compressedTexelBlockWidth,height/compressedTexelBlockHeight,depth/compressedTexelBlockDepth}.Copying to or from block-compressed images is typically done in multiples of
the compressed texel block size.
For this reason the imageExtent must be a multiple of the compressed
texel block dimension.
There is one exception to this rule which is required to handle compressed
images created with dimensions that are not a multiple of the compressed
texel block dimensions:
-
If
imageExtent.widthis not a multiple of the compressed texel block width, then (imageExtent.width+imageOffset.x) must equal the image subresource width. -
If
imageExtent.heightis not a multiple of the compressed texel block height, then (imageExtent.height+imageOffset.y) must equal the image subresource height. -
If
imageExtent.depthis not a multiple of the compressed texel block depth, then (imageExtent.depth+imageOffset.z) must equal the image subresource depth.
This allows the last compressed texel block of the image in each non-multiple dimension to be included as a source or destination of the copy.
20.3.2. Buffer and Image Addressing with Rotation
When VkCopyCommandTransformInfoQCOM is in the pNext chain of
VkBufferImageCopy2, a rotated copy is specified.
For both vkCmdCopyImageToBuffer2 and vkCmdCopyBufferToImage2, a
rotation is applied to the region used for image accesses, but a non-rotated
region is used for buffer accesses.
In the case of rotated vkCmdCopyImageToBuffer2, the source image
region is rotated.
In the case of rotated vkCmdCopyBufferToImage2, the destination image
region is rotated.
For a rotated copy, the following description of rotated addressing replaces the description in Buffer and Image Addressing.
The following code computes rotation of unnormalized coordinates.
// Forward rotation of unnormalized coordinates
VkOffset2D RotateUV(VkOffset2D in, VkSurfaceTransformFlagBitsKHR flags)
{
VkOffset2D output;
switch (flags)
{
case VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR:
out.x = in.x;
out.y = in.y;
break;
case VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR:
out.x = -in.y;
out.y = in.x;
break;
case VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR:
out.x = -in.x;
out.y = -in.y;
break;
case VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR:
out.x = in.y;
out.y = -in.x;
break;
}
return out;
}Pseudocode for image/buffer addressing of uncompressed formats with rotation is:
rowLength = region->bufferRowLength;
if (rowLength == 0)
rowLength = region->imageExtent.width;
imageHeight = region->bufferImageHeight;
if (imageHeight == 0)
imageHeight = region->imageExtent.height;
texelBlockSize = <texel block size of the format of the src/dstImage>;
// Buffer addressing is unaffected by rotation:
address of (x,y,z) = region->bufferOffset + (((z * imageHeight) + y) * rowLength + x) * texelBlockSize;
// When copying from buffer to image, the source buffer coordinates x,y,z range from (0,0,0) to
// region->imageExtent.{width,height,depth}. The source extent is rotated by the specified
// VK_SURFACE_TRANSFORM, centered on the imageOffset, to define a rotated destination region.
// For each source buffer texel with coordinates (x,y) the rotated destination image texel has
// coordinates (x',y') defined as:
(x',y')= RotateUV(x,y) + ImageOffset.{x,y}
// When copying from image to buffer, the the destination buffer coordinates x,y,z range from (0,0,0) to
// region->imageExtent.{width,height,depth}. The destination extent is rotated by the specified
// VK_SURFACE_TRANSFORM, centered on the imageOffset, to define a rotated source region. For each destination
// buffer texel with coordinates (x,y) the rotated source image texel has coordinates (x',y') defined as:
(x',y')= RotateUV(x,y) + ImageOffset.{x,y}Note that imageOffset does not affect addressing calculations for
buffer memory.
Instead, bufferOffset can be used to select the starting address in
buffer memory.
20.4. Image Copies with Scaling
To copy regions of a source image into a destination image, potentially performing format conversion, arbitrary scaling, and filtering, call:
// Provided by VK_VERSION_1_0
void vkCmdBlitImage(
VkCommandBuffer commandBuffer,
VkImage srcImage,
VkImageLayout srcImageLayout,
VkImage dstImage,
VkImageLayout dstImageLayout,
uint32_t regionCount,
const VkImageBlit* pRegions,
VkFilter filter);-
commandBufferis the command buffer into which the command will be recorded. -
srcImageis the source image. -
srcImageLayoutis the layout of the source image subresources for the blit. -
dstImageis the destination image. -
dstImageLayoutis the layout of the destination image subresources for the blit. -
regionCountis the number of regions to blit. -
pRegionsis a pointer to an array of VkImageBlit structures specifying the regions to blit. -
filteris a VkFilter specifying the filter to apply if the blits require scaling.
vkCmdBlitImage must not be used for multisampled source or
destination images.
Use vkCmdResolveImage for this purpose.
As the sizes of the source and destination extents can differ in any dimension, texels in the source extent are scaled and filtered to the destination extent. Scaling occurs via the following operations:
-
For each destination texel, the integer coordinate of that texel is converted to an unnormalized texture coordinate, using the effective inverse of the equations described in unnormalized to integer conversion:
-
ubase = i + ½
-
vbase = j + ½
-
wbase = k + ½
-
-
These base coordinates are then offset by the first destination offset:
-
uoffset = ubase - xdst0
-
voffset = vbase - ydst0
-
woffset = wbase - zdst0
-
aoffset = a -
baseArrayCountdst
-
-
The scale is determined from the source and destination regions, and applied to the offset coordinates:
-
scaleu = (xsrc1 - xsrc0) / (xdst1 - xdst0)
-
scalev = (ysrc1 - ysrc0) / (ydst1 - ydst0)
-
scalew = (zsrc1 - zsrc0) / (zdst1 - zdst0)
-
uscaled = uoffset × scaleu
-
vscaled = voffset × scalev
-
wscaled = woffset × scalew
-
-
Finally the source offset is added to the scaled coordinates, to determine the final unnormalized coordinates used to sample from
srcImage:-
u = uscaled + xsrc0
-
v = vscaled + ysrc0
-
w = wscaled + zsrc0
-
q =
mipLevel -
a = aoffset +
baseArrayCountsrc
-
These coordinates are used to sample from the source image, as described in
Image Operations chapter, with the filter mode equal to that
of filter, a mipmap mode of VK_SAMPLER_MIPMAP_MODE_NEAREST and
an address mode of VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE.
Implementations must clamp at the edge of the source image, and may
additionally clamp to the edge of the source region.
|
Note
Due to allowable rounding errors in the generation of the source texture coordinates, it is not always possible to guarantee exactly which source texels will be sampled for a given blit. As rounding errors are implementation-dependent, the exact results of a blitting operation are also implementation-dependent. |
Blits are done layer by layer starting with the baseArrayLayer member
of srcSubresource for the source and dstSubresource for the
destination.
layerCount layers are blitted to the destination image.
When blitting 3D textures, slices in the destination region bounded by
dstOffsets[0].z and dstOffsets[1].z are sampled from slices in
the source region bounded by srcOffsets[0].z and
srcOffsets[1].z.
If the filter parameter is VK_FILTER_LINEAR then the value
sampled from the source image is taken by doing linear filtering using the
interpolated z coordinate represented by w in the previous equations.
If the filter parameter is VK_FILTER_NEAREST then the value
sampled from the source image is taken from the single nearest slice, with
an implementation-dependent arithmetic rounding mode.
The following filtering and conversion rules apply:
-
Integer formats can only be converted to other integer formats with the same signedness.
-
No format conversion is supported between depth/stencil images. The formats must match.
-
Format conversions on unorm, snorm, scaled and packed float formats of the copied aspect of the image are performed by first converting the pixels to float values.
-
For sRGB source formats, nonlinear RGB values are converted to linear representation prior to filtering.
-
After filtering, the float values are first clamped and then cast to the destination image format. In case of sRGB destination format, linear RGB values are converted to nonlinear representation before writing the pixel to the image.
Signed and unsigned integers are converted by first clamping to the representable range of the destination format, then casting the value.
The VkImageBlit structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkImageBlit {
VkImageSubresourceLayers srcSubresource;
VkOffset3D srcOffsets[2];
VkImageSubresourceLayers dstSubresource;
VkOffset3D dstOffsets[2];
} VkImageBlit;-
srcSubresourceis the subresource to blit from. -
srcOffsetsis a pointer to an array of two VkOffset3D structures specifying the bounds of the source region withinsrcSubresource. -
dstSubresourceis the subresource to blit into. -
dstOffsetsis a pointer to an array of two VkOffset3D structures specifying the bounds of the destination region withindstSubresource.
For each element of the pRegions array, a blit operation is performed
for the specified source and destination regions.
A more extensible version of the blit image command is defined below.
To copy regions of a source image into a destination image, potentially performing format conversion, arbitrary scaling, and filtering, call:
// Provided by VK_VERSION_1_3
void vkCmdBlitImage2(
VkCommandBuffer commandBuffer,
const VkBlitImageInfo2* pBlitImageInfo);or the equivalent command
// Provided by VK_KHR_copy_commands2
void vkCmdBlitImage2KHR(
VkCommandBuffer commandBuffer,
const VkBlitImageInfo2* pBlitImageInfo);-
commandBufferis the command buffer into which the command will be recorded. -
pBlitImageInfois a pointer to a VkBlitImageInfo2 structure describing the blit parameters.
This command is functionally identical to vkCmdBlitImage, but includes
extensible sub-structures that include sType and pNext
parameters, allowing them to be more easily extended.
The VkBlitImageInfo2 structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkBlitImageInfo2 {
VkStructureType sType;
const void* pNext;
VkImage srcImage;
VkImageLayout srcImageLayout;
VkImage dstImage;
VkImageLayout dstImageLayout;
uint32_t regionCount;
const VkImageBlit2* pRegions;
VkFilter filter;
} VkBlitImageInfo2;or the equivalent
// Provided by VK_KHR_copy_commands2
typedef VkBlitImageInfo2 VkBlitImageInfo2KHR;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcImageis the source image. -
srcImageLayoutis the layout of the source image subresources for the blit. -
dstImageis the destination image. -
dstImageLayoutis the layout of the destination image subresources for the blit. -
regionCountis the number of regions to blit. -
pRegionsis a pointer to an array of VkImageBlit2 structures specifying the regions to blit. -
filteris a VkFilter specifying the filter to apply if the blits require scaling.
The VkImageBlit2 structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkImageBlit2 {
VkStructureType sType;
const void* pNext;
VkImageSubresourceLayers srcSubresource;
VkOffset3D srcOffsets[2];
VkImageSubresourceLayers dstSubresource;
VkOffset3D dstOffsets[2];
} VkImageBlit2;or the equivalent
// Provided by VK_KHR_copy_commands2
typedef VkImageBlit2 VkImageBlit2KHR;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcSubresourceis the subresource to blit from. -
srcOffsetsis a pointer to an array of two VkOffset3D structures specifying the bounds of the source region withinsrcSubresource. -
dstSubresourceis the subresource to blit into. -
dstOffsetsis a pointer to an array of two VkOffset3D structures specifying the bounds of the destination region withindstSubresource.
For each element of the pRegions array, a blit operation is performed
for the specified source and destination regions.
For vkCmdBlitImage2, each region copied can include a rotation.
To specify a rotated region, add VkCopyCommandTransformInfoQCOM to the
pNext chain of VkImageBlit2.
For each region with a rotation specified,
Image Blits with Scaling and Rotation
specifies how coordinates are rotated prior to sampling from the source
image.
When rotation is specified, the source and destination images must each be
2D images.
They must not be blocked images or have a
multi-planar format.
20.4.1. Image Blits with Scaling and Rotation
When VkCopyCommandTransformInfoQCOM is in the pNext chain of
VkImageBlit2, the specified region is rotated during the blit.
The following description of rotated addressing replaces the description in
vkCmdBlitImage.
The following code computes rotation of normalized coordinates.
// rotation of normalized coordinates
VkOffset2D RotateNormUV(VkOffset2D in, VkSurfaceTransformFlagBitsKHR flags)
{
VkOffset2D output;
switch (flags)
{
case VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR:
out.x = in.x;
out.y = in.y;
break;
case VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR:
out.x = in.y;
out.y = 1.0 - in.x;
break;
case VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR:
out.x = 1.0 - in.x;
out.y = 1.0 - in.y;
break;
case VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR:
out.x = 1.0 - in.y;
out.y = in.x;
break;
}
return out;
}-
For each destination texel, the integer coordinate of that texel is converted to an unnormalized texture coordinate, using the effective inverse of the equations described in unnormalized to integer conversion:
-
ubase = i + ½
-
vbase = j + ½
-
wbase = k + ½
-
-
These base coordinates are then offset by the first destination offset:
-
uoffset = ubase - xdst0
-
voffset = vbase - ydst0
-
woffset = wbase - zdst0
-
aoffset = a -
baseArrayCountdst
-
-
The UV destination coordinates are scaled by the destination region, rotated, and scaled by the source region.
-
udest_scaled = uoffset / (xdst1 - xdst0)
-
vdest_scaled = voffset / (ydst1 - ydst0)
-
(usrc_scaled, vsrc_scaled) =
RotateNormUV(udest_scaled, vdest_scaled,transform) -
uscaled = usrc_scaled × (xSrc1 - xSrc0)
-
vscaled = vsrc_scaled × (ySrc1 - ySrc0)
-
-
The W coordinate is unaffected by rotation. The scale is determined from the ratio of source and destination regions, and applied to the offset coordinate:
-
scalew = (zSrc1 - zSrc0) / (zdst1 - zdst0)
-
wscaled = woffset × scalew
-
-
Finally the source offset is added to the scaled source coordinates, to determine the final unnormalized coordinates used to sample from
srcImage:-
u = uscaled + xSrc0
-
v = vscaled + ySrc0
-
w = wscaled + zSrc0
-
q =
mipLevel -
a = aoffset +
baseArrayCountsrc
-
These coordinates are used to sample from the source image as described for
Image Operations, with the filter mode equal to that of
filter; a mipmap mode of VK_SAMPLER_MIPMAP_MODE_NEAREST; and an
address mode of VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE.
Implementations must clamp at the edge of the source image, and may
additionally clamp to the edge of the source region.
20.5. Resolving Multisample Images
To resolve a multisample color image to a non-multisample color image, call:
// Provided by VK_VERSION_1_0
void vkCmdResolveImage(
VkCommandBuffer commandBuffer,
VkImage srcImage,
VkImageLayout srcImageLayout,
VkImage dstImage,
VkImageLayout dstImageLayout,
uint32_t regionCount,
const VkImageResolve* pRegions);-
commandBufferis the command buffer into which the command will be recorded. -
srcImageis the source image. -
srcImageLayoutis the layout of the source image subresources for the resolve. -
dstImageis the destination image. -
dstImageLayoutis the layout of the destination image subresources for the resolve. -
regionCountis the number of regions to resolve. -
pRegionsis a pointer to an array of VkImageResolve structures specifying the regions to resolve.
During the resolve the samples corresponding to each pixel location in the source are converted to a single sample before being written to the destination. If the source formats are floating-point or normalized types, the sample values for each pixel are resolved in an implementation-dependent manner. If the source formats are integer types, a single sample’s value is selected for each pixel.
srcOffset and dstOffset select the initial x, y, and
z offsets in texels of the sub-regions of the source and destination
image data.
extent is the size in texels of the source image to resolve in
width, height and depth.
Each element of pRegions must be a region that is contained within
its corresponding image.
Resolves are done layer by layer starting with baseArrayLayer member
of srcSubresource for the source and dstSubresource for the
destination.
layerCount layers are resolved to the destination image.
The VkImageResolve structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkImageResolve {
VkImageSubresourceLayers srcSubresource;
VkOffset3D srcOffset;
VkImageSubresourceLayers dstSubresource;
VkOffset3D dstOffset;
VkExtent3D extent;
} VkImageResolve;-
srcSubresourceanddstSubresourceare VkImageSubresourceLayers structures specifying the image subresources of the images used for the source and destination image data, respectively. Resolve of depth/stencil images is not supported. -
srcOffsetanddstOffsetselect the initialx,y, andzoffsets in texels of the sub-regions of the source and destination image data. -
extentis the size in texels of the source image to resolve inwidth,heightanddepth.
A more extensible version of the resolve image command is defined below.
To resolve a multisample image to a non-multisample image, call:
// Provided by VK_VERSION_1_3
void vkCmdResolveImage2(
VkCommandBuffer commandBuffer,
const VkResolveImageInfo2* pResolveImageInfo);or the equivalent command
// Provided by VK_KHR_copy_commands2
void vkCmdResolveImage2KHR(
VkCommandBuffer commandBuffer,
const VkResolveImageInfo2* pResolveImageInfo);-
commandBufferis the command buffer into which the command will be recorded. -
pResolveImageInfois a pointer to a VkResolveImageInfo2 structure describing the resolve parameters.
This command is functionally identical to vkCmdResolveImage, but
includes extensible sub-structures that include sType and pNext
parameters, allowing them to be more easily extended.
The VkResolveImageInfo2 structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkResolveImageInfo2 {
VkStructureType sType;
const void* pNext;
VkImage srcImage;
VkImageLayout srcImageLayout;
VkImage dstImage;
VkImageLayout dstImageLayout;
uint32_t regionCount;
const VkImageResolve2* pRegions;
} VkResolveImageInfo2;or the equivalent
// Provided by VK_KHR_copy_commands2
typedef VkResolveImageInfo2 VkResolveImageInfo2KHR;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcImageis the source image. -
srcImageLayoutis the layout of the source image subresources for the resolve. -
dstImageis the destination image. -
dstImageLayoutis the layout of the destination image subresources for the resolve. -
regionCountis the number of regions to resolve. -
pRegionsis a pointer to an array of VkImageResolve2 structures specifying the regions to resolve.
The VkImageResolve2 structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkImageResolve2 {
VkStructureType sType;
const void* pNext;
VkImageSubresourceLayers srcSubresource;
VkOffset3D srcOffset;
VkImageSubresourceLayers dstSubresource;
VkOffset3D dstOffset;
VkExtent3D extent;
} VkImageResolve2;or the equivalent
// Provided by VK_KHR_copy_commands2
typedef VkImageResolve2 VkImageResolve2KHR;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcSubresourceanddstSubresourceare VkImageSubresourceLayers structures specifying the image subresources of the images used for the source and destination image data, respectively. Resolve of depth/stencil images is not supported. -
srcOffsetanddstOffsetselect the initialx,y, andzoffsets in texels of the sub-regions of the source and destination image data. -
extentis the size in texels of the source image to resolve inwidth,heightanddepth.
20.6. Buffer Markers
To write a 32-bit marker value into a buffer as a pipelined operation, call:
// Provided by VK_KHR_synchronization2 with VK_AMD_buffer_marker
void vkCmdWriteBufferMarker2AMD(
VkCommandBuffer commandBuffer,
VkPipelineStageFlags2 stage,
VkBuffer dstBuffer,
VkDeviceSize dstOffset,
uint32_t marker);-
commandBufferis the command buffer into which the command will be recorded. -
stagespecifies the pipeline stage whose completion triggers the marker write. -
dstBufferis the buffer where the marker will be written. -
dstOffsetis the byte offset into the buffer where the marker will be written. -
markeris the 32-bit value of the marker.
The command will write the 32-bit marker value into the buffer only after
all preceding commands have finished executing up to at least the specified
pipeline stage.
This includes the completion of other preceding
vkCmdWriteBufferMarker2AMD commands so long as their specified
pipeline stages occur either at the same time or earlier than this command’s
specified stage.
While consecutive buffer marker writes with the same stage parameter
implicitly complete in submission order, memory and execution dependencies
between buffer marker writes and other operations must still be explicitly
ordered using synchronization commands.
The access scope for buffer marker writes falls under the
VK_ACCESS_TRANSFER_WRITE_BIT, and the pipeline stages for identifying
the synchronization scope must include both stage and
VK_PIPELINE_STAGE_TRANSFER_BIT.
|
Note
Similar to |
|
Note
Implementations may only support a limited number of pipelined marker write operations in flight at a given time. Thus an excessive number of marker write operations may degrade command execution performance. |
To write a 32-bit marker value into a buffer as a pipelined operation, call:
// Provided by VK_AMD_buffer_marker
void vkCmdWriteBufferMarkerAMD(
VkCommandBuffer commandBuffer,
VkPipelineStageFlagBits pipelineStage,
VkBuffer dstBuffer,
VkDeviceSize dstOffset,
uint32_t marker);-
commandBufferis the command buffer into which the command will be recorded. -
pipelineStageis a VkPipelineStageFlagBits value specifying the pipeline stage whose completion triggers the marker write. -
dstBufferis the buffer where the marker will be written to. -
dstOffsetis the byte offset into the buffer where the marker will be written to. -
markeris the 32-bit value of the marker.
The command will write the 32-bit marker value into the buffer only after
all preceding commands have finished executing up to at least the specified
pipeline stage.
This includes the completion of other preceding
vkCmdWriteBufferMarkerAMD commands so long as their specified pipeline
stages occur either at the same time or earlier than this command’s
specified pipelineStage.
While consecutive buffer marker writes with the same pipelineStage
parameter are implicitly complete in submission order, memory and execution
dependencies between buffer marker writes and other operations must still be
explicitly ordered using synchronization commands.
The access scope for buffer marker writes falls under the
VK_ACCESS_TRANSFER_WRITE_BIT, and the pipeline stages for identifying
the synchronization scope must include both pipelineStage and
VK_PIPELINE_STAGE_TRANSFER_BIT.
|
Note
Similar to |
|
Note
Implementations may only support a limited number of pipelined marker write operations in flight at a given time, thus excessive number of marker write operations may degrade command execution performance. |