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