section-mainwindow.tex

\chapter{Main Window}

The only fixed UI elements in ngscopeclient are the main menu and toolbar at the top of the window. All remaining space
may be filled with waveform plots, properties dialogs, protocol analyzers, and other dockable windows as required for a
given experimental setup. This flexibility allows almost the entire screen to be dedicated to waveform views, or more
space allocated to controls and protocol decodes.

\section{Menu}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{File}

This menu contains commands for saving and loading session files.

\begin{itemize}

\item \menustyle{Open Online...}\\
Loads a session file and reconnects to the instrument(s) to continue existing work. Settings from the saved
session will be applied and overwrite the current channel and timebase configuration of the instrument, if different.

\item \menustyle{Open Offline...}\\
Loads a session file in offline mode, allowing you to work with saved waveform data without connecting to the
instrument(s) the data was captured from.

\item \menustyle{Recent Files}\\
Displays a list of recently accessed session files and allows them to be opened online or offline.

\item \menustyle{Save}\\
Saves UI configuration and waveform data (including history) to a session file for future use.

A session consists of a YAML file called \emph{filename}.scopesession containing instrument and UI configuration, as
well as a directory called \emph{filename}\_data which contains waveform metadata and sample values for all enabled
instrument channels, including history.

Note that both the .scopesession and the \_data directory must be copied if moving the session to a new location in
order to preserve waveform data. If you only wish to restore the filter graph and UI configuration without waveform
content, the \_data directory is not required.

\item \menustyle{Save As...}\\
Saves the session to a new file, rather than the current one.

\item \menustyle{Close}\\
Close the current session without exiting ngscopeclient.

\item \menustyle{Exit}\\
Exits the application

\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{View}

\begin{itemize}

\item \menustyle{Fullscreen}\\
Toggles full-screen mode

\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Add}

This menu allows new waveforms views or instrument connections to be created.

\begin{itemize}

\item \menustyle{BERT}\\
Connect to a new, or recently used, bit error rate tester

\item \menustyle{Function Generator}\\
Connect to a new, or recently used, function generator

\item \menustyle{Load}\\
Connect to a new, or recently used, electronic load

\item \menustyle{Misc}\\
Connect to a new, or recently used, miscellaneous instrument

\item \menustyle{Multimeter}\\
Connect to a new, or recently used, multimeter

\item \menustyle{Oscilloscope}\\
Connect to a new, or recently used, oscilloscope

\item \menustyle{Power Supply}\\
Connect to a new, or recently used, power supply

\item \menustyle{RF Generator}\\
Connect to a new, or recently used, RF signal generator

\item \menustyle{SDR}\\
Connect to a new, or recently used, software-defined radio

\item \menustyle{Spectrometer}\\
Connect to a new, or recently used, optical spectrometer

\item \menustyle{VNA}\\
Connect to a new, or recently used, vector network analyzer

\item \menustyle{Channels}\\
Displays a list of filters and instrument channels which can be opened in a new waveform view

\item \menustyle{Generate}\\
Allows synthetic waveforms to be generated for testing, simulation, and channel design applications

\item \menustyle{Import}\\
Allows waveforms to be loaded from external data files in various interchange formats

\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Setup}

\begin{itemize}

\item \menustyle{Manage Instruments...}\\
Opens the Manage Instruments dialog, which allows control over synchronization, deskewing, and cross-triggering of
multiple instruments.

\item \menustyle{Trigger...}\\
Opens the Trigger dialog, allowing configuration of trigger settings.

\item \menustyle{Preferences...}\\
Opens the \hyperref[dlg:preferences]{Preferences} dialog.

\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Window}

This menu provides access to various utility windows.

\begin{itemize}

\item \menustyle{Analyzer}\\
Opens protocol analyzer dialogs for active protocol decodes

\item \menustyle{Power Supply}\\
Opens the properties dialog for a currently connected power supply

\item \menustyle{Lab Notes}\\
Opens the \hyperref[dlg:labnotes]{Lab Notes} dialog, allowing you to take notes on your experiment.

\item \menustyle{Log Viewer}\\
Opens the \hyperref[dlg:logviewer]{Log Viewer dialog,},  allowing you to see debug log messages generated by the
application. This is the same log stream which is normally written to stdout, but this dialog allows it to be accessed
even when the application was not launched from a shell session and stdout is thus inaccessible.

