QComputeCommand allow to control the run behavior

It can either be Continuous, like it was until now or Manual.
When in manual mode, the compute shader will only be executed
by calling trigger()

Change-Id: Icaae24f4691ccd821297f967d564e7a883fa60b5
Reviewed-by: Sean Harmer <sean.harmer@kdab.com>

3 files changed, 117 insertions, 5 deletions

diff --git a/src/render/frontend/qcomputecommand.cpp b/src/render/frontend/qcomputecommand.cpp
index 5cb72a6ce..8b176cd4f 100644
--- a/src/render/frontend/qcomputecommand.cpp
+++ b/src/render/frontend/qcomputecommand.cpp
@@ -39,6 +39,7 @@
 
 #include "qcomputecommand.h"
 #include "qcomputecommand_p.h"
+#include <Qt3DCore/qpropertyupdatedchange.h>
 
 QT_BEGIN_NAMESPACE
 
@@ -75,12 +76,14 @@ namespace Qt3DRender {
     The compute shader is specified in the Material component of the same entity the
     ComputeCommand is added to. The workGroupX, workGroupY and workGroupZ properties
     specify the work group sizes for the compute shader invocation. DispatchCompute
-    node needs to be present in the FrameGraph to actually issue the commands.
+    node needs to be present in the FrameGraph to actually issue the commands. The execution behavior
+    of the compute command can be controlled with the run type property.
 
-    \note If the rendering policy is set to RenderSettings.OnDemand and there are no changes to the
-    scene, the ComputeCommand will not be invoked repeatedly.
-    The RenderSettings.Always render policy must be set for the ComputeCommand to be
-    repeatedly invoked if there are no other changes to the scene that triggers rendering a new
+    \note If the rendering policy is set to RenderSettings.OnDemand, the run
+    type is set to Continuous and there are no changes to the scene, the
+    ComputeCommand will not be invoked repeatedly. The RenderSettings.Always
+    render policy must be set for the ComputeCommand to be repeatedly invoked
+    if there are no other changes to the scene that triggers rendering a new
     frame.
  */
 
@@ -90,6 +93,19 @@ namespace Qt3DRender {
  */
 
 /*!
+    \qmlproperty QComputeCommand::runType
+
+    Specifies whether the compute command should be performed every frame or
+    manually triggered.
+
+    \value Continuous Compute command is executed everyframe. This is the
+    default.
+
+    \value Manual CompouteCommand is executed for a given number of frames and
+    then the component disables itself.
+ */
+
+/*!
     \qmlproperty int ComputeCommand::workGroupY
     Specifies Y workgroup size.
  */
@@ -114,12 +130,36 @@ namespace Qt3DRender {
     Specifies Z workgroup size.
  */
 
+/*!
+    \property QComputeCommand::runType
+
+    Specifies whether the compute command should be performed every frame or
+    manually triggered.
+
+    If set to Continuous, Compute command is executed everyframe. This is the
+    default.
+
+    If set to Manual CompouteCommand is executed for a given number of frames
+    and then the component disables itself.
+ */
+
 QComputeCommandPrivate::QComputeCommandPrivate()
     : Qt3DCore::QComponentPrivate()
     , m_workGroupX(1)
     , m_workGroupY(1)
     , m_workGroupZ(1)
+    , m_runType(QComputeCommand::Continuous)
+    , m_frameCount(0)
+{
+}
+
+void QComputeCommandPrivate::setFrameCount(int frameCount)
 {
+    m_frameCount = frameCount;
+    const auto propertyChange = Qt3DCore::QPropertyUpdatedChangePtr::create(m_id);
+    propertyChange->setPropertyName("frameCount");
+    propertyChange->setValue(m_frameCount);
+    notifyObservers(propertyChange);
 }
 
 /*!
@@ -154,6 +194,12 @@ int QComputeCommand::workGroupZ() const
     return d->m_workGroupZ;
 }
 
+QComputeCommand::RunType QComputeCommand::runType() const
+{
+    Q_D(const QComputeCommand);
+    return d->m_runType;
+}
+
 /*!
     Sets the workgroup for the first dimension to \a workGroupX.
  */
@@ -190,6 +236,50 @@ void QComputeCommand::setWorkGroupZ(int workGroupZ)
     }
 }
 
+void QComputeCommand::setRunType(QComputeCommand::RunType runType)
+{
+    Q_D(QComputeCommand);
+    if (d->m_runType != runType) {
+        d->m_runType = runType;
+        emit runTypeChanged();
+    }
+}
+
+/*!
+    When the run type is set to Manual, calling trigger will make the compute
+    command be executed for the next \a frameCount frames. Upon completion of
+    the execution, the enabled property will be set to false.
+ */
+void QComputeCommand::trigger(int frameCount)
+{
+    if (isEnabled())
+        qWarning() << Q_FUNC_INFO << "is triggered while it hasn't finished executing";
+
+    Q_D(QComputeCommand);
+    d->setFrameCount(frameCount);
+    setEnabled(true);
+}
+
+/*!
+    When the run type is set to Manual, calling trigger will make the compute
+    command be executed for the next \a frameCount frames. Upon completion of
+    the execution, the enabled property will be set to false. The size of the
+    workgroup previously set will be overridden with \a workGroupX, \a
+    workGroupY, \a workGroupZ.
+ */
+void QComputeCommand::trigger(int workGroupX, int workGroupY, int workGroupZ, int frameCount)
+{
+    if (isEnabled())
+        qWarning() << Q_FUNC_INFO << "is triggered while it hasn't finished executing";
+
+    setWorkGroupX(workGroupX);
+    setWorkGroupY(workGroupY);
+    setWorkGroupZ(workGroupZ);
+    Q_D(QComputeCommand);
+    d->setFrameCount(frameCount);
+    setEnabled(true);
+}
+
 Qt3DCore::QNodeCreatedChangeBasePtr QComputeCommand::createNodeCreationChange() const
 {
     auto creationChange = Qt3DCore::QNodeCreatedChangePtr<QComputeCommandData>::create(this);
@@ -198,6 +288,8 @@ Qt3DCore::QNodeCreatedChangeBasePtr QComputeCommand::createNodeCreationChange()
     data.workGroupX = d->m_workGroupX;
     data.workGroupY = d->m_workGroupY;
     data.workGroupZ = d->m_workGroupZ;
+    data.runType = d->m_runType;
+    data.frameCount = d->m_frameCount;
     return creationChange;
 }
 
diff --git a/src/render/frontend/qcomputecommand.h b/src/render/frontend/qcomputecommand.h
index c31082197..ad7f89a4d 100644
--- a/src/render/frontend/qcomputecommand.h
+++ b/src/render/frontend/qcomputecommand.h
@@ -55,24 +55,37 @@ class QT3DRENDERSHARED_EXPORT QComputeCommand : public Qt3DCore::QComponent
     Q_PROPERTY(int workGroupX READ workGroupX WRITE setWorkGroupX NOTIFY workGroupXChanged)
     Q_PROPERTY(int workGroupY READ workGroupY WRITE setWorkGroupY NOTIFY workGroupYChanged)
     Q_PROPERTY(int workGroupZ READ workGroupZ WRITE setWorkGroupZ NOTIFY workGroupZChanged)
+    Q_PROPERTY(RunType runType READ runType WRITE setRunType NOTIFY runTypeChanged REVISION 13)
 
 public:
+    enum RunType {
+        Continuous = 0,
+        Manual
+    };
+    Q_ENUM(RunType)
+
     explicit QComputeCommand(Qt3DCore::QNode *parent = nullptr);
     ~QComputeCommand();
 
     int workGroupX() const;
     int workGroupY() const;
     int workGroupZ() const;
+    RunType runType() const;
 
 public Q_SLOTS:
     void setWorkGroupX(int workGroupX);
     void setWorkGroupY(int workGroupY);
     void setWorkGroupZ(int workGroupZ);
+    void setRunType(RunType runType);
+
+    void trigger(int frameCount = 1);
+    void trigger(int workGroupX, int workGroupY, int workGroupZ, int frameCount = 1);
 
 Q_SIGNALS:
     void workGroupXChanged();
     void workGroupYChanged();
     void workGroupZChanged();
+    void runTypeChanged();
 
 private:
     Q_DECLARE_PRIVATE(QComputeCommand)
diff --git a/src/render/frontend/qcomputecommand_p.h b/src/render/frontend/qcomputecommand_p.h
index 874edb1fc..fc3376d5b 100644
--- a/src/render/frontend/qcomputecommand_p.h
+++ b/src/render/frontend/qcomputecommand_p.h
@@ -52,6 +52,7 @@
 //
 
 #include <Qt3DCore/private/qcomponent_p.h>
+#include <Qt3DRender/qcomputecommand.h>
 #include <Qt3DRender/private/qt3drender_global_p.h>
 
 QT_BEGIN_NAMESPACE
@@ -66,6 +67,10 @@ public:
     int m_workGroupX;
     int m_workGroupY;
     int m_workGroupZ;
+    QComputeCommand::RunType m_runType;
+    int m_frameCount;
+
+    void setFrameCount(int frameCount);
 };
 
 struct QComputeCommandData
@@ -73,6 +78,8 @@ struct QComputeCommandData
     int workGroupX;
     int workGroupY;
     int workGroupZ;
+    QComputeCommand::RunType runType;
+    int frameCount;
 };
 
 } // Qt3DRender