Vuo

2.0.0

Revised 2019.08.29


Getting started

Abstract

An example that illustrates the basic concepts

Welcome to the Vuo community! So you want to learn how to use Vuo in your creative work. Let’s jump right in with an example.

Quick start

This example will walk you through the process of creating an animated pattern like this:

You can watch a video of this example at https://vuo.org/tutorials

You can find the completed example composition in File > Open Example > Quick Start.

If you haven’t already, download and install Vuo, as described in the Installing Vuo section.

Creating a new composition

In Vuo, the documents that you work with are called compositions. Start a new composition by going to New Composition from Template > Window > Image.

The rounded rectangles in the composition window are called nodes. The area that you place nodes on is called the canvas.

For this example, you won’t need all of these nodes, just Fire on Display Refresh and Render Image to Window. So you can click on each of the rest of the nodes and hit (Delete).

As you may have guessed from their titles, each node has a job or responsibility. The two nodes on the canvas will each perform a task that contributes to the animated pattern that you’re creating. The Render Image to Window node will be in charge of displaying the pattern in a window. The Fire on Display Refresh node will be in charge of the timing of the animation.

An animation is a series of images displayed in rapid succession. The fastest rate at which your computer monitor can display a series of images is called the \emph{display refresh rate}. On many monitors, the display refresh rate is 60 times per second.

Running the composition

Let’s see what you’ve built so far. Click the Run button. This launches the composition.

Before, on the canvas, you were looking at a blueprint or instructions for what the composition is supposed to do. Now, you’re seeing the composition in action.

The window that pops up comes from the Render Image to Window node.

Adding a node

So far, you have a solid black graphics window. To show an image in the window, you’ll need a node whose job it is to make an image. To find such a node, search the Node Library for make image, like this:

The Node Library is a directory of all available nodes. If you don't see it, go to View > Node Library > Show Node Library.

In the search results, locate the Make Noise Image node.

Drag the Make Noise Image node from the Node Library onto the canvas.

Connecting nodes with cables

Now you have three nodes on the canvas. Individually, each node does a simple job. How do you make them work together to accomplish something bigger? You connect them with cables.

Start dragging from the circle on the right of the Fire on Display Refresh node, which is called an output port. The line that emerges from the port as you drag is called a cable. Drop the end of the cable onto the circle on the left side of the Make Noise Image node labeled Time, which is called an input port.

Next, drag a cable from the output port of Make Noise Image and drop it on the Render Image to Window node’s Image input port.

Back in the graphics window, you can see that the three nodes are now working together to make a rapid succession of noise images and display them in a window.

To learn about noise images, read the Make Noise Image node's documentation in the lower panel of the Node Library.

The ability to modify a composition while it's running and see the results immediately, as in this example, is called \emph{live editing}.

Editing an input port value

You can alter how a node does its job by editing its input port values. For example, double-click on the Make Noise Image node’s Color B input port and choose a different color.

Adding another node

You can add more nodes to your composition to make more interesting effects. Search the Node Library for image filter to see the built-in image effects.

Drag the Make Stained Glass Image node from the Node Library onto the canvas.

Draw a cable from the Make Noise Image node’s output port to the Make Stained Glass Image node’s Image input port, then another cable from the Make Stained Glass Image node’s output port to the Render Image to Window node’s input port.

As you did with the Make Noise Image node, you can adjust how the Make Stained Glass Image node affects the image by editing the node’s input port values.

Summary

This example covered many of the basics of using Vuo.

  • You learned that each node is in charge of one job.

  • You learned that nodes work together by communicating through cables connected at ports.

  • You launched your composition into action with the Run button.

  • You searched the Node Library for a node that does a specific job.

  • You added nodes to the canvas and connected them with cables.

  • You changed settings such as colors by editing input ports.

Next, we’ll take a closer look at what exactly happens while a composition is running.

Tracing through a composition

Abstract

Using port popovers to see the information flowing through a running composition

When you ran the Quick Start composition, the four nodes in the composition worked together to create an end result: a window displaying an animated pattern. As you added each node to the composition, you saw how it contributed to the end result. Now let’s look at each node’s contribution in more detail.

Port popovers

If you want to understand the inner workings of a composition, port popovers are an extremely useful tool. You can visualize step by step how each node contributes to the end result.

Open the port popover for the Fire on Display Refresh node’s Refreshed at Time output port by clicking on the port. The small window that appears is the port popover. As the composition runs, the port popover shows the information flowing through the port in real time.

Information flow

Two kinds of information can flow through ports: data and events.

