1/*! 2 3@page compat_guide Standards conformance 4 5@tableofcontents 6 7This guide describes the various API extensions used by this version of GLFW. 8It lists what are essentially implementation details, but which are nonetheless 9vital knowledge for developers intending to deploy their applications on a wide 10range of machines. 11 12The information in this guide is not a part of GLFW API, but merely 13preconditions for some parts of the library to function on a given machine. Any 14part of this information may change in future versions of GLFW and that will not 15be considered a breaking API change. 16 17 18@section compat_x11 X11 extensions, protocols and IPC standards 19 20As GLFW uses Xlib directly, without any intervening toolkit 21library, it has sole responsibility for interacting well with the many and 22varied window managers in use on Unix-like systems. In order for applications 23and window managers to work well together, a number of standards and 24conventions have been developed that regulate behavior outside the scope of the 25X11 API; most importantly the 26[Inter-Client Communication Conventions Manual](http://www.tronche.com/gui/x/icccm/) 27(ICCCM) and 28[Extended Window Manager Hints](http://standards.freedesktop.org/wm-spec/wm-spec-latest.html) 29(EWMH) standards. 30 31GLFW uses the `_MOTIF_WM_HINTS` window property to support borderless windows. 32If the running window manager does not support this property, the 33`GLFW_DECORATED` hint will have no effect. 34 35GLFW uses the ICCCM `WM_DELETE_WINDOW` protocol to intercept the user 36attempting to close the GLFW window. If the running window manager does not 37support this protocol, the close callback will never be called. 38 39GLFW uses the EWMH `_NET_WM_PING` protocol, allowing the window manager notify 40the user when the application has stopped responding, i.e. when it has ceased to 41process events. If the running window manager does not support this protocol, 42the user will not be notified if the application locks up. 43 44GLFW uses the EWMH `_NET_WM_STATE_FULLSCREEN` window state to tell the window 45manager to make the GLFW window full screen. If the running window manager does 46not support this state, full screen windows may not work properly. GLFW has 47a fallback code path in case this state is unavailable, but every window manager 48behaves slightly differently in this regard. 49 50GLFW uses the EWMH `_NET_WM_BYPASS_COMPOSITOR` window property to tell a 51compositing window manager to un-redirect full screen GLFW windows. If the 52running window manager uses compositing but does not support this property then 53additional copying may be performed for each buffer swap of full screen windows. 54 55GLFW uses the 56[clipboard manager protocol](http://www.freedesktop.org/wiki/ClipboardManager/) 57to push a clipboard string (i.e. selection) owned by a GLFW window about to be 58destroyed to the clipboard manager. If there is no running clipboard manager, 59the clipboard string will be unavailable once the window has been destroyed. 60 61GLFW uses the 62[X drag-and-drop protocol](http://www.freedesktop.org/wiki/Specifications/XDND/) 63to provide file drop events. If the application originating the drag does not 64support this protocol, drag and drop will not work. 65 66GLFW uses the XRandR 1.3 extension to provide multi-monitor support. If the 67running X server does not support this version of this extension, multi-monitor 68support will not function and only a single, desktop-spanning monitor will be 69reported. 70 71GLFW uses the XRandR 1.3 and Xf86vidmode extensions to provide gamma ramp 72support. If the running X server does not support either or both of these 73extensions, gamma ramp support will not function. 74 75GLFW uses the Xkb extension and detectable auto-repeat to provide keyboard 76input. If the running X server does not support this extension, a non-Xkb 77fallback path is used. 78 79 80@section compat_glx GLX extensions 81 82The GLX API is the default API used to create OpenGL contexts on Unix-like 83systems using the X Window System. 84 85GLFW uses the GLX 1.3 `GLXFBConfig` functions to enumerate and select framebuffer pixel 86formats. If GLX 1.3 is not supported, @ref glfwInit will fail. 87 88GLFW uses the `GLX_MESA_swap_control,` `GLX_EXT_swap_control` and 89`GLX_SGI_swap_control` extensions to provide vertical retrace synchronization 90(or _vsync_), in that order of preference. Where none of these extension are 91available, calling @ref glfwSwapInterval will have no effect. 92 93GLFW uses the `GLX_ARB_multisample` extension to create contexts with 94multisampling anti-aliasing. Where this extension is unavailable, the 95`GLFW_SAMPLES` hint will have no effect. 96 97GLFW uses the `GLX_ARB_create_context` extension when available, even when 98creating OpenGL contexts of version 2.1 and below. Where this extension is 99unavailable, the `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` 100hints will only be partially supported, the `GLFW_OPENGL_DEBUG_CONTEXT` hint 101will have no effect, and setting the `GLFW_OPENGL_PROFILE` or 102`GLFW_OPENGL_FORWARD_COMPAT` hints to `GLFW_TRUE` will cause @ref 103glfwCreateWindow to fail. 104 105GLFW uses the `GLX_ARB_create_context_profile` extension to provide support for 106context profiles. Where this extension is unavailable, setting the 107`GLFW_OPENGL_PROFILE` hint to anything but `GLFW_OPENGL_ANY_PROFILE`, or setting 108`GLFW_CLIENT_API` to anything but `GLFW_OPENGL_API` or `GLFW_NO_API` will cause 109@ref glfwCreateWindow to fail. 110 111GLFW uses the `GLX_ARB_context_flush_control` extension to provide control over 112whether a context is flushed when it is released (made non-current). Where this 113extension is unavailable, the `GLFW_CONTEXT_RELEASE_BEHAVIOR` hint will have no 114effect and the context will always be flushed when released. 115 116GLFW uses the `GLX_ARB_framebuffer_sRGB` and `GLX_EXT_framebuffer_sRGB` 117extensions to provide support for sRGB framebuffers. Where both of these 118extensions are unavailable, the `GLFW_SRGB_CAPABLE` hint will have no effect. 119 120 121@section compat_wgl WGL extensions 122 123The WGL API is used to create OpenGL contexts on Microsoft Windows and other 124implementations of the Win32 API, such as Wine. 125 126GLFW uses either the `WGL_EXT_extension_string` or the 127`WGL_ARB_extension_string` extension to check for the presence of all other WGL 128extensions listed below. If both are available, the EXT one is preferred. If 129neither is available, no other extensions are used and many GLFW features 130related to context creation will have no effect or cause errors when used. 131 132GLFW uses the `WGL_EXT_swap_control` extension to provide vertical retrace 133synchronization (or _vsync_). Where this extension is unavailable, calling @ref 134glfwSwapInterval will have no effect. 135 136GLFW uses the `WGL_ARB_pixel_format` and `WGL_ARB_multisample` extensions to 137create contexts with multisampling anti-aliasing. Where these extensions are 138unavailable, the `GLFW_SAMPLES` hint will have no effect. 139 140GLFW uses the `WGL_ARB_create_context` extension when available, even when 141creating OpenGL contexts of version 2.1 and below. Where this extension is 142unavailable, the `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` 143hints will only be partially supported, the `GLFW_OPENGL_DEBUG_CONTEXT` hint 144will have no effect, and setting the `GLFW_OPENGL_PROFILE` or 145`GLFW_OPENGL_FORWARD_COMPAT` hints to `GLFW_TRUE` will cause @ref 146glfwCreateWindow to fail. 147 148GLFW uses the `WGL_ARB_create_context_profile` extension to provide support for 149context profiles. Where this extension is unavailable, setting the 150`GLFW_OPENGL_PROFILE` hint to anything but `GLFW_OPENGL_ANY_PROFILE` will cause 151@ref glfwCreateWindow to fail. 152 153GLFW uses the `WGL_ARB_context_flush_control` extension to provide control over 154whether a context is flushed when it is released (made non-current). Where this 155extension is unavailable, the `GLFW_CONTEXT_RELEASE_BEHAVIOR` hint will have no 156effect and the context will always be flushed when released. 157 158GLFW uses the `WGL_ARB_framebuffer_sRGB` and `WGL_EXT_framebuffer_sRGB` 159extensions to provide support for sRGB framebuffers. Where both of these 160extension are unavailable, the `GLFW_SRGB_CAPABLE` hint will have no effect. 161 162 163@section compat_osx OpenGL 3.2 and later on OS X 164 165Support for OpenGL 3.2 and above was introduced with OS X 10.7 and even then 166only forward-compatible, core profile contexts are supported. Support for 167OpenGL 4.1 was introduced with OS X 10.9, also limited to forward-compatible, 168core profile contexts. There is also still no mechanism for requesting debug 169contexts. Versions of Mac OS X earlier than 10.7 support at most OpenGL 170version 2.1. 171 172Because of this, on OS X 10.7 and later, the `GLFW_CONTEXT_VERSION_MAJOR` and 173`GLFW_CONTEXT_VERSION_MINOR` hints will cause @ref glfwCreateWindow to fail if 174given version 3.0 or 3.1, the `GLFW_OPENGL_FORWARD_COMPAT` hint must be set to 175`GLFW_TRUE` and the `GLFW_OPENGL_PROFILE` hint must be set to 176`GLFW_OPENGL_CORE_PROFILE` when creating OpenGL 3.2 and later contexts and the 177`GLFW_OPENGL_DEBUG_CONTEXT` hint is ignored. 178 179Also, on Mac OS X 10.6 and below, the `GLFW_CONTEXT_VERSION_MAJOR` and 180`GLFW_CONTEXT_VERSION_MINOR` hints will fail if given a version above 2.1, 181setting the `GLFW_OPENGL_PROFILE` or `GLFW_OPENGL_FORWARD_COMPAT` hints to 182a non-default value will cause @ref glfwCreateWindow to fail and the 183`GLFW_OPENGL_DEBUG_CONTEXT` hint is ignored. 184 185 186@section compat_vulkan Vulkan loader and API 187 188GLFW uses the standard system-wide Vulkan loader to access the Vulkan API. 189This should be installed by graphics drivers and Vulkan SDKs. If this is not 190available, @ref glfwVulkanSupported will return `GLFW_FALSE` and all other 191Vulkan-related functions will fail with an @ref GLFW_API_UNAVAILABLE error. 192 193 194@section compat_wsi Vulkan WSI extensions 195 196The Vulkan WSI extensions are used to create Vulkan surfaces for GLFW windows on 197all supported platforms. 198 199GLFW uses the `VK_KHR_surface` and `VK_KHR_win32_surface` extensions to create 200surfaces on Microsoft Windows. If any of these extensions are not available, 201@ref glfwGetRequiredInstanceExtensions will return an empty list and window 202surface creation will fail. 203 204GLFW uses the `VK_KHR_surface` and either the `VK_KHR_xlib_surface` or 205`VK_KHR_xcb_surface` extensions to create surfaces on X11. If `VK_KHR_surface` 206or both `VK_KHR_xlib_surface` and `VK_KHR_xcb_surface` are not available, @ref 207glfwGetRequiredInstanceExtensions will return an empty list and window surface 208creation will fail. 209 210GLFW uses the `VK_KHR_surface` and `VK_KHR_wayland_surface` extensions to create 211surfaces on Wayland. If any of these extensions are not available, @ref 212glfwGetRequiredInstanceExtensions will return an empty list and window surface 213creation will fail. 214 215GLFW uses the `VK_KHR_surface` and `VK_KHR_mir_surface` extensions to create 216surfaces on Mir. If any of these extensions are not available, @ref 217glfwGetRequiredInstanceExtensions will return an empty list and window surface 218creation will fail. 219 220GLFW does not support any extensions for window surface creation on OS X, 221meaning@ref glfwGetRequiredInstanceExtensions will return an empty list and 222window surface creation will fail. 223 224*/ 225