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

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

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