You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and dots ('.'), can be up to 35 characters long. Letters must be lowercase.
166 lines
8.2 KiB
166 lines
8.2 KiB
/*! |
|
|
|
@page compat Standards conformance |
|
|
|
@tableofcontents |
|
|
|
This chapter 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 wishing to deploy their applications on machines |
|
with varied specifications. |
|
|
|
Note that the information in this appendix is not a part of the API |
|
specification but merely list some of the preconditions for certain parts of the |
|
API to function on a given machine. As such, any part of it may change in |
|
future versions without this being 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 XInput 2 extension to provide sub-pixel cursor motion events. If |
|
the running X server does not support this version of this extension, cursor |
|
motion will be snapped to the pixel grid. |
|
|
|
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 requires the Xkb extension with 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 `GLXFBConfig` API to enumerate and select framebuffer pixel |
|
formats. This requires GLX 1.3 or greater. |
|
|
|
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 a non-zero value 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 zero, or setting `GLFW_CLIENT_API` to |
|
anything but `GLFW_OPENGL_API` will cause @ref glfwCreateWindow to fail. |
|
|
|
@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 a non-zero value 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 zero will cause @ref glfwCreateWindow |
|
to fail. |
|
|
|
@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 |
|
non-zero 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. |
|
|
|
*/
|
|
|