Document QGLCompat headers and ViewerGL update

Gui/QGLExtrasCompat.h

@@ -17,11 +17,23 @@
  * along with Natron.  If not, see <http://www.gnu.org/licenses/gpl-2.0.html>
  * ***** END LICENSE BLOCK ***** */
 
+// This is a header that provides type declarations that map a subset of the newer QOpenGL
+// classes used by Natron with their older QGL counterparts
+
 #ifndef NATRON_GUI_QGLEXTRASCOMPAT_H
 #define NATRON_GUI_QGLEXTRASCOMPAT_H
 
-#include <QGLShaderProgram>
-#include <QGLShader>
+#if QT_VERSION >= QT_VERSION_CHECK(5, 4, 0)
+#error "This file must not be included while using Qt >= 5.4.0"
+#endif
+
+#include "Global/Macros.h"
+
+// QGL was deprecated in macOS
+CLANG_DIAG_OFF(deprecated)
+#include <QtOpenGL/QGLShaderProgram>
+#include <QtOpenGL/QGLShader>
+CLANG_DIAG_ON(deprecated)
 
 typedef QGLShaderProgram QOpenGLShaderProgram;
 typedef QSharedPointer<QGLShaderProgram> QOpenGLShaderProgramPtr;

Gui/QGLWidgetCompat.h

@@ -17,10 +17,21 @@
  * along with Natron.  If not, see <http://www.gnu.org/licenses/gpl-2.0.html>
  * ***** END LICENSE BLOCK ***** */
 
+// This is a header that provides type declarations that map a subset of the newer QOpenGL
+// classes used by Natron with their older QGL counterparts
+
 #ifndef NATRON_GUI_QGLWIDGETCOMPAT_H
 #define NATRON_GUI_QGLWIDGETCOMPAT_H
 
-#include <QGLWidget>
+#if QT_VERSION >= QT_VERSION_CHECK(5, 4, 0)
+#error "This file must not be included while using Qt >= 5.4.0"
+#endif
+
+#include "Global/Macros.h"
+
+CLANG_DIAG_OFF(deprecated)
+#include <QtOpenGL/QGLWidget>
+CLANG_DIAG_ON(deprecated)
 
 typedef QGLWidget QOpenGLWidget;
 typedef QGLContext QOpenGLContext;

Gui/ViewerGL.cpp

@@ -3632,6 +3632,7 @@ ViewerGL::swapOpenGLBuffers()
     // always running in the main thread
     assert( qApp && qApp->thread() == QThread::currentThread() );
 #if QT_VERSION >= QT_VERSION_CHECK(5, 4, 0)
+    // calls glSwapBuffers in the widget stack as described in https://doc.qt.io/qt-5/qopenglwidget.html#threading
     update();
 #else
     swapBuffers();