Help/Core/Ref.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <meta http-equiv="Content-Style-Type" content="text/css">
   6 <title></title>
   7 <meta name="Generator" content="Cocoa HTML Writer">
   8 <meta name="CocoaVersion" content="1038.25">
   9 <style type="text/css">
  10 p.p1 {margin: 0.0px 0.0px 0.0px 0.0px; font: 18.0px Helvetica}
  11 p.p2 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica}
  12 p.p3 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px}
  13 p.p4 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco}
  14 p.p5 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #5e3529}
  15 p.p6 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Monaco; min-height: 16.0px}
  16 p.p7 {margin: 0.0px 0.0px 0.0px 0.0px; font: 14.0px Helvetica}
  17 p.p8 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; min-height: 12.0px}
  18 p.p9 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #001db9}
  19 span.s1 {color: #1637a2}
  20 span.s2 {color: #000000}
  21 span.s3 {text-decoration: underline}
  22 span.s4 {font: 12.0px Monaco}
  23 span.s5 {color: #0000ff}
  24 span.s6 {color: #1637a4}
  25 span.s7 {color: #426f0e}
  26 span.s8 {color: #001db9}
  27 span.Apple-tab-span {white-space:pre}
  28 </style>
  29 </head>
  30 <body>
  31 <p class="p1"><b>Ref<span class="Apple-tab-span">       </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>a reference to a value</b></p>
  32 <p class="p2"><b>superclass: AbstractFunction</b></p>
  33 <p class="p3"><br></p>
  34 <p class="p2">A Ref holds an object which may be retrieved and altered with the messages <b>value </b>and <b>value_(obj)</b>.<span class="Apple-converted-space">   </span></p>
  35 <p class="p2">The backquote ` is a unary operator that is equivalent to calling Ref.new(obj).</p>
  36 <p class="p3"><br></p>
  37 <p class="p2">Refs are most commonly used to prevent <i>multi-channel </i>expansion in SynthDefs and Patterns (see <b>Klank </b>for an example).</p>
  38 <p class="p2">Refs can also be used to simplify the coding of co-routines used in EventStreams (see <b>Proutine </b>for an example).</p>
  39 <p class="p3"><br></p>
  40 <p class="p2">example:<span class="Apple-converted-space">   </span></p>
  41 <p class="p3"><br></p>
  42 <p class="p4">x = <span class="s1">Ref</span>(<span class="s1">nil</span>);</p>
  43 <p class="p5"><span class="s2">z = obj.method(x);<span class="Apple-tab-span">  </span><span class="Apple-tab-span">    </span></span>// method puts something in reference</p>
  44 <p class="p5"><span class="s2">x.value.doSomething;<span class="Apple-tab-span">        </span></span>// retrieve value and use it</p>
  45 <p class="p6"><br></p>
  46 <p class="p2">Ref is also used as a quoting device to protect against multi channel expansion in certain UGens that require Arrays.</p>
  47 <p class="p3"><br></p>
  48 <p class="p7"><b><span class="s3">Class methods:</span></b></p>
  49 <p class="p3"><br></p>
  50 <p class="p2"><b>new(anObject)</b></p>
  51 <p class="p3"><br></p>
  52 <p class="p2">create a Ref of an object.</p>
  53 <p class="p3"><br></p>
  54 <p class="p2"><b>`anObject</b></p>
  55 <p class="p3"><br></p>
  56 <p class="p2">create a Ref of an object.</p>
  57 <p class="p3"><br></p>
  58 <p class="p7"><b><span class="s3">Instance methods:</span></b></p>
  59 <p class="p3"><br></p>
  60 <p class="p2"><b>dereference</b></p>
  61 <p class="p3"><br></p>
  62 <p class="p2"><span class="Apple-tab-span">     </span>Answer the value. This message is also defined in class Object where it just returns the receiver.<span class="Apple-converted-space">  </span>Therefore <span class="s4">anything.dereference</span> will remove a Ref if there is one. This is slightly different than the value message, because value will also cause functions to evaluate themselves whereas dereference will not.</p>
  63 <p class="p3"><br></p>
  64 <p class="p2"><b>asRef</b></p>
  65 <p class="p3"><br></p>
  66 <p class="p2"><span class="Apple-tab-span">     </span>Answers the receiver. In class Object this message is defined to create a Ref of the object.</p>
  67 <p class="p3"><br></p>
  68 <p class="p2"><b>value</b></p>
  69 <p class="p3"><br></p>
  70 <p class="p2"><span class="Apple-tab-span">     </span>Returns value.</p>
  71 <p class="p3"><br></p>
  72 <p class="p2"><b>value_(aValue)</b></p>
  73 <p class="p3"><br></p>
  74 <p class="p2"><span class="Apple-tab-span">     </span>Sets value.</p>
  75 <p class="p3"><br></p>
  76 <p class="p2"><b>get</b></p>
  77 <p class="p3"><br></p>
  78 <p class="p2"><span class="Apple-tab-span">     </span>Returns value.</p>
  79 <p class="p3"><br></p>
  80 <p class="p2"><b>set(aValue)</b></p>
  81 <p class="p3"><br></p>
  82 <p class="p2"><span class="Apple-tab-span">     </span>Sets value.</p>
  83 <p class="p3"><br></p>
  84 <p class="p2"><b>at (index)</b></p>
  85 <p class="p2"><b><span class="Apple-tab-span">  </span></b>Returns value.at(index)</p>
  86 <p class="p3"><br></p>
  87 <p class="p2"><b>put(index, value)</b></p>
  88 <p class="p2"><b><span class="Apple-tab-span">  </span></b>Executes value.put(index, value)</p>
  89 <p class="p3"><span class="Apple-tab-span">     </span></p>
  90 <p class="p2"><b>seq(output)</b></p>
  91 <p class="p2"><b><span class="Apple-tab-span">  </span></b>this method is used to return values from within a Routine definition</p>
  92 <p class="p2"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>{ this.value = output.embedInStream(this.value); }</p>
  93 <p class="p3"><br></p>
  94 <p class="p2"><b>asUGenInput</b></p>
  95 <p class="p2"><b><span class="Apple-tab-span">  </span></b>Returns the Ref - this prevents multi-channel expansion in a SynthDef</p>
  96 <p class="p3"><span class="Apple-tab-span">     </span></p>
  97 <p class="p2"><b>asControlInput</b></p>
  98 <p class="p2"><b><span class="Apple-tab-span">  </span></b>Returns the value - this is used when sending a Ref as a control value to a server Node.</p>
  99 <p class="p3"><span class="Apple-tab-span">     </span></p>
 100 <p class="p2"><b>Typical uses of Ref:</b></p>
 101 <p class="p3"><br></p>
 102 <p class="p2"><b>preventing multi-channel expansion:</b></p>
 103 <p class="p8"><span class="Apple-tab-span">     </span></p>
 104 <p class="p2">Consult <a href="../Other Topics/MultiChannel.html"><span class="s5">MultiChannel</span></a> for details on multi-channel expansion in SynthDefs.</p>
 105 <p class="p3"><br></p>
 106 <p class="p2">Refs prevent multi-channel expansion in a SynthDef, so the array below defines one Klank UGen rather than three.</p>
 107 <p class="p3"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span></p>
 108 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>{ <span class="s6">Klank</span>.ar(`[[800, 1071, 1153, 1723], <span class="s6">nil</span>, [1, 1, 1, 1]], <span class="s6">Impulse</span>.ar(2, 0, 0.1)) }.play;</p>
 109 <p class="p8"><span class="Apple-tab-span">     </span></p>
 110 <p class="p8"><br></p>
 111 <p class="p2">Refs <span class="s3">cannot</span> be used reliably to suppress multi-channel expansion within Events and Patterns. <span class="Apple-converted-space"> </span></p>
 112 <p class="p2">Instead, it is necessary to enclose the array of values in another array:</p>
 113 <p class="p8"><br></p>
 114 <p class="p4">(</p>
 115 <p class="p9"><span class="s2"><span class="Apple-tab-span">    </span></span>SynthDef<span class="s2">(</span><span class="s7">\multi</span><span class="s2">, { </span>| out, freq = #[100,200,300], amp = 0.1, pan = 0, sustain = 1|</p>
 116 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="s8">var</span> audio, env;</p>
 117 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>env = <span class="s8">EnvGen</span>.kr(<span class="s8">Env</span>.perc(0.01, sustain), doneAction:2);</p>
 118 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>audio = <span class="s8">Mix</span>(<span class="s8">Saw</span>.ar(freq));</p>
 119 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>audio = <span class="s8">Pan2</span>.ar(audio * env, pan, amp);<span class="Apple-tab-span">     </span></p>
 120 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="s8">OffsetOut</span>.ar(out, audio)</p>
 121 <p class="p4"><span class="Apple-tab-span">     </span>}).add;</p>
 122 <p class="p8"><br></p>
 123 <p class="p4"><span class="Apple-tab-span">     </span>( instrument: \multi, freq: [ [500, 501, 700] ], sustain: 2).play</p>
 124 <p class="p8"><br></p>
 125 <p class="p4">)</p>
 126 <p class="p4">(</p>
 127 <p class="p9"><span class="s2"><span class="Apple-tab-span">    </span></span>Pbind<span class="s2">(*[</span></p>
 128 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>instrument: <span class="s7">\multi</span>,</p>
 129 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>freq: <span class="Apple-tab-span">      </span><span class="s8">Prand</span>([<span class="Apple-converted-space"> </span></p>
 130 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>[[100, 141, 103] ],<span class="Apple-converted-space"> </span></p>
 131 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>[[100, 310, 190] ],<span class="Apple-converted-space"> </span></p>
 132 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>[[100, 100.1, 110] ],<span class="Apple-converted-space"> </span></p>
 133 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>], <span class="s8">inf</span>),</p>
 134 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>dur: 0.2,</p>
 135 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>sustain: 0.3</p>
 136 <p class="p4"><span class="Apple-tab-span">     </span>]).play;</p>
 137 <p class="p4">)</p>
 138 </body>
 139 </html>