Add run-time context creation API selection

Fixes glfw#145.
mlbit · May 4, 2016 · ef80bea · ef80bea
1 parent 9d50a34
commit ef80bea
Showing 32 changed files with 802 additions and 800 deletions.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -35,13 +35,11 @@ if (APPLE)
     option(GLFW_USE_CHDIR "Make glfwInit chdir to Contents/Resources" ON)
     option(GLFW_USE_MENUBAR "Populate the menu bar on first window creation" ON)
     option(GLFW_USE_RETINA "Use the full resolution of Retina displays" ON)
-else()
-    option(GLFW_USE_EGL "Use EGL for context creation" OFF)
 endif()
 
 if (UNIX AND NOT APPLE)
-    option(GLFW_USE_WAYLAND "Use Wayland for context creation (implies EGL as well)" OFF)
-    option(GLFW_USE_MIR     "Use Mir for context creation (implies EGL as well)" OFF)
+    option(GLFW_USE_WAYLAND "Use Wayland for window creation" OFF)
+    option(GLFW_USE_MIR     "Use Mir for window creation" OFF)
 endif()
 
 if (MSVC)
@@ -59,12 +57,6 @@ else()
     set(GLFW_LIB_NAME glfw3)
 endif()
 
-if (GLFW_USE_WAYLAND)
-    set(GLFW_USE_EGL ON)
-elseif (GLFW_USE_MIR)
-    set(GLFW_USE_EGL ON)
-endif()
-
 set(CMAKE_MODULE_PATH "${GLFW_SOURCE_DIR}/CMake/modules")
 
 find_package(Threads REQUIRED)
@@ -129,19 +121,9 @@ endif()
 if (WIN32)
     set(_GLFW_WIN32 1)
     message(STATUS "Using Win32 for window creation")
-
-    if (GLFW_USE_EGL)
-        set(_GLFW_EGL 1)
-        message(STATUS "Using EGL for context creation")
-    else()
-        set(_GLFW_WGL 1)
-        message(STATUS "Using WGL for context creation")
-    endif()
 elseif (APPLE)
     set(_GLFW_COCOA 1)
     message(STATUS "Using Cocoa for window creation")
-    set(_GLFW_NSGL 1)
-    message(STATUS "Using NSGL for context creation")
 elseif (UNIX)
     if (GLFW_USE_WAYLAND)
         set(_GLFW_WAYLAND 1)
@@ -153,14 +135,6 @@ elseif (UNIX)
         set(_GLFW_X11 1)
         message(STATUS "Using X11 for window creation")
     endif()
-
-    if (GLFW_USE_EGL)
-        set(_GLFW_EGL 1)
-        message(STATUS "Using EGL for context creation")
-    else()
-        set(_GLFW_GLX 1)
-        message(STATUS "Using GLX for context creation")
-    endif()
 else()
     message(FATAL_ERROR "No supported platform was detected")
 endif()
@@ -306,7 +280,7 @@ endif()
 #--------------------------------------------------------------------
 # Use Cocoa for window creation and NSOpenGL for context creation
 #--------------------------------------------------------------------
-if (_GLFW_COCOA AND _GLFW_NSGL)
+if (_GLFW_COCOA)
 
     if (GLFW_USE_MENUBAR)
         set(_GLFW_USE_MENUBAR 1)

diff --git a/README.md b/README.md
@@ -93,12 +93,14 @@ does not find Doxygen, the documentation will not be generated.
  - Added `GLFW_NO_API` for creating window without contexts
  - Added `GLFW_CONTEXT_NO_ERROR` context hint for `GL_KHR_no_error` support
  - Added `GLFW_INCLUDE_VULKAN` for including the Vulkan header
+ - Added `GLFW_CONTEXT_CREATION_API`, `GLFW_NATIVE_CONTEXT_API` and
+   `GLFW_EGL_CONTEXT_API` for run-time context creation API selection
  - Added `GLFW_TRUE` and `GLFW_FALSE` as client API independent boolean values
  - Added icons to examples on Windows and OS X
  - Relaxed rules for native access header macros
  - Removed dependency on external OpenGL or OpenGL ES headers
