178 lines
6.3 KiB
Plaintext
178 lines
6.3 KiB
Plaintext
// Copyright (c) 2014-2016 Khronos Group. This work is licensed under a
|
|
// Creative Commons Attribution 4.0 International License; see
|
|
// http://creativecommons.org/licenses/by/4.0/
|
|
|
|
vkCmdBlitImage(3)
|
|
=================
|
|
|
|
Name
|
|
----
|
|
vkCmdBlitImage - Copy regions of an image, potentially performing format conversion,
|
|
|
|
C Specification
|
|
---------------
|
|
|
|
// 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[]
|
|
|
|
|
|
Parameters
|
|
----------
|
|
|
|
* 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.
|
|
|
|
|
|
Description
|
|
-----------
|
|
|
|
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[]
|
|
|
|
|
|
See Also
|
|
--------
|
|
|
|
slink:VkCommandBuffer, elink:VkFilter, slink:VkImage, slink:VkImageBlit, elink:VkImageLayout
|
|
|
|
|
|
Document Notes
|
|
--------------
|
|
|
|
For more information, see the Vulkan Specification at URL
|
|
|
|
https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#vkCmdBlitImage
|
|
|
|
This page is extracted from the Vulkan Specification.
|
|
Fixes and changes should be made to the Specification,not directly.
|
|
|
|
include::footer.txt[]
|
|
|