MutableRoot Class Reference

#include <nodesystem.h>

Inheritance diagram for MutableRoot:

Detailed Description

MutableRoot is a subclass of MutableNode and used for root nodes of node systems with write access. Such a node is returned by NodeSystem::BeginModifications(). The difference to MutableNode is that MutableRoot allows to add children, because this is only possible at the root level, and that MutableRoot holds a strong reference on the node system. You have to ensure that this reference is the only reference during the modification.

See also
$ref usernodes_modifications

Public Member Functions

void Reset ()
 
MutableRootoperator= (std::nullptr_t)
 
 MutableRoot ()=default
 
 ~MutableRoot ()
 
 MutableRoot (MutableRoot &&src)
 
 MAXON_OPERATOR_MOVE_ASSIGNMENT (MutableRoot)
 
 MAXON_DISALLOW_COPY_AND_ASSIGN (MutableRoot)
 
Result< void > CopyFrom (const MutableRoot &src)
 
AssetRepositoryRef GetLookupRepository () const
 
Result< MutableNodeAddChild (const Id &childId, const Result< NodeSystem > &base, Opt< ChangeList & > list={}) const
 
Result< MutableNodeAddChild (const Id &childId, const Result< NodeTemplate > &templ, const Result< TemplateArguments > &args=GetZeroRef< Result< TemplateArguments >>(), Opt< ChangeList & > list={}) const
 
Result< void > AddChildren (const Block< Tuple< InternedId, NodeSystem, GNodeHandle >> &children, Opt< ChangeList & > list={}) const
 
Result< ChangeList > ReplaceBase (const NodeSystem &base, Opt< ChangeList & > list={}) const
 
Result< ChangeList > ReplaceChild (const InternedId &childId, const NodeSystem &base, const HashMap< NodePath, NodePath > &portMap=GetZeroRef< HashMap< NodePath, NodePath >>(), Opt< ChangeList & > list={}) const
 
Result< MutableNodeMoveToGroup (MutableRoot &&groupRoot, const Id &groupId, const Block< const InternedId > &selection, Bool matchPorts=true, const FixedSizeArray< Block< const Tuple< NodePath, NodePath, NodePath >>, 2 > &mapping=GetZeroRef< const FixedSizeArray< Block< const Tuple< NodePath, NodePath, NodePath >>, 2 >>(), Opt< ChangeList & > list={}) const
 
Result< HomogenousTupleType< 3, HashMap< InternedId, InternedId > > > Merge (const NodeSystem &other, Opt< ChangeList & > list={}) const
 
Result< HomogenousTupleType< 3, HashMap< InternedId, InternedId > > > Duplicate (const Block< const NodePath > &selection, Bool withConnections, Opt< ChangeList & > list={})
 
Result< void > AddBase (const NodeSystem &other) const
 
Result< void > ValidateTopology () const
 
Result< void > ValidatePorts (Opt< ChangeList & > list={}) const
 
Result< void > Validate (Opt< ChangeList & > list={}) const
 
Result< NodeSystemEndModification (Opt< ChangeList & > list={}, NodeSystem::FINALIZE_FLAGS finalize=NodeSystem::FINALIZE_FLAGS::CLEANUP)
 
Result< void > SetTemplate (const NodeTemplate &templ, const TemplateArguments &args) const
 
Result< void > SetTemplate (const InstantiationTrace &trace, const NodeTemplate &templ, const TemplateArguments &args) const
 
Result< void > SetDerivationHandler (const NodeSystemDerivationHandler &handler) const
 
Result< ChangeList > Apply (const ChangeList &toApply, Bool inverse, Opt< ChangeList & > track={}) const
 
const MutableNodeToNode () const
 
const StringToString (const FormatStatement *fs=nullptr) const
 
Bool operator== (const MutableRoot &other) const
 
Bool operator!= (const MutableRoot &other) const
 

Static Public Member Functions

static MAXON_ATTRIBUTE_FORCE_INLINE const MutableRootDefaultValue ()
 

Private Member Functions

 MutableRoot (NodeSystem &&system)
 
- Private Member Functions inherited from MutableNode
const NodeToImmutable () const
 
Result< HashMap< InternedId, InternedId > > Ungroup (Opt< ChangeList & > list={})
 
