Introduce platform API abstraction for QOpenGLContext

The API is available by including qopenglcontext.h as usual,
but scoped in the QPlatformInterface namespace. The namespace
exposes platform specific type-safe interfaces that provide:

 a) Factory functions for adopting native contexts, e.g.

    QCocoaGLContext::fromNative(nsContext, shareContext);

 b) Access to underlying native handles, e.g.

    openGLContext->platformInterface<QCocoaGLContext>->nativeContext()

 c) Platform specific functionality, e.g.

    static QWGLContext::openGLModuleHandle()

    openGLContext->platformInterface<QEGLContext>->doSomething();

The platform interfaces live close to the classes they extend,
removing the need for complex indirection and plumbing, and
avoids kitchen-sink modules and APIs such as the extras modules,
QPlatformFunctions, or QPlatformNativeInterface.

In the case of QOpenGLContext these platform APIs are backed
by the platform plugin, so dynamic_cast is used to ensure the
platform plugin supports the requested interface, but this is
and implementation detail. The interface APIs are agnostic
to where the implementation lives, while still being available
to the user as part of the APIs they extend/augment.

The documentation will be restored when the dust settles.

Task-number: QTBUG-80233
Change-Id: Iac612403383991c4b24064332542a6e4bcbb3293
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>

1 files changed, 25 insertions, 92 deletions

diff --git a/src/gui/kernel/qopenglcontext.cpp b/src/gui/kernel/qopenglcontext.cpp
index 5c6d082f98..51bf5cf336 100644
--- a/src/gui/kernel/qopenglcontext.cpp
+++ b/src/gui/kernel/qopenglcontext.cpp
@@ -347,63 +347,15 @@ void QOpenGLContextPrivate::_q_screenDestroyed(QObject *object)
 }
 
 /*!
-    Set the native handles for this context. When create() is called and a
-    native handle is set, configuration settings, like format(), are ignored
-    since this QOpenGLContext will wrap an already created native context
-    instead of creating a new one from scratch.
-
-    On some platforms the native context handle is not sufficient and other
-    related handles (for example, for a window or display) have to be provided
-    in addition. Therefore \a handle is variant containing a platform-specific
-    value type. These classes can be found in the QtPlatformHeaders module.
-
-    When create() is called with native handles set, QOpenGLContext does not
-    take ownership of the handles, so destroying the QOpenGLContext does not
-    destroy the native context.
-
-    \note Some frameworks track the current context and surfaces internally.
-    Making the adopted QOpenGLContext current via Qt will have no effect on such
-    other frameworks' internal state. Therefore a subsequent makeCurrent done
-    via the other framework may have no effect. It is therefore advisable to
-    make explicit calls to make no context and surface current to reset the
-    other frameworks' internal state after performing OpenGL operations via Qt.
-
-    \note Using foreign contexts with Qt windows and Qt contexts with windows
-    and surfaces created by other frameworks may give unexpected results,
-    depending on the platform, due to potential mismatches in context and window
-    pixel formats. To make sure this does not happen, avoid making contexts and
-    surfaces from different frameworks current together. Instead, prefer
-    approaches based on context sharing where OpenGL resources like textures are
-    accessible both from Qt's and the foreign framework's contexts.
-
-    \since 5.4
-    \sa nativeHandle()
-*/
-void QOpenGLContext::setNativeHandle(const QVariant &handle)
-{
-    Q_D(QOpenGLContext);
-    d->nativeHandle = handle;
-}
+    \fn T QOpenGLContext::platformInterface<T>()
 
-/*!
-    Returns the native handle for the context.
+    Returns a platform interface of type T for the context.
 
-    This function provides access to the QOpenGLContext's underlying native
-    context. The returned variant contains a platform-specific value type. These
-    classes can be found in the module QtPlatformHeaders.
+    This function provides access to platform specific functionality
+    of QOpenGLContext, as defined in the QPlatformInterface namespace.
 
-    On platforms where retrieving the native handle is not supported, or if
-    neither create() nor setNativeHandle() was called, a null variant is
-    returned.
-
-    \since 5.4
-    \sa setNativeHandle()
+    If the requested interface is not available a \nullptr is returned.
  */
-QVariant QOpenGLContext::nativeHandle() const
-{
-    Q_D(const QOpenGLContext);
-    return d->nativeHandle;
-}
 
 /*!
     Attempts to create the OpenGL context with the current configuration.
@@ -433,18 +385,29 @@ bool QOpenGLContext::create()
     if (d->platformGLContext)
         destroy();
 
-    d->platformGLContext = QGuiApplicationPrivate::platformIntegration()->createPlatformOpenGLContext(this);
-    if (!d->platformGLContext)
+    auto *platformContext = QGuiApplicationPrivate::platformIntegration()->createPlatformOpenGLContext(this);
+    if (!platformContext)
         return false;
-    d->platformGLContext->setContext(this);
-    d->platformGLContext->initialize();
-    if (!d->platformGLContext->isSharing())
-        d->shareContext = nullptr;
-    d->shareGroup = d->shareContext ? d->shareContext->shareGroup() : new QOpenGLContextGroup;
-    d->shareGroup->d_func()->addContext(this);
+
+    d->adopt(platformContext);
+
     return isValid();
 }
 
+void QOpenGLContextPrivate::adopt(QPlatformOpenGLContext *context)
+{
+    Q_Q(QOpenGLContext);
+
+    platformGLContext = context;
+    platformGLContext->setContext(q);
+    platformGLContext->initialize();
+
+    if (!platformGLContext->isSharing())
+        shareContext = nullptr;
+    shareGroup = shareContext ? shareContext->shareGroup() : new QOpenGLContextGroup;
+    shareGroup->d_func()->addContext(q);
+}
+
 /*!
     \internal
 
@@ -490,8 +453,6 @@ void QOpenGLContext::destroy()
         d->vaoHelperDestroyCallback = nullptr;
     }
     d->vaoHelper = nullptr;
-
-    d->nativeHandle = QVariant();
 }
 
 /*!
@@ -915,33 +876,6 @@ QScreen *QOpenGLContext::screen() const
 }
 
 /*!
-  Returns the platform-specific handle for the OpenGL implementation that
-  is currently in use. (for example, a HMODULE on Windows)
-
-  On platforms that do not use dynamic GL switching, the return value
-  is \nullptr.
-
-  The library might be GL-only, meaning that windowing system interface
-  functions (for example EGL) may live in another, separate library.
-
-  \note This function requires that the QGuiApplication instance is already created.
-
-  \sa openGLModuleType()
-
-  \since 5.3
- */
-void *QOpenGLContext::openGLModuleHandle()
-{
-#ifdef QT_OPENGL_DYNAMIC
-    QPlatformNativeInterface *ni = QGuiApplication::platformNativeInterface();
-    Q_ASSERT(ni);
-    return ni->nativeResourceForIntegration(QByteArrayLiteral("glhandle"));
-#else
-    return nullptr;
-#endif
-}
-
-/*!
   \enum QOpenGLContext::OpenGLModuleType
   This enum defines the type of the underlying OpenGL implementation.
 
@@ -1350,8 +1284,7 @@ QDebug operator<<(QDebug debug, const QOpenGLContext *ctx)
     if (ctx)  {
         debug << static_cast<const void *>(ctx);
         if (ctx->isValid()) {
-            debug << ", nativeHandle=" << ctx->nativeHandle()
-                << ", format=" << ctx->format();
+            debug << ", format=" << ctx->format();
             if (const QSurface *sf = ctx->surface())
                 debug << ", surface=" << sf;
             if (const QScreen *s = ctx->screen())