Studio3D: emit presentationReady on the first frame action only

...and add presentationLoaded that resembles how presentationReady worked
before. This is also good for API symmetry since Q3DSWidget and
Q3DSSurfaceViewer have presentationLoaded already (and no
presentationReady). We also get a presentationReady that's closer to
what's there in 1.1.

This way the HomeAutomation demo, already relying on presentationReady for
its splash screen, behaves much nicer on startup.

Task-number: QT3DS-1830
Change-Id: I7047d5347b5d8bf9f77faa7ea24648a964c4cc3a
Reviewed-by: Andy Nichols <andy.nichols@qt.io>

2 files changed, 25 insertions, 2 deletions

diff --git a/src/imports/studio3d/q3dsstudio3ditem.cpp b/src/imports/studio3d/q3dsstudio3ditem.cpp
index 270de10..16e1ab4 100644
--- a/src/imports/studio3d/q3dsstudio3ditem.cpp
+++ b/src/imports/studio3d/q3dsstudio3ditem.cpp
@@ -121,12 +121,27 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \qmlsignal Studio3D::presentationReady()
+    \qmlsignal Studio3D::presentationLoaded()
 
     This signal is emitted when the presentation has been loaded and is ready
     to be shown.
 */
 
+/*!
+    \qmlsignal Studio3D::presentationReady()
+
+    This signal is emitted when the presentation has fully initialized its 3D
+    scene for the first frame.
+
+    The difference to presentationLoaded() is that this signal is emitted only
+    when the asynchronous operations needed to build to 3D scene and the first
+    frame have completed.
+
+    When implementing splash screens via Loader items and the Item::visible
+    property, this is the signal that should be used to trigger hiding the
+    splash screen.
+*/
+
 static bool engineCleanerRegistered = false;
 static QSet<Q3DSEngine *> engineTracker;
 static void engineCleaner()
@@ -355,13 +370,19 @@ void Q3DSStudio3DItem::createEngine()
                 m_running = true;
                 emit runningChanged();
             }
-            emit presentationReady();
+            emit presentationLoaded();
         });
         connect(m_engine, &Q3DSEngine::nextFrameStarting, this, [this]() {
+            if (m_needsPresReadySignal) {
+                m_needsPresReadySignal = false;
+                emit presentationReady();
+            }
             emit frameUpdate();
         });
     }
 
+    m_needsPresReadySignal = true;
+
     const QString fn = QQmlFile::urlToLocalFileOrQrc(m_source);
     qCDebug(lcStudio3D) << "source is now" << fn;
     const QSize sz(width(), height());
diff --git a/src/imports/studio3d/q3dsstudio3ditem_p.h b/src/imports/studio3d/q3dsstudio3ditem_p.h
index 042691c..fcd6da2 100644
--- a/src/imports/studio3d/q3dsstudio3ditem_p.h
+++ b/src/imports/studio3d/q3dsstudio3ditem_p.h
@@ -84,6 +84,7 @@ signals:
     void runningChanged();
     void errorChanged();
     void ignoredEventsChanged();
+    void presentationLoaded();
     void presentationReady();
     void frameUpdate();
 
@@ -131,6 +132,7 @@ private:
     bool m_running = false;
     QString m_error;
     EventIgnoreFlags m_eventIgnoreFlags;
+    bool m_needsPresReadySignal = true;
 };
 
 Q_DECLARE_OPERATORS_FOR_FLAGS(Q3DSStudio3DItem::EventIgnoreFlags)