mirror/glfw
1
0
Fork 0
mirror of https://github.com/glfw/glfw.git synced 2024-11-10 00:51:47 +00:00
Code Issues Packages Projects Releases Wiki Activity
d107e497a9
glfw/docs/compat.dox
Camilla Löwy 2c3eb75748 Wayland: Remove dependency on wayland-protocols 
This brings the latest released versions of all used Wayland protocol
files into this repository, removing the need for the user to arrange
a sufficiently new version of wayland-protocols.

The wayland.xml protocol file was copied from wayland 1.22.0.
The additional protocol files were copied from wayland-protocols 1.32.

Because of how files are moved and renamed inside the wayland-protocols
repository, it will not always be possible to update all our protocol
files from a single release without also potentially updating related
code (acceptable) and prematurely breaking compatibility with
compositors that still only support an earlier incompatible version
(unacceptable).

The macro in src/CMakeLists.txt has been modified to hopefully make it
easier to add new protocol files.  This made it necessary to change the
name of a few of the generated header files.

Closes #2053
2024-01-13 22:13:56 +01:00

284 lines
14 KiB
Plaintext
Raw Blame History

/*!
@page compat_guide Standards conformance
@tableofcontents
This guide describes the various API extensions used by this version of GLFW.
It lists what are essentially implementation details, but which are nonetheless
vital knowledge for developers intending to deploy their applications on a wide
range of machines.
The information in this guide is not a part of GLFW API, but merely
preconditions for some parts of the library to function on a given machine. Any
part of this information may change in future versions of GLFW and that will not
be considered a breaking API change.
@section compat_x11 X11 extensions, protocols and IPC standards
As GLFW uses Xlib directly, without any intervening toolkit
library, it has sole responsibility for interacting well with the many and
varied window managers in use on Unix-like systems. In order for applications
and window managers to work well together, a number of standards and
conventions have been developed that regulate behavior outside the scope of the
X11 API; most importantly the
[Inter-Client Communication Conventions Manual](https://www.tronche.com/gui/x/icccm/)
(ICCCM) and
[Extended Window Manager Hints](https://standards.freedesktop.org/wm-spec/wm-spec-latest.html)
(EWMH) standards.
GLFW uses the `_MOTIF_WM_HINTS` window property to support borderless windows.
If the running window manager does not support this property, the
`GLFW_DECORATED` hint will have no effect.
GLFW uses the ICCCM `WM_DELETE_WINDOW` protocol to intercept the user
attempting to close the GLFW window. If the running window manager does not
support this protocol, the close callback will never be called.
GLFW uses the EWMH `_NET_WM_PING` protocol, allowing the window manager notify
the user when the application has stopped responding, i.e. when it has ceased to
process events. If the running window manager does not support this protocol,
the user will not be notified if the application locks up.
GLFW uses the EWMH `_NET_WM_STATE_FULLSCREEN` window state to tell the window
manager to make the GLFW window full screen. If the running window manager does
not support this state, full screen windows may not work properly. GLFW has
a fallback code path in case this state is unavailable, but every window manager
behaves slightly differently in this regard.
GLFW uses the EWMH `_NET_WM_BYPASS_COMPOSITOR` window property to tell a
compositing window manager to un-redirect full screen GLFW windows. If the
running window manager uses compositing but does not support this property then
additional copying may be performed for each buffer swap of full screen windows.
GLFW uses the
[clipboard manager protocol](https://www.freedesktop.org/wiki/ClipboardManager/)
to push a clipboard string (i.e. selection) owned by a GLFW window about to be
destroyed to the clipboard manager. If there is no running clipboard manager,
the clipboard string will be unavailable once the window has been destroyed.
GLFW uses the
[X drag-and-drop protocol](https://www.freedesktop.org/wiki/Specifications/XDND/)
to provide file drop events. If the application originating the drag does not
support this protocol, drag and drop will not work.
GLFW uses the XRandR 1.3 extension to provide multi-monitor support. If the
running X server does not support this version of this extension, multi-monitor
support will not function and only a single, desktop-spanning monitor will be
reported.
GLFW uses the XRandR 1.3 and Xf86vidmode extensions to provide gamma ramp
support. If the running X server does not support either or both of these
extensions, gamma ramp support will not function.
GLFW uses the Xkb extension and detectable auto-repeat to provide keyboard
input. If the running X server does not support this extension, a non-Xkb
fallback path is used.
GLFW uses the XInput2 extension to provide raw, non-accelerated mouse motion
when the cursor is disabled. If the running X server does not support this
extension, regular accelerated mouse motion will be used.
GLFW uses both the XRender extension and the compositing manager to support
transparent window framebuffers. If the running X server does not support this
extension or there is no running compositing manager, the
`GLFW_TRANSPARENT_FRAMEBUFFER` framebuffer hint will have no effect.
GLFW uses both the Xcursor extension and the freedesktop cursor conventions to
provide an expanded set of standard cursor shapes. If the running X server does
not support this extension or the current cursor theme does not support the
conventions, the `GLFW_RESIZE_NWSE_CURSOR`, `GLFW_RESIZE_NESW_CURSOR` and
`GLFW_NOT_ALLOWED_CURSOR` shapes will not be available and other shapes may use
legacy images.
@section compat_wayland Wayland protocols and IPC standards
As GLFW uses libwayland directly, without any intervening toolkit library, it
has sole responsibility for interacting well with every compositor in use on
Unix-like systems. Most of the features are provided by the core protocol,
while cursor support is provided by the libwayland-cursor helper library, EGL
integration by libwayland-egl, and keyboard handling by
[libxkbcommon](https://xkbcommon.org/). In addition, GLFW uses some additional
Wayland protocols to implement certain features if the compositor supports them.
GLFW uses xkbcommon 0.5.0 to provide key and text input support. Earlier
versions are not supported.
GLFW uses the [xdg-shell protocol](https://wayland.app/protocols/xdg-shell)
to provide better window management. This protocol is mandatory for GLFW to
display a window.
GLFW uses the
[relative pointer protocol](https://wayland.app/protocols/relative-pointer-unstable-v1)
alongside the
[pointer constraints protocol](https://wayland.app/protocols/pointer-constraints-unstable-v1)
to implement disabled cursor. If the running compositor does not support both
of these protocols, disabling the cursor will have no effect.
GLFW uses the
[idle inhibit protocol](https://wayland.app/protocols/idle-inhibit-unstable-v1)
to prohibit the screensaver from starting. If the running compositor does not
support this protocol, the screensaver may start even for full screen windows.
GLFW uses the
[libdecor library](https://gitlab.freedesktop.org/libdecor/libdecor) for window
decorations, where available. This in turn provides good quality client-side
decorations (drawn by the application) on desktop systems that do not support
server-side decorations (drawn by the window manager). On systems that do not
provide either libdecor or xdg-decoration, very basic window decorations are
provided. These do not include the window title or any caption buttons.
GLFW uses the
[xdg-decoration protocol](https://wayland.app/protocols/xdg-decoration-unstable-v1)
to request decorations to be drawn around its windows. This protocol is part
of wayland-protocols 1.15, and mandatory at build time. If the running
compositor does not support this protocol, a very simple frame will be drawn by
GLFW itself, using the
[viewporter protocol](https://wayland.app/protocols/viewporter)
alongside subsurfaces. If the running compositor does not support these
protocols either, no decorations will be drawn around windows.
@section compat_glx GLX extensions
The GLX API is the default API used to create OpenGL contexts on Unix-like
systems using the X Window System.
GLFW uses the GLX 1.3 `GLXFBConfig` functions to enumerate and select framebuffer pixel
formats. If GLX 1.3 is not supported, @ref glfwInit will fail.
GLFW uses the `GLX_MESA_swap_control,` `GLX_EXT_swap_control` and
`GLX_SGI_swap_control` extensions to provide vertical retrace synchronization
(or _vsync_), in that order of preference. When none of these extensions are
available, calling @ref glfwSwapInterval will have no effect.
GLFW uses the `GLX_ARB_multisample` extension to create contexts with
multisampling anti-aliasing. Where this extension is unavailable, the
`GLFW_SAMPLES` hint will have no effect.
GLFW uses the `GLX_ARB_create_context` extension when available, even when
creating OpenGL contexts of version 2.1 and below. Where this extension is
unavailable, the `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR`
hints will only be partially supported, the `GLFW_CONTEXT_DEBUG` hint will have
no effect, and setting the `GLFW_OPENGL_PROFILE` or `GLFW_OPENGL_FORWARD_COMPAT`
hints to `GLFW_TRUE` will cause @ref glfwCreateWindow to fail.
GLFW uses the `GLX_ARB_create_context_profile` extension to provide support for
context profiles. Where this extension is unavailable, setting the
`GLFW_OPENGL_PROFILE` hint to anything but `GLFW_OPENGL_ANY_PROFILE`, or setting
`GLFW_CLIENT_API` to anything but `GLFW_OPENGL_API` or `GLFW_NO_API` will cause
@ref glfwCreateWindow to fail.
GLFW uses the `GLX_ARB_context_flush_control` extension to provide control over
whether a context is flushed when it is released (made non-current). Where this
extension is unavailable, the `GLFW_CONTEXT_RELEASE_BEHAVIOR` hint will have no
effect and the context will always be flushed when released.
GLFW uses the `GLX_ARB_framebuffer_sRGB` and `GLX_EXT_framebuffer_sRGB`
extensions to provide support for sRGB framebuffers. Where both of these
extensions are unavailable, the `GLFW_SRGB_CAPABLE` hint will have no effect.
@section compat_wgl WGL extensions
The WGL API is used to create OpenGL contexts on Microsoft Windows and other
implementations of the Win32 API, such as Wine.
GLFW uses either the `WGL_EXT_extension_string` or the
`WGL_ARB_extension_string` extension to check for the presence of all other WGL
extensions listed below. If both are available, the EXT one is preferred. If
neither is available, no other extensions are used and many GLFW features
related to context creation will have no effect or cause errors when used.
GLFW uses the `WGL_EXT_swap_control` extension to provide vertical retrace
synchronization (or _vsync_). Where this extension is unavailable, calling @ref
glfwSwapInterval will have no effect.
GLFW uses the `WGL_ARB_pixel_format` and `WGL_ARB_multisample` extensions to
create contexts with multisampling anti-aliasing. Where these extensions are
unavailable, the `GLFW_SAMPLES` hint will have no effect.
GLFW uses the `WGL_ARB_create_context` extension when available, even when
creating OpenGL contexts of version 2.1 and below. Where this extension is
unavailable, the `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR`
hints will only be partially supported, the `GLFW_CONTEXT_DEBUG` hint will have
no effect, and setting the `GLFW_OPENGL_PROFILE` or `GLFW_OPENGL_FORWARD_COMPAT`
hints to `GLFW_TRUE` will cause @ref glfwCreateWindow to fail.
GLFW uses the `WGL_ARB_create_context_profile` extension to provide support for
context profiles. Where this extension is unavailable, setting the
`GLFW_OPENGL_PROFILE` hint to anything but `GLFW_OPENGL_ANY_PROFILE` will cause
@ref glfwCreateWindow to fail.
GLFW uses the `WGL_ARB_context_flush_control` extension to provide control over
whether a context is flushed when it is released (made non-current). Where this
extension is unavailable, the `GLFW_CONTEXT_RELEASE_BEHAVIOR` hint will have no
effect and the context will always be flushed when released.
GLFW uses the `WGL_ARB_framebuffer_sRGB` and `WGL_EXT_framebuffer_sRGB`
extensions to provide support for sRGB framebuffers. When both of these
extensions are unavailable, the `GLFW_SRGB_CAPABLE` hint will have no effect.
@section compat_osx OpenGL on macOS
Support for OpenGL 3.2 and above was introduced with OS X 10.7 and even then
only forward-compatible, core profile contexts are supported. Support for
OpenGL 4.1 was introduced with OS X 10.9, also limited to forward-compatible,
core profile contexts. There is also still no mechanism for requesting debug
contexts or no-error contexts. Versions of Mac OS X earlier than 10.7 support
at most OpenGL version 2.1.
Because of this, on OS X 10.7 and later, the `GLFW_CONTEXT_VERSION_MAJOR` and
`GLFW_CONTEXT_VERSION_MINOR` hints will cause @ref glfwCreateWindow to fail if
given version 3.0 or 3.1. The `GLFW_OPENGL_PROFILE` hint must be set to
`GLFW_OPENGL_CORE_PROFILE` when creating OpenGL 3.2 and later contexts. The
`GLFW_CONTEXT_DEBUG` and `GLFW_CONTEXT_NO_ERROR` hints are ignored.
Also, on Mac OS X 10.6 and below, the `GLFW_CONTEXT_VERSION_MAJOR` and
`GLFW_CONTEXT_VERSION_MINOR` hints will fail if given a version above 2.1,
setting the `GLFW_OPENGL_PROFILE` or `GLFW_OPENGL_FORWARD_COMPAT` hints to
a non-default value will cause @ref glfwCreateWindow to fail and the
`GLFW_CONTEXT_DEBUG` hint is ignored.
@section compat_vulkan Vulkan loader and API
By default, GLFW uses the standard system-wide Vulkan loader to access the
Vulkan API on all platforms except macOS. This is installed by both graphics
drivers and Vulkan SDKs. If either the loader or at least one minimally
functional ICD is missing, @ref glfwVulkanSupported will return `GLFW_FALSE` and
all other Vulkan-related functions will fail with an @ref GLFW_API_UNAVAILABLE
error.
@section compat_wsi Vulkan WSI extensions
The Vulkan WSI extensions are used to create Vulkan surfaces for GLFW windows on
all supported platforms.
GLFW uses the `VK_KHR_surface` and `VK_KHR_win32_surface` extensions to create
surfaces on Microsoft Windows. If any of these extensions are not available,
@ref glfwGetRequiredInstanceExtensions will return an empty list and window
surface creation will fail.
GLFW uses the `VK_KHR_surface` and either the `VK_MVK_macos_surface` or
`VK_EXT_metal_surface` extensions to create surfaces on macOS. If any of these
extensions are not available, @ref glfwGetRequiredInstanceExtensions will
return an empty list and window surface creation will fail.
GLFW uses the `VK_KHR_surface` and either the `VK_KHR_xlib_surface` or
`VK_KHR_xcb_surface` extensions to create surfaces on X11. If `VK_KHR_surface`
or both `VK_KHR_xlib_surface` and `VK_KHR_xcb_surface` are not available, @ref
glfwGetRequiredInstanceExtensions will return an empty list and window surface
creation will fail.
GLFW uses the `VK_KHR_surface` and `VK_KHR_wayland_surface` extensions to create
surfaces on Wayland. If any of these extensions are not available, @ref
glfwGetRequiredInstanceExtensions will return an empty list and window surface
creation will fail.
*/
Reference in New Issue View Git Blame Copy Permalink