618 lines
27 KiB
Plaintext
618 lines
27 KiB
Plaintext
// Copyright (c) 2015-2016 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.
|
|
* 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::../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.
|
|
|
|
include::../validity/protos/vkCmdCopyBuffer.txt[]
|
|
|
|
// refBegin VkBufferCopy - Structure specifying a buffer copy operation
|
|
|
|
The sname:VkBufferCopy structure is defined as:
|
|
|
|
include::../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::../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 texel size in bytes 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 texel
|
|
size of the uncompressed format is equal to the compressed texel block size in
|
|
bytes 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. 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 and if pname:extent.width is not a
|
|
multiple of the compressed texel block width then (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 (pname:extent.height + pname:srcOffset.y) must: equal the image
|
|
subresource height and if pname:extent.depth is not a multiple of the
|
|
compressed texel block depth then (pname:extent.depth + pname:srcOffset.z)
|
|
must: equal the image subresource depth. Similarly, if the pname:dstImage is
|
|
compressed and if pname:extent.width is not a multiple of the compressed
|
|
texel block width then (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 (pname:extent.height + pname:dstOffset.y)
|
|
must: equal the image subresource height and if pname:extent.depth is not a
|
|
multiple of the compressed texel block depth then (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.
|
|
|
|
include::../validity/protos/vkCmdCopyImage.txt[]
|
|
|
|
// refBegin VkImageCopy - Structure specifying an image copy operation
|
|
|
|
The sname:VkImageCopy structure is defined as:
|
|
|
|
include::../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. 1D images use only pname:x
|
|
and pname:width. 2D images use pname:x, pname:y, pname:width and
|
|
pname:height. 3D images use pname:x, pname:y, pname:z, pname:width,
|
|
pname:height and pname:depth.
|
|
|
|
include::../validity/structs/VkImageCopy.txt[]
|
|
|
|
// refBegin VkImageSubresourceLayers - Structure specifying a image subresource layers
|
|
|
|
The sname:VkImageSubresourceLayers structure is defined as:
|
|
|
|
include::../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.
|
|
|
|
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::../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.
|
|
|
|
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::../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.
|
|
|
|
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::../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 an 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. 1D images use only pname:x
|
|
and pname:width. 2D images use pname:x, pname:y, pname:width and
|
|
pname:height. 3D images use pname:x, pname:y, pname:z, 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.
|
|
|
|
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.
|
|
|
|
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;
|
|
|
|
texelSize = <texel size taken from the src/dstImage>;
|
|
|
|
address of (x,y,z) = region->bufferOffset + (((z * imageHeight) + y) * rowLength + x) * texelSize;
|
|
|
|
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. 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 (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 (pname:imageExtent.height +
|
|
pname:imageOffset.y) must: equal the image subresource height and if
|
|
pname:imageExtent.depth is not a multiple of the compressed texel block
|
|
depth then (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::../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 mustnot: 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>>:
|
|
[latexmath]
|
|
++++++++++++++++++++++++
|
|
\begin{align*}
|
|
u_{base} & = i + \frac{1}{2}\\
|
|
v_{base} & = j + \frac{1}{2}\\
|
|
w_{base} & = k + \frac{1}{2}\\
|
|
\end{align*}
|
|
++++++++++++++++++++++++
|
|
* These base coordinates are then offset by the first destination offset:
|
|
[latexmath]
|
|
++++++++++++++++++++++++
|
|
\begin{align*}
|
|
u_{offset} & = u_{base} - x_{dst_0}\\
|
|
v_{offset} & = v_{base} - y_{dst_0}\\
|
|
w_{offset} & = w_{base} - z_{dst_0}\\
|
|
a_{offset} & = a - baseArrayCount_{dst}
|
|
\end{align*}
|
|
++++++++++++++++++++++++
|
|
* The scale is determined from the source and destination regions, and
|
|
applied to the offset coordinates:
|
|
[latexmath]
|
|
++++++++++++++++++++++++
|
|
\begin{align*}
|
|
scale_u & = \frac{x_{src_1} - x_{src_0}}{x_{dst_1} - x_{dst_0}}\\
|
|
scale_v & = \frac{y_{src_1} - y_{src_0}}{y_{dst_1} - y_{dst_0}}\\
|
|
scale_w & = \frac{z_{src_1} - z_{src_0}}{z_{dst_1} - z_{dst_0}}\\
|
|
\\
|
|
u_{scaled} & = u_{offset} * scale_u\\
|
|
v_{scaled} & = v_{offset} * scale_v\\
|
|
w_{scaled} & = w_{offset} * scale_w
|
|
\end{align*}
|
|
++++++++++++++++++++++++
|
|
* Finally the source offset is added to the scaled coordinates, to
|
|
determine the final unnormalized coordinates used to sample from
|
|
pname:srcImage:
|
|
[latexmath]
|
|
++++++++++++++++++++++++
|
|
\begin{align*}
|
|
u & = u_{scaled} + x_{src_0}\\
|
|
v & = v_{scaled} + y_{src_0}\\
|
|
w & = w_{scaled} + z_{src_0}\\
|
|
q & = mipLevel\\
|
|
a & = a_{offset} + baseArrayCount_{src}
|
|
\end{align*}
|
|
++++++++++++++++++++++++
|
|
|
|
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].z and pname:srcOffsets[1].z are copied to slices in
|
|
the destination region bounded by pname:dstOffsets[0].z and
|
|
pname:dstOffsets[1].z. For each destination slice, a source z coordinate is
|
|
linearly interpolated between pname:srcOffsets[0].z and
|
|
pname:srcOffsets[1].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.
|
|
* In case of sRGB source format, 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.
|
|
|
|
include::../validity/protos/vkCmdBlitImage.txt[]
|
|
|
|
// refBegin VkImageBlit - Structure specifying an image blit operation
|
|
|
|
The sname:VkImageBlit structure is defined as:
|
|
|
|
include::../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.
|
|
|
|
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::../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. 1D images use
|
|
only pname:x and pname:width. 2D images use pname:x, pname:y, pname:width
|
|
and pname:height. 3D images use pname:x, pname:y, pname:z, 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.
|
|
|
|
include::../validity/protos/vkCmdResolveImage.txt[]
|
|
|
|
// refBegin VkImageResolve - Structure specifying an image resolve operation
|
|
|
|
The sname:VkImageResolve structure is defined as:
|
|
|
|
include::../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. 1D images use only pname:x
|
|
and pname:width. 2D images use pname:x, pname:y, pname:width and
|
|
pname:height. 3D images use pname:x, pname:y, pname:z, pname:width,
|
|
pname:height and pname:depth.
|
|
|
|
include::../validity/structs/VkImageResolve.txt[]
|
|
|