Result< NodeSystemMoveToNodeSystem (Opt< ChangeList & > list={})
 
- Private Member Functions inherited from NodeFunctions< BASE >
Result< NodeSelector< BASE::MUTABLE > > GetParent () const
 
Result< NodeSelector< BASE::MUTABLE > > FindChild (const InternedId &name) const
 
Result< NodeSelector< BASE::MUTABLE > > FindChild (const Id &name) const
 
template<typename NODE >
Result< typename NODE::template Selector< BASE::MUTABLE > > FindInnerNode (const NODE &baseInner) const
 
Result< PortListSelector< BASE::MUTABLE > > GetPortList (PORT_DIR dir) const
 
Result< PortListSelector< BASE::MUTABLE > > GetInputs () const
 
Result< PortListSelector< BASE::MUTABLE > > GetOutputs () const
 
Result< IteratorGetChildren () const
 
template<typename PATH >
Result< void > InitFromPath (typename maxon::nodes::details::NodeFunctionsSuper< BASE >::NodeSystemCtorParam system, PATH &&path)
 

Friends

class NodeSystemImpl
 
class NodeSystemInterface
 

Additional Inherited Members

- Private Types inherited from MutableNode
using Super = MutableNodeFunctions< MutableGNodeBase >
 
- Private Types inherited from MutableNodeFunctions< MutableGNodeBase >
using ResultFunctions = MutableNodeFunctions< maxon::nodes::details::GNodeResultBase< SUPER > >
 
using Super = NodeFunctions< MutableGNodeBase >
 
- Private Types inherited from NodeFunctions< BASE >
using Iterator = GNodeIterator< NodeSelector< BASE::MUTABLE > >
 
template<typename SUPER >
using ResultFunctions = NodeFunctions< maxon::nodes::details::GNodeResultBase< SUPER > >
 
using Super = maxon::nodes::details::NodeFunctionsSuper< BASE >
 
- Static Private Member Functions inherited from MutableNode
static MAXON_ATTRIBUTE_FORCE_INLINE const MutableNodeDefaultValue ()
 

Constructor & Destructor Documentation

◆ MutableRoot() [1/3]

MutableRoot ( )
default

Constructs a null node reference.

◆ ~MutableRoot()

◆ MutableRoot() [2/3]

MutableRoot ( MutableRoot &&  src)

◆ MutableRoot() [3/3]

MutableRoot ( NodeSystem &&  system)
explicitprivate

Member Function Documentation

◆ Reset()

void Reset ( )

Resets this @CLASS to the state it has right after default construction. This includes freeing all resources held by this @CLASS.

◆ operator=()

MutableRoot& operator= ( std::nullptr_t  )

Resets this reference to a null reference.

◆ MAXON_OPERATOR_MOVE_ASSIGNMENT()

MAXON_OPERATOR_MOVE_ASSIGNMENT ( MutableRoot  )

◆ MAXON_DISALLOW_COPY_AND_ASSIGN()

MAXON_DISALLOW_COPY_AND_ASSIGN ( MutableRoot  )

◆ CopyFrom()

Result<void> CopyFrom ( const MutableRoot src)

◆ GetLookupRepository()

AssetRepositoryRef GetLookupRepository ( ) const

Returns the asset repository to use for asset lookup during modifications. This has been set by the method call which created this MutableRoot.

Returns
The asset repository for lookup.

◆ AddChild() [1/2]

Result<MutableNode> AddChild ( const Id childId,
const Result< NodeSystem > &  base,
Opt< ChangeList & >  list = {} 
) const

Adds an instance of a node system as child to this root node. If #childId is empty, a UUID will be chosen as identifier of the child, otherwise #childId. In the latter case it is an error if this root node already has a child with that identifier.

Parameters
[in]childIdIdentifier for the child node (if empty, a UUID is chosen).
[in]baseNode system to add as an instance.
[in]listAn optional ChangeList to track the changes.
Returns
Reference to the added child.

◆ AddChild() [2/2]

Result<MutableNode> AddChild ( const Id childId,
const Result< NodeTemplate > &  templ,
const Result< TemplateArguments > &  args = GetZeroRef< ResultTemplateArguments >>(),
Opt< ChangeList & >  list = {} 
) const

