18. Clear Commands

18.1. Clearing Images Outside A Render Pass Instance

Color and depth/stencil images can be cleared outside a render pass instance using vkCmdClearColorImage or vkCmdClearDepthStencilImage, respectively. These commands are only allowed outside of a render pass instance.

To clear one or more subranges of a color image, call:

// Provided by VK_VERSION_1_0
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 be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_GENERAL or VK_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 in pRanges.

  • 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

  • The format features of image must contain VK_FORMAT_FEATURE_TRANSFER_DST_BIT

  • image must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag

  • image must not use a format listed in Formats requiring sampler Y′CBCR conversion for VK_IMAGE_ASPECT_COLOR_BIT image views

  • If image is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • 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 VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, VK_IMAGE_LAYOUT_GENERAL, or VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR

  • The VkImageSubresourceRange::aspectMask members of the elements of the pRanges array must each only include VK_IMAGE_ASPECT_COLOR_BIT

  • 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

  • For each VkImageSubresourceRange element of pRanges, if the levelCount member is not VK_REMAINING_MIP_LEVELS, then baseMipLevel + levelCount must be less than the mipLevels specified in VkImageCreateInfo when image was created

  • 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

  • For each VkImageSubresourceRange element of pRanges, if the layerCount member is not VK_REMAINING_ARRAY_LAYERS, then baseArrayLayer + layerCount must be less than the arrayLayers specified in VkImageCreateInfo when image was created

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

  • If commandBuffer is an unprotected command buffer, then image must not be a protected image

  • If commandBuffer is a protected command buffer, then image must not be an unprotected image

Valid Usage (Implicit)

  • 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 valid pointer to a valid VkClearColorValue union

  • pRanges must be a valid 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

  • 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 that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Graphics
Compute

Transfer

To clear one or more subranges of a depth/stencil image, call:

