Add run-time context creation API selection

Fixes #145.

docs/compile.dox

@@ -225,19 +225,13 @@ need to be exported by the EXE to be detected by the driver, so the override
 will not work if GLFW is built as a DLL.
 
 
-@subsubsection compile_options_egl EGL specific CMake 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.
-
-
 @section compile_manual Compiling GLFW manually
 
 If you wish to compile GLFW without its CMake build environment then you will
 have to do at least some of the platform detection yourself.  GLFW needs
-a number of configuration macros to be defined in order to know what it's being
-compiled for and has many optional, platform-specific ones for various features.
+a configuration macro to be defined in order to know what window system it's
+being compiled for and also has optional, platform-specific ones for various
+features.
 
 When building with CMake, the `glfw_config.h` configuration header is generated
 based on the current platform and CMake options.  The GLFW CMake environment
@@ -245,10 +239,6 @@ defines `_GLFW_USE_CONFIG_H`, which causes this header to be included by
 `internal.h`.  Without this macro, GLFW will expect the necessary configuration
 macros to be defined on the command-line.
 
-Three macros _must_ be defined when compiling GLFW: one selecting the window
-creation API and one selecting the context creation API.  Exactly one of each
-kind must be defined for GLFW to compile and link.
-
 The window creation API is used to create windows, handle input, monitors, gamma
 ramps and clipboard.  The options are:
 
@@ -258,19 +248,14 @@ ramps and clipboard.  The options are:
  - `_GLFW_WAYLAND` to use the Wayland API (experimental and incomplete)
  - `_GLFW_MIR` to use the Mir API (experimental and incomplete)
 
-The context creation API is used to enumerate pixel formats / framebuffer
-configurations and to create contexts.  The options are:
-
- - `_GLFW_NSGL` to use the Cocoa OpenGL framework
- - `_GLFW_WGL` to use the Win32 WGL API
- - `_GLFW_GLX` to use the X11 GLX API
- - `_GLFW_EGL` to use the EGL API
-
-Wayland and Mir both require the EGL backend.
-
 If you are building GLFW as a shared library / dynamic library / DLL then you
 must also define `_GLFW_BUILD_DLL`.  Otherwise, you must not define it.
 
+For the EGL context creation API, the following options are available:
+
+ - `_GLFW_USE_EGLPLATFORM_H` to use `EGL/eglplatform.h` for native handle
+   definitions (fallback)
+
 If you are using the X11 window creation API, support for the following X11
 extensions can be enabled:
 
@@ -287,12 +272,6 @@ available:
  - `_GLFW_USE_RETINA` to have windows use the full resolution of Retina displays
    (recommended)
 
-If you are using the EGL context creation API, the following options are
-available:
-
- - `_GLFW_USE_EGLPLATFORM_H` to use `EGL/eglplatform.h` for native handle
-   definitions (fallback)
-
 @note None of the @ref build_macros may be defined during the compilation of
 GLFW.  If you define any of these in your build files, make sure they are not
 applied to the GLFW sources.

docs/context.dox

@@ -177,9 +177,10 @@ python main.py --generator c --no-loader --out-path output
 @endcode
 
 The `--no-loader` option is added because GLFW already provides a function for
-loading OpenGL and OpenGL ES function pointers and glad can call this instead of
-having to implement its own.  There are several other command-line options as
-well.  See the glad documentation for details.
+loading OpenGL and OpenGL ES function pointers, one that automatically uses the
+selected context creation API, and glad can call this instead of having to
+implement its own.  There are several other command-line options as well.  See
+the glad documentation for details.
 
 Add the generated `output/src/glad.c`, `output/include/glad/glad.h` and
 `output/include/KHR/khrplatform.h` files to your build.  Then you need to

docs/news.dox

@@ -61,6 +61,12 @@ GLFW now supports waiting for events for a set amount of time with @ref
 glfwWaitEventsTimeout.
 
 
+@subsection news_32_contextapi Run-time context creation API selection
+
+GLFW now supports selecting the context creation API at run-time with
+[GLFW_CONTEXT_CREATION_API](@ref window_hints_ctx).
+
+
 @section news_31 New features in 3.1
 
 These are the release highlights.  For a full list of changes see the

docs/window.dox

@@ -159,6 +159,7 @@ The following hints are always hard constraints:
 - `GLFW_STEREO`
 - `GLFW_DOUBLEBUFFER`
 - `GLFW_CLIENT_API`
+- `GLFW_CONTEXT_CREATION_API`
 
 The following additional hints are hard constraints when requesting an OpenGL
 context, but are ignored when requesting an OpenGL ES context:
@@ -249,6 +250,24 @@ This hint is ignored for windowed mode windows.
 Possible values are `GLFW_OPENGL_API`, `GLFW_OPENGL_ES_API` and `GLFW_NO_API`.
 This is a hard constraint.
 
+`GLFW_CONTEXT_CREATION_API` specifies which context creation API to use to
+create the context.  Possible values are `GLFW_NATIVE_CONTEXT_API` and
+`GLFW_EGL_CONTEXT_API`.  This is a hard constraint.  If no client API is
+requested, this hint is ignored.
+
+@par
+__OS X:__ The EGL API is not available on this platform and requests to use it
+will fail.
+
+@par
+__Wayland, Mir:__ The EGL API _is_ the native context creation API, so this hint
+will have no effect.
+
+@note An OpenGL extension loader library that assumes it knows which context
+creation API is used on a given platform may fail if you change this hint.  This
+can be resolved by having it load via @ref glfwGetProcAddress, which always uses
+the selected API.
+
 `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` specify the client
 API version that the created context must be compatible with.  The exact
 behavior of these hints depend on the requested client API.
@@ -362,6 +381,7 @@ Window hint                     | Default value               | Supported values
 `GLFW_SRGB_CAPABLE`             | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
 `GLFW_DOUBLEBUFFER`             | `GLFW_TRUE`                 | `GLFW_TRUE` or `GLFW_FALSE`
 `GLFW_CLIENT_API`               | `GLFW_OPENGL_API`           | `GLFW_OPENGL_API`, `GLFW_OPENGL_ES_API` or `GLFW_NO_API`
+`GLFW_CONTEXT_CREATION_API`     | `GLFW_NATIVE_CONTEXT_API`   | `GLFW_NATIVE_CONTEXT_API` or `GLFW_EGL_CONTEXT_API`
 `GLFW_CONTEXT_VERSION_MAJOR`    | 1                           | Any valid major version number of the chosen client API
 `GLFW_CONTEXT_VERSION_MINOR`    | 0                           | Any valid minor version number of the chosen client API
 `GLFW_CONTEXT_ROBUSTNESS`       | `GLFW_NO_ROBUSTNESS`        | `GLFW_NO_ROBUSTNESS`, `GLFW_NO_RESET_NOTIFICATION` or `GLFW_LOSE_CONTEXT_ON_RESET`
@@ -889,6 +909,10 @@ topmost or always-on-top.  This is controlled by the
 `GLFW_CLIENT_API` indicates the client API provided by the window's context;
 either `GLFW_OPENGL_API`, `GLFW_OPENGL_ES_API` or `GLFW_NO_API`.
 
+`GLFW_CONTEXT_CREATION_API` indicates the context creation API used to create
+the window's context; either `GLFW_NATIVE_CONTEXT_API` or
+`GLFW_EGL_CONTEXT_API`.
+
 `GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and
 `GLFW_CONTEXT_REVISION` indicate the client API version of the window's context.