1// Copyright 2015-2024 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->baseArrayLayer and 1224pname:pImageSubresources->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-08764]] 1266 If pname:layerCount is not ename:VK_REMAINING_ARRAY_LAYERS, the 1267 specified pname:baseArrayLayer {plus} pname:layerCount of each region 1268 must: be less than or equal to the pname:arrayLayers specified in 1269 slink:VkImageCreateInfo when pname:dstImage was created 1270 * [[VUID-vkCmdCopyMemoryToImageIndirectNV-imageOffset-07672]] 1271 The pname:imageOffset and pname:imageExtent members of each region must: 1272 respect the image transfer granularity requirements of 1273 pname:commandBuffer's command pool's queue family, as described in 1274 slink:VkQueueFamilyProperties 1275ifdef::VK_EXT_fragment_density_map[] 1276 * [[VUID-vkCmdCopyMemoryToImageIndirectNV-dstImage-07673]] 1277 pname:dstImage must: not have been created with pname:flags containing 1278 ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT 1279endif::VK_EXT_fragment_density_map[] 1280 * [[VUID-vkCmdCopyMemoryToImageIndirectNV-commandBuffer-07674]] 1281 If the queue family used to create the slink:VkCommandPool which 1282 pname:commandBuffer was allocated from does not support 1283 ename:VK_QUEUE_GRAPHICS_BIT, for each region, the pname:aspectMask 1284 member of pname:pImageSubresources must: not be 1285 ename:VK_IMAGE_ASPECT_DEPTH_BIT or ename:VK_IMAGE_ASPECT_STENCIL_BIT 1286 * [[VUID-vkCmdCopyMemoryToImageIndirectNV-imageOffset-07675]] 1287 For each region in sname:copyBufferAddress, pname:imageOffset.y and 1288 [eq]#(pname:imageExtent.height {plus} pname:imageOffset.y)# must: both 1289 be greater than or equal to `0` and less than or equal to the height of 1290 the specified subresource 1291 * [[VUID-vkCmdCopyMemoryToImageIndirectNV-offset-07676]] 1292 pname:offset must: be 4 byte aligned 1293 * [[VUID-vkCmdCopyMemoryToImageIndirectNV-stride-07677]] 1294 pname:stride must: be a multiple of `4` and must: be greater than or 1295 equal to sizeof(sname:VkCopyMemoryToImageIndirectCommandNV) 1296**** 1297 1298include::{generated}/validity/protos/vkCmdCopyMemoryToImageIndirectNV.adoc[] 1299-- 1300 1301[open,refpage='VkCopyMemoryToImageIndirectCommandNV',desc='Structure specifying indirect buffer image copy operation',type='structs'] 1302-- 1303The sname:VkCopyMemoryToImageIndirectCommandNV is defined as: 1304 1305include::{generated}/api/structs/VkCopyMemoryToImageIndirectCommandNV.adoc[] 1306 1307 * pname:srcAddress is the starting address of the source device memory to 1308 copy from. 1309 * pname:bufferRowLength and pname:bufferImageHeight specify in texels a 1310 subregion of a larger two- or three-dimensional image in buffer memory, 1311 and control the addressing calculations. 1312 If either of these values is zero, that aspect of the buffer memory is 1313 considered to be tightly packed according to the pname:imageExtent. 1314 * pname:imageSubresource is a slink:VkImageSubresourceLayers used to 1315 specify the specific image subresources of the image used for the 1316 destination image data, which must: match the values specified in 1317 pname:pImageSubresources parameter of 1318 flink:vkCmdCopyMemoryToImageIndirectNV during command recording. 1319 * pname:imageOffset selects the initial pname:x, pname:y, pname:z offsets 1320 in texels of the sub-region of the destination image data. 1321 * pname:imageExtent is the size in texels of the destination image in 1322 pname:width, pname:height and pname:depth. 1323 1324.Valid Usage 1325**** 1326 * [[VUID-VkCopyMemoryToImageIndirectCommandNV-srcAddress-07678]] 1327 The pname:srcAddress must: be 4 byte aligned 1328 * [[VUID-VkCopyMemoryToImageIndirectCommandNV-bufferRowLength-07679]] 1329 pname:bufferRowLength must: be `0`, or greater than or equal to the 1330 pname:width member of pname:imageExtent 1331 * [[VUID-VkCopyMemoryToImageIndirectCommandNV-bufferImageHeight-07680]] 1332 pname:bufferImageHeight must: be `0`, or greater than or equal to the 1333 pname:height member of pname:imageExtent 1334 * [[VUID-VkCopyMemoryToImageIndirectCommandNV-imageOffset-07681]] 1335 pname:imageOffset must: specify a valid offset in the destination image 1336 * [[VUID-VkCopyMemoryToImageIndirectCommandNV-imageExtent-07682]] 1337 pname:imageExtent must: specify a valid region in the destination image 1338 and can be `0` 1339**** 1340 1341include::{generated}/validity/structs/VkCopyMemoryToImageIndirectCommandNV.adoc[] 1342-- 1343endif::VK_NV_copy_memory_indirect[] 1344 1345 1346[[copies-imagescaling]] 1347== Image Copies With Scaling 1348 1349[open,refpage='vkCmdBlitImage',desc='Copy regions of an image, potentially performing format conversion,',type='protos'] 1350-- 1351:refpage: vkCmdBlitImage 1352 1353To copy regions of a source image into a destination image, potentially 1354performing format conversion, arbitrary scaling, and filtering, call: 1355 1356include::{generated}/api/protos/vkCmdBlitImage.adoc[] 1357 1358 * pname:commandBuffer is the command buffer into which the command will be 1359 recorded. 1360 * pname:srcImage is the source image. 1361 * pname:srcImageLayout is the layout of the source image subresources for 1362 the blit. 1363 * pname:dstImage is the destination image. 1364 * pname:dstImageLayout is the layout of the destination image subresources 1365 for the blit. 1366 * pname:regionCount is the number of regions to blit. 1367 * pname:pRegions is a pointer to an array of slink:VkImageBlit structures 1368 specifying the regions to blit. 1369 * pname:filter is a elink:VkFilter specifying the filter to apply if the 1370 blits require scaling. 1371 1372fname:vkCmdBlitImage must: not be used for multisampled source or 1373destination images. 1374Use flink:vkCmdResolveImage for this purpose. 1375 1376As the sizes of the source and destination extents can: differ in any 1377dimension, texels in the source extent are scaled and filtered to the 1378destination extent. 1379Scaling occurs via the following operations: 1380 1381 * For each destination texel, the integer coordinate of that texel is 1382 converted to an unnormalized texture coordinate, using the effective 1383 inverse of the equations described in 1384 <<textures-unnormalized-to-integer, unnormalized to integer 1385 conversion>>: 1386 {empty}:: [eq]#u~base~ = i {plus} {onehalf}# 1387 {empty}:: [eq]#v~base~ = j {plus} {onehalf}# 1388 {empty}:: [eq]#w~base~ = k {plus} {onehalf}# 1389 * These base coordinates are then offset by the first destination offset: 1390 {empty}:: [eq]#u~offset~ = u~base~ - x~dst0~# 1391 {empty}:: [eq]#v~offset~ = v~base~ - y~dst0~# 1392 {empty}:: [eq]#w~offset~ = w~base~ - z~dst0~# 1393 {empty}:: [eq]#a~offset~ = a - pname:baseArrayCount~dst~# 1394 * The scale is determined from the source and destination regions, and 1395 applied to the offset coordinates: 1396 {empty}:: [eq]#scale~u~ = (x~src1~ - x~src0~) / (x~dst1~ - x~dst0~)# 1397 {empty}:: [eq]#scale~v~ = (y~src1~ - y~src0~) / (y~dst1~ - y~dst0~)# 1398 {empty}:: [eq]#scale~w~ = (z~src1~ - z~src0~) / (z~dst1~ - z~dst0~)# 1399 {empty}:: [eq]#u~scaled~ = u~offset~ {times} scale~u~# 1400 {empty}:: [eq]#v~scaled~ = v~offset~ {times} scale~v~# 1401 {empty}:: [eq]#w~scaled~ = w~offset~ {times} scale~w~# 1402 * Finally the source offset is added to the scaled coordinates, to 1403 determine the final unnormalized coordinates used to sample from 1404 pname:srcImage: 1405 {empty}:: [eq]#u = u~scaled~ {plus} x~src0~# 1406 {empty}:: [eq]#v = v~scaled~ {plus} y~src0~# 1407 {empty}:: [eq]#w = w~scaled~ {plus} z~src0~# 1408 {empty}:: [eq]#q = pname:mipLevel# 1409 {empty}:: [eq]#a = a~offset~ {plus} pname:baseArrayCount~src~# 1410 1411These coordinates are used to sample from the source image, as described in 1412<<textures, Image Operations chapter>>, with the filter mode equal to that 1413of pname:filter, a mipmap mode of ename:VK_SAMPLER_MIPMAP_MODE_NEAREST and 1414an address mode of ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE. 1415Implementations must: clamp at the edge of the source image, and may: 1416additionally clamp to the edge of the source region. 1417 1418[NOTE] 1419.Note 1420==== 1421Due to allowable rounding errors in the generation of the source texture 1422coordinates, it is not always possible to guarantee exactly which source 1423texels will be sampled for a given blit. 1424As rounding errors are implementation-dependent, the exact results of a 1425blitting operation are also implementation-dependent. 1426==== 1427 1428Blits are done layer by layer starting with the pname:baseArrayLayer member 1429of pname:srcSubresource for the source and pname:dstSubresource for the 1430destination. 1431pname:layerCount layers are blitted to the destination image. 1432 1433When blitting 3D textures, slices in the destination region bounded by 1434pname:dstOffsets[0].z and pname:dstOffsets[1].z are sampled from slices in 1435the source region bounded by pname:srcOffsets[0].z and 1436pname:srcOffsets[1].z. 1437If the pname:filter parameter is ename:VK_FILTER_LINEAR then the value 1438sampled from the source image is taken by doing linear filtering using the 1439interpolated *z* coordinate represented by *w* in the previous equations. 1440If the pname:filter parameter is ename:VK_FILTER_NEAREST then the value 1441sampled from the source image is taken from the single nearest slice, with 1442an implementation-dependent arithmetic rounding mode. 1443 1444The following filtering and conversion rules apply: 1445 1446 * Integer formats can: only be converted to other integer formats with the 1447 same signedness. 1448 * No format conversion is supported between depth/stencil images. 1449 The formats must: match. 1450 * Format conversions on unorm, snorm, scaled and packed float formats of 1451 the copied aspect of the image are performed by first converting the 1452 pixels to float values. 1453 * For sRGB source formats, nonlinear RGB values are converted to linear 1454 representation prior to filtering. 1455 * After filtering, the float values are first clamped and then cast to the 1456 destination image format. 1457 In case of sRGB destination format, linear RGB values are converted to 1458 nonlinear representation before writing the pixel to the image. 1459 1460Signed and unsigned integers are converted by first clamping to the 1461representable range of the destination format, then casting the value. 1462 1463.Valid Usage 1464**** 1465include::{chapters}/commonvalidity/blit_image_command_buffer_common.adoc[] 1466include::{chapters}/commonvalidity/blit_image_common.adoc[] 1467**** 1468 1469include::{generated}/validity/protos/vkCmdBlitImage.adoc[] 1470-- 1471 1472[open,refpage='VkImageBlit',desc='Structure specifying an image blit operation',type='structs'] 1473-- 1474:refpage: VkImageBlit 1475 1476The sname:VkImageBlit structure is defined as: 1477 1478include::{generated}/api/structs/VkImageBlit.adoc[] 1479 1480 * pname:srcSubresource is the subresource to blit from. 1481 * pname:srcOffsets is a pointer to an array of two slink:VkOffset3D 1482 structures specifying the bounds of the source region within 1483 pname:srcSubresource. 1484 * pname:dstSubresource is the subresource to blit into. 1485 * pname:dstOffsets is a pointer to an array of two slink:VkOffset3D 1486 structures specifying the bounds of the destination region within 1487 pname:dstSubresource. 1488 1489For each element of the pname:pRegions array, a blit operation is performed 1490for the specified source and destination regions. 1491 1492.Valid Usage 1493**** 1494include::{chapters}/commonvalidity/image_blit_common.adoc[] 1495**** 1496 1497include::{generated}/validity/structs/VkImageBlit.adoc[] 1498-- 1499 1500ifdef::VK_VERSION_1_3,VK_KHR_copy_commands2[] 1501A more extensible version of the blit image command is defined below. 1502 1503[open,refpage='vkCmdBlitImage2',desc='Copy regions of an image, potentially performing format conversion,',type='protos',alias='vkCmdBlitImage2KHR'] 1504-- 1505:refpage: vkCmdBlitImage2 1506 1507To copy regions of a source image into a destination image, potentially 1508performing format conversion, arbitrary scaling, and filtering, call: 1509 1510ifdef::VK_VERSION_1_3[] 1511include::{generated}/api/protos/vkCmdBlitImage2.adoc[] 1512endif::VK_VERSION_1_3[] 1513 1514ifdef::VK_VERSION_1_3+VK_KHR_copy_commands2[or the equivalent command] 1515 1516ifdef::VK_KHR_copy_commands2[] 1517include::{generated}/api/protos/vkCmdBlitImage2KHR.adoc[] 1518endif::VK_KHR_copy_commands2[] 1519 1520 * pname:commandBuffer is the command buffer into which the command will be 1521 recorded. 1522 * pname:pBlitImageInfo is a pointer to a slink:VkBlitImageInfo2 structure 1523 describing the blit parameters. 1524 1525This command is functionally identical to flink:vkCmdBlitImage, but includes 1526extensible sub-structures that include pname:sType and pname:pNext 1527parameters, allowing them to be more easily extended. 1528 1529.Valid Usage 1530**** 1531include::{chapters}/commonvalidity/blit_image_command_buffer_common.adoc[] 1532**** 1533 1534include::{generated}/validity/protos/vkCmdBlitImage2.adoc[] 1535-- 1536 1537[open,refpage='VkBlitImageInfo2',desc='Structure specifying parameters of blit image command',type='structs',alias='VkBlitImageInfo2KHR'] 1538-- 1539:refpage: VkBlitImageInfo2 1540 1541The sname:VkBlitImageInfo2 structure is defined as: 1542 1543include::{generated}/api/structs/VkBlitImageInfo2.adoc[] 1544 1545ifdef::VK_KHR_copy_commands2[] 1546or the equivalent 1547 1548include::{generated}/api/structs/VkBlitImageInfo2KHR.adoc[] 1549endif::VK_KHR_copy_commands2[] 1550 1551 * pname:sType is a elink:VkStructureType value identifying this structure. 1552 * pname:pNext is `NULL` or a pointer to a structure extending this 1553 structure. 1554 * pname:srcImage is the source image. 1555 * pname:srcImageLayout is the layout of the source image subresources for 1556 the blit. 1557 * pname:dstImage is the destination image. 1558 * pname:dstImageLayout is the layout of the destination image subresources 1559 for the blit. 1560 * pname:regionCount is the number of regions to blit. 1561 * pname:pRegions is a pointer to an array of slink:VkImageBlit2 structures 1562 specifying the regions to blit. 1563 * pname:filter is a elink:VkFilter specifying the filter to apply if the 1564 blits require scaling. 1565 1566.Valid Usage 1567**** 1568include::{chapters}/commonvalidity/blit_image_common.adoc[] 1569ifdef::VK_QCOM_rotated_copy_commands[] 1570 * [[VUID-VkBlitImageInfo2-pRegions-04561]] 1571 If any element of pname:pRegions contains 1572 slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then 1573 pname:srcImage and pname:dstImage must: not be block-compressed images 1574 * [[VUID-VkBlitImageInfo2KHR-pRegions-06207]] 1575 If any element of pname:pRegions contains 1576 slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then 1577 pname:srcImage must: be of type ename:VK_IMAGE_TYPE_2D 1578 * [[VUID-VkBlitImageInfo2KHR-pRegions-06208]] 1579 If any element of pname:pRegions contains 1580 slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then 1581 pname:srcImage must: not have a 1582 <<formats-requiring-sampler-ycbcr-conversion, multi-planar format>> 1583endif::VK_QCOM_rotated_copy_commands[] 1584ifdef::VK_QCOM_filter_cubic_weights[] 1585 * [[VUID-VkBlitImageInfo2-filter-09204]] 1586 If pname:filter is ename:VK_FILTER_CUBIC_EXT and if the 1587 <<features-filter-cubic-weight-selection,selectableCubicWeights>> 1588 feature is not enabled then the cubic weights must: be 1589 ename:VK_CUBIC_FILTER_WEIGHTS_CATMULL_ROM_QCOM 1590endif::VK_QCOM_filter_cubic_weights[] 1591**** 1592 1593include::{generated}/validity/structs/VkBlitImageInfo2.adoc[] 1594-- 1595 1596ifdef::VK_QCOM_filter_cubic_weights[] 1597 1598If pname:filter is ename:VK_FILTER_CUBIC_EXT and if the pname:pNext chain of 1599slink:VkBlitImageInfo2 includes a sname:VkBlitImageCubicWeightsInfoQCOM 1600structure, then that structure specifies cubic weights are used in the blit. 1601If that structure is not present, then cubic weights are considered to be 1602ename:VK_CUBIC_FILTER_WEIGHTS_CATMULL_ROM_QCOM. 1603 1604[open,refpage='VkBlitImageCubicWeightsInfoQCOM',desc='Structure specifying image blit cubic weight info',type='structs',alias='VkImageBlit2KHR'] 1605-- 1606:refpage: VkBlitImageCubicWeightsInfoQCOM 1607 1608The sname:VkBlitImageCubicWeightsInfoQCOM structure is defined as: 1609 1610include::{generated}/api/structs/VkBlitImageCubicWeightsInfoQCOM.adoc[] 1611 1612 * pname:sType is a elink:VkStructureType value identifying this structure. 1613 * pname:pNext is `NULL` or a pointer to a structure extending this 1614 structure. 1615 * pname:cubicWeights is a elink:VkCubicFilterWeightsQCOM value controlling 1616 cubic filter weights for the blit. 1617 1618include::{generated}/validity/structs/VkBlitImageCubicWeightsInfoQCOM.adoc[] 1619-- 1620 1621endif::VK_QCOM_filter_cubic_weights[] 1622 1623 1624[open,refpage='VkImageBlit2',desc='Structure specifying an image blit operation',type='structs',alias='VkImageBlit2KHR'] 1625-- 1626:refpage: VkImageBlit2 1627 1628The sname:VkImageBlit2 structure is defined as: 1629 1630include::{generated}/api/structs/VkImageBlit2.adoc[] 1631 1632ifdef::VK_KHR_copy_commands2[] 1633or the equivalent 1634 1635include::{generated}/api/structs/VkImageBlit2KHR.adoc[] 1636endif::VK_KHR_copy_commands2[] 1637 1638 * pname:sType is a elink:VkStructureType value identifying this structure. 1639 * pname:pNext is `NULL` or a pointer to a structure extending this 1640 structure. 1641 * pname:srcSubresource is the subresource to blit from. 1642 * pname:srcOffsets is a pointer to an array of two slink:VkOffset3D 1643 structures specifying the bounds of the source region within 1644 pname:srcSubresource. 1645 * pname:dstSubresource is the subresource to blit into. 1646 * pname:dstOffsets is a pointer to an array of two slink:VkOffset3D 1647 structures specifying the bounds of the destination region within 1648 pname:dstSubresource. 1649 1650For each element of the pname:pRegions array, a blit operation is performed 1651for the specified source and destination regions. 1652 1653.Valid Usage 1654**** 1655include::{chapters}/commonvalidity/image_blit_common.adoc[] 1656**** 1657 1658include::{generated}/validity/structs/VkImageBlit2.adoc[] 1659-- 1660 1661ifdef::VK_QCOM_rotated_copy_commands[] 1662For flink:vkCmdBlitImage2, each region copied can include a rotation. 1663To specify a rotated region, add slink:VkCopyCommandTransformInfoQCOM to the 1664pname:pNext chain of slink:VkImageBlit2. 1665For each region with a rotation specified, 1666<<copies-images-scaling-rotation,Image Blits with Scaling and Rotation>> 1667specifies how coordinates are rotated prior to sampling from the source 1668image. 1669When rotation is specified, the source and destination images must: each be 16702D images, have a 1x1x1 <<formats-compatibility-classes,texel block 1671extent>>, and only one plane. 1672endif::VK_QCOM_rotated_copy_commands[] 1673endif::VK_VERSION_1_3,VK_KHR_copy_commands2[] 1674 1675ifdef::VK_QCOM_rotated_copy_commands[] 1676include::{chapters}/VK_QCOM_rotated_copies/rotated_addressing_blits.adoc[] 1677endif::VK_QCOM_rotated_copy_commands[] 1678 1679 1680[[copies-resolve]] 1681== Resolving Multisample Images 1682 1683[open,refpage='vkCmdResolveImage',desc='Resolve regions of an image',type='protos'] 1684-- 1685:refpage: vkCmdResolveImage 1686 1687To resolve a multisample color image to a non-multisample color image, call: 1688 1689include::{generated}/api/protos/vkCmdResolveImage.adoc[] 1690 1691 * pname:commandBuffer is the command buffer into which the command will be 1692 recorded. 1693 * pname:srcImage is the source image. 1694 * pname:srcImageLayout is the layout of the source image subresources for 1695 the resolve. 1696 * pname:dstImage is the destination image. 1697 * pname:dstImageLayout is the layout of the destination image subresources 1698 for the resolve. 1699 * pname:regionCount is the number of regions to resolve. 1700 * pname:pRegions is a pointer to an array of slink:VkImageResolve 1701 structures specifying the regions to resolve. 1702 1703During the resolve the samples corresponding to each pixel location in the 1704source are converted to a single sample before being written to the 1705destination. 1706If the source formats are floating-point or normalized types, the sample 1707values for each pixel are resolved in an implementation-dependent manner. 1708If the source formats are integer types, a single sample's value is selected 1709for each pixel. 1710 1711pname:srcOffset and pname:dstOffset select the initial pname:x, pname:y, and 1712pname:z offsets in texels of the sub-regions of the source and destination 1713image data. 1714pname:extent is the size in texels of the source image to resolve in 1715pname:width, pname:height and pname:depth. 1716Each element of pname:pRegions must: be a region that is contained within 1717its corresponding image. 1718 1719Resolves are done layer by layer starting with pname:baseArrayLayer member 1720of pname:srcSubresource for the source and pname:dstSubresource for the 1721destination. 1722pname:layerCount layers are resolved to the destination image. 1723 1724.Valid Usage 1725**** 1726include::{chapters}/commonvalidity/resolve_image_command_buffer_common.adoc[] 1727include::{chapters}/commonvalidity/resolve_image_common.adoc[] 1728**** 1729 1730include::{generated}/validity/protos/vkCmdResolveImage.adoc[] 1731-- 1732 1733[open,refpage='VkImageResolve',desc='Structure specifying an image resolve operation',type='structs'] 1734-- 1735:refpage: VkImageResolve 1736 1737The sname:VkImageResolve structure is defined as: 1738 1739include::{generated}/api/structs/VkImageResolve.adoc[] 1740 1741 * pname:srcSubresource and pname:dstSubresource are 1742 slink:VkImageSubresourceLayers structures specifying the image 1743 subresources of the images used for the source and destination image 1744 data, respectively. 1745 Resolve of depth/stencil images is not supported. 1746 * pname:srcOffset and pname:dstOffset select the initial pname:x, pname:y, 1747 and pname:z offsets in texels of the sub-regions of the source and 1748 destination image data. 1749 * pname:extent is the size in texels of the source image to resolve in 1750 pname:width, pname:height and pname:depth. 1751 1752.Valid Usage 1753**** 1754include::{chapters}/commonvalidity/image_resolve_common.adoc[] 1755**** 1756 1757include::{generated}/validity/structs/VkImageResolve.adoc[] 1758-- 1759 1760ifdef::VK_VERSION_1_3,VK_KHR_copy_commands2[] 1761 1762A more extensible version of the resolve image command is defined below. 1763 1764[open,refpage='vkCmdResolveImage2',desc='Resolve regions of an image',type='protos',alias='vkCmdResolveImage2KHR'] 1765-- 1766:refpage: vkCmdResolveImage2 1767 1768To resolve a multisample image to a non-multisample image, call: 1769 1770ifdef::VK_VERSION_1_3[] 1771include::{generated}/api/protos/vkCmdResolveImage2.adoc[] 1772endif::VK_VERSION_1_3[] 1773 1774ifdef::VK_VERSION_1_3+VK_KHR_copy_commands2[or the equivalent command] 1775 1776ifdef::VK_KHR_copy_commands2[] 1777include::{generated}/api/protos/vkCmdResolveImage2KHR.adoc[] 1778endif::VK_KHR_copy_commands2[] 1779 1780 * pname:commandBuffer is the command buffer into which the command will be 1781 recorded. 1782 * pname:pResolveImageInfo is a pointer to a slink:VkResolveImageInfo2 1783 structure describing the resolve parameters. 1784 1785This command is functionally identical to flink:vkCmdResolveImage, but 1786includes extensible sub-structures that include pname:sType and pname:pNext 1787parameters, allowing them to be more easily extended. 1788 1789 1790.Valid Usage 1791**** 1792include::{chapters}/commonvalidity/resolve_image_command_buffer_common.adoc[] 1793**** 1794 1795include::{generated}/validity/protos/vkCmdResolveImage2.adoc[] 1796-- 1797 1798[open,refpage='VkResolveImageInfo2',desc='Structure specifying parameters of resolve image command',type='structs',alias='VkResolveImageInfo2KHR'] 1799-- 1800:refpage: VkResolveImageInfo2 1801 1802The sname:VkResolveImageInfo2 structure is defined as: 1803 1804include::{generated}/api/structs/VkResolveImageInfo2.adoc[] 1805 1806ifdef::VK_KHR_copy_commands2[] 1807or the equivalent 1808 1809include::{generated}/api/structs/VkResolveImageInfo2KHR.adoc[] 1810endif::VK_KHR_copy_commands2[] 1811 1812 * pname:sType is a elink:VkStructureType value identifying this structure. 1813 * pname:pNext is `NULL` or a pointer to a structure extending this 1814 structure. 1815 * pname:srcImage is the source image. 1816 * pname:srcImageLayout is the layout of the source image subresources for 1817 the resolve. 1818 * pname:dstImage is the destination image. 1819 * pname:dstImageLayout is the layout of the destination image subresources 1820 for the resolve. 1821 * pname:regionCount is the number of regions to resolve. 1822 * pname:pRegions is a pointer to an array of slink:VkImageResolve2 1823 structures specifying the regions to resolve. 1824 1825.Valid Usage 1826**** 1827include::{chapters}/commonvalidity/resolve_image_common.adoc[] 1828**** 1829 1830include::{generated}/validity/structs/VkResolveImageInfo2.adoc[] 1831-- 1832 1833[open,refpage='VkImageResolve2',desc='Structure specifying an image resolve operation',type='structs',alias='VkImageResolve2KHR'] 1834-- 1835:refpage: VkImageResolve2 1836 1837The sname:VkImageResolve2 structure is defined as: 1838 1839include::{generated}/api/structs/VkImageResolve2.adoc[] 1840 1841ifdef::VK_KHR_copy_commands2[] 1842or the equivalent 1843 1844include::{generated}/api/structs/VkImageResolve2KHR.adoc[] 1845endif::VK_KHR_copy_commands2[] 1846 1847 * pname:sType is a elink:VkStructureType value identifying this structure. 1848 * pname:pNext is `NULL` or a pointer to a structure extending this 1849 structure. 1850 * pname:srcSubresource and pname:dstSubresource are 1851 slink:VkImageSubresourceLayers structures specifying the image 1852 subresources of the images used for the source and destination image 1853 data, respectively. 1854 Resolve of depth/stencil images is not supported. 1855 * pname:srcOffset and pname:dstOffset select the initial pname:x, pname:y, 1856 and pname:z offsets in texels of the sub-regions of the source and 1857 destination image data. 1858 * pname:extent is the size in texels of the source image to resolve in 1859 pname:width, pname:height and pname:depth. 1860 1861.Valid Usage 1862**** 1863include::{chapters}/commonvalidity/image_resolve_common.adoc[] 1864**** 1865 1866include::{generated}/validity/structs/VkImageResolve2.adoc[] 1867-- 1868endif::VK_VERSION_1_3,VK_KHR_copy_commands2[] 1869 1870ifdef::VK_KHR_object_refresh[] 1871include::{chapters}/VK_KHR_object_refresh/copies.adoc[] 1872endif::VK_KHR_object_refresh[] 1873 1874ifdef::VK_AMD_buffer_marker[] 1875include::{chapters}/VK_AMD_buffer_marker/copies.adoc[] 1876endif::VK_AMD_buffer_marker[] 1877