GraphNodes Manual

Table of Contents

• About
• Access
• GraphNode
• GraphNodeFunctions
• NodePath

About

A maxon::GraphNode is a node of a maxon::GraphModelInterface graph. A maxon::NodePath is used to identify a node within that graph.

Access

A maxon::GraphNode is obtained from a graph model:

• maxon::GraphModelInterface::GetRoot(): Returns the root node of the model.
• maxon::GraphModelInterface::GetNode(): Returns the node for the given maxon::NodePath.

See GraphModelInterface Manual.

  // This example shows how to obtain graph nodes from a graph model.
 
  // get node space ID
  const maxon::Id nodeSpaceID = GetActiveNodeSpaceId();
 
  // check material
  if (nodeMaterial->HasSpace(nodeSpaceID) == false)
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
  // get graph
  const maxon::nodes::NodesGraphModelRef& graph = nodeMaterial->GetGraph(nodeSpaceID) iferr_return;
 
  // get root node
  const maxon::GraphNode rootNode = graph.GetRoot();
 
  // get material node
  maxon::NodePath materialNodePath;
  nodeMaterial->GetMaterialNodePath(nodeSpaceID, materialNodePath) iferr_return;
  const maxon::GraphNode materialNode = graph.GetNode(materialNodePath);

GraphNode

The properties of a maxon::GraphNode are accessed with:

• maxon::GraphNode::GetId(): Returns the identifier of this node.
• maxon::GraphNode::IsInner(): Returns true if the node is a inner node (not the root node and not ports/port lists).
• maxon::GraphNode::GetKind(): Returns the kind of this node. See below.

Graph node types returned by maxon::GraphNode::GetKind() are:

• maxon::NODE_KIND::NONE: Special value used e.g. for null references.
• maxon::NODE_KIND::NODE: A true node (no port or port list etc.).
• maxon::NODE_KIND::INPUTS: An input port list.
• maxon::NODE_KIND::OUTPUTS: An output port list.
• maxon::NODE_KIND::INPORT: An input port.
• maxon::NODE_KIND::OUTPORT: An output port.
• maxon::NODE_KIND::IN_MASK: Mask to check for input port or input port list.
• maxon::NODE_KIND::OUT_MASK: Mask to check for output port or output port list.
• maxon::NODE_KIND::PORTLIST_MASK: Mask to check for port lists.
• maxon::NODE_KIND::PORT_MASK: Mask to check for ports.
• maxon::NODE_KIND::ALL_MASK: Mask to check for all node kinds.

      // This example checks if the given GraphNode is a real node and prints its ID.
 
      // check if node
      if (graphNode.GetKind() == maxon::NODE_KIND::NODE)
      {
        // get ID
        const maxon::InternedId id = graphNode.GetId();
        DiagnosticOutput("Node ID: @", id);
      }

The parent graph model and the path within that graph are obtained with:

• maxon::GraphNode::GetGraph(): Returns the maxon::GraphModelRef.
• maxon::GraphNode::GetPath(): Returns the maxon::NodePath.

      // This example obtains the graph nodes model and path.
 
      const maxon::GraphModelRef& graphModel = graphNode.GetGraph();
      const maxon::NodePath&      nodePath = graphNode.GetPath();
 
      DiagnosticOutput("Path: @", nodePath);

The validity of a node is checked with:

• maxon::GraphNode::IsValid(): Returns true if the node is a valid, existing node in a graph.
• maxon::GraphNode::IsPopulated(): Returns true if the node has graph and path references, but does not check if the graph contains the node.

Further utility functions are:

• maxon::GraphNode::GetHashCode(): Returns a hash value for the node.
• maxon::GraphNode::ToString(): Returns a maxon::String representation.

GraphNodeFunctions

maxon::GraphNode is based on maxon::GraphNodeFunctions.

The node can be removed from its model with:

• maxon::GraphNodeFunctions::Remove(): Removes the nodes with all nested nodes and connections from the graph.

The node hierarchy can be explored with:

