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 // set the source
  23 p[\out] = { SinOsc.ar([350, 351.3], 0, 0.2) };
  24 p[\out] = { Pulse.ar([350, 351.3] / 4, 0.4) * 0.2 };
  25 p[\out] = Pbind(\dur, 0.03, \freq, Pbrown(0, 1, 0.1, inf).linexp(0, 1, 200, 350));
  26
  27 p[\out] = { Ringz.ar(p[\in].ar, [350, 351.3] * 8, 0.2) * 4 };
  28 p[\in] = { Impulse.ar([5, 7]/2, [0, 0.5]) };
  29
  30 a.clear(3); // clear after 3 seconds
  31 b.clear(3);
  32 ::
  33
  34 ClassMethods::
  35
  36 private::initClass
  37
  38 subsection::Creation
  39
  40 method::new
  41
  42 argument::server
  43 a link::Classes/Server:: object. Note that on remote computers the clock must be in sync.
  44
  45 argument::name
  46 a link::Classes/Symbol::. If a name is given, the proxy space is strong::stored:: in code::ProxySpace.all:: under this name.
  47
  48 argument::clock
  49 for event-based or beat-sync playing use a link::Classes/TempoClock::.
  50
  51 method::push
  52 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).
  53
  54 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;::
  55
  56 method::pop
  57 restore the previous currentEnvironment
  58
  59 method::clearAll
  60 clear all registered spaces
  61
  62 InstanceMethods::
  63
  64 subsection::Play back and access
  65
  66 method::play
  67 returns a group that plays the link::Classes/NodeProxy:: at that strong::key::.
  68
  69 argument::key
  70 a link::Classes/Symbol::
  71
  72 argument::out
  73 output channel offset
  74
  75 argument::numChannels
  76 play this number of channels.
  77
  78 method::record
  79 returns a link::Classes/RecNodeProxy:: that records the NodeProxy at that key.
  80
  81 method::ar, kr
  82 returns a NodeProxy output that plays the NodeProxy at that key, to be used within a function used as input to a node proxy
  83
  84 method::wakeUp
  85 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).
  86
  87 method::fadeTime
  88 set the fadetime of all proxies as well as the default fade time
  89
  90 method::clock
  91 set the clock of all proxies as well as the default clock.
  92
  93 method::quant
  94 set the quant of all proxies as well as the default quant.
  95
  96 method::free
  97 free all proxies (i.e. free also the groups, do not stop the monitors)
  98
  99 method::release
 100 release all proxies (i.e. keep the groups running)
 101
 102 method::stop
 103 stop all proxies (stop only monitors, do not stop synths)
 104
 105 method::end
 106 end all proxies (free and stop the monitors)
 107
 108 method::clear
 109 clear the node proxy and remove it from the environment. this frees all buses. If a fadeTime is given, first fade out, then clear.
 110
 111 method::add
 112 add the ProxySpace to the repository (name required)
 113
 114 method::remove
 115 remove the ProxySpace from the repository
 116
 117 subsection::Setting the sources
 118
 119 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::.
 120
 121 method::put
 122 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::.
 123
 124 method::at
 125 Return the proxy source object at that key.
 126
 127 subsection::"garbage collecting"
 128
 129 method::clean
 130 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.
 131
 132 method::reduce
 133 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.
 134
 135 subsection::Coding
 136
 137 method::document
 138 creates a new document with the current proxyspace state. This does not allow open functions as proxy sources. see: link::Tutorials/JITLib/jitlib_asCompileString::.
 139
 140 argument::keys
 141 list of keys to document a subset of proxies
 142
 143 Examples::
 144
 145 code::
 146 // ProxySpace returns instances of NodeProxy:
 147 a = NodeProxy(s)        is equivalent to ~a;
 148 a.source = ...          is equivalent to ~a = ...
 149 a[3] = ...              is equivalent to ~a[3] = ...
 150
 151 // the two expressions are equivalent:
 152 ~out = something;
 153 currentEnvironment.put(\out, something);
 154 ::
 155
 156 code::
 157 // examples
 158
 159 p = ProxySpace.push(s.boot); // use ProxySpace as current environment.
 160
 161 ~out.play;
 162
 163 ~out = { SinOsc.ar([400, 407] * 0.9, 0, 0.2) };
 164
 165 ~out = { SinOsc.ar([400, 437] * 0.9, 0, 0.2) * LFPulse.kr([1, 1.3]) };
 166
 167 ~out = { SinOsc.ar([400, 437] * 0.9, 0, 0.2) * ~x.kr(2) };
 168
 169 ~x = { LFPulse.kr([1, 1.3] * MouseX.kr(1, 30, 1)) };
 170
 171 ~out = { SinOsc.ar([400, 437] * Lag.kr(0.1 + ~x, 0.3), 0, 0.2) * ~x };
 172
 173 p.fadeTime = 5;
 174
 175 ~out = { SinOsc.ar([400, 437] * 1.1, 0, 0.2) * ~x.kr(2) };
 176
 177 p.clear(8); // end and clear all in 8 sec.
 178
 179
 180 p.pop; // move out.
 181 ::