1  // Copyright (c) 2014-2019 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  
  5  include::meta/VK_KHR_wayland_surface.txt[]
  6  
  7  *Last Modified Date*::
  8      2015-11-28
  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  
 29  The `VK_KHR_wayland_surface` extension is an instance extension.
 30  It provides a mechanism to create a slink:VkSurfaceKHR object (defined by
 31  the `<<VK_KHR_surface>>` extension) that refers to a Wayland
 32  code:wl_surface, as well as a query to determine support for rendering to a
 33  Wayland compositor.
 34  
 35  === New Object Types
 36  
 37  None
 38  
 39  === New Enum Constants
 40  
 41    * Extending elink:VkStructureType:
 42    ** ename:VK_STRUCTURE_TYPE_WAYLAND_SURFACE_CREATE_INFO_KHR
 43  
 44  === New Enums
 45  
 46  None
 47  
 48  === New Structures
 49  
 50    * slink:VkWaylandSurfaceCreateInfoKHR
 51  
 52  === New Functions
 53  
 54    * flink:vkCreateWaylandSurfaceKHR
 55    * flink:vkGetPhysicalDeviceWaylandPresentationSupportKHR
 56  
 57  === Issues
 58  
 59  1) Does Wayland need a way to query for compatibility between a particular
 60  physical device and a specific Wayland display? This would be a more general
 61  query than flink:vkGetPhysicalDeviceSurfaceSupportKHR: if the
 62  Wayland-specific query returned ename:VK_TRUE for a (slink:VkPhysicalDevice,
 63  `struct wl_display*`) pair, then the physical device could be assumed to
 64  support presentation to any slink:VkSurfaceKHR for surfaces on the display.
 65  
 66  *RESOLVED*: Yes.
 67  flink:vkGetPhysicalDeviceWaylandPresentationSupportKHR was added to address
 68  this issue.
 69  
 70  2) Should we require surfaces created with flink:vkCreateWaylandSurfaceKHR
 71  to support the ename:VK_PRESENT_MODE_MAILBOX_KHR present mode?
 72  
 73  *RESOLVED*: Yes.
 74  Wayland is an inherently mailbox window system and mailbox support is
 75  required for some Wayland compositor interactions to work as expected.
 76  While handling these interactions may be possible with
 77  ename:VK_PRESENT_MODE_FIFO_KHR, it is much more difficult to do without
 78  deadlock and requiring all Wayland applications to be able to support
 79  implementations which only support ename:VK_PRESENT_MODE_FIFO_KHR would be
 80  an onerous restriction on application developers.
 81  
 82  === Version History
 83  
 84   * Revision 1, 2015-09-23 (Jesse Hall)
 85     - Initial draft, based on the previous contents of VK_EXT_KHR_swapchain
 86       (later renamed VK_EXT_KHR_surface).
 87  
 88   * Revision 2, 2015-10-02 (James Jones)
 89     - Added vkGetPhysicalDeviceWaylandPresentationSupportKHR() to resolve
 90       issue #1.
 91     - Adjusted wording of issue #1 to match the agreed-upon solution.
 92     - Renamed "window" parameters to "surface" to match Wayland conventions.
 93  
 94   * Revision 3, 2015-10-26 (Ian Elliott)
 95     - Renamed from VK_EXT_KHR_wayland_surface to VK_KHR_wayland_surface.
 96  
 97   * Revision 4, 2015-11-03 (Daniel Rakos)
 98     - Added allocation callbacks to vkCreateWaylandSurfaceKHR.
 99  
100   * Revision 5, 2015-11-28 (Daniel Rakos)
101     - Updated the surface create function to take a pCreateInfo structure.
102  
103   * Revision 6, 2017-02-08 (Jason Ekstrand)
104     - Added the requirement that implementations support
105       ename:VK_PRESENT_MODE_MAILBOX_KHR.
106     - Added wording about interactions between flink:vkQueuePresentKHR and
107       the Wayland requests sent to the compositor.