83 lines
3.4 KiB
Plaintext
83 lines
3.4 KiB
Plaintext
// Copyright (c) 2014-2019 Khronos Group. This work is licensed under a
|
||
// Creative Commons Attribution 4.0 International License; see
|
||
// http://creativecommons.org/licenses/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::../../api/protos/vkGetSwapchainStatusKHR.txt[]
|
||
|
||
* pname:device is the device associated with pname:swapchain.
|
||
* pname:swapchain is the swapchain to query.
|
||
|
||
include::../../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.
|
||
====
|
||
|
||
|