| 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 |
*/ |