diff --git a/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt b/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt index b61c4400..5109ba09 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: +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, 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 ====