Add a section about QOpenGLWidget alternatives

QOpenGLWindow with createWindowContainer() can be an option
for desktop-only apps in some special cases. Document this.

Task-number: QTBUG-45192
Change-Id: I7c59b7d04d6c0fe58ffe93ac72b204103bef2f4c
Reviewed-by: Gunnar Sletta <gunnar@sletta.org>

src/widgets/kernel/qopenglwidget.cpp

@@ -435,6 +435,23 @@ QT_BEGIN_NAMESPACE
   each frame. To restore the preserved behavior, call setUpdateBehavior() with
   \c PartialUpdate.
 
+  \section1 Alternatives
+
+  Adding a QOpenGLWidget into a window turns on OpenGL-based
+  compositing for the entire window.  In some special cases this may
+  not be ideal, and the old QGLWidget-style behavior with a separate,
+  native child window is desired. Desktop applications that understand
+  the limitations of this approach (for example when it comes to
+  overlaps, transparency, scroll views and MDI areas), can use
+  QOpenGLWindow with QWidget::createWindowContainer(). This is a
+  modern alternative to QGLWidget and is faster than QOpenGLWidget due
+  to the lack of the additional composition step. It is strongly
+  recommended to limit the usage of this approach to cases where there
+  is no other choice. Note that this option is not suitable for most
+  embedded and mobile platforms, and it is known to have issues on
+  certain desktop platforms (e.g. OS X) too. The stable,
+  cross-platform solution is always QOpenGLWidget.
+
   \e{OpenGL is a trademark of Silicon Graphics, Inc. in the United States and other
   countries.}