HelpSource/Classes/Bus.schelp

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