/*****************************************************************************
*                                                                            *
*   XPROJECT.SPL  Copyright (C) 2020 DSP Development Corporation             *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:       Randy Race                                                 *
*                                                                            *
*   Synopsis:     Overplots the X projection of XYZ data                     *
*                                                                            *
*   Revisions:    20 Feb 2020   RRR  Creation                                *
*                                                                            *
*****************************************************************************/

#if @HELP_XPROJECT

    XPROJECT

    Purpose: Overplots the X projection of an XYZ plot.

    Syntax:  XPROJECT(win, xloc, color)

             x = XPROJECT(win)

                win - Optional. A window that contains an XYZ series.
                      Defaults to the current window.

               xloc - Optional. A real, the fixed X location of the
                      projection. Defaults to the maximum X plotting range
                      of the XYZ series.

              color - Optional. An integer, the overplot color. Defaults
                      to -1, automatic.

    Returns: Nothing, the X projection is overplotted onto the XYZ series.

             y = XPROJECT(win) returns the X projection as an XYZ series.

    Example:
             W1: gsin(1000, 1/1000, 1)
             W2: gsin(1000, 1/1000, 2)
             W3: gsin(1000, 1/1000, 3)
             W4: xyz(w1, w2, w3);xproject()

             Creates a sinusoidal XYZ series. The X projection is overplotted
             as an XYZ series with constant X values at the largest X
             plotting range.

    Example:
             W1: gsin(1000, 1/1000, 1)
             W2: gsin(1000, 1/1000, 2)
             W3: gsin(1000, 1/1000, 3)
             W4: xyz(w1, w2, w3);xproject(w0, 0.5, purple)

             Same as above except the X projection is plotted in purple
             at x = 0.5.

    Remarks:
             XPROJECT overplots the X projection of an XYZ series. The
             projection is an XYZ series with constant X values equal to
             XLOC. By default, XLOC is set to the maximum X plotting range
             of the source XYZ plot.

             See XYZPROJECT to overplot the X, Y and Z projections of an
             XYZ series.

    See Also:
             Overplot
             XYZ
             XYZproject
             Yproject
             Zproject
#endif


/* X projection of XYZ plot */
xproject(win = refwindow(w0), xloc = getxr(win), color = -1)
{
        local x;

        if (isscalar(win))
        {
                color = xloc;
                xloc  = win;
                win   = refwindow(w0);
        }

        /* build y-z constant x */
        x = xyz(ones(length(win), 1) * xloc, yvals(win), zvals(win));

        if (outargc > 0)
        {
                return(x);
        }
        else
        {
                /* overplot */
                overplotwin(win, x, color);
        }
}