HelpSource/Classes/Stethoscope.schelp

   1 CLASS:: Stethoscope
   2 redirect:: implClass
   3 summary:: An oscilloscope
   4 categories:: GUI>Interfaces
   5 related:: Classes/ScopeView, Classes/FreqScope
   6
   7 DESCRIPTION::
   8
   9 Stethoscope provides a complete oscilloscope GUI. It displays a window containing a bus-plotting link::Classes/ScopeView:: and an interface to configure the plotting and choose among the buses.
  10
  11 SUBSECTION:: Creation by message .scope
  12
  13 Several classes provide a convenient 'scope' method that creates a Stethoscope to display their data. See for example: link::Classes/Server#-scope::, link::Classes/Bus#-scope::, link::Classes/Function#-scope::.
  14
  15 SUBSECTION:: Keyboard shortcuts
  16
  17 The following keyboard shortcuts may be used when focused on the Stethoscope display:
  18
  19 table::
  20 ## strong::Shortcut:: || strong::Action::
  21 ## J || one channel back
  22 ## K || switch rate (audio vs. control)
  23 ## L || one channel forward
  24 ## O || jump to first hardware output channel and adjust numChannels to hardware
  25 ## I || jump to first hardware input channel and adjust numChannels to hardware
  26 ## space || run, if not running already
  27 ## . (period) || stop
  28 ## M || toggle screen size
  29 ## + / - || zoom horizontally
  30 ## * / _ || zoom vertically
  31 ## S || change style between parallel and overlay
  32 ## Shift+S || change style to lissajou
  33 ## Shift+A || allocate buffer size so it fills the screen (to next power of two) (this can be dangerous, might crash)
  34 ::
  35
  36 CLASSMETHODS::
  37
  38 PRIVATE:: key
  39
  40 METHOD:: new
  41
  42     Create a Stethoscope, either as a window, or placed on a given parent view.
  43
  44     argument:: server
  45         A valid Server (see link::#*isValidServer::), or code::nil::, in which case the link::#*defaultServer:: is used.
  46     argument:: numChannels
  47         An integer. Default value is 2.
  48     argument:: index
  49         The offset index. An Integer. Default is nil.
  50     argument:: bufsize
  51         The size of the analysis buffer. Default is 4096. See also link::#-bufsize::.
  52     argument:: zoom
  53         Horizontal maginification of the displayed wave. Default is 1. See also link::#-xZoom::.
  54     argument:: rate
  55         \audio or \control. Default is \audio.
  56     argument:: view
  57         The optional parent view. Default is nil. If nil, then it will open in its own Window.
  58     argument:: bufnum
  59         The id number of the Buffer to analyze. Default value is nil. If nil, then a Buffer of size bufSize is allocated.
  60
  61     discussion:
  62     Example:
  63 code::
  64 Server.default = s = Server.internal
  65 s.boot
  66 {SinOsc.ar([330,440], 0, 0.4)}.play;
  67 SCStethoscope(s,2);
  68 ::
  69
  70 METHOD:: defaultServer
  71
  72     The default server used if no server is passed to the link::#*new#constructor::.
  73
  74
  75 METHOD:: isValidServer
  76
  77     Tests whether Stethoscope can operate on the given server.
  78
  79     This is the current state of server support:
  80     list::
  81     ## strong::Qt::: any local server (see link::Classes/Server#-isLocal::).
  82     ## strong::Cocoa::: only the in-process (internal) server (see link::Classes/Server#*internal:: and link::Classes/Server#-inProcess::).
  83     ## strong::SwingOSC::: any out-of-process server, even remote (see link::Classes/Server#-inProcess::).
  84     ::
  85
  86     argument::
  87         A link::Classes/Server::.
  88     returns::
  89         A Boolean.
  90
  91 METHOD:: ugenScopes
  92
  93     Returns an array of the running ugen scopes.
  94
  95 code::
  96 Server.default = s = Server.internal
  97 s.boot
  98 {[SinOsc.ar.scope,WhiteNoise.ar(0.5).scope]*0.1}.scope(2);
  99 Stethoscope.ugenScopes; // returns the ugen scopes
 100 ::
 101
 102 METHOD:: tileBounds
 103
 104     A utility method used by link::Classes/UGen#-scope:: to tile scope windows.
 105
 106     returns::
 107         A Rect.
 108
 109
 110
 111 INSTANCEMETHODS::
 112
 113
 114 SUBSECTION:: Data
 115
 116 METHOD:: server
 117     The server on which the scope operates.
 118
 119 METHOD:: rate
 120     Whether to operate on audio or control busses.
 121     argument::
 122         One of the two symbols: code::\audio:: or code::\control::.
 123
 124 METHOD:: index
 125     The starting index of the busses to scope.
 126     argument::
 127         An Integer.
 128
 129 METHOD:: numChannels
 130     The amount of adjacent busses to scope (from link::#-index:: on).
 131     argument::
 132         An Integer.
 133
 134 METHOD:: bufsize
 135     The size of the scoping buffer.
 136
 137     In strong::Swing:: and strong::Cococa:: GUI kits, this is the amount of signal frames that will be accumulated before they are displayed. However, it is strong::NOT ensured:: that the onsets of displayed portions of signals fall within any constant period. In other words, it is undefined how many frames will pass between one displayed portion, and another.
 138
 139     In strong::Qt:: GUI, this is not the issue; code::bufsize:: only defines the maximum allowed link::#-cycle::.
 140
 141 METHOD:: cycle
 142     note:: Only available in Qt GUI ::
 143
 144     The exact scoping period, in signal frames. Reciprocal to what is also known as emphasis::sweep speed:: in analog oscilloscopes. It is dynamically adjustable while the scope is running.
 145
 146     Data from scoped signals will be accumulated into a buffer until it reaches code::cycle:: amount frames, at which point the buffering will immediatly restart. The view will repeatedly display the entire buffer; it may skip a cycle if the drawing is too slow to keep up with the speed of incoming data, but the cycle boundaries will never shift with respect to signals.
 147
 148     If you are scoping a periodic signal, setting code::cycle:: to match the signal's period will keep the waveform locked in place.
 149
 150 SUBSECTION:: Display
 151
 152 METHOD:: window
 153     The (parent) Window of the scope.
 154
 155 METHOD:: size
 156     Sets the width and the height of the scope window.
 157     argument::
 158         An Integer (the window is square).
 159
 160 METHOD:: toggleSize
 161
 162     Toggle between small and large size.
 163
 164 METHOD:: zoom
 165     A synonym for link::#-xZoom::.
 166
 167 METHOD:: xZoom
 168     Magnifies the displayed wave horizontally to the given factor.
 169
 170     In strong::Qt GUI::, this sets link::#-cycle:: to code::1024 * xZoom.reciprocal::.
 171
 172     argument::
 173         A Float.
 174
 175 METHOD:: yZoom
 176     Magnifies the displayed wave vertically to the given factor.
 177
 178     argument::
 179         A Float.
 180
 181 METHOD:: style
 182     The plotting style:
 183     list::
 184     ## 0 = the channels are vertically spaced
 185     ## 1 = the channels are overlayed
 186     ## 2 = lissajou; the first two channels are used for 2D plotting (as streams of x and y coordinates).
 187     ::
 188
 189     argument::
 190         One of the above Integers.
 191
 192
 193 SUBSECTION:: Operation
 194
 195 METHOD:: run
 196
 197     Starts the scope, if not already running.
 198
 199 METHOD:: quit
 200
 201     Closes the window, and cleans up any used synths and buffers.
 202
 203 SUBSECTION:: Convenience
 204
 205 METHOD:: setProperties
 206
 207     Sets several properties at once: link::#-numChannels::, link::#-index::, link::#-bufsize::, link::#-zoom::, and link::#-rate::.
 208
 209
 210
 211 EXAMPLES::
 212
 213 SUBSECTION:: A step-by-step example
 214 code::
 215 (
 216 Server.default = Server.internal;
 217 s = Server.default;
 218 s.boot;
 219 )
 220 (
 221 {
 222     SinOsc.ar([225, 450, 900], 0, 0.2)
 223     + LPF.ar(
 224         LFPulse.ar(226 * [1, 2, 5],[0,0.1,0.1],0.2, 0.2),
 225         MouseX.kr(20, 10000, 1)
 226         )
 227 }.scope;
 228 )
 229
 230 // server.scope only changes the properies explicitly given:
 231
 232 s.scope(numChannels:5);
 233 s.scope(index:12);
 234 s.scope(zoom:4);
 235 s.scope(index:0);
 236
 237 s.scopeWindow.size = 600;
 238 s.scopeWindow.size = 222;
 239
 240 // scoping buses:
 241
 242 a = Bus.audio(s, 4);
 243 { WhiteNoise.ar(0.2.dup(4)) }.play(s, a);
 244
 245 a.scope;
 246
 247 c = Bus.control(s, 3);
 248 { WhiteNoise.kr(1.dup(4) * MouseX.kr) }.play(s, c);
 249
 250 c.scope;
 251
 252 // note that scoping control rate buses shows block size interpolation (this is due to the
 253 // fact that ScopeOut.kr doesn't work yet.)
 254 ::
 255
 256 SUBSECTION:: Embedded use
 257 You can pass your own view in to add a stethoscope to it:
 258
 259 code::
 260 w = Window.new("my own scope", Rect(20, 20, 400, 500));
 261 w.view.decorator = FlowLayout(w.view.bounds);
 262 c = Stethoscope.new(s, view:w.view);
 263 w.onClose = { c.free }; // don't forget this
 264 w.front;
 265 ::