Nodes Manual

Table of Contents

• About
• Access
• Use
• Port Lists
• Ports
• Connections

About

maxon::nodes::Node is a node based on maxon::nodes::GNode and maxon::nodes::NodeFunctions. It is stored in a node system.

Note

It is preferred to use the more generic graph nodes, see GraphModelInterface Manual and GraphNodes Manual.

Access

Nodes are obtained from a nodes graph model; see NodesGraphModelInterface Manual and NodeMaterial Manual.

• maxon::nodes::NodeSystemInterface::GetRoot(): Returns the root node.

A given maxon::GraphNode can be converted with:

• maxon::nodes::ToNode(): Converts a maxon::GraphNode to a Node.
• maxon::nodes::ToMutableNode(): Converts a maxon::GraphNode to a MutableNode.

See GraphNodes Manual.

  // This example accesses the root node of the given node material for the active node space.
 
  // get active node space ID.
  const maxon::Id nodeSpaceID = GetActiveNodeSpaceId();
 
  // check material
  if (nodeMaterial->HasSpace(nodeSpaceID) == false)
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
  // get graph model, node system and root node
  const maxon::nodes::NodesGraphModelRef& graph  = nodeMaterial->GetGraph(nodeSpaceID) iferr_return;
  const maxon::nodes::NodeSystem&         system = graph.GetNodeSystem();
  maxon::nodes::Node node = system.GetRoot();

Use

maxon::nodes::Node is based on maxon::nodes::NodeFunctions. Inherited functions allow to access parents and children:

• maxon::nodes::NodeFunctions::GetParent(): Returns the parent node.
• maxon::nodes::NodeFunctions::FindChild(): Finds the direct child node with the given identifier.
• maxon::nodes::NodeFunctions::GetChildren(): Returns an iterator over the child nodes.

  // This example prints the IDs of all children of the given node.
 
 
  // check children
  for (auto nodeSelector : node.GetChildren())
  {
    maxon::nodes::Node child = nodeSelector iferr_return;
    DiagnosticOutput("Child ID: @", child.GetId());
  }

  // This example searches for a child node with the given ID.
 
  const maxon::Id materialID { "material" };
  const maxon::nodes::Node materialNode = rootNode.FindChild(materialID) iferr_return;

A node contains lists of ports:

• maxon::nodes::NodeFunctions::GetPortList(): Returns the input or output port list.
• maxon::nodes::NodeFunctions::GetInputs(): Returns the input port list.
• maxon::nodes::NodeFunctions::GetOutputs(): Returns the output port list.

See Port Lists below.

    // This example obtains both the input and output port lists of the given node.
 
    const maxon::nodes::PortList inputs  = node.GetInputs() iferr_return;
    const maxon::nodes::PortList outputs = node.GetOutputs() iferr_return;

Further functions are:

• maxon::nodes::NodeFunctions::FindInnerNode(): Returns a reference to the nested GNode which corresponds to the given nested GNode of a base of this node.
• maxon::nodes::NodeFunctions::InitFromPath(): Initializes a node reference from a node system and a path.

maxon::nodes::Node is based on maxon::nodes::GNodeBase. Basic functions allow to check if a node is a valid reference:

• maxon::nodes::GNodeBase::operator Bool(): Checks if this is a non-null reference to a GNode.
• maxon::nodes::GNodeBase::IsEmpty(): Returns true if this GNode is empty and contains no reference.
• maxon::nodes::GNodeBase::IsPopulated(): Returns true if this is a non-null reference to a GNode in some node system.

A GNode is part of a node system:

• maxon::nodes::GNodeBase::GetNodeSystem(): Returns the node system of this node reference.
• maxon::nodes::GNodeBase::GetPath(): Returns the maxon::NodePath of this node reference.

Further node properties are:

• maxon::nodes::GNodeBase::GetId(): Returns the identifier of this node reference.
• maxon::nodes::GNodeBase::GetKind(): Returns the maxon::NODE_KIND of this GNode.
• maxon::nodes::GNodeBase::GetFlags(): Returns the maxon::nodes::GNODE_FLAGS flags.

A node can be compared with:

