Gaffer: All About Boxes [Addendum 3] (Patreon)

Another powerful feature of Gaffer is that it allows you to create node collections ("subgraphs") with custom interfaces. These are called Boxes. Let's take a look at how they work!

Going back to the image processing workflow described in Addendum 2, one extra feature I needed was the ability to quickly choose which image set should be processed. Using a LocalDispatcher it's easy to process them all at once and adding a Switch lets you choose one in particular. The Switch interface is a bit awkward, though. You have to manually set the input, in this case to either 0, 1, 2, 3 or 4.

A Box to the rescue! I created a Box node, renamed it to SelectOuputs, connected my four tasks to it and then clicked Show Contents.

This opens a new Graph Editor tab that shows what's in the Box. To start, it just contains the four inputs.

I added a Switch node and a TaskList to handle the case of doing all jobs at once. Connect everything and then connect the Switch output to a BoxOut.

This is well and good, but now all we have is our clunky Switch interface hidden inside a Box. Not much of an improvement! Let's create a custom interface on the Box for maximum user-friendliness. Any parameter on any node inside of a Box can be promoted to the Box's interface. Simply right click on a parameter and chose Promote to <Box Name>.

Going back to the original node tree, we can see that the Box now displays the Switch's Index parameter.

This isn't any better than the original Switch, as we still have to type in a number. Click on the gear icon in the upper right and select Edit UI... In the UI Editor window that pops up, select the Plugs tab. Click the Settings menu entry on the left and then select the index parameter. In the Widget field, select Presets Menu.

This will let us create a dropdown list assigned to each value of the Switch's index. In this case, I named index 0, Cover, index 1, Turntable, etc, finishing with index 4, All.

Close out of the UI Editor. Now all we have to do to pick which images are processed is chose from the dropdown. Selecting Closeups from the list is much more intuitive than typing, let's see, what was it... "2" into the Switch.

Finally, note that you can open up the UI Editor again and uncheck all the Plug Creators options. This will make for a nice clean box interface without the extraneous "plus" icons.

Conclusion

This was a simple but time-saving example of the power of Boxes. A more advanced use case might be to create a Box containing an entire Cycles material graph. For example, you could create a Box with a cyclesPrincipledBsdf, cyclesImageTexture inputs, cyclesDisplacement, ShaderAssignments and much more. Create the needed inputs and outputs and promote all the parameters you need access to: image paths, roughness values, displacement size, you name it.

Now, instead of having to wire up potentially dozens of nodes individually each time you want a new material, simply place a copy of the Box and update all its parameters. You can see how this would easily scale to ever larger and more complicated scenarios. You could have an entire scene with thousands of nodes in a Box and control only what you need through promoted parameters. Give it a try!