Context handling guide

Table of Contents

• Context handles
• Context creation hints
• Context object sharing
• Current context
• Swapping buffers
• OpenGL extension handling
  • The glext.h header
  • Checking for extensions
  • Fetching function pointers

The primary purpose of GLFW is to provide a simple interface to window management and OpenGL and OpenGL ES context creation. GLFW supports multiple windows, each of which has its own context.

Context handles

The GLFWwindow object encapsulates both a window and a context. They are created with glfwCreateWindow and destroyed with glfwDestroyWindow (or glfwTerminate, if any remain). As the window and context are inseparably linked, the object pointer is used as both a context and window handle.

Context creation hints

There are a number of hints, specified using glfwWindowHint, related to what kind of context is created. See context related hints in the window handling guide.

Context object sharing

When creating a window and context with glfwCreateWindow, you can specify another window whose context the new one should share its objects with. OpenGL object sharing is implemented by the operating system and graphics driver and is described in the OpenGL documentation. On platforms where it is possible to choose which types of objects are shared, GLFW requests that all are shared.

Current context

Before you can use the OpenGL or OpenGL ES APIs, you need to have a current context of the proper type. The context encapsulates all render state and all objects like textures and shaders.

Note that a context can only be current for a single thread at a time, and a thread can only have a single context at a time.

A context is made current with glfwMakeContextCurrent.

glfwMakeContextCurrent(window);

The current context is returned by glfwGetCurrentContext.

GLFWwindow* window = glfwGetCurrentContext();

Swapping buffers

See swapping buffers in the window handling guide.

OpenGL extension handling

One of the benefits of OpenGL is its extensibility. Independent hardware vendors (IHVs) may include functionality in their OpenGL implementations that expand upon the OpenGL standard before that functionality is included in a new version of the OpenGL specification.

An extension is defined by:

• An extension name (e.g. GL_ARB_debug_output)
• New OpenGL tokens (e.g. GL_DEBUG_SEVERITY_HIGH_ARB)
• New OpenGL functions (e.g. glGetDebugMessageLogARB)

Note the ARB affix, which stands for Architecture Review Board and is used for official extensions. There are many different affixes, depending on who wrote the extension. A list of extensions, together with their specifications, can be found at the OpenGL Registry.

To use a certain extension, you must first check whether the context supports that extension and then, if it introduces new functions, retrieve the pointers to those functions.

This can be done with GLFW, as will be described in this section, but usually you will instead want to use a dedicated extension loading library such as GLEW. This kind of library greatly reduces the amount of work necessary to use both OpenGL extensions and modern versions of the OpenGL API. GLEW in particular has been extensively tested with and works well with GLFW.

The glext.h header

The glext.h header is a continually updated file that defines the interfaces for all OpenGL extensions. The latest version of this can always be found at the OpenGL Registry. It it strongly recommended that you use your own copy, as the one shipped with your development environment may be several years out of date and may not include the extensions you wish to use.

The header defines function pointer types for all functions of all extensions it supports. These have names like PFNGLGETDEBUGMESSAGELOGARB (for glGetDebugMessageLogARB), i.e. the name is made uppercase and PFN and PROC are added to the ends.

Checking for extensions

A given machine may not actually support the extension (it may have older drivers or a graphics card that lacks the necessary hardware features), so it is necessary to check whether the context supports the extension. This is done with glfwExtensionSupported.

if (glfwExtensionSupported("GL_ARB_debug_output"))
{
    // The extension is supported by the current context
}

The argument is a null terminated ASCII string with the extension name. If the extension is supported, glfwExtensionSupported returns non-zero, otherwise it returns zero.

Fetching function pointers

Many extensions, though not all, require the use of new OpenGL functions. These entry points are often not exposed by your link libraries, making it necessary to fetch them at run time. With glfwGetProcAddress you can retrieve the address of extension and non-extension OpenGL functions.

PFNGLGETDEBUGMESSAGELOGARB pfnGetDebugMessageLog = glfwGetProcAddress("glGetDebugMessageLogARB");

In general, you should avoid giving the function pointer variables the (exact) same name as the function, as this may confuse your linker. Instead, you can use a different prefix, like above, or some other naming scheme.

Now that all the pieces have been introduced, here is what they might look like when used together.

#include "glext.h"

#define glGetDebugMessageLogARB pfnGetDebugMessageLog
PFNGLGETDEBUGMESSAGELOGARB pfnGetDebugMessageLog;

// Flag indicating whether the extension is supported
int has_debug_output = 0;

void load_extensions(void)
{
    if (glfwExtensionSupported("GL_ARB_debug_output"))
    {
        pfnGetDebugMessageLog = (PFNGLGETDEBUGMESSAGELOGARB) glfwGetProcAddress("glGetDebugMessageLogARB");
        if (pfnGetDebugMessageLog)
        {
            // Both the extension name and the function pointer are present
            has_debug_output = 1;
        }
    }
}

void some_function(void)
{
    // Now the extension function can be called as usual
    glGetDebugMessageLogARB(...);
}