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

/*!
    \title QQuickWidget - QQuickView Comparison Example
    \example quickwidgets/qquickwidgetversuswindow_opengl
    \brief Demonstrates the benefits of QQuickWidget over a QQuickView embedded as a native window.
    \examplecategory {User Interface Components}
    \image qquickwidgetversuswindow-opengl-example.jpg {Qt logo with red overlay demonstrating widget stacking}

    The example allows showing the same Qt Quick scene within the same
    QWidget-based user interface using two different approaches:

    \list
    \li Using a QQuickView.

        It is used as a child window and with QWidget::createWindowContainer()
    \li Using QQuickWidget.

        Acts as a true QWidget and supports, among others, better clipping and
        stacking, as is expected from a true QWidget.
    \endlist

    Clicking on the \uicontrol{Show widget overlay} checkbox demonstrates a widget
    stacking case that is not rendering as expected when embedding a native
    window, while QQuickWidget makes it render as expected.

    \include examples-run.qdocinc

    \section1 Platform notes

    The Qt Quick scene uses direct OpenGL rendering, even when embedded with
    QQuickWidget. This confirms that rendering continues to use the accelerated
    3D API.

    Therefore, the example is tied to OpenGL and won't work with other
    graphics APIs such as Vulkan, Metal, or Direct3D.

    \section1 Multisample antialiasing

    You can enable multisample antialiasing by selecting the corresponding
    checkbox. When enabled, QQuickWidget renders content into a multisample
    renderbuffer. After each render pass, the content is resolved into a
    standard 2D texture. This enables antialiasing for Qt Quick content without
    affecting the rest of the QWidget-based UI.

    If you're using QQuickView, the native window requests multisampling for its
    surface. This provides similar results, depending on platform support.

    \section1 Keyboard input

    The Qt Quick scene supports user interaction, including text input,
    regardless of the embedding technology used. When using QQuickWidget, input
    events are automatically forwarded to the Qt Quick scene.

    \sa {Qt Quick Widgets}
*/
