Custom Operators

From TouchDesigner Documentation
Jump to: navigation, search

Overview[edit]

A Custom OP can be created for a TOP, CHOP, SOP, and DAT types. A Custom OP is an operator created by a 3rd party using TouchDesigner's C++ API, but they behave just like the built-in operators that TouchDesigner has. Custom OPs are very similar to the CPlusPlus TOP, CPlusPlus CHOP, CPlusPlus SOP, and CPlusPlus DAT operators, but they have their own unique names and appear in the OP Create menu for better integration in TouchDesigner. Use them like regular built-in operators.

Security and Safety[edit]

Since a Custom OP is created with binary code that is loaded and executed in TouchDesigner, it can contain malicious code. To help with this, before loading any binary TouchDesigner will check if that binary has been loaded on that machine before. If being loaded for the first time, a dialog will be presented asking for permission to load it, and if so then a signature for that binary will be saved into a .json file in the plugins directory. If the binary changes, then the user will be prompted again to load the new binary.

Using Custom OPs - Plugin Folder Locations[edit]

Custom OPs are used by simply placing the plugins in the correct location on disk. They will be detected when TouchDesigner starts. On Windows a plugin is a .dll file, with possible extra files included with it. On macOS a plugin is a .plugin folder.

The Windows location is:
Documents/Derivative/Plugins
Which is usually:
C:/Users/<username>/Documents/Derivative/Plugins

On macOS the location is:
/Users/<username>/Library/Application Support/Derivative/TouchDesigner099/Plugins

Plugins can be placed in this directory directly, or placed in another directory contained within Plugins, with any name, to organized the plugins as desired. For example, the plugins directory could contain:

Documents/Derivative/Plugins/wave2.dll
Documents/Derivative/Plugins/Company1/feature1.dll
Documents/Derivative/Plugins/Company1/feature2.dll
Documents/Derivative/Plugins/Mine/customMerge.dll

The Custom OPs defined by wave2.dll, feature1.dll, feature2.dll and cusotmMerge.dll would all be loaded.

Project Specific Custom OPs[edit]

Along with the system wide Plugins folder listed above, a Plugins folder can also be placed next to the .toe file that is opened. This directory will also be searched for Plugins along with the system wide Plugins directory.

Creating Custom OPs[edit]

With the exceptions of how they are loaded, a Custom OP is created the same way as the CPlusPlus TOP, CPlusPlus CHOP, CPlusPlus SOP and CPlusPlus DAT are created. Refer to Write a CPlusPlus Plugin for more information.

When developing your Custom OP, you may find it more convienient to load it into a CPlusPlus node to more quickly recompile/reload the plugin instead of having to restart TouchDesigner every time you change your code. Once you are done developing you use the same plugin as a Custom OP.

Converting existing CPlusPlus projects to Custom OPs.[edit]

Taking an existing CPlusPlus project and making it can be used as a custom OP is relatively quick.

Header Files[edit]

First, from the Samples/CPlusPlus folder for the correct OP type, take the CPlusPlus_Common.h and *_CPlusPlusBase.h header file (SOP, TOP, CHOP, DAT instead of *), and replace the versions that are in the project you are upgrading.

Plugin Information[edit]

Next, you'll need to replace the functions Get*APIVersion() or Get*PluginInfo() with a new function containing one of these signatures (depending on the node type):

void FillTOPPluginInfo(TOP_PluginInfo *info);
void FillCHOPPluginInfo(CHOP_PluginInfo *info);
void FillSOPPluginInfo(SOP_PluginInfo *info);
void FillDATPluginInfo(DAT_PluginInfo *info);

This function is used to define the name/label of the Custom OP, as well as other behavior such as how many inputs it allows. Examples of how to fill in this structure can be found in the previously mentioned example folders.

Changed functions[edit]

Many of the virtual functions that your class overrides will have extra parameters or tweaks to the parameters (such as const changes). In most cases simply making your function signatures match those in the parent class should allow it to compile.

OP_String[edit]

To provide a less error prone interface, any situation where a string is returned from your Custom OP to TouchDesigner, where the lifetime the memory needs to extend beyond the function call, it is done by assigning a value to an OP_String object that TouchDesigner provided for you. E.g:

chan->name = "chan_name";

would become:

chan->name->setString("chan_name");

You will likely have compile errors that will need to be fixed by replacing the = operation to a setString() function call.

Building on macOS using XCode[edit]

  • Open one of the included .xcodeproj projects from the Samples/CPlusPlus directory.
  • Under the 'Product' menu select 'Archive'. If the build is successful a new window will come up showing a list of archives that have been created, including the one that was just created.
  • Select the one that was just created and click the 'Distribute Content' button. In the 'Select a method of distribution' dialog that comes up, select 'Build Products', and click 'Next'. Pick a location to save the archive and complete the operation.
  • In the folder where you saved the Build Products there will be a 'Products' folder and inside that <projectname>.plugin folder. This .plugin folder is what should be placed in your 'Plugins' folder to load this as a Custom OP.

The operating system's holder of files and other folders (directories). It does not refer to operators within TouchDesigner. See Network Path.

TOuch Environment file, the file type used by TouchDesigner to save your project.

Any of the procedural data operators. OPs do all the work in TouchDesigner. They "cook" and output data to other OPs, which ultimately result in new images, data and audio being generated. See Node.

An Operator Family that reads, creates and modifies 3D polygons, curves, NURBS surfaces, spheres, meatballs and other 3D surface data.

An Operator Family that creates, composites and modifies images, and reads/writes images and movies to/from files and the network. TOPs run on the graphics card's GPU.

An Operator Family which operate on Channels (a series of numbers) which are used for animation, audio, mathematics, simulation, logic, UI construction, and many other applications.

An Operator Family that manipulates text strings: multi-line text or tables. Multi-line text is often a command Script, but can be any multi-line text. Tables are rows and columns of cells, each containing a text string.