NodeΒΆ

class Node

Base class of all the document's nodes.

A node contains Plugs. A Node is implemented using a Lua table, containing said Plugs. Children nodes are contained in the Children table, if present.

Hierarchy

Children classes : class ChannelReader , class ControlNode , class DeletableNode , class Document , class EnvironmentBase , class GraphPlug , class RenderFarm , class RenderOutput , class RibAttributes , class Script , class SelectableNode , class Shader , class ShaderDataNode , class ShaderNodeIn , class ShaderNodeOut , class Texture

Members

Plugs:

string Name RW The node name

Methods:

bool result belongstoreference ( Reference ref ) Tells if the node belongs to the reference, or a sub reference
nil delete ( ) Delete a node
any value eval ( Plug plug ) Called by the framework when plug (a node's plug) must be evaluated
Node|Plug child findchild ( string path ) Find a child node or plug using a path
Node parent findparent ( string name ) Find the first parent Node of this Node of a specific class
Node result getchild ( string name ) Get a child node by its name
[string|number] name getname ( ) Get the Node name in its parent
Node parent getparent ( ) Get the parent Node of this Node
string path getpath ( ) Returns the node path as a string that can be reused with findchild
Reference reference getreference ( ) Returns the reference node it is connected to
of table getreferences ( [ topref Reference ] ) Returns the references in the document sorted depth first.
string result getstringcopy ( ) Return a copy of the node and its content as a string to be pasted
Reference reference gettopreference ( ) Returns the top reference node it is connected to
boolean editable iseditable ( ) Indicates if the node can be edited by the user in the UI
boolean indocument isindocument ( ) Tells if the node is inside a document, or is pending in the void
bool result ismoveable ( ) Tells if the node can be moved
boolean result isparent ( Node child ) Tells if this node is parent of the potential child
boolean result isreference ( ) Tells if a node comes from a reference project
boolean state isselected ( ) Tell if the node is selected
{Node} result loadfile ( string filename , [ table options ] ) load a file content in this node. Possible options are: overrideclass to enforce a specific class for the root node.
Node result loadtemplate ( string template , string name ) load a template file
nil move ( Node parent ) Move a node to a new parent
nil onpathchanged ( ) Called by the framework when the name of this node or of one of its parent is modified
{Node},string result,error pastestringcopy ( string copy , [ {} options ] ) Paste a string copy into this node
ReferenceBase refnode referencefile ( string name , string refpath , [ table options ] ) reference a file content in this node.
nil rename ( string name ) Rename a node
bool,string success,error savefile ( string filename ) load a node to a file
nil seteditable ( boolean editable ) Change the editable state of the node
nil setflags ( ) Set the node flags

Documentation

string Name RW

The node name

bool result belongstoreference ( Reference ref )

Tells if the node belongs to the reference, or a sub reference

Arguments:

  • ref The reference to test

Return:

  • result true is the node belongs to the reference or a sub reference

nil delete ( )

Delete a node

This method delete the node, without any recording in the undo/redo stack. To benefit from undo/redo, use Modifier.deletenode.

-- Assumes Node|Child is a node
 local node = _"Node|Child"
node:delete ()

any value eval ( Plug plug )

Called by the framework when plug (a node's plug) must be evaluated

The eval method is called when the node framework queries the value of a plug which is invalid or dependent on other plugs. This is the duty of the parent node to compute that value and return it.

-- Declare a Dummy class which inherits from Node
 class ("DummyClass", "Node")

-- The constructor, with dependent plugs
 function Dummy:construct (parent, name)
    Plug (self, "Plug", "HalfWidth", 0, types.int{}, 0)
    self.HalfWith:adddependencies (Document.ProjectWidth)
end

-- Evaluate HalfWidth
 function Dummy:eval (plug)
    if plug == self.HalfWidth then
        -- The framework is querying HalfWidth value
         -- Get the Document's ProjectWidth and divide by 2
         local    w = Document.ProjectWidth:get ()
        return math.floor ((w+0.5)/2)
    end
    -- If we don't know the plug to eval, return an error
     -- Note: if your class inherits a class that implements
     -- eval, then you have to call it! Use parenteval to
     -- evaluate parent classes in order
     return Plug.EvalError
end
Arguments:

  • plug

Return:

  • value The evaluated plug value

Node|Plug child findchild ( string path )

Find a child node or plug using a path

Arguments:

  • path the child node or plug path

Return:

  • child the child node or plug

Node parent findparent ( string name )

Find the first parent Node of this Node of a specific class

This method returns the first parent node of the given class.

-- Get the parent RenderPass of a Layer
 local renderpass = _"RenderPass|Layer":getparent ("RenderPass")
Arguments:

  • name the parent's class

Return:

  • parent the node's parent

Node result getchild ( string name )

Get a child node by its name

Arguments:

  • name the child name

Return:

  • result The child node

[string|number] name getname ( )

Get the Node name in its parent

print (_"RenderPass|Layer":getname ())
-- prints "Layer" in the console
Return:

  • name The Node name

Node parent getparent ( )

Get the parent Node of this Node

Return:

  • parent the node's parent

string path getpath ( )

Returns the node path as a string that can be reused with findchild

This method returns the path of a node. This path can be used by the _ function.

Note: getpath also returns an extra value, which you shouldn' care of.

-- Get the path of a node
 local layer = _"RenderPass|Layer"
local path = layer:getpath ()
print (path)
assert (path == "RenderPath|Layer"
Return:

  • path The node's path, each parent being separated by a '|'

Reference reference getreference ( )

Returns the reference node it is connected to

Return:

  • reference the reference node or nil if not referenced

of table getreferences ( [ topref Reference ] )

Returns the references in the document sorted depth first.

Arguments:

  • Reference an optional top reference

Return:

  • table references

string result getstringcopy ( )

Return a copy of the node and its content as a string to be pasted

-- Duplicate Layer in RenderPass
 local    strcopy = _"RenderPass|Layer":getstringcopy ()
local    copy = _"RenderPass":pastestringcopy (strcopy)
-- copy is a list of the copied nodes
Return:

  • result The string copy

Reference reference gettopreference ( )

Returns the top reference node it is connected to

Return:

  • reference the top reference node or nil if not referenced

boolean editable iseditable ( )

Indicates if the node can be edited by the user in the UI

The default behaviour is to return true if no IsEditable plug exists, otherwise it returns the IsEditable plug value. To render a node non editable, create a IsEditable dynamic plug, and set its value to false. Alternatively, use the seteditable function.
Return:

  • editable true if the node can be edited

boolean indocument isindocument ( )

Tells if the node is inside a document, or is pending in the void

Return:

  • indocument true if the node belongs to a document

bool result ismoveable ( )

Tells if the node can be moved

Return:

  • result True if the node can be moved

boolean result isparent ( Node child )

Tells if this node is parent of the potential child

This method returns true if the node is a parent of the given child.

-- Test that the Perspective camera is a child of the Document
 assert (Document:isparent (_"Perspective"))
-- Note that a node is considered a child of itself!
 assert (Document:isparent (Document))
Arguments:

  • child the potential child to check

Return:

  • result

boolean result isreference ( )

Tells if a node comes from a reference project

Return:

  • result true if the node is a reference

boolean state isselected ( )

Tell if the node is selected

This method returns true if the node is selected. Note that only SelectableNode nodes can be selected, thus simple Node always return false.

-- Select the Perspective camera
 local modifier = Document:modify ()
modifier.select ({_"Perspective"})
modifier.finish ()

assert (_"Perspective":isselected ())
Return:

  • state true if the node is selected

{Node} result loadfile ( string filename , [ table options ] )

load a file content in this node. Possible options are: overrideclass to enforce a specific class for the root node.

This method loads the content of a Guerilla file (.gmaterial, .glight ..) into the node. For a .gproject file, use the mergedocument function. If a node in the file is not accepted (that is, it cannot be a child of the node because of its class), the whole loading is aborted.

The returned value is a list of the root nodes contained in this file.

Use savefile to save a node into a file.

local result = Document:loadfile ("$(LIBRARY)/material/surface.gmaterial")
for k, node in pairs (result) do
    local    path = node:getpath ()
    print ("Loaded node "..path)
end
Arguments:

  • filename The file name to load
  • options Loading options as a table/dictionary

Return:

  • result The created nodes or nil if failed

Node result loadtemplate ( string template , string name )

load a template file

This method loads the content of a file into the node. The file must contain exactly one node or the method fails. If the node type is not accepted (because of its class), the method fails.

The template name is the file name without base path. Guerilla will first look up template pathes given in the TemplateDirectory Local Setting, and eventually in $(LIBRARY)/templates. The first matching file is loaded as the template.

This method is used in Guerilla to load files instead of creating new nodes from scratch, so you can provide Guerilla with default custom nodes.

-- Load the template for new renderpass
 local result = Document:loadtemplate ("new_renderpass.glayer")

Possible templates are:

  • new_document.gproject: template used when creating a new document
  • export.gproject: template used when exporting a project from Maya or another host package
  • new_rendergraph.grendergraph: template used when creating a new RenderGraph
  • new_light.glight: template used when creating a new Light
  • new_camera.glocator: template used when creating a new Camera
  • new_material.glocator: template used when creating a new Material
  • new_renderpass.glayer: template used when creating a new RenderPass
  • new_composition.gcomp: template used when creating a new Compositing
  • new_bake2d.glayer: template used when creating a new Bake2d render pass
  • new_shadernode.gnode: template used when creating a new shader macro

To use additional template directories:

Edit the guerilla.conf of your Guerilla installation and add a TemplateDirectory=/the/path/to/my/main/templates\n/the/path/to/my/other/templates line to it.

Arguments:

  • template The template file name to load
  • name The loaded template name to use

Return:

  • result The created node or nil if failed

nil move ( Node parent )

Move a node to a new parent

Arguments:

  • parent The new parent node

nil onpathchanged ( )

Called by the framework when the name of this node or of one of its parent is modified

{Node},string result,error pastestringcopy ( string copy , [ {} options ] )

Paste a string copy into this node

See also getstringcopy for an example of copy/pasting.
Arguments:

  • copy The string copy to paste
  • options The set of node creation options

Return:

  • result,error The pasted nodes, or nil if failed and an error message

ReferenceBase refnode referencefile ( string name , string refpath , [ table options ] )

reference a file content in this node.

This method is used to load a single node saved to a file using the savefile method,
Arguments:

  • name the reference node name
  • refpath the referenced file path
  • options the reference options

Return:

  • refnode the resulting reference node

nil rename ( string name )

Rename a node

Arguments:

  • name The new node name

bool,string success,error savefile ( string filename )

load a node to a file

This method saves a node and its hierarchy into a file.

-- Save the RenderPass into a temporary file
 _"RenderPass":savefile ("/tmp/renderpass.glayer")
Arguments:

  • filename The file name to save

Return:

  • success,error True if success, or nil and an error message

nil seteditable ( boolean editable )

Change the editable state of the node

Arguments:

  • editable The new state of the node

nil setflags ( )

Set the node flags