From a25e8eb50dcaccc4c6d55a83819a769581d3ee5a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Camilla=20L=C3=B6wy?= <elmindreda@elmindreda.org>
Date: Thu, 10 Dec 2020 00:11:44 +0100
Subject: [PATCH] Add docs for GLFW_X11_XCB_VULKAN_SURFACE

Related to #1793.
---
 README.md            |  2 ++
 docs/intro.dox       | 22 ++++++++++++++++------
 docs/news.dox        |  1 +
 include/GLFW/glfw3.h |  6 ++++++
 4 files changed, 25 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index f7d9d75a..1e4b8cc9 100644
--- a/README.md
+++ b/README.md
@@ -127,6 +127,8 @@ information on what to include when reporting a bug.
  - Added `GLFW_FEATURE_UNIMPLEMENTED` error for incomplete backends (#1692)
  - Added `GLFW_ANGLE_PLATFORM_TYPE` init hint and `GLFW_ANGLE_PLATFORM_TYPE_*`
    values to select ANGLE backend (#1380)
+ - Added `GLFW_X11_XCB_VULKAN_SURFACE` init hint for selecting X11 Vulkan
+   surface extension (#1793)
  - Made joystick subsystem initialize at first use (#1284,#1646)
  - Updated the minimum required CMake version to 3.1
  - Disabled tests and examples by default when built as a CMake subdirectory
diff --git a/docs/intro.dox b/docs/intro.dox
index efc7c34c..54c8549c 100644
--- a/docs/intro.dox
+++ b/docs/intro.dox
@@ -124,14 +124,24 @@ a nib or manually by GLFW.  Possible values are `GLFW_TRUE` and `GLFW_FALSE`.
 This is ignored on other platforms.
 
 
+@subsubsection init_hints_x11 X11 specific init hints
+
+@anchor GLFW_X11_XCB_VULKAN_SURFACE_hint
+__GLFW_X11_XCB_VULKAN_SURFACE__ specifies whether to prefer the
+`VK_KHR_xcb_surface` extension for creating Vulkan surfaces, or whether to use
+the `VK_KHR_xlib_surface` extension.  Possible values are `GLFW_TRUE` and
+`GLFW_FALSE`.  This is ignored on other platforms.
+
+
 @subsubsection init_hints_values Supported and default values
 
-Initialization hint             | Default value                   | Supported values
-------------------------------- | ------------------------------- | ----------------
-@ref GLFW_JOYSTICK_HAT_BUTTONS  | `GLFW_TRUE`                     | `GLFW_TRUE` or `GLFW_FALSE`
-@ref GLFW_ANGLE_PLATFORM_TYPE   | `GLFW_ANGLE_PLATFORM_TYPE_NONE` | `GLFW_ANGLE_PLATFORM_TYPE_NONE`, `GLFW_ANGLE_PLATFORM_TYPE_OPENGL`, `GLFW_ANGLE_PLATFORM_TYPE_OPENGLES`, `GLFW_ANGLE_PLATFORM_TYPE_D3D9`, `GLFW_ANGLE_PLATFORM_TYPE_D3D11`, `GLFW_ANGLE_PLATFORM_TYPE_VULKAN` or `GLFW_ANGLE_PLATFORM_TYPE_METAL`
-@ref GLFW_COCOA_CHDIR_RESOURCES | `GLFW_TRUE`                     | `GLFW_TRUE` or `GLFW_FALSE`
-@ref GLFW_COCOA_MENUBAR         | `GLFW_TRUE`                     | `GLFW_TRUE` or `GLFW_FALSE`
+Initialization hint              | Default value                   | Supported values
+-------------------------------- | ------------------------------- | ----------------
+@ref GLFW_JOYSTICK_HAT_BUTTONS   | `GLFW_TRUE`                     | `GLFW_TRUE` or `GLFW_FALSE`
+@ref GLFW_ANGLE_PLATFORM_TYPE    | `GLFW_ANGLE_PLATFORM_TYPE_NONE` | `GLFW_ANGLE_PLATFORM_TYPE_NONE`, `GLFW_ANGLE_PLATFORM_TYPE_OPENGL`, `GLFW_ANGLE_PLATFORM_TYPE_OPENGLES`, `GLFW_ANGLE_PLATFORM_TYPE_D3D9`, `GLFW_ANGLE_PLATFORM_TYPE_D3D11`, `GLFW_ANGLE_PLATFORM_TYPE_VULKAN` or `GLFW_ANGLE_PLATFORM_TYPE_METAL`
+@ref GLFW_COCOA_CHDIR_RESOURCES  | `GLFW_TRUE`                     | `GLFW_TRUE` or `GLFW_FALSE`
+@ref GLFW_COCOA_MENUBAR          | `GLFW_TRUE`                     | `GLFW_TRUE` or `GLFW_FALSE`
+@ref GLFW_X11_XCB_VULKAN_SURFACE | `GLFW_TRUE`                     | `GLFW_TRUE` or `GLFW_FALSE`
 
 
 @subsection intro_init_terminate Terminating GLFW
diff --git a/docs/news.dox b/docs/news.dox
index 19df848a..d9ed0b1d 100644
--- a/docs/news.dox
+++ b/docs/news.dox
@@ -142,6 +142,7 @@ then GLFW will fail to initialize.
  - @ref GLFW_ANGLE_PLATFORM_TYPE_D3D11
  - @ref GLFW_ANGLE_PLATFORM_TYPE_VULKAN
  - @ref GLFW_ANGLE_PLATFORM_TYPE_METAL
+ - @ref GLFW_X11_XCB_VULKAN_SURFACE
 
 
 @section news_archive Release notes for earlier versions
diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h
index ac696cd8..d62d82fa 100644
--- a/include/GLFW/glfw3.h
+++ b/include/GLFW/glfw3.h
@@ -6018,6 +6018,12 @@ GLFWAPI int glfwGetPhysicalDevicePresentationSupport(VkInstance instance, VkPhys
  *  @remark @macos This function creates and sets a `CAMetalLayer` instance for
  *  the window content view, which is required for MoltenVK to function.
  *
+ *  @remark @x11 GLFW by default attempts to use the `VK_KHR_xcb_surface`
+ *  extension, if available.  You can make it prefer the `VK_KHR_xlib_surface`
+ *  extension by setting the
+ *  [GLFW_X11_XCB_VULKAN_SURFACE](@ref GLFW_X11_XCB_VULKAN_SURFACE_hint) init
+ *  hint.
+ *
  *  @thread_safety This function may be called from any thread.  For
  *  synchronization details of Vulkan objects, see the Vulkan specification.
  *