mirror of
https://github.com/glfw/glfw.git
synced 2024-11-22 04:54:35 +00:00
Wayland related documentation work
This commit is contained in:
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.
|
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
|
||||||
|
@ -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.
|
||||||
|
@ -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
|
||||||
|
@ -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}
|
||||||
|
@ -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
|
||||||
|
Loading…
Reference in New Issue
Block a user