One of the major requests by OpenGL users has been the ability to
specify settings when creating a GL context, like the version to use
or whether the debug support should be enabled.

We have a couple of requirements in terms of API:

 • avoid, if at all possible, the "C arrays of integers with
   attribute, value pairs", which are hard to write and hard
   to bind in non-C languages.
 • allow failing in a recoverable way.
 • do not make the GL context creation API a mess of arguments.

Looking at prior art, it seems that a common pattern is to split the
construction phase in two:

 • a first phase that creates a GL context wrapper object and
   does preliminary checks on the environment.
 • a second phase that creates the backend-specific GL object.

We adopted a similar pattern:

 • gdk_window_create_gl_context() creates a GdkGLContext
 • gdk_gl_context_realize() creates the underlying resources

Calling gdk_gl_context_make_current() also realizes the context, so
simple GL users do not need to care. Advanced users will want to
call gdk_window_create_gl_context(), set up the optional requirements,
and then call gdk_gl_context_realize(). If either of these two steps
fails, it's possible to recover by changing the requirements, or simply
creating a new GdkGLContext instance.

https://bugzilla.gnome.org/show_bug.cgi?id=741946