1// Copyright (c) 2020 NVIDIA Corporation 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[open,refpage='vkAcquireWinrtDisplayNV',desc='Acquire access to a VkDisplayKHR',type='protos'] 6-- 7To acquire permission to directly access a display in Vulkan on Windows 10, 8call: 9 10include::{generated}/api/protos/vkAcquireWinrtDisplayNV.txt[] 11 12 * pname:physicalDevice The physical device the display is on. 13 * pname:display The display the caller wishes to control in Vulkan. 14 15All permissions necessary to control the display are granted to the Vulkan 16instance associated with pname:physicalDevice until the display is released 17or the application is terminated. 18Permission to access the display may: be revoked by events that cause 19Windows 10 itself to lose access to pname:display. 20If this has happened, operations which require access to the display must: 21fail with an appropriate error code. 22If permission to access pname:display has already been acquired by another 23entity, the call must: return the error code 24ename:VK_ERROR_INITIALIZATION_FAILED. 25 26[NOTE] 27.Note 28==== 29The Vulkan instance acquires control of a 30https://docs.microsoft.com/en-us/uwp/api/windows.devices.display.core.displaytarget["`winrt::Windows::Devices::Display::Core::DisplayTarget`"] 31by performing an operation equivalent to 32https://docs.microsoft.com/en-us/uwp/api/windows.devices.display.core.displaymanager.tryacquiretarget["`winrt::Windows::Devices::Display::Core::DisplayManager.TryAcquireTarget()`"] 33on the "`DisplayTarget`". 34==== 35 36[NOTE] 37.Note 38==== 39One example of when Windows 10 loses access to a display is when the display 40is hot-unplugged. 41==== 42 43[NOTE] 44.Note 45==== 46One example of when a display has already been acquired by another entity is 47when the Windows desktop compositor (DWM) is in control of the display. 48Beginning with Windows 10 version 2004 it is possible to cause DWM to 49release a display by using the "`Advanced display settings`" sub-page of the 50"`Display settings`" control panel. 51flink:vkAcquireWinrtDisplayNV does not itself cause DWM to release a 52display; this action must be performed outside of Vulkan. 53==== 54 55include::{generated}/validity/protos/vkAcquireWinrtDisplayNV.txt[] 56-- 57 58[open,refpage='vkGetWinrtDisplayNV',desc='Query the VkDisplayKHR corresponding to a WinRT DisplayTarget',type='protos'] 59-- 60When acquiring displays on Windows 10, an application may also wish to 61enumerate and identify them using a native handle rather than a 62sname:VkDisplayKHR handle. 63 64To determine the sname:VkDisplayKHR handle corresponding to a 65https://docs.microsoft.com/en-us/uwp/api/windows.devices.display.core.displaytarget["`winrt::Windows::Devices::Display::Core::DisplayTarget`"], 66call: 67 68include::{generated}/api/protos/vkGetWinrtDisplayNV.txt[] 69 70 * pname:physicalDevice The physical device on which to query the display 71 handle. 72 * pname:deviceRelativeId The value of the 73 https://docs.microsoft.com/en-us/uwp/api/windows.devices.display.core.displaytarget.adapterrelativeid["`AdapterRelativeId`"] 74 property of a 75 https://docs.microsoft.com/en-us/uwp/api/windows.devices.display.core.displaytarget["`DisplayTarget`"] 76 that is enumerated by a 77 https://docs.microsoft.com/en-us/uwp/api/windows.devices.display.core.displayadapter["`DisplayAdapter`"] 78 with an 79 https://docs.microsoft.com/en-us/uwp/api/windows.devices.display.core.displayadapter.id["`Id`"] 80 property matching the pname:deviceLUID property of a 81 slink:VkPhysicalDeviceIDProperties for pname:physicalDevice. 82 * pname:pDisplay The corresponding slink:VkDisplayKHR handle will be 83 returned here. 84 85If there is no slink:VkDisplayKHR corresponding to pname:deviceRelativeId on 86pname:physicalDevice, dlink:VK_NULL_HANDLE must: be returned in 87pname:pDisplay. 88 89include::{generated}/validity/protos/vkGetWinrtDisplayNV.txt[] 90-- 91