// 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.
    \ingroup explanations-platforms

    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 Integrating with other UI toolkits

    \include platformintegration.qdocinc mixing-qt-with-other-ui-toolkits-intro

    See \l{Mixing Qt with other UI toolkits} for a deep-dive into how Qt supports
    these two use-cases.

    \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

    In some situations 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.
*/
