Debian Codegraph @

examples/quick/scenegraph/openglunderqml/doc/src/openglunderqml.qdoc

raw
1 /****************************************************************************
2 **
3 ** Copyright (C) 2017 The Qt Company Ltd.
4 ** Contact: https://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see https://www.qt.io/terms-conditions. For further
15 ** information use the contact form at https://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file. Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29 \example scenegraph/openglunderqml
30 \title Scene Graph - OpenGL Under QML
31 \ingroup qtquickexamples
32 \brief Shows how to render OpenGL under a Qt Quick scene.
33
34 \image openglunderqml-example.jpg
35
36 The OpenGL under QML example shows how an application can make use
37 of the \l QQuickWindow::beforeRendering() signal to draw custom
38 OpenGL content under a Qt Quick scene. This signal is emitted at
39 the start of every frame, before the scene graph starts its
40 rendering, thus any OpenGL draw calls that are made as a response
41 to this signal, will stack under the Qt Quick items.
42
43 As an alternative, applications that wish to render OpenGL content
44 on top of the Qt Quick scene, can do so by connecting to the \l
45 QQuickWindow::afterRendering() signal.
46
47 In this example, we will also see how it is possible to have
48 values that are exposed to QML which affect the OpenGL
49 rendering. We animate the threshold value using a NumberAnimation
50 in the QML file and this value is used by the OpenGL shader
51 program that draws the squircles.
52
53 The example is equivalent in most ways to the \l{Scene Graph - Direct3D 11
54 Under QML}{Direct3D 11 Under QML}, \l{Scene Graph - Metal Under QML}{Metal
55 Under QML}, and \l{Scene Graph - Vulkan Under QML}{Vulkan Under QML}
56 examples, they all render the same custom content, just via different
57 native APIs.
58
59 \snippet scenegraph/openglunderqml/squircle.h 2
60
61 First of all, we need an object we can expose to QML. This is a
62 subclass of QQuickItem so we can easily access \l QQuickItem::window().
63 We expose it to QML using the QML_ELEMENT macro.
64
65 \snippet scenegraph/openglunderqml/squircle.h 1
66
67 Then we need an object to take care of the rendering. This
68 instance needs to be separated from the QQuickItem because the
69 item lives in the GUI thread and the rendering potentially happens
70 on the render thread. Since we want to connect to \l
71 QQuickWindow::beforeRendering(), we make the renderer a QObject.
72 The renderer contains a copy of all the state it needs,
73 independent of the GUI thread.
74
75 \note Don't be tempted to merge the two objects into
76 one. QQuickItems may be deleted on the GUI thread while the render
77 thread is rendering.
78
79 Lets move on to the implementation.
80
81 \snippet scenegraph/openglunderqml/squircle.cpp 7
82
83 The constructor of the \c Squircle class simply initializes the
84 values and connects to the window changed signal which we will use
85 to prepare our renderer.
86
87 \snippet scenegraph/openglunderqml/squircle.cpp 1
88
89 Once we have a window, we attach to the \l
90 QQuickWindow::beforeSynchronizing() signal which we will use to
91 create the renderer and to copy state into it safely. We also
92 connect to the \l QQuickWindow::sceneGraphInvalidated() signal to
93 handle the cleanup of the renderer.
94
95 \note Since the Squircle object has affinity to the GUI thread and
96 the signals are emitted from the rendering thread, it is crucial
97 that the connections are made with \l
98 Qt::DirectConnection. Failing to do so, will result in that the
99 slots are invoked on the wrong thread with no OpenGL context
100 present.
101
102 \snippet scenegraph/openglunderqml/squircle.cpp 3
103
104 The default behavior of the scene graph is to clear the framebuffer before
105 rendering. This is fine since we will insert our own rendering code after
106 this clear is enqueued. Make sure however that we clear to the desired
107 color (black).
108
109 \snippet scenegraph/openglunderqml/squircle.cpp 9
110
111 We use the \c sync() function to initialize the renderer and to copy the
112 state in our item into the renderer. When the renderer is created, we also
113 connect the \l QQuickWindow::beforeRendering() and \l
114 QQuickWindow::beforeRenderPassRecording() to the renderer's \c init() and
115 \c paint() slots.
116
117 \note The \l QQuickWindow::beforeSynchronizing() signal is emitted
118 on the rendering thread while the GUI thread is blocked, so it is
119 safe to simply copy the value without any additional protection.
120
121 \snippet scenegraph/openglunderqml/squircle.cpp 6
122
123 In the \c cleanup() function we delete the renderer which in turn cleans up
124 its own resources. This is complemented by reimplementing \l
125 QQuickWindow::releaseResources() since just connecting to the
126 sceneGraphInvalidated() signal is not sufficient on its own to handle all
127 cases.
128
129 \snippet scenegraph/openglunderqml/squircle.cpp 8
130
131 When the value of \c t changes, we call \l QQuickWindow::update()
132 rather than \l QQuickItem::update() because the former will force
133 the entire window to be redrawn, even when the scene graph has not
134 changed since the last frame.
135
136 \snippet scenegraph/openglunderqml/squircle.cpp 4
137
138 In the SquircleRenderer's \c init() function we start by initializing the
139 shader program if not yet done. The OpenGL context is current on the thread
140 when the slot is invoked.
141
142 \snippet scenegraph/openglunderqml/squircle.cpp 5
143
144 We use the shader program to draw the squircle in \c paint().
145
146 \snippet scenegraph/openglunderqml/main.cpp 1
147
148 The application's \c main() function instantiates a QQuickView and
149 launches the \c main.qml file.
150
151 \snippet scenegraph/openglunderqml/main.qml 1
152
153 We import the Squircle QML type with the name we registered in the
154 \c main() function. We then instantiate it and create a running
155 NumberAnimation on its \c t property.
156
157 \snippet scenegraph/openglunderqml/main.qml 2
158
159 Then we overlay a short descriptive text, so that it is clearly
160 visible that we are in fact rendering OpenGL under our Qt Quick
161 scene.
162
163 */