ngscopeclient · May 25, 2020
diff --git a/images/channel-properties.png b/images/channel-properties.png
diff --git a/images/proto-analyzer.png b/images/proto-analyzer.png
diff --git a/images/timebase-properties.png b/images/timebase-properties.png
diff --git a/images/timeline.png b/images/timeline.png
diff --git a/section-decodes.tex b/section-decodes.tex
@@ -1,4 +1,4 @@
-\section{Protocol Decodes, Math Functions, and Measurements}
+\section{Filters}
 
 \subsection{Introduction}
 

diff --git a/section-history.tex b/section-history.tex
@@ -2,11 +2,11 @@ \section{History View}
 \label{sec:history}
 
 glscopeclient has the ability to save every waveform during a session in memory, allowing you to go back in time and
-see previous state of the system being debugged.
+see previous state of the system being debugged. Clicking on a timestamp in the history view pauses acquisition and
+loads the historical waveform data for analysis.
 
 By default, the history view (Fig. \ref{historyview}) is not displayed and no history is captured. If the history view
-is closed, past history is removed. (TODO: we should probably display a warning prompt or keep existing history when
-doing this?)
+is closed, history continues to be captured up to the configured maximum history depth.
 
 \begin{figure}[H]
 \centering
@@ -15,7 +15,7 @@ \section{History View}
 \label{historyview}
 \end{figure}
 
-The ``max waveforms" box allows the depth of the history to be configured. It defaults to 100 but can be set to any
+The ``max waveforms" box allows the depth of the history to be configured. It defaults to 10 but can be set to any
 positive integer value. Older waveforms beyond the history limit are deleted as new waveforms are acquired.
 
 The status bar at the bottom of the history view displays the total number of waveforms in the history, as well as an
@@ -25,21 +25,21 @@ \subsection{Estimating Waveform Memory Usage}
 
 When selecting a maximum depth for the history, it is important to pick a reasonable limit to avoid running out of RAM!
 glscopeclient will happily fill tens or hundreds of gigabytes of memory with deep waveforms if given a chance. Memory
-usage of waveform data can be roughly estimated as 16+sizeof(sample type) bytes per point, since each sample contains a
+usage of waveform data can be roughly estimated as 16 + sizeof(sample type) bytes per point, since each sample contains a
 64-bit timestamp and duration plus the sample data.
 
 For example, an analog sample takes 20 bytes of RAM (16 of time plus a 32-bit floating point voltage measurement) per
 sample. Thus, a 1M point analog waveform takes approximately 20 MB of RAM per channel, or 80 MB per capture on a
 four-channel oscilloscope with all channels enabled.
 
 On the larger side, a 10M point four channel capture would use 800 MB and a 64M point deep-memory capture would use 5
-GB. The default 100-waveform history setting is thus wildly inappropriate for such deep captures! A future software
-release may support spilling waveform data to a temporary directory on disk, permitting effectively unlimited history
-depth given sufficient disk space.
+GB. A deep history setting, such as 100 waveforms, is thus wildly inappropriate for such deep captures! A future
+software release may support spilling waveform data to a temporary directory on disk, permitting effectively unlimited
+history depth given sufficient disk space.
 
 Digital waveforms use one byte per sample for the actual measurement, so 17 MB per channel for a 1M point waveform.
 
-Protocol decode memory usage varies depending on the specific decode, however it is typically not a large contributor
-to the overall glscopeclient RAM footprint when using history mode because decodes are evaluated dynamically each time
-a waveform is pulled from history rather than having output cached for every historical waveform. Thus, at most one
-copy of each decoder's output is present in memory regardless of history depth.
+Filter memory usage varies depending on the specific fitler in question, however it is typically not a large
+contributor to the overall glscopeclient RAM footprint when using history mode because filters are evaluated
+dynamically each time a waveform is pulled from history rather than having output cached for every historical waveform.
+Thus, at most one copy of each filter's output is present in memory regardless of history depth.
diff --git a/section-protoanalyzer.tex b/section-protoanalyzer.tex
@@ -1 +1,21 @@
 \section{Protocol Analyzer View}
