From 40e6fe780150161bb608f5df356bfe4f00861be5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tor=20Arne=20Vestb=C3=B8?= <tor.arne.vestbo@qt.io>
Date: Wed, 14 Oct 2020 12:20:38 +0200
Subject: doc: Update and flesh out native interface docs

The namespace and overviews are in the qtdoc repository.

Docs for individual interfaces should live with their platform.

Change-Id: Iba5fd7e9ebc4f1f634ec9dc3ec125ce88a1312ba
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
---
 src/gui/platform/unix/qunixnativeinterface.cpp | 108 ++++++++++++++++++++++++-
 1 file changed, 104 insertions(+), 4 deletions(-)

(limited to 'src/gui/platform/unix')

diff --git a/src/gui/platform/unix/qunixnativeinterface.cpp b/src/gui/platform/unix/qunixnativeinterface.cpp
index 378282936e..43184daa12 100644
--- a/src/gui/platform/unix/qunixnativeinterface.cpp
+++ b/src/gui/platform/unix/qunixnativeinterface.cpp
@@ -56,6 +56,46 @@ using namespace QNativeInterface::Private;
 #ifndef QT_NO_OPENGL
 
 #if defined(Q_OS_LINUX)
+
+/*!
+    \class QNativeInterface::QGLXContext
+    \since 6.0
+    \brief Native interface to a GLX context.
+
+    Accessed through QOpenGLContext::nativeInterface().
+
+    \inmodule QtGui
+    \ingroup native-interfaces
+    \ingroup native-interfaces-qopenglcontext
+*/
+
+/*!
+    \fn QOpenGLContext *QNativeInterface::QGLXContext::fromNative(GLXContext configBasedContext, QOpenGLContext *shareContext = nullptr)
+
+    \brief Adopts a GLXContext created from an FBConfig.
+
+    The context must be created from a framebuffer configuration, using the \c glXCreateNewContext function.
+
+    Ownership of the created QOpenGLContext is transferred to the caller.
+*/
+
+/*!
+    \fn QOpenGLContext *QNativeInterface::QGLXContext::fromNative(GLXContext visualBasedContext, void *visualInfo, QOpenGLContext *shareContext = nullptr)
+
+    \brief Adopts a GLXContext created from an X visual.
+
+    The context must be created from a visual, using the \c glXCreateContext function.
+    The same visual must be passed as a pointer to an \c XVisualInfo struct, in the \a visualInfo argument.
+
+    Ownership of the created QOpenGLContext is transferred to the caller.
+*/
+
+/*!
+    \fn GLXContext QNativeInterface::QGLXContext::nativeContext() const
+
+    \return the underlying GLXContext.
+*/
+
 QT_DEFINE_NATIVE_INTERFACE(QGLXContext, QOpenGLContext);
 QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QGLXIntegration);
 
@@ -70,9 +110,38 @@ QOpenGLContext *QNativeInterface::QGLXContext::fromNative(GLXContext visualBased
     return QGuiApplicationPrivate::platformIntegration()->call<
         &QGLXIntegration::createOpenGLContext>(visualBasedContext, visualInfo, shareContext);
 }
-#endif
+#endif // defined(Q_OS_LINUX)
 
 #if QT_CONFIG(egl)
+
+/*!
+    \class QNativeInterface::QEGLContext
+    \since 6.0
+    \brief Native interface to an EGL context.
+
+    Accessed through QOpenGLContext::nativeInterface().
+
+    \inmodule QtGui
+    \ingroup native-interfaces
+    \ingroup native-interfaces-qopenglcontext
+*/
+
+/*!
+    \fn QOpenGLContext *QNativeInterface::QEGLContext::fromNative(EGLContext context, EGLDisplay display, QOpenGLContext *shareContext = nullptr)
+
+    \brief Adopts an EGLContext.
+
+    The same \c EGLDisplay passed to \c eglCreateContext must be passed as the \a display argument.
+
+    Ownership of the created QOpenGLContext is transferred to the caller.
+*/
+
+/*!
+    \fn EGLContext QNativeInterface::QEGLContext::nativeContext() const
+
+    \return the underlying EGLContext.
+*/
+
 QT_DEFINE_NATIVE_INTERFACE(QEGLContext, QOpenGLContext);
 QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QEGLIntegration);
 
@@ -81,20 +150,51 @@ QOpenGLContext *QNativeInterface::QEGLContext::fromNative(EGLContext context, EG
     return QGuiApplicationPrivate::platformIntegration()->call<
         &QEGLIntegration::createOpenGLContext>(context, display, shareContext);
 }
-#endif
+#endif // QT_CONFIG(egl)
 
 #endif // QT_NO_OPENGL
 
 #if QT_CONFIG(xcb)
+
+/*!
+    \class QNativeInterface::Private::QXcbScreen
+    \since 6.0
+    \internal
+    \brief Native interface to QPlatformScreen.
+    \inmodule QtGui
+    \ingroup native-interfaces
+*/
+
 QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QXcbScreen);
+
+/*!
+    \class QNativeInterface::Private::QXcbWindow
+    \since 6.0
+    \internal
+    \brief Native interface to QPlatformWindow.
+    \inmodule QtGui
+    \ingroup native-interfaces
+*/
+
 QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QXcbWindow);
-#endif
+
+#endif // QT_CONFIG(xcb)
 
 #if QT_CONFIG(vsp2)
 QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QVsp2Screen);
 #endif
 
 #if QT_CONFIG(evdev)
+
+/*!
+    \class QNativeInterface::Private::QEvdevKeyMapper
+    \since 6.0
+    \internal
+    \brief Native interface to QKeyMapper.
+    \inmodule QtGui
+    \ingroup native-interfaces
+*/
+
 QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QEvdevKeyMapper);
 
 template <>
@@ -102,6 +202,6 @@ QEvdevKeyMapper *QKeyMapper::nativeInterface<QEvdevKeyMapper>() const
 {
     return dynamic_cast<QEvdevKeyMapper*>(QGuiApplicationPrivate::platformIntegration());
 }
-#endif
+#endif // QT_CONFIG(evdev)
 
 QT_END_NAMESPACE
-- 
cgit v1.2.3