This tutorial will cover the concept of encapsulation
within Max. Encapsulation allows us to place sections of our patcher within their own subpatch
using the patcher
object. This lets us hide parts of patcher logic that we no longer need to see, in order to make our projects easier to read and more concise. We will examine the creation of a patcher
that contains objects, as well as using some editing tools to encapsulate parts of a patcher that no longer need to be seen.
Properly encapsulating your Max logic is important for keeping your patch files clean, easy to read and maintainable. Encapsulated logic can be easily edited, and can also be saved off as separate files that can be reused in other patches.
At the top-left of the tutorial, there are two small patches that do the same thing – they both add +
object, while the patch on the right uses a patcher
object. The patcher
object (which can be abbreviated "p", much as trigger
can be abbreviated "t") is literally another patch embedded in the current patch. To see the contents of a patcher
object, you can double-click on it (when the patch is locked) to open the encapsulated patcher
to the incoming . The patch on the left does it with a
If we double-click on the patcher
object, a small patcher window shows the contents (in a window labeled - the name of the subpatch). It is a simple subpatch, with only three objects. The object in the middle is obvious – it is the +
object that performs the addition. The objects above and below the +
object are inlet
objects, respectively. An inlet
object causes the enclosing patcher
object to have an inlet, while an outlet
object causes the enclosing patcher to have an outlet. In this way, we can make patcher objects that act very much like built-in Max objects. Multiple inlet
objects will create corresponding inlets and outlets on the enclosing patcher
object, arrayed spatially in relation to how they are in the subpatch (e.g. the leftmost inlet
object will correspond to the leftmost inlet on the patcher
When working with inlet
objects, it is useful to add assistance
to them; in this way, the enclosing patcher
can display helpful information about the type of message that is expected by the inlet, or produced by the outlet. If you select an inlet
and then open the object’s Inspector, you will see that there is a field available. Any text that you enter in this field will show up as assistance in the patcher
object during patch editing.
Creating sub-patchers sometimes needs to happen after the logic is in place; perhaps your patcher has expanded beyond where you originally thought it would go, or you’ve added logic that wasn’t planned, and things are starting to get messy. In these cases, it would be useful to be able to select a group of objects and quickly turn them into a single encapsulated patcher. This can be done using the Encapsulate menu item.
Our example patch has an interesting drawing algorithm, where you move a puck around a rectangular area (using an object called the pictslider
), and small circles are drawn in the area randomly near the equivalent position in the lcd
at the bottom of the patch. If you need to clear the lcd
, you can hit the space bar (ASCII character , captured by the key
object and triggered by the select
object). The logic is rather messy, and it doesn’t really help us to see it spread around the screen. We are going to select a majority of the logic and encapsulate it into a subpatch.
There are two comment
boxes (“encapsulate from here” and “to here”) that we will use to select our encapsulated logic. Unlock
the patcher, then select (using click-and-drag) all of the objects between and to the right of the comment boxes. 15 objects will be selected. Select Encapsulate
from the Edit
menu, and you will see that all of this logic is folded into a single unnamed patcher
patcher. If you lock the patch and double-click the patcher
object (or command-double-click in an unlocked patcher), it will open the subpatch and show all of the objects again, tied to the outside world using four inlet
objects and one outlet
object. If, for some reason, we needed to reverse this process later, the De-encapsulate
command under the Edit
menu will unravel the subpatch back into our main patcher, re-connecting everything correctly as it was originally.
It is often useful to name our patcher
objects; while this adds no particular value to the patcher
, it will help you (and others) understand the logic that is encapsulated into the object. To name it, just click inside the object, and add a first argument that is the name you’d like to use. Something like would be perfectly useful for this example.
When you know ahead of time that you want to work within a subpatch, it is easy to create a patcher
object and work within its editing window. At the lower-left is a pair of number
boxes connected by – nothing. We will make a subpatch here and use it to convert one value into another.
Create a new, blank object in between the number
boxes by double-clicking in the blank area and selecting the object
box (at the top-left of the palette). In the new object box, type - this will create a new patcher
named . A new window will appear for editing our new subpatch. Start with an inlet
(both available from the object palette). Note that adding these to the patcher added and inlet and an outlet to the patcher
object in our main window. Next, connect the inlet
directly to the outlet
– thereby making a “thru” object that does nothing except pass incoming message to the outlet. Let’s test this encapsulation in the main patcher window.
Now that our patcher
object has an inlet
, we can connect it to the number
boxes. Connect the top number
box to the patcher inlet
; connect the patcher
outlet to the bottom number
box. Lock the patch, and change the top number
box: we should see the bottom number
box change to match. This shouldn’t be a surprise, since our patcher
object encapsulates a straight line between the two boxes!
Let’s go back to the patcher
editing window and add some logic - if the window has closed, double-click the patcher
object to open it up again and unlock it. Start by selecting and deleting the patch cord connecting the inlet
. Now, let’s add some math: create two new objects, a +
object and a /
object. Now, connect the inlet
to the +
object, the +
to the /
object, and the output of the /
object to the outlet
. We’ve changed our encapsulation from meaningless subpatch into an “(input + 50) / 7” patcher
. The nice thing about doing this within an encapsulation is that we don’t have to change anything in the top-level patcher – all of the connections remain as-is. Now, at our main patch, changing the top number box will produce the new result without any further changes.
Encapsulation of patching logic accomplishes two things:
1. it allows us to work at higher levels without having to interact with (or even see) all of our objects; and,
2. it allows us to change our lower-level logic without having to change anything at the higher-level programming.
In working with patcher
objects, you can either manually create and populate them, or you can select existing patcher logic and use the Encapsulate
menu option to automatically create a subpatch. In either case, you can further explore and change the patcher
code without any further changes to the higher level patch.
Create a subpatch within a patch
Receive messages from outside a patcher
Send messages out of a patcher
Picture-based slider control