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 formula::
  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::.
 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 anchor::synchronous::
 132
 133 Synchronous access to control busses only works for local servers.
 134
 135 note:: Before 3.5 the the internal server could be controlled via shared control busses and link::Classes/SharedIn:: and
 136 link::Classes/SharedOut::. These classes have been deprecated and will be removed.  ::
 137
 138 method:: getSynchronous
 139 Get the current value of this control bus. This command is synchronous.
 140
 141 returns::
 142 Value of the control bus.
 143
 144 method:: getnSynchronous
 145 Get the current values of this control bus. This command is synchronous.
 146 argument:: count
 147 The number of channels to read, starting from this bus' first channel.
 148 returns::
 149 Array of values.
 150
 151 method:: setSynchronous
 152 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.
 153
 154 method:: setnSynchronous
 155 As setSynchronous but takes an array as an argument.
 156
 157
 158 subsection:: conveniences for multichannel buses:
 159 method:: setAt
 160 set the bus value(s) beginning at offset. asynchronous.
 161
 162 method:: setnAt
 163 set the bus to the list of values supplied. asynchronous.
 164
 165 method:: setPairs
 166 set the bus values by pairs of index, value, ... asynchronous
 167
 168 subsection:: Using Buses like UGens
 169
 170 method:: kr, ar
 171 use a bus like a UGen. The numChannels and offset arguments can be used to get a subset of the bus.
 172 discussion::
 173 By default, all the bus channels are used. E.g. in an 8 channel bus,
 174 list::
 175 ## code::b.kr:: will return an link::Classes/In:: ugen reading from all the 8 channels of the bus;
 176 ## code::b.kr(4):: will return the first four channels, and
 177 ## code::b.kr(2, 5):: will return two channels, starting from the bus's channels at index 5 and 6.
 178 ::
 179
 180 subsection:: OSC Bundle Methods
 181
 182 method:: getMsg
 183 Returns a msg of the type /c_get for use in osc bundles.
 184
 185 method:: getnMsg
 186 Returns a msg of the type /c_getn for use in osc bundles.
 187 argument:: count
 188 the number of channels to read, starting from this bus' first channel. The default is this bus' numChannels.
 189
 190 method:: setMsg
 191 Returns a msg of the type /c_set for use in osc bundles.
 192
 193 method:: setnMsg
 194 Returns a msg of the type /c_setn for use in osc bundles.
 195 argument:: values
 196 an array of values to which adjacent channels should be set, starting at this bus' first channel.
 197
 198 method:: fillMsg
 199 Returns a msg of the type /c_fill for use in osc bundles.
 200 argument:: value
 201 the value to which this bus' channels will be set.
 202
 203
 204 Examples::
 205 code::
 206 s = Server.local;
 207 s.boot;
 208
 209 (
 210 // something to play with
 211 SynthDef(\help_Bus, { arg out=0,ffreq=100;
 212         var x;
 213         x = RLPF.ar(LFPulse.ar(SinOsc.kr(0.2, 0, 10, 21), [0,0.1], 0.1),
 214                         ffreq, 0.1)
 215                         .clip2(0.4);
 216         Out.ar(out, x);
 217 }).add;
 218
 219 )
 220
 221 x = Synth(\help_Bus);
 222
 223 // get a bus
 224 b = Bus.control(s);
 225
 226 // map the synth's second input (ffreq) to read
 227 // from the bus' output index
 228 x.map(1, b);
 229
 230 // By setting the bus' value you send a /c_fill message
 231 // to each channel of the bus setting it to supplied float value
 232 b.value = 100;
 233 b.value = 1000;
 234 b.value = 30;
 235
 236 // Since this is a single channel bus this has the same effect
 237 b.set(300);
 238 b.numChannels.postln;
 239
 240 // multi-channel:  b.set(300,350);
 241 // Get the current value. This is asynchronous so you can't rely on it happening immediately.
 242 (
 243 a = "waiting";
 244 b.get({arg value; a = value; ("after the server responds a is set to:" + a).postln;});
 245 ("a is now:" + a).postln;
 246 )
 247
 248 x.free;
 249
 250         // buses can also be used with kr or ar like UGens:
 251 (
 252
 253 SynthDef(\help_Bus, {
 254         var ffreq = b.kr;
 255         Out.ar(0,
 256                 RLPF.ar(
 257                         LFPulse.ar(SinOsc.kr(0.2, 0, 10, 21), [0,0.1], 0.1),
 258                         ffreq, 0.1
 259                 ).clip2(0.4)
 260         );
 261 }).play;
 262 )
 263
 264 b.free; // release it so it may be reallocated!
 265
 266
 267 // using and setting multichannel buses:
 268
 269 (
 270 b = Bus.control(s, 4);
 271
 272 x = SynthDef(\helpBusMulti, {
 273         var freqs = b.kr;
 274         Out.ar(0, Splay.ar(SinOsc.ar(freqs) * Decay2.ar(Dust.ar(10 ! 4), 0.001, 0.1)) * 0.5);
 275 }).play;
 276 )
 277
 278         // set bus beginning at index 0:
 279         // none of these methods checks whether the indexes remain
 280         // within the bus's range.
 281
 282 b.set(234, 345, 456, 567);
 283 b.getn;
 284 b.setn([100, 200, 300, 400]);
 285 b.getn;
 286
 287         // get to individual channels
 288 b.setAt(3, 500);
 289 b.getn;
 290 b.setAt(1, 300, 400);
 291 b.getn;
 292 b.setnAt(1, [250, 350]);
 293 b.getn;
 294         // set by pairs of index, value ...
 295 b.setPairs(3, 600, 0, 200);
 296 b.getn;
 297
 298 b.set(300, 500, 700, 900);
 299
 300 (       // just get the first 2 channels
 301 x = SynthDef(\helpBusMulti, {
 302         Out.ar(0, SinOsc.ar(b.kr(2)) * 0.2);
 303 }).play;
 304 )
 305 b.set(300, 303);
 306 x.free;
 307
 308 (       // just channels[[2, 3]];
 309 y = SynthDef(\helpBusMulti, {
 310         Out.ar(0, LFNoise2.ar(b.kr(2, 2)) * 0.2);
 311 }).play;
 312 )
 313 b.setAt(2, 1200);
 314 b.setAt(3, 2400);
 315
 316 y.free;
 317 b.free;
 318 ::