Wayland related documentation work

This commit is contained in:
Camilla Löwy 2024-02-19 15:06:59 +01:00
parent 559bd3adb9
commit 0bb605cd79
5 changed files with 38 additions and 45 deletions

View File

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

View File

@ -350,8 +350,8 @@ clipboard. The options are:
- @b _GLFW_COCOA to use the Cocoa frameworks - @b _GLFW_COCOA to use the Cocoa frameworks
- @b _GLFW_WIN32 to use the Win32 API - @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_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 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. attempts to detect the appropriate platform at initialization.

View File

@ -92,7 +92,7 @@ Setting these hints requires no platform specific headers or functions.
@anchor GLFW_PLATFORM @anchor GLFW_PLATFORM
__GLFW_PLATFORM__ specifies the platform to use for windowing and input. __GLFW_PLATFORM__ specifies the platform to use for windowing and input.
Possible values are `GLFW_ANY_PLATFORM`, `GLFW_PLATFORM_WIN32`, 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 `GLFW_PLATFORM_NULL`. The default value is `GLFW_ANY_PLATFORM`, which will
choose any platform the library includes support for except for the Null choose any platform the library includes support for except for the Null
backend. 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. 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} #### Wayland specific init hints {#init_hints_wayland}
@anchor GLFW_WAYLAND_LIBDECOR_hint @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 [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} #### Supported and default values {#init_hints_values}
Initialization hint | Default value | Supported 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_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_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_CHDIR_RESOURCES | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
@ref GLFW_COCOA_MENUBAR | `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_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} ### Runtime platform selection {#platform}
GLFW can be compiled for more than one platform (window system) at once. This lets 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 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 default, this is set to @ref GLFW_ANY_PLATFORM, which will look for supported window

View File

@ -511,6 +511,14 @@ should also declare this in its `Info.plist` by setting the
`NSSupportsAutomaticGraphicsSwitching` key to `true`. `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} #### X11 specific window hints {#window_hints_x11}
@anchor GLFW_X11_CLASS_NAME_hint @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. hints need to be set to something other than an empty string for them to take effect.
These are set with @ref glfwWindowHintString. 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} #### 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_WIN32_SHOWDEFAULT | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE`
GLFW_COCOA_FRAME_NAME | `""` | A UTF-8 encoded frame autosave name GLFW_COCOA_FRAME_NAME | `""` | A UTF-8 encoded frame autosave name
GLFW_COCOA_GRAPHICS_SWITCHING | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE` 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_CLASS_NAME | `""` | An ASCII encoded `WM_CLASS` class name
GLFW_X11_INSTANCE_NAME | `""` | An ASCII encoded `WM_CLASS` instance 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} ## Window event processing {#window_events}

View File

@ -1230,11 +1230,11 @@ extern "C" {
* @note @macos This shape is provided by a private system API and may fail * @note @macos This shape is provided by a private system API and may fail
* with @ref GLFW_CURSOR_UNAVAILABLE in the future. * 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 * @note @wayland This shape is provided by a newer standard not supported by
* all cursor themes. * 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 #define GLFW_RESIZE_NWSE_CURSOR 0x00036007
/*! @brief The top-right to bottom-left diagonal resize/move arrow shape. /*! @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 * @note @macos This shape is provided by a private system API and may fail
* with @ref GLFW_CURSOR_UNAVAILABLE in the future. * 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 * @note @wayland This shape is provided by a newer standard not supported by
* all cursor themes. * 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 #define GLFW_RESIZE_NESW_CURSOR 0x00036008
/*! @brief The omni-directional resize/move cursor shape. /*! @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 * The operation-not-allowed shape. This is usually a circle with a diagonal
* line through it. * 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 * @note @wayland This shape is provided by a newer standard not supported by
* all cursor themes. * 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 #define GLFW_NOT_ALLOWED_CURSOR 0x0003600A
/*! @brief Legacy name for compatibility. /*! @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 * and dock icon can be disabled entirely with the @ref GLFW_COCOA_MENUBAR init
* hint. * 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 * @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 * Wayland and X11, and the @ref GLFW_PLATFORM init hint is set to
* `GLFW_ANY_PLATFORM`, the `XDG_SESSION_TYPE` environment variable affects * `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 * to something other than `wayland` or `x11`, the regular detection mechanism
* will be used instead. * 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. * @thread_safety This function must only be called from the main thread.
* *
* @sa @ref intro_init * @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 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_PLATFORM_ERROR. * 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. * @thread_safety This function must only be called from the main thread.
* *
* @sa @ref window_size * @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 * @remark @wayland The desired window position is ignored, as there is no way
* for an application to set this property. * 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. * @thread_safety This function must only be called from the main thread.
* *
* @sa @ref window_monitor * @sa @ref window_monitor
@ -5447,8 +5441,6 @@ GLFWAPI GLFWscrollfun glfwSetScrollCallback(GLFWwindow* window, GLFWscrollfun ca
* *
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED. * @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. * @thread_safety This function must only be called from the main thread.
* *
* @sa @ref path_drop * @sa @ref path_drop