Welcome to version 3.0 of the GLFW library. GLFW is a free, open source, portable library for OpenGL application development. It provides a powerful API for handling operating system specific tasks, such as opening an OpenGL window, reading keyboard, mouse, joystick and time input, and more.
This is an experimental series intended to allow the new API to settle.
Note that the threading and image loading APIs from the 2.x series have been removed.
To compile GLFW and the accompanying example programs, you will need the CMake build system.
A rudimentary installation target is provided for all supported platforms via the CMake build system.
There are two aspects to using 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 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:
GL/gl.h or GL/glu.h
yourself, as GLFW does this for youwindows.h unless you actually need
direct access to the Windows APIwindows.h, do it
before including GL/glfw.h and the GLFW header will
detect this.
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 user32.lib |
| MinGW32 | -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_DLLWhen 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 |
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.
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 OpenGLNote 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.
GLFWwindow window handle type and updated window-related functions and callbacks to take a window handleglfwIsWindow function for verifying that a given window handle is (still) validglfwMakeContextCurrent function for making the context of the specified window currentglfwGetError and glfwErrorString error reporting functions and a number of error tokensglfwSetErrorCallback function and GLFWerrorfun type for receiving more specific and/or nested errorsglfwSetWindowUserPointer and glfwGetWindowUserPointer functions for per-window user pointersglfwGetVersionString function for determining which code paths were enabled at compile timeglfwGetWindowPos function for querying the position of the specified windowglfwSetWindowFocusCallback function and GLFWwindowfocusfun type for receiving window focus eventsglfwSetWindowIconifyCallback function and GLFWwindowiconifyfun type for receiving window iconification eventsglfwGetCurrentContext function for retrieving the window whose OpenGL context is currentGLFWallocator type and glfwInit parameter for pluggable memory allocatorglfwCopyContext function for copying OpenGL state categories between contextsGLFW_OPENGL_ES2_PROFILE profile for creating OpenGL ES 2.0 contexts using the GLX_EXT_create_context_es2_profile and WGL_EXT_create_context_es2_profile extensionsGLFW_OPENGL_ROBUSTNESS window hint and associated strategy tokens for GL_ARB_robustness supportGLFW_OPENGL_REVISION window parameter to make up for removal of glfwGetGLVersionGLFW_INCLUDE_GL3 macro for telling the GLFW header to include gl3.h header instead of gl.hwindows simple multi-window test programsharing simple OpenGL object sharing test programdynamic simple dynamic linking test programglfwOpenWindow for specifying a context the new window's context will share objects withglfwOpenWindowglfwSetGamma, glfwSetGammaRamp and glfwGetGammaRamp functions and GLFWgammaramp type for monitor gamma ramp controlglfwOpenWindow to window hintsglfwOpenWindow and glfwSetWindowTitle to use UTF-8 encoded stringsglfw.h to glfw3.h to avoid conflicts with 2.x seriesGLFW_WINDOW token to GLFW_WINDOWEDGLFW_WINDOW_NO_RESIZE to GLFW_WINDOW_RESIZABLEversion test to glfwinfoglfwEnable and glfwDisable with glfwGetInputMode and glfwSetInputModeGLFW_KEY_REPEATGLFW_AUTO_POLL_EVENTS window enableglfwSleep functionglfwGetNumberOfProcessors functionglfwGetGLVersion functionGLFW_OPENED window parameterGLFWCALL and GLFWAPIENTRY macros for stdcall calling conventionglfwinfo test was set to 1.1GL_ARB_multisampleGLX_EXT_swap_control extension as an alternative to GLX_SGI_swap_controlCLOCK_MONOTONIC time source as the preferred method_NET_WM_NAME and _NET_WM_ICON_NAME EWMH window propertiesglXCreateContextAttribsARB with an unavailable OpenGL version caused the application to terminate with a BadMatch Xlib errorGLFW_OPENGL_VERSION_MAJOR and GLFW_OPENGL_VERSION_MINOR
hints for versioned context creationGLFW_OPENGL_FORWARD_COMPAT hint for forward compatible context creationGLFW_OPENGL_DEBUG_CONTEXT hint for debug context creationGLFW_OPENL_PROFILE hint for context creation using profilesGLFW_NO_GLU macro for disabling the inclusion of the GLU header by the GLFW headerglfwOpenWindowHintglfwSwapBuffers to call glfwPollEvents after buffer swapkeytest example program, as it was superseded by the events testx11-dist-install install target, intended for packagers of GLFWx11-dist-clean build target, intended for developers of GLFWGLX_SGIX_fbconfigCFLAGSGLFW_SYSTEM_KEYSglfwCloseWindowBadMatch error_NET_WM_PING events was malformed_NET_ACTIVE_WINDOW_NET_WM_STATE client message-m32 flag caused build failure on 10.6 Snow Leopard-mmacosx-version-min flag caused build failure on 10.5 LeopardglfwOpenWindow did not call glClearWM_SYSCOMMANDGetExtensionsStringARB was not initializedDllMain performed a number of forbidden actions (by calling glfwTerminate)GLFW_FSAA_SAMPLES multisampling hintGLFW_WINDOW_NO_RESIZE hint for non-resizable windowsglfwReadMemoryImage function for creating a GLFWImage object from an image file in a memory bufferglfwLoadMemoryTexture2D function for decoding an image file in a memory buffer into a textureglfwLoadTextureImage2D function for loading a GLFWImage object into a texture_NET_WM_PING protocolgettimeofdayglfwSetMousePos for windowed modesupport folder to the distribution, which includes
support for various languagesHere 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 | The source code for GLFW | |
cocoa | Mac OS X/Cocoa specific implementation | |
win32 | Windows specific implementation | |
x11 | Unix/X11 specific implementation | |
support | ||
d | D support | |
msvc90 | Project files for Visual C++ 9.0 | |
pascal | Pascal support | |
tests | Several test programs in C |
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.
GLFW exists because people around the world donated their time and lent their skills. Special thanks go out to:
GLFW_ICON resourceGLFW_NO_GLU macro_NET_WM_PING response