diff options
Diffstat (limited to 'src/quick/items/qquickwindow.cpp')
| -rw-r--r-- | src/quick/items/qquickwindow.cpp | 100 |
1 files changed, 38 insertions, 62 deletions
diff --git a/src/quick/items/qquickwindow.cpp b/src/quick/items/qquickwindow.cpp index d484d425bc..f812840782 100644 --- a/src/quick/items/qquickwindow.cpp +++ b/src/quick/items/qquickwindow.cpp @@ -859,87 +859,63 @@ void QQuickWindowPrivate::cleanup(QSGNode *n) For easily displaying a scene from a QML file, see \l{QQuickView}. - \section1 Scene Graph and Rendering - The QQuickWindow uses a scene graph on top of OpenGL to render. This scene graph is disconnected - from the QML scene and potentially lives in another thread, depending on the platform - implementation. Since the rendering scene graph lives independently from the QML scene, it can - also be completely released without affecting the state of the QML scene. - The sceneGraphInitialized() signal is emitted on the rendering thread before the QML scene is - rendered to the screen for the first time. If the rendering scene graph has been released - the signal will be emitted again before the next frame is rendered. + \section1 Rendering - The rendering of each frame is broken down into the following - steps, in the given order: + QQuickWindow uses a scene graph on top of OpenGL to + render. This scene graph is disconnected from the QML scene and + potentially lives in another thread, depending on the platform + implementation. Since the rendering scene graph lives + independently from the QML scene, it can also be completely + released without affecting the state of the QML scene. - \list 1 + The sceneGraphInitialized() signal is emitted on the rendering + thread before the QML scene is rendered to the screen for the + first time. If the rendering scene graph has been released, the + signal will be emitted again before the next frame is rendered. - \li The QQuickWindow::beforeSynchronizing() signal is emitted. - Applications can make direct connections (Qt::DirectConnection) - to this signal to do any preparation required before calls to - QQuickItem::updatePaintNode(). - - \li Synchronization of the QML state into the scene graph. This is - done by calling the QQuickItem::updatePaintNode() function on all - items that have changed since the previous frame. When a dedicated - rendering thread is used, the GUI thread is blocked during this - synchroniation. This is the only time the QML items and the nodes - in the scene graph interact. - - \li The window to be rendered is made current using - QOpenGLContext::makeCurrent(). - - \li The QQuickWindow::beforeRendering() signal is - emitted. Applications can make direct connections - (Qt::DirectConnection) to this signal to use custom OpenGL calls - which will then stack visually beneath the QML scene. - \li Items that have specified QSGNode::UsesPreprocess, will have their - QSGNode::preprocess() function invoked. + \section2 Integration with OpenGL - \li The QQuickWindow is cleared according to what is specified - using QQuickWindow::setClearBeforeRendering() and - QQuickWindow::setClearColor(). + It is possible to integrate OpenGL calls directly into the + QQuickWindow using the same OpenGL context as the Qt Quick Scene + Graph. This is done by connecting to the + QQuickWindow::beforeRendering() or QQuickWindow::afterRendering() + signal. - \li The scene graph is rendered. + \note When using QQuickWindow::beforeRendering(), make sure to + disable clearing before rendering with + QQuickWindow::setClearBeforeRendering(). - \li The QQuickWindow::afterRendering() signal is - emitted. Applications can make direct connections - (Qt::DirectConnection) to this signal to use custom OpenGL calls - which will then stack visually over the QML scene. - \li The rendered frame is swapped and QQuickWindow::frameSwapped() - is emitted. + \section2 Exposure and Visibility - \endlist - - All of the above happen on the rendering thread, when applicable. - - While the scene graph is being rendered on the rendering thread, the GUI will process animations - for the next frame. This means that as long as users are not using scene graph API - directly, the added complexity of a rendering thread can be completely ignored. - - When a QQuickWindow is programatically hidden with hide() or setVisible(false), it will - stop rendering and its scene graph and OpenGL context might be released. The - sceneGraphInvalidated() signal will be emitted when this happens. + When a QQuickWindow instance is deliberately hidden with hide() or + setVisible(false), it will stop rendering and its scene graph and + OpenGL context might be released. The sceneGraphInvalidated() + signal will be emitted when this happens. - \warning It is crucial that OpenGL operations and interaction with the scene graph happens - exclusively on the rendering thread, primarily during the updatePaintNode() phase. + \warning It is crucial that OpenGL operations and interaction with + the scene graph happens exclusively on the rendering thread, + primarily during the updatePaintNode() phase. - \warning As signals related to rendering might be emitted from the rendering thread, - connections should be made using Qt::DirectConnection + \warning As signals related to rendering might be emitted from the + rendering thread, connections should be made using + Qt::DirectConnection. \section2 Resource Management - QML will typically try to cache images, scene graph nodes, etc to improve performance, but in - some low-memory scenarios it might be required to aggressively release these resources. The - releaseResources() can be used to force clean up of certain resources. Calling releaseResources() - may result in the entire scene graph and its OpenGL context being deleted. The + QML will try to cache images and scene graph nodes to + improve performance, but in some low-memory scenarios it might be + required to aggressively release these resources. The + releaseResources() can be used to force the clean up of certain + resources. Calling releaseResources() may result in the entire + scene graph and its OpenGL context being deleted. The sceneGraphInvalidated() signal will be emitted when this happens. - \sa {OpenGL Under QML Example} + \sa {OpenGL Under QML} */ |