GLFW 3.0.1 A multi-platform library for OpenGL, window and input

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

All Data Structures Files Functions Variables Typedefs Macros Groups Pages
Standards conformance

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.

# ICCCM and EWMH conformance

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 (ICCCM) and Extended Window Manager Hints (EWMH) standards.

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` protocol to tell the window manager to make the GLFW window full screen. If the running window manager does not support this protocol, full screen windows may not work properly. GLFW has a fallback code path in case this protocol is unavailable, but every window manager behaves slightly differently in this regard.

GLFW uses the clipboard manager protocol 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.

# 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 either GLX 1.3 or greater, or the `GLX_SGIX_fbconfig` extension. Where both are available, the SGIX extension is preferred. If neither is available, GLFW will be unable to create windows.

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 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 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 glfwCreateWindow to fail.

# 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 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 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 glfwCreateWindow to fail.

# OpenGL 3.2 on Mac OS X

Support for OpenGL 3.0 and above was introduced with Mac OS X 10.7, and even then only forward-compatible OpenGL 3.2 core profile contexts are supported. 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 Mac OS X 10.7, the `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` hints will fail if given a version above 3.2, the `GLFW_OPENGL_FORWARD_COMPAT` is required for creating OpenGL 3.2 contexts, the `GLFW_OPENGL_DEBUG_CONTEXT` hint is ignored and setting the `GLFW_OPENGL_PROFILE` hint to anything except `GLFW_OPENGL_CORE_PROFILE` will cause glfwCreateWindow to fail.

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, 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 glfwCreateWindow to fail.