mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-12 14:26:23 +00:00
279452463a
* Update release number to 92.
Public Issues:
* Move and modify valid usage statements dealing with pname:aspectMask in
flink:vkCmdClearColorImage, flink:vkCmdClearDepthStencilImage, and
slink:VkClearAttachment, so they are in places where all necessary
information is available (public issue 529).
* Fix math markup in <<textures-texel-anisotropic-filtering, Texel
Anisotropic Filtering>> (public pull request 840).
* Fix misspellings (public pull request 845).
Internal Issues:
* Add installation instructions and a Makefile "`chunked`" target for
chunked HTML generation (internal issue 1352).
* Fix pipeline mesh diagram style; also fix a minor bug in the classic
pipeline diagram where vertex/index buffers wrongly fed into the vertex
shader (internal issue 1436).
* Make asciidoctor ERROR output raise an error, and don't suppress
executed command output from CI make invocation (internal issue 1454).
* Minor typo fixes and clarifications for `VK_NV_raytracing`.
* Cleanup extension-specific properties
** Remove duplicated documentation for pname:maxDiscardRectangles,
pname:pointClippingBehavior, and pname:maxVertexAttribDivisor (they
shouldn't be documented with the other members of
slink:VkPhysicalDeviceLimits at all).
** Remove duplicate anchor for pname:maxVertexAttribDivisor
** Consistently document stext:VkPhysicalDevice<Extension>PropertiesKHR
*** Always document pname:sType/pname:pNext (was inconsistent before)
*** Always mention chaining to slink:VkPhysicalDeviceProperties2 (and not
as slink:VkPhysicalDeviceProperties2KHR)
*** Always include Valid Usage statements last
* Update Makefile 'checklinks' target and associated scripts, and fix
markup problems identified by checkLinks.py, so that we can rely on the
checklinks script as part of Gitlab CI.
615 lines
26 KiB
Plaintext
615 lines
26 KiB
Plaintext
// Copyright (c) 2015-2018 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>>.
|
|
|
|
Each specified range in pname:pRanges is cleared to the value specified by
|
|
pname:pColor.
|
|
|
|
.Valid Usage
|
|
****
|
|
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
|
|
* [[VUID-vkCmdClearColorImage-image-01993]]
|
|
The <<resources-image-format-features,format features>> of pname:image
|
|
must: contain ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT.
|
|
endif::VK_VERSION_1_1,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_VERSION_1_1,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_VERSION_1_1,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-aspectMask-02498]]
|
|
The slink:VkImageSubresourceRange::pname:aspectMask members of the
|
|
elements of the pname:pRanges array must: each only include
|
|
ename:VK_IMAGE_ASPECT_COLOR_BIT
|
|
* [[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
|
|
* [[VUID-vkCmdClearColorImage-pRanges-01692]]
|
|
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
|
|
* [[VUID-vkCmdClearColorImage-pRanges-01693]]
|
|
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
|
|
ifdef::VK_VERSION_1_1[]
|
|
* [[VUID-vkCmdClearColorImage-commandBuffer-01805]]
|
|
If pname:commandBuffer is an unprotected command buffer, then
|
|
pname:image must: not be a protected image
|
|
* [[VUID-vkCmdClearColorImage-commandBuffer-01806]]
|
|
If pname:commandBuffer is a protected command buffer, then pname:image
|
|
must: not be an unprotected image
|
|
endif::VK_VERSION_1_1[]
|
|
****
|
|
|
|
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>>.
|
|
|
|
.Valid Usage
|
|
****
|
|
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
|
|
* [[VUID-vkCmdClearDepthStencilImage-image-01994]]
|
|
The <<resources-image-format-features,format features>> of pname:image
|
|
must: contain ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT.
|
|
endif::VK_VERSION_1_1,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-aspectMask-02499]]
|
|
The slink:VkImageSubresourceRange::pname:aspectMask members of the
|
|
elements of the pname:pRanges array must: each only include
|
|
ename:VK_IMAGE_ASPECT_DEPTH_BIT if the image format has a depth
|
|
component
|
|
* [[VUID-vkCmdClearDepthStencilImage-aspectMask-02500]]
|
|
The slink:VkImageSubresourceRange::pname:aspectMask members of the
|
|
elements of the pname:pRanges array must: each only include
|
|
ename:VK_IMAGE_ASPECT_STENCIL_BIT if the image format has a stencil
|
|
component
|
|
* [[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
|
|
* [[VUID-vkCmdClearDepthStencilImage-pRanges-01694]]
|
|
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
|
|
* [[VUID-vkCmdClearDepthStencilImage-pRanges-01695]]
|
|
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
|
|
ifdef::VK_VERSION_1_1[]
|
|
* [[VUID-vkCmdClearDepthStencilImage-commandBuffer-01807]]
|
|
If pname:commandBuffer is an unprotected command buffer, then
|
|
pname:image must: not be a protected image
|
|
* [[VUID-vkCmdClearDepthStencilImage-commandBuffer-01808]]
|
|
If pname:commandBuffer is a protected command buffer, then pname:image
|
|
must: not be an unprotected image
|
|
endif::VK_VERSION_1_1[]
|
|
|
|
****
|
|
|
|
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 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.
|
|
If any attachment to be cleared in the current subpass is
|
|
ename:VK_ATTACHMENT_UNUSED, then the clear has no effect on that
|
|
attachment.
|
|
* 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-02501]]
|
|
If the pname:aspectMask member of any element of pname:pAttachments
|
|
contains ename:VK_IMAGE_ASPECT_COLOR_BIT, then the pname:colorAttachment
|
|
member of that element must: either refer to a color attachment which is
|
|
ename:VK_ATTACHMENT_UNUSED, or must: be a valid color attachment.
|
|
* [[VUID-vkCmdClearAttachments-aspectMask-02502]]
|
|
If the pname:aspectMask member of any element of pname:pAttachments
|
|
contains ename:VK_IMAGE_ASPECT_DEPTH_BIT, then the current subpass'
|
|
depth/stencil attachment must: either be ename:VK_ATTACHMENT_UNUSED, or
|
|
must: have a depth component
|
|
* [[VUID-vkCmdClearAttachments-aspectMask-02503]]
|
|
If the pname:aspectMask member of any element of pname:pAttachments
|
|
contains ename:VK_IMAGE_ASPECT_STENCIL_BIT, then the current subpass'
|
|
depth/stencil attachment must: either be ename:VK_ATTACHMENT_UNUSED, or
|
|
must: have a stencil component
|
|
* [[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
|
|
* [[VUID-vkCmdClearAttachments-layerCount-01934]]
|
|
The pname:layerCount member of each element of pname:pRects must: not be
|
|
`0`
|
|
ifdef::VK_VERSION_1_1[]
|
|
* [[VUID-vkCmdClearAttachments-commandBuffer-02504]]
|
|
If pname:commandBuffer is an unprotected command buffer, then each
|
|
attachment to be cleared must: not be a protected image.
|
|
* [[VUID-vkCmdClearAttachments-commandBuffer-02505]]
|
|
If pname:commandBuffer is a protected command buffer, then each
|
|
attachment to be cleared must: not be an unprotected image.
|
|
endif::VK_VERSION_1_1[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_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_VERSION_1_1,VK_KHR_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: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 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
|
|
ifdef::VK_EXT_image_drm_format_modifier[]
|
|
* [[VUID-VkClearAttachment-aspectMask-02246]]
|
|
pname:aspectMask must: not include
|
|
etext:VK_IMAGE_ASPECT_MEMORY_PLANE___i___BIT_EXT for any index __i__.
|
|
endif::VK_EXT_image_drm_format_modifier[]
|
|
* [[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.
|
|
|
|
.Valid Usage
|
|
****
|
|
ifdef::VK_EXT_depth_range_unrestricted[]
|
|
* [[VUID-VkClearDepthStencilValue-depth-00022]]
|
|
Unless the `<<VK_EXT_depth_range_unrestricted>>` extension is enabled
|
|
pname:depth must: be between `0.0` and `1.0`, inclusive
|
|
endif::VK_EXT_depth_range_unrestricted[]
|
|
ifndef::VK_EXT_depth_range_unrestricted[]
|
|
* [[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.
|
|
|
|
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_VERSION_1_1,VK_KHR_maintenance1[]
|
|
* [[VUID-vkCmdFillBuffer-commandBuffer-00030]]
|
|
The sname:VkCommandPool that pname:commandBuffer was allocated from
|
|
must: support graphics or compute operations
|
|
endif::VK_VERSION_1_1,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
|
|
ifdef::VK_VERSION_1_1[]
|
|
* [[VUID-vkCmdFillBuffer-commandBuffer-01811]]
|
|
If pname:commandBuffer is an unprotected command buffer, then
|
|
pname:dstBuffer must: not be a protected buffer
|
|
* [[VUID-vkCmdFillBuffer-commandBuffer-01812]]
|
|
If pname:commandBuffer is a protected command buffer, then
|
|
pname:dstBuffer must: not be an unprotected buffer
|
|
endif::VK_VERSION_1_1[]
|
|
****
|
|
|
|
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`
|
|
ifdef::VK_VERSION_1_1[]
|
|
* [[VUID-vkCmdUpdateBuffer-commandBuffer-01813]]
|
|
If pname:commandBuffer is an unprotected command buffer, then
|
|
pname:dstBuffer must: not be a protected buffer
|
|
* [[VUID-vkCmdUpdateBuffer-commandBuffer-01814]]
|
|
If pname:commandBuffer is a protected command buffer, then
|
|
pname:dstBuffer must: not be an unprotected buffer
|
|
endif::VK_VERSION_1_1[]
|
|
****
|
|
|
|
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 the <<boilerplate-headers,Vulkan Header Files>>.
|
|
This was a historical anomaly, as the source data may be of other types.
|
|
====
|