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 ()
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, Opt< ChangeList & > list={}) const
Result< HomogenousTupleType< 3, HashMap< InternedId, InternedId > > >	Merge (const NodeSystem &other, Opt< ChangeList & > list={}) const
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 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 &	NullValue ()

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

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,
		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 mach.

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]	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.

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:

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]

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:

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

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.

NullValue()

static MAXON_ATTRIBUTE_FORCE_INLINE const MutableRoot& NullValue ( )

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