README.md 9.33 KB
Newer Older
Camilla Berglund's avatar
Camilla Berglund committed
1
# GLFW
2

Camilla Berglund's avatar
Camilla Berglund committed
3
4
[![Build status](https://travis-ci.org/glfw/glfw.svg?branch=master)](https://travis-ci.org/glfw/glfw)
[![Build status](https://ci.appveyor.com/api/projects/status/0kf0ct9831i5l6sp/branch/master?svg=true)](https://ci.appveyor.com/project/elmindreda/glfw)
Camilla Berglund's avatar
Camilla Berglund committed
5
[![Coverity Scan](https://scan.coverity.com/projects/4884/badge.svg)](https://scan.coverity.com/projects/glfw-glfw)
Camilla Berglund's avatar
Camilla Berglund committed
6

7
8
## Introduction

Camilla Berglund's avatar
Camilla Berglund committed
9
10
11
GLFW is an Open Source, multi-platform library for OpenGL, OpenGL ES and Vulkan
application development.  It provides a simple, platform-independent API for
creating windows, contexts and surfaces, reading input, handling events, etc.
12

Camilla Löwy's avatar
Camilla Löwy committed
13
GLFW natively supports Windows, macOS and Linux and other Unix-like systems.  On
Luflosi's avatar
Luflosi committed
14
Linux both X11 and Wayland are supported.
Camilla Löwy's avatar
Camilla Löwy committed
15

Camilla Berglund's avatar
Camilla Berglund committed
16
GLFW is licensed under the [zlib/libpng
Camilla Berglund's avatar
Camilla Berglund committed
17
license](http://www.glfw.org/license.html).
Camilla Berglund's avatar
Camilla Berglund committed
18

Camilla Löwy's avatar
Camilla Löwy committed
19
20
21
You can [download](http://www.glfw.org/download.html) the latest stable release
as source or Windows binaries, or fetch the `latest` branch from GitHub.  Each
release starting with 3.0 also has a corresponding [annotated
Camilla Berglund's avatar
Camilla Berglund committed
22
23
tag](https://github.com/glfw/glfw/releases) with source and binary archives.

Camilla Löwy's avatar
Camilla Löwy committed
24
25
26
27
28
The [documentation](http://www.glfw.org/docs/latest/) is available online and is
included in all source and binary archives.  See the [release
notes](https://www.glfw.org/docs/latest/news.html) for new features, caveats and
deprecations in the latest release.  For more details see the [version
history](http://www.glfw.org/changelog.html).
Camilla Löwy's avatar
Camilla Löwy committed
29
30
31
32
33
34

The `master` branch is the stable integration branch and _should_ always compile
and run on all supported platforms, although details of newly added features may
change until they have been included in a release.  New features and many bug
fixes live in [other branches](https://github.com/glfw/glfw/branches/all) until
they are stable enough to merge.
Camilla Berglund's avatar
Camilla Berglund committed
35

36
If you are new to GLFW, you may find the
Camilla Löwy's avatar
Camilla Löwy committed
37
38
39
40
[tutorial](http://www.glfw.org/docs/latest/quick.html) for GLFW 3 useful.  If
you have used GLFW 2 in the past, there is a [transition
guide](http://www.glfw.org/docs/latest/moving.html) for moving to the GLFW
3 API.
41
42


43
## Compiling GLFW
Camilla Berglund's avatar
Camilla Berglund committed
44

Camilla Löwy's avatar
Camilla Löwy committed
45
46
47
48
GLFW itself requires only the headers and libraries for your OS and window
system.  It does not need the headers for any context creation API (WGL, GLX,
EGL, NSGL, OSMesa) or rendering API (OpenGL, OpenGL ES, Vulkan) to enable
support for them.
Camilla Berglund's avatar
Camilla Berglund committed
49

Camilla Berglund's avatar
Camilla Berglund committed
50
GLFW supports compilation on Windows with Visual C++ 2010 and later, MinGW and
51
MinGW-w64, on macOS with Clang and on Linux and other Unix-like systems with GCC
Camilla Berglund's avatar
Camilla Berglund committed
52
53
and Clang.  It will likely compile in other environments as well, but this is
not regularly tested.
54

Camilla Löwy's avatar
Camilla Löwy committed
55
56
There are [pre-compiled Windows binaries](http://www.glfw.org/download.html)
available for all supported compilers.
57

Camilla Löwy's avatar
Camilla Löwy committed
58
See the [compilation guide](http://www.glfw.org/docs/latest/compile.html) for
Camilla Löwy's avatar
Camilla Löwy committed
59
more information about how to compile GLFW yourself.
60

Camilla Berglund's avatar
Camilla Berglund committed
61

Camilla Berglund's avatar
Camilla Berglund committed
62
## Using GLFW
Camilla Berglund's avatar
Camilla Berglund committed
63

Camilla Löwy's avatar
Camilla Löwy committed
64
65
66
67
68
69
70
See the [documentation](http://www.glfw.org/docs/latest/) for tutorials, guides
and the API reference.


## Contributing to GLFW

See the [contribution
71
guide](https://github.com/glfw/glfw/blob/master/docs/CONTRIBUTING.md) for
Camilla Löwy's avatar
Camilla Löwy committed
72
more information.
Camilla Berglund's avatar
Camilla Berglund committed
73
74


Camilla Berglund's avatar
Camilla Berglund committed
75
## System requirements
Camilla Berglund's avatar
Camilla Berglund committed
76

77
GLFW supports Windows XP and later and macOS 10.8 and later.  Linux and other
Camilla Löwy's avatar
Camilla Löwy committed
78
79
80
Unix-like systems running the X Window System are supported even without
a desktop environment or modern extensions, although some features require
a running window or clipboard manager.  The OSMesa backend requires Mesa 6.3.
Camilla Berglund's avatar
Camilla Berglund committed
81
82

See the [compatibility guide](http://www.glfw.org/docs/latest/compat.html)
Camilla Berglund's avatar
Camilla Berglund committed
83
in the documentation for more information.
Camilla Berglund's avatar
Camilla Berglund committed
84
85


86
87
## Dependencies

Camilla Berglund's avatar
Camilla Berglund committed
88
89
GLFW itself depends only on the headers and libraries for your window system.

90
The (experimental) Wayland backend also depends on the `extra-cmake-modules`
Camilla Löwy's avatar
Camilla Löwy committed
91
package, which is used to generate Wayland protocol headers.
92

Camilla Berglund's avatar
Camilla Berglund committed
93
94
The examples and test programs depend on a number of tiny libraries.  These are
located in the `deps/` directory.
95

Camilla Berglund's avatar
Camilla Berglund committed
96
97
 - [getopt\_port](https://github.com/kimgr/getopt_port/) for examples
   with command-line options
Camilla Berglund's avatar
Camilla Berglund committed
98
 - [TinyCThread](https://github.com/tinycthread/tinycthread) for threaded
Camilla Berglund's avatar
Camilla Berglund committed
99
   examples
100
101
 - [glad2](https://github.com/Dav1dde/glad) for loading OpenGL and Vulkan
   functions
102
103
 - [linmath.h](https://github.com/datenwolf/linmath.h) for linear algebra in
   examples
Camilla Berglund's avatar
Camilla Berglund committed
104
 - [Nuklear](https://github.com/vurtun/nuklear) for test and example UI
Camilla Berglund's avatar
Camilla Berglund committed
105
 - [stb\_image\_write](https://github.com/nothings/stb) for writing images to disk
Camilla Berglund's avatar
Camilla Berglund committed
106

Camilla Löwy's avatar
Camilla Löwy committed
107
108
The documentation is generated with [Doxygen](http://doxygen.org/) if CMake can
find that tool.
Camilla Berglund's avatar
Camilla Berglund committed
109

110

Camilla Berglund's avatar
Camilla Berglund committed
111
112
113
114
## Reporting bugs

Bugs are reported to our [issue tracker](https://github.com/glfw/glfw/issues).
Please check the [contribution
115
guide](https://github.com/glfw/glfw/blob/master/docs/CONTRIBUTING.md) for
Camilla Berglund's avatar
Camilla Berglund committed
116
117
118
information on what to include when reporting a bug.


Camilla Berglund's avatar
Camilla Berglund committed
119
## Changelog
120

121
 - [Win32] Bugfix: Super key was not released after Win+V hotkey (#1622)
122
123
 - [Win32] Bugfix: `glfwGetKeyName` could access out of bounds and return an
   invalid pointer
124
125
 - [Win32] Bugfix: Some synthetic key events were reported as `GLFW_KEY_UNKNOWN`
   (#1623)
126
 - [Cocoa] Added support for `VK_EXT_metal_surface` (#1619)
127
 - [Cocoa] Added locating the Vulkan loader at runtime in an application bundle
128
 - [X11] Bugfix: `glfwFocusWindow` could terminate on older WMs or without a WM
Camilla Löwy's avatar
Camilla Löwy committed
129
 - [X11] Bugfix: Creating an undecorated window could fail with BadMatch (#1620)
130

131
132
133

## Contact

Camilla Berglund's avatar
Camilla Berglund committed
134
135
On [glfw.org](http://www.glfw.org/) you can find the latest version of GLFW, as
well as news, documentation and other information about the project.
136
137

If you have questions related to the use of GLFW, we have a
Camilla Löwy's avatar
Camilla Löwy committed
138
[forum](https://discourse.glfw.org/), and the `#glfw` IRC channel on
Camilla Berglund's avatar
Camilla Berglund committed
139
[Freenode](http://freenode.net/).
140
141

If you have a bug to report, a patch to submit or a feature you'd like to
142
143
request, please file it in the
[issue tracker](https://github.com/glfw/glfw/issues) on GitHub.
144
145

Finally, if you're interested in helping out with the development of GLFW or
Camilla Berglund's avatar
Camilla Berglund committed
146
porting it to your favorite platform, join us on the forum, GitHub or IRC.
147
148
149
150
151
152
153


## Acknowledgements

GLFW exists because people around the world donated their time and lent their
skills.

Camilla Berglund's avatar
Camilla Berglund committed
154
155
 - Bobyshev Alexander
 - Matt Arsenault
Camilla Löwy's avatar
Camilla Löwy committed
156
 - David Avedissian
Camilla Berglund's avatar
Camilla Berglund committed
157
158
 - Keith Bauer
 - John Bartholomew
Camilla Löwy's avatar
Camilla Löwy committed
159
 - Coşku Baş
160
 - Niklas Behrens
Camilla Löwy's avatar
Camilla Löwy committed
161
 - Andrew Belt
Camilla Berglund's avatar
Camilla Berglund committed
162
 - Niklas Bergström
Camilla Löwy's avatar
Cleanup    
Camilla Löwy committed
163
 - Denis Bernard
164
 - Doug Binks
Camilla Berglund's avatar
Camilla Berglund committed
165
 - blanco
Camilla Berglund's avatar
Cleanup    
Camilla Berglund committed
166
 - Kyle Brenneman
Camilla Löwy's avatar
Camilla Löwy committed
167
 - Rok Breulj
168
 - Kai Burjack
169
 - Martin Capitanio
Camilla Löwy's avatar
Cleanup    
Camilla Löwy committed
170
 - David Carlier
Camilla Löwy's avatar
Camilla Löwy committed
171
 - Arturo Castro
Camilla Berglund's avatar
Camilla Berglund committed
172
 - Chi-kwan Chan
Camilla Löwy's avatar
Camilla Löwy committed
173
 - Ian Clarkson
Camilla Löwy's avatar
Cleanup    
Camilla Löwy committed
174
 - Michał Cichoń
Camilla Berglund's avatar
Camilla Berglund committed
175
 - Lambert Clara
Camilla Löwy's avatar
Camilla Löwy committed
176
 - Anna Clarke
Camilla Löwy's avatar
Camilla Löwy committed
177
178
 - Yaron Cohen-Tal
 - Omar Cornut
Camilla Berglund's avatar
Camilla Berglund committed
179
 - Andrew Corrigan
180
 - Bailey Cosier
Camilla Berglund's avatar
Camilla Berglund committed
181
 - Noel Cower
Camilla Berglund's avatar
Camilla Berglund committed
182
 - Jason Daly
Camilla Berglund's avatar
Camilla Berglund committed
183
184
185
 - Jarrod Davis
 - Olivier Delannoy
 - Paul R. Deppe
Camilla Berglund's avatar
Camilla Berglund committed
186
 - Michael Dickens
Camilla Berglund's avatar
Camilla Berglund committed
187
 - Роман Донченко
188
 - Mario Dorn
189
 - Wolfgang Draxinger
Camilla Berglund's avatar
Camilla Berglund committed
190
191
 - Jonathan Dummer
 - Ralph Eastwood
Camilla Löwy's avatar
Camilla Löwy committed
192
193
 - Fredrik Ehnbom
 - Robin Eklind
194
 - Siavash Eliasi
Camilla Löwy's avatar
Cleanup    
Camilla Löwy committed
195
 - Felipe Ferreira
Camilla Berglund's avatar
Camilla Berglund committed
196
 - Michael Fogleman
Camilla Berglund's avatar
Camilla Berglund committed
197
 - Gerald Franz
Camilla Berglund's avatar
Cleanup    
Camilla Berglund committed
198
 - Mário Freitas
Camilla Berglund's avatar
Camilla Berglund committed
199
200
 - GeO4d
 - Marcus Geelnard
201
 - Charles Giessen
202
 - Ryan C. Gordon
Camilla Löwy's avatar
Camilla Löwy committed
203
204
 - Stephen Gowen
 - Kovid Goyal
205
 - Eloi Marín Gratacós
Camilla Berglund's avatar
Camilla Berglund committed
206
 - Stefan Gustavson
Camilla Löwy's avatar
Camilla Löwy committed
207
 - Jonathan Hale
Camilla Berglund's avatar
Camilla Berglund committed
208
 - Sylvain Hellegouarch
209
 - Matthew Henry
Camilla Berglund's avatar
Camilla Berglund committed
210
 - heromyth
211
 - Lucas Hinderberger
212
 - Paul Holden
Camilla Berglund's avatar
Cleanup    
Camilla Berglund committed
213
 - Warren Hu
Camilla Löwy's avatar
Camilla Löwy committed
214
 - Charles Huber
Camilla Berglund's avatar
Camilla Berglund committed
215
 - IntellectualKitty
216
 - Aaron Jacobs
217
 - Erik S. V. Jansson
Camilla Berglund's avatar
Camilla Berglund committed
218
 - Toni Jovanoski
219
 - Arseny Kapoulkine
220
 - Cem Karan
Camilla Berglund's avatar
Camilla Berglund committed
221
 - Osman Keskin
Camilla Löwy's avatar
Camilla Löwy committed
222
 - Josh Kilmer
223
 - Byunghoon Kim
Camilla Berglund's avatar
Camilla Berglund committed
224
225
 - Cameron King
 - Peter Knut
Camilla Berglund's avatar
Camilla Berglund committed
226
 - Christoph Kubisch
Camilla Löwy's avatar
Camilla Löwy committed
227
 - Yuri Kunde Schlesner
228
 - Rokas Kupstys
229
 - Konstantin Käfer
Camilla Berglund's avatar
Camilla Berglund committed
230
 - Eric Larson
Camilla Berglund's avatar
Camilla Berglund committed
231
232
233
 - Robin Leffmann
 - Glenn Lewis
 - Shane Liesegang
234
 - Anders Lindqvist
235
 - Leon Linhart
236
 - Eyal Lotem
Camilla Löwy's avatar
Camilla Löwy committed
237
 - Aaron Loucks
Camilla Löwy's avatar
Camilla Löwy committed
238
 - Luflosi
Camilla Berglund's avatar
Camilla Berglund committed
239
240
 - Tristam MacDonald
 - Hans Mackowiak
Camilla Löwy's avatar
Camilla Löwy committed
241
 - Дмитри Малышев
242
 - Zbigniew Mandziejewicz
243
 - Adam Marcus
Camilla Löwy's avatar
Camilla Löwy committed
244
 - Célestin Marot
245
 - Kyle McDonald
Camilla Berglund's avatar
Camilla Berglund committed
246
 - David Medlock
247
 - Bryce Mehring
Camilla Berglund's avatar
Camilla Berglund committed
248
249
 - Jonathan Mercier
 - Marcel Metz
Camilla Löwy's avatar
Cleanup    
Camilla Löwy committed
250
 - Liam Middlebrook
Camilla Löwy's avatar
Camilla Löwy committed
251
 - Ave Milia
252
 - Jonathan Miller
Camilla Berglund's avatar
Camilla Berglund committed
253
 - Kenneth Miller
Camilla Berglund's avatar
Camilla Berglund committed
254
 - Bruce Mitchener
Camilla Berglund's avatar
Camilla Berglund committed
255
 - Jack Moffitt
Camilla Berglund's avatar
Camilla Berglund committed
256
 - Jeff Molofee
Camilla Löwy's avatar
Camilla Löwy committed
257
 - Alexander Monakov
Camilla Löwy's avatar
Camilla Löwy committed
258
 - Pierre Morel
Camilla Berglund's avatar
Camilla Berglund committed
259
 - Jon Morton
260
 - Pierre Moulon
Camilla Löwy's avatar
Camilla Löwy committed
261
 - Martins Mozeiko
Camilla Berglund's avatar
Camilla Berglund committed
262
 - Julian Møller
Camilla Löwy's avatar
Camilla Löwy committed
263
 - ndogxj
Camilla Löwy's avatar
Cleanup    
Camilla Löwy committed
264
 - Kristian Nielsen
Camilla Berglund's avatar
Camilla Berglund committed
265
 - Kamil Nowakowski
Camilla Löwy's avatar
Camilla Löwy committed
266
 - Denis Ovod
Camilla Berglund's avatar
Camilla Berglund committed
267
 - Ozzy
268
 - Andri Pálsson
Camilla Berglund's avatar
Camilla Berglund committed
269
270
 - Peoro
 - Braden Pellett
271
 - Christopher Pelloux
Camilla Berglund's avatar
Camilla Berglund committed
272
 - Arturo J. Pérez
Camilla Löwy's avatar
Cleanup    
Camilla Löwy committed
273
 - Anthony Pesch
Camilla Berglund's avatar
Camilla Berglund committed
274
 - Orson Peters
Camilla Berglund's avatar
Camilla Berglund committed
275
 - Emmanuel Gil Peyrot
276
 - Cyril Pichard
Camilla Löwy's avatar
Camilla Löwy committed
277
278
 - Keith Pitt
 - Stanislav Podgorskiy
279
 - Konstantin Podsvirov
280
 - Nathan Poirier
Camilla Löwy's avatar
Camilla Löwy committed
281
 - Alexandre Pretyman
Camilla Löwy's avatar
Cleanup    
Camilla Löwy committed
282
 - Pablo Prietz
283
 - przemekmirek
284
 - pthom
Camilla Löwy's avatar
Camilla Löwy committed
285
 - Guillaume Racicot
Camilla Berglund's avatar
Cleanup    
Camilla Berglund committed
286
 - Philip Rideout
Camilla Löwy's avatar
Camilla Löwy committed
287
 - Eddie Ringle
Camilla Löwy's avatar
Cleanup    
Camilla Löwy committed
288
 - Max Risuhin
Camilla Berglund's avatar
Camilla Berglund committed
289
290
 - Jorge Rodriguez
 - Ed Ropple
291
 - Aleksey Rybalkin
Camilla Berglund's avatar
Camilla Berglund committed
292
 - Riku Salminen
293
 - Brandon Schaefer
Camilla Berglund's avatar
Camilla Berglund committed
294
 - Sebastian Schuberth
Camilla Löwy's avatar
Camilla Löwy committed
295
 - Christian Sdunek
Camilla Berglund's avatar
Camilla Berglund committed
296
297
 - Matt Sealey
 - Steve Sexton
Camilla Löwy's avatar
Camilla Löwy committed
298
 - Arkady Shapkin
299
 - Yoshiki Shibukawa
Camilla Berglund's avatar
Camilla Berglund committed
300
301
302
 - Dmitri Shuralyov
 - Daniel Skorupski
 - Bradley Smith
Camilla Löwy's avatar
Camilla Löwy committed
303
 - Cliff Smolinsky
Camilla Berglund's avatar
Cleanup    
Camilla Berglund committed
304
 - Patrick Snape
Camilla Löwy's avatar
Camilla Löwy committed
305
 - Erlend Sogge Heggen
Camilla Berglund's avatar
Camilla Berglund committed
306
307
 - Julian Squires
 - Johannes Stein
Camilla Löwy's avatar
Camilla Löwy committed
308
 - Pontus Stenetorp
Camilla Berglund's avatar
Cleanup    
Camilla Berglund committed
309
 - Michael Stocker
310
 - Justin Stoecker
Camilla Berglund's avatar
Camilla Berglund committed
311
 - Elviss Strazdins
Camilla Löwy's avatar
Camilla Löwy committed
312
 - Paul Sultana
Camilla Berglund's avatar
Camilla Berglund committed
313
314
315
 - Nathan Sweet
 - TTK-Bandit
 - Sergey Tikhomirov
A. Tombs's avatar
A. Tombs committed
316
 - Arthur Tombs
Camilla Berglund's avatar
Camilla Berglund committed
317
 - Ioannis Tsakpinis
Camilla Berglund's avatar
Camilla Berglund committed
318
 - Samuli Tuomola
319
 - Matthew Turner
320
 - urraka
Camilla Berglund's avatar
Camilla Berglund committed
321
 - Elias Vanderstuyft
Camilla Löwy's avatar
Camilla Löwy committed
322
 - Stef Velzel
Camilla Berglund's avatar
Camilla Berglund committed
323
 - Jari Vetoniemi
Camilla Berglund's avatar
Camilla Berglund committed
324
 - Ricardo Vieira
325
 - Nicholas Vitovitch
Camilla Berglund's avatar
Camilla Berglund committed
326
 - Simon Voordouw
327
 - Corentin Wallez
Camilla Berglund's avatar
Camilla Berglund committed
328
 - Torsten Walluhn
329
 - Patrick Walton
Xo Wang's avatar
Xo Wang committed
330
 - Xo Wang
Camilla Berglund's avatar
Camilla Berglund committed
331
332
 - Jay Weisskopf
 - Frank Wille
333
 - Ryogo Yoshimura
Camilla Löwy's avatar
Camilla Löwy committed
334
 - Lukas Zanner
Camilla Löwy's avatar
Cleanup    
Camilla Löwy committed
335
 - Andrey Zholos
Camilla Berglund's avatar
Camilla Berglund committed
336
 - Santi Zupancic
Camilla Berglund's avatar
Camilla Berglund committed
337
 - Jonas Ådahl
Camilla Berglund's avatar
Camilla Berglund committed
338
339
 - Lasse Öörni
 - All the unmentioned and anonymous contributors in the GLFW community, for bug
340
341
   reports, patches, feedback, testing and encouragement