HelpSource/Reference/softSet.schelp

   1 title:: softSet
   2 summary:: set a proxy param value conditionally
   3 categories:: Libraries>JITLib>GUI
   4 related:: Reference/softVol_, Reference/softPut
   5
   6 description::
   7 code::softSet:: is an extension method to link::Classes/NodeProxy:: and link::Classes/Ndef:: that sets a nodeproxy param value only in two conditions:
   8 list::
   9 ## if the new value is close enough to the current param value;
  10 ## or if the setting controller knows the previous value and sends it along. the idea here is that if the controller knows it did the last value change, it has authority to jump now.
  11 ::
  12 Typical uses would be switching to a preset, then using a faderbox, and avoiding sudden controller jumps that could occur (soft takeover).
  13
  14 method:: softSet (param, val, within = 0.025, mapped=false, lastVal, spec)
  15 argument:: param
  16 the name of the parameter to set
  17 argument:: val
  18 the value to set the param to (can be mapped or unmapped)
  19 argument:: within
  20 the normalized range within which the set is accepted - default is 0.025
  21 argument:: lastVal
  22 the previous value that a control has set - see last examples.
  23 argument:: mapped
  24 a flag whether strong::val:: is mapped (within the range of param.asSpec) or unmapped (0.0-1.0)
  25 argument:: spec
  26 a link::Classes/ControlSpec:: can be passed in. if nil, param.asSpec is used.
  27 note::
  28 if no spec is given, softSet simply allows setting.
  29 ::
  30
  31 examples::
  32 code::
  33 Ndef(\test, { |freq=200| Splay.ar(SinOsc.ar(freq * Array.rand(12, 0.95, 1.05))) });
  34 Ndef(\test).play(vol: 0.1);
  35
  36 Ndef(\test).gui(4)
  37
  38 Ndef(\test).set(\freq, 300);
  39
  40                 // 3 midi steps == 0.02362;
  41 Ndef(\test).softSet(\freq, 320, 0.03); // ok
  42 Ndef(\test).softSet(\freq, 280, 0.03); // ok
  43 Ndef(\test).softSet(\freq, 200, 0.03); // returns false if too big jump
  44
  45 Ndef(\test).set(\freq, 600);
  46
  47         // softSet can be risky - one can lose a parameter when moving a controller
  48         // too quickly. So, if we know the last value (e.g. because the same controller
  49         // knows it has set to that value), it is OK to jump:
  50 Ndef(\test).softSet(\freq, 330, 0.03, lastVal: 630);
  51
  52 Ndef(\test).softSet(\freq, rrand(300, 350), 0.01);      // sometimes yes, sometimes no
  53
  54
  55         // use unmapped, i.e. normalized values to set:
  56
  57 Ndef(\test).set(\freq, 600);    // ok
  58 Ndef(\test).softSet(\freq, 0.5, 0.05, mapped: false);   // ok
  59 Ndef(\test).softSet(\freq, 0.45, 0.03, mapped: false);  // no, too big
  60 Ndef(\test).softSet(\freq, 0.3, 0.03, mapped: false, lastVal: 0.5);     // but ok if lastVal is close
  61
  62
  63         // example of softSet, softSet which knows lastVal,
  64         // softVol_ and softVol_ which knows lastVol:
  65 (
  66 w = Window("softSet, softVol", Rect(500, 200, 400, 240)).front;
  67 w.view.addFlowLayout;
  68 NdefGui(Ndef(\test), 2, w);
  69
  70         // can lose control if wiggled too fast
  71 EZSlider(w, 340@30, \softSet, \freq, { |sl|
  72         Ndef(\test).softSet(\freq, sl.value, 0.05)
  73 });
  74
  75         // knows it was in control
  76 EZSlider(w, 340@30, \knowsLast, \freq, Routine { |sl|
  77         var newVal, lastVal;
  78         loop {
  79                 newVal = sl.value;
  80                 Ndef(\test).softSet(\freq, newVal, 0.05, lastVal: lastVal);
  81                 lastVal = newVal;
  82                 \dummy.yield;
  83         }
  84 });
  85
  86         // same for volume - not too safe
  87 EZSlider(w, 340@30, \softVol, \amp, { |sl|
  88         Ndef(\test).softVol_(sl.value, 0.05)
  89 });
  90         // safer
  91 EZSlider(w, 340@30, \knowLastV, \amp, Routine { |sl|
  92         var newVal, lastVal;
  93         loop {
  94                 newVal = sl.value;
  95                 Ndef(\test).softVol_(sl.value, 0.05, lastVal: lastVal);
  96                 lastVal = newVal;
  97                 \dummy.yield;
  98         }
  99 });
 100 )
 101 ::