mirror of
https://github.com/glfw/glfw.git
synced 2024-09-19 13:22:16 +00:00
Wayland related documentation work
This commit is contained in:
Camilla Löwy
parent
559bd3adb9
commit
0bb605cd79
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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}
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user