A node plug. More...

#include <Plug.h>

Classes
struct	Key

class	Outputs
	A Plug accessor to the outputs. More...

Public Types
enum	Flags { cache = 1 << 0, time_varying = 1 << 1, serial = 1 << 3, hidden = 1 << 8, channel = 1 << 9, main = 1 << 12, background = 1 << 30 }

enum	DependencyFlags { Automatic = -2 }
	Dependency flags to pass to add_value_dependency. More...

enum	EvaluationMode { EvaluationMode::Interactive = 0, EvaluationMode::Exact = 1, EvaluationMode::NoEvaluation = 2 }
	The value evaluation modes. More...

enum	Status { Status::Default, Status::Overridden, Status::Animated }
	Status of the plug. More...

Public Member Functions
	Plug (const char *name, const Value &value, uint32_t flags=0)
	Create a free plug (i.e. not attached to a Node). More...

std::string	name () const
	Return the plug name. More...

std::string	document_path () const
	Returns the path of this plug starting at the document node. More...

std::string	nice_name () const
	Returns the name of this plug to be displayed in UI (extracted from the 'nice_name' poperty of the description). More...

std::string	type_name () const
	Returns the name of the type the plug has been created with. More...

std::string	description () const
	Returns the plug's description as a json-object formatted string. More...

void	set_description (const std::string &description)
	Set the description of this plug. More...

void	set_default_value (const Value &value)
	Set the default value of this plug. More...

Value	default_value () const
	Return the default plug value. More...

void	force_varying (bool force)

Value	value (const QueryContext &qc=QueryContext::at_current_frame, EvaluationMode mode=EvaluationMode::Interactive) const
	Get the plug value. More...

bool	as_bool () const
	Returns the plug value as a bool. More...

int	as_int () const
	Returns the plug value as an integer. More...

float	as_float () const
	Returns the plug value as a float. More...

double	as_double () const
	Returns the plug value as a double. More...

const std::string &	as_string () const
	Returns the plug value as a string. More...

std::wstring	as_wstring () const

const Imath::V2d &	as_V2d () const
	Returns the plug value as a V2d. More...

const Imath::V3d &	as_V3d () const
	Returns the plug value as a V3d. More...

const Imath::V4d &	as_V4d () const
	Returns the plug value as a V4d. More...

const Imath::V2i &	as_V2i () const
	Returns the plug value as a V2i. More...

const Imath::V3i &	as_V3i () const
	Returns the plug value as a V3i. More...

const Imath::V4i &	as_V4i () const
	Returns the plug value as a V4i. More...

const Imath::M44d &	as_M44d () const
	Returns the plug value as a M44d. More...

const Imath::Box3f &	as_Box3f () const
	Returns the plug value as a Box3f. More...

const Imath::Color4f &	as_Color4f () const
	Returns the plug value as a Color4f. More...

const Imath::Quatd &	as_Quatd () const
	Returns the plug value as a Quatd. More...

std::shared_ptr< const class UserData >	as_user_data () const
	Returns the plug value as a user data. More...

void	set_value (const Value &value, bool undo_stack=false)
	Set a value. More...

void	set_value (const Value &value, const ModificationContext &mc)
	Set a value. More...

void	set_value (const Value &value, const ModificationContext &mc, int32_t start, int32_t end)
	Set a value with a custom invalidation range. More...

bool	can_connect (const Plug &other) const
	Check if the plug can be connected. More...

bool	is_connected () const
	Return true if the plug has an input connection. More...

bool	is_internal () const
	Return true if this plug should be ignored by users and the UI. More...

bool	is_channel () const
	Return true if this plug is a channel. More...

void	set_channel (bool channel)
	Set the channel status of this plug. More...

bool	is_constant () const
	Return true if the plug value is constant in time. More...

bool	is_evaluated () const
	Return true if this plug is evaluated. More...

bool	is_keyable () const
	Return true if this plug is keyable. More...

