qt5base-lts/tests/manual/rhi/rhiwidget/rhiwidget.cpp

// Copyright (C) 2021 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause

#include "rhiwidget_p.h"

#include <private/qguiapplication_p.h>
#include <qpa/qplatformintegration.h>
#include <private/qwidgetrepaintmanager_p.h>

/*!
    \class QRhiWidget
    \inmodule QtWidgets
    \since 6.x

    \brief The QRhiWidget class is a widget for rendering 3D graphics via an
    accelerated grapics API, such as Vulkan, Metal, or Direct 3D.

    QRhiWidget provides functionality for displaying 3D content rendered through
    the QRhi APIs within a QWidget-based application.

    QRhiWidget is expected to be subclassed. To render into the 2D texture that
    is implicitly created and managed by the QRhiWidget, subclasses should
    reimplement the virtual functions initialize() and render().

    The size of the texture will by default adapt to the size of the item. If a
    fixed size is preferred, set an explicit size specified in pixels by
    calling setExplicitSize().

    The QRhi for the widget's top-level window is configured to use a platform
    specific backend and graphics API by default: Metal on macOS and iOS,
    Direct 3D 11 on Windows, OpenGL otherwise. Call setApi() to override this.

    \note A single widget window can only use one QRhi backend, and so graphics
    API. If two QRhiWidget or QQuickWidget widgets in the window's widget
    hierarchy request different APIs, only one of them will function correctly.
 */

/*!
    Constructs a widget which is a child of \a parent, with widget flags set to \a f.
 */
QRhiWidget::QRhiWidget(QWidget *parent, Qt::WindowFlags f)
    : QWidget(*(new QRhiWidgetPrivate), parent, f)
{
    Q_D(QRhiWidget);
    if (Q_UNLIKELY(!QGuiApplicationPrivate::platformIntegration()->hasCapability(QPlatformIntegration::RhiBasedRendering)))
        qWarning("QRhiWidget: QRhi is not supported on this platform.");
    else
        d->setRenderToTexture();

    d->config.setEnabled(true);
#if defined(Q_OS_DARWIN)
    d->config.setApi(QPlatformBackingStoreRhiConfig::Metal);
#elif defined(Q_OS_WIN)
    d->config.setApi(QPlatformBackingStoreRhiConfig::D3D11);
#else
    d->config.setApi(QPlatformBackingStoreRhiConfig::OpenGL);
#endif
}

/*!
    Destructor.
 */
QRhiWidget::~QRhiWidget()
{
    Q_D(QRhiWidget);
    // rhi resources must be destroyed here, cannot be left to the private dtor
    delete d->t;
    d->offscreenRenderer.reset();
}

/*!
    Handles resize events that are passed in the \a e event parameter. Calls
    the virtual function initialize().

    \note Avoid overriding this function in derived classes. If that is not
    feasible, make sure that QRhiWidget's implementation is invoked too.
    Otherwise the underlying texture object and related resources will not get
    resized properly and will lead to incorrect rendering.
 */
void QRhiWidget::resizeEvent(QResizeEvent *e)
{
    Q_D(QRhiWidget);

    if (e->size().isEmpty()) {
        d->noSize = true;
        return;
    }
    d->noSize = false;

    d->sendPaintEvent(QRect(QPoint(0, 0), size()));
}

/*!
    Handles paint events.

    Calling QWidget::update() will lead to sending a paint event \a e, and thus
    invoking this function. (NB this is asynchronous and will happen at some
    point after returning from update()). This function will then, after some
    preparation, call the virtual render() to update the contents of the
    QRhiWidget's associated texture. The widget's top-level window will then
    composite the texture with the rest of the window.
 */
void QRhiWidget::paintEvent(QPaintEvent *)
{
    Q_D(QRhiWidget);
    if (!updatesEnabled() || d->noSize)
        return;

    d->ensureRhi();
    if (!d->rhi) {
        qWarning("QRhiWidget: No QRhi");
        return;
    }

    const QSize prevSize = d->t ? d->t->pixelSize() : QSize();
    d->ensureTexture();
    if (!d->t)
        return;
    if (d->t->pixelSize() != prevSize)
        initialize(d->rhi, d->t);

    QRhiCommandBuffer *cb = nullptr;
    d->rhi->beginOffscreenFrame(&cb);
    render(cb);
    d->rhi->endOffscreenFrame();
}

