You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
224 lines
11 KiB
224 lines
11 KiB
/*!
|
|
|
|
@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](http://www.tronche.com/gui/x/icccm/)
|
|
(ICCCM) and
|
|
[Extended Window Manager Hints](http://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](http://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](http://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.
|
|
|
|
|
|
@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 3.2 and later on OS X
|
|
|
|
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. 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 and the
|
|
`GLFW_OPENGL_DEBUG_CONTEXT` hint is 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
|
|
|
|
GLFW uses the standard system-wide Vulkan loader to access the Vulkan API.
|
|
This should be installed by graphics drivers and Vulkan SDKs. If this is not
|
|
available, @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_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.
|
|
|
|
GLFW uses the `VK_KHR_surface` and `VK_KHR_mir_surface` extensions to create
|
|
surfaces on Mir. If any of these extensions are not available, @ref
|
|
glfwGetRequiredInstanceExtensions will return an empty list and window surface
|
|
creation will fail.
|
|
|
|
GLFW does not support any extensions for window surface creation on OS X,
|
|
meaning@ref glfwGetRequiredInstanceExtensions will return an empty list and
|
|
window surface creation will fail.
|
|
|
|
*/
|