Wayland related documentation work

README.md

@@ -11,7 +11,7 @@ application development.  It provides a simple, platform-independent API for
 creating windows, contexts and surfaces, reading input, handling events, etc.
 
 GLFW natively supports Windows, macOS and Linux and other Unix-like systems.  On
-Linux both X11 and Wayland are supported.
+Linux both Wayland and X11 are supported.
 
 GLFW is licensed under the [zlib/libpng
 license](https://www.glfw.org/license.html).
@@ -170,6 +170,7 @@ information on what to include when reporting a bug.
    variables exposing pkg-config dependencies (#1307)
  - Made joystick subsystem initialize at first use (#1284,#1646)
  - Made `GLFW_DOUBLEBUFFER` a read-only window attribute
+ - Made Wayland the preferred platform over X11 if both are available (#2035)
  - Updated the minimum required CMake version to 3.1
  - Updated gamepad mappings from upstream
  - Renamed `GLFW_USE_WAYLAND` CMake option to `GLFW_BUILD_WAYLAND` (#1958)
@@ -358,7 +359,6 @@ information on what to include when reporting a bug.
  - [Wayland] Disabled alpha channel for opaque windows on systems lacking
    `EGL_EXT_present_opaque` (#1895)
  - [Wayland] Removed support for `wl_shell` (#1443)
- - [Wayland] Prefer Wayland over X11 if both are available (#2035)
  - [Wayland] Bugfix: The `GLFW_HAND_CURSOR` shape used the wrong image (#1432)
  - [Wayland] Bugfix: Repeated keys could be reported with `NULL` window (#1704)
  - [Wayland] Bugfix: Retrieving partial framebuffer size would segfault

docs/compile.md

@@ -350,8 +350,8 @@ clipboard.  The options are:
 
  - @b _GLFW_COCOA to use the Cocoa frameworks
  - @b _GLFW_WIN32 to use the Win32 API
+ - @b _GLFW_WAYLAND to use the Wayland protocol
  - @b _GLFW_X11 to use the X Window System
- - @b _GLFW_WAYLAND to use the Wayland API (incomplete)
 
 The @b _GLFW_WAYLAND and @b _GLFW_X11 macros may be combined and produces a library that
 attempts to detect the appropriate platform at initialization.

docs/intro.md

@@ -92,7 +92,7 @@ Setting these hints requires no platform specific headers or functions.
 @anchor GLFW_PLATFORM
 __GLFW_PLATFORM__ specifies the platform to use for windowing and input.
 Possible values are `GLFW_ANY_PLATFORM`, `GLFW_PLATFORM_WIN32`,
-`GLFW_PLATFORM_COCOA`, `GLFW_PLATFORM_X11`, `GLFW_PLATFORM_WAYLAND` and
+`GLFW_PLATFORM_COCOA`, `GLFW_PLATFORM_WAYLAND`, `GLFW_PLATFORM_X11` and
 `GLFW_PLATFORM_NULL`.  The default value is `GLFW_ANY_PLATFORM`, which will
 choose any platform the library includes support for except for the Null
 backend.
@@ -134,15 +134,6 @@ a nib or manually by GLFW.  Possible values are `GLFW_TRUE` and `GLFW_FALSE`.
 This is ignored on other platforms.
 
 
-#### X11 specific init hints {#init_hints_x11}
-
-@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.
-
-
 #### Wayland specific init hints {#init_hints_wayland}
 
 @anchor GLFW_WAYLAND_LIBDECOR_hint
@@ -153,23 +144,32 @@ and `GLFW_WAYLAND_DISABLE_LIBDECOR`.  This is ignored on other platforms.
 [libdecor]: https://gitlab.freedesktop.org/libdecor/libdecor
 
 
+#### X11 specific init hints {#init_hints_x11}
+
+@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.
+
+
 #### Supported and default values {#init_hints_values}
 
 Initialization hint              | Default value                   | Supported values
 -------------------------------- | ------------------------------- | ----------------
-@ref GLFW_PLATFORM               | `GLFW_ANY_PLATFORM`             | `GLFW_ANY_PLATFORM`, `GLFW_PLATFORM_WIN32`, `GLFW_PLATFORM_COCOA`, `GLFW_PLATFORM_X11`, `GLFW_PLATFORM_WAYLAND` or `GLFW_PLATFORM_NULL`
+@ref GLFW_PLATFORM               | `GLFW_ANY_PLATFORM`             | `GLFW_ANY_PLATFORM`, `GLFW_PLATFORM_WIN32`, `GLFW_PLATFORM_COCOA`, `GLFW_PLATFORM_WAYLAND`, `GLFW_PLATFORM_X11` or `GLFW_PLATFORM_NULL`
 @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`
 @ref GLFW_WAYLAND_LIBDECOR       | `GLFW_WAYLAND_PREFER_LIBDECOR`  | `GLFW_WAYLAND_PREFER_LIBDECOR` or `GLFW_WAYLAND_DISABLE_LIBDECOR`
+@ref GLFW_X11_XCB_VULKAN_SURFACE | `GLFW_TRUE`                     | `GLFW_TRUE` or `GLFW_FALSE`
 
 
 ### Runtime platform selection {#platform}
 
 GLFW can be compiled for more than one platform (window system) at once.  This lets
-a single library binary support both X11 and Wayland on Linux and other Unix-like systems.
+a single library binary support both Wayland and X11 on Linux and other Unix-like systems.
 
 You can control platform selection via the @ref GLFW_PLATFORM initialization hint.  By
 default, this is set to @ref GLFW_ANY_PLATFORM, which will look for supported window

docs/window.md

@@ -511,6 +511,14 @@ should also declare this in its `Info.plist` by setting the
 `NSSupportsAutomaticGraphicsSwitching` key to `true`.
 
 
+#### Wayland specific window hints {#window_hints_wayland}
+
+@anchor GLFW_WAYLAND_APP_ID_hint
+__GLFW_WAYLAND_APP_ID__ specifies the Wayland app_id for a window, used
+by window managers to identify types of windows. This is set with
+@ref glfwWindowHintString.
+
+
 #### X11 specific window hints {#window_hints_x11}
 
 @anchor GLFW_X11_CLASS_NAME_hint
@@ -520,13 +528,6 @@ ASCII encoded class and instance parts of the ICCCM `WM_CLASS` window property.
 hints need to be set to something other than an empty string for them to take effect.
 These are set with @ref glfwWindowHintString.
 
-#### Wayland specific window hints {#window_hints_wayland}
-
-@anchor GLFW_WAYLAND_APP_ID_hint
-__GLFW_WAYLAND_APP_ID__ specifies the Wayland app_id for a window, used
-by window managers to identify types of windows. This is set with
-@ref glfwWindowHintString.
-
 
 #### Supported and default values {#window_hints_values}
 
@@ -576,9 +577,9 @@ GLFW_WIN32_KEYBOARD_MENU      | `GLFW_FALSE`                | `GLFW_TRUE` or `GL
 GLFW_WIN32_SHOWDEFAULT        | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
 GLFW_COCOA_FRAME_NAME         | `""`                        | A UTF-8 encoded frame autosave name
 GLFW_COCOA_GRAPHICS_SWITCHING | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
+GLFW_WAYLAND_APP_ID           | `""`                        | An ASCII encoded Wayland `app_id` name
 GLFW_X11_CLASS_NAME           | `""`                        | An ASCII encoded `WM_CLASS` class name
 GLFW_X11_INSTANCE_NAME        | `""`                        | An ASCII encoded `WM_CLASS` instance name
-GLFW_WAYLAND_APP_ID           | `""`                        | An ASCII encoded Wayland `app_id` name
 
 
 ## Window event processing {#window_events}

include/GLFW/glfw3.h

@@ -1230,11 +1230,11 @@ extern "C" {
  *  @note @macos This shape is provided by a private system API and may fail
  *  with @ref GLFW_CURSOR_UNAVAILABLE in the future.
  *
- *  @note @x11 This shape is provided by a newer standard not supported by all
- *  cursor themes.
- *
  *  @note @wayland This shape is provided by a newer standard not supported by
  *  all cursor themes.
+ *
+ *  @note @x11 This shape is provided by a newer standard not supported by all
+ *  cursor themes.
  */
 #define GLFW_RESIZE_NWSE_CURSOR     0x00036007
 /*! @brief The top-right to bottom-left diagonal resize/move arrow shape.
@@ -1245,11 +1245,11 @@ extern "C" {
  *  @note @macos This shape is provided by a private system API and may fail
  *  with @ref GLFW_CURSOR_UNAVAILABLE in the future.
  *
- *  @note @x11 This shape is provided by a newer standard not supported by all
- *  cursor themes.
- *
  *  @note @wayland This shape is provided by a newer standard not supported by
  *  all cursor themes.
+ *
+ *  @note @x11 This shape is provided by a newer standard not supported by all
+ *  cursor themes.
  */
 #define GLFW_RESIZE_NESW_CURSOR     0x00036008
 /*! @brief The omni-directional resize/move cursor shape.
@@ -1263,11 +1263,11 @@ extern "C" {
  *  The operation-not-allowed shape.  This is usually a circle with a diagonal
  *  line through it.
  *
- *  @note @x11 This shape is provided by a newer standard not supported by all
- *  cursor themes.
- *
  *  @note @wayland This shape is provided by a newer standard not supported by
  *  all cursor themes.
+ *
+ *  @note @x11 This shape is provided by a newer standard not supported by all
+ *  cursor themes.
  */
 #define GLFW_NOT_ALLOWED_CURSOR     0x0003600A
 /*! @brief Legacy name for compatibility.
@@ -2195,10 +2195,6 @@ typedef struct GLFWallocator
  *  and dock icon can be disabled entirely with the @ref GLFW_COCOA_MENUBAR init
  *  hint.
  *
- *  @remark @x11 This function will set the `LC_CTYPE` category of the
- *  application locale according to the current environment if that category is
- *  still "C".  This is because the "C" locale breaks Unicode text input.
- *
  *  @remark __Wayland, X11:__ If the library was compiled with support for both
  *  Wayland and X11, and the @ref GLFW_PLATFORM init hint is set to
  *  `GLFW_ANY_PLATFORM`, the `XDG_SESSION_TYPE` environment variable affects
@@ -2206,6 +2202,10 @@ typedef struct GLFWallocator
  *  to something other than `wayland` or `x11`, the regular detection mechanism
  *  will be used instead.
  *
+ *  @remark @x11 This function will set the `LC_CTYPE` category of the
+ *  application locale according to the current environment if that category is
+ *  still "C".  This is because the "C" locale breaks Unicode text input.
+ *
  *  @thread_safety This function must only be called from the main thread.
  *
  *  @sa @ref intro_init
@@ -3620,9 +3620,6 @@ GLFWAPI void glfwSetWindowAspectRatio(GLFWwindow* window, int numer, int denom);
  *  @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
  *  GLFW_PLATFORM_ERROR.
  *
- *  @remark @wayland A full screen window will not attempt to change the mode,
- *  no matter what the requested size.
- *
  *  @thread_safety This function must only be called from the main thread.
  *
  *  @sa @ref window_size
@@ -4063,9 +4060,6 @@ GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window);
  *  @remark @wayland The desired window position is ignored, as there is no way
  *  for an application to set this property.
  *
- *  @remark @wayland Setting the window to full screen will not attempt to
- *  change the mode, no matter what the requested size or refresh rate.
- *
  *  @thread_safety This function must only be called from the main thread.
  *
  *  @sa @ref window_monitor
@@ -5447,8 +5441,6 @@ GLFWAPI GLFWscrollfun glfwSetScrollCallback(GLFWwindow* window, GLFWscrollfun ca
  *
  *  @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
  *
- *  @remark @wayland File drop is currently unimplemented.
- *
  *  @thread_safety This function must only be called from the main thread.
  *
  *  @sa @ref path_drop