/*!
  \reimp
*/
bool QRhiWidget::event(QEvent *e)
{
    Q_D(QRhiWidget);
    switch (e->type()) {
    case QEvent::WindowChangeInternal:
        // the QRhi will almost certainly change, prevent texture() from
        // returning the existing QRhiTexture in the meantime
        d->textureInvalid = true;
        break;
    case QEvent::Show:
        if (isVisible())
            d->sendPaintEvent(QRect(QPoint(0, 0), size()));
        break;
    default:
        break;
    }
    return QWidget::event(e);
}

QPlatformBackingStoreRhiConfig QRhiWidgetPrivate::rhiConfig() const
{
    return config;
}

void QRhiWidgetPrivate::ensureRhi()
{
    Q_Q(QRhiWidget);
    // the QRhi and infrastructure belongs to the top-level widget, not to this widget
    QWidget *tlw = q->window();
    QWidgetPrivate *wd = get(tlw);

    QRhi *currentRhi = nullptr;
    if (QWidgetRepaintManager *repaintManager = wd->maybeRepaintManager())
        currentRhi = repaintManager->rhi();

    if (currentRhi && currentRhi->backend() != QBackingStoreRhiSupport::apiToRhiBackend(config.api())) {
        qWarning("The top-level window is already using another graphics API for composition, "
                 "'%s' is not compatible with this widget",
                 currentRhi->backendName());
        return;
    }

    if (currentRhi && rhi && rhi != currentRhi) {
        // the texture belongs to the old rhi, drop it, this will also lead to
        // initialize() being called again
        delete t;
        t = nullptr;
        // if previously we created our own but now get a QRhi from the
        // top-level, then drop what we have and start using the top-level's
        if (rhi == offscreenRenderer.rhi())
            offscreenRenderer.reset();
    }

    rhi = currentRhi;
}

void QRhiWidgetPrivate::ensureTexture()
{
    Q_Q(QRhiWidget);

    QSize newSize = explicitSize;
    if (newSize.isEmpty())
        newSize = q->size() * q->devicePixelRatio();

    if (!t) {
        if (!rhi->isTextureFormatSupported(format))
            qWarning("QRhiWidget: The requested texture format is not supported by the graphics API implementation");
        t = rhi->newTexture(format, newSize, 1, QRhiTexture::RenderTarget | QRhiTexture::UsedAsTransferSource);
        if (!t->create()) {
            qWarning("Failed to create backing texture for QRhiWidget");
            delete t;
            t = nullptr;
            return;
        }
    }

    if (t->pixelSize() != newSize) {
        t->setPixelSize(newSize);
        if (!t->create())
            qWarning("Failed to rebuild texture for QRhiWidget after resizing");
    }

    textureInvalid = false;
}

/*!
    \return the currently set graphics API (QRhi backend).

    \sa setApi()
 */
QRhiWidget::Api QRhiWidget::api() const
{
    Q_D(const QRhiWidget);
    switch (d->config.api()) {
    case QPlatformBackingStoreRhiConfig::OpenGL:
        return OpenGL;
    case QPlatformBackingStoreRhiConfig::Metal:
        return Metal;
    case QPlatformBackingStoreRhiConfig::Vulkan:
        return Vulkan;
    case QPlatformBackingStoreRhiConfig::D3D11:
        return D3D11;
    default:
        return Null;
    }
}

/*!
    Sets the graphics API and QRhi backend to use to \a api.

    The default value depends on the platform: Metal on macOS and iOS, Direct
    3D 11 on Windows, OpenGL otherwise.

    \note This function must be called early enough, before the widget is added
    to a widget hierarchy and displayed on screen. For example, aim to call the
    function for the subclass constructor. If called too late, the function
    will have no effect.

    The \a api can only be set once for the widget and its top-level window,
    once it is done and takes effect, the window can only use that API and QRhi
    backend to render. Attempting to set another value, or to add another
    QRhiWidget with a different \a api will not function as expected.

    \sa setTextureFormat(), setDebugLayer(), api()
 */
void QRhiWidget::setApi(Api api)
{
    Q_D(QRhiWidget);
    switch (api) {
    case OpenGL:
        d->config.setApi(QPlatformBackingStoreRhiConfig::OpenGL);
        break;
    case Metal:
        d->config.setApi(QPlatformBackingStoreRhiConfig::Metal);
        break;
    case Vulkan:
        d->config.setApi(QPlatformBackingStoreRhiConfig::Vulkan);
        break;
    case D3D11:
        d->config.setApi(QPlatformBackingStoreRhiConfig::D3D11);
        break;
    default:
        d->config.setApi(QPlatformBackingStoreRhiConfig::Null);
        break;
    }
}

