/usr/share/qt5/doc/qtquick/qtquick-scenegraph-openglunderqml-example.html is in qtdeclarative5-doc-html 5.2.1-3ubuntu15.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- openglunderqml.qdoc -->
<title>Scene Graph - OpenGL Under QML | QtQuick 5.2</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<ul>
<li>Qt 5.2</li>
<li><a href="qtquick-index.html">Qt Quick</a></li>
<li>Scene Graph - OpenGL Under QML</li>
<li id="buildversion">
Qt 5.2.1 Reference Documentation</li>
</ul>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<h1 class="title">Scene Graph - OpenGL Under QML</h1>
<span class="subtitle"></span>
<!-- $$$scenegraph/openglunderqml-description -->
<div class="descr"> <a name="details"></a>
<p>Shows how to render OpenGL under a Qt Quick scene.<p class="centerAlign"><img src="images/openglunderqml-example.jpg" alt="" /></p><p>The OpenGL under QML example shows how an application can make use of the <a href="qquickwindow.html#beforeRendering">QQuickWindow::beforeRendering</a>() signal to draw custom OpenGL content under a Qt Quick scene. This signal is emitted at the start of every frame, before the scene graph starts its rendering, thus any OpenGL draw calls that are made as a response to this signal, will stack under the Qt Quick items.</p>
<p>As an alternative, applications that wish to render OpenGL content on top of the Qt Quick scene, can do so by connecting to the <a href="qquickwindow.html#afterRendering">QQuickWindow::afterRendering</a>() signal.</p>
<p>In this example, we will also see how it is possible to have values that are exposed to QML which affect the OpenGL rendering. We animate the threshold value using a <a href="qml-qtquick-numberanimation.html">NumberAnimation</a> in the QML file and this value is used by the OpenGL shader program that draws the squircles.</p>
<pre class="cpp"><span class="keyword">class</span> Squircle : <span class="keyword">public</span> <span class="type"><a href="qquickitem.html">QQuickItem</a></span>
{
Q_OBJECT
Q_PROPERTY(<span class="type">qreal</span> t READ t WRITE setT NOTIFY tChanged)
<span class="keyword">public</span>:
Squircle();
<span class="type">qreal</span> t() <span class="keyword">const</span> { <span class="keyword">return</span> m_t; }
<span class="type">void</span> setT(<span class="type">qreal</span> t);
<span class="keyword">signals</span>:
<span class="type">void</span> tChanged();
<span class="keyword">public</span> <span class="keyword">slots</span>:
<span class="type">void</span> paint();
<span class="type">void</span> cleanup();
<span class="type">void</span> sync();
<span class="keyword">private</span> <span class="keyword">slots</span>:
<span class="type">void</span> handleWindowChanged(<span class="type"><a href="qquickwindow.html">QQuickWindow</a></span> <span class="operator">*</span>win);
<span class="keyword">private</span>:
<span class="type">QOpenGLShaderProgram</span> <span class="operator">*</span>m_program;
<span class="type">qreal</span> m_t;
<span class="type">qreal</span> m_thread_t;
};</pre>
<p>First of all, we need a QObject with a slot to connect the signals to. We subclass <a href="qquickitem.html">QQuickItem</a> in order to use the <a href="qquickitem.html#window">QQuickItem::window</a>() which holds the window instance we want to connect to.</p>
<p>We use two values of <tt>t</tt>. The variable <tt>m_t</tt> is the property value as it exists in the GUI thread. The <tt>m_thread_t</tt> value is a copy of <tt>m_t</tt> for use in the rendering thread. We need an explicit copy because the scene graph can render in one thread while updating properties on the GUI thread in preparation for the next frame. If we had used only one value, the animation could have updated the value to that of the next frame before we got a chance to render it.</p>
<p><b>Note: </b>In this example, a wrong value for <tt>t</tt> will have minimal consequences, but we emphasize that rendering and GUI thread objects and values must stay separate to avoid race conditions, undesired behavior and in the worst case, crashes.</p><p>Lets move on to the implementation.</p>
<pre class="cpp">Squircle<span class="operator">::</span>Squircle()
: m_program(<span class="number">0</span>)
<span class="operator">,</span> m_t(<span class="number">0</span>)
<span class="operator">,</span> m_thread_t(<span class="number">0</span>)
{
connect(<span class="keyword">this</span><span class="operator">,</span> SIGNAL(windowChanged(<span class="type"><a href="qquickwindow.html">QQuickWindow</a></span><span class="operator">*</span>))<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> SLOT(handleWindowChanged(<span class="type"><a href="qquickwindow.html">QQuickWindow</a></span><span class="operator">*</span>)));
}</pre>
<p>The constructor of the <tt>Squircle</tt> class simply initializes the values. The shader program will be initialized during rendering later.</p>
<pre class="cpp"><span class="type">void</span> Squircle<span class="operator">::</span>setT(<span class="type">qreal</span> t)
{
<span class="keyword">if</span> (t <span class="operator">=</span><span class="operator">=</span> m_t)
<span class="keyword">return</span>;
m_t <span class="operator">=</span> t;
<span class="keyword">emit</span> tChanged();
<span class="keyword">if</span> (window())
window()<span class="operator">-</span><span class="operator">></span>update();
}</pre>
<p>The property setter checks that the value has indeed changed before updating its internal variable. It then calls <a href="qquickwindow.html#update">QQuickWindow::update</a>() which will trigger another frame to be rendered. Note that the setter might be called during initialization, before the object has been entered into the scene and before it has a window.</p>
<pre class="cpp"><span class="type">void</span> Squircle<span class="operator">::</span>handleWindowChanged(<span class="type"><a href="qquickwindow.html">QQuickWindow</a></span> <span class="operator">*</span>win)
{
<span class="keyword">if</span> (win) {
connect(win<span class="operator">,</span> SIGNAL(beforeRendering())<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> SLOT(paint())<span class="operator">,</span> <span class="type">Qt</span><span class="operator">::</span>DirectConnection);
connect(win<span class="operator">,</span> SIGNAL(beforeSynchronizing())<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> SLOT(sync())<span class="operator">,</span> <span class="type">Qt</span><span class="operator">::</span>DirectConnection);</pre>
<p>For our paint function to be called, we need to connect to the window's signals. When Squircle object is populated into the scene, the windowChanged signal is emitted. In our handler, we connect <a href="qquickwindow.html#beforeRendering">QQuickWindow::beforeRendering</a>() to <tt>paint()</tt> to do the rendering, and <a href="qquickwindow.html#beforeSynchronizing">QQuickWindow::beforeSynchronizing</a>() to <tt>sync()</tt> to copy the state of the <tt>t</tt> property for the upcoming frame.</p>
<p><b>Note: </b>Since the Squircle object has affinity to the GUI thread and the signals are emitted from the rendering thread, it is crucial that the connections are made with Qt::DirectConnection. Failing to do so, will result in that the slots are invoked on the wrong thread with no OpenGL context present.</p><pre class="cpp"> win<span class="operator">-</span><span class="operator">></span>setClearBeforeRendering(<span class="keyword">false</span>);
}
}</pre>
<p>The default behavior of the scene graph is to clear the framebuffer before rendering. Since we render before the scene graph, we need to turn this clearing off. This means that we need to clear ourselves in the <tt>paint()</tt> function.</p>
<pre class="cpp"><span class="type">void</span> Squircle<span class="operator">::</span>paint()
{
<span class="keyword">if</span> (<span class="operator">!</span>m_program) {
m_program <span class="operator">=</span> <span class="keyword">new</span> <span class="type">QOpenGLShaderProgram</span>();
m_program<span class="operator">-</span><span class="operator">></span>addShaderFromSourceCode(<span class="type">QOpenGLShader</span><span class="operator">::</span>Vertex<span class="operator">,</span>
<span class="string">"attribute highp vec4 vertices;"</span>
<span class="string">"varying highp vec2 coords;"</span>
<span class="string">"void main() {"</span>
<span class="string">" gl_Position = vertices;"</span>
<span class="string">" coords = vertices.xy;"</span>
<span class="string">"}"</span>);
m_program<span class="operator">-</span><span class="operator">></span>addShaderFromSourceCode(<span class="type">QOpenGLShader</span><span class="operator">::</span>Fragment<span class="operator">,</span>
<span class="string">"uniform lowp float t;"</span>
<span class="string">"varying highp vec2 coords;"</span>
<span class="string">"void main() {"</span>
<span class="string">" lowp float i = 1. - (pow(abs(coords.x), 4.) + pow(abs(coords.y), 4.));"</span>
<span class="string">" i = smoothstep(t - 0.8, t + 0.8, i);"</span>
<span class="string">" i = floor(i * 20.) / 20.;"</span>
<span class="string">" gl_FragColor = vec4(coords * .5 + .5, i, i);"</span>
<span class="string">"}"</span>);
m_program<span class="operator">-</span><span class="operator">></span>bindAttributeLocation(<span class="string">"vertices"</span><span class="operator">,</span> <span class="number">0</span>);
m_program<span class="operator">-</span><span class="operator">></span>link();
connect(window()<span class="operator">-</span><span class="operator">></span>openglContext()<span class="operator">,</span> SIGNAL(aboutToBeDestroyed())<span class="operator">,</span>
<span class="keyword">this</span><span class="operator">,</span> SLOT(cleanup())<span class="operator">,</span> <span class="type">Qt</span><span class="operator">::</span>DirectConnection);
}</pre>
<p>The first thing we do in the <tt>paint()</tt> function is to initialize the shader program. By initializing the shader program here, we make sure that the OpenGL context is bound and that we are on the correct thread.</p>
<p>We also connect to the QOpenGLContext::aboutToBeDestroyed() signal, so that we can clean up the shader program when the context is destroyed. Again, this is a Qt::DirectConnection as all rendering related operations must happen on the rendering thread.</p>
<pre class="cpp"> m_program<span class="operator">-</span><span class="operator">></span>bind();
m_program<span class="operator">-</span><span class="operator">></span>enableAttributeArray(<span class="number">0</span>);
<span class="type">float</span> values<span class="operator">[</span><span class="operator">]</span> <span class="operator">=</span> {
<span class="operator">-</span><span class="number">1</span><span class="operator">,</span> <span class="operator">-</span><span class="number">1</span><span class="operator">,</span>
<span class="number">1</span><span class="operator">,</span> <span class="operator">-</span><span class="number">1</span><span class="operator">,</span>
<span class="operator">-</span><span class="number">1</span><span class="operator">,</span> <span class="number">1</span><span class="operator">,</span>
<span class="number">1</span><span class="operator">,</span> <span class="number">1</span>
};
m_program<span class="operator">-</span><span class="operator">></span>setAttributeArray(<span class="number">0</span><span class="operator">,</span> GL_FLOAT<span class="operator">,</span> values<span class="operator">,</span> <span class="number">2</span>);
m_program<span class="operator">-</span><span class="operator">></span>setUniformValue(<span class="string">"t"</span><span class="operator">,</span> (<span class="type">float</span>) m_thread_t);
<span class="type">qreal</span> ratio <span class="operator">=</span> window()<span class="operator">-</span><span class="operator">></span>devicePixelRatio();
<span class="type">int</span> w <span class="operator">=</span> <span class="type">int</span>(ratio <span class="operator">*</span> window()<span class="operator">-</span><span class="operator">></span>width());
<span class="type">int</span> h <span class="operator">=</span> <span class="type">int</span>(ratio <span class="operator">*</span> window()<span class="operator">-</span><span class="operator">></span>height());
glViewport(<span class="number">0</span><span class="operator">,</span> <span class="number">0</span><span class="operator">,</span> w<span class="operator">,</span> h);
glDisable(GL_DEPTH_TEST);
glClearColor(<span class="number">0</span><span class="operator">,</span> <span class="number">0</span><span class="operator">,</span> <span class="number">0</span><span class="operator">,</span> <span class="number">1</span>);
glClear(GL_COLOR_BUFFER_BIT);
glEnable(GL_BLEND);
glBlendFunc(GL_SRC_ALPHA<span class="operator">,</span> GL_ONE);
glDrawArrays(GL_TRIANGLE_STRIP<span class="operator">,</span> <span class="number">0</span><span class="operator">,</span> <span class="number">4</span>);
m_program<span class="operator">-</span><span class="operator">></span>disableAttributeArray(<span class="number">0</span>);
m_program<span class="operator">-</span><span class="operator">></span>release();
}</pre>
<p>We use the shader program to draw the squircle. At the end of the <tt>paint</tt> function we release the program and disable the attributes we used so that the OpenGL context is in a "clean" state for the scene graph to pick it up.</p>
<pre class="cpp"><span class="type">void</span> Squircle<span class="operator">::</span>cleanup()
{
<span class="keyword">if</span> (m_program) {
<span class="keyword">delete</span> m_program;
m_program <span class="operator">=</span> <span class="number">0</span>;
}
}</pre>
<p>In the <tt>cleanup()</tt> function we delete the program.</p>
<pre class="cpp"><span class="type">void</span> Squircle<span class="operator">::</span>sync()
{
m_thread_t <span class="operator">=</span> m_t;
}</pre>
<p>We use the <tt>sync()</tt> function to copy the state of the object in the GUI thread into the rendering thread.</p>
<p>The signal is emitted on the rendering thread while the GUI thread is blocked, so it is safe to simply copy the value without any additional protection.</p>
<pre class="cpp"><span class="type">int</span> main(<span class="type">int</span> argc<span class="operator">,</span> <span class="type">char</span> <span class="operator">*</span><span class="operator">*</span>argv)
{
<span class="type">QGuiApplication</span> app(argc<span class="operator">,</span> argv);
qmlRegisterType<span class="operator"><</span>Squircle<span class="operator">></span>(<span class="string">"OpenGLUnderQML"</span><span class="operator">,</span> <span class="number">1</span><span class="operator">,</span> <span class="number">0</span><span class="operator">,</span> <span class="string">"Squircle"</span>);
<span class="type"><a href="qquickview.html">QQuickView</a></span> view;
view<span class="operator">.</span>setResizeMode(<span class="type"><a href="qquickview.html">QQuickView</a></span><span class="operator">::</span>SizeRootObjectToView);
view<span class="operator">.</span>setSource(<span class="type">QUrl</span>(<span class="string">"qrc:///scenegraph/openglunderqml/main.qml"</span>));
view<span class="operator">.</span>show();
<span class="keyword">return</span> app<span class="operator">.</span>exec();
}</pre>
<p>The application's <tt>main()</tt> function instantiates a <a href="qquickview.html">QQuickView</a> and launches the <tt>main.qml</tt> file. The only thing worth noting is that we export the <tt>Squircle</tt> class to QML using the qmlRegisterType() macro.</p>
<pre class="qml">import QtQuick 2.0
import OpenGLUnderQML 1.0
<span class="type"><a href="qml-qtquick-item.html">Item</a></span> {
<span class="name">width</span>: <span class="number">320</span>
<span class="name">height</span>: <span class="number">480</span>
<span class="type">Squircle</span> {
SequentialAnimation on <span class="name">t</span> {
<span class="type"><a href="qml-qtquick-numberanimation.html">NumberAnimation</a></span> { <span class="name">to</span>: <span class="number">1</span>; <span class="name">duration</span>: <span class="number">2500</span>; <span class="name">easing</span>.type: <span class="name">Easing</span>.<span class="name">InQuad</span> }
<span class="type"><a href="qml-qtquick-numberanimation.html">NumberAnimation</a></span> { <span class="name">to</span>: <span class="number">0</span>; <span class="name">duration</span>: <span class="number">2500</span>; <span class="name">easing</span>.type: <span class="name">Easing</span>.<span class="name">OutQuad</span> }
<span class="name">loops</span>: <span class="name">Animation</span>.<span class="name">Infinite</span>
<span class="name">running</span>: <span class="number">true</span>
}
}</pre>
<p>We import the Squircle QML type with the name we registered in the <tt>main()</tt> function. We then instantiate it and create a running <a href="qml-qtquick-numberanimation.html">NumberAnimation</a> on its <tt>t</tt> property.</p>
<pre class="qml"> <span class="type"><a href="qml-qtquick-rectangle.html">Rectangle</a></span> {
<span class="name">color</span>: <span class="name">Qt</span>.<span class="name">rgba</span>(<span class="number">1</span>, <span class="number">1</span>, <span class="number">1</span>, <span class="number">0.7</span>)
<span class="name">radius</span>: <span class="number">10</span>
<span class="name">border</span>.width: <span class="number">1</span>
<span class="name">border</span>.color: <span class="string">"white"</span>
<span class="name">anchors</span>.fill: <span class="name">label</span>
<span class="name">anchors</span>.margins: -<span class="number">10</span>
}
<span class="type"><a href="qml-qtquick-text.html">Text</a></span> {
<span class="name">id</span>: <span class="name">label</span>
<span class="name">color</span>: <span class="string">"black"</span>
<span class="name">wrapMode</span>: <span class="name">Text</span>.<span class="name">WordWrap</span>
<span class="name">text</span>: <span class="string">"The background here is a squircle rendered with raw OpenGL using the 'beforeRender()' signal in QQuickWindow. This text label and its border is rendered using QML"</span>
<span class="name">anchors</span>.right: <span class="name">parent</span>.<span class="name">right</span>
<span class="name">anchors</span>.left: <span class="name">parent</span>.<span class="name">left</span>
<span class="name">anchors</span>.bottom: <span class="name">parent</span>.<span class="name">bottom</span>
<span class="name">anchors</span>.margins: <span class="number">20</span>
}
}</pre>
<p>Then we overlay a short descriptive text, so that it is clearly visible that we are in fact rendering OpenGL under our Qt Quick scene.</p>
<p>Files:</p>
<ul>
<li><a href="qtquick-scenegraph-openglunderqml-main-qml.html">scenegraph/openglunderqml/main.qml</a></li>
<li><a href="qtquick-scenegraph-openglunderqml-squircle-cpp.html">scenegraph/openglunderqml/squircle.cpp</a></li>
<li><a href="qtquick-scenegraph-openglunderqml-squircle-h.html">scenegraph/openglunderqml/squircle.h</a></li>
<li><a href="qtquick-scenegraph-openglunderqml-main-cpp.html">scenegraph/openglunderqml/main.cpp</a></li>
<li><a href="qtquick-scenegraph-openglunderqml-openglunderqml-pro.html">scenegraph/openglunderqml/openglunderqml.pro</a></li>
<li><a href="qtquick-scenegraph-openglunderqml-openglunderqml-qrc.html">scenegraph/openglunderqml/openglunderqml.qrc</a></li>
</ul>
</div>
<!-- @@@scenegraph/openglunderqml -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2013 Digia Plc and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Digia, Qt and their respective logos are trademarks of Digia Plc in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
|