Jon Leech 82e0f83d43 Change log for February 10, 2017 Vulkan 1.0.40 spec update:
* Bump API patch number and header version number to 40 for this update.
  * There is a major build change in this release. We are now using the
    Ruby-based ``asciidoctor'' implementation, rather than the Python-based
    ``asciidoc'' implementation, to process the specification. While the
    actual specification markup changes were minimal, this requires a new
    set of build tools and a very different installation process, especially
    because we now use an experimental direct-to-PDF backend for Asciidoctor
    instead of Docbook->dblatex->PDF. It is no longer possible to build the
    Specification using asciidoc. See doc/specs/vulkan/README.adoc
    for some guidance on installing the new toolchain components.
  * There are some minor rendering issues in the PDF output due to teething
    problems with the asciidoctor toolchain, especially with mathematical
    equations. We are aware of these and working on them.

Github Issues:

  * Updated sample code for the <<sparsememory-examples-basic,sparse
    resource binding example>> (public issue 97).
  * Modify line and point clipping behavior in the
    <<vertexpostproc-clipping, Primitive Clipping>> section to allow for
    pop-free behavior. The ability to check for which behavior is
    implemented may be added a future feature or extension (public issue
    113).
  * Unify the discussions of implicit ordering throughout the spec, in
    particular in the new sections <<drawing-primitive-order, Primitive
    Order>>, <<primrast-order, Rasterization Order>>, and
    <<synchronization-implicit, Implicit Synchronization Guarantees>>; the
    discussion of <<synchronization-submission-order, submission order>>;
    and references elsewhere to these sections (public issue 133).
  * Clarify \<\<descriptorsets-compatibility,Pipeline Layout Compatibility>>
    language and introduce the term ``identically defined'' (public issue
    164).
  * Add a dependency to the +VK_EXT_debug_marker+ extension that's needed to
    reuse the object type enum from +VK_EXT_debug_report+, and moves the
    definition of that enum into +VK_EXT_debug_report+ where it should be
    (public issue 409).
  * Remove redundant valid usage statement from slink:VkImageBlit (public
    issue 421).
  * Update GL_KHR_vulkan_glsl to allow the ternary operator to result in a
    specialization constant (public issue 424).
  * Fix valid usage for flink:VkPipelineShaderStageCreateInfo (public issue
    426).
  * Correct typo in New Objects list for <<VK_EXT_debug_report>> (public
    issue 447).

Internal Issues:

  * Moved to asciidoctor for spec builds (internal issue 121).
  * Update style guide to describe where to put new extensions-specific
    asciidoc files, and what to name them (internal issue 626).
  * Add src/spec/indexExt.py to autogenerate registry index entries linking
    into the 1.0-extensions specification, instead of maintaining the index
    manually. (internal issue 642).
  * Autogenerate extension dependencies and lists of all extensions and all
    KHR extensions from the "supported" attributes in +vk.xml+. Execute
    +make config/extDependency.sh+ from +doc/specs/vulkan+ when a supported
    extension is added to vk.xml, to regenerate the dependency script. The
    consequence is that specifying a single extension to the +makeExt+
    script will automatically enable all extensions it depends on as well,
    and that the +makeAllExts+ and +makeKHR+ scripts do not need to be
    updated when a new extension is supported (internal issue 648).
  * Put extension appendices all at the same asciidoc section level, so KHR
    WSI extensions show up in the HTML index (internal issue 648).

Other Issues:

  * Imbed images in the generated HTML specs instead of loading them from
    the images/ directory.
  * Fix missing EXT in extension name
    (ename:VK_EXT_SWAPCHAIN_COLOR_SPACE_EXTENSION_NAME).
  * Add new +VK_EXT_SMPTE_2086_metadata+ extension.
  * In the <<platformCreateSurface_xlib,Xlib Surface>> section of the
    +VK_KHR_xlib_surface+ specification, add language warning users that
    they always need to call code:XinitThreads.
  * Use the term "presentable image" (rather than "swapchain image")
    consistently in +VK_KHR_swapchain+ and related extensions, and add a
    glossary term defining it.
  * Relocate the valid usage for samples of
    flink:vkGetPhysicalDeviceSparseImageFormatProperties2KHR::pname:pFormatInfo
    to be below the flink:VkPhysicalDeviceSparseImageFormatInfo2KHR
    structure.
2017-02-10 20:37:39 -08:00

430 lines
17 KiB
Plaintext

// Copyright (c) 2015-2017 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
****
ifdef::VK_KHR_maintenance1[]
* 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[]
* pname:image must: have been created with
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
* If pname:image is non-sparse then it must: be bound completely and
contiguously to a single sname:VkDeviceMemory object
* 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
****
ifdef::VK_KHR_maintenance1[]
* 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[]
* pname:image must: have been created with
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
* If pname:image is non-sparse then it must: be bound completely and
contiguously to a single sname:VkDeviceMemory object
* 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
ifndef::VK_KHR_maintenance1[]
* The sname:VkCommandPool that pname:commandBuffer was allocated from
must: support graphics or compute operations
endif::VK_KHR_maintenance1[]
* 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
// 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
* If pname:dstBuffer is non-sparse then it must: be bound completely and
contiguously to a single sname:VkDeviceMemory object
* 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.
====