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...
This commit is contained in:
Petr Kraus
parent
190c7c3d38
commit
ae56885102
|
|
@ -110,96 +110,99 @@ 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
|
||||
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.
|
||||
|
|
@ -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
|
||||
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.
|
||||
The application can: destroy pname:oldSwapchain to free all memory
|
||||
associated with pname:oldSwapchain.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
|
|
|
|||
Loading…
Reference in New Issue