glfw/README.md

361 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 is 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 generated 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
2016-09-25 12:08:33 +00:00
- [Nuklear](https://github.com/vurtun/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
- Added `GLFW_RESIZE_NWSE_CURSOR`, `GLFW_RESIZE_NESW_CURSOR`,
`GLFW_RESIZE_ALL_CURSOR` and `GLFW_NOT_ALLOWED_CURSOR` cursor shapes (#427)
- Added `GLFW_RESIZE_EW_CURSOR` alias for `GLFW_HRESIZE_CURSOR` (#427)
- Added `GLFW_RESIZE_NS_CURSOR` alias for `GLFW_VRESIZE_CURSOR` (#427)
- Added `GLFW_POINTING_HAND_CURSOR` alias for `GLFW_HAND_CURSOR` (#427)
- Disabled tests and examples by default when built as a CMake subdirectory
2019-05-02 19:32:14 +00:00
- Bugfix: The CMake config-file package used an absolute path and was not
relocatable (#1470)
- Bugfix: Video modes with a duplicate screen area were discarded (#1555,#1556)
2019-10-16 15:43:29 +00:00
- Bugfix: Compiling with -Wextra-semi caused warnings (#1440)
- [Win32] Added the `GLFW_WIN32_KEYBOARD_MENU` window hint for enabling access
to the window menu
- [Win32] Bugfix: `GLFW_INCLUDE_VULKAN` plus `VK_USE_PLATFORM_WIN32_KHR` caused
symbol redefinition (#1524)
2019-07-12 17:04:16 +00:00
- [Win32] Bugfix: The cursor position event was emitted before its cursor enter
event (#1490)
- [Win32] Bugfix: The window hint `GLFW_MAXIMIZED` did not move or resize the
window (#1499)
- [Cocoa] Bugfix: `glfwSetWindowSize` used a bottom-left anchor point (#1553)
- [Cocoa] Bugfix: Window remained on screen after destruction until event poll
(#1412)
- [Cocoa] Bugfix: Event processing before window creation would assert (#1543)
- [X11] Bugfix: The CMake files did not check for the XInput headers (#1480)
2019-07-11 18:21:04 +00:00
- [X11] Bugfix: Key names were not updated when the keyboard layout changed
(#1462,#1528)
- [X11] Bugfix: Decorations could not be enabled after window creation (#1566)
- [X11] Bugfix: Content scale fallback value could be inconsistent (#1578)
- [Wayland] Bugfix: The `GLFW_HAND_CURSOR` shape used the wrong image (#1432)
- [NSGL] Removed enforcement of forward-compatible flag for core contexts
- [NSGL] Bugfix: `GLFW_COCOA_RETINA_FRAMEBUFFER` had no effect on newer
macOS versions (#1442)
## 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
2019-10-13 14:42:54 +00:00
[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
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
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
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
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
2019-05-17 17:19:07 +00:00
- 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
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
2013-06-09 10:49:13 +00:00
- Robin Leffmann
- Glenn Lewis
- Shane Liesegang
- Anders Lindqvist
- Leon Linhart
- Eyal Lotem
2018-12-26 14:19:02 +00:00
- Aaron Loucks
2019-07-12 14:38:06 +00:00
- Luflosi
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
2019-07-16 12:35:35 +00:00
- 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
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
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
2019-05-02 19:32:14 +00:00
- Konstantin Podsvirov
- Nathan Poirier
2017-08-23 13:04:09 +00:00
- Alexandre Pretyman
2019-10-24 14:20:43 +00:00
- Pablo Prietz
2018-01-05 07:13:33 +00:00
- przemekmirek
2019-10-10 18:12:42 +00:00
- 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
- Ed Ropple
- Aleksey Rybalkin
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
- 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
2013-06-09 10:49:13 +00:00
- Jay Weisskopf
- Frank Wille
- Ryogo Yoshimura
2019-07-12 14:38:06 +00:00
- Lukas Zanner
2017-08-18 11:02:35 +00:00
- Andrey Zholos
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
- All the unmentioned and anonymous contributors in the GLFW community, for bug
reports, patches, feedback, testing and encouragement