1class:: Bus 2summary:: Representation of a bus on the server 3categories:: Server>Abstractions 4related:: Classes/Server 5 6description:: 7The clientside representation of an audio or control bus on a server. Encapsulates all the link::Browse#OpenSoundControl#OSC:: messages a Bus can receive. 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. 8 9For more information see link::Guides/ClientVsServer:: and link::Reference/Server-Architecture::. 10 11Note that using the Bus 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' link::Classes/Server:: object's bus allocators. code::abus.index:: simply returns the first of those indices. When using a Bus with an link::Classes/In:: or link::Classes/Out:: 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. 12 13Bus objects should not be created or modified within a link::Classes/SynthDef::. 14 15Note:: 16The lowest code::n:: bus indices are reserved for hardware output and input, where 17code:: 18n = server.options.numOutputBusChannels + server.options.numInputBusChannels 19:: 20definitionlist:: 21## Hardware output buses || code:: 0 .. (numOutputBusChannels - 1) :: 22## Hardware input buses || code:: numOutputBusChannels .. (numOutputBusChannels + numInputBusChannels - 1) :: 23## First private bus index || code:: numOutputBusChannels + numInputBusChannels :: 24:: 25Do not try to use hardware I/O buses as private buses. 26:: 27 28ClassMethods:: 29 30method:: control 31Allocate a control bus on the server. 32 33argument:: server 34The link::Classes/Server::. Defaults to Server.default. 35argument:: numChannels 36Number of channels to allocate 37 38method:: audio 39Allocate an audio bus on the server. 40 41argument:: server 42The link::Classes/Server::. Defaults to Server.default. 43argument:: numChannels 44Number of channels to allocate 45 46method:: alloc 47Allocate a bus of either rate as specified by code::rate::. 48argument:: rate 49Rate symbol: \control or \audio 50argument:: server 51The link::Classes/Server::. Defaults to Server.default. 52argument:: numChannels 53Number of channels to allocate 54 55method:: new 56This method does not allocate a bus index, but assumes that you 57already have allocated the appropriate bus index and can supply it 58yourself. 59 60method:: newFrom 61This method creates a new Bus that is a subset of the bus. The bus will be at the same rate as the input bus. 62offset is the index into the given bus. numChannels is the desired number of channels. 63If the combination of offset and numChannels is outside the input bus' range, an error will be thrown. 64 65InstanceMethods:: 66 67method:: index 68Get the Bus' index. Normally you should not need to do this since instances of Bus can be passed directly as link::Classes/UGen:: inputs or link::Classes/Synth:: args. 69 70method:: free 71Return the bus' indices to the server's bus allocator so they can be reallocated. 72 73method:: rate 74Get the Bus' rate. This is a symbol, either \control or \audio. 75 76method:: numChannels 77Get the Bus' number of channels. 78 79method:: server 80Get the Bus' server object. 81 82method:: asMap 83Returns:: 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. 84discussion:: 85See the link::Classes/Node:: help file for more information on mapping controls to buses. 86code:: 87( 88a = Bus.control(s, 1).set(440); 89b = Bus.control(s, 1).set(0.01); 90) 91( 92SynthDef(\rlpf, { |out, ffreq, rq| 93 Out.ar(out, RLPF.ar(WhiteNoise.ar(0.2), ffreq, rq)) 94}).play(s, [\ffreq, a.asMap, \rq, b.asMap]); 95) 96:: 97 98method:: subBus 99Get a new Bus that is a subset of this bus (see code::newFrom::). 100 101subsection:: Asynchronous Control Bus Methods 102 103The following commands apply only to control buses and are asynchronous. For synchronous access to control busses please 104consult link::#Synchronous Control Bus Methods::. 105 106method:: value 107Set all channels to this float value. This command is asynchronous. 108 109method:: set 110A list of values for each channel of the control bus. The list of values supplied should not be greater than the number of channels. This command is asynchronous. 111 112method:: setn 113As set but takes an array as an argument. 114 115method:: get 116Get the current value of this control bus. This command is asynchronous. 117argument:: action 118a 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. 119 120 121method:: getn 122Get the current values of this control bus. This command is asynchronous. 123argument:: count 124the number of channels to read, starting from this bus' first channel. 125argument:: action 126a function that will be evaluated when the server responds, with the current values of the bus in an array passed as an argument. 127 128 129subsection:: Synchronous Control Bus Methods 130 131Synchronous access to control busses only works for servers with a shared memory interface. You can check with link::Classes/Server#-hasShmInterface#hasShmInterface:: if the server provides these methods. 132 133note:: Before 3.5 the the internal server could be controlled via shared control busses and link::Classes/SharedIn:: and 134link::Classes/SharedOut::. These classes have been deprecated and will be removed. :: 135 136method:: getSynchronous 137Get the current value of this control bus. This command is synchronous. 138 139returns:: 140Value of the control bus. 141 142method:: getnSynchronous 143Get the current values of this control bus. This command is synchronous. 144argument:: count 145The number of channels to read, starting from this bus' first channel. 146returns:: 147Array of values. 148 149method:: setSynchronous 150A list of values for each channel of the control bus. The list of values supplied should not be greater than the number of channels. This command is synchronous. 151 152method:: setnSynchronous 153As setSynchronous but takes an array as an argument. 154 155 156subsection:: Conveniences for multichannel buses 157method:: setAt 158set the bus value(s) beginning at offset. asynchronous. 159 160method:: setnAt 161set the bus to the list of values supplied. asynchronous. 162 163method:: setPairs 164set the bus values by pairs of index, value, ... asynchronous 165 166subsection:: Using Buses like UGens 167 168method:: kr, ar 169use a bus like a UGen. The numChannels and offset arguments can be used to get a subset of the bus. 170discussion:: 171By default, all the bus channels are used. E.g. in an 8 channel bus, 172list:: 173## code::b.kr:: will return an link::Classes/In:: ugen reading from all the 8 channels of the bus; 174## code::b.kr(4):: will return the first four channels, and 175## code::b.kr(2, 5):: will return two channels, starting from the bus's channels at index 5 and 6. 176:: 177 178subsection:: OSC Bundle Methods 179 180method:: getMsg 181Returns a msg of the type /c_get for use in osc bundles. 182 183method:: getnMsg 184Returns a msg of the type /c_getn for use in osc bundles. 185argument:: count 186the number of channels to read, starting from this bus' first channel. The default is this bus' numChannels. 187 188method:: setMsg 189Returns a msg of the type /c_set for use in osc bundles. 190 191method:: setnMsg 192Returns a msg of the type /c_setn for use in osc bundles. 193argument:: values 194an array of values to which adjacent channels should be set, starting at this bus' first channel. 195 196method:: fillMsg 197Returns a msg of the type /c_fill for use in osc bundles. 198argument:: value 199the value to which this bus' channels will be set. 200 201subsection:: Monitoring with an oscilloscope 202 203method:: scope 204Displays a bus in a link::Classes/Stethoscope::, using the Bus' link::#-numChannels::, link::#-index::, and link::#-rate:: properties. 205code:: 206s.boot 207b=Bus.audio(s, 2); 208a={SinOsc.ar([330,440], 0, 0.4)}.play(s, b) //you won't hear this if you only have two channels 209b.scope 210 211a.free; 212b.free; 213:: 214 215Examples:: 216code:: 217s.boot; 218 219( 220// something to play with 221SynthDef(\help_Bus, { arg out=0,ffreq=100; 222 var x; 223 x = RLPF.ar(LFPulse.ar(SinOsc.kr(0.2, 0, 10, 21), [0,0.1], 0.1), 224 ffreq, 0.1) 225 .clip2(0.4); 226 Out.ar(out, x); 227}).add; 228 229) 230 231x = Synth(\help_Bus); 232 233// get a bus 234b = Bus.control(s); 235 236// map the synth's second input (ffreq) to read 237// from the bus' output index 238x.map(1, b); 239 240// By setting the bus' value you send a /c_fill message 241// to each channel of the bus setting it to supplied float value 242b.value = 100; 243b.value = 1000; 244b.value = 30; 245 246// Since this is a single channel bus this has the same effect 247b.set(300); 248b.numChannels.postln; 249 250// multi-channel: b.set(300,350); 251// Get the current value. This is asynchronous so you can't rely on it happening immediately. 252( 253a = "waiting"; 254b.get({arg value; a = value; ("after the server responds a is set to:" + a).postln;}); 255("a is now:" + a).postln; 256) 257 258x.free; 259 260 // buses can also be used with kr or ar like UGens: 261( 262 263SynthDef(\help_Bus, { |out| 264 var ffreq = b.kr; 265 Out.ar(out, 266 RLPF.ar( 267 LFPulse.ar(SinOsc.kr(0.2, 0, 10, 21), [0,0.1], 0.1), 268 ffreq, 0.1 269 ).clip2(0.4) 270 ); 271}).play; 272) 273 274b.free; // release it so it may be reallocated! 275 276 277// using and setting multichannel buses: 278 279( 280b = Bus.control(s, 4); 281 282x = SynthDef(\helpBusMulti, { |out| 283 var freqs = b.kr; 284 Out.ar(out, Splay.ar(SinOsc.ar(freqs) * Decay2.ar(Dust.ar(10 ! 4), 0.001, 0.1)) * 0.5); 285}).play; 286) 287 288 // set bus beginning at index 0: 289 // none of these methods checks whether the indexes remain 290 // within the bus's range. 291 292b.set(234, 345, 456, 567); 293b.getn; 294b.setn([100, 200, 300, 400]); 295b.getn; 296 297 // get to individual channels 298b.setAt(3, 500); 299b.getn; 300b.setAt(1, 300, 400); 301b.getn; 302b.setnAt(1, [250, 350]); 303b.getn; 304 // set by pairs of index, value ... 305b.setPairs(3, 600, 0, 200); 306b.getn; 307 308b.set(300, 500, 700, 900); 309 310( // just get the first 2 channels 311x = SynthDef(\helpBusMulti, { |out| 312 Out.ar(out, SinOsc.ar(b.kr(2)) * 0.2) 313}).play; 314) 315b.set(300, 303); 316x.free; 317 318( // just channels[[2, 3]]; 319y = SynthDef(\helpBusMulti, { |out| 320 Out.ar(out, LFNoise2.ar(b.kr(2, 2)) * 0.2); 321}).play; 322) 323b.setAt(2, 1200); 324b.setAt(3, 2400); 325 326y.free; 327b.free; 328:: 329