compat.dox 14.3 KB
Newer Older
1
2
/*!

3
@page compat_guide Standards conformance
4

Camilla Berglund's avatar
Camilla Berglund committed
5
6
@tableofcontents

Camilla Berglund's avatar
Camilla Berglund committed
7
This guide describes the various API extensions used by this version of GLFW.
8
It lists what are essentially implementation details, but which are nonetheless
Camilla Berglund's avatar
Camilla Berglund committed
9
10
11
vital knowledge for developers intending to deploy their applications on a wide
range of machines.

Camilla Berglund's avatar
Camilla Berglund committed
12
The information in this guide is not a part of GLFW API, but merely
Camilla Berglund's avatar
Camilla Berglund committed
13
14
15
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.
16
17


18
@section compat_x11 X11 extensions, protocols and IPC standards
19

Camilla Berglund's avatar
Camilla Berglund committed
20
As GLFW uses Xlib directly, without any intervening toolkit
21
22
23
24
25
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
MrVallentin's avatar
MrVallentin committed
26
[Inter-Client Communication Conventions Manual](https://www.tronche.com/gui/x/icccm/)
27
(ICCCM) and
MrVallentin's avatar
MrVallentin committed
28
[Extended Window Manager Hints](https://standards.freedesktop.org/wm-spec/wm-spec-latest.html)
29
30
(EWMH) standards.

Camilla Berglund's avatar
Camilla Berglund committed
31
32
33
34
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.

35
GLFW uses the ICCCM `WM_DELETE_WINDOW` protocol to intercept the user
36
37
38
attempting to close the GLFW window.  If the running window manager does not
support this protocol, the close callback will never be called.

39
GLFW uses the EWMH `_NET_WM_PING` protocol, allowing the window manager notify
40
41
42
43
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.

Camilla Berglund's avatar
Camilla Berglund committed
44
45
46
47
48
49
50
51
52
53
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.
54

55
GLFW uses the
MrVallentin's avatar
MrVallentin committed
56
[clipboard manager protocol](https://www.freedesktop.org/wiki/ClipboardManager/)
57
58
59
60
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.

61
GLFW uses the
MrVallentin's avatar
MrVallentin committed
62
[X drag-and-drop protocol](https://www.freedesktop.org/wiki/Specifications/XDND/)
63
64
65
to provide file drop events.  If the application originating the drag does not
support this protocol, drag and drop will not work.

66
67
68
69
70
71
72
73
74
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.

75
GLFW uses the Xkb extension and detectable auto-repeat to provide keyboard
Camilla Berglund's avatar
Camilla Berglund committed
76
77
input.  If the running X server does not support this extension, a non-Xkb
fallback path is used.
78

Camilla Löwy's avatar
Camilla Löwy committed
79
80
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
81
extension, regular accelerated mouse motion will be used.
Camilla Löwy's avatar
Camilla Löwy committed
82

83
84
GLFW uses both the XRender extension and the compositing manager to support
transparent window framebuffers.  If the running X server does not support this
85
86
extension or there is no running compositing manager, the
`GLFW_TRANSPARENT_FRAMEBUFFER` framebuffer hint will have no effect.
87

Camilla Berglund's avatar
Camilla Berglund committed
88

Emmanuel Gil Peyrot's avatar
Emmanuel Gil Peyrot committed
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
@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 compose key support.  When it has been
built against an older xkbcommon, the compose key will be disabled even if it
has been configured in the compositor.

Emmanuel Gil Peyrot's avatar
Emmanuel Gil Peyrot committed
104
105
106
107
108
109
110
111
112
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 mandatory at build time.  If the running compositor
does not support this protocol, the older [wl_shell
interface](https://cgit.freedesktop.org/wayland/wayland/tree/protocol/wayland.xml#n972)
will be used instead.  This will result in a worse integration with the
desktop, especially on tiling compositors.

Emmanuel Gil Peyrot's avatar
Emmanuel Gil Peyrot committed
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
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.

Emmanuel Gil Peyrot's avatar
Emmanuel Gil Peyrot committed
129
130
131
132
133
134
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
Emmanuel Gil Peyrot's avatar
Emmanuel Gil Peyrot committed
135
136
protocol](https://cgit.freedesktop.org/wayland/wayland-protocols/tree/stable/viewporter/viewporter.xml)
alongside
Emmanuel Gil Peyrot's avatar
Emmanuel Gil Peyrot committed
137
138
139
140
[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.
Emmanuel Gil Peyrot's avatar
Emmanuel Gil Peyrot committed
141

Emmanuel Gil Peyrot's avatar
Emmanuel Gil Peyrot committed
142

143
144
145
146
147
@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.

Camilla Berglund's avatar
Camilla Berglund committed
148
149
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.
150

151
152
GLFW uses the `GLX_MESA_swap_control,` `GLX_EXT_swap_control` and
`GLX_SGI_swap_control` extensions to provide vertical retrace synchronization
Camilla Berglund's avatar
Camilla Berglund committed
153
(or _vsync_), in that order of preference.  Where none of these extension are
154
155
available, calling @ref glfwSwapInterval will have no effect.

156
157
158
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.
159

160
GLFW uses the `GLX_ARB_create_context` extension when available, even when
161
creating OpenGL contexts of version 2.1 and below.  Where this extension is
162
163
164
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
165
`GLFW_OPENGL_FORWARD_COMPAT` hints to `GLFW_TRUE` will cause @ref
166
167
glfwCreateWindow to fail.

168
169
GLFW uses the `GLX_ARB_create_context_profile` extension to provide support for
context profiles.  Where this extension is unavailable, setting the
Camilla Berglund's avatar
Camilla Berglund committed
170
`GLFW_OPENGL_PROFILE` hint to anything but `GLFW_OPENGL_ANY_PROFILE`, or setting
171
172
`GLFW_CLIENT_API` to anything but `GLFW_OPENGL_API` or `GLFW_NO_API` will cause
@ref glfwCreateWindow to fail.
173

174
175
176
177
178
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.

179
180
181
182
183
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.


184
185
186
187
188
@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.

189
190
GLFW uses either the `WGL_EXT_extension_string` or the
`WGL_ARB_extension_string` extension to check for the presence of all other WGL
191
192
193
194
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.

195
GLFW uses the `WGL_EXT_swap_control` extension to provide vertical retrace
Camilla Berglund's avatar
Camilla Berglund committed
196
synchronization (or _vsync_).  Where this extension is unavailable, calling @ref
197
198
glfwSwapInterval will have no effect.

199
GLFW uses the `WGL_ARB_pixel_format` and `WGL_ARB_multisample` extensions to
200
create contexts with multisampling anti-aliasing.  Where these extensions are
201
unavailable, the `GLFW_SAMPLES` hint will have no effect.
202

203
GLFW uses the `WGL_ARB_create_context` extension when available, even when
204
creating OpenGL contexts of version 2.1 and below.  Where this extension is
205
206
207
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
208
`GLFW_OPENGL_FORWARD_COMPAT` hints to `GLFW_TRUE` will cause @ref
209
210
glfwCreateWindow to fail.

211
212
GLFW uses the `WGL_ARB_create_context_profile` extension to provide support for
context profiles.  Where this extension is unavailable, setting the
Camilla Berglund's avatar
Camilla Berglund committed
213
214
`GLFW_OPENGL_PROFILE` hint to anything but `GLFW_OPENGL_ANY_PROFILE` will cause
@ref glfwCreateWindow to fail.
215

216
217
218
219
220
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.

221
222
223
224
225
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.


Camilla Löwy's avatar
Camilla Löwy committed
226
@section compat_osx OpenGL on macOS
227
228
229
230
231

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
Camilla Löwy's avatar
Camilla Löwy committed
232
233
contexts or no-error contexts.  Versions of Mac OS X earlier than 10.7 support
at most OpenGL version 2.1.
234
235
236

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
Camilla Löwy's avatar
Camilla Löwy committed
237
given version 3.0 or 3.1.  The `GLFW_OPENGL_FORWARD_COMPAT` hint must be set to
238
`GLFW_TRUE` and the `GLFW_OPENGL_PROFILE` hint must be set to
Camilla Löwy's avatar
Camilla Löwy committed
239
240
`GLFW_OPENGL_CORE_PROFILE` when creating OpenGL 3.2 and later contexts.  The
`GLFW_OPENGL_DEBUG_CONTEXT` and `GLFW_CONTEXT_NO_ERROR` hints are ignored.
241

242
Also, on Mac OS X 10.6 and below, the `GLFW_CONTEXT_VERSION_MAJOR` and
243
244
245
246
`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.
247

Camilla Berglund's avatar
Camilla Berglund committed
248
249
250

@section compat_vulkan Vulkan loader and API

251
252
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
253
254
255
256
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.
Camilla Berglund's avatar
Camilla Berglund committed
257
258
259
260
261
262
263
264
265
266
267
268


@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.

269
270
271
272
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.
273

Camilla Berglund's avatar
Camilla Berglund committed
274
275
276
277
278
279
280
281
282
283
284
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.

285
*/