1// Copyright (c) 2014-2018 Khronos Group. This work is licensed under a 2// Creative Commons Attribution 4.0 International License; see 3// http://creativecommons.org/licenses/by/4.0/ 4 5include::meta/VK_KHR_win32_surface.txt[] 6 7*Last Modified Date*:: 8 2017-04-24 9*IP Status*:: 10 No known IP claims. 11*Contributors*:: 12 - Patrick Doane, Blizzard 13 - Jason Ekstrand, Intel 14 - Ian Elliott, LunarG 15 - Courtney Goeltzenleuchter, LunarG 16 - Jesse Hall, Google 17 - James Jones, NVIDIA 18 - Antoine Labour, Google 19 - Jon Leech, Khronos 20 - David Mao, AMD 21 - Norbert Nopper, Freescale 22 - Alon Or-bach, Samsung 23 - Daniel Rakos, AMD 24 - Graham Sellers, AMD 25 - Ray Smith, ARM 26 - Jeff Vigil, Qualcomm 27 - Chia-I Wu, LunarG 28 29The `VK_KHR_win32_surface` extension is an instance extension. 30It provides a mechanism to create a slink:VkSurfaceKHR object (defined by 31the `<<VK_KHR_surface>>` extension) that refers to a Win32 code:HWND, as 32well as a query to determine support for rendering to the windows desktop. 33 34=== New Object Types 35 36None 37 38=== New Enum Constants 39 40 * Extending elink:VkStructureType: 41 ** ename:VK_STRUCTURE_TYPE_WIN32_SURFACE_CREATE_INFO_KHR 42 43=== New Enums 44 45None 46 47=== New Structures 48 49 * slink:VkWin32SurfaceCreateInfoKHR 50 51=== New Functions 52 53 * flink:vkCreateWin32SurfaceKHR 54 * flink:vkGetPhysicalDeviceWin32PresentationSupportKHR 55 56=== Issues 57 581) Does Win32 need a way to query for compatibility between a particular 59physical device and a specific screen? Compatibility between a physical 60device and a window generally only depends on what screen the window is on. 61However, there is not an obvious way to identify a screen without already 62having a window on the screen. 63 64*RESOLVED*: No. 65While it may be useful, there is not a clear way to do this on Win32. 66However, a method was added to query support for presenting to the windows 67desktop as a whole. 68 692) If a native window object (code:HWND) is used by one graphics API, and 70then is later used by a different graphics API (one of which is Vulkan), can 71these uses interfere with each other? 72 73*RESOLVED*: Yes. 74 75Uses of a window object by multiple graphics APIs results in undefined 76behavior. 77Such behavior may succeed when using one Vulkan implementation but fail when 78using a different Vulkan implementation. 79Potential failures include: 80 81 * Creating then destroying a flip presentation model DXGI swapchain on a 82 window object can prevent flink:vkCreateSwapchainKHR from succeeding on 83 the same window object. 84 85 * Creating then destroying a slink:VkSwapchainKHR on a window object can 86 prevent creation of a bitblt model DXGI swapchain on the same window 87 object. 88 89 * Creating then destroying a slink:VkSwapchainKHR on a window object can 90 effectively code:SetPixelFormat to a different format than the format 91 chosen by an OpenGL application. 92 93 * Creating then destroying a slink:VkSwapchainKHR on a window object on 94 one slink:VkPhysicalDevice can prevent flink:vkCreateSwapchainKHR from 95 succeeding on the same window object, but on a different 96 slink:VkPhysicalDevice that is associated with a different Vulkan ICD. 97 98In all cases the problem can be worked around by creating a new window 99object. 100 101Technical details include: 102 103 * Creating a DXGI swapchain over a window object can alter the object for 104 the remainder of its lifetime. 105 The alteration persists even after the DXGI swapchain has been 106 destroyed. 107 This alteration can make it impossible for a conformant Vulkan 108 implementation to create a slink:VkSwapchainKHR over the same window 109 object. 110 Mention of this alteration can be found in the remarks section of the 111 MSDN documentation for code:DXGI_SWAP_EFFECT. 112 113 * Calling GDI's code:SetPixelFormat (needed by OpenGL's WGL layer) on a 114 window object alters the object for the remainder of its lifetime. 115 The MSDN documentation for code:SetPixelFormat explains that a window 116 object's pixel format can be set only one time. 117 118 * Creating a slink:VkSwapchainKHR over a window object can alter the 119 object for the remaining life of its lifetime. 120 Either of the above alterations may occur as a side-effect of 121 slink:VkSwapchainKHR. 122 123=== Version History 124 125 * Revision 1, 2015-09-23 (Jesse Hall) 126 - Initial draft, based on the previous contents of VK_EXT_KHR_swapchain 127 (later renamed VK_EXT_KHR_surface). 128 129 * Revision 2, 2015-10-02 (James Jones) 130 - Added presentation support query for win32 desktops. 131 132 * Revision 3, 2015-10-26 (Ian Elliott) 133 - Renamed from VK_EXT_KHR_win32_surface to VK_KHR_win32_surface. 134 135 * Revision 4, 2015-11-03 (Daniel Rakos) 136 - Added allocation callbacks to vkCreateWin32SurfaceKHR. 137 138 * Revision 5, 2015-11-28 (Daniel Rakos) 139 - Updated the surface create function to take a pCreateInfo structure. 140 141 * Revision 6, 2017-04-24 (Jeff Juliano) 142 - Add issue 2 addressing reuse of a native window object in a different 143 Graphics API, or by a different Vulkan ICD. 144