registry/vulkan/chapters/VK_NV_acquire_winrt_display/acquire_winrt_display.txt

// Copyright (c) 2020 NVIDIA Corporation
//
// SPDX-License-Identifier: CC-BY-4.0

[open,refpage='vkAcquireWinrtDisplayNV',desc='Acquire access to a VkDisplayKHR',type='protos']
--
To acquire permission to directly access a display in Vulkan on Windows 10,
call:

include::{generated}/api/protos/vkAcquireWinrtDisplayNV.txt[]

  * pname:physicalDevice The physical device the display is on.
  * pname:display The display the caller wishes to control in Vulkan.

All permissions necessary to control the display are granted to the Vulkan
instance associated with pname:physicalDevice until the display is released
or the application is terminated.
Permission to access the display may: be revoked by events that cause
Windows 10 itself to lose access to pname:display.
If this has happened, operations which require access to the display must:
fail with an appropriate error code.
If permission to access pname:display has already been acquired by another
entity, the call must: return the error code
ename:VK_ERROR_INITIALIZATION_FAILED.

[NOTE]
.Note
====
The Vulkan instance acquires control of a
https://docs.microsoft.com/en-us/uwp/api/windows.devices.display.core.displaytarget["`winrt::Windows::Devices::Display::Core::DisplayTarget`"]
by performing an operation equivalent to
https://docs.microsoft.com/en-us/uwp/api/windows.devices.display.core.displaymanager.tryacquiretarget["`winrt::Windows::Devices::Display::Core::DisplayManager.TryAcquireTarget()`"]
on the "`DisplayTarget`".
====

[NOTE]
.Note
====
One example of when Windows 10 loses access to a display is when the display
is hot-unplugged.
====

[NOTE]
.Note
====
One example of when a display has already been acquired by another entity is
when the Windows desktop compositor (DWM) is in control of the display.
Beginning with Windows 10 version 2004 it is possible to cause DWM to
release a display by using the "`Advanced display settings`" sub-page of the
"`Display settings`" control panel.
flink:vkAcquireWinrtDisplayNV does not itself cause DWM to release a
display; this action must be performed outside of Vulkan.
====

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

[open,refpage='vkGetWinrtDisplayNV',desc='Query the VkDisplayKHR corresponding to a WinRT DisplayTarget',type='protos']
--
When acquiring displays on Windows 10, an application may also wish to
enumerate and identify them using a native handle rather than a
sname:VkDisplayKHR handle.

To determine the sname:VkDisplayKHR handle corresponding to a
https://docs.microsoft.com/en-us/uwp/api/windows.devices.display.core.displaytarget["`winrt::Windows::Devices::Display::Core::DisplayTarget`"],
call:

include::{generated}/api/protos/vkGetWinrtDisplayNV.txt[]

  * pname:physicalDevice The physical device on which to query the display
    handle.
  * pname:deviceRelativeId The value of the
    https://docs.microsoft.com/en-us/uwp/api/windows.devices.display.core.displaytarget.adapterrelativeid["`AdapterRelativeId`"]
    property of a
    https://docs.microsoft.com/en-us/uwp/api/windows.devices.display.core.displaytarget["`DisplayTarget`"]
    that is enumerated by a
    https://docs.microsoft.com/en-us/uwp/api/windows.devices.display.core.displayadapter["`DisplayAdapter`"]
    with an
    https://docs.microsoft.com/en-us/uwp/api/windows.devices.display.core.displayadapter.id["`Id`"]
    property matching the pname:deviceLUID property of a
    slink:VkPhysicalDeviceIDProperties for pname:physicalDevice.
  * pname:pDisplay The corresponding slink:VkDisplayKHR handle will be
    returned here.

If there is no slink:VkDisplayKHR corresponding to pname:deviceRelativeId on
pname:physicalDevice, dlink:VK_NULL_HANDLE must: be returned in
pname:pDisplay.

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