| // Copyright (c) 2015-2018 Khronos Group. This work is licensed under a |
| // Creative Commons Attribution 4.0 International License; see |
| // http://creativecommons.org/licenses/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 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 |
| |
| 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 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 |
| |
| [open,refpage='vkCmdCopyBuffer',desc='Copy data between buffer regions',type='protos'] |
| -- |
| |
| To copy data between buffer objects, call: |
| |
| include::../api/protos/vkCmdCopyBuffer.txt[] |
| |
| * pname:commandBuffer is the command buffer into which the command will be |
| recorded. |
| * pname:srcBuffer is the source buffer. |
| * pname:dstBuffer is the destination buffer. |
| * pname:regionCount is the number of regions to copy. |
| * pname:pRegions is a pointer to an array of slink:VkBufferCopy structures |
| specifying the regions to copy. |
| |
| Each region in pname:pRegions is copied from the source buffer to the same |
| region of the destination buffer. |
| pname:srcBuffer and pname:dstBuffer can: be the same buffer or alias the |
| same memory, but the result is undefined if the copy regions overlap in |
| memory. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCmdCopyBuffer-srcOffset-00113]] |
| The pname:srcOffset member of each element of pname:pRegions must: be |
| less than the size of pname:srcBuffer |
| * [[VUID-vkCmdCopyBuffer-dstOffset-00114]] |
| The pname:dstOffset member of each element of pname:pRegions must: be |
| less than the size of pname:dstBuffer |
| * [[VUID-vkCmdCopyBuffer-size-00115]] |
| The pname:size member of each element of pname:pRegions must: be less |
| than or equal to the size of pname:srcBuffer minus pname:srcOffset |
| * [[VUID-vkCmdCopyBuffer-size-00116]] |
| The pname:size member of each element of pname:pRegions must: be less |
| than or equal to the size of pname:dstBuffer minus pname:dstOffset |
| * [[VUID-vkCmdCopyBuffer-pRegions-00117]] |
| The union of the source regions, and the union of the destination |
| regions, specified by the elements of pname:pRegions, must: not overlap |
| in memory |
| * [[VUID-vkCmdCopyBuffer-srcBuffer-00118]] |
| pname:srcBuffer must: have been created with |
| ename:VK_BUFFER_USAGE_TRANSFER_SRC_BIT usage flag |
| * [[VUID-vkCmdCopyBuffer-srcBuffer-00119]] |
| If pname:srcBuffer is non-sparse then it must: be bound completely and |
| contiguously to a single sname:VkDeviceMemory object |
| * [[VUID-vkCmdCopyBuffer-dstBuffer-00120]] |
| pname:dstBuffer must: have been created with |
| ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag |
| * [[VUID-vkCmdCopyBuffer-dstBuffer-00121]] |
| If pname:dstBuffer is non-sparse then it must: be bound completely and |
| contiguously to a single sname:VkDeviceMemory object |
| ifdef::VK_VERSION_1_1[] |
| * [[VUID-vkCmdCopyBuffer-commandBuffer-01822]] |
| If pname:commandBuffer is an unprotected command buffer, then |
| pname:srcBuffer must: not be a protected buffer |
| * [[VUID-vkCmdCopyBuffer-commandBuffer-01823]] |
| If pname:commandBuffer is an unprotected command buffer, then |
| pname:dstBuffer must: not be a protected buffer |
| * [[VUID-vkCmdCopyBuffer-commandBuffer-01824]] |
| If pname:commandBuffer is a protected command buffer, then |
| pname:dstBuffer must: not be an unprotected buffer |
| endif::VK_VERSION_1_1[] |
| **** |
| |
| include::../validity/protos/vkCmdCopyBuffer.txt[] |
| -- |
| |
| [open,refpage='VkBufferCopy',desc='Structure specifying a buffer copy operation',type='structs'] |
| -- |
| |
| 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. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkBufferCopy-size-01988]] |
| The pname:size must: be greater than `0` |
| **** |
| |
| 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. |
| |
| [open,refpage='vkCmdCopyImage',desc='Copy data between images',type='protos'] |
| -- |
| |
| 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-images-format-compatibility]] |
| The formats of pname:srcImage and pname:dstImage must: be compatible. |
| Formats are considered compatible if their element size is the same between |
| both formats. |
| For example, ename:VK_FORMAT_R8G8B8A8_UNORM is compatible with |
| ename:VK_FORMAT_R32_UINT because both texels are 4 bytes in size. |
| Depth/stencil formats must: match exactly. |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| If the format of pname:srcImage or pname:dstImage is a |
| <<features-formats-requiring-sampler-ycbcr-conversion,_multi-planar_ image |
| 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 |
| <<features-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 element size of the uncompressed format |
| is equal to the element size (compressed texel block size) of the compressed |
| format. |
| Such a copy does not perform on-the-fly compression or decompression. |
| When copying from an uncompressed format to a compressed format, each texel |
| of uncompressed data of the source image is copied as a raw value to the |
| corresponding compressed texel block of the destination image. |
| When copying from a compressed format to an uncompressed format, each |
| compressed texel block of the source image is copied as a raw value to the |
| corresponding texel of uncompressed data in the destination image. |
| Thus, for example, it is legal to copy between a 128-bit uncompressed format |
| and a compressed format which has a 128-bit sized compressed texel block |
| representing 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 |
| <<features-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 |
| **** |
| * [[VUID-vkCmdCopyImage-pRegions-00122]] |
| The source region specified by each element of pname:pRegions must: be a |
| region that is contained within pname:srcImage |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| if the pname:srcImage's elink:VkFormat is not a |
| <<features-formats-requiring-sampler-ycbcr-conversion,multi-planar |
| format>>, and must: be a region that is contained within the plane being |
| copied if the pname:srcImage's elink:VkFormat is a multi-planar format |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-vkCmdCopyImage-pRegions-00123]] |
| The destination region specified by each element of pname:pRegions must: |
| be a region that is contained within pname:dstImage |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| if the pname:dstImage's elink:VkFormat is not a |
| <<features-formats-requiring-sampler-ycbcr-conversion,multi-planar |
| format>>, and must: be a region that is contained within the plane being |
| copied to if the pname:dstImage's elink:VkFormat is a multi-planar |
| format |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-vkCmdCopyImage-pRegions-00124]] |
| The union of all source regions, and the union of all destination |
| regions, specified by the elements of pname:pRegions, must: not overlap |
| in memory |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * [[VUID-vkCmdCopyImage-srcImage-01995]] |
| The <<resources-image-format-features,format features>> of |
| pname:srcImage must: contain ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT. |
| endif::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * [[VUID-vkCmdCopyImage-srcImage-00126]] |
| pname:srcImage must: have been created with |
| ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag |
| ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-vkCmdCopyImage-srcImage-00127]] |
| If pname:srcImage is non-sparse then it must: be bound completely and |
| contiguously to a single sname:VkDeviceMemory object |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-vkCmdCopyImage-srcImage-01546]] |
| If pname:srcImage is non-sparse then the image or _disjoint_ plane to be |
| copied must: be bound completely and contiguously to a single |
| sname:VkDeviceMemory object |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-vkCmdCopyImage-srcImageLayout-00128]] |
| pname:srcImageLayout must: specify the layout of the image subresources |
| of pname:srcImage specified in pname:pRegions at the time this command |
| is executed on a sname:VkDevice |
| ifndef::VK_KHR_shared_presentable_image[] |
| * [[VUID-vkCmdCopyImage-srcImageLayout-00129]] |
| pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL |
| or ename:VK_IMAGE_LAYOUT_GENERAL |
| endif::VK_KHR_shared_presentable_image[] |
| ifdef::VK_KHR_shared_presentable_image[] |
| * [[VUID-vkCmdCopyImage-srcImageLayout-01917]] |
| pname:srcImageLayout must: be |
| ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, |
| ename:VK_IMAGE_LAYOUT_GENERAL, or |
| ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR |
| endif::VK_KHR_shared_presentable_image[] |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * [[VUID-vkCmdCopyImage-dstImage-01996]] |
| The <<resources-image-format-features,format features>> of |
| pname:dstImage must: contain ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT. |
| endif::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * [[VUID-vkCmdCopyImage-dstImage-00131]] |
| pname:dstImage must: have been created with |
| ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag |
| ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-vkCmdCopyImage-dstImage-00132]] |
| If pname:dstImage is non-sparse then it must: be bound completely and |
| contiguously to a single sname:VkDeviceMemory object |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-vkCmdCopyImage-dstImage-01547]] |
| If pname:dstImage is non-sparse then the image or _disjoint_ plane that |
| is the destination of the copy must: be bound completely and |
| contiguously to a single sname:VkDeviceMemory object |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-vkCmdCopyImage-dstImageLayout-00133]] |
| pname:dstImageLayout must: specify the layout of the image subresources |
| of pname:dstImage specified in pname:pRegions at the time this command |
| is executed on a sname:VkDevice |
| ifndef::VK_KHR_shared_presentable_image[] |
| * [[VUID-vkCmdCopyImage-dstImageLayout-00134]] |
| pname:dstImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL |
| or ename:VK_IMAGE_LAYOUT_GENERAL |
| endif::VK_KHR_shared_presentable_image[] |
| ifdef::VK_KHR_shared_presentable_image[] |
| * [[VUID-vkCmdCopyImage-dstImageLayout-01395]] |
| pname:dstImageLayout must: be |
| ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, |
| ename:VK_IMAGE_LAYOUT_GENERAL, or |
| ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR |
| endif::VK_KHR_shared_presentable_image[] |
| ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-vkCmdCopyImage-srcImage-00135]] |
| The elink:VkFormat of each of pname:srcImage and pname:dstImage must: be |
| compatible, as defined <<copies-images-format-compatibility, below>> |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-vkCmdCopyImage-srcImage-01548]] |
| If the elink:VkFormat of each of pname:srcImage and pname:dstImage is |
| not a |
| <<features-formats-requiring-sampler-ycbcr-conversion,_multi-planar |
| format_>>, the elink:VkFormat of each of pname:srcImage and |
| pname:dstImage must: be compatible, as defined |
| <<copies-images-format-compatibility, below>> |
| * [[VUID-vkCmdCopyImage-None-01549]] |
| In a copy to or from a plane of a |
| <<features-formats-requiring-sampler-ycbcr-conversion,multi-planar |
| image>>, the elink:VkFormat of the image and plane must: be compatible |
| according to <<features-formats-compatible-planes,the description of |
| compatible planes>> for the plane being copied |
| * [[VUID-vkCmdCopyImage-aspectMask-01550]] |
| When a copy is performed to or from an image with a |
| <<features-formats-requiring-sampler-ycbcr-conversion,multi-planar |
| format>>, the pname:aspectMask of the pname:srcSubresource and/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 (with |
| ename:VK_IMAGE_ASPECT_PLANE_2_BIT valid only for a elink:VkFormat with |
| three planes) |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-vkCmdCopyImage-srcImage-00136]] |
| The sample count of pname:srcImage and pname:dstImage must: match |
| ifdef::VK_VERSION_1_1[] |
| * [[VUID-vkCmdCopyImage-commandBuffer-01825]] |
| If pname:commandBuffer is an unprotected command buffer, then |
| pname:srcImage must: not be a protected image |
| * [[VUID-vkCmdCopyImage-commandBuffer-01826]] |
| If pname:commandBuffer is an unprotected command buffer, then |
| pname:dstImage must: not be a protected image |
| * [[VUID-vkCmdCopyImage-commandBuffer-01827]] |
| If pname:commandBuffer is a protected command buffer, then |
| pname:dstImage must: not be an unprotected image |
| endif::VK_VERSION_1_1[] |
| * [[VUID-vkCmdCopyImage-srcSubresource-01696]] |
| The pname:srcSubresource.mipLevel member of each element of |
| pname:pRegions must: be less than the pname:mipLevels specified in |
| slink:VkImageCreateInfo when pname:srcImage was created |
| * [[VUID-vkCmdCopyImage-dstSubresource-01697]] |
| The pname:dstSubresource.mipLevel member of each element of |
| pname:pRegions must: be less than the pname:mipLevels specified in |
| slink:VkImageCreateInfo when pname:dstImage was created |
| * [[VUID-vkCmdCopyImage-srcSubresource-01698]] |
| The [eq]#pname:srcSubresource.baseArrayLayer {plus} |
| pname:srcSubresource.layerCount# of each element of pname:pRegions must: |
| be less than or equal to the pname:arrayLayers specified in |
| slink:VkImageCreateInfo when pname:srcImage was created |
| * [[VUID-vkCmdCopyImage-dstSubresource-01699]] |
| The [eq]#pname:dstSubresource.baseArrayLayer {plus} |
| pname:dstSubresource.layerCount# of each element of pname:pRegions must: |
| be less than or equal to the pname:arrayLayers specified in |
| slink:VkImageCreateInfo when pname:dstImage was created |
| * [[VUID-vkCmdCopyImage-srcOffset-01783]] |
| The pname:srcOffset and pname:extent members of each element of |
| pname:pRegions must: respect the image transfer granularity requirements |
| of pname:commandBuffer's command pool's queue family, as described in |
| slink:VkQueueFamilyProperties |
| * [[VUID-vkCmdCopyImage-dstOffset-01784]] |
| The pname:dstOffset and pname:extent members of each element of |
| pname:pRegions must: respect the image transfer granularity requirements |
| of pname:commandBuffer's command pool's queue family, as described in |
| slink:VkQueueFamilyProperties |
| **** |
| |
| include::../validity/protos/vkCmdCopyImage.txt[] |
| -- |
| |
| [open,refpage='VkImageCopy',desc='Structure specifying an image copy operation',type='structs'] |
| -- |
| |
| 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 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 <<features-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 |
| **** |
| ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkImageCopy-aspectMask-00137]] |
| The pname:aspectMask member of pname:srcSubresource and |
| pname:dstSubresource must: match |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkImageCopy-srcImage-01551]] |
| If neither the calling command's pname:srcImage nor the calling |
| command's pname:dstImage has a |
| <<features-formats-requiring-sampler-ycbcr-conversion, multi-planar |
| image format>> then the pname:aspectMask member of pname:srcSubresource |
| and pname:dstSubresource must: match |
| * [[VUID-VkImageCopy-srcImage-01552]] |
| If the calling command's pname:srcImage has a elink:VkFormat with |
| <<features-formats-requiring-sampler-ycbcr-conversion,two planes>> then |
| the pname:srcSubresource pname:aspectMask must: be |
| ename:VK_IMAGE_ASPECT_PLANE_0_BIT or ename:VK_IMAGE_ASPECT_PLANE_1_BIT |
| * [[VUID-VkImageCopy-srcImage-01553]] |
| If the calling command's pname:srcImage has a elink:VkFormat with |
| <<features-formats-requiring-sampler-ycbcr-conversion,three planes>> |
| then the pname:srcSubresource pname:aspectMask must: be |
| ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or |
| ename:VK_IMAGE_ASPECT_PLANE_2_BIT |
| * [[VUID-VkImageCopy-dstImage-01554]] |
| If the calling command's pname:dstImage has a elink:VkFormat with |
| <<features-formats-requiring-sampler-ycbcr-conversion,two planes>> then |
| the pname:dstSubresource pname:aspectMask must: be |
| ename:VK_IMAGE_ASPECT_PLANE_0_BIT or ename:VK_IMAGE_ASPECT_PLANE_1_BIT |
| * [[VUID-VkImageCopy-dstImage-01555]] |
| If the calling command's pname:dstImage has a elink:VkFormat with |
| <<features-formats-requiring-sampler-ycbcr-conversion,three planes>> |
| then the pname:dstSubresource pname:aspectMask must: be |
| ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or |
| ename:VK_IMAGE_ASPECT_PLANE_2_BIT |
| * [[VUID-VkImageCopy-srcImage-01556]] |
| If the calling command's pname:srcImage has a |
| <<features-formats-requiring-sampler-ycbcr-conversion,multi-planar image |
| format>> and the pname:dstImage does not have a multi-planar image |
| format, the pname:dstSubresource pname:aspectMask must: be |
| ename:VK_IMAGE_ASPECT_COLOR_BIT |
| * [[VUID-VkImageCopy-dstImage-01557]] |
| If the calling command's pname:dstImage has a |
| <<features-formats-requiring-sampler-ycbcr-conversion,multi-planar image |
| format>> and the pname:srcImage does not have a multi-planar image |
| format, the pname:srcSubresource pname:aspectMask must: be |
| ename:VK_IMAGE_ASPECT_COLOR_BIT |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| ifndef::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * [[VUID-VkImageCopy-layerCount-00138]] |
| The pname:layerCount member of pname:srcSubresource and |
| pname:dstSubresource must: match |
| * [[VUID-VkImageCopy-srcImage-00139]] |
| If either of the calling command's pname:srcImage or pname:dstImage |
| parameters are of elink:VkImageType ename:VK_IMAGE_TYPE_3D, the |
| pname:baseArrayLayer and pname:layerCount members of both |
| pname:srcSubresource and pname:dstSubresource must: be `0` and `1`, |
| respectively |
| endif::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * [[VUID-VkImageCopy-extent-00140]] |
| The number of slices of the pname:extent (for 3D) or layers of the |
| pname:srcSubresource (for non-3D) must: match the number of slices of |
| the pname:extent (for 3D) or layers of the pname:dstSubresource (for |
| non-3D) |
| * [[VUID-VkImageCopy-srcImage-00141]] |
| If either of the calling command's pname:srcImage or pname:dstImage |
| parameters are of elink:VkImageType ename:VK_IMAGE_TYPE_3D, the |
| pname:baseArrayLayer and pname:layerCount members of the corresponding |
| subresource must: be `0` and `1`, respectively |
| endif::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * [[VUID-VkImageCopy-aspectMask-00142]] |
| The pname:aspectMask member of pname:srcSubresource must: specify |
| aspects present in the calling command's pname:srcImage |
| * [[VUID-VkImageCopy-aspectMask-00143]] |
| The pname:aspectMask member of pname:dstSubresource must: specify |
| aspects present in the calling command's pname:dstImage |
| * [[VUID-VkImageCopy-srcOffset-00144]] |
| pname:srcOffset.x and [eq]#(pname:extent.width {plus} |
| pname:srcOffset.x)# must: both be greater than or equal to `0` and less |
| than or equal to the source image subresource width |
| * [[VUID-VkImageCopy-srcOffset-00145]] |
| pname:srcOffset.y and [eq]#(pname:extent.height {plus} |
| pname:srcOffset.y)# must: both be greater than or equal to `0` and less |
| than or equal to the source image subresource height |
| * [[VUID-VkImageCopy-srcImage-00146]] |
| If the calling command's pname:srcImage is of type |
| ename:VK_IMAGE_TYPE_1D, then pname:srcOffset.y must: be `0` and |
| pname:extent.height must: be `1`. |
| * [[VUID-VkImageCopy-srcOffset-00147]] |
| pname:srcOffset.z and [eq]#(pname:extent.depth {plus} |
| pname:srcOffset.z)# must: both be greater than or equal to `0` and less |
| than or equal to the source image subresource depth |
| * [[VUID-VkImageCopy-srcImage-01785]] |
| If the calling command's pname:srcImage is of type |
| ename:VK_IMAGE_TYPE_1D, then pname:srcOffset.z must: be `0` and |
| pname:extent.depth must: be `1`. |
| * [[VUID-VkImageCopy-dstImage-01786]] |
| If the calling command's pname:dstImage is of type |
| ename:VK_IMAGE_TYPE_1D, then pname:dstOffset.z must: be `0` and |
| pname:extent.depth must: be `1`. |
| * [[VUID-VkImageCopy-srcImage-01787]] |
| If the calling command's pname:srcImage is of type |
| ename:VK_IMAGE_TYPE_2D, then pname:srcOffset.z must: be `0`. |
| * [[VUID-VkImageCopy-dstImage-01788]] |
| If the calling command's pname:dstImage is of type |
| ename:VK_IMAGE_TYPE_2D, then pname:dstOffset.z must: be `0`. |
| ifndef::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * [[VUID-VkImageCopy-srcImage-01789]] |
| If the calling command's pname:srcImage or pname:dstImage is of type |
| ename:VK_IMAGE_TYPE_2D, then pname:extent.depth must: be `1`. |
| endif::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * [[VUID-VkImageCopy-srcImage-01790]] |
| If both pname:srcImage and pname:dstImage are of type |
| ename:VK_IMAGE_TYPE_2D then pname:extent.depth must: be `1`. |
| * [[VUID-VkImageCopy-srcImage-01791]] |
| If the calling command's pname:srcImage is of type |
| ename:VK_IMAGE_TYPE_2D, and the pname:dstImage is of type |
| ename:VK_IMAGE_TYPE_3D, then pname:extent.depth must: equal to the |
| pname:layerCount member of pname:srcSubresource. |
| * [[VUID-VkImageCopy-dstImage-01792]] |
| If the calling command's pname:dstImage is of type |
| ename:VK_IMAGE_TYPE_2D, and the pname:srcImage is of type |
| ename:VK_IMAGE_TYPE_3D, then pname:extent.depth must: equal to the |
| pname:layerCount member of pname:dstSubresource. |
| endif::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * [[VUID-VkImageCopy-dstOffset-00150]] |
| pname:dstOffset.x and [eq]#(pname:extent.width {plus} |
| pname:dstOffset.x)# must: both be greater than or equal to `0` and less |
| than or equal to the destination image subresource width |
| * [[VUID-VkImageCopy-dstOffset-00151]] |
| pname:dstOffset.y and [eq]#(pname:extent.height {plus} |
| pname:dstOffset.y)# must: both be greater than or equal to `0` and less |
| than or equal to the destination image subresource height |
| * [[VUID-VkImageCopy-dstImage-00152]] |
| If the calling command's pname:dstImage is of type |
| ename:VK_IMAGE_TYPE_1D, then pname:dstOffset.y must: be `0` and |
| pname:extent.height must: be `1`. |
| * [[VUID-VkImageCopy-dstOffset-00153]] |
| pname:dstOffset.z and [eq]#(pname:extent.depth {plus} |
| pname:dstOffset.z)# must: both be greater than or equal to `0` and less |
| than or equal to the destination image subresource depth |
| // The block of VU below come in alternate versions when the extension is |
| // enabled. |
| ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkImageCopy-srcOffset-00157]] |
| If the calling command's pname:srcImage is a compressed image, all |
| members of pname:srcOffset must: be a multiple of the corresponding |
| dimensions of the compressed texel block |
| * [[VUID-VkImageCopy-extent-00158]] |
| If the calling command's pname:srcImage is a compressed image, |
| pname:extent.width must: be a multiple of the compressed texel block |
| width or [eq]#(pname:extent.width {plus} pname:srcOffset.x)# must: equal |
| the source image subresource width |
| * [[VUID-VkImageCopy-extent-00159]] |
| If the calling command's pname:srcImage is a compressed image, |
| pname:extent.height must: be a multiple of the compressed texel block |
| height or [eq]#(pname:extent.height {plus} pname:srcOffset.y)# must: |
| equal the source image subresource height |
| * [[VUID-VkImageCopy-extent-00160]] |
| If the calling command's pname:srcImage is a compressed image, |
| pname:extent.depth must: be a multiple of the compressed texel block |
| depth or [eq]#(pname:extent.depth {plus} pname:srcOffset.z)# must: equal |
| the source image subresource depth |
| * [[VUID-VkImageCopy-dstOffset-00162]] |
| If the calling command's pname:dstImage is a compressed format image, |
| all members of pname:dstOffset must: be a multiple of the corresponding |
| dimensions of the compressed texel block |
| * [[VUID-VkImageCopy-extent-00163]] |
| If the calling command's pname:dstImage is a compressed format image, |
| pname:extent.width must: be a multiple of the compressed texel block |
| width or [eq]#(pname:extent.width {plus} pname:dstOffset.x)# must: equal |
| the destination image subresource width |
| * [[VUID-VkImageCopy-extent-00164]] |
| If the calling command's pname:dstImage is a compressed format image, |
| pname:extent.height must: be a multiple of the compressed texel block |
| height or [eq]#(pname:extent.height {plus} pname:dstOffset.y)# must: |
| equal the destination image subresource height |
| * [[VUID-VkImageCopy-extent-00165]] |
| If the calling command's pname:dstImage is a compressed format image, |
| pname:extent.depth must: be a multiple of the compressed texel block |
| depth or [eq]#(pname:extent.depth {plus} pname:dstOffset.z)# must: equal |
| the destination image subresource depth |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| // The nested ifdefs are there in anticipation of the hoped-for day when the |
| // VU extractor and validation layers can handle VU with imbedded |
| // conditionals. They are commented out until then. |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkImageCopy-srcImage-01727]] |
| If the calling command's pname:srcImage is a compressed image, |
| // ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| or a _single-plane_, "`etext:_422`" image format, |
| // endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| all members of pname:srcOffset must: be a multiple of the corresponding |
| dimensions of the compressed texel block |
| * [[VUID-VkImageCopy-srcImage-01728]] |
| If the calling command's pname:srcImage is a compressed image, |
| // ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| or a _single-plane_, "`etext:_422`" image format, |
| // endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| pname:extent.width must: be a multiple of the compressed texel block |
| width or [eq]#(pname:extent.width {plus} pname:srcOffset.x)# must: equal |
| the source image subresource width |
| * [[VUID-VkImageCopy-srcImage-01729]] |
| If the calling command's pname:srcImage is a compressed image, |
| // ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| or a _single-plane_, "`etext:_422`" image format, |
| // endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| pname:extent.height must: be a multiple of the compressed texel block |
| height or [eq]#(pname:extent.height {plus} pname:srcOffset.y)# must: |
| equal the source image subresource height |
| * [[VUID-VkImageCopy-srcImage-01730]] |
| If the calling command's pname:srcImage is a compressed image, |
| // ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| or a _single-plane_, "`etext:_422`" image format, |
| // endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| pname:extent.depth must: be a multiple of the compressed texel block |
| depth or [eq]#(pname:extent.depth {plus} pname:srcOffset.z)# must: equal |
| the source image subresource depth |
| * [[VUID-VkImageCopy-dstImage-01731]] |
| If the calling command's pname:dstImage is a compressed format image, |
| // ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| or a _single-plane_, "`etext:_422`" image format, |
| // endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| all members of pname:dstOffset must: be a multiple of the corresponding |
| dimensions of the compressed texel block |
| * [[VUID-VkImageCopy-dstImage-01732]] |
| If the calling command's pname:dstImage is a compressed format image, |
| // ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| or a _single-plane_, "`etext:_422`" image format, |
| // endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| pname:extent.width must: be a multiple of the compressed texel block |
| width or [eq]#(pname:extent.width {plus} pname:dstOffset.x)# must: equal |
| the destination image subresource width |
| * [[VUID-VkImageCopy-dstImage-01733]] |
| If the calling command's pname:dstImage is a compressed format image, |
| // ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| or a _single-plane_, "`etext:_422`" image format, |
| // endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| pname:extent.height must: be a multiple of the compressed texel block |
| height or [eq]#(pname:extent.height {plus} pname:dstOffset.y)# must: |
| equal the destination image subresource height |
| * [[VUID-VkImageCopy-dstImage-01734]] |
| If the calling command's pname:dstImage is a compressed format image, |
| // ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| or a _single-plane_, "`etext:_422`" image format, |
| // endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| pname:extent.depth must: be a multiple of the compressed texel block |
| depth or [eq]#(pname:extent.depth {plus} pname:dstOffset.z)# must: equal |
| the destination image subresource depth |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| **** |
| |
| include::../validity/structs/VkImageCopy.txt[] |
| -- |
| |
| [open,refpage='VkImageSubresourceLayers',desc='Structure specifying an image subresource layers',type='structs'] |
| -- |
| |
| The sname:VkImageSubresourceLayers structure is defined as: |
| |
| include::../api/structs/VkImageSubresourceLayers.txt[] |
| |
| * pname:aspectMask is a combination of elink:VkImageAspectFlagBits, |
| selecting the color, depth and/or stencil aspects to be copied. |
| * pname:mipLevel is the mipmap level to copy from. |
| * pname:baseArrayLayer and pname:layerCount are the starting layer and |
| number of layers to copy. |
| |
| .Valid Usage |
| **** |
| * [[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 |
| * [[VUID-VkImageSubresourceLayers-layerCount-01700]] |
| pname:layerCount must: be greater than 0 |
| **** |
| |
| include::../validity/structs/VkImageSubresourceLayers.txt[] |
| -- |
| |
| |
| [[copies-buffers-images]] |
| == Copying Data Between Buffers and Images |
| |
| [open,refpage='vkCmdCopyBufferToImage',desc='Copy data from a buffer into an image',type='protos'] |
| -- |
| |
| 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. |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| If the format of pname:dstImage is a |
| <<features-formats-requiring-sampler-ycbcr-conversion,multi-planar image |
| 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 |
| <<features-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 |
| **** |
| * [[VUID-vkCmdCopyBufferToImage-pRegions-00171]] |
| pname:srcBuffer must: be large enough to contain all buffer locations |
| that are accessed according to <<copies-buffers-images-addressing,Buffer |
| and Image Addressing>>, for each element of pname:pRegions |
| * [[VUID-vkCmdCopyBufferToImage-pRegions-00172]] |
| The image region specified by each element of pname:pRegions must: be a |
| region that is contained within pname:dstImage |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| if the pname:dstImage's elink:VkFormat is not a |
| <<features-formats-requiring-sampler-ycbcr-conversion,multi-planar |
| format>>, and must: be a region that is contained within the plane being |
| copied to if the pname:dstImage's elink:VkFormat is a multi-planar |
| format |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-vkCmdCopyBufferToImage-pRegions-00173]] |
| The union of all source regions, and the union of all destination |
| regions, specified by the elements of pname:pRegions, must: not overlap |
| in memory |
| * [[VUID-vkCmdCopyBufferToImage-srcBuffer-00174]] |
| pname:srcBuffer must: have been created with |
| ename:VK_BUFFER_USAGE_TRANSFER_SRC_BIT usage flag |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * [[VUID-vkCmdCopyBufferToImage-dstImage-01997]] |
| The <<resources-image-format-features,format features>> of |
| pname:dstImage must: contain ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT. |
| endif::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * [[VUID-vkCmdCopyBufferToImage-srcBuffer-00176]] |
| If pname:srcBuffer is non-sparse then it must: be bound completely and |
| contiguously to a single sname:VkDeviceMemory object |
| * [[VUID-vkCmdCopyBufferToImage-dstImage-00177]] |
| pname:dstImage must: have been created with |
| ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag |
| * [[VUID-vkCmdCopyBufferToImage-dstImage-00178]] |
| If pname:dstImage is non-sparse then it must: be bound completely and |
| contiguously to a single sname:VkDeviceMemory object |
| * [[VUID-vkCmdCopyBufferToImage-dstImage-00179]] |
| pname:dstImage must: have a sample count equal to |
| ename:VK_SAMPLE_COUNT_1_BIT |
| * [[VUID-vkCmdCopyBufferToImage-dstImageLayout-00180]] |
| pname:dstImageLayout must: specify the layout of the image subresources |
| of pname:dstImage specified in pname:pRegions at the time this command |
| is executed on a sname:VkDevice |
| ifndef::VK_KHR_shared_presentable_image[] |
| * [[VUID-vkCmdCopyBufferToImage-dstImageLayout-00181]] |
| pname:dstImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL |
| or ename:VK_IMAGE_LAYOUT_GENERAL |
| endif::VK_KHR_shared_presentable_image[] |
| ifdef::VK_KHR_shared_presentable_image[] |
| * [[VUID-vkCmdCopyBufferToImage-dstImageLayout-01396]] |
| pname:dstImageLayout must: be |
| ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, |
| ename:VK_IMAGE_LAYOUT_GENERAL, or |
| ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR |
| endif::VK_KHR_shared_presentable_image[] |
| ifdef::VK_VERSION_1_1[] |
| * [[VUID-vkCmdCopyBufferToImage-commandBuffer-01828]] |
| If pname:commandBuffer is an unprotected command buffer, then |
| pname:srcBuffer must: not be a protected buffer |
| * [[VUID-vkCmdCopyBufferToImage-commandBuffer-01829]] |
| If pname:commandBuffer is an unprotected command buffer, then |
| pname:dstImage must: not be a protected image |
| * [[VUID-vkCmdCopyBufferToImage-commandBuffer-01830]] |
| If pname:commandBuffer is a protected command buffer, then |
| pname:dstImage must: not be an unprotected image |
| endif::VK_VERSION_1_1[] |
| * [[VUID-vkCmdCopyBufferToImage-imageSubresource-01701]] |
| The pname:imageSubresource.mipLevel member of each element of |
| pname:pRegions must: be less than the pname:mipLevels specified in |
| slink:VkImageCreateInfo when pname:dstImage was created |
| * [[VUID-vkCmdCopyBufferToImage-imageSubresource-01702]] |
| The [eq]#pname:imageSubresource.baseArrayLayer {plus} |
| pname:imageSubresource.layerCount# of each element of pname:pRegions |
| must: be less than or equal to the pname:arrayLayers specified in |
| slink:VkImageCreateInfo when pname:dstImage was created |
| * [[VUID-vkCmdCopyBufferToImage-imageOffset-01793]] |
| The pname:imageOffset and pname:imageExtent members of each element of |
| pname:pRegions must: respect the image transfer granularity requirements |
| of pname:commandBuffer's command pool's queue family, as described in |
| slink:VkQueueFamilyProperties |
| **** |
| |
| include::../validity/protos/vkCmdCopyBufferToImage.txt[] |
| -- |
| |
| [open,refpage='vkCmdCopyImageToBuffer',desc='Copy image data into a buffer',type='protos'] |
| -- |
| |
| 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. |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| If the elink:VkFormat of pname:srcImage is a |
| <<features-formats-requiring-sampler-ycbcr-conversion,multi-planar image |
| 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 |
| <<features-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 |
| **** |
| * [[VUID-vkCmdCopyImageToBuffer-pRegions-00182]] |
| The image region specified by each element of pname:pRegions must: be a |
| region that is contained within pname:srcImage |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| if the pname:srcImage's elink:VkFormat is not a |
| <<features-formats-requiring-sampler-ycbcr-conversion,multi-planar |
| format>>, and must: be a region that is contained within the plane being |
| copied if the pname:srcImage's elink:VkFormat is a multi-planar format |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-vkCmdCopyImageToBuffer-pRegions-00183]] |
| pname:dstBuffer must: be large enough to contain all buffer locations |
| that are accessed according to <<copies-buffers-images-addressing,Buffer |
| and Image Addressing>>, for each element of pname:pRegions |
| * [[VUID-vkCmdCopyImageToBuffer-pRegions-00184]] |
| The union of all source regions, and the union of all destination |
| regions, specified by the elements of pname:pRegions, must: not overlap |
| in memory |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * [[VUID-vkCmdCopyImageToBuffer-srcImage-01998]] |
| The <<resources-image-format-features,format features>> of |
| pname:srcImage must: contain ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT. |
| endif::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * [[VUID-vkCmdCopyImageToBuffer-srcImage-00186]] |
| pname:srcImage must: have been created with |
| ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag |
| * [[VUID-vkCmdCopyImageToBuffer-srcImage-00187]] |
| If pname:srcImage is non-sparse then it must: be bound completely and |
| contiguously to a single sname:VkDeviceMemory object |
| * [[VUID-vkCmdCopyImageToBuffer-srcImage-00188]] |
| pname:srcImage must: have a sample count equal to |
| ename:VK_SAMPLE_COUNT_1_BIT |
| * [[VUID-vkCmdCopyImageToBuffer-srcImageLayout-00189]] |
| pname:srcImageLayout must: specify the layout of the image subresources |
| of pname:srcImage specified in pname:pRegions at the time this command |
| is executed on a sname:VkDevice |
| ifndef::VK_KHR_shared_presentable_image[] |
| * [[VUID-vkCmdCopyImageToBuffer-srcImageLayout-00190]] |
| pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL |
| or ename:VK_IMAGE_LAYOUT_GENERAL |
| endif::VK_KHR_shared_presentable_image[] |
| ifdef::VK_KHR_shared_presentable_image[] |
| * [[VUID-vkCmdCopyImageToBuffer-srcImageLayout-01397]] |
| pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, |
| ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or |
| ename:VK_IMAGE_LAYOUT_GENERAL |
| endif::VK_KHR_shared_presentable_image[] |
| * [[VUID-vkCmdCopyImageToBuffer-dstBuffer-00191]] |
| pname:dstBuffer must: have been created with |
| ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag |
| * [[VUID-vkCmdCopyImageToBuffer-dstBuffer-00192]] |
| If pname:dstBuffer is non-sparse then it must: be bound completely and |
| contiguously to a single sname:VkDeviceMemory object |
| ifdef::VK_VERSION_1_1[] |
| * [[VUID-vkCmdCopyImageToBuffer-commandBuffer-01831]] |
| If pname:commandBuffer is an unprotected command buffer, then |
| pname:srcImage must: not be a protected image |
| * [[VUID-vkCmdCopyImageToBuffer-commandBuffer-01832]] |
| If pname:commandBuffer is an unprotected command buffer, then |
| pname:dstBuffer must: not be a protected buffer |
| * [[VUID-vkCmdCopyImageToBuffer-commandBuffer-01833]] |
| If pname:commandBuffer is a protected command buffer, then |
| pname:dstBuffer must: not be an unprotected buffer |
| endif::VK_VERSION_1_1[] |
| * [[VUID-vkCmdCopyImageToBuffer-imageSubresource-01703]] |
| The pname:imageSubresource.mipLevel member of each element of |
| pname:pRegions must: be less than the pname:mipLevels specified in |
| slink:VkImageCreateInfo when pname:srcImage was created |
| * [[VUID-vkCmdCopyImageToBuffer-imageSubresource-01704]] |
| The [eq]#pname:imageSubresource.baseArrayLayer {plus} |
| pname:imageSubresource.layerCount# of each element of pname:pRegions |
| must: be less than or equal to the pname:arrayLayers specified in |
| slink:VkImageCreateInfo when pname:srcImage was created |
| * [[VUID-vkCmdCopyImageToBuffer-imageOffset-01794]] |
| The pname:imageOffset and pname:imageExtent members of each element of |
| pname:pRegions must: respect the image transfer granularity requirements |
| of pname:commandBuffer's command pool's queue family, as described in |
| slink:VkQueueFamilyProperties |
| **** |
| |
| include::../validity/protos/vkCmdCopyImageToBuffer.txt[] |
| -- |
| |
| [open,refpage='VkBufferImageCopy',desc='Structure specifying a buffer image copy operation',type='structs'] |
| -- |
| |
| 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 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, the data in buffer memory must: be in the |
| the range [eq]#[0,1]# or undefined results occur. |
| |
| Copies are done layer by layer starting with image layer |
| pname:baseArrayLayer member of pname:imageSubresource. |
| pname:layerCount layers are copied from the source image or to the |
| destination image. |
| |
| .Valid Usage |
| **** |
| ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkBufferImageCopy-bufferOffset-00193]] |
| If the calling command's sname:VkImage parameter's format is not a |
| depth/stencil format, then pname:bufferOffset must: be a multiple of the |
| format's element size |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkBufferImageCopy-bufferOffset-01558]] |
| If the calling command's sname:VkImage parameter's format is not a |
| depth/stencil format or a |
| <<features-formats-requiring-sampler-ycbcr-conversion,multi-planar |
| format>>, then pname:bufferOffset must: be a multiple of the format's |
| element size |
| * [[VUID-VkBufferImageCopy-bufferOffset-01559]] |
| If the calling command's sname:VkImage parameter's format is a |
| <<features-formats-requiring-sampler-ycbcr-conversion,multi-planar |
| format>>, then pname:bufferOffset must: be a multiple of the element |
| size of the compatible format for the format and the pname:aspectMask of |
| the pname:imageSubresource as defined in |
| <<features-formats-compatible-planes>> |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkBufferImageCopy-bufferOffset-00194]] |
| pname:bufferOffset must: be a multiple of `4` |
| * [[VUID-VkBufferImageCopy-bufferRowLength-00195]] |
| pname:bufferRowLength must: be `0`, or greater than or equal to the |
| pname:width member of pname:imageExtent |
| * [[VUID-VkBufferImageCopy-bufferImageHeight-00196]] |
| pname:bufferImageHeight must: be `0`, or greater than or equal to the |
| pname:height member of pname:imageExtent |
| * [[VUID-VkBufferImageCopy-imageOffset-00197]] |
| 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 image subresource width |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| where this refers to the width of the _plane_ of the image involved in |
| the copy in the case of a |
| <<features-formats-requiring-sampler-ycbcr-conversion,multi-planar |
| format>> |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkBufferImageCopy-imageOffset-00198]] |
| 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 image subresource height |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| where this refers to the height of the _plane_ of the image involved in |
| the copy in the case of a |
| <<features-formats-requiring-sampler-ycbcr-conversion,multi-planar |
| format>> |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkBufferImageCopy-srcImage-00199]] |
| If the calling command's pname:srcImage (flink:vkCmdCopyImageToBuffer) |
| or pname:dstImage (flink:vkCmdCopyBufferToImage) is of type |
| ename:VK_IMAGE_TYPE_1D, then pname:imageOffset.y must: be `0` and |
| pname:imageExtent.height must: be `1`. |
| * [[VUID-VkBufferImageCopy-imageOffset-00200]] |
| pname:imageOffset.z and [eq]#(imageExtent.depth {plus} |
| pname:imageOffset.z)# must: both be greater than or equal to `0` and |
| less than or equal to the image subresource depth |
| * [[VUID-VkBufferImageCopy-srcImage-00201]] |
| If the calling command's pname:srcImage (flink:vkCmdCopyImageToBuffer) |
| or pname:dstImage (flink:vkCmdCopyBufferToImage) is of type |
| ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then |
| pname:imageOffset.z must: be `0` and pname:imageExtent.depth must: be |
| `1` |
| // The block of VU below come in alternate versions when the extension is |
| // enabled. |
| ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkBufferImageCopy-bufferRowLength-00203]] |
| If the calling command's sname:VkImage parameter is a compressed image, |
| pname:bufferRowLength must: be a multiple of the compressed texel block |
| width |
| * [[VUID-VkBufferImageCopy-bufferImageHeight-00204]] |
| If the calling command's sname:VkImage parameter is a compressed image, |
| pname:bufferImageHeight must: be a multiple of the compressed texel |
| block height |
| * [[VUID-VkBufferImageCopy-imageOffset-00205]] |
| If the calling command's sname:VkImage parameter is a compressed image, |
| all members of pname:imageOffset must: be a multiple of the |
| corresponding dimensions of the compressed texel block |
| * [[VUID-VkBufferImageCopy-bufferOffset-00206]] |
| If the calling command's sname:VkImage parameter is a compressed image, |
| pname:bufferOffset must: be a multiple of the compressed texel block |
| size in bytes |
| * [[VUID-VkBufferImageCopy-imageExtent-00207]] |
| If the calling command's sname:VkImage parameter is a compressed image, |
| pname:imageExtent.width must: be a multiple of the compressed texel |
| block width or [eq]#(pname:imageExtent.width {plus} |
| pname:imageOffset.x)# must: equal the image subresource width |
| * [[VUID-VkBufferImageCopy-imageExtent-00208]] |
| If the calling command's sname:VkImage parameter is a compressed image, |
| pname:imageExtent.height must: be a multiple of the compressed texel |
| block height or [eq]#(pname:imageExtent.height {plus} |
| pname:imageOffset.y)# must: equal the image subresource height |
| * [[VUID-VkBufferImageCopy-imageExtent-00209]] |
| If the calling command's sname:VkImage parameter is a compressed image, |
| pname:imageExtent.depth must: be a multiple of the compressed texel |
| block depth or [eq]#(pname:imageExtent.depth {plus} |
| pname:imageOffset.z)# must: equal the image subresource depth |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| // The nested ifdefs are there in anticipation of the hoped-for day when the |
| // VU extractor and validation layers can handle VU with imbedded |
| // conditionals. They are commented out until then. |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkBufferImageCopy-None-01735]] |
| If the calling command's sname:VkImage parameter is a compressed image, |
| // ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| or a _single-plane_, "`etext:_422`" image format, |
| // endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| pname:bufferRowLength must: be a multiple of the compressed texel block |
| width |
| * [[VUID-VkBufferImageCopy-None-01736]] |
| If the calling command's sname:VkImage parameter is a compressed image, |
| // ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| or a _single-plane_, "`etext:_422`" image format, |
| // endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| pname:bufferImageHeight must: be a multiple of the compressed texel |
| block height |
| * [[VUID-VkBufferImageCopy-None-01737]] |
| If the calling command's sname:VkImage parameter is a compressed image, |
| // ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| or a _single-plane_, "`etext:_422`" image format, |
| // endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| all members of pname:imageOffset must: be a multiple of the |
| corresponding dimensions of the compressed texel block |
| * [[VUID-VkBufferImageCopy-None-01738]] |
| If the calling command's sname:VkImage parameter is a compressed image, |
| // ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| or a _single-plane_, "`etext:_422`" image format, |
| // endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| pname:bufferOffset must: be a multiple of the compressed texel block |
| size in bytes |
| * [[VUID-VkBufferImageCopy-None-01739]] |
| If the calling command's sname:VkImage parameter is a compressed image, |
| // ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| or a _single-plane_, "`etext:_422`" image format, |
| // endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| pname:imageExtent.width must: be a multiple of the compressed texel |
| block width or [eq]#(pname:imageExtent.width {plus} |
| pname:imageOffset.x)# must: equal the image subresource width |
| * [[VUID-VkBufferImageCopy-None-01740]] |
| If the calling command's sname:VkImage parameter is a compressed image, |
| // ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| or a _single-plane_, "`etext:_422`" image format, |
| // endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| pname:imageExtent.height must: be a multiple of the compressed texel |
| block height or [eq]#(pname:imageExtent.height {plus} |
| pname:imageOffset.y)# must: equal the image subresource height |
| * [[VUID-VkBufferImageCopy-None-01741]] |
| If the calling command's sname:VkImage parameter is a compressed image, |
| // ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| or a _single-plane_, "`etext:_422`" image format, |
| // endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| pname:imageExtent.depth must: be a multiple of the compressed texel |
| block depth or [eq]#(pname:imageExtent.depth {plus} |
| pname:imageOffset.z)# must: equal the image subresource depth |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkBufferImageCopy-aspectMask-00211]] |
| The pname:aspectMask member of pname:imageSubresource must: specify |
| aspects present in the calling command's sname:VkImage parameter |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkBufferImageCopy-aspectMask-01560]] |
| If the calling command's sname:VkImage parameter's format is a |
| <<features-formats-requiring-sampler-ycbcr-conversion,multi-planar |
| format>>, then the pname:aspectMask member 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 |
| (with ename:VK_IMAGE_ASPECT_PLANE_2_BIT valid only for image formats |
| with three planes) |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkBufferImageCopy-aspectMask-00212]] |
| The pname:aspectMask member of pname:imageSubresource must: only have a |
| single bit set |
| * [[VUID-VkBufferImageCopy-baseArrayLayer-00213]] |
| If the calling command's sname:VkImage parameter is of elink:VkImageType |
| ename:VK_IMAGE_TYPE_3D, the pname:baseArrayLayer and pname:layerCount |
| members of pname:imageSubresource must: be `0` and `1`, respectively |
| * [[VUID-VkBufferImageCopy-None-00214]] |
| When copying to the depth aspect of an image subresource, the data in |
| the source buffer must: be in the range [eq]#[0,1]# |
| **** |
| |
| include::../validity/structs/VkBufferImageCopy.txt[] |
| -- |
| |
| [[copies-buffers-images-addressing]] |
| === Buffer and Image Addressing |
| |
| Pseudocode for image/buffer addressing is: |
| |
| [source,c] |
| --------------------------------------------------- |
| rowLength = region->bufferRowLength; |
| if (rowLength == 0) |
| rowLength = region->imageExtent.width; |
| |
| imageHeight = region->bufferImageHeight; |
| if (imageHeight == 0) |
| imageHeight = region->imageExtent.height; |
| |
| elementSize = <element size of the format of the src/dstImage>; |
| |
| address of (x,y,z) = region->bufferOffset + (((z * imageHeight) + y) * rowLength + x) * elementSize; |
| |
| where x,y,z range from (0,0,0) to region->imageExtent.{width,height,depth}. |
| --------------------------------------------------- |
| |
| Note that pname:imageOffset does not affect addressing calculations for |
| buffer memory. |
| Instead, pname:bufferOffset can: be used to select the starting address in |
| buffer memory. |
| |
| For block-compression formats, all parameters are still specified in texels |
| rather than compressed texel blocks, but the addressing math operates on |
| whole compressed texel blocks. |
| Pseudocode for compressed copy addressing is: |
| |
| [source,c] |
| --------------------------------------------------- |
| rowLength = region->bufferRowLength; |
| if (rowLength == 0) |
| rowLength = region->imageExtent.width; |
| |
| imageHeight = region->bufferImageHeight; |
| if (imageHeight == 0) |
| imageHeight = region->imageExtent.height; |
| |
| compressedTexelBlockSizeInBytes = <compressed texel block size taken from the src/dstImage>; |
| rowLength /= compressedTexelBlockWidth; |
| imageHeight /= compressedTexelBlockHeight; |
| |
| address of (x,y,z) = region->bufferOffset + (((z * imageHeight) + y) * rowLength + x) * compressedTexelBlockSizeInBytes; |
| |
| where x,y,z range from (0,0,0) to region->imageExtent.{width/compressedTexelBlockWidth,height/compressedTexelBlockHeight,depth/compressedTexelBlockDepth}. |
| --------------------------------------------------- |
| |
| Copying to or from block-compressed images is typically done in multiples of |
| the compressed texel block size. |
| For this reason the pname:imageExtent must: be a multiple of the compressed |
| texel block dimension. |
| There is one exception to this rule which is required: to handle compressed |
| images created with dimensions that are not a multiple of the compressed |
| texel block dimensions: |
| |
| * If pname:imageExtent.width is not a multiple of the compressed texel |
| block width, then [eq]#(pname:imageExtent.width {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. |
| |
| |
| [[copies-imagescaling]] |
| == Image Copies with Scaling |
| |
| [open,refpage='vkCmdBlitImage',desc='Copy regions of an image, potentially performing format conversion,',type='protos'] |
| -- |
| |
| To copy regions of a source image into a destination image, potentially |
| performing format conversion, arbitrary scaling, and filtering, call: |
| |
| include::../api/protos/vkCmdBlitImage.txt[] |
| |
| * pname:commandBuffer is the command buffer into which the command will be |
| recorded. |
| * pname:srcImage is the source image. |
| * pname:srcImageLayout is the layout of the source image subresources for |
| the blit. |
| * pname:dstImage is the destination image. |
| * pname:dstImageLayout is the layout of the destination image subresources |
| for the blit. |
| * pname:regionCount is the number of regions to blit. |
| * pname:pRegions is a pointer to an array of slink:VkImageBlit structures |
| specifying the regions to blit. |
| * pname:filter is a elink:VkFilter specifying the filter to apply if the |
| blits require scaling. |
| |
| fname:vkCmdBlitImage must: not be used for multisampled source or |
| destination images. |
| Use flink:vkCmdResolveImage for this purpose. |
| |
| As the sizes of the source and destination extents can: differ in any |
| dimension, texels in the source extent are scaled and filtered to the |
| destination extent. |
| Scaling occurs via the following operations: |
| |
| * For each destination texel, the integer coordinate of that texel is |
| converted to an unnormalized texture coordinate, using the effective |
| inverse of the equations described in |
| <<textures-unnormalized-to-integer, unnormalized to integer |
| conversion>>: |
| :: [eq]#u~base~ = i {plus} {onehalf}# |
| :: [eq]#v~base~ = j {plus} {onehalf}# |
| :: [eq]#w~base~ = k {plus} {onehalf}# |
| * These base coordinates are then offset by the first destination |
| offset: |
| :: [eq]#u~offset~ = u~base~ - x~dst0~# |
| :: [eq]#v~offset~ = v~base~ - y~dst0~# |
| :: [eq]#w~offset~ = w~base~ - z~dst0~# |
| :: [eq]#a~offset~ = a - pname:baseArrayCount~dst~# |
| * The scale is determined from the source and destination regions, and |
| applied to the offset coordinates: |
| :: [eq]#scale_u = (x~src1~ - x~src0~) / (x~dst1~ - x~dst0~)# |
| :: [eq]#scale_v = (y~src1~ - y~src0~) / (y~dst1~ - y~dst0~)# |
| :: [eq]#scale_w = (z~src1~ - z~src0~) / (z~dst1~ - z~dst0~)# |
| :: [eq]#u~scaled~ = u~offset~ * scale~u~# |
| :: [eq]#v~scaled~ = v~offset~ * scale~v~# |
| :: [eq]#w~scaled~ = w~offset~ * scale~w~# |
| * Finally the source offset is added to the scaled coordinates, to |
| determine the final unnormalized coordinates used to sample from |
| pname:srcImage: + |
| :: [eq]#u = u~scaled~ {plus} x~src0~# |
| :: [eq]#v = v~scaled~ {plus} y~src0~# |
| :: [eq]#w = w~scaled~ {plus} z~src0~# |
| :: [eq]#q = pname:mipLevel# |
| :: [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. |
| |
| 3D textures are blitted slice by slice. |
| Slices in the source region bounded by pname:srcOffsets[0].pname:z and |
| pname:srcOffsets[1].pname:z are copied to slices in the destination region |
| bounded by pname:dstOffsets[0].pname:z and pname:dstOffsets[1].pname:z. |
| For each destination slice, a source *z* coordinate is linearly interpolated |
| between pname:srcOffsets[0].pname:z and pname:srcOffsets[1].pname:z. |
| If the pname:filter parameter is ename:VK_FILTER_LINEAR then the value |
| sampled from the source image is taken by doing linear filtering using the |
| interpolated *z* coordinate. |
| If pname:filter parameter is ename:VK_FILTER_NEAREST then value sampled from |
| the source image is taken from the single nearest slice (with undefined |
| rounding mode). |
| |
| The following filtering and conversion rules apply: |
| |
| * Integer formats can: only be converted to other integer formats with the |
| same signedness. |
| * No format conversion is supported between depth/stencil images. |
| The formats must: match. |
| * Format conversions on unorm, snorm, unscaled and packed float formats of |
| the copied aspect of the image are performed by first converting the |
| pixels to float values. |
| * For sRGB source formats, nonlinear RGB values are converted to linear |
| representation prior to filtering. |
| * After filtering, the float values are first clamped and then cast to the |
| destination image format. |
| In case of sRGB destination format, linear RGB values are converted to |
| nonlinear representation before writing the pixel to the image. |
| |
| Signed and unsigned integers are converted by first clamping to the |
| representable range of the destination format, then casting the value. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCmdBlitImage-pRegions-00215]] |
| The source region specified by each element of pname:pRegions must: be a |
| region that is contained within pname:srcImage |
| * [[VUID-vkCmdBlitImage-pRegions-00216]] |
| The destination region specified by each element of pname:pRegions must: |
| be a region that is contained within pname:dstImage |
| * [[VUID-vkCmdBlitImage-pRegions-00217]] |
| The union of all destination regions, specified by the elements of |
| pname:pRegions, must: not overlap in memory with any texel that may: be |
| sampled during the blit operation |
| * [[VUID-vkCmdBlitImage-srcImage-01999]] |
| The <<resources-image-format-features,format features>> of |
| pname:srcImage must: contain ename:VK_FORMAT_FEATURE_BLIT_SRC_BIT. |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-vkCmdBlitImage-srcImage-01561]] |
| pname:srcImage must: not use a format listed in |
| <<features-formats-requiring-sampler-ycbcr-conversion>> |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-vkCmdBlitImage-srcImage-00219]] |
| pname:srcImage must: have been created with |
| ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag |
| * [[VUID-vkCmdBlitImage-srcImage-00220]] |
| If pname:srcImage is non-sparse then it must: be bound completely and |
| contiguously to a single sname:VkDeviceMemory object |
| * [[VUID-vkCmdBlitImage-srcImageLayout-00221]] |
| pname:srcImageLayout must: specify the layout of the image subresources |
| of pname:srcImage specified in pname:pRegions at the time this command |
| is executed on a sname:VkDevice |
| ifndef::VK_KHR_shared_presentable_image[] |
| * [[VUID-vkCmdBlitImage-srcImageLayout-00222]] |
| pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL |
| or ename:VK_IMAGE_LAYOUT_GENERAL |
| endif::VK_KHR_shared_presentable_image[] |
| ifdef::VK_KHR_shared_presentable_image[] |
| * [[VUID-vkCmdBlitImage-srcImageLayout-01398]] |
| pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, |
| ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or |
| ename:VK_IMAGE_LAYOUT_GENERAL |
| endif::VK_KHR_shared_presentable_image[] |
| * [[VUID-vkCmdBlitImage-dstImage-02000]] |
| The <<resources-image-format-features,format features>> of |
| pname:dstImage must: contain ename:VK_FORMAT_FEATURE_BLIT_DST_BIT. |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-vkCmdBlitImage-dstImage-01562]] |
| pname:dstImage must: not use a format listed in |
| <<features-formats-requiring-sampler-ycbcr-conversion>> |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-vkCmdBlitImage-dstImage-00224]] |
| pname:dstImage must: have been created with |
| ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag |
| * [[VUID-vkCmdBlitImage-dstImage-00225]] |
| If pname:dstImage is non-sparse then it must: be bound completely and |
| contiguously to a single sname:VkDeviceMemory object |
| * [[VUID-vkCmdBlitImage-dstImageLayout-00226]] |
| pname:dstImageLayout must: specify the layout of the image subresources |
| of pname:dstImage specified in pname:pRegions at the time this command |
| is executed on a sname:VkDevice |
| ifndef::VK_KHR_shared_presentable_image[] |
| * [[VUID-vkCmdBlitImage-dstImageLayout-00227]] |
| pname:dstImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL |
| or ename:VK_IMAGE_LAYOUT_GENERAL |
| endif::VK_KHR_shared_presentable_image[] |
| ifdef::VK_KHR_shared_presentable_image[] |
| * [[VUID-vkCmdBlitImage-dstImageLayout-01399]] |
| pname:dstImageLayout must: be ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, |
| ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or |
| ename:VK_IMAGE_LAYOUT_GENERAL |
| endif::VK_KHR_shared_presentable_image[] |
| * [[VUID-vkCmdBlitImage-srcImage-00228]] |
| The sample count of pname:srcImage and pname:dstImage must: both be |
| equal to ename:VK_SAMPLE_COUNT_1_BIT |
| * [[VUID-vkCmdBlitImage-srcImage-00229]] |
| If either of pname:srcImage or pname:dstImage was created with a signed |
| integer elink:VkFormat, the other must: also have been created with a |
| signed integer elink:VkFormat |
| * [[VUID-vkCmdBlitImage-srcImage-00230]] |
| If either of pname:srcImage or pname:dstImage was created with an |
| unsigned integer elink:VkFormat, the other must: also have been created |
| with an unsigned integer elink:VkFormat |
| * [[VUID-vkCmdBlitImage-srcImage-00231]] |
| If either of pname:srcImage or pname:dstImage was created with a |
| depth/stencil format, the other must: have exactly the same format |
| * [[VUID-vkCmdBlitImage-srcImage-00232]] |
| If pname:srcImage was created with a depth/stencil format, pname:filter |
| must: be ename:VK_FILTER_NEAREST |
| * [[VUID-vkCmdBlitImage-srcImage-00233]] |
| pname:srcImage must: have been created with a pname:samples value of |
| ename:VK_SAMPLE_COUNT_1_BIT |
| * [[VUID-vkCmdBlitImage-dstImage-00234]] |
| pname:dstImage must: have been created with a pname:samples value of |
| ename:VK_SAMPLE_COUNT_1_BIT |
| * [[VUID-vkCmdBlitImage-filter-02001]] |
| If pname:filter is ename:VK_FILTER_LINEAR, then the |
| <<resources-image-format-features,format features>> of pname:srcImage |
| must: contain ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT. |
| ifdef::VK_IMG_filter_cubic[] |
| * [[VUID-vkCmdBlitImage-filter-02002]] |
| If pname:filter is ename:VK_FILTER_CUBIC_IMG, then the |
| <<resources-image-format-features,format features>> of pname:srcImage |
| must: contain |
| ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG. |
| * [[VUID-vkCmdBlitImage-filter-00237]] |
| If pname:filter is ename:VK_FILTER_CUBIC_IMG, pname:srcImage must: have |
| a elink:VkImageType of ename:VK_IMAGE_TYPE_2D |
| endif::VK_IMG_filter_cubic[] |
| ifdef::VK_VERSION_1_1[] |
| * [[VUID-vkCmdBlitImage-commandBuffer-01834]] |
| If pname:commandBuffer is an unprotected command buffer, then |
| pname:srcImage must: not be a protected image |
| * [[VUID-vkCmdBlitImage-commandBuffer-01835]] |
| If pname:commandBuffer is an unprotected command buffer, then |
| pname:dstImage must: not be a protected image |
| * [[VUID-vkCmdBlitImage-commandBuffer-01836]] |
| If pname:commandBuffer is a protected command buffer, then |
| pname:dstImage must: not be an unprotected image |
| endif::VK_VERSION_1_1[] |
| * [[VUID-vkCmdBlitImage-srcSubresource-01705]] |
| The pname:srcSubresource.mipLevel member of each element of |
| pname:pRegions must: be less than the pname:mipLevels specified in |
| slink:VkImageCreateInfo when pname:srcImage was created |
| * [[VUID-vkCmdBlitImage-dstSubresource-01706]] |
| The pname:dstSubresource.mipLevel member of each element of |
| pname:pRegions must: be less than the pname:mipLevels specified in |
| slink:VkImageCreateInfo when pname:dstImage was created |
| * [[VUID-vkCmdBlitImage-srcSubresource-01707]] |
| The [eq]#pname:srcSubresource.baseArrayLayer {plus} |
| pname:srcSubresource.layerCount# of each element of pname:pRegions must: |
| be less than or equal to the pname:arrayLayers specified in |
| slink:VkImageCreateInfo when pname:srcImage was created |
| * [[VUID-vkCmdBlitImage-dstSubresource-01708]] |
| The [eq]#pname:dstSubresource.baseArrayLayer {plus} |
| pname:dstSubresource.layerCount# of each element of pname:pRegions must: |
| be less than or equal to the pname:arrayLayers specified in |
| slink:VkImageCreateInfo when pname:dstImage was created |
| **** |
| |
| include::../validity/protos/vkCmdBlitImage.txt[] |
| -- |
| |
| [open,refpage='VkImageBlit',desc='Structure specifying an image blit operation',type='structs'] |
| -- |
| |
| The sname:VkImageBlit structure is defined as: |
| |
| include::../api/structs/VkImageBlit.txt[] |
| |
| * pname:srcSubresource is the subresource to blit from. |
| * pname:srcOffsets is an array of two slink:VkOffset3D structures |
| specifying the bounds of the source region within pname:srcSubresource. |
| * pname:dstSubresource is the subresource to blit into. |
| * pname:dstOffsets is an array of two slink:VkOffset3D structures |
| specifying the bounds of the destination region within |
| pname:dstSubresource. |
| |
| For each element of the pname:pRegions array, a blit operation is performed |
| the specified source and destination regions. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkImageBlit-aspectMask-00238]] |
| The pname:aspectMask member of pname:srcSubresource and |
| pname:dstSubresource must: match |
| * [[VUID-VkImageBlit-layerCount-00239]] |
| The pname:layerCount member of pname:srcSubresource and |
| pname:dstSubresource must: match |
| * [[VUID-VkImageBlit-srcImage-00240]] |
| If either of the calling command's pname:srcImage or pname:dstImage |
| parameters are of elink:VkImageType ename:VK_IMAGE_TYPE_3D, the |
| pname:baseArrayLayer and pname:layerCount members of both |
| pname:srcSubresource and pname:dstSubresource must: be `0` and `1`, |
| respectively |
| * [[VUID-VkImageBlit-aspectMask-00241]] |
| The pname:aspectMask member of pname:srcSubresource must: specify |
| aspects present in the calling command's pname:srcImage |
| * [[VUID-VkImageBlit-aspectMask-00242]] |
| The pname:aspectMask member of pname:dstSubresource must: specify |
| aspects present in the calling command's pname:dstImage |
| * [[VUID-VkImageBlit-srcOffset-00243]] |
| pname:srcOffset[0].pname:x and pname:srcOffset[1].pname:x must: both be |
| greater than or equal to `0` and less than or equal to the source image |
| subresource width |
| * [[VUID-VkImageBlit-srcOffset-00244]] |
| pname:srcOffset[0].pname:y and pname:srcOffset[1].pname:y must: both be |
| greater than or equal to `0` and less than or equal to the source image |
| subresource height |
| * [[VUID-VkImageBlit-srcImage-00245]] |
| If the calling command's pname:srcImage is of type |
| ename:VK_IMAGE_TYPE_1D, then pname:srcOffset[0].y must: be `0` and |
| pname:srcOffset[1].y must: be `1`. |
| * [[VUID-VkImageBlit-srcOffset-00246]] |
| pname:srcOffset[0].pname:z and pname:srcOffset[1].pname:z must: both be |
| greater than or equal to `0` and less than or equal to the source image |
| subresource depth |
| * [[VUID-VkImageBlit-srcImage-00247]] |
| If the calling command's pname:srcImage is of type |
| ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then |
| pname:srcOffset[0].z must: be `0` and pname:srcOffset[1].z must: be `1`. |
| * [[VUID-VkImageBlit-dstOffset-00248]] |
| pname:dstOffset[0].pname:x and pname:dstOffset[1].pname:x must: both be |
| greater than or equal to `0` and less than or equal to the destination |
| image subresource width |
| * [[VUID-VkImageBlit-dstOffset-00249]] |
| pname:dstOffset[0].pname:y and pname:dstOffset[1].pname:y must: both be |
| greater than or equal to `0` and less than or equal to the destination |
| image subresource height |
| * [[VUID-VkImageBlit-dstImage-00250]] |
| If the calling command's pname:dstImage is of type |
| ename:VK_IMAGE_TYPE_1D, then pname:dstOffset[0].y must: be `0` and |
| pname:dstOffset[1].y must: be `1`. |
| * [[VUID-VkImageBlit-dstOffset-00251]] |
| pname:dstOffset[0].pname:z and pname:dstOffset[1].pname:z must: both be |
| greater than or equal to `0` and less than or equal to the destination |
| image subresource depth |
| * [[VUID-VkImageBlit-dstImage-00252]] |
| If the calling command's pname:dstImage is of type |
| ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then |
| pname:dstOffset[0].z must: be `0` and pname:dstOffset[1].z must: be `1`. |
| **** |
| |
| include::../validity/structs/VkImageBlit.txt[] |
| -- |
| |
| |
| [[copies-resolve]] |
| == Resolving Multisample Images |
| |
| [open,refpage='vkCmdResolveImage',desc='Resolve regions of an image',type='protos'] |
| -- |
| |
| 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 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. |
| |
| 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 |
| **** |
| * [[VUID-vkCmdResolveImage-pRegions-00253]] |
| The source region specified by each element of pname:pRegions must: be a |
| region that is contained within pname:srcImage |
| * [[VUID-vkCmdResolveImage-pRegions-00254]] |
| The destination region specified by each element of pname:pRegions must: |
| be a region that is contained within pname:dstImage |
| * [[VUID-vkCmdResolveImage-pRegions-00255]] |
| The union of all source regions, and the union of all destination |
| regions, specified by the elements of pname:pRegions, must: not overlap |
| in memory |
| * [[VUID-vkCmdResolveImage-srcImage-00256]] |
| If pname:srcImage is non-sparse then it must: be bound completely and |
| contiguously to a single sname:VkDeviceMemory object |
| * [[VUID-vkCmdResolveImage-srcImage-00257]] |
| pname:srcImage must: have a sample count equal to any valid sample count |
| value other than ename:VK_SAMPLE_COUNT_1_BIT |
| * [[VUID-vkCmdResolveImage-dstImage-00258]] |
| If pname:dstImage is non-sparse then it must: be bound completely and |
| contiguously to a single sname:VkDeviceMemory object |
| * [[VUID-vkCmdResolveImage-dstImage-00259]] |
| pname:dstImage must: have a sample count equal to |
| ename:VK_SAMPLE_COUNT_1_BIT |
| * [[VUID-vkCmdResolveImage-srcImageLayout-00260]] |
| pname:srcImageLayout must: specify the layout of the image subresources |
| of pname:srcImage specified in pname:pRegions at the time this command |
| is executed on a sname:VkDevice |
| ifndef::VK_KHR_shared_presentable_image[] |
| * [[VUID-vkCmdResolveImage-srcImageLayout-00261]] |
| pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL |
| or ename:VK_IMAGE_LAYOUT_GENERAL |
| endif::VK_KHR_shared_presentable_image[] |
| ifdef::VK_KHR_shared_presentable_image[] |
| * [[VUID-vkCmdResolveImage-srcImageLayout-01400]] |
| pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, |
| ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or |
| ename:VK_IMAGE_LAYOUT_GENERAL |
| endif::VK_KHR_shared_presentable_image[] |
| * [[VUID-vkCmdResolveImage-dstImageLayout-00262]] |
| pname:dstImageLayout must: specify the layout of the image subresources |
| of pname:dstImage specified in pname:pRegions at the time this command |
| is executed on a sname:VkDevice |
| ifndef::VK_KHR_shared_presentable_image[] |
| * [[VUID-vkCmdResolveImage-dstImageLayout-00263]] |
| pname:dstImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL |
| or ename:VK_IMAGE_LAYOUT_GENERAL |
| endif::VK_KHR_shared_presentable_image[] |
| ifdef::VK_KHR_shared_presentable_image[] |
| * [[VUID-vkCmdResolveImage-dstImageLayout-01401]] |
| pname:dstImageLayout must: be ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, |
| ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or |
| ename:VK_IMAGE_LAYOUT_GENERAL |
| endif::VK_KHR_shared_presentable_image[] |
| * [[VUID-vkCmdResolveImage-dstImage-02003]] |
| The <<resources-image-format-features,format features>> of |
| pname:dstImage must: contain |
| ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT. |
| * [[VUID-vkCmdResolveImage-srcImage-01386]] |
| pname:srcImage and pname:dstImage must: have been created with the same |
| image format |
| ifdef::VK_VERSION_1_1[] |
| * [[VUID-vkCmdResolveImage-commandBuffer-01837]] |
| If pname:commandBuffer is an unprotected command buffer, then |
| pname:srcImage must: not be a protected image |
| * [[VUID-vkCmdResolveImage-commandBuffer-01838]] |
| If pname:commandBuffer is an unprotected command buffer, then |
| pname:dstImage must: not be a protected image |
| * [[VUID-vkCmdResolveImage-commandBuffer-01839]] |
| If pname:commandBuffer is a protected command buffer, then |
| pname:dstImage must: not be an unprotected image |
| endif::VK_VERSION_1_1[] |
| * [[VUID-vkCmdResolveImage-srcSubresource-01709]] |
| The pname:srcSubresource.mipLevel member of each element of |
| pname:pRegions must: be less than the pname:mipLevels specified in |
| slink:VkImageCreateInfo when pname:srcImage was created |
| * [[VUID-vkCmdResolveImage-dstSubresource-01710]] |
| The pname:dstSubresource.mipLevel member of each element of |
| pname:pRegions must: be less than the pname:mipLevels specified in |
| slink:VkImageCreateInfo when pname:dstImage was created |
| * [[VUID-vkCmdResolveImage-srcSubresource-01711]] |
| The [eq]#pname:srcSubresource.baseArrayLayer {plus} |
| pname:srcSubresource.layerCount# of each element of pname:pRegions must: |
| be less than or equal to the pname:arrayLayers specified in |
| slink:VkImageCreateInfo when pname:srcImage was created |
| * [[VUID-vkCmdResolveImage-dstSubresource-01712]] |
| The [eq]#pname:dstSubresource.baseArrayLayer {plus} |
| pname:dstSubresource.layerCount# of each element of pname:pRegions must: |
| be less than or equal to the pname:arrayLayers specified in |
| slink:VkImageCreateInfo when pname:dstImage was created |
| **** |
| |
| include::../validity/protos/vkCmdResolveImage.txt[] |
| -- |
| |
| [open,refpage='VkImageResolve',desc='Structure specifying an image resolve operation',type='structs'] |
| -- |
| |
| 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 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 |
| **** |
| * [[VUID-VkImageResolve-aspectMask-00266]] |
| The pname:aspectMask member of pname:srcSubresource and |
| pname:dstSubresource must: only contain ename:VK_IMAGE_ASPECT_COLOR_BIT |
| * [[VUID-VkImageResolve-layerCount-00267]] |
| The pname:layerCount member of pname:srcSubresource and |
| pname:dstSubresource must: match |
| * [[VUID-VkImageResolve-srcImage-00268]] |
| If either of the calling command's pname:srcImage or pname:dstImage |
| parameters are of elink:VkImageType ename:VK_IMAGE_TYPE_3D, the |
| pname:baseArrayLayer and pname:layerCount members of both |
| pname:srcSubresource and pname:dstSubresource must: be `0` and `1`, |
| respectively |
| * [[VUID-VkImageResolve-srcOffset-00269]] |
| pname:srcOffset.x and [eq]#(pname:extent.width {plus} |
| pname:srcOffset.x)# must: both be greater than or equal to `0` and less |
| than or equal to the source image subresource width |
| * [[VUID-VkImageResolve-srcOffset-00270]] |
| pname:srcOffset.y and [eq]#(pname:extent.height {plus} |
| pname:srcOffset.y)# must: both be greater than or equal to `0` and less |
| than or equal to the source image subresource height |
| * [[VUID-VkImageResolve-srcImage-00271]] |
| If the calling command's pname:srcImage is of type |
| ename:VK_IMAGE_TYPE_1D, then pname:srcOffset.y must: be `0` and |
| pname:extent.height must: be `1`. |
| * [[VUID-VkImageResolve-srcOffset-00272]] |
| pname:srcOffset.z and [eq]#(pname:extent.depth {plus} |
| pname:srcOffset.z)# must: both be greater than or equal to `0` and less |
| than or equal to the source image subresource depth |
| * [[VUID-VkImageResolve-srcImage-00273]] |
| If the calling command's pname:srcImage is of type |
| ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then pname:srcOffset.z |
| must: be `0` and pname:extent.depth must: be `1`. |
| * [[VUID-VkImageResolve-dstOffset-00274]] |
| pname:dstOffset.x and [eq]#(pname:extent.width {plus} |
| pname:dstOffset.x)# must: both be greater than or equal to `0` and less |
| than or equal to the destination image subresource width |
| * [[VUID-VkImageResolve-dstOffset-00275]] |
| pname:dstOffset.y and [eq]#(pname:extent.height {plus} |
| pname:dstOffset.y)# must: both be greater than or equal to `0` and less |
| than or equal to the destination image subresource height |
| * [[VUID-VkImageResolve-dstImage-00276]] |
| If the calling command's pname:dstImage is of type |
| ename:VK_IMAGE_TYPE_1D, then pname:dstOffset.y must: be `0` and |
| pname:extent.height must: be `1`. |
| * [[VUID-VkImageResolve-dstOffset-00277]] |
| pname:dstOffset.z and [eq]#(pname:extent.depth {plus} |
| pname:dstOffset.z)# must: both be greater than or equal to `0` and less |
| than or equal to the destination image subresource depth |
| * [[VUID-VkImageResolve-dstImage-00278]] |
| If the calling command's pname:dstImage is of type |
| ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then pname:dstOffset.z |
| must: be `0` and pname:extent.depth must: be `1`. |
| **** |
| |
| include::../validity/structs/VkImageResolve.txt[] |
| -- |
| |
| ifdef::VK_AMD_buffer_marker[] |
| include::VK_AMD_buffer_marker/copies.txt[] |
| endif::VK_AMD_buffer_marker[] |
