Vuo
0.4.2
|
To write a node class in C, you need to:
#include "node.h"
Read on for details.
The easiest way to begin a new node class is with the Qt Creator wizard.
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.
Every node class needs this line.
This is metadata to help Vuo users know how to use your node class. For more information, see node.h.
This is metadata to indicate how your node class interacts with the outside world. For more information, see node.h.
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.
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.
This is the node class's metadata.
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.
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
When naming node classes and ports, you're encouraged to follow these conventions:
Modules | |
Node Metadata | |
Name, version, and behavior information to be defined by node classes. | |
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. | |
Macros | |
#define | VL() fprintf(stderr, "# %s :: %s()\n", __FILE__, __func__); |
Prints the name of the file and function to stderr (and implicitly flushes the output buffer). | |
#define | VLog(format,...) fprintf(stderr, "# %s :: %s() " format "\n", __FILE__, __func__, ##__VA_ARGS__); |
Prints the name of the file and function, and printf() -style format/arguments, to stderr (and implicitly flushes the output buffer). | |
Enumerations | |
enum | VuoPortConductivity { VuoPortAlwaysConducts, VuoPortMayConduct, VuoPortNeverConducts } |
Conductivity options for input ports. More... | |
#define VL | ( | ) | fprintf(stderr, "# %s :: %s()\n", __FILE__, __func__); |
#define VLog | ( | format, | |
... | |||
) | fprintf(stderr, "# %s :: %s() " format "\n", __FILE__, __func__, ##__VA_ARGS__); |
Prints the name of the file and function, and printf()
-style format/arguments, to stderr
(and implicitly flushes the output buffer).
Useful for debugging.
enum VuoPortConductivity |
Conductivity options for input ports.