Revision control
++ // Copyright (C) 2023 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \title QQuickRenderControl RHI Example
++ \example rendercontrol/rendercontrol_rhi
++ \brief Shows how to render a Qt Quick scene into a QRhiTexture.
++ \examplecategory {Graphics}
++ \image rendercontrol-rhi-example.jpg {Grid of rendered frames with
++ CPU and GPU timing metrics for each frame}
++
++ This example demonstrates how to set up a Qt Quick scene that has its
++ rendering redirected into a \l QRhiTexture. The application is then free to
++ do whatever it wants with the resulting texture from each frame.
++ This example is a QWidget-based application that performs a readback of the
++ image data, and then displays the collected per-frame renders with CPU and
++ GPU-based timing information for each.
++
++ By using Qt's 3D graphics API abstraction, this example is not tied to any
++ particular graphics API. At startup, a dialog is shown with the platforms'
++ potentially supported 3D APIs.
++
++ \snippet rendercontrol/rendercontrol_rhi/main.cpp apiselect
++
++ \note It is not guaranteed that all selections will be functional on a given
++ platform.
++
++ Once a selection is made, a QML file is loaded. However, we will not simply
++ create a \l QQuickView instance and \l{QQuickView::show()}{show()} it.
++ Rather, the \l QQuickWindow that manages the Qt Quick scene is never shown
++ on-screen. Instead, the application takes control over when and to where
++ render, via \l QQuickRenderControl.
++
++ \snippet rendercontrol/rendercontrol_rhi/main.cpp load-1
++
++ Once the object tree is instantiated, the root item (a \l Rectangle) is
++ queried, its size is ensured to be valid and then propagated.
++
++ \note Scenes that use the \l Window element within the object tree are not
++ supported.
++
++ \snippet rendercontrol/rendercontrol_rhi/main.cpp load-instantiate
++
++ At this point there are no rendering resources initialized, i.e., nothing has
++ been done with the native 3D graphics API yet. A \l QRhi is instantiated
++ only in the next step, and that is what triggers setting up the Vulkan,
++ Metal, Direct 3D, etc. rendering system under the hood.
++
++ \snippet rendercontrol/rendercontrol_rhi/main.cpp load-graphicsinit
++
++ \note This application uses a model where Qt creates an instance of QRhi.
++ This is not the only possible approach: if the application maintains its own
++ QRhi (and so OpenGL context, Vulkan device, etc.), then Qt Quick can be
++ requested to adopt and use that existing QRhi. That is done via passing a \l
++ QQuickGraphicsDevice created by \l{QQuickGraphicsDevice::fromRhi()} to
++ \l QQuickWindow, similarly to how \l QQuickGraphicsConfiguration is set in
++ the snippet above. Consider for example the case of wanting to use the Qt
++ Quick rendered textures in a QRhiWidget: in that case the QRhiWidget's QRhi
++ will need to passed on to Qt Quick, instead of letting Qt Quick create its
++ own.
++
++ Once \l QQuickRenderControl::initialize() succeeds, the renderer is live and
++ ready to go. For that, we need a color buffer to render into.
++
++ \l QQuickRenderTarget is a lightweight implicitly-shared class that carries
++ (but those not own) various sets of native or QRhi objects that describe
++ textures, render targets, or similar. Calling
++ \l{QQuickWindow::setRenderTarget()}{setRenderTarget()} on the \l
++ QQuickWindow (remember that we have a QQuickWindow that is not visible
++ on-screen) is what triggers redirecting the Qt Quick scene graph's rendering
++ into the texture provided by the application. When working with \l QRhi (and
++ not with native 3D API objects such as OpenGL texture IDs or VkImage
++ objects), the application should set up a \l QRhiTextureRenderTarget and
++ then pass it to Qt Quick via \l QQuickRenderTarget::fromRhiRenderTarget().
++
++ \snippet rendercontrol/rendercontrol_rhi/main.cpp texture-setup
++
++ \note Always provide a depth-stencil buffer for Qt Quick since both of these
++ buffers and the depth and stencil test may get utilized by the Qt Quick
++ scenegraph when rendering.
++
++ The main render loop is the following. This also shows how to perform
++ GPU->CPU readbacks of images. Once a QImage is available, the
++ QWidget-based user interface updates accordingly. We will omit diving
++ into the details for that here.
++
++ The example also demonstrates a simple way of measuring the cost of
++ rendering a frame on the CPU and the GPU. Offscreen-rendered frames are well
++ suited for this due to certain internal QRhi behavior, which implies that
++ operations that otherwise are asynchronous (in the sense that they complete
++ only when rendering a subsequent frame), are guaranteed to be ready once \l
++ QRhi::endOffscreenFrame() (i.e., QQuickRenderControl::endFrame()) returns.
++ We use this knowledge when reading back the texture, and it applies also to
++ GPU timestamps as well. That is why the application can display the GPU time
++ for each frame, while guaranteeing that the time actually refers to that
++ particular frame (not an earlier one). See
++ \l{QRhiCommandBuffer::lastCompletedGpuTime()}{lastCompletedGpuTime()} for
++ details around GPU timings. The CPU side timings are taken using
++ \l QElapsedTimer.
++
++ \snippet rendercontrol/rendercontrol_rhi/main.cpp render-core
++
++ One important piece is the stepping of Qt Quick animations. As we do not
++ have an on-screen window that can drive the animation system either via
++ measuring elapsed time, an ordinary timer, or presentation rate-based
++ throttling, redirecting the Qt Quick rendering often implies that the
++ driving of animations needs to be taken over by the application. Otherwise,
++ animations function based on a plain system timer, but the actual elapsed
++ time will often have nothing to do with what the offscreen-rendered scene is
++ expected to perceive. Consider rendering 5 frames in a row, in a tight loop.
++ How the animations in those 5 frames move depends on the speed with which
++ the CPU executes the loop iterations. That is almost never ideal. To ensure
++ consistent animations, install a custom QAnimationDriver. While this is
++ an undocumented (but public) API meant for advanced users, the example here
++ provides a simple example of using it.
++
++ \snippet rendercontrol/rendercontrol_rhi/main.cpp anim-driver
++
++ The application has a \l QSlider that can be used to change the animation
++ step value from the default 16 milliseconds to something else. Note the call
++ to the setStep() function of our QAnimationDriver subclass.
++
++ \snippet rendercontrol/rendercontrol_rhi/main.cpp anim-slider
++
++ \note Installing the custom animation driver is made optional via the
++ \c animCheckBox check box. This allows comparing the effect of having and
++ not having a custom animation driver installed. In addition, on some
++ platforms (and perhaps depending on the theme), having the custom driver
++ enabled may lead to lags in widget drawing. This is as expected, because if
++ some widget animation (e.g. highlight of a QPushButton or QCheckBox) is
++ managed via \l QPropertyAnimation and similar, then those animation are
++ driven by the same QAnimationDriver, and that does not advance until a new
++ frame is requested by clicking on the buttons.
++
++ Advancing the animations is done before each frame (i.e., before the
++ QQuickRenderControl::beginFrame() call) by simply calling advance():
++
++ \snippet rendercontrol/rendercontrol_rhi/main.cpp anim-step
++
++ \sa QRhi, QQuickRenderControl, QQuickWindow
++ */