Frequently Asked Questions

This page attempts to address some of the most commonly asked questions that we have received from GLFW users.

Table of contents


Introduction

1.1 - What is GLFW?

GLFW is a small C library that lets you create and manage windows, OpenGL and OpenGL ES contexts and Vulkan surfaces, enumerate monitors and video modes as well as handle inputs such as keyboard, mouse, joystick, clipboard and time.

GLFW provides a thin, multi-platform abstraction layer, primarily for applications whose sole graphics output is through OpenGL, OpenGL ES or Vulkan. While GLFW is very useful when developing multi-platform OpenGL applications, single-platform developers can also benefit from avoiding having to deal with kludgy platform-specific APIs.

Libraries like GLFW are useful because OpenGL and OpenGL ES by themselves do not provide any mechanisms for creating the necessary context, managing windows, user input, timing etc. As stated in the OpenGL 3.1 Specification (chapter 2, first paragraph):

OpenGL is concerned only with rendering into a framebuffer (and reading values stored in that framebuffer). There is no support for other peripherals sometimes associated with graphics hardware, such as mice and keyboards. Programmers must rely on other mechanisms to obtain user input.

GLFW matches the description of other mechanisms quite well.

Unlike the GL APIs, Vulkan does provide its own instance and surface creation functions, but surface creation is platform-specific and the API still only covers rendering.

1.2 - What is GLFW not?

GLFW is by design not…

1.3 - Why yet another OpenGL library?

There are several other libraries available for aiding OpenGL development. The most common ones are freeglut, an Open Source implementation of GLUT, and SDL.

However, freeglut is mostly concerned with providing a stable clone of GLUT, while SDL is too large for some people and has never had OpenGL as its main focus.

We therefore believe that there is room for a lightweight, modern library for managing OpenGL contexts, windows and input.

1.4 - What platforms are supported by GLFW?

Currently, GLFW supports Windows (XP and later), macOS (10.8 Mountain Lion and later) and Unix-like operating systems with Wayland or X11, such as Linux, FreeBSD and Cygwin.

GLFW is designed to be as portable as possible, and the code has been written with portability in mind.

1.5 - What versions of OpenGL are supported by GLFW?

TL;DR All versions supported by your operating system, driver and GPU.

This question likely stems from the original version of the WGL_ARB_create_context and GLX_ARB_create_context extensions, which stated that the old context creation mechanism would be limited to OpenGL version 2.1. However, this is no longer the case and the specifications have been updated accordingly.

GLFW 2.6 and earlier use only the older context creation mechanism, which on Windows and X11 may return contexts of any version, however new, provided they implement the ARB_compatibility extension. Most modern drivers do this.

Explicit creation of OpenGL contexts of version 3.0 and above on Windows and X11, including profiles and flags, is supported by GLFW 2.7 and later.

However, macOS did not support OpenGL 3.0 or later at the time that GLFW 2.7 was released, and the support that Apple has since added only includes forward-compatible OpenGL 3.2 core profile contexts. Additionally, creating such contexts requires new code, so older versions of GLFW cannot create OpenGL 3.0 contexts on macOS.

The first version of GLFW to support creation of OpenGL 3.2 contexts on macOS was 2.7.2.


General

2.1 - Why use separate red/green/blue bit depths?

Because that is how most platforms describe OpenGL-capable pixel formats and how OpenGL describes its framebuffers. It makes GLFW more consistent with the APIs it interacts with, and more future-proof.

This doesn’t, of course, prevent you from presenting the familiar, single value color depths to the user.

2.2 - Is it possible to change video modes after a window has been created?

You can change the resolution of a full screen window with glfwSetWindowSize, but the pixel format, i.e. the framebuffer bit depths will remain the same. Changing the pixel format requires the context to be recreated.

2.3 - Will image or texture loading support be added to GLFW?

No.

2.4 - Will sound support be added to GLFW?

No.

However, if you are looking for an OpenGL-like API for sound, have a look at OpenAL.

2.5 - Will font or text rendering support be added to GLFW?

No.

There are already several competent font rendering toolkits available for OpenGL, none of which require integration with a context or window management library.

2.6 - Will pop-up menu support be added to GLFW?

No.

2.7 - Will message box support be added to GLFW?

Not right now.

The main issue keeping this from being added is the lack of a standard, Unicode-enabled UI toolkit on Unix-like systems such as Linux and FreeBSD. Depending on, say, Gtk+, would therefore introduce a dependency on a huge amount of code not necessarily present on the user’s machine.

As there is no reason why message box code has to be integrated into GLFW, it is better to leave that functionality to a separate library.

2.8 - What is Unicode?

Unicode (sometimes referred to as ISO 10646), is a character coding standard that encodes virtually every character from every written language in the world into a common character set. It is gaining acceptance worldwide, and today most platforms, computer languages and APIs have some sort of support for Unicode (GLFW now being one of them).

Visit The Unicode Consortium for more information about Unicode.

See also Wikipedia on Unicode.

2.9 - Is GLFW thread safe?

Some parts are, specifically those needed to allow rendering and Vulkan object creation from secondary threads. See Thread Safety in the documentation for details.

2.10 - Can I check several keys at once?

Yes, you can.