• maxon::nodes::GNodeBase::operator==(): Returns true if this GNode is the same as other.
• maxon::nodes::GNodeBase::operator!=(): Returns true if this GNode and other denote different nodes.
• maxon::nodes::GNodeBase::GetHashCode(): Returns a hash value.
• maxon::nodes::GNodeBase::ToString(): Returns a maxon::String representation.

maxon::nodes::GNode is the base class of immutable node references. It is based on maxon::nodes::GNodeFunctions. This class allows to access node attributes:

• maxon::nodes::GNodeFunctions::GetValues(): Collects all attribute values.
• maxon::nodes::GNodeFunctions::GetValue(): Returns a pointer to the value of the given attribute.
• maxon::nodes::GNodeFunctions::GetBaseValues(): Yields all values which are stored for the given attribute.
• maxon::nodes::GNodeFunctions::GetDefaultValue(): Returns the value of the DefaultValue attribute at this GNode. Used for ports.
• maxon::nodes::GNodeFunctions::GetAttributeModificationsSince(): Reports all attribute modifications which have been made since the given maxon::TimeStamp.
• maxon::nodes::GNodeFunctions::GetAttributeStamp(): Returns the modification stamp of the given attribute.

  // This example read the node name and node space context from the found node.
 
  // find the node with the given ID
  const maxon::Id materialID { "material" };
  const maxon::nodes::Node materialNode = rootNode.FindChild(materialID) iferr_return;
 
  // get the node name
  const maxon::String nodeName = materialNode.GetValue<decltype(maxon::EffectiveName)>().GetValueOrNull() iferr_return;
 
  // get the space ID.
  const maxon::DataDictionary& currentPreviewContext = materialNode.GetValue<decltype(maxon::nodes::NODESPACE::NodeSpaceContext)>().GetValueOrNull() iferr_return;
  const maxon::Id currentSpaceId = currentPreviewContext.Get(maxon::nodes::NODESPACE::SPACEID, maxon::Id());
 
  DiagnosticOutput("Node Name: @", nodeName);
  DiagnosticOutput("Node Space: @", currentSpaceId);

  // This example gets all attributes from the given node for the defined mask.
 
  const maxon::GraphAttribute::FLAGS mask = maxon::GraphAttribute::FLAGS::TYPE_MASK;
 
  maxon::GraphAttributeMap map;
  materialNode.GetValues(mask, map, true, false) iferr_return;
 
  for (const auto& attr : map)
  {
    // get id and data
    const maxon::InternedId   id = attr.GetFirst();
    const maxon::ConstDataPtr data = attr.GetSecond();
 
    // get time stamp
    const maxon::TimeStamp timeStamp = materialNode.GetAttributeStamp(id);
 
    DiagnosticOutput("@ : @ (at @)", id, data, timeStamp);
  }

Further functions are:

• maxon::nodes::GNodeFunctions::GetNode(): Returns the enclosing (true) node to which this GNode belongs.
• maxon::nodes::GNodeFunctions::GetParent(): Returns the parent node of this node.
• maxon::nodes::GNodeFunctions::FindChild(): Finds a child with the given name or kind.
• maxon::nodes::GNodeFunctions::FindInnerNode(): Finds the inner child of this GNode with the given relative path.
• maxon::nodes::GNodeFunctions::GetInnerNodes(): Yields all inner nodes of this GNode matching the given mask.
• maxon::nodes::GNodeFunctions::GetBase(): Returns the base node system of this node.
• maxon::nodes::GNodeFunctions::GetTemplate(): Returns the maxon::nodes::NodeTemplateInterface which instantiated this node.
• maxon::nodes::GNodeFunctions::GetDerivationHandler(): Returns the derivation handler of this node.

  // This example read the node name and node space context from the found node.
 
  // find the node with the given ID
  const maxon::Id materialID { "material" };
  const maxon::nodes::Node materialNode = rootNode.FindChild(materialID) iferr_return;
 
  // get the node name
  const maxon::String nodeName = materialNode.GetValue<decltype(maxon::EffectiveName)>().GetValueOrNull() iferr_return;
 
  // get the space ID.
  const maxon::DataDictionary& currentPreviewContext = materialNode.GetValue<decltype(maxon::nodes::NODESPACE::NodeSpaceContext)>().GetValueOrNull() iferr_return;
  const maxon::Id currentSpaceId = currentPreviewContext.Get(maxon::nodes::NODESPACE::SPACEID, maxon::Id());
 
  DiagnosticOutput("Node Name: @", nodeName);
  DiagnosticOutput("Node Space: @", currentSpaceId);

