CMake | ||
deps | ||
docs | ||
examples | ||
include/GLFW | ||
src | ||
tests | ||
.gitignore | ||
cmake_uninstall.cmake.in | ||
CMakeLists.txt | ||
COPYING.txt | ||
README.md |
GLFW 3.0
Introduction
GLFW is a free, Open Source, portable library for OpenGL and OpenGL ES application development. It provides a simple, platform-independent API for creating windows and contexts, reading input, handling events, etc.
Version 3.0 brings a new API with many new features such as multiple windows and contexts, multi-monitor support, EGL and OpenGL ES support, clipboard text support, an error description callback, gamma ramp control, layout-independent keyboard input and UTF-8 for all strings.
GLFW is now hosted on GitHub.
If you are new to GLFW, you may find the introductory tutorial for GLFW 3 useful. If you have used GLFW 2 in the past, there is a transition guide for moving to the GLFW 3 API.
Compiling GLFW
To compile GLFW and the accompanying example programs, you will need the CMake build system.
Dependencies
X11 dependencies
To compile GLFW for X11 and GLX, you need to have the X and OpenGL header
packages installed. For example, on Ubuntu and other distributions based on
Debian GNU/Linux, you need to install the xorg-dev
and libglu1-mesa-dev
packages. Note that using header files from Mesa will not tie your binary to
the Mesa implementation of OpenGL.
CMake options
There are a number of CMake build options for GLFW, although not all are
available on all supported platforms. Some of these are de facto standards
among CMake users and so have no GLFW_
prefix.
Shared options
BUILD_SHARED_LIBS
determines whether GLFW is built as a static
library or as a DLL / shared library / dynamic library.
LIB_SUFFIX
affects where the GLFW shared /dynamic library is
installed. If it is empty, it is installed to $PREFIX/lib
. If it is set to
64
, it is installed to $PREFIX/lib64
.
GLFW_BUILD_EXAMPLES
determines whether the GLFW examples are built
along with the library.
GLFW_BUILD_TESTS
determines whether the GLFW test programs are
built along with the library.
Mac OS X specific options
GLFW_USE_CHDIR
determines whether glfwInit
changes the current
directory of bundled applications to the Contents/Resources
directory.
GLFW_USE_MENUBAR
determines whether the first call to
glfwCreateWindow
sets up a minimal menu bar.
GLFW_BUILD_UNIVERSAL
determines whether to build Universal Binaries.
Windows specific options
USE_MSVC_RUNTIME_LIBRARY_DLL
determines whether to use the DLL version of the
Visual C++ runtime library.
EGL specific options
GLFW_USE_EGL
determines whether to use EGL instead of the platform-specific
context creation API. Note that EGL is not yet provided on all supported
platforms.
GLFW_CLIENT_LIBRARY
determines which client API library to use. If set to
opengl
the OpenGL library is used, if set to glesv1
for the OpenGL ES 1.x
library is used, or if set to glesv2
the OpenGL ES 2.0 library is used. The
selected library and its header files must be present on the system for this to
work.
Installing GLFW
A rudimentary installation target is provided for all supported platforms via CMake.
Using GLFW
There are two aspects to using GLFW:
- Using the GLFW API
- Compiling and linking programs using the GLFW library
The first point is covered in the WIP reference manual.
Include the GLFW header file
In the files of your program where you use OpenGL or GLFW, you should include the GLFW 3 header file, i.e.:
#include <GLFW/glfw3.h>
This defines all the constants, types and function prototypes of the GLFW API. It also includes the chosen client API header files (by default OpenGL), and defines all the constants and types necessary for those headers to work on that platform.
For example, under Windows you are normally required to include windows.h
before including GL/gl.h
. This would make your source file tied to Windows
and pollute your code's namespace with the whole Win32 API.
Instead, the GLFW header takes care of this for you, not by including
windows.h
, but rather by itself duplicating only the necessary parts of it.
It does this only where needed, so if windows.h
is included, the GLFW header
does not try to redefine those symbols.
In other words:
- Do not include the OpenGL headers yourself, as GLFW does this for you
- Do not include
windows.h
or other platform-specific headers unless you plan on using those APIs directly - If you do need to include such headers, do it before including the GLFW one and it will detect this
If you are using an OpenGL extension loading library such as GLEW, the GLEW header should also be included before the GLFW one. The GLEW header defines macros that disable any OpenGL header that the GLFW header includes and GLEW will work as expected.
GLFW header option macros
These macros may be defined before the inclusion of the GLFW header.
GLFW_INCLUDE_GLCOREARB
makes the header include the modern GL/glcorearb.h
header (OpenGL/gl3.h
on Mac OS X) instead of the regular OpenGL header.
GLFW_INCLUDE_ES1
makes the header include the OpenGL ES 1.x GLES/gl.h
header
instead of the regular OpenGL header.
GLFW_INCLUDE_ES2
makes the header include the OpenGL ES 2.0 GLES2/gl2.h
header instead of the regular OpenGL header.
GLFW_INCLUDE_ES3
makes the header include the OpenGL ES 3.0 GLES3/gl3.h
header instead of the regular OpenGL header.
GLFW_INCLUDE_NONE
makes the header not include any client API header.
GLFW_INCLUDE_GLU
makes the header include the GLU header. This only makes
sense if you are using OpenGL.
GLFW_DLL
is necessary when using the GLFW DLL on Windows.
Link with the right libraries
Using GLFW from CMake
The GLFW_LIBRARIES
cache variable contains all link-time dependencies of GLFW
as it is currently configured, so to link against GLFW simply do:
target_link_libraries(myapp glfw ${GLFW_LIBRARIES})
Note that this does not include GLU, as GLFW does not use it. If your
application needs GLU, you can add it to the list of dependencies with the
OPENGL_glu_LIBRARY
cache variable.
Windows static library
The static version of the GLFW library is named glfw3
. When using this
version, it is also necessary to link with some libraries that GLFW uses.
When linking a program under Windows that uses the static version of GLFW, you
must link with opengl32
. If you are using GLU, you must also link with
glu32
.
Windows DLL
The link library for the GLFW DLL is named glfw3dll
. When compiling a program
that uses the DLL version of GLFW, you need to define the GLFW_DLL
macro
before any inclusion of the GLFW header. This can be done either with
a compiler switch or by defining it in your source code.
A program using the GLFW DLL does not need to link against any of its
dependencies, but you still have to link against opengl32
if your program uses
OpenGL and glu32
if it uses GLU.
Unix library
GLFW supports pkg-config,
and glfw3.pc
file is generated when the library is built and installed along
with it. You can use it without installation using the PKG_CONFIG_PATH
environment variable. See the documentation for pkg-config for more details.
A typical compile and link command-line when using the static may look like this:
cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --static --libs glfw3`
If you are using the shared library, simply omit the --static
flag.
If you are using GLU, you should also add -lGLU
to your link flags.
Mac OS X static library
GLFW on Mac OS X uses the Cocoa, OpenGL and IOKit frameworks.
If you are using Xcode, you can simply add the GLFW library and these frameworks as dependencies.
If you are building from the command-line, it is recommended that you use pkg-config
GLFW supports pkg-config,
and glfw3.pc
file is generated when the library is built and installed along
with it. You can use it without installation using the PKG_CONFIG_PATH
environment variable. See the documentation for pkg-config for more details.
You can find pkg-config in most package 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 glfw3` -o myprog myprog.c `pkg-config --static --libs glfw3`
If you do not wish to use pkg-config, you 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.
The OpenGL framework contains both the OpenGL and GLU APIs, so there is no need
to add additional libraries or frameworks when using GLU. Also note that even
though your machine may have libGL
-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.
Changes for version 3.0
- Added
GLFWmonitor
and updated monitor-related functions to take a monitor handle - Added
glfwGetMonitors
andglfwGetPrimaryMonitor
for enumerating available monitors - Added
glfwGetMonitorPos
,glfwGetMonitorPhysicalSize
andglfwGetMonitorName
for retrieving monitor properties - Added
glfwSetMonitorCallback
andGLFWmonitorfun
for notification of changes in the set of available monitors - Added
GLFWwindow
and updated window-related functions and callbacks to take a window handle - Added
glfwSetWindowShouldClose
andglfwWindowShouldClose
for setting and retrieving the window close flag - Added
glfwGetWindowPos
for retrieving the position of a window - Added
glfwDefaultWindowHints
for resetting all window hints to their default values - Added
glfwMakeContextCurrent
for making the context of the specified window current - Added
glfwSetErrorCallback
,GLFWerrorfun
and error type tokens for receiving error notifications - Added
glfwSetWindowUserPointer
andglfwGetWindowUserPointer
for per-window user pointers - Added
glfwGetVersionString
for determining which code paths were enabled at compile time - Added
glfwGetWindowMonitor
for querying the monitor, if any, of the specified window - Added
glfwGetFramebufferSize
andglfwSetFramebufferSizeCallback
for receiving the current size, in pixels, of the framebuffer - Added
glfwSetWindowPosCallback
andGLFWwindowposfun
for receiving window position events - Added
glfwSetWindowFocusCallback
andGLFWwindowfocusfun
for receiving window focus events - Added
glfwSetWindowIconifyCallback
andGLFWwindowiconifyfun
for receiving window iconification events - Added
glfwGetClipboardString
andglfwSetClipboardString
for interacting with the system clipboard - Added
glfwGetJoystickName
for retrieving the name of a joystick - Added
glfwGetCurrentContext
for retrieving the window whose OpenGL context is current - Added
GLFW_SRGB_CAPABLE
for requesting sRGB capable framebuffers - Added
GLFW_CLIENT_API
and its valuesGLFW_OPENGL_API
andGLFW_OPENGL_ES_API
for selecting client API - Added
GLFW_CONTEXT_ROBUSTNESS
and valuesGLFW_NO_ROBUSTNESS
,GLFW_NO_RESET_NOTIFICATION
andGLFW_LOSE_CONTEXT_ON_RESET
forGL_ARB_robustness
support - Added
GLFW_OPENGL_REVISION
to make up for removal ofglfwGetGLVersion
- Added
GLFW_INCLUDE_GLCOREARB
macro for includingGL/glcorearb.h
instead ofGL/gl.h
- Added
GLFW_INCLUDE_ES1
macro for telling the GLFW header to useGLES/gl.h
instead ofGL/gl.h
- Added
GLFW_INCLUDE_ES2
macro for telling the GLFW header to useGLES2/gl2.h
instead ofGL/gl.h
- Added
GLFW_INCLUDE_NONE
macro for telling the GLFW header to not include any client API header - Added
GLFW_VISIBLE
window hint and parameter for controlling and polling window visibility - Added
GLFW_REPEAT
key action for repeated keys - Added scancode parameter to key callback
- Added
refreshRate
member toGLFWvidmode
struct - Added key modifier parameter to key and mouse button callbacks
- Added
windows
simple multi-window test program - Added
sharing
simple OpenGL object sharing test program - Added
modes
video mode enumeration and setting test program - Added
threads
simple multi-threaded rendering test program - Added
glfw3native.h
header and platform-specific functions for explicit access to native display, window and context handles - Added
glfwSetGamma
,glfwSetGammaRamp
andglfwGetGammaRamp
functions andGLFWgammaramp
type for monitor gamma ramp control - Added window parameter to
glfwSwapBuffers
- Changed buffer bit depth parameters of
glfwOpenWindow
to window hints - Changed
glfwCreateWindow
andglfwSetWindowTitle
to use UTF-8 encoded strings - Changed
glfwGetProcAddress
to return a (generic) function pointer - Changed
glfwGetVideoModes
to return a dynamic, unlimited number of video modes for the specified monitor - Changed cursor position to double-precision floating-point
- Changed default cursor mode for fullscreen to normal
- Renamed header directory
GL
toGLFW
- Renamed
glfw.h
toglfw3.h
to avoid conflicts with 2.x series - Renamed
glfwOpenWindowHint
toglfwWindowHint
- Renamed
glfwGetWindowParam
toglfwGetWindowAttrib
- Renamed
GLFW_ACTIVE
toGLFW_FOCUSED
- Renamed
GLFW_FSAA_SAMPLES
toGLFW_SAMPLES
- Renamed
GLFW_WINDOW_NO_RESIZE
toGLFW_RESIZABLE
- Renamed
GLFW_BUILD_DLL
to_GLFW_BUILD_DLL
- Renamed
version
test toglfwinfo
- Renamed
GLFW_NO_GLU
toGLFW_INCLUDE_GLU
and made it disabled by default - Renamed
glfwGetJoystickPos
toglfwGetJoystickAxes
to matchglfwGetJoystickButtons
- Renamed mouse position functions to cursor position equivalents
- Replaced
glfwOpenWindow
andglfwCloseWindow
withglfwCreateWindow
andglfwDestroyWindow
- Replaced
glfwGetDesktopMode
widthglfwGetVideoMode
- Replaced ad hoc build system with CMake
- Replaced layout-dependent key codes with single, platform-independent set based on US layout
- Replaced mouse wheel interface with two-dimensional, floating point scrolling interface
- Replaced
glfwEnable
andglfwDisable
withglfwGetInputMode
andglfwSetInputMode
- Replaced
joystick
test with graphical version - Replaced automatic closing of windows with the window close flag
- Removed the
GLFW_KEY_REPEAT
input option - Removed event auto-polling and the
GLFW_AUTO_POLL_EVENTS
window enable - Removed the Win32 port .def files
- Removed the entire threading API
- Removed the entire image loading API
- Removed deprecated Carbon port
- Removed registering
glfwTerminate
withatexit
- Removed
glfwSleep
function - Removed
glfwGetNumberOfProcessors
function - Removed
glfwGetGLVersion
function - Removed
GLFW_OPENED
window parameter - Removed
GLFW_WINDOW
andGLFW_FULLSCREEN
- Removed nonsensical key actions for Unicode character input
- Removed
GLFWCALL
andGLFWAPIENTRY
macros for stdcall calling convention - Removed
GLFW_ACCELERATED
window parameter - Removed default framebuffer attributes from
glfwGetWindowParam
- Bugfix: The default OpenGL version in the
glfwinfo
test was set to 1.1 - Bugfix: The OpenGL profile and forward-compatibility window parameters were not saved after context creation
- Bugfix: The FSAA test did not check for the availability of
GL_ARB_multisample
- Bugfix: Cursor centering upon leaving captured cursor mode was reported before the mode was changed to non-captured
- [Cocoa] Added support for OpenGL 3.2 core profile in 10.7 Lion and above
- [Cocoa] Added support for high-DPI (Retina) monitors
- [Cocoa] Added support for joysticks
- [Cocoa] Postponed menu creation to first window creation
- [Cocoa] Replaced
NSDate
time source withmach_absolute_time
- [Cocoa] Replaced all deprecated CoreGraphics calls with non-deprecated counterparts
- [Cocoa] Bugfix: The
NSOpenGLPFAFullScreen
pixel format attribute caused creation to fail on some machines - [Cocoa] Bugfix:
glfwCreateWindow
did not properly enforce the forward-compatible and context profile hints - [Cocoa] Bugfix: The loop condition for saving video modes used the wrong index variable
- [Cocoa] Bugfix: The OpenGL framework was not retrieved, making
glfwGetProcAddress
crash - [Cocoa] Bugfix:
glfwInit
changed the current directory for unbundled executables - [Cocoa] Bugfix: The
GLFW_WINDOW_NO_RESIZE
window parameter was always zero - [Cocoa] Bugfix: The cursor position incorrectly rounded during conversion
- [Cocoa] Bugfix: Cursor positioning led to nonsensical results for fullscreen windows
- [Cocoa] Bugfix: The GLFW window was flagged as restorable
- [X11] Added support for the
GLX_EXT_swap_control
andGLX_MESA_swap_control
extensions as alternatives toGLX_SGI_swap_control
- [X11] Added the POSIX
CLOCK_MONOTONIC
time source as the preferred method - [X11] Added dependency on libm, where present
- [X11] Added support for the
_NET_WM_NAME
and_NET_WM_ICON_NAME
EWMH window properties - [X11] Made client-side RandR and Xf86VidMode extensions required
- [X11] Bugfix: Some window properties required by the ICCCM were not set
- [X11] Bugfix: Calling
glXCreateContextAttribsARB
with an unavailable OpenGL version caused the application to terminate with aBadMatch
Xlib error - [X11] Bugfix: A synchronization point necessary for jitter-free locked cursor mode was incorrectly removed
- [X11] Bugfix: The window size hints were not updated when calling
glfwSetWindowSize
on a non-resizable window - [Win32] Added support for high-DPI monitors
- [Win32] Changed port to use Unicode mode only
- [Win32] Removed explicit support for versions of Windows older than Windows XP
- [Win32] Bugfix: Window activation and iconification did not work as expected
- [Win32] Bugfix: Software rasterizer pixel formats were not discarded by the
WGL_ARB_pixel_format
code path - [Win32] Bugfix: The array for WGL context attributes was too small and could overflow
- [Win32] Bugfix: Alt+F4 hot key was not translated into
WM_CLOSE
- [Win32] Bugfix: The
GLFW_WINDOW_NO_RESIZE
window parameter was always zero - [Win32] Bugfix: A test was missing for whether all available pixel formats had been disqualified
Contact
The official website for GLFW is glfw.org. There you can find the latest version of GLFW, as well as news, documentation and other information about the project.
If you have questions related to the use of GLFW, we have a
support forum, and the 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 issue 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
.
Acknowledgements
GLFW exists because people around the world donated their time and lent their skills.
- Bobyshev Alexander
- artblanc
- Matt Arsenault
- Keith Bauer
- John Bartholomew
- Niklas Bergström
- blanco
- Lambert Clara
- Noel Cower
- Jarrod Davis
- Olivier Delannoy
- Paul R. Deppe
- Jonathan Dummer
- Ralph Eastwood
- Gerald Franz
- GeO4d
- Marcus Geelnard
- Stefan Gustavson
- Sylvain Hellegouarch
- heromyth
- Toni Jovanoski
- Osman Keskin
- Cameron King
- Peter Knut
- Robin Leffmann
- Glenn Lewis
- Shane Liesegang
- Дмитри Малышев
- Martins Mozeiko
- Tristam MacDonald
- Hans Mackowiak
- David Medlock
- Jonathan Mercier
- Marcel Metz
- Kenneth Miller
- Jeff Molofee
- Jon Morton
- Julian Møller
- Ozzy at Orkysquad
- Peoro
- Braden Pellett
- Arturo J. Pérez
- Jorge Rodriguez
- Ed Ropple
- Riku Salminen
- Sebastian Schuberth
- Matt Sealey
- SephiRok
- Steve Sexton
- Dmitri Shuralyov
- Daniel Skorupski
- Bradley Smith
- Julian Squires
- Johannes Stein
- Nathan Sweet
- TTK-Bandit
- Sergey Tikhomirov
- Samuli Tuomola
- Jari Vetoniemi
- Simon Voordouw
- Torsten Walluhn
- Jay Weisskopf
- Frank Wille
- yuriks
- Santi Zupancic
- Lasse Öörni
- All the unmentioned and anonymous contributors in the GLFW community, for bug reports, patches, feedback, testing and encouragement