\item \menustyle{Measurements}\\
Opens the Measurements window, displaying scalar-valued measurements coming from instrument channels or filter blocks.

\item \menustyle{History}\\
Opens the History dialog (see Chapter \ref{sec:history}), which allows access to a rolling buffer of recently acquired
waveforms.

\item \menustyle{Filter Graph}\\
Reopens the filter graph editor if it had been closed.

\item \menustyle{Stream Browser}\\
Reopens the stream browser if it had been closed.

\item \menustyle{Filter Palette}\\
Reopens the filter palette if it had been closed.

\item \menustyle{New Workspace}\\
Create a new workspace to organize other windows in.

\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Debug}

Provides access to various features intended only for developers.

\begin{itemize}

\item \menustyle{SCPI Console}\\
Opens a console window allowing you to send raw SCPI commands to a currently connected instrument.

This is a low level debug tool primarily intended for use by driver developers. The console is interlocked with
background threads polling the instrument, so that replies to commands typed in the console will not be mixed with
replies which the instrument driver is expecting to its own commands. However, commands sent in the console will bypass
any caching in the driver and can easily lead to the driver and instrument firmware states becoming mutually
inconsistent.

\item \menustyle{ImGui Demo}\\

Launches a GUI library demo window allowing you to test out various widgets and features

\item \menustyle{Memory Leaker}\\

Allows you to allocate a large block of memory (up to 4GB or the Vulkan allocation limit per dialog instance, but
multiple dialogs may be spawned) in order to test video or system memory pressure.

\item \menustyle{Hardware Flags}\\
Opens the Hardware Flags dialog, which allows you to override automatic detection of CPU and GPU feature flags. This is mostly intended to allow testing of fallback code (by disabling a code path that your hardware supports, pretending your CPU or GPU is less capable than it is in reality).

NOTE: This is a low level interface with no validation. If you enable a feature that was not automatically enabled, ngscopeclient is very likely to crash with an illegal-instruction exception (GPU-side equivalent) at an unpredictable time in the future when a filter or driver attempts to use the unavailable functionality.

\item \menustyle{Performance Metrics}\\
Opens the \hyperref[dlg:perfemetrics]{Performance Metrics} window, which provides access to debug information which can
be helpful when debugging slow application performance, optimizing the code, or benchmarking instruments.

\item \menustyle{Memory Analysis}\\
Opens the Memory Analysis window, which display a list of all Vulkan memory buffers allocated via the AcceleratorBuffer class (buffers internally allocated by third-party libraries such as Dear ImGui or vkFFT are not shown, but anything allocated within ngscopeclient / libscopehal / libscopeprotocols should be displayed), their data type, allocation size, and actual consumed size. Lines are color coded in yellow or red to highlight particularly inefficient usage of memory (capacity grossly exceeds size).

\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Help}

\begin{itemize}

\item \menustyle{Tutorial}\\
Launches the tutorial wizard to help you learn the basics of the application

\item \menustyle{About}\\
Displays program version and copyright information

\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Toolbar}

The toolbar contains buttons and controls for the most frequently used actions.

\begin{comment}
\begin{figure}[h]
\centering
\includegraphics[width=16cm]{images/toolbar.png}
\caption{ngscopeclient toolbar}
\label{toolbar}
\end{figure}
\end{comment}

\subsection{Capture buttons}

The capture button group (Fig. \ref{capturebuttons}) contains five buttons. From left to right these are ``arm
normal trigger", ``arm one-shot trigger", ``immediate/forced trigger", ``arm auto trigger", and ``stop trigger".

Note that the ``normal" and ``auto" trigger mode still uses one-shot capture internally so that all waveform data can
be downloaded before the next trigger event \footnote{The repeating-trigger mode on almost all benchtop oscilloscopes is not interlocked with data transfer, meaning that attempting to download waveform data when the trigger is active will likely lead to corruption or desynchronization in which the data from one channel is from a later trigger event than a channel downloaded previously. Halting the trigger during waveform transfer avoids this issue, although refresh rate is reduced somewhat.}, so it is normal to see the scope rapidly switching back and forth between
single-shot and stopped mode.