Adds an instance of a node system as child to this root node. If #childId is empty, a UUID will be chosen as identifier of the child, otherwise #childId. In the latter case it is an error if this root node already has a child with that identifier.

Parameters
[in]childIdIdentifier for the child node (if empty, a UUID is chosen).
[in]templNodeTemplate of which an instantiation shall be added as an instance to this root node.
[in]argsTemplate arguments for templ.
[in]listAn optional ChangeList to track the changes.
Returns
Reference to the added child.

◆ AddChildren()

Result<void> AddChildren ( const Block< Tuple< InternedId, NodeSystem, GNodeHandle >> &  children,
Opt< ChangeList & >  list = {} 
) const

Adds several children at once to this root node. For a large number of children this is much faster then individual calls to AddChild(). However there's no check if the used identifiers are unique, you have to ensure that yourself.

Parameters
[in,out]childrenThe list of children. The first two members of the tuple are the identifier and the base node system to use (see AddChild()), these members may be modified (e.g. moved away) by the implementation. The GNodeHandle member will be overwritten by the handle of the added child.
[in]listAn optional ChangeList to track the changes.

◆ ReplaceBase()

Result<ChangeList> ReplaceBase ( const NodeSystem base,
Opt< ChangeList & >  list = {} 
) const

Replaces the base of the current node system.

Parameters
[in]baseThe new base node system.
[in]listAn optional ChangeList to track the changes.
Returns
A new change list which contains those parts of the original node system. which couldn't be restored for the new base.

◆ ReplaceChild()

Result<ChangeList> ReplaceChild ( const InternedId childId,
const NodeSystem base,
const HashMap< NodePath, NodePath > &  portMap = GetZeroRef< HashMap< NodePath, NodePath >>(),
Opt< ChangeList & >  list = {} 
) const

Replaces the base of an existing child node of this root node. This removes the original child, adds an instance of base as new child (with the same identifier), and finally tries to re-establish connections and attribute values of the original node at the new node.

With the optional portMap parameter you can handle cases where port identifiers of previous and new base don't match exactly. The node paths in portMap are relative paths of the mapped ports in the context of their node such as "<vec" or ">out". For example if an input port changes its identifier from "vec" to "vector", portMap has to contain a mapping from "<vec" to "<vector". If the port is additionally moved to a port bundle named "object", the mapping has to be from "<vec" to "<object/vector".

An entry in portMap applies to all nested ports of the mapped ports as well. Ports for which there's no entry at all in portMap keep their path.

You can't remap input ports to output ports, or ports of inner nodes of the child to ports of the child itself.

Parameters
[in]childIdIdentifier for the child node.
[in]baseNode system to use for the replacement.
[in]portMapAn optional port mapping from old port paths to new port paths.
[in]listAn optional ChangeList to track the changes.
Returns
A new change list which contains those parts of the original node system. which couldn't be restored for the new base.

◆ MoveToGroup()

Result<MutableNode> MoveToGroup ( MutableRoot &&  groupRoot,
const Id groupId,
const Block< const InternedId > &  selection,
Bool  matchPorts = true,
const FixedSizeArray< Block< const Tuple< NodePath, NodePath, NodePath >>, 2 > &  mapping = GetZeroRef<const FixedSizeArray<Block<const Tuple<NodePath, NodePath, NodePath>>, 2>>(),
Opt< ChangeList & >  list = {} 
) const

Groups the selection of direct child nodes of this node system into a new group node. groupRoot is used to set up the new group node, usually you provide an empty new node system for groupRoot. All selected nodes are moved to the group using their original identifiers, including inner connections. Afterwards the group is finalized and an instance of the group is added to this node system using the given groupId.

Connections which leave the group are kept by adding ports to the group node as needed, and connecting them correspondingly. If the used group node already has ports, these will be used where identifiers match if matchPorts is true.

In addition, you can provide a mapping to precisely control how existing group ports shall be used:

  • mapping[0] is a block of NodePath triples where the first path points to a port of this node system outside of the selection. All outgoing connections from this port to ports within the group shall use the port given by the second path at the inside of the group, and the port given by the third path at the outside of the group. These ports have to exist before in groupRoot. Usually the inside and outside path coincide, but there are special groups like the LCV node where you may want to use different ports.
  • mapping[1] is similar, here the first path points to a port within the selection. All outgoing connections from this port to ports outside of the group shall use the port given by the second path at the inside of the group, and the port given by the third path at the outside of the group.
