mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-12 15:04:10 +00:00
85184f305a
* Bump API patch number and header version number to 25 for this update.
* Structurally change the specification so that multiple extensions are
included in the +1.0+ git branch, and specifications will include or not
include those extensions at build time based on options passed to the
Makefile. See +doc/specs/vulkan/README.html+ and the ``Layers and
Extensions'' section of the ``Vulkan Documentation and Extensions''
document for more information on this change.
* Register and publish new extensions in the single-branch form:
** +VK_NV_external_memory_capabilities+
** +VK_NV_external_memory+
** +VK_NV_external_memory_win32+
** +VK_NV_win32_keyed_mutex+
Github Issues:
* Clarify description of GetInstanceProcAddr and GetDeviceProcAddr (public
issue 212).
* Add SPIR-V <<textures-operation-validation, instruction validation>> for
single-sampled images (public issue 316).
* Fix spelling of ``tesselation'' in a few places and note it as an
exception to the American spelling rules convention (public issue
327).
* Fix Makefile to create output directory for ``styleguide''
target (public issue 329).
* Fix numerous minor issues with incorrectly tags on enumerant names and
table titles (public issue 330).
* Generate specversion.txt date in UTC time and RFC 2822 format
(public issue 335).
* Convert link to the SPIR-V Specification for
flink:VkShaderModuleCreateInfo into an internal link to the normative
reference (public issue 336).
* Add ename:VK_ERROR_OUT_OF_MEMORY error code to
flink:vkCreateDebugReportCallbackEXT (public issue 337).
Internal Issues:
* Update style guide regarding use of code:NULL and dname:VK_NULL_HANDLE
(internal issue 393).
* Change the definition of latexmath:[$q$] in the
<<textures-image-level-selection,texture image level selection>> section
to be the index of the maximum defined level for the view, not the
number of levels in the view (internal issue 406).
* Allow developers to override dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE
with their own binary-compatible definition (internal issue 439).
* Fix +vk_platform.h+ conditional logic causing compile failure with some
Android compilers (internal issue 441).
* Implement the single-branch model as described above (internal issue
461).
Other Issues:
119 lines
5.7 KiB
Plaintext
119 lines
5.7 KiB
Plaintext
// Copyright (c) 2014-2016 Khronos Group. This work is licensed under a
|
|
// Creative Commons Attribution 4.0 International License; see
|
|
// http://creativecommons.org/licenses/by/4.0/
|
|
|
|
VkImageLayout(3)
|
|
================
|
|
|
|
Name
|
|
----
|
|
VkImageLayout - Layout of image and image subresources
|
|
|
|
C Specification
|
|
---------------
|
|
|
|
// refBegin VkImageLayout - Layout of image and image subresources
|
|
|
|
The set of image layouts consists of:
|
|
|
|
include::../api/enums/VkImageLayout.txt[]
|
|
|
|
|
|
Description
|
|
-----------
|
|
|
|
The type(s) of device access supported by each layout are:
|
|
|
|
* ename:VK_IMAGE_LAYOUT_UNDEFINED: Supports no device access. This layout
|
|
must: only be used as the pname:initialLayout member of
|
|
sname:VkImageCreateInfo or sname:VkAttachmentDescription, or as the pname:oldLayout
|
|
in an image transition. When transitioning out of this layout, the
|
|
contents of the memory are not guaranteed to be preserved.
|
|
* ename:VK_IMAGE_LAYOUT_PREINITIALIZED: Supports no device access. This
|
|
layout must: only be used as the pname:initialLayout member of
|
|
sname:VkImageCreateInfo or sname:VkAttachmentDescription, or as the
|
|
pname:oldLayout in an image transition. When transitioning out of this
|
|
layout, the contents of the memory are preserved. This
|
|
layout is intended to be used as the initial layout for an image whose
|
|
contents are written by the host, and hence the data can: be written to
|
|
memory immediately, without first executing a layout transition.
|
|
Currently, ename:VK_IMAGE_LAYOUT_PREINITIALIZED is only useful with
|
|
ename:VK_IMAGE_TILING_LINEAR images because there is not a standard
|
|
layout defined for ename:VK_IMAGE_TILING_OPTIMAL images.
|
|
* ename:VK_IMAGE_LAYOUT_GENERAL: Supports all types of device access.
|
|
* ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL: must: only be used as a
|
|
color or resolve attachment in a sname:VkFramebuffer. This layout is
|
|
valid only for image subresources of images created with the
|
|
ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT usage bit enabled.
|
|
* ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL: must: only be
|
|
used as a depth/stencil attachment in a sname:VkFramebuffer. This layout
|
|
is valid only for image subresources of images created with the
|
|
ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage bit enabled.
|
|
* ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL: must: only be
|
|
used as a read-only depth/stencil attachment in a sname:VkFramebuffer
|
|
and/or as a read-only image in a shader (which can: be read as a sampled
|
|
image, combined image/sampler and/or input attachment). This layout is
|
|
valid only for image subresources of images created with the
|
|
ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage bit enabled.
|
|
* ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL: must: only be used as a
|
|
read-only image in a shader (which can: be read as a sampled image,
|
|
combined image/sampler and/or input attachment). This layout is valid
|
|
only for image subresources of images created with the
|
|
ename:VK_IMAGE_USAGE_SAMPLED_BIT or
|
|
ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT usage bit enabled.
|
|
* ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL: must: only be used as a
|
|
source image of a transfer command (see the definition of
|
|
<<synchronization-transfer,ename:VK_PIPELINE_STAGE_TRANSFER_BIT>>).
|
|
This layout is valid only for image subresources of images created with
|
|
the ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage bit enabled.
|
|
* ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL: must: only be used as a
|
|
destination image of a transfer command. This layout is valid only for
|
|
image subresources of images created with the
|
|
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage bit enabled.
|
|
ifdef::VK_KHR_swapchain[]
|
|
include::../chapters/VK_KHR_swapchain/VkImageLayout_swapchain.txt[]
|
|
endif::VK_KHR_swapchain[]
|
|
|
|
For each mechanism of accessing an image in the API, there is a parameter or
|
|
structure member that controls the image layout used to access the image.
|
|
For transfer commands, this is a parameter to the command (see <<clears>>
|
|
and <<copies>>). For use as a framebuffer attachment, this is a member in
|
|
the substructures of the sname:VkRenderPassCreateInfo (see
|
|
<<renderpass,Render Pass>>). For use in a descriptor set, this is a member
|
|
in the sname:VkDescriptorImageInfo structure (see
|
|
<<descriptorsets-updates>>). At the time that any command buffer command
|
|
accessing an image executes on any queue, the layouts of the image
|
|
subresources that are accessed must: all match the layout specified via the
|
|
API controlling those accesses.
|
|
|
|
The image layout of each image subresource must: be well-defined at each
|
|
point in the image subresource's lifetime. This means that when performing a
|
|
layout transition on the image subresource, the old layout value must:
|
|
either equal the current layout of the image subresource (at the time the
|
|
transition executes), or else be ename:VK_IMAGE_LAYOUT_UNDEFINED (implying
|
|
that the contents of the image subresource need not be preserved). The new
|
|
layout used in a transition mustnot: be ename:VK_IMAGE_LAYOUT_UNDEFINED or
|
|
ename:VK_IMAGE_LAYOUT_PREINITIALIZED.
|
|
|
|
// refEnd VkImageLayout
|
|
|
|
|
|
See Also
|
|
--------
|
|
|
|
slink:VkAttachmentDescription, slink:VkAttachmentReference, slink:VkDescriptorImageInfo, slink:VkImageCreateInfo, slink:VkImageMemoryBarrier, flink:vkCmdBlitImage, flink:vkCmdClearColorImage, flink:vkCmdClearDepthStencilImage, flink:vkCmdCopyBufferToImage, flink:vkCmdCopyImage, flink:vkCmdCopyImageToBuffer, flink:vkCmdResolveImage
|
|
|
|
|
|
Document Notes
|
|
--------------
|
|
|
|
For more information, see the Vulkan Specification at URL
|
|
|
|
https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#VkImageLayout
|
|
|
|
This page is extracted from the Vulkan Specification.
|
|
Fixes and changes should be made to the Specification,not directly.
|
|
|
|
include::footer.txt[]
|
|
|