Merge remote-tracking branch 'origin/5.15' into dev

Change-Id: I6f320ea43b5837444226228c118e57c4bda8702a

8 files changed, 108 insertions, 10 deletions

diff --git a/src/qml/doc/src/qmlfunctions.qdoc b/src/qml/doc/src/qmlfunctions.qdoc
index 04d907f168..0ff0de1ef9 100644
--- a/src/qml/doc/src/qmlfunctions.qdoc
+++ b/src/qml/doc/src/qmlfunctions.qdoc
@@ -906,7 +906,7 @@
 */
 
 /*!
-   \fn template<typename T> auto qmlRegisterSingletonInstance(const char *uri, int versionMajor, int versionMinor, const char *typeName, T *cppObject)
+   \fn int qmlRegisterSingletonInstance(const char *uri, int versionMajor, int versionMinor, const char *typeName, QObject *cppObject)
    \relates QQmlEngine
    \since 5.14
 
diff --git a/src/qml/qml/qqml.h b/src/qml/qml/qqml.h
index 7404a62d23..524af7181c 100644
--- a/src/qml/qml/qqml.h
+++ b/src/qml/qml/qqml.h
@@ -736,9 +736,14 @@ inline int qmlRegisterSingletonType(const char *uri, int versionMajor, int versi
     return QQmlPrivate::qmlregister(QQmlPrivate::SingletonRegistration, &api);
 }
 
+#ifdef Q_QDOC
+int qmlRegisterSingletonInstance(const char *uri, int versionMajor, int versionMinor,
+                                 const char *typeName, QObject *cppObject)
+#else
 template<typename T>
 inline auto qmlRegisterSingletonInstance(const char *uri, int versionMajor, int versionMinor,
                                          const char *typeName, T *cppObject) -> typename std::enable_if<std::is_base_of<QObject, T>::value, int>::type
+#endif
 {
     QQmlPrivate::SingletonFunctor registrationFunctor;
     registrationFunctor.m_object = cppObject;
diff --git a/src/quick/items/qquickwindow.cpp b/src/quick/items/qquickwindow.cpp
index 81eabe0591..acf6fd68c8 100644
--- a/src/quick/items/qquickwindow.cpp
+++ b/src/quick/items/qquickwindow.cpp
@@ -433,7 +433,7 @@ void QQuickWindowPrivate::syncSceneGraph()
     if (renderTargetId && !QQuickRenderControl::renderWindowFor(q))
         devicePixelRatio = 1;
 
-    context->prepareSync(devicePixelRatio);
+    context->prepareSync(devicePixelRatio, rhi ? swapchain->currentFrameCommandBuffer() : nullptr);
 
     animationController->beforeNodeSync();
 
@@ -3872,6 +3872,13 @@ bool QQuickWindow::isSceneGraphInitialized() const
     This signal will be emitted from the scene graph rendering thread.
 */
 
+/*!
+    \qmlsignal QtQuick.Window::Window::frameSwapped()
+
+    This signal is emitted when a frame has been queued for presenting. With
+    vertical synchronization enabled the signal is emitted at most once per
+    vsync interval in a continuously animating scene.
+ */
 
 /*!
     \fn void QQuickWindow::sceneGraphInitialized()
@@ -3879,9 +3886,12 @@ bool QQuickWindow::isSceneGraphInitialized() const
     This signal is emitted when the scene graph has been initialized.
 
     This signal will be emitted from the scene graph rendering thread.
-
  */
 
