| // Copyright 2015-2021 The Khronos Group, Inc. |
| // |
| // SPDX-License-Identifier: CC-BY-4.0 |
| |
| [[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 |
| ifdef::VK_KHR_copy_commands2[] |
| fname:vkCmdCopyBuffer2KHR and |
| endif::VK_KHR_copy_commands2[] |
| fname:vkCmdCopyBuffer and a portion of an image can: be copied to another |
| image with |
| ifdef::VK_KHR_copy_commands2[] |
| fname:vkCmdCopyImage2KHR and |
| endif::VK_KHR_copy_commands2[] |
| fname:vkCmdCopyImage. |
| Image data can: also be copied to and from buffer memory using |
| ifndef::VK_KHR_copy_commands2[] |
| fname:vkCmdCopyImageToBuffer and fname:vkCmdCopyBufferToImage. |
| endif::VK_KHR_copy_commands2[] |
| ifdef::VK_KHR_copy_commands2[] |
| fname:vkCmdCopyImageToBuffer2KHR, fname:vkCmdCopyImageToBuffer, |
| fname:vkCmdCopyBufferToImage2KHR, and fname:vkCmdCopyBufferToImage. |
| endif::VK_KHR_copy_commands2[] |
| Image data can: be blitted (with or without scaling and filtering) with |
| ifdef::VK_KHR_copy_commands2[] |
| fname:vkCmdBlitImage2KHR and |
| endif::VK_KHR_copy_commands2[] |
| fname:vkCmdBlitImage. |
| Multisampled images can: be resolved to a non-multisampled image with |
| ifdef::VK_KHR_copy_commands2[] |
| fname:vkCmdResolveImage2KHR and |
| endif::VK_KHR_copy_commands2[] |
| fname:vkCmdResolveImage. |
| |
| |
| == Common Operation |
| |
| The following valid usage rules apply to all copy commands: |
| |
| * Copy commands must: be recorded outside of a render pass instance. |
| * The set of all bytes bound to all the source regions must: not overlap |
| the set of all bytes bound to the destination regions. |
| * The set of all bytes bound to each destination region must: not overlap |
| the set of all bytes bound to another destination region. |
| * 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 the |
| ifdef::VK_KHR_shared_presentable_image[] |
| ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, |
| endif::VK_KHR_shared_presentable_image[] |
| 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_VERSION_1_1,VK_KHR_maintenance1[] |
| * Source images must: have ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT in |
| their <<resources-image-format-features,format features>>. |
| * Destination images must: have ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT |
| in their <<resources-image-format-features,format features>>. |
| endif::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * 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. |
| ifndef::VK_VERSION_1_2+VK_EXT_separate_stencil_usage[] |
| * Source images must: have been created with |
| ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT set in |
| slink:VkImageCreateInfo::pname:usage |
| * Destination images must: have been created with |
| ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT set in |
| slink:VkImageCreateInfo::pname:usage |
| endif::VK_VERSION_1_2+VK_EXT_separate_stencil_usage[] |
| ifdef::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] |
| * If the stencil aspect of source image is accessed, and the source image |
| was not created with <<VkImageStencilUsageCreateInfo,separate stencil |
| usage>>, the source image must: have been created with |
| ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT set in |
| slink:VkImageCreateInfo::pname:usage |
| * If the stencil aspect of destination image is accessed, and the |
| destination image was not created with |
| <<VkImageStencilUsageCreateInfo,separate stencil usage>>, the |
| destination image must: have been created with |
| ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT set in |
| slink:VkImageCreateInfo::pname:usage |
| * If the stencil aspect of source image is accessed, and the source image |
| was created with <<VkImageStencilUsageCreateInfo,separate stencil |
| usage>>, the source image must: have been created with |
| ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT set in |
| slink:VkImageStencilUsageCreateInfo::pname:stencilUsage |
| * If the stencil aspect of destination image is accessed, and the |
| destination image was created with |
| <<VkImageStencilUsageCreateInfo,separate stencil usage>>, the |
| destination image must: have been created with |
| ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT set in |
| slink:VkImageStencilUsageCreateInfo::pname:stencilUsage |
| * If non-stencil aspects of a source image are accessed, the source image |
| must: have been created with ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT set |
| in slink:VkImageCreateInfo::pname:usage |
| * If non-stencil aspects of a destination image are accessed, the |
| destination image must: have been created with |
| ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT set in |
| slink:VkImageCreateInfo::pname:usage |
| endif::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] |
| |
| All copy commands are treated as "`transfer`" operations for the purposes of |
| synchronization barriers. |
| |
| All copy commands that have a source format with an X component in its |
| format description read undefined: values from those bits. |
| |
| All copy commands that have a destination format with an X component in its |
| format description write undefined: values to those bits. |
| |
| |
| [[copies-buffers]] |
| == Copying Data Between Buffers |
| |
| [open,refpage='vkCmdCopyBuffer',desc='Copy data between buffer regions',type='protos'] |
| -- |
| :refpage: vkCmdCopyBuffer |
| |
| To copy data between buffer objects, call: |
| |
| include::{generated}/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 resulting values are undefined: if the copy regions |
| overlap in memory. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/copy_buffer_command_buffer_common.txt[] |
| include::{chapters}/commonvalidity/copy_buffer_common.txt[] |
| **** |
| |
| include::{generated}/validity/protos/vkCmdCopyBuffer.txt[] |
| -- |
| |
| [open,refpage='VkBufferCopy',desc='Structure specifying a buffer copy operation',type='structs'] |
| -- |
| :refpage: VkBufferCopy |
| |
| The sname:VkBufferCopy structure is defined as: |
| |
| include::{generated}/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. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/buffer_copy_common.txt[] |
| **** |
| |
| include::{generated}/validity/structs/VkBufferCopy.txt[] |
| -- |
| |
| ifdef::VK_KHR_copy_commands2[] |
| |
| A more extensible version of the copy buffer command is defined below. |
| |
| [open,refpage='vkCmdCopyBuffer2KHR',desc='Copy data between buffer regions',type='protos'] |
| -- |
| :refpage: vkCmdCopyBuffer2KHR |
| |
| To copy data between buffer objects, call: |
| |
| include::{generated}/api/protos/vkCmdCopyBuffer2KHR.txt[] |
| |
| * pname:commandBuffer is the command buffer into which the command will be |
| recorded. |
| * pname:pCopyBufferInfo is a pointer to a slink:VkCopyBufferInfo2KHR |
| structure describing the copy parameters. |
| |
| This command is functionally identical to flink:vkCmdCopyBuffer, but |
| includes extensible sub-structures that include pname:sType and pname:pNext |
| parameters, allowing them to be more easily extended. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/copy_buffer_command_buffer_common.txt[] |
| **** |
| |
| include::{generated}/validity/protos/vkCmdCopyBuffer2KHR.txt[] |
| -- |
| |
| [open,refpage='VkCopyBufferInfo2KHR',desc='Structure specifying parameters of a buffer copy command',type='structs'] |
| -- |
| :refpage: VkCopyBufferInfo2KHR |
| |
| The sname:VkCopyBufferInfo2KHR structure is defined as: |
| |
| include::{generated}/api/structs/VkCopyBufferInfo2KHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * 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:VkBufferCopy2KHR |
| structures specifying the regions to copy. |
| |
| Members defined by this structure with the same name as parameters in |
| flink:vkCmdCopyBuffer have the identical effect to those parameters; the |
| child structure slink:VkBufferCopy2KHR is a variant of slink:VkBufferCopy |
| which includes pname:sType and pname:pNext parameters, allowing it to be |
| extended. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/copy_buffer_common.txt[] |
| **** |
| |
| include::{generated}/validity/structs/VkCopyBufferInfo2KHR.txt[] |
| -- |
| |
| [open,refpage='VkBufferCopy2KHR',desc='Structure specifying a buffer copy operation',type='structs'] |
| -- |
| :refpage: VkBufferCopy2KHR |
| |
| The sname:VkBufferCopy2KHR structure is defined as: |
| |
| include::{generated}/api/structs/VkBufferCopy2KHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * 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. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/buffer_copy_common.txt[] |
| **** |
| |
| include::{generated}/validity/structs/VkBufferCopy2KHR.txt[] |
| -- |
| |
| endif::VK_KHR_copy_commands2[] |
| |
| |
| [[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. |
| |
| [open,refpage='vkCmdCopyImage',desc='Copy data between images',type='protos'] |
| -- |
| :refpage: vkCmdCopyImage |
| |
| To copy data between image objects, call: |
| |
| include::{generated}/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-images-format-compatibility]] |
| The formats of pname:srcImage and pname:dstImage must: be compatible. |
| Formats are compatible if they share the same class, as shown in the |
| <<formats-compatibility,Compatible Formats>> table. |
| Depth/stencil formats must: match exactly. |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| If either pname:srcImage or pname:dstImage has a |
| <<formats-requiring-sampler-ycbcr-conversion, _multi-planar_ format>>, |
| regions of each plane to be copied must: be specified separately using the |
| pname:srcSubresource and pname:dstSubresource members of the |
| slink:VkImageCopy structure. |
| In this case, the pname:aspectMask of the pname:srcSubresource or |
| pname:dstSubresource that refers to the multi-planar image must: be |
| ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or |
| ename:VK_IMAGE_ASPECT_PLANE_2_BIT. |
| For the purposes of fname:vkCmdCopyImage, each plane of a multi-planar image |
| is treated as having the format listed in <<formats-compatible-planes>> for |
| the plane identified by the pname:aspectMask of the corresponding |
| subresource. |
| This applies both to elink:VkFormat and to coordinates used in the copy, |
| which correspond to texels in the _plane_ rather than how these texels map |
| to coordinates in the image as a whole. |
| |
| [NOTE] |
| .Note |
| ==== |
| For example, the ename:VK_IMAGE_ASPECT_PLANE_1_BIT plane of a |
| ename:VK_FORMAT_G8_B8R8_2PLANE_420_UNORM image is compatible with an image |
| of format ename:VK_FORMAT_R8G8_UNORM and (less usefully) with the |
| ename:VK_IMAGE_ASPECT_PLANE_0_BIT plane of an image of format |
| ename:VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_420_UNORM_3PACK16, as each texel is |
| 2 bytes in size. |
| ==== |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| |
| [[copies-images-format-size-compatibility]] |
| fname:vkCmdCopyImage allows copying between _size-compatible_ compressed and |
| uncompressed internal formats. |
| Formats are size-compatible if the texel block size of the uncompressed |
| format is equal to the 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 4{times}4 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 4{times}4 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 {plus} 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 {plus} 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 {plus} 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 {plus} 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 {plus} 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 {plus} 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. |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| "`etext:_422`" image formats that are not |
| <<formats-requiring-sampler-ycbcr-conversion,_multi-planar_>> are treated as |
| having a 2{times}1 compressed texel block for the purposes of these rules. |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| |
| fname:vkCmdCopyImage can: be used to copy image data between multisample |
| images, but both images must: have the same number of samples. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/copy_image_command_buffer_common.txt[] |
| include::{chapters}/commonvalidity/copy_image_common.txt[] |
| **** |
| |
| include::{generated}/validity/protos/vkCmdCopyImage.txt[] |
| -- |
| |
| [open,refpage='VkImageCopy',desc='Structure specifying an image copy operation',type='structs'] |
| -- |
| :refpage: VkImageCopy |
| |
| The sname:VkImageCopy structure is defined as: |
| |
| include::{generated}/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 pname:x, pname:y, |
| and pname:z offsets in texels of the sub-regions of the source and |
| destination image data. |
| * pname:extent is the size in texels of the image to copy in pname:width, |
| pname:height and pname:depth. |
| |
| ifdef::VK_VERSION_1_1,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_VERSION_1_1,VK_KHR_maintenance1[] |
| ifndef::VK_VERSION_1_1,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_VERSION_1_1,VK_KHR_maintenance1[] |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| Copies involving a <<formats-requiring-sampler-ycbcr-conversion, |
| multi-planar image format>> specify the region to be copied in terms of the |
| _plane_ to be copied, not the coordinates of the multi-planar image. |
| This means that copies accessing the R/B planes of "`etext:_422`" format |
| images must: fit the copied region within half the pname:width of the parent |
| image, and that copies accessing the R/B planes of "`etext:_420`" format |
| images must: fit the copied region within half the pname:width and |
| pname:height of the parent image. |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/image_copy_common.txt[] |
| **** |
| |
| include::{generated}/validity/structs/VkImageCopy.txt[] |
| -- |
| |
| [open,refpage='VkImageSubresourceLayers',desc='Structure specifying an image subresource layers',type='structs'] |
| -- |
| |
| The sname:VkImageSubresourceLayers structure is defined as: |
| |
| include::{generated}/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 |
| * pname:baseArrayLayer and pname:layerCount are the starting layer and |
| number of layers to copy. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkImageSubresourceLayers-aspectMask-00167]] |
| 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 |
| * [[VUID-VkImageSubresourceLayers-aspectMask-00168]] |
| pname:aspectMask must: not contain ename:VK_IMAGE_ASPECT_METADATA_BIT |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| * [[VUID-VkImageSubresourceLayers-aspectMask-02247]] |
| pname:aspectMask must: not include |
| `VK_IMAGE_ASPECT_MEMORY_PLANE__{ibit}__BIT_EXT` for any index _i_ |
| endif::VK_EXT_image_drm_format_modifier[] |
| * [[VUID-VkImageSubresourceLayers-layerCount-01700]] |
| pname:layerCount must: be greater than 0 |
| **** |
| |
| include::{generated}/validity/structs/VkImageSubresourceLayers.txt[] |
| -- |
| |
| ifdef::VK_KHR_copy_commands2[] |
| |
| A more extensible version of the copy image command is defined below. |
| |
| [open,refpage='vkCmdCopyImage2KHR',desc='Copy data between images',type='protos'] |
| -- |
| :refpage: vkCmdCopyImage2KHR |
| |
| To copy data between image objects, call: |
| |
| include::{generated}/api/protos/vkCmdCopyImage2KHR.txt[] |
| |
| * pname:commandBuffer is the command buffer into which the command will be |
| recorded. |
| * pname:pCopyImageInfo is a pointer to a slink:VkCopyImageInfo2KHR |
| structure describing the copy parameters. |
| |
| This command is functionally identical to flink:vkCmdCopyImage, but includes |
| extensible sub-structures that include pname:sType and pname:pNext |
| parameters, allowing them to be more easily extended. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/copy_image_command_buffer_common.txt[] |
| **** |
| |
| include::{generated}/validity/protos/vkCmdCopyImage2KHR.txt[] |
| -- |
| |
| |
| [open,refpage='VkCopyImageInfo2KHR',desc='Structure specifying parameters of an image copy command',type='structs'] |
| -- |
| :refpage: VkCopyImageInfo2KHR |
| |
| The sname:VkCopyImageInfo2KHR structure is defined as: |
| |
| include::{generated}/api/structs/VkCopyImageInfo2KHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * 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:VkImageCopy2KHR |
| structures specifying the regions to copy. |
| |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/copy_image_common.txt[] |
| **** |
| |
| include::{generated}/validity/structs/VkCopyImageInfo2KHR.txt[] |
| -- |
| |
| [open,refpage='VkImageCopy2KHR',desc='Structure specifying an image copy operation',type='structs'] |
| -- |
| :refpage: VkImageCopy2KHR |
| |
| The sname:VkImageCopy2KHR structure is defined as: |
| |
| include::{generated}/api/structs/VkImageCopy2KHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * 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 pname:x, pname:y, |
| and pname:z offsets in texels of the sub-regions of the source and |
| destination image data. |
| * pname:extent is the size in texels of the image to copy in pname:width, |
| pname:height and pname:depth. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/image_copy_common.txt[] |
| **** |
| |
| include::{generated}/validity/structs/VkImageCopy2KHR.txt[] |
| -- |
| |
| endif::VK_KHR_copy_commands2[] |
| |
| |
| [[copies-buffers-images]] |
| == Copying Data Between Buffers and Images |
| |
| [open,refpage='vkCmdCopyBufferToImage',desc='Copy data from a buffer into an image',type='protos'] |
| -- |
| :refpage: vkCmdCopyBufferToImage |
| :imageparam: pname:dstImage |
| |
| To copy data from a buffer object to an image object, call: |
| |
| include::{generated}/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. |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| If pname:dstImage has a |
| <<formats-requiring-sampler-ycbcr-conversion,multi-planar format>>, regions |
| of each plane to be a target of a copy must: be specified separately using |
| the pname:pRegions member of the slink:VkBufferImageCopy structure. |
| In this case, the pname:aspectMask of pname:imageSubresource must: be |
| ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or |
| ename:VK_IMAGE_ASPECT_PLANE_2_BIT. |
| For the purposes of fname:vkCmdCopyBufferToImage, each plane of a |
| multi-planar image is treated as having the format listed in |
| <<formats-compatible-planes>> for the plane identified by the |
| pname:aspectMask of the corresponding subresource. |
| This applies both to elink:VkFormat and to coordinates used in the copy, |
| which correspond to texels in the _plane_ rather than how these texels map |
| to coordinates in the image as a whole. |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/copy_buffer_to_image_command_buffer_common.txt[] |
| * [[VUID-vkCmdCopyBufferToImage-pRegions-06217]] |
| The image region specified by each element of pname:pRegions must: be |
| contained within the specified pname:imageSubresource of pname:dstImage |
| include::{chapters}/commonvalidity/copy_buffer_to_image_common.txt[] |
| * [[VUID-vkCmdCopyBufferToImage-pRegions-06218]] |
| For each element of pname:pRegions, pname:imageOffset.x and |
| [eq]#(pname:imageExtent.width {plus} pname:imageOffset.x)# must: both be |
| greater than or equal to `0` and less than or equal to the width of the |
| specified pname:imageSubresource of pname:dstImage |
| * [[VUID-vkCmdCopyBufferToImage-pRegions-06219]] |
| For each element of pname:pRegions, pname:imageOffset.y and |
| [eq]#(pname:imageExtent.height {plus} pname:imageOffset.y)# must: both |
| be greater than or equal to `0` and less than or equal to the height of |
| the specified pname:imageSubresource of pname:dstImage |
| include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_common.txt[] |
| **** |
| |
| include::{generated}/validity/protos/vkCmdCopyBufferToImage.txt[] |
| -- |
| |
| [open,refpage='vkCmdCopyImageToBuffer',desc='Copy image data into a buffer',type='protos'] |
| -- |
| :refpage: vkCmdCopyImageToBuffer |
| :imageparam: pname:srcImage |
| |
| To copy data from an image object to a buffer object, call: |
| |
| include::{generated}/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. |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| If pname:srcImage has a <<formats-requiring-sampler-ycbcr-conversion, |
| multi-planar format>>, regions of each plane to be a source of a copy must: |
| be specified separately using the pname:pRegions member of the |
| slink:VkBufferImageCopy structure. |
| In this case, the pname:aspectMask of pname:imageSubresource must: be |
| ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or |
| ename:VK_IMAGE_ASPECT_PLANE_2_BIT. |
| For the purposes of fname:vkCmdCopyBufferToImage, each plane of a |
| multi-planar image is treated as having the format listed in |
| <<formats-compatible-planes>> for the plane identified by the |
| pname:aspectMask of the corresponding subresource. |
| This applies both to elink:VkFormat and to coordinates used in the copy, |
| which correspond to texels in the _plane_ rather than how these texels map |
| to coordinates in the image as a whole. |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/copy_image_to_buffer_command_buffer_common.txt[] |
| * [[VUID-vkCmdCopyImageToBuffer-pRegions-06220]] |
| The image region specified by each element of pname:pRegions must: be |
| contained within the specified pname:imageSubresource of pname:srcImage |
| include::{chapters}/commonvalidity/copy_image_to_buffer_common.txt[] |
| * [[VUID-vkCmdCopyImageToBuffer-pRegions-06221]] |
| For each element of pname:pRegions, pname:imageOffset.x and |
| [eq]#(pname:imageExtent.width {plus} pname:imageOffset.x)# must: both be |
| greater than or equal to `0` and less than or equal to the width of the |
| specified pname:imageSubresource of pname:srcImage |
| * [[VUID-vkCmdCopyImageToBuffer-pRegions-06222]] |
| For each element of pname:pRegions, pname:imageOffset.y and |
| [eq]#(imageExtent.height {plus} pname:imageOffset.y)# must: both be |
| greater than or equal to `0` and less than or equal to the height of the |
| specified pname:imageSubresource of pname:srcImage |
| include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_common.txt[] |
| **** |
| |
| include::{generated}/validity/protos/vkCmdCopyImageToBuffer.txt[] |
| -- |
| |
| [open,refpage='VkBufferImageCopy',desc='Structure specifying a buffer image copy operation',type='structs'] |
| -- |
| :refpage: VkBufferImageCopy |
| |
| For both flink:vkCmdCopyBufferToImage and flink:vkCmdCopyImageToBuffer, each |
| element of pname:pRegions is a structure defined as: |
| |
| include::{generated}/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 in texels a |
| subregion of a larger two- or three-dimensional image in buffer memory, |
| and control the addressing calculations. |
| If either of these values is zero, that aspect of the buffer memory is |
| considered to be tightly packed according to 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 pname:x, pname:y, pname: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, |
| ifdef::VK_EXT_depth_range_unrestricted[] |
| and the `apiext:VK_EXT_depth_range_unrestricted` extension is not enabled, |
| endif::VK_EXT_depth_range_unrestricted[] |
| the data in buffer memory must: be in the range [eq]#[0,1]#, or the |
| resulting values are undefined:. |
| |
| 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. |
| |
| [[blocked-image]] |
| For purpose of valid usage statements here and in related copy commands, a |
| _blocked image_ is defined as: |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * an image with a _single-plane_, "`etext:_422`" format, which is treated |
| as a format with a 2 {times} 1 compressed texel block, or |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * a compressed image. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/buffer_image_copy_common.txt[] |
| **** |
| |
| include::{generated}/validity/structs/VkBufferImageCopy.txt[] |
| -- |
| |
| ifdef::VK_KHR_copy_commands2[] |
| |
| More extensible versions of the commands to copy between buffers and images |
| are defined below. |
| |
| [open,refpage='vkCmdCopyBufferToImage2KHR',desc='Copy data from a buffer into an image',type='protos'] |
| -- |
| :refpage: vkCmdCopyBufferToImage2KHR |
| |
| To copy data from a buffer object to an image object, call: |
| |
| include::{generated}/api/protos/vkCmdCopyBufferToImage2KHR.txt[] |
| |
| * pname:commandBuffer is the command buffer into which the command will be |
| recorded. |
| * pname:pCopyBufferToImageInfo is a pointer to a |
| slink:VkCopyBufferToImageInfo2KHR structure describing the copy |
| parameters. |
| |
| This command is functionally identical to flink:vkCmdCopyBufferToImage, but |
| includes extensible sub-structures that include pname:sType and pname:pNext |
| parameters, allowing them to be more easily extended. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/copy_buffer_to_image_command_buffer_common.txt[] |
| **** |
| |
| include::{generated}/validity/protos/vkCmdCopyBufferToImage2KHR.txt[] |
| -- |
| |
| [open,refpage='VkCopyBufferToImageInfo2KHR',desc='Structure specifying parameters of a buffer to image copy command',type='structs'] |
| -- |
| :refpage: VkCopyBufferToImageInfo2KHR |
| :imageparam: pname:dstImage |
| |
| The sname:VkCopyBufferToImageInfo2KHR structure is defined as: |
| |
| include::{generated}/api/structs/VkCopyBufferToImageInfo2KHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * 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:VkBufferImageCopy2KHR |
| structures specifying the regions to copy. |
| |
| .Valid Usage |
| **** |
| ifndef::VK_QCOM_rotated_copy_commands[] |
| * [[VUID-VkCopyBufferToImageInfo2KHR-pRegions-00172]] |
| The image region specified by each element of pname:pRegions must: be |
| contained within the specified pname:imageSubresource of pname:dstImage |
| endif::VK_QCOM_rotated_copy_commands[] |
| ifdef::VK_QCOM_rotated_copy_commands[] |
| * [[VUID-VkCopyBufferToImageInfo2KHR-pRegions-04565]] |
| If the image region specified by each element of pname:pRegions does not |
| contain slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, |
| it must: be a region that is contained within the specified |
| pname:imageSubresource of pname:dstImage |
| * [[VUID-VkCopyBufferToImageInfo2KHR-pRegions-04554]] |
| If the image region specified by each element of pname:pRegions contains |
| slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, the |
| rotated destination region as described in |
| <<copies-buffers-images-rotation-addressing>> must: be contained within |
| pname:dstImage |
| * [[VUID-VkCopyBufferToImageInfo2KHR-pRegions-04555]] |
| If any element of pname:pRegions contains |
| slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then |
| pname:dstImage must: not be a <<blocked-image,blocked image>> |
| * [[VUID-VkCopyBufferToImageInfo2KHR-pRegions-06203]] |
| If any element of pname:pRegions contains |
| slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then |
| pname:dstImage must: be of type ename:VK_IMAGE_TYPE_2D |
| * [[VUID-VkCopyBufferToImageInfo2KHR-pRegions-06204]] |
| If any element of pname:pRegions contains |
| slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then |
| pname:dstImage must: not have a |
| <<formats-requiring-sampler-ycbcr-conversion, multi-planar format>> |
| endif::VK_QCOM_rotated_copy_commands[] |
| include::{chapters}/commonvalidity/copy_buffer_to_image_common.txt[] |
| * [[VUID-VkCopyBufferToImageInfo2KHR-pRegions-06223]] |
| For each element of pname:pRegions not containing |
| sname:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, |
| pname:imageOffset.x and [eq]#(pname:imageExtent.width {plus} |
| pname:imageOffset.x)# must: both be greater than or equal to `0` and |
| less than or equal to the width of the specified pname:imageSubresource |
| of pname:dstImage |
| * [[VUID-VkCopyBufferToImageInfo2KHR-pRegions-06224]] |
| For each element of pname:pRegions not containing |
| sname:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, |
| pname:imageOffset.y and [eq]#(pname:imageExtent.height {plus} |
| pname:imageOffset.y)# must: both be greater than or equal to `0` and |
| less than or equal to the height of the specified pname:imageSubresource |
| of pname:dstImage |
| include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_common.txt[] |
| **** |
| |
| include::{generated}/validity/structs/VkCopyBufferToImageInfo2KHR.txt[] |
| -- |
| |
| [open,refpage='vkCmdCopyImageToBuffer2KHR',desc='Copy image data into a buffer',type='protos'] |
| -- |
| :refpage: vkCmdCopyImageToBuffer2KHR |
| :imageparam: pname:srcImage |
| |
| To copy data from an image object to a buffer object, call: |
| |
| include::{generated}/api/protos/vkCmdCopyImageToBuffer2KHR.txt[] |
| |
| * pname:commandBuffer is the command buffer into which the command will be |
| recorded. |
| * pname:pCopyImageToBufferInfo is a pointer to a |
| slink:VkCopyImageToBufferInfo2KHR structure describing the copy |
| parameters. |
| |
| This command is functionally identical to flink:vkCmdCopyImageToBuffer, but |
| includes extensible sub-structures that include pname:sType and pname:pNext |
| parameters, allowing them to be more easily extended. |
| |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/copy_image_to_buffer_command_buffer_common.txt[] |
| **** |
| |
| include::{generated}/validity/protos/vkCmdCopyImageToBuffer2KHR.txt[] |
| -- |
| |
| [open,refpage='VkCopyImageToBufferInfo2KHR',desc='Structure specifying parameters of an image to buffer copy command',type='structs'] |
| -- |
| :refpage: VkCopyImageToBufferInfo2KHR |
| |
| The sname:VkCopyImageToBufferInfo2KHR structure is defined as: |
| |
| include::{generated}/api/structs/VkCopyImageToBufferInfo2KHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * 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:VkBufferImageCopy2KHR |
| structures specifying the regions to copy. |
| |
| .Valid Usage |
| **** |
| ifndef::VK_QCOM_rotated_copy_commands[] |
| * [[VUID-VkCopyImageToBufferInfo2KHR-pRegions-00182]] |
| The image region specified by each element of pname:pRegions must: be |
| contained within the specified pname:imageSubresource of pname:srcImage |
| endif::VK_QCOM_rotated_copy_commands[] |
| ifdef::VK_QCOM_rotated_copy_commands[] |
| * [[VUID-VkCopyImageToBufferInfo2KHR-pRegions-04566]] |
| If the image region specified by each element of pname:pRegions does not |
| contain slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, |
| it must: be contained within the specified pname:imageSubresource of |
| pname:srcImage |
| * [[VUID-VkCopyImageToBufferInfo2KHR-pRegions-04557]] |
| If the image region specified by each element of pname:pRegions contains |
| slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, the |
| rotated source region as described in |
| <<copies-buffers-images-rotation-addressing>> must: be contained within |
| pname:srcImage |
| * [[VUID-VkCopyImageToBufferInfo2KHR-pRegions-04558]] |
| If any element of pname:pRegions contains |
| slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then |
| pname:srcImage must: not be a <<blocked-image,blocked image>> |
| * [[VUID-VkCopyImageToBufferInfo2KHR-pRegions-06205]] |
| If any element of pname:pRegions contains |
| slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then |
| pname:srcImage must: be of type ename:VK_IMAGE_TYPE_2D |
| * [[VUID-VkCopyImageToBufferInfo2KHR-pRegions-06206]] |
| If any element of pname:pRegions contains |
| slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then |
| pname:srcImage must: not have a |
| <<formats-requiring-sampler-ycbcr-conversion, multi-planar format>> |
| endif::VK_QCOM_rotated_copy_commands[] |
| include::{chapters}/commonvalidity/copy_image_to_buffer_common.txt[] |
| * [[VUID-VkCopyImageToBufferInfo2KHR-imageOffset-00197]] |
| For each element of pname:pRegions not containing |
| sname:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, |
| pname:imageOffset.x and [eq]#(pname:imageExtent.width {plus} |
| pname:imageOffset.x)# must: both be greater than or equal to `0` and |
| less than or equal to the width of the specified pname:imageSubresource |
| of pname:srcImage |
| * [[VUID-VkCopyImageToBufferInfo2KHR-imageOffset-00198]] |
| For each element of pname:pRegions not containing |
| sname:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, |
| pname:imageOffset.y and [eq]#(pname:imageExtent.height {plus} |
| pname:imageOffset.y)# must: both be greater than or equal to `0` and |
| less than or equal to the height of the specified pname:imageSubresource |
| of pname:srcImage |
| include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_common.txt[] |
| **** |
| |
| include::{generated}/validity/structs/VkCopyImageToBufferInfo2KHR.txt[] |
| -- |
| |
| [open,refpage='VkBufferImageCopy2KHR',desc='Structure specifying a buffer image copy operation',type='structs'] |
| -- |
| :refpage: VkBufferImageCopy2KHR |
| |
| For both flink:vkCmdCopyBufferToImage2KHR and |
| flink:vkCmdCopyImageToBuffer2KHR, each element of pname:pRegions is a |
| structure defined as: |
| |
| include::{generated}/api/structs/VkBufferImageCopy2KHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * 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 in texels a |
| subregion of a larger two- or three-dimensional image in buffer memory, |
| and control the addressing calculations. |
| If either of these values is zero, that aspect of the buffer memory is |
| considered to be tightly packed according to 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 pname:x, pname:y, pname: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. |
| |
| This structure is functionally identical to slink:VkBufferImageCopy, but |
| adds pname:sType and pname:pNext parameters, allowing it to be more easily |
| extended. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/buffer_image_copy_common.txt[] |
| **** |
| |
| include::{generated}/validity/structs/VkBufferImageCopy2KHR.txt[] |
| -- |
| endif::VK_KHR_copy_commands2[] |
| |
| ifdef::VK_QCOM_rotated_copy_commands[] |
| For both flink:vkCmdCopyBufferToImage2KHR and |
| flink:vkCmdCopyImageToBuffer2KHR, each region copied can include a rotation. |
| To specify a region with rotation, add the |
| slink:VkCopyCommandTransformInfoQCOM to the pname:pNext chain of |
| slink:VkBufferImageCopy2KHR. |
| When a rotation is specified, <<copies-buffers-images-rotation-addressing, |
| Buffer and Image Addressing with Rotation>> specifies how coordinates of |
| texels in the source region are rotated by pname:transform to produce texel |
| coordinates in the destination region. |
| When rotation is specified, the source and destination images must: each be |
| 2D images. |
| They must: not be <<blocked-image,blocked images>> or have a |
| <<formats-requiring-sampler-ycbcr-conversion, multi-planar format>>. |
| |
| [open,refpage='VkCopyCommandTransformInfoQCOM',desc='Structure describing transform parameters of rotated copy command',type='structs'] |
| -- |
| The sname:VkRenderPassTransformBeginInfoQCOM structure is defined as: |
| |
| include::{generated}/api/structs/VkCopyCommandTransformInfoQCOM.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:transform is a elink:VkSurfaceTransformFlagBitsKHR value |
| describing the transform to be applied. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkCopyCommandTransformInfoQCOM-transform-04560]] |
| pname:transform must: be ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, |
| ename:VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR, |
| ename:VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR, or |
| ename:VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR |
| **** |
| |
| include::{generated}/validity/structs/VkCopyCommandTransformInfoQCOM.txt[] |
| -- |
| |
| endif::VK_QCOM_rotated_copy_commands[] |
| |
| |
| [[copies-buffers-images-addressing]] |
| === Buffer and Image Addressing |
| |
| Pseudocode for image/buffer addressing of uncompressed formats is: |
| |
| [source,c] |
| --------------------------------------------------- |
| rowLength = region->bufferRowLength; |
| if (rowLength == 0) |
| rowLength = region->imageExtent.width; |
| |
| imageHeight = region->bufferImageHeight; |
| if (imageHeight == 0) |
| imageHeight = region->imageExtent.height; |
| |
| texelBlockSize = <texel block size of the format of the src/dstImage>; |
| |
| address of (x,y,z) = region->bufferOffset + (((z * imageHeight) + y) * rowLength + x) * texelBlockSize; |
| |
| 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-compressed 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 = (rowLength + compressedTexelBlockWidth - 1) / compressedTexelBlockWidth; |
| imageHeight = (imageHeight + compressedTexelBlockHeight - 1) / 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 {plus} |
| 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 {plus} |
| 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. |
| |
| ifdef::VK_QCOM_rotated_copy_commands[] |
| include::VK_QCOM_rotated_copies/rotated_addressing_copies.txt[] |
| endif::VK_QCOM_rotated_copy_commands[] |
| |
| |
| [[copies-imagescaling]] |
| == Image Copies with Scaling |
| |
| [open,refpage='vkCmdBlitImage',desc='Copy regions of an image, potentially performing format conversion,',type='protos'] |
| -- |
| :refpage: vkCmdBlitImage |
| |
| To copy regions of a source image into a destination image, potentially |
| performing format conversion, arbitrary scaling, and filtering, call: |
| |
| include::{generated}/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>>: |
| {empty}:: [eq]#u~base~ = i {plus} {onehalf}# |
| {empty}:: [eq]#v~base~ = j {plus} {onehalf}# |
| {empty}:: [eq]#w~base~ = k {plus} {onehalf}# |
| * These base coordinates are then offset by the first destination offset: |
| {empty}:: [eq]#u~offset~ = u~base~ - x~dst0~# |
| {empty}:: [eq]#v~offset~ = v~base~ - y~dst0~# |
| {empty}:: [eq]#w~offset~ = w~base~ - z~dst0~# |
| {empty}:: [eq]#a~offset~ = a - pname:baseArrayCount~dst~# |
| * The scale is determined from the source and destination regions, and |
| applied to the offset coordinates: |
| {empty}:: [eq]#scale~u~ = (x~src1~ - x~src0~) / (x~dst1~ - x~dst0~)# |
| {empty}:: [eq]#scale~v~ = (y~src1~ - y~src0~) / (y~dst1~ - y~dst0~)# |
| {empty}:: [eq]#scale~w~ = (z~src1~ - z~src0~) / (z~dst1~ - z~dst0~)# |
| {empty}:: [eq]#u~scaled~ = u~offset~ {times} scale~u~# |
| {empty}:: [eq]#v~scaled~ = v~offset~ {times} scale~v~# |
| {empty}:: [eq]#w~scaled~ = w~offset~ {times} scale~w~# |
| * Finally the source offset is added to the scaled coordinates, to |
| determine the final unnormalized coordinates used to sample from |
| pname:srcImage: |
| {empty}:: [eq]#u = u~scaled~ {plus} x~src0~# |
| {empty}:: [eq]#v = v~scaled~ {plus} y~src0~# |
| {empty}:: [eq]#w = w~scaled~ {plus} z~src0~# |
| {empty}:: [eq]#q = pname:mipLevel# |
| {empty}:: [eq]#a = a~offset~ {plus} 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. |
| |
| When blitting 3D textures, slices in the destination region bounded by |
| pname:dstOffsets[0].z and pname:dstOffsets[1].z are sampled from slices in |
| the source region bounded by 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 represented by *w* in the previous equations. |
| If the pname:filter parameter is ename:VK_FILTER_NEAREST then the value |
| sampled from the source image is taken from the single nearest slice, with |
| an implementation-dependent arithmetic rounding mode. |
| |
| The following filtering and conversion rules apply: |
| |
| * Integer formats can: only be converted to other integer formats with the |
| same signedness. |
| * No format conversion is supported between depth/stencil images. |
| The formats must: match. |
| * Format conversions on unorm, snorm, 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 |
| **** |
| include::{chapters}/commonvalidity/blit_image_command_buffer_common.txt[] |
| include::{chapters}/commonvalidity/blit_image_common.txt[] |
| **** |
| |
| include::{generated}/validity/protos/vkCmdBlitImage.txt[] |
| -- |
| |
| [open,refpage='VkImageBlit',desc='Structure specifying an image blit operation',type='structs'] |
| -- |
| :refpage: VkImageBlit |
| |
| The sname:VkImageBlit structure is defined as: |
| |
| include::{generated}/api/structs/VkImageBlit.txt[] |
| |
| * pname:srcSubresource is the subresource to blit from. |
| * pname:srcOffsets is a pointer to 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 a pointer to 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 |
| for the specified source and destination regions. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/image_blit_common.txt[] |
| **** |
| |
| include::{generated}/validity/structs/VkImageBlit.txt[] |
| -- |
| |
| ifdef::VK_KHR_copy_commands2[] |
| |
| A more extensible version of the blit image command is defined below. |
| |
| [open,refpage='vkCmdBlitImage2KHR',desc='Copy regions of an image, potentially performing format conversion,',type='protos'] |
| -- |
| :refpage: vkCmdBlitImage2KHR |
| |
| To copy regions of a source image into a destination image, potentially |
| performing format conversion, arbitrary scaling, and filtering, call: |
| |
| include::{generated}/api/protos/vkCmdBlitImage2KHR.txt[] |
| |
| * pname:commandBuffer is the command buffer into which the command will be |
| recorded. |
| * pname:pBlitImageInfo is a pointer to a slink:VkBlitImageInfo2KHR |
| structure describing the blit parameters. |
| |
| This command is functionally identical to flink:vkCmdBlitImage, but includes |
| extensible sub-structures that include pname:sType and pname:pNext |
| parameters, allowing them to be more easily extended. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/blit_image_command_buffer_common.txt[] |
| **** |
| |
| include::{generated}/validity/protos/vkCmdBlitImage2KHR.txt[] |
| -- |
| |
| [open,refpage='VkBlitImageInfo2KHR',desc='Structure specifying parameters of blit image command',type='structs'] |
| -- |
| :refpage: VkBlitImageInfo2KHR |
| |
| The sname:VkBlitImageInfo2KHR structure is defined as: |
| |
| include::{generated}/api/structs/VkBlitImageInfo2KHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * 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:VkImageBlit2KHR |
| structures specifying the regions to blit. |
| * pname:filter is a elink:VkFilter specifying the filter to apply if the |
| blits require scaling. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/blit_image_common.txt[] |
| ifdef::VK_QCOM_rotated_copy_commands[] |
| * [[VUID-VkBlitImageInfo2KHR-pRegions-04561]] |
| If any element of pname:pRegions contains |
| slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then |
| pname:srcImage and pname:dstImage must: not be block-compressed images |
| * [[VUID-VkBlitImageInfo2KHR-pRegions-06207]] |
| If any element of pname:pRegions contains |
| slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then |
| pname:srcImage must: be of type ename:VK_IMAGE_TYPE_2D |
| * [[VUID-VkBlitImageInfo2KHR-pRegions-06208]] |
| If any element of pname:pRegions contains |
| slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then |
| pname:srcImage must: not have a |
| <<formats-requiring-sampler-ycbcr-conversion, multi-planar format>> |
| endif::VK_QCOM_rotated_copy_commands[] |
| **** |
| |
| include::{generated}/validity/structs/VkBlitImageInfo2KHR.txt[] |
| -- |
| |
| [open,refpage='VkImageBlit2KHR',desc='Structure specifying an image blit operation',type='structs'] |
| -- |
| :refpage: VkImageBlit2KHR |
| |
| The sname:VkImageBlit2KHR structure is defined as: |
| |
| include::{generated}/api/structs/VkImageBlit2KHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:srcSubresource is the subresource to blit from. |
| * pname:srcOffsets is a pointer to 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 a pointer to 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 |
| for the specified source and destination regions. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/image_blit_common.txt[] |
| **** |
| |
| include::{generated}/validity/structs/VkImageBlit2KHR.txt[] |
| -- |
| |
| ifdef::VK_QCOM_rotated_copy_commands[] |
| For flink:vkCmdBlitImage2KHR, each region copied can include a rotation. |
| To specify a rotated region, add slink:VkCopyCommandTransformInfoQCOM to the |
| pname:pNext chain of slink:VkImageBlit2KHR. |
| For each region with a rotation specified, |
| <<copies-images-scaling-rotation,Image Blits with Scaling and Rotation>> |
| specifies how coordinates are rotated prior to sampling from the source |
| image. |
| When rotation is specified, the source and destination images must: each be |
| 2D images. |
| They must: not be <<blocked-image,blocked images>> or have a |
| <<formats-requiring-sampler-ycbcr-conversion, multi-planar format>>. |
| endif::VK_QCOM_rotated_copy_commands[] |
| |
| endif::VK_KHR_copy_commands2[] |
| |
| ifdef::VK_QCOM_rotated_copy_commands[] |
| include::VK_QCOM_rotated_copies/rotated_addressing_blits.txt[] |
| endif::VK_QCOM_rotated_copy_commands[] |
| |
| |
| [[copies-resolve]] |
| == Resolving Multisample Images |
| |
| [open,refpage='vkCmdResolveImage',desc='Resolve regions of an image',type='protos'] |
| -- |
| :refpage: vkCmdResolveImage |
| |
| To resolve a multisample color image to a non-multisample color image, call: |
| |
| include::{generated}/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 pname:x, pname:y, and |
| pname: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. |
| Each element of pname:pRegions must: be a region that is contained within |
| its corresponding image. |
| |
| 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 |
| **** |
| include::{chapters}/commonvalidity/resolve_image_command_buffer_common.txt[] |
| include::{chapters}/commonvalidity/resolve_image_common.txt[] |
| **** |
| |
| include::{generated}/validity/protos/vkCmdResolveImage.txt[] |
| -- |
| |
| [open,refpage='VkImageResolve',desc='Structure specifying an image resolve operation',type='structs'] |
| -- |
| :refpage: VkImageResolve |
| |
| The sname:VkImageResolve structure is defined as: |
| |
| include::{generated}/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 pname:x, pname:y, |
| and pname: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 |
| **** |
| include::{chapters}/commonvalidity/image_resolve_common.txt[] |
| **** |
| |
| include::{generated}/validity/structs/VkImageResolve.txt[] |
| -- |
| |
| ifdef::VK_AMD_buffer_marker[] |
| include::VK_AMD_buffer_marker/copies.txt[] |
| endif::VK_AMD_buffer_marker[] |
| |
| ifdef::VK_KHR_copy_commands2[] |
| |
| A more extensible version of the resolve image command is defined below. |
| |
| [open,refpage='vkCmdResolveImage2KHR',desc='Resolve regions of an image',type='protos'] |
| -- |
| :refpage: vkCmdResolveImage2KHR |
| |
| To resolve a multisample image to a non-multisample image, call: |
| |
| include::{generated}/api/protos/vkCmdResolveImage2KHR.txt[] |
| |
| * pname:commandBuffer is the command buffer into which the command will be |
| recorded. |
| * pname:pResolveImageInfo is a pointer to a slink:VkResolveImageInfo2KHR |
| structure describing the resolve parameters. |
| |
| This command is functionally identical to flink:vkCmdResolveImage, but |
| includes extensible sub-structures that include pname:sType and pname:pNext |
| parameters, allowing them to be more easily extended. |
| |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/resolve_image_command_buffer_common.txt[] |
| **** |
| |
| include::{generated}/validity/protos/vkCmdResolveImage2KHR.txt[] |
| -- |
| |
| [open,refpage='VkResolveImageInfo2KHR',desc='Structure specifying parameters of resolve image command',type='structs'] |
| -- |
| :refpage: VkResolveImageInfo2KHR |
| |
| The sname:VkResolveImageInfo2KHR structure is defined as: |
| |
| include::{generated}/api/structs/VkResolveImageInfo2KHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * 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:VkImageResolve2KHR |
| structures specifying the regions to resolve. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/resolve_image_common.txt[] |
| **** |
| |
| include::{generated}/validity/structs/VkResolveImageInfo2KHR.txt[] |
| -- |
| |
| [open,refpage='VkImageResolve2KHR',desc='Structure specifying an image resolve operation',type='structs'] |
| -- |
| :refpage: VkImageResolve2KHR |
| |
| The sname:VkImageResolve2KHR structure is defined as: |
| |
| include::{generated}/api/structs/VkImageResolve2KHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * 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 pname:x, pname:y, |
| and pname: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 |
| **** |
| include::{chapters}/commonvalidity/image_resolve_common.txt[] |
| **** |
| |
| include::{generated}/validity/structs/VkImageResolve2KHR.txt[] |
| -- |
| |
| endif::VK_KHR_copy_commands2[] |
