Help/Scheduling/Quant.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <meta http-equiv="Content-Style-Type" content="text/css">
   6 <title></title>
   7 <meta name="Generator" content="Cocoa HTML Writer">
   8 <meta name="CocoaVersion" content="824.44">
   9 <style type="text/css">
  10 p.p1 {margin: 0.0px 0.0px 0.0px 0.0px; font: 18.0px Helvetica}
  11 p.p2 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px}
  12 p.p3 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica}
  13 p.p4 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #000000}
  14 p.p5 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #bf0000}
  15 p.p6 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #000000; min-height: 12.0px}
  16 span.s1 {color: #0029f3}
  17 span.s2 {color: #0000bf}
  18 span.s3 {color: #007300}
  19 span.s4 {color: #606060}
  20 span.Apple-tab-span {white-space:pre}
  21 </style>
  22 </head>
  23 <body>
  24 <p class="p1"><b>Quant</b></p>
  25 <p class="p2"><br></p>
  26 <p class="p3"><b>Superclass: Object</b></p>
  27 <p class="p2"><br></p>
  28 <p class="p3">Represents the standard scheduling model for Routines, Tasks and Patterns. A Quant object stores the parameters needed to calculate the precise time when a Routine/Task/Pattern will start playing on a specified TempoClock.</p>
  29 <p class="p2"><br></p>
  30 <p class="p3">The standard scheduling model uses quant and phase to locate the starting time. They are evaluated with reference to the TempoClock's baseBarBeat, which is normally zero but is updated when you change the clock's meter using the clock's setMeterAtBeat method. Thus scheduling still makes sense even after a meter change. See the <a href="TempoClock.html"><span class="s1">TempoClock</span></a> help file for details on its representation of time.</p>
  31 <p class="p2"><br></p>
  32 <p class="p3">quant: Quantization granularity. The routine will begin on the next integer multiple of this number after the baseBarBeat. If negative, it indicates the number of bars in the future to schedule (where the bar length is taken from the clock's beatsPerBar variable).</p>
  33 <p class="p2"><br></p>
  34 <p class="p3">phase: An offset to push the scheduling time into the middle of the bar. +1 is one beat later, -1 is one beat earlier. A negative phase is legal, but it might result in a scheduling time that is later than the current time, in which case scheduling will be incorrect. It's your responsibility to take this into account.</p>
  35 <p class="p2"><br></p>
  36 <p class="p3">timingOffset: For use with patterns only -- this enables patterns to run slightly ahead of their sounding time on the clock, giving you control over the order in which threads execute.</p>
  37 <p class="p2"><br></p>
  38 <p class="p3"><b>Examples</b></p>
  39 <p class="p2"><br></p>
  40 <p class="p3"><b>quant = 1</b> -- schedule for the next whole beat</p>
  41 <p class="p3"><b>quant = 4, phase = -1</b> -- a one beat pick-up to the next 4/4 barline</p>
  42 <p class="p2"><br></p>
  43 <p class="p3">Suppose the clock's meter was 3/4 for 3 bars (starting at 0). Then:</p>
  44 <p class="p2"><br></p>
  45 <p class="p3"><b>quant = 3, phase = 1</b> -- would schedule for 1, 4, or 7 beats</p>
  46 <p class="p2"><br></p>
  47 <p class="p3">During this time, clock.setMeterAtBeat(4, 9) is executed. Then:</p>
  48 <p class="p2"><br></p>
  49 <p class="p3"><b>quant = 4, phase = 0</b> -- would schedule for 9, 13, 17, 21 etc. beats</p>
  50 <p class="p2"><br></p>
  51 <p class="p3">Every point in time can be precisely identified this way, and it can be related back easily to the Western concept of meter or time signature.</p>
  52 <p class="p2"><br></p>
  53 <p class="p2"><br></p>
  54 <p class="p3"><b>*new(quant, phase, timingOffset)</b></p>
  55 <p class="p2"><br></p>
  56 <p class="p3">Explicitly create an instance of Quant, which may be used and reused. Phase and offset may be nil, in which case they are treated as 0. If quant is nil, it will schedule for the current time exactly.</p>
  57 <p class="p2"><br></p>
  58 <p class="p2"><br></p>
  59 <p class="p3"><b>Automatic instantiation</b></p>
  60 <p class="p2"><br></p>
  61 <p class="p3">Certain objects convert themselves into Quant objects when used with Routine:play, Task:play or Pattern:play.</p>
  62 <p class="p2"><br></p>
  63 <p class="p3"><b>4.0</b> (i.e., SimpleNumber) --&gt; Quant(4.0, nil, nil)</p>
  64 <p class="p3"><b>[4.0, 1.0]</b> (i.e., Array) --&gt; Quant(4.0, 1.0, nil)</p>
  65 <p class="p3"><b>[4.0, 1.0, 0.1]</b> --&gt; Quant(4.0, 1.0, 0.1)</p>
  66 <p class="p3"><b>nil</b> --&gt; Quant(nil, nil, nil)</p>
  67 <p class="p2"><br></p>
  68 <p class="p3">This simplifies the syntax:</p>
  69 <p class="p2"><br></p>
  70 <p class="p3">Routine({ ... }).play(quant: 4.0)<span class="Apple-converted-space">  </span>vs.<span class="Apple-converted-space">  </span>Routine({ ... }).play(quant: Quant(4.0))</p>
  71 <p class="p2"><br></p>
  72 <p class="p2"><br></p>
  73 <p class="p3"><b>Timing offset in Patterns</b></p>
  74 <p class="p2"><br></p>
  75 <p class="p3">In some cases, you might want two patterns that are sounding at the same time to evaluate in a specific order -- for instance, the second pattern might depend upon data calculated by the first. If they are scheduled on the clock for exactly the same time, you have no control over the order of execution: the second pattern might evaluate first, in which case it would be using stale data for the pattern that should have run first.</p>
  76 <p class="p2"><br></p>
  77 <p class="p3">The timing offset is a positive number, usually small, that pushes the scheduling time slightly earlier, guaranteeing that patterns with larger timing offsets will execute earlier than others. The timing offset value is saved in the event prototype, which then delays its messages to the server by exactly that number of beats.</p>
  78 <p class="p2"><br></p>
  79 <p class="p3">Two patterns, scheduled for the same quant and phase but with different timing offsets, should sound exactly together.</p>
  80 <p class="p2"><br></p>
  81 <p class="p4">(</p>
  82 <p class="p5">// timing offset = 0</p>
  83 <p class="p4">p = <span class="s2">Pbind</span>(<span class="s3">\freq</span>, 440, <span class="s3">\pan</span>, -1, <span class="s3">\delta</span>, 1.0, <span class="s3">\sustain</span>, 0.1).play(quant: [2, 0, 0]);</p>
  84 <p class="p5">// timing offest = 0.1</p>
  85 <p class="p4">q = <span class="s2">Pbind</span>(<span class="s3">\freq</span>, 880, <span class="s3">\pan</span>, 1, <span class="s3">\delta</span>, 0.5, <span class="s3">\sustain</span>, 0.1).play(quant: [2, 0, 0.1]);</p>
  86 <p class="p4">)</p>
  87 <p class="p6"><br></p>
  88 <p class="p5">// p's nextBeat is x.0 - q's is x.4 or x.9 (e.g., halves of a beat minus 0.1)</p>
  89 <p class="p4">[p.nextBeat, q.nextBeat]</p>
  90 <p class="p6"><br></p>
  91 <p class="p4">p.stop; q.stop;</p>
  92 <p class="p2"><br></p>
  93 <p class="p2"><br></p>
  94 <p class="p3"><b>Extensibility: adding custom scheduling models</b></p>
  95 <p class="p2"><br></p>
  96 <p class="p3">While the standard scheduling model should be sufficient for most uses, the point of using an object to encapsulate scheduling details is that you can use a different object to schedule Routines or Patterns differently. (Users are not forced to use the standard scheduling model in every case.)</p>
  97 <p class="p2"><br></p>
  98 <p class="p3">If it's a kind of scheduling you expect to use often, you can create a subclass of Quant that implements the following methods:</p>
  99 <p class="p2"><br></p>
 100 <p class="p3"><b>*new(...)</b>: create a new instance, with whatever arguments you need</p>
 101 <p class="p2"><br></p>
 102 <p class="p3"><b>nextTimeOnGrid(clock)</b>: calculate the exact beat number on the clock</p>
 103 <p class="p2"><br></p>
 104 <p class="p3">Your class should also have methods asQuant, offset and offset_. If your class is a subclass of Quant, it will inherit those methods automatically.</p>
 105 <p class="p2"><br></p>
 106 <p class="p3">You can also use an Event for one shot scheduling. It should at least have an entry for nextTimeOnGrid, which will usually be a function taking the arguments "self" and "clock" that returns the absolute scheduling time. Any other values needed for that calculation should also be present in the Event.</p>
 107 <p class="p2"><br></p>
 108 <p class="p5">// schedule for a random number of beats after the next integer</p>
 109 <p class="p4"><span class="s2">Pfuncn</span>({ <span class="s2">thisThread</span>.clock.beats.debug(<span class="s4">"scheduled for"</span>); <span class="s2">nil</span> }, 1)</p>
 110 <p class="p4"><span class="Apple-tab-span">     </span>.play(quant: (</p>
 111 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>nextTimeOnGrid: { <span class="s2">|self, clock|</span></p>
 112 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>clock.beats.roundUp(1).debug(<span class="s4">"clock beats"</span>) + rrand(self.lo, self.hi).debug(<span class="s4">"rand"</span>)</p>
 113 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>},</p>
 114 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>lo: 0, hi: 4</p>
 115 <p class="p4"><span class="Apple-tab-span">     </span>));</p>
 116 <p class="p2"><br></p>
 117 </body>
 118 </html>