Parameters
[in]groupRootThe MutableRoot of another (usually empty) node system which will become the group. The function will clear this reference after successful creation of the group.
[in]groupIdIdentifier for the new group within this node system (if empty, a UUID is chosen).
[in]selectionA selection of nodes, namely children of the root node. Identifiers for which no root child node exists are ignored.
[in]matchPortsUse true (the default) to use existing ports of groupRoot for connections into the group if their identifiers match, or false to disable this behaviour.
[in]mappingAn optional mapping to control the use of groupRoot ports for connections between the group and the outside.
[in]listAn optional ChangeList to track the changes.
Returns
Reference to the added group node.
See also
MutableNode::Ungroup

◆ Merge()

Result<HomogenousTupleType<3, HashMap<InternedId, InternedId> > > Merge ( const NodeSystem other,
Opt< ChangeList & >  list = {} 
) const

Merges the other node system into this node system. Top-level nodes and ports are added into this node system using new unique identifiers to prevent naming conflicts. The mapping from the original identifiers of other to the new ones is returned.

Parameters
[in]otherAnother node system to merge into this node system.
[in]listAn optional ChangeList to track the changes.
Returns
The mapping from original identifiers of other to the identifiers used for the merge:
  • first contains the mapping of top-level nodes.
  • second contains the mapping of top-level input ports.
  • third contains the mapping of top-level output ports.

◆ Duplicate()

Result<HomogenousTupleType<3, HashMap<InternedId, InternedId> > > Duplicate ( const Block< const NodePath > &  selection,
Bool  withConnections,
Opt< ChangeList & >  list = {} 
)

Duplicates the subgraph given by the selection within this node system. The nodes and ports of the subgraph are added into this node system using new unique identifiers. The mapping from the original identifiers to the new ones is returned.

Parameters
[in]selectionA selection of nodes and ports, these have to be at top level of the node system.
[in]withConnectionsTrue if incoming connections shall be duplicated as well, false otherwise.
[in]listAn optional ChangeList to track the changes.
Returns
The mapping from original identifiers to the identifiers used for the merge:
  • first contains the mapping of top-level nodes.
  • second contains the mapping of top-level input ports.
  • third contains the mapping of top-level output ports.

◆ AddBase()

Result<void> AddBase ( const NodeSystem other) const

Adds the other node system as an additional base of this node system. This merges the other node system into this node system, port identifiers are kept (unlike for Merge).

Parameters
[in]otherAnother node system to add as base and merge into this node system.

◆ ValidateTopology()

Result<void> ValidateTopology ( ) const

Validates the topology of the node system. This checks for cycles in the node graph and sets up the topological layering. Usually you don't have to call this as it gets called implicitly by ValidatePorts, Validate or EndModification.

Returns
OK on success. If there is a cycle, an IllegalStateError is returned.

◆ ValidatePorts()

Result<void> ValidatePorts ( Opt< ChangeList & >  list = {}) const

Validates the ports of the node system after a sequence of modifications. You should invoke this function whenever you have applied several modifications to the node system which affect derived ports and want them to be up-to-date. For example a new connection between two ports #a, #b might induce derived nested ports at #b if #a has nested ports.

ValidatePorts() does the following steps:

  1. The topology of the node system is checked (see ValidateTopology). If cycles are detected, an IllegalStateError is returned.
  2. Nested ports are derived:
    1. Nested ports are derived from sources to targets of connections.
    2. After this has been done for the complete node system, nested ports are derived from targets to sources of connections.
See also
$ref usernodes_modifications
$ref usernodes_derivation
Validate() which validates ports and derived attributes.
Parameters
[in]listAn optional ChangeList to track the changes.

◆ Validate()

Result<void> Validate ( Opt< ChangeList & >  list = {}) const

Completely validates the node system after a sequence of modifications. This includes the validation which happens as part of ValidatePorts(), but afterwards usernodes_attributes_derived are validated, too. So you should invoke this function whenever you have applied several modifications to the node system which affect derived attributes and want the values of derived attributes to be up-to-date.

