From 0bb605cd797e4d63709495f4074ec59362064ab4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Camilla=20L=C3=B6wy?= Date: Mon, 19 Feb 2024 15:06:59 +0100 Subject: [PATCH] Wayland related documentation work --- README.md | 4 ++-- docs/compile.md | 2 +- docs/intro.md | 26 +++++++++++++------------- docs/window.md | 17 +++++++++-------- include/GLFW/glfw3.h | 34 +++++++++++++--------------------- 5 files changed, 38 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index b3e784e9..95ac99c4 100644 --- a/README.md +++ b/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 diff --git a/docs/compile.md b/docs/compile.md index 14c8bc10..f8385fef 100644 --- a/docs/compile.md +++ b/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. diff --git a/docs/intro.md b/docs/intro.md index 54e6e5bb..0610202f 100644 --- a/docs/intro.md +++ b/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 diff --git a/docs/window.md b/docs/window.md index 3d6c6805..371baa56 100644 --- a/docs/window.md +++ b/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} diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h index da3c3c57..9c55ac9d 100644 --- a/include/GLFW/glfw3.h +++ b/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