HelpSource/Classes/NamedControl.schelp

   1 class:: NamedControl
   2 categories:: UGens>Synth control
   3 summary:: Named reference to a control
   4 related:: Classes/ControlName, Classes/Control
   5
   6 description::
   7
   8 A NamedControl directly combines a ControlName and a Control UGen conveniently. Also this makes it safe even if several identical controls exist (see example below).
   9
  10 There are syntax shortcuts that generate NamedControls from the name:
  11 code::
  12 \name.ar(values, lags)
  13 \name.kr(values, lags, fixedLag)
  14 \name.ir(values, lags)
  15 \name.tr(values, lags)
  16 ::
  17
  18 ClassMethods::
  19 method:: ar
  20 add a new instance of link::Classes/AudioControl:: with given name and default values.
  21 If lags are given, apply a Lag UGen to it.
  22 discussion::
  23 code::\symbol.ar(values, lags):: is a synonym.
  24
  25 method:: kr
  26 add a new instance of link::Classes/Control:: (kr) with given name and default values.
  27 If lags are given, apply a link::Classes/Lag:: UGen to it. If fixedLag is set to true, create a link::Classes/LagControl::
  28 (lags cannot be modulated then, but fewer UGens are required).
  29 discussion::
  30 code::\symbol.kr(values, lags, fixedLag):: is a synonym.
  31
  32 method:: ir
  33 add a new instance of link::Classes/Control:: (ir) with given name and default values.
  34 If lags are given, apply a link::Classes/Lag:: UGen to it.
  35 discussion::
  36 code::\symbol.ir(values, lags):: is a synonym.
  37
  38 method:: tr
  39 add a new instance of link::Classes/TrigControl:: with given name and default values.
  40 If lags are given, apply a link::Classes/Lag:: UGen to it.
  41 discussion::
  42 code::\symbol.tr(values, lags):: is a synonym.
  43
  44 method:: new
  45 add a new instance with the given rate, name and default values.
  46 If lags are given, apply a link::Classes/Lag:: UGen to it. If fixedLag is set to true, create a link::Classes/LagControl::
  47 (lags cannot be modulated then, but fewer UGens are required).
  48
  49 Examples::
  50 code::
  51 // use NamedControl to create a number of multichannel controls:
  52
  53 a = { SinOsc.ar(NamedControl.kr(\freq, [300, 330, 370], [1, 0.3, 0.02])).sum * 0.1 }.play;
  54 a.setn(\freq, [700, 705, 890]);
  55 a.setn(\freq, [0, 2, 5].midiratio * 400);
  56
  57 // synonymous:
  58 a = { SinOsc.ar(\freq.kr([300, 330, 370], [1, 0.3, 0.02])).sum * 0.1 }.play;
  59
  60 // multiple usage of the same name:
  61 a = { SinOsc.ar(\freq.kr(440, 3.5)) + Saw.ar(\freq.kr(440, 0.05) * 0.5) * 0.1 }.play;
  62
  63
  64 a.set(\freq, 1220)
  65 a.set(\freq, 120)
  66 ::
  67
  68 subsection:: Comparison with direct use of Controls
  69
  70 In the situation when functions are used to combine UGens to more complex SynthDefs, it may not be known which ControlNames are already taken by others. NamedControl allows to reuse existing control names.
  71 code::
  72 // compare:
  73 (
  74 a = {
  75         var x, y;
  76         x = NamedControl.kr(\freq, 440, 3.5);
  77         y = NamedControl.kr(\freq, 440, 1);
  78         SinOsc.ar([x, y] * [2, 1.2]) * 0.1
  79 }.play;
  80 )
  81
  82 a.set(\freq, 1220)
  83 a.set(\freq, 120)
  84
  85 (
  86 a = {
  87         var x, y;
  88         x = Control.names([\freq]).kr(440).lag(3.5);
  89         y = Control.names([\freq]).kr(440).lag(1);
  90         SinOsc.ar([x, y] * [2, 1.2]) * 0.1
  91 }.play;
  92 )
  93
  94 a.set(\freq, 1220)
  95 a.set(\freq, 120)
  96 ::
  97
  98 subsection:: Using dictionary with functions to build SynthDefs
  99 Here is a basic example using a dictionary with functions that can be combined to build SynthDefs.
 100 code::
 101 (
 102 q = ();
 103 q.makeEnv = { |q, env, doneAction = 0| EnvGen.kr(env, NamedControl.kr(\gate, 1), doneAction: doneAction) };
 104 q.chooseNoise = { [ {PinkNoise.ar}, {WhiteNoise.ar}, {LFNoise2.ar(Rand(100, 1000))}].choose.value};
 105 q.filterInput = { |q, in| [
 106         { BPF.ar(in * 15, NamedControl.kr(\freq, 800), 0.2) },
 107         { RHPF.ar(in, NamedControl.kr(\freq, 800, 0.2), 0.2) }
 108         ].choose.value
 109 };
 110 )
 111
 112 // test the envelope:
 113 a = { SinOsc.ar(440) * q.makeEnv(Env.asr, 2) * 0.1 }.play;
 114 a.set(\gate, -3); // release in 3 seconds
 115
 116 // single channel:
 117 a = { q.chooseNoise * q.makeEnv(Env.asr, 2) }.play;
 118 a.set(\gate, -3); // release in 3 seconds
 119
 120 a = { q.filterInput(q.chooseNoise) * q.makeEnv(Env.asr, 2) }.play;
 121 a.set(\freq, 1000); // set filter frequency
 122 a.set(\gate, -3); // release in 3 seconds
 123
 124 (
 125 a = {
 126         var channels = Array.fill(8, {
 127                 q.filterInput(q.chooseNoise) * q.makeEnv(Env.asr, 2)
 128         });
 129         Splay.ar(channels);
 130
 131 }.play;
 132 )
 133 a.set(\freq, 6000); // set filter frequency
 134 a.set(\gate, -3); // release in 3 seconds
 135 ::
 136