bool	is_main_plug () const
	Return true if the plug is a main plug, i-e, is displayed by default. More...

bool	is_auto_connect () const
	Return true if the plug connects when a node is dropped over a connection. More...

bool	is_dynamic () const
	Return true if the plug is dynamic. More...

bool	is_animable () const
	Return true if this plug is animable. More...

bool	is_mutable () const
	Return true if this plug is mutable (i.e. can be modified). More...

Plug::Status	status () const
	Return the plug status. More...

void	connect (const Plug &src, bool undo_stack=false, bool serialize=false)
	Connect src to this plug. More...

void	disconnect (bool undo_stack=false)
	If true, the connection is restored if an undo is performed. Ignored if undo_stack is false. More...

void	add_valued_dependency (const Plug &dependence, int32_t index=-1, int32_t time_offset=0, bool undo_stack=false, bool serialize=false)

void	remove_valued_dependency (const Plug &dependence, bool undo_stack=true)

void	remove_valued_dependency (uint32_t index, bool undo_stack=true)

void	remove_all_valued_dependencies (bool undo_stack=true)

std::vector< Plug >	notification_dependencies ()

void	add_notification_dependency (const Plug &dependence, bool serialize=false)

void	remove_notification_dependency (const Plug &dependence, bool notify=true)

void	remove_all_notification_dependencies (bool notify=true)

std::vector< Plug >	back_dependencies ()

size_t	back_dependencies_count ()

std::vector< Plug >	valued_dependencies ()

uint32_t	valued_dependencies_count ()

bool	has_valued_dependency (const Plug &plug)

void	touch ()

void	touch (int first_frame, int last_frame, bool rest)

void	set_to_default ()
	Reset the plug default value flag. More...

uint32_t	flags () const
	Return the plug flags. More...

void	set_flags (uint32_t flags)
	Set the plug flags. More...

Plug	input () const
	Get the input plug. More...

Outputs	outputs () const
	Return the node plugs iteration. More...

std::vector< Plug >	channels ()
	Return this plug exposed channels. More...

bool	has_node () const

Node	node () const

std::vector< Plug >	walk_down () const
	Returns the next plugs to visit to traverse the graph from inputs to outputs, stating at this plug. More...

bool	operator== (const Plug &o) const

bool	operator!= (const Plug &o) const

std::shared_ptr< NodeDelegate >	node_delegate () const
	Return a node delegate for this plug. More...

std::unordered_map< float, Key >	key_frames () const
	Get the plug keys in targeted layer. More...

std::unordered_map< float, Key >	key_frames_in_layer (const Node &layer) const
	Get the plug keys in the layer. More...

Static Public Member Functions
static bool	validate_name (const char *plug_name)
	Return true if the name is a valid plug name. More...

Public Attributes
void *	_plug

Static Public Attributes
static const int32_t	AllFrames = int32_t(0x80000000)

Detailed Description

A node plug.

A Plug is a node attribute. It can hold a Value object.

A Plug can be an input Plug, in that case, another plug can be connected into it and propagate its value in it.

A plug can be an output Plug, in that case, its value is evaluated using dependancies on other plugs and an evaluation function. Output Plugs can't have an input connection.

The Value of a Plug can be :

The Plug stored Value
The Value of the input connected Plug, for input Plugs.
The computed Value for output Plugs.

Member Enumeration Documentation

◆ DependencyFlags

enum maquina::Plug::DependencyFlags

Dependency flags to pass to add_value_dependency.

Enumerator
Automatic

◆ EvaluationMode

enum maquina::Plug::EvaluationMode

strong

The value evaluation modes.

Enumerator
Interactive	The value is evaluated using an approximation method. This is fast but this may not return the correct result if the value has complex temporal dependencies.
Exact	The value is perfectly evaluated.
NoEvaluation	The value is not evaluated, the last evaluated value is returned.

◆ Flags

enum maquina::Plug::Flags

