HelpSource/Classes/ProxySpace.schelp

   1 class:: ProxySpace
   2 summary:: an environment of references on a server
   3 categories:: Libraries>JITLib>Environments
   4 related:: Classes/NodeProxy, Classes/ProxyMixer, Overviews/JITLib
   5
   6 description::
   7 Generally a strong::proxy:: is a placeholder for something. A node proxy is a placeholder for something strong::playing on a server:: that writes to a limited number of busses (e.g. a synth or an event stream). NodeProxy objects can be replaced and recombined while they play. Also they can be used to build a larger structure which is used and modified later on. Overview: link::Overviews/JITLib::
   8
   9 When accessed, ProxySpace returns a link::Classes/NodeProxy::. A similar class without environment: link::Classes/Ndef::
  10
  11 For more examples see: link::Tutorials/JITLib/proxyspace_examples::, link::Tutorials/JITLib/jitlib_basic_concepts_01::
  12
  13 For GUI overview, see link::Classes/ProxyMixer::. See link::Classes/NodeProxy:: for many relevant methods.
  14
  15 subsection::First Example
  16
  17 code::
  18 s.boot;
  19
  20 p = ProxySpace.new;
  21 p.fadeTime = 2; // fadeTime specifies crossfade
  22 p[\out].play; // monitor an empty placeholder through hardware ouput
  23 // set its source
  24 p[\out] = { SinOsc.ar([350, 351.3], 0, 0.2) };
  25 p[\out] = { Pulse.ar([350, 351.3] / 4, 0.4) * 0.2 };
  26 p[\out] = Pbind(\dur, 0.03, \freq, Pbrown(0, 1, 0.1, inf).linexp(0, 1, 200, 350));
  27
  28 // route one proxy through another:
  29 p[\out] = { Ringz.ar(p[\in].ar, [350, 351.3] * 8, 0.2) * 4 };
  30 p[\in] = { Impulse.ar([5, 7]/2, [0, 0.5]) };
  31
  32 a.clear(3); // clear after 3 seconds
  33 b.clear(3);
  34 ::
  35
  36 ClassMethods::
  37
  38 private::initClass
  39
  40 subsection::Creation
  41
  42 method::new
  43
  44 argument::server
  45 a link::Classes/Server:: object. Note that on remote computers the clock must be in sync.
  46
  47 argument::name
  48 a link::Classes/Symbol::. If a name is given, the proxy space is strong::stored:: in code::ProxySpace.all:: under this name.
  49
  50 argument::clock
  51 for event-based or beat-sync playing use a link::Classes/TempoClock::.
  52
  53 method::push
  54 replace the currentEnvironment with a new ProxySpace and strong::clear:: the current one, if it is a ProxySpace (this is to avoid piling up proxy spaces).
  55
  56 In order to move to another ProxySpace while keeping the current, use strong::pop:: and then strong::push:: a new one. To have multiple levels of proxy spaces, use strong::.new.push;::
  57
  58 method::pop
  59 restore the previous currentEnvironment
  60
  61 method::clearAll
  62 clear all registered spaces
  63
  64 InstanceMethods::
  65
  66 subsection::Play back and access
  67
  68 method::play
  69 returns a group that plays the link::Classes/NodeProxy:: at that strong::key::.
  70
  71 argument::key
  72 a link::Classes/Symbol::
  73
  74 argument::out
  75 output channel offset
  76
  77 argument::numChannels
  78 play this number of channels.
  79
  80 method::record
  81 returns a link::Classes/RecNodeProxy:: that records the NodeProxy at that key.
  82
  83 method::ar, kr
  84 returns a NodeProxy output that plays the NodeProxy at that key, to be used within a function used as input to a node proxy
  85
  86 method::wakeUp
  87 when the proxyspace is created without a running server this method can be used. To run it (internally this is done by link::#-play:: as well).
  88
  89 method::fadeTime
  90 set the fadetime of all proxies as well as the default fade time
  91
  92 method::clock
  93 set the clock of all proxies as well as the default clock.
  94
  95 method::quant
  96 set the quant of all proxies as well as the default quant.
  97
  98 method::free
  99 free all proxies (i.e. free also the groups, do not stop the monitors)
 100
 101 method::release
 102 release all proxies (i.e. keep the groups running)
 103
 104 method::stop
 105 stop all proxies (stop only monitors, do not stop synths)
 106
 107 method::end
 108 end all proxies (free and stop the monitors)
 109
 110 method::clear
 111 clear the node proxy and remove it from the environment. this frees all buses. If a fadeTime is given, first fade out, then clear.
 112
 113 method::add
 114 add the ProxySpace to the repository (name required)
 115
 116 method::remove
 117 remove the ProxySpace from the repository
 118
 119 subsection::Setting the sources
 120
 121 The strong::rate:: and strong::numChannels:: of the link::Classes/NodeProxy:: determined in a lazy way from the first object put into this environment (see helpfile). Once it is created it can only be set to a function that returns the same rate and a number of channels equal to the intial one or smaller. For details, see link::Tutorials/JITLib/the_lazy_proxy::.
 122
 123 method::put
 124 Gets the NodeProxy at strong::key:: (if none exists, returns a new one) and sets its source to strong::obj::. For how this works, see also link::Classes/LazyEnvir:: and link::Classes/NodeProxy::.
 125
 126 method::at
 127 Return the proxy source object at that key.
 128
 129 subsection::"garbage collecting"
 130
 131 method::clean
 132 free and remove all proxies that are not needed in order to play the ones passed in with 'exclude'. if none are passed in, all proxies that are monitoring (with the .play message) are kept as well as their parents etc.
 133
 134 method::reduce
 135 free all proxies that are not needed in order to play the ones passed in with 'to'. if none are passed in, all proxies that are monitored (with the play message) are kept as well as their parents etc.
 136
 137 subsection::Coding
 138
 139 method::document
 140 creates a new document with the current proxyspace state. This does not allow open functions as proxy sources. see: link::Tutorials/JITLib/jitlib_asCompileString::.
 141
 142 argument::keys
 143 list of keys to document a subset of proxies
 144
 145 argument::onlyAudibleOutput
 146 a boolean.
 147
 148 argument::includeSettings
 149 a boolean.
 150
 151 Examples::
 152
 153 code::
 154 // ProxySpace returns instances of NodeProxy:
 155 a = NodeProxy(s)        is equivalent to ~a;
 156 a.source = ...          is equivalent to ~a = ...
 157 a[3] = ...              is equivalent to ~a[3] = ...
 158
 159 // the two expressions are equivalent:
 160 ~out = something;
 161 currentEnvironment.put(\out, something);
 162 ::
 163
 164 code::
 165 // examples
 166
 167 p = ProxySpace.push(s.boot); // use ProxySpace as current environment.
 168
 169 ~out.play;
 170
 171 ~out = { SinOsc.ar([400, 407] * 0.9, 0, 0.2) };
 172
 173 ~out = { SinOsc.ar([400, 437] * 0.9, 0, 0.2) * LFPulse.kr([1, 1.3]) };
 174
 175 ~out = { SinOsc.ar([400, 437] * 0.9, 0, 0.2) * ~x.kr(2) };
 176
 177 ~x = { LFPulse.kr([1, 1.3] * MouseX.kr(1, 30, 1)) };
 178
 179 ~out = { SinOsc.ar([400, 437] * Lag.kr(0.1 + ~x, 0.3), 0, 0.2) * ~x };
 180
 181 p.fadeTime = 5;
 182
 183 ~out = { SinOsc.ar([400, 437] * 1.1, 0, 0.2) * ~x.kr(2) };
 184
 185 p.clear(8); // end and clear all in 8 sec.
 186
 187
 188 p.pop; // move out.
 189 ::