19. Clear Commands
19.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);-
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.
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);-
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_GENERALorVK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL. -
pDepthStencilis 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). -
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.
Clears outside render pass instances are treated as transfer operations for the purposes of memory barriers.
19.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);-
commandBufferis the command buffer into which the command will be recorded. -
attachmentCountis the number of entries in thepAttachmentsarray. -
pAttachmentsis a pointer to an array of VkClearAttachment structures defining the attachments to clear and the clear values to use. -
rectCountis the number of entries in thepRectsarray. -
pRectsis a pointer to an array of VkClearRect structures defining regions within each selected attachment to clear.
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 is not a
transfer command.
It performs its operations in rasterization order.
For color attachments, the operations are executed as color attachment
writes, by the VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT stage.
For depth/stencil attachments, the operations are executed as
depth writes and stencil writes by
the VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT and
VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT stages.
vkCmdClearAttachments is not affected by the bound pipeline state.
|
Note
It is generally preferable to clear attachments by using the
|
If any attachment’s aspectMask to be cleared is not backed by an image
view, the clear has no effect on that aspect.
If an attachment being cleared refers to an image view created with an
aspectMask equal to one of VK_IMAGE_ASPECT_PLANE_0_BIT,
VK_IMAGE_ASPECT_PLANE_1_BIT or VK_IMAGE_ASPECT_PLANE_2_BIT, it
is considered to be VK_IMAGE_ASPECT_COLOR_BIT for purposes of this
command, and must be cleared with the VK_IMAGE_ASPECT_COLOR_BIT
aspect as specified by image view creation.
The VkClearRect structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkClearRect {
VkRect2D rect;
uint32_t baseArrayLayer;
uint32_t layerCount;
} VkClearRect;-
rectis the two-dimensional region to be cleared. -
baseArrayLayeris the first layer to be cleared. -
layerCountis 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;-
aspectMaskis a mask selecting the color, depth and/or stencil aspects of the attachment to be cleared. -
colorAttachmentis only meaningful ifVK_IMAGE_ASPECT_COLOR_BITis set inaspectMask, in which case it is an index into the currently bound color attachments. -
clearValueis the color or depth/stencil value to clear the attachment to, as described in Clear Values below.
19.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;-
float32are the color clear values when the format of the image or attachment is one of the numeric formats with a numeric type that is floating-point. 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. -
int32are the color clear values when the format of the image or attachment has a numeric type that 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. -
uint32are the color clear values when the format of the image or attachment has a numeric type that 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;-
depthis 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. -
stencilis 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.
The VkClearValue union is defined as:
// Provided by VK_VERSION_1_0
typedef union VkClearValue {
VkClearColorValue color;
VkClearDepthStencilValue depthStencil;
} VkClearValue;-
colorspecifies the color image clear values to use when clearing a color image or attachment. -
depthStencilspecifies 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.
19.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);-
commandBufferis the command buffer into which the command will be recorded. -
dstBufferis the buffer to be filled. -
dstOffsetis the byte offset into the buffer at which to start filling, and must be a multiple of 4. -
sizeis the number of bytes to fill, and must be either a multiple of 4, orVK_WHOLE_SIZEto fill the range fromoffsetto the end of the buffer. IfVK_WHOLE_SIZEis used and the remaining size of the buffer is not a multiple of 4, then the nearest smaller multiple is used. -
datais the 4-byte word written repeatedly to the buffer to fillsizebytes of data. The data word is written to memory according to the host endianness.
vkCmdFillBuffer is treated as a “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.
19.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);-
commandBufferis the command buffer into which the command will be recorded. -
dstBufferis a handle to the buffer to be updated. -
dstOffsetis the byte offset into the buffer to start updating, and must be a multiple of 4. -
dataSizeis the number of bytes to update, and must be a multiple of 4. -
pDatais a pointer to the source data for the buffer update, and must be at leastdataSizebytes 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 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
|
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 a “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.
|
Note
The |