VKCMDCLEARCOLORIMAGE(3)

NAME
vkCmdClearColorImage - Clear regions of a color image.

C SPECIFICATION

    void vkCmdClearColorImage(
        VkCommandBuffer                             commandBuffer,
        VkImage                                     image,
        VkImageLayout                               imageLayout,
        const VkClearColorValue*                    pColor,
        uint32_t                                    rangeCount,
        const VkImageSubresourceRange*              pRanges);

PARAMETERS

commandBuffer
    The command buffer into which the clear command is to be placed.

image
    The image that contains the regions to be cleared.

imageLayout
    The layout of the image at the time of the clear operation.

pColor
    A pointer to a structure containing the color with which to clear the image.

rangeCount
    The number of ranges to clear.

pRanges
    A pointer to an array of structures defining the regions to be cleared.

DESCRIPTION

vkCmdClearColorImage clears rangeCount regions of an image. The color with which to clear the image is specified an instance of the VkClearColorValue union pointed to by pColor. The definition of VkClearColorValue is:

    typedef union VkClearColorValue {
        float       float32[4];
        int32_t     int32[4];
        uint32_t    uint32[4];
    } VkClearColorValue;

The float32, int32 and uint32 members of pColor are arrays of four 32-bit floating point, signed integer or unsigned integer values, respectively. Which is used is determined from the format of the image specified in image.

The first element of the selected array is written to the first component of the target image, the second element to the second component, the third to the third and the fourth to the fourth, if those components exist. pRanges describes the regions to be cleared and points to an array of rangeCount VkImageSubresourceRange structures, the definition of which is:

    typedef struct VkImageSubresourceRange {
        VkImageAspectFlags    aspectMask;
        uint32_t              baseMipLevel;
        uint32_t              levelCount;
        uint32_t              baseArrayLayer;
        uint32_t              layerCount;
    } VkImageSubresourceRange;

VALID USAGE

    • commandBuffer must be a valid VkCommandBuffer handle

    • image must be a valid VkImage handle

    • imageLayout must be a valid VkImageLayout value

    • pColor must be a pointer to a valid VkClearColorValue union

    • pRanges must be a pointer to an array of rangeCount valid VkImageSubresourceRange structures

    • commandBuffer must be in the recording state

    • The VkCommandPool that commandBuffer was allocated from must support graphics or compute operations

    • This command must only be called outside of a render pass instance

    • rangeCount must be greater than 0

    • Each of commandBuffer and image must have been created, allocated or retrieved from the same VkDevice

    • image must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag

    • 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

    • imageLayout must be either of VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

    • The image range of any given element of pRanges must be an image subresource range that is contained within image

    • image must not have a compressed or depth/stencil format

HOST SYNCHRONIZATION

    • Host access to commandBuffer must be externally synchronized

COMMAND PROPERTIES
Command Buffer Levels | Render Pass Scope | Supported Queue Types
Primary Secondary | Outside | GRAPHICS COMPUTE

NOTES

Although vkCmdClearColorImage does not generate errors or return a value, enabled validation layers may detect possible error conditions or potentially undefined behavior and report this via some other means.

SEE ALSO

vkCmdClearDepthStencilImage

COPYRIGHT

Copyright © 2014-2016 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.

AUTHOR

Khronos Group
    Author.