Differences

This shows you the differences between two versions of the page.

--- combobox [2020/11/09 02:09] – created shane
+++ combobox [2024/03/09 19:33] (current) – [User interface basics] shane
@@ Line 1: / Line 1: @@
 ====== ComboBox ======
-The //ComboBox// built-in plug-in was added in Unify v1.2.0. Unlike all the other plug-ins bundled with Unify, it neither produces or processes either sound or MIDI by itself, but instead provides an environment in which you can connect any number of plug-in instances in arbitrary ways, and thus escape the constraints of Unify's linear-chain layer architecture. It's also unique in that you can use a //ComboBox// instance in any of Unify's three types of plug-in slots: Instrument, MIDI-effect, and Audio-effect. ([[midi-monitor|MIDI Monitor]] is the only other plug-in which can sensibly be used in all three slot types.)
+The //ComboBox// plug-in was added in Unify v1.2.0. Unlike all the other plug-ins bundled with Unify, it neither produces or processes either sound or MIDI by itself, but instead provides an environment in which you can connect any number of plug-in instances in arbitrary ways, and thus escape the constraints of Unify's linear-chain layer architecture. It's also unique in that you can use a //ComboBox// instance in any of Unify's three types of plug-in slots: Instrument, MIDI-effect, and Audio-effect. ([[midi-monitor|MIDI Monitor]] is the only other plug-in which can sensibly be used in all three slot types.)
+{{::combobox-0.png|}}
+===== Basic concepts and terms =====
+The image above shows a fairly simple //ComboBox// patch, taken from the first INST layer of the "Arrival - 0 - Welcome to Unify!" patch in the Unify Standard Library.
+  * The three boxes labeled "Audio File Player 1", "Guru Sampler 2", and "mda Vocoder 1" each represent plug-in instances.
+  * The two boxes labeled "MIDI Input" and "Audio Output" do not represent plug-ins, but rather the inputs and outputs of //ComboBox// itself.
+  * The colored lines represent **connections**, red for MIDI, green for audio. The arrows indicate the direction in which the MIDI or audio flows.
+  * The boxes (of any kind) are called **nodes**, and the entire structure of nodes and connections is called a **graph** (a mathematical term; see https://en.wikipedia.org/wiki/Directed_acyclic_graph).
+  * The keyhole-shaped bumps where connections begin and end are called **pins** (by analogy to connector pins in electronics).
+In this particular graph, the input MIDI stream is sent to the MIDI inputs of the //Audio File Player// and //Guru Sampler//. Each of those nodes has two audio outputs, representing the Left and Right stereo channels. One of the most important things about //ComboBox// is that it allows you to connect each plug-in's Left and Right outputs (or inputs) individually, and make multiple connections to a single pin (as is the case with the MIDI input here). Contrast this with Unify's layers, where plug-ins are always connected in daisy-chain fashion, and all audio connections are stereo.
+The ability to connect Left and Right pins in different ways is absolutely critical for the //mda Vocoder//, whose Left input takes the Modulator signal and the Right takes the Carrier signal. The vocoder impresses the dynamic tone of the Modulator (in this case a short vocal sample played by an //Audio File Player//) onto the Carrier (in this case, musical notes/chords played by a //Guru Sampler// using a synthesized pad sound). The //mda Vocoder// is actually a mono effect, so its Left and Right outputs are exactly the same.
+When the state of a //ComboBox// is saved within a Unify patch, the state-data includes
+  * The list of nodes, their names, and their X-Y position coordinates in the display
+  * The name and type of plug-in used for each node (except input/output nodes)
+  * The state-date for each plug-in
+This information is sufficient for Unify to completely restore the //ComboBox// instance to the state it was in when the patch was saved.
 ===== User interface basics =====
-When you first load an instance of //ComboBox//, the user interface will look like this:
+When you first load an instance of //ComboBox//, it will look like this:
+{{::combobox-1.png?600|}}
+  * Right-click in background area to add new plug-in instance nodes
+    * A "quick select" dialog will appear, allowing you to select any type of plug-in from the Known Plug-Ins list.
+    * Hold down ALT (Option on Mac) if you prefer the older cascading-menus method.
+    * Unify assigns node-names automatically by adding "1", "2", "3", etc. to the plug-in name
+  * Double-click in any plug-in node to open that plug-in's GUI in a separate window
+  * Right-click in any node for a menu of operations
+    * Including removing the node (and all its connections) from the graph
+    * You can safely remove any input/output nodes you don't need (you can add them back later)
+  * Plug-ins which have more than one stereo output-bus (Left and Right) will be drawn using a different pin color for each bus.
+  * Create connections by left-clicking any output pin and dragging to any input pin of the same type (MIDI/audio)
+    * You can also drag in the other direction (from an input to an output)
+    * You can connect one output to several inputs; this is called a **split**. The output data are simply copied to all inputs, without change.
+    * You can also connect several outputs to one input; this is called a **merge**. Merging MIDI streams yields one combined MIDI stream. Merging two or more audio streams is basically the same as //mixing// them; the audio samples are simply summed.
+===== Using ComboBox vs. Layers =====
+Unify's layer system provides another way to combine and connect multiple plug-ins, so what does //ComboBox// offer that Layers do not (or vice versa)?
+  * The main **advantage** of //ComboBox// is that it allows you to connect groups of plug-ins in arbitrary ways, as opposed to the strict stereo-only "daisy chaining" allowed by Layers.
+  * The main **drawback** of //ComboBox// is that, because //ComboBox// is itself a single plug-in, all plug-in instances inside a //ComboBox// are executed by only one CPU core at a time. Parallel Layers, in contrast, can run simultaneously using multiple CPU cores.
+===== ComboBox and Linked Parameters =====
+//ComboBox// exposes all parameters of all embedded plug-in instances for linking to Unify's [[realtime-params|Macro Knobs]]. The link paths are constructed in a simple way, best illustrated with an example. Using the mono vocoder graph shown in the first image above, you could select, say, the //Hi Thru// parameter of the //mda Vocoder 1// plug-in like this:
+{{::combobox-2.png|}}
-{{::combobox-1.png|}}
+The resulting parameter path would look like this:
-===== Headline =====
+{{::combobox-3.png|}}
-===== Headline =====
+**Note:** If you delete plug-in nodes from a //ComboBox// graph, any parameter links to that node will become invalid (they will display in red instead of green).