HelpSource/Tutorials/Mark_Polishook_tutorial/15_Groups.schelp

   1 title:: 15_Groups
   2 summary:: Mark Polishook tutorial
   3 categories:: Tutorials>Mark_Polishook_tutorial
   4 related:: Tutorials/Mark_Polishook_tutorial/00_Introductory_tutorial
   5
   6 The simplest synthesis processes use a single ugen.
   7
   8 code::
   9 { Saw.ar(500, 0.1) }.scope;
  10 ::
  11
  12 or
  13
  14 code::
  15 { Formlet.ar(Saw.ar(22), 400, 0.01, 0.11, 0.022) }.scope
  16 ::
  17
  18 Most of the SuperCollider help documents for the UGens show other such examples.
  19
  20 link::Browse#UGens::
  21
  22 ////////////////////////////////////////////////////////////////////////////////////////////////////
  23
  24 Many synthesis processes, because they use more than a few ugens, are often best divided into component parts. This can make code modular, resusable, and easier to read.
  25
  26 The link::Classes/Group:: class, which is the means to specify a collection of nodes, provides a mechanism through which to control several synths at once.
  27
  28 section::Groups are linked lists
  29
  30 The important technical feature of groups is that the nodes they contain are items in a linked list. A linked list is a data structure that makes it easy to order and reorder nodes. The first item in a linked list is the "head" and the last item is the "tail."
  31
  32 Groups, through their head and tail mechanisms, allow synths to be placed in order so one synth verifiably executes before another, eg, the head synth runs before the tail synth. The ability to order synths is essential when sending source audio through an effect, such as a reverb or a filter.
  33
  34 Another feature of groups is they allow synths to receive messages from a single point of control, eg, one message to the group goes to all of nodes that belong to the group.
  35
  36 section::Nodes, linked lists, trees
  37
  38 See the link::Reference/Server-Architecture:: document for a definition of a node in SuperCollider or look to the Wikipedia for a general discussion of nodes, linked lists, and trees.
  39
  40 list::
  41 ## http://en.wikipedia.org/wiki/Node
  42 ## http://en.wikipedia.org/wiki/Linked_list
  43 ## http://en.wikipedia.org/wiki/Tree_data_structure
  44 ::
  45
  46 section::RootNode and default_group
  47
  48 By default, the localhost and internal servers each boot with two predefined groups: the link::Classes/RootNode:: and the link::Reference/default_group:: (see their help files). To see this, start the localhost server and then evaluate
  49
  50 code::
  51 s.queryAllNodes;
  52 ::
  53
  54 The next two lines
  55
  56 code::
  57 Group(0)
  58         Group(1)
  59 ::
  60
  61 will appear in the transcript window.
  62
  63 Group(0) is the rootnode group and Group(1) is the default_group. Group(1) is indented to show that it branches from Group(0).
  64
  65 ////////////////////////////////////////////////////////////////////////////////////////////////////
  66
  67 New synths are attached by default to the head of the default_group.
  68
  69 code::
  70 // 1st, evaluate a synthdef
  71 (
  72 SynthDef("ringModulation", {
  73         Out.ar(
  74                 0,
  75                 Mix.ar(
  76                         SinOsc.ar([440.067, 441.013], 0, 1)
  77                         *
  78                         SinOsc.ar([111, 109], 0, 0.2)
  79                 )
  80         )
  81 }).add;
  82 )
  83
  84 // 2nd, make a synth
  85 (
  86 Synth("ringModulation");
  87 )
  88
  89 // 3rd, tell the server to list its nodes
  90 (
  91 s.queryAllNodes;
  92 )
  93 ::
  94
  95 code::
  96 Group(0)
  97         Group(1)
  98                 Synth 1003
  99 ::
 100
 101 will appear in the transcript window. It shows Group(0) as the rootnode, Group(1) as the branching default_node and Synth 1003 (or some such number) as a leaf attached to the default_node.
 102
 103 code::
 104 Rootnode - Group(0)
 105           |
 106           |
 107 default_node - Group(1)
 108       /
 109      /
 110 Synth 1003
 111 ::
 112
 113 ////////////////////////////////////////////////////////////////////////////////////////////////////
 114
 115 An example with two synths.
 116
 117 code::
 118 // 1st, evaluate a synthdef
 119 (
 120 SynthDef("pitchFromNoise", { arg out = 0;
 121         Out.ar(
 122                 out,
 123                 Resonz.ar(
 124                         WhiteNoise.ar(15),
 125                         LFNoise0.kr(2, 110, 660),
 126                         0.005
 127                 )
 128         )
 129 }).add;
 130 )
 131
 132 // 2nd, make 2 synths
 133 (
 134 Synth("ringModulation");
 135 Synth("pitchFromNoise", [\out, 1]);
 136 )
 137
 138 // 3rd, tell the server to list its nodes
 139 (
 140 s.queryAllNodes;
 141 )
 142 ::
 143
 144 The printout in the transcript window
 145
 146 code::
 147 Group(0)
 148         Group(1)
 149                 Synth 1005
 150                 Synth 1004
 151 ::
 152
 153 shows that Group(0) is the rootnode and Group(1) is the default_node.
 154
 155 Synth 1005 and 1004 (or similar such numbers) are leaves attached to the default_node. Synth 1005 is first in the list because of the way nodes are attached, by default, to the head of a list: Synth 1004, the "ringModulation" synth, was evaluated first and attached to the head of Group(1). Then Synth 1005, the "pitchFromNoise"s synth, was evaluated and placed at the head of the list (in front of Synth 1004).
 156
 157 code::
 158         Rootnode - Group(0)
 159           |
 160           |
 161  default_node - Group(1)
 162       /     \
 163      /       \
 164 Synth 1005  Synth 1004
 165 (head)      (tail)
 166 ::
 167
 168 ////////////////////////////////////////////////////////////////////////////////////////////////////
 169
 170 It's the responsibility of the user to make sure that nodes on the server are ordered properly. For this reason, the two synths below must be evaluated in the order in which they're given - because the first synth is source material for the second synth, a filter that processes its input.
 171
 172 code::
 173 (
 174 SynthDef("firstNode-source", {
 175         Out.ar(
 176                 0,
 177                 Saw.ar([200, 201], 0.05)
 178         )
 179 }).add;
 180
 181 SynthDef("secondNode-filter", {
 182         ReplaceOut.ar(
 183                 0,
 184                 LPF.ar(
 185                         In.ar(0, 2),
 186                         Lag.kr(
 187                                 LFNoise0.kr([4, 4.001], 500, 1000),
 188                                 0.1
 189                         )
 190                 )
 191         )
 192 }).add;
 193 )
 194
 195 // evaluate "secondNode-filter" first
 196 // "firstNode-source" will go at the head of default_node
 197 (
 198 Synth("secondNode-filter");
 199 Synth("firstNode-source");
 200 )
 201
 202 (
 203 s.queryAllNodes;
 204 )
 205 ::
 206
 207 ////////////////////////////////////////////////////////////////////////////////////////////////////
 208
 209 Or, use .head and .tail messages to attach the the nodes to the default_group).
 210
 211 code::
 212 (
 213 Synth.head(s, "firstNode-source");
 214 Synth.tail(s, "secondNode-filter");
 215 )
 216
 217 (
 218 s.queryAllNodes;
 219 )
 220 ::
 221
 222 ////////////////////////////////////////////////////////////////////////////////////////////////////
 223
 224 Or, assign the synths to groups.
 225
 226 code::
 227 (
 228 ~source = Group.head(s);        // attach the group to the head of the default_node
 229 ~effect = Group.tail(s);        // attach the group to the tail of the default_node
 230 )
 231
 232 (
 233 // add the synths to the appropriate groups
 234 Synth.head(~effect, "secondNode-filter");
 235 Synth.head(~source, "firstNode-source");
 236 )
 237 ::
 238
 239 The idea is that the groups are attached first to the default_group in the desired order. The synths can then be evaluated in any order as long as they're attached to the appropriate group.
 240
 241 code::
 242 // run the code to see a diagram of the nodes
 243 (
 244 s.queryAllNodes;
 245 )
 246 ::
 247
 248 code::
 249         Rootnode
 250           |
 251           |
 252  default_node
 253       /\
 254      /  \
 255 Group    Group
 256   |        |
 257   |        |
 258 Synth    Synth
 259 ::
 260
 261 ////////////////////////////////////////////////////////////////////////////////////////////////////
 262
 263 Set a control for all of the synths in a group.
 264
 265 code::
 266 // each of the synthdefs below has a control for amplitude (mul)
 267 (
 268 // build 3 synthdefs and a group
 269 SynthDef("synthNumber1", { arg mul = 0.2;
 270         Out.ar(
 271                 0,
 272                 BrownNoise.ar(mul) * LFNoise0.kr([1, 1.01])
 273         )
 274         }, [0.1]).add;
 275 SynthDef("synthNumber2", { arg mul = 0.2;
 276         Out.ar(
 277                 0,
 278                 WhiteNoise.ar(mul) * LFNoise1.kr([2.99, 3])
 279         )
 280         }, [0.1]).add;
 281 SynthDef("synthNumber3", { arg mul = 0.2;
 282         Out.ar(
 283                 0,
 284                 PinkNoise.ar(mul) * LFNoise2.kr([0.79, 0.67])
 285         )
 286 }, [0.1]).add;
 287 )
 288
 289 (
 290 // make a group
 291 ~myGroup = Group.new;
 292 )
 293
 294 (
 295 // attach 3 synths
 296 Synth.head(~myGroup, "synthNumber1");
 297 Synth.head(~myGroup, "synthNumber2");
 298 Synth.head(~myGroup, "synthNumber3");
 299 )
 300
 301 // set the \mul control of each of the 3 synths in the group
 302 ~myGroup.set(\mul, 0.01.rrand(0.2))
 303
 304 // execute to see a diagram of the nodes
 305 (
 306 s.queryAllNodes;
 307 )
 308 ::
 309
 310 ////////////////////////////////////////////////////////////////////////////////////////////////////
 311
 312 go to link::Tutorials/Mark_Polishook_tutorial/16_Playbuf::