status-im/Vulkan-Docs
2
0
Fork 0
mirror of https://github.com/status-im/Vulkan-Docs.git synced 2025-02-17 08:46:32 +00:00
Code Issues Projects Releases Wiki Activity
Vulkan-Docs/doc/specs/vulkan/chapters/clears.txt
Jon Leech ce60b9c887 Change log for March 7, 2018 Vulkan 1.1.70 spec update: 
* Vulkan 1.1 initial release. Bump API patch number and header version
    number to 70 for this update. The patch number will be used for both
    Vulkan 1.1 and Vulkan 1.0 updates, and continues to increment
    continuously from the previous Vulkan 1.0.69 update.

    NOTE: We are not publishing an updated 1.0.70 specification, or 1.1
    reference pages, along with 1.1.70. There are still minor issues to work
    out with those build targets. However, we will soon generate all three
    types of documents as part of the regular spec update cycle.

    NOTE: The GitHub KhronosGroup/Vulkan-Docs repository now maintains the
    current specification in the `master` branch. The `1.0` branch is out of
    date and will not be maintained, since we will be generating both 1.1
    and 1.0 specifications from the `master` branch in the future.

Github Issues:

  * Clarify how mapped memory ranges are flushed in
    flink:vkFlushMappedMemoryRanges (public issue 127).
  * Specify that <<synchronization-pipeline-stages, Pipeline Stages>> are a
    list of tasks that each command performs, rather than necessarily being
    discrete pieces of hardware that one task flows through. Add a
    "`synchronization command`" pipeline type which all synchronization
    command execute (it's just TOP + BOTTOM), with an explanatory note
    (public issue 554).

Internal Issues:

  * Regenerate all images used in the spec in Inkscape with a consistent
    look-and-feel, and adjust image size attributes so they're all legible,
    and not too large with respect to the spec body text (internal issue
    701).
  * Document in the <<extensions,extensions>> appendix and in the style
    guide that `KHX` extensions are no longer supported or used in the
    Vulkan 1.1 timeframe (internal issue 714).
  * Remove the leftover equations_temp directory after PDF build completes
    (internal issue 925).
  * Update the <<credits, Credits (Informative)>> appendix to include
    contributors to Vulkan 1.1, and to list them according to the API
    version(s) they contributed to (internal issue 987).
  * Add a NOTE to the introduction explaining that interfaces defined by
    extensions which were promoted to Vulkan 1.1 are now expressed as
    aliases of the Vulkan 1.1 type (internal issue 991).
  * Instrument spec source conditionals so spec can be built with 1.1
    features, extensions promoted to 1.1, or both (internal issues 992,
    998).
  * Modify the XML schema and tools to support explicit aliasing of types,
    structures, and commands, and use this to express the promotion of 1.0
    extensions to 1.1 core features, by making the extension interfaces
    aliases of the core features they were promoted to. Mark up promoted
    interfaces to allow still generating 1.0 + extension specifications
    (internal issue 991).
  * Platform names, along with corresponding preprocessor symbols to enable
    extensions specific to those platforms, are now reserved in vk.xml using
    the <platform> tag. Update the registry schema and schema specification
    to match (internal issue 1011).
  * Updated the <<textures-texel-replacement, Texel Replacement>> section to
    clarify that reads from invalid texels for image resources result in
    undefined values (internal issue 1014).
  * Modify description of patch version so it continues to increment across
    minor version changes (internal issue 1033).
  * Clarify and unify language describing physical device-level core and
    extension functionality in the <<fundamentals-validusage-extensions,
    Valid Usage for Extensions>>, <<fundamentals-validusage-versions, Valid
    Usage for Newer Core Versions>>, <<initialization-functionpointers
    Command Function Pointers>>, <<initialization-phys-dev-extensions,
    Extending Physical Device From Device Extensions>>
    <<extended-functionality-instance-extensions-and-devices, Instance
    Extensions and Device Extensions>> sections and for
    flink:vkGetPhysicalDeviceImageFormatProperties2. This documents that
    instance-level functionality is tied to the loader, and independent of
    the ICD; physical device-level functionality is tied to the ICD, and
    associated with device extensions; physical devices are treated more
    uniformly between core and extensions; and instance and physical
    versions can be different (internal issue 1048).
  * Updated the <<commandbuffers-lifecycle, Command Buffer Lifecycle>>
    section to clarify the ability for pending command buffers to transition
    to the invalid state after submission, and add a command buffer
    lifecycle diagram (internal issue 1050).
  * Clarify that some flink:VkDescriptorUpdateTemplateCreateInfo parameters
    are ignored when push descriptors are not supported (internal issue
    1054).
  * Specify that flink:vkCreateImage will return an error if the image is
    too large, in a NOTE in the slink:VkImageFormatProperties description
    (internal issue 1078).
  * Remove near-duplicate NOTEs about when to query function pointers
    dynamically in the <<initialization, Initialization>> chapter and
    replace by extending the NOTE in the <<fundamentals-abi, Application
    Binary Interface>> section (internal issue 1085).
  * Restore missing references to "`Sparse Resource Features`" in the
    flink:VkBufferCreateFlagBits description (internal issue 1086).
  * Tidy up definitions of descriptor types in the `GL_KHR_vulkan_glsl`
    specification, the <<descriptorsets, Resource Descriptors>> section and
    its subsections, and the <<interfaces-resources-descset, Descriptor Set
    Interface>> for consistency, reduction of duplicate information, and
    removal of GLSL correspondance/examples (internal issue 1090).
  * Correctly describe code:PrimitiveId as an Input for tessellation control
    and evaluation shaders, not an Output (internal issue 1109).
  * Relax the requirements on chroma offsets for nearest filtering in
    <<textures-implict-reconstruction, Implicit Reconstruction>> (internal
    issue 1116).

Other Issues:

  * Clarify the intended relationship between specification language and
    certain terms defined in the Khronos Intellectual Property Rights
    policy. Specific changes include:
  ** Rewrote IP/Copyright preamble and introduction to better agree with
     normative language both as laid out in the introduction, and the
     Khronos IPR policy.
  ** Added notion of fully informative sections, which are now tagged with
     "`(Informative)`" in their titles.
  ** Removed non-normative uses of the phrase "`not required`"
  ** Clarified the distinction between terms "`optional`" and "`not
     required:`" as they relate to the IPR Policy, and updated specification
     text to use terms consistent with the intent.
  ** Reduced additions to RFC 2119, and ensured the specification agreed
     with the leaner language.
  ** Removed the terms "`hardware`", "`software`", "`CPU`", and "`GPU`" from
     normative text.
  ** Moved several paragraphs that should not have been normative to
     informative notes.
  ** Clarified a number of definitions in the Glossary.
  ** Updated the document writing guide to match new terminology changes.
  * Explicitly state in the <<fundamentals-objectmodel-lifetime-acquire,
    application memory lifetime>> language that that for objects other than
    descriptor sets, a slink:VkDescriptorSetLayout object used in the
    creation of another object (such as slink:VkPipelineLayout or
    slink:VkDescriptorUpdateTemplateKHR) is only in use during the creation
    of that object and can be safely destroyed afterwards.
  * Updated the <<textures-scale-factor, Scale Factor Operation>> section to
    use the ratio of anisotropy, rather than the integer sample rate, to
    perform the LOD calculation. The spec still allows use of the sample
    rate as the value used to calculate the LOD, but no longer requires it.
  * Update `vulkan_ext.c` to include all platform-related definitions from
    the Vulkan platform headers, following the split of the headers into
    platform-specific and non-platform-specific files.
  * Fix bogus anchor name in the <<commandbuffers, Command Buffers>> chapter
    which accidentally duplicated an anchor in the pipelines chapter. There
    were no reference to this anchor, fortunately.
  * Add valid usage statement for slink:VkWriteDescriptorSet and
    slink:VkCopyDescriptorSet requiring that the slink:VkDescriptorSetLayout
    used to allocate the source and destination sets must not have been
    destroyed at the time flink:vkUpdateDescriptorSets is called.
  * Document mapping of subgroup barrier functions to SPIR-V, and clarify a
    place where subgroupBarrier sounds like it's execution-only in the
    standalone `GL_KHR_shader_subgroup` specification.
  * Use an HTML stylesheet derived from the Asciidoctor `colony` theme, with
    the default Arial font family replaced by the sans-serif Noto font
    family.
  * Numerous minor updates to README.adoc, build scripts, Makefiles, and
    registry and style guide specifications to support Vulkan 1.1 outputs,
    use them as defaults, and remove mention of `KHX` extensions, which are
    no longer supported.

New Extensions:

  * `VK_EXT_vertex_attrib_divisor`
2018-03-07 04:18:52 -08:00

603 lines
25 KiB
Plaintext
Raw Blame History

// 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>>.
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_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-vkCmdClearColorImage-image-00001]]
pname:image must: use a format that supports
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT, 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_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-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[]
* If pname:commandBuffer is an unprotected command buffer, then
pname:image must: not be a protected image
* 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>>.
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_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-vkCmdClearDepthStencilImage-image-00008]]
pname:image must: use a format that supports
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT, 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_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-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[]
* If pname:commandBuffer is an unprotected command buffer, then
pname:image must: not be a protected image
* 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 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_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: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
ifdef::VK_VERSION_1_1[]
* If pname:commandBuffer is an unprotected command buffer, then the
attachment to be cleared must: not be a protected image.
* If pname:commandBuffer is a protected command buffer, then the
attachment to be cleared must: not be an unprotected image.
endif::VK_VERSION_1_1[]
****
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.
.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_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[]
* If pname:commandBuffer is an unprotected command buffer, then
pname:dstBuffer must: not be a protected buffer
* 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[]
* If pname:commandBuffer is an unprotected command buffer, then
pname:dstBuffer must: not be a protected buffer
* 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.
====
Reference in New Issue View Git Blame Copy Permalink