+/*!
+    \qmlsignal QtQuick.Window::Window::sceneGraphInitialized()
+    \internal
+ */
 
 /*!
     \fn void QQuickWindow::sceneGraphInvalidated()
@@ -3901,6 +3911,11 @@ bool QQuickWindow::isSceneGraphInitialized() const
  */
 
 /*!
+    \qmlsignal QtQuick.Window::Window::sceneGraphInvalidated()
+    \internal
+ */
+
+/*!
     \fn void QQuickWindow::sceneGraphError(SceneGraphError error, const QString &message)
 
     This signal is emitted when an \a error occurred during scene graph initialization.
@@ -3916,6 +3931,19 @@ bool QQuickWindow::isSceneGraphInitialized() const
  */
 
 /*!
+    \qmlsignal QtQuick.Window::Window::sceneGraphError(SceneGraphError error, QString message)
+
+    This signal is emitted when an \a error occurred during scene graph initialization.
+
+    You can implement onSceneGraphError(error, message) to handle errors,
+    such as graphics context creation failures, in a custom way.
+    If no handler is connected to this signal, Quick will print the \a message,
+    or show a message box, and terminate the application.
+
+    \since 5.3
+ */
+
+/*!
     \class QQuickCloseEvent
     \internal
     \since 5.1
@@ -4260,6 +4288,11 @@ QQmlIncubationController *QQuickWindow::incubationController() const
 */
 
 /*!
+    \qmlsignal QtQuick.Window::Window::beforeSynchronizing()
+    \internal
+*/
+
+/*!
     \fn void QQuickWindow::afterSynchronizing()
 
     This signal is emitted after the scene graph is synchronized with the QML state.
@@ -4283,6 +4316,12 @@ QQmlIncubationController *QQuickWindow::incubationController() const
  */
 
 /*!
+    \qmlsignal QtQuick.Window::Window::afterSynchronizing()
+    \internal
+    \since 5.3
+ */
+
+/*!
     \fn void QQuickWindow::beforeRendering()
 
     This signal is emitted before the scene starts rendering.
@@ -4318,6 +4357,11 @@ QQmlIncubationController *QQuickWindow::incubationController() const
 */
 
 /*!
+    \qmlsignal QtQuick.Window::Window::beforeRendering()
+    \internal
+*/
+
+/*!
     \fn void QQuickWindow::afterRendering()
 
     This signal is emitted after the scene has completed rendering, before swapbuffers is called.
@@ -4351,6 +4395,11 @@ QQmlIncubationController *QQuickWindow::incubationController() const
  */
 
 /*!
+    \qmlsignal QtQuick.Window::Window::afterRendering()
+    \internal
+ */
+
+/*!
     \fn void QQuickWindow::beforeRenderPassRecording()
 
     This signal is emitted before the scenegraph starts recording commands for
@@ -4383,6 +4432,12 @@ QQmlIncubationController *QQuickWindow::incubationController() const
 */
 
 /*!
+    \qmlsignal QtQuick.Window::Window::beforeRenderPassRecording()
+    \internal
+    \since 5.14
+*/
+
+/*!
     \fn void QQuickWindow::afterRenderPassRecording()
 
     This signal is emitted after the scenegraph has recorded the commands for
@@ -4414,6 +4469,12 @@ QQmlIncubationController *QQuickWindow::incubationController() const
 */
 
 /*!
+    \qmlsignal QtQuick.Window::Window::afterRenderPassRecording()
+    \internal
+    \since 5.14
+*/
+
+/*!
     \fn void QQuickWindow::afterAnimating()
 
     This signal is emitted on the gui thread before requesting the render thread to
@@ -4428,6 +4489,17 @@ QQmlIncubationController *QQuickWindow::incubationController() const
  */
 
 /*!
+    \qmlsignal QtQuick.Window::Window::afterAnimating()
+
+    This signal is emitted on the gui thread before requesting the render thread to
+    perform the synchronization of the scene graph.
+
+    You can implement onAfterAnimating to do additional processing after each animation step.
+
+    \since 5.3
+ */
+
+/*!
     \fn void QQuickWindow::openglContextCreated(QOpenGLContext *context)
 
     This signal is emitted on the gui thread when the OpenGL \a context
@@ -4450,6 +4522,12 @@ QQmlIncubationController *QQuickWindow::incubationController() const
  */
 
 /*!
+    \qmlsignal QtQuick.Window::Window::openglContextCreated()
+    \internal
+    \since 5.3
+ */
+
+/*!
     \fn void QQuickWindow::sceneGraphAboutToStop()
 
     This signal is emitted on the render thread when the scene graph is
@@ -4472,6 +4550,11 @@ QQmlIncubationController *QQuickWindow::incubationController() const
     \since 5.3
  */
 
