|
Vuo
0.4.9
|
In a node, each data-and-event port has a port type, which is its type of data. Vuo comes with many built-in port types, such as VuoInteger, VuoReal, VuoBoolean, and VuoText. For a complete list of built-in port types, see Built-in Types. You can also create your own custom port types.
One reason you might want to create your own port type is to allow a node set to pass some structured data between nodes. For example, the vuo.image node set uses a port type called VuoImage to pass image data between nodes. You can connect a cable from a VuoImage output port to a VuoImage input port.
Another reason you might want to create your own port type is to create an input port that provides a menu of options. For example, in the Vuo Editor, when you double-click on the constant flag for the Make Wave node's wave input port, it pops up a menu that lets you select the type of wave (sine, triangle, or sawtooth). The first step toward creating that menu was to define a port type called VuoWave and use it in the Make Wave node class, as described in this documentation. The other step was to create an input editor for the VuoWave type, as described in Developing an Input Editor.
The easiest way to start developing a port type is with the example Qt project for a port type, which is provided with the Vuo SDK.
example/type/MyPairOfReals).MyPairOfReals.pro, change MyPairOfReals.c and MyPairOfReals.h to your port type file names.MyPairOfReals.c and MyPairOfReals.h to your port type file names.When writing a node class, you should now be able to use your port type in VuoInputData and VuoOutputData. To allow your node class to compile:
#include "MyPairOfReals.h" to the node class.vuo-compile, use the --header-search-path flag to specify the folder that contains MyPairOfReals.h.The next step is to modify the port type's source code so that it actually implements the data type you want. To learn how, read on.
To implement a port type, you need to:
#include "type.h".When you implement a port type, the first thing you have to decide is the type name. Every port type has two names: a type name (like VuoInteger and a title (like "Integer"). The type name is how node classes refer to your port type. The title is what Vuo Editor users see when they hover over a port to see its information. When you create a port type, the file name is the type name. For example, the port type with name VuoInteger is implemented in files called VuoInteger.c and VuoInteger.h.
Here's an example of metadata for a port type:
The VuoModuleDetails macro takes a JSON-formatted argument. The argument includes the title for the port type, a version number to help users upgrade and manage their port types, a description, and an array of keywords. The description and keywords are not currently used.
For more information, see the documentation for VuoModuleDetails.
Your port type needs to be implemented with some C data type, such as a long, a char*, or a struct. Use a typedef to make your port type name an alias for this C data type.
Here's one example:
Here's another example:
A port type can be composed of other port types. For example:
When you implement a port type, you have to implement certain functions to convert values of your port type to and from JSON, and to get a textual summary of a value.
Unlike in a node class, in a port type each function name needs to be prefixed with the type name and an underscore. For example, the VuoInteger type has functions VuoInteger_valueFromJson, VuoInteger_jsonFromValue, and VuoInteger_summaryFromValue. In this documentation, we'll use "MyType" in place of the port type name.
Every type needs to implement the MyType_valueFromJson function and the MyType_jsonFromValue function. These functions are responsible for converting a value of MyType to and from a JSON-C object. For each input port of type MyType in a composition, the MyType_valueFromJson function is called when the composition starts in order to initialize the port's value. While the composition is running, MyType_valueFromJson is also called each time the composition receives a message to change the input port's value — for example, when a Vuo Editor user edits an input port value. For each input or output port of type MyType, the MyType_jsonFromValue function is called each time the composition receives a message to retrieve the port's value.
Every type also needs to implement the MyType_summaryFromValue function, which returns a brief textual description of the port's value. This function is called each time the port's node receives an event. The summary appears in the Vuo Editor when the user hovers over a port to see its value while the composition is running. Be sure to keep the summary brief so that it can be efficiently sent many times per second to the Vuo Editor or another process.
You can define additional functions for working with your port type. For example, many built-in port types define a MyType_make function as a constructor that node classes and other port types can use to construct a value of MyType. Be sure to prefix your functions with the port type name to avoid naming conflicts with other port types.
When you compile a port type, the Vuo compiler automatically adds some functions to it. These functions appear in the compiled port type file but not in the port type's source code.
For more information about the port type functions, see the documentation for type.h.
Also see the source code for Vuo's built-in port types, which can serve as examples to help you write your own port types.
Before you can install your port type, you need to use the Vuo Compiler to compile it to a .bc file.
If you're using the example Qt project for creating a port type, then you can just build the Qt project (Build > Build All).
Otherwise, you need to use the vuo-compile command-line tool that comes with the Vuo SDK. To learn how to use vuo-compile, see the Vuo Manual, run vuo-compile --help, or look at the vuo-compile command in the example Qt project.
The final step is to place your compiled port type in the correct folder, so that it will be detected by the Vuo framework and the Vuo command-line tools. You can place it in either ~/Library/Application Support/Vuo/Modules/ or /Library/Application Support/Vuo/Modules/. For more information about these folders, see the Vuo Manual.
If you're using the example Qt project for creating a port type, then when you build the project, the compiled port type is automatically placed in ~/Library/Application Support/Vuo/Modules/.
Otherwise, you need to manually move the compiled port type (.bc) file to one of these folders.
After that, you should be able to use your port type in a node class, just like the built-in port types.
Please do not begin your port type's name with "Vuo". This is reserved for port types distributed by Team Vuo / Kosada. Please use your own company or personal name for your port types so that Vuo users can appreciate your work (and not be confused).
Modules | |
| Module Metadata | |
| Name, version, and behavior information to be defined by node classes, port types, and library modules. | |
| Module Debugging | |
| Macros to help with debugging. | |
| Type Methods | |
| Functions to serialize, unserialize, and summarize values of the type. | |
1.8.3