Name

VK_KHR_win32_surface - instance extension

VK_KHR_win32_surface

Name String

VK_KHR_win32_surface

Extension Type

Instance extension

Registered Extension Number

10

Revision

6

Extension and Version Dependencies

• Requires Vulkan 1.0
• Requires VK_KHR_surface

Contact

• Jesse Hall https://github.com/KhronosGroup/Vulkan-Docs/issues/new?title=VK_KHR_win32_surface:%20&body=@critsec%20
• Ian Elliott https://github.com/KhronosGroup/Vulkan-Docs/issues/new?title=VK_KHR_win32_surface:%20&body=@ianelliottus%20

Other Extension Metadata

Last Modified Date

2017-04-24

IP Status

No known IP claims.

Contributors

• Patrick Doane, Blizzard
• Jason Ekstrand, Intel
• Ian Elliott, LunarG
• Courtney Goeltzenleuchter, LunarG
• Jesse Hall, Google
• James Jones, NVIDIA
• Antoine Labour, Google
• Jon Leech, Khronos
• David Mao, AMD
• Norbert Nopper, Freescale
• Alon Or-bach, Samsung
• Daniel Rakos, AMD
• Graham Sellers, AMD
• Ray Smith, ARM
• Jeff Vigil, Qualcomm
• Chia-I Wu, LunarG

Description

The VK_KHR_win32_surface extension is an instance extension. It provides a mechanism to create a SurfaceKHR object (defined by the VK_KHR_surface extension) that refers to a Win32 HWND, as well as a query to determine support for rendering to the windows desktop.

New Commands

• createWin32SurfaceKHR

• getPhysicalDeviceWin32PresentationSupportKHR

New Structures

• Win32SurfaceCreateInfoKHR

New Bitmasks

• Win32SurfaceCreateFlagsKHR

New Enum Constants

• KHR_WIN32_SURFACE_EXTENSION_NAME

• KHR_WIN32_SURFACE_SPEC_VERSION

• Extending StructureType:

  • STRUCTURE_TYPE_WIN32_SURFACE_CREATE_INFO_KHR

Issues

1) Does Win32 need a way to query for compatibility between a particular physical device and a specific screen? Compatibility between a physical device and a window generally only depends on what screen the window is on. However, there is not an obvious way to identify a screen without already having a window on the screen.

RESOLVED: No. While it may be useful, there is not a clear way to do this on Win32. However, a method was added to query support for presenting to the windows desktop as a whole.

2) If a native window object (HWND) is used by one graphics API, and then is later used by a different graphics API (one of which is Vulkan), can these uses interfere with each other?

RESOLVED: Yes.

Uses of a window object by multiple graphics APIs results in undefined behavior. Such behavior may succeed when using one Vulkan implementation but fail when using a different Vulkan implementation. Potential failures include:

• Creating then destroying a flip presentation model DXGI swapchain on a window object can prevent createSwapchainKHR from succeeding on the same window object.
• Creating then destroying a SwapchainKHR on a window object can prevent creation of a bitblt model DXGI swapchain on the same window object.
• Creating then destroying a SwapchainKHR on a window object can effectively SetPixelFormat to a different format than the format chosen by an OpenGL application.
• Creating then destroying a SwapchainKHR on a window object on one PhysicalDevice can prevent createSwapchainKHR from succeeding on the same window object, but on a different PhysicalDevice that is associated with a different Vulkan ICD.

In all cases the problem can be worked around by creating a new window object.

Technical details include:

• Creating a DXGI swapchain over a window object can alter the object for the remainder of its lifetime. The alteration persists even after the DXGI swapchain has been destroyed. This alteration can make it impossible for a conformant Vulkan implementation to create a SwapchainKHR over the same window object. Mention of this alteration can be found in the remarks section of the MSDN documentation for DXGI_SWAP_EFFECT.
• Calling GDI’s SetPixelFormat (needed by OpenGL’s WGL layer) on a window object alters the object for the remainder of its lifetime. The MSDN documentation for SetPixelFormat explains that a window object’s pixel format can be set only one time.
• Creating a SwapchainKHR over a window object can alter the object for the remaining life of its lifetime. Either of the above alterations may occur as a side-effect of SwapchainKHR.

Version History

• Revision 1, 2015-09-23 (Jesse Hall)

  • Initial draft, based on the previous contents of VK_EXT_KHR_swapchain (later renamed VK_EXT_KHR_surface).

• Revision 2, 2015-10-02 (James Jones)

  • Added presentation support query for win32 desktops.

• Revision 3, 2015-10-26 (Ian Elliott)

  • Renamed from VK_EXT_KHR_win32_surface to VK_KHR_win32_surface.

• Revision 4, 2015-11-03 (Daniel Rakos)

  • Added allocation callbacks to vkCreateWin32SurfaceKHR.

• Revision 5, 2015-11-28 (Daniel Rakos)

  • Updated the surface create function to take a pCreateInfo structure.

• Revision 6, 2017-04-24 (Jeff Juliano)

  • Add issue 2 addressing reuse of a native window object in a different Graphics API, or by a different Vulkan ICD.

See Also

Win32SurfaceCreateFlagsKHR, Win32SurfaceCreateInfoKHR, createWin32SurfaceKHR, getPhysicalDeviceWin32PresentationSupportKHR

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.