GLFW 2.7 Lite

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

1. Introduction

Welcome to version 2.7 Lite of the GLFW OpenGL framework. GLFW is a free, open source, portable framework for OpenGL application development. In short, it is a library that constitutes a powerful API for handling operating system specific tasks, such as opening an OpenGL window, reading keyboard and mouse input, and more.

Please note that this is the Lite version of GLFW, which means that some areas of functionality present in 2.x mainline versions of GLFW have been removed.

2. Compiling GLFW and the example programs

To compile GLFW and the accompanying example programs, you will need the CMake build system.

3. Installing GLFW

A rudimentary installation target is provided for all supported platforms via the CMake build system.

For Unix-like platforms, the command is:

$ make install

Note that you may need to run this command as root or via sudo(1) in order to install GLFW into the various system directories.

For Visual C++ and other integrated development environments, an installation target should appear in the by CMake generated project files.

4. Using GLFW

There are two aspects to using GLFW:

  1. How the GLFW API works
  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 GL/glfw.h

In your program, you should include GL/glfw.h like this:

#include <GL/glfw.h>

This include file defines all the necessary constants, types and prototypes that are used to interact with the GLFW API. It also includes GL/gl.h and GL/glu.h, and - it defines all the necessary constants and types that are necessary for OpenGL to work on different platforms.

For instance, under Windows you are normally required to include windows.h before you include GL/gl.h. If you write such a program, it would not compile under e.g. Linux since windows.h does not exist under Linux. GL/glfw.h takes care of these things for you. Note however that it does not actually include windows.h, it merely mimics the parts of it that are needed for GL/gl.h and GL/glu.h (this way we do not get the thousands of constants, types and prototypes that could otherwise possibly interfere with our own declarations).

In other words:

4.2 Link with the correct 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
Pelles C glfw.lib opengl32.lib user32.lib kernel32.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 that include glfw.h, before including it:

#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
Pelles C glfwdll.lib

4.2.3 Unix static library

GLFW now supports pkgconfig, and a libglfw.pc file is generated and installed when you install the library. For systems that do not provide pkgconfig, 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 (using GCC):

gcc `pkg-config --cflags libglfw` -o myprog myprog.c `pkg-config --libs libglfw`

If you use GLU functions in your program then you should also add the -lGLU flag.

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 the following frameworks: Carbon.framework, AGL.framework and OpenGL.framework.

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 now supports pkgconfig, and a pkgconfig file named libglfw.pc is generated and installed when you install the library. You can find pkgconfig in most packaging systems, such as Fink and DarwinPorts, so if you have one of them installed, simply install pkgconfig. Once you have pkgconfig available, the command line for compiling and linking your program is:

gcc `pkg-config --cflags libglfw` -o myprog myprog.c `pkg-config --libs libglfw`

If you do not wish to use pkgconfig, you will need to add the required frameworks and libraries to your command line using the -l and -framework switches, i.e.:

gcc -o myprog myprog.c -lglfw -framework Carbon -framework AGL -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 GL 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 GL libraries, they are for use with the X Window System, and will not work with the Mac OS X native version of GLFW.

9. Frequently Asked Questions

5. Version history

2.7 Lite

2.7

2.6

2.5

2.4.2

2.4.1

2.4

2.3.2

2.3.1

2.3

2.2.3

2.2.2

2.2.1

2.2

2.1

2.0.3

2.0.2

2.0.1

2.0

1.0.2

1.0.1

1.0.0

6. Directory structure of the GLFW distribution

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

Directory Contents
docs GLFW manuals in PDF format
examples Several example programs in C
include/GL The GLFW C/C++ header file
lib The source code for GLFW
lib/macosx Mac OS X-specific code
lib/win32 Windows-specific code
lib/x11 Unix/X11-specific code

7. Contacting the project

The official GLFW web site can be found here: http://glfw.sourceforge.net/. 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 IRC channel #glfw on Freenode.

If you have a bug to report or a feature you'd like to request, please file it in the SF.net trackers.

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 would not be what it is today without the help from: