Add QNodeCommand

Adding QNodeCommand to send commands between a node
and it’s backend, and back.
Contains a command name and data as a QVariant.
Also has an integer id so replies can be related to the
original command.

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

9 files changed, 391 insertions, 2 deletions

diff --git a/src/core/changes/changes.pri b/src/core/changes/changes.pri
index 49d560a56..11d66a83e 100644
--- a/src/core/changes/changes.pri
+++ b/src/core/changes/changes.pri
@@ -35,7 +35,9 @@ HEADERS += \
     $$PWD/qpropertyvalueaddedchange.h \
     $$PWD/qpropertyvalueaddedchange_p.h \
     $$PWD/qpropertyvalueremovedchange.h \
-    $$PWD/qpropertyvalueremovedchange_p.h
+    $$PWD/qpropertyvalueremovedchange_p.h \
+    $$PWD/qnodecommand.h \
+    $$PWD/qnodecommand_p.h
 
 SOURCES += \
     $$PWD/qscenechange.cpp \
@@ -54,4 +56,5 @@ SOURCES += \
     $$PWD/qpropertynodeaddedchange.cpp \
     $$PWD/qpropertynoderemovedchange.cpp \
     $$PWD/qpropertyvalueaddedchange.cpp \
-    $$PWD/qpropertyvalueremovedchange.cpp
+    $$PWD/qpropertyvalueremovedchange.cpp \
+    $$PWD/qnodecommand.cpp
diff --git a/src/core/changes/qnodecommand.cpp b/src/core/changes/qnodecommand.cpp
new file mode 100644
index 000000000..fc7e01697
--- /dev/null
+++ b/src/core/changes/qnodecommand.cpp
@@ -0,0 +1,151 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 Klaralvdalens Datakonsult AB (KDAB).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the Qt3D module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL3$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/contact-us.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 3 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPLv3 included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 3 requirements
+** will be met: https://www.gnu.org/licenses/lgpl.html.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 2.0 or later as published by the Free
+** Software Foundation and appearing in the file LICENSE.GPL included in
+** the packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 2.0 requirements will be
+** met: http://www.gnu.org/licenses/gpl-2.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include "qnodecommand.h"
+#include "qnodecommand_p.h"
+#include <Qt3DCore/qnode.h>
+#include <Qt3DCore/private/qnode_p.h>
+
+QT_BEGIN_NAMESPACE
+
+namespace Qt3DCore {
+
+QNodeCommandPrivate::QNodeCommandPrivate()
+    : QSceneChangePrivate()
+    , m_commandId(createId())
+    , m_replyToCommandId()
+{
+}
+
+QNodeCommand::CommandId QNodeCommandPrivate::createId()
+{
+    static QBasicAtomicInteger<QNodeCommand::CommandId> next = Q_BASIC_ATOMIC_INITIALIZER(0);
+    return next.fetchAndAddRelaxed(1) + 1;
+}
+
+/*!
+ * \class Qt3DCore::QNodeCommand
+ * \inheaderfile Qt3DCore/QNodeCommand
+ * \inherits Qt3DCore::QSceneChange
+ * \inmodule Qt3DCore
+ * \since 5.9
+ * \brief The QNodeCommand class is the base class for all CommandRequested QSceneChange events
+ *
+ * The QNodeCommand class is the base class for all QSceneChange events that
+ * have the changeType() CommandRequested.
+ *
+ * You can subclass this to create your own node update types for communication between
+ * your QNode and QBackendNode subclasses when writing your own aspects.
+ */
+
+/*!
+ * \typedef Qt3DCore::QNodeCommandPtr
+ * \relates Qt3DCore::QNodeCommand
+ *
+ * A shared pointer for QNodeCommand.
+ */
+
+/*!
+ * Constructs a new QNodeCommand with \a node.
+ */
+QNodeCommand::QNodeCommand(QNodeId id)
+    : QSceneChange(*new QNodeCommandPrivate(), CommandRequested, id)
+{
+}
+
+QNodeCommand::QNodeCommand(QNodeCommandPrivate &dd, QNodeId id)
+    : QSceneChange(dd, CommandRequested, id)
+{
+}
+
+QNodeCommand::~QNodeCommand()
+{
+}
+
+/*!
+ * \return commandId.
+ */
+QNodeCommand::CommandId QNodeCommand::commandId() const
+{
+    Q_D(const QNodeCommand);
+    return d->m_commandId;
+}
+
+/*!
+ * \return name.
+ */
+QString QNodeCommand::name() const
+{
+    Q_D(const QNodeCommand);
+    return d->m_name;
+}
+
+void QNodeCommand::setName(const QString &name)
+{
+    Q_D(QNodeCommand);
+    d->m_name = name;
+}
+
+/*!
+ * \return data.
+ */
+QVariant QNodeCommand::data() const
+{
+    Q_D(const QNodeCommand);
+    return d->m_data;
+}
+
+void QNodeCommand::setData(const QVariant &data)
+{
+    Q_D(QNodeCommand);
+    d->m_data = data;
+}
+
+QNodeCommand::CommandId QNodeCommand::inReplyTo() const
+{
+    Q_D(const QNodeCommand);
+    return d->m_replyToCommandId;
+}
+
+void QNodeCommand::setReplyToCommandId(QNodeCommand::CommandId id)
+{
+    Q_D(QNodeCommand);
+    d->m_replyToCommandId = id;
+}
+
+} // namespace Qt3DCore
+
+QT_END_NAMESPACE
diff --git a/src/core/changes/qnodecommand.h b/src/core/changes/qnodecommand.h
new file mode 100644
index 000000000..c02365a59
--- /dev/null
+++ b/src/core/changes/qnodecommand.h
@@ -0,0 +1,85 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 Klaralvdalens Datakonsult AB (KDAB).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the Qt3D module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL3$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/contact-us.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 3 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPLv3 included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 3 requirements
+** will be met: https://www.gnu.org/licenses/lgpl.html.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 2.0 or later as published by the Free
+** Software Foundation and appearing in the file LICENSE.GPL included in
+** the packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 2.0 requirements will be
+** met: http://www.gnu.org/licenses/gpl-2.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef QT3DCORE_QNODECOMMAND_H
+#define QT3DCORE_QNODECOMMAND_H
+
+#include <Qt3DCore/qt3dcore_global.h>
+#include <Qt3DCore/qscenechange.h>
+
+#include <QtCore/qsharedpointer.h>
+
+QT_BEGIN_NAMESPACE
+
+namespace Qt3DCore {
+
+class QNodeCommandPrivate;
+
+class QT3DCORESHARED_EXPORT QNodeCommand : public QSceneChange
+{
+public:
+#if defined(Q_ATOMIC_INT64_IS_SUPPORTED)
+    typedef quint64 CommandId;
+#else
+    typedef quint32 CommandId;
+#endif
+
+    explicit QNodeCommand(QNodeId id);
+    ~QNodeCommand();
+
+    CommandId commandId() const;
+
+    QString name() const;
+    void setName(const QString &name);
+    QVariant data() const;
+    void setData(const QVariant &data);
+    CommandId inReplyTo() const;
+    void setReplyToCommandId(CommandId id);
+
+protected:
+    QNodeCommand(QNodeCommandPrivate &dd, QNodeId id);
+
+private:
+    Q_DECLARE_PRIVATE(QNodeCommand)
+};
+
+typedef QSharedPointer<QNodeCommand> QNodeCommandPtr;
+
+} // namespace Qt3DCore
+
+QT_END_NAMESPACE
+
+#endif // QT3DCORE_QNODECOMMAND_H
diff --git a/src/core/changes/qnodecommand_p.h b/src/core/changes/qnodecommand_p.h
new file mode 100644
index 000000000..09be873f5
--- /dev/null
+++ b/src/core/changes/qnodecommand_p.h
@@ -0,0 +1,75 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 Klaralvdalens Datakonsult AB (KDAB).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the Qt3D module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL3$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/contact-us.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 3 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPLv3 included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 3 requirements
+** will be met: https://www.gnu.org/licenses/lgpl.html.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 2.0 or later as published by the Free
+** Software Foundation and appearing in the file LICENSE.GPL included in
+** the packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 2.0 requirements will be
+** met: http://www.gnu.org/licenses/gpl-2.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef QT3DCORE_QNODECOMMAND_P_H
+#define QT3DCORE_QNODECOMMAND_P_H
+
+//
+//  W A R N I N G
+//  -------------
+//
+// This file is not part of the Qt API.  It exists for the convenience
+// of other Qt classes.  This header file may change from version to
+// version without notice, or even be removed.
+//
+// We mean it.
+//
+
+#include <private/qt3dcore_global_p.h>
+#include <private/qscenechange_p.h>
+
+QT_BEGIN_NAMESPACE
+
+namespace Qt3DCore {
+
+class QT3DCORE_PRIVATE_EXPORT QNodeCommandPrivate : public QSceneChangePrivate
+{
+public:
+    QNodeCommandPrivate();
+
+    static QNodeCommand::CommandId createId();
+
+    QNodeCommand::CommandId m_commandId;
+    QNodeCommand::CommandId m_replyToCommandId;
+    QString m_name;
+    QVariant m_data;
+};
+
+} // namespace Qt3DCore
+
+QT_END_NAMESPACE
+
+#endif // QT3DCORE_QNODECOMMAND_P_H
diff --git a/src/core/changes/qscenechange.h b/src/core/changes/qscenechange.h
index 378c2f676..854bab051 100644
--- a/src/core/changes/qscenechange.h
+++ b/src/core/changes/qscenechange.h
@@ -56,6 +56,7 @@ enum ChangeFlag {
     PropertyValueRemoved    = 1 << 4,
     ComponentAdded          = 1 << 5,
     ComponentRemoved        = 1 << 6,
+    CommandRequested        = 1 << 7,
     AllChanges              = 0xFFFFFFFF
 };
 Q_DECLARE_FLAGS(ChangeFlags, ChangeFlag)
