mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-21 10:38:09 +00:00
95dd2f34c5
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
650 lines
27 KiB
Plaintext
650 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::../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.
|
|
|
|
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 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.pname: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.pname: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.pname: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.pname: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.pname: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.pname: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::../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.
|
|
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::../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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
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.
|
|
When copying to a depth aspect, the data in buffer memory must: be in the
|
|
the range latexmath:[$[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.
|
|
|
|
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.pname: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.pname: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.pname: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>>:
|
|
[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].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.
|
|
* 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::../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.
|
|
|
|
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.
|
|
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::../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.
|
|
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[]
|
|
|