QuartzComposer Adding a published input
From VidvoxWiki
By adding published inputs to a Quartz Composer document, you can make almost any parameter accessible when the patch is loaded into VDMX5.
Contents |
Adding a published input
There are four basic steps involved with adding an input to your patch. Each Quartz Composer patch can have as many published inputs as needed.
Adding an 'input splitter' node to your patch
- In the Patch Library panel, scroll until you see 'input splitter' object (or type 'input splitter' into the search box)
- Click on the 'input splitter' text in the list and drag it into your patch
Setting the data type of an input splitter
- Click on the 'input splitter' node in the patch window. The node will become highlighted.
- Open the inspector window (cmd+i or 'Show Inspector' in the Editor menu)
- Switch the inspector to the settings view (via the pop up menu at the top of the inspector, or press cmd+3)
- Select the type of input from the pop up menu next to the word 'Type'. See below for a description of each of the input types and their corresponding interface items in VDMX. When appropriate (for number and index inputs), be sure to also provide the minimum and maximum values, otherwise these will automatically be treated as 0 and 1.
Publishing the input
- Right click (or control+click) on the input splitter to bring up the Published Input/Output contextual menu
- From the Published Inputs sub-menu, select the 'input' option
- A text entry box will appear over the input splitter with the default text 'input'. Type in the name that you wish to appear next to the UI item in VDMX (this is often referred to as the 'key' and is different from the 'title' that you can set in the inspector)
- Once you have finished, the empty circle next to the word 'input' will become filled. You can mouse over the input to see the name of the key for the splitter.
Connecting the output of the splitter to the inlets of the nodes in your patch
Do this as you would any other connection in Quartz Composer.
Input types
Whenever a Quartz Composer document is used in VDMX, either as an FX or as a source, VDMX will automatically create interface items for each of the input splitters on the top level of the qtz patch based on it's input type.
Standard types
Boolean
Think on/off switch. These inputs are represented by the standard vvbutton toggle button.
Index
Indexes are the 'counting' numbers (eg 0,1,2,3,...) and are represented as a menu. 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 no maximum value is set, VDMX will default to a menu ranging from 0 to 15.
Number
Number inputs are represented by the standard vvslider, with a range determined by the minimum and maximum values set in the inspector. If the minimum or maximum values are not specified, VDMX will use 0.0 and 1.0 respectively.
Color
Color inputs are represented by the standard VDMX rgb picker (which has 3 vvsliders, one each for red, green, and blue).
String
String inputs are represented by a text field input. Commonly used with the 'Image With String' object to create text generators.
Image
Image inputs are represented by a 'video tap' menu which allow you to pass video from a layer in VDMX into a Quartz Composer document. These can be used to build mixers or FX.
Special types
In some cases, the standard input types available in Quartz Composer do not fully describe the type of information that you wish to receive from VDMX. To get around this, VDMX will check the input key for each input splitter looking for special tags and handle these inputs differently.
Font Menu
If an input of type 'string' has the tag 'FontMenu' anywhere in it's key name, VDMX will provide a menu with a list of all system fonts instead of a regular text entry box. Otherwise you would have to type in the name of the font you wanted to use.
BPM Input
To receive the current BPM of the VDMX clock, create an input splitter of type 'number' and enter the tag 'VDMXBPM' at the beginning of the key name. No interface item will be provided, this is handled behind the scenes.
Measure position
The current measure position (ranged 0 to 1) of the VDMX clock can be automatically fed into a Quartz Composer document by using the tag 'MeasurePosition' at the beginning of the key for an input splitter of type 'number'. Like with the BPM input, no interface item will be created when the document is used. This could also be accomplished by creating a 'number' input and syncing the provided slider to the measure position data source.
2-d Point Control
To include a standard VDMX 2-d point picker in the control interface for your QC patch, first follow the above instructions for creating an Input Splitter. When it comes time to set the type, choose Structure and prefix "xy" (without quotes) to the beginning of the input key. The received 2-d point structure will be an ordered pair of coordinates (x, y) which can be accessed using the Structure Index Member object (index 0 for the x value, index 1 for the y value).
As a note, both the x and y values are ranged 0 to 1 (going from the bottom left to the top right corner) and may need to be mapped to the coordinate system of the receiving patch. This additonal mapping is left to the designer of the patch as QC patches can have multiple coordinate representations (such as when using CoreImage filters), as well as situations where the 2-d point picker is being used for setting non-position based controls.
Quartz Composer FX
When preparing a Quartz Composer document to use as an FX for VDMX5, there must be an input splitter of type 'image' set up receive the incoming video stream. The key name for this object must be "inputImage" (no quotes) or VDMX will not recognize the document as an FX.
Once you added the image input and set it's key, place the qtz document in the qcFX folder (located in the VDMX folder) and launch VDMX - the FX should be available in the Video FX palette under the category Quartz Composer FX.