Upgrading Custom Operators and CPlusPlus Plugins to 2022 and Newer Builds

For your existing custom operator to work with latest version of TouchDesigner, you will have to make certain updates to the operator C++ code. The base classes (for example TOP_CPlusPlusBase.h) and CPlusPlus_Common.h will most likely have been updated since your version. You can replace these base files, in your operator code, with the new versions. The new versions can be accessed from the example plugins in Samples/CPlusPlus/.

For each operator family, different changes to the base classes will have been made. In particular, with the switch to Vulkan, and deprecation of OpenGL, the TOP API has undergone significant changes since the 2021 versions of TouchDesigner. In this article we outline the major changes since the last API version

TOP Changes

With the switch to Vulkan, and deprecation of OpenGL, the TOP API has undergone significant changes since the 2021 versions of TouchDesigner. Here we outline the major changes.

• OpenGL workflow is gone.
• Everything in the common files has been moved to the TD namespace, so you'll have to scope everything appropriately
• The method getOutputFormat() is gone. Now you need to specify the output format from within execute(). More flexibility offered this way.
• The class TOP_OutputFormatSpecs is gone and split into TOP_Output and TOP_UploadInfo. TOP_UploadInfo stores the format of the texture to be outputted. TOP_Output contains the methods for creating buffer via TOP_Context::createOutputBuffer() and uploading the texture to CPU memory via TOP_Output::uploadBuffer().
• This is a workflow change, not API change, but the context via class TOP_Context is stored as a member within your operators class, and is passed in there.
• To download texture from the input TOPs, OP_Inputs::getTOPDataInCPUMemory() is gone. OP_TOPInput::downloadTexture() will have to be used along with specifying the download options via an object of OP_TOPInputDownloadOptions.
• This is a workflow change, not API change, but instead of storing the operator parameters in a separate header file Parameters.h, create and store it within setupParameters().
• While you still have access to 3 texture memory locations, to get the output of memory location index 1 and 2, a RenderSelectTOP has to be used. Textures in only index 0 are outputted to the TOP by default.
• The option of either delaying downloading the frame, or instantly downloading the frame via OP_TOPInputDownloadType has to now be done manually. Instead of setting it as a parameter value, use a temporary memory buffer to store the last frame's data, to delay by one frame.
• If you want to use CUDA to do processing on the GPU, then significant changes:
  • create and store a cuda stream object cudaStream_t in the operator. Initialize the cuda stream via cudaStreamCreate() in the operator's constructor, and destroy via cudaStreamDestroy() in the operator's destructor.
  • Accessing the input cudaArray requires more steps now, and cannot simply be pulled from OP_TOPInput::cudaInput. First, populate an object of OP_CUDAAcquireInfo with the correct cuda stream. then get the input cuda array via OP_TOPInput::getCUDAArray(). Note that this acquired array won't be filled out until beginCUDAOperations() has been called, more on this later.
  • Similarly, uploading the cuda output back to the CPU requires more steps now. Populate an object of TOP_CUDAOutputInfo with the correct output format and cuda stream. Then call TOP_Output::createCUDAArray() to create an object of class OP_CUDAArrayInfo that will store the output cuda array. Again, this stored cuda array will remain null until beginCUDAOperations() is called.
  • In this new API, cuda operations can only begin once TOP_Context::beginCUDAOperations() has been called using your context object. The relevant input cuda array buffers and output cuda array buffers will get filled up once this method has been called, and you can start doing cuda operations. Once you're done, call TOP_Context::endCUDAOperations() to upload the buffer back to the CPU.
  • Further, after calling beginCUDAOperations() and before calling endCUDAOperations(), your OP_Inputs inputs object cannot be accessed, so store the relevant data in local variables before doing cuda operations.

• For setting pixel formats, use the enum OP_PixelFormat

For a better understanding of all of these changes, refer to the examples in Samples\CPlusPlus\

CHOP Changes

CHOP plugin API hasn't gone through significant changes, so you'll only have to make minor workflow changes to get your code to work with the latest version of TouchDesigner.

• Replace the existing CHOP_CPlusPlusBase.h and CPlusPlus_Common.h files with the one found in \Samples\CPlusPlus\ in the version of TouchDesigner you want the plugin to work.
• Instead of using a separate file for your parameters Parameters.h - define all the parameters within the main cpp file in setupParameters()
  • You can get away without making this change, however, you'll then have to make sure that every API function is scoped correctly under the TD namespace
• Everything in the common files has been moved to the TD namespace - so you'll have to scope everything appropriately

DAT Changes

• Replace the existing DAT_CPlusPlusBase.h and CPlusPlus_Common.h files with the one found in \Samples\CPlusPlus\ in the version of TouchDesigner you want the plugin to work.
• Instead of using a separate file for your parameters Parameters.h - define all the parameters within the main cpp file in setupParameters().
  • You can get away without making this change, however, you'll then have to make sure that every API function is scoped correctly under the TD namespace
• Everything in the common files has been moved to the TD namespace - so you'll have to scope everything appropriately

See Also

Write a CPlusPlus TOP
Write a CPlusPlus CHOP
CPlusPlus DAT

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.

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.

The Graphics Processing Unit. This is the high-speed, many-core processor of the graphics card/chip that takes geometry, images and data from the CPU and creates images and processed data.

An Operator Family which operate on Channels (a sequence of numbers (Samples)) which are used for animation, audio, mathematics, simulation, logic, UI construction, and data streamed from/to devices and protocols.

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