/*!
    \return true if a debug or validation layer will be requested if applicable
    to the graphics API in use.

    \sa setDebugLayer()
 */
bool QRhiWidget::isDebugLayerEnabled() const
{
    Q_D(const QRhiWidget);
    return d->config.isDebugLayerEnabled();
}

/*!
    Requests the debug or validation layer of the underlying graphics API
    when \a enable is true.

    Applicable for Vulkan and Direct 3D.

    \note This function must be called early enough, before the widget is added
    to a widget hierarchy and displayed on screen. For example, aim to call the
    function for the subclass constructor. If called too late, the function
    will have no effect.

    By default this is disabled.

    \sa setApi(), isDebugLayerEnabled()
 */
void QRhiWidget::setDebugLayer(bool enable)
{
    Q_D(QRhiWidget);
    d->config.setDebugLayer(enable);
}

/*!
    \return the currently set texture format.

    The default value is QRhiTexture::RGBA8.

    \sa setTextureFormat()
 */
QRhiTexture::Format QRhiWidget::textureFormat() const
{
    Q_D(const QRhiWidget);
    return d->format;
}

/*!
    Sets the associated texture's \a format.

    The default value is QRhiTexture::RGBA8. Only formats that are reported as
    supported from QRhi::isTextureFormatSupported() should be specified,
    rendering will not be functional otherwise.

    \note This function must be called early enough, before the widget is added
    to a widget hierarchy and displayed on screen. For example, aim to call the
    function for the subclass constructor. If called too late, the function
    will have no effect.

    \sa setApi(), textureFormat()
 */
void QRhiWidget::setTextureFormat(QRhiTexture::Format format)
{
    Q_D(QRhiWidget);
    d->format = format;
}

/*!
    \property QRhiWidget::explicitSize

    The fixed size (in pixels) of the QRhiWidget's associated texture.

    Only relevant when a fixed texture size is desired that does not depend on
    the widget's size.

    By default the value is a null QSize. A null or empty QSize means that the
    texture's size follows the QRhiWidget's size. (\c{texture size} = \c{widget
    size} * \c{device pixel ratio}).
 */

QSize QRhiWidget::explicitSize() const
{
    Q_D(const QRhiWidget);
    return d->explicitSize;
}

void QRhiWidget::setExplicitSize(const QSize &pixelSize)
{
    Q_D(QRhiWidget);
    if (d->explicitSize != pixelSize) {
        d->explicitSize = pixelSize;
        emit explicitSizeChanged(pixelSize);
        update();
    }
}

/*!
    Renders a new frame, reads the contents of the texture back, and returns it
    as a QImage.

    When an error occurs, a null QImage is returned.

    \note This function only supports reading back QRhiTexture::RGBA8 textures
    at the moment. For other formats, the implementer of render() should
    implement their own readback logic as they see fit.

    The returned QImage will have a format of QImage::Format_RGBA8888.
    QRhiWidget does not know the renderer's approach to blending and
    composition, and therefore cannot know if the output has alpha
    premultiplied.

    This function can also be called when the QRhiWidget is not added to a
    widget hierarchy belonging to an on-screen top-level window. This allows
    generating an image from a 3D rendering off-screen.

    \sa setTextureFormat()
 */
QImage QRhiWidget::grabTexture()
{
    Q_D(QRhiWidget);
    if (d->noSize)
        return QImage();

    if (d->format != QRhiTexture::RGBA8) {
        qWarning("QRhiWidget::grabTexture() only supports RGBA8 textures");
        return QImage();
    }

    d->ensureRhi();
    if (!d->rhi) {
        // The widget (and its parent chain, if any) may not be shown at
        // all, yet one may still want to use it for grabs. This is
        // ridiculous of course because the rendering infrastructure is
        // tied to the top-level widget that initializes upon expose, but
        // it has to be supported.
        d->offscreenRenderer.setConfig(d->config);
        // no window passed in, so no swapchain, but we get a functional QRhi which we own
        d->offscreenRenderer.create();
        d->rhi = d->offscreenRenderer.rhi();
        if (!d->rhi) {
            qWarning("QRhiWidget: Failed to create dedicated QRhi for grabbing");
            return QImage();
        }
    }

    const QSize prevSize = d->t ? d->t->pixelSize() : QSize();
    d->ensureTexture();
    if (!d->t)
        return QImage();
    if (d->t->pixelSize() != prevSize)
        initialize(d->rhi, d->t);

    QRhiReadbackResult readResult;
    bool readCompleted = false;
    readResult.completed = [&readCompleted] { readCompleted = true; };

    QRhiCommandBuffer *cb = nullptr;
    d->rhi->beginOffscreenFrame(&cb);
    render(cb);
    QRhiResourceUpdateBatch *readbackBatch = d->rhi->nextResourceUpdateBatch();
    readbackBatch->readBackTexture(d->t, &readResult);
    cb->resourceUpdate(readbackBatch);
    d->rhi->endOffscreenFrame();

    if (readCompleted) {
        QImage wrapperImage(reinterpret_cast<const uchar *>(readResult.data.constData()),
                            readResult.pixelSize.width(), readResult.pixelSize.height(),
                            QImage::Format_RGBA8888);
        QImage result = wrapperImage.copy();
        result.setDevicePixelRatio(devicePixelRatio());
        return result;
    } else {
        Q_UNREACHABLE();
    }

    return QImage();
}

