8. Using subcompositions inside of other compositions

If you find yourself copying and pasting the same group of nodes and cables into many compositions, you may want to turn those nodes and cables into a subcomposition. A subcomposition is a composition that can be used as a node inside of other compositions. A subcomposition saves you the effort of having to recreate the same nodes and cables over and over. They’re packaged neatly inside a node, which you can drag from the Node Library onto your canvas just like any other node.

Let’s walk through an example. Suppose you often draw hemispheres (half spheres) in your 3D compositions, and it would be convenient to have a Make Hemisphere node in your Node Library. The first step is to identify the nodes and cables that you want to package into a subcomposition.

The composition above renders two rotating hemispheres to a window. (The Trim 3D Object node cuts off half of the sphere. The Show Back of 3D Object node makes the inside of the sphere visible.) In other compositions, you might want to create any number of hemispheres. The hemispheres could have different rotations, positions, sizes, and colors. They could be rendered to a window or an image. For the subcomposition, let’s choose a piece of the composition that’s flexible enough to be used in all of these cases: the nodes and cables tinted magenta.

The next step is to create the subcomposition, which starts as a regular composition (File > New Composition). You can copy and paste a piece of an existing composition into the new composition.

The subcomposition above contains the nodes that were repeated in the previous composition to make two hemispheres. In the previous composition, the Make Sphere node’s Material input port and the Transform 3D Object node’s Transform input port controlled the color, position, rotation, and size of the hemisphere. The Transform 3D Object node outputted a Scene Object that was sent to the Render Scene to Window node.

But in this subcomposition, since there aren’t any cables going into the first node in the line (Make Sphere), none of the nodes will execute. And since there aren’t any cables going out of the last node in the line (Transform 3D Object), the Scene Object won’t be rendered. In short, this composition won’t do anything. The next step is to add some cables.

The subcomposition above now has published ports and cables. Published ports are the subcomposition’s way of inputting/outputting events and data from/to the composition that contains it. When you turn the subcomposition into a node (in the next step), its published input and output ports will become the input and output ports on the node.

The above subcomposition has published input ports for the hemisphere’s Transform and Color. These published input ports provide enough flexibility to change the hemisphere’s position, rotation, size, and color. They don’t allow changing the Trim 3D Object node’s inputs, since that would make the subcomposition output a shape other than a hemisphere.

Now that the subcomposition contains the nodes needed to create a hemisphere and the published ports and cables needed to input and output data and events, you can turn the subcomposition into a node. Go to File > Move Composition to Node Library (or File > Save Composition to Node Library if you haven’t yet saved the composition). This makes the subcomposition appear as a node in your Node Library. You can now use the node inside of other compositions, as demonstrated below.

8.1. Reasons to use subcompositions

The Make Hemisphere subcomposition illustrated one motivation for using subcompositions: to avoid recreating the same composition pieces over and over again. A subcomposition enables you to assemble a composition piece once and reuse it many times. If you notice a problem with the subcomposition or want to improve it, you only have to make the change in one place to have it apply everywhere the subcomposition is used.

Another reason you may want to use subcompositions is to better organize large compositions to make them more readable. You can replace a complex network of nodes and cables with a subcomposition that has a descriptive title and a clearly defined set of inputs and outputs.

A third reason for using subcompositions is to share your work with others in a modular format. When you create a composition piece that other people might like to use inside of their compositions, you can package it as a subcomposition that others can install in their Node Libraries.