SoftSet | SuperCollider 3.13.0 Help

Description

SoftSet is intended for letting a controller set a numerical parameter of an object politely. The common problem is that when a controller is newly assigned to a process parameter, the physical position can differ widely from the current param value in the process/object, which would create undesirable large parameter jumps when moving the controller.

SoftSet solves this by considering whether the new value is acceptable: if the new value is close enough to the current value in the object, or if the previous value of the controller is close enough to the current value of the process param (which implies that the object was last set from this controller, so the controller conceptually 'owns' it now), it is considered OK to set.

SoftSet returns a boolean whether the set message was accepted.// Some Basic Examples : // make an Ndef and set values for its parameters. Ndef(\a).clear; Ndef(\a).gui.moveTo(0, 400).skipjack.dt = 0.05; s.boot; // freq does not have a value yet, so you can set it SoftSet(Ndef(\a), \freq, 200); // try to set to a far away value - it will not change SoftSet(Ndef(\a), \freq, 2000); // close enough (within unipolar distance of 0.1) will set SoftSet(Ndef(\a), \freq, 219, within: 0.1); // now put in a sound process that uses \freq: Ndef(\a, { Ringz.ar(PinkNoise.ar, \freq.kr(440).lag(0.1), 0.3) }).play; // See examples below for how to use this in controllers, // but first see their different behaviors with sliders here: ( var w = Window("SoftSet - compare 4 Variants", Rect(10,300, 400, 600)).front; var lastVal, lastValUni, dim = 380@40; w.addFlowLayout; StaticText(w, dim).string_("Set SoftSet classvar defaultWithin: this is the unipolar range within which a destination's parameter will be set."); EZSlider(w, dim, 'SoftSet-defaultWithin', [0.01, 0.2, \exp], { |sl| SoftSet.defaultWithin = sl.value; }, 0.03, true, labelWidth: 150); StaticText(w, dim).string_("SoftSet(name, val) only depends on 'within' closeness - control connection is lost when jumps are too big (moving slider too fast)." ); EZSlider(w, dim, 'SoftSet(name, val)', \freq, { |sl| SoftSet(Ndef(\a), \freq, sl.value); }, labelWidth: 150); StaticText(w, dim).string_("SoftSet.uni(name, normVal) without a lastVal can also lose connection with big jumps." ); EZSlider(w, dim, 'SoftSet.uni()', nil, { |sl| SoftSet.uni(Ndef(\a), \freq, sl.value); }, labelWidth: 150); StaticText(w, dim).string_("SoftSet(name, val, lastVal) remains connected even with big jumps, unless something else sets the param to a value outside 'within'." ); EZSlider(w, dim, 'SoftSet with lastVal', \freq, { |sl| [\last, lastVal, \new, sl.value].postln; SoftSet(Ndef(\a), \freq, sl.value, lastVal: lastVal); lastVal = sl.value; }, labelWidth: 150); StaticText(w, dim).string_("SoftSet.uni(name, val, ... lastVal) also remains tightly connected once value has been within range." ); EZSlider(w, dim, 'Soft.uni with lastVal', nil, { |sl| SoftSet.uni(Ndef(\a), \freq, sl.value, lastVal: lastValUni); lastValUni = sl.value; }, labelWidth: 150); StaticText(w, dim).string_("Example destination: Ndef('a'), param: 'freq'" ); NdefGui(Ndef(\a), 3, w, 380@40); )

Class Methods

NOTE: SoftSet only has class methods, to be used as pseudo methods with multiple classes.

.new

SoftSet an object's parameters from a simple value. Convenient with e.g. sliders that use an appropriate parameter range.

Arguments:

obj	the object whose parameter is to be set
paramName	the name of the parameter to be set
value	the unipolar value to set it to, will be mapped by a spec
within	the range within which the value should match the current parameter value to allow the softset
lastVal	the last value which the controller has sent; this helps to determine whether the controller has done the last set of the param in question.
spec	a spec to use for calculation of the unipolar distance within which values should match.

Returns:

