Creating Image Generator and Image Filter compositions
Transcript
Hi, this is Jaymie from Team Vuo.
In part 1 of this tutorial, you learned that a protocol composition has to have certain published input and output ports. This guarantees that the app running the composition knows exactly what information to send to the composition and get out of it. Each different protocol has its own specific set of inputs and outputs.
Image Generator protocol
One protocol for Vuo compositions is called the Image Generator protocol. The Ripple Image Gradients composition from part 1 of this tutorial was an Image Generator.
To create a composition that follows the Image Generator protocol, go to “File > New Composition with Protocol > Image Generator”. Or, if you already have a composition and want to make it conform to the Image Generator protocol, go to “Edit > Protocols > Image Generator”.
An Image Generator composition has inputs called “width” and “height” for the size in pixels of the image to be generated, and an input called “time” for the point in the animation at which to take a snapshot. When running a composition in Vuo, and usually in other applications too, “time” is measured in seconds. The Image Generator composition also, of course, needs an output port for the generated image — this is called “outputImage”.
When you make an Image Generator composition, you’ll want to take these “width” and “height” published input ports and feed them into your image effect so your image comes out the right size. Then take the created image and feed that into the “outputImage” published output port.
So if you just do that much, the Image Generator composition creates a still image of a checkerboard. It would be more interesting if the checkerboard would animate somehow. For animations, you’ll want to use the “time” published input port. Feed that into whatever numbers you want to change over time. Here, the Time input is fed into a Wave node to twirl the image back and forth.
So, that’s how to create a composition that follows the Image Generator protocol. The Image Generator is the protocol to use for exporting movies from Vuo, plus you can use it in VJ apps like CoGe.
Image Filter protocol
There’s a second protocol for Vuo compositions, and that’s called the Image Filter protocol. Whereas an Image Generator composition creates a new image, an Image Filter composition takes an existing image and adds some kind of effects to it.
Just like with the Image Generator protocol, you can create a new Image Filter composition by going to “File > New Composition with Protocol”.
Since the Image Filter composition is altering an existing image instead of creating a new one, it has an “image” published input port instead of “width” and “height”. It also has a “time” published input port and an “outputImage” published output port.
When you run an Image Filter composition in Vuo, Vuo feeds in a sample image and a series of times through the published input ports, and displays the filtered image in a window.
Extra published input ports
In a protocol composition, sometimes it’s handy to be able to control parameters besides the protocol inputs. For example, with the checkerboard image generator, you might want to change the color. You can change the color in the Vuo editor by editing the input port value within the composition. But what if you want to be able to change the color from within CoGe or another app?
When you’re running a protocol composition inside another app, if that app supports it, you can expose extra parameters to control by turning them into published input ports in the composition. Drag a cable from the input port inside the composition onto this “Publish” well, and it gets published. If you run the composition in Vuo editor, you can now change the color by using the input editor for the published port, which gives you a slider. If you run the composition in CoGe, then you can see a slider for the “Hue” published input port and use it to change the color.
One event in, one event out — preventing hangs and unintended outputs
In part 1 of this tutorial, you learned that, when Vuo or another app runs a protocol composition, it sends a stream of information into the composition’s published input ports. What that actually looks like from the composition’s point of view is that, every fraction of a second, an event comes in through all of the published input ports simultaneously, and carries the data along the published cables into the composition. Then the composition does whatever it does with the data, and the event carries it on out through the published output port.
It’s really important to make sure that, for each event that comes in, exactly one event goes out. Basically, that means: make sure that each event coming in through the published input ports makes it to the published output port, and that no extra events are getting fired from within the composition to the published output port.
Why is it important to make sure that each event coming in through the published input ports makes it to the published output port? Here’s a composition that doesn’t do that. If you run it in the Vuo editor, you just get a blank window. And if you try to export a movie from it, you can’t — Vuo tells you there’s a missing cable to the ‘outputImage’ published port. If you try to run the composition in another app, it might cause the app to hang.
Why is that? Well, each time the movie exporter or app sends an event into the composition, it’s going to wait for as long as it takes for the event to come out the other side before it sends the next event. If the event never comes out, well, it might just wait forever. So, if you get an error when exporting a movie or see a hang when running a protocol composition, that might be why. You can avoid these problems by testing your composition in the Vuo editor to make sure your events are going all the way through the composition and not being blocked.
I mentioned it’s also important to make sure that no extra events are getting sent through the composition. How come? Well, let’s look at trying to export a movie. Here’s a composition that illustrates the problem. When you run this composition in the Vuo editor, it displays the number of seconds that the composition has been running. If I export a 10-second movie from this composition, will it print times 0 to 10? And if I make it 30 frames per second, will the displayed times increment by 1/30 of a second? No. The displayed times increment erratically, and they only go up to 3.96. That’s because the extra events fired by the Fire Periodically node get in the way. Plus, Fire Periodically is firing in real time, so it doesn’t account for the fact that it only took the movie exporter 3.96 seconds to render 10 seconds’ worth of frames.
How would you fix this composition so that it works the same whether you run it in the Vuo editor or export it as a movie? Instead of using ‘Fire Periodically’ and ‘Count’, you could feed the ‘time’ published input port directly in to make the displayed text. In other words, replace the node that fires events with equivalent nodes that don’t.
Here’s another example. This composition fires extra events from its Play Movie node through the published output port. You can get rid of those extra events by replacing the Play Movie node with a Decode Movie Image node, which doesn’t fire events.
Here’s one more example. This composition fires an extra event from its Fire on Start node. Instead of Fire on Start, you can use Allow First Event. Allow First Event is good for setup, like fetching images, since it only lets its first event through, and it doesn’t fire any events of its own.
One last trick to avoid firing extra events from a protocol composition is to block events before they reach the published output port. If you want to use a Vuo composition to display live video in CoGe, you can create an Image Generator composition with a Receive Live Video node. That node does fire events, but you can block them with a Hold Value node. Each time an event from the published input port hits the Hold Value node’s refresh port, the event goes through the node and carries the most recent live video frame with it. The live video frame reaches the published output port without an extra event.
So, once again, the rule for event flow that protocol compositions need to follow is: for each event that comes into the published input ports, exactly one event goes out of the published output ports.
Summary
The two types of protocol compositions in Vuo are Image Generators and Image Filters. An Image Generator creates a new image, while an Image Filter takes an existing image and adds effects to it.
Protocol compositions can have additional published input ports if you want to control additional stuff from the app that runs the composition.
When making a protocol composition, make sure that, for each event that comes in through the published input ports, exactly one event goes out through the published output ports.
If you’d like to learn more about Vuo, check out our other tutorials on vuo.org. Thanks for using Vuo. We look forward to seeing what you create.
