• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 // Copyright 2015-2023 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 
12 Color and depth/stencil images can: be cleared outside a render pass
13 instance using flink:vkCmdClearColorImage or
14 flink:vkCmdClearDepthStencilImage, respectively.
15 These 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 To clear one or more subranges of a color image, call:
20 
21 include::{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
28 ifdef::VK_KHR_shared_presentable_image[]
29     ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
30 endif::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 
43 Each specified range in pname:pRanges is cleared to the value specified by
44 pname:pColor.
45 
46 .Valid Usage
47 ****
48 ifdef::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
52 endif::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
56 ifdef::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>>
61 endif::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
71 ifdef::VK_KHR_shared_presentable_image[]
72     ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
73 endif::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
106 ifdef::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
115 endif::VK_VERSION_1_1[]
116 ****
117 
118 include::{generated}/validity/protos/vkCmdClearColorImage.adoc[]
119 --
120 
121 [open,refpage='vkCmdClearDepthStencilImage',desc='Fill regions of a combined depth/stencil image',type='protos']
122 --
123 To clear one or more subranges of a depth/stencil image, call:
124 
125 include::{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 ****
145 ifdef::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
149 endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
150 ifdef::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
158 endif::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,
162 ifdef::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[]
163     and pname:image was not created with
164     <<VkImageStencilUsageCreateInfo,separate stencil usage>>,
165 endif::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
222 ifdef::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
231 endif::VK_VERSION_1_1[]
232 ****
233 
234 include::{generated}/validity/protos/vkCmdClearDepthStencilImage.adoc[]
235 --
236 
237 Clears outside render pass instances are treated as transfer operations for
238 the 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 --
246 To clear one or more regions of color and depth/stencil attachments inside a
247 render pass instance, call:
248 
249 include::{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 
262 ifdef::VK_EXT_fragment_density_map[]
263 If the render pass has a <<renderpass-fragmentdensitymapattachment,fragment
264 density map attachment>>, clears follow the
265 <<fragmentdensitymapops,operations of fragment density maps>> as if each
266 clear region was a primitive which generates fragments.
267 The clear color is applied to all pixels inside each fragment's area
268 regardless if the pixels lie outside of the clear region.
269 Clears may: have a different set of supported fragment areas than draws.
270 endif::VK_EXT_fragment_density_map[]
271 
272 Unlike other <<clears,clear commands>>, flink:vkCmdClearAttachments is not a
273 transfer command.
274 It performs its operations in <<primsrast-order, rasterization order>>.
275 For color attachments, the operations are executed as color attachment
276 writes, by the ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT stage.
277 For depth/stencil attachments, the operations are executed as
278 <<fragops-depth, depth writes>> and <<fragops-stencil, stencil writes>> by
279 the ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT and
280 ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT stages.
281 
282 fname:vkCmdClearAttachments is not affected by the bound pipeline state.
283 
284 [NOTE]
285 .Note
286 ====
287 It is generally preferable to clear attachments by using the
288 ename:VK_ATTACHMENT_LOAD_OP_CLEAR load operation at the start of rendering,
289 as it is more efficient on some implementations.
290 ====
291 
292 If any attachment's pname:aspectMask to be cleared is not backed by an image
293 view, the clear has no effect on that aspect.
294 
295 ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
296 If an attachment being cleared refers to an image view created with an
297 pname:aspectMask equal to one of ename:VK_IMAGE_ASPECT_PLANE_0_BIT,
298 ename:VK_IMAGE_ASPECT_PLANE_1_BIT or ename:VK_IMAGE_ASPECT_PLANE_2_BIT, it
299 is considered to be ename:VK_IMAGE_ASPECT_COLOR_BIT for purposes of this
300 command, and must: be cleared with the ename:VK_IMAGE_ASPECT_COLOR_BIT
301 aspect as specified by <<image-views-plane-promotion,image view creation>>.
302 endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
303 
304 .Valid Usage
305 ****
306   * [[VUID-vkCmdClearAttachments-aspectMask-07884]]
307     If
308 ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[]
309     the current render pass instance does not use dynamic rendering, and
310 endif::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
317 ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[]
318     the current render pass instance does not use dynamic rendering, and
319 endif::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`
348 ifdef::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
357 endif::VK_VERSION_1_1[]
358 ifdef::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
362 endif::VK_VERSION_1_1,VK_KHR_multiview[]
363 ifdef::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_
368 endif::VK_ANDROID_external_format_resolve[]
369 ****
370 
371 include::{generated}/validity/protos/vkCmdClearAttachments.adoc[]
372 --
373 
374 [open,refpage='VkClearRect',desc='Structure specifying a clear rectangle',type='structs']
375 --
376 The sname:VkClearRect structure is defined as:
377 
378 include::{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 
384 The layers [eq]#[pname:baseArrayLayer, pname:baseArrayLayer {plus}
385 pname:layerCount)# counting from the base layer of the attachment image view
386 are cleared.
387 
388 include::{generated}/validity/structs/VkClearRect.adoc[]
389 --
390 
391 [open,refpage='VkClearAttachment',desc='Structure specifying a clear attachment',type='structs']
392 --
393 The sname:VkClearAttachment structure is defined as:
394 
395 include::{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
413 ifdef::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_
417 endif::VK_EXT_image_drm_format_modifier[]
418 ****
419 
420 include::{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 --
429 The sname:VkClearColorValue structure is defined as:
430 
431 include::{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 
452 The four array elements of the clear color map to R, G, B, and A components
453 of image formats, in order.
454 
455 If the image has more than one sample, the same value is written to all
456 samples for any pixels being cleared.
457 
458 include::{generated}/validity/structs/VkClearColorValue.adoc[]
459 --
460 
461 [open,refpage='VkClearDepthStencilValue',desc='Structure specifying a clear depth stencil value',type='structs']
462 --
463 The sname:VkClearDepthStencilValue structure is defined as:
464 
465 include::{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]]
479 ifdef::VK_EXT_depth_range_unrestricted[]
480     Unless the `apiext:VK_EXT_depth_range_unrestricted` extension is enabled
481 endif::VK_EXT_depth_range_unrestricted[]
482     pname:depth must: be between `0.0` and `1.0`, inclusive
483 ****
484 
485 include::{generated}/validity/structs/VkClearDepthStencilValue.adoc[]
486 --
487 
488 [open,refpage='VkClearValue',desc='Structure specifying a clear value',type='structs']
489 --
490 The sname:VkClearValue union is defined as:
491 
492 include::{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 
499 This union is used where part of the API requires either color or
500 depth/stencil clear values, depending on the attachment, and defines the
501 initial clear values in the slink:VkRenderPassBeginInfo structure.
502 
503 include::{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 --
512 To clear buffer data, call:
513 
514 include::{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 
530 fname:vkCmdFillBuffer is treated as a "`transfer`" operation for the
531 purposes of synchronization barriers.
532 The ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT must: be specified in pname:usage
533 of slink:VkBufferCreateInfo in order for the buffer to be compatible with
534 fname: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]]
555 ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
556 ifndef::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
560 endif::VKSC_VERSION_1_0[]
561 endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
562 ifndef::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
568 ifdef::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
577 endif::VK_VERSION_1_1[]
578 ****
579 
580 include::{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 --
589 To update buffer data inline in a command buffer, call:
590 
591 include::{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 
603 pname:dataSize must: be less than or equal to 65536 bytes.
604 For larger updates, applications can: use buffer to buffer
605 <<copies-buffers,copies>>.
606 
607 [NOTE]
608 .Note
609 ====
610 Buffer updates performed with fname:vkCmdUpdateBuffer first copy the data
611 into command buffer memory when the command is recorded (which requires
612 additional storage and may incur an additional allocation), and then copy
613 the data from the command buffer into pname:dstBuffer when the command is
614 executed on a device.
615 
616 The additional cost of this functionality compared to <<copies-buffers,
617 buffer to buffer copies>> means it is only recommended for very small
618 amounts of data, and is why it is limited to only 65536 bytes.
619 
620 Applications can: work around this by issuing multiple
621 fname:vkCmdUpdateBuffer commands to different ranges of the same buffer, but
622 it is strongly recommended that they should: not.
623 ====
624 
625 The source data is copied from the user pointer to the command buffer when
626 the command is called.
627 
628 fname:vkCmdUpdateBuffer is only allowed outside of a render pass.
629 This command is treated as a "`transfer`" operation for the purposes of
630 synchronization barriers.
631 The ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT must: be specified in pname:usage
632 of slink:VkBufferCreateInfo in order for the buffer to be compatible with
633 fname: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`
654 ifdef::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
663 endif::VK_VERSION_1_1[]
664 ****
665 
666 include::{generated}/validity/protos/vkCmdUpdateBuffer.adoc[]
667 --
668 
669 ifndef::VKSC_VERSION_1_0[]
670 [NOTE]
671 .Note
672 ====
673 The pname:pData parameter was of type code:uint32_t* instead of code:void*
674 prior to version 1.0.19 of the Specification and dlink:VK_HEADER_VERSION 19
675 of the <<boilerplate-headers,Vulkan Header Files>>.
676 This was a historical anomaly, as the source data may be of other types.
677 ====
678 endif::VKSC_VERSION_1_0[]
679