• maxon::GraphNodeFunctions::GetChildren(): Gets all children of this node including port lists.
• maxon::GraphNodeFunctions::FindChild(): Returns the child with the given ID.
• maxon::GraphNodeFunctions::GetParent(): Returns the parent.
• maxon::GraphNodeFunctions::GetAncestor(): Returns the closest ancestor node of this node for the given mask.
• maxon::GraphNodeFunctions::FindInnerNode(): Returns the inner child of this node for the given relative path.
• maxon::GraphNodeFunctions::GetInnerNodes(): Yields all inner nodes of this node matching the given mask.
• maxon::GraphModelHelper::GetDirectPredecessors(): Retrieves the first level of nodes connected to the input port of this node.
• maxon::GraphModelHelper::GetAllPredecessors(): Retrieves all nodes connected to the input port of this node.
• maxon::GraphModelHelper::GetDirectSuccessors(): Retrieves the first level of nodes connected to the output port of this node.
• maxon::GraphModelHelper::GetAllSuccessors(): Retrieves all nodes connected to the output port of this node.

  // This example receives all child nodes of the given GraphNode.
 
  // using a lambda function
 
  maxon::ValueReceiver<const maxon::GraphNode&> lambda;
 
  lambda = [](const maxon::GraphNode& childNode) -> maxon::Result<maxon::Bool>
           {
             iferr_scope;
 
             const maxon::InternedId id = childNode.GetId();
             DiagnosticOutput("Node ID: @", id);
 
             return true;
           };
 
  graphNode.GetChildren(lambda) iferr_return;
 
  // or using a BaseArray
 
  maxon::BaseArray<maxon::GraphNode> childNodes;
  graphNode.GetChildren(childNodes) iferr_return;
 
  for (const maxon::GraphNode& childNode : childNodes)
  {
    const maxon::InternedId id = childNode.GetId();
    DiagnosticOutput("Node ID: @", id);
  }

  // This example searches in the given GraphModelRef for a node with the given nodeID and stores the node paths.
 
  // array of node paths
  maxon::BaseArray<maxon::NodePath> paths;
 
  // check all inner nodes of the root node
  graph.GetRoot().GetInnerNodes(maxon::NODE_KIND::NODE, false,
    [&paths, nodeID](const maxon::GraphNode& node) -> maxon::Result<Bool>
    {
      iferr_scope;
// get
      const maxon::IdAndVersion id = node.GetValue<decltype(maxon::NODE::ATTRIBUTE::ASSETID)>().GetValueOrNull() iferr_return;
      if (id.Get<0>() == nodeID)
      {
// store node path
        paths.Append(node.GetPath()) iferr_return;
      }
      return true;
    }) iferr_return;

The port lists and ports of a node are obtained with:

• maxon::GraphNodeFunctions::GetInputs(): Returns the input port list.
• maxon::GraphNodeFunctions::GetOutputs(): Returns the output port list.
• maxon::GraphNodeFunctions::GetPortList(): Returns the input or output port list based on the given value, see maxon::PORT_DIR.
• maxon::GraphNodeFunctions::AddPort(): Adds a port to this node with the given id. This node has to be a port list or a port itself.

Port directions are:

• maxon::PORT_DIR::INPUT: Input direction.
• maxon::PORT_DIR::OUTPUT: Output direction.
• maxon::PORT_DIR::BEGIN: The start value for a loop over port directions.
• maxon::PORT_DIR::END: The end value for a loop over port directions.

  // This example obtains the input ports of the given GraphNode.
 
  // get input port list
  maxon::GraphNode inputPortList = node.GetInputs() iferr_return;
 
  maxon::ValueReceiver<const maxon::GraphNode&> lambda;
  lambda = [](const maxon::GraphNode& port) -> maxon::Result<maxon::Bool>
           {
             iferr_scope;
 
              // check if port
             if (port.GetKind() == maxon::NODE_KIND::INPORT)
             {
               const maxon::InternedId id = port.GetId();
               DiagnosticOutput("Port ID: @", id);
             }
 
             return true;
           };
 
  inputPortList.GetChildren(lambda) iferr_return;
 
  // or using a BaseArray
 
  maxon::BaseArray<maxon::GraphNode> ports;
  inputPortList.GetChildren(ports) iferr_return;
 
  for (const maxon::GraphNode& port : ports)
  {
    const maxon::InternedId id = port.GetId();
    DiagnosticOutput("Port ID: @", id);
  }

Ports can be created with:

• maxon::GraphModelHelper::CreateInputPort(): Creates and returns a new InputPort that correspond to the name passed as argument
• maxon::GraphModelHelper::CreateOutputPort(): Creates and returns a new OutputPort that correspond to the name passed as argument

Ports of different nodes can be connected:

• maxon::GraphNodeFunctions::GetConnections(): Receives all connections of this port for the given direction.
• maxon::GraphNodeFunctions::GetWires(): Returns the maxon::Wires from this node to the given target.
• maxon::GraphNodeFunctions::Connect(): Connects the port with the given port.
• maxon::GraphNodeFunctions::RemoveConnections(): Removes all connections of the port for the given direction.
• maxon::GraphNodeFunctions::GetConnectionValues(): Gets all attribute values of the connection from this port to target.
• maxon::GraphNodeFunctions::GetConnectionValue(): Gets the value of the given attribute for the connection from this port to target.
• maxon::GraphNodeFunctions::SetConnectionValue(): Sets the value of the given attribute.
• maxon::GraphNodeFunctions::CopyConnectionsFrom(): Copies all connections of the given source.

Connection can be muted or unmuted:

• maxon::GraphModelHelper::MuteConnection(): Mutes the connection from the current port to the passed port.
• maxon::GraphModelHelper::MuteAllConnections(): Mutes all the connections in one direction
• maxon::GraphModelHelper::UnmuteConnection(): Unmutes the connection from the current port to the passed port.
• maxon::GraphModelHelper::UnmuteAllConnections(): Unmutes all the connections in one direction

Connection can be checked with:

• maxon::GraphModelHelper::IsConnected(): Checks if this port is connected to another port.

Connection can be removed with:

• maxon::GraphModelHelper::RemoveAllConnections(): Removes the Wires between two True Nodes or Ports.

GraphNode selection can be checked with:

• maxon::GraphModelHelper::IsNodeSelected(): Returns if the node is selected or not.
• maxon::GraphModelHelper::IsConnectionSelected(): Returns if the connection from two given port is selected or not.

  // This example gets the list of output connections for the given output port.
 
  // get connections
  maxon::BaseArray<maxon::GraphConnection> connections;
  port.GetConnections(maxon::PORT_DIR::OUTPUT, connections) iferr_return;
 
  // check connections
  for (const maxon::GraphConnection& connection : connections)
  {
    const maxon::GraphNode targetNode = connection.first;
    const maxon::NodePath  path = targetNode.GetPath();
 
    DiagnosticOutput("Connected to : @", path);
  }

A graph node can store multiple values:

• maxon::GraphNodeFunctions::GetValue(): Returns value of the given attribute.
• maxon::GraphNodeFunctions::SetValue(): Sets the value for the given attribute.
• maxon::GraphNodeFunctions::GetValues(): Gets all attribute values.
• maxon::GraphNodeFunctions::RemoveValue(): Removes the given attribute value.
• maxon::GraphNodeFunctions::InheritValue(): Restores the inherited state of the value for the given attribute.
• maxon::GraphNodeFunctions::TouchValue(): Marks the value of the given attribute as modified.
• maxon::GraphNodeFunctions::ChangeValue(): Sets a part of the value of the given attribute.
• maxon::GraphNodeFunctions::GetDefaultValue(): Returns the default value of this port.
• maxon::GraphNodeFunctions::SetDefaultValue(): Sets the value of the attribute maxon::DESCRIPTION::DATA::BASE::DEFAULTVALUE.
• maxon::GraphNodeFunctions::GetConstantValue(): Returns the constant value of this port.
• maxon::GraphNodeFunctions::CopyValuesFrom(): Copies all directly set attribute values of the given source node.

Important values are:

• maxon::nodes::PortType: The port type.
• maxon::ConstantValue: The value stored in the port.
• maxon::EffectiveName: The name of the node or port.

See maxon::NODE::BASE, graphattribs.h and portattributes.h.

  // This example checks the input ports of the given node
  // and prints the values of all ports of the type Float64.
 
  // get input ports
  maxon::GraphNode inputPortList = node.GetInputs() iferr_return;
 
  maxon::BaseArray<maxon::GraphNode> ports;
  inputPortList.GetChildren(ports) iferr_return;
 
  // check each port
  for (const maxon::GraphNode& port : ports)
  {
    DiagnosticOutput("Port: @", port.GetId());
 
    // get data type
    const maxon::DataType& type = port.GetValue<decltype(maxon::nodes::PortType)>().GetValueOrNull() iferr_return;
    DiagnosticOutput("Data Type: @", type.GetId());
 
    // check for float value
    if (type.Is<maxon::Float64>())
    {
      // get data
      const maxon::Float64 floatValue = port.GetConstantValue(maxon::Float64()) iferr_return;
      DiagnosticOutput("Float value: @", floatValue);
    }
  }

  // This example gets all output ports of the given nodes and prints the port names.
 
  // get output ports
  const maxon::GraphNode outputPortList = node.GetOutputs() iferr_return;
 
  maxon::BaseArray<maxon::GraphNode> outputPorts;
  outputPortList.GetChildren(outputPorts) iferr_return;
 
  // print all port names
  for (const maxon::GraphNode& currentport : outputPorts)
  {
    // get port name
    const maxon::String portName = currentport.GetValue<decltype(maxon::EffectiveName)>().GetValueOrNull() iferr_return;
    DiagnosticOutput("Port name: @", portName);
  }

  // This example lists all attributes of the given node or port.
 
  maxon::GraphAttributeMap map;
 
  port.GetValues(maxon::GraphAttribute::FLAGS::DIRECT, map) iferr_return;
 
  for (const auto& e : map)
  {
    const maxon::InternedId&   key  = e.GetKey();
    const maxon::ConstDataPtr& data = e.GetValue();
    DiagnosticOutput("Key: @, Data: @", key, data);
  }

