17. Clear Commands

17.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_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
  • 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 a format listed in Formats requiring sampler Y′CBCR conversion for VK_IMAGE_ASPECT_COLOR_BIT image views

  • 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-00005
    imageLayout must be 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 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 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-commandBuffer-01805
    If commandBuffer is an unprotected command buffer, then image must not be a protected image

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

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-pColor-parameter
    pColor must be a valid pointer to a valid VkClearColorValue union

  • 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-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 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
  • VUID-vkCmdClearDepthStencilImage-image-01994
    The format features of image must contain VK_FORMAT_FEATURE_TRANSFER_DST_BIT

  • VUID-vkCmdClearDepthStencilImage-image-00009
    image must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag

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

  • VUID-vkCmdClearDepthStencilImage-imageLayout-00011
    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-vkCmdClearDepthStencilImage-imageLayout-00012
    imageLayout must be either of VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

  • VUID-vkCmdClearDepthStencilImage-aspectMask-02824
    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

  • VUID-vkCmdClearDepthStencilImage-image-02825
    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

  • VUID-vkCmdClearDepthStencilImage-image-02826
    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

  • VUID-vkCmdClearDepthStencilImage-baseMipLevel-01474
    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-vkCmdClearDepthStencilImage-pRanges-01694
    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

  • VUID-vkCmdClearDepthStencilImage-baseArrayLayer-01476
    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-vkCmdClearDepthStencilImage-pRanges-01695
    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

  • VUID-vkCmdClearDepthStencilImage-image-00014
    image must have a depth/stencil format

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

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

Valid Usage (Implicit)
  • VUID-vkCmdClearDepthStencilImage-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdClearDepthStencilImage-image-parameter
    image must be a valid VkImage handle

  • VUID-vkCmdClearDepthStencilImage-imageLayout-parameter
    imageLayout must be a valid VkImageLayout value

  • VUID-vkCmdClearDepthStencilImage-pDepthStencil-parameter
    pDepthStencil must be a valid pointer to a valid VkClearDepthStencilValue structure

  • VUID-vkCmdClearDepthStencilImage-pRanges-parameter
    pRanges must be a valid pointer to an array of rangeCount valid VkImageSubresourceRange structures

  • VUID-vkCmdClearDepthStencilImage-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdClearDepthStencilImage-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdClearDepthStencilImage-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdClearDepthStencilImage-rangeCount-arraylength
    rangeCount must be greater than 0

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

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

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
  • VUID-vkCmdClearAttachments-aspectMask-02501
    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

  • VUID-vkCmdClearAttachments-aspectMask-02502
    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

  • VUID-vkCmdClearAttachments-aspectMask-02503
    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

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

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

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

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

  • VUID-vkCmdClearAttachments-layerCount-01934
    The layerCount member of each element of pRects must not be 0

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

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

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

Valid Usage (Implicit)
  • VUID-vkCmdClearAttachments-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdClearAttachments-pAttachments-parameter
    pAttachments must be a valid pointer to an array of attachmentCount valid VkClearAttachment structures

  • VUID-vkCmdClearAttachments-pRects-parameter
    pRects must be a valid pointer to an array of rectCount VkClearRect structures

  • VUID-vkCmdClearAttachments-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdClearAttachments-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdClearAttachments-renderpass
    This command must only be called inside of a render pass instance

  • VUID-vkCmdClearAttachments-attachmentCount-arraylength
    attachmentCount must be greater than 0

  • VUID-vkCmdClearAttachments-rectCount-arraylength
    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
  • VUID-VkClearAttachment-aspectMask-00019
    If aspectMask includes VK_IMAGE_ASPECT_COLOR_BIT, it must not include VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT

  • VUID-VkClearAttachment-aspectMask-00020
    aspectMask must not include VK_IMAGE_ASPECT_METADATA_BIT

  • VUID-VkClearAttachment-clearValue-00021
    clearValue must be a valid VkClearValue union

Valid Usage (Implicit)
  • VUID-VkClearAttachment-aspectMask-parameter
    aspectMask must be a valid combination of VkImageAspectFlagBits values

  • VUID-VkClearAttachment-aspectMask-requiredbitmask
    aspectMask must not be 0

17.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
  • VUID-VkClearDepthStencilValue-depth-02506
    depth must be between 0.0 and 1.0, inclusive

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.

17.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
  • VUID-vkCmdFillBuffer-dstOffset-00024
    dstOffset must be less than the size of dstBuffer

  • VUID-vkCmdFillBuffer-dstOffset-00025
    dstOffset must be a multiple of 4

  • VUID-vkCmdFillBuffer-size-00026
    If size is not equal to VK_WHOLE_SIZE, size must be greater than 0

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

  • VUID-vkCmdFillBuffer-size-00028
    If size is not equal to VK_WHOLE_SIZE, size must be a multiple of 4

  • VUID-vkCmdFillBuffer-dstBuffer-00029
    dstBuffer must have been created with VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag

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

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

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

Valid Usage (Implicit)
  • VUID-vkCmdFillBuffer-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdFillBuffer-dstBuffer-parameter
    dstBuffer must be a valid VkBuffer handle

  • VUID-vkCmdFillBuffer-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdFillBuffer-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics or compute operations

  • VUID-vkCmdFillBuffer-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdFillBuffer-commonparent
    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

Graphics
Compute

Transfer

17.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
  • VUID-vkCmdUpdateBuffer-dstOffset-00032
    dstOffset must be less than the size of dstBuffer

  • VUID-vkCmdUpdateBuffer-dataSize-00033
    dataSize must be less than or equal to the size of dstBuffer minus dstOffset

  • VUID-vkCmdUpdateBuffer-dstBuffer-00034
    dstBuffer must have been created with VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag

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

  • VUID-vkCmdUpdateBuffer-dstOffset-00036
    dstOffset must be a multiple of 4

  • VUID-vkCmdUpdateBuffer-dataSize-00037
    dataSize must be less than or equal to 65536

  • VUID-vkCmdUpdateBuffer-dataSize-00038
    dataSize must be a multiple of 4

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

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

Valid Usage (Implicit)
  • VUID-vkCmdUpdateBuffer-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdUpdateBuffer-dstBuffer-parameter
    dstBuffer must be a valid VkBuffer handle

  • VUID-vkCmdUpdateBuffer-pData-parameter
    pData must be a valid pointer to an array of dataSize bytes

  • VUID-vkCmdUpdateBuffer-commandBuffer-recording
    commandBuffer must be in the recording state

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

  • VUID-vkCmdUpdateBuffer-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdUpdateBuffer-dataSize-arraylength
    dataSize must be greater than 0

  • VUID-vkCmdUpdateBuffer-commonparent
    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.