+
+Some filters for decoding packet-oriented data provide an alternate means of visualizing the decoded traffic.
+
+The protocol analyzer view (Fig. \ref{proto-analyzer}) displays each packet in the history as a row in a list view. The
+first column is always the timestamp of the packet; remaining columns vary depending on the particular filter in
+question.
+
+Clicking on a packet pauses acquisition, loads the relevant waveform from history if the packet is not in the current
+waveform, and scrolls the waveform view containing the protocol decode to the start of the packet. This allows
+packet-level data to be easily correlated to physical layer waveforms.
+
+\begin{figure}[H]
+\centering
+\includegraphics[width=14cm]{images/proto-analyzer.png}
+\caption{Protocol analyzer view}
+\label{proto-analyzer}
+\end{figure}
+
+Once closed, the protocol analyzer view is gone for good, although it will eventually be possible to bring it back via
+some sort of menu (scopehal-apps:44).
diff --git a/section-timeline.tex b/section-timeline.tex
@@ -9,6 +9,26 @@ \section{Timeline}
 the duration of the acquisition. It is possible to zoom or scroll beyond the end of the acquisition (displaying empty
 background with no signal) or have a deep capture in which nearly all acquired data is offscreen.
 
-TODO: talk about how to set trigger offset in capture and change timebase once that's implemented
+\begin{figure}[h]
+\centering
+\includegraphics[width=13cm]{images/timeline.png}
+\caption{The timeline}
+\label{timeline}
+\end{figure}
 
-TODO: insert screenshot after we have some pending UI changes done
+TODO: talk about how to set trigger offset within acquisition, once implemented (scopehal:21, scopehal-apps:12)
+
+Double-clicking on the timeline brings up the timebase properties dialog (Fig. \ref{timebase-properties}), which allows
+the sample rate and memory depth to be configured. If multiple instruments are connected, a separate tab appears in the
+dialog for each instrument.
+
+\begin{figure}[h]
+\centering
+\includegraphics[width=5cm]{images/timebase-properties.png}
+\caption{Timebase properties dialog}
+\label{timebase-properties}
+\end{figure}
+
+
+Note that the timeline may occasionally show units other than time. For example, an ``eye width" measurement has X axis
+units of voltage and Y axis units of time.
diff --git a/section-waveformviews.tex b/section-waveformviews.tex
@@ -31,10 +31,9 @@ \subsection{Y Axis Scale}
 
 Each waveform view has its own Y axis scale, which is locked to the ADC range of the instrument.
 
-Dragging the Y axis scale with the left mouse button currently does nothing (scopehal-apps:54) but in a future software
-release will change the voltage offset of the channel.
-
-Scrolling the Y axis scale with the mouse wheel changes the gain of the channel.
+If the waveform view is connected to a physical channel of an instrument, the gain may be configured by scrolling with
+the mouse wheel, and the offset may be adjusted by dragging with the left mouse button. If the view is displaying the
+output of a filter block, gain and offset are set by the filter and not adjustable.
 
 If a left-pointing arrow (as seen in Fig. \ref{y-axis}) is visible, the current channel is selected as a trigger
 source. Click on the arrow and drag up or down to select the trigger level.
@@ -52,15 +51,27 @@ \subsection{Channel Information Box}
 information about the channel. Currently this is the display name of the channel, the sample rate, and the record
 length of the acquisition. Other information, such as probe coupling, may be displayed there in the future.
 
-Double-clicking the information box opens the channel properties dialog.
-
 \begin{figure}[H]
 \centering
 \includegraphics[width=2cm]{images/channel-infobox.png}
 \caption{Channel information box}
 \label{channel-infobox}
 \end{figure}
 
+The information box may be dragged with the left mouse button to move the entire waveform view to a new location.
+
+Double-clicking the information box opens the channel properties dialog (Fig. \ref{channel-properties}). This dialog
+allows changing of the channel's nickname or color. The ``hardware name" of the channel is also displayed, so that a
+renamed channel can be easily traced back to a physical instrument input.
+
+\begin{figure}[H]
+\centering
+\includegraphics[width=8cm]{images/channel-properties.png}
+\caption{Channel properties dialog}
+\label{channel-properties}
+\end{figure}
+
+
 \subsection{Overlays}
 
 Waveforms may have additional information overlaid on top of them, such as protocol decodes. Each overlay has its own
@@ -78,5 +89,5 @@ \subsection{Overlays}
 \label{overlays}
 \end{figure}
 
-Overlays can be deleted but cannot currently be moved between waveform areas or reordered within a single waveform area
-(scopehal-apps:7, scopehal-apps:6)
+Overlays can be deleted by means of the right-click context menu. Dragging the information box with the left mouse
+button allows overlays to be reordered, however they cannot currently be moved to another waveform view.