1186 lines
56 KiB
Plaintext
1186 lines
56 KiB
Plaintext
// Copyright (c) 2015-2017 The Khronos Group Inc.
|
|
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
|
|
|
[[copies]]
|
|
= 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 fname:vkCmdCopyBuffer and a
|
|
portion of an image can: be copied to another image with
|
|
fname:vkCmdCopyImage.
|
|
Image data can: also be copied to and from buffer memory using
|
|
fname:vkCmdCopyImageToBuffer and fname:vkCmdCopyBufferToImage.
|
|
Image data can: be blitted (with or without scaling and filtering) with
|
|
fname:vkCmdBlitImage.
|
|
Multisampled images can: be resolved to a non-multisampled image with
|
|
fname:vkCmdResolveImage.
|
|
|
|
|
|
== Common Operation
|
|
|
|
Some rules for valid operation are common to all copy commands:
|
|
|
|
* Copy commands must: be recorded outside of a render pass instance.
|
|
* For non-sparse resources, the union of the source regions in a given
|
|
buffer or image must: not overlap the union of the destination regions
|
|
in the same buffer or image.
|
|
* For sparse resources, the set of bytes used by all the source regions
|
|
must: not intersect the set of bytes used by all the destination
|
|
regions.
|
|
* Copy regions must: be non-empty.
|
|
* Regions must: not extend outside the bounds of the buffer or image
|
|
level, except that regions of compressed images can: extend as far as
|
|
the dimension of the image level rounded up to a complete compressed
|
|
texel block.
|
|
* Source image subresources must: be in either the
|
|
ename:VK_IMAGE_LAYOUT_GENERAL or
|
|
ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL layout.
|
|
Destination image subresources must: be in either the
|
|
ename:VK_IMAGE_LAYOUT_GENERAL or
|
|
ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL layout.
|
|
As a consequence, if an image subresource is used as both source and
|
|
destination of a copy, it must: be in the ename:VK_IMAGE_LAYOUT_GENERAL
|
|
layout.
|
|
ifdef::VK_KHR_maintenance1[]
|
|
* Source images must: use a format that supports
|
|
ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR, which is indicated by
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
|
|
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
|
|
optimally tiled images) - as returned by
|
|
flink:vkGetPhysicalDeviceFormatProperties.
|
|
* Destination images must: use a format that supports
|
|
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR, which is indicated by
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
|
|
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
|
|
optimally tiled images) - as returned by
|
|
flink:vkGetPhysicalDeviceFormatProperties.
|
|
endif::VK_KHR_maintenance1[]
|
|
* Source images must: have been created with the
|
|
ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage bit enabled and destination
|
|
images must: have been created with the
|
|
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage bit enabled.
|
|
* Source buffers must: have been created with the
|
|
ename:VK_BUFFER_USAGE_TRANSFER_SRC_BIT usage bit enabled and destination
|
|
buffers must: have been created with the
|
|
ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage bit enabled.
|
|
|
|
All copy commands are treated as ``transfer'' operations for the purposes of
|
|
synchronization barriers.
|
|
|
|
|
|
[[copies-buffers]]
|
|
== Copying Data Between Buffers
|
|
|
|
// refBegin vkCmdCopyBuffer Copy data between buffer regions
|
|
|
|
To copy data between buffer objects, call:
|
|
|
|
include::../api/protos/vkCmdCopyBuffer.txt[]
|
|
|
|
* pname:commandBuffer is the command buffer into which the command will be
|
|
recorded.
|
|
* pname:srcBuffer is the source buffer.
|
|
* pname:dstBuffer is the destination buffer.
|
|
* pname:regionCount is the number of regions to copy.
|
|
* pname:pRegions is a pointer to an array of slink:VkBufferCopy structures
|
|
specifying the regions to copy.
|
|
|
|
Each region in pname:pRegions is copied from the source buffer to the same
|
|
region of the destination buffer.
|
|
pname:srcBuffer and pname:dstBuffer can: be the same buffer or alias the
|
|
same memory, but the result is undefined if the copy regions overlap in
|
|
memory.
|
|
|
|
.Valid Usage
|
|
****
|
|
* The pname:size member of a given element of pname:pRegions must: be
|
|
greater than `0`
|
|
* The pname:srcOffset member of a given element of pname:pRegions must: be
|
|
less than the size of pname:srcBuffer
|
|
* The pname:dstOffset member of a given element of pname:pRegions must: be
|
|
less than the size of pname:dstBuffer
|
|
* The pname:size member of a given element of pname:pRegions must: be less
|
|
than or equal to the size of pname:srcBuffer minus pname:srcOffset
|
|
* The pname:size member of a given element of pname:pRegions must: be less
|
|
than or equal to the size of pname:dstBuffer minus pname:dstOffset
|
|
* The union of the source regions, and the union of the destination
|
|
regions, specified by the elements of pname:pRegions, must: not overlap
|
|
in memory
|
|
* pname:srcBuffer must: have been created with
|
|
ename:VK_BUFFER_USAGE_TRANSFER_SRC_BIT usage flag
|
|
* If pname:srcBuffer is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
* pname:dstBuffer must: have been created with
|
|
ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag
|
|
* If pname:dstBuffer is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
****
|
|
|
|
include::../validity/protos/vkCmdCopyBuffer.txt[]
|
|
|
|
// refBegin VkBufferCopy Structure specifying a buffer copy operation
|
|
|
|
The sname:VkBufferCopy structure is defined as:
|
|
|
|
include::../api/structs/VkBufferCopy.txt[]
|
|
|
|
* pname:srcOffset is the starting offset in bytes from the start of
|
|
pname:srcBuffer.
|
|
* pname:dstOffset is the starting offset in bytes from the start of
|
|
pname:dstBuffer.
|
|
* pname:size is the number of bytes to copy.
|
|
|
|
include::../validity/structs/VkBufferCopy.txt[]
|
|
|
|
|
|
[[copies-images]]
|
|
== Copying Data Between Images
|
|
|
|
fname: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.
|
|
fname:vkCmdCopyImage can: copy between images with different formats,
|
|
provided the formats are compatible as defined below.
|
|
|
|
// refBegin vkCmdCopyImage Copy data between images
|
|
|
|
To copy data between image objects, call:
|
|
|
|
include::../api/protos/vkCmdCopyImage.txt[]
|
|
|
|
* pname:commandBuffer is the command buffer into which the command will be
|
|
recorded.
|
|
* pname:srcImage is the source image.
|
|
* pname:srcImageLayout is the current layout of the source image
|
|
subresource.
|
|
* pname:dstImage is the destination image.
|
|
* pname:dstImageLayout is the current layout of the destination image
|
|
subresource.
|
|
* pname:regionCount is the number of regions to copy.
|
|
* pname:pRegions is a pointer to an array of slink:VkImageCopy structures
|
|
specifying the regions to copy.
|
|
|
|
Each region in pname:pRegions is copied from the source image to the same
|
|
region of the destination image.
|
|
pname:srcImage and pname:dstImage can: be the same image or alias the same
|
|
memory.
|
|
|
|
Copies are done layer by layer starting with pname:baseArrayLayer member of
|
|
pname:srcSubresource for the source and pname:dstSubresource for the
|
|
destination.
|
|
pname:layerCount layers are copied to the destination image.
|
|
|
|
[[copies-images-format-compatibility]]
|
|
The formats of pname:srcImage and pname:dstImage must: be compatible.
|
|
Formats are considered compatible if their element size is the same between
|
|
both formats.
|
|
For example, ename:VK_FORMAT_R8G8B8A8_UNORM is compatible with
|
|
ename:VK_FORMAT_R32_UINT because both texels are 4 bytes in size.
|
|
Depth/stencil formats must: match exactly.
|
|
|
|
fname:vkCmdCopyImage allows copying between size-compatible compressed and
|
|
uncompressed internal formats.
|
|
Formats are size-compatible if the element size of the uncompressed format
|
|
is equal to the element size (compressed 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 4x4 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 4x4 texels (using 4 bits per texel).
|
|
|
|
When copying between compressed and uncompressed formats the pname: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 pname: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 pname:srcImage is compressed, then:
|
|
|
|
* If pname:extent.width is not a multiple of the compressed texel block
|
|
width, then [eq]#(pname:extent.width + pname:srcOffset.x)# must: equal
|
|
the image subresource width.
|
|
* If pname:extent.height is not a multiple of the compressed texel block
|
|
height, then [eq]#(pname:extent.height + pname:srcOffset.y)# must: equal
|
|
the image subresource height.
|
|
* If pname:extent.depth is not a multiple of the compressed texel block
|
|
depth, then [eq]#(pname:extent.depth + pname:srcOffset.z)# must: equal
|
|
the image subresource depth.
|
|
|
|
Similarly, if the pname:dstImage is compressed, then:
|
|
|
|
* If pname:extent.width is not a multiple of the compressed texel block
|
|
width, then [eq]#(pname:extent.width + pname:dstOffset.x)# must: equal
|
|
the image subresource width.
|
|
* If pname:extent.height is not a multiple of the compressed texel block
|
|
height, then [eq]#(pname:extent.height + pname:dstOffset.y)# must: equal
|
|
the image subresource height.
|
|
* If pname:extent.depth is not a multiple of the compressed texel block
|
|
depth, then [eq]#(pname:extent.depth + pname: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.
|
|
|
|
fname:vkCmdCopyImage can: be used to copy image data between multisample
|
|
images, but both images must: have the same number of samples.
|
|
|
|
.Valid Usage
|
|
****
|
|
* The source region specified by a given element of pname:pRegions must:
|
|
be a region that is contained within pname:srcImage
|
|
* The destination region specified by a given element of pname:pRegions
|
|
must: be a region that is contained within pname:dstImage
|
|
* The union of all source regions, and the union of all destination
|
|
regions, specified by the elements of pname:pRegions, must: not overlap
|
|
in memory
|
|
ifdef::VK_KHR_maintenance1[]
|
|
* pname:srcImage must: use a format that supports
|
|
ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR, which is indicated by
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
|
|
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
|
|
optimally tiled images) - as returned by
|
|
flink:vkGetPhysicalDeviceFormatProperties
|
|
endif::VK_KHR_maintenance1[]
|
|
* pname:srcImage must: have been created with
|
|
ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag
|
|
* If pname:srcImage is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
* pname:srcImageLayout must: specify the layout of the image subresources
|
|
of pname:srcImage specified in pname:pRegions at the time this command
|
|
is executed on a sname:VkDevice
|
|
* pname:srcImageLayout must: be either of
|
|
ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or
|
|
ename:VK_IMAGE_LAYOUT_GENERAL
|
|
ifdef::VK_KHR_maintenance1[]
|
|
* pname:dstImage must: use a format that supports
|
|
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR, which is indicated by
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
|
|
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
|
|
optimally tiled images) - as returned by
|
|
flink:vkGetPhysicalDeviceFormatProperties
|
|
endif::VK_KHR_maintenance1[]
|
|
* pname:dstImage must: have been created with
|
|
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
|
|
* If pname:dstImage is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
* pname:dstImageLayout must: specify the layout of the image subresources
|
|
of pname:dstImage specified in pname:pRegions at the time this command
|
|
is executed on a sname:VkDevice
|
|
* pname:dstImageLayout must: be either of
|
|
ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or
|
|
ename:VK_IMAGE_LAYOUT_GENERAL
|
|
* The elink:VkFormat of each of pname:srcImage and pname:dstImage must: be
|
|
compatible, as defined <<copies-images-format-compatibility, below>>
|
|
* The sample count of pname:srcImage and pname:dstImage must: match
|
|
****
|
|
|
|
include::../validity/protos/vkCmdCopyImage.txt[]
|
|
|
|
// refBegin VkImageCopy Structure specifying an image copy operation
|
|
|
|
The sname:VkImageCopy structure is defined as:
|
|
|
|
include::../api/structs/VkImageCopy.txt[]
|
|
|
|
* pname:srcSubresource and pname:dstSubresource are
|
|
slink:VkImageSubresourceLayers structures specifying the image
|
|
subresources of the images used for the source and destination image
|
|
data, respectively.
|
|
* pname:srcOffset and pname:dstOffset select the initial x, y, and z
|
|
offsets in texels of the sub-regions of the source and destination image
|
|
data.
|
|
* pname:extent is the size in texels of the source image to copy in
|
|
pname:width, pname:height and pname:depth.
|
|
|
|
ifdef::VK_KHR_maintenance1[]
|
|
For ename:VK_IMAGE_TYPE_3D images, copies are performed slice by slice
|
|
starting with the pname:z member of the pname:srcOffset or pname:dstOffset,
|
|
and copying pname:depth slices.
|
|
For images with multiple layers, copies are performed layer by layer
|
|
starting with the pname:baseArrayLayer member of the pname:srcSubresource or
|
|
pname:dstSubresource and copying pname:layerCount layers.
|
|
Image data can: be copied between images with different image types.
|
|
If one image is ename:VK_IMAGE_TYPE_3D and the other image is
|
|
ename:VK_IMAGE_TYPE_2D with multiple layers, then each slice is copied to or
|
|
from a different layer.
|
|
endif::VK_KHR_maintenance1[]
|
|
ifndef::VK_KHR_maintenance1[]
|
|
Copies are done layer by layer starting with pname:baseArrayLayer member of
|
|
pname:srcSubresource for the source and pname:dstSubresource for the
|
|
destination.
|
|
pname:layerCount layers are copied to the destination image.
|
|
endif::VK_KHR_maintenance1[]
|
|
|
|
.Valid Usage
|
|
****
|
|
* The pname:aspectMask member of pname:srcSubresource and
|
|
pname:dstSubresource must: match
|
|
ifndef::VK_KHR_maintenance1[]
|
|
* The pname:layerCount member of pname:srcSubresource and
|
|
pname:dstSubresource must: match
|
|
* If either of the calling command's pname:srcImage or pname:dstImage
|
|
parameters are of elink:VkImageType ename:VK_IMAGE_TYPE_3D, the
|
|
pname:baseArrayLayer and pname:layerCount members of both
|
|
pname:srcSubresource and pname:dstSubresource must: be `0` and `1`,
|
|
respectively
|
|
endif::VK_KHR_maintenance1[]
|
|
ifdef::VK_KHR_maintenance1[]
|
|
* The number of slices of the pname:extent (for 3D) or layers of the
|
|
pname:srcSubresource (for non-3D) must: match the number of slices of
|
|
the pname:extent (for 3D) or layers of the pname:dstSubresource (for
|
|
non-3D)
|
|
* If either of the calling command's pname:srcImage or pname:dstImage
|
|
parameters are of elink:VkImageType ename:VK_IMAGE_TYPE_3D, the
|
|
pname:baseArrayLayer and pname:layerCount members of the corresponding
|
|
subresource must: be `0` and `1`, respectively
|
|
endif::VK_KHR_maintenance1[]
|
|
* The pname:aspectMask member of pname:srcSubresource must: specify
|
|
aspects present in the calling command's pname:srcImage
|
|
* The pname:aspectMask member of pname:dstSubresource must: specify
|
|
aspects present in the calling command's pname:dstImage
|
|
* pname:srcOffset.x and (pname:extent.width + pname:srcOffset.x) must:
|
|
both be greater than or equal to `0` and less than or equal to the
|
|
source image subresource width
|
|
* pname:srcOffset.y and (pname:extent.height + pname:srcOffset.y) must:
|
|
both be greater than or equal to `0` and less than or equal to the
|
|
source image subresource height
|
|
* If the calling command's pname:srcImage is of type
|
|
ename:VK_IMAGE_TYPE_1D, then pname:srcOffset.y must: be `0` and
|
|
pname:extent.height must: be `1`.
|
|
* pname:srcOffset.z and (pname:extent.depth + pname:srcOffset.z) must:
|
|
both be greater than or equal to `0` and less than or equal to the
|
|
source image subresource depth
|
|
* If the calling command's pname:srcImage is of type
|
|
ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then pname:srcOffset.z
|
|
must: be `0` and pname:extent.depth must: be `1`.
|
|
* pname:srcSubresource.baseArrayLayer must: be less than and
|
|
(pname:srcSubresource.layerCount + pname:srcSubresource.baseArrayLayer)
|
|
must: be less than or equal to the number of layers in the source image
|
|
* pname:dstOffset.x and (pname:extent.width + pname:dstOffset.x) must:
|
|
both be greater than or equal to `0` and less than or equal to the
|
|
destination image subresource width
|
|
* pname:dstOffset.y and (pname:extent.height + pname:dstOffset.y) must:
|
|
both be greater than or equal to `0` and less than or equal to the
|
|
destination image subresource height
|
|
* If the calling command's pname:dstImage is of type
|
|
ename:VK_IMAGE_TYPE_1D, then pname:dstOffset.y must: be `0` and
|
|
pname:extent.height must: be `1`.
|
|
* pname:dstOffset.z and (pname:extent.depth + pname:dstOffset.z) must:
|
|
both be greater than or equal to `0` and less than or equal to the
|
|
destination image subresource depth
|
|
* If the calling command's pname:dstImage is of type
|
|
ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then pname:dstOffset.z
|
|
must: be `0` and pname:extent.depth must: be `1`.
|
|
* pname:dstSubresource.baseArrayLayer must: be less than and
|
|
(pname:dstSubresource.layerCount + pname:dstSubresource.baseArrayLayer)
|
|
must: be less than or equal to the number of layers in the destination
|
|
image
|
|
* If the calling command's pname:srcImage is a compressed format image:
|
|
** all members of pname:srcOffset must: be a multiple of the corresponding
|
|
dimensions of the compressed texel block
|
|
** pname:extent.width must: be a multiple of the compressed texel block
|
|
width or (pname:extent.width + pname:srcOffset.x) must: equal the
|
|
source image subresource width
|
|
** pname:extent.height must: be a multiple of the compressed texel block
|
|
height or (pname:extent.height + pname:srcOffset.y) must: equal the
|
|
source image subresource height
|
|
** pname:extent.depth must: be a multiple of the compressed texel block
|
|
depth or (pname:extent.depth + pname:srcOffset.z) must: equal the
|
|
source image subresource depth
|
|
* If the calling command's pname:dstImage is a compressed format image:
|
|
** all members of pname:dstOffset must: be a multiple of the corresponding
|
|
dimensions of the compressed texel block
|
|
** pname:extent.width must: be a multiple of the compressed texel block
|
|
width or (pname:extent.width + pname:dstOffset.x) must: equal the
|
|
destination image subresource width
|
|
** pname:extent.height must: be a multiple of the compressed texel block
|
|
height or (pname:extent.height + pname:dstOffset.y) must: equal the
|
|
destination image subresource height
|
|
** pname:extent.depth must: be a multiple of the compressed texel block
|
|
depth or (pname:extent.depth + pname:dstOffset.z) must: equal the
|
|
destination image subresource depth
|
|
* pname:srcOffset, pname:dstOffset, and pname:extent must: respect the
|
|
image transfer granularity requirements of the queue family that it will
|
|
be submitted against, as described in
|
|
<<devsandqueues-physical-device-enumeration,Physical Device
|
|
Enumeration>>
|
|
****
|
|
|
|
include::../validity/structs/VkImageCopy.txt[]
|
|
|
|
// refBegin VkImageSubresourceLayers Structure specifying a image subresource layers
|
|
|
|
The sname:VkImageSubresourceLayers structure is defined as:
|
|
|
|
include::../api/structs/VkImageSubresourceLayers.txt[]
|
|
|
|
* pname:aspectMask is a combination of elink:VkImageAspectFlagBits,
|
|
selecting the color, depth and/or stencil aspects to be copied.
|
|
* pname:mipLevel is the mipmap level to copy from.
|
|
* pname:baseArrayLayer and pname:layerCount are the starting layer and
|
|
number of layers to copy.
|
|
|
|
.Valid Usage
|
|
****
|
|
* If pname:aspectMask contains ename:VK_IMAGE_ASPECT_COLOR_BIT, it must:
|
|
not contain either of ename:VK_IMAGE_ASPECT_DEPTH_BIT or
|
|
ename:VK_IMAGE_ASPECT_STENCIL_BIT
|
|
* pname:aspectMask must: not contain ename:VK_IMAGE_ASPECT_METADATA_BIT
|
|
* pname:mipLevel must: be less than the pname:mipLevels specified in
|
|
slink:VkImageCreateInfo when the image was created
|
|
* [eq]#(pname:baseArrayLayer + pname:layerCount)# must: be less than or
|
|
equal to the pname:arrayLayers specified in slink:VkImageCreateInfo when
|
|
the image was created
|
|
****
|
|
|
|
include::../validity/structs/VkImageSubresourceLayers.txt[]
|
|
|
|
|
|
[[copies-buffers-images]]
|
|
== Copying Data Between Buffers and Images
|
|
|
|
// refBegin vkCmdCopyBufferToImage Copy data from a buffer into an image
|
|
|
|
To copy data from a buffer object to an image object, call:
|
|
|
|
include::../api/protos/vkCmdCopyBufferToImage.txt[]
|
|
|
|
* pname:commandBuffer is the command buffer into which the command will be
|
|
recorded.
|
|
* pname:srcBuffer is the source buffer.
|
|
* pname:dstImage is the destination image.
|
|
* pname:dstImageLayout is the layout of the destination image subresources
|
|
for the copy.
|
|
* pname:regionCount is the number of regions to copy.
|
|
* pname:pRegions is a pointer to an array of slink:VkBufferImageCopy
|
|
structures specifying the regions to copy.
|
|
|
|
Each region in pname:pRegions is copied from the specified region of the
|
|
source buffer to the specified region of the destination image.
|
|
|
|
.Valid Usage
|
|
****
|
|
* The buffer region specified by a given element of pname:pRegions must:
|
|
be a region that is contained within pname:srcBuffer
|
|
* The image region specified by a given element of pname:pRegions must: be
|
|
a region that is contained within pname:dstImage
|
|
* The union of all source regions, and the union of all destination
|
|
regions, specified by the elements of pname:pRegions, must: not overlap
|
|
in memory
|
|
* pname:srcBuffer must: have been created with
|
|
ename:VK_BUFFER_USAGE_TRANSFER_SRC_BIT usage flag
|
|
ifdef::VK_KHR_maintenance1[]
|
|
* pname:dstImage must: use a format that supports
|
|
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR, which is indicated by
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
|
|
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
|
|
optimally tiled images) - as returned by
|
|
flink:vkGetPhysicalDeviceFormatProperties
|
|
endif::VK_KHR_maintenance1[]
|
|
* If pname:srcBuffer is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
* pname:dstImage must: have been created with
|
|
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
|
|
* If pname:dstImage is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
* pname:dstImage must: have a sample count equal to
|
|
ename:VK_SAMPLE_COUNT_1_BIT
|
|
* pname:dstImageLayout must: specify the layout of the image subresources
|
|
of pname:dstImage specified in pname:pRegions at the time this command
|
|
is executed on a sname:VkDevice
|
|
* pname:dstImageLayout must: be either of
|
|
ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or
|
|
ename:VK_IMAGE_LAYOUT_GENERAL
|
|
****
|
|
|
|
include::../validity/protos/vkCmdCopyBufferToImage.txt[]
|
|
|
|
// refBegin vkCmdCopyImageToBuffer Copy image data into a buffer
|
|
|
|
To copy data from an image object to a buffer object, call:
|
|
|
|
include::../api/protos/vkCmdCopyImageToBuffer.txt[]
|
|
|
|
* pname:commandBuffer is the command buffer into which the command will be
|
|
recorded.
|
|
* pname:srcImage is the source image.
|
|
* pname:srcImageLayout is the layout of the source image subresources for
|
|
the copy.
|
|
* pname:dstBuffer is the destination buffer.
|
|
* pname:regionCount is the number of regions to copy.
|
|
* pname:pRegions is a pointer to an array of slink:VkBufferImageCopy
|
|
structures specifying the regions to copy.
|
|
|
|
Each region in pname:pRegions is copied from the specified region of the
|
|
source image to the specified region of the destination buffer.
|
|
|
|
.Valid Usage
|
|
****
|
|
* The image region specified by a given element of pname:pRegions must: be
|
|
a region that is contained within pname:srcImage
|
|
* The buffer region specified by a given element of pname:pRegions must:
|
|
be a region that is contained within pname:dstBuffer
|
|
* The union of all source regions, and the union of all destination
|
|
regions, specified by the elements of pname:pRegions, must: not overlap
|
|
in memory
|
|
ifdef::VK_KHR_maintenance1[]
|
|
* pname:srcImage must: use a format that supports
|
|
ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR, which is indicated by
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
|
|
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
|
|
optimally tiled images) - as returned by
|
|
flink:vkGetPhysicalDeviceFormatProperties
|
|
endif::VK_KHR_maintenance1[]
|
|
* pname:srcImage must: have been created with
|
|
ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag
|
|
* If pname:srcImage is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
* pname:srcImage must: have a sample count equal to
|
|
ename:VK_SAMPLE_COUNT_1_BIT
|
|
* pname:srcImageLayout must: specify the layout of the image subresources
|
|
of pname:srcImage specified in pname:pRegions at the time this command
|
|
is executed on a sname:VkDevice
|
|
* pname:srcImageLayout must: be either of
|
|
ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or
|
|
ename:VK_IMAGE_LAYOUT_GENERAL
|
|
* pname:dstBuffer must: have been created with
|
|
ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag
|
|
* If pname:dstBuffer is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
****
|
|
|
|
include::../validity/protos/vkCmdCopyImageToBuffer.txt[]
|
|
|
|
// refBegin VkBufferImageCopy Structure specifying a buffer image copy operation
|
|
|
|
For both flink:vkCmdCopyBufferToImage and flink:vkCmdCopyImageToBuffer, each
|
|
element of pname:pRegions is a structure defined as:
|
|
|
|
include::../api/structs/VkBufferImageCopy.txt[]
|
|
|
|
* pname:bufferOffset is the offset in bytes from the start of the buffer
|
|
object where the image data is copied from or to.
|
|
* pname:bufferRowLength and pname:bufferImageHeight specify the data in
|
|
buffer memory as a subregion of a larger two- or three-dimensional
|
|
image, and control the addressing calculations of data in buffer memory.
|
|
If either of these values is zero, that aspect of the buffer memory is
|
|
considered to be tightly packed according to the pname:imageExtent.
|
|
* pname:imageSubresource is a slink:VkImageSubresourceLayers used to
|
|
specify the specific image subresources of the image used for the source
|
|
or destination image data.
|
|
* pname:imageOffset selects the initial x, y, z offsets in texels of the
|
|
sub-region of the source or destination image data.
|
|
* pname:imageExtent is the size in texels of the image to copy in
|
|
pname:width, pname:height and pname:depth.
|
|
|
|
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 ename:VK_FORMAT_S8_UINT value per texel.
|
|
* data copied to or from the depth aspect of a ename:VK_FORMAT_D16_UNORM
|
|
or ename:VK_FORMAT_D16_UNORM_S8_UINT format is tightly packed with one
|
|
ename:VK_FORMAT_D16_UNORM value per texel.
|
|
* data copied to or from the depth aspect of a ename:VK_FORMAT_D32_SFLOAT
|
|
or ename:VK_FORMAT_D32_SFLOAT_S8_UINT format is tightly packed with one
|
|
ename:VK_FORMAT_D32_SFLOAT value per texel.
|
|
* data copied to or from the depth aspect of a
|
|
ename:VK_FORMAT_X8_D24_UNORM_PACK32 or ename:VK_FORMAT_D24_UNORM_S8_UINT
|
|
format 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]
|
|
.Note
|
|
====
|
|
To copy both the depth and stencil aspects of a depth/stencil format, two
|
|
entries in pname:pRegions can: be used, where one specifies the depth aspect
|
|
in pname:imageSubresource, and the other specifies the stencil aspect.
|
|
====
|
|
|
|
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, the data in buffer memory must: be in the
|
|
the range [eq]#[0,1]# or undefined results occur.
|
|
|
|
Copies are done layer by layer starting with image layer
|
|
pname:baseArrayLayer member of pname:imageSubresource.
|
|
pname:layerCount layers are copied from the source image or to the
|
|
destination image.
|
|
|
|
.Valid Usage
|
|
****
|
|
* If the the calling command's sname:VkImage parameter's format is not a
|
|
depth/stencil format, then pname:bufferOffset must: be a multiple of the
|
|
format's element size
|
|
* pname:bufferOffset must: be a multiple of `4`
|
|
* pname:bufferRowLength must: be `0`, or greater than or equal to the
|
|
pname:width member of pname:imageExtent
|
|
* pname:bufferImageHeight must: be `0`, or greater than or equal to the
|
|
pname:height member of pname:imageExtent
|
|
* pname:imageOffset.x and (pname:imageExtent.width + pname:imageOffset.x)
|
|
must: both be greater than or equal to `0` and less than or equal to the
|
|
image subresource width
|
|
* pname:imageOffset.y and (imageExtent.height + pname:imageOffset.y) must:
|
|
both be greater than or equal to `0` and less than or equal to the image
|
|
subresource height
|
|
* If the calling command's pname:srcImage (flink:vkCmdCopyImageToBuffer)
|
|
or pname:dstImage (flink:vkCmdCopyBufferToImage) is of type
|
|
ename:VK_IMAGE_TYPE_1D, then pname:imageOffset.y must: be `0` and
|
|
pname:imageExtent.height must: be `1`.
|
|
* pname:imageOffset.z and (imageExtent.depth + pname:imageOffset.z) must:
|
|
both be greater than or equal to `0` and less than or equal to the image
|
|
subresource depth
|
|
* If the calling command's pname:srcImage (flink:vkCmdCopyImageToBuffer)
|
|
or pname:dstImage (flink:vkCmdCopyBufferToImage) is of type
|
|
ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then
|
|
pname:imageOffset.z must: be `0` and pname:imageExtent.depth must: be
|
|
`1`.
|
|
* If the calling command's sname:VkImage parameter is a compressed format
|
|
image:
|
|
** pname:bufferRowLength must: be a multiple of the compressed texel block
|
|
width
|
|
** pname:bufferImageHeight must: be a multiple of the compressed texel
|
|
block height
|
|
** all members of pname:imageOffset must: be a multiple of the
|
|
corresponding dimensions of the compressed texel block
|
|
** pname:bufferOffset must: be a multiple of the compressed texel block
|
|
size in bytes
|
|
** pname:imageExtent.width must: be a multiple of the compressed texel
|
|
block width or (pname:imageExtent.width + pname:imageOffset.x) must:
|
|
equal the image subresource width
|
|
** pname:imageExtent.height must: be a multiple of the compressed texel
|
|
block height or (pname:imageExtent.height + pname:imageOffset.y) must:
|
|
equal the image subresource height
|
|
** pname:imageExtent.depth must: be a multiple of the compressed texel
|
|
block depth or (pname:imageExtent.depth + pname:imageOffset.z) must:
|
|
equal the image subresource depth
|
|
* pname:bufferOffset, pname:bufferRowLength, pname:bufferImageHeight and
|
|
all members of pname:imageOffset and pname:imageExtent must: respect the
|
|
image transfer granularity requirements of the queue family that it will
|
|
be submitted against, as described in
|
|
<<devsandqueues-physical-device-enumeration,Physical Device
|
|
Enumeration>>
|
|
* The pname:aspectMask member of pname:imageSubresource must: specify
|
|
aspects present in the calling command's sname:VkImage parameter
|
|
* The pname:aspectMask member of pname:imageSubresource must: only have a
|
|
single bit set
|
|
* If the calling command's sname:VkImage parameter is of elink:VkImageType
|
|
ename:VK_IMAGE_TYPE_3D, the pname:baseArrayLayer and pname:layerCount
|
|
members of pname:imageSubresource must: be `0` and `1`, respectively
|
|
* When copying to the depth aspect of an image subresource, the data in
|
|
the source buffer must: be in the range [eq]#[0,1]#
|
|
****
|
|
|
|
include::../validity/structs/VkBufferImageCopy.txt[]
|
|
|
|
Pseudocode for image/buffer addressing is:
|
|
|
|
[source,c]
|
|
---------------------------------------------------
|
|
rowLength = region->bufferRowLength;
|
|
if (rowLength == 0)
|
|
rowLength = region->imageExtent.width;
|
|
|
|
imageHeight = region->bufferImageHeight;
|
|
if (imageHeight == 0)
|
|
imageHeight = region->imageExtent.height;
|
|
|
|
elementSize = <element size of the format of the src/dstImage>;
|
|
|
|
address of (x,y,z) = region->bufferOffset + (((z * imageHeight) + y) * rowLength + x) * elementSize;
|
|
|
|
where x,y,z range from (0,0,0) to region->imageExtent.{width,height,depth}.
|
|
---------------------------------------------------
|
|
|
|
Note that pname:imageOffset does not affect addressing calculations for
|
|
buffer memory.
|
|
Instead, pname:bufferOffset can: be used to select the starting address in
|
|
buffer memory.
|
|
|
|
For block-compression 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:
|
|
|
|
[source,c]
|
|
---------------------------------------------------
|
|
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 /= compressedTexelBlockWidth;
|
|
imageHeight /= 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 pname: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 pname:imageExtent.width is not a multiple of the compressed texel
|
|
block width, then [eq]#(pname:imageExtent.width + pname:imageOffset.x)#
|
|
must: equal the image subresource width.
|
|
* If pname:imageExtent.height is not a multiple of the compressed texel
|
|
block height, then [eq]#(pname:imageExtent.height {plus}
|
|
pname:imageOffset.y)# must: equal the image subresource height.
|
|
* If pname:imageExtent.depth is not a multiple of the compressed texel
|
|
block depth, then [eq]#(pname:imageExtent.depth + pname: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.
|
|
|
|
|
|
[[copies-imagescaling]]
|
|
== Image Copies with Scaling
|
|
|
|
// refBegin vkCmdBlitImage Copy regions of an image, potentially performing format conversion,
|
|
|
|
To copy regions of a source image into a destination image, potentially
|
|
performing format conversion, arbitrary scaling, and filtering, call:
|
|
|
|
include::../api/protos/vkCmdBlitImage.txt[]
|
|
|
|
* pname:commandBuffer is the command buffer into which the command will be
|
|
recorded.
|
|
* pname:srcImage is the source image.
|
|
* pname:srcImageLayout is the layout of the source image subresources for
|
|
the blit.
|
|
* pname:dstImage is the destination image.
|
|
* pname:dstImageLayout is the layout of the destination image subresources
|
|
for the blit.
|
|
* pname:regionCount is the number of regions to blit.
|
|
* pname:pRegions is a pointer to an array of slink:VkImageBlit structures
|
|
specifying the regions to blit.
|
|
* pname:filter is a elink:VkFilter specifying the filter to apply if the
|
|
blits require scaling.
|
|
|
|
fname:vkCmdBlitImage must: not be used for multisampled source or
|
|
destination images.
|
|
Use flink: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
|
|
<<textures-unnormalized-to-integer, unnormalized to integer
|
|
conversion>>:
|
|
:: [eq]#u~base~ = i + {onehalf}#
|
|
:: [eq]#v~base~ = j + {onehalf}#
|
|
:: [eq]#w~base~ = k + {onehalf}#
|
|
* These base coordinates are then offset by the first destination
|
|
offset:
|
|
:: [eq]#u~offset~ = u~base~ - x~dst0~#
|
|
:: [eq]#v~offset~ = v~base~ - y~dst0~#
|
|
:: [eq]#w~offset~ = w~base~ - z~dst0~#
|
|
:: [eq]#a~offset~ = a - pname:baseArrayCount~dst~#
|
|
* The scale is determined from the source and destination regions, and
|
|
applied to the offset coordinates:
|
|
:: [eq]#scale_u = (x~src1~ - x~src0~) / (x~dst1~ - x~dst0~)#
|
|
:: [eq]#scale_v = (y~src1~ - y~src0~) / (y~dst1~ - y~dst0~)#
|
|
:: [eq]#scale_w = (z~src1~ - z~src0~) / (z~dst1~ - z~dst0~)#
|
|
:: [eq]#u~scaled~ = u~offset~ * scale~u~#
|
|
:: [eq]#v~scaled~ = v~offset~ * scale~v~#
|
|
:: [eq]#w~scaled~ = w~offset~ * scale~w~#
|
|
* Finally the source offset is added to the scaled coordinates, to
|
|
determine the final unnormalized coordinates used to sample from
|
|
pname:srcImage: +
|
|
:: [eq]#u = u~scaled~ + x~src0~#
|
|
:: [eq]#v = v~scaled~ + y~src0~#
|
|
:: [eq]#w = w~scaled~ + z~src0~#
|
|
:: [eq]#q = pname:mipLevel#
|
|
:: [eq]#a = a~offset~ + pname:baseArrayCount~src~#
|
|
|
|
These coordinates are used to sample from the source image, as described in
|
|
<<textures, Image Operations chapter>>, with the filter mode equal to that
|
|
of pname:filter, a mipmap mode of ename:VK_SAMPLER_MIPMAP_MODE_NEAREST and
|
|
an address mode of ename: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]
|
|
.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 pname:baseArrayLayer member
|
|
of pname:srcSubresource for the source and pname:dstSubresource for the
|
|
destination.
|
|
pname:layerCount layers are blitted to the destination image.
|
|
|
|
3D textures are blitted slice by slice.
|
|
Slices in the source region bounded by pname:srcOffsets[0].pname:z and
|
|
pname:srcOffsets[1].pname:z are copied to slices in the destination region
|
|
bounded by pname:dstOffsets[0].pname:z and pname:dstOffsets[1].pname:z.
|
|
For each destination slice, a source z coordinate is linearly interpolated
|
|
between pname:srcOffsets[0].pname:z and pname:srcOffsets[1].pname:z.
|
|
If the pname:filter parameter is ename:VK_FILTER_LINEAR then the value
|
|
sampled from the source image is taken by doing linear filtering using the
|
|
interpolated z coordinate.
|
|
If pname:filter parameter is ename:VK_FILTER_NEAREST then value sampled from
|
|
the source image is taken from the single nearest slice (with undefined
|
|
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, unscaled 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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* The source region specified by a given element of pname:pRegions must:
|
|
be a region that is contained within pname:srcImage
|
|
* The destination region specified by a given element of pname:pRegions
|
|
must: be a region that is contained within pname:dstImage
|
|
* The union of all destination regions, specified by the elements of
|
|
pname:pRegions, must: not overlap in memory with any texel that may: be
|
|
sampled during the blit operation
|
|
* pname:srcImage must: use a format that supports
|
|
ename:VK_FORMAT_FEATURE_BLIT_SRC_BIT, which is indicated by
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (for linear tiled
|
|
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
|
|
optimally tiled images) - as returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties
|
|
* pname:srcImage must: have been created with
|
|
ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag
|
|
* If pname:srcImage is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
* pname:srcImageLayout must: specify the layout of the image subresources
|
|
of pname:srcImage specified in pname:pRegions at the time this command
|
|
is executed on a sname:VkDevice
|
|
* pname:srcImageLayout must: be either of
|
|
ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or
|
|
ename:VK_IMAGE_LAYOUT_GENERAL
|
|
* pname:dstImage must: use a format that supports
|
|
ename:VK_FORMAT_FEATURE_BLIT_DST_BIT, which is indicated by
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (for linear tiled
|
|
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
|
|
optimally tiled images) - as returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties
|
|
* pname:dstImage must: have been created with
|
|
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
|
|
* If pname:dstImage is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
* pname:dstImageLayout must: specify the layout of the image subresources
|
|
of pname:dstImage specified in pname:pRegions at the time this command
|
|
is executed on a sname:VkDevice
|
|
* pname:dstImageLayout must: be either of
|
|
ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or
|
|
ename:VK_IMAGE_LAYOUT_GENERAL
|
|
* The sample count of pname:srcImage and pname:dstImage must: both be
|
|
equal to ename:VK_SAMPLE_COUNT_1_BIT
|
|
* If either of pname:srcImage or pname:dstImage was created with a signed
|
|
integer elink:VkFormat, the other must: also have been created with a
|
|
signed integer elink:VkFormat
|
|
* If either of pname:srcImage or pname:dstImage was created with an
|
|
unsigned integer elink:VkFormat, the other must: also have been created
|
|
with an unsigned integer elink:VkFormat
|
|
* If either of pname:srcImage or pname:dstImage was created with a
|
|
depth/stencil format, the other must: have exactly the same format
|
|
* If pname:srcImage was created with a depth/stencil format, pname:filter
|
|
must: be ename:VK_FILTER_NEAREST
|
|
* pname:srcImage must: have been created with a pname:samples value of
|
|
ename:VK_SAMPLE_COUNT_1_BIT
|
|
* pname:dstImage must: have been created with a pname:samples value of
|
|
ename:VK_SAMPLE_COUNT_1_BIT
|
|
* If pname:filter is ename:VK_FILTER_LINEAR, pname:srcImage must: be of a
|
|
format which supports linear filtering, as specified by the
|
|
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (for a linear
|
|
image) or sname:VkFormatProperties::pname:optimalTilingFeatures(for an
|
|
optimally tiled image) returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties
|
|
ifdef::VK_IMG_filter_cubic[]
|
|
* If pname:filter is ename:VK_FILTER_CUBIC_IMG, pname:srcImage must: be of
|
|
a format which supports cubic filtering, as specified by the
|
|
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG flag in
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (for a linear
|
|
image) or sname:VkFormatProperties::pname:optimalTilingFeatures(for an
|
|
optimally tiled image) returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties
|
|
* If pname:filter is ename:VK_FILTER_CUBIC_IMG, pname:srcImage must: have
|
|
a elink:VkImageType of ename:VK_IMAGE_TYPE_3D
|
|
endif::VK_IMG_filter_cubic[]
|
|
****
|
|
|
|
include::../validity/protos/vkCmdBlitImage.txt[]
|
|
|
|
// refBegin VkImageBlit Structure specifying an image blit operation
|
|
|
|
The sname:VkImageBlit structure is defined as:
|
|
|
|
include::../api/structs/VkImageBlit.txt[]
|
|
|
|
* pname:srcSubresource is the subresource to blit from.
|
|
* pname:srcOffsets is an array of two slink:VkOffset3D structures
|
|
specifying the bounds of the source region within pname:srcSubresource.
|
|
* pname:dstSubresource is the subresource to blit into.
|
|
* pname:dstOffsets is an array of two slink:VkOffset3D structures
|
|
specifying the bounds of the destination region within
|
|
pname:dstSubresource.
|
|
|
|
For each element of the pname:pRegions array, a blit operation is performed
|
|
the specified source and destination regions.
|
|
|
|
.Valid Usage
|
|
****
|
|
* The pname:aspectMask member of pname:srcSubresource and
|
|
pname:dstSubresource must: match
|
|
* The pname:layerCount member of pname:srcSubresource and
|
|
pname:dstSubresource must: match
|
|
* If either of the calling command's pname:srcImage or pname:dstImage
|
|
parameters are of elink:VkImageType ename:VK_IMAGE_TYPE_3D, the
|
|
pname:baseArrayLayer and pname:layerCount members of both
|
|
pname:srcSubresource and pname:dstSubresource must: be `0` and `1`,
|
|
respectively
|
|
* The pname:aspectMask member of pname:srcSubresource must: specify
|
|
aspects present in the calling command's pname:srcImage
|
|
* The pname:aspectMask member of pname:dstSubresource must: specify
|
|
aspects present in the calling command's pname:dstImage
|
|
* The pname:layerCount member of pname:dstSubresource must: be equal to
|
|
the pname:layerCount member of pname:srcSubresource
|
|
* pname:srcOffset[0].pname:x and pname:srcOffset[1].pname:x must: both be
|
|
greater than or equal to `0` and less than or equal to the source image
|
|
subresource width
|
|
* pname:srcOffset[0].pname:y and pname:srcOffset[1].pname:y must: both be
|
|
greater than or equal to `0` and less than or equal to the source image
|
|
subresource height
|
|
* If the calling command's pname:srcImage is of type
|
|
ename:VK_IMAGE_TYPE_1D, then pname:srcOffset[0].y must: be `0` and
|
|
pname:srcOffset[1].y must: be `1`.
|
|
* pname:srcOffset[0].pname:z and pname:srcOffset[1].pname:z must: both be
|
|
greater than or equal to `0` and less than or equal to the source image
|
|
subresource depth
|
|
* If the calling command's pname:srcImage is of type
|
|
ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then
|
|
pname:srcOffset[0].z must: be `0` and pname:srcOffset[1].z must: be `1`.
|
|
* pname:dstOffset[0].pname:x and pname:dstOffset[1].pname:x must: both be
|
|
greater than or equal to `0` and less than or equal to the destination
|
|
image subresource width
|
|
* pname:dstOffset[0].pname:y and pname:dstOffset[1].pname:y must: both be
|
|
greater than or equal to `0` and less than or equal to the destination
|
|
image subresource height
|
|
* If the calling command's pname:dstImage is of type
|
|
ename:VK_IMAGE_TYPE_1D, then pname:dstOffset[0].y must: be `0` and
|
|
pname:dstOffset[1].y must: be `1`.
|
|
* pname:dstOffset[0].pname:z and pname:dstOffset[1].pname:z must: both be
|
|
greater than or equal to `0` and less than or equal to the destination
|
|
image subresource depth
|
|
* If the calling command's pname:dstImage is of type
|
|
ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then
|
|
pname:dstOffset[0].z must: be `0` and pname:dstOffset[1].z must: be `1`.
|
|
****
|
|
|
|
include::../validity/structs/VkImageBlit.txt[]
|
|
|
|
|
|
[[copies-resolve]]
|
|
== Resolving Multisample Images
|
|
|
|
// refBegin vkCmdResolveImage Resolve regions of an image
|
|
|
|
To resolve a multisample image to a non-multisample image, call:
|
|
|
|
include::../api/protos/vkCmdResolveImage.txt[]
|
|
|
|
* pname:commandBuffer is the command buffer into which the command will be
|
|
recorded.
|
|
* pname:srcImage is the source image.
|
|
* pname:srcImageLayout is the layout of the source image subresources for
|
|
the resolve.
|
|
* pname:dstImage is the destination image.
|
|
* pname:dstImageLayout is the layout of the destination image subresources
|
|
for the resolve.
|
|
* pname:regionCount is the number of regions to resolve.
|
|
* pname:pRegions is a pointer to an array of slink: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.
|
|
|
|
pname:srcOffset and pname:dstOffset select the initial x, y, and z offsets
|
|
in texels of the sub-regions of the source and destination image data.
|
|
pname:extent is the size in texels of the source image to resolve in
|
|
pname:width, pname:height and pname:depth.
|
|
|
|
Resolves are done layer by layer starting with pname:baseArrayLayer member
|
|
of pname:srcSubresource for the source and pname:dstSubresource for the
|
|
destination.
|
|
pname:layerCount layers are resolved to the destination image.
|
|
|
|
.Valid Usage
|
|
****
|
|
* The source region specified by a given element of pname:pRegions must:
|
|
be a region that is contained within pname:srcImage
|
|
* The destination region specified by a given element of pname:pRegions
|
|
must: be a region that is contained within pname:dstImage
|
|
* The union of all source regions, and the union of all destination
|
|
regions, specified by the elements of pname:pRegions, must: not overlap
|
|
in memory
|
|
* If pname:srcImage is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
* pname:srcImage must: have a sample count equal to any valid sample count
|
|
value other than ename:VK_SAMPLE_COUNT_1_BIT
|
|
* If pname:dstImage is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
* pname:dstImage must: have a sample count equal to
|
|
ename:VK_SAMPLE_COUNT_1_BIT
|
|
* pname:srcImageLayout must: specify the layout of the image subresources
|
|
of pname:srcImage specified in pname:pRegions at the time this command
|
|
is executed on a sname:VkDevice
|
|
* pname:srcImageLayout must: be either of
|
|
ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or
|
|
ename:VK_IMAGE_LAYOUT_GENERAL
|
|
* pname:dstImageLayout must: specify the layout of the image subresources
|
|
of pname:dstImage specified in pname:pRegions at the time this command
|
|
is executed on a sname:VkDevice
|
|
* pname:dstImageLayout must: be either of
|
|
ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or
|
|
ename:VK_IMAGE_LAYOUT_GENERAL
|
|
* If pname:dstImage was created with pname:tiling equal to
|
|
ename:VK_IMAGE_TILING_LINEAR, pname:dstImage must: have been created
|
|
with a pname:format that supports being a color attachment, as specified
|
|
by the ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT flag in
|
|
sname:VkFormatProperties::pname:linearTilingFeatures returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties
|
|
* If pname:dstImage was created with pname:tiling equal to
|
|
ename:VK_IMAGE_TILING_OPTIMAL, pname:dstImage must: have been created
|
|
with a pname:format that supports being a color attachment, as specified
|
|
by the ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT flag in
|
|
sname:VkFormatProperties::pname:optimalTilingFeatures returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties
|
|
****
|
|
|
|
include::../validity/protos/vkCmdResolveImage.txt[]
|
|
|
|
// refBegin VkImageResolve Structure specifying an image resolve operation
|
|
|
|
The sname:VkImageResolve structure is defined as:
|
|
|
|
include::../api/structs/VkImageResolve.txt[]
|
|
|
|
* pname:srcSubresource and pname:dstSubresource are
|
|
slink: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.
|
|
* pname:srcOffset and pname:dstOffset select the initial x, y, and z
|
|
offsets in texels of the sub-regions of the source and destination image
|
|
data.
|
|
* pname:extent is the size in texels of the source image to resolve in
|
|
pname:width, pname:height and pname:depth.
|
|
|
|
.Valid Usage
|
|
****
|
|
* The pname:aspectMask member of pname:srcSubresource and
|
|
pname:dstSubresource must: only contain ename:VK_IMAGE_ASPECT_COLOR_BIT
|
|
* The pname:layerCount member of pname:srcSubresource and
|
|
pname:dstSubresource must: match
|
|
* If either of the calling command's pname:srcImage or pname:dstImage
|
|
parameters are of elink:VkImageType ename:VK_IMAGE_TYPE_3D, the
|
|
pname:baseArrayLayer and pname:layerCount members of both
|
|
pname:srcSubresource and pname:dstSubresource must: be `0` and `1`,
|
|
respectively
|
|
* pname:srcOffset.x and (pname:extent.width + pname:srcOffset.x) must:
|
|
both be greater than or equal to `0` and less than or equal to the
|
|
source image subresource width
|
|
* pname:srcOffset.y and (pname:extent.height + pname:srcOffset.y) must:
|
|
both be greater than or equal to `0` and less than or equal to the
|
|
source image subresource height
|
|
* If the calling command's pname:srcImage is of type
|
|
ename:VK_IMAGE_TYPE_1D, then pname:srcOffset.y must: be `0` and
|
|
pname:extent.height must: be `1`.
|
|
* pname:srcOffset.z and (pname:extent.depth + pname:srcOffset.z) must:
|
|
both be greater than or equal to `0` and less than or equal to the
|
|
source image subresource depth
|
|
* If the calling command's pname:srcImage is of type
|
|
ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then pname:srcOffset.z
|
|
must: be `0` and pname:extent.depth must: be `1`.
|
|
* pname:dstOffset.x and (pname:extent.width + pname:dstOffset.x) must:
|
|
both be greater than or equal to `0` and less than or equal to the
|
|
destination image subresource width
|
|
* pname:dstOffset.y and (pname:extent.height + pname:dstOffset.y) must:
|
|
both be greater than or equal to `0` and less than or equal to the
|
|
destination image subresource height
|
|
* If the calling command's pname:dstImage is of type
|
|
ename:VK_IMAGE_TYPE_1D, then pname:dstOffset.y must: be `0` and
|
|
pname:extent.height must: be `1`.
|
|
* pname:dstOffset.z and (pname:extent.depth + pname:dstOffset.z) must:
|
|
both be greater than or equal to `0` and less than or equal to the
|
|
destination image subresource depth
|
|
* If the calling command's pname:dstImage is of type
|
|
ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then pname:dstOffset.z
|
|
must: be `0` and pname:extent.depth must: be `1`.
|
|
****
|
|
|
|
include::../validity/structs/VkImageResolve.txt[]
|
|
|