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