vkCmdClearColorImage
To clear one or more subranges of a color image, call:
void vkCmdClearColorImage(
VkCommandBuffer commandBuffer,
VkImage image,
VkImageLayout imageLayout,
const VkClearColorValue* pColor,
uint32_t rangeCount,
const VkImageSubresourceRange* pRanges);
commandBuffer
is the command buffer into which the command will be recorded.image
is the image to be cleared.imageLayout
specifies the current layout of the image subresource ranges to be cleared, and must beVK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
,VK_IMAGE_LAYOUT_GENERAL
orVK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL
.pColor
is a pointer to a VkClearColorValue structure containing the values that the image subresource ranges will be cleared to (see Clear Values below).rangeCount
is the number of image subresource range structures inpRanges
.pRanges
is a pointer to an array of VkImageSubresourceRange structures describing a range of mipmap levels, array layers, and aspects to be cleared, as described in Image Views.
Each specified range in pRanges
is cleared to the value specified by
pColor
.
Valid Usage
VUID-vkCmdClearColorImage-image-01993
The format features of image
must contain VK_FORMAT_FEATURE_TRANSFER_DST_BIT
VUID-vkCmdClearColorImage-image-00002
image
must have been created with
VK_IMAGE_USAGE_TRANSFER_DST_BIT
usage flag
VUID-vkCmdClearColorImage-image-01545
image
must not use any of the
formats that require a
sampler Y′CBCR conversion
VUID-vkCmdClearColorImage-image-00003
If image
is non-sparse then it must be bound completely and
contiguously to a single VkDeviceMemory
object
VUID-vkCmdClearColorImage-imageLayout-00004
imageLayout
must specify the layout of the image subresource
ranges of image
specified in pRanges
at the time this
command is executed on a VkDevice
VUID-vkCmdClearColorImage-imageLayout-01394
imageLayout
must be
VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
,
VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL
or
VK_IMAGE_LAYOUT_GENERAL
VUID-vkCmdClearColorImage-aspectMask-02498
The VkImageSubresourceRange::aspectMask
members of the
elements of the pRanges
array must each only include
VK_IMAGE_ASPECT_COLOR_BIT
VUID-vkCmdClearColorImage-baseMipLevel-01470
The VkImageSubresourceRange::baseMipLevel
members of the
elements of the pRanges
array must each be less than the
mipLevels
specified in VkImageCreateInfo when image
was created
VUID-vkCmdClearColorImage-pRanges-01692
For each VkImageSubresourceRange element of pRanges
, if the
levelCount
member is not VK_REMAINING_MIP_LEVELS
, then
baseMipLevel
+ levelCount
must be less than or
equal to the mipLevels
specified in VkImageCreateInfo when
image
was created
VUID-vkCmdClearColorImage-baseArrayLayer-01472
The VkImageSubresourceRange::baseArrayLayer
members of the
elements of the pRanges
array must each be less than the
arrayLayers
specified in VkImageCreateInfo when image
was created
VUID-vkCmdClearColorImage-pRanges-01693
For each VkImageSubresourceRange element of pRanges
, if the
layerCount
member is not VK_REMAINING_ARRAY_LAYERS
, then
baseArrayLayer
+ layerCount
must be less than or
equal to the arrayLayers
specified in VkImageCreateInfo when
image
was created
VUID-vkCmdClearColorImage-image-00007
image
must not have a compressed or depth/stencil format
VUID-vkCmdClearColorImage-pColor-04961
pColor
must be a valid pointer to a VkClearColorValue union
VUID-vkCmdClearColorImage-image-09678
If image
’s format has components other than R and G, it must not
have a 64-bit component width
Valid Usage (Implicit)
VUID-vkCmdClearColorImage-commandBuffer-parameter
commandBuffer
must be a valid VkCommandBuffer handle
VUID-vkCmdClearColorImage-image-parameter
image
must be a valid VkImage handle
VUID-vkCmdClearColorImage-imageLayout-parameter
imageLayout
must be a valid VkImageLayout value
VUID-vkCmdClearColorImage-pRanges-parameter
pRanges
must be a valid pointer to an array of rangeCount
valid VkImageSubresourceRange structures
VUID-vkCmdClearColorImage-commandBuffer-recording
commandBuffer
must be in the recording state
VUID-vkCmdClearColorImage-commandBuffer-cmdpool
The VkCommandPool
that commandBuffer
was allocated from must support graphics, or compute operations
VUID-vkCmdClearColorImage-renderpass
This command must only be called outside of a render pass instance
VUID-vkCmdClearColorImage-videocoding
This command must only be called outside of a video coding scope
VUID-vkCmdClearColorImage-rangeCount-arraylength
rangeCount
must be greater than 0
VUID-vkCmdClearColorImage-commonparent
Both of commandBuffer
, and image
must have been created, allocated, or retrieved from the same VkDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized - Host access to the
VkCommandPool
thatcommandBuffer
was allocated from must be externally synchronized ::