GenericGlobalControl | SuperCollider 3.13.0 Help

Description

GenericGlobalControl is a placeholder for a numeric value, synchronized between the language and the server. Because it is synchronized, it may be used interchangeably in math operations, patterns and synths.

GenericGlobalControl supports the following uses (assuming g is a GenericGlobalControl):

GUI -- Use .gui to embed the GenericGlobalControl in a crucial-library style GUI. Also, a GenericGlobalControl sends a notification to dependents when its value changes, so you can easily use it as a model in your own Model-View-Controller (MVC) scheme.
Math -- GenericGlobalControl will try to respond to math ops by substituting the numeric value: g + 2 is the same as g.value + 2.
Patterns -- In patterns, GenericGlobalControls automatically convert themselves into streams: Pbind(\g, g) is the same as Pbind(\g, Pfunc { g.value }).
Synth arguments -- GenericGlobalControls automatically map the control bus: Synth(\default, [freq: g]) is the same as Synth(\default, [freq: g.asMap]).
SynthDefs -- GenericGlobalControl supports the kr message to read the bus with In (optionally wrapping itself in a Lag): SinOsc.ar(g) is the same as SinOsc.ar(In.kr(g.bus, 1)).

GenericGlobalControl also supports automation, by playing a control-rate synth onto its bus.

Most methods are defined in GlobalControlBase, but documented here.

Notifications

GenericGlobalControl uses Events for notifications, so that additional data may be added later without breaking the argument signature, e.g.:this.changed((what: \value, updateGUI: updateGUI, resync: resync, updateBus: false));

Dependants' update methods traditionally receive object, what ... args. GenericGlobalControl notifications pass the event to what. Within the event, the \what key holds an identifier for the type of notification.g = GenericGlobalControl(\test, nil, 0, [0, 1]); c = Updater(g, { |object, what| switch(what[\what]) { \value } { ... do something appropriate for value changes... } { \modelWasFreed } { c.remove; // cleanup dependant }; });

GenericGlobalControl broadcasts the following notifications on state changes:

\value: When a new value is set. (what: \value, updateGUI: updateGUI, resync: resync, updateBus: false); use object.value to get the new value.
\modelWasFreed: Upon GenericGlobalControl: -free.
\spec: When the control spec is changed. (what: \spec, updateGUI: updateGUI).
\midi: When an associated MIDI control object is changed. (what: \midi).

Class Methods

.new

Create a new GenericGlobalControl. The server must be booted.

Arguments:

name	The name (generally a Symbol) to identify the value in GUIs.
bus	(Optional) You may provide a specific control bus -- as a Bus instance (a number is not allowed here). If `nil`, a control bus will be allocated for you on the default server. If you want to use a non-default server, you must provide a Bus instance.
value	The initial value: float or integer.
spec	A ControlSpec (or any object responding to `asSpec`), describing the range for the GUI slider.
allowGUI	For subclasses. If true, this control may appear in GUIs. If false, it may be omitted. VoicerGlobalControl uses this flag. GenericGlobalControl does not.
... extraArgs	For subclasses.

.defaultLag

The lag time assigned to new GenericGlobalControls during initialization. See GenericGlobalControl: -lag.

Returns:

The current default lag (float, in seconds).

Instance Methods

.free

Stop active automation, and release the control bus index. (Note: If automation is ongoing, the bus number will not be released until a /n_end message is received from the server indicating that the automation synth has stopped. This is to prevent the old automation synth from writing values onto a bus number that may be reassigned for another use.)

Arguments:

updateGUI

Deprecated argument. Not used.

.value

Get or set the control's value. Sends a \value notification.

.set

Set the control's value. (This is the implementation of the value_.) Stops any active automation, and sends a \value notification.

Arguments:

val	The new value (float or integer).
updateGUI	Internal use. Pass `false` if you want to suppress GUI updates.
latency	Optional. If a float is given, this is used as OSC messaging latency for the `/c_set` message that updates the control bus.
resync	A flag, passed on in the notification, telling associated MIDI controllers whether to reset any sync information.

.activeValue

A synonym for set.

Arguments:

v	The new value (float or integer).

.silentValue

Sets the GenericGlobalControl's language-side value variable, without touching the control bus or notifying any dependence (e.g. GUIs). Generally internal use only.

Arguments:

val	The new value (float or integer).

.setMsg

Constructs a /c_set message to update the control bus. Useful if you are building your own message bundles.

Arguments:

val	Deprecated argument. Not used.

Returns:

An array containing a /c_set message.

.unmappedValue

Get the control's value, normalized to the range 0-1.

State variables

.name

Get or set the name.

.bus

Get the control Bus instance.

.index

Get the bus number (integer).

.spec

Get or set the ControlSpec.

Arguments:

newSpec	A ControlSpec, or anything that responds to `.asSpec`.
updateGUI	Boolean. If true, notify dependants to update the display to match the new range.

.lag

Set the lag time to apply in the GenericGlobalControl: -kr method. New lag times apply only to new kr calls; they do not update previously-created SynthDefs (because the lag time is hardcoded).

.server

The bus's server.

.allowGUI

Get the flag that permits the control to be displayed, e.g., in a Voicer GUI.

Returns:

Boolean.

.active

Boolean. True if the GenericGlobalControl still exists in the server; false after it has been freed.

Conversions (type casting)

.asBus

Returns the control bus.

.asMap

Returns a mapping symbol for use in Synth argument lists. See Bus: -asMap.

.asMapArg

.asNodeArg

Synonyms for asMap.

