2013-06-13 13:07:28 +00:00
|
|
|
# GLFW
|
2013-02-04 09:46:02 +00:00
|
|
|
|
2021-06-07 20:21:23 +00:00
|
|
|
[](https://github.com/glfw/glfw/actions)
|
2016-02-04 13:58:44 +00:00
|
|
|
[](https://ci.appveyor.com/project/elmindreda/glfw)
|
2015-04-14 21:47:17 +00:00
|
|
|
|
2013-02-04 09:46:02 +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.
|
2013-02-04 09:46:02 +00:00
|
|
|
|
2019-04-15 23:36:49 +00:00
|
|
|
GLFW natively supports Windows, macOS and Linux and other Unix-like systems. On
|
2024-02-19 14:06:59 +00:00
|
|
|
Linux both Wayland and X11 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
|
2021-06-09 20:43:27 +00:00
|
|
|
license](https://www.glfw.org/license.html).
|
2016-06-05 17:35:39 +00:00
|
|
|
|
2021-06-09 20:43:27 +00:00
|
|
|
You can [download](https://www.glfw.org/download.html) the latest stable release
|
2024-02-22 21:22:47 +00:00
|
|
|
as source or Windows binaries. Each release starting with 3.0 also has
|
|
|
|
|
a corresponding [annotated tag](https://github.com/glfw/glfw/releases) with
|
|
|
|
|
source and binary archives.
|
2016-08-17 14:48:22 +00:00
|
|
|
|
2021-06-09 20:43:27 +00:00
|
|
|
The [documentation](https://www.glfw.org/docs/latest/) is available online and is
|
2019-04-15 23:36:49 +00:00
|
|
|
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
|
2021-06-09 20:43:27 +00:00
|
|
|
history](https://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
|
2021-06-09 20:43:27 +00:00
|
|
|
[tutorial](https://www.glfw.org/docs/latest/quick.html) for GLFW 3 useful. If
|
2017-07-11 22:21:17 +00:00
|
|
|
you have used GLFW 2 in the past, there is a [transition
|
2021-06-09 20:43:27 +00:00
|
|
|
guide](https://www.glfw.org/docs/latest/moving.html) for moving to the GLFW
|
2017-07-11 22:21:17 +00:00
|
|
|
3 API.
|
2013-02-04 09:46:02 +00:00
|
|
|
|
2021-07-19 16:25:50 +00:00
|
|
|
GLFW exists because of the contributions of [many people](CONTRIBUTORS.md)
|
|
|
|
|
around the world, whether by reporting bugs, providing community support, adding
|
|
|
|
|
features, reviewing or testing code, debugging, proofreading docs, suggesting
|
|
|
|
|
features or fixing bugs.
|
|
|
|
|
|
2013-02-04 09:46:02 +00:00
|
|
|
|
2013-10-27 11:50:33 +00:00
|
|
|
## Compiling GLFW
|
2013-10-21 20:23:15 +00:00
|
|
|
|
2024-01-29 21:47:04 +00:00
|
|
|
GLFW is written primarily in C99, with parts of macOS support being written in
|
|
|
|
|
Objective-C. GLFW itself requires only the headers and libraries for your OS
|
|
|
|
|
and window system. It does not need any additional headers for context creation
|
|
|
|
|
APIs (WGL, GLX, EGL, NSGL, OSMesa) or rendering APIs (OpenGL, OpenGL ES, Vulkan)
|
|
|
|
|
to enable support for them.
|
2016-07-14 16:32:30 +00:00
|
|
|
|
2024-01-29 21:47:04 +00:00
|
|
|
GLFW supports compilation on Windows with Visual C++ 2013 and later, MinGW and
|
2016-10-19 22:50:54 +00:00
|
|
|
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.
|
2013-02-04 09:46:02 +00:00
|
|
|
|
2024-01-29 21:47:04 +00:00
|
|
|
There are [pre-compiled binaries](https://www.glfw.org/download.html) available
|
|
|
|
|
for all supported compilers on Windows and macOS.
|
2013-02-04 09:46:02 +00:00
|
|
|
|
2021-06-09 20:43:27 +00:00
|
|
|
See the [compilation guide](https://www.glfw.org/docs/latest/compile.html) for
|
2017-07-11 22:21:17 +00:00
|
|
|
more information about how to compile GLFW yourself.
|
2013-02-04 09:46:02 +00:00
|
|
|
|
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
|
|
|
|
2021-06-09 20:43:27 +00:00
|
|
|
See the [documentation](https://www.glfw.org/docs/latest/) for tutorials, guides
|
2017-01-29 19:10:53 +00:00
|
|
|
and the API reference.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Contributing to GLFW
|
|
|
|
|
|
|
|
|
|
See the [contribution
|
2017-11-20 17:55:43 +00:00
|
|
|
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
|
|
|
|
2024-04-07 17:26:01 +00:00
|
|
|
GLFW supports Windows XP and later and macOS 10.11 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
|
|
|
|
2021-06-09 20:43:27 +00:00
|
|
|
See the [compatibility guide](https://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
|
|
|
|
|
|
2024-02-29 14:39:21 +00:00
|
|
|
GLFW itself needs only CMake 3.4 or later and the headers and libraries for your
|
2019-11-26 17:09:22 +00:00
|
|
|
OS and window system.
|
2016-08-08 23:34:56 +00:00
|
|
|
|
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
|
2019-04-14 15:34:38 +00:00
|
|
|
- [glad2](https://github.com/Dav1dde/glad) for loading OpenGL and Vulkan
|
|
|
|
|
functions
|
2015-08-09 14:58:25 +00:00
|
|
|
- [linmath.h](https://github.com/datenwolf/linmath.h) for linear algebra in
|
|
|
|
|
examples
|
2021-01-03 20:13:02 +00:00
|
|
|
- [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
|
2015-08-10 18:19:04 +00:00
|
|
|
|
2021-06-09 20:43:27 +00:00
|
|
|
The documentation is generated with [Doxygen](https://doxygen.org/) if CMake can
|
2017-07-11 22:21:17 +00:00
|
|
|
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
|
2017-11-20 17:55:43 +00:00
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
2024-02-29 14:28:46 +00:00
|
|
|
## Changelog since 3.4
|
2022-03-31 15:49:50 +00:00
|
|
|
|
2021-03-23 12:53:17 +00:00
|
|
|
- Added OpenGL and OpenGL ES user contexts for multiple window contexts via
|
|
|
|
|
`GLFWusercontext`, `glfwCreateUserContext`, `glfwDestroyUserContext`,
|
2024-03-07 15:02:57 +00:00
|
|
|
`glfwMakeUserContextCurrent`, `glfwGetCurrentUserContext` (#1687,#1870)
|
2024-02-29 15:50:50 +00:00
|
|
|
- Added `GLFW_UNLIMITED_MOUSE_BUTTONS` input mode that allows mouse buttons beyond
|
|
|
|
|
the limit of the mouse button tokens to be reported (#2423)
|
2024-04-07 17:39:52 +00:00
|
|
|
- [Cocoa] Added `QuartzCore` framework as link-time dependency
|
2024-04-07 17:26:01 +00:00
|
|
|
- [Cocoa] Removed support for OS X 10.10 Yosemite and earlier (#2506)
|
2024-03-08 14:22:36 +00:00
|
|
|
- [Wayland] Bugfix: The fractional scaling related objects were not destroyed
|
2024-03-25 20:00:08 +00:00
|
|
|
- [Wayland] Bugfix: `glfwInit` would segfault on compositor with no seat (#2517)
|
2024-04-08 16:50:08 +00:00
|
|
|
- [Wayland] Bugfix: A drag entering a non-GLFW surface could cause a segfault
|
2024-03-11 10:33:51 +00:00
|
|
|
- [Null] Added Vulkan 'window' surface creation via `VK_EXT_headless_surface`
|
2024-03-11 13:29:07 +00:00
|
|
|
- [Null] Added EGL context creation on Mesa via `EGL_MESA_platform_surfaceless`
|
2024-03-25 20:02:10 +00:00
|
|
|
- [EGL] Allowed native access on Wayland with `GLFW_CONTEXT_CREATION_API` set to
|
|
|
|
|
`GLFW_NATIVE_CONTEXT_API` (#2518)
|
2013-02-04 09:46:02 +00:00
|
|
|
|
|
|
|
|
## Contact
|
|
|
|
|
|
2021-06-09 20:43:27 +00:00
|
|
|
On [glfw.org](https://www.glfw.org/) you can find the latest version of GLFW, as
|
2016-08-02 13:58:58 +00:00
|
|
|
well as news, documentation and other information about the project.
|
2013-02-04 09:46:02 +00:00
|
|
|
|
|
|
|
|
If you have questions related to the use of GLFW, we have a
|
2024-01-25 15:30:56 +00:00
|
|
|
[forum](https://discourse.glfw.org/).
|
2013-02-04 09:46:02 +00:00
|
|
|
|
|
|
|
|
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.
|
2013-02-04 09:46:02 +00:00
|
|
|
|
|
|
|
|
Finally, if you're interested in helping out with the development of GLFW or
|
2024-01-25 15:30:56 +00:00
|
|
|
porting it to your favorite platform, join us on the forum or GitHub.
|
2013-02-04 09:46:02 +00:00
|
|
|
|
