Copy Commands
An application can copy buffer and image data using several methods described in this chapter, depending on the type of data transfer.
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.
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);
-
commandBuffer
is the command buffer into which the command will be recorded. -
srcBuffer
is the source buffer. -
dstBuffer
is the destination buffer. -
regionCount
is the number of regions to copy. -
pRegions
is a pointer to an array of VkBufferCopy structures specifying the regions to copy.
Each source region specified by pRegions
is copied from the source
buffer to the destination region of the destination buffer.
If any of the specified regions in srcBuffer
overlaps in memory with
any of the specified regions in dstBuffer
, values read from those
overlapping regions are undefined.
The VkBufferCopy
structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkBufferCopy {
VkDeviceSize srcOffset;
VkDeviceSize dstOffset;
VkDeviceSize size;
} VkBufferCopy;
-
srcOffset
is the starting offset in bytes from the start ofsrcBuffer
. -
dstOffset
is the starting offset in bytes from the start ofdstBuffer
. -
size
is 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);
-
commandBuffer
is the command buffer into which the command will be recorded. -
pCopyBufferInfo
is a pointer to a VkCopyBufferInfo2 structure describing the copy parameters.
Each source region specified by pCopyBufferInfo->pRegions
is copied
from the source buffer to the destination region of the destination buffer.
If any of the specified regions in pCopyBufferInfo->srcBuffer
overlaps
in memory with any of the specified regions in
pCopyBufferInfo->dstBuffer
, values read from those overlapping regions
are undefined.
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
srcBuffer
is the source buffer. -
dstBuffer
is the destination buffer. -
regionCount
is the number of regions to copy. -
pRegions
is a pointer to an array of VkBufferCopy2 structures specifying the regions to copy.
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
srcOffset
is the starting offset in bytes from the start ofsrcBuffer
. -
dstOffset
is the starting offset in bytes from the start ofdstBuffer
. -
size
is the number of bytes to copy.
Copying Data Between Images
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);
-
commandBuffer
is the command buffer into which the command will be recorded. -
srcImage
is the source image. -
srcImageLayout
is the current layout of the source image subresource. -
dstImage
is the destination image. -
dstImageLayout
is the current layout of the destination image subresource. -
regionCount
is the number of regions to copy. -
pRegions
is a pointer to an array of VkImageCopy structures specifying the regions to copy.
Each source region specified by pRegions
is copied from the source
image to the destination region of the destination image.
If any of the specified regions in srcImage
overlaps in memory with
any of the specified regions in dstImage
, values read from those
overlapping regions are undefined.
Multi-planar images can only be copied on a per-plane basis, and the subresources used in each region when copying to or from such images must specify only one plane, though different regions can specify different planes. When copying planes of multi-planar images, the format considered is the compatible format for that plane, rather than the format of the multi-planar image.
If the format of the destination image has a different block extent than the source image (e.g. one is a compressed format), the offset and extent for each of the regions specified is scaled according to the block extents of each format to match in size. Copy regions for each image must be aligned to a multiple of the texel block extent in each dimension, except at the edges of the image, where region extents must match the edge of the image.
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.
If the maintenance5
feature is enabled, all
other combinations are allowed and function as if 1D images are 2D images
with a height of 1.
Otherwise, other combinations of image types are disallowed.
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;
-
srcSubresource
anddstSubresource
are VkImageSubresourceLayers structures specifying the image subresources of the images used for the source and destination image data, respectively. -
srcOffset
anddstOffset
select the initialx
,y
, andz
offsets in texels of the sub-regions of the source and destination image data. -
extent
is the size in texels of the image to copy inwidth
,height
anddepth
.
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;
-
aspectMask
is a combination of VkImageAspectFlagBits, selecting the color, depth and/or stencil aspects to be copied. -
mipLevel
is the mipmap level to copy -
baseArrayLayer
andlayerCount
are 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);
-
commandBuffer
is the command buffer into which the command will be recorded. -
pCopyImageInfo
is 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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
srcImage
is the source image. -
srcImageLayout
is the current layout of the source image subresource. -
dstImage
is the destination image. -
dstImageLayout
is the current layout of the destination image subresource. -
regionCount
is the number of regions to copy. -
pRegions
is 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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
srcSubresource
anddstSubresource
are VkImageSubresourceLayers structures specifying the image subresources of the images used for the source and destination image data, respectively. -
srcOffset
anddstOffset
select the initialx
,y
, andz
offsets in texels of the sub-regions of the source and destination image data. -
extent
is the size in texels of the image to copy inwidth
,height
anddepth
.
Copying Data Between Buffers and Images
Data can be copied between buffers and images, enabling applications to load and store data between images and application-defined offsets in buffer memory.
When copying between a buffer and an image, texels in the image and bytes in the buffer are accessed as follows.
Texels at each coordinate (x,y,z,layer) in the image subresource are accessed, where:
-
x is in the range [
imageOffset.x
,imageOffset.x
+imageExtent.width
), -
y is in the range [
imageOffset.y
,imageOffset.y
+imageExtent.height
), -
z is in the range [
imageOffset.z
,imageOffset.z
+imageExtent.depth
), -
layer is in the range [eq]#[
imageSubresource.baseArrayLayer
,imageSubresource.baseArrayLayer
+imageSubresource.layerCount
)
For each (x,y,z,layer) coordinate in the image, bytes in the buffer are accessed at offsets in the range [texelOffset, texelOffset + blockSize), where:
-
texelOffset =
bufferOffset
+ (⌊(x - imageOffset.x) / blockWidth⌋ × blockSize) + (⌊(y - imageOffset.y) / blockHeight⌋ × rowExtent) + (⌊(z - imageOffset.z) / blockDepth⌋ × sliceExtent) + ((layer -imageSubresource.baseArrayLayer
) × layerExtent) -
rowExtent = ⌈ max(
bufferRowLength
,imageExtent.width
) / blockWidth ⌉ × blockSize -
sliceExtent = ⌈ max(
bufferImageHeight
,imageExtent.height
) / blockHeight ⌉ × rowExtent -
layerExtent = ⌈
imageExtent.depth
/ blockDepth ⌉ × sliceExtent
and where blockSize, blockWidth, blockHeight, and blockDepth are the texel block size and extents of the image’s format.
If a rotation is specified by VkCopyCommandTransformInfoQCOM, the 2D region of the image being addressed is rotated around the offset, and texels at each coordinate (x',y',z',layer) are accessed in the image subresource instead, where:
-
If
VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR
is specified, no rotation is performed:-
x' is in the same range as x
-
y' is in the same range as y
-
-
If
VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR
is specified-
x' is in the range [
imageOffset.x
-imageExtent.height
,imageOffset.x
) -
y' is in the range [
imageOffset.y
,imageOffset.y
+imageExtent.width
)
-
-
If
VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR
is specified:-
x' is in the range [
imageOffset.x
-imageExtent.width
,imageOffset.x
) -
y' is in the range [
imageOffset.y
-imageExtent.height
,imageOffset.y
)
-
-
If
VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR
is specified:-
x' is in the range [
imageOffset.x
,imageOffset.x
+imageExtent.height
) -
y' is in the range [
imageOffset.y
-imageExtent.width
,imageOffset.y
)
-
Buffer addressing calculations are unaffected by this rotation.
When copying between a buffer and the depth or stencil aspect of an image, data in the buffer is assumed to be laid out as separate planes rather than interleaved. Addressing calculations are thus performed for a different format than the base image, according to the aspect, as described in the following table:
Base Format | Depth Aspect Format | Stencil Aspect Format |
---|---|---|
|
|
- |
|
|
- |
|
|
- |
|
- |
|
|
|
|
|
|
|
|
|
|
When copying between a buffer and any plane of a multi-planar image, addressing calculations are performed using the compatible format for that plane, rather than the format of the multi-planar image.
Each texel block is copied from one resource to the other according to the above addressing equations.
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);
-
commandBuffer
is the command buffer into which the command will be recorded. -
srcBuffer
is the source buffer. -
dstImage
is the destination image. -
dstImageLayout
is the layout of the destination image subresources for the copy. -
regionCount
is the number of regions to copy. -
pRegions
is a pointer to an array of VkBufferImageCopy structures specifying the regions to copy.
Each source region specified by pRegions
is copied from the source
buffer to the destination region of the destination image according to the
addressing calculations for each
resource.
If any of the specified regions in srcBuffer
overlaps in memory with
any of the specified regions in dstImage
, values read from those
overlapping regions are undefined.
If any region accesses a depth aspect in dstImage
and the VK_EXT_depth_range_unrestricted
extension is not enabled,
values copied from srcBuffer
outside of the range [0,1] will be
written as undefined values to the destination image.
Copy regions for the image must be aligned to a multiple of the texel block extent in each dimension, except at the edges of the image, where region extents must match the edge of the image.
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);
-
commandBuffer
is the command buffer into which the command will be recorded. -
srcImage
is the source image. -
srcImageLayout
is the layout of the source image subresources for the copy. -
dstBuffer
is the destination buffer. -
regionCount
is the number of regions to copy. -
pRegions
is a pointer to an array of VkBufferImageCopy structures specifying the regions to copy.
Each source region specified by pRegions
is copied from the source
image to the destination region of the destination buffer according to the
addressing calculations for each
resource.
If any of the specified regions in srcImage
overlaps in memory with
any of the specified regions in dstBuffer
, values read from those
overlapping regions are undefined.
Copy regions for the image must be aligned to a multiple of the texel block extent in each dimension, except at the edges of the image, where region extents must match the edge of the image.
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;
-
bufferOffset
is the offset in bytes from the start of the buffer object where the image data is copied from or to. -
bufferRowLength
andbufferImageHeight
specify 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
. -
imageSubresource
is a VkImageSubresourceLayers used to specify the specific image subresources of the image used for the source or destination image data. -
imageOffset
selects the initialx
,y
,z
offsets in texels of the sub-region of the source or destination image data. -
imageExtent
is the size in texels of the image to copy inwidth
,height
anddepth
.
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);
-
commandBuffer
is the command buffer into which the command will be recorded. -
pCopyBufferToImageInfo
is 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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
srcBuffer
is the source buffer. -
dstImage
is the destination image. -
dstImageLayout
is the layout of the destination image subresources for the copy. -
regionCount
is the number of regions to copy. -
pRegions
is 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);
-
commandBuffer
is the command buffer into which the command will be recorded. -
pCopyImageToBufferInfo
is 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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
srcImage
is the source image. -
srcImageLayout
is the layout of the source image subresources for the copy. -
dstBuffer
is the destination buffer. -
regionCount
is the number of regions to copy. -
pRegions
is 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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
bufferOffset
is the offset in bytes from the start of the buffer object where the image data is copied from or to. -
bufferRowLength
andbufferImageHeight
specify 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
. -
imageSubresource
is a VkImageSubresourceLayers used to specify the specific image subresources of the image used for the source or destination image data. -
imageOffset
selects the initialx
,y
,z
offsets in texels of the sub-region of the source or destination image data. -
imageExtent
is the size in texels of the image to copy inwidth
,height
anddepth
.
This structure is functionally identical to VkBufferImageCopy, but
adds sType
and pNext
parameters, allowing it to be more easily
extended.
The VkCopyCommandTransformInfoQCOM
structure is defined as:
// Provided by VK_QCOM_rotated_copy_commands
typedef struct VkCopyCommandTransformInfoQCOM {
VkStructureType sType;
const void* pNext;
VkSurfaceTransformFlagBitsKHR transform;
} VkCopyCommandTransformInfoQCOM;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
transform
is a VkSurfaceTransformFlagBitsKHR value describing the transform to be applied.
Including this structure in the pNext
chain of
VkBufferImageCopy2 defines a rotation to be performed when copying
between an image and a buffer.
Including this structure in the pNext
chain of VkBlitImageInfo2
defines a rotation to be performed when blitting between two images.
If this structure is not specified in either case, the implementation
behaves as if it was specified with a transform
equal to
VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR
.
Specifying a transform for a copy between an image and a buffer rotates the region accessed in the image around the offset. Specifying a transform for a blit performs a similar transform as described in Image Blits with Scaling and Rotation.
Rotations other than VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR
can only
be specified for single-plane 2D images with a 1x1x1
texel block extent.
The following commands can be used to copy between host memory and images. Bytes in host memory and texels in images are accessed as specified in Copying Data Between Buffers and Images, with buffers replaced with host memory.
Copies to and from an image on the host are not internally synchronized. Simultaneous access (involving writes) to overlapping image memory on the host constitutes a data race. |
To copy data from host memory to an image object, call:
// Provided by VK_VERSION_1_4
VkResult vkCopyMemoryToImage(
VkDevice device,
const VkCopyMemoryToImageInfo* pCopyMemoryToImageInfo);
or the equivalent command
// Provided by VK_EXT_host_image_copy
VkResult vkCopyMemoryToImageEXT(
VkDevice device,
const VkCopyMemoryToImageInfo* pCopyMemoryToImageInfo);
-
device
is the device which ownspCopyMemoryToImageInfo->dstImage
. -
pCopyMemoryToImageInfo
is a pointer to a VkCopyMemoryToImageInfo structure describing the copy parameters.
This command is functionally similar to vkCmdCopyBufferToImage2,
except it is executed on the host and reads from host memory instead of a
buffer.
The memory of pCopyMemoryToImageInfo->dstImage
is accessed by the host
as if coherent.
Because queue submissions automatically make host memory visible to the device, there would not be a need for a memory barrier before using the results of this copy operation on the device. |
The VkCopyMemoryToImageInfo
structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkCopyMemoryToImageInfo {
VkStructureType sType;
const void* pNext;
VkHostImageCopyFlags flags;
VkImage dstImage;
VkImageLayout dstImageLayout;
uint32_t regionCount;
const VkMemoryToImageCopy* pRegions;
} VkCopyMemoryToImageInfo;
or the equivalent
// Provided by VK_EXT_host_image_copy
typedef VkCopyMemoryToImageInfo VkCopyMemoryToImageInfoEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is a bitmask of VkHostImageCopyFlagBits values describing additional copy parameters. -
dstImage
is the destination image. -
dstImageLayout
is the layout of the destination image subresources for the copy. -
regionCount
is the number of regions to copy. -
pRegions
is a pointer to an array of VkMemoryToImageCopy structures specifying the regions to copy.
vkCopyMemoryToImage
does not check whether the device memory
associated with dstImage
is currently in use before performing the
copy.
The application must guarantee that any previously submitted command that
reads from or writes to the copy regions has completed before the host
performs the copy.
Copy regions for the image must be aligned to a multiple of the texel block extent in each dimension, except at the edges of the image, where region extents must match the edge of the image.
Each element of VkCopyMemoryToImageInfo::pRegions
is a structure
defined as:
// Provided by VK_VERSION_1_4
typedef struct VkMemoryToImageCopy {
VkStructureType sType;
const void* pNext;
const void* pHostPointer;
uint32_t memoryRowLength;
uint32_t memoryImageHeight;
VkImageSubresourceLayers imageSubresource;
VkOffset3D imageOffset;
VkExtent3D imageExtent;
} VkMemoryToImageCopy;
or the equivalent
// Provided by VK_EXT_host_image_copy
typedef VkMemoryToImageCopy VkMemoryToImageCopyEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
pHostPointer
is the host memory address which is the source of the copy. -
memoryRowLength
andmemoryImageHeight
specify in texels a subregion of a larger two- or three-dimensional image in host memory, and control the addressing calculations. If either of these values is zero, that aspect of the host memory is considered to be tightly packed according to theimageExtent
. -
imageSubresource
is a VkImageSubresourceLayers used to specify the specific image subresources of the image used for the source or destination image data. -
imageOffset
selects the initialx
,y
,z
offsets in texels of the sub-region of the destination image data. -
imageExtent
is the size in texels of the image to copy inwidth
,height
anddepth
.
This structure is functionally similar to VkBufferImageCopy2, except it defines host memory as the source of copy instead of a buffer. In particular, the same data packing rules and restrictions as that structure apply here as well.
To copy data from an image object to host memory, call:
// Provided by VK_VERSION_1_4
VkResult vkCopyImageToMemory(
VkDevice device,
const VkCopyImageToMemoryInfo* pCopyImageToMemoryInfo);
or the equivalent command
// Provided by VK_EXT_host_image_copy
VkResult vkCopyImageToMemoryEXT(
VkDevice device,
const VkCopyImageToMemoryInfo* pCopyImageToMemoryInfo);
-
device
is the device which ownspCopyImageToMemoryInfo->srcImage
. -
pCopyImageToMemoryInfo
is a pointer to a VkCopyImageToMemoryInfo structure describing the copy parameters.
This command is functionally similar to vkCmdCopyImageToBuffer2,
except it is executed on the host and writes to host memory instead of a
buffer.
The memory of pCopyImageToMemoryInfo->srcImage
is accessed by the host
as if coherent.
If the device has written to the image memory, it is not automatically made
available to the host.
Before this copy command can be called, a memory barrier for this image
must have been issued on the device with the second
synchronization scope including
|
The VkCopyImageToMemoryInfo
structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkCopyImageToMemoryInfo {
VkStructureType sType;
const void* pNext;
VkHostImageCopyFlags flags;
VkImage srcImage;
VkImageLayout srcImageLayout;
uint32_t regionCount;
const VkImageToMemoryCopy* pRegions;
} VkCopyImageToMemoryInfo;
or the equivalent
// Provided by VK_EXT_host_image_copy
typedef VkCopyImageToMemoryInfo VkCopyImageToMemoryInfoEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is a bitmask of VkHostImageCopyFlagBits values describing additional copy parameters. -
srcImage
is the source image. -
srcImageLayout
is the layout of the source image subresources for the copy. -
regionCount
is the number of regions to copy. -
pRegions
is a pointer to an array of VkImageToMemoryCopy structures specifying the regions to copy.
vkCopyImageToMemory
does not check whether the device memory
associated with srcImage
is currently in use before performing the
copy.
The application must guarantee that any previously submitted command that
writes to the copy regions has completed before the host performs the copy.
Copy regions for the image must be aligned to a multiple of the texel block extent in each dimension, except at the edges of the image, where region extents must match the edge of the image.
Each element of VkCopyImageToMemoryInfo::pRegions
is a structure
defined as:
// Provided by VK_VERSION_1_4
typedef struct VkImageToMemoryCopy {
VkStructureType sType;
const void* pNext;
void* pHostPointer;
uint32_t memoryRowLength;
uint32_t memoryImageHeight;
VkImageSubresourceLayers imageSubresource;
VkOffset3D imageOffset;
VkExtent3D imageExtent;
} VkImageToMemoryCopy;
or the equivalent
// Provided by VK_EXT_host_image_copy
typedef VkImageToMemoryCopy VkImageToMemoryCopyEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
pHostPointer
is the host memory address which is the destination of the copy. -
memoryRowLength
andmemoryImageHeight
specify in texels a subregion of a larger two- or three-dimensional image in host memory, and control the addressing calculations. If either of these values is zero, that aspect of the host memory is considered to be tightly packed according to theimageExtent
. -
imageSubresource
is a VkImageSubresourceLayers used to specify the specific image subresources of the image used for the source or destination image data. -
imageOffset
selects the initialx
,y
,z
offsets in texels of the sub-region of the source image data. -
imageExtent
is the size in texels of the image to copy inwidth
,height
anddepth
.
This structure is functionally similar to VkBufferImageCopy2, except it defines host memory as the target of copy instead of a buffer. In particular, the same data packing rules and restrictions as that structure apply here as well.
Bits which can be set in VkCopyMemoryToImageInfo::flags
,
VkCopyImageToMemoryInfo::flags
, and
VkCopyImageToImageInfo::flags
, specifying additional copy
parameters are:
// Provided by VK_VERSION_1_4
typedef enum VkHostImageCopyFlagBits {
VK_HOST_IMAGE_COPY_MEMCPY = 0x00000001,
// Provided by VK_EXT_host_image_copy
VK_HOST_IMAGE_COPY_MEMCPY_EXT = VK_HOST_IMAGE_COPY_MEMCPY,
} VkHostImageCopyFlagBits;
or the equivalent
// Provided by VK_EXT_host_image_copy
typedef VkHostImageCopyFlagBits VkHostImageCopyFlagBitsEXT;
-
VK_HOST_IMAGE_COPY_MEMCPY
specifies that no memory layout swizzling is to be applied during data copy. For copies between memory and images, this flag indicates that image data in host memory is swizzled in exactly the same way as the image data on the device. Using this flag indicates that the implementations may use a simple memory copy to transfer the data between the host memory and the device memory. The format of the swizzled data in host memory is platform dependent and is not defined in this specification.
// Provided by VK_VERSION_1_4
typedef VkFlags VkHostImageCopyFlags;
or the equivalent
// Provided by VK_EXT_host_image_copy
typedef VkHostImageCopyFlags VkHostImageCopyFlagsEXT;
VkHostImageCopyFlags
is a bitmask type for setting a mask of zero or
more VkHostImageCopyFlagBits.
To copy data from an image object to another image object using the host, call:
// Provided by VK_VERSION_1_4
VkResult vkCopyImageToImage(
VkDevice device,
const VkCopyImageToImageInfo* pCopyImageToImageInfo);
or the equivalent command
// Provided by VK_EXT_host_image_copy
VkResult vkCopyImageToImageEXT(
VkDevice device,
const VkCopyImageToImageInfo* pCopyImageToImageInfo);
-
device
is the device which ownspCopyImageToImageInfo->srcImage
andpCopyImageToImageInfo->dstImage
. -
pCopyImageToImageInfo
is a pointer to a VkCopyImageToImageInfo structure describing the copy parameters.
This command is functionally similar to vkCmdCopyImage2, except it is
executed on the host.
The memory of pCopyImageToImageInfo->srcImage
and
pCopyImageToImageInfo->dstImage
is accessed by the host as if
coherent.
If the device has written to the memory of
Because queue submissions automatically make host memory visible to the device, there would not be a
need for a memory barrier before using the results of this copy operation in
|
The VkCopyImageToImageInfo
structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkCopyImageToImageInfo {
VkStructureType sType;
const void* pNext;
VkHostImageCopyFlags flags;
VkImage srcImage;
VkImageLayout srcImageLayout;
VkImage dstImage;
VkImageLayout dstImageLayout;
uint32_t regionCount;
const VkImageCopy2* pRegions;
} VkCopyImageToImageInfo;
or the equivalent
// Provided by VK_EXT_host_image_copy
typedef VkCopyImageToImageInfo VkCopyImageToImageInfoEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is a bitmask of VkHostImageCopyFlagBits values describing additional copy parameters. -
srcImage
is the source image. -
srcImageLayout
is the layout of the source image subresources for the copy. -
dstImage
is the destination image. -
dstImageLayout
is the layout of the destination image subresources for the copy. -
regionCount
is the number of regions to copy. -
pRegions
is a pointer to an array of VkImageCopy2 structures specifying the regions to copy.
vkCopyImageToImage
does not check whether the device memory associated
with srcImage
or dstImage
is currently in use before performing
the copy.
The application must guarantee that any previously submitted command that
writes to the copy regions has completed before the host performs the copy.
Indirect Copies
An application can use indirect copies when the copy parameters are not known during the command buffer creation time.
To copy data between two memory regions by specifying copy parameters indirectly in a buffer, call:
// Provided by VK_NV_copy_memory_indirect
void vkCmdCopyMemoryIndirectNV(
VkCommandBuffer commandBuffer,
VkDeviceAddress copyBufferAddress,
uint32_t copyCount,
uint32_t stride);
-
commandBuffer
is the command buffer into which the command will be recorded. -
copyBufferAddress
is the buffer address specifying the copy parameters. This buffer is laid out in memory as an array of VkCopyMemoryIndirectCommandNV structures. -
copyCount
is the number of copies to execute, and can be zero. -
stride
is the stride in bytes between successive sets of copy parameters.
Each region read from copyBufferAddress
is copied from the source
region to the specified destination region.
The results are undefined if any of the source and destination regions
overlap in memory.
The structure describing source and destination memory regions,
VkCopyMemoryIndirectCommandNV
is defined as:
// Provided by VK_NV_copy_memory_indirect
typedef struct VkCopyMemoryIndirectCommandNV {
VkDeviceAddress srcAddress;
VkDeviceAddress dstAddress;
VkDeviceSize size;
} VkCopyMemoryIndirectCommandNV;
-
srcAddress
is the starting address of the source device memory to copy from. -
dstAddress
is the starting address of the destination device memory to copy to. -
size
is the size of the copy in bytes.
To copy data from a memory region to an image object by specifying copy parameters in a buffer, call:
// Provided by VK_NV_copy_memory_indirect
void vkCmdCopyMemoryToImageIndirectNV(
VkCommandBuffer commandBuffer,
VkDeviceAddress copyBufferAddress,
uint32_t copyCount,
uint32_t stride,
VkImage dstImage,
VkImageLayout dstImageLayout,
const VkImageSubresourceLayers* pImageSubresources);
-
commandBuffer
is the command buffer into which the command will be recorded. -
copyBufferAddress
is the buffer address specifying the copy parameters. This buffer is laid out in memory as an array of VkCopyMemoryToImageIndirectCommandNV structures. -
copyCount
is the number of copies to execute, and can be zero. -
stride
is the byte stride between successive sets of copy parameters. -
dstImage
is the destination image. -
dstImageLayout
is the layout of the destination image subresources for the copy. -
pImageSubresources
is a pointer to an array of sizecopyCount
of VkImageSubresourceLayers used to specify the specific image subresource of the destination image data for that copy.
Each region in copyBufferAddress
is copied from the source memory
region to an image region in the destination image.
If the destination image is of type VK_IMAGE_TYPE_3D
, the starting
slice and number of slices to copy are specified in
pImageSubresources->baseArrayLayer
and
pImageSubresources->layerCount
respectively.
The copy must be performed on a queue that supports indirect copy
operations, see VkPhysicalDeviceCopyMemoryIndirectPropertiesNV.
The VkCopyMemoryToImageIndirectCommandNV
is defined as:
// Provided by VK_NV_copy_memory_indirect
typedef struct VkCopyMemoryToImageIndirectCommandNV {
VkDeviceAddress srcAddress;
uint32_t bufferRowLength;
uint32_t bufferImageHeight;
VkImageSubresourceLayers imageSubresource;
VkOffset3D imageOffset;
VkExtent3D imageExtent;
} VkCopyMemoryToImageIndirectCommandNV;
-
srcAddress
is the starting address of the source device memory to copy from. -
bufferRowLength
andbufferImageHeight
specify 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
. -
imageSubresource
is a VkImageSubresourceLayers used to specify the specific image subresources of the image used for the destination image data, which must match the values specified inpImageSubresources
parameter of vkCmdCopyMemoryToImageIndirectNV during command recording. -
imageOffset
selects the initialx
,y
,z
offsets in texels of the sub-region of the destination image data. -
imageExtent
is the size in texels of the destination image inwidth
,height
anddepth
.
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);
-
commandBuffer
is the command buffer into which the command will be recorded. -
srcImage
is the source image. -
srcImageLayout
is the layout of the source image subresources for the blit. -
dstImage
is the destination image. -
dstImageLayout
is the layout of the destination image subresources for the blit. -
regionCount
is the number of regions to blit. -
pRegions
is a pointer to an array of VkImageBlit structures specifying the regions to blit. -
filter
is 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 -
baseArrayCount
dst
-
-
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 +
baseArrayCount
src
-
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.
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;
-
srcSubresource
is the subresource to blit from. -
srcOffsets
is a pointer to an array of two VkOffset3D structures specifying the bounds of the source region withinsrcSubresource
. -
dstSubresource
is the subresource to blit into. -
dstOffsets
is 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);
-
commandBuffer
is the command buffer into which the command will be recorded. -
pBlitImageInfo
is 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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
srcImage
is the source image. -
srcImageLayout
is the layout of the source image subresources for the blit. -
dstImage
is the destination image. -
dstImageLayout
is the layout of the destination image subresources for the blit. -
regionCount
is the number of regions to blit. -
pRegions
is a pointer to an array of VkImageBlit2 structures specifying the regions to blit. -
filter
is a VkFilter specifying the filter to apply if the blits require scaling.
If filter
is VK_FILTER_CUBIC_EXT
and if the pNext
chain of
VkBlitImageInfo2 includes a VkBlitImageCubicWeightsInfoQCOM
structure, then that structure specifies cubic weights are used in the blit.
If that structure is not present, then cubic weights are considered to be
VK_CUBIC_FILTER_WEIGHTS_CATMULL_ROM_QCOM
.
The VkBlitImageCubicWeightsInfoQCOM
structure is defined as:
// Provided by VK_QCOM_filter_cubic_weights
typedef struct VkBlitImageCubicWeightsInfoQCOM {
VkStructureType sType;
const void* pNext;
VkCubicFilterWeightsQCOM cubicWeights;
} VkBlitImageCubicWeightsInfoQCOM;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
cubicWeights
is a VkCubicFilterWeightsQCOM value controlling cubic filter weights for the blit.
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
srcSubresource
is the subresource to blit from. -
srcOffsets
is a pointer to an array of two VkOffset3D structures specifying the bounds of the source region withinsrcSubresource
. -
dstSubresource
is the subresource to blit into. -
dstOffsets
is 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, have a 1x1x1 texel block extent, and only one plane.
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 -
baseArrayCount
dst
-
-
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 +
baseArrayCount
src
-
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.
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);
-
commandBuffer
is the command buffer into which the command will be recorded. -
srcImage
is the source image. -
srcImageLayout
is the layout of the source image subresources for the resolve. -
dstImage
is the destination image. -
dstImageLayout
is the layout of the destination image subresources for the resolve. -
regionCount
is the number of regions to resolve. -
pRegions
is 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;
-
srcSubresource
anddstSubresource
are 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. -
srcOffset
anddstOffset
select the initialx
,y
, andz
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 inwidth
,height
anddepth
.
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);
-
commandBuffer
is the command buffer into which the command will be recorded. -
pResolveImageInfo
is 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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
srcImage
is the source image. -
srcImageLayout
is the layout of the source image subresources for the resolve. -
dstImage
is the destination image. -
dstImageLayout
is the layout of the destination image subresources for the resolve. -
regionCount
is the number of regions to resolve. -
pRegions
is 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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
srcSubresource
anddstSubresource
are 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. -
srcOffset
anddstOffset
select the initialx
,y
, andz
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 inwidth
,height
anddepth
.
Buffer Markers
To write a 32-bit marker value into a buffer as a pipelined operation, call:
// Provided by VK_AMD_buffer_marker with VK_VERSION_1_3 or VK_KHR_synchronization2
void vkCmdWriteBufferMarker2AMD(
VkCommandBuffer commandBuffer,
VkPipelineStageFlags2 stage,
VkBuffer dstBuffer,
VkDeviceSize dstOffset,
uint32_t marker);
-
commandBuffer
is the command buffer into which the command will be recorded. -
stage
specifies the pipeline stage whose completion triggers the marker write. -
dstBuffer
is the buffer where the marker will be written. -
dstOffset
is the byte offset into the buffer where the marker will be written. -
marker
is 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
.
Similar to |
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);
-
commandBuffer
is the command buffer into which the command will be recorded. -
pipelineStage
is a VkPipelineStageFlagBits value specifying the pipeline stage whose completion triggers the marker write. -
dstBuffer
is the buffer where the marker will be written to. -
dstOffset
is the byte offset into the buffer where the marker will be written to. -
marker
is 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
.
Similar to |
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. |