For the Refreshed at Time port, the data is the time — the number of seconds since the composition started running. At the moment the screenshot above was taken, the port popover showed that the data was about 4.05.

The port popover also shows that the Refreshed at Time port is outputting information at about 60 times per second (the monitor’s refresh rate). Every 1/60 second, the port outputs a slightly greater number of seconds — accompanied by a second piece of information called an event.

Events control the timing of your composition. An event is an impetus or signal that tells a node that it’s time to do its job.

Why are events and data separate things? This will become clear later when you learn about event-only ports and event-only cables, in which events travel without data.

When you run the Quick Start composition, the nodes do their jobs one at a time, left to right. That’s not because they happen to be placed left to right on the canvas, but because the events and data flow through nodes and cables in a methodical way — which we’ll trace through now using port popovers.

Step 1

Click on the port popover for Refreshed at Time so it will stay open on the canvas. Then click on the Make Noise Image node’s Time input port to open its popover.

As you can see, the events and data shown in the two port popovers are the same. A stream of information is flowing out of the Refreshed at Time output port, along the cable, and into the Time input port.

As each event hits the Make Noise Image node’s Time input port, it prompts the Make Noise Image node to do its job. The node does so, using the data that accompanied the event as one of its parameters.

Step 2

Open the port popover for the Make Noise Image node’s output port. It shows a small version of the image created by the node.

Each time the Make Noise Image node does its job, it sends two pieces of information through its output port — the same event that came in the Time input port, accompanied by new data: the image created by the node.

The event and data then flow along the cable to the Make Stained Glass Image node’s Image input port

Step 3

Open the port popover for the Make Stained Glass Image node’s output port.

Now that the Fire on Display Refresh, Make Noise Image, and Make Stained Glass Image nodes have worked together to produce the image shown in the port popover, the final step is for the Render Image to Window node to display the image in a window.

Summary

By tracing through the Quick Start composition, this section illustrated some skills and concepts for understanding how a composition works.

  • You learned that Vuo has two basic kinds of information: data and events.

  • You opened port popovers to reveal the data and events flowing through the composition.

  • You watched two types of data, numbers and images, flowing through the composition.

  • You observed the rate at which events were prompting nodes to do their jobs.

Learning Vuo

Now that you’ve perused the Quick Start and Tracing through a composition sections, you’ve been exposed to the key concepts underlying Vuo and are well on your way to creating your own custom compositions. Before digging deeper into those concepts, we’ll mention some resources that teach Vuo in different ways. You can choose the path that best matches your learning style.

User manual

The user manual (this document) provides the most detailed documentation of the concepts underlying Vuo and of Vuo’s user interface. You may choose to read it all the way through, or you may refer to it when you have questions about a specific topic.

Terms used in this manual are defined in the glossary at the end.

Tutorials

Video tutorials are available on our tutorials page.

Example compositions

Vuo comes with over 200 example compositions that demonstrate how to accomplish tasks in Vuo.

Example compositions can be quite helpful when learning how to use a node. Many nodes have relevant example compositions listed in their Node Documentation Panel.

@todo image

You can search for an example composition by name in the Help menu's Search box.

To browse the list of all example compositions, go to File > Open Example.

Community support

The community of people who use Vuo can be an incredibly helpful resource when you’re learning Vuo. As part of that community, you can discuss questions and answers on how to use Vuo, share compositions, and suggest features to improve Vuo. To get started, visit our community page.

Node documentation

Every built-in node and node set in Vuo comes with documentation that explains how to use it.

@todo image

Alternatively, you can browse the online node documentation.

SDK documentation

If you’re a developer who would like to embed Vuo in an application or to implement custom nodes, you can explore the API documentation.

Vuo in other applications

If you use CoGe or VDMX (VJ applications that mix and composite media), you can install Vuo compositions to add to your available visual effects. This manual explains how to set up your compositions in Making compositions fit a mold with protocols. To learn how to install and use compositions in CoGe and VDMX, check out their documentation.

Installing Vuo

  • Go to https://vuo.org/download.

  • Click the Download Vuo button.

  • Uncompress the ZIP file (double-click on it in Finder).

  • Move the Vuo application to your Applications folder.

  • Open the Vuo application.

  • Follow the instructions in the dialogs.

Activating Vuo Pro

If you’ve purchased Vuo Pro, you’ll need to activate your license in the application.

After launching Vuo, when you reach the dialog below, click Activate Vuo Pro.

In the next dialog, follow the instructions to activate Vuo Pro.