TouchDesigner in VDMX6 Plus

TouchDesigner is a node-based development environment, similar in many ways to Quartz Composer while at the same time having a lot of fundamental differences that make it a substantially unique environment with a vibrant user community that often overlaps with Quartz Composer. You can find more information here: https://derivative.ca or check out the VDMX TouchDesigner tutorial.

TouchDesigner shares many of the same benefits as Quartz Composer, and accordingly we have made it an integral part of VDMX, which has many different ways to work with TouchDesigner.

Example compositions

The VDMX6 Plus dmg Extras folder contains example compositions to help get started with making TouchDesigner compositions to use in VDMX.

To install the demo files on your machine, go-to the VDMX assets folder located at: "~/Library/Application Support/VDMX/"

• You can use the “Open Assets Folder in Finder” option in the VDMX help menu to jump to this directory).
• You may have to create some of the folders yourself.

Use TouchDesigner sources in VDMX

TouchDesigner compositions require some minor modifications before they can be used in VDMX sources and effects, as demonstrated in the example compositions.

Once your compositions are ready to use in VDMX, the quickest way to get your TouchDesigner compositions doing something in VDMX is simply to drag them into a media bin (or choose "Import Media" from the file menu) and trigger them on a layer. There will be a delay of a few seconds the first time you trigger it while TouchDesigner compiles your patch, after which it will be played on your layer just like any other media file.

If your TouchDesigner composition has any published inputs, VDMX will automatically create UI items of the appropriate type (slider, button, color picker, text field, video source picker, etc) for them.

Passing control data and images from VDMX into patches using Published Inputs