A maxon::nodes::MutableRoot is returned from maxon::nodes::NodeSystemClassInterface::CreateNodeSystem() and is the root node of node systems with write access.

• maxon::nodes::MutableRoot::CopyFrom(): Copies the data of the given mutable root.
• maxon::nodes::MutableRoot::AddChild(): Adds an instance of a node system as child.
• maxon::nodes::MutableRoot::ReplaceBase(): Replaces the base of the current node system.
• maxon::nodes::MutableRoot::ReplaceChild(): Replaces the base of an existing child.
• maxon::nodes::MutableRoot::MoveToGroup(): Groups the selection of direct child nodes of this node system into a new group node.
• maxon::nodes::MutableRoot::Merge(): Merges the other node system into this node system.
• maxon::nodes::MutableRoot::ValidateTopology(): Validates the topology of the node system.
• maxon::nodes::MutableRoot::ValidatePorts(): Validates the ports of the node system after a sequence of modifications.
• maxon::nodes::MutableRoot::Validate(): Completely validates the node system after a sequence of modifications.
• maxon::nodes::MutableRoot::EndModification(): Ends a sequence of modifications.
• maxon::nodes::MutableRoot::SetTemplate(): Sets template and arguments for the current node system if it is an instantiation of a NodeTemplate.
• maxon::nodes::MutableRoot::SetDerivationHandler(): Sets the derivation handler for the current node system.
• maxon::nodes::MutableRoot::Apply(): Applies the given change list to this node system.
• maxon::nodes::MutableRoot::ToNode(): Upcasts this MutableRoot to a MutableNode.

maxon::nodes::MutableNode represents a node within a NodeSystem with write access.

• maxon::nodes::ToImmutable(): Casts this MutableNode to an immutable Node.
• maxon::nodes::Ungroup(): Dissolves this node into its children.
• maxon::nodes::MoveToNodeSystem()

Port Lists

A maxon::nodes::PortList represents a port list within a node system. Each Node has exactly two port lists, one for its top-level input ports and one for its top-level output ports.

A given maxon::GraphNode can be converted to a port list with:

• maxon::nodes::ToPortList(): Converts a GraphNode to a PortList.
• maxon::nodes::ToMutablePortList(): Converts a GraphNode to a MutablePortList.

A maxon::nodes::PortList is based on maxon::nodes::PortListFunctions:

• maxon::nodes::PortListFunctions::GetPortDirection(): Returns the direction of this port or port list.
• maxon::nodes::PortListFunctions::IsPort(): Returns true if this reference addresses a port or a port list.
• maxon::nodes::PortListFunctions::ToPort(): Downcasts this reference to a port reference.
• maxon::nodes::PortListFunctions::GetNode(): Returns the enclosing (true) node to which this port list or port belongs.
• maxon::nodes::PortListFunctions::GetPorts(): Returns an iterator over the ports of this port list.
• maxon::nodes::PortListFunctions::GetSinglePort(): Returns the single port of this port list.
• maxon::nodes::PortListFunctions::FindPort(): Finds the port with the given identifier.

Ports

A maxon::nodes::Port represents a port within a node system.

A given maxon::GraphNode can be converted to a port with:

• maxon::nodes::ToPort(): Converts a GraphNode to a Port.
• maxon::nodes::ToMutablePort(): Converts a GraphNode to a MutablePort.

A maxon::nodes::Port is based on maxon::nodes::PortFunctions:

