README.md 8.99 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
 - [Cocoa] Added support for `VK_EXT_metal_surface` (#1619)
122
 - [X11] Bugfix: `glfwFocusWindow` could terminate on older WMs or without a WM
Camilla Löwy's avatar
Camilla Löwy committed
123
 - [X11] Bugfix: Creating an undecorated window could fail with BadMatch (#1620)
124

125
126
127

## Contact

Camilla Berglund's avatar
Camilla Berglund committed
128
129
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.
130
131

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

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

Finally, if you're interested in helping out with the development of GLFW or
Camilla Berglund's avatar
Camilla Berglund committed
140
porting it to your favorite platform, join us on the forum, GitHub or IRC.
141
142
143
144
145
146
147


## Acknowledgements

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

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