Add native interface overview documentation

Change-Id: Id3474406e289c0f336d60ba3b715344c869439b3
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

4 files changed, 145 insertions, 1 deletions

diff --git a/doc/src/platformintegration/platformintegration.h b/doc/src/platformintegration/platformintegration.h
new file mode 100644
index 00000000..3ce5b69c
--- /dev/null
+++ b/doc/src/platformintegration/platformintegration.h
@@ -0,0 +1,3 @@
+
+namespace QNativeInterface {}
+namespace QNativeInterface::Private {}
diff --git a/doc/src/platformintegration/platformintegration.qdoc b/doc/src/platformintegration/platformintegration.qdoc
index 7ae5aa06..17d7a2fa 100644
--- a/doc/src/platformintegration/platformintegration.qdoc
+++ b/doc/src/platformintegration/platformintegration.qdoc
@@ -93,6 +93,19 @@
 
     \section1 Native Interfaces
 
+    Platform specific functionality not covered by the APIs mentioned above
+    are handled by the more generic \l{Native Interfaces}{native interface}
+    mechanism in Qt. The interfaces provide access to native or platform
+    specific APIs of the classes they extend.
+
+    \include platformintegration.qdocinc native-interface-blurb
+
+    \include platformintegration.qdocinc native-interface-handle-access-example
+
+    For a complete list of all native interfaces, see the \l{Native Interfaces} overview.
+
+    \warning \include platformintegration.qdocinc native-interface-compat-warning
+
     \section1 Platform Support
 
     In addition to the application developer APIs, Qt also interfaces with the
@@ -114,3 +127,107 @@
 
     The following list enumerates all of the available type conversions:
 */
+
+/*!
+    \group native-interfaces
+    \title Native Interfaces
+
+    The native interfaces provide access to native or platform specific APIs of
+    the classes they extend.
+
+    \include platformintegration.qdocinc native-interface-blurb
+
+    \section1 Example Usage
+
+    \section2 Accessing underlying native handles
+
+    In situations where a feature of the native platform is not exposed in Qt,
+    it can be helpful to access the native handles maintained by Qt, and use
+    those to call the native APIs instead.
+
+    \include platformintegration.qdocinc native-interface-handle-access-example
+
+    The native interface is accessed through the QOpenGLContext::nativeInterface()
+    accessor, which ensures that the requested interface is available, and otherwise
+    returns \nullptr. The underlying NSOpenGLContext is then accessed through the
+    \l{QNativeInterface::QCocoaGLContext::nativeContext()}{nativeContext()} accessor.
+
+    \section2 Adopting existing native handles
+
+    Similarly to the \l{Window Embedding}{window embedding} use-case, there are
+    situations where the native platform, or another toolkit, has created a native
+    handle that you would like to pass on to Qt \mdash wrapping the existing handle
+    instead of creating a new one.
+
+    For example, to adopt an existing NSOpenGLContext, and use that to share
+    resources with a context created by Qt:
+
+    \code
+        using namespace QNativeInterface;
+        QOpenGLContext *adoptedContext = QCocoaGLContext::fromNativeContext(nsOpenGLContext);
+        anotherContext->setShareContext(adoptedContext);
+    \endcode
+
+    The adopted context is created by a platform specific factory function
+    in the QNativeInterface::QCocoaGLContext native interface.
+
+    \section2 Accessing platform specific APIs
+
+    In some cases an API is too platform specific to be included in the cross platform
+    Qt classes, but is still useful to include. These APIs are available either in the
+    same way as when accessing the underlying native handles, through the
+    \l{QOpenGLContext::nativeInterface()}{nativeInterface()} accessor, or directly
+    as static function in the native interface.
+
+    For example, to pull out the OpenGL module handle on Windows:
+
+    \code
+        using namespace QNativeInterface;
+        HMODULE moduleHandle = QWGLContext::openGLModuleHandle();
+    \endcode
+
+    \section1 Source and Binary Compatibility
+
+    \include platformintegration.qdocinc native-interface-compat-warning
+
+    \section1 Available Interfaces
+
+    For a list of all available interfaces, see the QNativeInterface namespace.
+
+    \section2 QOpenGLContext
+
+    Accessed through QOpenGLContext::nativeInterface().
+
+    \annotatedlist native-interfaces-qopenglcontext
+
+    \section2 QOffscreenSurface
+
+    Accessed through QOffscreenSurface::nativeInterface().
+
+    \annotatedlist native-interfaces-qoffscreensurface
+
+    \noautolist
+*/
+
+/*!
+    \namespace QNativeInterface
+    \inmodule QtPlatformIntegration
+    \inheaderfile
+    \since 6.0
+
+    \brief Contains the available native interfaces.
+
+    For documentation on how to use these interfaces, see the \l{Native Interfaces} overview.
+
+    \warning \include platformintegration.qdocinc native-interface-compat-warning
+*/
+
+/*!
+    \namespace QNativeInterface::Private
+    \inmodule QtPlatformIntegration
+    \internal
+    \inheaderfile
+    \since 6.0
+
+    \brief Contains the available private native interfaces.
+*/
diff --git a/doc/src/platformintegration/platformintegration.qdocinc b/doc/src/platformintegration/platformintegration.qdocinc
index e394ad50..6a7a9558 100644
--- a/doc/src/platformintegration/platformintegration.qdocinc
+++ b/doc/src/platformintegration/platformintegration.qdocinc
@@ -32,4 +32,28 @@ Many of Qt's basic data types, such as QString, QPoint, or QImage, provide
 conversions to and from the native equivalent types.
 //! [type-conversions]
 
+//! [native-interface-compat-warning]
+There are no source or binary compatibility guarantees for the
+native interface APIs, meaning that an application using these
+interfaces is only guaranteed to work with the Qt version it was
+developed against.
+//! [native-interface-compat-warning]
+
+//! [native-interface-blurb]
+The interfaces live in the QNativeInterface namespace, and cover use-cases
+such as accessing underlying native handles, adopting existing native
+handles, or providing platform specific APIs.
+//! [native-interface-blurb]
+
+//! [native-interface-handle-access-example]
+For example, to access the underlying NSOpenGLContext of an QOpenGLContext
+on \macos, via the QNativeInterface::QCocoaGLContext native interface:
+
+\code
+    using namespace QNativeInterface;
+    if (auto *cocoaGLContext = glContext->nativeInterface<QCocoaGLContext>())
+        [cocoaGLContext->nativeContext() makeCurrentContext];
+\endcode
+//! [native-interface-handle-access-example]
+
 */
diff --git a/doc/src/platformintegration/qtplatformintegration.qdocconf b/doc/src/platformintegration/qtplatformintegration.qdocconf
index 71744da4..cab6bbf5 100644
--- a/doc/src/platformintegration/qtplatformintegration.qdocconf
+++ b/doc/src/platformintegration/qtplatformintegration.qdocconf
@@ -10,7 +10,7 @@ depends += qtcore qtgui qtwidgets qtquick qtdoc
 sourcedirs = .
 headerdirs = .
 
-moduleheader =
+moduleheader = platformintegration.h
 
 qhp.projects = QtPlatformIntegration