// Copyright (C) 2020 The Qt Company Ltd
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page platform-integration.html
    \title Platform Integration
    \brief Integrating Qt with the native platform.

    Qt's main strength as a cross-platform toolkit for application development
    is removing the need for duplicating the application code for each target
    platform.

    While Qt solves many of the typical tasks of writing an application,
    there are always corner cases that Qt can not cover, or where it makes more
    sense to build a feature on top of the platform specific APIs, or another
    toolkit.

    To support these use-cases, while still allowing Qt to handle the bulk of
    the application logic, Qt provides a wide range of platform integration
    APIs, from simple type conversions to platform specific native interfaces.

    \section1 Type Conversions

    \include platformintegration.qdocinc type-conversions

    For example, to get the current user's username on Apple platforms:

    \code
        NSProcessInfo *processInfo = NSProcessInfo.processInfo;
        QString userName = QString::fromNSString(processInfo.userName)
    \endcode

    For a complete list of all type conversions, see the \l{Type Conversions} overview.

    \section1 Window Embedding

    Windows created by the underlying platform APIs may be used as both
    parent containers for Qt windows, or embedded into Qt windows as child
    windows.

    The former is useful if the application is mainly written using the native
    platform APIs, but where parts of the application uses Qt, for example
    to draw a specialized UI. To embed Qt into the window hierarchy of the
    native application, use QWindow::winId() to get the native handle for
    the Qt window, and then use the native APIs to re-parent the window
    into the native UI.

    The latter is useful if the native platform, or another toolkit, exposes
    a specialized control as a native window. By using QWindow::fromWinId()
    to wrap the native window handle in a QWindow, the window can then be
    re-parented into the Qt window hierarchy as any other QWindow. To re-parent
    this QWindow into a Qt Widget based UI, use the widgets-specific
    QWidget::createWindowContainer() function.

    \section1 Event Handling

    Most event handling use-cases in Qt are sufficiently covered by the cross
    platform event delivery, via QWindow::event() and friends, or through
    QObject::installEventFilter().

    In cases where this is not enough, Qt provides access to the delivery of the
    native events. A global event filter that receives all native events can be
    installed by using QCoreApplication::installNativeEventFilter(), while
    per-window native events can be handled in QWindow::nativeEvent().

    \note Interfering with the native event flow may put Qt in an inconsistent
    state. These APIs should primarily be used to augment Qt's existing
    event handling, for example for events Qt doesn't handle yet.

    \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
    platform when providing the underlying implementations of the cross-platform
    building blocks in Qt.

    Examples are the event dispatcher abstractions in \l{Qt Core} and the rendering
    hardware abstractions in RHI.

    The main abstraction layer here is the \l{Qt Platform Abstraction},
    or QPA for short, which deals with window system integration and related use-cases.
*/

/*!
    \group platform-type-conversions
    \title Type Conversions

    \include platformintegration.qdocinc type-conversions

    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

    \section2 QSGTexture

    Accessed through QSGTexture::nativeInterface().

    \annotatedlist native-interfaces-qsgtexture

    \noautolist
*/

/*!
    \namespace QNativeInterface
    \inmodule QtPlatformIntegration
    \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
    \since 6.0

    \brief Contains the available private native interfaces.
*/