See also
$ref usernodes_modifications
$ref usernodes_derivation
Parameters
[in]listAn optional ChangeList to track the changes.

◆ EndModification()

Result<NodeSystem> EndModification ( Opt< ChangeList & >  list = {},
NodeSystem::FINALIZE_FLAGS  finalize = NodeSystem::FINALIZE_FLAGS::CLEANUP 
)

Ends a sequence of modifications of this MutableRoot. You have to call this at the end of a sequence of modifications which has been started with NodeSystem::BeginModification, see there for an example. This MutableRoot reference is cleared by this function.

This function executes several steps:

  1. The node system is validated.
  2. The node system is finalized according to the given flags.
  3. The (exclusive) strong reference to the node system is moved from this MutableRoot to the returned NodeSystem.
Parameters
[in]listAn optional ChangeList to track the changes.
[in]finalizeThe flags to pass to NodeSystemClass::FinalizeModification.
Returns
Strong reference to the node system, this is moved from the MutableRoot to the return value.

◆ SetTemplate() [1/2]

Result<void> SetTemplate ( const NodeTemplate &  templ,
const TemplateArguments args 
) const

Sets template and arguments for the current node system if it is an instantiation of a NodeTemplate. This method has to be called within NodeTemplate::Instantiate to have a back reference to the arguments of the instantiation.

Parameters
[in]templThe NodeTemplate which instantiated the current node system.
[in]argsThe template arguments used for the instantiation.

◆ SetTemplate() [2/2]

Result<void> SetTemplate ( const InstantiationTrace &  trace,
const NodeTemplate &  templ,
const TemplateArguments args 
) const

Sets template and arguments for the current node system if it is an instantiation of a NodeTemplate. This method has to be called within NodeTemplate::Instantiate to have a back reference to the arguments of the instantiation.

Parameters
[in]traceThe instantiation trace.
[in]templThe NodeTemplate which instantiated the current node system.
[in]argsThe template arguments used for the instantiation.

◆ SetDerivationHandler()

Result<void> SetDerivationHandler ( const NodeSystemDerivationHandler &  handler) const

Sets the derivation handler for the current node system. Only NodeTemplates are allowed to change the derivation handler within their InstantiateImpl method, and they have to do so immediately after the creation of the new node system.

Parameters
[in]handlerThe derivation handler to use for the current node system.

◆ Apply()

Result<ChangeList> Apply ( const ChangeList &  toApply,
Bool  inverse,
Opt< ChangeList & >  track = {} 
) const

Applies the given change list to this node system. For an undo set inverse to true, for a redo or if you want to apply the change list to a different graph use false.

Parameters
[in]toApplyChange list to apply.
[in]inverseUse true if the inverse of the change list shall be applied (for an undo), false otherwise.
[in]trackAn optional ChangeList to track the changes.
Returns
A new change list which contains those changes of toApply which couldn't be applied, for example the change of an attribute value at a node which doesn't exist in the node system.

◆ DefaultValue()

static MAXON_ATTRIBUTE_FORCE_INLINE const MutableRoot& DefaultValue ( )
static

◆ ToNode()

const MutableNode& ToNode ( ) const

Upcasts this MutableRoot to a MutableNode.

Returns
This MutableRoot as a MutableNode.

◆ ToString()

const String& ToString ( const FormatStatement fs = nullptr) const

Returns a String representation of this @CLASS.

Parameters
[in]formatStatementNullptr or additional formatting instruction.
Returns
String representation of this @CLASS.

◆ operator==()

Bool operator== ( const MutableRoot other) const

Checks if this MutableRoot is the same object as other. Note that a MutableRoot has to be the exclusive owner of its NodeSystem, so two different MutableRoots will always point to different node systems.

Parameters
[in]otherAnother MutableRoot.
Returns
True if this is the same as other, false otherwise.

◆ operator!=()

Bool operator!= ( const MutableRoot other) const

Checks if this MutableRoot is a different object as other.

Parameters
[in]otherAnother MutableRoot.
Returns
True if this and other are different MutableRoots, false otherwise.

Friends And Related Function Documentation

◆ NodeSystemImpl

friend class NodeSystemImpl
friend

◆ NodeSystemInterface

friend class NodeSystemInterface
friend