.asPattern

Returns a Pattern, which polls the control's current value for every "next" call: Pfunc { this.value }.

.asStream

For convenience, returns a Stream based on the pattern from GenericGlobalControl: -asPattern -- this.asPattern.asStream.

.asControlInput

This method is called when preparing an argument list for Synth messaging -- so, it returns the mapping string as in GenericGlobalControl: -asMap.

.kr

Returns an In reading from the control bus. If the GenericGlobalControl's GenericGlobalControl: -lag is not nil, the In will be wrapped in a Lag for smoothing.

.asUGenInput

This method is called on all inputs to UGens -- so, it returns an In reading from the control bus as in kr.

Automation

A GenericGlobalControl can maintain a Synth to "automate" the control's value. This is not exactly the same thing as automation in a DAW, because it is not based on control points pinned to a timeline. (If you need to control points, you can play an EnvGen onto the control.)

.automate

Play a Synth or other object on the bus. Generally you should use this method, because it tracks the automation player. Also, if you already have automation running and you call automate, it will automatically stop the old automation player. This way is much better for safety.

Arguments:

thing	Anything that responds to `playOnGlobalControl(this, args, target, addAction)`. Currently supported are: String or Symbol: Play a `Synth(name)`. SynthDef: Play a `Synth(def.name)`. Function: Similar to `theFunction.play(target, this.bus, addAction: addAction, args: args)`. AbstractPlayer: Any kind of crucial library Patch or other player (but control rate only). `args` are ignored because they should have been given to the player. Instr: Also crucial library. Automatically makes a Patch (using the given arguments) and plays it.
args	Argument list.
target	The target for node positioning (default is the server's defaultGroup).
addAction	See Synth: *new.

Returns:

The new automation player, a Synth or crucial-library player, depending on the thing.

.autoSynth

As a getter, returns the current automation player.

As a setter, stops any currently running automation player and sets the autoSynth variable to the new node. Normally, you will not call autoSynth_ yourself; use GenericGlobalControl: -automate instead. However, there may be rare cases in which to create an automation player manually. In those cases, use autoSynth_ for tracking. Your player should respond to free.

.stopAuto

Stop any current automation.

.watch

"Watch" for value changes on the server's control bus. While automating, the global control's value is changing in the server; the language does not automatically synchronize (because this requires repeated server requests, and you might not need it).

watch adds the control bus to a KrBusWatcher and updates the control's value based on notifications from the bus watcher. The global control will also send \value notifications, for GUI updates.

Typical idiom: g.watch.automate({ ..... });.

Arguments:

count

Several objects might be interested in the control's "watching" status. count is the number of "watch-watchers" to add. At least 1 will always be added to the current count.

.stopWatching

Tells the global control that the caller is not interested in syncing to the server value anymore. The count of current "watch-watchers" will be decreased. When it reaches 0, the bus will be removed from the KrBusWatcher.

Arguments:

count

The number to subtract from the current count. If 0, it will hard-stop all watching. Otherwise, your client object should pass the same number that you passed earlier to watch.

.play

Simply plays the thing on the control's bus (using playOnGlobalControl). No tracking is done. You should consider this a private method: use GenericGlobalControl: -automate instead.

Examples

s.boot;

g = GenericGlobalControl(\freq, nil, 440, \freq);
g.gui;

a = Synth(\default, [freq: g]);
// ... and move the slider: 'freq' was mapped to g

a.release;

// 'g' is automatically converted to kr for use in VarSaw.ar()
a = { VarSaw.ar(g, mul: 0.1) ! 2 }.play;
a.release;
// zipper noise not good

g.lag = 0.1;  // set lag
// same function, but now 'g' is wrapped in a Lag
a = { VarSaw.ar(g, mul: 0.1) ! 2 }.play;
a.release;

g.lag = nil;

// 'g' as a pattern:
// value is sampled-and-held for each event
p = Pbind(
    \freq, g,
    \dur, Pwhite(1, 4, inf) * 0.25,
    \legato, 1.6
).play;

// 'watch' returns itself
// so it's easy to start watching and automate in one go
g.watch.automate({ LFDNoise3.kr(0.6).exprange(200, 600) });

// sample-and-hold continues

// faster screen updates:
KrBusWatcher.newFrom(s).updateFreq = 6;

p.stop;

// asMap in pattern: same value for all synths
// already-playing notes follow the control value
// for fun, faster = higher.
// note here that the server is generating freq values;
// 'watch' easily syncs these to the client and they are
// available for pattern calculations!
p = Pbind(
    \freq, g.asMap,
    \dur, g.asPattern.expexp(200, 600, 0.2, 0.08),
    \legato, 1.6
).play;

p.stop;

g.stopWatching.stopAuto;
g.free;

helpfile source: HelpSource/Classes/GenericGlobalControl.schelp
link::ddwCommon/Classes/GenericGlobalControl::

GenericGlobalControlExtension

.new

Arguments:

.defaultLag

Returns:

.free

Arguments:

.value

.set

Arguments:

.activeValue

Arguments:

.silentValue

Arguments:

.setMsg

Arguments:

Returns:

.unmappedValue

.name

.bus

.index

.spec

Arguments:

.lag

.server

.allowGUI

Returns:

.active

.asBus

.asMap

.asMapArg

.asNodeArg

.asPattern

.asStream

.asControlInput

.kr

.asUGenInput

.automate

Arguments:

Returns:

.autoSynth

.stopAuto

.watch

Arguments:

.stopWatching

Arguments:

.play

GenericGlobalControl
Extension