HelpSource/Classes/EnvGen.schelp

   1 class:: EnvGen
   2 summary:: Envelope generator
   3 related:: Classes/Linen, Classes/Env
   4 categories::  UGens>Envelopes
   5
   6
   7 Description::
   8
   9 Plays back break point envelopes. The envelopes are instances of the
  10 link::Classes/Env:: class. The envelope and the arguments for  code::levelScale:: ,
  11 code::levelBias:: , and  code::timeScale::
  12 are polled when the EnvGen is triggered and remain constant for the
  13 duration of the envelope.
  14
  15
  16 classmethods::
  17
  18 method::ar, kr
  19
  20 argument::envelope
  21
  22 An link::Classes/Env:: instance, or an Array of Controls.
  23 (See link::Classes/Control::  and the example below for how to use
  24 this.)
  25
  26 The envelope is polled when the EnvGen is triggered. The Env inputs can be other UGens.
  27
  28
  29 argument::gate
  30
  31 This triggers the envelope and holds it open while > 0. If the
  32 Env is fixed-length (e.g. Env.linen, Env.perc), the gate argument
  33 is used as a simple trigger. If it is an sustaining envelope
  34 (e.g. Env.adsr, Env.asr), the envelope is held open until the
  35 gate becomes 0, at which point is released.
  36
  37 If strong::gate:: < 0, force release with time code:: -1.0 - gate ::, see link::#forced_release:: below.
  38
  39 argument::levelScale
  40
  41 Scales the levels of the breakpoints.
  42
  43
  44 argument::levelBias
  45
  46 Offsets the levels of the breakpoints.
  47
  48
  49 argument::timeScale
  50
  51 Scales the durations of the segments.
  52
  53
  54 argument::doneAction
  55
  56 An integer representing an action to be executed when the env is
  57 finished playing. This can be used to free the enclosing synth,
  58 etc. See link::Reference/UGen-doneActions::  for more detail.
  59
  60 discussion::
  61 note::
  62 The actual minimum duration of a segment is not zero, but one sample step for audio rate and one block for control rate. This may result in asynchronicity when in two envelopes of different number of levels, the envelope times add up to the same total duration. Similarly, when modulating times, the new time is only updated at the end of the current segment - this may lead to asynchronicity of two envelopes with modulated times.
  63 ::
  64
  65 Examples::
  66
  67 code::
  68 (
  69 SynthDef(\env_help, { | out, gate = 0 |
  70     var z;
  71     z = EnvGen.kr(Env.adsr, gate) * SinOsc.ar(440, 0, 0.1);
  72     Out.ar(out, z)
  73 }).add;
  74 )
  75
  76 a = Synth(\env_help);
  77
  78
  79 // turn on
  80 a.set(\gate, 1);
  81
  82 // turn off
  83 a.set(\gate, 0);
  84
  85 // it does not matter to what value the gate is set, as long as it is > 0
  86 a.set(\gate, 2);
  87
  88 a.free;
  89 ::
  90
  91 subsection:: Changing an Env while playing
  92 code::
  93 (
  94 SynthDef(\env, { arg i_outbus=0;
  95     var env, envctl;
  96
  97     // make a dummy 8 segment envelope
  98     env = Env.newClear(8);
  99
 100     // create a control argument array
 101     envctl = \env.kr( env.asArray );
 102
 103     ReplaceOut.kr(i_outbus, EnvGen.kr(envctl, doneAction: 2));
 104 }).add;
 105 )
 106
 107 (
 108 SynthDef(\sine, {
 109     Out.ar(0, SinOsc.ar(In.kr(0), 0, 0.2));
 110 }).add;
 111 )
 112
 113 s.sendMsg(\c_set, 0, 800);
 114
 115 s.sendMsg(\s_new, \sine, 1001, 1, 0);
 116
 117 e = Env([700, 900, 900, 800], [1, 1, 1]*0.4, \exp).asArray;
 118 s.sendBundle(nil, [\s_new, \env, 1002, 2, 1001], [\n_setn, 1002, \env, e.size] ++ e);
 119
 120 f = Env([1000, 1000, 800, 1000, 900, 1000], [1, 1, 1, 1, 1]*0.3, \step).asArray;
 121 s.sendBundle(nil, [\s_new, \env, 1003, 2, 1001], [\n_setn, 1003, \env, f.size] ++ f);
 122
 123 s.sendMsg(\n_free, 1001);
 124 ::
 125
 126 subsection:: Forced release
 127 If the gate of an EnvGen is set to -1 or below, then the envelope will cutoff immediately.
 128 The time for it to cutoff is the amount less than -1, with -1 being as fast as possible, -1.5 being a cutoff in 0.5 seconds, etc.
 129 The cutoff shape is linear.
 130 code::
 131 (
 132 SynthDef(\stealMe, { arg gate = 1;
 133     Out.ar(0, {BrownNoise.ar}.dup * EnvGen.kr(Env.asr, gate, doneAction:2))
 134 }).add;
 135 )
 136
 137 s.sendMsg(\s_new, \stealMe, 1001, 1, 0);
 138
 139 s.sendMsg(\n_set, 1001, \gate, -1.1); // cutoff in 0.1 seconds
 140 ::
 141 If the synthDef has an arg named "gate", the convenience method of Node can be used: code::node.release(releaseTime)::
 142 code::
 143 d = { arg gate=1; {BrownNoise.ar}.dup * EnvGen.kr(Env.asr, gate, doneAction:2) }.play;
 144 d.release(3);
 145 ::
 146
 147 subsection:: Fast triggering tests
 148 code::
 149 (
 150 {
 151     EnvGen.kr(
 152         Env.new([ 0.001, 1, 0.5, 0 ], [ 0.01, 0.3, 1 ], -4, 2, nil),
 153         Impulse.kr(10)
 154     ) * SinOsc.ar(440, 0, 0.1)
 155 }.play;
 156 )
 157
 158 (
 159 {
 160     EnvGen.kr(
 161         Env.perc( 0.1, 0.0, 0.5, 1, \welch ),
 162         Impulse.kr(100),
 163         timeScale: 0.1
 164     ) * SinOsc.ar(440, 0, 0.3)
 165 }.play;
 166 )
 167 ::
 168
 169 subsection:: Modulating the levelScale
 170 code::
 171 // no, it doesn't take a ugen in
 172 (
 173 {
 174     EnvGen.kr(
 175         Env.asr( 0.1, 1.0, 0.5, \welch ),
 176         1.0,
 177         FSinOsc.ar(1.0).range(0.0, 1.0),
 178         timeScale: 0.1
 179     ) * SinOsc.ar(440, 0, 0.3)
 180 }.play;
 181 )
 182
 183 // an .ir rate input, a float or an ir rate ugen like Rand would work
 184 (
 185 {
 186     EnvGen.kr(
 187         Env.asr( 0.1, 1.0, 0.5, \welch ),
 188         1.0,
 189         Rand(0.1, 1.0),
 190         timeScale: 0.1
 191     ) * SinOsc.ar(440, 0, 0.3)
 192 }.play;
 193 )
 194 ::
 195