1// Copyright 2014-2022 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5If a swapchain is created with pname:presentMode set to either 6ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or 7ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR, a single presentable 8image can: be acquired, referred to as a shared presentable image. 9A shared presentable image may: be concurrently accessed by the application 10and the presentation engine, without transitioning the image's layout after 11it is initially presented. 12 13 * With ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR, the presentation 14 engine is only required to update to the latest contents of a shared 15 presentable image after a present. 16 The application must: call fname:vkQueuePresentKHR to guarantee an 17 update. 18 However, the presentation engine may: update from it at any time. 19 * With ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR, the 20 presentation engine will automatically present the latest contents of a 21 shared presentable image during every refresh cycle. 22 The application is only required to make one initial call to 23 fname:vkQueuePresentKHR, after which the presentation engine will update 24 from it without any need for further present calls. 25 The application can: indicate the image contents have been updated by 26 calling fname:vkQueuePresentKHR, but this does not guarantee the timing 27 of when updates will occur. 28 29The presentation engine may: access a shared presentable image at any time 30after it is first presented. 31To avoid tearing, an application should: coordinate access with the 32presentation engine. 33This requires presentation engine timing information through 34platform-specific mechanisms and ensuring that color attachment writes are 35made available during the portion of the presentation engine's refresh cycle 36they are intended for. 37 38[NOTE] 39.Note 40==== 41The `apiext:VK_KHR_shared_presentable_image` extension does not provide 42functionality for determining the timing of the presentation engine's 43refresh cycles. 44==== 45 46[open,refpage='vkGetSwapchainStatusKHR',desc='Get a swapchain\'s status',type='protos'] 47-- 48In order to query a swapchain's status when rendering to a shared 49presentable image, call: 50include::{generated}/api/protos/vkGetSwapchainStatusKHR.adoc[] 51 52 * pname:device is the device associated with pname:swapchain. 53 * pname:swapchain is the swapchain to query. 54 55include::{generated}/validity/protos/vkGetSwapchainStatusKHR.adoc[] 56-- 57 58The possible return values for fname:vkGetSwapchainStatusKHR should: be 59interpreted as follows: 60 61 * ename:VK_SUCCESS specifies the presentation engine is presenting the 62 contents of the shared presentable image, as per the swapchain's 63 elink:VkPresentModeKHR. 64 * ename:VK_SUBOPTIMAL_KHR the swapchain no longer matches the surface 65 properties exactly, but the presentation engine is presenting the 66 contents of the shared presentable image, as per the swapchain's 67 elink:VkPresentModeKHR. 68 * ename:VK_ERROR_OUT_OF_DATE_KHR the surface has changed in such a way 69 that it is no longer compatible with the swapchain. 70 * ename:VK_ERROR_SURFACE_LOST_KHR the surface is no longer available. 71 72[NOTE] 73.Note 74==== 75The swapchain state may: be cached by implementations, so applications 76should: regularly call fname:vkGetSwapchainStatusKHR when using a swapchain 77with elink:VkPresentModeKHR set to 78ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR. 79==== 80 81 82