\begin{comment}
\begin{figure}[h]
\centering
\includegraphics[height=1cm]{images/capture-icons.png}
\caption{Capture control buttons}
\label{capturebuttons}
\end{figure}
\end{comment}

\subsection{History}

The history button (Fig. \ref{historybutton}) toggles display of the \hyperref[sec:history]{waveform history view}.

\begin{comment}
\begin{figure}[h]
\centering
\includegraphics[height=1cm]{images/history-button.png}
\caption{History button}
\label{historybutton}
\end{figure}
\end{comment}

\subsection{Refresh Settings}

In order to improve performance, ngscopeclient caches many instrument settings locally rather than constantly querying
the instrument for the current timebase, trigger configuration, etc. If settings are changed via the instrument front
panel while ngscopeclient is running, ngscopeclient may not be aware of these changes.

The Refresh Settings button (Fig. \ref{refreshbutton}) clears all cached instrument configuration and updates
ngscopeclient with the current instrument settings. For most ``headless" instruments, such as Pico Technology devices
or the  ThunderScope, this button has no effect.

\begin{comment}
\begin{figure}[h]
\centering
\includegraphics[height=1cm]{images/refresh-button.png}
\caption{Refresh Settings button}
\label{refreshbutton}
\end{figure}
\end{comment}

\subsection{Clear Sweeps}

The Clear Sweeps button (Fig. \ref{clearbutton}) clears all persistence waveforms, accumulated eye pattern / waterfall
data, and any other data that filter grap blocks persist across multiple waveforms. Waveform data, both history and the
currently displayed waveforms, are not deleted.

\begin{comment}
\begin{figure}[h]
\centering
\includegraphics[height=1cm]{images/clear-button.png}
\caption{Clear Sweeps button}
\label{clearbutton}
\end{figure}
\end{comment}

\subsection{Fullscreen}

The Fullscreen button (Fig. \ref{fullscreenbutton}) toggles ngscopeclient between normal and full-screen mode.

\begin{comment}
\begin{figure}[h]
\centering
\includegraphics[height=1cm]{images/fullscreen-button.png}
\caption{Fullscreen button}
\label{fullscreenbutton}
\end{figure}
\end{comment}

\subsection{Intensity slider}

The opacity slider (Fig. \ref{opacityslider}) controls the alpha/opacity used to display intensity-graded waveforms. At
the leftmost position, waveforms are invisible. At the rightmost position, waveforms are fully opaque with no intensity grading other than that provided by antialiasing (Fig. \ref{intensity2}). Experiment to find what setting gives the most useful visualization for your data (Fig. \ref{intensity1}).

\begin{figure}[H]
\centering
\includegraphics[height=1cm]{ng-images/opacity-slider.png}
\caption{Trace opacity slider}
\label{opacityslider}
\end{figure}

\begin{figure}[H]
\centering
\includegraphics[width=10cm]{ng-images/intensity1.png}
\caption{Intensity graded waveform}
\label{intensity1}
\end{figure}

\begin{figure}[H]
\centering
\includegraphics[width=10cm]{ng-images/intensity2.png}
\caption{Same waveform with opacity turned up to 100\%, losing fine details}
\label{intensity2}
\end{figure}

\subsection{Persistence slider}

The persistence slider (Fig. \ref{persistenceslider}) controls the decay rate for persistence-mode waveform display. At
the far-left position (default) there is no persistence, and only the data from the most recent trigger event is visible. At the far right position, waveforms persist forever (until the clear-sweeps button is clicked or the display is scrolled/zoomed).

Persistence is applied to all analog and digital waveforms by default, but can be turned off for any individual waveform by right clicking the channel name in the plot and unchecking the ``persistence" menu item. Digital buses and protocol decodes do not support persistence, and will always only show the most recent waveform state.

\begin{figure}[H]
\centering
\includegraphics[height=1cm]{ng-images/persistence-slider.png}
\caption{Waveform persistence slider}
\label{persistenceslider}
\end{figure}


\begin{figure}[H]
\centering
\includegraphics[height=1cm]{ng-images/persistence.png}
\caption{Example waveform display with persistence active}
\label{persistence}
\end{figure}