Help/ServerArchitecture/Bus.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="949.54">
   9 <style type="text/css">
  10 p.p1 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica}
  11 p.p2 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; min-height: 12.0px}
  12 p.p3 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px}
  13 p.p4 {margin: 0.0px 0.0px 0.0px 0.0px; font: 14.0px Helvetica}
  14 p.p5 {margin: 0.0px 0.0px 0.0px 0.0px; font: 14.0px Helvetica; min-height: 17.0px}
  15 p.p6 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco}
  16 p.p7 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #0020b2}
  17 p.p8 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #bf0000}
  18 p.p9 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #007300}
  19 p.p10 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #606060}
  20 span.s1 {font: 18.0px Helvetica}
  21 span.s2 {color: #0020b2}
  22 span.s3 {color: #000000}
  23 span.s4 {color: #426e1c}
  24 span.s5 {color: #0000bf}
  25 span.s6 {color: #007300}
  26 span.s7 {color: #606060}
  27 span.Apple-tab-span {white-space:pre}
  28 </style>
  29 </head>
  30 <body>
  31 <p class="p1"><span class="s1"><b>Bus<span class="Apple-tab-span">      </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span></b></span><b>representation of a bus on the server</b></p>
  32 <p class="p2"><br></p>
  33 <p class="p1">The clientside representation of an audio or control bus on a server.<span class="Apple-converted-space">  </span>Encapsulates all the OSC messages a Bus can receive.<span class="Apple-converted-space">  </span>Manages allocation and deallocation of bus indices so that you don't need to worry about conflicts. The number of control busses, audio busses, and input and output busses is fixed and cannot be changed after the server has been booted. For more information see <a href="ClientVsServer.html"><span class="s2">ClientVsServer</span></a> and <a href="Server-Architecture.html"><span class="s2">Server-Architecture</span></a>.</p>
  34 <p class="p2"><br></p>
  35 <p class="p1">Note that using the <b>Bus</b> class to allocate a multichannel bus does not 'create' a multichannel bus, but rather simply reserves a series of adjacent bus indices with the bus' <a href="Server.html"><span class="s2">Server</span></a> object's bus allocators. abus.index simply returns the first of those indices. When using a Bus with an <a href="../UGens/InOut/In.html"><span class="s2">In</span></a> or <a href="../UGens/InOut/Out.html"><span class="s2">Out</span></a> ugen there is nothing to stop you from reading to or writing from a larger range, or from hardcoding to a bus that has been allocated. You are responsible for making sure that the number of channels match and that there are no conflicts.</p>
  36 <p class="p3"><br></p>
  37 <p class="p1">Bus objects should not be created or modified within a <a href="SynthDef.html"><span class="s2">SynthDef</span></a>.</p>
  38 <p class="p3"><br></p>
  39 <p class="p1"><b>Note:</b> The lowest <i>n</i> bus indices are reserved for hardware output and input, where <i>n</i> = server.options.numOutputBusChannels + server.options.numInputBusChannels.</p>
  40 <p class="p3"><br></p>
  41 <p class="p1">Hardware output buses: 0 .. (numOutputBusChannels - 1)</p>
  42 <p class="p1">Hardware input buses: numOutputBusChannels .. (numOutputBusChannels + numInputBusChannels - 1)</p>
  43 <p class="p1">First private bus index: numOutputBusChannels + numInputBusChannels</p>
  44 <p class="p3"><br></p>
  45 <p class="p1">Do not try to use hardware I/O buses as private buses.</p>
  46 <p class="p3"><br></p>
  47 <p class="p3"><br></p>
  48 <p class="p4"><b>Class Methods</b></p>
  49 <p class="p3"><br></p>
  50 <p class="p1"><b>Bus.control(server, numChannels);</b></p>
  51 <p class="p1"><span class="Apple-tab-span">     </span>Allocate a control bus on the server. <span class="Apple-converted-space"> </span></p>
  52 <p class="p1"><span class="Apple-tab-span">     </span>Defaults: default server, 1 channel.</p>
  53 <p class="p3"><span class="Apple-tab-span">     </span></p>
  54 <p class="p1"><b>Bus.audio(server, numChannels);</b></p>
  55 <p class="p1"><span class="Apple-tab-span">     </span>Allocate an audio bus on the server.<span class="Apple-converted-space"> </span></p>
  56 <p class="p1"><span class="Apple-tab-span">     </span>Defaults: default server, 1 channel.</p>
  57 <p class="p3"><span class="Apple-tab-span">     </span></p>
  58 <p class="p1"><b>Bus.alloc(rate, server, numChannels);</b></p>
  59 <p class="p1"><span class="Apple-tab-span">     </span>Allocate a bus of either rate as specified by the symbols:<span class="Apple-converted-space"> </span></p>
  60 <p class="p1"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>\control or \audio</p>
  61 <p class="p3"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span></p>
  62 <p class="p1"><b>Bus.new(rate, index, numChannels);</b></p>
  63 <p class="p1"><span class="Apple-tab-span">     </span>This method does not allocate a bus index, but assumes that you</p>
  64 <p class="p1"><span class="Apple-tab-span">     </span>already have allocated the appropriate bus index and can supply it</p>
  65 <p class="p1"><span class="Apple-tab-span">     </span>yourself.</p>
  66 <p class="p3"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span></p>
  67 <p class="p1"><b>Bus.newFrom(bus, offset, numChannels=1);</b></p>
  68 <p class="p1"><span class="Apple-tab-span">     </span>This method creates a new Bus that is a subset of the bus. The bus will be at the same rate as the input bus.</p>
  69 <p class="p1"><span class="Apple-tab-span">     </span>offset is the index into the given bus. numChannels is the desired number of channels.</p>
  70 <p class="p1"><span class="Apple-tab-span">     </span>If the combination of offset and numChannels is outside the input bus' range, an error will be thrown.</p>
  71 <p class="p2"><span class="Apple-tab-span">     </span></p>
  72 <p class="p5"><br></p>
  73 <p class="p4"><b>Instance Methods</b></p>
  74 <p class="p3"><br></p>
  75 <p class="p1"><b>index </b>-<b> </b>Get the Bus' index. Normally you should not need to do this since instances of Bus can be passed directly as UGen inputs or Synth args.</p>
  76 <p class="p3"><span class="Apple-tab-span">     </span></p>
  77 <p class="p1"><b>free</b> - Return the bus' indices to the server's bus allocator so they can be reallocated.</p>
  78 <p class="p3"><span class="Apple-tab-span">     </span></p>
  79 <p class="p1"><b>rate</b> - Get the Bus' rate. This is a symbol, either \control or \audio.</p>
  80 <p class="p3"><span class="Apple-tab-span">     </span></p>
  81 <p class="p1"><b>numChannels </b>- Get the Bus' number of channels.</p>
  82 <p class="p3"><br></p>
  83 <p class="p1"><b>server</b> - Get the Bus' server object.</p>
  84 <p class="p3"><br></p>
  85 <p class="p1"><b>asMap</b> - Returns a symbol consisting of the letter 'c' or 'a' (for control or audio) followed by the bus's index. This may be used when setting a synth node's control inputs to map the input to the control bus. See the <a href="Node.html"><span class="s2">Node</span></a> help file for more information on mapping controls to buses.<span class="Apple-converted-space"> </span></p>
  86 <p class="p3"><br></p>
  87 <p class="p3"><span class="Apple-tab-span">     </span></p>
  88 <p class="p6">(</p>
  89 <p class="p6">a = <span class="s2">Bus</span>.control(s, 1).set(440);</p>
  90 <p class="p6">b = <span class="s2">Bus</span>.control(s, 1).set(0.01);</p>
  91 <p class="p6">)</p>
  92 <p class="p6">(</p>
  93 <p class="p7">SynthDef<span class="s3">(</span><span class="s4">\rlpf</span><span class="s3">, { </span>|ffreq, rq|</p>
  94 <p class="p6"><span class="Apple-tab-span">     </span><span class="s2">Out</span>.ar(0, <span class="s2">RLPF</span>.ar(<span class="s2">WhiteNoise</span>.ar(0.2), ffreq, rq))</p>
  95 <p class="p6">}).play(s, [<span class="s4">\ffreq</span>, a.asMap, <span class="s4">\rq</span>, b.asMap]);</p>
  96 <p class="p6">)</p>
  97 <p class="p3"><br></p>
  98 <p class="p1"><b>subBus(offset,numChannels) </b>-<b> </b>Get a new Bus that is a subset of this bus (see <b>*newFrom</b>).</p>
  99 <p class="p3"><br></p>
 100 <p class="p4"><b>Asynchronous Control Bus Methods</b></p>
 101 <p class="p3"><br></p>
 102 <p class="p1">The following commands apply only to control buses and are asynchronous. For synchronous access to control buses one should use the internal server's shared control buses and <a href="../UGens/InOut/SharedIn.html"><span class="s2">SharedIn</span></a> / <a href="../UGens/InOut/SharedOut.html"><span class="s2">SharedOut</span></a>.</p>
 103 <p class="p3"><br></p>
 104 <p class="p1"><b>value_(aFloat) </b>-<b> </b>Set all channels to this float value. This command is asynchronous.</p>
 105 <p class="p3"><span class="Apple-tab-span">     </span></p>
 106 <p class="p1"><b>set(...values) </b>- A list of values for each channel of the control bus.<span class="Apple-converted-space">  </span>The list of values supplied should not be greater than the number of channels. This command is asynchronous.</p>
 107 <p class="p3"><br></p>
 108 <p class="p1"><b>setn(values) </b>- As <b>set</b> but takes an array as an argument.</p>
 109 <p class="p3"><span class="Apple-tab-span">     </span></p>
 110 <p class="p1"><b>get(action)</b> - Get the current value of this control bus. This command is asynchronous. <b>action </b>is a function that will be evaluated when the server responds, with the current value of the bus passed as an argument. This will be a float for a single channel bus, or an array of floats for a multichannel bus. The default action posts the bus values.</p>
 111 <p class="p3"><br></p>
 112 <p class="p1"><b>getn(count, action)</b> - Get the current values of this control bus. This command is asynchronous. <b>count</b> is the number of channels to read, starting from this bus' first channel. <b>action </b>is a function that will be evaluated when the server responds, with the current values of the bus in an array passed as an argument.</p>
 113 <p class="p3"><br></p>
 114 <p class="p1"><b><span class="Apple-tab-span">  </span>conveniences for multichannel buses:<span class="Apple-converted-space"> </span></b></p>
 115 <p class="p1"><b>setAt(offset, value1, value2, ... valueN) </b>- set the bus value(s) beginning at offset. asynchronous.</p>
 116 <p class="p3"><br></p>
 117 <p class="p1"><b>setnAt(pos, values)</b> - set the bus to the list of values supplied. asynchronous.</p>
 118 <p class="p3"><br></p>
 119 <p class="p1"><b>setPairs(index1, value1, index2, value2 ... indexN, valueN)</b> - set the bus values by pairs of index, value, index value. asynchronous</p>
 120 <p class="p3"><br></p>
 121 <p class="p4"><b>Using Buses like UGens</b></p>
 122 <p class="p3"><br></p>
 123 <p class="p1"><b>kr(numChannels, offset),</b></p>
 124 <p class="p1"><b>ar(numChannels, offset)</b> - use a bus like a UGen. The numChannels and offset arguments can be used to get a subset of the bus.</p>
 125 <p class="p1"><span class="Apple-tab-span">     </span>By default, all the bus channels are used. E.g. in an 8 channel bus,<span class="Apple-converted-space"> </span></p>
 126 <p class="p1"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>b.kr will return an In ugen reading from all the 8 channels of the bus;<span class="Apple-converted-space"> </span></p>
 127 <p class="p1"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>b.kr(4) will return the first four channels, and<span class="Apple-converted-space"> </span></p>
 128 <p class="p1"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>b.kr(2, 5) will return two channels, starting from the bus's channels at index 5 and 6.<span class="Apple-converted-space"> </span></p>
 129 <p class="p3"><br></p>
 130 <p class="p5"><br></p>
 131 <p class="p4"><b>OSC Bundle Methods</b></p>
 132 <p class="p3"><br></p>
 133 <p class="p1"><b>getMsg</b> - Returns a msg of the type /c_get for use in osc bundles.</p>
 134 <p class="p3"><br></p>
 135 <p class="p1"><b>getnMsg(count)</b> - Returns a msg of the type /c_getn for use in osc bundles. <b>count</b> is the number of channels to read, starting from this bus' first channel. The default is this bus' numChannels.</p>
 136 <p class="p3"><br></p>
 137 <p class="p1"><b>setMsg(... values)</b> - Returns a msg of the type /c_set for use in osc bundles.</p>
 138 <p class="p3"><br></p>
 139 <p class="p1"><b>setnMsg(values)</b> - Returns a msg of the type /c_setn for use in osc bundles. <b>values </b>is a an array of values to which adjacent channels should be set, starting at this bus' first channel.<span class="Apple-converted-space"> </span></p>
 140 <p class="p3"><br></p>
 141 <p class="p1"><b>fillMsg(value)</b> - Returns a msg of the type /c_fill for use in osc bundles. <b>value </b>is the value to which this bus' channels will be set.</p>
 142 <p class="p3"><br></p>
 143 <p class="p3"><br></p>
 144 <p class="p1"><b>Examples</b></p>
 145 <p class="p2"><br></p>
 146 <p class="p6">s = <span class="s5">Server</span>.local;</p>
 147 <p class="p6">s.boot;</p>
 148 <p class="p3"><span class="Apple-tab-span">     </span></p>
 149 <p class="p6">(</p>
 150 <p class="p8">// something to play with</p>
 151 <p class="p6"><span class="s5">SynthDef</span>(<span class="s6">\help_Bus</span>, { <span class="s5">arg</span> out=0,ffreq=100;</p>
 152 <p class="p6"><span class="Apple-tab-span">     </span><span class="s5">var</span> x;</p>
 153 <p class="p6"><span class="Apple-tab-span">     </span>x = <span class="s5">RLPF</span>.ar(<span class="s5">LFPulse</span>.ar(<span class="s5">SinOsc</span>.kr(0.2, 0, 10, 21), [0,0.1], 0.1),</p>
 154 <p class="p6"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>ffreq, 0.1)</p>
 155 <p class="p6"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>.clip2(0.4);</p>
 156 <p class="p6"><span class="Apple-tab-span">     </span><span class="s5">Out</span>.ar(out, x);</p>
 157 <p class="p6">}).add;</p>
 158 <p class="p2"><br></p>
 159 <p class="p6">)</p>
 160 <p class="p2"><br></p>
 161 <p class="p9"><span class="s3">x = </span><span class="s5">Synth</span><span class="s3">(</span>\help_Bus<span class="s3">);</span></p>
 162 <p class="p2"><br></p>
 163 <p class="p8">// get a bus</p>
 164 <p class="p6">b = <span class="s5">Bus</span>.control(s);</p>
 165 <p class="p2"><br></p>
 166 <p class="p8">// map the synth's second input (ffreq) to read</p>
 167 <p class="p8">// from the bus' output index</p>
 168 <p class="p6">x.map(1, b);</p>
 169 <p class="p2"><br></p>
 170 <p class="p8">// By setting the bus' value you send a /c_fill message</p>
 171 <p class="p8">// to each channel of the bus setting it to supplied float value</p>
 172 <p class="p6">b.value = 100;</p>
 173 <p class="p6">b.value = 1000;</p>
 174 <p class="p6">b.value = 30;</p>
 175 <p class="p2"><br></p>
 176 <p class="p8">// Since this is a single channel bus this has the same effect</p>
 177 <p class="p6">b.set(300);</p>
 178 <p class="p6">b.numChannels.postln;</p>
 179 <p class="p2"><br></p>
 180 <p class="p8">// multi-channel:<span class="Apple-converted-space">  </span>b.set(300,350);</p>
 181 <p class="p8">// Get the current value. This is asynchronous so you can't rely on it happening immediately.</p>
 182 <p class="p6">(</p>
 183 <p class="p10"><span class="s3">a = </span>"waiting"<span class="s3">;</span></p>
 184 <p class="p6">b.get({<span class="s5">arg</span> value; a = value; (<span class="s7">"after the server responds a is set to:"</span> + a).postln;});</p>
 185 <p class="p6">(<span class="s7">"a is now:"</span> + a).postln;</p>
 186 <p class="p6">)</p>
 187 <p class="p2"><br></p>
 188 <p class="p6">x.free;</p>
 189 <p class="p2"><span class="Apple-tab-span">     </span></p>
 190 <p class="p8"><span class="s3"><span class="Apple-tab-span">    </span></span>// buses can also be used with kr or ar like UGens:<span class="Apple-converted-space"> </span></p>
 191 <p class="p6">(</p>
 192 <p class="p2"><br></p>
 193 <p class="p9"><span class="s5">SynthDef</span><span class="s3">(</span>\help_Bus<span class="s3">, {</span></p>
 194 <p class="p6"><span class="Apple-tab-span">     </span><span class="s5">var</span> ffreq = b.kr;<span class="Apple-converted-space"> </span></p>
 195 <p class="p6"><span class="Apple-tab-span">     </span><span class="s5">Out</span>.ar(0,<span class="Apple-converted-space"> </span></p>
 196 <p class="p6"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="s5">RLPF</span>.ar(</p>
 197 <p class="p6"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="s5">LFPulse</span>.ar(<span class="s5">SinOsc</span>.kr(0.2, 0, 10, 21), [0,0.1], 0.1),<span class="Apple-converted-space"> </span></p>
 198 <p class="p6"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>ffreq, 0.1</p>
 199 <p class="p6"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>).clip2(0.4)</p>
 200 <p class="p6"><span class="Apple-tab-span">     </span>);</p>
 201 <p class="p6">}).play;</p>
 202 <p class="p6">)</p>
 203 <p class="p2"><br></p>
 204 <p class="p8"><span class="s3">b.free; </span>// release it so it may be reallocated!</p>
 205 <p class="p2"><br></p>
 206 <p class="p2"><br></p>
 207 <p class="p1"><b>// using and setting multichannel buses:<span class="Apple-converted-space"> </span></b></p>
 208 <p class="p2"><br></p>
 209 <p class="p6">(</p>
 210 <p class="p6">b = <span class="s5">Bus</span>.control(s, 4);</p>
 211 <p class="p2"><br></p>
 212 <p class="p9"><span class="s3">x = </span><span class="s5">SynthDef</span><span class="s3">(</span>\helpBusMulti<span class="s3">, {<span class="Apple-converted-space"> </span></span></p>
 213 <p class="p6"><span class="Apple-tab-span">     </span><span class="s5">var</span> freqs = b.kr;</p>
 214 <p class="p6"><span class="Apple-tab-span">     </span><span class="s5">Out</span>.ar(0, <span class="s5">Splay</span>.ar(<span class="s5">SinOsc</span>.ar(freqs) * <span class="s5">Decay2</span>.ar(<span class="s5">Dust</span>.ar(10 ! 4), 0.001, 0.1)) * 0.5);</p>
 215 <p class="p6">}).play;</p>
 216 <p class="p6">)</p>
 217 <p class="p2"><br></p>
 218 <p class="p8"><span class="s3"><span class="Apple-tab-span">    </span></span>// set bus beginning at index 0:<span class="Apple-converted-space"> </span></p>
 219 <p class="p8"><span class="s3"><span class="Apple-tab-span">    </span></span>// none of these methods checks whether the indexes remain<span class="Apple-converted-space"> </span></p>
 220 <p class="p8"><span class="s3"><span class="Apple-tab-span">    </span></span>// within the bus's range.<span class="Apple-converted-space"> </span></p>
 221 <p class="p2"><span class="Apple-tab-span">     </span></p>
 222 <p class="p6">b.set(234, 345, 456, 567);</p>
 223 <p class="p6">b.getn;</p>
 224 <p class="p6">b.setn([100, 200, 300, 400]);</p>
 225 <p class="p6">b.getn;</p>
 226 <p class="p2"><br></p>
 227 <p class="p8"><span class="s3"><span class="Apple-tab-span">    </span></span>// get to individual channels</p>
 228 <p class="p6">b.setAt(3, 500);</p>
 229 <p class="p6">b.getn;</p>
 230 <p class="p6">b.setAt(1, 300, 400);</p>
 231 <p class="p6">b.getn;</p>
 232 <p class="p6">b.setnAt(1, [250, 350]);</p>
 233 <p class="p6">b.getn;</p>
 234 <p class="p8"><span class="s3"><span class="Apple-tab-span">    </span></span>// set by pairs of index, value ...</p>
 235 <p class="p6">b.setPairs(3, 600, 0, 200);</p>
 236 <p class="p6">b.getn;</p>
 237 <p class="p2"><br></p>
 238 <p class="p6">b.set(300, 500, 700, 900);</p>
 239 <p class="p2"><br></p>
 240 <p class="p8"><span class="s3">(<span class="Apple-tab-span">   </span></span>// just get the first 2 channels</p>
 241 <p class="p9"><span class="s3">x = </span><span class="s5">SynthDef</span><span class="s3">(</span>\helpBusMulti<span class="s3">, {<span class="Apple-converted-space"> </span></span></p>
 242 <p class="p6"><span class="Apple-tab-span">     </span><span class="s5">Out</span>.ar(0, <span class="s5">SinOsc</span>.ar(b.kr(2)) * 0.2);</p>
 243 <p class="p6">}).play;</p>
 244 <p class="p6">)</p>
 245 <p class="p6">b.set(300, 303);</p>
 246 <p class="p6">x.free;</p>
 247 <p class="p2"><br></p>
 248 <p class="p8"><span class="s3">(<span class="Apple-tab-span">   </span></span>// just channels[[2, 3]];</p>
 249 <p class="p9"><span class="s3">y = </span><span class="s5">SynthDef</span><span class="s3">(</span>\helpBusMulti<span class="s3">, {<span class="Apple-converted-space"> </span></span></p>
 250 <p class="p6"><span class="Apple-tab-span">     </span><span class="s5">Out</span>.ar(0, <span class="s5">LFNoise2</span>.ar(b.kr(2, 2)) * 0.2);</p>
 251 <p class="p6">}).play;</p>
 252 <p class="p6">)</p>
 253 <p class="p6">b.setAt(2, 1200);</p>
 254 <p class="p6">b.setAt(3, 2400);</p>
 255 <p class="p2"><br></p>
 256 <p class="p6">y.free;</p>
 257 <p class="p6">b.free;</p>
 258 <p class="p2"><br></p>
 259 </body>
 260 </html>