269 lines
11 KiB
Plaintext
269 lines
11 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 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 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 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 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. describe these
|
||
|
|
regions.
|
||
|
|
|
||
|
|
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 struct is defined as follows:
|
||
|
|
|
||
|
|
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 struct is defined as follows:
|
||
|
|
|
||
|
|
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.
|
||
|
|
* 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.
|
||
|
|
* 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 commands 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 definition of sname:VkClearColorValue is as follows:
|
||
|
|
|
||
|
|
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. The ftext:vkClear*Image commands do
|
||
|
|
not support compressed image formats.
|
||
|
|
|
||
|
|
include::../validity/structs/VkClearColorValue.txt[]
|
||
|
|
|
||
|
|
The definition of sname:VkClearDepthStencilValue is as follows:
|
||
|
|
|
||
|
|
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. For this the sname:VkClearValue union is
|
||
|
|
defined as follows:
|
||
|
|
|
||
|
|
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.
|
||
|
|
* 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]]
|