xref: /glfw/
Name Date Size

..05-Sep-20204 KiB

.appveyor.ymlH A D17-Jan-20201.6 KiB

.gitattributesH A D02-Sep-2019142

.gitignoreH A D15-Jul-20201.6 KiB

.mailmapH A D14-Nov-2019384

.travis.ymlH A D02-Sep-20203.3 KiB

CMake/H13-Feb-20204 KiB

CMakeLists.txtH A D02-Sep-202010.8 KiB

deps/H15-Jul-20204 KiB

docs/H07-Sep-20204 KiB

examples/H15-Jul-20204 KiB

include/GLFW/H02-Sep-20194 KiB

LICENSE.mdH A D06-Sep-2019904

README.mdH A D02-Sep-202014.7 KiB

src/H02-Sep-20204 KiB

tests/H15-Jul-20204 KiB

README.md

1# GLFW
2
3[![Build status](https://travis-ci.org/glfw/glfw.svg?branch=master)](https://travis-ci.org/glfw/glfw)
4[![Build status](https://ci.appveyor.com/api/projects/status/0kf0ct9831i5l6sp/branch/master?svg=true)](https://ci.appveyor.com/project/elmindreda/glfw)
5[![Coverity Scan](https://scan.coverity.com/projects/4884/badge.svg)](https://scan.coverity.com/projects/glfw-glfw)
6
7## Introduction
8
9GLFW is an Open Source, multi-platform library for OpenGL, OpenGL ES and Vulkan
10application development.  It provides a simple, platform-independent API for
11creating windows, contexts and surfaces, reading input, handling events, etc.
12
13GLFW natively supports Windows, macOS and Linux and other Unix-like systems.  On
14Linux both X11 and Wayland are supported.
15
16GLFW is licensed under the [zlib/libpng
17license](http://www.glfw.org/license.html).
18
19You can [download](http://www.glfw.org/download.html) the latest stable release
20as source or Windows binaries, or fetch the `latest` branch from GitHub.  Each
21release starting with 3.0 also has a corresponding [annotated
22tag](https://github.com/glfw/glfw/releases) with source and binary archives.
23
24The [documentation](http://www.glfw.org/docs/latest/) is available online and is
25included in all source and binary archives.  See the [release
26notes](https://www.glfw.org/docs/latest/news.html) for new features, caveats and
27deprecations in the latest release.  For more details see the [version
28history](http://www.glfw.org/changelog.html).
29
30The `master` branch is the stable integration branch and _should_ always compile
31and run on all supported platforms, although details of newly added features may
32change until they have been included in a release.  New features and many bug
33fixes live in [other branches](https://github.com/glfw/glfw/branches/all) until
34they are stable enough to merge.
35
36If you are new to GLFW, you may find the
37[tutorial](http://www.glfw.org/docs/latest/quick.html) for GLFW 3 useful.  If
38you have used GLFW 2 in the past, there is a [transition
39guide](http://www.glfw.org/docs/latest/moving.html) for moving to the GLFW
403 API.
41
42
43## Compiling GLFW
44
45GLFW itself requires only the headers and libraries for your OS and window
46system.  It does not need the headers for any context creation API (WGL, GLX,
47EGL, NSGL, OSMesa) or rendering API (OpenGL, OpenGL ES, Vulkan) to enable
48support for them.
49
50GLFW supports compilation on Windows with Visual C++ 2010 and later, MinGW and
51MinGW-w64, on macOS with Clang and on Linux and other Unix-like systems with GCC
52and Clang.  It will likely compile in other environments as well, but this is
53not regularly tested.
54
55There are [pre-compiled Windows binaries](http://www.glfw.org/download.html)
56available for all supported compilers.
57
58See the [compilation guide](http://www.glfw.org/docs/latest/compile.html) for
59more information about how to compile GLFW yourself.
60
61
62## Using GLFW
63
64See the [documentation](http://www.glfw.org/docs/latest/) for tutorials, guides
65and the API reference.
66
67
68## Contributing to GLFW
69
70See the [contribution
71guide](https://github.com/glfw/glfw/blob/master/docs/CONTRIBUTING.md) for
72more information.
73
74
75## System requirements
76
77GLFW supports Windows XP and later and macOS 10.8 and later.  Linux and other
78Unix-like systems running the X Window System are supported even without
79a desktop environment or modern extensions, although some features require
80a running window or clipboard manager.  The OSMesa backend requires Mesa 6.3.
81
82See the [compatibility guide](http://www.glfw.org/docs/latest/compat.html)
83in the documentation for more information.
84
85
86## Dependencies
87
88GLFW itself needs only CMake 3.1 or later and the headers and libraries for your
89OS and window system.
90
91The (experimental) Wayland backend also depends on the `extra-cmake-modules`
92package, which is used to generate Wayland protocol headers.
93
94The examples and test programs depend on a number of tiny libraries.  These are
95located in the `deps/` directory.
96
97 - [getopt\_port](https://github.com/kimgr/getopt_port/) for examples
98   with command-line options
99 - [TinyCThread](https://github.com/tinycthread/tinycthread) for threaded
100   examples
101 - [glad2](https://github.com/Dav1dde/glad) for loading OpenGL and Vulkan
102   functions
103 - [linmath.h](https://github.com/datenwolf/linmath.h) for linear algebra in
104   examples
105 - [Nuklear](https://github.com/vurtun/nuklear) for test and example UI
106 - [stb\_image\_write](https://github.com/nothings/stb) for writing images to disk
107
108The documentation is generated with [Doxygen](http://doxygen.org/) if CMake can
109find that tool.
110
111
112## Reporting bugs
113
114Bugs are reported to our [issue tracker](https://github.com/glfw/glfw/issues).
115Please check the [contribution
116guide](https://github.com/glfw/glfw/blob/master/docs/CONTRIBUTING.md) for
117information on what to include when reporting a bug.
118
119
120## Changelog
121
122 - Added `GLFW_RESIZE_NWSE_CURSOR`, `GLFW_RESIZE_NESW_CURSOR`,
123   `GLFW_RESIZE_ALL_CURSOR` and `GLFW_NOT_ALLOWED_CURSOR` cursor shapes (#427)
124 - Added `GLFW_RESIZE_EW_CURSOR` alias for `GLFW_HRESIZE_CURSOR` (#427)
125 - Added `GLFW_RESIZE_NS_CURSOR` alias for `GLFW_VRESIZE_CURSOR` (#427)
126 - Added `GLFW_POINTING_HAND_CURSOR` alias for `GLFW_HAND_CURSOR` (#427)
127 - Added `GLFW_MOUSE_PASSTHROUGH` window hint for letting mouse input pass
128   through the window (#1236,#1568)
129 - Added `GLFW_FEATURE_UNAVAILABLE` error for platform limitations (#1692)
130 - Added `GLFW_FEATURE_UNIMPLEMENTED` error for incomplete backends (#1692)
131 - Added `GLFW_ANGLE_PLATFORM_TYPE` init hint and `GLFW_ANGLE_PLATFORM_TYPE_*`
132   values to select ANGLE backend (#1380)
133 - Made joystick subsystem initialize at first use (#1284,#1646)
134 - Updated the minimum required CMake version to 3.1
135 - Disabled tests and examples by default when built as a CMake subdirectory
136 - Bugfix: The CMake config-file package used an absolute path and was not
137   relocatable (#1470)
138 - Bugfix: Video modes with a duplicate screen area were discarded (#1555,#1556)
139 - Bugfix: Compiling with -Wextra-semi caused warnings (#1440)
140 - Bugfix: Built-in mappings failed because some OEMs re-used VID/PID (#1583)
141 - Bugfix: Some extension loader headers did not prevent default OpenGL header
142   inclusion (#1695)
143 - [Win32] Added the `GLFW_WIN32_KEYBOARD_MENU` window hint for enabling access
144           to the window menu
145 - [Win32] Added a version info resource to the GLFW DLL
146 - [Win32] Disabled framebuffer transparency on Windows 7 when DWM windows are
147   opaque (#1512)
148 - [Win32] Bugfix: `GLFW_INCLUDE_VULKAN` plus `VK_USE_PLATFORM_WIN32_KHR` caused
149   symbol redefinition (#1524)
150 - [Win32] Bugfix: The cursor position event was emitted before its cursor enter
151   event (#1490)
152 - [Win32] Bugfix: The window hint `GLFW_MAXIMIZED` did not move or resize the
153   window (#1499)
154 - [Win32] Bugfix: Disabled cursor mode interfered with some non-client actions
155 - [Win32] Bugfix: Super key was not released after Win+V hotkey (#1622)
156 - [Win32] Bugfix: `glfwGetKeyName` could access out of bounds and return an
157   invalid pointer
158 - [Win32] Bugfix: Some synthetic key events were reported as `GLFW_KEY_UNKNOWN`
159   (#1623)
160 - [Win32] Bugfix: Non-BMP Unicode codepoint input was reported as UTF-16
161 - [Cocoa] Added support for `VK_EXT_metal_surface` (#1619)
162 - [Cocoa] Added locating the Vulkan loader at runtime in an application bundle
163 - [Cocoa] Moved main menu creation to GLFW initialization time (#1649)
164 - [Cocoa] Changed `EGLNativeWindowType` from `NSView` to `CALayer` (#1169)
165 - [Cocoa] Removed dependency on the CoreVideo framework
166 - [Cocoa] Bugfix: `glfwSetWindowSize` used a bottom-left anchor point (#1553)
167 - [Cocoa] Bugfix: Window remained on screen after destruction until event poll
168   (#1412)
169 - [Cocoa] Bugfix: Event processing before window creation would assert (#1543)
170 - [Cocoa] Bugfix: Undecorated windows could not be iconified on recent macOS
171 - [Cocoa] Bugfix: Touching event queue from secondary thread before main thread
172   would abort (#1649)
173 - [Cocoa] Bugfix: Non-BMP Unicode codepoint input was reported as UTF-16
174   (#1635)
175 - [Cocoa] Bugfix: Failing to retrieve the refresh rate of built-in displays
176   could leak memory
177 - [X11] Bugfix: The CMake files did not check for the XInput headers (#1480)
178 - [X11] Bugfix: Key names were not updated when the keyboard layout changed
179   (#1462,#1528)
180 - [X11] Bugfix: Decorations could not be enabled after window creation (#1566)
181 - [X11] Bugfix: Content scale fallback value could be inconsistent (#1578)
182 - [X11] Bugfix: `glfwMaximizeWindow` had no effect on hidden windows
183 - [X11] Bugfix: Clearing `GLFW_FLOATING` on a hidden window caused invalid read
184 - [X11] Bugfix: Changing `GLFW_FLOATING` on a hidden window could silently fail
185 - [X11] Bugfix: Disabled cursor mode was interrupted by indicator windows
186 - [X11] Bugfix: Monitor physical dimensions could be reported as zero mm
187 - [X11] Bugfix: Window position events were not emitted during resizing (#1613)
188 - [X11] Bugfix: `glfwFocusWindow` could terminate on older WMs or without a WM
189 - [X11] Bugfix: Querying a disconnected monitor could segfault (#1602)
190 - [X11] Bugfix: IME input of CJK was broken for "C" locale (#1587,#1636)
191 - [X11] Bugfix: Termination would segfault if the IM had been destroyed
192 - [X11] Bugfix: Any IM started after initialization would not be detected
193 - [X11] Bugfix: Xlib errors caused by other parts of the application could be
194   reported as GLFW errors
195 - [X11] Bugfix: A handle race condition could cause a `BadWindow` error (#1633)
196 - [X11] Bugfix: XKB path used keysyms instead of physical locations for
197   non-printable keys (#1598)
198 - [X11] Bugfix: Function keys were mapped to `GLFW_KEY_UNKNOWN` for some layout
199   combinaitons (#1598)
200 - [X11] Bugfix: Keys pressed simultaneously with others were not always
201   reported (#1112,#1415,#1472,#1616)
202 - [Wayland] Removed support for `wl_shell` (#1443)
203 - [Wayland] Bugfix: The `GLFW_HAND_CURSOR` shape used the wrong image (#1432)
204 - [Wayland] Bugfix: `CLOCK_MONOTONIC` was not correctly enabled
205 - [Wayland] Bugfix: Repeated keys could be reported with `NULL` window (#1704)
206 - [Wayland] Bugfix: Retrieving partial framebuffer size would segfault
207 - [Wayland] Bugfix: Scrolling offsets were inverted compared to other platforms
208   (#1463)
209 - [POSIX] Bugfix: `CLOCK_MONOTONIC` was not correctly tested for or enabled
210 - [NSGL] Removed enforcement of forward-compatible flag for core contexts
211 - [NSGL] Bugfix: `GLFW_COCOA_RETINA_FRAMEBUFFER` had no effect on newer
212   macOS versions (#1442)
213 - [NSGL] Bugfix: Workaround for swap interval on 10.14 broke on 10.12 (#1483)
214 - [EGL] Added platform selection via the `EGL_EXT_platform_base` extension
215   (#442)
216 - [EGL] Added ANGLE backend selection via `EGL_ANGLE_platform_angle` extension
217   (#1380)
218
219
220## Contact
221
222On [glfw.org](http://www.glfw.org/) you can find the latest version of GLFW, as
223well as news, documentation and other information about the project.
224
225If you have questions related to the use of GLFW, we have a
226[forum](https://discourse.glfw.org/), and the `#glfw` IRC channel on
227[Freenode](http://freenode.net/).
228
229If you have a bug to report, a patch to submit or a feature you'd like to
230request, please file it in the
231[issue tracker](https://github.com/glfw/glfw/issues) on GitHub.
232
233Finally, if you're interested in helping out with the development of GLFW or
234porting it to your favorite platform, join us on the forum, GitHub or IRC.
235
236
237## Acknowledgements
238
239GLFW exists because people around the world donated their time and lent their
240skills.
241
242 - Bobyshev Alexander
243 - Matt Arsenault
244 - David Avedissian
245 - Keith Bauer
246 - John Bartholomew
247 - Coşku Baş
248 - Niklas Behrens
249 - Andrew Belt
250 - Niklas Bergström
251 - Denis Bernard
252 - Doug Binks
253 - blanco
254 - Kyle Brenneman
255 - Rok Breulj
256 - Kai Burjack
257 - Martin Capitanio
258 - David Carlier
259 - Arturo Castro
260 - Chi-kwan Chan
261 - Ian Clarkson
262 - Michał Cichoń
263 - Lambert Clara
264 - Anna Clarke
265 - Yaron Cohen-Tal
266 - Omar Cornut
267 - Andrew Corrigan
268 - Bailey Cosier
269 - Noel Cower
270 - Jason Daly
271 - Jarrod Davis
272 - Olivier Delannoy
273 - Paul R. Deppe
274 - Michael Dickens
275 - Роман Донченко
276 - Mario Dorn
277 - Wolfgang Draxinger
278 - Jonathan Dummer
279 - Ralph Eastwood
280 - Fredrik Ehnbom
281 - Robin Eklind
282 - Siavash Eliasi
283 - Felipe Ferreira
284 - Michael Fogleman
285 - Gerald Franz
286 - Mário Freitas
287 - GeO4d
288 - Marcus Geelnard
289 - Charles Giessen
290 - Ryan C. Gordon
291 - Stephen Gowen
292 - Kovid Goyal
293 - Eloi Marín Gratacós
294 - Stefan Gustavson
295 - Jonathan Hale
296 - Sylvain Hellegouarch
297 - Matthew Henry
298 - heromyth
299 - Lucas Hinderberger
300 - Paul Holden
301 - Warren Hu
302 - Charles Huber
303 - IntellectualKitty
304 - Aaron Jacobs
305 - Erik S. V. Jansson
306 - Toni Jovanoski
307 - Arseny Kapoulkine
308 - Cem Karan
309 - Osman Keskin
310 - Josh Kilmer
311 - Byunghoon Kim
312 - Cameron King
313 - Peter Knut
314 - Christoph Kubisch
315 - Yuri Kunde Schlesner
316 - Rokas Kupstys
317 - Konstantin Käfer
318 - Eric Larson
319 - Francis Lecavalier
320 - Robin Leffmann
321 - Glenn Lewis
322 - Shane Liesegang
323 - Anders Lindqvist
324 - Leon Linhart
325 - Eyal Lotem
326 - Aaron Loucks
327 - Luflosi
328 - lukect
329 - Tristam MacDonald
330 - Hans Mackowiak
331 - Дмитри Малышев
332 - Zbigniew Mandziejewicz
333 - Adam Marcus
334 - Célestin Marot
335 - Kyle McDonald
336 - David Medlock
337 - Bryce Mehring
338 - Jonathan Mercier
339 - Marcel Metz
340 - Liam Middlebrook
341 - Ave Milia
342 - Jonathan Miller
343 - Kenneth Miller
344 - Bruce Mitchener
345 - Jack Moffitt
346 - Jeff Molofee
347 - Alexander Monakov
348 - Pierre Morel
349 - Jon Morton
350 - Pierre Moulon
351 - Martins Mozeiko
352 - Julian Møller
353 - ndogxj
354 - Kristian Nielsen
355 - Kamil Nowakowski
356 - onox
357 - Denis Ovod
358 - Ozzy
359 - Andri Pálsson
360 - Peoro
361 - Braden Pellett
362 - Christopher Pelloux
363 - Arturo J. Pérez
364 - Anthony Pesch
365 - Orson Peters
366 - Emmanuel Gil Peyrot
367 - Cyril Pichard
368 - Keith Pitt
369 - Stanislav Podgorskiy
370 - Konstantin Podsvirov
371 - Nathan Poirier
372 - Alexandre Pretyman
373 - Pablo Prietz
374 - przemekmirek
375 - pthom
376 - Guillaume Racicot
377 - Philip Rideout
378 - Eddie Ringle
379 - Max Risuhin
380 - Jorge Rodriguez
381 - Luca Rood
382 - Ed Ropple
383 - Aleksey Rybalkin
384 - Mikko Rytkönen
385 - Riku Salminen
386 - Brandon Schaefer
387 - Sebastian Schuberth
388 - Christian Sdunek
389 - Matt Sealey
390 - Steve Sexton
391 - Arkady Shapkin
392 - Ali Sherief
393 - Yoshiki Shibukawa
394 - Dmitri Shuralyov
395 - Daniel Skorupski
396 - Bradley Smith
397 - Cliff Smolinsky
398 - Patrick Snape
399 - Erlend Sogge Heggen
400 - Julian Squires
401 - Johannes Stein
402 - Pontus Stenetorp
403 - Michael Stocker
404 - Justin Stoecker
405 - Elviss Strazdins
406 - Paul Sultana
407 - Nathan Sweet
408 - TTK-Bandit
409 - Jared Tiala
410 - Sergey Tikhomirov
411 - Arthur Tombs
412 - Ioannis Tsakpinis
413 - Samuli Tuomola
414 - Matthew Turner
415 - urraka
416 - Elias Vanderstuyft
417 - Stef Velzel
418 - Jari Vetoniemi
419 - Ricardo Vieira
420 - Nicholas Vitovitch
421 - Simon Voordouw
422 - Corentin Wallez
423 - Torsten Walluhn
424 - Patrick Walton
425 - Xo Wang
426 - Waris
427 - Jay Weisskopf
428 - Frank Wille
429 - Tatsuya Yatagawa
430 - Ryogo Yoshimura
431 - Lukas Zanner
432 - Andrey Zholos
433 - Aihui Zhu
434 - Santi Zupancic
435 - Jonas Ådahl
436 - Lasse Öörni
437 - All the unmentioned and anonymous contributors in the GLFW community, for bug
438   reports, patches, feedback, testing and encouragement
439
440