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
|
// Copyright (C) 2022 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example scenegraph/customrendernode
\title Scene Graph - Custom QSGRenderNode
\examplecategory {Graphics & Multimedia}
\ingroup qtquickexamples
\brief Shows how to use QSGRenderNode to implement custom rendering in the Qt Quick scenegraph.
The custom render node example shows how to implement a QQuickItem subclass
that is backed by a scene graph node derived from QSGRenderNode, providing
it's own QRhi-based rendering.
\image customrendernode-example.jpg
\note This example demonstrates advanced, low-level functionality performing
portable, cross-platform 3D rendering, while relying on APIs with limited
compatibility guarantee from the Qt Gui module. To be able to use the QRhi
APIs, the application links to \c{Qt::GuiPrivate} and includes
\c{<rhi/qrhi.h>}.
QSGRenderNode allows direct access to the Render Hardware Interface (RHI)
within the scenegraph. This example demonstrates how to create QSGRenderNode
based render node and manage it with a custom item. The render node creates
an RHI pipeline, updates vertex and uniform buffers, and renders into the
RHI command buffer.
In practice this is a portable, cross-platform approach to perform custom
rendering inline with the scenegraph's own rendering, without resorting to a
native 3D API such as OpenGL, Metal, or Vulkan. Rather, the application uses
Qt's graphics and shader abstraction layer.
QSGRenderNode is the enabler for one of the three ways to integrate custom
2D/3D rendering into a Qt Quick scene. The other two options are to perform
the rendering \c before or \c after the Qt Quick scene's own rendering,
or to generate a whole separate render pass targeting a dedicated render
target (a texture) and then have an item in the scene display the texture.
The QSGRenderNode-based approach is similar to the former, in the sense
that no additional render passes or render targets are involved, and allows
injecting custom rendering commands "inline" with the Qt Quick scene's
own rendering.
Refer to the following examples for these three approaches:
\list
\li \l{Scene Graph - RHI Under QML} - Demonstrates an "underlay" approach
based on the \l{QQuickWindow::beforeRendering()} signal. No additional
render pass and resources are needed, but composition and blending with the
rest of the Qt Quick scene is quite limited. Rendering "under" or "over" the
Qt Quick scene is the simplest approach.
\li \l{Scene Graph - RHI Texture Item} - Demonstrates creating a custom
QQuickItem that renders into a texture and displays a quad textured with the
generated content. This is very flexible and allows complete blending and
composition of the resulting 2D image with the rest of the Qt Quick scene.
That comes at the expense of an additional render pass and render target.
\li This example - Demonstrates the "inline" approach, where the Qt Quick
scene graph calls into the custom item and node implementation during the
main render pass. This approach can be great for performance (no extra
render passes, texturing, and blending are involved), but has potential
pitfalls and is the most complicated method.
\endlist
The custom item derives from QQuickItem. Most importantly, it reimplements
\l{QQuickItem::}updatePaintNode().
\snippet scenegraph/customrendernode/customrender.h item
The constructor sets the \l{QQuickItem::}ItemHasContents flag to indicate
that this is a visual item.
\snippet scenegraph/customrendernode/customrender.cpp item-ctor
The updatePaintNode() implementation creates an instance of the custom
scenegraph node, if not yet done. The backing QSGNode tree for this item
consists of a single node, an instance of a QSGRenderNode-derived class.
When Qt Quick's threaded rendering model is in use, this function is called
on the render thread with the main thread blocked. That is why it is safe to
access main thread data (such as data stored in QQuickItems). The node, the
instance of the QSGRenderNode subclass, is going to "live on" the render
thread.
\snippet scenegraph/customrendernode/customrender.cpp item-update
The \c CustomRenderNode class derives from QSGRenderNode, reimplementing a
number of virtual functions. To manage QRhi resources (buffers, pipelines,
etc.), smart pointers are quite useful in this case, because the node is
destroyed by the scene graph together with the rest of the scene on the
render thread (if there is one) while the QRhi is still available, and
therefore releasing resources from the destructor or via smart pointers is
legal and safe.
\snippet scenegraph/customrendernode/customrender.cpp node
Well-behaving QSGRenderNode subclasses also reimplement
\l{QSGRenderNode::}releaseResources(),which in this case can be a simple set
of reset() calls.
\snippet scenegraph/customrendernode/customrender.cpp node-release
This QSGRenderNode is performing its rendering through the QRhi APIs (and
not directly through OpenGL, Vulkan, Metal, etc.), and it takes the item
transform into account (as it only really does 2D rendering). Hence
specifying the appropriate flags, which may bring a small performance
improvement.
\snippet scenegraph/customrendernode/customrender.cpp node-flags
The prepare() and render() functions are called every time the Qt Quick
scene renders. The first is called when preparing (but not yet recording)
the render pass. This typically creates resources, such as buffers,
textures, and graphics pipelines, if not yet done, and enqueues uploading
data to them.
\snippet scenegraph/customrendernode/customrender.cpp node-prepare
The render() function is called while the recording of a render pass,
targeting either the QQuickWindow's swapchain, or a texture (in case of
layered items, or when within a ShaderEffectSource), is active.
\snippet scenegraph/customrendernode/customrender.cpp node-render
\sa QSGRenderNode, QRhi, {Scene Graph - RHI Under QML}, {Scene Graph - RHI Texture Item}, {Qt Quick Scene Graph}
*/
|
