1// Copyright (c) 2015-2018 Khronos Group. This work is licensed under a 2// Creative Commons Attribution 4.0 International License; see 3// http://creativecommons.org/licenses/by/4.0/ 4 5[[clears]] 6= Clear Commands 7 8 9[[clears-outside]] 10== Clearing Images Outside A Render Pass Instance 11 12Color and depth/stencil images can: be cleared outside a render pass 13instance using flink:vkCmdClearColorImage or 14flink:vkCmdClearDepthStencilImage, respectively. 15These commands are only allowed outside of a render pass instance. 16 17[open,refpage='vkCmdClearColorImage',desc='Clear regions of a color image',type='protos'] 18-- 19 20To clear one or more subranges of a color image, call: 21 22include::../api/protos/vkCmdClearColorImage.txt[] 23 24 * pname:commandBuffer is the command buffer into which the command will be 25 recorded. 26 * pname:image is the image to be cleared. 27 * pname:imageLayout specifies the current layout of the image subresource 28 ranges to be cleared, and must: be 29ifdef::VK_KHR_shared_presentable_image[] 30 ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, 31endif::VK_KHR_shared_presentable_image[] 32 ename:VK_IMAGE_LAYOUT_GENERAL or 33 ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL. 34 * pname:pColor is a pointer to a slink:VkClearColorValue structure that 35 contains the values the image subresource ranges will be cleared to (see 36 <<clears-values>> below). 37 * pname:rangeCount is the number of image subresource range structures in 38 pname:pRanges. 39 * pname:pRanges points to an array of slink:VkImageSubresourceRange 40 structures that describe a range of mipmap levels, array layers, and 41 aspects to be cleared, as described in <<resources-image-views,Image 42 Views>>. 43 The pname:aspectMask of all image subresource ranges must: only include 44 ename:VK_IMAGE_ASPECT_COLOR_BIT. 45 46Each specified range in pname:pRanges is cleared to the value specified by 47pname:pColor. 48 49.Valid Usage 50**** 51ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 52 * [[VUID-vkCmdClearColorImage-image-01993]] 53 The <<resources-image-format-features,format features>> of pname:image 54 must: contain ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT. 55endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 56 * [[VUID-vkCmdClearColorImage-image-00002]] 57 pname:image must: have been created with 58 ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag 59ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 60 * [[VUID-vkCmdClearColorImage-image-01545]] 61 pname:image must: not use a format listed in 62 <<features-formats-requiring-sampler-ycbcr-conversion>> 63endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 64 * [[VUID-vkCmdClearColorImage-image-00003]] 65 If pname:image is non-sparse then it must: be bound completely and 66 contiguously to a single sname:VkDeviceMemory object 67 * [[VUID-vkCmdClearColorImage-imageLayout-00004]] 68 pname:imageLayout must: specify the layout of the image subresource 69 ranges of pname:image specified in pname:pRanges at the time this 70 command is executed on a sname:VkDevice 71ifndef::VK_KHR_shared_presentable_image[] 72 * [[VUID-vkCmdClearColorImage-imageLayout-00005]] 73 pname:imageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or 74 ename:VK_IMAGE_LAYOUT_GENERAL 75endif::VK_KHR_shared_presentable_image[] 76ifdef::VK_KHR_shared_presentable_image[] 77 * [[VUID-vkCmdClearColorImage-imageLayout-01394]] 78 pname:imageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, 79 ename:VK_IMAGE_LAYOUT_GENERAL, or 80 ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR 81endif::VK_KHR_shared_presentable_image[] 82 * [[VUID-vkCmdClearColorImage-baseMipLevel-01470]] 83 The slink:VkImageSubresourceRange::pname:baseMipLevel members of the 84 elements of the pname:pRanges array must: each be less than the 85 pname:mipLevels specified in slink:VkImageCreateInfo when pname:image 86 was created 87 * [[VUID-vkCmdClearColorImage-pRanges-01692]] 88 For each slink:VkImageSubresourceRange element of pname:pRanges, if the 89 pname:levelCount member is not ename:VK_REMAINING_MIP_LEVELS, then 90 [eq]#pname:baseMipLevel {plus} pname:levelCount# must: be less than the 91 pname:mipLevels specified in slink:VkImageCreateInfo when pname:image 92 was created 93 * [[VUID-vkCmdClearColorImage-baseArrayLayer-01472]] 94 The slink:VkImageSubresourceRange::pname:baseArrayLayer members of the 95 elements of the pname:pRanges array must: each be less than the 96 pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image 97 was created 98 * [[VUID-vkCmdClearColorImage-pRanges-01693]] 99 For each slink:VkImageSubresourceRange element of pname:pRanges, if the 100 pname:layerCount member is not ename:VK_REMAINING_ARRAY_LAYERS, then 101 [eq]#pname:baseArrayLayer {plus} pname:layerCount# must: be less than 102 the pname:arrayLayers specified in slink:VkImageCreateInfo when 103 pname:image was created 104 * [[VUID-vkCmdClearColorImage-image-00007]] 105 pname:image must: not have a compressed or depth/stencil format 106ifdef::VK_VERSION_1_1[] 107 * [[VUID-vkCmdClearColorImage-commandBuffer-01805]] 108 If pname:commandBuffer is an unprotected command buffer, then 109 pname:image must: not be a protected image 110 * [[VUID-vkCmdClearColorImage-commandBuffer-01806]] 111 If pname:commandBuffer is a protected command buffer, then pname:image 112 must: not be an unprotected image 113endif::VK_VERSION_1_1[] 114**** 115 116include::../validity/protos/vkCmdClearColorImage.txt[] 117-- 118 119[open,refpage='vkCmdClearDepthStencilImage',desc='Fill regions of a combined depth/stencil image',type='protos'] 120-- 121 122To clear one or more subranges of a depth/stencil image, call: 123 124include::../api/protos/vkCmdClearDepthStencilImage.txt[] 125 126 * pname:commandBuffer is the command buffer into which the command will be 127 recorded. 128 * pname:image is the image to be cleared. 129 * pname:imageLayout specifies the current layout of the image subresource 130 ranges to be cleared, and must: be ename:VK_IMAGE_LAYOUT_GENERAL or 131 ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL. 132 * pname:pDepthStencil is a pointer to a slink:VkClearDepthStencilValue 133 structure that contains the values the depth and stencil image 134 subresource ranges will be cleared to (see <<clears-values>> below). 135 * pname:rangeCount is the number of image subresource range structures in 136 pname:pRanges. 137 * pname:pRanges points to an array of slink:VkImageSubresourceRange 138 structures that describe a range of mipmap levels, array layers, and 139 aspects to be cleared, as described in <<resources-image-views,Image 140 Views>>. 141 The pname:aspectMask of each image subresource range in pname:pRanges 142 can: include ename:VK_IMAGE_ASPECT_DEPTH_BIT if the image format has a 143 depth component, and ename:VK_IMAGE_ASPECT_STENCIL_BIT if the image 144 format has a stencil component. 145 146.Valid Usage 147**** 148ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 149 * [[VUID-vkCmdClearDepthStencilImage-image-01994]] 150 The <<resources-image-format-features,format features>> of pname:image 151 must: contain ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT. 152endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 153 * [[VUID-vkCmdClearDepthStencilImage-image-00009]] 154 pname:image must: have been created with 155 ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag 156 * [[VUID-vkCmdClearDepthStencilImage-image-00010]] 157 If pname:image is non-sparse then it must: be bound completely and 158 contiguously to a single sname:VkDeviceMemory object 159 * [[VUID-vkCmdClearDepthStencilImage-imageLayout-00011]] 160 pname:imageLayout must: specify the layout of the image subresource 161 ranges of pname:image specified in pname:pRanges at the time this 162 command is executed on a sname:VkDevice 163 * [[VUID-vkCmdClearDepthStencilImage-imageLayout-00012]] 164 pname:imageLayout must: be either of 165 ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or 166 ename:VK_IMAGE_LAYOUT_GENERAL 167 * [[VUID-vkCmdClearDepthStencilImage-baseMipLevel-01474]] 168 The slink:VkImageSubresourceRange::pname:baseMipLevel members of the 169 elements of the pname:pRanges array must: each be less than the 170 pname:mipLevels specified in slink:VkImageCreateInfo when pname:image 171 was created 172 * [[VUID-vkCmdClearDepthStencilImage-pRanges-01694]] 173 For each slink:VkImageSubresourceRange element of pname:pRanges, if the 174 pname:levelCount member is not ename:VK_REMAINING_MIP_LEVELS, then 175 [eq]#pname:baseMipLevel {plus} pname:levelCount# must: be less than the 176 pname:mipLevels specified in slink:VkImageCreateInfo when pname:image 177 was created 178 * [[VUID-vkCmdClearDepthStencilImage-baseArrayLayer-01476]] 179 The slink:VkImageSubresourceRange::pname:baseArrayLayer members of the 180 elements of the pname:pRanges array must: each be less than the 181 pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image 182 was created 183 * [[VUID-vkCmdClearDepthStencilImage-pRanges-01695]] 184 For each slink:VkImageSubresourceRange element of pname:pRanges, if the 185 pname:layerCount member is not ename:VK_REMAINING_ARRAY_LAYERS, then 186 [eq]#pname:baseArrayLayer {plus} pname:layerCount# must: be less than 187 the pname:arrayLayers specified in slink:VkImageCreateInfo when 188 pname:image was created 189 * [[VUID-vkCmdClearDepthStencilImage-image-00014]] 190 pname:image must: have a depth/stencil format 191ifdef::VK_VERSION_1_1[] 192 * [[VUID-vkCmdClearDepthStencilImage-commandBuffer-01807]] 193 If pname:commandBuffer is an unprotected command buffer, then 194 pname:image must: not be a protected image 195 * [[VUID-vkCmdClearDepthStencilImage-commandBuffer-01808]] 196 If pname:commandBuffer is a protected command buffer, then pname:image 197 must: not be an unprotected image 198endif::VK_VERSION_1_1[] 199 200**** 201 202include::../validity/protos/vkCmdClearDepthStencilImage.txt[] 203-- 204 205Clears outside render pass instances are treated as transfer operations for 206the purposes of memory barriers. 207 208 209[[clears-inside]] 210== Clearing Images Inside A Render Pass Instance 211 212[open,refpage='vkCmdClearAttachments',desc='Clear regions within bound framebuffer attachments',type='protos'] 213-- 214 215To clear one or more regions of color and depth/stencil attachments inside a 216render pass instance, call: 217 218include::../api/protos/vkCmdClearAttachments.txt[] 219 220 * pname:commandBuffer is the command buffer into which the command will be 221 recorded. 222 * pname:attachmentCount is the number of entries in the pname:pAttachments 223 array. 224 * pname:pAttachments is a pointer to an array of slink:VkClearAttachment 225 structures defining the attachments to clear and the clear values to 226 use. 227 * pname:rectCount is the number of entries in the pname:pRects array. 228 * pname:pRects points to an array of slink:VkClearRect structures defining 229 regions within each selected attachment to clear. 230 231fname:vkCmdClearAttachments can: clear multiple regions of each attachment 232used in the current subpass of a render pass instance. 233This command must: be called only inside a render pass instance, and 234implicitly selects the images to clear based on the current framebuffer 235attachments and the command parameters. 236 237.Valid Usage 238**** 239 * [[VUID-vkCmdClearAttachments-aspectMask-00015]] 240 If the pname:aspectMask member of any element of pname:pAttachments 241 contains ename:VK_IMAGE_ASPECT_COLOR_BIT, the pname:colorAttachment 242 member of that element must: refer to a valid color attachment in the 243 current subpass 244 * [[VUID-vkCmdClearAttachments-pRects-00016]] 245 The rectangular region specified by each element of pname:pRects must: 246 be contained within the render area of the current render pass instance 247 * [[VUID-vkCmdClearAttachments-pRects-00017]] 248 The layers specified by each element of pname:pRects must: be contained 249 within every attachment that pname:pAttachments refers to 250 * [[VUID-vkCmdClearAttachments-layerCount-01934]] 251 The pname:layerCount member of each element of pname:pRects must: not be 252 `0` 253ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 254 * [[VUID-vkCmdClearAttachments-baseArrayLayer-00018]] 255 If the render pass instance this is recorded in uses multiview, then 256 pname:baseArrayLayer must: be zero and pname:layerCount must: be one. 257endif::VK_VERSION_1_1,VK_KHR_multiview[] 258**** 259 260include::../validity/protos/vkCmdClearAttachments.txt[] 261-- 262 263[open,refpage='VkClearRect',desc='Structure specifying a clear rectangle',type='structs'] 264-- 265 266The sname:VkClearRect structure is defined as: 267 268include::../api/structs/VkClearRect.txt[] 269 270 * pname:rect is the two-dimensional region to be cleared. 271 * pname:baseArrayLayer is the first layer to be cleared. 272 * pname:layerCount is the number of layers to clear. 273 274The layers [eq]#[pname:baseArrayLayer, pname:baseArrayLayer {plus} 275pname:layerCount)# counting from the base layer of the attachment image view 276are cleared. 277 278include::../validity/structs/VkClearRect.txt[] 279-- 280 281[open,refpage='VkClearAttachment',desc='Structure specifying a clear attachment',type='structs'] 282-- 283 284The sname:VkClearAttachment structure is defined as: 285 286include::../api/structs/VkClearAttachment.txt[] 287 288 * pname:aspectMask is a mask selecting the color, depth and/or stencil 289 aspects of the attachment to be cleared. 290 pname:aspectMask can: include ename:VK_IMAGE_ASPECT_COLOR_BIT for color 291 attachments, ename:VK_IMAGE_ASPECT_DEPTH_BIT for depth/stencil 292 attachments with a depth component, and 293 ename:VK_IMAGE_ASPECT_STENCIL_BIT for depth/stencil attachments with a 294 stencil component. 295 If the subpass's depth/stencil attachment is ename:VK_ATTACHMENT_UNUSED, 296 then the clear has no effect. 297 * pname:colorAttachment is only meaningful if 298 ename:VK_IMAGE_ASPECT_COLOR_BIT is set in pname:aspectMask, in which 299 case it is an index to the pname:pColorAttachments array in the 300 slink:VkSubpassDescription structure of the current subpass which 301 selects the color attachment to clear. 302 If pname:colorAttachment is ename:VK_ATTACHMENT_UNUSED then the clear 303 has no effect. 304 * pname:clearValue is the color or depth/stencil value to clear the 305 attachment to, as described in <<clears-values,Clear Values>> below. 306 307No memory barriers are needed between fname:vkCmdClearAttachments and 308preceding or subsequent draw or attachment clear commands in the same 309subpass. 310 311The fname:vkCmdClearAttachments command is not affected by the bound 312pipeline state. 313 314Attachments can: also be cleared at the beginning of a render pass instance 315by setting pname:loadOp (or pname:stencilLoadOp) of 316slink:VkAttachmentDescription to ename:VK_ATTACHMENT_LOAD_OP_CLEAR, as 317described for flink:vkCreateRenderPass. 318 319.Valid Usage 320**** 321 * [[VUID-VkClearAttachment-aspectMask-00019]] 322 If pname:aspectMask includes ename:VK_IMAGE_ASPECT_COLOR_BIT, it must: 323 not include ename:VK_IMAGE_ASPECT_DEPTH_BIT or 324 ename:VK_IMAGE_ASPECT_STENCIL_BIT 325 * [[VUID-VkClearAttachment-aspectMask-00020]] 326 pname:aspectMask must: not include ename:VK_IMAGE_ASPECT_METADATA_BIT 327 * [[VUID-VkClearAttachment-clearValue-00021]] 328 pname:clearValue must: be a valid sname:VkClearValue union 329ifdef::VK_VERSION_1_1[] 330 * [[VUID-VkClearAttachment-commandBuffer-01809]] 331 If pname:commandBuffer is an unprotected command buffer, then the 332 attachment to be cleared must: not be a protected image. 333 * [[VUID-VkClearAttachment-commandBuffer-01810]] 334 If pname:commandBuffer is a protected command buffer, then the 335 attachment to be cleared must: not be an unprotected image. 336endif::VK_VERSION_1_1[] 337**** 338 339include::../validity/structs/VkClearAttachment.txt[] 340-- 341 342 343[[clears-values]] 344== Clear Values 345 346[open,refpage='VkClearColorValue',desc='Structure specifying a clear color value',type='structs'] 347-- 348 349The sname:VkClearColorValue structure is defined as: 350 351include::../api/structs/VkClearColorValue.txt[] 352 353 * pname:float32 are the color clear values when the format of the image or 354 attachment is one of the formats in the 355 <<features-formats-numericformat, Interpretation of Numeric Format>> 356 table other than signed integer (etext:SINT) or unsigned integer 357 (etext:UINT). 358 Floating point values are automatically converted to the format of the 359 image, with the clear value being treated as linear if the image is 360 sRGB. 361 * pname:int32 are the color clear values when the format of the image or 362 attachment is signed integer (etext:SINT). 363 Signed integer values are converted to the format of the image by 364 casting to the smaller type (with negative 32-bit values mapping to 365 negative values in the smaller type). 366 If the integer clear value is not representable in the target type (e.g. 367 would overflow in conversion to that type), the clear value is 368 undefined. 369 * pname:uint32 are the color clear values when the format of the image or 370 attachment is unsigned integer (etext:UINT). 371 Unsigned integer values are converted to the format of the image by 372 casting to the integer type with fewer bits. 373 374The four array elements of the clear color map to R, G, B, and A components 375of image formats, in order. 376 377If the image has more than one sample, the same value is written to all 378samples for any pixels being cleared. 379 380include::../validity/structs/VkClearColorValue.txt[] 381-- 382 383[open,refpage='VkClearDepthStencilValue',desc='Structure specifying a clear depth stencil value',type='structs'] 384-- 385 386The sname:VkClearDepthStencilValue structure is defined as: 387 388include::../api/structs/VkClearDepthStencilValue.txt[] 389 390 * pname:depth is the clear value for the depth aspect of the depth/stencil 391 attachment. 392 It is a floating-point value which is automatically converted to the 393 attachment's format. 394 * pname:stencil is the clear value for the stencil aspect of the 395 depth/stencil attachment. 396 It is a 32-bit integer value which is converted to the attachment's 397 format by taking the appropriate number of LSBs. 398 399.Valid Usage 400**** 401ifdef::VK_EXT_depth_range_unrestricted[] 402 * [[VUID-VkClearDepthStencilValue-depth-00022]] 403 Unless the `<<VK_EXT_depth_range_unrestricted>>` extension is enabled 404 pname:depth must: be between `0.0` and `1.0`, inclusive 405endif::VK_EXT_depth_range_unrestricted[] 406ifndef::VK_EXT_depth_range_unrestricted[] 407 * [[VUID-VkClearDepthStencilValue-depth-00022]] 408 pname:depth must: be between `0.0` and `1.0`, inclusive 409endif::VK_EXT_depth_range_unrestricted[] 410**** 411 412 413include::../validity/structs/VkClearDepthStencilValue.txt[] 414-- 415 416[open,refpage='VkClearValue',desc='Structure specifying a clear value',type='structs'] 417-- 418 419The sname:VkClearValue union is defined as: 420 421include::../api/structs/VkClearValue.txt[] 422 423 * pname:color specifies the color image clear values to use when clearing 424 a color image or attachment. 425 * pname:depthStencil specifies the depth and stencil clear values to use 426 when clearing a depth/stencil image or attachment. 427 428This union is used where part of the API requires either color or 429depth/stencil clear values, depending on the attachment, and defines the 430initial clear values in the slink:VkRenderPassBeginInfo structure. 431 432include::../validity/structs/VkClearValue.txt[] 433-- 434 435 436[[clears-filling-buffers]] 437== Filling Buffers 438 439[open,refpage='vkCmdFillBuffer',desc='Fill a region of a buffer with a fixed value',type='protos'] 440-- 441 442To clear buffer data, call: 443 444include::../api/protos/vkCmdFillBuffer.txt[] 445 446 * pname:commandBuffer is the command buffer into which the command will be 447 recorded. 448 * pname:dstBuffer is the buffer to be filled. 449 * pname:dstOffset is the byte offset into the buffer at which to start 450 filling, and must: be a multiple of 4. 451 * pname:size is the number of bytes to fill, and must: be either a 452 multiple of 4, or ename:VK_WHOLE_SIZE to fill the range from 453 pname:offset to the end of the buffer. 454 If ename:VK_WHOLE_SIZE is used and the remaining size of the buffer is 455 not a multiple of 4, then the nearest smaller multiple is used. 456 * pname:data is the 4-byte word written repeatedly to the buffer to fill 457 pname:size bytes of data. 458 The data word is written to memory according to the host endianness. 459 460fname:vkCmdFillBuffer is treated as "`transfer`" operation for the purposes 461of synchronization barriers. 462The ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT must: be specified in pname:usage 463of sname:VkBufferCreateInfo in order for the buffer to be compatible with 464fname:vkCmdFillBuffer. 465 466.Valid Usage 467**** 468 * [[VUID-vkCmdFillBuffer-dstOffset-00024]] 469 pname:dstOffset must: be less than the size of pname:dstBuffer 470 * [[VUID-vkCmdFillBuffer-dstOffset-00025]] 471 pname:dstOffset must: be a multiple of `4` 472 * [[VUID-vkCmdFillBuffer-size-00026]] 473 If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:size must: be 474 greater than `0` 475 * [[VUID-vkCmdFillBuffer-size-00027]] 476 If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:size must: be 477 less than or equal to the size of pname:dstBuffer minus pname:dstOffset 478 * [[VUID-vkCmdFillBuffer-size-00028]] 479 If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:size must: be a 480 multiple of `4` 481 * [[VUID-vkCmdFillBuffer-dstBuffer-00029]] 482 pname:dstBuffer must: have been created with 483 ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag 484ifndef::VK_VERSION_1_1,VK_KHR_maintenance1[] 485 * [[VUID-vkCmdFillBuffer-commandBuffer-00030]] 486 The sname:VkCommandPool that pname:commandBuffer was allocated from 487 must: support graphics or compute operations 488endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 489 * [[VUID-vkCmdFillBuffer-dstBuffer-00031]] 490 If pname:dstBuffer is non-sparse then it must: be bound completely and 491 contiguously to a single sname:VkDeviceMemory object 492ifdef::VK_VERSION_1_1[] 493 * [[VUID-vkCmdFillBuffer-commandBuffer-01811]] 494 If pname:commandBuffer is an unprotected command buffer, then 495 pname:dstBuffer must: not be a protected buffer 496 * [[VUID-vkCmdFillBuffer-commandBuffer-01812]] 497 If pname:commandBuffer is a protected command buffer, then 498 pname:dstBuffer must: not be an unprotected buffer 499endif::VK_VERSION_1_1[] 500**** 501 502include::../validity/protos/vkCmdFillBuffer.txt[] 503-- 504 505 506[[clears-updating-buffers]] 507== Updating Buffers 508 509[open,refpage='vkCmdUpdateBuffer',desc='Update a buffer\'s contents from host memory',type='protos'] 510-- 511 512To update buffer data inline in a command buffer, call: 513 514include::../api/protos/vkCmdUpdateBuffer.txt[] 515 516 * pname:commandBuffer is the command buffer into which the command will be 517 recorded. 518 * pname:dstBuffer is a handle to the buffer to be updated. 519 * pname:dstOffset is the byte offset into the buffer to start updating, 520 and must: be a multiple of 4. 521 * pname:dataSize is the number of bytes to update, and must: be a multiple 522 of 4. 523 * pname:pData is a pointer to the source data for the buffer update, and 524 must: be at least pname:dataSize bytes in size. 525 526pname:dataSize must: be less than or equal to 65536 bytes. 527For larger updates, applications can: use buffer to buffer 528<<copies-buffers,copies>>. 529 530[NOTE] 531.Note 532==== 533Buffer updates performed with fname:vkCmdUpdateBuffer first copy the data 534into command buffer memory when the command is recorded (which requires 535additional storage and may incur an additional allocation), and then copy 536the data from the command buffer into pname:dstBuffer when the command is 537executed on a device. 538 539The additional cost of this functionality compared to <<copies-buffers, 540buffer to buffer copies>> means it is only recommended for very small 541amounts of data, and is why it is limited to only 65536 bytes. 542 543Applications can: work around this by issuing multiple 544fname:vkCmdUpdateBuffer commands to different ranges of the same buffer, but 545it is strongly recommended that they should: not. 546==== 547 548The source data is copied from the user pointer to the command buffer when 549the command is called. 550 551fname:vkCmdUpdateBuffer is only allowed outside of a render pass. 552This command is treated as "`transfer`" operation, for the purposes of 553synchronization barriers. 554The ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT must: be specified in pname:usage 555of slink:VkBufferCreateInfo in order for the buffer to be compatible with 556fname:vkCmdUpdateBuffer. 557 558.Valid Usage 559**** 560 * [[VUID-vkCmdUpdateBuffer-dstOffset-00032]] 561 pname:dstOffset must: be less than the size of pname:dstBuffer 562 * [[VUID-vkCmdUpdateBuffer-dataSize-00033]] 563 pname:dataSize must: be less than or equal to the size of 564 pname:dstBuffer minus pname:dstOffset 565 * [[VUID-vkCmdUpdateBuffer-dstBuffer-00034]] 566 pname:dstBuffer must: have been created with 567 ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag 568 * [[VUID-vkCmdUpdateBuffer-dstBuffer-00035]] 569 If pname:dstBuffer is non-sparse then it must: be bound completely and 570 contiguously to a single sname:VkDeviceMemory object 571 * [[VUID-vkCmdUpdateBuffer-dstOffset-00036]] 572 pname:dstOffset must: be a multiple of `4` 573 * [[VUID-vkCmdUpdateBuffer-dataSize-00037]] 574 pname:dataSize must: be less than or equal to `65536` 575 * [[VUID-vkCmdUpdateBuffer-dataSize-00038]] 576 pname:dataSize must: be a multiple of `4` 577ifdef::VK_VERSION_1_1[] 578 * [[VUID-vkCmdUpdateBuffer-commandBuffer-01813]] 579 If pname:commandBuffer is an unprotected command buffer, then 580 pname:dstBuffer must: not be a protected buffer 581 * [[VUID-vkCmdUpdateBuffer-commandBuffer-01814]] 582 If pname:commandBuffer is a protected command buffer, then 583 pname:dstBuffer must: not be an unprotected buffer 584endif::VK_VERSION_1_1[] 585**** 586 587include::../validity/protos/vkCmdUpdateBuffer.txt[] 588-- 589 590[NOTE] 591.Note 592==== 593The pname:pData parameter was of type code:uint32_t* instead of code:void* 594prior to revision 1.0.19 of the Specification and dlink:VK_HEADER_VERSION 19 595of the <<boilerplate-headers,Vulkan Header Files>>. 596This was a historical anomaly, as the source data may be of other types. 597==== 598