Writing a Node Class

Description

To write a node class in C, you need to:

• #include "node.h"
  • This file contains macros needed for writing node classes.
• Define global variables for the node class's metadata.
  • The metadata includes information like name, version, and keywords.
• Implement either the nodeEvent function (for stateless node classes) or the nodeInstanceEvent, nodeInstanceInit, and nodeInstanceFini functions (for stateful node classes).
  • The nodeEvent or nodeInstanceEvent function is called when an event reaches one or more of the node's input ports, or in other words, when the node executes. This function can receive data and events through input ports and send data and events through output ports.
  • The nodeInstanceInit function is called once when the composition starts running. It initializes the node's state.
  • The nodeInstanceFini function is called once when the composition stops running. It can be used for cleanup, if needed.

Read on for details.

Getting started

The easiest way to begin a new node class is with the Qt Creator wizard.

Todo:

: Qt Creator wizard for custom node classes - https://b33p.net/kosada/node/4015. Describe how to create a node class C file, how to build, how to install.

Stateless node classes

Stateless node classes are simpler, so let's start with them. A stateless node (for example, Add or Read from Console) can take in data and events through input ports. If it's an interface node, it can also see the world outside the composition (filesystem, network, devices). But when a stateless node executes, it can't look up information about previous executions. It has no way to store its state in memory.

Let's walk through a simple example: a simplified version of the Add node class. We'll call it Add Two Integers. This node class will output the sum of two integers.

The node class will be implemented in a file called example.addTwoIntegers.c. The file name determines the class's machine name (as opposed to its human-readable name, Add Two Integers). So the machine name is example.addTwoIntegers.

#include "node.h"

Every node class needs this line.

VuoModuleDetails({
                     "name" : "Add Two Integers",
                     "description" : "Adds the terms and outputs their sum.",
                     "keywords" : [ "sum" ],
                     "version" : "1.0.0",
                     "dependencies" : [ ],
                     "node": {
                         "isInterface" : false
                     }
                 });

This is metadata to help Vuo users know how to use your node class. For more information, see module.h (which is included by node.h).

void nodeEvent(
    VuoInputData(VuoInteger, {"default":0}) in0, 
    VuoInputData(VuoInteger, {"default":0}) in1, 
    VuoOutputData(VuoInteger) sum
) {
    *sum = in0 + in1;
}

This function is called each time the node executes. The input and output ports are defined here, as parameters of this function. An Add Two Integers node has two input ports called in0 and in1 and an output port called sum. The function adds the two integers supplied by the input ports and sends their sum through the output port.

The second argument of the VuoInputData macro, {"default":0}, assigns the input port a default value of 0. In a running composition, the input port data keeps its default value until the port receives some other data through an incoming cable or unless the port has been assigned a constant value.

In addition to the port's default value, the second argument of the VuoInputData macro can specify other details about the port. These details can be used by input editor plugins in the Vuo Editor when the user is editing the constant value of the port. For example, VuoInputData(VuoInteger, {"default":0,"suggestedMin":0}) would cause the port's input editor to display a spin box widget whose buttons have a minimum value of 0 (but whose text box has no limit). Some input editors support suggestedMin, suggestedMax, and suggestedStep. suggestedMin and suggestedMax provide a hint about the typical range of values for this port (but don't actually limit the values that the port can receive). suggestedStep is the suggested step amount for spin box and slider widgets. Some input editors may support additional details about the port. The details must be JSON-formatted.

For more information on input and output ports, see node.h.

For more information on VuoInteger and other built-in port types, see Built-in Types.

Stateful node classes

A stateful node class (for example, Count or Recur) keeps track of its state, which is stored in node instance data. The node instance data can be of any data type. It's returned by nodeInstanceInit and passed as an argument to nodeInstanceEvent and nodeInstanceFini.

Let's walk through another example: a simplified version of the Count node class. We'll call it Count by One. A Count by One node will output a count, which will be incremented whenever the node executes.

The node class will be implemented in a file called example.countByOne.c, so its machine name will be example.countByOne.

#include "node.h"

VuoModuleDetails({
                     "name" : "Count By One",
                     "description" : "Counts up by one when the refresh port receives an event.",
                     "keywords" : [ "increment" ],
                     "dependencies" : [ ],
                     "version" : "1.0.0",
                     "node": {
                         "isInterface" : false
                     }
                 });

This is the node class's metadata.

VuoInteger nodeInstanceInit()
{
    return 0;
}

This function is called once for each Count by One node when the composition starts running. Its return type determines the type of the node instance data (VuoInteger). It returns 0, so each Count by One node starts off with a count of 0.

void nodeInstanceEvent(
    VuoInstanceData(VuoInteger) countState,
    VuoOutputData(VuoInteger) count
) {
    *countState = *countState + 1;
    *count = *countState;
}

This function is called each time the node executes. The function updates the node instance data (countState) and sends the updated count to the output port (count).

void nodeInstanceFini(
    VuoInstanceData(VuoInteger) countState,
} {

}

This function is called once for each Count by One node when the composition is stopped. The nodeInstanceFini function can clean up after nodeInstanceInit and nodeInstanceEvent if needed (for example, closing files and sockets). For the Count by One node class, like most node classes, no cleanup is needed.

Some node classes need to store heap-allocated data in their node instance data. For information on memory management, see

Todo:

Managing Memory.

Type-converter nodes

In the Vuo Editor, when the user attempts to connect a cable between ports of different types (for example, VuoInteger to VuoReal), the connection is bridged by a type-converter node (for example, Convert Integer to Real) if one is available. This type-converter node is rendered in a special collapsed form and is attached to the input port to which it's connected. Currently, only certain built-in nodes may be used as type converters. Eventually, any node with a single data-and-event input port and a single data-and-event output port of a different type may be used as a type converter. Vuo's rendering engine decides when a node should be rendered as a collapsed, attached type converter, based on its connections to other nodes.

Naming node classes and ports

When naming node classes and ports, you're encouraged to follow these conventions:

• Node class names should:
  • be verb phrases (Subtract, not Difference)
  • use title case (Chicago Manual of Style) (Count within Range)
• Node class file names should:
  • use lower camel case (vuo.math.isLessThan.integer)
  • include a lower camel case data type name as the last term, if and only if there are multiple versions of the node specializing in different data types
• Port names should:
  • be full words or phrases, not abbreviations (increment, not incr)
  • use lower-camel-case (wrapMode)
  • for nodes that may be used as type converters, be descriptive enough that the node's functionality can be understood even when the node's title is hidden (roundedInteger, not integer)
• Trigger port names should:
  • be past-tense verb phrases (started)

Modules
	Node Instance Data
	Node instance data structure.
	Node Parameters
	Parameter decorations to be used by node classes.
	Node Methods: Stateless
	Event handler method to be implemented by node classes.
	Node Methods: Stateful
	Setup, event handler, and teardown methods to be implemented by stateful node classes.

Files
file	module.h
	Prototypes for node class, type, and library module implementations.