Clear Commands
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 beVK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
,VK_IMAGE_LAYOUT_GENERAL
orVK_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 inpRanges
. -
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
.
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 beVK_IMAGE_LAYOUT_GENERAL
orVK_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 inpRanges
. -
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.
Clears outside render pass instances are treated as transfer operations for the purposes of memory barriers.
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 thepAttachments
array. -
pAttachments
is a pointer to an array of VkClearAttachment structures defining the attachments to clear and the clear values to use. -
rectCount
is the number of entries in thepRects
array. -
pRects
is 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.
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;
-
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 ifVK_IMAGE_ASPECT_COLOR_BIT
is set inaspectMask
, in which case it is an index into the currently bound color attachments. -
clearValue
is the color or depth/stencil value to clear the attachment to, as described in Clear Values below.
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 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. -
int32
are 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. -
uint32
are 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.
If the image or attachment format has a 64-bit component width, the first 2 array elements of each of the arrays above are reinterpreted as a single 64-bit element for the R component. The next 2 array elements are used in the same way for the G component. In other words, the union behaves as if it had the following additional members:
double float64[2];
int64_t int64[2];
uint64_t uint64[2];
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.
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.
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, orVK_WHOLE_SIZE
to fill the range fromoffset
to the end of the buffer. IfVK_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 fillsize
bytes 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
.
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 leastdataSize
bytes in size.
dataSize
must be less than or equal to 65536 bytes.
For larger updates, applications can use buffer to buffer
copies.
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 pData
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
.
The |