glfw/README.md

380 lines
11 KiB
Markdown
Raw Normal View History

2013-06-13 13:07:28 +00:00
# GLFW
2016-02-04 13:58:44 +00:00
[![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)
2016-06-23 14:09:55 +00:00
[![Coverity Scan](https://scan.coverity.com/projects/4884/badge.svg)](https://scan.coverity.com/projects/glfw-glfw)
2015-04-14 21:47:17 +00:00
## Introduction
2016-08-08 23:34:56 +00:00
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.
2019-04-15 23:36:49 +00:00
GLFW natively supports Windows, macOS and Linux and other Unix-like systems. On
Linux both X11 and Wayland are supported.
2017-01-29 19:10:53 +00:00
2016-08-17 14:48:22 +00:00
GLFW is licensed under the [zlib/libpng
2016-11-14 00:31:53 +00:00
license](http://www.glfw.org/license.html).
2016-06-05 17:35:39 +00:00
2019-04-15 23:36:49 +00:00
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
2016-08-17 14:48:22 +00:00
tag](https://github.com/glfw/glfw/releases) with source and binary archives.
2019-04-15 23:36:49 +00:00
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).
2017-01-29 19:10:53 +00:00
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.
2016-08-18 21:42:15 +00:00
2013-04-07 11:26:06 +00:00
If you are new to GLFW, you may find the
2017-07-11 22:21:17 +00:00
[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.
2013-10-27 11:50:33 +00:00
## Compiling GLFW
2013-10-21 20:23:15 +00:00
2019-04-15 23:36:49 +00:00
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.
2016-07-14 16:32:30 +00:00
2016-07-14 16:29:39 +00:00
GLFW supports compilation on Windows with Visual C++ 2010 and later, MinGW and
MinGW-w64, on macOS with Clang and on Linux and other Unix-like systems with GCC
2016-07-14 16:29:39 +00:00
and Clang. It will likely compile in other environments as well, but this is
not regularly tested.
2017-07-11 22:21:17 +00:00
There are [pre-compiled Windows binaries](http://www.glfw.org/download.html)
available for all supported compilers.
2017-01-29 19:10:53 +00:00
See the [compilation guide](http://www.glfw.org/docs/latest/compile.html) for
2017-07-11 22:21:17 +00:00
more information about how to compile GLFW yourself.
2016-07-14 16:02:44 +00:00
2016-07-14 16:11:17 +00:00
## Using GLFW
2016-07-14 16:02:44 +00:00
2017-01-29 19:10:53 +00:00
See the [documentation](http://www.glfw.org/docs/latest/) for tutorials, guides
and the API reference.
## Contributing to GLFW
See the [contribution
guide](https://github.com/glfw/glfw/blob/master/docs/CONTRIBUTING.md) for
2017-01-29 19:10:53 +00:00
more information.
2016-07-14 16:02:44 +00:00
2016-07-14 16:11:17 +00:00
## System requirements
2016-07-14 16:02:44 +00:00
GLFW supports Windows XP and later and macOS 10.8 and later. Linux and other
2017-01-29 19:10:53 +00:00
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.
2016-07-14 16:02:44 +00:00
See the [compatibility guide](http://www.glfw.org/docs/latest/compat.html)
2016-07-14 16:19:46 +00:00
in the documentation for more information.
2016-07-14 16:02:44 +00:00
2014-01-12 04:40:36 +00:00
## Dependencies
2016-08-08 23:34:56 +00:00
GLFW itself depends only on the headers and libraries for your window system.
The (experimental) Wayland backend also depends on the `extra-cmake-modules`
package, which is used to generate Wayland protocol headers.
2016-02-08 15:23:44 +00:00
The examples and test programs depend on a number of tiny libraries. These are
located in the `deps/` directory.
2014-01-12 04:40:36 +00:00
2014-06-18 14:13:49 +00:00
- [getopt\_port](https://github.com/kimgr/getopt_port/) for examples
with command-line options
2014-10-15 01:55:25 +00:00
- [TinyCThread](https://github.com/tinycthread/tinycthread) for threaded
2014-06-18 14:13:49 +00:00
examples
- [glad2](https://github.com/Dav1dde/glad) for loading OpenGL and Vulkan
functions
- [linmath.h](https://github.com/datenwolf/linmath.h) for linear algebra in
examples
- [Nuklear](https://github.com/Immediate-Mode-UI/Nuklear) for test and example UI
2016-10-13 15:42:44 +00:00
- [stb\_image\_write](https://github.com/nothings/stb) for writing images to disk
2017-07-11 22:21:17 +00:00
The documentation is generated with [Doxygen](http://doxygen.org/) if CMake can
find that tool.
2016-02-08 15:23:44 +00:00
2014-01-12 04:40:36 +00:00
2016-07-14 16:32:30 +00:00
## Reporting bugs
Bugs are reported to our [issue tracker](https://github.com/glfw/glfw/issues).
Please check the [contribution
guide](https://github.com/glfw/glfw/blob/master/docs/CONTRIBUTING.md) for
2016-07-14 16:32:30 +00:00
information on what to include when reporting a bug.
2013-06-13 13:09:10 +00:00
## Changelog
- Bugfix: Some extension loader headers did not prevent default OpenGL header
inclusion (#1695)
- [Win32] Disabled framebuffer transparency on Windows 7 when DWM windows are
opaque (#1512)
- [Win32] Bugfix: Non-BMP Unicode codepoint input was reported as UTF-16
- [Win32] Bugfix: Monitor functions could return invalid values after
configuration change (#1761)
- [Win32] Bugfix: Initialization would segfault on Windows 8 (not 8.1) (#1775)
- [Win32] Bugfix: Duplicate size events were not filtered (#1610)
- [Cocoa] Changed `EGLNativeWindowType` from `NSView` to `CALayer` (#1169)
- [Cocoa] Bugfix: Non-BMP Unicode codepoint input was reported as UTF-16
(#1635)
- [Cocoa] Bugfix: Failing to retrieve the refresh rate of built-in displays
could leak memory
- [Cocoa] Bugfix: Objective-C files were compiled as C with CMake 3.19 (#1787)
- [X11] Bugfix: IME input of CJK was broken for "C" locale (#1587,#1636)
- [X11] Bugfix: Xlib errors caused by other parts of the application could be
reported as GLFW errors
- [X11] Bugfix: A handle race condition could cause a `BadWindow` error (#1633)
- [X11] Bugfix: XKB path used keysyms instead of physical locations for
non-printable keys (#1598)
- [X11] Bugfix: Function keys were mapped to `GLFW_KEY_UNKNOWN` for some layout
combinaitons (#1598)
- [X11] Bugfix: Keys pressed simultaneously with others were not always
reported (#1112,#1415,#1472,#1616)
- [Wayland] Bugfix: Repeated keys could be reported with `NULL` window (#1704)
- [Wayland] Bugfix: Retrieving partial framebuffer size would segfault
- [Wayland] Bugfix: Scrolling offsets were inverted compared to other platforms
(#1463)
- [Wayland] Bugfix: Client-Side Decorations were destroyed in the wrong worder
(#1798)
## Contact
2016-08-02 13:58:58 +00:00
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.
If you have questions related to the use of GLFW, we have a
[forum](https://discourse.glfw.org/), and the `#glfw` IRC channel on
2016-08-17 14:48:22 +00:00
[Freenode](http://freenode.net/).
If you have a bug to report, a patch to submit or a feature you'd like to
2013-06-24 12:28:42 +00:00
request, please file it in the
[issue tracker](https://github.com/glfw/glfw/issues) on GitHub.
Finally, if you're interested in helping out with the development of GLFW or
2016-08-17 14:48:22 +00:00
porting it to your favorite platform, join us on the forum, GitHub or IRC.
## Acknowledgements
GLFW exists because people around the world donated their time and lent their
skills.
2013-06-09 10:49:13 +00:00
- Bobyshev Alexander
- Matt Arsenault
- ashishgamedev
2017-08-23 13:04:09 +00:00
- David Avedissian
2013-06-09 10:49:13 +00:00
- Keith Bauer
- John Bartholomew
2018-08-09 16:17:40 +00:00
- Coşku Baş
2013-06-16 10:35:46 +00:00
- Niklas Behrens
2018-12-25 19:52:58 +00:00
- Andrew Belt
2013-06-09 10:49:13 +00:00
- Niklas Bergström
2017-05-17 20:12:47 +00:00
- Denis Bernard
2013-08-16 15:48:11 +00:00
- Doug Binks
2013-06-09 10:49:13 +00:00
- blanco
2016-09-28 21:47:22 +00:00
- Kyle Brenneman
2017-08-23 13:04:09 +00:00
- Rok Breulj
- Kai Burjack
- Martin Capitanio
- Nicolas Caramelli
2017-07-03 12:25:47 +00:00
- David Carlier
2017-08-23 13:04:09 +00:00
- Arturo Castro
2015-04-09 14:09:39 +00:00
- Chi-kwan Chan
2017-08-23 13:04:09 +00:00
- Ian Clarkson
- Michał Cichoń
2013-06-09 10:49:13 +00:00
- Lambert Clara
2019-04-15 23:05:57 +00:00
- Anna Clarke
2017-08-23 13:04:09 +00:00
- Yaron Cohen-Tal
- Omar Cornut
2013-10-06 09:37:16 +00:00
- Andrew Corrigan
- Bailey Cosier
2013-06-09 10:49:13 +00:00
- Noel Cower
- Jason Daly
2013-06-09 10:49:13 +00:00
- Jarrod Davis
- Olivier Delannoy
- Paul R. Deppe
2014-02-13 23:45:27 +00:00
- Michael Dickens
2015-10-28 21:57:57 +00:00
- Роман Донченко
- Mario Dorn
- Wolfgang Draxinger
2013-06-09 10:49:13 +00:00
- Jonathan Dummer
- Ralph Eastwood
2017-08-23 13:04:09 +00:00
- Fredrik Ehnbom
- Robin Eklind
- Siavash Eliasi
2017-05-11 12:36:56 +00:00
- Felipe Ferreira
2013-12-10 12:45:21 +00:00
- Michael Fogleman
2013-12-11 13:41:51 +00:00
- Gerald Franz
2016-10-10 16:09:05 +00:00
- Mário Freitas
2013-06-09 10:49:13 +00:00
- GeO4d
- Marcus Geelnard
- Charles Giessen
- Ryan C. Gordon
2017-12-18 14:47:34 +00:00
- Stephen Gowen
- Kovid Goyal
- Eloi Marín Gratacós
2013-06-09 10:49:13 +00:00
- Stefan Gustavson
2017-08-23 13:04:09 +00:00
- Jonathan Hale
- hdf89shfdfs
2013-06-09 10:49:13 +00:00
- Sylvain Hellegouarch
- Matthew Henry
2013-06-09 10:49:13 +00:00
- heromyth
- Lucas Hinderberger
2013-06-16 16:32:16 +00:00
- Paul Holden
- Warren Hu
- Charles Huber
2016-03-29 12:00:44 +00:00
- IntellectualKitty
- Aaron Jacobs
- Erik S. V. Jansson
2013-06-09 10:49:13 +00:00
- Toni Jovanoski
- Arseny Kapoulkine
- Cem Karan
2013-06-09 10:49:13 +00:00
- Osman Keskin
2017-08-23 13:04:09 +00:00
- Josh Kilmer
- Byunghoon Kim
2013-06-09 10:49:13 +00:00
- Cameron King
- Peter Knut
- Christoph Kubisch
2017-08-23 13:04:09 +00:00
- Yuri Kunde Schlesner
- Rokas Kupstys
- Konstantin Käfer
2015-04-14 19:15:50 +00:00
- Eric Larson
- Francis Lecavalier
- Jong Won Lee
2013-06-09 10:49:13 +00:00
- Robin Leffmann
- Glenn Lewis
- Shane Liesegang
- Anders Lindqvist
- Leon Linhart
- Marco Lizza
- Eyal Lotem
2018-12-26 14:19:02 +00:00
- Aaron Loucks
- Luflosi
- lukect
2013-06-09 10:49:13 +00:00
- Tristam MacDonald
- Hans Mackowiak
2017-08-23 13:04:09 +00:00
- Дмитри Малышев
- Zbigniew Mandziejewicz
2019-02-27 18:50:43 +00:00
- Adam Marcus
2017-08-23 13:04:09 +00:00
- Célestin Marot
- Kyle McDonald
2013-06-09 10:49:13 +00:00
- David Medlock
- Bryce Mehring
2013-06-09 10:49:13 +00:00
- Jonathan Mercier
- Marcel Metz
2017-02-06 14:03:50 +00:00
- Liam Middlebrook
- Ave Milia
- Jonathan Miller
2013-06-09 10:49:13 +00:00
- Kenneth Miller
2013-07-01 11:18:05 +00:00
- Bruce Mitchener
2013-10-28 12:22:34 +00:00
- Jack Moffitt
2013-06-09 10:49:13 +00:00
- Jeff Molofee
2018-12-26 13:59:31 +00:00
- Alexander Monakov
2017-08-23 13:04:09 +00:00
- Pierre Morel
2013-06-09 10:49:13 +00:00
- Jon Morton
2013-09-13 12:41:13 +00:00
- Pierre Moulon
2017-08-23 13:04:09 +00:00
- Martins Mozeiko
2013-06-09 10:49:13 +00:00
- Julian Møller
2017-08-23 13:04:09 +00:00
- ndogxj
- Kristian Nielsen
2013-11-13 11:59:49 +00:00
- Kamil Nowakowski
- onox
2017-08-23 13:04:09 +00:00
- Denis Ovod
2013-06-17 09:58:46 +00:00
- Ozzy
- Andri Pálsson
2013-06-09 10:49:13 +00:00
- Peoro
- Braden Pellett
- Christopher Pelloux
2013-06-09 10:49:13 +00:00
- Arturo J. Pérez
- Vladimir Perminov
2017-06-15 15:13:23 +00:00
- Anthony Pesch
- Orson Peters
2015-04-19 11:27:27 +00:00
- Emmanuel Gil Peyrot
- Cyril Pichard
2017-08-23 13:04:09 +00:00
- Keith Pitt
- Stanislav Podgorskiy
- Konstantin Podsvirov
- Nathan Poirier
2017-08-23 13:04:09 +00:00
- Alexandre Pretyman
- Pablo Prietz
2018-01-05 07:13:33 +00:00
- przemekmirek
- pthom
- Guillaume Racicot
- Philip Rideout
2017-08-23 13:04:09 +00:00
- Eddie Ringle
2019-02-13 22:21:05 +00:00
- Max Risuhin
2013-06-09 10:49:13 +00:00
- Jorge Rodriguez
- Luca Rood
2013-06-09 10:49:13 +00:00
- Ed Ropple
- Aleksey Rybalkin
- Mikko Rytkönen
2013-06-09 10:49:13 +00:00
- Riku Salminen
- Brandon Schaefer
2013-06-09 10:49:13 +00:00
- Sebastian Schuberth
2017-08-23 13:04:09 +00:00
- Christian Sdunek
2013-06-09 10:49:13 +00:00
- Matt Sealey
- Steve Sexton
2017-08-23 13:04:09 +00:00
- Arkady Shapkin
- Ali Sherief
- Yoshiki Shibukawa
2013-06-09 10:49:13 +00:00
- Dmitri Shuralyov
- Daniel Skorupski
- Bradley Smith
2019-04-01 16:23:21 +00:00
- Cliff Smolinsky
- Patrick Snape
2017-08-23 13:04:09 +00:00
- Erlend Sogge Heggen
2013-06-09 10:49:13 +00:00
- Julian Squires
- Johannes Stein
2017-08-23 13:04:09 +00:00
- Pontus Stenetorp
- Michael Stocker
- Justin Stoecker
2015-04-09 12:03:26 +00:00
- Elviss Strazdins
2017-08-23 13:04:09 +00:00
- Paul Sultana
2013-06-09 10:49:13 +00:00
- Nathan Sweet
- TTK-Bandit
- Sergey Tikhomirov
2016-07-14 10:49:46 +00:00
- Arthur Tombs
- Ioannis Tsakpinis
2013-06-09 10:49:13 +00:00
- Samuli Tuomola
- Matthew Turner
- urraka
- Elias Vanderstuyft
2017-08-23 13:04:09 +00:00
- Stef Velzel
2013-06-09 10:49:13 +00:00
- Jari Vetoniemi
2014-07-01 08:49:50 +00:00
- Ricardo Vieira
- Nicholas Vitovitch
2013-06-09 10:49:13 +00:00
- Simon Voordouw
- Corentin Wallez
2013-06-09 10:49:13 +00:00
- Torsten Walluhn
- Patrick Walton
- Xo Wang
- Waris
2013-06-09 10:49:13 +00:00
- Jay Weisskopf
- Frank Wille
- Tatsuya Yatagawa
- Ryogo Yoshimura
- Lukas Zanner
2017-08-18 11:02:35 +00:00
- Andrey Zholos
- Aihui Zhu
2013-06-09 10:49:13 +00:00
- Santi Zupancic
2014-03-18 20:43:24 +00:00
- Jonas Ådahl
2013-06-09 10:49:13 +00:00
- Lasse Öörni
- Leonard König
2013-06-09 10:49:13 +00:00
- All the unmentioned and anonymous contributors in the GLFW community, for bug
reports, patches, feedback, testing and encouragement