1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
// 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
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
*/
|