a Boolean whether the set has been accepted.

.uni

SoftSet an object's parameters from a unipolar value. Convenient with many controllers that use unipolar values. The mapping spec is done by the receiving object's spec for that param name.

Arguments:

obj	the object whose parameter is to be set
paramName	the name of the parameter to be set
value	the unipolar value to set it to, will be mapped by a spec
within	the range within which the value should match the current parameter value to allow the softset
lastVal	the last value which the controller has sent; this helps to determine whether the controller has done the last set of the param in question.

Returns:

a Boolean whether the set has been accepted.

.nextPair

same as *new, but does not do the setting yet. Instead it returns a pair of values if setting would be accepted, or nil if not. This is intended for collecting multiple name value pairs for a single set message.

Returns:

a pair of values if setting would be accepted, nil if not

.uniNextPair

Returns:

a pair of unipolar values if setting would be accepted, nil if not

.defaultWithin

gets and set a default value for unipolar distance within which softset is accepted.

.getSpec

ask an object for its spec for a given param name. this is used when no spec is given explicitly, and expects object to answer to getSpec.

Returns:

a spec

Examples

// tests: make an Ndef and set values for its parameters.

// clear first, so no settings remembered
Ndef(\a).clear;
Ndef(\a).gui.moveTo(0, 400).skipjack.dt = 0.05;

s.boot;
Ndef(\a, { Ringz.ar(PinkNoise.ar, \freq.kr(440).lag(0.1), 0.3) }).play;

// arguments to SoftSet.new are:
//// the object to set,
//// the paramName,
//// the new value to set it to,
//// within: the unipolar range within which to take over
//// lastVal: the last value the controller has sent to the object
//// spec: the spec to use for mapping

// try a big jump - too far way, so does not set, and returns false
SoftSet(Ndef(\a), \freq, 200, 0.025, nil, \freq);

// freq 500 is close to initial 440, so should be ok
SoftSet(Ndef(\a), \freq, 500, 0.025, nil, \freq);

// but if I know the lastVal coming from this controller, it does set.
// this is useful when the controller creates wide jumps,
// e.g. when making wild movements. if one just relies on proximity,
// one can 'lose' the control.
SoftSet(Ndef(\a), \freq, 500, 0.025, lastVal: 200); //
SoftSet(Ndef(\a), \freq, 1000, 0.025, lastVal: 500);

// a within value of 0.025 is 40 steps for the entire controller range.
// if you want a larger catching area, you can set it in the SoftSet call,
/// or globally like this:
SoftSet.defaultWithin = 0.1;

// If no spec is given, the object is asked to provide one via obj.getSpec

Ndef(\a).getSpec(\freq); // this finds the global default for freq;

SoftSet(Ndef(\a), \freq, 500 + 50.rand2);

// you can also give an Ndef a spec like this:
// this requires the JITLibExtensions quark ATM.
Ndef(\a).addSpec(\freq, [200, 2000]);
// now the spec is there:
Ndef(\a).getSpec(\freq, [200, 2000]);

// set by unipolar value, let object handle the spec
// this requires the object to understand getUni and getSpec calls.
Ndef(\a).get(\freq);
Ndef(\a).getUni(\freq);
Ndef(\a).getSpec(\freq);
SoftSet.uni(Ndef(\a), \freq, 0.45);

// as within is 0.025 by default, this is always in range:
SoftSet.uni(Ndef(\a), \freq, Ndef(\a).getUni(\freq) + 0.025.rand2);

Ndef(\a).addSpec(\freq, \freq);  // back to global default

// Later - implement a SoftSet method that supports multiple name/value pairs.

helpfile source: Modality/HelpSource/Classes/SoftSet.schelp
link::Modality-toolkit/Classes/SoftSet::

SoftSetExtension

Description

Class Methods

.new

Arguments:

Returns:

.uni

Arguments:

Returns:

.nextPair

Returns:

.uniNextPair

Returns:

.defaultWithin

.getSpec

Returns:

Examples

SoftSet
Extension