GLFW

GLFW 2.7.2 release notes

Table of contents

  1. Introduction
  2. Compiling GLFW and the example programs
  3. Installing GLFW
  4. Using GLFW
  5. Version history
  6. Directory structure of the GLFW distribution
  7. Contacting the project
  8. Acknowledgements

1. Introduction

Welcome to version 2.7.2 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 is expected to be the last major release of the 2.x series, with most development now being done on what will become version 3.0.

This release brings support for OpenGL 3.2 on OS X Lion and adds a number of bug fixes for minor issues in 2.7.1.

2. Compiling GLFW and the example programs

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 or gmake, depending on the name of your make tool), 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 with the LCC-Win32 C compiler, i.e.:

make win32-lcc

That will compile the GLFW static link library and the supplied example programs. For Windows compilers, a Win32 DLL will also be compiled.

Currently supported compilers and systems are:

There are also project files available for Microsoft Visual C++ 2008 and 2010 in the support/msvc90 and support/msvc100 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 bug tracker on SourceForge.net. 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.

2.1 Microsoft Windows

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.

2.1.1 Microsoft Visual C++ 2008 and later

Project files for both the static and dynamic versions of the GLFW library are provided in the support/msvc90 and support/msvc100 directories.

2.1.2 MSYS or Cygwin on Windows

GLFW can be cross-compiled to native Win32 code using the Cygwin environment. The Cygwin build path will also work on MinGW with MSYS.

Open a Cygwin or MSYS shell, enter the GLFW root directory and run make with the win32-cygwin target.

2.1.3 Bare MinGW on Windows

GLFW can be compiled using only bare bone MinGW, using the Windows command-line environment for file management. Open a regular command prompt, enter the GLFW root directory and run the MinGW make program mingw32-make with the win32-mingw target.

2.1.4 OpenWatcom on Windows

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).

2.1.5 MinGW cross-compilation for Unix or Unix-like systems

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. Use the regular make program with the cross-mgw target. These binaries are also regularly tested with Wine.

2.2 X11 on Unix-like systems

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 when necessary. It has been tested under Ubuntu Linux, Slackware Linux, Debian GNU/Linux and others and should hopefully run on the majority of available Unix-like systems and generate functional Makefiles. You do not have to run the script manually, since it is called from the top-level makefile.

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.

_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.

2.3 Apple GCC or Clang on Mac OS X

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.

3. Installing GLFW

3.1 Windows

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).

3.2 Unix

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-distro-install target.

3.4 Mac OS X

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.

4. Using GLFW

There are two aspects to using GLFW:

  1. How does the GLFW API work
  2. 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.

4.1 Include the GLFW header file

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 gl.h and GL/glu.h header files, and - this is very important - it defines all the necessary constants and types that are necessary for the OpenGL headers to work on different platforms.

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.

In other words:

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.

4.2 Link with the right libraries

4.2.1 Windows static library

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 user32.lib
MinGW32 -lglfw -lopengl32
OpenWatcom glfw.lib opengl32.lib user32.lib

4.2.2 Windows DLL

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
MinGW32 -lglfwdll
OpenWatcom glfwdll.lib

4.2.3 Unix static library

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 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.

4.2.5 Mac OS X static library

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

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.

5. Version history

v2.7.2

v2.7.1

v2.7

v2.6

v2.5

v2.4.2

v2.4.1

v2.4

v2.3.2

v2.3.1

v2.3

v2.2.3

v2.2.2

v2.2.1

v2.2

v2.1

v2.0.3

v2.0.2

v2.0.1

v2.0

v1.0.2

v1.0.1

v1.0.0

6. Directory structure of the GLFW distribution

Here is an overview of the directory structure of the GLFW distribution:

docs GLFW manuals in PDF format
examples Several example programs in C
include/GL Here is the GLFW C/C++ include file
lib Platform independent source files
lib/cocoa Mac OS X/Cocoa specific implementation
lib/win32 Windows specific implementation
lib/x11 Unix/X11 specific implementation
support/d D support
support/msvc90 Project files for Visual C++ 2008
support/msvc100 Project files for Visual C++ 2010
support/pascal Pascal support
tests Several test programs in C

7. Contacting the project

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, and a user's mailing list 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 one of the GLFW trackers on SF.net.

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.

8. Acknowledgements

GLFW exists because people around the world donated their time and lent their skills. Special thanks go out to:

Copyright © elmindreda