glfw/README.md

337 lines
12 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.
2017-01-29 19:10:53 +00:00
GLFW natively supports Windows, macOS and Linux and other Unix-like systems.
Experimental implementations for the Wayland protocol and the Mir display server
are available but not yet officially supported.
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
2016-08-18 21:42:15 +00:00
The latest stable release is version 3.2.1.
2013-04-18 22:19:22 +00:00
2016-08-17 14:48:22 +00:00
See the [downloads](http://www.glfw.org/download.html) page for details and
files, or fetch the `latest` branch, which always points to the latest stable
release. Each release starting with 3.0 also has a corresponding [annotated
tag](https://github.com/glfw/glfw/releases) with source and binary archives.
2016-11-14 00:31:53 +00:00
The [version history](http://www.glfw.org/changelog.html) lists all user-visible
changes for every release.
2016-08-17 14:48:22 +00:00
2016-08-18 21:42:15 +00:00
This is a development branch for version 3.3, which is _not yet described_.
2017-01-29 19:10:53 +00:00
Pre-release documentation is available [here](http://www.glfw.org/docs/3.3/).
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
2016-02-27 20:58:09 +00:00
[tutorial](http://www.glfw.org/docs/latest/quick.html) for GLFW
2013-06-17 09:58:46 +00:00
3 useful. If you have used GLFW 2 in the past, there is a
2013-07-10 13:51:10 +00:00
[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
2016-08-08 23:34:56 +00:00
GLFW itself requires only the headers and libraries for your window system. It
2016-07-14 16:32:30 +00:00
does not need the headers for any context creation API (WGL, GLX, EGL, NSGL) or
rendering API (OpenGL, OpenGL ES, Vulkan) to enable support for them.
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.
2016-07-14 16:11:17 +00:00
There are also [pre-compiled Windows
2016-07-14 16:29:39 +00:00
binaries](http://www.glfw.org/download.html) available for all compilers
supported on that platform.
2017-01-29 19:10:53 +00:00
See the [compilation guide](http://www.glfw.org/docs/latest/compile.html) for
more information about how to compile GLFW.
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/.github/CONTRIBUTING.md) for
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
2017-01-29 19:10:53 +00:00
GLFW supports Windows XP and later and macOS 10.7 and later. Linux and other
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.
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
- An OpenGL 3.2 core loader generated by
[glad](https://github.com/Dav1dde/glad) for examples using modern OpenGL
- [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
- [Vulkan headers](https://www.khronos.org/registry/vulkan/) for Vulkan tests
2014-01-12 04:40:36 +00:00
The Vulkan example additionally requires the Vulkan SDK to be installed, or it
2017-01-29 19:10:53 +00:00
will not be included in the build. On macOS you need to set the path to the
MoltenVK SDK manually as it has no standard location.
2016-02-08 15:23:44 +00:00
The documentation is generated with [Doxygen](http://doxygen.org/). If CMake
2016-08-08 23:34:56 +00:00
does not find Doxygen, the documentation will not be generated when you build.
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/.github/CONTRIBUTING.md) for
information on what to include when reporting a bug.
2013-06-13 13:09:10 +00:00
## Changelog
2016-09-14 15:41:06 +00:00
- Added `glfwGetKeyScancode` function that allows retrieving platform dependent
scancodes for keys (#830)
- Added `glfwSetWindowMaximizeCallback` and `GLFWwindowmaximizefun` for
receiving window maximization events (#778)
- Added `glfwSetWindowAttrib` function for changing window attributes (#537)
- Added `glfwInitHint` function for setting library initialization hints
2017-02-07 05:39:09 +00:00
- Added headless [OSMesa](http://mesa3d.org/osmesa.html) backend (#850)
2016-11-08 11:39:18 +00:00
- Added definition of `GLAPIENTRY` to public header
2017-02-06 14:03:50 +00:00
- Added `GLFW_CENTER_CURSOR` window hint for controlling cursor centering
(#749,#842)
- Added macOS specific `GLFW_COCOA_RETINA_FRAMEBUFFER` window hint
- Added macOS specific `GLFW_COCOA_FRAME_AUTOSAVE` window hint (#195)
- Added macOS specific `GLFW_COCOA_GRAPHICS_SWITCHING` window hint (#377,#935)
- Added macOS specific `GLFW_COCOA_CHDIR_RESOURCES` init hint
- Added macOS specific `GLFW_COCOA_MENUBAR` init hint
2017-01-02 04:58:41 +00:00
- Added `GLFW_INCLUDE_ES32` for including the OpenGL ES 3.2 header
- Added `GLFW_OSMESA_CONTEXT_API` for creating OpenGL contexts with
[OSMesa](https://www.mesa3d.org/osmesa.html) (#281)
- Removed `GLFW_USE_RETINA` compile-time option
- Removed `GLFW_USE_CHDIR` compile-time option
- Removed `GLFW_USE_MENUBAR` compile-time option
- Bugfix: Calling `glfwMaximizeWindow` on a full screen window was not ignored
- Bugfix: `GLFW_INCLUDE_VULKAN` could not be combined with the corresponding
OpenGL and OpenGL ES header macros
- Bugfix: `glfwGetInstanceProcAddress` returned `NULL` for
`vkGetInstanceProcAddr` when `_GLFW_VULKAN_STATIC` was enabled
- Bugfix: Invalid library paths were used in test and example CMake files (#930)
- Bugfix: The scancode for synthetic key release events was always zero
- [Win32] Added system error strings to relevant GLFW error descriptions (#733)
- [Win32] Moved to `WM_INPUT` for disabled cursor mode motion input (#125)
- [Win32] Bugfix: Undecorated windows could not be iconified by the user (#861)
- [Win32] Bugfix: Deadzone logic could underflow with some controllers (#910)
2017-01-15 14:20:30 +00:00
- [Win32] Bugfix: Bitness test in `FindVulkan.cmake` was VS specific (#928)
- [Win32] Bugfix: `glfwVulkanSupported` emitted an error on systems with
a loader but no ICD (#916)
- [Win32] Bugfix: Non-iconified full sreeen windows did not prevent screen
blanking or password enabled screensavers (#851)
- [Win32] Bugfix: Mouse capture logic lost secondary release messages (#954)
- [Win32] Bugfix: The 32-bit Vulkan loader library static was not searched for
- [Win32] Bugfix: Vulkan libraries have a new path as of SDK 1.0.42.0 (#956)
2016-12-10 22:41:19 +00:00
- [X11] Replaced `_GLFW_HAS_XF86VM` compile-time option with dynamic loading
- [X11] Bugfix: `glfwGetVideoMode` would segfault on Cygwin/X
- [X11] Bugfix: Dynamic X11 library loading did not use full sonames (#941)
- [X11] Bugfix: Window creation on 64-bit would read past top of stack (#951)
- [Linux] Bugfix: Event processing did not detect joystick disconnection (#932)
2017-01-02 17:17:40 +00:00
- [Cocoa] Added support for Vulkan window surface creation via
[MoltenVK](https://moltengl.com/moltenvk/) (#870)
- [Cocoa] Added support for loading a `MainMenu.nib` when available
2016-10-10 16:09:05 +00:00
- [Cocoa] Bugfix: Disabling window aspect ratio would assert (#852)
2016-10-16 11:59:21 +00:00
- [Cocoa] Bugfix: Window creation failed to set first responder (#876,#883)
- [Cocoa] Bugfix: Removed use of deprecated `CGDisplayIOServicePort` function
(#165,#192,#508,#511)
- [Cocoa] Bugfix: Disabled use of deprecated `CGDisplayModeCopyPixelEncoding`
function on macOS 10.12+
2016-12-03 20:02:14 +00:00
- [Cocoa] Bugfix: Running in AppSandbox would emit warnings (#816,#882)
- [Cocoa] Bugfix: Windows created after the first were not cascaded (#195)
- [X11] Moved to XI2 `XI_RawMotion` for disable cursor mode motion input (#125)
2016-09-28 23:06:40 +00:00
- [EGL] Added support for `EGL_KHR_get_all_proc_addresses` (#871)
2017-01-02 15:01:20 +00:00
- [EGL] Bugfix: The test for `EGL_RGB_BUFFER` was invalid
## 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
2016-08-17 14:48:22 +00:00
[forum](http://discourse.glfw.org/), and the `#glfw` IRC channel on
[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
- artblanc
- arturo
2013-06-09 10:49:13 +00:00
- Matt Arsenault
- Keith Bauer
- John Bartholomew
2013-06-16 10:35:46 +00:00
- Niklas Behrens
2013-06-09 10:49:13 +00:00
- Niklas Bergström
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
- Martin Capitanio
2015-04-09 14:09:39 +00:00
- Chi-kwan Chan
2013-06-09 10:49:13 +00:00
- Lambert Clara
2013-10-06 09:37:16 +00:00
- Andrew Corrigan
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
2013-06-09 10:49:13 +00:00
- Jonathan Dummer
- Ralph Eastwood
- Siavash Eliasi
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
- Eloi Marín Gratacós
2013-06-09 10:49:13 +00:00
- Stefan Gustavson
- 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
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
2013-06-09 10:49:13 +00:00
- Osman Keskin
- Cameron King
- Peter Knut
- Christoph Kubisch
- 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
- Eyal Lotem
2013-06-09 10:49:13 +00:00
- Дмитри Малышев
- Martins Mozeiko
- Tristam MacDonald
- Hans Mackowiak
- Zbigniew Mandziejewicz
- 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
- 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
- Jon Morton
2013-09-13 12:41:13 +00:00
- Pierre Moulon
2013-06-09 10:49:13 +00:00
- Julian Møller
2013-11-13 11:59:49 +00:00
- Kamil Nowakowski
2013-06-17 09:58:46 +00:00
- Ozzy
- Andri Pálsson
2013-06-09 10:49:13 +00:00
- Peoro
- Braden Pellett
- Arturo J. Pérez
- Orson Peters
2015-04-19 11:27:27 +00:00
- Emmanuel Gil Peyrot
- Cyril Pichard
2013-10-09 21:58:43 +00:00
- Pieroman
- Philip Rideout
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
- Matt Sealey
- SephiRok
- Steve Sexton
- Systemcluster
- Yoshiki Shibukawa
2013-06-09 10:49:13 +00:00
- Dmitri Shuralyov
- Daniel Skorupski
- Bradley Smith
- Patrick Snape
2013-06-09 10:49:13 +00:00
- Julian Squires
- Johannes Stein
- Michael Stocker
- Justin Stoecker
2015-04-09 12:03:26 +00:00
- Elviss Strazdins
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
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
- Torsten Walluhn
- Patrick Walton
- Xo Wang
2013-06-09 10:49:13 +00:00
- Jay Weisskopf
- Frank Wille
- yuriks
- 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