registry/vulkan/chapters/VK_KHR_shared_presentable_image/wsi.txt

// Copyright 2014-2021 The Khronos Group, Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

If a swapchain is created with pname:presentMode set to either
ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or
ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR, a single presentable
image can: be acquired, referred to as a shared presentable image.
A shared presentable image may: be concurrently accessed by the application
and the presentation engine, without transitioning the image's layout after
it is initially presented.

  * With ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR, the presentation
    engine is only required to update to the latest contents of a shared
    presentable image after a present.
    The application must: call fname:vkQueuePresentKHR to guarantee an
    update.
    However, the presentation engine may: update from it at any time.
  * With ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR, the
    presentation engine will automatically present the latest contents of a
    shared presentable image during every refresh cycle.
    The application is only required to make one initial call to
    fname:vkQueuePresentKHR, after which the presentation engine will update
    from it without any need for further present calls.
    The application can: indicate the image contents have been updated by
    calling fname:vkQueuePresentKHR, but this does not guarantee the timing
    of when updates will occur.

The presentation engine may: access a shared presentable image at any time
after it is first presented.
To avoid tearing, an application should: coordinate access with the
presentation engine.
This requires presentation engine timing information through
platform-specific mechanisms and ensuring that color attachment writes are
made available during the portion of the presentation engine’s refresh cycle
they are intended for.

[NOTE]
.Note
====
The `VK_KHR_shared_presentable_image` extension does not provide
functionality for determining the timing of the presentation engine's
refresh cycles.
====

[open,refpage='vkGetSwapchainStatusKHR',desc='Get a swapchain\'s status',type='protos']
--
In order to query a swapchain's status when rendering to a shared
presentable image, call:
include::{generated}/api/protos/vkGetSwapchainStatusKHR.txt[]

  * pname:device is the device associated with pname:swapchain.
  * pname:swapchain is the swapchain to query.

include::{generated}/validity/protos/vkGetSwapchainStatusKHR.txt[]
--

The possible return values for fname:vkGetSwapchainStatusKHR should: be
interpreted as follows:

  * ename:VK_SUCCESS specifies the presentation engine is presenting the
    contents of the shared presentable image, as per the swapchain's
    elink:VkPresentModeKHR.
  * ename:VK_SUBOPTIMAL_KHR the swapchain no longer matches the surface
    properties exactly, but the presentation engine is presenting the
    contents of the shared presentable image, as per the swapchain's
    elink:VkPresentModeKHR.
  * ename:VK_ERROR_OUT_OF_DATE_KHR the surface has changed in such a way
    that it is no longer compatible with the swapchain.
  * ename:VK_ERROR_SURFACE_LOST_KHR the surface is no longer available.

[NOTE]
.Note
====
The swapchain state may: be cached by implementations, so applications
should: regularly call fname:vkGetSwapchainStatusKHR when using a swapchain
with elink:VkPresentModeKHR set to
ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR.
====