Enumerator
cache	This plug value should be keeped in memory because it takes time to be computed.
time_varying	This plug is never constant.
serial	This plug value should be serialized.
hidden	This plug should be hidden in the UI by default.
channel	This plug is a channel.
main	This plug is always visible in the node editor.
background	This plug is evaluated by the background engine.

◆ Status

enum maquina::Plug::Status

strong

Status of the plug.

Enumerator
Default	Untouched plug.
Overridden	Plug is connected to an animation graph and is overridden by a single value.
Animated	Plug is connected to an animation graph and is overridden by an animated value.

Constructor & Destructor Documentation

◆ Plug()

maquina::Plug::Plug	(	const char *	name,
		const Value &	value,
		uint32_t	flags = `0`
	)

Create a free plug (i.e. not attached to a Node).

Parameters

name	Name of the plug
value	Value of the plug
flags	Plug flags

Member Function Documentation

◆ add_notification_dependency()

void maquina::Plug::add_notification_dependency	(	const Plug &	dependence,
		bool	serialize = `false`
	)

◆ add_valued_dependency()

void maquina::Plug::add_valued_dependency	(	const Plug &	dependence,
		int32_t	index = `-1`,
		int32_t	time_offset = `0`,
		bool	undo_stack = `false`,
		bool	serialize = `false`
	)

Add a valued dependence to this plug.

The evaluation function of this plug will receive values from the given dependence plug. {std::runtime_error,RuntimeError} if this plug is not evaluated.

Parameters

dependence	the new dependence plug
index	index in the evaluation context, use a negative value for automatically managed index
undo_stack	if true, use a modification to be able to revert this action
serialize	if true and undo_stack is false, this dependency will be serialized on save.

◆ as_bool()

bool maquina::Plug::as_bool ( ) const

Returns the plug value as a bool.

You must be sure the plug value is an integer, a float or a boolean or you get false.

◆ as_Box3f()

const Imath::Box3f& maquina::Plug::as_Box3f ( ) const

Returns the plug value as a Box3f.

You must be sure the plug value is a Box3f or you will have an empty box.

◆ as_Color4f()

const Imath::Color4f& maquina::Plug::as_Color4f ( ) const

Returns the plug value as a Color4f.

You must be sure the plug value is a Color4f or you will have {0,0,0,0}.

◆ as_double()

double maquina::Plug::as_double ( ) const

Returns the plug value as a double.

You must be sure the plug value is an integer, a float or a boolean or you get 0.0.

◆ as_float()

float maquina::Plug::as_float ( ) const

Returns the plug value as a float.

You must be sure the plug value is an integer, a float or a boolean or you get 0.f.

◆ as_int()

int maquina::Plug::as_int ( ) const

Returns the plug value as an integer.

You must be sure the plug value is an integer, a float or a boolean or you get 0.

◆ as_M44d()

const Imath::M44d& maquina::Plug::as_M44d ( ) const

Returns the plug value as a M44d.

You must be sure the plug value is a M44d or you will have an identity matrix.

◆ as_Quatd()

const Imath::Quatd& maquina::Plug::as_Quatd ( ) const

Returns the plug value as a Quatd.

You must be sure the plug value is a Quatd or you will have an identity quaternion.

◆ as_string()

const std::string& maquina::Plug::as_string ( ) const

Returns the plug value as a string.

You must be sure the plug value is a string or you will have an empty string.

◆ as_user_data()

std::shared_ptr<const class UserData> maquina::Plug::as_user_data ( ) const

Returns the plug value as a user data.

If the underlying time is not a used data, a nullptr is returned.

◆ as_V2d()

const Imath::V2d& maquina::Plug::as_V2d ( ) const

Returns the plug value as a V2d.

You must be sure the plug value is a V2d or you will have {0,0}.

◆ as_V2i()

const Imath::V2i& maquina::Plug::as_V2i ( ) const

Returns the plug value as a V2i.

You must be sure the plug value is a V2i or you will have {0,0}.

◆ as_V3d()

