Help/3vs2/Backwards-Compatibility.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="824.42">
   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; min-height: 14.0px}
  12 p.p3 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica}
  13 p.p4 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #a71e12}
  14 p.p5 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco}
  15 p.p6 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; min-height: 12.0px}
  16 p.p7 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #606060}
  17 p.p8 {margin: 0.0px 0.0px 0.0px 0.0px; font: 10.0px Monaco; min-height: 14.0px}
  18 span.s1 {color: #000000}
  19 span.s2 {color: #0019b7}
  20 span.s3 {color: #326f17}
  21 span.s4 {color: #606060}
  22 span.Apple-tab-span {white-space:pre}
  23 </style>
  24 </head>
  25 <body>
  26 <p class="p1"><b>Backwards Compatibility</b></p>
  27 <p class="p2"><br></p>
  28 <p class="p3">There are a number of classes and methods that have been added to allow for backwards compatibility with SC2 code. The most notable of these is Synth.play, which is basically a wrapper for Function.play.</p>
  29 <p class="p2"><br></p>
  30 <p class="p4"><span class="s1">{ </span><span class="s2">SinOsc</span><span class="s1">.ar(440, 0, 0.5) }.play; </span>// creates an arbitrarily named SynthDef and a Synth to play it</p>
  31 <p class="p4"><span class="s2">Synth</span><span class="s1">.play({ </span><span class="s2">SinOsc</span><span class="s1">.ar(440, 0, 0.5) }); </span>// in SC3 just a wrapper for Function.play with fewer args</p>
  32 <p class="p2"><br></p>
  33 <p class="p3">Both of these will create synth nodes on the default server. Note that neither requires the use of an Out.ar ugen; they simply output to the first audio bus. One can however add an Out to Function.play in order to specify.</p>
  34 <p class="p2"><br></p>
  35 <p class="p5"><span class="s2">Synth</span>.play({ <span class="s2">Out</span>.ar(1, <span class="s2">SinOsc</span>.ar(440, 0, 0.5)) });</p>
  36 <p class="p2"><br></p>
  37 <p class="p3">In general, one should be aware of this distinction when using this code. When copying such code for reuse with other SC3 classes (for example in a reusable SynthDef), it will usually be necessary to add an Out.ar. Although useful for quick testing these methods are generally inferior to SynthDef.play, as the latter is more direct, requires no modifications for general reuse, has greater general flexibility and has slightly less overhead. (Although this is insignificant in most cases, it could be relevant when large numbers of defs or nodes are being created.)<span class="Apple-converted-space"> </span></p>
  38 <p class="p2"><br></p>
  39 <p class="p3">Like SynthDef.play, Function.play returns a Synth object which can then be messaged, etc. However, since Function.play creates an arbitrarily named SynthDef, one cannot reuse the resulting def, at least not without reading its name from the post window, or getting it from the Synth object.</p>
  40 <p class="p2"><br></p>
  41 <p class="p4">//The following examples are functionally equivalent</p>
  42 <p class="p5">x = { <span class="s2">arg</span> freq = 440; <span class="s2">Out</span>.ar(1, <span class="s2">SinOsc</span>.ar(freq, 0, 0.5)) }.play(fadeTime: 0);<span class="Apple-converted-space"> </span></p>
  43 <p class="p4"><span class="s1">x.set(</span><span class="s3">\freq</span><span class="s1">, 880); <span class="Apple-tab-span"> </span><span class="Apple-tab-span">    </span></span>// you can set arguments</p>
  44 <p class="p4"><span class="s1">y = </span><span class="s2">Synth</span><span class="s1">.new(x.defName); <span class="Apple-tab-span">  </span></span>// get the arbitrary defname from x</p>
  45 <p class="p5">x.free;</p>
  46 <p class="p5">y.free;</p>
  47 <p class="p6"><br></p>
  48 <p class="p5">x = <span class="s2">SynthDef</span>(<span class="s4">"backcompat-sine"</span>, { <span class="s2">arg</span> freq = 440; <span class="s2">Out</span>.ar(1, <span class="s2">SinOsc</span>.ar(freq, 0, 0.5)) }).play;<span class="Apple-converted-space"> </span></p>
  49 <p class="p5">x.set(<span class="s3">\freq</span>, 880);</p>
  50 <p class="p7"><span class="s1">y = </span><span class="s2">Synth</span><span class="s1">.new(</span>"backcompat-sine"<span class="s1">);</span></p>
  51 <p class="p5">x.free;</p>
  52 <p class="p5">y.free;</p>
  53 <p class="p8"><br></p>
  54 <p class="p3">Function.play is in general superior to both its SC2 equivalent and Synth.play. It has a number of significant features such as the ability to specify the output bus and fade times as arguments. See the <b>Function</b> helpfile for a more in-depth discussion.</p>
  55 <p class="p2"><br></p>
  56 <p class="p3">A number of other classes and methods have also been added to improve compatibility. These are listed below. In general there are equivalent or better ways of doing the same things in SC3.</p>
  57 <p class="p2"><br></p>
  58 <p class="p3"><b>Synth *play<span class="Apple-tab-span">       </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span></b>use Function.play or SynthDef.play</p>
  59 <p class="p3"><b>GetFileDialog</b><span class="Apple-converted-space">  <span class="Apple-tab-span">  </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span></span>use CocoaDialog</p>
  60 <p class="p3"><b>GetStringDialog</b></p>
  61 <p class="p3"><b>Synth *stop</b><span class="Apple-tab-span">   </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>use Server.freeAll</p>
  62 <p class="p3"><b>Synth *isPlaying</b><span class="Apple-tab-span">      </span><span class="Apple-tab-span">    </span>Server.numSynths (this will include non-running nodes)</p>
  63 <p class="p3"><b>Mix *ar *arFill<span class="Apple-tab-span">   </span></b><span class="Apple-tab-span">        </span><span class="Apple-tab-span">    </span>use Mix *new and *fill</p>
  64 <p class="p3"><b>SimpleNumber.rgb</b></p>
  65 <p class="p3"><b>Rawarray.write</b></p>
  66 </body>
  67 </html>