Removing an old, cherished, yet pointless caveat "This documentation is
[supercollider.git] / Help / GUI / Cocoa-GUI / SCFreqScope.html
blob73f3c14ccfb758ca43853068261da5a717cd15e2
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="949.43">
9 <style type="text/css">
10 p.p1 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.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: 9.0px Monaco; min-height: 12.0px}
13 p.p4 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; color: #001bec}
14 p.p5 {margin: 0.0px 0.0px 0.0px 0.0px; font: 14.0px Helvetica}
15 p.p6 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco}
16 p.p7 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 9.0px Monaco; min-height: 12.0px}
17 p.p8 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 12.0px Helvetica}
18 p.p9 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 12.0px Helvetica; min-height: 14.0px}
19 p.p10 {margin: 0.0px 0.0px 0.0px 85.0px; text-indent: -85.0px; font: 12.0px Helvetica}
20 p.p11 {margin: 0.0px 0.0px 0.0px 85.0px; text-indent: -85.0px; font: 12.0px Helvetica; min-height: 14.0px}
21 p.p12 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #ae1a19}
22 p.p13 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #96251f; min-height: 12.0px}
23 p.p14 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 14.0px Helvetica}
24 p.p15 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 14.0px Helvetica; min-height: 17.0px}
25 p.p16 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Monaco; min-height: 16.0px}
26 span.s1 {font: 18.0px Helvetica}
27 span.s2 {color: #1a45de}
28 span.s3 {color: #000000}
29 span.s4 {text-decoration: underline ; color: #0029e4}
30 span.s5 {text-decoration: underline}
31 span.s6 {color: #0016bd}
32 span.s7 {color: #606060}
33 span.s8 {color: #ae1a19}
34 span.s9 {color: #6f7178}
35 span.s10 {color: #0036ec}
36 span.s11 {color: #4f6a1d}
37 span.s12 {font: 9.0px Monaco; color: #4f6a1d}
38 span.s13 {font: 14.0px Helvetica}
39 span.s14 {font: 11.0px Monaco; color: #1435a6}
40 span.Apple-tab-span {white-space:pre}
41 </style>
42 </head>
43 <body>
44 <p class="p1"><span class="s1"><b>SCFreqScope<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b></span><b>frequency analysis view</b><span class="s1"><b><span class="Apple-tab-span"> </span></b></span></p>
45 <p class="p2"><br></p>
46 <p class="p1"><b>Inherits from: Object : </b><a href="SCView.html"><span class="s2"><b>SCView</b></span></a><b> : </b><a href="SCScope.html"><span class="s2"><b>SCScope</b></span></a></p>
47 <p class="p3"><br></p>
48 <p class="p1">SCFreqScope shows the frequency spectrum of a specified audio bus.</p>
49 <p class="p2"><br></p>
50 <p class="p4"><span class="s3"><b>See also:</b> <a href="SCScope.html"><span class="s4">SCScope</span></a>, <a href="SCFreqScopeWindow.html"><span class="s5">SCFreqScopeWindow</span></a></span></p>
51 <p class="p2"><br></p>
52 <p class="p5"><b>A Very Important Issue Regarding SCFreqScope:</b></p>
53 <p class="p2"><br></p>
54 <p class="p1">The scope will remain active after a command-period. To turn it off you must use the 'active' method.</p>
55 <p class="p1"><b>Very important:</b> You must run <b>kill() </b>when the parent window is closed to avoid problems.</p>
56 <p class="p1">It also frees the buffers that the scope allocated and stops the FFT analysis synth. So:</p>
57 <p class="p2"><br></p>
58 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>(</p>
59 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>w = <span class="s6">SCWindow</span>(<span class="s7">"My Analyzer"</span>, <span class="s6">Rect</span>(0, 0, 511, 300));</p>
60 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>f = <span class="s6">SCFreqScope</span>(w, w.view.bounds);</p>
61 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>w.onClose_({ f.kill }); <span class="s8">// YOU MUST HAVE THIS</span></p>
62 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>w.front;</p>
63 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>)</p>
64 <p class="p2"><br></p>
65 <p class="p5"><b>Creation / Class Methods</b></p>
66 <p class="p7"><br></p>
67 <p class="p8"><b><span class="Apple-tab-span"> </span>*new (parent, bounds)</b></p>
68 <p class="p9"><b><span class="Apple-tab-span"> </span></b></p>
69 <p class="p10"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><b>parent </b>- The parent view.</p>
70 <p class="p10"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><b>bounds </b>- An instance of <a href="../../Geometry/Rect.html"><span class="s9">Rect</span></a>, or a <a href="../../Geometry/Point.html"><span class="s9">Point</span></a> indicating width@height.</p>
71 <p class="p11"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
72 <p class="p12"><span class="s3"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// Start internal server</p>
73 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>s = <span class="s6">Server</span>.internal.boot;</p>
74 <p class="p3"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
75 <p class="p12"><span class="s3"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// Create analyzer in a window</p>
76 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>(</p>
77 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>w = <span class="s6">SCWindow</span>(<span class="s7">"My Analyzer"</span>, <span class="s6">Rect</span>(0, 0, 511, 300)); <span class="s8">// width should be 511</span></p>
78 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>f = <span class="s6">SCFreqScope</span>(w, w.view.bounds);</p>
79 <p class="p12"><span class="s3"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>f.active_(</span><span class="s6">true</span><span class="s3">); <span class="Apple-tab-span"> </span></span>// turn it on the first time;</p>
80 <p class="p3"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
81 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>w.onClose_({ f.kill }); <span class="s8">// you must have this</span></p>
82 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>w.front;</p>
83 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>{ <span class="s6">SinOsc</span>.ar([500, 1000], 0, 0.25).mean.dup }.play(s); <span class="s8">// start two sine waves</span></p>
84 <p class="p3"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
85 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>)</p>
86 <p class="p7"><br></p>
87 <p class="p8"><b><span class="Apple-tab-span"> </span>*response (parent, bounds, bus1, bus2, freqMode)</b></p>
88 <p class="p9"><b><span class="Apple-tab-span"> </span></b></p>
89 <p class="p10"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>Create a scope in a special frequency-response mode. This uses FFT-based spectral division to estimate the frequency response of some effect, on the assumption that the signal to <b>bus1</b> is transformed to the signal at <b>bus2</b> by some linear time-invariant process.</p>
90 <p class="p10"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><b>parent </b>- The parent view.</p>
91 <p class="p10"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><b>bounds </b>- An instance of <a href="../../Geometry/Rect.html"><span class="s9">Rect</span></a>, or a <a href="../../Geometry/Point.html"><span class="s9">Point</span></a> indicating width@height.</p>
92 <p class="p10"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><b>bus1</b> - The bus on which the "pre" signal is found.</p>
93 <p class="p10"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><b>bus2</b> - The bus on which the "post" signal is found.</p>
94 <p class="p10"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><b>freqMode</b> - linear (0) or log(1) frequency mode. Defaults to 1.</p>
95 <p class="p7"><br></p>
96 <p class="p13"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
97 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s6">Server</span>.default = s = <span class="s6">Stethoscope</span>.defaultServer.boot;</p>
98 <p class="p3"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
99 <p class="p12"><span class="s3"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// basic usage. try these. Each one will open a new window</p>
100 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>// move the mouse left and right to test response in different ranges<span class="Apple-tab-span"> </span></p>
101 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s6">LPF</span>.scopeResponse</p>
102 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s6">HPF</span>.scopeResponse</p>
103 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s6">MoogFF</span>.scopeResponse</p>
104 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s6">BBandPass</span>.scopeResponse</p>
105 <p class="p12"><span class="s3"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span><span class="s6">BLowShelf</span><span class="s3">.scopeResponse </span>// by default BLowShelf doesn't mangle much</p>
106 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s6">Resonz</span>.scopeResponse</p>
107 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s6">BRF</span>.scopeResponse</p>
108 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s6">Integrator</span>.scopeResponse</p>
109 <p class="p12"><span class="s3"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span><span class="s6">Median</span><span class="s3">.scopeResponse </span>// nonlinear, and therefore interesting</p>
110 <p class="p3"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
111 <p class="p3"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
112 <p class="p12"><span class="s3"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// customize the parameters for more informative scoping</p>
113 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>{<span class="s6">|in|</span> <span class="s6">MoogFF</span>.ar(in, freq: <span class="s6">MouseX</span>.kr(10, 10000, 1),</p>
114 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>gain:<span class="s6">MouseY</span>.kr(4,0))}.scopeResponse</p>
115 <p class="p3"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
116 <p class="p13"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
117 <p class="p14"><b>Instance Methods</b></p>
118 <p class="p15"><br></p>
119 <p class="p8"><b><span class="Apple-tab-span"> </span>kill</b></p>
120 <p class="p8"><b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>Very important</b>. This must be run when the parent window is closed to avoid problems. It also frees the buffers that the scope allocated and stops the FFT analysis synth.</p>
121 <p class="p9"><span class="Apple-tab-span"> </span></p>
122 <p class="p8"><b><span class="Apple-tab-span"> </span>active</b></p>
123 <p class="p8"><b><span class="Apple-tab-span"> </span>active_ (bool)</b></p>
124 <p class="p9"><b><span class="Apple-tab-span"> </span></b></p>
125 <p class="p8"><b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>Turn the scope on or off.</p>
126 <p class="p10"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><b>bool </b>- An instance of Boolean.</p>
127 <p class="p11"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
128 <p class="p8"><b><span class="Apple-tab-span"> </span>freqMode</b></p>
129 <p class="p8"><b><span class="Apple-tab-span"> </span>freqMode_ (mode)</b></p>
130 <p class="p9"><b><span class="Apple-tab-span"> </span></b></p>
131 <p class="p10"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><b>mode </b>- 0= linear, 1= logarithmic.</p>
132 <p class="p11"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
133 <p class="p8"><b><span class="Apple-tab-span"> </span>inBus</b></p>
134 <p class="p8"><b><span class="Apple-tab-span"> </span>inBus_ (num)</b></p>
135 <p class="p9"><b><span class="Apple-tab-span"> </span></b></p>
136 <p class="p8"><b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>The bus to listen on.</p>
137 <p class="p10"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><b>num </b>- an audio <a href="../../ServerArchitecture/Bus.html"><span class="s2">Bus</span></a> number.</p>
138 <p class="p9"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
139 <p class="p8"><b><span class="Apple-tab-span"> </span>dbRange</b></p>
140 <p class="p8"><b><span class="Apple-tab-span"> </span>dbRange_ (db)</b></p>
141 <p class="p9"><b><span class="Apple-tab-span"> </span></b></p>
142 <p class="p8"><b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>Get/set the amplitude range.</p>
143 <p class="p10"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><b>db </b>- A <a href="../../Math/Number.html"><span class="s2">Number</span></a>.</p>
144 <p class="p9"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
145 <p class="p8"><b><span class="Apple-tab-span"> </span>special (defname, extraArgs)</b></p>
146 <p class="p9"><b><span class="Apple-tab-span"> </span></b></p>
147 <p class="p8"><b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>Put the scope into a special mode using a user-specified <a href="../../ServerArchitecture/SynthDef.html"><span class="s10">SynthDef</span></a>. Note that only very particular SynthDefs should be used, namely ones that are derived from the <span class="s11">\</span><span class="s12">freqScope0</span> or <span class="s12">\freqScope1</span> SynthDefs. Most users will not need to use this method directly, but it can be used to provide a customised analysis shown in the scope.</p>
148 <p class="p10"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><b>defname </b>- Name of the SynthDef you wish to use.</p>
149 <p class="p10"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><b>extraArgs </b>- extra arguments that you may wish to pass to the synth.</p>
150 <p class="p9"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
151 <p class="p14"><b>Subclassing and Internal Methods</b></p>
152 <p class="p8"><span class="s13"><span class="Apple-tab-span"> </span></span>The following methods are usually not used directly or are called by a primitive. Programmers can still call or override these as needed.</p>
153 <p class="p9"><span class="Apple-tab-span"> </span></p>
154 <p class="p8"><b><span class="Apple-tab-span"> </span>*viewClass</b> Returns <span class="s14">SCScope</span>. See also Subclassing and Internal Methods in <a href="SCView.html"><span class="s2">SCView</span></a></p>
155 <p class="p7"><br></p>
156 <p class="p8"><b><span class="Apple-tab-span"> </span>*initClass</b> Sets the classVar , <b>server</b> = Server.internal.</p>
157 <p class="p9"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
158 <p class="p8"><b><span class="Apple-tab-span"> </span>server</b> - A classVar. must be Server.internal</p>
159 <p class="p8"><b><span class="Apple-tab-span"> </span>start</b></p>
160 <p class="p8"><b><span class="Apple-tab-span"> </span>eventSeq (delta, funcs)</b></p>
161 <p class="p8"><b><span class="Apple-tab-span"> </span>cmdPeriod</b></p>
162 <p class="p8"><b><span class="Apple-tab-span"> </span>initSCFreqScope</b></p>
163 <p class="p8"><b><span class="Apple-tab-span"> </span>sendSynthDefs</b></p>
164 <p class="p8"><b><span class="Apple-tab-span"> </span>allocBuffers</b></p>
165 <p class="p8"><b><span class="Apple-tab-span"> </span>freeBuffers</b></p>
166 <p class="p8"><b><span class="Apple-tab-span"> </span>node</b></p>
167 <p class="p8"><b><span class="Apple-tab-span"> </span>scopebuf</b></p>
168 <p class="p8"><b><span class="Apple-tab-span"> </span>fftbuf</b></p>
169 <p class="p8"><b><span class="Apple-tab-span"> </span>bufSize</b></p>
170 <p class="p9"><b><span class="Apple-tab-span"> </span></b></p>
171 <p class="p14"><b>Examples</b></p>
172 <p class="p2"><br></p>
173 <p class="p12">// Start internal server</p>
174 <p class="p6">s = <span class="s6">Server</span>.internal.boot;</p>
175 <p class="p3"><br></p>
176 <p class="p3"><br></p>
177 <p class="p12">// Create analyzer in a window</p>
178 <p class="p6">(</p>
179 <p class="p6">w = <span class="s6">SCWindow</span>(<span class="s7">"My Analyzer"</span>, <span class="s6">Rect</span>(0, 0, 511, 300)); <span class="s8">// width should be 511</span></p>
180 <p class="p6">f = <span class="s6">SCFreqScope</span>(w, w.view.bounds);</p>
181 <p class="p12"><span class="s3">f.active_(</span><span class="s6">true</span><span class="s3">); <span class="Apple-tab-span"> </span></span>// turn it on the first time;</p>
182 <p class="p3"><br></p>
183 <p class="p6">w.onClose_({ f.kill }); <span class="s8">// you must have this</span></p>
184 <p class="p6">w.front;</p>
185 <p class="p6">{ <span class="s6">SinOsc</span>.ar([500, 1000], 0, 0.25).mean.dup }.play(s); <span class="s8">// start two sine waves</span></p>
186 <p class="p3"><br></p>
187 <p class="p6">)</p>
188 <p class="p3"><br></p>
189 <p class="p3"><br></p>
190 <p class="p12"><span class="s3">f.freqMode_(1);<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// change to log scale so we can see them</p>
191 <p class="p12"><span class="s3">f.inBus_(1);<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// look at bus 1</p>
192 <p class="p12"><span class="s3">f.dbRange_(200);<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// expand amplitude range</p>
193 <p class="p12"><span class="s3">f.active_(</span><span class="s6">false</span><span class="s3">);<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// turn scope off (watch CPU)</p>
194 <p class="p12"><span class="s3">f.active_(</span><span class="s6">true</span><span class="s3">);<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// turn it back on<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
195 <p class="p3"><br></p>
196 <p class="p3"><br></p>
197 <p class="p12">// Now press command-period. The scope is still running.</p>
198 <p class="p3"><br></p>
199 <p class="p3"><br></p>
200 <p class="p6">{ <span class="s6">Mix</span>.ar(<span class="s6">SinOsc</span>.ar([500, 1200, 3000, 9000,12000], 0, [0.2,0.1,0.05,0.03,0.01])) }.play(s); <span class="s8">// restart some sines</span></p>
201 <p class="p3"><br></p>
202 <p class="p3"><br></p>
203 <p class="p12">// Close window and scope is killed.</p>
204 <p class="p3"><br></p>
205 <p class="p3"><br></p>
206 <p class="p3"><br></p>
207 <p class="p3"><br></p>
208 <p class="p3"><br></p>
209 <p class="p3"><br></p>
210 <p class="p16"><br></p>
211 </body>
212 </html>