295 lines
11 KiB
Markdown
295 lines
11 KiB
Markdown
# GLFW
|
|
|
|
## Introduction
|
|
|
|
GLFW is a free, Open Source, multi-platform library for OpenGL and OpenGL ES
|
|
application development. It provides a simple, platform-independent API for
|
|
creating windows and contexts, reading input, handling events, etc.
|
|
|
|
Version 3.1 adds improved documentation, support for custom system cursors, file
|
|
drop events, main thread wake-up, window frame size retrieval, floating windows,
|
|
character input with modifier keys, single buffered windows, build improvements
|
|
and fixes for a large number of bugs.
|
|
|
|
If you are new to GLFW, you may find the
|
|
[introductory 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.
|
|
|
|
Note that a number of source files have been added or renamed in 3.1, which may
|
|
require you to update any custom build files you have.
|
|
|
|
|
|
## Compiling GLFW
|
|
|
|
See the [Compiling GLFW](http://www.glfw.org/docs/latest/compile.html) guide in
|
|
the GLFW documentation.
|
|
|
|
|
|
## Using GLFW
|
|
|
|
See the
|
|
[Building programs that use GLFW](http://www.glfw.org/docs/latest/build.html)
|
|
guide in the GLFW documentation.
|
|
|
|
|
|
## Reporting bugs
|
|
|
|
Bugs are reported to our [issue tracker](https://github.com/glfw/glfw/issues).
|
|
Please always include the name and version of the OS where the bug occurs and
|
|
the version of GLFW used. If you have cloned it, include the commit ID used.
|
|
|
|
If it's a build issue, please also include the build log and the name and
|
|
version of your development environment.
|
|
|
|
If it's a context creation issue, please also include the make and model of your
|
|
graphics card and the version of your driver.
|
|
|
|
This will help both us and other people experiencing the same bug.
|
|
|
|
|
|
## Dependencies
|
|
|
|
GLFW bundles a number of dependencies in the `deps/` directory.
|
|
|
|
- [Khronos extension headers](https://www.opengl.org/registry/) for API
|
|
extension symbols used by GLFW
|
|
- [getopt\_port](https://github.com/kimgr/getopt_port/) for examples
|
|
with command-line options
|
|
- [TinyCThread](https://github.com/tinycthread/tinycthread) for threaded
|
|
examples
|
|
- An OpenGL 3.2 core loader generated by
|
|
[glad](https://github.com/Dav1dde/glad) for examples using modern OpenGL
|
|
|
|
|
|
## Changelog
|
|
|
|
- Added `GLFWcursor` custom system cursor handle
|
|
- Added `glfwCreateCursor`, `glfwCreateStandardCursor`, `glfwDestroyCursor` and
|
|
`glfwSetCursor` for managing system cursor images
|
|
- Added `GLFWimage` struct for passing 32-bit RGBA images
|
|
- Added monitor and adapter identifier access to native API
|
|
- Added `glfwSetDropCallback` and `GLFWdropfun` for receiving dropped files
|
|
- Added `glfwPostEmptyEvent` for allowing secondary threads to cause
|
|
`glfwWaitEvents` to return
|
|
- Added `empty` test program for verifying posting of empty events
|
|
- Added `glfwSetCharModsCallback` for receiving character events with modifiers
|
|
- Added `glfwGetWindowFrameSize` for retrieving the size of the frame around
|
|
the client area of a window
|
|
- Added `GLFW_AUTO_ICONIFY` for controlling whether full screen windows
|
|
automatically iconify (and restore the previous video mode) on focus loss
|
|
- Added `GLFW_DONT_CARE` for indicating that any value is acceptable
|
|
- Added `GLFW_DOUBLEBUFFER` for controlling whether to use double buffering
|
|
- Added `GLFW_CONTEXT_RELEASE_BEHAVIOR` and values
|
|
`GLFW_ANY_RELEASE_BEHAVIOR`, `GLFW_RELEASE_BEHAVIOR_FLUSH` and
|
|
`GLFW_RELEASE_BEHAVIOR_NONE` for `GL_KHR_context_flush_control` support
|
|
- Added `GLFW_INCLUDE_ES31` for including the OpenGL ES 3.1 header
|
|
- Added `GLFW_FLOATING` for creating always-on-top windowed mode windows
|
|
- Added `GLFW_FOCUSED` window hint for controlling initial input focus
|
|
- Added *partial and experimental* support for Wayland
|
|
- Added *partial and experimental* support for Mir
|
|
- Changed the window state attributes (focused, iconified and visible) to query
|
|
the system directly
|
|
- Changed the default of `GLFW_REFRESH_RATE` to `GLFW_DONT_CARE` to maintain
|
|
the default behavior
|
|
- Changed static library to build as position independent code for easier use
|
|
from the Rust language
|
|
- Changed `glfwGetCursorPos` to query the system directly for all cursor modes
|
|
except captured mode
|
|
- Bugfix: The debug context attribute was set from `GL_ARB_debug_output` even
|
|
when a debug context had not been requested
|
|
- Bugfix: The particles example was not linked against the threading library
|
|
- Bugfix: The cursor was not positioned over newly created full screen windows
|
|
- Bugfix: The queried cursor position was not always up-to-date
|
|
- Bugfix: `glfwExtensionSupported` always failed for OpenGL ES 3.0 and later if
|
|
the library was compiled for OpenGL ES
|
|
- [Cocoa] Added `_GLFW_USE_RETINA` to control whether windows will use the full
|
|
resolution on Retina displays
|
|
- [Cocoa] Made content view subclass of `NSOpenGLView`
|
|
- [Cocoa] Bugfix: Using a 1x1 cursor for hidden mode caused some screen
|
|
recorders to fail
|
|
- [Cocoa] Bugfix: Some Core Foundation objects were leaked during joystick
|
|
enumeration and termination
|
|
- [Cocoa] Bugfix: One copy of each display name string was leaked
|
|
- [Cocoa] Bugfix: Monitor enumeration caused a segfault if no `NSScreen` was
|
|
found for a given `CGDisplay`
|
|
- [Cocoa] Bugfix: Modifier key events were lost if the corresponding modifier
|
|
bit field was unchanged
|
|
- [Cocoa] Bugfix: Joystick enumeration took hundreds of ms on some systems
|
|
- [Cocoa] Bugfix: The cursor was hidden when the user resized a GLFW window
|
|
- [Cocoa] Bugfix: The 10.10 Yosemite OpenGL 4.1 profile token was not used
|
|
- [Cocoa] Bugfix: The generic software OpenGL renderer could be selected under
|
|
certain conditions
|
|
- [Cocoa] Bugfix: The virtual cursor jumped unpredictably when entering
|
|
disabled cursor mode
|
|
- [Win32] Enabled generation of pkg-config file for MinGW
|
|
- [Win32] Removed option to require explicitly linking against `winmm.dll`
|
|
- [Win32] Bugfix: Failure to load winmm or its functions was not reported to
|
|
the error callback
|
|
- [Win32] Bugfix: Some keys were reported based on the current layout instead
|
|
of their physical location
|
|
- [Win32] Bugfix: Maximized hidden windows were restored by `glfwShowWindow`
|
|
- [Win32] Bugfix: Context re-creation was not triggered by sRGB hint
|
|
- [Win32] Bugfix: Full screen windows were incorrectly sized and placed on some
|
|
systems
|
|
- [Win32] Bugfix: Gamma ramp functions acted on entire desktop instead of the
|
|
specified monitor
|
|
- [Win32] Bugfix: The wrong incorrect physical size was returned for
|
|
non-primary monitors
|
|
- [Win32] Bugfix: X-axis scroll offsets were inverted
|
|
- [Win32] Bugfix: The Optimus HPG forcing variable was not correctly exported
|
|
- [Win32] Bugfix: The iconified window state attribute was not always updated
|
|
- [Win32] Bugfix: Previously focused windows with disabled cursor mode and that
|
|
had been iconified by Win+D were not visible when restored
|
|
- [Win32] Bugfix: The virtual cursor jumped unpredictably when entering
|
|
disabled cursor mode
|
|
- [X11] Added run-time support for systems lacking the XKB extension
|
|
- [X11] Made GLX 1.3 the minimum supported version
|
|
- [X11] Replaced `XRRGetScreenResources` with `XRRGetScreenResourcesCurrent`
|
|
for monitor property retrieval
|
|
- [X11] Bugfix: The case of finding no usable CRTCs was not detected
|
|
- [X11] Bugfix: Detection of broken Nvidia RandR gamma support did not verify
|
|
that at least one CRTC was present
|
|
- [X11] Bugfix: A stale `_NET_SUPPORTING_WM_CHECK` root window property would
|
|
cause an uncaught `BadWindow` error
|
|
- [X11] Bugfix: No check was made for the presence of GLX 1.3 when
|
|
`GLX_SGIX_fbconfig` was unavailable
|
|
- [X11] Bugfix: The message type of ICCCM protocol events was not checked
|
|
- [X11] Bugfix: `glfwDestroyWindow` did not flush the output buffer
|
|
- [X11] Bugfix: Window frame interactions were reported as focus events
|
|
- [X11] Bugfix: Workaround for legacy Compiz caused flickering during resize
|
|
- [X11] Bugfix: The name pointer of joysticks were not cleared on disconnection
|
|
- [X11] Bugfix: Video mode resolutions and monitor physical sizes were not
|
|
corrected for rotated CRTCs
|
|
- [X11] Bugfix: Unicode character input ignored dead keys
|
|
- [X11] Bugfix: X-axis scroll offsets were inverted
|
|
- [X11] Bugfix: Full screen override redirect windows were not always
|
|
positioned over the specified monitor
|
|
- [X11] Bugfix: Character input did not work for the default `"C"` locale
|
|
- [X11] Bugfix: Joysticks connected after `glfwInit` were not detected
|
|
(temporary inotify solution until proper libudev solution)
|
|
|
|
|
|
## Contact
|
|
|
|
The official website for GLFW is [glfw.org](http://www.glfw.org/). There 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
|
|
[support forum](https://sourceforge.net/p/glfw/discussion/247562/), and the IRC
|
|
channel `#glfw` on [Freenode](http://freenode.net/).
|
|
|
|
If you have a bug to report, a patch to submit or a feature you'd like to
|
|
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
|
|
porting it to your favorite platform, we have an occasionally active
|
|
[developer's mailing list](https://lists.stacken.kth.se/mailman/listinfo/glfw-dev),
|
|
or you could join us on `#glfw`.
|
|
|
|
|
|
## Acknowledgements
|
|
|
|
GLFW exists because people around the world donated their time and lent their
|
|
skills.
|
|
|
|
- Bobyshev Alexander
|
|
- artblanc
|
|
- arturo
|
|
- Matt Arsenault
|
|
- Keith Bauer
|
|
- John Bartholomew
|
|
- Niklas Behrens
|
|
- Niklas Bergström
|
|
- Doug Binks
|
|
- blanco
|
|
- Martin Capitanio
|
|
- Lambert Clara
|
|
- Andrew Corrigan
|
|
- Noel Cower
|
|
- Jarrod Davis
|
|
- Olivier Delannoy
|
|
- Paul R. Deppe
|
|
- Michael Dickens
|
|
- Jonathan Dummer
|
|
- Ralph Eastwood
|
|
- Michael Fogleman
|
|
- Gerald Franz
|
|
- GeO4d
|
|
- Marcus Geelnard
|
|
- Eloi Marín Gratacós
|
|
- Stefan Gustavson
|
|
- Sylvain Hellegouarch
|
|
- Matthew Henry
|
|
- heromyth
|
|
- Lucas Hinderberger
|
|
- Paul Holden
|
|
- Toni Jovanoski
|
|
- Arseny Kapoulkine
|
|
- Osman Keskin
|
|
- Cameron King
|
|
- Peter Knut
|
|
- Robin Leffmann
|
|
- Glenn Lewis
|
|
- Shane Liesegang
|
|
- Дмитри Малышев
|
|
- Martins Mozeiko
|
|
- Tristam MacDonald
|
|
- Hans Mackowiak
|
|
- Kyle McDonald
|
|
- David Medlock
|
|
- Jonathan Mercier
|
|
- Marcel Metz
|
|
- Kenneth Miller
|
|
- Bruce Mitchener
|
|
- Jack Moffitt
|
|
- Jeff Molofee
|
|
- Jon Morton
|
|
- Pierre Moulon
|
|
- Julian Møller
|
|
- Kamil Nowakowski
|
|
- Ozzy
|
|
- Andri Pálsson
|
|
- Peoro
|
|
- Braden Pellett
|
|
- Arturo J. Pérez
|
|
- Cyril Pichard
|
|
- Pieroman
|
|
- Jorge Rodriguez
|
|
- Ed Ropple
|
|
- Riku Salminen
|
|
- Brandon Schaefer
|
|
- Sebastian Schuberth
|
|
- Matt Sealey
|
|
- SephiRok
|
|
- Steve Sexton
|
|
- Systemcluster
|
|
- Dmitri Shuralyov
|
|
- Daniel Skorupski
|
|
- Bradley Smith
|
|
- Julian Squires
|
|
- Johannes Stein
|
|
- Justin Stoecker
|
|
- Nathan Sweet
|
|
- TTK-Bandit
|
|
- Sergey Tikhomirov
|
|
- Samuli Tuomola
|
|
- urraka
|
|
- Jari Vetoniemi
|
|
- Ricardo Vieira
|
|
- Simon Voordouw
|
|
- Torsten Walluhn
|
|
- Patrick Walton
|
|
- Jay Weisskopf
|
|
- Frank Wille
|
|
- yuriks
|
|
- Santi Zupancic
|
|
- Jonas Ådahl
|
|
- Lasse Öörni
|
|
- All the unmentioned and anonymous contributors in the GLFW community, for bug
|
|
reports, patches, feedback, testing and encouragement
|
|
|