/*****************************************************************************
*                                                                            *
*   OVERLAYXSYNC.SPL  Copyright (C) 2021 DSP Development Corporation         *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Simple time synchronization of multiple overlays            *
*                                                                            *
*   Revisions:   22 Jan 2021  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/

#if @HELP_OVERLAYXSYNC

    OVERLAYXSYNC

    Purpose: Time synchronization of one or more overlays.

    Syntax:  OVERLAYXSYNC(win)

               win - Optional. The target window. Defaults to the current
                     window.

    Returns: Nothing, the overlays of a window are synchronized based on time.

    Example:
             W1: 1..10;settime(w0, "12:00");sethunits("Time")
             W2: 3..0.1..20;settime(w0, "12:00");sethunits("Time")
             W3: w1;overlay(w2);focus(2);scales(13);focus(1);
             W4: w1;overlay(w2);focus(2);scales(13);overlayxsync();

             The series in W1 starts at 12:00:01 and contains 10 samples.
             The series in W2 starts at 12:00:03 and contains 171 samples.
             The sample rate of W1 is 1 Hz and the sample rate of W2 is 10 Hz.

             W3 contains a simple overlay of W1 and W2. Because the series
             do not begin at the same time, the data values do not line up
             in time.

             W4 contains an overlay of W1 and W2. The traces are time aligned
             such that data samples with the same time value plot at the
             same X coordinate.

    Example:
             W1: 1..10;settime(w0, "12:00");sethunits("Time")
             W2: 3..0.1..20;settime(w0, "12:00");sethunits("Time")
             W3: w2;overlay(w1);focus(2);scales(13);setsym(14);focus(1);
             W4: w2;overlay(w1);focus(2);scales(13);setsym(14);overlayxsync();

             Same as above except the input series are swapped. The data
             values of W4 still line up in time, but since the first trace
             has more samples per second, there may not be a corresponding
             value of the second trace for every sample of the first trace.

    Example:
             W1: 1..10;settime(w0, "12:00");sethunits("Time")
             W2: 3..0.1..20;settime(w0, "12:00");sethunits("Time")
             W3: (y1, y2) = timesync(w1, w2);y2;overlay(y1);focus(2);scales(13);setsym(14);focus(1);
             W4: (y1, y2) = timesync(w1, w2);y2;overlay(y1);focus(2);scales(13);setsym(14);overlayxsync();

             Same as above except the series are first time synchronized
             by TIMESYNC to have the same sample rate. The data
             values of W4 line up in time, and each value of the first trace
             has a corresponding value in the second trace.

    Remarks:
             OVERLAYXSYNC synchronizes overlays by adjusting the window
             extent so time values align. The data values are not changed.

             See TIMESYNC to perform time synchronization of two series
             by resampling and extraction.

    See Also:
             Overlay
             Sync
             Timesync
#endif


/* time synchronize overlays */
overlaytsync(win)
{
        local nfoc, xr, xl, j;

        if (argc < 1) win = refwindow(w0);

        /* number of traces */
        if ((nfoc = numfocus(win)) > 1)
        {
                /* root */
                focus(win, 1);

                /* sync x */
                sync(win, 1);

                /* full x range */
                autoscale(win);

                /* x coords of root */
                xl = getxl(win);
                xr = getxr(win);

                time_l = strtodmsec(xl + todmsecstr(gettime(win, 13)));
                time_r = strtodmsec(xr + todmsecstr(gettime(win, 13)));

                /* set coords of each trace */
                loop (j = 2..nfoc)
                {
                        focus(win, j);

                        setxtime(win, time_l, time_r);
                        xl = getxl(win);
                        xr = getxr(win);
                        setxauto(win, xl, xr);
                        autoscale(win);
                }

                /* root */
                focus(win, 1);
        }
}