Vuo  0.4.1
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Modules | Enumerations

Description

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

Read on for details.

Getting started

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

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 a provider 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.

const char * moduleName = "Add Two Integers";
const char * moduleDescription = "Outputs the sum of the input integers.";
const unsigned int moduleVersion = 100;
const char * moduleKeywords[] = { "sum" };

This is metadata to help Vuo users know how to use your node class. For more information, see node.h.

const bool nodeProvides = false;
const bool nodeConsumes = false;

This is metadata to indicate how your node class interacts with the outside world. For more information, see node.h.

void nodeEvent(
) {
*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.

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"
const char * moduleName = "Count By One";
const char * moduleDescription = "Counts up by one when the receptor port receives an event.";
const unsigned int moduleVersion = 100;
const char * moduleKeywords[] = { "count", "increment" };
const bool nodeProvides = false;
const bool nodeConsumes = false;

This is the node class's metadata.

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

) {
*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).

} {
}

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

Naming node classes and ports

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

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.
 

Enumerations

enum  VuoPortConductivity { VuoPortAlwaysConducts, VuoPortMayConduct, VuoPortNeverConducts }
 Conductivity options for input ports. More...
 

Enumeration Type Documentation

Conductivity options for input ports.

Enumerator
VuoPortAlwaysConducts 

An event received by this input port is conducted to all output ports.

VuoPortMayConduct 

An event received by this input port may be conducted to all, some, or none of the output ports.

VuoPortNeverConducts 

An event received by this input port is never conducted to any output port.