Discard datainput set value if it is the same as the last committed value

Store the latest value that was committed (sent out to runtime engine) and
only create setValue call when the incoming value is actually different.
Combined with batching, this should eliminate most performance impacts from
client-side API spamming.

Also, add "force" parameter to setValue C++ interface. It can be used
to force a value change to runtime engine even if the value would be
otherwise discarded.

Change-Id: Iedd4df89a0d45b79f306dfd384745a94df8f26be
Task-id: QT3DS-3861
Task-id: QT3DS-3842
Reviewed-by: Mahmoud Badri <mahmoud.badri@qt.io>
Reviewed-by: Tomi Korpipää <tomi.korpipaa@qt.io>

5 files changed, 55 insertions, 24 deletions

diff --git a/src/api/studio3d/q3dsdatainput.cpp b/src/api/studio3d/q3dsdatainput.cpp
index f3a1bad..232fd0e 100644
--- a/src/api/studio3d/q3dsdatainput.cpp
+++ b/src/api/studio3d/q3dsdatainput.cpp
@@ -218,9 +218,7 @@ void Q3DSDataInput::setName(const QString &name)
     Q3DSDataInput instance. If the value of the same data input in the
     presentation is changed elsewhere, for example via animations or
     Q3DSPresentation::setAttribute(), those changes are not reflected in the
-    value of this property. Due to this uncertainty, this property treats all
-    value sets as changes even if the newly set value is the same value as the
-    previous value.
+    value of this property.
 
     To get actual values from the presentation, use DataOutput.
     \sa DataOutput
@@ -235,9 +233,7 @@ void Q3DSDataInput::setName(const QString &name)
     Q3DSDataInput instance. If the value of the same data input in the
     presentation is changed elsewhere, for example via animations or
     Q3DSPresentation::setAttribute(), those changes are not reflected in the
-    value of this property. Due to this uncertainty, this property treats all
-    value sets as changes even if the newly set value is the same value as the
-    previous value.
+    value of this property.
 
     To get actual values from the presentation, use DataOutput.
     \sa DataOutput
@@ -338,17 +334,22 @@ QStringList Q3DSDataInput::metadataKeys() const
 
 /*!
     \brief Q3DSDataInput::setValue Set a new \a value for this data input.
-    \note For performance reasons do not call setValue unnecessarily.
+
+    SetValue calls are batched within a single frame period. The most recently set \a value will be
+    used to commit a change event for the runtime engine at the end of frame period. By default,
+    a change event is only created if the new \a value is actually different from the previous
+    frame's committed value.
+
+    Use \a force parameter to force commit a change. This can be useful in situations where the
+    target element property is being changed by several controllers, and the caller wants to be
+    certain that value change will be processed. Note that animations take precedence over
+    datainput control.
+
+    \note For performance reasons do not call setValue with \a force set to true unnecessarily.
  */
-void Q3DSDataInput::setValue(const QVariant &value)
+void Q3DSDataInput::setValue(const QVariant &value, bool force)
 {
-    // Since properties controlled by data inputs can change without the current value being
-    // reflected on the value of the DataInput element, we allow setting the value to the
-    // same one it was previously and still consider it a change.
-    // For example, when controlling timeline, the value set to DataInput will only be
-    // the current value for one frame if presentation has a running animation.
-    // In order to track an element property, see DataOutput API.
-    d_ptr->setValue(value);
+    d_ptr->setValue(value, force);
     Q_EMIT valueChanged();
 }
 
@@ -362,6 +363,11 @@ void Q3DSDataInputPrivate::setDirty(bool dirty)
     m_dirty = dirty;
 }
 
+void Q3DSDataInputPrivate::setCommittedValue(const QVariant &value)
+{
+    m_committedValue = value;
+}
+
 Q3DSDataInputPrivate::Q3DSDataInputPrivate(Q3DSDataInput *parent)
     : q_ptr(parent)
 {
@@ -373,13 +379,18 @@ Q3DSDataInputPrivate::~Q3DSDataInputPrivate()
         m_presentation->unregisterDataInput(q_ptr);
 }
 
-void Q3DSDataInputPrivate::setValue(const QVariant &value)
+void Q3DSDataInputPrivate::setValue(const QVariant &value, bool force)
 {
+    // Was there a force set at some point during this frame? If so, then inherit force flag
+    // to all value set calls after it so that we do not discard the forced change.
+    if (!m_forced)
+        m_forced = force;
+
     m_value = value;
     setDirty(true);
 
     if (m_presentation)
-        m_presentation->setDataInputValue(m_name, m_value);
+        m_presentation->setDataInputValue(m_name, m_value, m_forced);
 }
 
 void Q3DSDataInputPrivate::setViewerApp(Q3DSViewer::Q3DSViewerApp *app)
diff --git a/src/api/studio3d/q3dsdatainput.h b/src/api/studio3d/q3dsdatainput.h
index 8ca46b7..8d6cff7 100644
--- a/src/api/studio3d/q3dsdatainput.h
+++ b/src/api/studio3d/q3dsdatainput.h
@@ -68,7 +68,7 @@ public:
 
 public Q_SLOTS:
     void setName(const QString &name);
