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

include::{generated}/meta/{refprefix}VK_KHR_wayland_surface.adoc[]

=== Other Extension Metadata

*Last Modified Date*::
    2015-11-28
*IP Status*::
    No known IP claims.
*Contributors*::
  - Patrick Doane, Blizzard
  - Faith 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_wayland_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 Wayland
code:wl_surface, as well as a query to determine support for rendering to a
Wayland compositor.

include::{generated}/interfaces/VK_KHR_wayland_surface.adoc[]

=== Issues

1) Does Wayland need a way to query for compatibility between a particular
physical device and a specific Wayland display? This would be a more general
query than flink:vkGetPhysicalDeviceSurfaceSupportKHR: if the
Wayland-specific query returned ename:VK_TRUE for a (slink:VkPhysicalDevice,
`struct wl_display*`) pair, then the physical device could be assumed to
support presentation to any slink:VkSurfaceKHR for surfaces on the display.

*RESOLVED*: Yes.
flink:vkGetPhysicalDeviceWaylandPresentationSupportKHR was added to address
this issue.

2) Should we require surfaces created with flink:vkCreateWaylandSurfaceKHR
to support the ename:VK_PRESENT_MODE_MAILBOX_KHR present mode?

*RESOLVED*: Yes.
Wayland is an inherently mailbox window system and mailbox support is
required for some Wayland compositor interactions to work as expected.
While handling these interactions may be possible with
ename:VK_PRESENT_MODE_FIFO_KHR, it is much more difficult to do without
deadlock and requiring all Wayland applications to be able to support
implementations which only support ename:VK_PRESENT_MODE_FIFO_KHR would be
an onerous restriction on application developers.

=== 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 vkGetPhysicalDeviceWaylandPresentationSupportKHR() to resolve
     issue #1.
  ** Adjusted wording of issue #1 to match the agreed-upon solution.
  ** Renamed "`window`" parameters to "`surface`" to match Wayland
     conventions.

  * Revision 3, 2015-10-26 (Ian Elliott)
  ** Renamed from VK_EXT_KHR_wayland_surface to VK_KHR_wayland_surface.

  * Revision 4, 2015-11-03 (Daniel Rakos)
  ** Added allocation callbacks to vkCreateWaylandSurfaceKHR.

  * Revision 5, 2015-11-28 (Daniel Rakos)
  ** Updated the surface create function to take a pCreateInfo structure.

  * Revision 6, 2017-02-08 (Faith Ekstrand)
  ** Added the requirement that implementations support
     ename:VK_PRESENT_MODE_MAILBOX_KHR.
  ** Added wording about interactions between flink:vkQueuePresentKHR and
     the Wayland requests sent to the compositor.