Add public and QPA APIs for adapting existing OpenGL contexts

For now only xcb on GLX is supported. Other platforms will follow later.

Add also some missing documentation for the platform OpenGL context factory
functions.

[ChangeLog] QOpenGLContext is now able to adopt existing native contexts.

Task-number: QTBUG-37552
Change-Id: I5dd959f102df178f646b2df5989203b5dc6de376
Reviewed-by: Jørgen Lind <jorgen.lind@digia.com>

1 files changed, 20 insertions, 1 deletions

diff --git a/src/gui/kernel/qplatformintegration.cpp b/src/gui/kernel/qplatformintegration.cpp
index a6e0d4705b..432199f142 100644
--- a/src/gui/kernel/qplatformintegration.cpp
+++ b/src/gui/kernel/qplatformintegration.cpp
@@ -271,13 +271,32 @@ QPlatformPixmap *QPlatformIntegration::createPlatformPixmap(QPlatformPixmap::Pix
 }
 
 #ifndef QT_NO_OPENGL
+/*!
+    Factory function for QPlatformOpenGLContext. The \a context parameter is a pointer to
+    the context for which a platform-specific context backend needs to be
+    created. Configuration settings like the format, share context and screen have to be
+    taken from this QOpenGLContext and the resulting platform context is expected to be
+    backed by a native context that fulfills these criteria.
+
+    If the context has native handles set, no new native context is expected to be created.
+    Instead, the provided handles have to be used. In this case the ownership of the handle
+    must not be taken and the platform implementation is not allowed to destroy the native
+    context. Configuration parameters like the format are also to be ignored. Instead, the
+    platform implementation is responsible for querying the configuriation from the provided
+    native context.
+
+    Returns a pointer to a QPlatformOpenGLContext instance or \c NULL if the context could
+    not be created.
+
+    \sa QOpenGLContext
+*/
 QPlatformOpenGLContext *QPlatformIntegration::createPlatformOpenGLContext(QOpenGLContext *context) const
 {
     Q_UNUSED(context);
     qWarning("This plugin does not support createPlatformOpenGLContext!");
     return 0;
 }
-#endif
+#endif // QT_NO_OPENGL
 
 /*!
    Factory function for QPlatformSharedGraphicsCache. This function will return 0 if the platform