const Imath::V3d& maquina::Plug::as_V3d ( ) const

Returns the plug value as a V3d.

You must be sure the plug value is a V3d or you will have {0,0,0}.

◆ as_V3i()

const Imath::V3i& maquina::Plug::as_V3i ( ) const

Returns the plug value as a V3i.

You must be sure the plug value is a V3i or you will have {0,0,0}.

◆ as_V4d()

const Imath::V4d& maquina::Plug::as_V4d ( ) const

Returns the plug value as a V4d.

You must be sure the plug value is a V4d or you will have {0,0,0,0}.

◆ as_V4i()

const Imath::V4i& maquina::Plug::as_V4i ( ) const

Returns the plug value as a V4i.

You must be sure the plug value is a V4i or you will have {0,0,0,0}.

◆ as_wstring()

std::wstring maquina::Plug::as_wstring ( ) const

◆ back_dependencies()

std::vector<Plug> maquina::Plug::back_dependencies ( )

◆ back_dependencies_count()

size_t maquina::Plug::back_dependencies_count ( )

◆ can_connect()

bool maquina::Plug::can_connect ( const Plug & other ) const

Check if the plug can be connected.

Check if a loop can be be created by connecting those two plugs

Parameters

other The plug to be connected

◆ channels()

std::vector<Plug> maquina::Plug::channels ( )

Return this plug exposed channels.

◆ connect()

void maquina::Plug::connect	(	const Plug &	src,
		bool	undo_stack = `false`,
		bool	serialize = `false`
	)

Connect src to this plug.

The value of src will be propagated to this plug.If true, the connection will be serialized in the file. If undo_stack is true, the connection is assumed to be serialized, and serialize is ignored.

Parameters

src	The source plug
undo_stack	If true, the connection is reverted if an undo is performed. Ignored if undo_stack is true.

◆ default_value()

Value maquina::Plug::default_value ( ) const

Return the default plug value.

The default value is the value the plug has been created with. This is not the REST value (the value with no animation).

◆ description()

std::string maquina::Plug::description ( ) const

Returns the plug's description as a json-object formatted string.

◆ disconnect()

void maquina::Plug::disconnect ( bool undo_stack = false )

If true, the connection is restored if an undo is performed. Ignored if undo_stack is false.

◆ document_path()

std::string maquina::Plug::document_path ( ) const

Returns the path of this plug starting at the document node.

◆ flags()

uint32_t maquina::Plug::flags ( ) const

Return the plug flags.

◆ force_varying()

void maquina::Plug::force_varying ( bool force )

Force the value of this plug to be time varying. true if this plug should always be considered as time varying, false if the evaluation engine should determine it iself.

◆ has_node()

bool maquina::Plug::has_node ( ) const

◆ has_valued_dependency()

bool maquina::Plug::has_valued_dependency ( const Plug & plug )

Check if this plug has a valued dependency on another plug.

Parameters

plug	The plug we want to check if is a dependence.

Returns: True if plug is a valued dependence of this plug.

◆ input()

Plug maquina::Plug::input ( ) const

Get the input plug.

Exceptions

std::runtime_error if the plug is not connected

◆ is_animable()

bool maquina::Plug::is_animable ( ) const

Return true if this plug is animable.

◆ is_auto_connect()

bool maquina::Plug::is_auto_connect ( ) const

Return true if the plug connects when a node is dropped over a connection.

A node should have an input and an output plug for every types the node can auto connect.

◆ is_channel()

bool maquina::Plug::is_channel ( ) const

Return true if this plug is a channel.

◆ is_connected()

bool maquina::Plug::is_connected ( ) const

Return true if the plug has an input connection.

◆ is_constant()

bool maquina::Plug::is_constant ( ) const

Return true if the plug value is constant in time.

◆ is_dynamic()

bool maquina::Plug::is_dynamic ( ) const

Return true if the plug is dynamic.

A dynamic plug can be dynamically created or removed

◆ is_evaluated()

