With the new 2022 official release of TouchDesigner, one of the most developer-requested features is the ability to add comments directly into your network. This was previously something you had to do by dropping Text DATs around the project, but it was neither intuitive, clean, nor easy to use. We finally have native comments in TouchDesigner and networks are about to get a WHOLE lot cleaner and more manageable!
The hierarchy of comments
The three main new components of commenting are part of the new Network Utilities functionality in TouchDesigner. Network Utilities is an important name to remember going forward, as it seems like more and more things might get included in this group of functionality. Especially as there is the main reference for comments being under the page named Network Utilities:
https://docs.derivative.ca/Network_Utilities:_Comments,_Network_Boxes,_Annotates
For now, our network utilities are exclusively used for commenting/documentation/grouping purposes in our projects and involve 3 sub-features: comments, network boxes, and Annotate COMP. The relationship between these 3 features is important because the comment and network boxes functionalities are made using different modes and parameters of the Annotate COMP. This means you can think about the Annotate COMP as the fully-featured program-your-own-commenting-and-grouping COMP, and the comments and network boxes are like quick preset versions you can drop into your network. This is a good way to visualize this relationship:
Following this diagram, we have our network utilities group of functionality, inside that is the Annotate COMP which is the most fully-featured building block, and then from the Annotate COMP come the comment and network box features. In this post, we’ll mainly look at the comments and network boxes as those are the features you’ll want to dive into and start using right away!
Comments basics
Comments are the most basic form of using the Annotate COMP. They give you a block that looks like a Text DAT except it has some additional functionality in that it can site behind other operators, having internal text styling, and it can do something called Enclosing. To get started, you can drop a comment into the network with Shift + C. Immediately memorize this hotkey. The last thing you want to be doing is opening up the Right-click menu every time you want to make a comment (although you can access them from there).
You’ll notice that the comment box gets dropped wherever you last clicked your mouse. You’ll want to remember this and start to train your muscle memory to click then hit Shift + C to drop a comment where you want it to be. This is different from other environments that use the hover position of the mouse for where to drop comments. There are a few immediate things you can do with the comment box. First is to type your comments inside the body of the comment, and second is to move and resize the comment box:
Typing inside the comment box is as easy as double-clicking inside it and starting to type. Moving it is as easy as clicking on the network background (or hitting escape on the keyboard) to exit the text editing mode, and then you can click and drag or resize it like any other operator. Even with just these basics, you can start to make very pretty commented areas of your project that could look like this:
Already this looks way better than having a Text DAT note beside this series of operators! So what about some more advanced features of comments?
Comments advanced
Two additional things you can do with a comment box (and all network boxes and annotations) is to change the text size and enable operator enclosing. You can do these easily through the right click menu. If you right-click on the comment when the text editing isn’t active, you can select Parameters to open up its basic settings. In here you’ll have custom parameters for editing the comment text as well as the text size:
That’s helpful, especially if your networks start to get bigger and the comments start to become difficult to read as you zoom out. More exciting than that is the enclosing feature. What you’ll notice now is that if you move the comment box, you just move the comment box. The enclosing feature does something really cool: it attaches the operators inside the comment to the comment box itself. That way, if you move the comment box, you end up moving the comment AND all the operators inside it. To enable and disable the enclosing feature, you can right click on the comment box and toggle Enclose Operators:
This is a HUGELY impactful way that you can start to organize your projects. Previously, if you wanted to do a similar kind of grouping, you would have to encapsulate those operators inside a Base COMP or Container COMP. In many cases, that made sense, but there were also a lot of cases where that was 100% overkill. This ability to enclose operators inside the comment boxes (as well as the network boxes and Annotate COMPs!) gives us a great alternative to network organization and grouping operators. So what about network boxes?
Network boxes
Both comment boxes and network boxes derive from the functionality of the Annotate COMP we mentioned earlier. We’ll go over the Annotate COMP on its own in a more full length tutorial. What this means is that all of the functionality we talked about with the comment boxes also applies to network boxes. This includes the ability to open it’s parameters to change text sizes as well as the ability to enclose operators. To create a network box we can use the hotkey Shift + B.
A good way to remember this is that Comments -> Shift + C and network Boxes -> Shift + B.
You’ll immediately notice one of the main differences between comment boxes and network boxes: the title bar.
The comment boxes are focused on typing text into the body of the comment, while the network boxes are focused on having a title bar. The reason it is set up like this is because of the second main difference: network boxes have Enclose operators enabled by default. Their functionality is more about grouping operators together and giving that area of the network a title than they is about holding dense documentation. The comment boxes are where you’ll want to put paragraphs of help text. The nice way this works in practice is that once you create a comment box, you can double-click inside it, and it will open the Op Create dialogue. As you add new operators inside the network box, they are automatically enclosed with it:
Other than that, there aren’t any fundamental differences between comments and network boxes. They’re built to do slightly different things and have different hotkeys to create them.
For a further look at comments inside of TouchDesigner, check out our tutorial here:
Wrap up
Whether you’re a new developer or a seasoned expert, everyone is excited about diving into the new commenting system. The important things to remember from this post is that these are all housed in the new Network Utilities group of features, and the comments and network boxes derive functionality of the Annotate COMP. We’ll dive into Annotate COMP’s much more advanced functionality in another post, but in the meantime, happy commenting!