- - Removed `_GLFW_USE_OPENGL`, `_GLFW_USE_GLESV1` and `_GLFW_USE_GLESV2`
-   configuration macros
+ - Removed `_GLFW_USE_OPENGL`, `_GLFW_USE_GLESV1`, `_GLFW_USE_GLESV2`,
+   `_GLFW_WGL`, `_GLFW_NSGL`, `_GLFW_GLX` and `_GLFW_EGL` configuration macros
  - [Win32] Added support for Windows 8.1 per-monitor DPI
  - [Win32] Replaced winmm with XInput and DirectInput for joystick input
  - [Win32] Bugfix: Window creation would segfault if video mode setting required

diff --git a/docs/compile.dox b/docs/compile.dox
@@ -225,30 +225,20 @@ 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
 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.

diff --git a/docs/context.dox b/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

diff --git a/docs/news.dox b/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

diff --git a/docs/window.dox b/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.
 

diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h
@@ -655,6 +655,7 @@ extern "C" {
 #define GLFW_OPENGL_PROFILE         0x00022008
 #define GLFW_CONTEXT_RELEASE_BEHAVIOR 0x00022009
 #define GLFW_CONTEXT_NO_ERROR       0x0002200A
+#define GLFW_CONTEXT_CREATION_API   0x0002200B
 
 #define GLFW_NO_API                          0
 #define GLFW_OPENGL_API             0x00030001
@@ -680,6 +681,9 @@ extern "C" {
 #define GLFW_RELEASE_BEHAVIOR_FLUSH 0x00035001
 #define GLFW_RELEASE_BEHAVIOR_NONE  0x00035002
 
+#define GLFW_NATIVE_CONTEXT_API     0x00036001
+#define GLFW_EGL_CONTEXT_API        0x00036002
+
 /*! @defgroup shapes Standard cursor shapes
  *
  *  See [standard cursor creation](@ref cursor_standard) for how these are used.

diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
@@ -7,23 +7,29 @@ set(common_SOURCES context.c init.c input.c monitor.c vulkan.c window.c)
 
 if (_GLFW_COCOA)
     set(glfw_HEADERS ${common_HEADERS} cocoa_platform.h cocoa_joystick.h
-                     posix_tls.h)
+                     posix_tls.h nsgl_context.h)
     set(glfw_SOURCES ${common_SOURCES} cocoa_init.m cocoa_joystick.m
-                     cocoa_monitor.m cocoa_window.m cocoa_time.c posix_tls.c)
+                     cocoa_monitor.m cocoa_window.m cocoa_time.c posix_tls.c
+                     nsgl_context.m)
 elseif (_GLFW_WIN32)
-    set(glfw_HEADERS ${common_HEADERS} win32_platform.h win32_joystick.h)
+    set(glfw_HEADERS ${common_HEADERS} win32_platform.h win32_joystick.h
+                     wgl_context.h egl_context.h)
     set(glfw_SOURCES ${common_SOURCES} win32_init.c win32_joystick.c
-                     win32_monitor.c win32_time.c win32_tls.c win32_window.c)
+                     win32_monitor.c win32_time.c win32_tls.c win32_window.c
+                     wgl_context.c egl_context.c)
 elseif (_GLFW_X11)
     set(glfw_HEADERS ${common_HEADERS} x11_platform.h xkb_unicode.h
-                     linux_joystick.h posix_time.h posix_tls.h)
+                     linux_joystick.h posix_time.h posix_tls.h glx_context.h
+                     egl_context.h)
     set(glfw_SOURCES ${common_SOURCES} x11_init.c x11_monitor.c x11_window.c
-                     xkb_unicode.c linux_joystick.c posix_time.c posix_tls.c)
+                     xkb_unicode.c linux_joystick.c posix_time.c posix_tls.c
+                     glx_context.c egl_context.c)
 elseif (_GLFW_WAYLAND)
     set(glfw_HEADERS ${common_HEADERS} wl_platform.h linux_joystick.h
-                     posix_time.h posix_tls.h xkb_unicode.h)
+                     posix_time.h posix_tls.h xkb_unicode.h egl_context.h)
     set(glfw_SOURCES ${common_SOURCES} wl_init.c wl_monitor.c wl_window.c
-                     linux_joystick.c posix_time.c posix_tls.c xkb_unicode.c)
+                     linux_joystick.c posix_time.c posix_tls.c xkb_unicode.c
+                     egl_context.c)
 
     ecm_add_wayland_client_protocol(glfw_SOURCES
         PROTOCOL
@@ -35,23 +41,10 @@ elseif (_GLFW_WAYLAND)
         BASENAME pointer-constraints-unstable-v1)
 elseif (_GLFW_MIR)
     set(glfw_HEADERS ${common_HEADERS} mir_platform.h linux_joystick.h
-                     posix_time.h posix_tls.h xkb_unicode.h)
+                     posix_time.h posix_tls.h xkb_unicode.h egl_context.h)
     set(glfw_SOURCES ${common_SOURCES} mir_init.c mir_monitor.c mir_window.c
-                     linux_joystick.c posix_time.c posix_tls.c xkb_unicode.c)
-endif()
-
-if (_GLFW_EGL)
-    list(APPEND glfw_HEADERS ${common_HEADERS} egl_context.h)
-    list(APPEND glfw_SOURCES ${common_SOURCES} egl_context.c)
-elseif (_GLFW_NSGL)
-    list(APPEND glfw_HEADERS ${common_HEADERS} nsgl_context.h)
-    list(APPEND glfw_SOURCES ${common_SOURCES} nsgl_context.m)
-elseif (_GLFW_WGL)
-    list(APPEND glfw_HEADERS ${common_HEADERS} wgl_context.h)
-    list(APPEND glfw_SOURCES ${common_SOURCES} wgl_context.c)
-elseif (_GLFW_X11)
-    list(APPEND glfw_HEADERS ${common_HEADERS} glx_context.h)
-    list(APPEND glfw_SOURCES ${common_SOURCES} glx_context.c)
+                     linux_joystick.c posix_time.c posix_tls.c xkb_unicode.c
+                     egl_context.c)
 endif()
 
 if (APPLE)

diff --git a/src/cocoa_init.m b/src/cocoa_init.m
@@ -280,10 +280,7 @@ void _glfwPlatformTerminate(void)
 
 const char* _glfwPlatformGetVersionString(void)
 {
-    return _GLFW_VERSION_NUMBER " Cocoa"
-#if defined(_GLFW_NSGL)
-        " NSGL"
-#endif
+    return _GLFW_VERSION_NUMBER " Cocoa NSGL"
 #if defined(_GLFW_USE_CHDIR)
         " chdir"
 #endif

diff --git a/src/cocoa_platform.h b/src/cocoa_platform.h
@@ -41,12 +41,7 @@ typedef void* id;
 
 #include "posix_tls.h"
 #include "cocoa_joystick.h"
-
-#if defined(_GLFW_NSGL)
- #include "nsgl_context.h"
-#else
- #error "The Cocoa backend depends on NSGL platform support"
-#endif
+#include "nsgl_context.h"
 
 #define _glfw_dlopen(name) dlopen(name, RTLD_LAZY | RTLD_LOCAL)
 #define _glfw_dlclose(handle) dlclose(handle)
@@ -58,6 +53,9 @@ typedef void* id;
 #define _GLFW_PLATFORM_MONITOR_STATE        _GLFWmonitorNS ns
 #define _GLFW_PLATFORM_CURSOR_STATE         _GLFWcursorNS  ns
 
+#define _GLFW_EGL_CONTEXT_STATE
+#define _GLFW_EGL_LIBRARY_CONTEXT_STATE
+
 
 // Cocoa-specific per-window data
 //