How events travel through a subcomposition

Abstract

Events into and out of a subcomposition’s published ports

Events into a subcomposition

Changed in Vuo 2.0An event now only enters a subcomposition through the published input ports that it hit, not all published input ports.

When an event hits an input port of a subcomposition node, it travels into the subcomposition through the corresponding published input port.

When an event hits multiple input ports of the subcomposition node, it travels in through all of the corresponding published input ports simultaneously.

To illustrate, here’s a composition that uses a subcomposition node called Connect Recent Points to draw a series of connected line segments behind the mouse cursor as it moves. Below that is the Connect Recent Points subcomposition.

When an event hits the Add Point input port of the Connect Recent Points node (in the first composition above), it travels into the subcomposition (second composition above) through the AddPoint published input port. The event hits the Enqueue and Allow First Event nodes and travels onward through the subcomposition.

You might be wondering about the Max Recent Points input port, which has no incoming events. We’ll talk more about ports with constant values in a moment, but for now just know that the constant data does enter the subcomposition through the MaxRecentPoints published input port and reach the Enqueue node.

Here’s a modification of the first composition above that allows the user to toggle between a short tail and a long tail by pressing any key.

Now events come in through the MaxRecentPoints published input port whenever the user presses a key and the AddPoint published input port whenever the user moves the mouse.

Events out of a subcomposition

Changed in Vuo 2.0An event now only exits a subcomposition through the published output ports that it hit, not all published output ports.

If an event reaches a published output port of a subcomposition, it travels out of the corresponding output port of the subcomposition node.

If an event into a subcomposition node reaches multiple published output ports of the subcomposition, it travels out of all of the corresponding output ports of the subcomposition node simultaneously. For example, in the subcomposition below, even though the Calculate nodes can execute concurrently and may not output their values at exactly the same time, the Convert Cartesian To Polar subcomposition node always outputs the event from its R and Theta ports simultaneously.

If an event that comes in through a subcomposition’s published input ports doesn’t reach any of the subcomposition’s published output ports (because of wall or door ports within the subcomposition), then the event doesn’t come of out any of the subcomposition node’s output ports. The subcomposition node blocks the event.

A subcomposition can fire events, as demonstrated below. The Fire At Tempo subcomposition node is set to fire at a rate of 120 beats per minute.

Changed in Vuo 2.0Events from triggers within a subcomposition don't exit the subcomposition if they overlap with events from published input ports.

If events fired from within the subcomposition can overlap with events from the published input ports, only the events from the published input ports will exit through the published output ports. The subcomposition node will transmit events but not fire events.

The subcomposition above, me.fireAtTempo, does fire events from its published output port. That’s because there’s no overlap between the events coming in through the BeatsPerMinute published input port (which are blocked at the Fire Periodically node’s input port) and the events fired from the Fire Periodically node’s output port.

The subcomposition below does not fire events from its published output port. That’s because the event fired from the Fire on Start node travels along the same path as the events coming in from the published input port (nodes tinted magenta). The event fired from Fire on Start travels within the subcomposition but is blocked from exiting the subcomposition. Meanwhile, events that come in through the published input port do exit through the published output port.

Constant input port values

If an input port on a subcomposition node has a constant value with no cables going into it, the constant value travels into the subcomposition through the corresponding published input port when the composition starts and whenever you edit the constant value.

The data travels from the published input port to any input ports that are directly connected to it by a cable. This is a rare case in which data can travel without an event. The data reaches the input ports on nodes but does not cause the nodes to execute.

In the example below, the Generate Checkerboard Image subcomposition’s width and height input ports are set to the constant values 1920 and 1080. The subcomposition outputs a 1920x1080 image.

It’s important to realize that the data travels only through the cable from the published input port to the next node, no farther. With the below variation on Generate Checkerboard Image, the subcomposition no longer outputs an image of size specified by width and height. Why? Because the constant values 1920 and 1080 only flow as far as the Multiply node’s input ports. They don’t cause the Multiply node to execute and pass its data along to the Make Checkerboard Image node.

To fix the composition above, you could add an event cable from the time published input port to each of the Multiply nodes. This would ensure that the Multiply nodes provide the halved width and height to Make Checkerboard Image whenever Make Checkerboard Image needs them, even if width and height have constant values.

As long as the published input port connects directly to the node’s input port, you can use a constant value to control a node that fires events. In the example below, editing the subcomposition node’s Seconds input port would affect the firing rate of the Fire Periodically node inside of it.