3.3. Events are what cause nodes to execute

Let’s think again about creating a composition that applies a color effect to a movie. Your first step might be to drop a Play Movie node, an Adjust Image Colors node, and a Append to Movie node onto the canvas. Then what? How do you tell the composition that, first, you want Play Movie to bring the movie into the composition, second, you want Adjust Image Colors to apply the effect, and third, you want Append to Movie to save the movie to a file? The way that you control when nodes do their job and how information flows between them is with events.

In the Quick Start section, you walked through the process of creating a composition that displays some text:

If you're familiar with the way that patches execute in a Quartz Composition, then Vuo takes some getting used to. In Quartz Composer, when patches execute is largely based on the display refresh rate, and influenced by patch execution modes and interaction ports. Data is usually "pulled" through the composition by rendering patches. In Vuo, data is "pushed" through the composition by events fired from trigger ports.

Vuo is event-driven. The events are generated by trigger ports, and the event handlers are implemented by the nodes executed as the event travels through the composition.

How do events come into play in this composition? This composition involves a single event that causes the text to render as soon as the composition starts running. The event is fired (originates) from the trigger port called Started on the Fire on Start node. (A trigger port is a special kind of port, which you can recognize by the thick line along its left side.) The event travels to the Make Text Image node, causing that node to execute (do its job). The event then travels onward to the Render Image to Window node, causing it to execute as well. From the Make Text Image node to the Render Image to Window node, the event carries with it the image that was created by Make Text Image and will be rendered by Render Image to Window.

Here’s a variation on that composition that involves multiple events:

This composition displays an animation of the text becoming more and more twirled as time passes. It still has the event fired from the Fire on Start node’s Started port when the composition starts. It also has events being fired from another trigger port: the Render Image to Window node’s Requested Frame port. Unlike the Started port, which fires only once, the Requested Frame port fires 60 times per second (or whatever your computer display’s refresh rate is). Unlike the event from Started port, which is useful for doing something once, the events from the Requested Frame port are useful for doing something continuously, such as displaying an animation that changes smoothly over time. In the composition above, each of those 60 times per second that the Requested Frame node fires an event, that event (along with a piece of information that says how long the composition has been running) travels to the Multiply node. The event (along with the result of multiplying numbers) travels to the Twirl Image node. Finally, the event (along with the twirled image) travels to the Render Image to Window node. As the event travels along its path, it causes each node to execute in turn, and carries information with it from one node to the next.

Here’s a composition that doesn’t display text in the window (can you guess why?):

This composition doesn’t have any events going into the Make Text Image node. Without any incoming events, the Make Text Image node never executes and never passes an image along to the Render Image to Window node. So no text is displayed. If you want a node to execute, make sure you feed it some events!

If you’d like to watch the events moving through a composition, you can do that in the Vuo Editor by clicking the Show Events button in the toolbar. As the composition runs, you can see the events being fired from trigger ports, and you can trace the path of the event by watching each node change color as it executes.

You can use Vuo's events somewhat like you'd use Quartz Composer's signals or pulses. For example, Vuo's Count node works a lot like Quartz Composer's Counter patch.