bool maquina::Plug::is_evaluated ( ) const

Return true if this plug is evaluated.

◆ is_internal()

bool maquina::Plug::is_internal ( ) const

Return true if this plug should be ignored by users and the UI.

◆ is_keyable()

bool maquina::Plug::is_keyable ( ) const

Return true if this plug is keyable.

◆ is_main_plug()

bool maquina::Plug::is_main_plug ( ) const

Return true if the plug is a main plug, i-e, is displayed by default.

◆ is_mutable()

bool maquina::Plug::is_mutable ( ) const

Return true if this plug is mutable (i.e. can be modified).

◆ key_frames()

std::unordered_map<float, Key> maquina::Plug::key_frames ( ) const

Get the plug keys in targeted layer.

◆ key_frames_in_layer()

std::unordered_map<float, Key> maquina::Plug::key_frames_in_layer ( const Node & layer ) const

Get the plug keys in the layer.

◆ name()

std::string maquina::Plug::name ( ) const

Return the plug name.

◆ nice_name()

std::string maquina::Plug::nice_name ( ) const

Returns the name of this plug to be displayed in UI (extracted from the 'nice_name' poperty of the description).

◆ node()

Node maquina::Plug::node ( ) const

◆ node_delegate()

std::shared_ptr<NodeDelegate> maquina::Plug::node_delegate ( ) const

Return a node delegate for this plug.

◆ notification_dependencies()

std::vector<Plug> maquina::Plug::notification_dependencies ( )

◆ operator!=()

bool maquina::Plug::operator!= ( const Plug & o ) const

inline

◆ operator==()

bool maquina::Plug::operator== ( const Plug & o ) const

inline

◆ outputs()

Outputs maquina::Plug::outputs ( ) const

Return the node plugs iteration.

◆ remove_all_notification_dependencies()

void maquina::Plug::remove_all_notification_dependencies ( bool notify = true )

◆ remove_all_valued_dependencies()

void maquina::Plug::remove_all_valued_dependencies ( bool undo_stack = true )

Remove all valued dependencies from this plug.

Parameters

undo_stack if true, use a modification to be able to revert this action.

◆ remove_notification_dependency()

void maquina::Plug::remove_notification_dependency	(	const Plug &	dependence,
		bool	notify = `true`
	)

◆ remove_valued_dependency() [1/2]

void maquina::Plug::remove_valued_dependency	(	const Plug &	dependence,
		bool	undo_stack = `true`
	)

Remove a valued dependence from this plug.

The dependence is identified by the given plug. If there is more than one dependence on the given plug, on the first one is removed (the one with the smallest index). (see modify_begin()).

Parameters

dependence	dependence plug
undo_stack	if true, use a modification to be able to revert this action.

◆ remove_valued_dependency() [2/2]

void maquina::Plug::remove_valued_dependency	(	uint32_t	index,
		bool	undo_stack = `true`
	)

Remove a valued dependence from this plug.

The dependence is identified by an index.

Parameters

index	index of the dependence
undo_stack	if true, use a modification to be able to revert this action.

◆ set_channel()

void maquina::Plug::set_channel ( bool channel )

Set the channel status of this plug.

◆ set_default_value()

void maquina::Plug::set_default_value ( const Value & value )

Set the default value of this plug.

◆ set_description()

void maquina::Plug::set_description ( const std::string & description )

Set the description of this plug.

◆ set_flags()

void maquina::Plug::set_flags ( uint32_t flags )

Set the plug flags.

◆ set_to_default()

void maquina::Plug::set_to_default ( )

Reset the plug default value flag.

◆ set_value() [1/3]

void maquina::Plug::set_value	(	const Value &	value,
		bool	undo_stack = `false`
	)

Set a value.

◆ set_value() [2/3]

void maquina::Plug::set_value	(	const Value &	value,
		const ModificationContext &	mc
	)

Set a value.

◆ set_value() [3/3]

