#include <nodesystem.h>

Inheritance diagram for MutableRoot:

[legend]

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 ()

MutableRoot &	operator= (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< MutableNode >	AddChild (const Id &childId, const Result< NodeSystem > &base, Opt< ChangeList & > list={}) const

Result< MutableNode >	AddChild (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< 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

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< NodeSystem >	EndModification (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 MutableNode &	ToNode () const

const String &	ToString (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 MutableRoot &	DefaultValue ()

Private Member Functions
	MutableRoot (NodeSystem &&system)

Private Member Functions inherited from MutableNode
const Node &	ToImmutable () const

Result< HashMap< InternedId, InternedId > >	Ungroup (Opt< ChangeList & > list={})

Result< NodeSystem >	MoveToNodeSystem (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< Iterator >	GetChildren () 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 MutableNode &	DefaultValue ()

Constructor & Destructor Documentation

◆ MutableRoot() [1/3]

MutableRoot ( )

default

Constructs a null node reference.

◆ ~MutableRoot()

~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]	childId	Identifier for the child node (if empty, a UUID is chosen).
[in]	base	Node system to add as an instance.
[in]	list	An 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< Result< TemplateArguments >>()`,
		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]	childId	Identifier for the child node (if empty, a UUID is chosen).
[in]	templ	NodeTemplate of which an instantiation shall be added as an instance to this root node.
[in]	args	Template arguments for templ.
[in]	list	An 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]	children	The 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]	list	An 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]	base	The new base node system.
[in]	list	An 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]	childId	Identifier for the child node.
[in]	base	Node system to use for the replacement.
[in]	portMap	An optional port mapping from old port paths to new port paths.
[in]	list	An 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]	groupRoot	The 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]	groupId	Identifier for the new group within this node system (if empty, a UUID is chosen).
[in]	selection	A selection of nodes, namely children of the root node. Identifiers for which no root child node exists are ignored.
[in]	matchPorts	Use 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]	mapping	An optional mapping to control the use of groupRoot ports for connections between the group and the outside.
[in]	list	An 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]	other	Another node system to merge into this node system.
[in]	list	An 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]	selection	A selection of nodes and ports, these have to be at top level of the node system.
[in]	withConnections	True if incoming connections shall be duplicated as well, false otherwise.
[in]	list	An 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] other Another 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:

The topology of the node system is checked (see ValidateTopology). If cycles are detected, an IllegalStateError is returned.
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] list An 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] list An 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:

The node system is validated.
The node system is finalized according to the given flags.
The (exclusive) strong reference to the node system is moved from this MutableRoot to the returned NodeSystem.

Parameters

[in]	list	An optional ChangeList to track the changes.
[in]	finalize	The 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]	templ	The NodeTemplate which instantiated the current node system.
[in]	args	The 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]	trace	The instantiation trace.
[in]	templ	The NodeTemplate which instantiated the current node system.
[in]	args	The 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] handler The 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]	toApply	Change list to apply.
[in]	inverse	Use true if the inverse of the change list shall be applied (for an undo), false otherwise.
[in]	track	An 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] formatStatement Nullptr 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] other Another 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] other Another 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

Detailed Description

Public Member Functions

Static Public Member Functions

Private Member Functions

Friends

Additional Inherited Members

Constructor & Destructor Documentation

◆ MutableRoot() [1/3]

◆ ~MutableRoot()

◆ MutableRoot() [2/3]

◆ MutableRoot() [3/3]

Member Function Documentation

◆ Reset()

◆ operator=()

◆ MAXON_OPERATOR_MOVE_ASSIGNMENT()

◆ MAXON_DISALLOW_COPY_AND_ASSIGN()

◆ CopyFrom()

◆ GetLookupRepository()

◆ AddChild() [1/2]

◆ AddChild() [2/2]

◆ AddChildren()

◆ ReplaceBase()

◆ ReplaceChild()

◆ MoveToGroup()

◆ Merge()

◆ Duplicate()

◆ AddBase()

◆ ValidateTopology()

◆ ValidatePorts()

◆ Validate()

◆ EndModification()

◆ SetTemplate() [1/2]

◆ SetTemplate() [2/2]

◆ SetDerivationHandler()

◆ Apply()

◆ DefaultValue()

◆ ToNode()

◆ ToString()

◆ operator==()

◆ operator!=()

Friends And Related Function Documentation

◆ NodeSystemImpl

◆ NodeSystemInterface