7.2. Common patterns - How do I…

This section describes a few approaches to controlling data and event flow that you’re likely to use in many different compositions. As you begin with an idea of what you want your composition to do, you might come up with questions on how to use Vuo’s nodes and cables to create a certain result in your composition. This section of the user manual can help answer those questions.

7.2.1. Checking if a condition is met

Vuo has nodes that can evaluate whether a statement is True or False. True and false are called Boolean values.

The following is an example of a node that outputs a Boolean value, by determining if A is less than B.

You can execute downstream nodes based on whether an output is true or false. Logic nodes are often used with nodes that route data, where the logic node acts as an if and the node that routes data (normally one of Vuo’s Select nodes) as a then do this, or if not, do that.

In Vuo, you can change certain data from one type to another through type converters. Vuo converts some types automatically by letting you connect a cable of a compatible type to that of another type, using a collapsed type converter. Using this feature, True can be converted to "1" and False can be converted to "0".

Vuo also has nodes for evaluating if points are within certain parameters, such as the Is within Circle, or Is Point within Layer nodes.

7.2.2. Checking more than one condition

The nodes Are All True, Are Any True, and Is One True can be used to check if a certain combination of conditions have been met. If the conditions produce events, you can use the node Are All Hit.

The node Are All Hit will become true only if each input port receives the same event. For this to happen, an event generated by a trigger port has to be sent to two or more different nodes, splitting the event. The Are All Hit node then checks that the arriving event is identical at both its input ports. Events that are generated by different trigger ports (even if they are nearly simultaneous) are not the same event and will not cause the node to output a true value.

In the following composition a data + event cable can feed into the Share Value: A, and a different cable in to Share Value:B. The node Are All True will check if both the conditions are true.

7.2.3. Checking when a condition changes

You might want to know when there is a change in the data in your composition. Vuo’s logic node set and math node sets include nodes to test for data changes, such as Is Greater Than and Is Within Range, which output the Boolean values True and False.

You might also want to control your composition based on when something changes, such as when the output of a Is Less Than node first becomes true. The Vuo node Became True outputs an event when the input changes from false to true, as do similar nodes.

Became True and Became False are not trigger nodes. They don't generate new events; they only let an event received at the Value port through.

7.2.4. Choosing which data and events to send through the composition

A Select Input node lets you select a value from different input ports and route it to the output. There are two different classes of Select nodes. The first uses integers to control how the node functions, while the second uses Boolean true or false values. The first set of Select Input will show up in the Node Library when using Display by Name (View > Node Library > Display by name) as Select Input (2), or Select Input (8), or Select Input (Boolean). With these different options, you can control your composition based on what makes sense with respect to the rest of your composition.

Vuo's Select Input node is similar to Quartz Composer's Multiplexer patch. Vuo's Select Output node is similar to Quartz Composer's Demultiplexer patch.

Vuo's Select Input and Select Output are similar to if/else or switch/case statements.

When the Select Input node executes, it looks at what is present at the Which port and outputs the value found at the corresponding port below it. For example, if the value 1 is present at the Which port, whatever value is present at the Option 1 port will be output. If the value false is present at the Which port, whatever value is present at the False Option will be output.

Here’s a composition using both a logic node and a Select Input node. The composition will write The count is less than five four times, before The count is 5 or more begins to be written.

7.2.5. Choosing which parts of the composition to execute

A Select Output node lets you route an input value to one of several outputs. Similar to the Select Input, you pick an output port using the Which input port. Similar to the Select Input nodes, Vuo has three different Select Output nodes, one for Boolean values and two for inputs controlled by a numeric Which port, one with two outputs and one with eight.

A Select Output is useful for routing data to different parts of your composition, or only letting data through that meets certain conditions. In the following composition, although the Count node is counting up, only when the count is greater than 5 will it be written.

7.2.6. Merging events from multiple triggers

A Select Latest node lets you select the latest data and event to arrive at the node. In the following composition, Each time the mouse is scrolled or a keyboard button is pressed, the event that is generated causes the text associated with that option to be output.

If an event comes into both Option 1 and Option 2 at the same time, then Option 1 is used.

7.2.7. Setting data with one trigger and using it with another

This composition has two trigger ports firing at different rates. It writes a count upon the console window every 5 seconds. The count updates every 1 second.

The Hold Value node prevents the count from being written each time it’s updated by the 1-second Fire Periodically node.

Every 5 seconds, when the two Fire Periodically nodes fire at nearly the same time, it's unpredictable whether the count will be written before or after it's incremented.

7.2.8. Stripping data from an event, or adding an event to data

To separate out an event, you can use the option + drag from an output port to begin an event-only cable from that port.

