HelpSource/Classes/UGen.schelp

   1 class:: UGen
   2 summary:: Abstract superclass of all unit generators
   3 categories:: UGens, Server>Abstractions
   4 related:: Browse#UGens, Guides/Tour_of_UGens, Guides/UGens-and-Synths
   5
   6 description::
   7
   8 UGens represent calculations with signals. They are the basic building blocks of synth definitions on the server, and are used to generate or process both audio and control signals. The many subclasses of UGen are the client-side representations of unit generators, and are used to specify their parameters when constructing synth definitions (see link::Classes/SynthDef::).
   9
  10 subsection:: Interface
  11 All UGens respond to one or more of the following class methods:
  12 list::
  13 ## code:: ar(arg1, arg2, ... ) ::
  14 ## code:: kr(arg1, arg2, ... ) ::
  15 ## code:: ir(arg1, arg2, ... ) ::
  16 ::
  17
  18 They return a new instance of UGen that calculates at audio/control rate or at initialization only (ir). Some UGens, like link::Classes/Rand::, use the code::*new:: method instead. These methods are implemented in subclasses, where argument names and their meaning depend on the case.
  19
  20 If any argument is an array, they return an array of UGens ( see: link::Guides/Multichannel-Expansion:: ). If the combination of rates between arguments and ugen are not allowed, calling the methods will throw an error. This method adds the UGen to the current SynthDef, so it only fully works inside a UGen function.
  21 code::
  22 { Blip.ar(Blip.kr(4, 5, 500, 60), 59, 0.1) }.play;
  23 ::
  24
  25 subsection:: Documentation of mul and add arguments
  26
  27 A great number of UGens take arguments for code::mul:: and code::add:: in their code::*ar:: and code::*kr:: methods. Because these arguments are so ubiquitous, they are not general documented in the individual help files.
  28 Mul and add simply refer to a constant or signal by which to multiply the output of the UGen, and a constant or signal to add to the output of the UGen. (mul happens before add.) They thus correspond in many cases to scaling the amplitude of the UGen signal in the case of mul, and adding a constant or DC offset in the case of add.
  29 In most cases the defaults for mul and add are 1 and 0 respectively, and they are commonly implemented using a automatically generated link::Classes/MulAdd:: UGen for efficiency. See also the code::range:: and code::madd:: methods below.
  30
  31 classmethods::
  32 private:: categories
  33
  34 method:: buildSynthDef
  35 Returns:: the SynthDef in which the UGen is situated.
  36 Discussion::
  37 code::
  38 { UGen.buildSynthDef.dump; Silent.ar }.play;
  39 ::
  40
  41 subsection:: Internally used class methods
  42
  43 method:: multiNew
  44 These methods are responsible for multichannel expansion. They call code::*new1(rate, ...args):: for each parallel combination. Most code::*ar/*kr:: methods delegate to link::#*multiNewList::.
  45 argument:: ... args
  46 The first argument is rate, then the rest of the arguments. code::(rate, ...args)::
  47
  48 method:: multiNewList
  49 See link::#*multiNew::.
  50 argument:: args
  51 An array where the first argument is rate, then the rest of the arguments. code::([rate, ...args])::
  52
  53 method:: new1
  54 This method returns a single instance of the UGen, not multichannel expanded. It is called inside multiNewList, whenever a new single instance is needed.
  55
  56 method:: methodSelectorForRate
  57 argument:: rate
  58 A link::Classes/Symbol::, code:: \audio, \control, \scalar ::
  59 Returns::
  60 An appropriate message selector ( link::Classes/Symbol:: like code:: \ar, \kr, \ir :: ) for the given rate.
  61
  62 method:: replaceZeroesWithSilence
  63 Returns::
  64 A new link::Classes/Array::, where every zero is replaced by a link::Classes/Silent:: UGen.
  65 discussion::
  66 This is required internally sometimes for UGens like link::Classes/Out::.
  67
  68 instancemethods::
  69
  70 subsection:: Convenience Methods
  71
  72 method:: scope
  73
  74 Displays the output of this UGen in an individual link::Classes/Stethoscope:: window.
  75 argument::name
  76 The name of the window
  77 argument::bufsize
  78 Buffer size
  79 argument::zoom
  80 Zoom factor
  81
  82 discussion::
  83 code::
  84 Server.default = s = Server.internal.boot; // scope works only for internal server
  85
  86 { Ringz.ar(PinkNoise.ar([0.1, 0.2]).scope(\pink), 2000, 1, 0.25) }.play; // multichannel works
  87 s.scope; // can still separately scope the output of the server
  88
  89 Server.default = s = Server.local.boot; // switch back to local server.
  90 ::
  91
  92 method:: poll
  93
  94 Polls the output of this UGen every interval seconds, and posts the result.
  95
  96 argument::trig
  97 Trig frequency
  98 argument::label
  99 A symbol to label the output
 100 argument::trigid
 101 Numerical ID
 102 discussion::
 103 The default trig is 10, which converts to 10 triggers per second (or every 0.1 seconds). See link::Classes/Poll:: for more info on polling.
 104 code::
 105 { SinOsc.ar(LFNoise0.ar(2).range(420, 460).poll(label: \LFNoise), 0, 0.2) }.play;
 106
 107 // multichannel polling:
 108 (
 109 {
 110     var freqs = SinOsc.ar([0.2, 0.3]).range(420, 460);
 111     freqs.poll(label: [\freq1, \freq2]);
 112     SinOsc.ar(freqs, 0, 0.2);
 113 }.play;
 114 )
 115 ::
 116
 117
 118 method:: dpoll
 119
 120 Like code::poll::, only that code::dpoll:: is used for Demand ugens. See link::Classes/Poll:: for more info on polling.
 121
 122 method:: range
 123
 124 Scales the output of this UGen to be within the range of code::lo:: and code::hi::.
 125 discussion::
 126 Note that code::range:: expects the default output range, and thus should not be used in conjunction with mul and add arguments.
 127 code::
 128 { SinOsc.ar(SinOsc.ar(0.3).range(440, 660), 0, 0.5) * 0.1 }.play;
 129 ::
 130
 131 method:: exprange
 132
 133 Maps the output of this UGen exponentially to be within the range of code::lo:: and code::hi:: using a link::Classes/LinExp:: UGen.
 134 discussion::
 135 code::lo:: and code::hi:: should both be non-zero and have the same sign. Note that code::exprange:: expects the default output range, and thus should not be used in conjunction with mul and add arguments.
 136 code::
 137 { SinOsc.ar(SinOsc.ar(0.3).exprange(440, 6600), 0, 0.5) * 0.1 }.play;
 138 ::
 139
 140 method:: unipolar
 141
 142 Scales the output of this UGen to be between code::(0..mul):: range (default 1).
 143 discussion::
 144 Note that code::unipolar:: expects the default output range, and thus should not be used in conjunction with mul and add arguments.
 145 code::
 146 { SinOsc.ar(300, 0, 0.5) * SinOsc.kr(2).unipolar * 0.1 }.play;
 147 ::
 148
 149 method:: bipolar
 150
 151 Scales the output of this UGen to be between code::(-mul..mul):: range (default 1).
 152 discussion::
 153 Note that code::bipolar:: expects the default output range, and thus should not be used in conjunction with mul and add arguments.
 154 code::
 155 { SinOsc.ar(500 + LFPulse.ar(4).bipolar(40), 0, 0.5) * 0.1 }.play;
 156 ::
 157
 158 method:: clip
 159 Wraps the receiver in a link::Classes/Clip:: UGen, clipping its output at code::lo:: and code::hi::.
 160
 161 method:: fold
 162 Wraps the receiver in a link::Classes/Fold:: UGen, folding its output at code::lo:: and code::hi::.
 163
 164 method:: wrap
 165 Wraps the receiver in a link::Classes/Wrap:: UGen, wrapping its output at code::lo:: and code::hi::.
 166
 167 method:: lag
 168 Wraps the receiver in a link::Classes/Lag:: UGen, smoothing its output by code::t1:: seconds lagtime. If a second argument is given, it wraps it in a link::Classes/LagUD:: UGen.
 169
 170 method:: lag2
 171 Wraps the receiver in a link::Classes/Lag2:: UGen, smoothing its output by code::t1:: seconds lagtime. If a second argument is given, it wraps it in a link::Classes/Lag2UD:: UGen.
 172
 173 method:: lag3
 174 Wraps the receiver in a link::Classes/Lag3:: UGen, smoothing its output by code::t1:: seconds lagtime. If a second argument is given, it wraps it in a link::Classes/Lag3UD:: UGen.
 175
 176 method:: lagud
 177 Wraps the receiver in a link::Classes/LagUD:: UGen, smoothing its output by code::lagtimeU:: and code::lagtimeD::.
 178
 179 method:: lag2ud
 180 Wraps the receiver in a link::Classes/Lag2UD:: UGen, smoothing its output by code::lagtimeU:: and code::lagtimeD::.
 181
 182 method:: lag3ud
 183 Wraps the receiver in a link::Classes/Lag3UD:: UGen, smoothing its output by code::lagtimeU:: and code::lagtimeD::.
 184
 185 method:: varlag
 186 Wraps the receiver in a link::Classes/VarLag:: UGen, smoothing its output by code::time:: seconds.
 187
 188 method:: slew
 189 Wraps the receiver in a link::Classes/Slew:: UGen, limiting the slope of its output.
 190
 191 method:: degreeToKey
 192
 193 Wraps the receiver in a link::Classes/DegreeToKey:: UGen.
 194
 195 method:: minNyquist
 196
 197 Wraps the receiver in a code::min:: link::Classes/BinaryOpUGen::, such that the lesser of the receiver's output and the Nyquist frequency is output. This can be useful to prevent aliasing.
 198
 199 method:: linlin
 200 Wraps the receiver so that a linear input range is mapped to a linear output range.
 201
 202 discussion::
 203 The clip argument can be one of the four:
 204 table::
 205 ## code::nil:: || do not clip at outMin or outMax
 206 ## code::\minmax:: || clip at outMin or outMax
 207 ## code::\min:: || clip at outMin
 208 ## code::\max:: || clip at outMax
 209 ::
 210 Example:
 211 code::
 212 { Line.ar(-1, 5, 0.1).linlin(0, 3, -1, 1) }.plot(0.1);
 213
 214 // modulate some values
 215 (
 216 { Line.ar(-1, 5, 0.1).lincurve(SinOsc.ar(100), SinOsc.ar(130) + 3, -1, 1, clip: nil) }
 217     .plot(0.1, minval: -15, maxval: 5)
 218 )
 219 ::
 220
 221 method:: linexp
 222
 223 Wraps the receiver so that a linear inputrange is mapped to an exponential output range.
 224 discussion::
 225 outMin and outMax must be nonzero and of the same sign. For clip argument, see code::linlin:: above.
 226 code::
 227 { Line.ar(-1, 5, 0.1).linexp(0, 3, 0.01, 1) }.plot(0.1);
 228 ::
 229
 230 method:: explin
 231
 232 Wraps the receiver so that an exponential inputrange is mapped to a linear output range.
 233 discussion::
 234 inMin and inMax must be nonzero and of the same sign. For clip argument, see code::linlin:: above.
 235 code::
 236 { Line.ar(1, 5, 0.1).explin(1, 3, -1, 1) }.plot(0.1);
 237 ::
 238
 239 method:: expexp
 240
 241 Wraps the receiver so that an exponential inputrange is mapped to an exponential output range.
 242 discussion::
 243 outMin, outMax, inMin and inMax must be nonzero and of the same sign. For clip argument, see code::linlin:: above.
 244 code::
 245 { Line.ar(1, 5, 0.1).expexp(1, 3, 0.01, 1) }.plot(0.1);
 246 ::
 247
 248 method:: lincurve
 249
 250 Wraps the receiver so that a linear inputrange is mapped to a curve-like exponential output range.
 251 discussion::
 252 outMin and outMax may be zero and of the different sign. For clip argument, see code::linlin:: above.
 253 code::
 254 { Line.ar(-1, 5, 0.1).lincurve(0, 3, -1, 1, curve: -4) }.plot(0.1);
 255
 256 // modulate the curve. Unlike with numbers and CurveSpec, the curve absolute value
 257 // should not be much smaller than 0.5.
 258 { SinOsc.ar(100).lincurve(-1, 1, -1, 1, XLine.kr(-3, -100, 0.1)) * 0.1 }.plot(0.1);
 259 ::
 260
 261 method:: curvelin
 262 Wraps the receiver so that a  curve-like exponential inputrange is mapped to a linear output range.
 263 discussion::
 264 inMin and inMax may be zero and of the different sign. For clip argument, see code::linlin:: above.
 265 code::
 266 { Line.ar(-1, 5, 0.1).curvelin(0, 3, -1, 1, curve: -4) }.plot(0.1);
 267 ::
 268
 269 method:: prune
 270 Limits the receiver range to one of the four clip modes, see code::linlin:: above.
 271
 272 method:: checkBadValues
 273 Wraps the receiver in a link::Classes/CheckBadValues:: UGen with the corresponding code::id:: and code::post:: flag.
 274
 275 method:: if
 276 Outputs trueUGen when the receiver outputs 1, falseUGen when the receiver outputs 0. If the receiver outputs a value between 0 and 1, a mixture of both will be played.
 277 discussion::
 278 This is implemented as: code::(this * (trueUGen - falseUGen)) + falseUGen)::
 279
 280 Note that both trueUGen and falseUGen will be calculated regardless of whether they are output, so this may not be the most efficient approach.
 281 code::
 282 // note different syntax in these two examples
 283 { if( LFNoise1.kr(1.0, 0.5, 0.5) , SinOsc.ar, Saw.ar ) * 0.1 }.play;
 284
 285 { Trig1.ar(Dust.ar(3), 0.2).lag(0.1).if(FSinOsc.ar(440), FSinOsc.ar(880)) * 0.1 }.play;
 286 ::
 287
 288 method:: @
 289 Dynamic geometry support. Returns code::Point(this, y)::.
 290 discussion::
 291 code::
 292 { (SinOsc.ar(1001) @ SinOsc.ar(1207)).rho }.scope;
 293 ::
 294
 295 method:: asComplex
 296 Complex math support. Returns code::Complex(this, 0.0)::.
 297
 298 method:: dumpArgs
 299 Posts a list of the arguments for this UGen and their values.
 300
 301
 302 subsection:: Other Instance Methods
 303
 304 The following methods and instance variables are largely used in the construction of synth definitions, synth descriptions (see link::Classes/SynthDesc::), UGen class definitions, etc., and are usually not needed for general use.
 305 Users should not attempt to set any of these values in general code.
 306
 307 method:: synthDef
 308 The SynthDef which contains the UGen.
 309
 310 method:: inputs
 311 The array of inputs to the UGen.
 312
 313 method:: rate
 314 The output rate of the UGen which is one of the link::Classes/Symbol::s code::\audio::, or code::\control::.
 315
 316 method:: signalRange
 317 Returns:: A symbol indicating the signal range of the receiver. Either code::\bipolar:: or code::\unipolar::.
 318
 319 method:: numChannels
 320 Returns:: The number of output channels.
 321 discussion::
 322 For a UGen, this will always be 1, but link::Classes/Array:: also implements this method, so multichannel expansion is supported. See link::Guides/Multichannel-Expansion::.
 323
 324 method:: numInputs
 325 Returns:: The number of inputs for this UGen.
 326
 327 method:: numOutputs
 328 Returns:: The number of outputs for this UGen.
 329
 330 method:: name
 331 Returns:: The Class name of the receiver as a link::Classes/String::.
 332
 333 method:: madd
 334 Wraps the receiver in a link::Classes/MulAdd:: UGen.
 335 discussion::
 336 This is for the most part only used in UGen class definitions in order to allow efficient implementation of code::mul:: and code::add:: arguments.
 337
 338 method:: isValidUGenInput
 339 Returns:: true
 340
 341 method:: asUGenInput
 342 Returns:: the receiver
 343 discussion::
 344 This method is implemented in a number of classes in order to allow objects like link::Classes/Node::s, link::Classes/Bus::ses, and link::Classes/Buffer::s to be passed directly as UGen inputs and link::Classes/Synth:: args.
 345
 346 method:: copy
 347 Returns:: the receiver.
 348 discussion::
 349 Thus UGen-dup effectively returns a reference to the original and is a convenient way to copy a mono signal to multiple channels.
 350 code::
 351 { SinOsc.ar(Rand(200, 4000), 0, 0.2).dup }.plot // this is the same UGen
 352 ::
 353 Function-dup evaluates that function multiple times, thus potentially returning distinct UGens.
 354 code::
 355 { { SinOsc.ar(Rand(200, 4000), 0, 0.2) }.dup }.plot // these are different UGens
 356 ::
 357
 358
 359 subsection:: Internally used instance methods
 360
 361 method:: methodSelectorForRate
 362 See link::#*methodSelectorForRate::
 363
 364 method:: init
 365 By default, this method stores the inputs (e.g. the arguments to code::*ar:: and code::*kr::) in the UGen.
 366 discussion::
 367 This may be overridden to do other initialisations, as long as the inputs are set correctly.
 368