diff options
author | rtk0c <[email protected]> | 2025-08-16 11:23:49 -0700 |
---|---|---|
committer | rtk0c <[email protected]> | 2025-08-16 11:23:49 -0700 |
commit | 047f294de1b4d385b811ac9f5afc393d81cc4ae9 (patch) | |
tree | f96100a813a4ffb28dcd074455d3a2f8ee426430 /3rdparty/glfw/source/docs/compat.dox | |
parent | 488fb8b4b9da7f99a5cc37e39fff9f1cb700f2a8 (diff) |
Copy changes from the no-history fork, generated back in 2023
Original commit message:
> commit f138311d2d2e0cc9ba0496d523bb46f2c1c9fb73
> Author: rtk0c <[email protected]>
> Date: Wed Sep 20 23:58:58 2023 -0700
>
> Copy from the PlasticSCM repo, replace vendored glm wtih conan
In reality, this also introduced a few uncommitted changes in the
original PlasticSCM repo. See the modified and new files in this patch.
Diffstat (limited to '3rdparty/glfw/source/docs/compat.dox')
-rw-r--r-- | 3rdparty/glfw/source/docs/compat.dox | 284 |
1 files changed, 0 insertions, 284 deletions
diff --git a/3rdparty/glfw/source/docs/compat.dox b/3rdparty/glfw/source/docs/compat.dox deleted file mode 100644 index 989c4c1..0000000 --- a/3rdparty/glfw/source/docs/compat.dox +++ /dev/null @@ -1,284 +0,0 @@ -/*! - -@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 protocols -from wayland-protocols to provide additional 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://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 is mandatory for GLFW to display a window. - -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_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. 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_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. - -*/ |