diff options
Diffstat (limited to 'libs/glfw-3.3.8/docs/compat.dox')
| -rw-r--r-- | libs/glfw-3.3.8/docs/compat.dox | 281 |
1 files changed, 281 insertions, 0 deletions
diff --git a/libs/glfw-3.3.8/docs/compat.dox b/libs/glfw-3.3.8/docs/compat.dox new file mode 100644 index 0000000..0b7c4b0 --- /dev/null +++ b/libs/glfw-3.3.8/docs/compat.dox @@ -0,0 +1,281 @@ +/*! + +@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. + + +@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 protocols +from wayland-protocols to provide additional features if the compositor +supports them. + +GLFW uses xkbcommon 0.5.0 to provide compose key support. When it has been +built against an older xkbcommon, the compose key will be disabled even if it +has been configured in the compositor. + +GLFW uses the [xdg-shell +protocol](https://cgit.freedesktop.org/wayland/wayland-protocols/tree/stable/xdg-shell/xdg-shell.xml) +to provide better window management. This protocol is part of +wayland-protocols 1.12, and mandatory at build time. + +GLFW uses the [relative pointer +protocol](https://cgit.freedesktop.org/wayland/wayland-protocols/tree/unstable/relative-pointer/relative-pointer-unstable-v1.xml) +alongside the [pointer constraints +protocol](https://cgit.freedesktop.org/wayland/wayland-protocols/tree/unstable/pointer-constraints/pointer-constraints-unstable-v1.xml) +to implement disabled cursor. These two protocols are part of +wayland-protocols 1.1, and mandatory at build time. 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://cgit.freedesktop.org/wayland/wayland-protocols/tree/unstable/idle-inhibit/idle-inhibit-unstable-v1.xml) +to prohibit the screensaver from starting. This protocol is part of +wayland-protocols 1.6, and mandatory at build time. If the running compositor +does not support this protocol, the screensaver may start even for full screen +windows. + +GLFW uses the [xdg-decoration +protocol](https://cgit.freedesktop.org/wayland/wayland-protocols/tree/unstable/xdg-decoration/xdg-decoration-unstable-v1.xml) +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://cgit.freedesktop.org/wayland/wayland-protocols/tree/stable/viewporter/viewporter.xml) +alongside +[subsurfaces](https://cgit.freedesktop.org/wayland/wayland/tree/protocol/wayland.xml#n2598). +This protocol is part of wayland-protocols 1.4, and mandatory at build time. +If the running compositor does not support this protocol 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. Where none of these extension 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_OPENGL_DEBUG_CONTEXT` 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_OPENGL_DEBUG_CONTEXT` 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. Where both of these +extension 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_FORWARD_COMPAT` hint must be set to +`GLFW_TRUE` and the `GLFW_OPENGL_PROFILE` hint must be set to +`GLFW_OPENGL_CORE_PROFILE` when creating OpenGL 3.2 and later contexts. The +`GLFW_OPENGL_DEBUG_CONTEXT` 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_OPENGL_DEBUG_CONTEXT` 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. + +*/ |