Sometimes you may want to add data to an event. For example, you might want to add a Boolean value to an event. You can do this by connecting an event-only cable into a data port that has data. Two nodes that are helpful in adding data to an event are the Share Value node and the Select Input node with the appropriate Which port set.

Here is part of a composition that creates a color to be used by a downstream node. The color is initialized to green. If a data + event cable were connected to the A input port of the Is Greater Than node and data was received that was over a limit (in this case 100), the event from the Became True node would change the color to red.

Another way get data and an event is to use the refresh port of a node that will output the data-and-event you want, such as the Count node.

7.2.9. Starting with a certain data value

It is often good practice to initialize node data values. You can do this by using a Select Latest with one incoming cable from a Fire on Start to initialize the node’s values and another data-and-event cable from elsewhere in the composition to receive the changed data as your composition executes.

7.2.10. Simplifying your composition by sending the same data to multiple ports

What if you want to set the same value on multiple input ports? For example, suppose you want to draw several images, all having the same height. One way to accomplish this would be to go one by one to each node’s height input port, open the input editor, and set it to the height you want. But what if you later decide to change the height? It would be better to set the height in one place and have it affect all nodes.

You can do this with the Share Value node, as illustrated here. When the Share Value node receives an event, it sends the value in its input port (100) through its output port to all connected nodes.

Share Value nodes can help reduce the number of cables that cross your composition by using one cable to a Share Value node, and then creating multiple output cables from that Share Value node.

7.2.11. Keeping numbers within a certain range

Vuo has nodes that limit the range of data (Limit to Range, Fit in Range, and Count within Range), and a Scale node that scales data.

7.2.12. Doing something after a certain amount of time has elapsed

One way to do this is to use a Count node that receives an event from a Fire Periodically node. If you set up the Fire Periodically node to fire every second, the output is the number of times (thus seconds) since the node started.

If you already have a source for time in your composition (such as a Render Scene to Window, with its Requested Frame output port) you could use the Measure Time node.

In both cases, you can test the elapsed time with a logic node, such as an Is Greater Than node, and use the result to initiate your action.

7.2.13. Alternating what happens in your composition

Vuo has two logic nodes, Toggle and Switch, which can be used to in conjunction with a Select Input node to alternate between two values or two actions.

7.2.14. Changing a data value gradually between limits

Vuo has two nodes, Wave and Curve, that can be used to gradually change between two different data values. The Wave output defaults to values between -1 and 1. By changing the input values, or using this node with a Scale node, you can change gradually from a first to a second value, and back to the first value again.

7.2.15. Keeping track of the number of times that something happens

First, you will need to generate an event when the condition happens. You can then input this event into a Count node to increment its count.

7.2.16. Executing slow nodes in the background

The example composition above, Load Images Asynchronously (File > Open Example > vuo.event), shows how a composition can do some work in the background (asynchronously). It displays a colored background while downloading an image from the internet, then displays the image.

The Spin Off Event node is what allows the image to download in the background. When an event reaches the Spin Off Event node, the Spin Off Event node fires a new event. Because it’s a new event instead of the same old event, other parts of the composition can go on executing without having to wait on the event.

Let’s take a more detailed look. When the Fire on Start node fires an event, the event travels to the Spin Off Event node (where it stops) and through the upper Make Color Image node, Select Latest, Render Image to Window. All of these nodes execute without waiting for the lower Fetch Image node. Meanwhile, the Spin Off Event node fires a new event, the Fetch Image node downloads the image, and eventually the new event travels onward through Select Latest and Render Image to Window.

7.2.17. Doing something more than once (iteration)

Creating a list, and then completing actions on each item in that list is one way to perform a sequence of actions in your composition.

One way to build a list is to use the Build List node. This node fires events that can be sent to a sequence of nodes to create each item for the list. The Fire input port is used for how many events, and thus items, to generate.

The Enqueue node can be used to create a list of a set size where newer items are put in the list and older items over the set size are discarded.

Once you have created your list, two nodes are useful in acting on each item in the list. The Process List node will fire an event for each item in the input list, output that item for processing by other nodes, and through its Processed Item input port, collect the results into a new list.

The Cycle Through List node will output the next item in a list when it receives an event at its Go Forward or Go Backward input port, allowing you set up a sequence of actions for each item output.

This is a composition that uses an Enqueue node and a Cycle through List node to recolor a movie.

This composition builds a list using a Build List node and a Cycle through List node and arranges the result to make a grid of four colored squares.

7.2.18. Creating a new event when needed

If you’re building a composition, you might run into a situation where you need an event to cause something in the composition to happen, but events from the other trigger ports in your composition will cause an infinite feedback loop, or they produce events that are not timed to solve your problem. In this case, you might be able to use a Spin Off Event node.