1class:: UGen 2summary:: Abstract superclass of all unit generators 3categories:: UGens, Server>Abstractions 4related:: Browse#UGens, Guides/Tour_of_UGens, Guides/UGens-and-Synths 5 6description:: 7 8UGens 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 10subsection:: Interface 11All UGens respond to one or more of the following class methods: 12list:: 13## code:: ar(arg1, arg2, ... ) :: 14## code:: kr(arg1, arg2, ... ) :: 15## code:: ir(arg1, arg2, ... ) :: 16:: 17 18They 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 20If 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. 21code:: 22{ Blip.ar(Blip.kr(4, 5, 500, 60), 59, 0.1) }.play; 23:: 24 25subsection:: Documentation of mul and add arguments 26 27A 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. 28Mul 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. 29In 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 31classmethods:: 32private:: categories 33 34method:: buildSynthDef 35Returns:: the SynthDef in which the UGen is situated. 36Discussion:: 37code:: 38{ UGen.buildSynthDef.dump; Silent.ar }.play; 39:: 40 41subsection:: Internally used class methods 42 43method:: multiNew 44These 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::. 45argument:: ... args 46The first argument is rate, then the rest of the arguments. code::(rate, ...args):: 47 48method:: multiNewList 49See link::#*multiNew::. 50argument:: args 51An array where the first argument is rate, then the rest of the arguments. code::([rate, ...args]):: 52 53method:: new1 54This method returns a single instance of the UGen, not multichannel expanded. It is called inside multiNewList, whenever a new single instance is needed. 55 56method:: methodSelectorForRate 57argument:: rate 58A link::Classes/Symbol::, code:: \audio, \control, \scalar :: 59Returns:: 60An appropriate message selector ( link::Classes/Symbol:: like code:: \ar, \kr, \ir :: ) for the given rate. 61 62method:: replaceZeroesWithSilence 63Returns:: 64A new link::Classes/Array::, where every zero is replaced by a link::Classes/Silent:: UGen. 65discussion:: 66This is required internally sometimes for UGens like link::Classes/Out::. 67 68instancemethods:: 69 70subsection:: Convenience Methods 71 72method:: scope 73 74Displays the output of this UGen in an individual link::Classes/Stethoscope:: window. 75argument::name 76The name of the window 77argument::bufsize 78Buffer size 79argument::zoom 80Zoom factor 81 82discussion:: 83code:: 84s.boot 85 86{ Ringz.ar(PinkNoise.ar([0.1, 0.2]).scope(\pink), 2000, 1, 0.25) }.play; // multichannel works 87s.scope; // can still separately scope the output of the server 88:: 89 90method:: poll 91 92Polls the output of this UGen every interval seconds, and posts the result. 93 94argument::trig 95Trig frequency 96argument::label 97A symbol to label the output 98argument::trigid 99Numerical ID 100discussion:: 101The 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. 102code:: 103{ SinOsc.ar(LFNoise0.ar(2).range(420, 460).poll(label: \LFNoise), 0, 0.2) }.play; 104 105// multichannel polling: 106( 107{ 108 var freqs = SinOsc.ar([0.2, 0.3]).range(420, 460); 109 freqs.poll(label: [\freq1, \freq2]); 110 SinOsc.ar(freqs, 0, 0.2); 111}.play; 112) 113:: 114 115 116method:: dpoll 117 118Like code::poll::, only that code::dpoll:: is used for Demand ugens. See link::Classes/Poll:: for more info on polling. 119 120method:: range 121 122Scales the output of this UGen to be within the range of code::lo:: and code::hi::. 123discussion:: 124Note that code::range:: expects the default output range, and thus should not be used in conjunction with mul and add arguments. 125code:: 126{ SinOsc.ar(SinOsc.ar(0.3).range(440, 660), 0, 0.5) * 0.1 }.play; 127:: 128 129method:: exprange 130 131Maps the output of this UGen exponentially to be within the range of code::lo:: and code::hi:: using a link::Classes/LinExp:: UGen. 132discussion:: 133code::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. 134code:: 135{ SinOsc.ar(SinOsc.ar(0.3).exprange(440, 6600), 0, 0.5) * 0.1 }.play; 136:: 137 138method:: curverange 139 140Scales the output of this UGen to be within the range of code::lo:: and code::hi:: using a curve factor of code::curve::. 141discussion:: 142Note that code::curverange:: expects the default output range, and thus should not be used in conjunction with mul and add arguments. 143code:: 144{ SinOsc.ar(SinOsc.ar(0.3).curverange(440, 660, -3), 0, 0.5) * 0.1 }.play; 145:: 146 147 148 149method:: unipolar 150 151Scales the output of this UGen to be between code::(0..mul):: range (default 1). 152discussion:: 153Note that code::unipolar:: expects the default output range, and thus should not be used in conjunction with mul and add arguments. 154code:: 155{ SinOsc.ar(300, 0, 0.5) * SinOsc.kr(2).unipolar * 0.1 }.play; 156:: 157 158method:: bipolar 159 160Scales the output of this UGen to be between code::(-mul..mul):: range (default 1). 161discussion:: 162Note that code::bipolar:: expects the default output range, and thus should not be used in conjunction with mul and add arguments. 163code:: 164{ SinOsc.ar(500 + LFPulse.ar(4).bipolar(40), 0, 0.5) * 0.1 }.play; 165:: 166 167method:: degrad 168Converts degrees to radians. This method multiplies the receiver's output by code::pi/180::. 169 170method:: raddeg 171Converts radians to degrees. This method multiplies the receiver's output by code::180/pi::. 172 173method:: clip 174Wraps the receiver in a link::Classes/Clip:: UGen, clipping its output at code::lo:: and code::hi::. 175 176method:: fold 177Wraps the receiver in a link::Classes/Fold:: UGen, folding its output at code::lo:: and code::hi::. 178 179method:: wrap 180Wraps the receiver in a link::Classes/Wrap:: UGen, wrapping its output at code::lo:: and code::hi::. 181 182method:: blend 183Blends code::this:: with code::that:: by wrapping the receiver in an link::Classes/XFade2:: (if code::this:: or code::that:: are audio-rate UGens) or link::Classes/LinXFade2:: UGen. 184note:: The code::blendFrac:: argument is between 0 and 1:: 185 186 187method:: lag 188Wraps 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. 189 190method:: lag2 191Wraps 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. 192 193method:: lag3 194Wraps 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. 195 196method:: lagud 197Wraps the receiver in a link::Classes/LagUD:: UGen, smoothing its output by code::lagtimeU:: and code::lagtimeD::. 198 199method:: lag2ud 200Wraps the receiver in a link::Classes/Lag2UD:: UGen, smoothing its output by code::lagtimeU:: and code::lagtimeD::. 201 202method:: lag3ud 203Wraps the receiver in a link::Classes/Lag3UD:: UGen, smoothing its output by code::lagtimeU:: and code::lagtimeD::. 204 205method:: varlag 206Wraps the receiver in a link::Classes/VarLag:: UGen, smoothing its output by code::time:: seconds. 207 208method:: slew 209Wraps the receiver in a link::Classes/Slew:: UGen, limiting the slope of its output. 210 211method:: degreeToKey 212 213Wraps the receiver in a link::Classes/DegreeToKey:: UGen. 214 215method:: minNyquist 216 217Wraps 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. 218 219method:: snap 220 221Wraps the receiver so that its values are rounded within code::margin:: distance from a multiple of code::resolution:: to a multiple of resolution. By using code::margin:: and code::strength:: you can control when values will be rounded, and by how much. See link::Classes/SimpleNumber#-snap:: for more details. 222 223This can be used to make control signals (e.g. from sensors) "snap" to defined resolution. Example: 224code:: 225s.boot; 226x = {SinOsc.ar((Line.kr(0, 10, 10).snap(1, 0.3, 1) + 60).poll.midicps, 0, -24.dbamp)}.play 227:: 228 229method:: softRound 230 231Wraps the receiver so that its values are rounded outside of code::margin:: distance from a multiple of code::resolution:: to a multiple of resolution. By using code::margin:: and code::strength:: you can control when values will be rounded, and by how much. See link::Classes/SimpleNumber#-softRound:: for more details. 232 233method:: linlin 234Wraps the receiver so that a linear input range is mapped to a linear output range. 235 236discussion:: 237The clip argument can be one of the four: 238table:: 239## code::nil:: || do not clip at outMin or outMax 240## code::\minmax:: || clip at outMin or outMax 241## code::\min:: || clip at outMin 242## code::\max:: || clip at outMax 243:: 244Example: 245code:: 246{ Line.ar(-1, 5, 0.1).linlin(0, 3, -1, 1) }.plot(0.1); 247 248// modulate some values 249( 250{ Line.ar(-1, 5, 0.1).lincurve(SinOsc.ar(100), SinOsc.ar(130) + 3, -1, 1, clip: nil) } 251 .plot(0.1, minval: -15, maxval: 5) 252) 253:: 254 255method:: linexp 256 257Wraps the receiver so that a linear inputrange is mapped to an exponential output range. 258discussion:: 259outMin and outMax must be nonzero and of the same sign. For clip argument, see code::linlin:: above. 260code:: 261{ Line.ar(-1, 5, 0.1).linexp(0, 3, 0.01, 1) }.plot(0.1); 262:: 263 264method:: explin 265 266Wraps the receiver so that an exponential inputrange is mapped to a linear output range. 267discussion:: 268inMin and inMax must be nonzero and of the same sign. For clip argument, see code::linlin:: above. 269code:: 270{ Line.ar(1, 5, 0.1).explin(1, 3, -1, 1) }.plot(0.1); 271:: 272 273method:: expexp 274 275Wraps the receiver so that an exponential inputrange is mapped to an exponential output range. 276discussion:: 277outMin, outMax, inMin and inMax must be nonzero and of the same sign. For clip argument, see code::linlin:: above. 278code:: 279{ Line.ar(1, 5, 0.1).expexp(1, 3, 0.01, 1) }.plot(0.1); 280:: 281 282method:: lincurve 283 284Wraps the receiver so that a linear inputrange is mapped to a curve-like exponential output range. 285discussion:: 286outMin and outMax may be zero and of the different sign. For clip argument, see code::linlin:: above. 287code:: 288{ Line.ar(-1, 5, 0.1).lincurve(0, 3, -1, 1, curve: -4) }.plot(0.1); 289 290// modulate the curve. Unlike with numbers and CurveSpec, the curve absolute value 291// should not be much smaller than 0.5. 292{ SinOsc.ar(100).lincurve(-1, 1, -1, 1, XLine.kr(-3, -100, 0.1)) * 0.1 }.plot(0.1); 293:: 294 295method:: curvelin 296Wraps the receiver so that a curve-like exponential inputrange is mapped to a linear output range. 297discussion:: 298inMin and inMax may be zero and of the different sign. For clip argument, see code::linlin:: above. 299code:: 300{ Line.ar(-1, 5, 0.1).curvelin(0, 3, -1, 1, curve: -4) }.plot(0.1); 301:: 302 303 304method:: bilin 305Map the receiver from two assumed linear input ranges (inMin..inCenter) and (inCenter..inMax) to two linear output ranges (outMin..outCenter) and (outCenter..outMax). If the input exceeds the input range, the following behaviours are specified by the clip argument. 306argument::inCenter 307argument::inMin 308assumed input minimum 309argument::inMax 310assumed input maximum 311argument::outCenter 312argument::outMin 313output minimum 314argument::outMax 315output maximum 316argument::clip 317nil (don't clip) 318\max (clip ceiling) 319\min (clip floor) 320\minmax (clip both - this is default). 321discussion:: 322code:: 323{Line.kr(0, 10, 0.1).bilin(1, 0, 10, 0.6, 0, 1)}.plot(0.1) 324:: 325 326 327method:: prune 328Limits the receiver range to one of the four clip modes, see code::linlin:: above. 329 330method:: checkBadValues 331Wraps the receiver in a link::Classes/CheckBadValues:: UGen with the corresponding code::id:: and code::post:: flag. 332 333method:: if 334Outputs 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. 335discussion:: 336This is implemented as: code::(this * (trueUGen - falseUGen)) + falseUGen):: 337 338Note that both trueUGen and falseUGen will be calculated regardless of whether they are output, so this may not be the most efficient approach. 339code:: 340// note different syntax in these two examples 341{ if( LFNoise1.kr(1.0, 0.5, 0.5) , SinOsc.ar, Saw.ar ) * 0.1 }.play; 342 343{ Trig1.ar(Dust.ar(3), 0.2).lag(0.1).if(FSinOsc.ar(440), FSinOsc.ar(880)) * 0.1 }.play; 344:: 345 346method:: @ 347Dynamic geometry support. Returns code::Point(this, y)::. 348discussion:: 349code:: 350{ (SinOsc.ar(1001) @ SinOsc.ar(1207)).rho }.scope; 351:: 352 353method:: asComplex 354Complex math support. Returns code::Complex(this, 0.0)::. 355 356method:: dumpArgs 357Posts a list of the arguments for this UGen and their values. 358 359 360subsection:: Other Instance Methods 361 362The 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. 363Users should not attempt to set any of these values in general code. 364 365method:: synthDef 366The SynthDef which contains the UGen. 367 368method:: inputs 369The array of inputs to the UGen. 370 371method:: rate 372The output rate of the UGen which is one of the link::Classes/Symbol::s code::\audio::, or code::\control::. 373 374method:: signalRange 375Returns:: A symbol indicating the signal range of the receiver. Either code::\bipolar:: or code::\unipolar::. 376 377method:: numChannels 378Returns:: The number of output channels. 379discussion:: 380For 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::. 381 382method:: numInputs 383Returns:: The number of inputs for this UGen. 384 385method:: numOutputs 386Returns:: The number of outputs for this UGen. 387 388method:: name 389Returns:: The Class name of the receiver as a link::Classes/String::. 390 391method:: madd 392Wraps the receiver in a link::Classes/MulAdd:: UGen. 393discussion:: 394This is for the most part only used in UGen class definitions in order to allow efficient implementation of code::mul:: and code::add:: arguments. 395 396method:: isValidUGenInput 397Returns:: true 398 399method:: asUGenInput 400Returns:: the receiver 401discussion:: 402This 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. 403 404method:: copy 405Returns:: the receiver. 406discussion:: 407Thus UGen-dup effectively returns a reference to the original and is a convenient way to copy a mono signal to multiple channels. 408code:: 409{ SinOsc.ar(Rand(200, 4000), 0, 0.2).dup }.plot // this is the same UGen 410:: 411Function-dup evaluates that function multiple times, thus potentially returning distinct UGens. 412code:: 413{ { SinOsc.ar(Rand(200, 4000), 0, 0.2) }.dup }.plot // these are different UGens 414:: 415 416 417subsection:: Internally used instance methods 418 419method:: methodSelectorForRate 420See link::#*methodSelectorForRate:: 421 422method:: init 423By default, this method stores the inputs (e.g. the arguments to code::*ar:: and code::*kr::) in the UGen. 424discussion:: 425This may be overridden to do other initialisations, as long as the inputs are set correctly. 426