Using Vuo compositions with VDMX.

Vuo

Vuo 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: vuo.orgg

Vuo 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 Vuo.

A word on Protocols

Protocols define required behavior for a protocol- Vuo explicitly defines two protocols: the “Image Generator” protocol, and the “Image Filter” protocol. Patches that conform to the “Image Generator” protocol must have inputs for “width”, “height”, and “time” values and an image-type output published as “outputImage”. “Image Filters” must have an image-type input published as “image”, a real-type input published as “time”, and an image-type output published as “outputImage”. If your Vuo composition doesn’t adhere to these protocols, VDMX won’t be able to exchange data with it, and it won’t work. You can examine and modify the protocols your composition conforms to via the “Protocols” sub-menu in the Vuo Editor’s “Edit” menu.

Separate Process or Same Process?

Vuo compositions can be run in the same process as VDMX, or they can be run in another process (as another application that passes data back and forth with VDMX). Running Vuo compositions in a separate process is safer- if Vuo crashes for any reason, VDMX will be unaffected- but file triggering will be slightly slower (if you need super-fast triggering you may want to disable this), and there may be more overhead when passing image data back and forth on some hardware as a result of performance differences in OS X’s drivers. The default behavior is to run Vuo comps in another process, but you can change this behavior in the “Vuo” section of VDMX’s preferences.

Trigger Vuo compositions in VDMX

The quickest way to get your Vuo 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. If the Vuo composition conforms to Vuo’s “Image Generator” protocol, there will be a delay of a few seconds the first time you trigger it while Vuo compiles your patch (all subsequent triggers- even after relaunching VDMX- will be immediate), after which it will be played on your layer just like any other media file. If your Vuo 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

Vuo consists of objects which are connected together with patch cords. A complete description of how to use and work with Vuo is beyond the scope of this wiki (Vuo’s documentation is excellent), but generally speaking you publish an input in your patch by dragging from the desired input to the “Inputs” sidebar on the left-hand side of the editor window. VDMX will automatically attempt to make a UI item for your published inputs; different types of inputs get different types of interface items.

  • 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. Vuo 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 Vuo will be based on the dimensions at which the Vuo composition is being rendered (VDMX passes pixel-scale coords to Vuo, 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 Vuo 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 Vuo 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 Vuo composition to be listed here, place it in the “vuoSources” 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 Vuo

If your Vuo composition conforms to the “Image Filter” protocol, it can be used as an image filter in VDMX- just place it in the “vuoFX” 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.

Vuo-based VDMX Plugins

Vuo 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 Vuo to program complicated mathematical or logical behaviors that both receive data from and send data back to VDMX.

Vuo Text Sources- Using Vuo 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 Vuo patches that will be used to render text. To be used as a text source, your Vuo composition must have a string-type input published as “FileInput”, and it must be placed in the “vuoTextSources” 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 Vuo 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”).

Tags: vdmx_manual