This guide introduces the basic concepts of GLFW and describes initialization, error handling and API guarantees and limitations. For a broad but shallow tutorial, see Getting started instead. There are also guides for the other areas of GLFW.
Before most GLFW functions may be called, the library must be initialized. This initialization checks what features are available on the machine, enumerates monitors and joysticks, initializes the timer and performs any required platform-specific initialization.
Only the following functions may be called before the library has been successfully initialized, and only from the main thread.
Calling any other function before that time will cause a GLFW_NOT_INITIALIZED error.
The library is initialized with glfwInit, which returns GL_FALSE if an error occurred.
If any part of initialization fails, all remaining bits are terminated as if glfwTerminate was called. The library only needs to be initialized once and additional calls to an already initialized library will simply return GL_TRUE immediately.
Once the library has been successfully initialized, it should be terminated before the application exits.
Before your application exits, you should terminate the GLFW library if it has been initialized. This is done with glfwTerminate.
This will destroy any remaining window, monitor and cursor objects, restore any modified gamma ramps, re-enable the screensaver if it had been disabled and free any resources allocated by GLFW.
Once the library is terminated, it is as if it had never been initialized and you will need to initialize it again before being able to use GLFW. If the library was not initialized or had already been terminated, it return immediately.
Some GLFW functions have return values that indicate an error, but this is often not very helpful when trying to figure out why the error occurred. Some functions also return otherwise valid values on error. Finally, far from all GLFW functions have return values.
This is where the error callback comes in. This callback is called whenever an error occurs. It is set with glfwSetErrorCallback, a function that may be called regardless of whether GLFW is initialized.
The error callback receives a human-readable description of the error and (when possible) its cause. The description encoded as UTF-8. The callback is also provided with an error code.
The error code indicates the general category of the error. Some error codes, such as GLFW_NOT_INITIALIZED has only a single meaning, whereas others like GLFW_PLATFORM_ERROR are used for many different errors.
The description string is only valid until the error callback returns, as it may have been generated specifically for that error. This lets GLFW provide much more specific error descriptions but means you must make a copy if you want to keep the description string.
GLFW has two primary coordinate systems: the virtual screen and the window client area or content area. Both use the same unit: virtual screen coordinates, or just screen coordinates, which don't necessarily correspond to pixels.
Both the virtual screen and the client area coordinate systems have the X-axis pointing to the right and the Y-axis pointing down.
Window and monitor positions are specified as the position of the upper-left corners of their content areas relative to the virtual screen, while cursor positions are specified relative to a window's client area.
Because the origin of the window's client area coordinate system is also the point from which the window position is specified, you can translate client area coordinates to the virtual screen by adding the window position. The window frame, when present, extends out from the client area but does not affect the window position.
Almost all positions and sizes in GLFW are measured in screen coordinates relative to one of the two origins above. This includes cursor positions, window positions and sizes, window frame sizes, monitor positions and video mode resolutions.
Two exceptions are the monitor physical size, which is measured in millimetres, and framebuffer size, which is measured in pixels.
Pixels and screen coordinates may map 1:1 on your machine, but they won't on every other machine, for example on a Mac with a Retina display. The ratio between screen coordinates and pixels may also change at run-time depending on which monitor the window is currently considered to be on.
This section describes the conditions under which GLFW can be expected to function, barring bugs in the operating system or drivers. Use of GLFW outside of these limits may work on some platforms, or on some machines, or some of the time, or on some versions of GLFW, but it may break at any time and this will not be considered a bug.
GLFW will never free any pointer you provide to it and you must never free any pointer it provides to you.
Many GLFW functions return pointers to dynamically allocated structures, strings or arrays, and some callbacks are provided with strings or arrays. These are always managed by GLFW and should never be freed by the application. The lifetime of these pointers is documented for each GLFW function and callback. If you need to keep this data, you must copy it before its lifetime expires.
Many GLFW functions accept pointers to structures or strings allocated by the application. These are never freed by GLFW and are always the responsibility of the application. If GLFW needs to keep the data in these structures or strings, it is copied before the function returns.
Pointer lifetimes are guaranteed not to be shortened in future minor or patch releases.
GLFW event processing and object creation and destruction are not reentrant. This means that the following functions may not be called from any callback function:
These functions may be made reentrant in future minor or patch releases, but functions not on this list will not be made non-reentrant.
Most GLFW functions may only be called from the main thread, but some may be called from any thread. However, no GLFW function may be called from any other thread until GLFW has been successfully initialized on the main thread, including functions that may called before initialization.
The reference documentation for every GLFW function states whether it is limited to the main thread.
Initialization and termination, event processing and the creation and destruction of windows, contexts and cursors are all limited to the main thread due to limitations of one or several platforms.
Because event processing must be performed on the main thread, all callbacks except for the error callback will only be called on that thread. The error callback may be called on any thread, as any GLFW function may generate errors.
The posting of empty events may be done from any thread. The window user pointer and close flag may also be accessed and modified from any thread, but this is not synchronized by GLFW. The following window related functions may be called from any thread:
Rendering may be done on any thread. The following context related functions may be called from any thread:
The timer may be accessed from any thread, but this is not synchronized by GLFW. The following timer related functions may be called from any thread:
Library version information may be queried from any thread. The following version related functions may be called from any thread:
GLFW uses no synchronization objects internally except for thread-local storage to keep track of the current context for each thread. Synchronization is left to the application.
Functions that may currently be called from any thread will always remain so, but functions that are currently limited to the main may be updated to allow calls from any thread in future releases.
GLFW guarantees binary backward compatibility with earlier minor versions of the API. This means that you can drop in a newer version of the GLFW DLL / shared library / dynamic library and existing applications will continue to run.
Once a function or constant has been added, the signature of that function or value of that constant will remain unchanged until the next major version of GLFW. No compatibility of any kind is guaranteed between major versions.
Undocumented behavior, i.e. behavior that is not described in the documentation, may change at any time until it is documented.
If the reference documentation and the implementation differ, the reference documentation is correct and the implementation will be fixed in the next release.
The order of arrival of related events is not guaranteed to be consistent across platforms. The exception is synthetic key and mouse button release events, which are always delivered after the window defocus event.
GLFW provides mechanisms for identifying what version of GLFW your application was compiled against as well as what version it is currently running against. If you are loading GLFW dynamically (not just linking dynamically), you can use this to verify that the library binary is compatible with your application.
The compile-time version of GLFW is provided by the GLFW header with the GLFW_VERSION_MAJOR, GLFW_VERSION_MINOR and GLFW_VERSION_REVISION macros.
The run-time version can be retrieved with glfwGetVersion, a function that may be called regardless of whether GLFW is initialized.
GLFW 3 also provides a compile-time generated version string that describes the version, platform, compiler and any platform-specific compile-time options. This is primarily intended for submitting bug reports, to allow developers to see which code paths are enabled in a binary.
The version string is returned by glfwGetVersionString, a function that may be called regardless of whether GLFW is initialized.
Do not use the version string to parse the GLFW library version. The glfwGetVersion function already provides the version of the running library binary.
The format of the string is as follows:
For example, when compiling GLFW 3.0 with MinGW using the Win32 and WGL back ends, the version string may look something like this:
Last update on Sun Nov 4 2018 for GLFW 3.1.2