Welcome to version 2.7.9 of the GLFW library. GLFW is a free, Open Source, multi-platform library for OpenGL application development that provides a powerful API for handling operating system specific tasks such as opening an OpenGL window, reading keyboard, mouse, joystick and time input, creating threads, and more.
GLFW 2.7.9 is the last release of the 2.x series, having been replaced by
GLFW 3.0. They do not share a repository as
GLFW 3.0 was based on the now defunct glfw-lite branch and was then developed
in parallel with 2.7.x for several years.
This release adds fixes for multiple cursor motion bugs on Windows and fixes support for the LFLAGS environment variable on OS X.
For a full list of changes, see the change log below.
A top level makefile can be found in the root directory of the GLFW
distribution that has been designed to work with several compilers. If you
simply enter the GLFW root directory in a shell and type make (or
nmake, mingw32-make, gnumake,
gmake or something else, depending on your development
envronment), and a list should appear with the currently supported options for
systems and compilers.
For example, one of the options is to compile GLFW for Windows using MinGW and MSYS. To do this, use:
make win32-msys
This will compile the GLFW static library and DLL as well as the supplied example and test programs.
Currently supported compilers and systems are:
- Microsoft Visual C++ 2008, 2010 and 2012
- MinGW with or without MSYS
- MinGW cross-compilation for Unix-like systems
- OpenWatcom for Windows
- Unix or Unix-like systems running the X Window System
- Apple GCC or Clang on Mac OS X
There are also project files available for Microsoft Visual C++ 2008, 2010 and
2012 in the support/msvc90, support/msvc100 and support/msvc110
directories.
If your compiler/system is not in the list, you may have to create new
makefiles in the lib\win32, lib/x11 or
lib/cocoa directory, and in the examples directory.
If you have any problems, please use our
support forum
and
issue tracker. We would like to
support as many systems as possible, so if you had to make any modifications or
additions to the source and/or makefiles in order to make GLFW compile
successfully, we would very much like to know what you had to do.
When building GLFW as a DLL (dynamic link library), all compilation units
need to have the GLFW_BUILD_DLL macro defined. All build methods
listed below already does this, but you need to do it yourself if you are
making a custom build. Without this macro, the GLFW DLL will not export
functions correctly and code calling the DLL will be incorrectly generated.
Project files for both the static and dynamic versions of the GLFW library are
provided in the support/msvc90, support/msvc100 and support/msvc110
directories.
GLFW can be compiled using only
MinGW. Open a Windows command prompt,
enter the root directory of the GLFW source distribution and use the
win32-mingw target:
mingw32-make win32-mingw
If you have both MinGW and MSYS
installed, a better alternative is to use the built-in MSYS support. Open an
MSYS shell, enter the root directory of the GLFW source distribution and use
the win32-msys target:
mingw32-make win32-msys
GLFW can be cross-compiled to native Win32 code using the MinGW packages in
Cygwin (the newer mingw-
packages, not the older gcc-mingw- ones). Open a Cygwin shell,
enter the root directory of the GLFW source distribution and use the
cross-mgw target:
env TARGET=i686-pc-mingw32- make cross-mgw
This results in binaries that are functionally identical to those produced
by the other MinGW variants, i.e. they will use msvcrt.dll as libc
and will have no dependency on Cygwin.
Some Unix-like systems have a MinGW cross-compilation package for compiling
native Win32 binaries, for example the mingw32 package on Debian
GNU/Linux and its derivatives. You can use this to build Win32 binaries of
GLFW and all examples without having to run Microsoft Windows or even Wine.
Use the regular make program with the cross-mgw target. You may
also need to adjust the TARGET environment variable, depending on
how packagers named the binaries.
GLFW can be compiled using OpenWatcom for Windows by running the following in the GLFW root directory:
nmake MAKE=nmake win32-ow
Also make sure that you have all your environment variables set up
correctly. It is the default option when installing OpenWatcom to permanently
set up all the required environment variables. If nmake is
unavailable, you probably have to run WATCOM\setvars.bat from the
command prompt first, where WATCOM is the directory in which you
installed OpenWatcom (e.g. C:\Watcom).
Compiler and link library capabilities are auto-detected with a script
called compile.sh. Note that you don't need to run this script
yourself, as it is run automatically by the top-level makefile when necessary.
It has been tested on FreeBSD and many Linux distributions and should hopefully
run correctly on the majority of available Unix-like systems.
If you wish to customize the compilation or link flags for GLFW, set the
CFLAGS or LFLAGS environment variables as needed
before building the library. These flags will be picked up and added to the
generated Makefile.x11 files.
If you wish to use a certain compiler, set the CC environment
variable before building the library. This will also be stored in the
generated Makefile.x11 files.
If you have already configured your source tree, you can reset it to an
un-configured state by running make with the x11-dist-clean target.
If you are making your own build setup for GLFW, you need to be aware of the
various preprocessor symbols that the bundled makefiles use to enable various
features and code paths. They need to be defined either on the command-line or
at the very beginning for each GLFW source file with an x11_
prefix.
Note that the X11 port of GLFW compiles on Mac OS X, but is currently unable to open a window when running against X11.app, due to Apple's incomplete implementation of GLXFBConfigs.
| Preprocessor | Description |
|---|---|
_GLFW_USE_LINUX_JOYSTICKS |
Use the Linux joystick API. This is the only supported API for the X11 port. Without it, joystick input will be unavailable. |
_GLFW_HAS_XRANDR |
Use the X Resize and Rotate extension for display mode changes. This is the preferred method. |
_GLFW_HAS_XF86VIDMODE |
Use the Xf86VidMode extension for display mode changes. This is a fall-back method. |
_GLFW_HAS_PTHREAD |
Use the POSIX Threads API for threading. This is the only supported API for the X11 port. Without it, threading will be disabled. |
_GLFW_HAS_SCHED_YIELD |
Call the sched_yield function inside glfwPlatformSleep. |
_GLFW_HAS_GLXGETPROCADDRESS |
Use the glXGetProcAddress function to retrieve OpenGL entry point addresses. |
_GLFW_HAS_GLXGETPROCADDRESSARB |
Use the glXGetProcAddressARB function to retrieve OpenGL entry point addresses. |
_GLFW_HAS_GLXGETPROCADDRESSEXT |
Use the glXGetProcAddressEXT function to retrieve OpenGL entry point addresses. |
_GLFW_HAS_DLOPEN |
Use dlopen on the OpenGL shared library to retrieve OpenGL entry point addresses. This is a fall-back method. |
_GLFW_HAS_SYSCONF |
Use the sysconf API to find the number of processors. |
_GLFW_HAS_SYSCTL |
Use the sysctl API to find the number of processors. |
To compile GLFW for Mac OS X, you will need to have installed the Developer Tools. A version of these tools can be found on your Mac OS X disc, with newer versions available from the Apple Developer Connection site. When they are installed, simply open Terminal and go to the root GLFW directory. From there, you can build the library and all the examples by running make with the appropriate target, i.e.:
make cocoa
The default compiler for the Cocoa port of GLFW is cc, which as
of Mac OS X 10.6 still defaults to GCC, but you can override this using the
CC environment variable. For example, to build GLFW using Clang,
use:
env CC=clang make cocoa
There is also a deprecated Carbon port of GLFW, which is limited to 32-bit code and only runs well on Mac OS X 10.3 and 10.4. However, if you need to build applications for those systems, it is a better choice than the Cocoa port, which uses APIs unavailable on systems older than 10.5.
After compiling GLFW with MinGW or Cygwin, three files of interest should
have appeared in the lib\win32 directory. They are:
libglfw.a (the static link version of GLFW), glfw.dll
(the DLL version of GLFW) and libglfwdll.a (the DLL import
library).
To install GLFW on Cygwin (and possibly MinGW), run make with the
cygwin-install target. This will generate the pkg-config file and
copy it, the header file and the library to the correct locations of your
Cygwin installation. If you wish to change the installation location from its
default, set the desired prefix path with the environment variable
PREFIX.
If you used Borland C++ Builder, LCC-Win32, Microsoft Visual C++ or
OpenWatcom, the files are named glfw.lib (the static link version
of GLFW), glfw.dll (the DLL version of GLFW) and
glfwdll.lib (the DLL import library).
The static link library and the DLL import library should be copied to your
compiler's LIB directory (where all other link libraries are
located). The DLL can be copied either to your Windows system directory (where
opengl32.dll is located), or to the project directory of your GLFW-based
projects (where you place your executable files).
You should also copy the GLFW include file, include\GL\glfw.h,
to the GL directory of your compiler's include directory (i.e.
where gl.h, glu.h etc. are located).
After compiling GLFW, three files named libglfw.pc.in,
libglfw.a and libglfw.so should have appeared in the
lib/x11 directory. This is the pkg-config template file, the GLFW
static link library and the GLFW shared library, respectively.
To install GLFW onto your system, run make as root with the
x11-install make target. This will install the pkg-config file, the
static library and the header. By default, the files will be installed under
/usr/local. If you wish to install to a different location, set the
PREFIX environment variable appropriately when running make.
Note that the shared library is not installed by default, as you really should think twice before using it. GLFW is very small and shared library distribution on Unix outside of packaging systems is quite tricky. The GLFW license also allows static linking without requiring you to share your code.
However, if you're a *nix distribution packager, use a language binding or
for some other reason wish to install the shared library along with the rest,
run make with the x11-dist-install target.
After compiling GLFW, three files named libglfw.pc.in,
libglfw.a and libglfw.dylib should appear in the
lib/cocoa directory. This is the pkg-config template file, the GLFW
static link library and the GLFW dynamic library, respectively.
To install GLFW onto your system, run make with sudo and the
cocoa-install build target, i.e.:
sudo make cocoa-install
This will install the pkg-config file, the static library and the header. By
default, the files will be installed under /usr/local. If you wish
to install to a different location, set the environment variable
PREFIX appropriately when running make.
Note that the shared library is not installed by default, as you really should think twice before using it. GLFW is very small and very suitable for static linking. The GLFW license also allows static linking without requiring your to share your code.
There are two aspects to using GLFW:
- How does the GLFW API work
- How to compile programs that use GLFW
The first point is covered in the GLFW Users Guide and the GLFW Reference Manual, and we suggest that you read at least the Users Guide, since it's a good introduction to the GLFW API.
Designing and compiling programs that use GLFW is not very difficult. A few rules for successfully designing GLFW-based programs are presented in the following sections.
In the files of your program where you use OpenGL or GLFW, you should
include the GL/glfw.h header file, i.e.:
#include <GL/glfw.h>
This defines all the constants, types and function prototypes of the GLFW API. It also includes the OpenGL and GLU header files, and defines all the necessary constants and types that are necessary for these headers to work on that particular platform.
For example, under Microsoft Windows you are normally required to include
windows.h before you include GL/gl.h. This would
however make your code dependent on the Windows platform, or at least require
your program to check which platform it is being compiled on.
The GLFW header file takes care of this for you, not by including
windows.h, but rather by itself duplicating the necessary parts of
it. This way, the namespace won't be cluttered by the entire Windows API.
By default, the regular gl.h OpenGL header is included. If you
wish to include the draft gl3.h header instead, define
GLFW_INCLUDE_GL3 before the inclusion of the GLFW header.
By default, the glu.h GLU header is included. If you wish to
avoid this, define GLFW_NO_GLU before the inclusion of the GLFW
header.
In other words:
- Do not include
gl.horglu.hyourself, as GLFW does this for you - Do not include
windows.hunless you need direct access to the Windows API - If you do include
windows.h, do it before includingGL/glfw.h. The GLFW header will detect this and act appropriately.
Also note that if you are using an OpenGL extension loading library such as
GLEW, you should include the GLEW
header before the GLFW one. The GLEW header defines macros that
disable any gl.h that the GLFW header includes and GLEW will work
as expected.
If you link with the static version of GLFW, it is also necessary to link with some system libraries that GLFW uses.
When linking a program under Windows that uses the static version of GLFW,
you must also link with the following libraries: opengl32,
user32 and kernel32. Some of these libraries may be
linked with by default by your compiler. In the table below you can see the
minimum required link options for each supported Windows compiler (you may want
to add other libraries as well, such as glu32):
| Compiler | Link options |
|---|---|
| Borland C++ Builder | glfw.lib opengl32.lib |
| Cygwin | See Unix static library below |
| LCC-Win32 | glfw.lib opengl32.lib |
| Microsoft Visual C++ | glfw.lib opengl32.lib |
| MinGW and MinGW-w64 | -lglfw -lopengl32 |
| OpenWatcom | glfw.lib opengl32.lib user32.lib |
To compile a program that uses the DLL version of GLFW, you need to
define the GLFW_DLL constant. This can either be done with a
compiler switch, typically by adding -DGLFW_DLL to the list of
compiler options. You can also do it by adding the following line to all your
source files before including the GLFW header file:
#define GLFW_DLL
When linking a program under Windows that uses the DLL version of GLFW,
the only library you need to link with for GLFW to work is glfwdll.
In the table below you can see the minimum required link options for each
supported Windows compiler (you may want to add other libraries as well,
such as opengl32 and glu32):
| Compiler | Link options |
|---|---|
| Borland C++ Builder | glfwdll.lib |
| Cygwin | -lglfwdll |
| LCC-Win32 | glfwdll.lib |
| Microsoft Visual C++ | glfwdll.lib |
| MinGW and MinGW-w64 | -lglfwdll |
| OpenWatcom | glfwdll.lib |
GLFW supports pkg-config,
and a libglfw.pc file is generated and installed when you install
the library. For systems that do not provide pkg-config, you should look in
this file for the proper compile and link flags for your system, as determined
by compile.sh at compile time.
A typical compile and link command-line when using the GLFW static library may look like this:
cc `pkg-config --cflags libglfw` -o myprog myprog.c `pkg-config --static --libs libglfw`
When using the GLFW sharedd library it may look like this:
cc `pkg-config --cflags libglfw` -o myprog myprog.c `pkg-config --libs libglfw`
If you use GLU functions in your program you should also add
-lGLU to your link flags.
When compiling and linking a program under Mac OS X that uses GLFW, you must also link with Cocoa and OpenGL frameworks.
If you are using Xcode, you simply add the GLFW library libglfw.a and
these frameworks to your project. If, however, you are building your program
from the command-line, there are two methods for correctly linking your GLFW
program.
GLFW supports pkg-config, and a libglfw.pc file is generated and installed when you install the library. You can find pkg-config in most packaging systems, such as Fink and MacPorts, so if you have one of them installed, simply install pkg-config. Once you have pkg-config available, the command-line for compiling and linking your program is:
cc `pkg-config --cflags libglfw` -o myprog myprog.c `pkg-config --libs libglfw`
If you do not wish to use pkg-config, you will need to add the required
frameworks and libraries to your command-line using the -l and
-framework switches, i.e.:
cc -o myprog myprog.c -lglfw -framework Cocoa -framework OpenGL -framework IOKit
Note that you do not add the .framework extension to a framework when adding it from the command-line.
These frameworks contain all OpenGL and GLU functions, so there is no need to add additional libraries or frameworks when using GLU functionality. Also note that even though your machine may have Unix-style OpenGL libraries, they are for use with the X Window System, and will not work with the Mac OS X native version of GLFW.
- [Cocoa] Bugfix: The dynamic library makefile rule did not use LFLAGS
- [Win32] Bugfix: Enabling or disabling the cursor for an inactive window did nothing (backported from 3.0)
- [Win32] Bugfix: The locked cursor was re-centered when the window was inactive (backported from 3.0)
- [Win32] Bugfix: The cursor clip rectangle included the title bar (backported from 3.0)
For the full change log since version 1.0, see the version history page.
The official website for GLFW is glfw.org. It contains the latest version of GLFW, news and other information that is useful for OpenGL development.
If you have questions related to the use of GLFW, we have a
user's web forum,
on SF.net, and the registered IRC channel #glfw on
Freenode.
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 on GitHub.
Finally, if you're interested in helping out with the development of
GLFW or porting it to your favorite platform, we have a
developer's mailing list,
or you could join us on #glfw.
GLFW exists because people around the world donated their time and lent their skills. Special thanks go out to:
- artblanc, for a patch replacing a deprecated Core Graphics call
- Bobyshev Alexander and Martins Mozeiko, for the original proposal of an FSAA hint and their work on the Win32 implementation of FSAA
- Keith Bauer, for his invaluable help with porting and maintaining GLFW on Mac OS X, and for his many ideas
- Jarrod Davis, for the Delphi port of GLFW
- Olivier Delannoy, for the initial implementation of FSAA support on X11, cross-compiling support for MinGW and general extreme usefulness
- Paul R. Deppe, who helped with Cygwin support, and made an adaption of PLIB so that it can use GLFW (instead of GLUT)
- Jonathan Dummer, for submitting a patch fixing an input bug on Win32 and
adding logic for the
GLFW_ICONresource - Gerald Franz, who made GLFW compile under IRIX, and supplied patches for the X11 keyboard translation routine
- Marcus Geelnard, the original author and long-time maintainer of GLFW, without whose brilliant work none of this would have happened
- Stefan Gustavson, for quick and thorough testing of GLFW on many and varied operating systems and hardware configurations
- Sylvain Hellegouarch, for support, bug reports and testing
- Alex Holkner, for writing the code from which the Compiz/Intel fix was stolen
- Toni Jovanoski, for helping with the MASM32 port of GLFW, and supplying the example program and fixed OpenGL and GLU bindings for MASM32
- Cameron King, for reporting a hidden cursor mouse bug on X11
- Peter Knut, for his many and detailed reports of difficult to find input bugs
- Robin Leffmann, for his work on Mac OS X and other platforms, and his invaluable support
- Glenn Lewis, for helping out with support for the D programming language
- Shane Liesegang, for providing a bug fix relating to Cocoa window restoration and reporting several Cocoa bugs
- Tristam MacDonald, for his bug reports and feedback on the Cocoa port
- David Medlock, for doing the initial Lua port
- Kenneth Miller, for his many and detailed bug reports on Win32
- Jeff Molofee, the author of the excellent OpenGL tutorials at NeHe Productions. Much of the Windows code of GLFW was originally based on Jeff's code
- Douglas C. Schmidt and Irfan Pyarali, for their excellent article Strategies for Implementing POSIX Condition Variables on Win32
- Sebastian Schuberth, for the OpenWatcom makefiles
- Matt Sealey, for helping with the MorphOS port
- Steve Sexton, for reporting an input bug in the Carbon port
- Dmitri Shuralyov, for support, bug reports, bug fixes and testing
- Daniel Skorupski, for reporting a bug in the Win32 DEF file
- Bradley Smith, for his updates of the D support and his ports of the remaining examples to the D language
- Julian Squires, for submitting a patch for a bug in the key repeat logic on X11
- Liam Staskawicz, for finding a bug in the termination logic of the OS X port
- Johannes Stein, for maintaining the Pascal bindings
- Cort Stratton, for reporting two bugs related to the creation of debug contexts
- Sergey Tikhomirov, for the initial implementation of joystick support on Mac OS X
- Samuli Tuomola, for support, bug reports and testing
- Frank Wille, for helping with the AmigaOS port and making GLFW compile under IRIX 5.3
- Yaniel, for fixing a bug with fullscreen windows using OpenGL 3.0 contexts on Cocoa
- Santi Zupancic, for support, bug reports and testing
- Lasse Öörni, for submitting patches for the input code of the Win32 and X11 ports
- Дмитри Малышев, for the idea of a
GLFW_NO_GLUmacro - blanco, for submitting a patch for a deprecation bug in the Cocoa port
- heromyth, for reporting a bug in the D bindings
- Ozzy @ Orkysquad, for his dedication to GLFW, for debugging my source, and for his valuable experience with game development
- Peoro, for reporting a bug in the
_NET_WM_PINGresponse - TTK-Bandit, for submitting a number of input patches adding many missing keys to the Win32 and X11 ports
- yuriks, for reporting a bug in Win32 context creation
- All the unmentioned and anonymous contributors in the GLFW community, for bug reports, patches, feedback and encouragement
- OpenGL.org, and all the people on the discussion forums there that have provided help during the development of GLFW