Package org.lwjgl.vulkan

Class NVAcquireWinrtDisplay

java.lang.Object
org.lwjgl.vulkan.NVAcquireWinrtDisplay
public class NVAcquireWinrtDisplay extends Object
This extension allows an application to take exclusive control of a display on Windows 10 provided that the display is not already controlled by a compositor. Examples of compositors include the Windows desktop compositor, other applications using this Vulkan extension, and applications that “Acquire” a “DisplayTarget” using a “WinRT” command such as “winrt::Windows::Devices::Display::Core::DisplayManager.TryAcquireTarget()”.

When control is acquired the application has exclusive access to the display until control is released or the application terminates. An application’s attempt to acquire is denied if a different application has already acquired the display.

Name String
VK_NV_acquire_winrt_display
Extension Type
Device extension
Registered Extension Number
346
Revision
1
Extension and Version Dependencies
VK_EXT_direct_mode_display
Contact
Other Extension Metadata
Last Modified Date
2020-09-29
IP Status
No known IP claims.
Contributors
  • Jeff Juliano, NVIDIA

  • Field Details

    • VK_NV_ACQUIRE_WINRT_DISPLAY_SPEC_VERSION

      public static final int VK_NV_ACQUIRE_WINRT_DISPLAY_SPEC_VERSION
      The extension specification version.
      See Also:

    • VK_NV_ACQUIRE_WINRT_DISPLAY_EXTENSION_NAME

      public static final String VK_NV_ACQUIRE_WINRT_DISPLAY_EXTENSION_NAME
      The extension name.
      See Also:

  • Method Details

    • vkAcquireWinrtDisplayNV

      public static int vkAcquireWinrtDisplayNV(org.lwjgl.vulkan.VkPhysicalDevice physicalDevice, long display)
      Acquire access to a VkDisplayKHR.
      C Specification

      To acquire permission to directly access a display in Vulkan on Windows 10, call:

      
 VkResult vkAcquireWinrtDisplayNV(
     VkPhysicalDevice                            physicalDevice,
     VkDisplayKHR                                display);
      Description

      All permissions necessary to control the display are granted to the Vulkan instance associated with 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 display. If this has happened, operations which require access to the display must fail with an appropriate error code. If permission to access display has already been acquired by another entity, the call must return the error code ERROR_INITIALIZATION_FAILED.

      Note

      The Vulkan instance acquires control of a “winrt::Windows::Devices::Display::Core::DisplayTarget” by performing an operation equivalent to “winrt::Windows::Devices::Display::Core::DisplayManager.TryAcquireTarget()” on the “DisplayTarget”.

      Note

      One example of when Windows 10 loses access to a display is when the display is hot-unplugged.

      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. AcquireWinrtDisplayNV does not itself cause DWM to release a display; this action must be performed outside of Vulkan.

      Valid Usage (Implicit)
      • physicalDevice must be a valid VkPhysicalDevice handle
      • display must be a valid VkDisplayKHR handle
      • display must have been created, allocated, or retrieved from physicalDevice
      Return Codes
      On success, this command returns
      On failure, this command returns
      Parameters:
      physicalDevice - The physical device the display is on.
      display - The display the caller wishes to control in Vulkan.

    • nvkGetWinrtDisplayNV

      public static int nvkGetWinrtDisplayNV(org.lwjgl.vulkan.VkPhysicalDevice physicalDevice, int deviceRelativeId, long pDisplay)
      Unsafe version of: GetWinrtDisplayNV

    • vkGetWinrtDisplayNV

      public static int vkGetWinrtDisplayNV(org.lwjgl.vulkan.VkPhysicalDevice physicalDevice, int deviceRelativeId, LongBuffer pDisplay)
      Query the VkDisplayKHR corresponding to a WinRT DisplayTarget.
      C Specification

      When acquiring displays on Windows 10, an application may also wish to enumerate and identify them using a native handle rather than a VkDisplayKHR handle.

      To determine the VkDisplayKHR handle corresponding to a “winrt::Windows::Devices::Display::Core::DisplayTarget”, call:

      
 VkResult vkGetWinrtDisplayNV(
     VkPhysicalDevice                            physicalDevice,
     uint32_t                                    deviceRelativeId,
     VkDisplayKHR*                               pDisplay);
      Description

      If there is no VkDisplayKHR corresponding to deviceRelativeId on physicalDevice, NULL_HANDLE must be returned in pDisplay.

      Valid Usage (Implicit)
      • physicalDevice must be a valid VkPhysicalDevice handle
      • pDisplay must be a valid pointer to a VkDisplayKHR handle
      Return Codes
      On success, this command returns
      On failure, this command returns
      Parameters:
      physicalDevice - The physical device on which to query the display handle.
      deviceRelativeId - The value of the “AdapterRelativeId” property of a “DisplayTarget” that is enumerated by a “DisplayAdapter” with an “Id” property matching the deviceLUID property of a VkPhysicalDeviceIDProperties for physicalDevice.
      pDisplay - The corresponding VkDisplayKHR handle will be returned here.

    • vkGetWinrtDisplayNV

      public static int vkGetWinrtDisplayNV(org.lwjgl.vulkan.VkPhysicalDevice physicalDevice, int deviceRelativeId, long[] pDisplay)
      Array version of: GetWinrtDisplayNV