1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
// Copyright 2015-2023 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0
[[clears]]
= Clear Commands
[[clears-outside]]
== Clearing Images Outside A Render Pass Instance
Color and depth/stencil images can: be cleared outside a render pass
instance using flink:vkCmdClearColorImage or
flink:vkCmdClearDepthStencilImage, respectively.
These commands are only allowed outside of a render pass instance.
[open,refpage='vkCmdClearColorImage',desc='Clear regions of a color image',type='protos']
--
To clear one or more subranges of a color image, call:
include::{generated}/api/protos/vkCmdClearColorImage.adoc[]
* pname:commandBuffer is the command buffer into which the command will be
recorded.
* pname:image is the image to be cleared.
* pname:imageLayout specifies the current layout of the image subresource
ranges to be cleared, and must: be
ifdef::VK_KHR_shared_presentable_image[]
ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
endif::VK_KHR_shared_presentable_image[]
ename:VK_IMAGE_LAYOUT_GENERAL or
ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL.
* pname:pColor is a pointer to a slink:VkClearColorValue structure
containing the values that the image subresource ranges will be cleared
to (see <<clears-values>> below).
* pname:rangeCount is the number of image subresource range structures in
pname:pRanges.
* pname:pRanges is a pointer to an array of slink:VkImageSubresourceRange
structures describing a range of mipmap levels, array layers, and
aspects to be cleared, as described in <<resources-image-views,Image
Views>>.
Each specified range in pname:pRanges is cleared to the value specified by
pname:pColor.
.Valid Usage
****
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-vkCmdClearColorImage-image-01993]]
The <<resources-image-format-features,format features>> of pname:image
must: contain ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-vkCmdClearColorImage-image-00002]]
pname:image must: have been created with
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-vkCmdClearColorImage-image-01545]]
pname:image must: not use any of the
<<formats-requiring-sampler-ycbcr-conversion, formats that require a
sampler {YCbCr} conversion>>
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-vkCmdClearColorImage-image-00003]]
If pname:image is non-sparse then it must: be bound completely and
contiguously to a single sname:VkDeviceMemory object
* [[VUID-vkCmdClearColorImage-imageLayout-00004]]
pname:imageLayout must: specify the layout of the image subresource
ranges of pname:image specified in pname:pRanges at the time this
command is executed on a sname:VkDevice
ifndef::VK_KHR_shared_presentable_image[]
* [[VUID-vkCmdClearColorImage-imageLayout-00005]]
pname:imageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or
ename:VK_IMAGE_LAYOUT_GENERAL
endif::VK_KHR_shared_presentable_image[]
ifdef::VK_KHR_shared_presentable_image[]
* [[VUID-vkCmdClearColorImage-imageLayout-01394]]
pname:imageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL,
ename:VK_IMAGE_LAYOUT_GENERAL, or
ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
endif::VK_KHR_shared_presentable_image[]
* [[VUID-vkCmdClearColorImage-aspectMask-02498]]
The slink:VkImageSubresourceRange::pname:aspectMask members of the
elements of the pname:pRanges array must: each only include
ename:VK_IMAGE_ASPECT_COLOR_BIT
* [[VUID-vkCmdClearColorImage-baseMipLevel-01470]]
The slink:VkImageSubresourceRange::pname:baseMipLevel members of the
elements of the pname:pRanges array must: each be less than the
pname:mipLevels specified in slink:VkImageCreateInfo when pname:image
was created
* [[VUID-vkCmdClearColorImage-pRanges-01692]]
For each slink:VkImageSubresourceRange element of pname:pRanges, if the
pname:levelCount member is not ename:VK_REMAINING_MIP_LEVELS, then
[eq]#pname:baseMipLevel {plus} pname:levelCount# must: be less than or
equal to the pname:mipLevels specified in slink:VkImageCreateInfo when
pname:image was created
* [[VUID-vkCmdClearColorImage-baseArrayLayer-01472]]
The slink:VkImageSubresourceRange::pname:baseArrayLayer members of the
elements of the pname:pRanges array must: each be less than the
pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image
was created
* [[VUID-vkCmdClearColorImage-pRanges-01693]]
For each slink:VkImageSubresourceRange element of pname:pRanges, if the
pname:layerCount member is not ename:VK_REMAINING_ARRAY_LAYERS, then
[eq]#pname:baseArrayLayer {plus} pname:layerCount# must: be less than or
equal to the pname:arrayLayers specified in slink:VkImageCreateInfo when
pname:image was created
* [[VUID-vkCmdClearColorImage-image-00007]]
pname:image must: not have a compressed or depth/stencil format
* [[VUID-vkCmdClearColorImage-pColor-04961]]
pname:pColor must: be a valid pointer to a slink:VkClearColorValue union
ifdef::VK_VERSION_1_1[]
* [[VUID-vkCmdClearColorImage-commandBuffer-01805]]
If pname:commandBuffer is an unprotected command buffer and
<<limits-protectedNoFault, pname:protectedNoFault>> is not supported,
pname:image must: not be a protected image
* [[VUID-vkCmdClearColorImage-commandBuffer-01806]]
If pname:commandBuffer is a protected command buffer and
<<limits-protectedNoFault, pname:protectedNoFault>> is not supported,
must: not be an unprotected image
endif::VK_VERSION_1_1[]
****
include::{generated}/validity/protos/vkCmdClearColorImage.adoc[]
--
|
