vulkan-3.26.1: Bindings to the Vulkan graphics API.
Safe HaskellSafe-Inferred
LanguageHaskell2010

Vulkan.Extensions.VK_NV_acquire_winrt_display

Description

Name

VK_NV_acquire_winrt_display - device extension

VK_NV_acquire_winrt_display

Name String
VK_NV_acquire_winrt_display
Extension Type
Device extension
Registered Extension Number
346
Revision
1
Ratification Status
Not ratified
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

Description

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.

New Commands

New Enum Constants

Issues

1) What should the platform substring be for this extension:

RESOLVED: The platform substring is “Winrt”.

The substring “Winrt” matches the fact that the OS API exposing the acquire and release functionality is called “WinRT”.

The substring “Win32” is wrong because the related “WinRT” API is explicitly not a “Win32” API. “WinRT” is a competing API family to the “Win32” API family.

The substring “Windows” is suboptimal because there could be more than one relevant API on the Windows platform. There is preference to use the more-specific substring “Winrt”.

2) Should acquireWinrtDisplayNV take a winRT DisplayTarget, or a Vulkan display handle as input?

RESOLVED: A Vulkan display handle. This matches the design of acquireXlibDisplayEXT.

3) Should the acquire command be platform-independent named “vkAcquireDisplayNV”, or platform-specific named “vkAcquireWinrtDisplayNV”?

RESOLVED: Add a platform-specific command.

The inputs to the Acquire command are all Vulkan types. None are WinRT types. This opens the possibility of the winrt extension defining a platform-independent acquire command.

The X11 acquire command does need to accept a platform-specific parameter. This could be handled by adding to a platform-independent acquire command a params struct to which platform-dependent types can be chained by pNext pointer.

The prevailing opinion is that it would be odd to create a second platform-independent function that is used on the Windows 10 platform, but that is not used for the X11 platform. Since a Windows 10 platform-specific command is needed anyway for converting between vkDisplayKHR and platform-native handles, opinion was to create a platform-specific acquire function.

4) Should the getWinrtDisplayNV parameter identifying a display be named “deviceRelativeId” or “adapterRelativeId”?

RESOLVED: The WinRT name is “AdapterRelativeId”. The name “adapter” is the Windows analog to a Vulkan “physical device”. Vulkan already has precedent to use the name deviceLUID for the concept that Windows APIs call “AdapterLuid”. Keeping form with this precedent, the name “deviceRelativeId” is chosen.

5) Does acquireWinrtDisplayNV cause the Windows desktop compositor to release a display?

RESOLVED: No. acquireWinrtDisplayNV does not itself cause the Windows desktop compositor to release a display. This action must be performed outside of Vulkan.

Beginning with Windows 10 version 2004 it is possible to cause the Windows desktop compositor to release a display by using the “Advanced display settings” sub-page of the “Display settings” control panel. See https://docs.microsoft.com/en-us/windows-hardware/drivers/display/specialized-monitors

6) Where can one find additional information about custom compositors for Windows 10?

RESOLVED: Relevant references are as follows.

According to Microsoft’s documentation on "building a custom compositor", the ability to write a custom compositor is not a replacement for a fullscreen desktop window. The feature is for writing compositor apps that drive specialized hardware.

Only certain editions of Windows 10 support custom compositors, "documented here". The product type can be queried from Windows 10. See https://docs.microsoft.com/en-us/windows/win32/api/sysinfoapi/nf-sysinfoapi-getproductinfo

Version History

  • Revision 1, 2020-09-29 (Jeff Juliano)

    • Initial draft

See Also

acquireWinrtDisplayNV, getWinrtDisplayNV

Document Notes

For more information, see the Vulkan Specification

This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.

Synopsis

Documentation

acquireWinrtDisplayNV Source #

Arguments

:: forall io. MonadIO io 
=> PhysicalDevice

physicalDevice The physical device the display is on.

physicalDevice must be a valid PhysicalDevice handle

-> DisplayKHR

display The display the caller wishes to control in Vulkan.

display must be a valid DisplayKHR handle

display must have been created, allocated, or retrieved from physicalDevice

-> io () 

vkAcquireWinrtDisplayNV - Acquire access to a VkDisplayKHR

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.

Return Codes

Success
Failure

See Also

VK_NV_acquire_winrt_display, DisplayKHR, PhysicalDevice

getWinrtDisplayNV Source #

Arguments

:: forall io. MonadIO io 
=> PhysicalDevice

physicalDevice The physical device on which to query the display handle.

physicalDevice must be a valid PhysicalDevice handle

-> ("deviceRelativeId" ::: Word32)

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 PhysicalDeviceIDProperties for physicalDevice.

-> io DisplayKHR 

vkGetWinrtDisplayNV - Query the VkDisplayKHR corresponding to a WinRT DisplayTarget

Description

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

Return Codes

Success
Failure

See Also

VK_NV_acquire_winrt_display, DisplayKHR, PhysicalDevice

type NV_ACQUIRE_WINRT_DISPLAY_EXTENSION_NAME = "VK_NV_acquire_winrt_display" Source #

newtype DisplayKHR Source #

Constructors

DisplayKHR Word64 

Instances

Instances details
Storable DisplayKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

Show DisplayKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

Eq DisplayKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

Ord DisplayKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

HasObjectType DisplayKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

IsHandle DisplayKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

Zero DisplayKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles