Add public API for working with jobs

Existing jobs used private API for doing work after jobs were run or
controlling if running was required or not.

Make this public so that new jobs in custom aspects don't need to
use private API.

Unfortunately, this requires changing the signature of one public
method that mistakenly was using a private class as a parameter.

Change-Id: Ie8315a0f98ec48f84650163b4ac713e7e6845a92
Reviewed-by: Paul Lemire <paul.lemire@kdab.com>

9 files changed, 75 insertions, 9 deletions

diff --git a/src/core/aspects/qabstractaspect.cpp b/src/core/aspects/qabstractaspect.cpp
index 1e88e6216..f01124e19 100644
--- a/src/core/aspects/qabstractaspect.cpp
+++ b/src/core/aspects/qabstractaspect.cpp
@@ -393,6 +393,28 @@ void QAbstractAspect::onEngineShutdown()
 {
 }
 
+/*!
+ * Called in the main thread once all the jobs have been executed.
+ *
+ * \note This is called after QAspectJob::postFrame is called on every jobs.
+ *
+ * \sa QAspectJob::postFrame
+ */
+void QAbstractAspect::jobsDone()
+{
+    Q_D(QAbstractAspect);
+    d->jobsDone();
+}
+
+/*!
+ * Called in the main thread when the frame processing is complete.
+ */
+void QAbstractAspect::frameDone()
+{
+    Q_D(QAbstractAspect);
+    d->frameDone();
+}
+
 void QAbstractAspect::scheduleSingleShotJob(const Qt3DCore::QAspectJobPtr &job)
 {
     Q_D(QAbstractAspect);
diff --git a/src/core/aspects/qabstractaspect.h b/src/core/aspects/qabstractaspect.h
index e15b987c1..4dcc59cec 100644
--- a/src/core/aspects/qabstractaspect.h
+++ b/src/core/aspects/qabstractaspect.h
@@ -93,9 +93,13 @@ private:
     virtual void onEngineStartup();
     virtual void onEngineShutdown();
 
+    virtual void jobsDone();
+    virtual void frameDone();
+
     Q_DECLARE_PRIVATE(QAbstractAspect)
     friend class QAspectEngine;
     friend class QAspectManager;
+    friend class QScheduler;
 };
 
 template<class Frontend>
diff --git a/src/core/aspects/qaspectengine.cpp b/src/core/aspects/qaspectengine.cpp
index d73771910..946355d05 100644
--- a/src/core/aspects/qaspectengine.cpp
+++ b/src/core/aspects/qaspectengine.cpp
@@ -425,6 +425,18 @@ void QAspectEngine::processFrame()
     d->m_aspectManager->processFrame();
 }
 
+QNode *QAspectEngine::lookupNode(QNodeId id) const
+{
+    Q_D(const QAspectEngine);
+    return d->m_scene ? d->m_scene->lookupNode(id) : nullptr;
+}
+
+QVector<QNode *> QAspectEngine::lookupNodes(const QVector<QNodeId> &ids) const
+{
+    Q_D(const QAspectEngine);
+    return d->m_scene ? d->m_scene->lookupNodes(ids) : QVector<QNode *>{};
+}
+
 /*!
  * Sets the \a root entity for the aspect engine.
  */
diff --git a/src/core/aspects/qaspectengine.h b/src/core/aspects/qaspectengine.h
index 1d5d7e220..ac34e0c54 100644
--- a/src/core/aspects/qaspectengine.h
+++ b/src/core/aspects/qaspectengine.h
@@ -41,6 +41,7 @@
 #define QT3DCORE_QASPECTENGINE_H
 
 #include <Qt3DCore/qt3dcore_global.h>
+#include <Qt3DCore/qnodeid.h>
 #include <QtCore/QObject>
 #include <QtCore/QVector>
 
@@ -86,6 +87,9 @@ public:
 
     void processFrame();
 
+    QNode *lookupNode(QNodeId id) const;
+    QVector<QNode *> lookupNodes(const QVector<QNodeId> &ids) const;
+
 private:
     Q_DECLARE_PRIVATE(QAspectEngine)
 };
diff --git a/src/core/aspects/qaspectmanager.cpp b/src/core/aspects/qaspectmanager.cpp
index e93902c54..aac209588 100644
--- a/src/core/aspects/qaspectmanager.cpp
+++ b/src/core/aspects/qaspectmanager.cpp
@@ -541,7 +541,7 @@ void QAspectManager::processFrame()
 
     // Tell the aspect the frame is complete (except rendering)
     for (QAbstractAspect *aspect : qAsConst(m_aspects))
