Node.hpp

////////////////////////////////////////////////////////////////////////////////////////////////////
//                               This file is part of CosmoScout VR                               //
////////////////////////////////////////////////////////////////////////////////////////////////////

// SPDX-FileCopyrightText: German Aerospace Center (DLR) <cosmoscout@dlr.de>
// SPDX-License-Identifier: MIT

#ifndef CSL_NODE_EDITOR_NODE_HPP
#define CSL_NODE_EDITOR_NODE_HPP

#include "csl_node_editor_export.hpp"

#include "internal/NodeGraph.hpp"

#include <memory>
#include <nlohmann/json.hpp>
#include <optional>
#include <string>
#include <vector>

namespace csl::nodeeditor {

class CommunicationChannel;

/// This is the base class for all node types which should be available in an instance of the node
/// editor. In addition to the pure virtual methods getName() and process(), each derived class must
/// implement these three static items:
///   static const std::string            sName;           // A unique type name.
///   static std::string                  sSource();       // Returns the JavaScript source snippet.
///   static std::unique_ptr<DerivedNode> sCreate();       // Creates an instance of the node type.
/// For examples how the JavaScript source snippets work, please refer to the csp-demo-node-editor
/// plugin. It contains some easy-to-understand nodes which you can uses as a basis for your custom
/// nodes.
class CSL_NODE_EDITOR_EXPORT Node {
 public:
  Node()          = default;
  virtual ~Node() = default;

  /// This method gets called, once the node has been created and initialized. You can run some
  /// initial logic here, that interacts with the JavaScript counterpart of this node.
  virtual void init(){};

  /// Sends a custom message to the JavaScript counterpart of this node. The message can be received
  /// in the frontend with the onMessageFromCPP method of the node:
  ///   node.onMessageFromCPP = (message) => {
  ///     console.log(message);
  ///   };
  /// @param message A custom JSON object.
  void sendMessageToJS(nlohmann::json const& message) const;

  /// Called whenever the JavaScript counterpart of this node has sent a message via the global
  /// sendMessageToCPP() method:
  ///   CosmoScout.sendMessageToCPP(message, this.parent.id);
  /// @param message A custom JSON object.
  virtual void onMessageFromJS(nlohmann::json const& message){};

  /// This will be called whenever the node needs a reprocessing. This could be due to changed input
  /// values, dropped input connections, new output connections, or due to the entire graph needing
  /// a reprocessing because a new web client connected.
  virtual void process() = 0;

  /// Each node must override this. It simply returns the static sName.
  virtual std::string const& getName() const = 0;

  /// If your node has some internal state (like a value selected by the user), you should return
  /// this state in this call. It will then be given to setData() once a node graph is restored from
  /// disk.
  /// @return The default implementation returns an empty object.
  virtual nlohmann::json getData() const {
    return nlohmann::json::object();
  };

  /// If a node graph is restored, any custom node state which has been returned by getData() during
  /// serialization, will be passed to the re-created nodes. It will also be given to the JavaScript
  /// counterpart of the newly created node as the 'data' property of the node object:
  ///   builder(node) {
  ///     console.log(node.data);
  ///     ...
  ///   }
  /// @param json A JSON object which has been generated by getData() before.
  virtual void setData(nlohmann::json const& json){};

  // Node graph and node editor API ----------------------------------------------------------------

  // The methods below are primarily meant to be used by the NodeEditor and NodeGraph classes.
  // Usually, you should not have to call them.

  /// The node ID is unique amongst all nodes in the node graph. It gets assigned to the node right
  /// after its creation.
  void     setID(uint32_t id);
  uint32_t getID() const;

  /// The 2D position of the node on the canvas. This gets updated from JavaScript; there is
  /// currently no way to move nodes from C++. We store this only for being able do serialize and
  /// deserialize the entire graph.
  void                          setPosition(std::array<int32_t, 2> position);
  std::array<int32_t, 2> const& getPosition() const;

  /// Nodes can be collapsed to save space. This gets updated from JavaScript; there is currently no
  /// way to collapse nodes from C++. We store this only for being able do serialize and deserialize
  /// the entire graph.
  void setIsCollapsed(bool collapsed);
  bool getIsCollapsed() const;

  /// These are set by the node editor right after the creation of a node.
  void setSocket(std::shared_ptr<CommunicationChannel> socket);
  void setGraph(std::shared_ptr<NodeGraph> graph);

 protected:
  /// Call this to write a value to all connections which are connected to an output socket. This
  /// will automatically trigger a reprocessing of all connected nodes if the value actually
  /// changed.
  /// @tparam T      The data type to write. You have to be extremely careful to always read and
  ///                write data in the same format to a given socket type. For instance, do not mix
  ///                floats and doubles! Else you will receive a bad_any_cast. It is a good practice
  ///                to explicitly state the template parameter.
  /// @param socket  The name of the socket to write to.
  /// @param value   The value to write. It will be compared to any previously written value and
  ///                only written if changed.
  template <typename T>
  void writeOutput(std::string const& socket, T const& value) {
    auto connections = mGraph->getOutputConnections(mID, socket);

    for (auto& c : connections) {
      if (!c->mData.has_value() || std::any_cast<T>(c->mData) != value) {
        mGraph->queueProcess(c->mToNode);
        c->mData = value;
      }
    }
  }

  /// Call this to read the value of an input socket.
  /// @tparam T            The data type to read. You have to be extremely careful to always read
  ///                      and write data in the same format to a given socket type. For instance,
  ///                      do not mix floats and doubles! Else you will receive a bad_any_cast.
  /// @param socket        The name of the socket to read from.
  /// @param defaultValue  If there is no input connection, this value will be returned.
  template <typename T>
  T readInput(std::string const& socket, T defaultValue) {
    auto const* connection = mGraph->getInputConnection(mID, socket);

    if (connection && connection->mData.has_value()) {
      return std::any_cast<T>(connection->mData);
    }

    return std::move(defaultValue);
  }

 private:
  uint32_t                              mID = 0;
  std::array<int32_t, 2>                mPosition{};
  bool                                  mIsCollapsed = false;
  std::shared_ptr<CommunicationChannel> mSocket;
  std::shared_ptr<NodeGraph>            mGraph;
};

} // namespace csl::nodeeditor

#endif // CSL_NODE_EDITOR_NODE_HPP