1// Copyright 2021-2023 The Khronos Group, Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5The following commands can be used to copy between host memory and images. 6 7[open,refpage='vkCopyMemoryToImageEXT',desc='Copy data from host memory into an image',type='protos'] 8-- 9:refpage: vkCopyMemoryToImageEXT 10 11To copy data from host memory to an image object, call: 12 13include::{generated}/api/protos/vkCopyMemoryToImageEXT.adoc[] 14 15 * pname:device is the device which owns 16 pname:pCopyMemoryToImageInfo->dstImage. 17 * pname:pCopyMemoryToImageInfo is a pointer to a 18 slink:VkCopyMemoryToImageInfoEXT structure describing the copy 19 parameters. 20 21This command is functionally similar to flink:vkCmdCopyBufferToImage2, 22except it is executed on the host and reads from host memory instead of a 23buffer. 24 25.Valid Usage 26**** 27 * [[VUID-vkCopyMemoryToImageEXT-hostImageCopy-09058]] 28 The <<features-hostImageCopy, pname:hostImageCopy>> feature must: be 29 enabled 30**** 31 32include::{generated}/validity/protos/vkCopyMemoryToImageEXT.adoc[] 33-- 34 35[open,refpage='VkCopyMemoryToImageInfoEXT',desc='Structure specifying parameters of host memory to image copy command',type='structs'] 36-- 37:refpage: VkCopyMemoryToImageInfoEXT 38:imageparam: dstImage 39:imagesubresource: imageSubresource 40:imageoffset: imageOffset 41:imageextent: imageExtent 42:bufferrowlength: memoryRowLength 43:bufferimageheight: memoryImageHeight 44 45The sname:VkCopyMemoryToImageInfoEXT structure is defined as: 46 47include::{generated}/api/structs/VkCopyMemoryToImageInfoEXT.adoc[] 48 49 * pname:sType is a elink:VkStructureType value identifying this structure. 50 * pname:pNext is `NULL` or a pointer to a structure extending this 51 structure. 52 * pname:flags is a bitmask of elink:VkHostImageCopyFlagBitsEXT values 53 describing additional copy parameters. 54 * pname:dstImage is the destination image. 55 * pname:dstImageLayout is the layout of the destination image subresources 56 for the copy. 57 * pname:regionCount is the number of regions to copy. 58 * pname:pRegions is a pointer to an array of slink:VkMemoryToImageCopyEXT 59 structures specifying the regions to copy. 60 61fname:vkCopyMemoryToImageEXT does not check whether the device memory 62associated with pname:dstImage is currently in use before performing the 63copy. 64The application must: guarantee that any previously submitted command that 65reads from or writes to the copy regions has completed before the host 66performs the copy. 67 68Copy regions for the image must: be aligned to a multiple of the texel block 69extent in each dimension, except at the edges of the image, where region 70extents must: match the edge of the image. 71 72.Valid Usage 73**** 74include::{chapters}/commonvalidity/copy_memoryimage_to_imagememory_common.adoc[] 75include::{chapters}/commonvalidity/copy_anyimage_to_imageany_common.adoc[] 76include::{chapters}/commonvalidity/copy_anyimage_to_imageany_no_rotation_common.adoc[] 77include::{chapters}/commonvalidity/copy_anyimage_to_imageany_single_sampled_common.adoc[] 78include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_common.adoc[] 79include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_not_both_image_common.adoc[] 80 * [[VUID-VkCopyMemoryToImageInfoEXT-dstImageLayout-09059]] 81 pname:dstImageLayout must: specify the current layout of the image 82 subresources of pname:dstImage specified in pname:pRegions 83 * [[VUID-VkCopyMemoryToImageInfoEXT-dstImageLayout-09060]] 84 pname:dstImageLayout must: be one of the image layouts returned in 85 slink:VkPhysicalDeviceHostImageCopyPropertiesEXT::pname:pCopyDstLayouts 86 * [[VUID-VkCopyMemoryToImageInfoEXT-flags-09393]] 87 If pname:flags includes ename:VK_HOST_IMAGE_COPY_MEMCPY_EXT, for each 88 region in pname:pRegions, pname:memoryRowLength and 89 pname:memoryImageHeight must: both be 0 90**** 91 92include::{generated}/validity/structs/VkCopyMemoryToImageInfoEXT.adoc[] 93-- 94 95[open,refpage='VkMemoryToImageCopyEXT',desc='Structure specifying a host memory to image copy operation',type='structs'] 96-- 97:refpage: VkMemoryToImageCopyEXT 98:bufferrowlength: memoryRowLength 99:bufferimageheight: memoryImageHeight 100 101Each element of slink:VkCopyMemoryToImageInfoEXT::pname:pRegions is a 102structure defined as: 103 104include::{generated}/api/structs/VkMemoryToImageCopyEXT.adoc[] 105 106 * pname:sType is a elink:VkStructureType value identifying this structure. 107 * pname:pNext is `NULL` or a pointer to a structure extending this 108 structure. 109 * pname:pHostPointer is the host memory address which is the source of the 110 copy. 111 * pname:memoryRowLength and pname:memoryImageHeight specify in texels a 112 subregion of a larger two- or three-dimensional image in host memory, 113 and control the addressing calculations. 114 If either of these values is zero, that aspect of the host memory is 115 considered to be tightly packed according to the pname:imageExtent. 116 * pname:imageSubresource is a slink:VkImageSubresourceLayers used to 117 specify the specific image subresources of the image used for the source 118 or destination image data. 119 * pname:imageOffset selects the initial pname:x, pname:y, pname:z offsets 120 in texels of the sub-region of the destination image data. 121 * pname:imageExtent is the size in texels of the image to copy in 122 pname:width, pname:height and pname:depth. 123 124This structure is functionally similar to slink:VkBufferImageCopy2, except 125it defines host memory as the source of copy instead of a buffer. 126In particular, the same data packing rules and restrictions as that 127structure apply here as well. 128 129.Valid Usage 130**** 131 * [[VUID-VkMemoryToImageCopyEXT-pHostPointer-09061]] 132 pname:pHostPointer must: point to memory that is large enough to contain 133 all memory locations that are accessed according to 134 <<copies-buffers-images-addressing,Buffer and Image Addressing>>, for 135 each element of pname:pRegions 136 * [[VUID-VkMemoryToImageCopyEXT-pRegions-09062]] 137 The union of all source regions, and the union of all destination 138 regions, specified by the elements of pname:pRegions, must: not overlap 139 in memory 140include::{chapters}/commonvalidity/buffer_or_memory_image_copy_common.adoc[] 141**** 142 143include::{generated}/validity/structs/VkMemoryToImageCopyEXT.adoc[] 144-- 145 146[open,refpage='vkCopyImageToMemoryEXT',desc='Copy image data into host memory',type='protos'] 147-- 148:refpage: vkCopyImageToMemoryEXT 149 150To copy data from an image object to host memory, call: 151 152include::{generated}/api/protos/vkCopyImageToMemoryEXT.adoc[] 153 154 * pname:device is the device which owns 155 pname:pCopyImageToMemoryInfo->srcImage. 156 * pname:pCopyImageToMemoryInfo is a pointer to a 157 slink:VkCopyImageToMemoryInfoEXT structure describing the copy 158 parameters. 159 160This command is functionally similar to flink:vkCmdCopyImageToBuffer2, 161except it is executed on the host and writes to host memory instead of a 162buffer. 163 164.Valid Usage 165**** 166 * [[VUID-vkCopyImageToMemoryEXT-hostImageCopy-09063]] 167 The <<features-hostImageCopy, pname:hostImageCopy>> feature must: be 168 enabled 169**** 170 171include::{generated}/validity/protos/vkCopyImageToMemoryEXT.adoc[] 172-- 173 174[open,refpage='VkCopyImageToMemoryInfoEXT',desc='Structure specifying parameters of an image to host memory copy command',type='structs'] 175-- 176:refpage: VkCopyImageToMemoryInfoEXT 177:imageparam: srcImage 178:imagesubresource: imageSubresource 179:imageoffset: imageOffset 180:imageextent: imageExtent 181:bufferrowlength: memoryRowLength 182:bufferimageheight: memoryImageHeight 183 184The sname:VkCopyImageToMemoryInfoEXT structure is defined as: 185 186include::{generated}/api/structs/VkCopyImageToMemoryInfoEXT.adoc[] 187 188 * pname:sType is a elink:VkStructureType value identifying this structure. 189 * pname:pNext is `NULL` or a pointer to a structure extending this 190 structure. 191 * pname:flags is a bitmask of elink:VkHostImageCopyFlagBitsEXT values 192 describing additional copy parameters. 193 * pname:srcImage is the source image. 194 * pname:srcImageLayout is the layout of the source image subresources for 195 the copy. 196 * pname:regionCount is the number of regions to copy. 197 * pname:pRegions is a pointer to an array of slink:VkImageToMemoryCopyEXT 198 structures specifying the regions to copy. 199 200fname:vkCopyImageToMemoryEXT does not check whether the device memory 201associated with pname:srcImage is currently in use before performing the 202copy. 203The application must: guarantee that any previously submitted command that 204writes to the copy regions has completed before the host performs the copy. 205 206Copy regions for the image must: be aligned to a multiple of the texel block 207extent in each dimension, except at the edges of the image, where region 208extents must: match the edge of the image. 209 210.Valid Usage 211**** 212include::{chapters}/commonvalidity/copy_memoryimage_to_imagememory_common.adoc[] 213include::{chapters}/commonvalidity/copy_anyimage_to_imageany_common.adoc[] 214include::{chapters}/commonvalidity/copy_anyimage_to_imageany_no_rotation_common.adoc[] 215include::{chapters}/commonvalidity/copy_anyimage_to_imageany_single_sampled_common.adoc[] 216include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_common.adoc[] 217include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_not_both_image_common.adoc[] 218 * [[VUID-VkCopyImageToMemoryInfoEXT-srcImageLayout-09064]] 219 pname:srcImageLayout must: specify the current layout of the image 220 subresources of pname:srcImage specified in pname:pRegions 221 * [[VUID-VkCopyImageToMemoryInfoEXT-srcImageLayout-09065]] 222 pname:srcImageLayout must: be one of the image layouts returned in 223 slink:VkPhysicalDeviceHostImageCopyPropertiesEXT::pname:pCopySrcLayouts 224 * [[VUID-VkCopyImageToMemoryInfoEXT-flags-09394]] 225 If pname:flags includes ename:VK_HOST_IMAGE_COPY_MEMCPY_EXT, for each 226 region in pname:pRegions, pname:memoryRowLength and 227 pname:memoryImageHeight must: both be 0 228**** 229 230include::{generated}/validity/structs/VkCopyImageToMemoryInfoEXT.adoc[] 231-- 232 233[open,refpage='VkImageToMemoryCopyEXT',desc='Structure specifying an image to host memory copy operation',type='structs'] 234-- 235:refpage: VkImageToMemoryCopyEXT 236:bufferrowlength: memoryRowLength 237:bufferimageheight: memoryImageHeight 238 239Each element of slink:VkCopyImageToMemoryInfoEXT::pname:pRegions is a 240structure defined as: 241 242include::{generated}/api/structs/VkImageToMemoryCopyEXT.adoc[] 243 244 * pname:sType is a elink:VkStructureType value identifying this structure. 245 * pname:pNext is `NULL` or a pointer to a structure extending this 246 structure. 247 * pname:pHostPointer is the host memory address which is the destination 248 of the copy. 249 * pname:memoryRowLength and pname:memoryImageHeight specify in texels a 250 subregion of a larger two- or three-dimensional image in host memory, 251 and control the addressing calculations. 252 If either of these values is zero, that aspect of the host memory is 253 considered to be tightly packed according to the pname:imageExtent. 254 * pname:imageSubresource is a slink:VkImageSubresourceLayers used to 255 specify the specific image subresources of the image used for the source 256 or destination image data. 257 * pname:imageOffset selects the initial pname:x, pname:y, pname:z offsets 258 in texels of the sub-region of the source image data. 259 * pname:imageExtent is the size in texels of the image to copy in 260 pname:width, pname:height and pname:depth. 261 262This structure is functionally similar to slink:VkBufferImageCopy2, except 263it defines host memory as the target of copy instead of a buffer. 264In particular, the same data packing rules and restrictions as that 265structure apply here as well. 266 267.Valid Usage 268**** 269 * [[VUID-VkImageToMemoryCopyEXT-pHostPointer-09066]] 270 pname:pHostPointer must: point to memory that is large enough to contain 271 all memory locations that are accessed according to 272 <<copies-buffers-images-addressing,Buffer and Image Addressing>>, for 273 each element of pname:pRegions 274 * [[VUID-VkImageToMemoryCopyEXT-pRegions-09067]] 275 The union of all source regions, and the union of all destination 276 regions, specified by the elements of pname:pRegions, must: not overlap 277 in memory 278include::{chapters}/commonvalidity/buffer_or_memory_image_copy_common.adoc[] 279**** 280 281include::{generated}/validity/structs/VkImageToMemoryCopyEXT.adoc[] 282-- 283 284[open,refpage='VkHostImageCopyFlagBitsEXT',desc='Bitmask specifying additional copy parameters',type='enums'] 285-- 286Bits which can: be set in slink:VkCopyMemoryToImageInfoEXT::pname:flags, 287slink:VkCopyImageToMemoryInfoEXT::pname:flags, and 288slink:VkCopyImageToImageInfoEXT::pname:flags, specifying additional copy 289parameters are: 290 291include::{generated}/api/enums/VkHostImageCopyFlagBitsEXT.adoc[] 292 293 * ename:VK_HOST_IMAGE_COPY_MEMCPY_EXT specifies that no memory layout 294 swizzling is to be applied during data copy. 295 For copies between memory and images, this flag indicates that image 296 data in host memory is swizzled in exactly the same way as the image 297 data on the device. 298 Using this flag indicates that the implementations may: use a simple 299 memory copy to transfer the data between the host memory and the device 300 memory. 301 The format of the swizzled data in host memory is platform dependent and 302 is not defined in this specification. 303-- 304 305[open,refpage='VkHostImageCopyFlagsEXT',desc='Bitmask of VkHostImageCopyFlagBitsEXT',type='flags'] 306-- 307include::{generated}/api/flags/VkHostImageCopyFlagsEXT.adoc[] 308 309tname:VkHostImageCopyFlagsEXT is a bitmask type for setting a mask of zero 310or more elink:VkHostImageCopyFlagBitsEXT. 311-- 312[open,refpage='vkCopyImageToImageEXT',desc='Copy image data using the host',type='protos'] 313-- 314:refpage: vkCopyImageToImageEXT 315 316To copy data from an image object to another image object using the host, 317call: 318 319include::{generated}/api/protos/vkCopyImageToImageEXT.adoc[] 320 321 * pname:device is the device which owns 322 pname:pCopyImageToMemoryInfo->srcImage. 323 * pname:pCopyImageToImageInfo is a pointer to a 324 slink:VkCopyImageToImageInfoEXT structure describing the copy 325 parameters. 326 327This command is functionally similar to flink:vkCmdCopyImage2, except it is 328executed on the host. 329 330.Valid Usage 331**** 332 * [[VUID-vkCopyImageToImageEXT-hostImageCopy-09068]] 333 The <<features-hostImageCopy, pname:hostImageCopy>> feature must: be 334 enabled 335**** 336 337include::{generated}/validity/protos/vkCopyImageToImageEXT.adoc[] 338-- 339 340[open,refpage='VkCopyImageToImageInfoEXT',desc='Structure specifying parameters of an image to image host copy command',type='structs'] 341-- 342:refpage: VkCopyImageToImageInfoEXT 343 344The sname:VkCopyImageToImageInfoEXT structure is defined as: 345 346include::{generated}/api/structs/VkCopyImageToImageInfoEXT.adoc[] 347 348 * pname:sType is a elink:VkStructureType value identifying this structure. 349 * pname:pNext is `NULL` or a pointer to a structure extending this 350 structure. 351 * pname:flags is a bitmask of elink:VkHostImageCopyFlagBitsEXT values 352 describing additional copy parameters. 353 * pname:srcImage is the source image. 354 * pname:srcImageLayout is the layout of the source image subresources for 355 the copy. 356 * pname:dstImage is the destination image. 357 * pname:dstImageLayout is the layout of the destination image subresources 358 for the copy. 359 * pname:regionCount is the number of regions to copy. 360 * pname:pRegions is a pointer to an array of slink:VkImageCopy2 structures 361 specifying the regions to copy. 362 363fname:vkCopyImageToImageEXT does not check whether the device memory 364associated with pname:srcImage or pname:dstImage is currently in use before 365performing the copy. 366The application must: guarantee that any previously submitted command that 367writes to the copy regions has completed before the host performs the copy. 368 369.Valid Usage 370**** 371 * [[VUID-VkCopyImageToImageInfoEXT-srcImage-09069]] 372 pname:srcImage and pname:dstImage must: have been created with identical 373 image creation parameters 374 375:imageparam: srcImage 376:imagesubresource: srcSubresource 377:imageoffset: srcOffset 378:imageextent: extent 379include::{chapters}/commonvalidity/copy_memoryimage_to_imagememory_common.adoc[] 380include::{chapters}/commonvalidity/copy_anyimage_to_imageany_common.adoc[] 381include::{chapters}/commonvalidity/copy_anyimage_to_imageany_no_rotation_common.adoc[] 382include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_common.adoc[] 383 384:imageparam: dstImage 385:imagesubresource: dstSubresource 386:imageoffset: dstOffset 387:imageextent: extent 388include::{chapters}/commonvalidity/copy_memoryimage_to_imagememory_common.adoc[] 389include::{chapters}/commonvalidity/copy_anyimage_to_imageany_common.adoc[] 390include::{chapters}/commonvalidity/copy_anyimage_to_imageany_no_rotation_common.adoc[] 391include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_common.adoc[] 392 * [[VUID-VkCopyImageToImageInfoEXT-srcImageLayout-09070]] 393 pname:srcImageLayout must: specify the current layout of the image 394 subresources of pname:srcImage specified in pname:pRegions 395 * [[VUID-VkCopyImageToImageInfoEXT-dstImageLayout-09071]] 396 pname:dstImageLayout must: specify the current layout of the image 397 subresources of pname:dstImage specified in pname:pRegions 398 * [[VUID-VkCopyImageToImageInfoEXT-srcImageLayout-09072]] 399 pname:srcImageLayout must: be one of the image layouts returned in 400 slink:VkPhysicalDeviceHostImageCopyPropertiesEXT::pname:pCopySrcLayouts 401 * [[VUID-VkCopyImageToImageInfoEXT-dstImageLayout-09073]] 402 pname:dstImageLayout must: be one of the image layouts returned in 403 slink:VkPhysicalDeviceHostImageCopyPropertiesEXT::pname:pCopyDstLayouts 404**** 405 406include::{generated}/validity/structs/VkCopyImageToImageInfoEXT.adoc[] 407-- 408