-        QAbstractAspectPrivate::get(aspect)->frameDone();
+        aspect->frameDone();
 }
 
 } // namespace Qt3DCore
diff --git a/src/core/aspects/qaspectmanager_p.h b/src/core/aspects/qaspectmanager_p.h
index e0aefdfde..d3b3992fe 100644
--- a/src/core/aspects/qaspectmanager_p.h
+++ b/src/core/aspects/qaspectmanager_p.h
@@ -88,6 +88,9 @@ public:
     explicit QAspectManager(QAspectEngine *parent = nullptr);
     ~QAspectManager();
 
+    QAspectEngine * engine() const { return  m_engine; }
+    QScheduler *scheduler() const { return m_scheduler; }
+
     void setRunMode(QAspectEngine::RunMode mode);
     void enterSimulationLoop();
     void exitSimulationLoop();
diff --git a/src/core/jobs/qaspectjob.cpp b/src/core/jobs/qaspectjob.cpp
index 0a2ee9841..557756581 100644
--- a/src/core/jobs/qaspectjob.cpp
+++ b/src/core/jobs/qaspectjob.cpp
@@ -40,6 +40,9 @@
 #include "qaspectjob.h"
 #include "qaspectjob_p.h"
 
+#include <Qt3DCore/qaspectengine.h>
+#include <Qt3DCore/private/qaspectengine_p.h>
+
 #include <QtCore/QByteArray>
 
 QT_BEGIN_NAMESPACE
@@ -91,7 +94,7 @@ QAspectJob::QAspectJob()
 
 /*!
  * \fn void Qt3DCore::QAspectJob::run()
- * Executes the job.
+ * Executes the job. This is called on a separate thread by the scheduler.
  */
 
 /*!
@@ -146,11 +149,28 @@ QVector<QWeakPointer<QAspectJob> > QAspectJob::dependencies() const
     return d->m_dependencies;
 }
 
-void QAspectJob::postFrame(QAspectManager *aspectManager)
+/*!
+ * This is called, in the main thread, when all the jobs have completed.
+ * It's a good point to push changes back to the frontend.
+ */
+void QAspectJob::postFrame(QAspectEngine *aspectEngine)
+{
+    Q_D(QAspectJob);
+    if (aspectEngine) {
+        auto manager = QAspectEnginePrivate::get(aspectEngine)->m_aspectManager;
+        d->postFrame(manager);
+    }
+}
+
+/*!
+ * Should return true (default) if the job has actually something to do.
+ * If returning false, the job will not be scheduled (but it's dependencies
+ * will be).
+ */
+bool QAspectJob::isRequired()
 {
     Q_D(QAspectJob);
-    if (aspectManager)
-        d->postFrame(aspectManager);
+    return d->isRequired();
 }
 
 } // namespace Qt3DCore
diff --git a/src/core/jobs/qaspectjob.h b/src/core/jobs/qaspectjob.h
index 7cc784e0f..c618c3c19 100644
--- a/src/core/jobs/qaspectjob.h
+++ b/src/core/jobs/qaspectjob.h
@@ -49,7 +49,7 @@ QT_BEGIN_NAMESPACE
 namespace Qt3DCore {
 
 class QAspectJobPrivate;
-class QAspectManager;
+class QAspectEngine;
 
 class Q_3DCORESHARED_EXPORT QAspectJob
 {
@@ -63,7 +63,8 @@ public:
     QVector<QWeakPointer<QAspectJob> > dependencies() const;
 
     virtual void run() = 0;
-    void postFrame(QAspectManager *aspectManager);
+    virtual void postFrame(QAspectEngine *aspectEngine);
+    virtual bool isRequired();
 
 protected:
     explicit QAspectJob(QAspectJobPrivate &dd);
diff --git a/src/core/qscheduler.cpp b/src/core/qscheduler.cpp
index c52445a35..6c63fc1c1 100644
--- a/src/core/qscheduler.cpp
+++ b/src/core/qscheduler.cpp
@@ -140,10 +140,10 @@ int QScheduler::scheduleAndWaitForFrameAspectJobs(qint64 time, bool dumpJobs)
         QTaskLogger logger(m_aspectManager->serviceLocator()->systemInformation(), 4097, 0, QTaskLogger::AspectJob);
 
         for (auto &job : qAsConst(jobQueue))
-            QAspectJobPrivate::get(job.data())->postFrame(m_aspectManager);
+            job->postFrame(m_aspectManager->engine());
 
         for (QAbstractAspect *aspect : aspects)
-            QAbstractAspectPrivate::get(aspect)->jobsDone();
+            aspect->jobsDone();
     }
 
     return totalJobs;