Further attribute settings are:

• maxon::GraphNodeFunctions::GetAttributeModificationsSince(): Reports all attribute modifications since the given maxon::TimeStamp.
• maxon::GraphNodeFunctions::GetAttributeStamp(): Returns the modification stamp of the given attribute.

Warning and error messages are obtained with:

• maxon::GraphNodeFunctions::GetMessageFlags(): Returns the message flags of the given attribute.
• maxon::GraphNodeFunctions::GetMessages(): Yields the error or warning messages for the given attribute.

NodePath

A maxon::NodePath identifies a maxon::GraphNode within a node graph model. Only this path uniquely identifies a node.

A maxon::NodePath is obtain with:

• maxon::GraphNode::GetPath(): Returns the node path.
• NodeMaterial::GetMaterialNodePath(): Returns the node path of the material node.
• NodeMaterial::GetSoloNodePath(): Returns the node path of the solo node.

If a node path is empty or not can be checked with:

• maxon::NodePathInterface::IsEmpty(): Returns true if the path is empty.
• maxon::NodePathInterface::IsPopulated(): Returns true if the path is populated.

Components and properties of the node path are:

• maxon::NodePathInterface::GetKind(): Returns the node kind of the graph node which is identified by this path. See port directions above.
• maxon::NodePathInterface::GetLastId(): Returns the last element.
• maxon::NodePathInterface::GetCount(): Returns the length.
• maxon::NodePathInterface::GetPortPart(): Returns the port part as a new maxon::NodePath.
• maxon::NodePathInterface::GetPortPath(): Returns the port part as a maxon::PathBlock.
• maxon::NodePathInterface::GetParent(): Returns the path of the parent.
• maxon::NodePathInterface::StartsWith(): Returns true whether this path starts with the given maxon::PathBlock.
• maxon::NodePathInterface::Prepend(): Prepends a node prefix at the beginning.
• maxon::NodePathInterface::GetPart(): Returns a part of the path as a new maxon::NodePath.
• maxon::NodePathInterface::GetTopLevelPort(): Returns the path to the top-level port of this path.
• maxon::NodePathInterface::GetNode(): Returns only the path of the node without ports.
• maxon::NodePathInterface::GetNodeDepth(): Returns the hierarchy depth of the true node which is identified by this path.
• maxon::NodePathInterface::IsTopLevelPort(): Returns true if this path identifies a top-level port.
• maxon::NodePathInterface::IsPortOfRoot(): Returns true if this path identifies a port of the root node of a node system.
• maxon::NodePathInterface::operator[](): Returns the path element at the given index.

A maxon::NodePath can be constructed with:

• maxon::NodePathInterface::operator+(): Appends a single identifier at the end.

A maxon::NodePath can be converted:

• maxon::NodePathInterface::ToString(): Returns the maxon::String representation of the path.
• maxon::NodePathInterface::ToCString(): Returns the textual notation.
• maxon::NodePathInterface::ToBlock(): Returns the internally stored path as a maxon::PathBlock.

Two paths can be compared with:

• maxon::NodePathInterface::IsEqual(): Returns true if the given path is equal.
• maxon::NodePathInterface::Compare(): Compares the given path and returns a maxon::COMPARERESULT.
• maxon::NodePathInterface::GetHashCode(): Returns a hash code.

One can iterate over the components of a path with:

• maxon::NodePathInterface::Begin(): Returns an iterator pointing to the first identifier.
• maxon::NodePathInterface::End(): Returns an iterator pointing behind the last identifier.