diff --git a/src/core/nodes/qbackendnode.cpp b/src/core/nodes/qbackendnode.cpp
index dc751cb93..65d140067 100644
--- a/src/core/nodes/qbackendnode.cpp
+++ b/src/core/nodes/qbackendnode.cpp
@@ -42,6 +42,7 @@
 
 #include <Qt3DCore/qaspectengine.h>
 #include <Qt3DCore/qnode.h>
+#include <Qt3DCore/qnodecommand.h>
 #include <Qt3DCore/qpropertyupdatedchange.h>
 
 #include <Qt3DCore/private/corelogging_p.h>
@@ -206,6 +207,25 @@ void QBackendNode::notifyObservers(const QSceneChangePtr &e)
     d->notifyObservers(e);
 }
 
+QNodeCommand::CommandId QBackendNode::sendCommand(const QString &name,
+                                                  const QVariant &data,
+                                                  QNodeCommand::CommandId replyTo)
+{
+    auto e = QNodeCommandPtr::create(peerId());
+    e->setName(name);
+    e->setData(data);
+    e->setReplyToCommandId(replyTo);
+    e->setDeliveryFlags(QSceneChange::Nodes);
+    notifyObservers(e);
+    return e->commandId();
+}
+
+void QBackendNode::sendReply(const QNodeCommandPtr &command)
+{
+    command->setDeliveryFlags(QSceneChange::Nodes);
+    notifyObservers(command);
+}
+
 void QBackendNode::initializeFromPeer(const QNodeCreatedChangeBasePtr &change)
 {
     Q_UNUSED(change);
diff --git a/src/core/nodes/qbackendnode.h b/src/core/nodes/qbackendnode.h
index d2cae5696..99e483cff 100644
--- a/src/core/nodes/qbackendnode.h
+++ b/src/core/nodes/qbackendnode.h
@@ -42,6 +42,7 @@
 
 #include <Qt3DCore/qnodecreatedchange.h>
 #include <Qt3DCore/qnodeid.h>
+#include <Qt3DCore/qnodecommand.h>
 #include <Qt3DCore/qscenechange.h>
 #include <Qt3DCore/qt3dcore_global.h>
 
@@ -90,6 +91,9 @@ protected:
     Q_DECLARE_PRIVATE(QBackendNode)
     explicit QBackendNode(QBackendNodePrivate &dd);
     void notifyObservers(const QSceneChangePtr &e);
+    QNodeCommand::CommandId sendCommand(const QString &name, const QVariant &data,
+                                        QNodeCommand::CommandId replyTo = QNodeCommand::CommandId());
+    void sendReply(const QNodeCommandPtr &command);
     virtual void sceneChangeEvent(const QSceneChangePtr &e);
 
     QBackendNodePrivate *d_ptr;
diff --git a/src/core/nodes/qnode.cpp b/src/core/nodes/qnode.cpp
index ce5e76a55..58e016cda 100644
--- a/src/core/nodes/qnode.cpp
+++ b/src/core/nodes/qnode.cpp
@@ -902,6 +902,51 @@ QNodeCreatedChangeBasePtr QNode::createNodeCreationChange() const
     return QNodeCreatedChangeBasePtr::create(this);
 }
 