/*!
    Called when the widget is initialized, when the associated texture's size
    changes, or when the QRhi and texture change for some reason.

    The implementation should be prepared that both \a rhi and \a outputTexture
    can change between invocations of this function, although this is not
    always going to happen in practice. When the widget size changes, this
    function is called with the same \a rhi and \a outputTexture as before, but
    \a outputTexture may have been rebuilt, meaning its
    \l{QRhiTexture::pixelSize()}{size} and the underlying native texture
    resource may be different than in the last invocation.

    One special case where the objects will be different is when performing a
    grabTexture() with a widget that is not yet shown, and then making the
    widget visible on-screen within a top-level widget. There the grab will
    happen with a dedicated QRhi that is then replaced with the top-level
    window's associated QRhi in subsequent initialize() and render()
    invocations.

    Another, more common case is when the widget is reparented so that it
    belongs to a new top-level window. In this case \a rhi and \a outputTexture
    will definitely be different in the subsequent call to this function. Is is
    then important that all existing QRhi resources are destroyed because they
    belong to the previous QRhi that should not be used by the widget anymore.

    Implementations will typically create or rebuild a QRhiTextureRenderTarget
    in order to allow the subsequent render() call to render into the texture.
    When a depth buffer is necessary create a QRhiRenderBuffer as well. The
    size if this must follow the size of \a outputTexture. A compact and
    efficient way for this is the following:

    \code
    if (m_rhi != rhi) {
        // reset all resources (incl. m_ds, m_rt, m_rp)
    } else if (m_output != outputTexture) {
        // reset m_rt and m_rp
    }
    m_rhi = rhi;
    m_output = outputTexture;
    if (!m_ds) {
        // no depth-stencil buffer yet, create one
        m_ds = m_rhi->newRenderBuffer(QRhiRenderBuffer::DepthStencil, m_output->pixelSize());
        m_ds->create();
    } else if (m_ds->pixelSize() != m_output->pixelSize()) {
        // the size has changed, update the size and rebuild
        m_ds->setPixelSize(m_output->pixelSize());
        m_ds->create();
    }
    if (!m_rt) {
        m_rt = m_rhi->newTextureRenderTarget({ { m_output }, m_ds });
        m_rp = m_rt->newCompatibleRenderPassDescriptor();
        m_rt->setRenderPassDescriptor(m_rp);
        m_rt->create();
    }
    \endcode

    The above snippet is also prepared for \a rhi and \a outputTexture changing
    between invocations, via the checks at the beginning of the function.

    The created resources are expected to be released in the destructor
    implementation of the subclass. \a rhi and \a outputTexture are not owned
    by, and are guaranteed to outlive the QRhiWidget.

    \sa render()
 */
void QRhiWidget::initialize(QRhi *rhi, QRhiTexture *outputTexture)
{
    Q_UNUSED(rhi);
    Q_UNUSED(outputTexture);
}

/*!
    Called when the widget contents (i.e. the contents of the texture) need
    updating.

    There is always at least one call to initialize() before this function is
    called.

    To request updates, call QWidget::update(). Calling update() from within
    render() will lead to updating continuously, throttled by vsync.

    \a cb is the QRhiCommandBuffer for the current frame of the Qt Quick
    scenegraph. The function is called with a frame being recorded, but without
    an active render pass.

    \sa initialize()
 */
void QRhiWidget::render(QRhiCommandBuffer *cb)
{
    Q_UNUSED(cb);
}