• maxon::nodes::PortFunctions::GetParent(): Returns the parent node of this port.
• maxon::nodes::PortFunctions::GetConnections(): Yields all connections of this port for the given direction.
• maxon::nodes::PortFunctions::GetWires(): Returns the Wires which are present between this port and the given target.
• maxon::nodes::PortFunctions::GetConnectionValues(): Gets all attribute values of the connection from this port to target.
• maxon::nodes::PortFunctions::GetConnectionValue(): Gets the value of the given attribute.
• maxon::nodes::PortFunctions::IsPortOfRoot(): Returns true if this port is a port of the root node of a node system.
• maxon::nodes::PortFunctions::IsTopLevelPort(): Returns true if this port is a top-level port.
• maxon::nodes::PortFunctions::GetTopologicalOrder(): Returns an maxon::Int value which corresponds to the index of this port in the topological ordering of its node system.
• maxon::nodes::PortFunctions::InitFromPath(): Initializes a g-node reference from a node system and a path.

  // This example searches a child node of the given root node
  // and a specific port in the node's input port list.
 
  // find the "material" node
  const maxon::Id materialID { "material" };
  const maxon::nodes::Node materialNode = rootNode.FindChild(materialID) iferr_return;
 
  // get input ports
  const maxon::nodes::PortList inputs = materialNode.GetInputs() iferr_return;
 
  // find the "normal" port
  const maxon::Id normalID { "normal" };
  const maxon::nodes::Port normalPort = inputs.FindPort(normalID) iferr_return;

  // This example reads various properties of the given port.
 
  DiagnosticOutput("Port: @", port.GetId());
 
  // prints the port name
  const maxon::String* const directlySetName = port.GetValue<decltype(maxon::NODE::BASE::NAME)>() iferr_return;
  if (directlySetName != nullptr)
    DiagnosticOutput("Name: @", directlySetName);
 
  // print the data type
  const maxon::DataType& dataType = port.GetValue<decltype(maxon::nodes::PortType)>().GetValueOrNull() iferr_return;
  DiagnosticOutput("DataType: @", dataType);
 
  // print the default value
  const maxon::Data* const def = port.GetValue<decltype(maxon::DESCRIPTION::DATA::BASE::DEFAULTVALUE)>() iferr_return;
  if (def != nullptr)
    DiagnosticOutput("Default Value: @", def);
 
  // check if this is a hidden port
  maxon::nodes::PORT_FLAGS flags = port.GetValue<decltype(maxon::nodes::PortFlags)>().GetValueOrNull() iferr_return;
 
  if (flags & maxon::nodes::PORT_FLAGS::HIDDEN)
  {
    DiagnosticOutput("Port is hidden.");
  }

maxon::nodes::MutablePort is based on maxon::nodes::MutablePortFunctions:

• maxon::nodes::MutablePortFunctions::Connect(): Connects this port to the other port.
• maxon::nodes::MutablePortFunctions::SetDefaultValue(): Sets the value of the DefaultValue attribute.
• maxon::nodes::MutablePortFunctions::SetType(): Sets the given data type as the value of the FixedPortType attribute.
• maxon::nodes::MutablePortFunctions::SetConnectionValue(): Sets the value of of the given attribute for the given connection.

Connections

maxon::nodes::Connection is a tuple of maxon::node::Port and maxon::Wires.

    // This example gets the connections of the input ports of the given node.
 
    // get input ports
    maxon::nodes::PortList inPorts = node.GetInputs() iferr_return;
 
    // loop over input ports
    for (auto it : inPorts.GetPorts())
    {
      const maxon::nodes::Port port = it iferr_return;
 
      // get connections
      maxon::SingleValueReceiver<const maxon::nodes::Connection&, false> unique;
      port.GetConnections(maxon::PORT_DIR::INPUT, unique) iferr_return;
 
      // check if this port has one input connection
      if (unique.GetCount() == 1)
      {
        // get connection
        const maxon::nodes::Connection connection = *unique.Get();
 
        // the other port this port is connected to
        const maxon::nodes::Port connectedPort = connection.GetFirst();
 
        // the other node this port is connected to
        const maxon::nodes::Node sourceNode = connectedPort.GetNode() iferr_return;
 
        // print source node and port
        const maxon::Id sourceNodeId = sourceNode.GetId();
        const maxon::Id sourcePortId = connectedPort.GetId();
 
        DiagnosticOutput("Connected to \"@\" : \"@\"", sourceNodeId, sourcePortId);
      }
    }