564 lines
23 KiB
Plaintext
564 lines
23 KiB
Plaintext
// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a
|
|
// Creative Commons Attribution 4.0 International License; see
|
|
// http://creativecommons.org/licenses/by/4.0/
|
|
|
|
[[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.
|
|
|
|
[open,refpage='vkCmdClearColorImage',desc='Clear regions of a color image',type='protos']
|
|
--
|
|
|
|
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
|
|
ifdef::VK_KHR_shared_presentable_image[]
|
|
ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
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
|
|
****
|
|
ifdef::VK_KHR_maintenance1[]
|
|
* [[VUID-vkCmdClearColorImage-image-00001]]
|
|
pname:image must: use a format that supports
|
|
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR, which is indicated by
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
|
|
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
|
|
optimally tiled images) - as returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties
|
|
endif::VK_KHR_maintenance1[]
|
|
* [[VUID-vkCmdClearColorImage-image-00002]]
|
|
pname:image must: have been created with
|
|
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkCmdClearColorImage-image-01545]]
|
|
pname:image must: not use a format listed in
|
|
<<features-formats-requiring-sampler-ycbcr-conversion>>
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkCmdClearColorImage-image-00003]]
|
|
If pname:image is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
* [[VUID-vkCmdClearColorImage-imageLayout-00004]]
|
|
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
|
|
ifndef::VK_KHR_shared_presentable_image[]
|
|
* [[VUID-vkCmdClearColorImage-imageLayout-00005]]
|
|
pname:imageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or
|
|
ename:VK_IMAGE_LAYOUT_GENERAL
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
ifdef::VK_KHR_shared_presentable_image[]
|
|
* [[VUID-vkCmdClearColorImage-imageLayout-01394]]
|
|
pname:imageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL,
|
|
ename:VK_IMAGE_LAYOUT_GENERAL, or
|
|
ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
* [[VUID-vkCmdClearColorImage-baseMipLevel-01470]]
|
|
The slink:VkImageSubresourceRange::pname:baseMipLevel members of the
|
|
elements of the pname:pRanges array must: each be less than the
|
|
pname:mipLevels specified in slink:VkImageCreateInfo when pname:image
|
|
was created
|
|
* For each slink:VkImageSubresourceRange element of pname:pRanges, if
|
|
the pname:levelCount member is not ename:VK_REMAINING_MIP_LEVELS, then
|
|
[eq]#pname:baseMipLevel {plus} pname:levelCount# must: be less than the
|
|
pname:mipLevels specified in slink:VkImageCreateInfo when pname:image
|
|
was created
|
|
* [[VUID-vkCmdClearColorImage-baseArrayLayer-01472]]
|
|
The slink:VkImageSubresourceRange::pname:baseArrayLayer members of the
|
|
elements of the pname:pRanges array must: each be less than the
|
|
pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image
|
|
was created
|
|
* For each slink:VkImageSubresourceRange element of pname:pRanges, if
|
|
the pname:layerCount member is not ename:VK_REMAINING_ARRAY_LAYERS, then
|
|
[eq]#pname:baseArrayLayer {plus} pname:layerCount# must: be less than
|
|
the pname:arrayLayers specified in slink:VkImageCreateInfo when
|
|
pname:image was created
|
|
* [[VUID-vkCmdClearColorImage-image-00007]]
|
|
pname:image must: not have a compressed or depth/stencil format
|
|
****
|
|
|
|
include::../validity/protos/vkCmdClearColorImage.txt[]
|
|
--
|
|
|
|
[open,refpage='vkCmdClearDepthStencilImage',desc='Fill regions of a combined depth/stencil image',type='protos']
|
|
--
|
|
|
|
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
|
|
****
|
|
ifdef::VK_KHR_maintenance1[]
|
|
* [[VUID-vkCmdClearDepthStencilImage-image-00008]]
|
|
pname:image must: use a format that supports
|
|
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR, which is indicated by
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
|
|
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
|
|
optimally tiled images) - as returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties
|
|
endif::VK_KHR_maintenance1[]
|
|
* [[VUID-vkCmdClearDepthStencilImage-image-00009]]
|
|
pname:image must: have been created with
|
|
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
|
|
* [[VUID-vkCmdClearDepthStencilImage-image-00010]]
|
|
If pname:image is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
* [[VUID-vkCmdClearDepthStencilImage-imageLayout-00011]]
|
|
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
|
|
* [[VUID-vkCmdClearDepthStencilImage-imageLayout-00012]]
|
|
pname:imageLayout must: be either of
|
|
ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or
|
|
ename:VK_IMAGE_LAYOUT_GENERAL
|
|
* [[VUID-vkCmdClearDepthStencilImage-baseMipLevel-01474]]
|
|
The slink:VkImageSubresourceRange::pname:baseMipLevel members of the
|
|
elements of the pname:pRanges array must: each be less than the
|
|
pname:mipLevels specified in slink:VkImageCreateInfo when pname:image
|
|
was created
|
|
* For each slink:VkImageSubresourceRange element of pname:pRanges, if
|
|
the pname:levelCount member is not ename:VK_REMAINING_MIP_LEVELS, then
|
|
[eq]#pname:baseMipLevel {plus} pname:levelCount# must: be less than the
|
|
pname:mipLevels specified in slink:VkImageCreateInfo when pname:image
|
|
was created
|
|
* [[VUID-vkCmdClearDepthStencilImage-baseArrayLayer-01476]]
|
|
The slink:VkImageSubresourceRange::pname:baseArrayLayer members of the
|
|
elements of the pname:pRanges array must: each be less than the
|
|
pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image
|
|
was created
|
|
* For each slink:VkImageSubresourceRange element of pname:pRanges, if
|
|
the pname:layerCount member is not ename:VK_REMAINING_ARRAY_LAYERS, then
|
|
[eq]#pname:baseArrayLayer {plus} pname:layerCount# must: be less than
|
|
the pname:arrayLayers specified in slink:VkImageCreateInfo when
|
|
pname:image was created
|
|
* [[VUID-vkCmdClearDepthStencilImage-image-00014]]
|
|
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
|
|
|
|
[open,refpage='vkCmdClearAttachments',desc='Clear regions within currently bound framebuffer attachments',type='protos']
|
|
--
|
|
|
|
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
|
|
****
|
|
* [[VUID-vkCmdClearAttachments-aspectMask-00015]]
|
|
If the pname:aspectMask member of any element of pname:pAttachments
|
|
contains ename:VK_IMAGE_ASPECT_COLOR_BIT, the pname:colorAttachment
|
|
member of that element must: refer to a valid color attachment in the
|
|
current subpass
|
|
* [[VUID-vkCmdClearAttachments-pRects-00016]]
|
|
The rectangular region specified by each element of pname:pRects must:
|
|
be contained within the render area of the current render pass instance
|
|
* [[VUID-vkCmdClearAttachments-pRects-00017]]
|
|
The layers specified by each element of pname:pRects must: be contained
|
|
within every attachment that pname:pAttachments refers to
|
|
ifdef::VK_KHX_multiview[]
|
|
* [[VUID-vkCmdClearAttachments-baseArrayLayer-00018]]
|
|
If the render pass instance this is recorded in uses multiview, then
|
|
pname:baseArrayLayer must: be zero and pname:layerCount must: be one.
|
|
endif::VK_KHX_multiview[]
|
|
****
|
|
|
|
include::../validity/protos/vkCmdClearAttachments.txt[]
|
|
--
|
|
|
|
[open,refpage='VkClearRect',desc='Structure specifying a clear rectangle',type='structs']
|
|
--
|
|
|
|
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[]
|
|
--
|
|
|
|
[open,refpage='VkClearAttachment',desc='Structure specifying a clear attachment',type='structs']
|
|
--
|
|
|
|
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
|
|
****
|
|
* [[VUID-VkClearAttachment-aspectMask-00019]]
|
|
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
|
|
* [[VUID-VkClearAttachment-aspectMask-00020]]
|
|
pname:aspectMask must: not include ename:VK_IMAGE_ASPECT_METADATA_BIT
|
|
* [[VUID-VkClearAttachment-clearValue-00021]]
|
|
pname:clearValue must: be a valid sname:VkClearValue union
|
|
****
|
|
|
|
include::../validity/structs/VkClearAttachment.txt[]
|
|
--
|
|
|
|
|
|
[[clears-values]]
|
|
== Clear Values
|
|
|
|
[open,refpage='VkClearColorValue',desc='Structure specifying a clear color value',type='structs']
|
|
--
|
|
|
|
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[]
|
|
--
|
|
|
|
[open,refpage='VkClearDepthStencilValue',desc='Structure specifying a clear depth stencil value',type='structs']
|
|
--
|
|
|
|
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.
|
|
|
|
ifndef::VK_EXT_depth_range_unrestricted[]
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkClearDepthStencilValue-depth-00022]]
|
|
pname:depth must: be between `0.0` and `1.0`, inclusive
|
|
****
|
|
|
|
endif::VK_EXT_depth_range_unrestricted[]
|
|
|
|
include::../validity/structs/VkClearDepthStencilValue.txt[]
|
|
--
|
|
|
|
[open,refpage='VkClearValue',desc='Structure specifying a clear value',type='structs']
|
|
--
|
|
|
|
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
|
|
****
|
|
* [[VUID-VkClearValue-depthStencil-00023]]
|
|
pname:depthStencil must: be a valid sname:VkClearDepthStencilValue
|
|
structure
|
|
****
|
|
|
|
include::../validity/structs/VkClearValue.txt[]
|
|
--
|
|
|
|
|
|
[[clears-filling-buffers]]
|
|
== Filling Buffers
|
|
|
|
[open,refpage='vkCmdFillBuffer',desc='Fill a region of a buffer with a fixed value',type='protos']
|
|
--
|
|
|
|
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
|
|
****
|
|
* [[VUID-vkCmdFillBuffer-dstOffset-00024]]
|
|
pname:dstOffset must: be less than the size of pname:dstBuffer
|
|
* [[VUID-vkCmdFillBuffer-dstOffset-00025]]
|
|
pname:dstOffset must: be a multiple of `4`
|
|
* [[VUID-vkCmdFillBuffer-size-00026]]
|
|
If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:size must: be
|
|
greater than `0`
|
|
* [[VUID-vkCmdFillBuffer-size-00027]]
|
|
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
|
|
* [[VUID-vkCmdFillBuffer-size-00028]]
|
|
If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:size must: be a
|
|
multiple of `4`
|
|
* [[VUID-vkCmdFillBuffer-dstBuffer-00029]]
|
|
pname:dstBuffer must: have been created with
|
|
ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag
|
|
ifndef::VK_KHR_maintenance1[]
|
|
* [[VUID-vkCmdFillBuffer-commandBuffer-00030]]
|
|
The sname:VkCommandPool that pname:commandBuffer was allocated from
|
|
must: support graphics or compute operations
|
|
endif::VK_KHR_maintenance1[]
|
|
* [[VUID-vkCmdFillBuffer-dstBuffer-00031]]
|
|
If pname:dstBuffer is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
****
|
|
|
|
include::../validity/protos/vkCmdFillBuffer.txt[]
|
|
--
|
|
|
|
|
|
[[clears-updating-buffers]]
|
|
== Updating Buffers
|
|
|
|
[open,refpage='vkCmdUpdateBuffer',desc='Update a buffer\'s contents from host memory',type='protos']
|
|
--
|
|
|
|
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>>.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Buffer updates performed with fname:vkCmdUpdateBuffer first copy the data
|
|
into command buffer memory when the command is recorded (which requires
|
|
additional storage and may incur an additional allocation), and then copy
|
|
the data from the command buffer into pname:dstBuffer when the command is
|
|
executed on a device.
|
|
|
|
The additional cost of this functionality compared to <<copies-buffers,
|
|
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
|
|
fname:vkCmdUpdateBuffer commands to different ranges of the same buffer, but
|
|
it is strongly recommended that they should: not.
|
|
====
|
|
|
|
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
|
|
****
|
|
* [[VUID-vkCmdUpdateBuffer-dstOffset-00032]]
|
|
pname:dstOffset must: be less than the size of pname:dstBuffer
|
|
* [[VUID-vkCmdUpdateBuffer-dataSize-00033]]
|
|
pname:dataSize must: be less than or equal to the size of
|
|
pname:dstBuffer minus pname:dstOffset
|
|
* [[VUID-vkCmdUpdateBuffer-dstBuffer-00034]]
|
|
pname:dstBuffer must: have been created with
|
|
ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag
|
|
* [[VUID-vkCmdUpdateBuffer-dstBuffer-00035]]
|
|
If pname:dstBuffer is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
* [[VUID-vkCmdUpdateBuffer-dstOffset-00036]]
|
|
pname:dstOffset must: be a multiple of `4`
|
|
* [[VUID-vkCmdUpdateBuffer-dataSize-00037]]
|
|
pname:dataSize must: be less than or equal to `65536`
|
|
* [[VUID-vkCmdUpdateBuffer-dataSize-00038]]
|
|
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.
|
|
====
|