284 lines
12 KiB
Plaintext
284 lines
12 KiB
Plaintext
// 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[]
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
The pname:pData parameter was of type basetype:uint32_t* instead of
|
|
basetype:void* prior to revision 1.0.19 of the Specification and
|
|
ename:VK_HEADER_VERSION 19 of +vulkan.h+. This was a
|
|
historical anomaly, as the source data may be of other types.
|
|
====
|
|
|
|
[[clears-end]]
|