Quartz Composer

Important Note: This is a legacy document. Quartz Composer has been deprecated by Apple. VDMX will continue to support QC for as long as we can.

Quartz Composer was a groundbreaking node-based graphics development environment that made it possible to explore the incredible power of the graphics stack of Mac OS X Tiger. With Quartz Composer, you can easily combine the capabilities of Cocoa, Quartz 2D, Core Image, OpenGL, and QuickTime, all using an approachable visual programming paradigm. Quartz Composer can be used to prototype Core Image filters, make data-driven visual effects, and create live performance animations.

Quartz Composer was free, easy to pick up, and offers people with absolutely no programming experience a comfortable way to create stunning interactive pieces. As such, we do our best to support the aspects of it that we think are most advantageous- its ease of use and interactivity. There are several different ways to use Quartz Composer with VDMX:

Trigger QC compositions in VDMX

The quickest way to get your Quartz Composer patches doing something in VDMX is to simply drag them into a media bin, (or choose "Import Media" from the file menu) and trigger them in a layer. Your QC patch may then be triggered and played on a layer just like any other media file. If your QC patch 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

Quartz Composer consists of objects which are connected together with patch cords. The "Input Splitter" object lets you make inputs in patches; data may be passed to objects through these inputs. If you make an input splitter in the top level of your patch and publish it, VDMX will attempt to make a UI item for your input; different types of inputs (numbers, toggles, colors, etc.) get different types of interface items.

  • Boolean-type inputs will be represented in VDMX as a toggle button (on/off)
  • Index-type inputs will be represented in VDMX as a pop-up button. The number of items in the menu is determined by the maximum value set in the node inspector, such that the items in the menu range from 0 to the maximum value minus one. If the input is specified as having labeled indices, the menu items in the menu will correspond to the provided labels.
  • Number-type inputs will be represented in VDMX as a standard slider, with a range determined by the minimum and maximum values set in the inspector. If no min/max values are specified, the slider will be ranged 0.0-1.0.
  • Color-type inputs will be represented in VDMX as a standard RGBA/HSVA color picker.
  • String-type inputs will be represented in VDMX as a text field.
  • 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)
  • Structure-type inputs are used to represent input types that are not of the aforementioned types, and can be represented in VDMX as several different UI items, depending on the name of the of the published input.
    • If the published name of the structure-type input includes the letters "XY", VDMX will create a 2d point-type UI item
    • If the published name of the structure-type input includes the letters "MultiButton", followed by two dimensions, VDMX will create a multi-button UI item, with the passed dimensions. For example, a structure-type input splitter published as "ButtonField_MultiButton_2x2" will create a 2x2 multi-button UI item labeled as "ButtonField" in VDMX. The same exact UI item would be created if the name was "ButtonField MultiButton 2x2", "ButtonField-MultiButton-2x2", or "ButtonField-MultiButton-2-2". The values of the buttons will be passed to the composition as an array.
    • If the published name of the structure-type input includes the letters "MultiSlider", followed by two dimensions, VDMX will create a multi-slider UI item, with the passed dimensions. The naming pattern for this UI item matches that of multi-button inputs.
  • 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 QC 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 QC 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 QC composition to be listed here, place it in the "qcSources" 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 QC

If you add an image-type input splitter to your patch and publish it as "inputImage", the composition can be used as an image filter in VDMX- just place it in the "qcFX" 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.

QC-based Composition Modes

QC compositions can be used as composition modes in VDMX (they can be used to composite layers together) if they meet the following requirements:

  • It must have an image-type input splitter published as "background". video from the "background" layer will be sent to this input.
  • It must have an image-type input splitter published as "foreground". video from the "foreground" layer will be sent to this input.
  • It must have a number-type input splitter (ranged 0.0-1.0) published as "opacity"- the opacity of the "foreground" layer will be passed to this input.
  • The composition must be placed in the "qcCompModes" folder of your VDMX Assets folder (choose "Open Assets Folder in Finder" from VDMX's "Help" menu).

QC-based VDMX Plugins

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

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

Installing the Quartz Composer Editor

No extra install is needed to use Quartz Composer compositions within VDMX.

To create or edit your own QC compositions, the Quartz Composer Editor tool can be found as part of the 'Additional Tools for Xcode' disk image, which you can find in here: https://developer.apple.com/download/more/

Download Quartz Composer Editor.