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:: degreeToKey
 189
 190 Wraps the receiver in a link::Classes/DegreeToKey:: UGen.
 191
 192 method:: minNyquist
 193
 194 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.
 195
 196 method:: linlin
 197 Wraps the receiver so that a linear input range is mapped to a linear output range.
 198
 199 discussion::
 200 The clip argument can be one of the four:
 201 table::
 202 ## code::nil:: || do not clip at outMin or outMax
 203 ## code::\minmax:: || clip at outMin or outMax
 204 ## code::\min:: || clip at outMin
 205 ## code::\max:: || clip at outMax
 206 ::
 207 Example:
 208 code::
 209 { Line.ar(-1, 5, 0.1).linlin(0, 3, -1, 1) }.plot(0.1);
 210
 211 // modulate some values
 212 (
 213 { Line.ar(-1, 5, 0.1).lincurve(SinOsc.ar(100), SinOsc.ar(130) + 3, -1, 1, clip: nil) }
 214     .plot(0.1, minval: -15, maxval: 5)
 215 )
 216 ::
 217
 218 method:: linexp
 219
 220 Wraps the receiver so that a linear inputrange is mapped to an exponential output range.
 221 discussion::
 222 outMin and outMax must be nonzero and of the same sign. For clip argument, see code::linlin:: above.
 223 code::
 224 { Line.ar(-1, 5, 0.1).linexp(0, 3, 0.01, 1) }.plot(0.1);
 225 ::
 226
 227 method:: explin
 228
 229 Wraps the receiver so that an exponential inputrange is mapped to a linear output range.
 230 discussion::
 231 inMin and inMax must be nonzero and of the same sign. For clip argument, see code::linlin:: above.
 232 code::
 233 { Line.ar(1, 5, 0.1).explin(1, 3, -1, 1) }.plot(0.1);
 234 ::
 235
 236 method:: expexp
 237
 238 Wraps the receiver so that an exponential inputrange is mapped to an exponential output range.
 239 discussion::
 240 outMin, outMax, inMin and inMax must be nonzero and of the same sign. For clip argument, see code::linlin:: above.
 241 code::
 242 { Line.ar(1, 5, 0.1).expexp(1, 3, 0.01, 1) }.plot(0.1);
 243 ::
 244
 245 method:: lincurve
 246
 247 Wraps the receiver so that a linear inputrange is mapped to a curve-like exponential output range.
 248 discussion::
 249 outMin and outMax may be zero and of the different sign. For clip argument, see code::linlin:: above.
 250 code::
 251 { Line.ar(-1, 5, 0.1).lincurve(0, 3, -1, 1, curve: -4) }.plot(0.1);
 252
 253 // modulate the curve. Unlike with numbers and CurveSpec, the curve absolute value
 254 // should not be much smaller than 0.5.
 255 { SinOsc.ar(100).lincurve(-1, 1, -1, 1, XLine.kr(-3, -100, 0.1)) * 0.1 }.plot(0.1);
 256 ::
 257
 258 method:: curvelin
 259 Wraps the receiver so that a  curve-like exponential inputrange is mapped to a linear output range.
 260 discussion::
 261 inMin and inMax may be zero and of the different sign. For clip argument, see code::linlin:: above.
 262 code::
 263 { Line.ar(-1, 5, 0.1).curvelin(0, 3, -1, 1, curve: -4) }.plot(0.1);
 264 ::
 265
 266 method:: prune
 267 Limits the receiver range to one of the four clip modes, see code::linlin:: above.
 268
 269 method:: checkBadValues
 270 Wraps the receiver in a link::Classes/CheckBadValues:: UGen with the corresponding code::id:: and code::post:: flag.
 271
 272 method:: if
 273 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.
 274 discussion::
 275 This is implemented as: code::(this * (trueUGen - falseUGen)) + falseUGen)::
 276
 277 Note that both trueUGen and falseUGen will be calculated regardless of whether they are output, so this may not be the most efficient approach.
 278 code::
 279 // note different syntax in these two examples
 280 { if( LFNoise1.kr(1.0, 0.5, 0.5) , SinOsc.ar, Saw.ar ) * 0.1 }.play;
 281
 282 { Trig1.ar(Dust.ar(3), 0.2).lag(0.1).if(FSinOsc.ar(440), FSinOsc.ar(880)) * 0.1 }.play;
 283 ::
 284
 285 method:: @
 286 Dynamic geometry support. Returns code::Point(this, y)::.
 287 discussion::
 288 code::
 289 { (SinOsc.ar(1001) @ SinOsc.ar(1207)).rho }.scope;
 290 ::
 291
 292 method:: asComplex
 293 Complex math support. Returns code::Complex(this, 0.0)::.
 294
 295 method:: dumpArgs
 296 Posts a list of the arguments for this UGen and their values.
 297
 298
 299 subsection:: Other Instance Methods
 300
 301 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.
 302 Users should not attempt to set any of these values in general code.
 303
 304 method:: synthDef
 305 The SynthDef which contains the UGen.
 306
 307 method:: inputs
 308 The array of inputs to the UGen.
 309
 310 method:: rate
 311 The output rate of the UGen which is one of the link::Classes/Symbol::s code::\audio::, or code::\control::.
 312
 313 method:: signalRange
 314 Returns:: A symbol indicating the signal range of the receiver. Either code::\bipolar:: or code::\unipolar::.
 315
 316 method:: numChannels
 317 Returns:: The number of output channels.
 318 discussion::
 319 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::.
 320
 321 method:: numInputs
 322 Returns:: The number of inputs for this UGen.
 323
 324 method:: numOutputs
 325 Returns:: The number of outputs for this UGen.
 326
 327 method:: name
 328 Returns:: The Class name of the receiver as a link::Classes/String::.
 329
 330 method:: madd
 331 Wraps the receiver in a link::Classes/MulAdd:: UGen.
 332 discussion::
 333 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.
 334
 335 method:: isValidUGenInput
 336 Returns:: true
 337
 338 method:: asUGenInput
 339 Returns:: the receiver
 340 discussion::
 341 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.
 342
 343 method:: copy
 344 Returns:: the receiver.
 345 discussion::
 346 Thus UGen-dup effectively returns a reference to the original and is a convenient way to copy a mono signal to multiple channels.
 347 code::
 348 { SinOsc.ar(Rand(200, 4000), 0, 0.2).dup }.plot // this is the same UGen
 349 ::
 350 Function-dup evaluates that function multiple times, thus potentially returning distinct UGens.
 351 code::
 352 { { SinOsc.ar(Rand(200, 4000), 0, 0.2) }.dup }.plot // these are different UGens
 353 ::
 354
 355
 356 subsection:: Internally used instance methods
 357
 358 method:: methodSelectorForRate
 359 See link::#*methodSelectorForRate::
 360
 361 method:: init
 362 By default, this method stores the inputs (e.g. the arguments to code::*ar:: and code::*kr::) in the UGen.
 363 discussion::
 364 This may be overridden to do other initialisations, as long as the inputs are set correctly.
 365