1// Copyright 2015-2023 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[copies]] 6= Copy Commands 7 8An application can: copy buffer and image data using several methods 9described in this chapter, depending on the type of data transfer. 10 11All copy commands are treated as "`transfer`" operations for the purposes of 12synchronization barriers. 13 14All copy commands that have a source format with an X component in its 15format description read undefined: values from those bits. 16 17All copy commands that have a destination format with an X component in its 18format description write undefined: values to those bits. 19 20 21[[copies-buffers]] 22== Copying Data Between Buffers 23 24[open,refpage='vkCmdCopyBuffer',desc='Copy data between buffer regions',type='protos'] 25-- 26:refpage: vkCmdCopyBuffer 27 28To copy data between buffer objects, call: 29 30include::{generated}/api/protos/vkCmdCopyBuffer.adoc[] 31 32 * pname:commandBuffer is the command buffer into which the command will be 33 recorded. 34 * pname:srcBuffer is the source buffer. 35 * pname:dstBuffer is the destination buffer. 36 * pname:regionCount is the number of regions to copy. 37 * pname:pRegions is a pointer to an array of slink:VkBufferCopy structures 38 specifying the regions to copy. 39 40Each source region specified by pname:pRegions is copied from the source 41buffer to the destination region of the destination buffer. 42If any of the specified regions in pname:srcBuffer overlaps in memory with 43any of the specified regions in pname:dstBuffer, values read from those 44overlapping regions are undefined:. 45 46.Valid Usage 47**** 48include::{chapters}/commonvalidity/copy_buffer_command_buffer_common.adoc[] 49include::{chapters}/commonvalidity/copy_buffer_common.adoc[] 50**** 51 52include::{generated}/validity/protos/vkCmdCopyBuffer.adoc[] 53-- 54 55[open,refpage='VkBufferCopy',desc='Structure specifying a buffer copy operation',type='structs'] 56-- 57:refpage: VkBufferCopy 58 59The sname:VkBufferCopy structure is defined as: 60 61include::{generated}/api/structs/VkBufferCopy.adoc[] 62 63 * pname:srcOffset is the starting offset in bytes from the start of 64 pname:srcBuffer. 65 * pname:dstOffset is the starting offset in bytes from the start of 66 pname:dstBuffer. 67 * pname:size is the number of bytes to copy. 68 69.Valid Usage 70**** 71include::{chapters}/commonvalidity/buffer_copy_common.adoc[] 72**** 73 74include::{generated}/validity/structs/VkBufferCopy.adoc[] 75-- 76 77ifdef::VK_VERSION_1_3,VK_KHR_copy_commands2[] 78A more extensible version of the copy buffer command is defined below. 79 80[open,refpage='vkCmdCopyBuffer2',desc='Copy data between buffer regions',type='protos',alias='vkCmdCopyBuffer2KHR'] 81-- 82:refpage: vkCmdCopyBuffer2 83 84To copy data between buffer objects, call: 85 86ifdef::VK_VERSION_1_3[] 87include::{generated}/api/protos/vkCmdCopyBuffer2.adoc[] 88endif::VK_VERSION_1_3[] 89 90ifdef::VK_VERSION_1_3+VK_KHR_copy_commands2[or the equivalent command] 91 92ifdef::VK_KHR_copy_commands2[] 93include::{generated}/api/protos/vkCmdCopyBuffer2KHR.adoc[] 94endif::VK_KHR_copy_commands2[] 95 96 * pname:commandBuffer is the command buffer into which the command will be 97 recorded. 98 * pname:pCopyBufferInfo is a pointer to a slink:VkCopyBufferInfo2 99 structure describing the copy parameters. 100 101Each source region specified by pname:pCopyBufferInfo->pRegions is copied 102from the source buffer to the destination region of the destination buffer. 103If any of the specified regions in pname:pCopyBufferInfo->srcBuffer overlaps 104in memory with any of the specified regions in 105pname:pCopyBufferInfo->dstBuffer, values read from those overlapping regions 106are undefined:. 107 108.Valid Usage 109**** 110include::{chapters}/commonvalidity/copy_buffer_command_buffer_common.adoc[] 111**** 112 113include::{generated}/validity/protos/vkCmdCopyBuffer2.adoc[] 114-- 115 116[open,refpage='VkCopyBufferInfo2',desc='Structure specifying parameters of a buffer copy command',type='structs',alias='VkCopyBufferInfo2KHR'] 117-- 118:refpage: VkCopyBufferInfo2 119 120The sname:VkCopyBufferInfo2 structure is defined as: 121 122include::{generated}/api/structs/VkCopyBufferInfo2.adoc[] 123 124ifdef::VK_KHR_copy_commands2[] 125or the equivalent 126 127include::{generated}/api/structs/VkCopyBufferInfo2KHR.adoc[] 128endif::VK_KHR_copy_commands2[] 129 130 * pname:sType is a elink:VkStructureType value identifying this structure. 131 * pname:pNext is `NULL` or a pointer to a structure extending this 132 structure. 133 * pname:srcBuffer is the source buffer. 134 * pname:dstBuffer is the destination buffer. 135 * pname:regionCount is the number of regions to copy. 136 * pname:pRegions is a pointer to an array of slink:VkBufferCopy2 137 structures specifying the regions to copy. 138 139.Valid Usage 140**** 141include::{chapters}/commonvalidity/copy_buffer_common.adoc[] 142**** 143 144include::{generated}/validity/structs/VkCopyBufferInfo2.adoc[] 145-- 146 147[open,refpage='VkBufferCopy2',desc='Structure specifying a buffer copy operation',type='structs',alias='VkBufferCopy2KHR'] 148-- 149:refpage: VkBufferCopy2 150 151The sname:VkBufferCopy2 structure is defined as: 152 153include::{generated}/api/structs/VkBufferCopy2.adoc[] 154 155ifdef::VK_KHR_copy_commands2[] 156or the equivalent 157 158include::{generated}/api/structs/VkBufferCopy2KHR.adoc[] 159endif::VK_KHR_copy_commands2[] 160 161 * pname:sType is a elink:VkStructureType value identifying this structure. 162 * pname:pNext is `NULL` or a pointer to a structure extending this 163 structure. 164 * pname:srcOffset is the starting offset in bytes from the start of 165 pname:srcBuffer. 166 * pname:dstOffset is the starting offset in bytes from the start of 167 pname:dstBuffer. 168 * pname:size is the number of bytes to copy. 169 170.Valid Usage 171**** 172include::{chapters}/commonvalidity/buffer_copy_common.adoc[] 173**** 174 175include::{generated}/validity/structs/VkBufferCopy2.adoc[] 176-- 177endif::VK_VERSION_1_3,VK_KHR_copy_commands2[] 178 179 180[[copies-images]] 181== Copying Data Between Images 182 183[open,refpage='vkCmdCopyImage',desc='Copy data between images',type='protos'] 184-- 185:refpage: vkCmdCopyImage 186 187To copy data between image objects, call: 188 189include::{generated}/api/protos/vkCmdCopyImage.adoc[] 190 191 * pname:commandBuffer is the command buffer into which the command will be 192 recorded. 193 * pname:srcImage is the source image. 194 * pname:srcImageLayout is the current layout of the source image 195 subresource. 196 * pname:dstImage is the destination image. 197 * pname:dstImageLayout is the current layout of the destination image 198 subresource. 199 * pname:regionCount is the number of regions to copy. 200 * pname:pRegions is a pointer to an array of slink:VkImageCopy structures 201 specifying the regions to copy. 202 203Each source region specified by pname:pRegions is copied from the source 204image to the destination region of the destination image. 205If any of the specified regions in pname:srcImage overlaps in memory with 206any of the specified regions in pname:dstImage, values read from those 207overlapping regions are undefined:. 208 209ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 210<<formats-requiring-sampler-ycbcr-conversion, Multi-planar images>> can: 211only be copied on a per-plane basis, and the subresources used in each 212region when copying to or from such images must: specify only one plane, 213though different regions can: specify different planes. 214When copying planes of multi-planar images, the format considered is the 215<<formats-compatible-planes, compatible format for that plane>>, rather than 216the format of the multi-planar image. 217endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 218 219If the format of the destination image has a different 220<<formats-compatibility-classes,block extent>> than the source image (e.g. 221one is a compressed format), the offset and extent for each of the regions 222specified is <<formats-size-compatibility, scaled according to the block 223extents of each format>> to match in size. 224Copy regions for each image must: be aligned to a multiple of the texel 225block extent in each dimension, except at the edges of the image, where 226region extents must: match the edge of the image. 227 228ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 229Image data can: be copied between images with different image types. 230If one image is ename:VK_IMAGE_TYPE_3D and the other image is 231ename:VK_IMAGE_TYPE_2D with multiple layers, then each slice is copied to or 232from a different layer; pname:depth slices in the 3D image correspond to 233pname:layerCount layers in the 2D image, with an effective pname:depth of 234`1` used for the 2D image. 235ifndef::VK_KHR_maintenance5[] 236Other combinations of image types are disallowed. 237endif::VK_KHR_maintenance5[] 238ifdef::VK_KHR_maintenance5[] 239If <<features-maintenance5,pname:maintenance5>> is enabled, all other 240combinations are allowed and function as if 1D images are 2D images with a 241height of 1. 242Otherwise, other combinations of image types are disallowed. 243endif::VK_KHR_maintenance5[] 244endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 245 246.Valid Usage 247**** 248include::{chapters}/commonvalidity/copy_image_command_buffer_common.adoc[] 249include::{chapters}/commonvalidity/copy_image_common.adoc[] 250 251:imageparam: srcImage 252:imagesubresource: srcSubresource 253include::{chapters}/commonvalidity/copy_anyimage_to_imageany_common.adoc[] 254 255:imageparam: dstImage 256:imagesubresource: dstSubresource 257include::{chapters}/commonvalidity/copy_anyimage_to_imageany_common.adoc[] 258**** 259 260include::{generated}/validity/protos/vkCmdCopyImage.adoc[] 261-- 262 263[open,refpage='VkImageCopy',desc='Structure specifying an image copy operation',type='structs'] 264-- 265:refpage: VkImageCopy 266 267The sname:VkImageCopy structure is defined as: 268 269include::{generated}/api/structs/VkImageCopy.adoc[] 270 271 * pname:srcSubresource and pname:dstSubresource are 272 slink:VkImageSubresourceLayers structures specifying the image 273 subresources of the images used for the source and destination image 274 data, respectively. 275 * pname:srcOffset and pname:dstOffset select the initial pname:x, pname:y, 276 and pname:z offsets in texels of the sub-regions of the source and 277 destination image data. 278 * pname:extent is the size in texels of the image to copy in pname:width, 279 pname:height and pname:depth. 280 281.Valid Usage 282**** 283include::{chapters}/commonvalidity/image_copy_common.adoc[] 284**** 285 286include::{generated}/validity/structs/VkImageCopy.adoc[] 287-- 288 289[open,refpage='VkImageSubresourceLayers',desc='Structure specifying an image subresource layers',type='structs'] 290-- 291The sname:VkImageSubresourceLayers structure is defined as: 292 293include::{generated}/api/structs/VkImageSubresourceLayers.adoc[] 294 295 * pname:aspectMask is a combination of elink:VkImageAspectFlagBits, 296 selecting the color, depth and/or stencil aspects to be copied. 297 * pname:mipLevel is the mipmap level to copy 298 * pname:baseArrayLayer and pname:layerCount are the starting layer and 299 number of layers to copy. 300 301.Valid Usage 302**** 303 * [[VUID-VkImageSubresourceLayers-aspectMask-00167]] 304 If pname:aspectMask contains ename:VK_IMAGE_ASPECT_COLOR_BIT, it must: 305 not contain either of ename:VK_IMAGE_ASPECT_DEPTH_BIT or 306 ename:VK_IMAGE_ASPECT_STENCIL_BIT 307 * [[VUID-VkImageSubresourceLayers-aspectMask-00168]] 308 pname:aspectMask must: not contain ename:VK_IMAGE_ASPECT_METADATA_BIT 309ifdef::VK_EXT_image_drm_format_modifier[] 310 * [[VUID-VkImageSubresourceLayers-aspectMask-02247]] 311 pname:aspectMask must: not include 312 `VK_IMAGE_ASPECT_MEMORY_PLANE__{ibit}__BIT_EXT` for any index _i_ 313endif::VK_EXT_image_drm_format_modifier[] 314 * [[VUID-VkImageSubresourceLayers-layerCount-09243]] 315 {empty} 316ifdef::VK_KHR_maintenance5[] 317 If the <<features-maintenance5, pname:maintenance5>> feature is not 318 enabled, 319endif::VK_KHR_maintenance5[] 320 pname:layerCount must: not be ename:VK_REMAINING_ARRAY_LAYERS 321 * [[VUID-VkImageSubresourceLayers-layerCount-01700]] 322 If pname:layerCount is not ename:VK_REMAINING_ARRAY_LAYERS, it must: be 323 greater than 0 324**** 325 326include::{generated}/validity/structs/VkImageSubresourceLayers.adoc[] 327-- 328 329ifdef::VK_VERSION_1_3,VK_KHR_copy_commands2[] 330A more extensible version of the copy image command is defined below. 331 332[open,refpage='vkCmdCopyImage2',desc='Copy data between images',type='protos',alias='vkCmdCopyImage2KHR'] 333-- 334:refpage: vkCmdCopyImage2 335 336To copy data between image objects, call: 337 338ifdef::VK_VERSION_1_3[] 339include::{generated}/api/protos/vkCmdCopyImage2.adoc[] 340endif::VK_VERSION_1_3[] 341 342ifdef::VK_VERSION_1_3+VK_KHR_copy_commands2[or the equivalent command] 343 344ifdef::VK_KHR_copy_commands2[] 345include::{generated}/api/protos/vkCmdCopyImage2KHR.adoc[] 346endif::VK_KHR_copy_commands2[] 347 348 * pname:commandBuffer is the command buffer into which the command will be 349 recorded. 350 * pname:pCopyImageInfo is a pointer to a slink:VkCopyImageInfo2 structure 351 describing the copy parameters. 352 353This command is functionally identical to flink:vkCmdCopyImage, but includes 354extensible sub-structures that include pname:sType and pname:pNext 355parameters, allowing them to be more easily extended. 356 357.Valid Usage 358**** 359include::{chapters}/commonvalidity/copy_image_command_buffer_common.adoc[] 360**** 361 362include::{generated}/validity/protos/vkCmdCopyImage2.adoc[] 363-- 364 365 366[open,refpage='VkCopyImageInfo2',desc='Structure specifying parameters of an image copy command',type='structs',alias='VkCopyImageInfo2KHR'] 367-- 368:refpage: VkCopyImageInfo2 369 370The sname:VkCopyImageInfo2 structure is defined as: 371 372include::{generated}/api/structs/VkCopyImageInfo2.adoc[] 373 374ifdef::VK_KHR_copy_commands2[] 375or the equivalent 376 377include::{generated}/api/structs/VkCopyImageInfo2KHR.adoc[] 378endif::VK_KHR_copy_commands2[] 379 380 * pname:sType is a elink:VkStructureType value identifying this structure. 381 * pname:pNext is `NULL` or a pointer to a structure extending this 382 structure. 383 * pname:srcImage is the source image. 384 * pname:srcImageLayout is the current layout of the source image 385 subresource. 386 * pname:dstImage is the destination image. 387 * pname:dstImageLayout is the current layout of the destination image 388 subresource. 389 * pname:regionCount is the number of regions to copy. 390 * pname:pRegions is a pointer to an array of slink:VkImageCopy2 structures 391 specifying the regions to copy. 392 393 394.Valid Usage 395**** 396include::{chapters}/commonvalidity/copy_image_common.adoc[] 397 398:imageparam: srcImage 399:imagesubresource: srcSubresource 400include::{chapters}/commonvalidity/copy_anyimage_to_imageany_common.adoc[] 401 402:imageparam: dstImage 403:imagesubresource: dstSubresource 404include::{chapters}/commonvalidity/copy_anyimage_to_imageany_common.adoc[] 405**** 406 407include::{generated}/validity/structs/VkCopyImageInfo2.adoc[] 408-- 409 410[open,refpage='VkImageCopy2',desc='Structure specifying an image copy operation',type='structs',alias='VkImageCopy2KHR'] 411-- 412:refpage: VkImageCopy2 413 414The sname:VkImageCopy2 structure is defined as: 415 416include::{generated}/api/structs/VkImageCopy2.adoc[] 417 418ifdef::VK_KHR_copy_commands2[] 419or the equivalent 420 421include::{generated}/api/structs/VkImageCopy2KHR.adoc[] 422endif::VK_KHR_copy_commands2[] 423 424 * pname:sType is a elink:VkStructureType value identifying this structure. 425 * pname:pNext is `NULL` or a pointer to a structure extending this 426 structure. 427 * pname:srcSubresource and pname:dstSubresource are 428 slink:VkImageSubresourceLayers structures specifying the image 429 subresources of the images used for the source and destination image 430 data, respectively. 431 * pname:srcOffset and pname:dstOffset select the initial pname:x, pname:y, 432 and pname:z offsets in texels of the sub-regions of the source and 433 destination image data. 434 * pname:extent is the size in texels of the image to copy in pname:width, 435 pname:height and pname:depth. 436 437.Valid Usage 438**** 439include::{chapters}/commonvalidity/image_copy_common.adoc[] 440**** 441 442include::{generated}/validity/structs/VkImageCopy2.adoc[] 443-- 444endif::VK_VERSION_1_3,VK_KHR_copy_commands2[] 445 446 447[[copies-buffers-images]] 448== Copying Data Between Buffers and Images 449 450Data can: be copied between buffers and images, enabling applications to 451load and store data between images and user defined offsets in buffer 452memory. 453 454[[copies-buffers-images-addressing]] 455When copying between a buffer and an image, whole texel blocks are always 456copied; each texel block in the specified extent in the image to be copied 457will be written to a region in the buffer, specified according to the 458position of the texel block, and the <<formats-compatibility-classes,texel 459block extent>> and size of the format being copied. 460 461For a set of coordinates [eq]#(x,y,z,layer)#, where: 462 463 {empty}:: [eq]#x# is in the range [eq]#[pname:imageOffset.x / blockWidth, 464 {lceil}(pname:imageOffset.x {plus} pname:imageExtent.width) / 465 blockWidth{rceil})#, 466 {empty}:: [eq]#y# is in the range [eq]#[pname:imageOffset.y / blockHeight, 467 {lceil}(pname:imageOffset.y {plus} pname:imageExtent.height) / 468 blockHeight{rceil})#, 469 {empty}:: [eq]#z# is in the range [eq]#[pname:imageOffset.z / blockDepth, 470 {lceil}(pname:imageOffset.z {plus} pname:imageExtent.depth) / 471 blockDepth{rceil})#, 472 {empty}:: [eq]#layer# is in the range 473 [pname:imageSubresource.baseArrayLayer, 474 pname:imageSubresource.baseArrayLayer {plus} 475 pname:imageSubresource.layerCount), 476 477and where [eq]#blockWidth#, [eq]#blockHeight#, and [eq]#blockDepth# are the 478dimensions of the <<formats-compatibility-classes,texel block extent>> of 479the image's format. 480 481For each [eq]#(x,y,z,layer)# coordinate, texels in the image layer selected 482by [eq]#layer# are accessed in the following ranges: 483 484 {empty}:: [eq]#[x {times} blockWidth, max( (x {times} blockWidth) {plus} 485 blockWidth, imageWidth) )# 486 {empty}:: [eq]#[y {times} blockHeight, max( (y {times} blockHeight) {plus} 487 blockHeight, imageHeight) )# 488 {empty}:: [eq]#[z {times} blockDepth, max( (z {times} blockDepth) {plus} 489 blockDepth, imageDepth) )# 490 491where [eq]#imageWidth#, [eq]#imageHeight#, and [eq]#imageDepth# are the 492dimensions of the image subresource. 493 494For each [eq]#(x,y,z,layer)# coordinate, bytes in the buffer are accessed at 495offsets in the range [eq]#[texelOffset, texelOffset {plus} blockSize)#, 496where: 497 498 {empty}:: [eq]#texelOffset = pname:bufferOffset {plus} (x {times} 499 blockSize) {plus} (y {times} rowExtent) {plus} (z {times} 500 sliceExtent) + (layer {times} layerExtent)# 501 {empty}:: [eq]#blockSize# is the size of the block in bytes for the format 502 {empty}:: [eq]#rowExtent = max(pname:bufferRowLength, 503 {lceil}pname:imageExtent.width / blockWidth{rceil} {times} 504 blockSize)# 505 {empty}:: [eq]#sliceExtent = max(pname:bufferImageHeight, 506 pname:imageExtent.height {times} rowExtent)# 507 {empty}:: [eq]#layerExtent = pname:imageExtent.depth {times} sliceExtent# 508 509ifdef::VK_QCOM_rotated_copy_commands[] 510[[copies-buffers-images-rotation-addressing]] 511If a rotation is specified by slink:VkCopyCommandTransformInfoQCOM, the 2D 512region of the image being addressed is rotated around the offset, modifying 513the range of [eq]#x# and [eq]#y# coordinates for the image address according 514to the specified elink:VkSurfaceTransformFlagBitsKHR: 515 516 * If ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR is specified, no rotation 517 is performed: 518 {empty}:: [eq]#x'# is in the same range as [eq]#x# 519 {empty}:: [eq]#y'# is in the same range as [eq]#y# 520 {empty}:: [eq]#blockWidth' = blockWidth# 521 {empty}:: [eq]#blockHeight' = blockHeight# 522 {empty}:: [eq]#imageWidth' = imageWidth# 523 {empty}:: [eq]#imageHeight' = imageHeight# 524 * If ename:VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR is specified 525 {empty}:: [eq]#x'# is in the range [eq]#[{lceil}(pname:imageOffset.x 526 {minus} pname:imageExtent.height) / blockHeight{rceil}, 527 pname:imageOffset.x {minus} image/ blockHeight)# 528 {empty}:: [eq]#y'# is in the range [eq]#[pname:imageOffset.y / 529 blockWidth, {lceil}(pname:imageOffset.y {plus} 530 pname:imageExtent.width) / blockWidth{rceil})# 531 {empty}:: [eq]#blockWidth' = blockHeight# 532 {empty}:: [eq]#blockHeight' = blockWidth# 533 {empty}:: [eq]#imageWidth' = imageHeight# 534 {empty}:: [eq]#imageHeight' = imageWidth# 535 * If ename:VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR is specified: 536 {empty}:: [eq]#x'# is in the range [eq]#[{lceil}(pname:imageOffset.x 537 {minus} pname:imageExtent.width) / blockWidth{rceil}, 538 pname:imageOffset.x / blockWidth)#, 539 {empty}:: [eq]#y'# is in the range [eq]#[{lceil}(pname:imageOffset.x 540 {plus} pname:imageExtent.height) / blockHeight{rceil}, 541 pname:imageOffset.x / blockHeight)#, 542 {empty}:: [eq]#blockWidth' = blockWidth# 543 {empty}:: [eq]#blockHeight' = blockHeight# 544 {empty}:: [eq]#imageWidth' = imageWidth# 545 {empty}:: [eq]#imageHeight' = imageHeight# 546 * If ename:VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR is specified: 547 {empty}:: [eq]#x# is in the range [eq]#[pname:imageOffset.x / 548 blockHeight, {lceil}(pname:imageOffset.x {plus} 549 pname:imageExtent.height) / blockHeight{rceil})# 550 {empty}:: [eq]#y# is in the range [eq]#[{lceil}(pname:imageOffset.y 551 {minus} pname:imageExtent.width) / blockWidth{rceil}, 552 pname:imageOffset.y / blockWidth)#. 553 {empty}:: [eq]#blockWidth' = blockHeight# 554 {empty}:: [eq]#blockHeight' = blockWidth# 555 {empty}:: [eq]#imageWidth' = imageHeight# 556 {empty}:: [eq]#imageHeight' = imageWidth# 557 558When rotation is performed, for each [eq]#(x,y,z,layer)# coordinate, texels 559in the image layer selected by [eq]#layer# are instead accessed in the 560following ranges: 561 562 {empty}:: [eq]#[x' {times} blockWidth', max( (x' {times} blockWidth') 563 {plus} blockWidth', imageWidth') )# 564 {empty}:: [eq]#[y' {times} blockHeight', max( (y' {times} blockHeight') 565 {plus} blockHeight', imageHeight') )# 566 {empty}:: [eq]#[z' {times} blockDepth', max( (z' {times} blockDepth') 567 {plus} blockDepth', imageDepth') )# 568 569Buffer addressing calculations are unaffected by this rotation. 570endif::VK_QCOM_rotated_copy_commands[] 571 572[[copies-buffers-images-depth-stencil]] 573When copying between a buffer and the depth or stencil aspect of an image, 574data in the buffer is assumed to be laid out as separate planes rather than 575interleaved. 576Addressing calculations are thus performed for a different format than the 577base image, according to the aspect, as described in the following table: 578 579.Depth/Stencil Aspect Copy Table 580[width="95%",cols="1,1,1",options="header"] 581|==== 582^| Base Format ^| Depth Aspect Format ^| Stencil Aspect Format 583^| ename:VK_FORMAT_D16_UNORM 584^| ename:VK_FORMAT_D16_UNORM 585^| - 586^| ename:VK_FORMAT_X8_D24_UNORM_PACK32 587^| ename:VK_FORMAT_X8_D24_UNORM_PACK32 588^| - 589^| ename:VK_FORMAT_D32_SFLOAT 590^| ename:VK_FORMAT_D32_SFLOAT 591^| - 592^| ename:VK_FORMAT_S8_UINT 593^| - 594^| ename:VK_FORMAT_S8_UINT 595^| ename:VK_FORMAT_D16_UNORM_S8_UINT 596^| ename:VK_FORMAT_D16_UNORM 597^| ename:VK_FORMAT_S8_UINT 598^| ename:VK_FORMAT_D24_UNORM_S8_UINT 599^| ename:VK_FORMAT_X8_D24_UNORM_PACK32 600^| ename:VK_FORMAT_S8_UINT 601^| ename:VK_FORMAT_D32_SFLOAT_S8_UINT 602^| ename:VK_FORMAT_D32_SFLOAT 603^| ename:VK_FORMAT_S8_UINT 604|==== 605 606ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 607[[copies-buffers-images-multi-planar]] 608When copying between a buffer and any plane of a 609<<formats-requiring-sampler-ycbcr-conversion, multi-planar image>>, 610addressing calculations are performed using the <<formats-compatible-planes, 611compatible format for that plane>>, rather than the format of the 612multi-planar image. 613endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 614 615Each texel block is copied from one resource to the other according to the 616above addressing equations. 617 618 619[open,refpage='vkCmdCopyBufferToImage',desc='Copy data from a buffer into an image',type='protos'] 620-- 621:refpage: vkCmdCopyBufferToImage 622 623To copy data from a buffer object to an image object, call: 624 625include::{generated}/api/protos/vkCmdCopyBufferToImage.adoc[] 626 627 * pname:commandBuffer is the command buffer into which the command will be 628 recorded. 629 * pname:srcBuffer is the source buffer. 630 * pname:dstImage is the destination image. 631 * pname:dstImageLayout is the layout of the destination image subresources 632 for the copy. 633 * pname:regionCount is the number of regions to copy. 634 * pname:pRegions is a pointer to an array of slink:VkBufferImageCopy 635 structures specifying the regions to copy. 636 637Each source region specified by pname:pRegions is copied from the source 638buffer to the destination region of the destination image according to the 639<<copies-buffers-images-addressing,addressing calculations>> for each 640resource. 641If any of the specified regions in pname:srcBuffer overlaps in memory with 642any of the specified regions in pname:dstImage, values read from those 643overlapping regions are undefined:. 644If any region accesses a depth aspect in pname:dstImage 645ifdef::VK_EXT_depth_range_unrestricted[] 646and the `apiext:VK_EXT_depth_range_unrestricted` extension is not enabled, 647endif::VK_EXT_depth_range_unrestricted[] 648values copied from pname:srcBuffer outside of the range [eq]#[0,1]# will be 649be written as undefined: values to the destination image. 650 651Copy regions for the image must: be aligned to a multiple of the texel block 652extent in each dimension, except at the edges of the image, where region 653extents must: match the edge of the image. 654 655:imageparam: dstImage 656:imagesubresource: imageSubresource 657:imageoffset: imageOffset 658:imageextent: imageExtent 659:bufferrowlength: bufferRowLength 660:bufferimageheight: bufferImageHeight 661:regionsparam: pname:pRegions 662 663.Valid Usage 664**** 665include::{chapters}/commonvalidity/copy_anyimage_to_imageany_common.adoc[] 666include::{chapters}/commonvalidity/copy_anyimage_to_imageany_no_rotation_common.adoc[] 667include::{chapters}/commonvalidity/copy_anyimage_to_imageany_single_sampled_common.adoc[] 668include::{chapters}/commonvalidity/copy_buffer_to_image_command_buffer_common.adoc[] 669include::{chapters}/commonvalidity/copy_buffer_to_image_common.adoc[] 670include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_common.adoc[] 671include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_not_both_image_common.adoc[] 672include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_buffer_alignment_common.adoc[] 673**** 674 675include::{generated}/validity/protos/vkCmdCopyBufferToImage.adoc[] 676-- 677 678[open,refpage='vkCmdCopyImageToBuffer',desc='Copy image data into a buffer',type='protos'] 679-- 680:refpage: vkCmdCopyImageToBuffer 681 682To copy data from an image object to a buffer object, call: 683 684include::{generated}/api/protos/vkCmdCopyImageToBuffer.adoc[] 685 686 * pname:commandBuffer is the command buffer into which the command will be 687 recorded. 688 * pname:srcImage is the source image. 689 * pname:srcImageLayout is the layout of the source image subresources for 690 the copy. 691 * pname:dstBuffer is the destination buffer. 692 * pname:regionCount is the number of regions to copy. 693 * pname:pRegions is a pointer to an array of slink:VkBufferImageCopy 694 structures specifying the regions to copy. 695 696Each source region specified by pname:pRegions is copied from the source 697image to the destination region of the destination buffer according to the 698<<copies-buffers-images-addressing,addressing calculations>> for each 699resource. 700If any of the specified regions in pname:srcImage overlaps in memory with 701any of the specified regions in pname:dstBuffer, values read from those 702overlapping regions are undefined:. 703 704Copy regions for the image must: be aligned to a multiple of the texel block 705extent in each dimension, except at the edges of the image, where region 706extents must: match the edge of the image. 707 708:imageparam: srcImage 709:imagesubresource: imageSubresource 710:imageoffset: imageOffset 711:imageextent: imageExtent 712:bufferrowlength: bufferRowLength 713:bufferimageheight: bufferImageHeight 714:regionsparam: pname:pRegions 715 716.Valid Usage 717**** 718include::{chapters}/commonvalidity/copy_anyimage_to_imageany_common.adoc[] 719include::{chapters}/commonvalidity/copy_anyimage_to_imageany_no_rotation_common.adoc[] 720include::{chapters}/commonvalidity/copy_anyimage_to_imageany_single_sampled_common.adoc[] 721include::{chapters}/commonvalidity/copy_image_to_buffer_command_buffer_common.adoc[] 722include::{chapters}/commonvalidity/copy_image_to_buffer_common.adoc[] 723include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_common.adoc[] 724include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_not_both_image_common.adoc[] 725include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_buffer_alignment_common.adoc[] 726**** 727 728include::{generated}/validity/protos/vkCmdCopyImageToBuffer.adoc[] 729-- 730 731[open,refpage='VkBufferImageCopy',desc='Structure specifying a buffer image copy operation',type='structs'] 732-- 733:refpage: VkBufferImageCopy 734 735For both flink:vkCmdCopyBufferToImage and flink:vkCmdCopyImageToBuffer, each 736element of pname:pRegions is a structure defined as: 737 738include::{generated}/api/structs/VkBufferImageCopy.adoc[] 739 740 * pname:bufferOffset is the offset in bytes from the start of the buffer 741 object where the image data is copied from or to. 742 * pname:bufferRowLength and pname:bufferImageHeight specify in texels a 743 subregion of a larger two- or three-dimensional image in buffer memory, 744 and control the addressing calculations. 745 If either of these values is zero, that aspect of the buffer memory is 746 considered to be tightly packed according to the pname:imageExtent. 747 * pname:imageSubresource is a slink:VkImageSubresourceLayers used to 748 specify the specific image subresources of the image used for the source 749 or destination image data. 750 * pname:imageOffset selects the initial pname:x, pname:y, pname:z offsets 751 in texels of the sub-region of the source or destination image data. 752 * pname:imageExtent is the size in texels of the image to copy in 753 pname:width, pname:height and pname:depth. 754 755:bufferrowlength: bufferRowLength 756:bufferimageheight: bufferImageHeight 757 758.Valid Usage 759**** 760include::{chapters}/commonvalidity/buffer_or_memory_image_copy_common.adoc[] 761**** 762 763include::{generated}/validity/structs/VkBufferImageCopy.adoc[] 764-- 765 766ifdef::VK_VERSION_1_3,VK_KHR_copy_commands2[] 767More extensible versions of the commands to copy between buffers and images 768are defined below. 769 770[open,refpage='vkCmdCopyBufferToImage2',desc='Copy data from a buffer into an image',type='protos',alias='vkCmdCopyBufferToImage2KHR'] 771-- 772:refpage: vkCmdCopyBufferToImage2 773 774To copy data from a buffer object to an image object, call: 775 776ifdef::VK_VERSION_1_3[] 777include::{generated}/api/protos/vkCmdCopyBufferToImage2.adoc[] 778endif::VK_VERSION_1_3[] 779 780ifdef::VK_VERSION_1_3+VK_KHR_copy_commands2[or the equivalent command] 781 782ifdef::VK_KHR_copy_commands2[] 783include::{generated}/api/protos/vkCmdCopyBufferToImage2KHR.adoc[] 784endif::VK_KHR_copy_commands2[] 785 786 * pname:commandBuffer is the command buffer into which the command will be 787 recorded. 788 * pname:pCopyBufferToImageInfo is a pointer to a 789 slink:VkCopyBufferToImageInfo2 structure describing the copy parameters. 790 791This command is functionally identical to flink:vkCmdCopyBufferToImage, but 792includes extensible sub-structures that include pname:sType and pname:pNext 793parameters, allowing them to be more easily extended. 794 795:regionsparam: pname:pCopyBufferToImageInfo->pRegions 796 797.Valid Usage 798**** 799include::{chapters}/commonvalidity/copy_buffer_to_image_command_buffer_common.adoc[] 800**** 801 802include::{generated}/validity/protos/vkCmdCopyBufferToImage2.adoc[] 803-- 804 805[open,refpage='VkCopyBufferToImageInfo2',desc='Structure specifying parameters of a buffer to image copy command',type='structs',alias='VkCopyBufferToImageInfo2KHR'] 806-- 807:refpage: VkCopyBufferToImageInfo2 808 809The sname:VkCopyBufferToImageInfo2 structure is defined as: 810 811include::{generated}/api/structs/VkCopyBufferToImageInfo2.adoc[] 812 813ifdef::VK_KHR_copy_commands2[] 814or the equivalent 815 816include::{generated}/api/structs/VkCopyBufferToImageInfo2KHR.adoc[] 817endif::VK_KHR_copy_commands2[] 818 819 * pname:sType is a elink:VkStructureType value identifying this structure. 820 * pname:pNext is `NULL` or a pointer to a structure extending this 821 structure. 822 * pname:srcBuffer is the source buffer. 823 * pname:dstImage is the destination image. 824 * pname:dstImageLayout is the layout of the destination image subresources 825 for the copy. 826 * pname:regionCount is the number of regions to copy. 827 * pname:pRegions is a pointer to an array of slink:VkBufferImageCopy2 828 structures specifying the regions to copy. 829 830:imageparam: dstImage 831:imagesubresource: imageSubresource 832:imageoffset: imageOffset 833:imageextent: imageExtent 834:bufferrowlength: bufferRowLength 835:bufferimageheight: bufferImageHeight 836:regionsparam: pname:pRegions 837 838.Valid Usage 839**** 840 * [[VUID-VkCopyBufferToImageInfo2-pRegions-04565]] 841 The image region specified by each element of pname:pRegions 842ifdef::VK_QCOM_rotated_copy_commands[] 843 that does not contain slink:VkCopyCommandTransformInfoQCOM in its 844 pname:pNext chain 845endif::VK_QCOM_rotated_copy_commands[] 846 must: be contained within the specified pname:imageSubresource of 847 pname:dstImage 848ifdef::VK_QCOM_rotated_copy_commands[] 849 * [[VUID-VkCopyBufferToImageInfo2KHR-pRegions-04554]] 850 If the image region specified by each element of pname:pRegions contains 851 slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, the 852 rotated destination region as described in 853 <<copies-buffers-images-rotation-addressing>> must: be contained within 854 pname:dstImage 855 * [[VUID-VkCopyBufferToImageInfo2KHR-pRegions-04555]] 856 If any element of pname:pRegions contains 857 slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then 858 pname:dstImage must: have a 1x1x1 <<formats-compatibility-classes,texel 859 block extent>> 860 * [[VUID-VkCopyBufferToImageInfo2KHR-pRegions-06203]] 861 If any element of pname:pRegions contains 862 slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then 863 pname:dstImage must: be of type ename:VK_IMAGE_TYPE_2D 864 * [[VUID-VkCopyBufferToImageInfo2KHR-pRegions-06204]] 865 If any element of pname:pRegions contains 866 slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then 867 pname:dstImage must: not have a 868 <<formats-requiring-sampler-ycbcr-conversion, multi-planar format>> 869endif::VK_QCOM_rotated_copy_commands[] 870include::{chapters}/commonvalidity/copy_buffer_to_image_common.adoc[] 871include::{chapters}/commonvalidity/copy_anyimage_to_imageany_common.adoc[] 872include::{chapters}/commonvalidity/copy_anyimage_to_imageany_single_sampled_common.adoc[] 873include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_common.adoc[] 874include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_not_both_image_common.adoc[] 875include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_buffer_alignment_common.adoc[] 876 * [[VUID-VkCopyBufferToImageInfo2-pRegions-06223]] 877 For each element of pname:pRegions not containing 878 sname:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, 879 pname:imageOffset.x and [eq]#(pname:imageExtent.width {plus} 880 pname:imageOffset.x)# must: both be greater than or equal to `0` and 881 less than or equal to the width of the specified pname:imageSubresource 882 of pname:dstImage 883 * [[VUID-VkCopyBufferToImageInfo2-pRegions-06224]] 884 For each element of pname:pRegions not containing 885 sname:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, 886 pname:imageOffset.y and [eq]#(pname:imageExtent.height {plus} 887 pname:imageOffset.y)# must: both be greater than or equal to `0` and 888 less than or equal to the height of the specified pname:imageSubresource 889 of pname:dstImage 890**** 891 892include::{generated}/validity/structs/VkCopyBufferToImageInfo2.adoc[] 893-- 894 895[open,refpage='vkCmdCopyImageToBuffer2',desc='Copy image data into a buffer',type='protos',alias='vkCmdCopyImageToBuffer2KHR'] 896-- 897:refpage: vkCmdCopyImageToBuffer2 898 899To copy data from an image object to a buffer object, call: 900 901ifdef::VK_VERSION_1_3[] 902include::{generated}/api/protos/vkCmdCopyImageToBuffer2.adoc[] 903endif::VK_VERSION_1_3[] 904 905ifdef::VK_VERSION_1_3+VK_KHR_copy_commands2[or the equivalent command] 906 907ifdef::VK_KHR_copy_commands2[] 908include::{generated}/api/protos/vkCmdCopyImageToBuffer2KHR.adoc[] 909endif::VK_KHR_copy_commands2[] 910 911 * pname:commandBuffer is the command buffer into which the command will be 912 recorded. 913 * pname:pCopyImageToBufferInfo is a pointer to a 914 slink:VkCopyImageToBufferInfo2 structure describing the copy parameters. 915 916This command is functionally identical to flink:vkCmdCopyImageToBuffer, but 917includes extensible sub-structures that include pname:sType and pname:pNext 918parameters, allowing them to be more easily extended. 919 920:regionsparam: pname:pCopyImageToBufferInfo->pRegions 921 922.Valid Usage 923**** 924include::{chapters}/commonvalidity/copy_image_to_buffer_command_buffer_common.adoc[] 925**** 926 927include::{generated}/validity/protos/vkCmdCopyImageToBuffer2.adoc[] 928-- 929 930[open,refpage='VkCopyImageToBufferInfo2',desc='Structure specifying parameters of an image to buffer copy command',type='structs',alias='VkCopyImageToBufferInfo2KHR'] 931-- 932:refpage: VkCopyImageToBufferInfo2 933 934The sname:VkCopyImageToBufferInfo2 structure is defined as: 935 936include::{generated}/api/structs/VkCopyImageToBufferInfo2.adoc[] 937 938ifdef::VK_KHR_copy_commands2[] 939or the equivalent 940 941include::{generated}/api/structs/VkCopyImageToBufferInfo2KHR.adoc[] 942endif::VK_KHR_copy_commands2[] 943 944 * pname:sType is a elink:VkStructureType value identifying this structure. 945 * pname:pNext is `NULL` or a pointer to a structure extending this 946 structure. 947 * pname:srcImage is the source image. 948 * pname:srcImageLayout is the layout of the source image subresources for 949 the copy. 950 * pname:dstBuffer is the destination buffer. 951 * pname:regionCount is the number of regions to copy. 952 * pname:pRegions is a pointer to an array of slink:VkBufferImageCopy2 953 structures specifying the regions to copy. 954 955:imageparam: srcImage 956:imagesubresource: imageSubresource 957:imageoffset: imageOffset 958:imageextent: imageExtent 959:bufferrowlength: bufferRowLength 960:bufferimageheight: bufferImageHeight 961:regionsparam: pname:pRegions 962 963.Valid Usage 964**** 965 * [[VUID-VkCopyImageToBufferInfo2-pRegions-04566]] 966 The image region specified by each element of pname:pRegions 967ifdef::VK_QCOM_rotated_copy_commands[] 968 that does not contain slink:VkCopyCommandTransformInfoQCOM in its 969 pname:pNext chain 970endif::VK_QCOM_rotated_copy_commands[] 971 must: be contained within the specified pname:imageSubresource of 972 pname:srcImage 973ifdef::VK_QCOM_rotated_copy_commands[] 974 * [[VUID-VkCopyImageToBufferInfo2KHR-pRegions-04557]] 975 If the image region specified by each element of pname:pRegions contains 976 slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, the 977 rotated source region as described in 978 <<copies-buffers-images-rotation-addressing>> must: be contained within 979 pname:srcImage 980 * [[VUID-VkCopyImageToBufferInfo2KHR-pRegions-04558]] 981 If any element of pname:pRegions contains 982 slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then 983 pname:srcImage must: have a 1x1x1 <<formats-compatibility-classes,texel 984 block extent>> 985 * [[VUID-VkCopyImageToBufferInfo2KHR-pRegions-06205]] 986 If any element of pname:pRegions contains 987 slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then 988 pname:srcImage must: be of type ename:VK_IMAGE_TYPE_2D 989 * [[VUID-VkCopyImageToBufferInfo2KHR-pRegions-06206]] 990 If any element of pname:pRegions contains 991 slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then 992 pname:srcImage must: not have a 993 <<formats-requiring-sampler-ycbcr-conversion, multi-planar format>> 994endif::VK_QCOM_rotated_copy_commands[] 995include::{chapters}/commonvalidity/copy_image_to_buffer_common.adoc[] 996include::{chapters}/commonvalidity/copy_anyimage_to_imageany_common.adoc[] 997include::{chapters}/commonvalidity/copy_anyimage_to_imageany_single_sampled_common.adoc[] 998include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_common.adoc[] 999include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_not_both_image_common.adoc[] 1000include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_buffer_alignment_common.adoc[] 1001 * [[VUID-VkCopyImageToBufferInfo2-imageOffset-00197]] 1002 For each element of pname:pRegions not containing 1003 sname:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, 1004 pname:imageOffset.x and [eq]#(pname:imageExtent.width {plus} 1005 pname:imageOffset.x)# must: both be greater than or equal to `0` and 1006 less than or equal to the width of the specified pname:imageSubresource 1007 of pname:srcImage 1008 * [[VUID-VkCopyImageToBufferInfo2-imageOffset-00198]] 1009 For each element of pname:pRegions not containing 1010 sname:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, 1011 pname:imageOffset.y and [eq]#(pname:imageExtent.height {plus} 1012 pname:imageOffset.y)# must: both be greater than or equal to `0` and 1013 less than or equal to the height of the specified pname:imageSubresource 1014 of pname:srcImage 1015**** 1016 1017include::{generated}/validity/structs/VkCopyImageToBufferInfo2.adoc[] 1018-- 1019 1020[open,refpage='VkBufferImageCopy2',desc='Structure specifying a buffer image copy operation',type='structs',alias='VkBufferImageCopy2KHR'] 1021-- 1022:refpage: VkBufferImageCopy2 1023 1024For both flink:vkCmdCopyBufferToImage2 and flink:vkCmdCopyImageToBuffer2, 1025each element of pname:pRegions is a structure defined as: 1026 1027include::{generated}/api/structs/VkBufferImageCopy2.adoc[] 1028 1029ifdef::VK_KHR_copy_commands2[] 1030or the equivalent 1031 1032include::{generated}/api/structs/VkBufferImageCopy2KHR.adoc[] 1033endif::VK_KHR_copy_commands2[] 1034 1035 * pname:sType is a elink:VkStructureType value identifying this structure. 1036 * pname:pNext is `NULL` or a pointer to a structure extending this 1037 structure. 1038 * pname:bufferOffset is the offset in bytes from the start of the buffer 1039 object where the image data is copied from or to. 1040 * pname:bufferRowLength and pname:bufferImageHeight specify in texels a 1041 subregion of a larger two- or three-dimensional image in buffer memory, 1042 and control the addressing calculations. 1043 If either of these values is zero, that aspect of the buffer memory is 1044 considered to be tightly packed according to the pname:imageExtent. 1045 * pname:imageSubresource is a slink:VkImageSubresourceLayers used to 1046 specify the specific image subresources of the image used for the source 1047 or destination image data. 1048 * pname:imageOffset selects the initial pname:x, pname:y, pname:z offsets 1049 in texels of the sub-region of the source or destination image data. 1050 * pname:imageExtent is the size in texels of the image to copy in 1051 pname:width, pname:height and pname:depth. 1052 1053This structure is functionally identical to slink:VkBufferImageCopy, but 1054adds pname:sType and pname:pNext parameters, allowing it to be more easily 1055extended. 1056 1057:bufferrowlength: bufferRowLength 1058:bufferimageheight: bufferImageHeight 1059 1060.Valid Usage 1061**** 1062include::{chapters}/commonvalidity/buffer_or_memory_image_copy_common.adoc[] 1063**** 1064 1065include::{generated}/validity/structs/VkBufferImageCopy2.adoc[] 1066-- 1067endif::VK_VERSION_1_3,VK_KHR_copy_commands2[] 1068 1069ifdef::VK_QCOM_rotated_copy_commands[] 1070[open,refpage='VkCopyCommandTransformInfoQCOM',desc='Structure describing transform parameters of rotated copy command',type='structs'] 1071-- 1072The sname:VkCopyCommandTransformInfoQCOM structure is defined as: 1073 1074include::{generated}/api/structs/VkCopyCommandTransformInfoQCOM.adoc[] 1075 1076 * pname:sType is a elink:VkStructureType value identifying this structure. 1077 * pname:pNext is `NULL` or a pointer to a structure extending this 1078 structure. 1079 * pname:transform is a elink:VkSurfaceTransformFlagBitsKHR value 1080 describing the transform to be applied. 1081 1082Including this structure in the pname:pNext chain of 1083slink:VkBufferImageCopy2 defines a rotation to be performed when copying 1084between an image and a buffer. 1085Including this structure in the pname:pNext chain of slink:VkBlitImageInfo2 1086defines a rotation to be performed when blitting between two images. 1087If this structure is not specified in either case, the implementation 1088behaves as if it was specified with a pname:transform equal to 1089ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR. 1090 1091Specifying a transform for a copy between an image and a buffer 1092<<copies-buffers-images-rotation-addressing, rotates the region accessed in 1093the image around the offset>>. 1094Specifying a transform for a blit performs a similar transform as described 1095in <<copies-images-scaling-rotation, Image Blits with Scaling and 1096Rotation>>. 1097 1098Rotations other than ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR can: only 1099be specified for single-plane 2D images with a 1x1x1 1100<<formats-compatibility-classes,texel block extent>>. 1101 1102.Valid Usage 1103**** 1104 * [[VUID-VkCopyCommandTransformInfoQCOM-transform-04560]] 1105 pname:transform must: be ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, 1106 ename:VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR, 1107 ename:VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR, or 1108 ename:VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR 1109**** 1110 1111include::{generated}/validity/structs/VkCopyCommandTransformInfoQCOM.adoc[] 1112-- 1113endif::VK_QCOM_rotated_copy_commands[] 1114 1115ifdef::VK_EXT_host_image_copy[] 1116include::{chapters}/VK_EXT_host_image_copy/copies.adoc[] 1117endif::VK_EXT_host_image_copy[] 1118 1119 1120ifdef::VK_NV_copy_memory_indirect[] 1121[[indirect-copies]] 1122== Indirect Copies 1123 1124An application can use indirect copies when the copy parameters are not 1125known during the command buffer creation time. 1126 1127[open,refpage='vkCmdCopyMemoryIndirectNV',desc='Copy data between memory regions',type='protos'] 1128-- 1129To copy data between two memory regions by specifying copy parameters 1130indirectly in a buffer, call: 1131 1132include::{generated}/api/protos/vkCmdCopyMemoryIndirectNV.adoc[] 1133 1134 * pname:commandBuffer is the command buffer into which the command will be 1135 recorded. 1136 * pname:copyBufferAddress is the buffer address specifying the copy 1137 parameters. 1138 This buffer is laid out in memory as an array of 1139 slink:VkCopyMemoryIndirectCommandNV structures. 1140 * pname:copyCount is the number of copies to execute, and can be zero. 1141 * pname:stride is the stride in bytes between successive sets of copy 1142 parameters. 1143 1144Each region read from pname:copyBufferAddress is copied from the source 1145region to the specified destination region. 1146The results are undefined: if any of the source and destination regions 1147overlap in memory. 1148 1149.Valid Usage 1150**** 1151 * [[VUID-vkCmdCopyMemoryIndirectNV-None-07653]] 1152 The <<features-indirectCopy, pname:indirectCopy>> feature must: be 1153 enabled 1154 * [[VUID-vkCmdCopyMemoryIndirectNV-copyBufferAddress-07654]] 1155 pname:copyBufferAddress must: be 4 byte aligned 1156 * [[VUID-vkCmdCopyMemoryIndirectNV-stride-07655]] 1157 pname:stride must: be a multiple of `4` and must: be greater than or 1158 equal to sizeof(sname:VkCopyMemoryIndirectCommandNV) 1159 * [[VUID-vkCmdCopyMemoryIndirectNV-commandBuffer-07656]] 1160 The slink:VkCommandPool that pname:commandBuffer was allocated from 1161 must: support at least one of the 1162 slink:VkPhysicalDeviceCopyMemoryIndirectPropertiesNV::pname:supportedQueues 1163**** 1164 1165include::{generated}/validity/protos/vkCmdCopyMemoryIndirectNV.adoc[] 1166-- 1167 1168[open,refpage='VkCopyMemoryIndirectCommandNV',desc='Structure specifying indirect memory region copy operation',type='structs'] 1169-- 1170The structure describing source and destination memory regions, 1171sname:VkCopyMemoryIndirectCommandNV is defined as: 1172 1173include::{generated}/api/structs/VkCopyMemoryIndirectCommandNV.adoc[] 1174 1175 * pname:srcAddress is the starting address of the source device memory to 1176 copy from. 1177 * pname:dstAddress is the starting address of the destination device 1178 memory to copy to. 1179 * pname:size is the size of the copy in bytes. 1180 1181.Valid Usage 1182**** 1183 * [[VUID-VkCopyMemoryIndirectCommandNV-srcAddress-07657]] 1184 The pname:srcAddress must: be 4 byte aligned 1185 * [[VUID-VkCopyMemoryIndirectCommandNV-dstAddress-07658]] 1186 The pname:dstAddress must: be 4 byte aligned 1187 * [[VUID-VkCopyMemoryIndirectCommandNV-size-07659]] 1188 The pname:size must: be 4 byte aligned 1189**** 1190 1191include::{generated}/validity/structs/VkCopyMemoryIndirectCommandNV.adoc[] 1192-- 1193 1194[open,refpage='vkCmdCopyMemoryToImageIndirectNV',desc='Copy data from a memory region into an image',type='protos'] 1195-- 1196:refpage: vkCmdCopyMemoryToImageIndirectNV 1197 1198To copy data from a memory region to an image object by specifying copy 1199parameters in a buffer, call: 1200 1201include::{generated}/api/protos/vkCmdCopyMemoryToImageIndirectNV.adoc[] 1202 1203 * pname:commandBuffer is the command buffer into which the command will be 1204 recorded. 1205 * pname:copyBufferAddress is the buffer address specifying the copy 1206 parameters. 1207 This buffer is laid out in memory as an array of 1208 slink:VkCopyMemoryToImageIndirectCommandNV structures. 1209 * pname:copyCount is the number of copies to execute, and can be zero. 1210 * pname:stride is the byte stride between successive sets of copy 1211 parameters. 1212 * pname:dstImage is the destination image. 1213 * pname:dstImageLayout is the layout of the destination image subresources 1214 for the copy. 1215 * pname:pImageSubresources is a pointer to an array of size 1216 pname:copyCount of slink:VkImageSubresourceLayers used to specify the 1217 specific image subresource of the destination image data for that copy. 1218 1219Each region in pname:copyBufferAddress is copied from the source memory 1220region to an image region in the destination image. 1221If the destination image is of type ename:VK_IMAGE_TYPE_3D, the starting 1222slice and number of slices to copy are specified in 1223pname:pImageSubresources::pname:baseArrayLayer and 1224pname:pImageSubresources::pname:layerCount respectively. 1225The copy must: be performed on a queue that supports indirect copy 1226operations, see slink:VkPhysicalDeviceCopyMemoryIndirectPropertiesNV. 1227 1228:imageparam: dstImage 1229 1230.Valid Usage 1231**** 1232 * [[VUID-vkCmdCopyMemoryToImageIndirectNV-None-07660]] 1233 The <<features-indirectCopy, pname:indirectCopy>> feature must: be 1234 enabled 1235 * [[VUID-vkCmdCopyMemoryToImageIndirectNV-dstImage-07661]] 1236 pname:dstImage must: not be a protected image 1237 * [[VUID-vkCmdCopyMemoryToImageIndirectNV-aspectMask-07662]] 1238 The pname:aspectMask member for every subresource in 1239 pname:pImageSubresources must: only have a single bit set 1240 * [[VUID-vkCmdCopyMemoryToImageIndirectNV-dstImage-07663]] 1241 The image region specified by each element in sname:copyBufferAddress 1242 must: be a region that is contained within pname:dstImage 1243 * [[VUID-vkCmdCopyMemoryToImageIndirectNV-dstImage-07664]] 1244 pname:dstImage must: have been created with 1245 ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag 1246 * [[VUID-vkCmdCopyMemoryToImageIndirectNV-dstImage-07665]] 1247 If pname:dstImage is non-sparse then it must: be bound completely and 1248 contiguously to a single sname:VkDeviceMemory object 1249include::{chapters}/commonvalidity/copy_anyimage_to_imageany_single_sampled_common.adoc[] 1250 * [[VUID-vkCmdCopyMemoryToImageIndirectNV-dstImageLayout-07667]] 1251 pname:dstImageLayout must: specify the layout of the image subresources 1252 of pname:dstImage at the time this command is executed on a 1253 sname:VkDevice 1254 * [[VUID-vkCmdCopyMemoryToImageIndirectNV-dstImageLayout-07669]] 1255 pname:dstImageLayout must: be 1256 ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, 1257ifdef::VK_KHR_shared_presentable_image[] 1258 ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, 1259endif::VK_KHR_shared_presentable_image[] 1260 or ename:VK_IMAGE_LAYOUT_GENERAL 1261 * [[VUID-vkCmdCopyMemoryToImageIndirectNV-mipLevel-07670]] 1262 The specified pname:mipLevel of each region must: be less than the 1263 pname:mipLevels specified in slink:VkImageCreateInfo when pname:dstImage 1264 was created 1265 * [[VUID-vkCmdCopyMemoryToImageIndirectNV-layerCount-09244]] 1266 {empty} 1267ifdef::VK_KHR_maintenance5[] 1268 If the <<features-maintenance5, pname:maintenance5>> feature is not 1269 enabled, 1270endif::VK_KHR_maintenance5[] 1271 pname:layerCount must: not be ename:VK_REMAINING_ARRAY_LAYERS 1272 * [[VUID-vkCmdCopyMemoryToImageIndirectNV-layerCount-08764]] 1273 If pname:layerCount is not ename:VK_REMAINING_ARRAY_LAYERS, the 1274 specified pname:baseArrayLayer {plus} pname:layerCount of each region 1275 must: be less than or equal to the pname:arrayLayers specified in 1276 slink:VkImageCreateInfo when pname:dstImage was created 1277 * [[VUID-vkCmdCopyMemoryToImageIndirectNV-imageOffset-07672]] 1278 The pname:imageOffset and pname:imageExtent members of each region must: 1279 respect the image transfer granularity requirements of 1280 pname:commandBuffer's command pool's queue family, as described in 1281 slink:VkQueueFamilyProperties 1282ifdef::VK_EXT_fragment_density_map[] 1283 * [[VUID-vkCmdCopyMemoryToImageIndirectNV-dstImage-07673]] 1284 pname:dstImage must: not have been created with pname:flags containing 1285 ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT 1286endif::VK_EXT_fragment_density_map[] 1287 * [[VUID-vkCmdCopyMemoryToImageIndirectNV-commandBuffer-07674]] 1288 If the queue family used to create the slink:VkCommandPool which 1289 pname:commandBuffer was allocated from does not support 1290 ename:VK_QUEUE_GRAPHICS_BIT, for each region, the pname:aspectMask 1291 member of pname:pImageSubresources must: not be 1292 ename:VK_IMAGE_ASPECT_DEPTH_BIT or ename:VK_IMAGE_ASPECT_STENCIL_BIT 1293 * [[VUID-vkCmdCopyMemoryToImageIndirectNV-imageOffset-07675]] 1294 For each region in sname:copyBufferAddress, pname:imageOffset.y and 1295 [eq]#(pname:imageExtent.height {plus} pname:imageOffset.y)# must: both 1296 be greater than or equal to `0` and less than or equal to the height of 1297 the specified subresource 1298 * [[VUID-vkCmdCopyMemoryToImageIndirectNV-offset-07676]] 1299 pname:offset must: be 4 byte aligned 1300 * [[VUID-vkCmdCopyMemoryToImageIndirectNV-stride-07677]] 1301 pname:stride must: be a multiple of `4` and must: be greater than or 1302 equal to sizeof(sname:VkCopyMemoryToImageIndirectCommandNV) 1303**** 1304 1305include::{generated}/validity/protos/vkCmdCopyMemoryToImageIndirectNV.adoc[] 1306-- 1307 1308[open,refpage='VkCopyMemoryToImageIndirectCommandNV',desc='Structure specifying indirect buffer image copy operation',type='structs'] 1309-- 1310The sname:VkCopyMemoryToImageIndirectCommandNV is defined as: 1311 1312include::{generated}/api/structs/VkCopyMemoryToImageIndirectCommandNV.adoc[] 1313 1314 * pname:srcAddress is the starting address of the source device memory to 1315 copy from. 1316 * pname:bufferRowLength and pname:bufferImageHeight specify in texels a 1317 subregion of a larger two- or three-dimensional image in buffer memory, 1318 and control the addressing calculations. 1319 If either of these values is zero, that aspect of the buffer memory is 1320 considered to be tightly packed according to the pname:imageExtent. 1321 * pname:imageSubresource is a slink:VkImageSubresourceLayers used to 1322 specify the specific image subresources of the image used for the 1323 destination image data, which must: match the values specified in 1324 pname:pImageSubresources parameter of 1325 flink:vkCmdCopyMemoryToImageIndirectNV during command recording. 1326 * pname:imageOffset selects the initial pname:x, pname:y, pname:z offsets 1327 in texels of the sub-region of the destination image data. 1328 * pname:imageExtent is the size in texels of the destination image in 1329 pname:width, pname:height and pname:depth. 1330 1331.Valid Usage 1332**** 1333 * [[VUID-VkCopyMemoryToImageIndirectCommandNV-srcAddress-07678]] 1334 The pname:srcAddress must: be 4 byte aligned 1335 * [[VUID-VkCopyMemoryToImageIndirectCommandNV-bufferRowLength-07679]] 1336 pname:bufferRowLength must: be `0`, or greater than or equal to the 1337 pname:width member of pname:imageExtent 1338 * [[VUID-VkCopyMemoryToImageIndirectCommandNV-bufferImageHeight-07680]] 1339 pname:bufferImageHeight must: be `0`, or greater than or equal to the 1340 pname:height member of pname:imageExtent 1341 * [[VUID-VkCopyMemoryToImageIndirectCommandNV-imageOffset-07681]] 1342 pname:imageOffset must: specify a valid offset in the destination image 1343 * [[VUID-VkCopyMemoryToImageIndirectCommandNV-imageExtent-07682]] 1344 pname:imageExtent must: specify a valid region in the destination image 1345 and can be `0` 1346**** 1347 1348include::{generated}/validity/structs/VkCopyMemoryToImageIndirectCommandNV.adoc[] 1349-- 1350endif::VK_NV_copy_memory_indirect[] 1351 1352 1353[[copies-imagescaling]] 1354== Image Copies With Scaling 1355 1356[open,refpage='vkCmdBlitImage',desc='Copy regions of an image, potentially performing format conversion,',type='protos'] 1357-- 1358:refpage: vkCmdBlitImage 1359 1360To copy regions of a source image into a destination image, potentially 1361performing format conversion, arbitrary scaling, and filtering, call: 1362 1363include::{generated}/api/protos/vkCmdBlitImage.adoc[] 1364 1365 * pname:commandBuffer is the command buffer into which the command will be 1366 recorded. 1367 * pname:srcImage is the source image. 1368 * pname:srcImageLayout is the layout of the source image subresources for 1369 the blit. 1370 * pname:dstImage is the destination image. 1371 * pname:dstImageLayout is the layout of the destination image subresources 1372 for the blit. 1373 * pname:regionCount is the number of regions to blit. 1374 * pname:pRegions is a pointer to an array of slink:VkImageBlit structures 1375 specifying the regions to blit. 1376 * pname:filter is a elink:VkFilter specifying the filter to apply if the 1377 blits require scaling. 1378 1379fname:vkCmdBlitImage must: not be used for multisampled source or 1380destination images. 1381Use flink:vkCmdResolveImage for this purpose. 1382 1383As the sizes of the source and destination extents can: differ in any 1384dimension, texels in the source extent are scaled and filtered to the 1385destination extent. 1386Scaling occurs via the following operations: 1387 1388 * For each destination texel, the integer coordinate of that texel is 1389 converted to an unnormalized texture coordinate, using the effective 1390 inverse of the equations described in 1391 <<textures-unnormalized-to-integer, unnormalized to integer 1392 conversion>>: 1393 {empty}:: [eq]#u~base~ = i {plus} {onehalf}# 1394 {empty}:: [eq]#v~base~ = j {plus} {onehalf}# 1395 {empty}:: [eq]#w~base~ = k {plus} {onehalf}# 1396 * These base coordinates are then offset by the first destination offset: 1397 {empty}:: [eq]#u~offset~ = u~base~ - x~dst0~# 1398 {empty}:: [eq]#v~offset~ = v~base~ - y~dst0~# 1399 {empty}:: [eq]#w~offset~ = w~base~ - z~dst0~# 1400 {empty}:: [eq]#a~offset~ = a - pname:baseArrayCount~dst~# 1401 * The scale is determined from the source and destination regions, and 1402 applied to the offset coordinates: 1403 {empty}:: [eq]#scale~u~ = (x~src1~ - x~src0~) / (x~dst1~ - x~dst0~)# 1404 {empty}:: [eq]#scale~v~ = (y~src1~ - y~src0~) / (y~dst1~ - y~dst0~)# 1405 {empty}:: [eq]#scale~w~ = (z~src1~ - z~src0~) / (z~dst1~ - z~dst0~)# 1406 {empty}:: [eq]#u~scaled~ = u~offset~ {times} scale~u~# 1407 {empty}:: [eq]#v~scaled~ = v~offset~ {times} scale~v~# 1408 {empty}:: [eq]#w~scaled~ = w~offset~ {times} scale~w~# 1409 * Finally the source offset is added to the scaled coordinates, to 1410 determine the final unnormalized coordinates used to sample from 1411 pname:srcImage: 1412 {empty}:: [eq]#u = u~scaled~ {plus} x~src0~# 1413 {empty}:: [eq]#v = v~scaled~ {plus} y~src0~# 1414 {empty}:: [eq]#w = w~scaled~ {plus} z~src0~# 1415 {empty}:: [eq]#q = pname:mipLevel# 1416 {empty}:: [eq]#a = a~offset~ {plus} pname:baseArrayCount~src~# 1417 1418These coordinates are used to sample from the source image, as described in 1419<<textures, Image Operations chapter>>, with the filter mode equal to that 1420of pname:filter, a mipmap mode of ename:VK_SAMPLER_MIPMAP_MODE_NEAREST and 1421an address mode of ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE. 1422Implementations must: clamp at the edge of the source image, and may: 1423additionally clamp to the edge of the source region. 1424 1425[NOTE] 1426.Note 1427==== 1428Due to allowable rounding errors in the generation of the source texture 1429coordinates, it is not always possible to guarantee exactly which source 1430texels will be sampled for a given blit. 1431As rounding errors are implementation-dependent, the exact results of a 1432blitting operation are also implementation-dependent. 1433==== 1434 1435Blits are done layer by layer starting with the pname:baseArrayLayer member 1436of pname:srcSubresource for the source and pname:dstSubresource for the 1437destination. 1438pname:layerCount layers are blitted to the destination image. 1439 1440When blitting 3D textures, slices in the destination region bounded by 1441pname:dstOffsets[0].z and pname:dstOffsets[1].z are sampled from slices in 1442the source region bounded by pname:srcOffsets[0].z and 1443pname:srcOffsets[1].z. 1444If the pname:filter parameter is ename:VK_FILTER_LINEAR then the value 1445sampled from the source image is taken by doing linear filtering using the 1446interpolated *z* coordinate represented by *w* in the previous equations. 1447If the pname:filter parameter is ename:VK_FILTER_NEAREST then the value 1448sampled from the source image is taken from the single nearest slice, with 1449an implementation-dependent arithmetic rounding mode. 1450 1451The following filtering and conversion rules apply: 1452 1453 * Integer formats can: only be converted to other integer formats with the 1454 same signedness. 1455 * No format conversion is supported between depth/stencil images. 1456 The formats must: match. 1457 * Format conversions on unorm, snorm, scaled and packed float formats of 1458 the copied aspect of the image are performed by first converting the 1459 pixels to float values. 1460 * For sRGB source formats, nonlinear RGB values are converted to linear 1461 representation prior to filtering. 1462 * After filtering, the float values are first clamped and then cast to the 1463 destination image format. 1464 In case of sRGB destination format, linear RGB values are converted to 1465 nonlinear representation before writing the pixel to the image. 1466 1467Signed and unsigned integers are converted by first clamping to the 1468representable range of the destination format, then casting the value. 1469 1470.Valid Usage 1471**** 1472include::{chapters}/commonvalidity/blit_image_command_buffer_common.adoc[] 1473include::{chapters}/commonvalidity/blit_image_common.adoc[] 1474**** 1475 1476include::{generated}/validity/protos/vkCmdBlitImage.adoc[] 1477-- 1478 1479[open,refpage='VkImageBlit',desc='Structure specifying an image blit operation',type='structs'] 1480-- 1481:refpage: VkImageBlit 1482 1483The sname:VkImageBlit structure is defined as: 1484 1485include::{generated}/api/structs/VkImageBlit.adoc[] 1486 1487 * pname:srcSubresource is the subresource to blit from. 1488 * pname:srcOffsets is a pointer to an array of two slink:VkOffset3D 1489 structures specifying the bounds of the source region within 1490 pname:srcSubresource. 1491 * pname:dstSubresource is the subresource to blit into. 1492 * pname:dstOffsets is a pointer to an array of two slink:VkOffset3D 1493 structures specifying the bounds of the destination region within 1494 pname:dstSubresource. 1495 1496For each element of the pname:pRegions array, a blit operation is performed 1497for the specified source and destination regions. 1498 1499.Valid Usage 1500**** 1501include::{chapters}/commonvalidity/image_blit_common.adoc[] 1502**** 1503 1504include::{generated}/validity/structs/VkImageBlit.adoc[] 1505-- 1506 1507ifdef::VK_VERSION_1_3,VK_KHR_copy_commands2[] 1508A more extensible version of the blit image command is defined below. 1509 1510[open,refpage='vkCmdBlitImage2',desc='Copy regions of an image, potentially performing format conversion,',type='protos',alias='vkCmdBlitImage2KHR'] 1511-- 1512:refpage: vkCmdBlitImage2 1513 1514To copy regions of a source image into a destination image, potentially 1515performing format conversion, arbitrary scaling, and filtering, call: 1516 1517ifdef::VK_VERSION_1_3[] 1518include::{generated}/api/protos/vkCmdBlitImage2.adoc[] 1519endif::VK_VERSION_1_3[] 1520 1521ifdef::VK_VERSION_1_3+VK_KHR_copy_commands2[or the equivalent command] 1522 1523ifdef::VK_KHR_copy_commands2[] 1524include::{generated}/api/protos/vkCmdBlitImage2KHR.adoc[] 1525endif::VK_KHR_copy_commands2[] 1526 1527 * pname:commandBuffer is the command buffer into which the command will be 1528 recorded. 1529 * pname:pBlitImageInfo is a pointer to a slink:VkBlitImageInfo2 structure 1530 describing the blit parameters. 1531 1532This command is functionally identical to flink:vkCmdBlitImage, but includes 1533extensible sub-structures that include pname:sType and pname:pNext 1534parameters, allowing them to be more easily extended. 1535 1536.Valid Usage 1537**** 1538include::{chapters}/commonvalidity/blit_image_command_buffer_common.adoc[] 1539**** 1540 1541include::{generated}/validity/protos/vkCmdBlitImage2.adoc[] 1542-- 1543 1544[open,refpage='VkBlitImageInfo2',desc='Structure specifying parameters of blit image command',type='structs',alias='VkBlitImageInfo2KHR'] 1545-- 1546:refpage: VkBlitImageInfo2 1547 1548The sname:VkBlitImageInfo2 structure is defined as: 1549 1550include::{generated}/api/structs/VkBlitImageInfo2.adoc[] 1551 1552ifdef::VK_KHR_copy_commands2[] 1553or the equivalent 1554 1555include::{generated}/api/structs/VkBlitImageInfo2KHR.adoc[] 1556endif::VK_KHR_copy_commands2[] 1557 1558 * pname:sType is a elink:VkStructureType value identifying this structure. 1559 * pname:pNext is `NULL` or a pointer to a structure extending this 1560 structure. 1561 * pname:srcImage is the source image. 1562 * pname:srcImageLayout is the layout of the source image subresources for 1563 the blit. 1564 * pname:dstImage is the destination image. 1565 * pname:dstImageLayout is the layout of the destination image subresources 1566 for the blit. 1567 * pname:regionCount is the number of regions to blit. 1568 * pname:pRegions is a pointer to an array of slink:VkImageBlit2 structures 1569 specifying the regions to blit. 1570 * pname:filter is a elink:VkFilter specifying the filter to apply if the 1571 blits require scaling. 1572 1573.Valid Usage 1574**** 1575include::{chapters}/commonvalidity/blit_image_common.adoc[] 1576ifdef::VK_QCOM_rotated_copy_commands[] 1577 * [[VUID-VkBlitImageInfo2-pRegions-04561]] 1578 If any element of pname:pRegions contains 1579 slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then 1580 pname:srcImage and pname:dstImage must: not be block-compressed images 1581 * [[VUID-VkBlitImageInfo2KHR-pRegions-06207]] 1582 If any element of pname:pRegions contains 1583 slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then 1584 pname:srcImage must: be of type ename:VK_IMAGE_TYPE_2D 1585 * [[VUID-VkBlitImageInfo2KHR-pRegions-06208]] 1586 If any element of pname:pRegions contains 1587 slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then 1588 pname:srcImage must: not have a 1589 <<formats-requiring-sampler-ycbcr-conversion, multi-planar format>> 1590endif::VK_QCOM_rotated_copy_commands[] 1591ifdef::VK_QCOM_filter_cubic_weights[] 1592 * [[VUID-VkBlitImageInfo2-filter-09204]] 1593 If pname:filter is ename:VK_FILTER_CUBIC_EXT and if the 1594 <<features-filter-cubic-weight-selection,selectableCubicWeights>> 1595 feature is not enabled then the cubic weights must: be 1596 ename:VK_CUBIC_FILTER_WEIGHTS_CATMULL_ROM_QCOM 1597endif::VK_QCOM_filter_cubic_weights[] 1598**** 1599 1600include::{generated}/validity/structs/VkBlitImageInfo2.adoc[] 1601-- 1602 1603ifdef::VK_QCOM_filter_cubic_weights[] 1604 1605If pname:filter is ename:VK_FILTER_CUBIC_EXT and if the pname:pNext chain of 1606slink:VkBlitImageInfo2 includes a sname:VkBlitImageCubicWeightsInfoQCOM 1607structure, then that structure specifies cubic weights are used in the blit. 1608If that structure is not present, then cubic weights are considered to be 1609ename:VK_CUBIC_FILTER_WEIGHTS_CATMULL_ROM_QCOM. 1610 1611[open,refpage='VkBlitImageCubicWeightsInfoQCOM',desc='Structure specifying image blit cubic weight info',type='structs',alias='VkImageBlit2KHR'] 1612-- 1613:refpage: VkBlitImageCubicWeightsInfoQCOM 1614 1615The sname:VkBlitImageCubicWeightsInfoQCOM structure is defined as: 1616 1617include::{generated}/api/structs/VkBlitImageCubicWeightsInfoQCOM.adoc[] 1618 1619 * pname:sType is a elink:VkStructureType value identifying this structure. 1620 * pname:pNext is `NULL` or a pointer to a structure extending this 1621 structure. 1622 * pname:cubicWeights is a elink:VkCubicFilterWeightsQCOM value controlling 1623 cubic filter weights for the blit. 1624 1625include::{generated}/validity/structs/VkBlitImageCubicWeightsInfoQCOM.adoc[] 1626-- 1627 1628endif::VK_QCOM_filter_cubic_weights[] 1629 1630 1631[open,refpage='VkImageBlit2',desc='Structure specifying an image blit operation',type='structs',alias='VkImageBlit2KHR'] 1632-- 1633:refpage: VkImageBlit2 1634 1635The sname:VkImageBlit2 structure is defined as: 1636 1637include::{generated}/api/structs/VkImageBlit2.adoc[] 1638 1639ifdef::VK_KHR_copy_commands2[] 1640or the equivalent 1641 1642include::{generated}/api/structs/VkImageBlit2KHR.adoc[] 1643endif::VK_KHR_copy_commands2[] 1644 1645 * pname:sType is a elink:VkStructureType value identifying this structure. 1646 * pname:pNext is `NULL` or a pointer to a structure extending this 1647 structure. 1648 * pname:srcSubresource is the subresource to blit from. 1649 * pname:srcOffsets is a pointer to an array of two slink:VkOffset3D 1650 structures specifying the bounds of the source region within 1651 pname:srcSubresource. 1652 * pname:dstSubresource is the subresource to blit into. 1653 * pname:dstOffsets is a pointer to an array of two slink:VkOffset3D 1654 structures specifying the bounds of the destination region within 1655 pname:dstSubresource. 1656 1657For each element of the pname:pRegions array, a blit operation is performed 1658for the specified source and destination regions. 1659 1660.Valid Usage 1661**** 1662include::{chapters}/commonvalidity/image_blit_common.adoc[] 1663**** 1664 1665include::{generated}/validity/structs/VkImageBlit2.adoc[] 1666-- 1667 1668ifdef::VK_QCOM_rotated_copy_commands[] 1669For flink:vkCmdBlitImage2, each region copied can include a rotation. 1670To specify a rotated region, add slink:VkCopyCommandTransformInfoQCOM to the 1671pname:pNext chain of slink:VkImageBlit2. 1672For each region with a rotation specified, 1673<<copies-images-scaling-rotation,Image Blits with Scaling and Rotation>> 1674specifies how coordinates are rotated prior to sampling from the source 1675image. 1676When rotation is specified, the source and destination images must: each be 16772D images, have a 1x1x1 <<formats-compatibility-classes,texel block 1678extent>>, and only one plane. 1679endif::VK_QCOM_rotated_copy_commands[] 1680endif::VK_VERSION_1_3,VK_KHR_copy_commands2[] 1681 1682ifdef::VK_QCOM_rotated_copy_commands[] 1683include::{chapters}/VK_QCOM_rotated_copies/rotated_addressing_blits.adoc[] 1684endif::VK_QCOM_rotated_copy_commands[] 1685 1686 1687[[copies-resolve]] 1688== Resolving Multisample Images 1689 1690[open,refpage='vkCmdResolveImage',desc='Resolve regions of an image',type='protos'] 1691-- 1692:refpage: vkCmdResolveImage 1693 1694To resolve a multisample color image to a non-multisample color image, call: 1695 1696include::{generated}/api/protos/vkCmdResolveImage.adoc[] 1697 1698 * pname:commandBuffer is the command buffer into which the command will be 1699 recorded. 1700 * pname:srcImage is the source image. 1701 * pname:srcImageLayout is the layout of the source image subresources for 1702 the resolve. 1703 * pname:dstImage is the destination image. 1704 * pname:dstImageLayout is the layout of the destination image subresources 1705 for the resolve. 1706 * pname:regionCount is the number of regions to resolve. 1707 * pname:pRegions is a pointer to an array of slink:VkImageResolve 1708 structures specifying the regions to resolve. 1709 1710During the resolve the samples corresponding to each pixel location in the 1711source are converted to a single sample before being written to the 1712destination. 1713If the source formats are floating-point or normalized types, the sample 1714values for each pixel are resolved in an implementation-dependent manner. 1715If the source formats are integer types, a single sample's value is selected 1716for each pixel. 1717 1718pname:srcOffset and pname:dstOffset select the initial pname:x, pname:y, and 1719pname:z offsets in texels of the sub-regions of the source and destination 1720image data. 1721pname:extent is the size in texels of the source image to resolve in 1722pname:width, pname:height and pname:depth. 1723Each element of pname:pRegions must: be a region that is contained within 1724its corresponding image. 1725 1726Resolves are done layer by layer starting with pname:baseArrayLayer member 1727of pname:srcSubresource for the source and pname:dstSubresource for the 1728destination. 1729pname:layerCount layers are resolved to the destination image. 1730 1731.Valid Usage 1732**** 1733include::{chapters}/commonvalidity/resolve_image_command_buffer_common.adoc[] 1734include::{chapters}/commonvalidity/resolve_image_common.adoc[] 1735**** 1736 1737include::{generated}/validity/protos/vkCmdResolveImage.adoc[] 1738-- 1739 1740[open,refpage='VkImageResolve',desc='Structure specifying an image resolve operation',type='structs'] 1741-- 1742:refpage: VkImageResolve 1743 1744The sname:VkImageResolve structure is defined as: 1745 1746include::{generated}/api/structs/VkImageResolve.adoc[] 1747 1748 * pname:srcSubresource and pname:dstSubresource are 1749 slink:VkImageSubresourceLayers structures specifying the image 1750 subresources of the images used for the source and destination image 1751 data, respectively. 1752 Resolve of depth/stencil images is not supported. 1753 * pname:srcOffset and pname:dstOffset select the initial pname:x, pname:y, 1754 and pname:z offsets in texels of the sub-regions of the source and 1755 destination image data. 1756 * pname:extent is the size in texels of the source image to resolve in 1757 pname:width, pname:height and pname:depth. 1758 1759.Valid Usage 1760**** 1761include::{chapters}/commonvalidity/image_resolve_common.adoc[] 1762**** 1763 1764include::{generated}/validity/structs/VkImageResolve.adoc[] 1765-- 1766 1767ifdef::VK_VERSION_1_3,VK_KHR_copy_commands2[] 1768 1769A more extensible version of the resolve image command is defined below. 1770 1771[open,refpage='vkCmdResolveImage2',desc='Resolve regions of an image',type='protos',alias='vkCmdResolveImage2KHR'] 1772-- 1773:refpage: vkCmdResolveImage2 1774 1775To resolve a multisample image to a non-multisample image, call: 1776 1777ifdef::VK_VERSION_1_3[] 1778include::{generated}/api/protos/vkCmdResolveImage2.adoc[] 1779endif::VK_VERSION_1_3[] 1780 1781ifdef::VK_VERSION_1_3+VK_KHR_copy_commands2[or the equivalent command] 1782 1783ifdef::VK_KHR_copy_commands2[] 1784include::{generated}/api/protos/vkCmdResolveImage2KHR.adoc[] 1785endif::VK_KHR_copy_commands2[] 1786 1787 * pname:commandBuffer is the command buffer into which the command will be 1788 recorded. 1789 * pname:pResolveImageInfo is a pointer to a slink:VkResolveImageInfo2 1790 structure describing the resolve parameters. 1791 1792This command is functionally identical to flink:vkCmdResolveImage, but 1793includes extensible sub-structures that include pname:sType and pname:pNext 1794parameters, allowing them to be more easily extended. 1795 1796 1797.Valid Usage 1798**** 1799include::{chapters}/commonvalidity/resolve_image_command_buffer_common.adoc[] 1800**** 1801 1802include::{generated}/validity/protos/vkCmdResolveImage2.adoc[] 1803-- 1804 1805[open,refpage='VkResolveImageInfo2',desc='Structure specifying parameters of resolve image command',type='structs',alias='VkResolveImageInfo2KHR'] 1806-- 1807:refpage: VkResolveImageInfo2 1808 1809The sname:VkResolveImageInfo2 structure is defined as: 1810 1811include::{generated}/api/structs/VkResolveImageInfo2.adoc[] 1812 1813ifdef::VK_KHR_copy_commands2[] 1814or the equivalent 1815 1816include::{generated}/api/structs/VkResolveImageInfo2KHR.adoc[] 1817endif::VK_KHR_copy_commands2[] 1818 1819 * pname:sType is a elink:VkStructureType value identifying this structure. 1820 * pname:pNext is `NULL` or a pointer to a structure extending this 1821 structure. 1822 * pname:srcImage is the source image. 1823 * pname:srcImageLayout is the layout of the source image subresources for 1824 the resolve. 1825 * pname:dstImage is the destination image. 1826 * pname:dstImageLayout is the layout of the destination image subresources 1827 for the resolve. 1828 * pname:regionCount is the number of regions to resolve. 1829 * pname:pRegions is a pointer to an array of slink:VkImageResolve2 1830 structures specifying the regions to resolve. 1831 1832.Valid Usage 1833**** 1834include::{chapters}/commonvalidity/resolve_image_common.adoc[] 1835**** 1836 1837include::{generated}/validity/structs/VkResolveImageInfo2.adoc[] 1838-- 1839 1840[open,refpage='VkImageResolve2',desc='Structure specifying an image resolve operation',type='structs',alias='VkImageResolve2KHR'] 1841-- 1842:refpage: VkImageResolve2 1843 1844The sname:VkImageResolve2 structure is defined as: 1845 1846include::{generated}/api/structs/VkImageResolve2.adoc[] 1847 1848ifdef::VK_KHR_copy_commands2[] 1849or the equivalent 1850 1851include::{generated}/api/structs/VkImageResolve2KHR.adoc[] 1852endif::VK_KHR_copy_commands2[] 1853 1854 * pname:sType is a elink:VkStructureType value identifying this structure. 1855 * pname:pNext is `NULL` or a pointer to a structure extending this 1856 structure. 1857 * pname:srcSubresource and pname:dstSubresource are 1858 slink:VkImageSubresourceLayers structures specifying the image 1859 subresources of the images used for the source and destination image 1860 data, respectively. 1861 Resolve of depth/stencil images is not supported. 1862 * pname:srcOffset and pname:dstOffset select the initial pname:x, pname:y, 1863 and pname:z offsets in texels of the sub-regions of the source and 1864 destination image data. 1865 * pname:extent is the size in texels of the source image to resolve in 1866 pname:width, pname:height and pname:depth. 1867 1868.Valid Usage 1869**** 1870include::{chapters}/commonvalidity/image_resolve_common.adoc[] 1871**** 1872 1873include::{generated}/validity/structs/VkImageResolve2.adoc[] 1874-- 1875endif::VK_VERSION_1_3,VK_KHR_copy_commands2[] 1876 1877ifdef::VK_KHR_object_refresh[] 1878include::{chapters}/VK_KHR_object_refresh/copies.adoc[] 1879endif::VK_KHR_object_refresh[] 1880 1881ifdef::VK_AMD_buffer_marker[] 1882include::{chapters}/VK_AMD_buffer_marker/copies.adoc[] 1883endif::VK_AMD_buffer_marker[] 1884