+/*!
+ * \brief Sends a command messages to the backend node
+ *
+ * Creates a QNodeCommand message and dispatches it to the backend node. The
+ * command is given and a \a name and some \a data which can be used in the
+ * backend node to performe various operations.
+ * This returns a CommandId which can be used to identify the initial command
+ * when receiving a message in reply. If the command message is to be sent in
+ * reply to another command, \a replyTo contains the id of that command.
+ *
+ * \sa QNodeCommand, QNode::sendReply
+ */
+QNodeCommand::CommandId QNode::sendCommand(const QString &name,
+                                           const QVariant &data,
+                                           QNodeCommand::CommandId replyTo)
+{
+    Q_D(QNode);
+
+    // Bail out early if we can to avoid operator new
+    if (d->m_blockNotifications)
+        return QNodeCommand::CommandId(0);
+
+    auto e = QNodeCommandPtr::create(d->m_id);
+    e->setName(name);
+    e->setData(data);
+    e->setReplyToCommandId(replyTo);
+    d->notifyObservers(e);
+    return e->commandId();
+}
+
+/*!
+ * \brief Send a command back to the backend node
+ *
+ * Assumes the command is to be to sent back in reply to itself to the backend node
+ *
+ * \sa QNodeCommand, QNode::sendCommand
+ */
+void QNode::sendReply(const QNodeCommandPtr &command)
+{
+    Q_D(QNode);
+    command->setDeliveryFlags(QSceneChange::BackendNodes);
+    d->notifyObservers(command);
+}
+
+
 namespace {
 
 /*! \internal */
diff --git a/src/core/nodes/qnode.h b/src/core/nodes/qnode.h
index cf3a16301..1fe03f5e0 100644
--- a/src/core/nodes/qnode.h
+++ b/src/core/nodes/qnode.h
@@ -42,6 +42,7 @@
 
 #include <Qt3DCore/qnodecreatedchange.h>
 #include <Qt3DCore/qnodeid.h>
+#include <Qt3DCore/qnodecommand.h>
 #include <Qt3DCore/qscenechange.h>
 #include <Qt3DCore/qt3dcore_global.h>
 #include <QtCore/QObject>
@@ -98,6 +99,10 @@ public:
     void clearPropertyTracking(const QString &propertyName);
     void clearPropertyTrackings();
 
+    QNodeCommand::CommandId sendCommand(const QString &name, const QVariant &data = QVariant(),
+                                        QNodeCommand::CommandId replyTo = QNodeCommand::CommandId());
+    void sendReply(const QNodeCommandPtr &command);
+
 public Q_SLOTS:
     void setParent(QNode *parent);
     void setEnabled(bool isEnabled);