// Provided by VK_VERSION_1_0
void vkCmdClearDepthStencilImage(
    VkCommandBuffer                             commandBuffer,
    VkImage                                     image,
    VkImageLayout                               imageLayout,
    const VkClearDepthStencilValue*             pDepthStencil,
    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 be VK_IMAGE_LAYOUT_GENERAL or VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL.

  • pDepthStencil is a pointer to a VkClearDepthStencilValue structure containing the values that the depth and stencil image subresource ranges will be cleared to (see Clear Values below).

  • rangeCount is the number of image subresource range structures in pRanges.

  • 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.

Valid Usage

  • The format features of image must contain VK_FORMAT_FEATURE_TRANSFER_DST_BIT

  • If the aspect member of any element of pRanges includes VK_IMAGE_ASPECT_STENCIL_BIT, and image was created with separate stencil usage, VK_IMAGE_USAGE_TRANSFER_DST_BIT must have been included in the VkImageStencilUsageCreateInfo::stencilUsage used to create image

  • If the aspect member of any element of pRanges includes VK_IMAGE_ASPECT_STENCIL_BIT, and image was not created with separate stencil usage, VK_IMAGE_USAGE_TRANSFER_DST_BIT must have been included in the VkImageCreateInfo::usage used to create image

  • If the aspect member of any element of pRanges includes VK_IMAGE_ASPECT_DEPTH_BIT, VK_IMAGE_USAGE_TRANSFER_DST_BIT must have been included in the VkImageCreateInfo::usage used to create image

  • If image is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • 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 VkImageSubresourceRange::aspectMask member of each element of the pRanges array must not include bits other than VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT

  • If the image’s format does not have a stencil component, then the VkImageSubresourceRange::aspectMask member of each element of the pRanges array must not include the VK_IMAGE_ASPECT_STENCIL_BIT bit

  • If the image’s format does not have a depth component, then the VkImageSubresourceRange::aspectMask member of each element of the pRanges array must not include the VK_IMAGE_ASPECT_DEPTH_BIT bit

  • 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

  • For each VkImageSubresourceRange element of pRanges, if the levelCount member is not VK_REMAINING_MIP_LEVELS, then baseMipLevel + levelCount must be less than the mipLevels specified in VkImageCreateInfo when image was created

  • 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

  • For each VkImageSubresourceRange element of pRanges, if the layerCount member is not VK_REMAINING_ARRAY_LAYERS, then baseArrayLayer + layerCount must be less than the arrayLayers specified in VkImageCreateInfo when image was created

  • image must have a depth/stencil format

  • If commandBuffer is an unprotected command buffer, then image must not be a protected image

  • If commandBuffer is a protected command buffer, then image must not be an unprotected image

Valid Usage (Implicit)

  • commandBuffer must be a valid VkCommandBuffer handle

  • image must be a valid VkImage handle

  • imageLayout must be a valid VkImageLayout value

  • pDepthStencil must be a valid pointer to a valid VkClearDepthStencilValue structure

  • pRanges must be a valid 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 operations

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

  • rangeCount must be greater than 0

  • 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 that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Graphics

Transfer

Clears outside render pass instances are treated as transfer operations for the purposes of memory barriers.

18.2. Clearing Images Inside A Render Pass Instance

To clear one or more regions of color and depth/stencil attachments inside a render pass instance, call:

// Provided by VK_VERSION_1_0
void vkCmdClearAttachments(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    attachmentCount,
    const VkClearAttachment*                    pAttachments,
    uint32_t                                    rectCount,
    const VkClearRect*                          pRects);

  • commandBuffer is the command buffer into which the command will be recorded.

  • attachmentCount is the number of entries in the pAttachments array.

  • pAttachments is a pointer to an array of VkClearAttachment structures defining the attachments to clear and the clear values to use. If any attachment to be cleared in the current subpass is VK_ATTACHMENT_UNUSED, then the clear has no effect on that attachment.

  • rectCount is the number of entries in the pRects array.

  • pRects is a pointer to an array of VkClearRect structures defining regions within each selected attachment to clear.

vkCmdClearAttachments can clear multiple regions of each attachment used in the current subpass of a render pass instance. This command must be called only inside a render pass instance, and implicitly selects the images to clear based on the current framebuffer attachments and the command parameters.

If the render pass has a fragment density map attachment, clears follow the operations of fragment density maps as if each clear region was a primitive which generates fragments. The clear color is applied to all pixels inside each fragment’s area regardless if the pixels lie outside of the clear region. Clears may have a different set of supported fragment areas than draws.

Unlike other clear commands, vkCmdClearAttachments executes as a drawing command, rather than a transfer command, with writes performed by it executing in rasterization order. Clears to color attachments are executed as color attachment writes, by the VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT stage. Clears to depth/stencil attachments are executed as depth writes and writes by the VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT and VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT stages.

Valid Usage

  • If the aspectMask member of any element of pAttachments contains VK_IMAGE_ASPECT_COLOR_BIT, then the colorAttachment member of that element must either refer to a color attachment which is VK_ATTACHMENT_UNUSED, or must be a valid color attachment

  • If the aspectMask member of any element of pAttachments contains VK_IMAGE_ASPECT_DEPTH_BIT, then the current subpass' depth/stencil attachment must either be VK_ATTACHMENT_UNUSED, or must have a depth component

  • If the aspectMask member of any element of pAttachments contains VK_IMAGE_ASPECT_STENCIL_BIT, then the current subpass' depth/stencil attachment must either be VK_ATTACHMENT_UNUSED, or must have a stencil component

  • The rect member of each element of pRects must have an extent.width greater than 0

  • The rect member of each element of pRects must have an extent.height greater than 0

  • The rectangular region specified by each element of pRects must be contained within the render area of the current render pass instance

  • The layers specified by each element of pRects must be contained within every attachment that pAttachments refers to

  • The layerCount member of each element of pRects must not be 0

  • If commandBuffer is an unprotected command buffer, then each attachment to be cleared must not be a protected image

  • If commandBuffer is a protected command buffer, then each attachment to be cleared must not be an unprotected image

  • If the render pass instance this is recorded in uses multiview, then baseArrayLayer must be zero and layerCount must be one

Valid Usage (Implicit)

  • commandBuffer must be a valid VkCommandBuffer handle

  • pAttachments must be a valid pointer to an array of attachmentCount valid VkClearAttachment structures

  • pRects must be a valid pointer to an array of rectCount VkClearRect structures

  • commandBuffer must be in the recording state

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

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

  • attachmentCount must be greater than 0

  • rectCount must be greater than 0

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Inside

Graphics

Graphics

The VkClearRect structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkClearRect {
    VkRect2D    rect;
    uint32_t    baseArrayLayer;
    uint32_t    layerCount;
} VkClearRect;

  • rect is the two-dimensional region to be cleared.

  • baseArrayLayer is the first layer to be cleared.

  • layerCount is the number of layers to clear.

The layers [baseArrayLayer, baseArrayLayer + layerCount) counting from the base layer of the attachment image view are cleared.

The VkClearAttachment structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkClearAttachment {
    VkImageAspectFlags    aspectMask;
    uint32_t              colorAttachment;
    VkClearValue          clearValue;
} VkClearAttachment;

  • aspectMask is a mask selecting the color, depth and/or stencil aspects of the attachment to be cleared.

  • colorAttachment is only meaningful if VK_IMAGE_ASPECT_COLOR_BIT is set in aspectMask, in which case it is an index to the pColorAttachments array in the VkSubpassDescription structure of the current subpass which selects the color attachment to clear.

  • clearValue is the color or depth/stencil value to clear the attachment to, as described in Clear Values below.

No memory barriers are needed between vkCmdClearAttachments and preceding or subsequent draw or attachment clear commands in the same subpass.

The vkCmdClearAttachments command is not affected by the bound pipeline state.

Attachments can also be cleared at the beginning of a render pass instance by setting loadOp (or stencilLoadOp) of VkAttachmentDescription to VK_ATTACHMENT_LOAD_OP_CLEAR, as described for vkCreateRenderPass.

Valid Usage

  • If aspectMask includes VK_IMAGE_ASPECT_COLOR_BIT, it must not include VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT

  • aspectMask must not include VK_IMAGE_ASPECT_METADATA_BIT

  • aspectMask must not include VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT for any index i

  • clearValue must be a valid VkClearValue union

Valid Usage (Implicit)

18.3. Clear Values

The VkClearColorValue structure is defined as:

// Provided by VK_VERSION_1_0
typedef union VkClearColorValue {
    float       float32[4];
    int32_t     int32[4];
    uint32_t    uint32[4];
} VkClearColorValue;

  • float32 are the color clear values when the format of the image or attachment is one of the formats in the Interpretation of Numeric Format table other than signed integer (SINT) or unsigned integer (UINT). Floating point values are automatically converted to the format of the image, with the clear value being treated as linear if the image is sRGB.

  • int32 are the color clear values when the format of the image or attachment is signed integer (SINT). Signed integer values are converted to the format of the image by casting to the smaller type (with negative 32-bit values mapping to negative values in the smaller type). If the integer clear value is not representable in the target type (e.g. would overflow in conversion to that type), the clear value is undefined.

  • uint32 are the color clear values when the format of the image or attachment is unsigned integer (UINT). Unsigned integer values are converted to the format of the image by casting to the integer type with fewer bits.

The four array elements of the clear color map to R, G, B, and A components of image formats, in order.

If the image has more than one sample, the same value is written to all samples for any pixels being cleared.

The VkClearDepthStencilValue structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkClearDepthStencilValue {
    float       depth;
    uint32_t    stencil;
} VkClearDepthStencilValue;

  • depth is the clear value for the depth aspect of the depth/stencil attachment. It is a floating-point value which is automatically converted to the attachment’s format.

  • stencil is the clear value for the stencil aspect of the depth/stencil attachment. It is a 32-bit integer value which is converted to the attachment’s format by taking the appropriate number of LSBs.

Valid Usage

The VkClearValue union is defined as:

// Provided by VK_VERSION_1_0
typedef union VkClearValue {
    VkClearColorValue           color;
    VkClearDepthStencilValue    depthStencil;
} VkClearValue;

  • color specifies the color image clear values to use when clearing a color image or attachment.

  • depthStencil specifies the depth and stencil clear values to use when clearing a depth/stencil image or attachment.

This union is used where part of the API requires either color or depth/stencil clear values, depending on the attachment, and defines the initial clear values in the VkRenderPassBeginInfo structure.

18.4. Filling Buffers

To clear buffer data, call:

// Provided by VK_VERSION_1_0
void vkCmdFillBuffer(
    VkCommandBuffer                             commandBuffer,
    VkBuffer                                    dstBuffer,
    VkDeviceSize                                dstOffset,
    VkDeviceSize                                size,
    uint32_t                                    data);

  • commandBuffer is the command buffer into which the command will be recorded.

  • dstBuffer is the buffer to be filled.

  • dstOffset is the byte offset into the buffer at which to start filling, and must be a multiple of 4.

  • size is the number of bytes to fill, and must be either a multiple of 4, or VK_WHOLE_SIZE to fill the range from offset to the end of the buffer. If VK_WHOLE_SIZE is used and the remaining size of the buffer is not a multiple of 4, then the nearest smaller multiple is used.

  • data is the 4-byte word written repeatedly to the buffer to fill size bytes of data. The data word is written to memory according to the host endianness.

vkCmdFillBuffer is treated as “transfer” operation for the purposes of synchronization barriers. The VK_BUFFER_USAGE_TRANSFER_DST_BIT must be specified in usage of VkBufferCreateInfo in order for the buffer to be compatible with vkCmdFillBuffer.

Valid Usage

  • dstOffset must be less than the size of dstBuffer

  • dstOffset must be a multiple of 4

  • If size is not equal to VK_WHOLE_SIZE, size must be greater than 0

  • If size is not equal to VK_WHOLE_SIZE, size must be less than or equal to the size of dstBuffer minus dstOffset

  • If size is not equal to VK_WHOLE_SIZE, size must be a multiple of 4

  • dstBuffer must have been created with VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag

  • If dstBuffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • If commandBuffer is an unprotected command buffer, then dstBuffer must not be a protected buffer

  • If commandBuffer is a protected command buffer, then dstBuffer must not be an unprotected buffer

Valid Usage (Implicit)

  • commandBuffer must be a valid VkCommandBuffer handle

  • dstBuffer must be a valid VkBuffer handle

  • commandBuffer must be in the recording state

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

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

  • Both of commandBuffer, and dstBuffer 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 that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Transfer
Graphics
Compute

Transfer

18.5. Updating Buffers

To update buffer data inline in a command buffer, call:

// Provided by VK_VERSION_1_0
void vkCmdUpdateBuffer(
    VkCommandBuffer                             commandBuffer,
    VkBuffer                                    dstBuffer,
    VkDeviceSize                                dstOffset,
    VkDeviceSize                                dataSize,
    const void*                                 pData);

  • commandBuffer is the command buffer into which the command will be recorded.

  • dstBuffer is a handle to the buffer to be updated.

  • dstOffset is the byte offset into the buffer to start updating, and must be a multiple of 4.

  • dataSize is the number of bytes to update, and must be a multiple of 4.

  • pData is a pointer to the source data for the buffer update, and must be at least dataSize bytes in size.

dataSize must be less than or equal to 65536 bytes. For larger updates, applications can use buffer to buffer copies.

Note

Buffer updates performed with vkCmdUpdateBuffer first copy the data into command buffer memory when the command is recorded (which requires additional storage and may incur an additional allocation), and then copy the data from the command buffer into dstBuffer when the command is executed on a device.

The additional cost of this functionality compared to buffer to buffer copies means it is only recommended for very small amounts of data, and is why it is limited to only 65536 bytes.

Applications can work around this by issuing multiple vkCmdUpdateBuffer commands to different ranges of the same buffer, but it is strongly recommended that they should not.

The source data is copied from the user pointer to the command buffer when the command is called.

vkCmdUpdateBuffer is only allowed outside of a render pass. This command is treated as “transfer” operation, for the purposes of synchronization barriers. The VK_BUFFER_USAGE_TRANSFER_DST_BIT must be specified in usage of VkBufferCreateInfo in order for the buffer to be compatible with vkCmdUpdateBuffer.

Valid Usage

  • dstOffset must be less than the size of dstBuffer

  • dataSize must be less than or equal to the size of dstBuffer minus dstOffset

  • dstBuffer must have been created with VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag

  • If dstBuffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • dstOffset must be a multiple of 4

  • dataSize must be less than or equal to 65536

  • dataSize must be a multiple of 4

  • If commandBuffer is an unprotected command buffer, then dstBuffer must not be a protected buffer

  • If commandBuffer is a protected command buffer, then dstBuffer must not be an unprotected buffer

Valid Usage (Implicit)

  • commandBuffer must be a valid VkCommandBuffer handle

  • dstBuffer must be a valid VkBuffer handle

  • pData must be a valid pointer to an array of dataSize bytes

  • commandBuffer must be in the recording state

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

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

  • dataSize must be greater than 0

  • Both of commandBuffer, and dstBuffer 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 that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Transfer
Graphics
Compute

Transfer
Note

The pData parameter was of type uint32_t* instead of void* prior to version 1.0.19 of the Specification and VK_HEADER_VERSION 19 of the Vulkan Header Files. This was a historical anomaly, as the source data may be of other types.