Gregory Taylor

 anxiety reduction regimen. Last time out, we talked about the 

 operator - what it does, how it works, how you can use it to create your own functions and - should you so desire - add some procedural coding to your 

Working with Abstractions, Debugging and Signal-Rate Processing

We’ve suggested that the Code Tab in your patcher window is a great place to acquaint yourself with GenExpr - the language of the codebox. This tutorial is intended to help you leverage what you already know about Gen operators, operator outlets and attributes, and provide an introduction to how you can work with 

 operators in the GenExpr language. It’s time for some thinking 

More about GenExpr - Outlets and Attributes

So far, we’ve talked about some of the basic features of GenExpr, and showed you some examples of how you can create your own simple patches.

 operators, I’d like to touch on two topics that we’ll encounter when doing 

 operator to count through samples in a buffer. So far, we’ve been working with GenExpr and operators that output a single value. What happens when GenExpr specifies the output of an operator when there’s more than one outlet to the original operator?

When it comes to reading buffer data and other 

 patching, we’ve often made use of operator attributes. How do we do that in 

By now, you’ve probably gotten used to using the patcher window’s Code Tab to see what the GenExpr version of the Gen operators you work with are, whether it’s to see what the default values associated with an operator are…

image.png

...or to see what the syntax of the operator is. And remember - if you can’t remember what a given inlet for an operator does, hover over the inlet with your mouse.

pasted image

You will have noticed that the order in which parameters in GenExpr are listed corresponds to the inlets in the Gen operator of the same name, and are conveniently in left-to-right order. You’ve also noticed that you can assign a variable name to the outlet of one of those GenExpr-format operators, too. But how does GenExpr deal with operators that have 

To explore that, we’ll take a really simple example taken from an earlier 

 for Beginners tutorial – an example of the 

 operator with all of its inlets specified using constants. The counter counts to 44100 by ones, and is always on (that’s what the zero constant in the second inlet of the 

 operator does). To take a look at the GenExpr code related to the counter operator, we can select it and take a look at the Code Tab, where the GenExpr code will be highlighted:

Multiple outlets from an operator are represented in GenExpr as a list of variables that appear to the left of the code associated with the operator (in this example, they’re 

. As with the input values to the operator (the stuff inside of the counter operator’s parentheses), the outlets are also listed in the same order as the outlets, from left to right. Those are the variables you use inside of your codebox.

When you’re patching using operators, the GenExpr code you see in the Code Tab is automatically generated as you patch, and those automatically generated variable names are not very memorable. Since you know what the 

 operator output is (the current count, the carry flag, and the carry count), you can label those variables yourself in a way that’s more intuitive. Here’s a codebox version of the same patch that names things a bit more clearly:

The example patch makes use of and outputs all of the output from the 

 operator, but it may be that you only care about a single output (say, the count itself). When your GenExpr function returns multiple values but assigns to only one value, the unused return values will be ignored, and GenExpr compiler gets rid of most calculations that aren’t necessary automatically.

In addition to operator outputs, there’s another feature of the Gen operator that we’ve made note of from time to time: operator attributes. In previous tutorials in this series, we’ve seen attributes used for several things:

There are a number of Gen patchers that use operators - in particular, the operators used to read from and write to 

 objects offer a number of options to you, which we’ll be exploring further in an upcoming tutorial. In GenExpr, function arguments correspond to operator inlets and function return values correspond to outlets. Attributes are set using a 

 style argument, and their listing follows that of the operator inlets.

 patcher we just looked at and add just a little bit more logic to the patch to do buffer playback - nothing fancy, we’ll just read one sample after another for the length of our buffer operator, and then start over. We’ll use 2 attributes to the 

 attribute to handle trying to read from buffer operators with unknown channel counts (see 

 for beginners tutorial 4 for more on this), and we’ll even use the 

 operator to explicitly set the number of channels we’ll be reading.

We can use the Code Tab to see how GenExpr represents those two attributes - just select the 

 operator, open the Code Tab, and look at the highlighted text.

 attribute is set by putting the name of the mode in quotations, and 

I hope you’re getting the basic idea that you can use 

 patcher window’s Code Tab to explore and broaden your understanding of GenExpr by looking at patches you already have.

Using what we now know, let’s create a version of our simple buffer playback using a codebox:

While we’re at it, let’s take what we now know and take the random segment playback patch from back in tutorial 4, and see if we can create a codebox version of it.

 patcher includes a minor change to the original patch - I decided I was always going to be working with stereo files, so I used the same 

 attributes that our last example includes).

 operator portions should be looking pretty familiar to you by now - the parts of this patch we’ll want to take a look at have to do with the logic we use to generate a random number to function as the segment we want to play, as well as the way we calculate the proper count for the segment length. Here’s what the codebox version of this patch looks like:

So - how did I know how to write the GenExpr code for the random segment stuff, anyway?

When it came to naming the variables I was going to use, I went with some renaming to give me variable names that told me what was going on (segments, segment_length, buffer_length, and so on. When it came to the 

 operator’s output, I repeated what I’ve been doing throughout the section - I changed the variable names to stuff that made more sense - instead of

counter_6, counter_7, counter_8 = counter(int_3, eq_5, dim_4);

current_count, carry_flag, carry_count - counter(1, in1, segment_length);

 patcher and found the lines that corresponded to that part of the program:

I noticed the fact that several of those lines of code just set a variable in one line that was immediately referenced in the next line - 

 and the value of the carry flag output of the 

 operator (it’s called counter_8 here - you can see it referenced in the line right above the highlighted stuff). The 

), and so on. So what I did was to fold all those assignments up -

random_start = latch(noise(), carry_flag);

Neat trick, huh? In turn, At each step along the way, I could remove the previous line I’d folded in.

I used the random_start variable and folded it into next few lines of code to give me another variable I could easily understand - the number of the sample to start playing my segment.

segment_2_play = trunc( scale(random_start, -1., 1., 0, in2, 1) );

I’m sure that other people have their own techniques for getting used to working with GenExpr. This is how I got my feet wet. Now, it’s time to look at 