The function glfwGetKey lets you check the state of any keyboard key (including special keys). You can even call the function from within a callback function, which makes it possible to check for things like Ctrl+F3 key events (when you get a GLFW_KEY_F3 key press event, check the state of the left or right CTRL key with glfwGetKey(window, GLFW_KEY_LEFT_CONTROL) or glfwGetKey(window, GLFW_KEY_RIGHT_CONTROL), or both).

2.11 - What timer APIs does GLFW use?

On Windows, the QueryPerformanceCounter API is used if available, with timeGetTime as a fallback.

On macOS, the Mach mach_absolute_time time source is used.

On Unix-like operating systems using the Wayland and X11 backends, the POSIX CLOCK_MONOTONIC time source is used if available.

2.12 - What window system APIs does GLFW use?

On Windows, plain Win32 is used for window and input management, and WGL or EGL to create OpenGL and OpenGL ES contexts.

On macOS, Cocoa is used for window and input management, and NSOpenGL to create OpenGL contexts.

On Unix-like systems using Wayland, the Wayland API is used for window and input management, and EGL to create OpenGL and OpenGL ES contexts.

On Unix-like systems using X11, the Xlib API is used for window and input management, and GLX or EGL to create OpenGL and OpenGL ES contexts.

2.13 - Why doesn’t your gl.h have the functions I need?

GLFW does not provide any version of either gl.h or glu.h. The glfw3.h header file includes the versions already present in your development environment.

However, if you are using Windows, you cannot get anything newer than OpenGL 1.2 without using extensions. As the extension management in GLFW is very rudimentary, we recommend that you use a dedicated extension loading library such as glad.

2.14 - Why do my objects look all wrong?

GLFW does not wrap OpenGL. No GLFW code is involved when you make an OpenGL call. Think instead of GLFW as connecting your code to OpenGL and then getting out of the way. That connection is the OpenGL context you create and make current with GLFW. If you get incorrect rendering results, it is therefore most likely due to errors in your code, the OpenGL implementation or both.

The OpenGL.org wiki has an extensive article on common mistakes that may be able to help you locate the problem.

2.15 - Can I use extension loaders with GLFW?

Yes, as long as you prevent the GLFW header from including the platform client API header (for example gl.h for OpenGL). There are two ways to do this. Either include the extension loader header before including the GLFW header:

#include <glad/glad.h>
#include <GLFW/glfw3.h>

The extension loader header will disable and replace the standard OpenGL header that the GLFW header includes. You can also disable the standard OpenGL header yourself by defining GLFW_INCLUDE_NONE before including the GLFW header. This will let you include the GLFW and extension loader headers in any order:

#define GLFW_INCLUDE_NONE
#include <GLFW/glfw3.h>
#include <glad/glad.h>

2.16 - How do I use C++ methods as callbacks?

You cannot use regular methods as callbacks, as GLFW is a C library and doesn’t know about objects and this pointers. If you wish to receive callbacks to a C++ object, use static methods or regular functions as callbacks, store the pointer to the object you wish to call as the user pointer for the window and use it to call methods on your object.


Windows

3.1 - What compilers are supported by GLFW?

Currently, GLFW releases are tested with MinGW-w64 and Visual C++ 2013-2022, but it should work with any compiler that supports C99 (C89 on Windows). Very old development environments may require updated system headers.

See the Building programs that use GLFW guide for details on how to compile and link programs on various platforms.

3.3 - Why doesn’t glfwSwapInterval work?

Modern graphics drivers have settings that allow users to override an application’s request for (among other things) swap interval. If such a setting is enabled, glfwSwapInterval will have no effect.

See the Building programs that use GLFW guide for details.

3.5 - Why does my application freeze when I move or resize the window?

The Windows event loop is blocked by certain actions like dragging or resizing a window, or opening the window menu. This is part of the design of Windows and cannot be changed by GLFW. If you wish to keep rendering during such actions, you should render from a secondary thread.


macOS

4.1 - How do I create an OpenGL 3.0+ context?

The only OpenGL 3.x and 4.x contexts currently supported by macOS are forward-compatible, core profile contexts. The supported versions are 3.2 on 10.7 Lion and 3.3 and 4.1 on 10.9 Mavericks. In all cases, your GPU needs to support the specified OpenGL version for context creation to succeed.

To create either an OpenGL 3.2 or later context, you should set the following hints:

glfwWindowHint(GLFW_CONTEXT_VERSION_MAJOR, 3);
glfwWindowHint(GLFW_CONTEXT_VERSION_MINOR, 2);
glfwWindowHint(GLFW_OPENGL_FORWARD_COMPAT, GL_TRUE);
glfwWindowHint(GLFW_OPENGL_PROFILE, GLFW_OPENGL_CORE_PROFILE);

This will give you a context for the highest version of OpenGL greater than or equal to 3.2 that is supported by your OS and GPU. This works because no features were deprecated between OpenGL 3.2 and 4.1, making forward-compatible OpenGL 4.1 backards-compatible with 3.2. If the requested version is not supported, window creation will fail.

If your code requires OpenGL 3.3 or 4.1, you can specify those versions instead, as well as any valid OpenGL version in between.

See the Building programs that use GLFW guide for details.

4.3 - Why is my output in the lower-left corner of the window?

You are passing the window size, which is in screen coordinates, to glViewport, which works with pixels. On macOS with a Retina display, and possibly on other platforms in the future, screen coordinates and pixels do not map 1:1. Use the framebuffer size, which is in pixels, instead of the window size. See the Window handling guide for details.


Unix / X11

See the Building programs that use GLFW guide for details.