Add GLFW_COCOA_RETINA_FRAMEBUFFER

Look, a can of worms!  I wonder what's inside.

This adds the first platform specific window hint, transforming
a compile-time option to a run-time per-window one.

CMakeLists.txt

@@ -39,7 +39,6 @@ endif()
 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)
 endif()
 
 if (UNIX AND NOT APPLE)
@@ -355,10 +354,6 @@ if (_GLFW_COCOA)
         set(_GLFW_USE_CHDIR 1)
     endif()
 
-    if (GLFW_USE_RETINA)
-        set(_GLFW_USE_RETINA 1)
-    endif()
-
     list(APPEND glfw_LIBRARIES
         "-framework Cocoa"
         "-framework IOKit"

README.md

@@ -110,6 +110,8 @@ information on what to include when reporting a bug.
 - Added `glfwSetWindowAttrib` function for changing window attributes (#537)
 - Added headless [OSMesa](http://mesa3d.org/osmesa.html) backend (#281,#850)
 - Added definition of `GLAPIENTRY` to public header
+- Added macOS specific `GLFW_COCOA_RETINA_FRAMEBUFFER` window hint
+- Removed `GLFW_USE_RETINA` compile-time option
 - Bugfix: Calling `glfwMaximizeWindow` on a full screen window was not ignored
 - Bugfix: `GLFW_INCLUDE_VULKAN` could not be combined with the corresponding
           OpenGL and OpenGL ES header macros

docs/compile.dox

@@ -229,10 +229,6 @@ directory of bundled applications to the `Contents/Resources` directory.
 __GLFW_USE_MENUBAR__ determines whether the first call to @ref glfwCreateWindow
 sets up a minimal menu bar.
 
-@anchor GLFW_USE_RETINA
-__GLFW_USE_RETINA__ determines whether windows will use the full resolution of
-Retina displays.
-
 
 @subsubsection compile_options_win32 Windows specific CMake options
 
@@ -298,8 +294,6 @@ available:
    application bundle during @ref glfwInit (recommended)
  - @b _GLFW_USE_MENUBAR to create and populate the menu bar when the first window
    is created (recommended)
- - @b _GLFW_USE_RETINA to have windows use the full resolution of Retina displays
-   (recommended)
 
 @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

docs/window.dox

@@ -146,6 +146,11 @@ context.  These hints are set to their default values each time the library is
 initialized with @ref glfwInit, can be set individually with @ref glfwWindowHint
 and reset all at once to their defaults with @ref glfwDefaultWindowHints.
 
+Some hints are platform specific.  These are always valid to set on any
+platform but they will only affect their specific platform.  Other platforms
+will simply ignore them.  Setting these hints requires no platform specific
+headers or calls.
+
 Note that hints need to be set _before_ the creation of the window and context
 you wish to have the specified attributes.
 
@@ -400,6 +405,13 @@ fail on early drivers where this flag is supported without those extensions
 being listed.
 
 
+@subsubsection window_hints_osx macOS specific hints
+
+@anchor GLFW_COCOA_RETINA_FRAMEBUFFER_hint
+__GLFW_COCOA_RETINA_FRAMEBUFFER__ specifies whether to use full resolution
+framebuffers on Retina displays.  This is ignored on other platforms.
+
+
 @subsubsection window_hints_values Supported and default values
 
 Window hint                   | Default value               | Supported values
@@ -436,6 +448,7 @@ GLFW_CONTEXT_RELEASE_BEHAVIOR | `GLFW_ANY_RELEASE_BEHAVIOR` | `GLFW_ANY_RELEASE_
 GLFW_OPENGL_FORWARD_COMPAT    | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
 GLFW_OPENGL_DEBUG_CONTEXT     | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
 GLFW_OPENGL_PROFILE           | `GLFW_OPENGL_ANY_PROFILE`   | `GLFW_OPENGL_ANY_PROFILE`, `GLFW_OPENGL_COMPAT_PROFILE` or `GLFW_OPENGL_CORE_PROFILE`
+GLFW_COCOA_RETINA_FRAMEBUFFER | `GLFW_TRUE`                 | `GLFW_TRUE` or `GLFW_FALSE`
 
 
 @section window_events Window event processing

include/GLFW/glfw3.h

@@ -776,6 +776,8 @@ extern "C" {
 #define GLFW_CONTEXT_NO_ERROR       0x0002200A
 #define GLFW_CONTEXT_CREATION_API   0x0002200B
 
+#define GLFW_COCOA_RETINA_FRAMEBUFFER 0x00023001
+
 #define GLFW_NO_API                          0
 #define GLFW_OPENGL_API             0x00030001
 #define GLFW_OPENGL_ES_API          0x00030002
@@ -1972,9 +1974,10 @@ GLFWAPI void glfwWindowHint(int hint, int value);
  *  [compile-time option](@ref compile_options_osx).
  *
  *  @remark @macos On OS X 10.10 and later the window frame will not be rendered
- *  at full resolution on Retina displays unless the `NSHighResolutionCapable`
- *  key is enabled in the application bundle's `Info.plist`.  For more
- *  information, see
+ *  at full resolution on Retina displays unless the
+ *  [GLFW_COCOA_RETINA_FRAMEBUFFER](@ref GLFW_COCOA_RETINA_FRAMEBUFFER_hint)
+ *  hint is `GLFW_TRUE` and the `NSHighResolutionCapable` key is enabled in the
+ *  application bundle's `Info.plist`.  For more information, see
  *  [High Resolution Guidelines for OS X](https://developer.apple.com/library/mac/documentation/GraphicsAnimation/Conceptual/HighResolutionOSX/Explained/Explained.html)
  *  in the Mac Developer Library.  The GLFW test and example programs use
  *  a custom `Info.plist` template for this, which can be found as

src/cocoa_init.m

@@ -381,9 +381,6 @@ const char* _glfwPlatformGetVersionString(void)
 #if defined(_GLFW_USE_MENUBAR)
         " menubar"
 #endif
-#if defined(_GLFW_USE_RETINA)
-        " retina"
-#endif
 #if defined(_GLFW_BUILD_DLL)
         " dynamic"
 #endif

src/cocoa_window.m

@@ -1038,9 +1038,8 @@ static GLFWbool createNativeWindow(_GLFWwindow* window,
 
     window->ns.view = [[GLFWContentView alloc] initWithGlfwWindow:window];
 
-#if defined(_GLFW_USE_RETINA)
+    if (wndconfig->ns.retina)
         [window->ns.view setWantsBestResolutionOpenGLSurface:YES];
-#endif /*_GLFW_USE_RETINA*/
 
     [window->ns.object setContentView:window->ns.view];
     [window->ns.object makeFirstResponder:window->ns.view];

src/glfw_config.h.in

@@ -62,6 +62,4 @@
 #cmakedefine _GLFW_USE_CHDIR
 // Define this to 1 if glfwCreateWindow should populate the menu bar
 #cmakedefine _GLFW_USE_MENUBAR
-// Define this to 1 if windows should use full resolution on Retina displays
-#cmakedefine _GLFW_USE_RETINA
 

src/internal.h

@@ -264,6 +264,9 @@ struct _GLFWwndconfig
     GLFWbool      autoIconify;
     GLFWbool      floating;
     GLFWbool      maximized;
+    struct {
+        GLFWbool  retina;
+    } ns;
 };
 
 /*! @brief Context configuration.

src/window.c

@@ -266,6 +266,9 @@ void glfwDefaultWindowHints(void)
 
     // The default is to select the highest available refresh rate
     _glfw.hints.refreshRate = GLFW_DONT_CARE;
+
+    // The default is to use full Retina resolution framebuffers
+    _glfw.hints.window.ns.retina = GLFW_TRUE;
 }
 
 GLFWAPI void glfwWindowHint(int hint, int value)
@@ -340,6 +343,9 @@ GLFWAPI void glfwWindowHint(int hint, int value)
         case GLFW_VISIBLE:
             _glfw.hints.window.visible = value ? GLFW_TRUE : GLFW_FALSE;
             break;
+        case GLFW_COCOA_RETINA_FRAMEBUFFER:
+            _glfw.hints.window.ns.retina = value ? GLFW_TRUE : GLFW_FALSE;
+            break;
         case GLFW_CLIENT_API:
             _glfw.hints.context.client = value;
             break;