void maquina::Plug::set_value	(	const Value &	value,
		const ModificationContext &	mc,
		int32_t	start,
		int32_t	end
	)

Set a value with a custom invalidation range.

The plug is set to the new value, but its back dependent plugs will be invalidated but only on the frame range specified by the user.

◆ status()

Plug::Status maquina::Plug::status ( ) const

Return the plug status.

Check if the plug is overriden, animated or untouched

◆ touch() [1/2]

void maquina::Plug::touch ( )

◆ touch() [2/2]

void maquina::Plug::touch	(	int	first_frame,
		int	last_frame,
		bool	rest
	)

Invalidate a plug sub domain

Parameters

first_frame	The first frame to invalidate.
last_frame	The last frame to invalidate.
rest	If true, invalidate the rest value of this plug.

◆ type_name()

std::string maquina::Plug::type_name ( ) const

Returns the name of the type the plug has been created with.

◆ validate_name()

static bool maquina::Plug::validate_name ( const char * plug_name )

static

Return true if the name is a valid plug name.

◆ value()

Value maquina::Plug::value	(	const QueryContext &	qc = `QueryContext::at_current_frame`,
		EvaluationMode	mode = `EvaluationMode::Interactive`
	)		const

Get the plug value.

Parameters

qc	Specifies the context of the value query (the frame or the default value)
mode	Specifies the method to use to evaluate the value

◆ valued_dependencies()

std::vector<Plug> maquina::Plug::valued_dependencies ( )

Return all valued dependencies of this plug, ordered by their indices.

◆ valued_dependencies_count()

uint32_t maquina::Plug::valued_dependencies_count ( )

◆ walk_down()

std::vector<Plug> maquina::Plug::walk_down ( ) const

Returns the next plugs to visit to traverse the graph from inputs to outputs, stating at this plug.

This function will returns all the output plugs which depend on this plug and all the plugs connected to this plug.

Member Data Documentation

◆ _plug

void* maquina::Plug::_plug

◆ AllFrames

const int32_t maquina::Plug::AllFrames = int32_t(0x80000000)

static

The documentation for this class was generated from the following file:

include/Maquina/Plug.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ DependencyFlags

◆ EvaluationMode

◆ Flags

◆ Status

Constructor & Destructor Documentation

◆ Plug()

Member Function Documentation

◆ add_notification_dependency()

◆ add_valued_dependency()

◆ as_bool()

◆ as_Box3f()

◆ as_Color4f()

◆ as_double()

◆ as_float()

◆ as_int()

◆ as_M44d()

◆ as_Quatd()

◆ as_string()

◆ as_user_data()

◆ as_V2d()

◆ as_V2i()

◆ as_V3d()

◆ as_V3i()

◆ as_V4d()

◆ as_V4i()

◆ as_wstring()

◆ back_dependencies()

◆ back_dependencies_count()

◆ can_connect()

◆ channels()

◆ connect()

◆ default_value()

◆ description()

◆ disconnect()

◆ document_path()

◆ flags()

◆ force_varying()

◆ has_node()

◆ has_valued_dependency()

◆ input()

◆ is_animable()

◆ is_auto_connect()

◆ is_channel()

◆ is_connected()

◆ is_constant()

◆ is_dynamic()

◆ is_evaluated()

◆ is_internal()

◆ is_keyable()

◆ is_main_plug()

◆ is_mutable()

◆ key_frames()

◆ key_frames_in_layer()

◆ name()

◆ nice_name()

◆ node()

◆ node_delegate()

◆ notification_dependencies()

◆ operator!=()

◆ operator==()

◆ outputs()

◆ remove_all_notification_dependencies()

◆ remove_all_valued_dependencies()

◆ remove_notification_dependency()

◆ remove_valued_dependency() [1/2]

◆ remove_valued_dependency() [2/2]

◆ set_channel()

◆ set_default_value()

◆ set_description()

◆ set_flags()

◆ set_to_default()

◆ set_value() [1/3]