402 lines
16 KiB
Plaintext
402 lines
16 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.
|
|
|
|
// refBegin vkCmdClearColorImage Clear regions of a color image
|
|
|
|
To clear one or more subranges of a color image, call:
|
|
|
|
include::../api/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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* pname:image must: have been created with
|
|
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
|
|
* pname:imageLayout must: specify the layout of the image subresource
|
|
ranges of pname:image specified in pname:pRanges at the time this
|
|
command is executed on a sname:VkDevice
|
|
* pname:imageLayout must: be either of
|
|
ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or
|
|
ename:VK_IMAGE_LAYOUT_GENERAL
|
|
* The image range of any given element of pname:pRanges must: be an image
|
|
subresource range that is contained within pname:image
|
|
* pname:image must: not have a compressed or depth/stencil format
|
|
****
|
|
|
|
include::../validity/protos/vkCmdClearColorImage.txt[]
|
|
|
|
// refBegin vkCmdClearDepthStencilImage Fill regions of a combined depth-stencil image
|
|
|
|
To clear one or more subranges of a depth/stencil image, call:
|
|
|
|
include::../api/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).
|
|
|
|
.Valid Usage
|
|
****
|
|
* pname:image must: have been created with
|
|
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
|
|
* pname:imageLayout must: specify the layout of the image subresource
|
|
ranges of pname:image specified in pname:pRanges at the time this
|
|
command is executed on a sname:VkDevice
|
|
* pname:imageLayout must: be either of
|
|
ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or
|
|
ename:VK_IMAGE_LAYOUT_GENERAL
|
|
* The image range of any given element of pname:pRanges must: be an image
|
|
subresource range that is contained within pname:image
|
|
* pname:image must: have a depth/stencil format
|
|
****
|
|
|
|
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
|
|
|
|
// refBegin vkCmdClearAttachments Clear regions within currently bound framebuffer attachments
|
|
|
|
To clear one or more regions of color and depth/stencil attachments inside a
|
|
render pass instance, call:
|
|
|
|
include::../api/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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* If the pname:aspectMask member of any given element of
|
|
pname:pAttachments contains ename:VK_IMAGE_ASPECT_COLOR_BIT, the
|
|
pname:colorAttachment member of those elements must: refer to a valid
|
|
color attachment in the current subpass
|
|
* The rectangular region specified by a given element of pname:pRects
|
|
must: be contained within the render area of the current render pass
|
|
instance
|
|
* The layers specified by a given element of pname:pRects must: be
|
|
contained within every attachment that pname:pAttachments refers to
|
|
****
|
|
|
|
include::../validity/protos/vkCmdClearAttachments.txt[]
|
|
|
|
// refBegin VkClearRect Structure specifying a clear rectangle
|
|
|
|
The sname:VkClearRect structure is defined as:
|
|
|
|
include::../api/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 [eq]#[pname:baseArrayLayer, pname:baseArrayLayer {plus}
|
|
pname:layerCount)# counting from the base layer of the attachment image view
|
|
are cleared.
|
|
|
|
include::../validity/structs/VkClearRect.txt[]
|
|
|
|
// refBegin VkClearAttachment Structure specifying a clear attachment
|
|
|
|
The sname:VkClearAttachment structure is defined as:
|
|
|
|
include::../api/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 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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* If pname:aspectMask includes ename:VK_IMAGE_ASPECT_COLOR_BIT, it must:
|
|
not include ename:VK_IMAGE_ASPECT_DEPTH_BIT or
|
|
ename:VK_IMAGE_ASPECT_STENCIL_BIT
|
|
* pname:aspectMask must: not include ename:VK_IMAGE_ASPECT_METADATA_BIT
|
|
* pname:clearValue must: be a valid sname:VkClearValue union
|
|
****
|
|
|
|
include::../validity/structs/VkClearAttachment.txt[]
|
|
|
|
|
|
[[clears-values]]
|
|
== Clear Values
|
|
|
|
// refBegin VkClearColorValue Structure specifying a clear color value
|
|
|
|
The sname:VkClearColorValue structure is defined as:
|
|
|
|
include::../api/structs/VkClearColorValue.txt[]
|
|
|
|
* pname:float32 are the color clear values when the format of the image or
|
|
attachment is one of the formats in the
|
|
<<features-formats-numericformat, Interpretation of Numeric Format>>
|
|
table other than signed integer (etext:SINT) or unsigned integer
|
|
(etext:UINT).
|
|
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.
|
|
* pname:int32 are the color clear values when the format of the image or
|
|
attachment is signed integer (etext: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.
|
|
* pname:uint32 are the color clear values when the format of the image or
|
|
attachment is unsigned integer (etext: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.
|
|
|
|
include::../validity/structs/VkClearColorValue.txt[]
|
|
|
|
// refBegin VkClearDepthStencilValue Structure specifying a clear depth stencil value
|
|
|
|
The sname:VkClearDepthStencilValue structure is defined as:
|
|
|
|
include::../api/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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* pname:depth must: be between `0.0` and `1.0`, inclusive
|
|
****
|
|
|
|
include::../validity/structs/VkClearDepthStencilValue.txt[]
|
|
|
|
// refBegin VkClearValue Structure specifying a clear value
|
|
|
|
The sname:VkClearValue union is defined as:
|
|
|
|
include::../api/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 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 slink:VkRenderPassBeginInfo structure.
|
|
|
|
.Valid Usage
|
|
****
|
|
* pname:depthStencil must: be a valid sname:VkClearDepthStencilValue
|
|
structure
|
|
****
|
|
|
|
include::../validity/structs/VkClearValue.txt[]
|
|
|
|
|
|
[[clears-filling-buffers]]
|
|
== Filling Buffers
|
|
|
|
// refBegin vkCmdFillBuffer Fill a region of a buffer with a fixed value
|
|
|
|
To clear buffer data, call:
|
|
|
|
include::../api/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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* pname:dstOffset must: be less than the size of pname:dstBuffer
|
|
* pname:dstOffset must: be a multiple of `4`
|
|
* If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:size must: be
|
|
greater than `0`
|
|
* If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:size must: be
|
|
less than or equal to the size of pname:dstBuffer minus pname:dstOffset
|
|
* If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:size must: be a
|
|
multiple of `4`
|
|
* pname:dstBuffer must: have been created with
|
|
ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag
|
|
****
|
|
|
|
include::../validity/protos/vkCmdFillBuffer.txt[]
|
|
|
|
|
|
[[clears-updating-buffers]]
|
|
== Updating Buffers
|
|
|
|
// refBegin vkCmdUpdateBuffer Update a buffer's contents from host memory
|
|
|
|
To update buffer data inline in a command buffer, call:
|
|
|
|
include::../api/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 slink:VkBufferCreateInfo in order for the buffer to be compatible with
|
|
fname:vkCmdUpdateBuffer.
|
|
|
|
.Valid Usage
|
|
****
|
|
* pname:dstOffset must: be less than the size of pname:dstBuffer
|
|
* pname:dataSize must: be less than or equal to the size of
|
|
pname:dstBuffer minus pname:dstOffset
|
|
* pname:dstBuffer must: have been created with
|
|
ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag
|
|
* pname:dstOffset must: be a multiple of `4`
|
|
* pname:dataSize must: be less than or equal to `65536`
|
|
* pname:dataSize must: be a multiple of `4`
|
|
****
|
|
|
|
include::../validity/protos/vkCmdUpdateBuffer.txt[]
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
The pname:pData parameter was of type code:uint32_t*` instead of code:void*
|
|
prior to revision 1.0.19 of the Specification and dlink:VK_HEADER_VERSION 19
|
|
of +vulkan.h+.
|
|
This was a historical anomaly, as the source data may be of other types.
|
|
====
|