As we discussed way back in our very first tutorial, your 

 patcher is working on one sample at a time, and data is always synchronous. That means that things like feedback really aren’t possible (i.e. you can’t read and write a single sample from a 

The Gen world provides a special operator called 

 to let us create feedback loops and perform other useful operations. The 

 operator acts like a single sample delay - it stashes its last value and outputs it at the start of the next sample’s worth of calculations.

That’s an incredibly useful thing to be able to do, but how can we do that when using a 

 operator? To see how it’s done, let’s take a real-world example from the Gen examples folder – the Lorenz attractor example included with the gen~.chaos.maxpat patch. It’s a good example of the use of the 

 operator, because chaotic functions do their work by performing 

 calculations – the result of the current sample’s worth of calculations are saved and become what is operated upon during the next sample iteration. Let’s look inside the patch’s 

You’ll notice several parts of the patch that will likely be familiar to you - at the very bottom, we’re multiplying results by a 0. or 1.0 signal to to “freeze” our calculations. You’ll also notice that each of the three separate calculations in the center of the patcher calculate a change in the previous value of the 

 parameters. When the input signal from the 

 calculations are incremented by a fixed amount, and then added to the output of the three 

 operators at the top of the patch, with the result being stored in the same 

 operators. What you’re seeing, of course, is a single-sample delay - the sum of the 

, and dz + dt calculations are added with the previous sample’s worth of calculation, and then stored to be reused. That’s a classic example of the 

So, how might we perform this kind of calculation inside of a codebox operator? Let’s see if the Code Tab in the patcher window can give us any insight into using the 

 operators, right up at the top of the codebox, along with the 

 operators are all initialized (to the value specified in parentheses), and that the listing of them precedes the calculation portions of the GenExpr version of our patch. That’s because we want to make use of the values of those variables globally.

Compare that original Lorenz attractor patcher with a codebox version of the very same patch:

 operators are listed along with the parameters (the 

 operator to provide single sample delays which are recursively recalculated

By the way - you might also want to take a look at the GenExpr code that is used to update the histories. Let’s look at one of those lines of code:

It’s an interesting challenge to parse, but you’ll probably recognize its component parts, with a little study: the 

 (which is the 0. Or 1.0 signal at inlet 1 that is used to pass or freeze the calculation). There are two possible outputs following the name of the operator, separated by a colon. The first one (

) is the value that will be assigned to the variable 

 is any non-zero value (on), and the previous 

 value will be assigned if newval is set to 0. The result of that line is what is stored in the 

 operator, waiting for the next sample’s worth of calculation.

 procedural coding to achieve a similar purpose. Perhaps that’d be an interesting assignment to yourself to try.

There are three ways to store and access data beyond the single sample you’re currently doing calculations on inside your 

 operator, which functions as a single-sample delay. It’s useful for any situations where you need access to something that you dealt with during your last sample’s worth of calculations inside your 

 operator lets you work with multichannel MSP buffer~ data that you can store information to and fetch information from. The 

 operator always references an external named MSP 

 operator takes a first argument that specifies the name by which to refer to the buffer in other Gen objects in our 

 operator to access samples using the name of a 

 patcher can be a different one than the name of the MSP external in your parent patch. If you want to do that, you can provide an optional second argument to the operator.

 operator has two outlets – one that “broadcasts” the length of the buffer with every sample’s worth of calculations, and a second outlet that broadcasts the number of channels.

 stores an array of sample data internally to the gen patcher. Like the 

 operator, it takes a first argument that specifies the name by which to refer to the data using other gen operators. Like the 

 operator also broadcasts its length and number of channels from its left and right outlets.

Working with buffer and data operators in the Codebox

The rules for declaring and accessing buffer and data operators in a codebox operator are simple:

You’ll need to include information about any 

 operators you’re going to work with in your 

 object at the beginning of the codebox - the same place as you do with 

 operators. They merely need to precede the definition of variables or calculations. While you can also add 

 operator, including that information in your 

 operator this way. If you are referencing an external MSP 

You declare a data operator with the size (in samples) of the data and number of channels (optional) as follows:

There are two ways to acquire and use information about your 

 operators “broadcast” the number of samples in the 

 operator, and the right outlet does the same with the number of channels for the operator.

You can also use GenExpr equivalent of the 

 operators to get that same data. Here’s an example of what that looks like in GenExpr

That’s really all there is to it. Let’s look at a few examples.

In Tutorial 4, we looked at a “Fripp in the box” patcher that recorded incoming data into a data object for up to 16 seconds of recirculating looping. Here’s the 

 operator-based version of the patcher (with a nifty little addition):

To jog your memory a little, here’s a rundown of what’s going on:

 operator to serve as the read/write area for the looper, with a maximum time set to 16 seconds.. This patch includes a nice modification that our original patch didn't have - one that we can make use of that will allow us to use it with 

 operator. We can specify the length of our data operator using an expression as an argument (

Welcome to our next installment of our gen~ anxiety reduction regimen. Last time out, we talked about the codebox operator - what it does, how it works, how you can use it to create your own functions and - should you so desire - add some procedural coding to your gen~ patching life.

All the tutorials in this series: Part 1, Part 2, Part 3, Part 4, Part 5, Part 6, Part 7  
Follow-up video tutorials: Working with Abstractions, Debugging and Signal-Rate Processing

We’ve suggested that the Code Tab in your patcher window is a great place to acquaint yourself with GenExpr - the language of the codebox. This tutorial is intended to help you leverage what you already know about Gen operators, operator outlets and attributes, and provide an introduction to how you can work with history, buffer, and data operators in the GenExpr language. It’s time for some thinking inside the box.

Before we go on to consider the history, buffer, and data operators, I’d like to touch on two topics that we’ll encounter when doing buffer/data operator reads and writes:

I often use the counter operator to count through samples in a buffer. So far, we’ve been working with GenExpr and operators that output a single value. What happens when GenExpr specifies the output of an operator when there’s more than one outlet to the original operator?

When it comes to reading buffer data and other gen~ patching, we’ve often made use of operator attributes. How do we do that in gen~ patching inside of a codebox operator?

By now, you’ve probably gotten used to using the patcher window’s Code Tab to see what the GenExpr version of the Gen operators you work with are, whether it’s to see what the default values associated with an operator are… 

You will have noticed that the order in which parameters in GenExpr are listed corresponds to the inlets in the Gen operator of the same name, and are conveniently in left-to-right order. You’ve also noticed that you can assign a variable name to the outlet of one of those GenExpr-format operators, too. But how does GenExpr deal with operators that have more than one outlet? 

To explore that, we’ll take a really simple example taken from an earlier gen~ for Beginners tutorial – an example of the counter operator. The following gen~ patcher that includes a counter operator with all of its inlets specified using constants. The counter counts to 44100 by ones, and is always on (that’s what the zero constant in the second inlet of the counter operator does). To take a look at the GenExpr code related to the counter operator, we can select it and take a look at the Code Tab, where the GenExpr code will be highlighted:

Multiple outlets from an operator are represented in GenExpr as a list of variables that appear to the left of the code associated with the operator (in this example, they’re counter_4, counter_5, and counter_6. As with the input values to the operator (the stuff inside of the counter operator’s parentheses), the outlets are also listed in the same order as the outlets, from left to right. Those are the variables you use inside of your codebox.

When you’re patching using operators, the GenExpr code you see in the Code Tab is automatically generated as you patch, and those automatically generated variable names are not very memorable. Since you know what the counter operator output is (the current count, the carry flag, and the carry count), you can label those variables yourself in a way that’s more intuitive. Here’s a codebox version of the same patch that names things a bit more clearly:

The example patch makes use of and outputs all of the output from the counter operator, but it may be that you only care about a single output (say, the count itself). When your GenExpr function returns multiple values but assigns to only one value, the unused return values will be ignored, and GenExpr compiler gets rid of most calculations that aren’t necessary automatically.

We’ve used attributes used to clip input and to assign minimum and maximum values.

When dealing with the peek operator to grab samples from a buffer, we’ve used attributes to specify that we wanted to interpolate the value we get, and also to set the behavior when addressing multichannel buffer objects.

There are a number of Gen patchers that use operators - in particular, the operators used to read from and write to buffer or data objects offer a number of options to you, which we’ll be exploring further in an upcoming tutorial. In GenExpr, function arguments correspond to operator inlets and function return values correspond to outlets. Attributes are set using a key/value style argument, and their listing follows that of the operator inlets. 

As an example, let’s take the simple counter operator-based gen~ patcher we just looked at and add just a little bit more logic to the patch to do buffer playback - nothing fancy, we’ll just read one sample after another for the length of our buffer operator, and then start over. We’ll use 2 attributes to the peek operator: the @channelmode attribute to handle trying to read from buffer operators with unknown channel counts (see gen~ for beginners tutorial 4 for more on this), and we’ll even use the @channels operator to explicitly set the number of channels we’ll be reading.

We can use the Code Tab to see how GenExpr represents those two attributes - just select the peek operator, open the Code Tab, and look at the highlighted text.

The @channelmode attribute is set by putting the name of the mode in quotations, and @channels attribute just uses a number.

I hope you’re getting the basic idea that you can use gen~ patcher window’s Code Tab to explore and broaden your understanding of GenExpr by looking at patches you already have.

While we’re at it, let’s take what we now know and take the random segment playback patch from back in tutorial 4, and see if we can create a codebox version of it. 

Note: This gen~ patcher includes a minor change to the original patch - I decided I was always going to be working with stereo files, so I used the same @channelmode and @channels attributes that our last example includes).

The counter operator and peek operator portions should be looking pretty familiar to you by now - the parts of this patch we’ll want to take a look at have to do with the logic we use to generate a random number to function as the segment we want to play, as well as the way we calculate the proper count for the segment length. Here’s what the codebox version of this patch looks like:

So - how did I know how to write the GenExpr code for the random segment stuff, anyway? 

When it came to naming the variables I was going to use, I went with some renaming to give me variable names that told me what was going on (segments, segment_length, buffer_length, and so on. When it came to the counter operator’s output, I repeated what I’ve been doing throughout the section - I changed the variable names to stuff that made more sense - instead of 

I looked at the Code Tab in my original gen~ patcher and found the lines that corresponded to that part of the program:

I noticed the fact that several of those lines of code just set a variable in one line that was immediately referenced in the next line - noise_10 was just the value returned by the noise operator. Similarly, latch_11 was just the output of the latch operator, which made use of noise_10 and the value of the carry flag output of the counter operator (it’s called counter_8 here - you can see it referenced in the line right above the highlighted stuff). The latch_11 stuff is used for scaling (scale_12), and so on. So what I did was to fold all those assignments up - 

I replaced noise_10 in the next line of code with noise().

So what’s now called latch_11 is now a variable I can rename random_start. 

Neat trick, huh? In turn, At each step along the way, I could remove the previous line I’d folded in. 

I’m sure that other people have their own techniques for getting used to working with GenExpr. This is how I got my feet wet. Now, it’s time to look at history, buffer, and data operators in the codebox.

As we discussed way back in our very first tutorial, your gen~ patcher is working on one sample at a time, and data is always synchronous. That means that things like feedback really aren’t possible (i.e. you can’t read and write a single sample from a buffer operator at the same time). 

The Gen world provides a special operator called history to let us create feedback loops and perform other useful operations. The history operator acts like a single sample delay - it stashes its last value and outputs it at the start of the next sample’s worth of calculations. 

That’s an incredibly useful thing to be able to do, but how can we do that when using a codebox operator? To see how it’s done, let’s take a real-world example from the Gen examples folder – the Lorenz attractor example included with the gen~.chaos.maxpat patch. It’s a good example of the use of the history operator, because chaotic functions do their work by performing recursive calculations – the result of the current sample’s worth of calculations are saved and become what is operated upon during the next sample iteration. Let’s look inside the patch’s gen~ object:


You’ll notice several parts of the patch that will likely be familiar to you - at the very bottom, we’re multiplying results by a 0. or 1.0 signal to to “freeze” our calculations. You’ll also notice that each of the three separate calculations in the center of the patcher calculate a change in the previous value of the a, b, and c parameters. When the input signal from the in 1 operator is a value of 1, The a, b, and c calculations are incremented by a fixed amount, and then added to the output of the three history operators at the top of the patch, with the result being stored in the same history operators. What you’re seeing, of course, is a single-sample delay - the sum of the dx + dt, dy + dt, and dz + dt calculations are added with the previous sample’s worth of calculation, and then stored to be reused. That’s a classic example of the history operator in action.

So, how might we perform this kind of calculation inside of a codebox operator? Let’s see if the Code Tab in the patcher window can give us any insight into using the history operator:

There are the three History operators, right up at the top of the codebox, along with the Param operators. You’ll notice that the History operators are all initialized (to the value specified in parentheses), and that the listing of them precedes the calculation portions of the GenExpr version of our patch. That’s because we want to make use of the values of those variables globally.

Again - notice that the History operators are listed along with the parameters (the Param declarations), and that both the History and Param declarations precede any calculations. 

That’s how the history operator can be used in a codebox operator to provide single sample delays which are recursively recalculated

It’s an interesting challenge to parse, but you’ll probably recognize its component parts, with a little study: the ? operator is used to test the variable newval (which is the 0. Or 1.0 signal at inlet 1 that is used to pass or freeze the calculation). There are two possible outputs following the name of the operator, separated by a colon. The first one (x + dx * dt) is the value that will be assigned to the variable x (on the left of the line) if newval is any non-zero value (on), and the previous x value will be assigned if newval is set to 0. The result of that line is what is stored in the history operator, waiting for the next sample’s worth of calculation.

Of course, you could also use if… else procedural coding to achieve a similar purpose. Perhaps that’d be an interesting assignment to yourself to try.

There are three ways to store and access data beyond the single sample you’re currently doing calculations on inside your gen~ object:

We’ve just discussed one of them, the history operator, which functions as a single-sample delay. It’s useful for any situations where you need access to something that you dealt with during your last sample’s worth of calculations inside your gen~ patcher.

The buffer operator lets you work with multichannel MSP buffer~ data that you can store information to and fetch information from. The buffer operator always references an external named MSP buffer~ object - the buffer operator takes a first argument that specifies the name by which to refer to the buffer in other Gen objects in our gen~ patcher (e.g. you can tell a peek operator to access samples using the name of a buffer operator).

The name you give the buffer operator inside of your codebox  object or gen~ patcher can be a different one than the name of the MSP external in your parent patch. If you want to do that, you can provide an optional second argument to the operator.

Once instantiated, the buffer operator has two outlets – one that “broadcasts” the length of the buffer with every sample’s worth of calculations, and a second outlet that broadcasts the number of channels.

Rather than referring to external data,  data operator in gen~ stores an array of sample data internally to the gen patcher. Like the buffer operator, it takes a first argument that specifies the name by which to refer to the data using other gen operators. Like the buffer operator, the data operator also broadcasts its length and number of channels from its left and right outlets.

However, the buffer and data operators differ in some important ways

The data contained in a buffer operator is 32-bit data, while the contents of a data operator consists of 64-bit data.

The buffer operator only refers to data that is defined within an MSP  buffer~ object, and can be modified and resized within normal Max patchers. The data operator meanwhile is local to gen~, and takes one argument to specify its length in samples, and a second optional argument to define the number of channels. Once specified, the length of the data operator cannot be changed.

You’ll need to include information about any buffer or data operators you’re going to work with in your codebox object at the beginning of the codebox - the same place as you do with history operators. They merely need to precede the definition of variables or calculations. While you can also add buffer or data operators in your gen~ patcher and then refer to them in the codebox operator, including that information in your codebox object is a good habit to develop

You declare a buffer operator this way. If you are referencing an external MSP buffer~ object, you can declare it as follows:

There are two ways to acquire and use information about your buffer or data operator.

The left outlet of the buffer and data operators “broadcast” the number of samples in the buffer or data operator, and the right outlet does the same with the number of channels for the operator.

You can also use GenExpr equivalent of the dim and the channels operators to get that same data. Here’s an example of what that looks like in GenExpr

In Tutorial 4, we looked at a “Fripp in the box” patcher that  recorded incoming data into a data object for up to 16 seconds of recirculating looping. Here’s the gen~ operator-based version of the patcher (with a nifty little addition):

gen6_tutorial_patches.zip

Screen Shot 2018-05-15 at 9.55.32 AM.png

This tutorial is intended to help you leverage what you already know about Gen operators, operator outlets and attributes, and provide an introduction to how you can work with history, buffer, and data operators in the GenExpr language.

gen~-for-beginners-part-6-thinking-inside-the-codebox

Thanks for the tutorial! In your example "two_loopers", the version with code box doesn't use history to store the counter, but the graphical objects version does. I wonder why the code box version can work without using history operator.

I guess I know why now... because when written in the code box, we can make sure poke is executed at the very end of the whole process, but in the patch mode we can't (I tried removing the history object and then I noticed that poke is called before peek, so the future delaying signal is written to the data (loopieness) and then used for the current sample).

I guess I know why now... because when written in the code box, we can make sure  poke is executed at the very end of the whole process, but in the patch mode we can't (I tried removing the history object and then I noticed that poke is called before peek, so the future delaying signal is written to the data (loopieness)  and then used for the current sample).

gen~ for Beginners, Part 6: Thinking Inside the Codebox