summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorPetr Kraus <petr_kraus@email.cz>2017-10-18 20:23:54 +0200
committerPetr Kraus <petr_kraus@email.cz>2017-10-18 20:23:54 +0200
commitae568851029239361bfaac93e90e4d75e1c618a4 (patch)
tree87d3454245b5fe6703b01d76db20f8410438287e
parent190c7c3d3860996ba4d1da790588a11ed0c927c1 (diff)
downloadvulkan-spec-ae568851029239361bfaac93e90e4d75e1c618a4.zip
vulkan-spec-ae568851029239361bfaac93e90e4d75e1c618a4.tar.xz
Update VkSwapchainCreateInfoKHR descriptions
- fix `pretransform` and `compositeAlpha`; they are values not bitmasks - update `imageFormat`, `imageColorSpace`, `imageUsage` and `oldSwapchain` to be specific to behavior of this command - fix broken unintended code block - move `VK_TRUE` clipping text to correct bullet point - random tweaks...
-rw-r--r--doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt110
1 files changed, 57 insertions, 53 deletions
diff --git a/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt b/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt
index b61c440..5109ba0 100644
--- a/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt
+++ b/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt
@@ -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:
-
- * 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.
+During some situations, sname:VkSwapchainKHR cannot: be created because of
+the Valid Usage of the pname:imageExtent parameter.
+
+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, 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, 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 must: destroy sname:oldSwapchain to free all memory
- associated with sname:oldSwapchain.
[NOTE]
.Note
====