mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-26 14:20:33 +00:00
1f875738fd
* Bump API patch number and header version number to 6 for this
update.
Github Issues:
* Define 'invocation group' for compute and graphics shaders. Cleanup
definition and use of 'workgroup', and add glossary entries (public
issue 1).
* Various minor editorial fixes (public issue 33).
* Clarify locations for block members in the
<<interfaces-iointerfaces-locations,Location Assignment>>
section (public issue 45).
* Editorial fixes for <<commandbuffer-allocation,Command Buffer
Allocation>> section (public issues 54, 59).
* Clarify behavior of depth test in the <<fragops-depth,Depth
Test>> section (public issues 80, 81).
* Remove discussion of return codes from
flink:vkGetPhysicalDeviceSparseImageFormatProperties and
flink:vkGetImageSparseMemoryRequirements, which don't return values
(public issue 82).
* Allow flink:vkCmdDrawIndirect and flink:vkCmdDrawIndexedIndirect
pname:drawCount of 0, as well as 1, when the multiDrawIndirect
feature is not supported (public issue 88).
* Remove confusing wording in the <<features-limits,Limits>>
section describing the slink:VkPhysicalDeviceLimits
pname:minTexelBufferOffsetAlignment,
pname:minUniformBufferOffsetAlignment, and
pname:minStorageBufferOffsetAlignment members as both minimums and
maximums (public issue 91).
* Clarified that only the RGB components should be affected in places
where sRGB is referred to in the spec, such as ASTC formats. Minor
re-wording to avoid "color space" when actively incorrect, now that
we refer to the Data Format Spec which actually makes a distinction
between color space and transfer function (public issue 94).
* Treat pname:pPropertyCount == 0 consistently in
flink:vkEnumerateInstanceLayerProperties and
flink:vkEnumerateDeviceLayerProperties (public issue 99)
* Cleanup minor editorial issues in chapters 14-17 (public issue 100).
* Clarify definition of flink:vkEnumerateInstanceExtensionProperties
and flink:vkEnumerateDeviceExtensionProperties (public issue 101).
* Define the flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties pname:pLayerName
parameter to be a pointer to a null-terminated UTF-8 string (public
issue 101).
* Rearrange "Missing information" references in mandatory format
tables (public issue 101).
* Clarify that the enumerated extensions returned by
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties will only include
extensions provided by the platform or extensions implemented in
implicitly enabled layers (public issue 101).
* Miscellaneous editorial fixes. Include the Vulkan spec patch number
in the PDF title. Fix label on <<fig-non-strict-lines,Non
strict lines>> diagram. Use more easily distinguished symbols in
tables in the <<features-required-format-support,Required
Format Support>> section. Don't require FQDNs used as layer names be
encoded in lower case if not possible, in the
<<extensions-naming-conventions, Extension and Layer Naming
Conventions>> section (public issues 101, 119, 121).
Internal Issues:
* Fixed excessive spacing in tables in XHTML (internal issue 18).
* Clarify that ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT
applies to secondary command buffers. Previously spec only referred
to the members of pname:pCommandBuffers being affected by this bit.
Added a separate slink:VkSubmitInfo Valid Usage restriction
specifying that ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT
also applies to any secondary command buffers that are recorded into
the primary command buffers in pname:pCommandBuffers (internal issue
106).
* Clarify that slink:VkDeviceCreateInfo::pname:pEnabledFeatures can be
NULL (internal issue 117).
* Remove "the value of" where it is redundant (e.g. speaking of an API
parameter, struct member, or SPIR-V variable, but not when speaking
of color components) (internal issue 175).
* Forced patch version to always be 0 in the header. Add a
"VK_API_VERSION_<major>_<minor>" macro for people to use to do the
right thing. Add a VK_HEADER_VERSION which captures the header
release number independent of the spec patch number (internal issue
176).
* Correct description of
slink:VkPipelineShaderStageCreateInfo::pname:pName to "a pointer to
a null-terminated UTF-8 string" (internal issue #197).
Other Commits:
* Updated DataFormat spec reference to the new date for revision 5 of
that spec.
* Fixed KEEP option (to retain LaTeX intermediate files) in the
Makefile to be included when edited there, as well as set on the
command line.
* Reserve and add "VK_IMG_filter_cubic" to the registry, and implement
script functionality to add and remove validity from existing
functions. Includes schema and readme changes.
* Update GL_KHR_vulkan_glsl so push_constants do not have descriptor
sets.
268 lines
11 KiB
Plaintext
268 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.
|
|
|
|
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]]
|