mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-12 23:14:20 +00:00
1ca0ea1ef0
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
299 lines
12 KiB
Plaintext
299 lines
12 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.
|
|
|
|
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).
|
|
|
|
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.
|
|
|
|
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 latexmath:[$[baseArrayLayer, baseArrayLayer+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 or is greater than or equal to
|
|
sname:VkSubpassDescription::pname:colorAttachmentCount, 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.
|
|
|
|
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 floating point, unorm, snorm, uscaled, packed float, or
|
|
sRGB. 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. 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. 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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
include::../validity/protos/vkCmdUpdateBuffer.txt[]
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
The pname:pData parameter was of type basetype:uint32_t* instead of
|
|
basetype: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.
|
|
====
|