status-im
/
Vulkan-Docs
mirror of https://github.com/status-im/Vulkan-Docs.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #585 from krOoze/fix_wsi_param_descs 

Update VkSwapchainCreateInfoKHR descriptions
This commit is contained in:
Jon Leech 2017-10-26 16:07:52 -07:00 committed by GitHub
parent 5436521608 ae56885102
commit 50877099cb
1 changed files with 56 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt
View File

@ -110,106 +110,110 @@ include::../../api/structs/VkSwapchainCreateInfoKHR.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:flags is a bitmask of elink:VkSwapchainCreateFlagBitsKHR
indicating parameters of swapchain creation.
* pname:surface is the surface to which the swapchain will present images.
The swapchain is associated with pname:surface.
indicating parameters of the swapchain creation.
* pname:surface is the surface onto which the swapchain will present
images.
If the creation succeeds, the swapchain becomes associated with
pname:surface.
* pname:minImageCount is the minimum number of presentable images that the
application needs.
The platform will either create the swapchain with at least that many
images, or will fail to create the swapchain.
* pname:imageFormat is a slink:VkFormat that is valid for swapchains on
the specified surface.
* pname:imageColorSpace is a slink:VkColorSpaceKHR that is valid for
swapchains on the specified surface.
* pname:imageExtent is the non-zero size (in pixels) of the swapchain.
Behavior is platform-dependent when the image extent does not match the
surface's pname:currentExtent as returned by
The implementation will either create the swapchain with at least that
many images, or it will fail to create the swapchain.
* pname:imageFormat is a elink:VkFormat value specifying the format
the swapchain image(s) will be created with.
* pname:imageColorSpace is a slink:VkColorSpaceKHR value specifying the
way the swapchain interprets image data.
* pname:imageExtent is the size (in pixels) of the swapchain image(s).
The behavior is platform-dependent if the image extent does not match
the surface's pname:currentExtent as returned by
fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR.
[NOTE]
.Note
====
On some platforms, flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR can
return in slink:VkSurfaceCapabilitiesKHR a pname:currentExtent that has a
pname:width and/or pname:height equal to zero.
This can happen, e.g., while a native window object is minimized.
In this situation, the native window object may have to be restored from the
minimized state before a sname:VkSwapchainKHR can be created, because:
During some situations, sname:VkSwapchainKHR cannot: be created because of
the Valid Usage of the pname:imageExtent parameter.
* The pname:minImageExtent and pname:maxImageExtent values returned by
flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR may match the
pname:currentExtent.
* On some platforms, the pname:imageExtent member of
sname:VkSwapchainCreateInfoKHR must match the pname:currentExtent
returned by flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR.
The flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR may: return in
slink:VkSurfaceCapabilitiesKHR a pname:currentExtent that has the
pname:width and/or pname:height equal to 0, or that is less than its
counterpart in pname:minImageExtent.
Similarly, pname:maxImageExtent may: also have 0 values for pname:width
and/or pname:height.
For example, on some platforms that may: happen while an associated window
is minimized.
====
* pname:imageArrayLayers is the number of views in a multiview/stereo
surface.
For non-stereoscopic-3D applications, this value is 1.
* pname:imageUsage is a bitmask of elink:VkImageUsageFlagBits, indicating
how the application will use the swapchain's presentable images.
* pname:imageSharingMode is the sharing mode used for the images of the
* pname:imageUsage is a bitmask of elink:VkImageUsageFlagBits describing
the intended usage of the (acquired) swapchain images.
* pname:imageSharingMode is the sharing mode used for the image(s) of the
swapchain.
* pname:queueFamilyIndexCount is the number of queue families having
access to the images of the swapchain in case pname:imageSharingMode is
access to the image(s) of the swapchain when pname:imageSharingMode is
ename:VK_SHARING_MODE_CONCURRENT.
* pname:pQueueFamilyIndices is an array of queue family indices having
access to the images of the swapchain in case pname:imageSharingMode is
access to the images(s) of the swapchain when pname:imageSharingMode is
ename:VK_SHARING_MODE_CONCURRENT.
* pname:preTransform is a bitmask of elink:VkSurfaceTransformFlagBitsKHR,
* pname:preTransform is a elink:VkSurfaceTransformFlagBitsKHR value
describing the transform, relative to the presentation engine's natural
orientation, applied to the image content prior to presentation.
If it does not match the pname:currentTransform value returned by
fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR, the presentation engine
will transform the image content as part of the presentation operation.
* pname:compositeAlpha is a bitmask of elink:VkCompositeAlphaFlagBitsKHR
* pname:compositeAlpha is a elink:VkCompositeAlphaFlagBitsKHR value
indicating the alpha compositing mode to use when this surface is
composited together with other surfaces on certain window systems.
* pname:presentMode is the presentation mode the swapchain will use.
A swapchain's present mode determines how incoming present requests will
be processed and queued internally.
* pname:clipped indicates whether the Vulkan implementation is allowed to
discard rendering operations that affect regions of the surface which
discard rendering operations that affect regions of the surface that
are not visible.
** If set to ename:VK_TRUE, the presentable images associated with the
swapchain may: not own all of their pixels.
Pixels in the presentable images that correspond to regions of the
target surface obscured by another window on the desktop or subject to
target surface obscured by another window on the desktop, or subject to
some other clipping mechanism will have undefined content when read
back.
Pixel shaders may: not execute for these pixels, and thus any side
affects they would have had will not occur.
** If set to ename:VK_FALSE, presentable images associated with the
swapchain will own all the pixels they contain.
Setting this value to ename:VK_TRUE does not guarantee any clipping
effects they would have had will not occur.
ename:VK_TRUE value does not guarantee any clipping
will occur, but allows more optimal presentation methods to be used on
some platforms.
** If set to ename:VK_FALSE, presentable images associated with the
swapchain will own all of the pixels they contain.
[NOTE]
.Note
====
Applications should: set this value to ename:VK_TRUE if they do not expect
to read back the content of presentable images before presenting them or
after reacquiring them and if their pixel shaders do not have any side
after reacquiring them, and if their pixel shaders do not have any side
effects that require them to run for all pixels in the presentable image.
====
* pname:oldSwapchain, if not dlink:VK_NULL_HANDLE, specifies an existing
non-retired swapchain that is associated with surface.
* pname:oldSwapchain is dlink:VK_NULL_HANDLE, or the existing non-retired
swapchain currently associated with pname:surface.
Providing a valid pname:oldSwapchain may: aid in the resource reuse, and
also allows the application to still present any images that are already
acquired from it.
Upon calling fname:vkCreateSwapchainKHR with a pname:oldSwapchain that
is not dlink:VK_NULL_HANDLE, pname:oldSwapchain is retired, even if
creation of the new swapchain fails.
The new swapchain is created in the non-retired state whether or not
pname:oldSwapchain is dlink:VK_NULL_HANDLE.
Upon calling fname:vkCreateSwapchainKHR with a pname:oldSwapchain that
is not dlink:VK_NULL_HANDLE, pname:oldSwapchain is retired -- even if
creation of the new swapchain fails.
The new swapchain is created in the non-retired state whether or not
pname:oldSwapchain is dlink:VK_NULL_HANDLE.
Upon calling fname:vkCreateSwapchainKHR with a pname:oldSwapchain that
is not dlink:VK_NULL_HANDLE, any images from pname:oldSwapchain that are
not acquired by the application may: be freed by the implementation,
which may: occur even if creation of the new swapchain fails.
The application can: destroy pname:oldSwapchain to free all memory
associated with pname:oldSwapchain.
Upon calling fname:vkCreateSwapchainKHR with a pname:oldSwapchain that
is not dlink:VK_NULL_HANDLE, any images from pname:oldSwapchain that are
not acquired by the application may: be freed by the implementation,
which may: occur even if creation of the new swapchain fails.
The application must: destroy sname:oldSwapchain to free all memory
associated with sname:oldSwapchain.
[NOTE]
.Note
====