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);
commandBufferis the command buffer into which the command will be recorded.imageis the image to be cleared.imageLayoutspecifies the current layout of the image subresource ranges to be cleared, and must beVK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,VK_IMAGE_LAYOUT_GENERALorVK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL.pColoris a pointer to a VkClearColorValue structure containing the values that the image subresource ranges will be cleared to (see Clear Values below).rangeCountis the number of image subresource range structures inpRanges.pRangesis 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 imagemust 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
commandBuffermust be externally synchronized - Host access to the
VkCommandPoolthatcommandBufferwas allocated from must be externally synchronized ::