-    void setValue(const QVariant &value);
+    void setValue(const QVariant &value, bool force = false);
 
 Q_SIGNALS:
     void nameChanged();
diff --git a/src/api/studio3d/q3dsdatainput_p.h b/src/api/studio3d/q3dsdatainput_p.h
index 022c815..546e06a 100644
--- a/src/api/studio3d/q3dsdatainput_p.h
+++ b/src/api/studio3d/q3dsdatainput_p.h
@@ -56,11 +56,13 @@ public:
     explicit Q3DSDataInputPrivate(Q3DSDataInput *parent);
     virtual ~Q3DSDataInputPrivate();
 
-    void setValue(const QVariant &value);
+    void setValue(const QVariant &value, bool force = false);
     void setViewerApp(Q3DSViewer::Q3DSViewerApp *app);
     void setCommandQueue(CommandQueue *queue);
     void setPresentation(Q3DSPresentation *presentation);
     void setDirty(bool dirty);
+    // Used by presentation to indicate which is the latest committed (not cached locally) value.
+    void setCommittedValue(const QVariant &value);
 
 protected:
     Q3DSDataInput *q_ptr;
@@ -75,6 +77,9 @@ protected:
     float m_min = 0;
 
     bool m_dirty = false;
+    bool m_forced = false;
+
+    QVariant m_committedValue; // Latest value that was committed to runtime engine
 
     // Note: Qt3d Runtime allows metadata to be both read and set, therefore requiring
     // internal representation of both keys and values to be QVariant as per API convention.
diff --git a/src/api/studio3d/q3dspresentation.cpp b/src/api/studio3d/q3dspresentation.cpp
index 4a8c402..9484792 100644
--- a/src/api/studio3d/q3dspresentation.cpp
+++ b/src/api/studio3d/q3dspresentation.cpp
@@ -843,12 +843,22 @@ void Q3DSPresentation::setGlobalAnimationTime(qint64 milliseconds)
     is also an alternative to the goToSlide() and goToTime() family of APIs and
     to Q3DSSceneElement.
 
+    Use \a force parameter to always create a change event. (The default behavior
+    for datainput is to only forward the change event to runtime engine if the set
+    value differs from the previously committed value.) Note that property changes
+    from animations take precedence over datainput control regardless of force parameter.
+
     \sa DataInput
  */
-void Q3DSPresentation::setDataInputValue(const QString &name, const QVariant &value)
+void Q3DSPresentation::setDataInputValue(const QString &name, const QVariant &value, bool force)
 {
-    // Set directly to avoid loop between Q3DSDataInput and Q3DSPresentation value setters
+    // Set directly to avoid loop between Q3DSDataInput and Q3DSPresentation value setters.
     d_ptr->m_dataInputs[name]->d_ptr->m_value = value;
+
+    // If we have had forced set during this frame, inherit force flag to all subsequent setters.
+    if (!d_ptr->m_dataInputs[name]->d_ptr->m_forced)
+        d_ptr->m_dataInputs[name]->d_ptr->m_forced = force;
+
     d_ptr->setDataInputDirty(name, true);
     // We batch datainput changes within a frame, so just tell the presentation that one
     // or more datainputs have changed value.
@@ -1937,8 +1947,13 @@ void Q3DSPresentationPrivate::setDataInputValueBatch()
     QVector<QPair<QString, QVariant>> *theProperties = new QVector<QPair<QString, QVariant>>();
     for (const auto &di : qAsConst(m_dataInputs)) {
         if (di->d_ptr->m_dirty) {
-            theProperties->append({di->name(), di->value()});
-            di->d_ptr->m_dirty = false;
+            if (di->value() != di->d_ptr->m_committedValue || di->d_ptr->m_forced) {
+                theProperties->append({di->name(), di->value()});
+                di->d_ptr->m_dirty = false;
+                di->d_ptr->m_forced = false; // Reset also forced flag as it is per-frame.
+                di->d_ptr->setCommittedValue(di->value()); // Make note of value that was actually
+                                                           // forwarded to runtime engine.
+            }
         }
     }
 
diff --git a/src/api/studio3d/q3dspresentation.h b/src/api/studio3d/q3dspresentation.h
index 535ba40..91e76c5 100644
--- a/src/api/studio3d/q3dspresentation.h
+++ b/src/api/studio3d/q3dspresentation.h
@@ -130,7 +130,7 @@ public Q_SLOTS:
     void setPresentationActive(const QString &id, bool active);
     void fireEvent(const QString &elementPath, const QString &eventName);
     void setGlobalAnimationTime(qint64 milliseconds);
-    void setDataInputValue(const QString &name, const QVariant &value);
+    void setDataInputValue(const QString &name, const QVariant &value, bool force = false);
 
 Q_SIGNALS:
     void variantListChanged(const QStringList &variantList);