// Copyright 2014-2021 The Khronos Group, Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/{refprefix}VK_KHR_win32_surface.txt[]

=== 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 slink:VkSurfaceKHR object (defined by
the `apiext:VK_KHR_surface` extension) that refers to a Win32 code:HWND, as
well as a query to determine support for rendering to the windows desktop.

include::{generated}/interfaces/VK_KHR_win32_surface.txt[]

=== 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 (code: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 flink:vkCreateSwapchainKHR from succeeding on
    the same window object.
  * Creating then destroying a slink:VkSwapchainKHR on a window object can
    prevent creation of a bitblt model DXGI swapchain on the same window
    object.
  * Creating then destroying a slink:VkSwapchainKHR on a window object can
    effectively code:SetPixelFormat to a different format than the format
    chosen by an OpenGL application.
  * Creating then destroying a slink:VkSwapchainKHR on a window object on
    one slink:VkPhysicalDevice can prevent flink:vkCreateSwapchainKHR from
    succeeding on the same window object, but on a different
    slink:VkPhysicalDevice 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 slink:VkSwapchainKHR over the same window
    object.
    Mention of this alteration can be found in the remarks section of the
    MSDN documentation for code:DXGI_SWAP_EFFECT.
  * Calling GDI's code:SetPixelFormat (needed by OpenGL's WGL layer) on a
    window object alters the object for the remainder of its lifetime.
    The MSDN documentation for code:SetPixelFormat explains that a window
    object's pixel format can be set only one time.
  * Creating a slink:VkSwapchainKHR over a window object can alter the
    object for its remaining lifetime.
    Either of the above alterations may occur as a side effect of
    flink:vkCreateSwapchainKHR.

=== 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.