clears.txt

// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html

[[clears]]
= Clear Commands


[[clears-outside]]
== Clearing Images Outside A Render Pass Instance

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

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

include::../protos/vkCmdClearColorImage.txt[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:image is the image to be cleared.
  * pname:imageLayout specifies the current layout of the image subresource
    ranges to be cleared, and must: be ename:VK_IMAGE_LAYOUT_GENERAL or
    ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL.
  * pname:pColor is a pointer to a slink:VkClearColorValue structure that
    contains the values the image subresource ranges will be cleared to (see
    <<clears-values>> below).
  * pname:rangeCount is the number of image subresource range structures in
    pname:pRanges.
  * pname:pRanges points to an array of slink:VkImageSubresourceRange
    structures that describe a range of mipmap levels, array layers, and
    aspects to be cleared, as described in <<resources-image-views,Image
    Views>>. The pname:aspectMask of all image subresource ranges must: only
    include ename:VK_IMAGE_ASPECT_COLOR_BIT.

Each specified range in pname:pRanges is cleared to the value specified by
pname:pColor.

include::../validity/protos/vkCmdClearColorImage.txt[]

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

include::../protos/vkCmdClearDepthStencilImage.txt[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:image is the image to be cleared.
  * pname:imageLayout specifies the current layout of the image subresource
    ranges to be cleared, and must: be ename:VK_IMAGE_LAYOUT_GENERAL or
    ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL.
  * pname:pDepthStencil is a pointer to a slink:VkClearDepthStencilValue
    structure that contains the values the depth and stencil image
    subresource ranges will be cleared to (see <<clears-values>> below).
  * pname:rangeCount is the number of image subresource range structures in
    pname:pRanges.
  * pname:pRanges points to an array of slink:VkImageSubresourceRange
    structures that describe a range of mipmap levels, array layers, and
    aspects to be cleared, as described in <<resources-image-views,Image
    Views>>. The pname:aspectMask of each image subresource range in
    pname:pRanges can: include ename:VK_IMAGE_ASPECT_DEPTH_BIT if the image
    format has a depth component, and ename:VK_IMAGE_ASPECT_STENCIL_BIT if
    the image format has a stencil component. pname:pDepthStencil is a
    pointer to a sname:VkClearDepthStencilValue structure that contains the
    values the image subresource ranges will be cleared to (see
    <<clears-values>> below).

include::../validity/protos/vkCmdClearDepthStencilImage.txt[]

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


[[clears-inside]]
== 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:

include::../protos/vkCmdClearAttachments.txt[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:attachmentCount is the number of entries in the pname:pAttachments
    array.
  * pname:pAttachments is a pointer to an array of slink:VkClearAttachment
    structures defining the attachments to clear and the clear values to
    use.
  * pname:rectCount is the number of entries in the pname:pRects array.
  * pname:pRects points to an array of slink:VkClearRect structures defining
    regions within each selected attachment to clear.

fname: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.

include::../validity/protos/vkCmdClearAttachments.txt[]

The sname:VkClearRect structure is defined as:

include::../structs/VkClearRect.txt[]

  * pname:rect is the two-dimensional region to be cleared.
  * pname:baseArrayLayer is the first layer to be cleared.
  * pname:layerCount is the number of layers to clear.

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

include::../validity/structs/VkClearRect.txt[]

The sname:VkClearAttachment structure is defined as:

include::../structs/VkClearAttachment.txt[]

  * pname:aspectMask is a mask selecting the color, depth and/or stencil
    aspects of the attachment to be cleared. pname:aspectMask can: include
    ename:VK_IMAGE_ASPECT_COLOR_BIT for color attachments,
    ename:VK_IMAGE_ASPECT_DEPTH_BIT for depth/stencil attachments with a
    depth component, and ename:VK_IMAGE_ASPECT_STENCIL_BIT for depth/stencil
    attachments with a stencil component. If the subpass's depth/stencil
    attachment is ename:VK_ATTACHMENT_UNUSED, then the clear has no effect.
  * pname:colorAttachment is only meaningful if
    ename:VK_IMAGE_ASPECT_COLOR_BIT is set in pname:aspectMask, in which
    case it is an index to the pname:pColorAttachments array in the
    slink:VkSubpassDescription structure of the current subpass which
    selects the color attachment to clear. If pname:colorAttachment is
    ename:VK_ATTACHMENT_UNUSED or is greater than or equal to
    sname:VkSubpassDescription::pname:colorAttachmentCount, then the clear has
    no effect.
  * pname:clearValue is the color or depth/stencil value to clear the
    attachment to, as described in <<clears-values,Clear Values>> below.

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

The fname: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 pname:loadOp (or pname:stencilLoadOp) of
slink:VkAttachmentDescription to ename:VK_ATTACHMENT_LOAD_OP_CLEAR, as
described for flink:vkCreateRenderPass.

include::../validity/structs/VkClearAttachment.txt[]


[[clears-values]]
== Clear Values

The sname:VkClearColorValue structure is defined as:

include::../structs/VkClearColorValue.txt[]

Color clear values are taken from the sname:VkClearColorValue union based on
the format of the image or attachment. Floating point, unorm, snorm,
uscaled, packed float, and sRGB images use the pname:float32 member,
unsigned integer formats use the pname:uint32 member, and signed integer
formats use the pname:int32 member. 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.

Unsigned integer values are converted to the format of the image by casting
to the integer type with fewer bits. 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.

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.

include::../validity/structs/VkClearColorValue.txt[]

The sname:VkClearDepthStencilValue structure is defined as:

include::../structs/VkClearDepthStencilValue.txt[]

  * pname: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.
  * pname: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.

include::../validity/structs/VkClearDepthStencilValue.txt[]

Some parts of the API require either color or depth/stencil clear values,
depending on the attachment. The sname:VkClearValue union represents such
values.

The sname:VkClearValue union is defined as:

include::../structs/VkClearValue.txt[]

  * pname:color specifies the color image clear values to use when
    clearing a color image or attachment.
  * pname:depthStencil specifies the depth and stencil clear values to use
    when clearing a depth/stencil image or attachment.

This union is used to define the initial clear values in the
sname:VkRenderPassBeginInfo structure.

include::../validity/structs/VkClearValue.txt[]


[[clears-filling-buffers]]
== Filling Buffers

To clear buffer data, call:

include::../protos/vkCmdFillBuffer.txt[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:dstBuffer is the buffer to be filled.
  * pname:dstOffset is the byte offset into the buffer at which to start
    filling, and must: be a multiple of 4.
  * pname:size is the number of bytes to fill, and must: be either a
    multiple of 4, or ename:VK_WHOLE_SIZE to fill the range from
    pname:offset to the end of the buffer. If ename: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.
  * pname:data is the 4-byte word written repeatedly to the buffer to fill
    pname:size bytes of data. The data word is written to memory according
    to the host endianness.

fname:vkCmdFillBuffer is treated as ``transfer'' operation for the purposes
of synchronization barriers. The ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT
must: be specified in pname:usage of sname:VkBufferCreateInfo in order for
the buffer to be compatible with fname:vkCmdFillBuffer.

include::../validity/protos/vkCmdFillBuffer.txt[]


[[clears-updating-buffers]]
== Updating Buffers

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

include::../protos/vkCmdUpdateBuffer.txt[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:dstBuffer is a handle to the buffer to be updated.
  * pname:dstOffset is the byte offset into the buffer to start updating,
    and must: be a multiple of 4.
  * pname:dataSize is the number of bytes to update, and must: be a multiple
    of 4.
  * pname:pData is a pointer to the source data for the buffer update, and
    must: be at least pname:dataSize bytes in size.

pname:dataSize must: be less than or equal to 65536 bytes. For larger
updates, applications can: use buffer to buffer <<copies-buffers,copies>>.

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

fname:vkCmdUpdateBuffer is only allowed outside of a render pass. This
command is treated as ``transfer'' operation, for the purposes of
synchronization barriers. The ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT must:
be specified in pname:usage of sname:VkBufferCreateInfo in order for the
buffer to be compatible with fname:vkCmdUpdateBuffer.

include::../validity/protos/vkCmdUpdateBuffer.txt[]

[[clears-end]]