Oscilloscope plugin
==================================================
The Oscilloscope is a DSSI plugin with a GUI that displays the audio input
in an oscilloscope view. I wrote it because I wanted something too 
use in modular synths to view the waveforms with at different places in
the synth graph. I am licensing it under the GNU General Public License,
so if you are writing GPL software too, feel free to use any pieces of
this plugin in your own code.

The plugin DOES NOT WORK with jack-dssi-host 0.9, because that does not
support audio input ports. You will either need a later release (which 
unfortunately does not exist yet) or get the latest development version
from the DSSI CVS repository on SourceForge (http://sf.net/projects/dssi).
You can of course also use another DSSI host, like Om (0.1.0 and 0.1.1
will not work though).

This document describes how to install and use the DSSI Scope
plugin. If you have any questions or comments about the plugin, send
them to larsl@users.sourceforge.net.


1. Installation
==================================================
To build the plugin you will need the following libraries (and all
libraries they depend on):
 
 * libglademm, version 2.6.0 or later (it might work with earlier versions
                                       but that has not been tested)
 * liblo, version 0.18 or later (same comment as above)

 * the DSSI header, dssi.h

This plugin does not use the GNU autotools since I thought it would be
overkill for a small project that also is not meant to be cross-platform,
so you will have to edit the Makefile to change the installation settings.
The only thing you should have to change is the INSTALL_DIR variable. The
default setting is to install the plugin in /usr/local/lib/dssi.

To build the plugin, just type

 make

in the plugin source directory. To install the plugin, type

 make install

as root (unless you have set the INSTALL_DIR to something you can write to
without being root).


2. Use
==================================================
When you bring up the GUI for the DSSI Scope you will see a rectangular
display and some sliders, spinbuttons, and other control widgets. The display
will show the audio data from both input channels - channel 1 is green and
channel 2 is red. If the input to channel 1 is constant 0 nothing might be
shown at all, because you need a zero crossing to trigger the drawing. To
test the plugin you can load it on Om and connect it to an oscillator, or
run it in jack-dssi-host (which comes with the DSSI SDK) and connect it
to a sound player such as XMMS.

2.1 The trigger
==================================================
The oscilloscope will not show anything in the display until it detects a
"trigger". This trigger consists of the audio signal in channel 1 moving over
the trigger level, either from below to above (ascending) or from above to 
below (descending). When a trigger is detected a block of audio data 
corresponding to the display width will be copied from the input of both
channels and shown in the display. 

You can control the trigger level by changing the value of the spinbutton
labeled "Trg level". The current trigger level is shown as a small yellow
line at the left edge of the display. You can also change whether the trigger
will fire on ascending or descending signal by checking or unchecking the
checkbox labeled "Trigger on ascending".

2.2 Offsets and scaling
==================================================
The display is divided into 6 x 4 squares called "divisions". You can determine
the amount of time (in the X direction) and signal amplitude (in the Y 
direction) that each division corresponds to by changing the value in the 
spinbuttons "ms/DIV", "V1/DIV", and "V2/DIV". ms/DIV will set the number of 
milliseconds per division, and V1/DIV will set the number of signal strength 
units per division for channel 1 while V2/DIV will do the same for channel 2.

You can also use the vertical sliders to the left of the display to change
the 0 levels for the two channels (i.e. moving the channels vertically).
The leftmost slider controls the 0 level for channel 1 and the other controls
the level for channel 2. The horizontal slider below the display can be used
to move the signals from both channels horizontally.

2.3 Different modes
==================================================
You can "freeze" the signal currently shown by left-clicking in the display.
This will tell the oscilloscope to ignore any new triggers. Left-clicking
again will unfreeze the signal.

Right-clicking the display toggles "cumulative mode". In cumulative mode
the display does not get cleared before a new audio block is drawn.

Finally, middle-clicking the display hides or shows all the control widgets.
