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         In Qt GUI: any local Server (internal or another process on the same machine).
  46         In other GUI kits: must be Server.internal.
  47     argument:: numChannels
  48         An integer. Default value is 2.
  49     argument:: index
  50         The offset index. An Integer. Default is nil.
  51     argument:: bufsize
  52         The size of the analysis buffer. Default is 4096.
  53     argument:: zoom
  54         Horizontal maginification of the displayed wave. Default is 1.
  55     argument:: rate
  56         \audio or \control. Default is \audio.
  57     argument:: view
  58         The optional parent view. Default is nil. If nil, then it will open in its own Window.
  59     argument:: bufnum
  60         The id number of the Buffer to analyze. Default value is nil. If nil, then a Buffer of size bufSize is allocated.
  61
  62     discussion:
  63     Example:
  64 code::
  65 Server.default = s = Server.internal
  66 s.boot
  67 {SinOsc.ar([330,440], 0, 0.4)}.play;
  68 SCStethoscope(s,2);
  69 ::
  70
  71 METHOD:: ugenScopes
  72
  73     Returns an array of the running ugen scopes.
  74
  75 code::
  76 Server.default = s = Server.internal
  77 s.boot
  78 {[SinOsc.ar.scope,WhiteNoise.ar(0.5).scope]*0.1}.scope(2);
  79 SCStethoscope.ugenScopes; // returns the ugen scopes
  80 ::
  81
  82 METHOD:: defaultServer
  83
  84         SCStethoscope's default server. Returns Server.internal
  85
  86
  87 METHOD:: isValidServer (aServer)
  88
  89         Tests if a server is a valid server. Returns a n instanc of Boolean;
  90         aServer - An instance of Server.
  91
  92 METHOD:: tileBounds
  93
  94         A utility used by Ugen : scope to tile scope windows.
  95
  96
  97
  98 INSTANCEMETHODS::
  99
 100 METHOD:: ugenScopes
 101
 102     Returns an array of the running UGen scopes, just like the class method link::#*ugenScopes::.
 103
 104
 105 SUBSECTION:: Data
 106
 107 METHOD:: server
 108     The server on which the scope operates.
 109
 110 METHOD:: rate
 111     Whether to operate on audio or control busses.
 112     argument::
 113         One of the two symbols: code::\audio:: or code::\control::.
 114
 115 METHOD:: index
 116     The starting index of the busses to scope.
 117     argument::
 118         An Integer.
 119
 120 METHOD:: numChannels
 121     The amount of adjacent busses to scope (from link::#-index:: on).
 122     argument::
 123         An Integer.
 124
 125 METHOD:: bufsize
 126     The size of the scope buffer.
 127
 128
 129 SUBSECTION:: Display
 130
 131 METHOD:: window
 132     The (parent) Window of the scope.
 133
 134 METHOD:: size
 135     Sets the width and the height of the scope window.
 136     argument::
 137         An Integer (the window is square).
 138
 139 METHOD:: toggleSize
 140
 141     Toggle between small and large size.
 142
 143 METHOD:: zoom
 144     A synonym for link::#-xZoom::.
 145
 146 METHOD:: xZoom
 147     Zoom horizontally by the given factor.
 148     argument::
 149         A Float.
 150
 151 METHOD:: yZoom
 152
 153     Zoom vertically by by the given factor.
 154     argument::
 155         A Float.
 156
 157 METHOD:: style
 158     The plotting style:
 159     list::
 160     ## 0 = the channels are vertically spaced
 161     ## 1 = the channels are overlayed
 162     ## 2 = lissajou; the first two channels are used for 2D plotting (as streams of x and y coordinates).
 163     ::
 164
 165     argument::
 166         One of the above Integers.
 167
 168
 169 SUBSECTION:: Operation
 170
 171 METHOD:: run
 172
 173     Starts the scope, if not already running.
 174
 175 METHOD:: quit
 176
 177     Closes the window, and cleans up any used synths and buffers.
 178
 179 SUBSECTION:: Convenience
 180
 181 METHOD:: setProperties (numChannels, index, bufsize, zoom, rate)
 182
 183     Sets several properties at once: link::#-numChannels::, link::#-index::, link::#-bufsize::, link::#-zoom::, and link::#-rate::.
 184
 185
 186
 187 EXAMPLES::
 188
 189 SUBSECTION:: A step-by-step example
 190 code::
 191 (
 192 Server.default = Server.internal;
 193 s = Server.default;
 194 s.boot;
 195 )
 196 (
 197 {
 198     SinOsc.ar([225, 450, 900], 0, 0.2)
 199     + LPF.ar(
 200         LFPulse.ar(226 * [1, 2, 5],[0,0.1,0.1],0.2, 0.2),
 201         MouseX.kr(20, 10000, 1)
 202         )
 203 }.scope;
 204 )
 205
 206 // server.scope only changes the properies explicitly given:
 207
 208 s.scope(numChannels:5);
 209 s.scope(index:12);
 210 s.scope(zoom:4);
 211 s.scope(index:0);
 212
 213 s.scopeWindow.size = 600;
 214 s.scopeWindow.size = 222;
 215
 216 // scoping buses:
 217
 218 a = Bus.audio(s, 4);
 219 { WhiteNoise.ar(0.2.dup(4)) }.play(s, a);
 220
 221 a.scope;
 222
 223 c = Bus.control(s, 3);
 224 { WhiteNoise.kr(1.dup(4) * MouseX.kr) }.play(s, c);
 225
 226 c.scope;
 227
 228 // note that scoping control rate buses shows block size interpolation (this is due to the
 229 // fact that ScopeOut.kr doesn't work yet.)
 230 ::
 231
 232 SUBSECTION:: Embedded use
 233 You can pass your own view in to add a stethoscope to it:
 234
 235 code::
 236 w = Window.new("my own scope", Rect(20, 20, 400, 500));
 237 w.view.decorator = FlowLayout(w.view.bounds);
 238 c = Stethoscope.new(s, view:w.view);
 239 w.onClose = { c.free }; // don't forget this
 240 w.front;
 241 ::