TouchDesigner consists of objects which are connected together with patch cords. A complete description of how to use and work with TouchDesigner is beyond the scope of this wiki (TouchDesigner's documentation is excellent).

• Image-type inputs will be represented in VDMX as a pop-up button with a list of all available video sources (other layers, video inputs, syphon sources, etc).
• Real- and Integer-type inputs will be represented in VDMX as sliders. TouchDesigner lets you set a default min and max value (right-click on the published input and choose "Edit Details" to set this)- the slider in VDMX will have its range set by these values.
• Color-type inputs will be represented in VDMX as a standard RGBA/HSVA color picker.
• Boolean-type inputs will be represented in VDMX as toggle buttons (on/off).
• Point-type inputs will be represented in VDMX as a 2d point picker. The range of the values VDMX passes to TouchDesigner will be based on the dimensions at which the TouchDesigner composition is being rendered (VDMX passes pixel-scale coords to TouchDesigner, which at this time does not offer a way to specify the min/max values of its point-type inputs).
• Text-type inputs will be represented in VDMX as a text field.
• If you have a string-type input published with "FontMenu" anywhere in its name, VDMX will create a pop-up button with a list of all the system fonts (the name of the font will be passed to TouchDesigner when you select it).
• If you have a number-type input published with "VDMXBPM" anywhere in its name, VDMX will automatically pass the BPM of your clock to your composition. No UI item is created, this is handled entirely behind the scenes.
• If you have a number-type input published with "MeasurePosition" anywhere in its name, VDMX will automatically pass the measure position to this input as a value ranged 0.0-1.0.

Built-in TouchDesigner sources

VDMX offers a number of built-in media files and video sources that are quickly accessible in the "Use Source:" pop-up button in the layer source UI. If you want your TouchDesigner composition to be listed here, place it in the "TouchDesignerSources" folder in your VDMX Assets folder (choose "Open Assets Folder in Finder" from VDMX's "Help" menu). It will immediately be listed as an available effect in VDMX, and can be previewed in the Workspace Inspector's "Assets" tab or added to layers.

Making Video FX with TouchDesigner

If your TouchDesigner composition conforms to the "Image Filter" protocol, it can be used as an image filter in VDMX- just place it in the "TouchDesignerFX" folder in your VDMX Assets folder (choose "Open Assets Folder in Finder" from VDMX's "Help" menu). It will immediately be added as an available effect in VDMX, and can be previewed in the Workspace Inspector's "Assets" tab or added to layers.

TouchDesigner-based VDMX Plugins

TouchDesigner compositions can be used as plugins in VDMX- when loaded as a plugin, VDMX will not only create UI items for any published inputs in your patch, but any outputs you publish will be made available in VDMX as either a video source (if the published output is an image-type splitter) or a data source (if it's a bool/number/color/string/etc). This allows you to use TouchDesigner to program complicated mathematical or logical behaviors that both receive data from and send data back to VDMX. Place these .tox files in the 'plugins' directory of the VDMX Assets Folder.

TouchDesigner Text Sources- Using TouchDesigner to Render Text

Text files in VDMX can be triggered and played back on layers- you can customize how your text files are rendered by creating TouchDesigner patches that will be used to render text. To be used as a text source, your TouchDesigner composition must have a string-type input published as "FileInput", and it must be placed in the "TouchDesignerTextSources" folder of your VDMX Assets folder (choose "Open Assets Folder in Finder" from VDMX's "Help" menu). Once you trigger a text file, you can choose which TouchDesigner compositions is used to render its contents using the appropriate pop-up button in the layer source controls- VDMX will automatically display a browser for your text file that allows you to trigger individual words/lines/etc (these words/lines/etc will be passed to your patch via the "FileInput").

Important notes

• Using TouchDesigner compositions in VDMX6 Plus requires a TouchDesigner install with a valid TouchDesigner license on the same computer (Education, Commercial, or Pro). Non-commercial will not work.
• Each time you launch a TouchDesigner file, it launches a new instance of the TouchEngine. Keep this in mind when opening up multiple TD files at once as it can pull a lot of memory.

TouchDesigner in VDMX6 Plus — Expanded Reference

This document picks up where the official VDMX TouchDesigner page leaves off: https://docs.vidvox.net/vdmx/vdmx_touchdesigner.html

The official page covers what each folder is for, the supported published-input types at a high level, and the licensing/memory caveats. This supplement covers the TouchDesigner-side construction details — the operator names, parameter styles, page conventions, and resolution wiring that a .tox must follow to behave correctly inside VDMX. Everything below is derived from the official Vidvox example .tox files shipped in the Extras folder of the VDMX6 Plus disk image.

---

1. Component contract

Every .tox exported for VDMX is a single top-level baseCOMP, exported via right-click → Save Component .tox…. Inside that component:

• All published parameters live on a single custom page named Custom (capital C, exactly).

• No parentshortcut is set on the component. Vidvox examples reference parent parameters via parent().par.Name, not via shortcut.

• A parameterCHOP named par1 is conventional at the top level. It exports every parent custom parameter to a CHOP channel that other internal nodes can read. Configuration in every Vidvox example:

  Parameter	Value
  ops	..
  parameters	*
  custom	True
  builtin	False

  In Python: parent.create(parameterCHOP, 'par1') followed by setting those four pars.

2. The Rendersize parameter

Every .tox — FX, source, text source, and plugin — must publish a Rendersize WH parameter on the Custom page. VDMX writes the host layer's pixel dimensions into this parameter every frame.

Setting	Value
Style	WH (width/height pair)
Parameter name	Rendersize (creates Rendersizew / Rendersizeh internally)
Label	renderSize (camelCase, exactly)
Default	1920 × 1080

In Python:

page = comp.appendCustomPage('Custom')
rs = page.appendWH('Rendersize', label='renderSize')
rs[0].default = 1920; rs[0].val = 1920
rs[1].default = 1080; rs[1].val = 1080

Driving internal resolution from Rendersize

Your render chain has to actually use Rendersize, otherwise VDMX will receive a fixed-size image regardless of the layer it's been dropped on. The standard pattern:

1. Set the source renderTOP's outputresolution to custom.
2. Bind resolutionw / resolutionh to parent().par.Rendersizew / parent().par.Rendersizeh as expressions.

render.par.outputresolution = 'custom'
render.par.resolutionw.expr = 'parent().par.Rendersizew'
render.par.resolutionw.mode = ParMode.EXPRESSION
render.par.resolutionh.expr = 'parent().par.Rendersizeh'
render.par.resolutionh.mode = ParMode.EXPRESSION

The fitTOP safety net

Some palette COMPs and feedback loops have internal resolutions that can't be re-routed from the parent. Insert a final fitTOP between the last node of your network and outputImage, with its resolution bound to Rendersize. This guarantees the output that reaches VDMX is always exactly the requested size, regardless of what's happening upstream.

fit = comp.create(fitTOP, 'resize')
fit.par.outputresolution = 'custom'
fit.par.fit = 'fill'
fit.par.resolutionw.expr = 'parent().par.Rendersizew'
fit.par.resolutionw.mode = ParMode.EXPRESSION
fit.par.resolutionh.expr = 'parent().par.Rendersizeh'
fit.par.resolutionh.mode = ParMode.EXPRESSION

Note: an outTOP does not resize its input — its Common-page outputresolution/resolutionw/resolutionh parameters evaluate but do not actually rescale. The resampling has to happen on a node before outputImage. fitTOP is the cleanest choice.

3. Required operators by folder

VDMX recognizes input slots and output streams by the names of top-level operators inside the baseCOMP. The contract differs per folder:

TouchDesignerFX/

Operator	Type	Required	Notes
inputImage	inTOP	Yes	Always present, even when not actively used. Receives the layer below.
outputImage	outTOP	Yes	The processed result returned to VDMX.
Additional inTOPs	inTOP	Optional	Each extra top-level inTOP becomes another Video Input slot in VDMX, named after the operator. The Vidvox TDIO_Image_Input.tox example ships an extra inTOP named dodgeImage that VDMX exposes as a second input.

TouchDesignerSources/

Operator	Type	Required	Notes
outputImage	outTOP	Yes	The generated output.
inputImage	inTOP	No — sources have no input.	Do not include one.

TouchDesignerTextSources/

Operator	Type	Required	Notes
outputImage	outTOP	Yes	The rendered text frame.
FileInput parameter	Str	Yes	A published string parameter labeled exactly FileInput. VDMX writes the active text-source identifier into this parameter.
fileOutputNext	outCHOP	Optional	Pulse on this channel signals VDMX to advance to the next text item.
fileOutputPrev	outCHOP	Optional	Pulse on this channel signals VDMX to rewind.

plugins/

Plugins can output any combination of operator types — they're not restricted to images. The operator's name becomes the source's name in VDMX's Data Sources list.

Operator type	Use	Example name in Vidvox tox
outTOP (any number)	Image streams	outputImage, secondOutputImage
outCHOP (any number)	Float / numeric streams (first channel)	floatOut
outDAT (any number)	Text streams	textOut1

A plugin can publish, e.g., one outCHOP only — no image required. See TDIO_Float_Output.tox (one outCHOP named floatOut, driven by an lfoCHOP) and TDIO_String_Output.tox (one outDAT named textOut1, driven by evaluateDAT → convertDAT).

4. Published parameter reference

Drop all user-facing parameters on the Custom page. The label, not the parameter name, is what VDMX displays. Use CamelCase labels (e.g. BaseColor, LightIntensity).

VDMX UI control	TD style	Python	Notes
Float Slider	Float	page.appendFloat('Name', label='Name')	min/max/normMin/normMax define slider range
Integer Slider	Int	page.appendInt('Name')
Toggle Button	Toggle	page.appendToggle('Name')	Boolean
Momentary Button	Pulse	page.appendPulse('Name')	Trigger / fire
Text Field	Str	page.appendStr('Name')	Plain string
Pop-up Menu	StrMenu	page.appendMenu('Name', menuNames=[...], menuLabels=[...])	Defined in TD
2D Point Pad	XY (style reads XYZW)	page.appendXY('Name')	Two-component pair
Color Picker (RGB)	RGB	page.appendRGB('Name')	3 channels
Color Picker (RGBA)	RGBA	page.appendRGBA('Name')	4 channels — VDMX uses RGBA / HSVA picker
Render Size	WH	page.appendWH('Rendersize', label='renderSize')	The one and only Rendersize parameter — see §2
Video Input slot	n/a — inTOP	comp.create(inTOP, 'name')	Top-level inTOP; the operator name becomes the slot name in VDMX

Group styles that VDMX does not expose

These styles produce parameters that VDMX skips entirely — even though they appear in TouchDesigner:

Style	Workaround
XYZ (3-component point)	Use three individual Float parameters named Namex, Namey, Namez.
XYZW (4-component)	Use four individual Float parameters.
File (file-picker)	Use Str style instead. VDMX shows a text field; users paste the file path.

If your source/effect needs to load a model, video, or texture file, the Str workaround also makes the path editable directly inside VDMX without re-saving the .tox.

5. Reserved label names

The official documentation lists these — included here for completeness with the TouchDesigner-side specifics:

Label (exact)	Style	Effect
renderSize	WH	VDMX writes the layer's pixel size into the parameter every frame
FileInput	Str	Marks a Text Source parameter as the active file/identifier (text-sources only)
FontMenu	StrMenu	Replaces the menu values with the system's installed fonts
VDMXBPM	Float	VDMX passes the current host BPM; no slider is shown in VDMX
MeasurePosition	Float	VDMX passes a 0.0–1.0 position within the current measure; no slider is shown

6. Recommended top-level layout

A minimal, convention-aligned skeleton (any of the four folder types — strip the parts that don't apply):

/myFX (baseCOMP — the file you save as .tox)
│
├── Custom page
│   ├── Rendersize     (WH, label "renderSize")
│   └── …your published parameters
│
├── par1               (parameterCHOP   — exports parent custom pars to channels)
├── inputImage         (inTOP           — only for TouchDesignerFX)
├── outputImage        (outTOP          — for FX, Sources, TextSources, Image plugins)
├── …your network…
└── resize             (fitTOP at the end → outputImage, driven by Rendersize)

For plugins, replace outputImage with the appropriate outTOP/outCHOP/outDAT(s), each named to suit the data they expose.

7. Common pitfalls

Symptom	Cause	Fix
Sliders work but VDMX shows a black or transparent output	Internal renderTOP not bound to Rendersize; render chain renders at a fixed size while VDMX expects a different one	Bind renderTOP.resolutionw/h to parent().par.Rendersizew/h, set outputresolution=custom
Output appears upscaled or letterboxed in VDMX	Final node has fixed resolution that doesn't match VDMX's request	Insert a fitTOP driven by Rendersize between the last node and outputImage
A parameter is missing in VDMX even though it's on the Custom page	Parameter style isn't supported (XYZ group, File picker, etc.)	Convert to individual Floats or to a Str
Modelfile / MoviePath parameter doesn't update internally when changed in VDMX	The internal op references a different parameter, or path is cached	Bind the internal op's file parameter to parent().par.<YourPar>.eval() as an Expression
Effect renders fine in TD, blank in VDMX	A palette COMP inside has a feedback loop pinned at a fixed resolution	Add the fitTOP safety net (§2)
Sliders appear but the host TouchEngine never finishes loading	Non-Commercial TouchDesigner license	Install Education / Commercial / Pro

8. Notes on iteration

Changes to a .tox are not live in VDMX. To iterate:

1. Edit the composition in TouchDesigner.
2. Right-click the top-level baseCOMP → Save Component .tox…
3. Overwrite the file in the matching VDMX assets folder.
4. In VDMX, remove and re-add the asset (or restart the host).

Parameter values exposed to VDMX are live within a session — the user can drive them from VDMX's UI, MIDI, OSC, or the cuelist without re-saving the .tox. Only changes to the network structure (new ops, rewiring, new pars) require re-export.

---