HelpSource/Classes/Pspawn.schelp

   1 class:: Pspawn
   2 summary:: Spawns sub-patterns based on parameters in an event pattern
   3 related:: Classes/Pspawner
   4 categories:: Streams-Patterns-Events>Patterns>Parallel
   5
   6 description::
   7
   8 Pspawn is a pattern-based version of link::Classes/Pspawner::. Where Pspawner uses a Routine-style function to determine when and how to spawn child patterns into the result stream, Pspawn uses an event pattern to determine the actions to take.
   9
  10 Recommended to read the link::Classes/Pspawner:: help file to become familiar with pattern spawning capabilities.
  11
  12 note::
  13 Important: There are two kinds of events involved in Pspawn:
  14
  15 definitionList::
  16 ## strong::parent:: events
  17 || which specify the pattern to embed, how to embed it (in parallel or sequence), and how long to wait until the next action;
  18 ## strong::child:: events
  19 || which produce the resulting notes (or take other actions on the server).
  20 ::
  21 ::
  22
  23 Of these, only the child events are returned to the event stream player during play. The parent events are used strictly internally to control spawning behavior. The parent and child event streams do not mix together. Thus pattern composition ( link::Classes/Pchain:: ) and parallelization ( link::Classes/Ppar:: ) may be used without special handling. It is up to the user to be aware of whether the parent or child stream should be subject to further manipulation, and put that manipulation in the right place. If it is to affect the child stream, it should enclose the entire Pspawn; for the parent stream, it should be inside Pspawn. (See the link::#Examples:: below.)
  24
  25 Pspawn uses the following items in the parent pattern:
  26 definitionList::
  27 ## method
  28 || The action to call on the spawner object. Currently supported: wait, seq, par, suspendAll.
  29 ## delta
  30 || How long to wait until the next action.
  31 ## dict
  32 || If 'pattern' is given as a symbol (see below), this is the dictionary in which the pattern will be looked up. If not specified, the link::Classes/Pdef:: collection will be used.
  33 ## pattern
  34 || If 'method' is seq or par, this is a pattern or function to be embedded, according to the following rules.
  35 ::
  36
  37 table::
  38 ## strong::'pattern' in the event:: || strong::Resulting behavior::
  39 ## A link::Classes/Function:: : code:: { ... } :: || The function should return a pattern; this pattern is spawned.
  40 ## A link::Classes/Ref:: to a pattern: code::`Pbind(...):: || The referenced pattern is spawned.
  41 ## A link::Classes/Symbol:: : code::\scaleUp:: || The pattern is looked up in the event's 'dict'.
  42 ::
  43
  44 subsection::Using references to protect patterns from embedding
  45
  46 Normally, when a pattern appears inside another pattern, the subpattern is embedded in the main output stream. It is not visible to the outside world as a pattern in itself; only its values appear.
  47
  48 code::
  49 Pseq([Pwhite(0, 9, 5), Pwhite(10, 19, 5)], 1).asStream.all;
  50 ::
  51
  52 When using Pspawn, a sub pattern must be returned directly into the event. To accomplish this, every such pattern should be wrapped in a link::Classes/Ref:: :
  53
  54 code::
  55 Pseq([`Pwhite(0, 9, 5), `Pwhite(10, 19, 5)], 1).asStream.all;
  56 ::
  57
  58 Hint: link::Classes/Pfunc:: is another good way to wrap patterns, because it simply returns its result values without further embedding. See the first example.
  59
  60 ClassMethods::
  61
  62 method::new
  63
  64 argument::pattern
  65 An event pattern (typically link::Classes/Pbind::) encapsulating the desired spawning behavior. Parameters in this event are described below.
  66
  67 argument::spawnProtoEvent
  68 The event prototype against which the pattern is evaluated. Good for giving default values that should apply to all spawning (parent) events.
  69
  70 Examples::
  71
  72 code::
  73 // Play overlapping major scales, up and down
  74 (
  75 p = Pspawn(Pbind(
  76                 // Pbind returned by Pfunc is not embedded, just placed in the event
  77                 // So, it can be spawned
  78         \pattern, Pfunc { Pbind(\degree, Pseries(rrand(0, 10), #[-1, 1].choose, rrand(4, 10)), \dur, 0.125) },
  79         \delta, Pwhite(1, 5, inf) * 0.125,
  80         \method, \par
  81 )).play;
  82 )
  83
  84 p.stop;
  85
  86
  87 // Same, using a dictionary of patterns, changing dur rhythm also
  88 (
  89 var     patternChoices = (
  90         up: { Pbind(\degree, Pseries(rrand(-4, 5), 1, rrand(4, 10)), \dur, 0.125) },
  91         down: { Pbind(\degree, Pseries(rrand(4, 11), -1, rrand(4, 10)), \dur, 0.125 * 4/3) }
  92 );
  93
  94 p = Pspawn(Pbind(
  95         \pattern, Prand([\up, \down], inf),
  96         \delta, Pwhite(1, 5, inf) * 0.125,
  97         \method, \par
  98 ), (dict: patternChoices)).play;
  99 )
 100
 101 p.stop;
 102
 103
 104 // Using pattern composition (perhaps gratuitously) to build the parent events
 105 (
 106 var     patternChoices = (
 107         up: { Pbind(\degree, Pseries(rrand(-4, 5), 1, rrand(4, 10)), \dur, 0.125) },
 108         down: { Pbind(\degree, Pseries(rrand(4, 11), -1, rrand(4, 10)), \dur, 0.125 * 4/3) }
 109 );
 110
 111 p = Pspawn(Pchain(
 112         Pbind(
 113                 \pattern, Prand([\up, \down], inf),
 114                 \method, \par
 115         ),
 116         Pbind(
 117                 \delta, Pwhite(1, 5, inf) * 0.125
 118         )
 119 ), (dict: patternChoices)).play;
 120 )
 121
 122 p.stop;
 123
 124
 125 // Play parallel scales in the left channel and sequentially-arranged scales in the right
 126 // This means parallelizing (Ppar) the child streams; thus Ppar surrounds a pair of Pspawns
 127
 128 // Handling of \pan is interesting: \pan needs to be a property of the patternChoices items
 129 // It is NOT a property of the spawning events
 130 // To reuse patternChoices, the Pspawns wrap the base patterns in a Pbindf, which adds new values
 131 (
 132 var     patternChoices = (
 133         up: { Pbind(\degree, Pseries(rrand(-4, 5), 1, rrand(4, 10)), \dur, 0.125) },
 134         down: { Pbind(\degree, Pseries(rrand(4, 11), -1, rrand(4, 10)), \dur, 0.125 * 4/3) }
 135 );
 136
 137 p = Ppar([
 138         Pspawn(Pbind(
 139                         // intermediate value
 140                 \patternKey, Prand([\up, \down], inf),
 141                         // pattern is selected and pan applied here
 142                 \pattern, Pfunc { |ev| Pbindf(ev.dict[ev.patternKey].value, \pan, -1) },
 143                 \delta, Pwhite(1, 5, inf) * 0.125,
 144                 \method, \par
 145         ), (dict: patternChoices)),
 146         Pspawn(Pbind(
 147                 \patternKey, Prand([\up, \down], inf),
 148                 \pattern, Pfunc { |ev| Pbindf(ev.dict[ev.patternKey].value, \pan, 1) },
 149                 \delta, Pwhite(1, 5, inf) * 0.125,
 150                 \method, \seq
 151         ), (dict: patternChoices)),
 152 ]).play;
 153 )
 154
 155 p.stop;
 156 ::