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