Doxygen: describe better support for OpenGL on HighDPI displays.

4 files changed, 35 insertions, 14 deletions

diff --git a/FL/Fl_Gl_Window.H b/FL/Fl_Gl_Window.H
index 48b7d39b0..f7574496a 100644
--- a/FL/Fl_Gl_Window.H
+++ b/FL/Fl_Gl_Window.H
@@ -208,17 +208,21 @@ public:
   
   float pixels_per_unit();
   /** Gives the window width in OpenGL pixels.
-   Generally identical with the result of the w() function, but for a window mapped to
-   an Apple 'retina' display, and if Fl::use_high_res_GL(bool) is set to true,
-   pixel_w() returns 2 * w(). This method detects when the window has been moved
+   When an Fl_Gl_Window is mapped to a HighDPI display, the value given by Fl_Gl_Window::w()
+   which is expressed in FLTK units, may differ from the window width in pixels.
+   Calls to OpenGL functions expecting pixel values (e.g., glViewport) must therefore
+   use this method rather than method w().
+   This method detects when the GUI is rescaled or when the window has been moved
    between low and high resolution displays and automatically adjusts the returned value.
    \version 1.3.4
    */
   int pixel_w() { return int(pixels_per_unit() * w() + 0.5f); }
   /** Gives the window height in OpenGL pixels.
-   Generally identical with the result of the h() function, but for a window mapped to
-   an Apple 'retina' display, and if Fl::use_high_res_GL(bool) is set to true,
-   pixel_h() returns 2 * h(). This method detects when the window has been moved
+   When an Fl_Gl_Window is mapped to a HighDPI display, the value given by Fl_Gl_Window::h()
+   which is expressed in FLTK units, may differ from the window height in pixels.
+   Calls to OpenGL functions expecting pixel values (e.g., glViewport) must therefore
+   use this method rather than method h().
+   This method detects when the GUI is rescaled or when the window has been moved
    between low and high resolution displays and automatically adjusts the returned value.
    \version 1.3.4
    */
diff --git a/documentation/src/opengl.dox b/documentation/src/opengl.dox
index 91983f0c9..b0c6b3d65 100644
--- a/documentation/src/opengl.dox
+++ b/documentation/src/opengl.dox
@@ -25,9 +25,9 @@ the file \p <GL/gl.h> (on macOS: \p <OpenGL/gl.h>), define
 some extra drawing functions provided by FLTK, and include the
 \p <windows.h> header file needed by Windows applications.
 
-Some simple coding rules (see \ref osissues_retina) allow to write
-cross-platform code that will draw high resolution
-OpenGL graphics if run on 'retina' displays with MacOS.
+Some simple coding rules (see \ref opengl_highdpi) allow to write
+cross-platform code that will support OpenGL run on HighDPI displays
+(including the 'retina' displays of Apple hardware).
 
 \section opengl_subclass Making a Subclass of Fl_Gl_Window
 
@@ -179,6 +179,24 @@ You must put <tt>glwindow->show()</tt> in your main code
 after calling \p show() on the window containing the
 OpenGL window.
 
+\section opengl_highdpi  OpenGL and support of HighDPI displays
+
+HighDPI displays (including the so-called 'retina' displays of Apple
+hardware) are supported by FLTK in such a way that 1 unit of an FLTK
+quantity (say, the value given by Fl_Gl_Window::w()) corresponds to more
+than 1 pixel on the display. Conversely, when a program specifies the width and height of the
+OpenGL viewport, it is necessary to use an API that returns quantities expressed in pixels
+as follows:
+\code
+  Fl_Gl_Window *glw = ...;
+  glViewport(0, 0, glw->pixel_w(), glw->pixel_h());
+\endcode
+which makes use of the Fl_Gl_Window::pixel_w() and Fl_Gl_Window::pixel_h() functions giving
+the size in pixels of an Fl_Gl_Window that is potentially mapped to a HighDPI display.
+Method Fl_Gl_Window::pixels_per_unit() can also be useful in this context.
+\note A further coding rule is necessary to properly support retina displays
+and OpenGL under macOS (see \ref osissues_retina)
+
 \section opengl_normal Using OpenGL in Normal FLTK Windows
 
 You can put OpenGL code into the \p draw() method, as described in
diff --git a/documentation/src/osissues.dox b/documentation/src/osissues.dox
index 790899765..86b05b9c0 100644
--- a/documentation/src/osissues.dox
+++ b/documentation/src/osissues.dox
@@ -857,7 +857,8 @@ the GL scene in pixels: if the Fl_Gl_Window is mapped on a retina display, these
 reported by Fl_Widget::w() and Fl_Widget::h(); if it's mapped on a regular display, they return the same values
 as w() and h(). These methods dynamically change their values if the window is moved into/out from a retina
 display. If Fl::use_high_res_GL(1) is not called, all Fl_Gl_Window 's are drawn at low resolution.
-These methods are synonyms of w() and h() on non-Mac OS X platforms, so the source code remains cross-platform.
+These methods are useful on all platforms because Fl_Gl_Window::w() and Fl_Gl_Window::h() don't return,
+on HighDPI displays, the quantitites in pixels necessary to OpenGL functions .
 
 The Fl_Gl_Window::pixels_per_unit() method is useful when the OpenGL code depends on the pixel dimension
 of the GL scene. This occurs, e.g., if a window's handle() method uses Fl::event_x() and Fl::event_y()
diff --git a/src/Fl_Gl_Window.cxx b/src/Fl_Gl_Window.cxx
index 9bb09c0cd..be0c95a5a 100644
--- a/src/Fl_Gl_Window.cxx
+++ b/src/Fl_Gl_Window.cxx
@@ -439,10 +439,8 @@ int Fl_Gl_Window::gl_plugin_linkage() {
 }
 
 /** The number of pixels per FLTK unit of length for the window.
- Returns 1, except for a window mapped to
- an Apple 'retina' display, and if Fl::use_high_res_GL(bool) is set to true,
- when it returns 2. This method dynamically adjusts its value when the window
- is moved to/from a retina display. This method is useful, e.g., to convert,
+ This method dynamically adjusts its value when the GUI is rescaled or when the window
+ is moved to/from displays of distinct resolutions. This method is useful, e.g., to convert,
  in a window's handle() method, the FLTK units returned by Fl::event_x() and
  Fl::event_y() to the pixel units used by the OpenGL source code.
  \version 1.3.4