% -*- texinfo -*-
% @deftypefn {Function File} {[@var{y},@var{t},@var{scale}] = } auplot (@var{x})
% @deftypefnx {Function File} {[@var{y},@var{t},@var{scale}] = } auplot (@var{x},@var{fs})
% @deftypefnx {Function File} {[@var{y},@var{t},@var{scale}] = } auplot (@var{x},@var{fs},@var{offset})
% @deftypefnx {Function File} {[@var{y},@var{t},@var{scale}] = } auplot (@var{...},@var{plotstr})
%
% Plot the waveform data, displaying time on the @var{x} axis. If you are
% plotting a slice from the middle of an array, you may want to specify
% the @var{offset} into the array to retain the appropriate time index. If
% the waveform contains multiple channels, then the data are scaled to
% the range [-1,1] and shifted so that they do not overlap. If a @var{plotstr}
% is given, it is passed as the third argument to the plot command. This
% allows you to set the linestyle easily. @var{fs} defaults to 8000 Hz, and
% @var{offset} defaults to 0 samples.
%
% Instead of plotting directly, you can ask for the returned processed
% vectors. If @var{y} has multiple channels, the plot should have the y-range
% [-1 2*size(y,2)-1]. scale specifies how much the matrix was scaled
% so that each signal would fit in the specified range.
%
% Since speech samples can be very long, we need a way to plot them
% rapidly. For long signals, auplot windows the data and keeps the
% minimum and maximum values in the window. Together, these values
% define the minimal polygon which contains the signal. The number of
% points in the polygon is set with the global variable auplot_points.
% The polygon may be either 'filled' or 'outline', as set by the global
% variable auplot_format. For moderately long data, the window does
% not contain enough points to draw an interesting polygon. In this
% case, simply choosing an arbitrary point from the window looks best.
% The global variable auplot_window sets the size of the window
% required for creating polygons. You can turn off the polygons
% entirely by setting auplot_format to 'sampled'. To turn off fast
% plotting entirely, set auplot_format to 'direct', or set
% auplot_points=1. There is no reason to do this since your screen
% resolution is limited and increasing the number of points plotted
% will not add any information. auplot_format, auplot_points and
% auplot_window may be set in .octaverc. By default auplot_format is
% 'outline', auplot_points=1000 and auplot_window=7.
% @end deftypefn