+/*!
+    \qmlsignal QtQuick.Window::Window::sceneGraphAboutToStop()
+    \internal
+    \since 5.3
+ */
 
 /*!
     Sets whether the scene graph rendering of QML should clear the color buffer
diff --git a/src/quick/scenegraph/coreapi/qsgtexture.cpp b/src/quick/scenegraph/coreapi/qsgtexture.cpp
index 486fe50190..df6f5cffe6 100644
--- a/src/quick/scenegraph/coreapi/qsgtexture.cpp
+++ b/src/quick/scenegraph/coreapi/qsgtexture.cpp
@@ -842,11 +842,15 @@ void QSGTexturePrivate::updateRhiTexture(QRhi *rhi, QRhiResourceUpdateBatch *res
 /*!
     \fn bool QSGDynamicTexture::updateTexture()
 
-    Call this function to explicitly update the dynamic texture. Calling bind() will bind
-    the content that was previously updated.
+    Call this function to explicitly update the dynamic texture.
 
     The function returns true if the texture was changed as a resul of the update; otherwise
     returns false.
+
+    \note This function is typically called from QQuickItem::updatePaintNode()
+    or QSGNode::preprocess(), meaning during the \c{synchronization} or the
+    \c{node preprocessing} phases of the scenegraph. Calling it at other times
+    is discouraged and can lead to unexpected behavior.
  */
 
 /*!
diff --git a/src/quick/scenegraph/qsgcontext.cpp b/src/quick/scenegraph/qsgcontext.cpp
index 17eb1e312c..e3c951e5ed 100644
--- a/src/quick/scenegraph/qsgcontext.cpp
+++ b/src/quick/scenegraph/qsgcontext.cpp
@@ -341,9 +341,10 @@ void QSGRenderContext::invalidate()
 {
 }
 
-void QSGRenderContext::prepareSync(qreal devicePixelRatio)
+void QSGRenderContext::prepareSync(qreal devicePixelRatio, QRhiCommandBuffer *cb)
 {
     Q_UNUSED(devicePixelRatio);
+    Q_UNUSED(cb);
 }
 
 void QSGRenderContext::beginNextFrame(QSGRenderer *renderer,
diff --git a/src/quick/scenegraph/qsgcontext_p.h b/src/quick/scenegraph/qsgcontext_p.h
index 244bcfabd1..d389420907 100644
--- a/src/quick/scenegraph/qsgcontext_p.h
+++ b/src/quick/scenegraph/qsgcontext_p.h
@@ -174,7 +174,7 @@ public:
 
     using RenderPassCallback = void (*)(void *);
 
-    virtual void prepareSync(qreal devicePixelRatio);
+    virtual void prepareSync(qreal devicePixelRatio, QRhiCommandBuffer *cb);
     virtual void beginNextFrame(QSGRenderer *renderer,
                                 RenderPassCallback mainPassRecordingStart,
                                 RenderPassCallback mainPassRecordingEnd,
diff --git a/src/quick/scenegraph/qsgdefaultrendercontext.cpp b/src/quick/scenegraph/qsgdefaultrendercontext.cpp
index ae227a0106..14314b2c94 100644
--- a/src/quick/scenegraph/qsgdefaultrendercontext.cpp
+++ b/src/quick/scenegraph/qsgdefaultrendercontext.cpp
@@ -200,9 +200,14 @@ void QSGDefaultRenderContext::invalidate()
     emit invalidated();
 }
 
-void QSGDefaultRenderContext::prepareSync(qreal devicePixelRatio)
+void QSGDefaultRenderContext::prepareSync(qreal devicePixelRatio, QRhiCommandBuffer *cb)
 {
     m_currentDevicePixelRatio = devicePixelRatio;
+
+    // we store the command buffer already here, in case there is something in
+    // an updatePaintNode() implementation that leads to needing it (for
+    // example, an updateTexture() call on a QSGRhiLayer)
+    m_currentFrameCommandBuffer = cb;
 }
 
 static QBasicMutex qsg_framerender_mutex;
@@ -244,7 +249,7 @@ void QSGDefaultRenderContext::beginNextRhiFrame(QSGRenderer *renderer, QRhiRende
     renderer->setCommandBuffer(cb);
     renderer->setRenderPassRecordingCallbacks(mainPassRecordingStart, mainPassRecordingEnd, callbackUserData);
 
-    m_currentFrameCommandBuffer = cb;
+    m_currentFrameCommandBuffer = cb; // usually the same as what was passed to prepareSync() but cannot count on that having been called
     m_currentFrameRenderPass = rp;
 }
 
diff --git a/src/quick/scenegraph/qsgdefaultrendercontext_p.h b/src/quick/scenegraph/qsgdefaultrendercontext_p.h
index 2fdb3a48dd..97ed681f9a 100644
--- a/src/quick/scenegraph/qsgdefaultrendercontext_p.h
+++ b/src/quick/scenegraph/qsgdefaultrendercontext_p.h
@@ -104,7 +104,7 @@ public:
     void initialize(const QSGRenderContext::InitParams *params) override;
     void invalidate() override;
 
-    void prepareSync(qreal devicePixelRatio) override;
+    void prepareSync(qreal devicePixelRatio, QRhiCommandBuffer *cb) override;
     void beginNextFrame(QSGRenderer *renderer,
                         RenderPassCallback mainPassRecordingStart,
                         RenderPassCallback mainPassRecordingEnd,